Skip to content

httpland/coep-middleware

Repository files navigation

coep-middleware

deno land deno doc GitHub release (latest by date) codecov GitHub

test NPM

HTTP cross-origin embedder policy(COEP) middleware.

Compliant with HTML Living Standard, 7.1.4 Cross-origin embedder policies.

Middleware

For a definition of Universal HTTP middleware, see the http-middleware project.

Usage

Middleware adds the Cross-Origin-Embedder-Policy header to the response.

import {
  coep,
  type Handler,
} from "https://deno.land/x/coep_middleware@$VERSION/mod.ts";
import { assert } from "https://deno.land/std/testing/asserts.ts";

declare const request: Request;
declare const handler: Handler;

const middleware = coep();
const response = await middleware(request, handler);

assert(response.headers.has("cross-origin-embedder-policy"));

yield:

Cross-Origin-Embedder-Policy: require-corp

Options

The middleware factory accepts the following fields:

Name Type Default Description
policy "require-corp" | "unsafe-none" | credentialless "require-corp" Embedder policy value.
reportTo string - Reporting endpoint name.
reportOnly boolean false Whether header is report-only or not.

policy

If specified, change the embedder policy value.

import { coep } from "https://deno.land/x/coep_middleware@$VERSION/middleware.ts";

const middleware = coep({ policy: "credentialless" });

yield:

Cross-Origin-Embedder-Policy: credentialless

reportTo

If specified, adds a report-to param to the output.

import { coep } from "https://deno.land/x/coep_middleware@$VERSION/middleware.ts";

const middleware = coep({ reportTo: "default" });

yield:

Cross-Origin-Embedder-Policy: require-corp;report-to=default

reportOnly

Depending on the value, the header will be:

Value Field name
true Cross-Origin-Embedder-Policy-Report-Only
false Cross-Origin-Embedder-Policy
import { coep } from "https://deno.land/x/coep_middleware@$VERSION/middleware.ts";

const middleware = coep({ reportOnly: true });

yield:

Cross-Origin-Embedder-Policy-Report-Only: require-corp

Throwing error

If serialize of embedder policy fails, it may throw TypeError.

Serialize fails in the following cases:

  • If reportTo field is an invalid <sf-token> syntax
import { coep } from "https://deno.land/x/coep_middleware@$VERSION/middleware.ts";
import { assertThrows } from "https://deno.land/std/testing/asserts.ts";

assertThrows(() => coep({ reportTo: "<invalid>" }));

Conditions

Middleware will execute if all of the following conditions are met:

  • Response does not include Cross-Origin-Embedder-Policy header
  • Response does not include Cross-Origin-Embedder-Policy-Report-Only header

Effects

Middleware may make changes to the following elements of the HTTP message.

  • HTTP Headers
    • Cross-Origin-Embedder-Policy
    • Cross-Origin-Embedder-Policy-Report-Only

API

All APIs can be found in the deno doc.

License

Copyright © 2023-present httpland.

Released under the MIT license