permissions-policy-parse

Zero-dependency Node.js parser for the HTTP Permissions-Policy and Feature-Policy response headers.

Parses header values like camera=(); microphone=(self "https://trusted.example.com"); geolocation=(self) into typed JavaScript objects, with a serializer, per-feature allowlist extractor, and isFeatureAllowed predicate.

Install

npm install permissions-policy-parse

API

import {
  parsePermissionsPolicy,
  serializePermissionsPolicy,
  getFeatureAllowlist,
  isFeatureAllowed,
  PermissionsPolicyParseError,
} from 'permissions-policy-parse';

parsePermissionsPolicy(headerValue, options?)

Parses a header value and returns an object with directives array and the raw string.

const result = parsePermissionsPolicy(
  'camera=(); microphone=(self "https://trusted.example.com"); geolocation=(self)'
);
// → {
//     directives: [
//       { feature: 'camera', allowlist: [] },
//       { feature: 'microphone', allowlist: [
//         { type: 'self' },
//         { type: 'origin', value: 'https://trusted.example.com' }
//       ]},
//       { feature: 'geolocation', allowlist: [{ type: 'self' }] }
//     ],
//     raw: 'camera=(); microphone=(self "https://trusted.example.com"); geolocation=(self)'
//   }

Options:

• allowUnknownFeatures (default false) — set true to accept feature names not in the W3C registry
• normalize (default true) — set false to preserve the raw field exactly as given

serializePermissionsPolicy(obj)

Round-trip a directives object back to a header string.

serializePermissionsPolicy({
  directives: [
    { feature: 'camera', allowlist: [] },
    { feature: 'geolocation', allowlist: [{ type: 'self' }] }
  ]
});
// → "camera=(); geolocation=('self')"

getFeatureAllowlist(feature, headerValue)

Extract the allowlist for a specific feature.

getFeatureAllowlist('microphone', 'camera=(); microphone=(self "https://example.com")');
// → [{ type: 'self' }, { type: 'origin', value: 'https://example.com' }]

isFeatureAllowed(feature, originOrKeyword, headerValue)

Check whether a keyword ('self', 'src', 'none', '*') or origin is in the allowlist for a feature.

isFeatureAllowed('geolocation', 'self', 'geolocation=(self)');
// → true

isFeatureAllowed('camera', 'https://evil.com', 'camera=("https://example.com")');
// → false

PermissionsPolicyParseError

Thrown on malformed input. Has message, input, and position properties.

Feature-Policy Compatibility

Both Permissions-Policy (W3C, 2020–present) and its predecessor Feature-Policy (2018–2020) use identical syntax. This library parses both:

parsePermissionsPolicy('camera=self; microphone=none');
// Works — Feature-Policy bare keyword form

Syntax

Permissions-Policy = Directive *( ';' Directive )
Directive = feature-token '=' ( '*' | allowlist )
allowlist = '(' *( token / quoted-origin ) ')'
token = 'self' | 'none' | 'src' | 'lazyload' | 'lazyload-allowlist'
quoted-origin = '"' uri '"' | "'" uri "'"

Key rules:

• No space between feature name and =
• Origins must be quoted (double or single quotes)
• camera=* means "allowed in all contexts"
• camera=(none) or camera=() means "fully blocked"
• 'self' is a keyword token, not the literal string "self"

Test count

100 tests (run with npm test).

License

MIT