permissions-policy-middleware

HTTP permissions policy middleware.

Compliant with W3C, Permissions Policy.

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>" }));

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

Copyright © 2023-present httpland.

Released under the MIT license