permissions-policy

Define your Permissions-Policy in JavaScript and let this library generate the header for you.

• Installation
• About
• Docs
• Usage
• Configuration
  • Options
  • Features
  • Allowlist
• Troubleshooting
• Dependencies
• License

Installation

npm install @jackdbd/permissions-policy

Note: this library was tested on Node.js >=18. It might work on other Node.js versions though.

About

This library allows you to define a Permissions-Policy and a Feature-Policy in JavaScript, and then it generates the corresponding headers for you.

Docs

Docs generated by TypeDoc

:open_book: API Docs

This project uses API Extractor and api-documenter markdown to generate a bunch of markdown files and a .d.ts rollup file containing all type definitions consolidated into a single file. I don't find this .d.ts rollup file particularly useful. On the other hand, the markdown files that api-documenter generates are quite handy when reviewing the public API of this project.

See Generating API docs if you want to know more.

Usage

Here is how you can generate a Permissions-Policy header:

import { permissionsPolicy } from '@jackdbd/permissions-policy'

const { error, value } = permissionsPolicy({
  features: {
    bluetooth: [],
    camera: ['self'],
    fullscreen: ['*'],
    microphone: ['self', 'https://*.example.com']
  },
  reportingEndpoint: 'permissions_policy'
})

Since at the moment browser support for Permissions-Policy is not as wide as for Feature-Policy, it's probably a good idea to generate Feature-Policy too. This library has you covered:

import { featurePolicy } from '@jackdbd/permissions-policy'

const { error, value } = featurePolicy({
  features: {
    bluetooth: [],
    camera: ['self'],
    fullscreen: ['*'],
    microphone: ['self', 'https://*.example.com']
  }
})

Configuration

Read these resources to understand how to configure the Permissions-Policy and the Feature-Policy HTTP response headers.

• A new security header: Feature Policy
• Goodbye Feature Policy and hello Permissions Policy!
• Permissions Policy Explainer
• Policy Controlled Features
• Controlling browser features with Permissions Policy

Options

| Key | Default | Description | |---|---|---| | features | {} | Hash map for configuring Permissions-Policy. Each entry has a directive as the key, and an allowlist as the value. | | reportingEndpoint | undefined | Endpoint for the Reporting API. Violations of Permissions-Policy (or Permissions-Policy-Report-Only) will be sent here. |

Features

This library defines 55 Permissions-Policy features:

accelerometer, ambient-light-sensor, attribution-reporting, autoplay, battery, bluetooth, browsing-topics, camera, ch-device-memory, ch-downlink, ch-ect, ch-rtt, ch-save-data, ch-ua-arch, ch-ua-bitness, clipboard-read, clipboard-write, conversion-measurement, cross-origin-isolated, display-capture, document-domain, encrypted-media, execution-while-not-rendered, execution-while-out-of-viewport, focus-without-user-activation, fullscreen, gamepad, geolocation, gyroscope, hid, idle-detection, layout-animations, legacy-image-formats, magnetometer, microphone, midi, navigation-override, oversized-images, payment, picture-in-picture, publickey-credentials-get, screen-wake-lock, serial, speaker-selection, sync-script, sync-xhr, trust-token-redemption, unload, unoptimized-images, unsized-media, usb, vertical-scroll, web-share, window-placement, xr-spatial-tracking

Allowlist

An allowlist is a list containing specific origins or special values.

Troubleshooting

This library uses debug for logging. You can control what's logged using the DEBUG environment variable.

For example, if you set your environment variables in a .envrc file, you can do:

export DEBUG=permissions-policy

If you are trying to configure Permissions-Policy or Feature-Policy with one or more features not implemented in this library, you can opt out of the schema validation by setting the environment variable SKIP_VALIDATION to 1.

export SKIP_VALIDATION=1

Dependencies

| Package | Version | |---|---| | zod | ^3.23.4 | | zod-validation-error | ^3.2.0 |

⚠️ Peer Dependencies

This package defines 1 peer dependency.

| Peer | Version range | |---|---| | debug | >=4.0.0 |

License

© 2024 Giacomo Debidda // MIT License