@o3co/auth-provider-foundation 0.17.0 → 0.18.0-rc.1

package/cookies/src/contract.d.ts

@@ -0,0 +1,15 @@
+import type { HttpRequest } from "@o3co/auth-provider-foundation/http";
+/** This deployment's cookies, named and set by one rule. */
+export interface Cookies {
+    /** The cookie the request carries once under this name; none when sent twice, or over plain http where cookies are secure. */
+    read(request: HttpRequest, name: string): string | undefined;
+    /**
+     * A `Set-Cookie` value: path `/`, HttpOnly, SameSite=Lax; zero seconds removes it. A cross-site one
+     * is SameSite=None and only ever `__Host-` and Secure: it throws where cookies cannot be secure. A name that is not a token, or a value with anything but cookie-octets, throws.
+     */
+    write(name: string, value: string, maxAgeSeconds: number, options?: {
+        readonly crossSite?: true;
+    }): string;
+}
+export declare const cookies: import("@o3co/auth-provider-foundation/kernel").Contract<Cookies>;
+export { cookiesFor } from "./cookies.js";

package/cookies/src/contract.js

@@ -0,0 +1,3 @@
+import { contract } from "@o3co/auth-provider-foundation/kernel";
+export const cookies = contract("cookies");
+export { cookiesFor } from "./cookies.js";

package/cookies/src/cookies.d.ts

@@ -0,0 +1,3 @@
+import type { Cookies } from "./contract.js";
+/** Cookies for this deployment: `__Host-` and Secure where they can be secure, plain names otherwise. */
+export declare function cookiesFor(secure: boolean): Cookies;

package/cookies/src/cookies.js

@@ -0,0 +1,39 @@
+/** A cookie's name: an HTTP token (RFC 9110 §5.6.2). */
+const tokenName = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+/** A cookie's value: cookie-octets only (RFC 6265 §4.1.1), so it cannot end the cookie or add an attribute. */
+const cookieValue = /^[\x21\x23-\x2B\x2D-\x3A\x3C-\x5B\x5D-\x7E]*$/;
+/** Whether a request came over HTTPS, by the scheme its source holds. */
+const overHttps = (source) => source.scheme === "https";
+/** Cookies for this deployment: `__Host-` and Secure where they can be secure, plain names otherwise. */
+export function cookiesFor(secure) {
+    const nameOf = (base) => (secure ? `__Host-${base}` : base);
+    return Object.freeze({
+        read: (request, base) => {
+            if (secure && !overHttps(request.source))
+                return undefined;
+            const name = nameOf(base);
+            const found = (request.headers.get("cookie") ?? "")
+                .split(";")
+                .map((part) => part.trim())
+                .filter((part) => part.startsWith(`${name}=`));
+            return found.length === 1 ? found[0]?.slice(name.length + 1) : undefined;
+        },
+        write: (base, value, maxAgeSeconds, options = {}) => {
+            if (options.crossSite && !secure)
+                throw new Error("a cross-site cookie needs secure cookies");
+            if (!tokenName.test(base))
+                throw new Error("a cookie name must be a token");
+            if (!cookieValue.test(value))
+                throw new Error("a cookie value must be cookie-octets");
+            const sameSite = options.crossSite ? "None" : "Lax";
+            return [
+                `${nameOf(base)}=${value}`,
+                "Path=/",
+                "HttpOnly",
+                `SameSite=${sameSite}`,
+                ...(secure ? ["Secure"] : []),
+                `Max-Age=${maxAgeSeconds}`,
+            ].join("; ");
+        },
+    });
+}

package/cookies/src/module.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("@o3co/auth-provider-foundation/kernel").Module;
+export default _default;

package/cookies/src/module.js

@@ -0,0 +1,7 @@
+import { site } from "@o3co/auth-provider-foundation/http";
+import { defineModule } from "@o3co/auth-provider-foundation/kernel";
+import { cookies } from "./contract.js";
+import { cookiesFor } from "./cookies.js";
+export default defineModule({ name: "cookies" }, (m) => [
+    m.provide(cookies).by(async (c) => cookiesFor((await c.get(site)).secureCookies)),
+]);

