permissions-policy-middleware

HTTP permissions policy middleware.

Middleware

For a definition of Universal HTTP middleware, see the http-middleware project.

Usage

Middleware adds the Permissions-Policy header to the response.

import {
  type Handler,
  permissionsPolicy,
} from "https://deno.land/x/permissions_policy_middleware@$VERSION/mod.ts";
import { assert } from "https://deno.land/std/testing/asserts.ts";

declare const request: Request;
declare const handler: Handler;

const middleware = permissionsPolicy({ features: { autoplay: "*", usb: [] } });
const response = await middleware(request, handler);

assert(response.headers.has("permissions-policy"));

yield:

Permissions-Policy: autoplay=*, usb=()

Options

Middleware require options argument.

It is following fields:

Name	Type	Required	Description
features	`PolicyControlledFeatures`	✅	Policy controlled feature name and value mapping.
reportTo	`string`	-	Representation of `report-to` directive.
reportOnly	`boolean`	-	Whether header is report-only or not.

Features

features specifies a map of permissions policy feature name and value.

All policy controlled features are supported.

import {
  permissionsPolicy,
} from "https://deno.land/x/permissions_policy_middleware@$VERSION/mod.ts";

const middleware = permissionsPolicy({
  features: {
    camera: "*",
    payment: [],
    pictureInPicture: ["self", "https://test.example"],
  },
});

yield:

Permissions-Policy: camera=*, payment=(), picture-in-picture=(self "https://test.example")

Report to

Specify the report-to directive for the Reporting API.

import {
  permissionsPolicy,
} from "https://deno.land/x/permissions_policy_middleware@$VERSION/mod.ts";

const middleware = permissionsPolicy({
  features: {},
  reportTo: "default",
});

yield:

Permissions-Policy: report-to=default

Report only

The header field changes depending on the value of reportOnly.

Value	Header field
`true`	Permissions-Policy-Report-Only
`false`	Permissions-Policy

The default reportOnly is false.

import {
  type Handler,
  permissionsPolicy,
} from "https://deno.land/x/permissions_policy_middleware@$VERSION/mod.ts";
import { assert } from "https://deno.land/std/testing/asserts.ts";

declare const request: Request;
declare const handler: Handler;

const middleware = permissionsPolicy({ features: {}, reportOnly: true });
const response = await middleware(request, handler);

assert(response.headers.has("permissions-policy-report-only"));

Serialization

features and reportTo will serialize into structured field value.

If the feature value is other than * and self, it is assumed to be an ASCII origin.

import {
  permissionsPolicy,
} from "https://deno.land/x/permissions_policy_middleware@$VERSION/mod.ts";

const middleware = permissionsPolicy({
  features: { geolocation: "https://text.example/geolocation" },
});

yield:

Permissions-Policy: geolocation=https://text.example

Serialization error

If serialization fails, an error may be thrown.

Cases that throw an error are as follows:

features value is invalid allowlist
reportTo is invalid sf-token format

import { permissionsPolicy } from "https://deno.land/x/permissions_policy_middleware@$VERSION/middleware.ts";
import { assertThrows } from "https://deno.land/std/testing/asserts.ts";

assertThrows(() =>
  permissionsPolicy({ features: { battery: "<invalid:origin>" } })
);
assertThrows(() =>
  permissionsPolicy({ features: {}, reportTo: "<invalid:sf-token>" })
);

Effects

Middleware may make changes to the following elements of the HTTP message.

HTTP Headers
- Permissions-Policy
- Permissions-Policy-Report-Only

Conditions

Middleware will execute if all of the following conditions are met:

Depends on reportOnly:

Permissions-Policy header does not exist in response
Permissions-Policy-Report-Only header does not exist in response

API

All APIs can be found in the deno doc.

License

Released under the MIT license