@httpland/permissions-policy-middleware NPM

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({ autoplay: "*", usb: [] });
const response = await middleware(request, handler);

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

yield:

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

Features

Policy controlled feature name and value mapping.

This is a required argument.

All policy controlled features are supported.

The following values can be specified for policy value.

*
self
URL origin string
Zero or more of the above items.

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

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

yield:

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

Options

The following options can be specified for the middleware factory:

Name	Type	Description
reportTo	`string`	Representation of `report-to` directive.
reportOnly	`boolean`	Whether header is report-only or not.

Report to

Specify the report-to directive for the Reporting API.

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

const middleware = permissionsPolicy({}, {
  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({}, { 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.

All feature name will convert to kebab-case.

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/middleware.ts";

const middleware = permissionsPolicy({
  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({ battery: "<invalid:origin>" }));
assertThrows(() => permissionsPolicy({}, { reportTo: "<invalid:sf-token>" }));