package/external-jwt/README.md

@@ -0,0 +1,38 @@
+# external-jwt
+
+## Responsibilities
+- Checks a JWT signed by a key from outside (header, key, signature, times, issuer, audience, subject), and keeps each key set fetched from a URL once in the process; knows no feature.
+
+## Not here
+- What to expect (issuer, audiences, subject, algorithms, clock allowance, longest lifetime): the caller's, from its own section.
+- Single use of a `jti`, and the meaning of any other claim: the caller's.
+- Where requests may go, and the transport: `outbound`.
+
+## Offers
+- The `externalJwt` contract: a verifier from a key source and the caller's policy, and the asymmetric algorithms it knows.
+  - Key sources: JWKs written in; PEM keys, each for the algorithm it is given for; a key set at a URL, fetched through `outbound` from the caller's hosts.
+  - Verifying answers valid (the header and claims, frozen), invalid with a reason, or unavailable when no key set can be had.
+  - Reasons: `malformed`, `algorithm`, `no-key`, `ambiguous-key`, `signature`, `expired`, `not-yet`, `future-iat`, `too-long`, `issuer`, `audience`, `subject`. A caller maps them to its own words.
+- Composition definition, with the operator section `key-set-max-age-ms` (3600000–2592000000, default 86400000), how long after its fetch a key set is used while no new one can be had.
+- A test signer (`./testing`): a key pair as a JWK and PEM, signing claims or exact bytes with any header, as a sender might.
+
+## Invariants
+- A token not written in its one form (`keys`' rule for a JWS) is malformed, so one token has one string.
+- Only asymmetric algorithms the caller allows are taken; none and shared secrets never are.
+- A header with `b64` or `crit`, a `kid` that is no string, or a `typ` other than the caller's is malformed. `typ` compares without case and with or without `application/`.
+- Keys are read and fit to the algorithm by `keys`' rules for outside keys, and must agree with the header's `kid`; exactly one must, else no key or an ambiguous key.
+- The claims are one JSON object in UTF-8 with a numeric `exp`; `nbf` and `iat`, where given, are numeric.
+- On `kernel`'s clock, with the caller's allowance on each side, a token is expired at `exp`, not yet valid before `nbf`, and refused for an `iat` in the future.
+- With a longest lifetime, neither `exp` ahead nor `iat` behind may pass it.
+- An expected audience is met by any one of the token's audiences; a list of audiences holds only strings.
+- A key set is fetched when first needed and used an hour from when its fetch began; before then, only for a key it lacks, never for one it holds twice.
+- One fetch runs at a time, shared by every check waiting for it; fetches are at least a minute apart, whether they worked or not.
+- Only a `200` answer holding a `keys` list is a set; entries that are no public key are skipped.
+- While no set can be had, the last one is used until `key-set-max-age-ms` after its fetch; past that, or with none, the answer is unavailable.
+- A refused destination, an unreachable host, or an answer that is no JSON is an outage; any other error is thrown.
+
+## Data
+- Key sets, one per URL and set of hosts, held in the process; nothing is stored.
+
+## Depends on
+- `kernel`, `keys`, `outbound`

package/external-jwt/src/contract.d.ts

@@ -0,0 +1,58 @@
+export type Jwk = Readonly<Record<string, unknown>>;
+/** A JWS algorithm's name; only the asymmetric ones `algorithms` lists ever verify. */
+export type Algorithm = string;
+/** A key set at a URL, fetched only from the hosts named. */
+export interface JwksSource {
+    readonly url: string;
+    readonly hosts: readonly string[];
+}
+/** A public key written as PEM, taken only for the algorithm it is given for. */
+export interface PemKey {
+    readonly alg: Algorithm;
+    readonly kid?: string;
+    readonly pem: string;
+}
+/** Where the keys come from: written in, as PEM, or a key set at a URL. */
+export type KeySource = {
+    readonly inline: readonly Jwk[];
+} | {
+    readonly pem: readonly PemKey[];
+} | {
+    readonly jwks: JwksSource;
+};
+/** What the caller decides: each value is the caller's own, given from its section. */
+export interface Policy {
+    readonly algorithms: readonly Algorithm[];
+    /** How far the issuer's clock may be from `kernel`'s. */
+    readonly skewMs: number;
+    readonly maxLifetimeMs?: number;
+    /** The header's `typ`, compared as RFC 7515 says. */
+    readonly typ?: string;
+    readonly expect?: {
+        readonly iss?: string;
+        /** Any one of these among the token's audiences. */
+        readonly aud?: readonly string[];
+        readonly sub?: string;
+    };
+}
+export type Reason = "malformed" | "algorithm" | "no-key" | "ambiguous-key" | "signature" | "expired" | "not-yet" | "future-iat" | "too-long" | "issuer" | "audience" | "subject";
+export type Verified = {
+    readonly kind: "valid";
+    readonly header: Readonly<Record<string, unknown>>;
+    readonly claims: Readonly<Record<string, unknown>>;
+} | {
+    readonly kind: "invalid";
+    readonly reason: Reason;
+} | {
+    readonly kind: "unavailable";
+};
+export interface Verifier {
+    verify(jwt: string): Promise<Verified>;
+}
+/** Makes verifiers; one per process, keeping each key set once, by its URL and hosts. */
+export interface ExternalJwt {
+    verifierOf(keys: KeySource, policy: Policy): Verifier;
+    /** The asymmetric algorithms it knows; a policy may name any of them. */
+    readonly algorithms: readonly Algorithm[];
+}
+export declare const externalJwt: import("@o3co/auth-provider-foundation/kernel").Contract<ExternalJwt>;

package/external-jwt/src/contract.js

@@ -0,0 +1,2 @@
+import { contract } from "@o3co/auth-provider-foundation/kernel";
+export const externalJwt = contract("external-jwt");

package/external-jwt/src/jwks.d.ts

@@ -0,0 +1,20 @@
+import { type Clock } from "@o3co/auth-provider-foundation/kernel";
+import { type Outbound } from "@o3co/auth-provider-foundation/outbound";
+import type { JwksSource } from "./contract.js";
+import { type Candidate } from "./keys.js";
+/**
+ * The key set at a URL: fetched when first needed, kept an hour, fetched again at most once a minute,
+ * and past `maxAgeMs` after it was fetched never used.
+ */
+export declare function jwksAt(source: JwksSource, deps: {
+    readonly clock: Clock;
+    readonly outbound: Outbound;
+    readonly maxAgeMs: number;
+}): {
+    /** The set to check with: the kept one while it holds, else a fresh one where it can be had, else the last. */
+    keys: () => Promise<readonly Candidate[] | undefined>;
+    /** A fresh set for a key the kept one lacks, where a fetch is due. */
+    again: () => Promise<readonly Candidate[] | undefined>;
+};
+/** A key set at a URL, as one composition keeps it. */
+export type KeySet = ReturnType<typeof jwksAt>;

package/external-jwt/src/jwks.js

@@ -0,0 +1,61 @@
+import { isUnavailable } from "@o3co/auth-provider-foundation/kernel";
+import { DestinationRefused, jsonObjectOf, } from "@o3co/auth-provider-foundation/outbound";
+import { fromJwk } from "./keys.js";
+/** A set is used this long after it was fetched. */
+const holdMs = 3_600_000;
+/** Fetches, whether they worked or not, are at least this far apart. */
+const spacingMs = 60_000;
+/**
+ * The key set at a URL: fetched when first needed, kept an hour, fetched again at most once a minute,
+ * and past `maxAgeMs` after it was fetched never used.
+ */
+export function jwksAt(source, deps) {
+    const { clock } = deps;
+    let kept;
+    let tried;
+    let fetching;
+    const fetchAndKeep = async () => {
+        // The set's age counts from the start, however long the answer takes.
+        const began = clock.now();
+        tried = began;
+        let response;
+        try {
+            response = await deps.outbound.fetch(source.url, { headers: { accept: "application/json" } }, { hosts: source.hosts });
+        }
+        catch (error) {
+            if (isUnavailable(error) || error instanceof DestinationRefused)
+                return;
+            throw error;
+        }
+        const answer = jsonObjectOf(response);
+        const listed = answer.kind === "object" ? answer.value.keys : undefined;
+        if (!Array.isArray(listed))
+            return;
+        const keys = listed.flatMap((jwk) => jwk && typeof jwk === "object" && !Array.isArray(jwk) ? (fromJwk(jwk) ?? []) : []);
+        kept = { keys, fetchedAt: began };
+    };
+    /** One fetch at a time, shared by every check that waits for it, and none within a minute of the last. */
+    const refresh = async () => {
+        if (!fetching && (tried === undefined || clock.now() - tried >= spacingMs)) {
+            fetching = fetchAndKeep().finally(() => {
+                fetching = undefined;
+            });
+        }
+        await fetching;
+    };
+    /** The kept set while it is young enough to use, even when it cannot be renewed. */
+    const usable = () => kept && clock.now() - kept.fetchedAt < deps.maxAgeMs ? kept.keys : undefined;
+    return {
+        /** The set to check with: the kept one while it holds, else a fresh one where it can be had, else the last. */
+        keys: async () => {
+            if (!kept || clock.now() - kept.fetchedAt >= holdMs)
+                await refresh();
+            return usable();
+        },
+        /** A fresh set for a key the kept one lacks, where a fetch is due. */
+        again: async () => {
+            await refresh();
+            return usable();
+        },
+    };
+}

package/external-jwt/src/keys.d.ts

@@ -0,0 +1,16 @@
+import type { KeyObject } from "node:crypto";
+import type { Algorithm, Jwk, PemKey } from "./contract.js";
+/** A key that may verify: as a JWK, for choosing it, and as the platform reads it. */
+export interface Candidate {
+    readonly jwk: Jwk;
+    readonly key: KeyObject;
+}
+/** The asymmetric algorithms `keys` knows. */
+export declare const algorithms: readonly Algorithm[];
+export declare const isAlgorithm: (alg: unknown) => alg is Algorithm;
+/** A public key `keys` reads from a JWK; none for anything else. */
+export declare const fromJwk: (jwk: Jwk) => Candidate | undefined;
+/** A PEM public key, taken only for the algorithm it is given for; a private one never is. */
+export declare function fromPem(given: PemKey): Candidate | undefined;
+/** The one key that may verify under the header's algorithm and id. */
+export declare function picked(candidates: readonly Candidate[], alg: Algorithm, kid: string | undefined): Candidate | "no-key" | "ambiguous-key";

package/external-jwt/src/keys.js

@@ -0,0 +1,26 @@
+import { publicJwk, publicPem, verifiesUnder, verifyAlgorithms } from "@o3co/auth-provider-foundation/keys";
+/** The asymmetric algorithms `keys` knows. */
+export const algorithms = verifyAlgorithms;
+export const isAlgorithm = (alg) => typeof alg === "string" && algorithms.includes(alg);
+/** A public key `keys` reads from a JWK; none for anything else. */
+export const fromJwk = (jwk) => publicJwk(jwk);
+/** A PEM public key, taken only for the algorithm it is given for; a private one never is. */
+export function fromPem(given) {
+    const key = publicPem(given.pem);
+    if (!key)
+        return undefined;
+    const jwk = {
+        ...key.export({ format: "jwk" }),
+        alg: given.alg,
+        ...(given.kid ? { kid: given.kid } : {}),
+    };
+    return { jwk, key };
+}
+/** The one key that may verify under the header's algorithm and id. */
+export function picked(candidates, alg, kid) {
+    const matching = candidates.filter(({ jwk }) => verifiesUnder(jwk, alg) && (kid === undefined || jwk.kid === kid));
+    const [only, ...more] = matching;
+    if (!only)
+        return "no-key";
+    return more.length > 0 ? "ambiguous-key" : only;
+}

package/external-jwt/src/module.d.ts

@@ -0,0 +1,6 @@
+import { z } from "zod";
+export declare const section: z.ZodObject<{
+    "key-set-max-age-ms": z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+declare const _default: import("@o3co/auth-provider-foundation/kernel").Module;
+export default _default;

package/external-jwt/src/module.js

@@ -0,0 +1,21 @@
+import { defineModule } from "@o3co/auth-provider-foundation/kernel";
+import { outbound } from "@o3co/auth-provider-foundation/outbound";
+import { z } from "zod";
+import { externalJwt } from "./contract.js";
+import { externalJwtOver } from "./verifier.js";
+export const section = z.strictObject({
+    "key-set-max-age-ms": z
+        .number()
+        .int()
+        .min(3_600_000)
+        .max(2_592_000_000)
+        .default(86_400_000)
+        .describe("How long after its fetch a key set is still used while no new one can be had, in milliseconds."),
+});
+export default defineModule({ name: "external-jwt", section }, (m) => [
+    m.provide(externalJwt).by(async (c) => externalJwtOver({
+        clock: c.clock,
+        outbound: await c.get(outbound),
+        keySetMaxAgeMs: c.section["key-set-max-age-ms"],
+    })),
+]);

package/external-jwt/src/testing.d.ts

@@ -0,0 +1,38 @@
+/** What differs by algorithm: the key pair, the digest, and how an EC signature is written (RFC 7518 §3.4). */
+declare const byAlg: {
+    ES256: {
+        pair: () => import("node:crypto").KeyPairExportResult<{
+            namedCurve: string;
+        }>;
+        digest: string;
+        encoding: {
+            dsaEncoding: "ieee-p1363";
+        };
+    };
+    RS256: {
+        pair: () => import("node:crypto").KeyPairExportResult<{
+            modulusLength: number;
+        }>;
+        digest: string;
+        encoding: {};
+    };
+    EdDSA: {
+        pair: () => import("node:crypto").KeyPairExportResult<{}>;
+        digest: null;
+        encoding: {};
+    };
+};
+type TestAlgorithm = keyof typeof byAlg;
+/**
+ * A key pair for a test: its public key as a JWK (with `kid` where given) and as PEM, and signers
+ * that write any header as a sender might, unencoded payloads and critical extensions included.
+ */
+export declare function testSigner(alg: TestAlgorithm, kid?: string): Promise<{
+    jwk: Record<string, unknown>;
+    pem: string;
+    /** Signs the claims; `header` adds to or, with undefined, removes from `{ alg, kid }`. */
+    sign: (claims: unknown, header?: Record<string, unknown>) => Promise<string>;
+    /** Signs a payload's exact bytes, which no JSON value can carry; `header` is as for `sign`. */
+    signBytes: (payload: Uint8Array, header?: Record<string, unknown>) => Promise<string>;
+}>;
+export {};

package/external-jwt/src/testing.js

@@ -0,0 +1,43 @@
+import { generateKeyPairSync, sign } from "node:crypto";
+/** What differs by algorithm: the key pair, the digest, and how an EC signature is written (RFC 7518 §3.4). */
+const byAlg = {
+    ES256: {
+        pair: () => generateKeyPairSync("ec", { namedCurve: "P-256" }),
+        digest: "sha256",
+        encoding: { dsaEncoding: "ieee-p1363" },
+    },
+    RS256: {
+        pair: () => generateKeyPairSync("rsa", { modulusLength: 2048 }),
+        digest: "sha256",
+        encoding: {},
+    },
+    EdDSA: { pair: () => generateKeyPairSync("ed25519"), digest: null, encoding: {} },
+};
+const encoded = (text) => Buffer.from(text).toString("base64url");
+/**
+ * A key pair for a test: its public key as a JWK (with `kid` where given) and as PEM, and signers
+ * that write any header as a sender might, unencoded payloads and critical extensions included.
+ */
+export async function testSigner(alg, kid) {
+    const { publicKey, privateKey } = byAlg[alg].pair();
+    const jwk = {
+        ...publicKey.export({ format: "jwk" }),
+        ...(kid ? { kid } : {}),
+    };
+    return {
+        jwk,
+        pem: publicKey.export({ format: "pem", type: "spki" }).toString(),
+        /** Signs the claims; `header` adds to or, with undefined, removes from `{ alg, kid }`. */
+        sign: async (claims, header = {}) => signed(Buffer.from(JSON.stringify(claims)), header),
+        /** Signs a payload's exact bytes, which no JSON value can carry; `header` is as for `sign`. */
+        signBytes: async (payload, header = {}) => signed(payload, header),
+    };
+    function signed(payload, header) {
+        const written = Object.fromEntries(Object.entries({ alg, ...(kid ? { kid } : {}), ...header }).filter(([, value]) => value !== undefined));
+        const body = Buffer.from(payload);
+        const input = `${encoded(JSON.stringify(written))}.${written.b64 === false ? body.toString() : body.toString("base64url")}`;
+        const { digest, encoding } = byAlg[alg];
+        const signature = sign(digest, Buffer.from(input), { key: privateKey, ...encoding });
+        return `${input}.${signature.toString("base64url")}`;
+    }
+}

package/external-jwt/src/verifier.d.ts

@@ -0,0 +1,10 @@
+import { type Clock } from "@o3co/auth-provider-foundation/kernel";
+import type { Outbound } from "@o3co/auth-provider-foundation/outbound";
+import type { ExternalJwt } from "./contract.js";
+/** Verifiers on `kernel`'s clock, fetching key sets through `outbound`, each set kept once by its URL and hosts. */
+export declare function externalJwtOver(deps: {
+    readonly clock: Clock;
+    readonly outbound: Outbound;
+    /** How long after it was fetched a key set may still be used. */
+    readonly keySetMaxAgeMs: number;
+}): ExternalJwt;

package/external-jwt/src/verifier.js

@@ -0,0 +1,147 @@
+import { deepFreeze } from "@o3co/auth-provider-foundation/kernel";
+import { isCanonicalJws } from "@o3co/auth-provider-foundation/keys";
+import { compactVerify, decodeProtectedHeader } from "jose";
+import { jwksAt } from "./jwks.js";
+import { algorithms, fromJwk, fromPem, isAlgorithm, picked } from "./keys.js";
+/** A `typ` as RFC 7515 compares it: without case and without `application/`. */
+const mediaTypeOf = (typ) => typeof typ === "string" ? typ.toLowerCase().replace(/^application\//, "") : undefined;
+/** Claims are UTF-8, as RFC 7519 says; bytes that are not refuse them. */
+const utf8 = new TextDecoder("utf-8", { fatal: true });
+const isTime = (value) => typeof value === "number" && Number.isFinite(value);
+/** Verifiers on `kernel`'s clock, fetching key sets through `outbound`, each set kept once by its URL and hosts. */
+export function externalJwtOver(deps) {
+    const sets = new Map();
+    const setAt = (url, hosts) => {
+        const key = JSON.stringify([url, [...hosts].sort()]);
+        const kept = sets.get(key);
+        if (kept)
+            return kept;
+        const made = jwksAt({ url, hosts }, { clock: deps.clock, outbound: deps.outbound, maxAgeMs: deps.keySetMaxAgeMs });
+        sets.set(key, made);
+        return made;
+    };
+    const chooserOf = (keys) => {
+        if ("jwks" in keys)
+            return fromSet(setAt(keys.jwks.url, keys.jwks.hosts));
+        const written = "inline" in keys
+            ? keys.inline.flatMap((jwk) => fromJwk(jwk) ?? [])
+            : keys.pem.flatMap((given) => fromPem(given) ?? []);
+        return async (alg, kid) => picked(written, alg, kid);
+    };
+    return {
+        algorithms,
+        verifierOf: (keys, policy) => verifierWith(chooserOf(keys), policy, deps.clock),
+    };
+}
+/** Picks from the kept set, and from a fresh one only when the kept set has no key that fits. */
+function fromSet(set) {
+    return async (alg, kid) => {
+        const held = await set.keys();
+        const first = held ? picked(held, alg, kid) : undefined;
+        // An ambiguous pick is the set's own answer; fetching again would not settle it.
+        if (first !== undefined && first !== "no-key")
+            return first;
+        const again = await set.again();
+        return again ? picked(again, alg, kid) : "unavailable";
+    };
+}
+function headerOf(jwt) {
+    try {
+        return decodeProtectedHeader(jwt);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function signedPayload(jwt, key) {
+    try {
+        return (await compactVerify(jwt, key.key)).payload;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** One JSON object in UTF-8, or undefined. */
+function claimsOf(payload) {
+    try {
+        const claims = JSON.parse(utf8.decode(payload));
+        return typeof claims === "object" && claims !== null ? claims : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** What is wrong with the claims under the policy at `now`, if anything. */
+function claimsFault(claims, policy, now) {
+    const { exp, nbf, iat } = claims;
+    if (!isTime(exp) || (nbf !== undefined && !isTime(nbf)) || (iat !== undefined && !isTime(iat))) {
+        return "malformed";
+    }
+    const [expMs, nbfMs, iatMs] = [
+        exp * 1000,
+        isTime(nbf) ? nbf * 1000 : undefined,
+        isTime(iat) ? iat * 1000 : undefined,
+    ];
+    const skew = policy.skewMs;
+    if (expMs <= now - skew)
+        return "expired";
+    if (nbfMs !== undefined && nbfMs > now + skew)
+        return "not-yet";
+    if (iatMs !== undefined && iatMs > now + skew)
+        return "future-iat";
+    if (policy.maxLifetimeMs !== undefined) {
+        const reach = policy.maxLifetimeMs + skew;
+        if (expMs - now > reach || (iatMs !== undefined && now - iatMs > reach))
+            return "too-long";
+    }
+    const expected = policy.expect;
+    if (expected?.iss !== undefined && claims.iss !== expected.iss)
+        return "issuer";
+    const wanted = expected?.aud;
+    if (wanted !== undefined) {
+        const audiences = typeof claims.aud === "string" ? [claims.aud] : claims.aud;
+        // A list of audiences holds only strings, as RFC 7519 says.
+        const allStrings = Array.isArray(audiences) && audiences.every((a) => typeof a === "string");
+        if (!allStrings || !audiences.some((a) => wanted.includes(a)))
+            return "audience";
+    }
+    if (expected?.sub !== undefined && claims.sub !== expected.sub)
+        return "subject";
+    return undefined;
+}
+function verifierWith(choose, policy, clock) {
+    const invalid = (reason) => ({ kind: "invalid", reason });
+    return {
+        verify: async (jwt) => {
+            const header = isCanonicalJws(jwt) ? headerOf(jwt) : undefined;
+            if (!header)
+                return invalid("malformed");
+            // A JWT is encoded, and no critical extension is taken.
+            if (header.b64 !== undefined || header.crit !== undefined)
+                return invalid("malformed");
+            if (policy.typ !== undefined && mediaTypeOf(header.typ) !== mediaTypeOf(policy.typ))
+                return invalid("malformed");
+            const kid = header.kid;
+            if (kid !== undefined && typeof kid !== "string")
+                return invalid("malformed");
+            const alg = header.alg;
+            if (!isAlgorithm(alg) || !policy.algorithms.includes(alg))
+                return invalid("algorithm");
+            const key = await choose(alg, kid);
+            if (key === "unavailable")
+                return { kind: "unavailable" };
+            if (typeof key === "string")
+                return invalid(key);
+            const payload = await signedPayload(jwt, key);
+            if (!payload)
+                return invalid("signature");
+            const claims = claimsOf(payload);
+            if (!claims)
+                return invalid("malformed");
+            const fault = claimsFault(claims, policy, clock.now());
+            if (fault)
+                return invalid(fault);
+            return { kind: "valid", header: deepFreeze({ ...header }), claims: deepFreeze(claims) };
+        },
+    };
+}

package/http/README.md

@@ -0,0 +1,39 @@
+# http
+
+## Responsibilities
+- Owns the HTTP entry point: it connects the routes that modules contribute and applies the policies each route declares.
+- Reads what a request sends (query, form, JSON, headers) once at the boundary into read-only maps.
+- Answers unavailable with `503`: retryable, with no body, kept out of caches (`noStore`: `no-store`, `Pragma: no-cache`).
+
+## Not here
+- What a route means and its error vocabulary (the contributing module's); what a policy decides and answers (its owner's).
+- Any name taken from request headers: the public origin comes only from configuration.
+
+## Offers
+- `routes`: a method, a path and a handler, with the policies used (and their options), the bodies taken and cross-origin use when declared; a GET route also answers HEAD, with the same headers and no body.
+- Paths: an exact path comes first, then the longest `/*` above it; a handler reads the URL parser's path (dot segments resolved, percent-encoding kept as sent), and a `/*` handler checks the segments under it by its own rules.
+- Bodies: a route may take a form, JSON, none, or several, and any other body is `415`, refused only after the route's policies have seen the request.
+- A form and a JSON body share one size limit of 64 KiB: a larger form is read as empty, and a larger JSON body is `413`.
+- A JSON body is one object in well-formed UTF-8, frozen, naming no member twice in one object; anything else is `400`.
+- Values with the same name keep the order sent: `single` gives a name's only value, `repeated` the names with more, and whether one must be single is the route's.
+- A request's fields are its body's values by name; a JSON member that is not a string is told apart as `mistyped`, its meaning the route's.
+- Cross-origin routes: a preflight is answered before the policies, and answers vary by `Origin`, naming the request's origin only when listed, never `*` and never with credentials.
+- A preflight from a listed origin, for a method a declared route takes, names the methods of the path's declared routes, the request headers the route takes, and a max age of 600 seconds.
+- Any other preflight on such a path gets `204` with nothing to read by.
+- `loads`: what a page declares it loads (the origins it frames, its inline scripts); its answer's policy allows those and nothing else, and a frame a policy cannot name makes the answer `500`.
+- Policies: `policy` makes one, unique as a value; `use` is a route's use of one with its options; `policies` takes one rule per policy, which passes the request on or answers it; a route's policies run in its order before its handler, and the first answer ends the request.
+- The request type, with its source as `request-source` decides it from the direct peer, the headers and this section's trusted proxies.
+- `listening` (the port) and `site` (the public origin; cookies can be made secure unless it is http); an answer's `cookies` are sent one `Set-Cookie` each; `client-certificate`'s `certificateForwarding` is provided from this section.
+- `requestEnds`: each request's end, once, answered or closed: the method sent, the declared path of the route reached (none when none), the status written or `closed` when the client closed first, and the milliseconds taken (never negative); an observer's throw is dropped.
+- Observers are told after the request, asynchronously, and what they throw or reject is dropped.
+- `./testing`: test configuration and request builders with working defaults.
+
+## Invariants
+- Boot is refused, naming the route and the policy, when two routes take one method and path, a route uses a policy no module applies, or a policy has two rules; policies match by value, and a label only names one in a report.
+- Every answer it writes carries the security headers, set in one place: a Content-Security-Policy that loads nothing by default and lets no one frame the answer, HSTS, `nosniff`, `X-Frame-Options`, `Referrer-Policy: no-referrer` and the cross-origin ones; a route's own values of them, its policy included, are replaced; only `loads` widens a page's policy.
+- Stop refuses new connections and closes idle ones; requests in flight finish (`Connection: close`) until its deadline cuts them.
+- A request target that is not a URL gets `400`, an answer whose headers cannot be written gets `500`, no request stops the process, and error answers never show exception text or internal values.
+- A path no route reaches gets `404`, and a path whose routes take other methods gets `405` naming them in `Allow`.
+
+## Depends on
+- `kernel`, `request-source`, `client-certificate`.

package/http/config.example

@@ -0,0 +1,5 @@
+http {
+	host = 127.0.0.1
+	port = 8080
+	public-origin = "https://login.example.invalid"
+}