# @httpland/permissions-policy-middleware

> HTTP permissions policy middleware

Latest version **1.0.0** (published 2023-04-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install @httpland/permissions-policy-middleware
pnpm add @httpland/permissions-policy-middleware
yarn add @httpland/permissions-policy-middleware
bun add @httpland/permissions-policy-middleware
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2023-04-17 |
| First published | 2023-04-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 5 |
| Unpacked size | 48.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Maintainers | miyauci |
| Keywords | http, middleware, permissions-policy, permissions, policy, permissions-policy-report-only |

## Links

- npm: https://www.npmjs.com/package/@httpland/permissions-policy-middleware
- Repository: https://github.com/httpland/permissions-policy-middleware
- Issues: https://github.com/httpland/permissions-policy-middleware/issues
- npm.io page: https://npm.io/package/@httpland/permissions-policy-middleware

## Dependencies (5)

- [kebab-case](https://npm.io/package/kebab-case.md) 1.0.2
- [@miyauci/isx](https://npm.io/package/@miyauci/isx.md) 1.3.0
- [@httpland/http-utils](https://npm.io/package/@httpland/http-utils.md) 1.0.0
- [@httpland/sfv-parser](https://npm.io/package/@httpland/sfv-parser.md) 1.1.0
- [@httpland/http-middleware](https://npm.io/package/@httpland/http-middleware.md) 1.0.0

## Alternatives

- [@sindresorhus/slugify](https://npm.io/package/@sindresorhus/slugify.md) — 3.7M weekly downloads
- [solid-js](https://npm.io/package/solid-js.md) — 2.7M weekly downloads
- [expo-glass-effect](https://npm.io/package/expo-glass-effect.md) — 2.5M weekly downloads
- [nanoassert](https://npm.io/package/nanoassert.md) — 780.8K weekly downloads
- [@ffmpeg/ffmpeg](https://npm.io/package/@ffmpeg/ffmpeg.md) — 529.5K weekly downloads

## Recent versions

- 1.0.0 (latest) — 2023-04-17
- 1.0.0-beta.2 (beta) — 2023-04-17
- 1.0.0-beta.1 — 2023-04-17

## README

# permissions-policy-middleware

[![deno land](http://img.shields.io/badge/available%20on-deno.land/x-lightgrey.svg?logo=deno)](https://deno.land/x/permissions_policy_middleware)
[![deno doc](https://doc.deno.land/badge.svg)](https://doc.deno.land/https/deno.land/x/permissions_policy_middleware/mod.ts)
[![GitHub release (latest by date)](https://img.shields.io/github/v/release/httpland/permissions-policy-middleware)](https://github.com/httpland/permissions-policy-middleware/releases)
[![codecov](https://codecov.io/github/httpland/permissions-policy-middleware/branch/main/graph/badge.svg)](https://codecov.io/gh/httpland/permissions-policy-middleware)
[![GitHub](https://img.shields.io/github/license/httpland/permissions-policy-middleware)](https://github.com/httpland/permissions-policy-middleware/blob/main/LICENSE)

[![test](https://github.com/httpland/permissions-policy-middleware/actions/workflows/test.yaml/badge.svg)](https://github.com/httpland/permissions-policy-middleware/actions/workflows/test.yaml)
[![NPM](https://nodei.co/npm/@httpland/permissions-policy-middleware.png?mini=true)](https://nodei.co/npm/@httpland/permissions-policy-middleware/)

HTTP permissions policy middleware.

Compliant with
[W3C, Permissions Policy](https://www.w3.org/TR/permissions-policy/).

## Middleware

For a definition of Universal HTTP middleware, see the
[http-middleware](https://github.com/httpland/http-middleware) project.

## Usage

Middleware adds the `Permissions-Policy` header to the response.

```ts
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:

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

## Features

Policy controlled feature name and value mapping.

This is a required argument.

All
[policy controlled features](https://github.com/w3c/webappsec-permissions-policy/blob/main/features.md)
are supported.

The following values can be specified for policy value.

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

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

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

yield:

```http
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.

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

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

yield:

```http
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`.

```ts
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](https://www.rfc-editor.org/rfc/rfc8941.html).

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.

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

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

yield:

```http
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](https://www.w3.org/TR/permissions-policy/#allowlist)
- `reportTo` is invalid
  [`sf-token`](https://www.rfc-editor.org/rfc/rfc8941.html#section-3.3.4-3)
  format

```ts
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](#report-only):

- `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](https://doc.deno.land/https/deno.land/x/permissions_policy_middleware/mod.ts).

## License

Copyright © 2023-present [httpland](https://github.com/httpland).

Released under the [MIT](./LICENSE) license

---
_Source: https://npm.io/package/@httpland/permissions-policy-middleware · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._