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

package/audit/README.md

@@ -0,0 +1,38 @@
+# audit
+
+## Responsibilities
+- Takes audit events from the modules that emit them, stamps them with `kernel`'s clock, and hands them to the receivers the operator names.
+- Provides the built-in receiver `log`, which writes one log line per event.
+
+## Not here
+- The kinds of events and what they hold: the emitting side's.
+- Keeping, batching or retrying events: each receiver's.
+
+## Offers
+- `audit`: record an event (kind, subject, attributes as names and string values), returning at once.
+- `audit`: the losses since boot, per named receiver, for a health check to read; the same as the metric `auth_audit_events_lost_total`, by `receiver`.
+- Extension point: receivers, keyed by name, each taking an event.
+- `auditEvents`: a module's declaration of its events (each kind's attributes, and when it is recorded), which it exports as `./audit-events` for the audit event reference; `declaredAudit` records only the kinds declared, with their attributes, and throws on another.
+- The built-in receiver `log`: the kind, time, subject and the attributes' names, never their values.
+- Operator section: `receivers`, their names or `none` (no default); `max-pending` (default 1000), each receiver's deliveries under way at once.
+- Test configuration builders, and a stand-in that keeps every event (`./testing`).
+
+## Invariants
+- A receiver gets the event frozen, with its time (`at`, epoch ms) from `kernel`'s clock, whatever the emitter wrote.
+- The emitter's own attributes are copied, never frozen. A `userAgent`, the request's own text, reaches receivers bounded as 0.17 bounded it: a `?` for each character outside RFC 6749's NQSCHAR, at most 200 characters (a longer one keeps 197 and `...`); the subject and other attributes stay as written.
+- Delivery is best effort (tier 1): receivers run after `record` returns, so an answer never waits for its events. One that throws or rejects never changes the emitter's answer or stops the others.
+- An event is lost past a receiver's pending limit (never queued), when its receiver fails, or when still under way at the stop deadline: at stop, deliveries under way are awaited until `kernel.stop-seconds`.
+- The built-in receiver `log` writes at `info`, so `kernel` drops its lines when the operator's log level is higher; the other receivers are not subject to that level.
+- Every loss is counted, and a warning names the receiver once when it starts losing, with the failure's kind alone (`backlog`, `stopped`, or the error's name, never its message), and once when it next takes an event.
+- Boot is refused without the section, for a name that is no receiver, for a composed receiver left unnamed or named `log`, and for `none` while a receiver is composed.
+
+## Data
+- Each instance's own delivery counts; nothing is shared, so it is safe on many instances.
+
+## Depends on
+- `kernel`, `metrics`
+
+## Vocabulary
+- audit event: an occurrence the emitting module names and wants on record.
+- receiver: a place audit events go.
+- lost: an event a receiver did not take.

package/audit/config.example

@@ -0,0 +1,3 @@
+audit {
+	receivers = none
+}

package/audit/src/contract.d.ts

@@ -0,0 +1,37 @@
+/** What an emitter records. The kind and the attributes are the emitter's vocabulary. */
+export interface AuditRecord {
+    readonly kind: string;
+    readonly subject?: string;
+    readonly attributes?: Readonly<Record<string, string>>;
+}
+/** A record as receivers get it, stamped with `kernel`'s clock (epoch ms). */
+export interface AuditEvent extends AuditRecord {
+    readonly at: number;
+}
+export interface Audit {
+    /** Hands the event to the receivers and returns at once; their failures never reach the caller. */
+    record(event: AuditRecord): void;
+    /** The events each named receiver did not take since boot (failed or past its pending limit). */
+    lost(): Readonly<Record<string, number>>;
+}
+export declare const audit: import("@o3co/auth-provider-foundation/kernel").Contract<Audit>;
+/** A place audit events go. Keeping and retrying them are its own. */
+export interface AuditReceiver {
+    readonly name: string;
+    receive(event: AuditEvent): Promise<void>;
+}
+export declare const auditReceivers: import("@o3co/auth-provider-foundation/kernel").ExtensionPoint<AuditReceiver>;
+/** An event a module records: the attributes it may carry, and when it is recorded. */
+export interface AuditEventDeclaration {
+    readonly attributes: readonly string[];
+    readonly when: string;
+}
+/** The events a module declares, by kind; its `./audit-events` exports them for the audit event reference. */
+export declare const auditEvents: <const E extends Readonly<Record<string, AuditEventDeclaration>>>(events: E) => E;
+/** Records only the kinds declared, with only their attributes; an undeclared one throws. */
+export declare function declaredAudit<const E extends Readonly<Record<string, AuditEventDeclaration>>>(recorder: Pick<Audit, "record">, events: E): {
+    record<K extends keyof E & string>(kind: K, event?: {
+        readonly subject?: string;
+        readonly attributes?: Partial<Record<E[K]["attributes"][number], string>>;
+    }): void;
+};

package/audit/src/contract.js

@@ -0,0 +1,29 @@
+import { contract, extensionPoint } from "@o3co/auth-provider-foundation/kernel";
+export const audit = contract("audit");
+export const auditReceivers = extensionPoint("audit.receivers", {
+    multiplicity: "keyed",
+    keyOf: (receiver) => receiver.name,
+});
+/** The events a module declares, by kind; its `./audit-events` exports them for the audit event reference. */
+export const auditEvents = (events) => Object.freeze(events);
+/** Records only the kinds declared, with only their attributes; an undeclared one throws. */
+export function declaredAudit(recorder, events) {
+    return {
+        record(kind, event = {}) {
+            const declared = events[kind];
+            if (!declared)
+                throw new Error(`${kind} is not declared`);
+            for (const name of Object.keys(event.attributes ?? {})) {
+                if (!declared.attributes.includes(name))
+                    throw new Error(`${kind} does not declare ${name}`);
+            }
+            recorder.record({
+                kind,
+                ...(event.subject === undefined ? {} : { subject: event.subject }),
+                ...(event.attributes === undefined
+                    ? {}
+                    : { attributes: event.attributes }),
+            });
+        },
+    };
+}

package/audit/src/module.d.ts

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

package/audit/src/module.js

@@ -0,0 +1,151 @@
+import { contract, deepFreeze, defineModule } from "@o3co/auth-provider-foundation/kernel";
+import { counter, instruments } from "@o3co/auth-provider-foundation/metrics";
+import { audit, auditReceivers, } from "./contract.js";
+import { section } from "./section.js";
+/** The built-in receiver: one log line per event, naming the attributes without their values. */
+const logReceiver = (log) => ({
+    name: "log",
+    receive: async (event) => {
+        log.info("audit", {
+            kind: event.kind,
+            at: event.at,
+            ...(event.subject === undefined ? {} : { subject: event.subject }),
+            ...(event.attributes ? { attributes: Object.keys(event.attributes).join(",") } : {}),
+        });
+    },
+});
+/** RFC 6749's NQSCHAR: printable ASCII but `"` and `\\`. */
+const outsideNqschar = /[^\x20-\x21\x23-\x5b\x5d-\x7e]/gu;
+/** The one attribute a request writes as it likes, bounded as 0.17 bounded it; identifiers are left as written. */
+const requestText = "userAgent";
+/** The most characters it keeps; a longer one is cut, the cut marked. */
+const longest = 200;
+/** The request's text as receivers get it, as 0.17 bounded it: `?` for each character outside NQSCHAR, at most 200. */
+const bounded = (value) => {
+    const clean = value.replace(outsideNqschar, "?");
+    return clean.length <= longest ? clean : `${clean.slice(0, longest - 3)}...`;
+};
+/** Each named receiver's lost events since boot, as a metric. */
+const lostEvents = contract("audit.lost-events");
+/** Resolves once the signal aborts. */
+const abortOf = (signal) => new Promise((resolve) => {
+    if (signal.aborted)
+        resolve();
+    else
+        signal.addEventListener("abort", () => resolve(), { once: true });
+});
+export default defineModule({ name: "audit", section, replicaSafe: true }, (m) => [
+    m.provide(lostEvents).by((c) => {
+        const named = c.section.receivers === "none" ? [] : c.section.receivers;
+        const spec = {
+            name: "auth_audit_events_lost_total",
+            help: "Audit events a receiver lost since boot: past max-pending, failed, or under way at the stop deadline.",
+        };
+        // A label needs one value at least; with no receiver the counter has no label and no series.
+        if (named.length === 0)
+            return counter({ ...spec, labels: {} });
+        return counter({ ...spec, labels: { receiver: named } });
+    }),
+    m.contribute(instruments).by((c) => c.get(lostEvents)),
+    m.provide(audit).by(async (c) => {
+        const contributed = await c.collect(auditReceivers);
+        const named = c.section.receivers === "none" ? [] : c.section.receivers;
+        const builtIns = new Map([["log", logReceiver(c.log)]]);
+        const known = new Map(builtIns);
+        const refusals = [];
+        for (const receiver of contributed) {
+            if (builtIns.has(receiver.name)) {
+                refusals.push({ where: "audit.receivers", reason: `${receiver.name} is a built-in name` });
+            }
+            else if (!named.includes(receiver.name)) {
+                refusals.push({
+                    where: "audit.receivers",
+                    reason: `${receiver.name} is composed but not named`,
+                });
+            }
+            known.set(receiver.name, receiver);
+        }
+        for (const name of named) {
+            if (!known.has(name))
+                refusals.push({ where: "audit.receivers", reason: `${name} is no receiver` });
+        }
+        if (refusals.length > 0)
+            c.refuseAll(refusals);
+        const max = c.section["max-pending"];
+        /** One receiver's events under way, lost since boot, and lost since it last took one. */
+        const lanes = named.map((name) => ({
+            receiver: known.get(name),
+            pending: 0,
+            lost: 0,
+            losing: 0,
+        }));
+        const counted = await c.get(lostEvents);
+        /** Past the stop deadline: what settles after is neither taken nor lost again. */
+        let closed = false;
+        const underWay = new Set();
+        /** `failure` is the kind alone (`backlog`, `stopped`, or the error's name), never a message a receiver wrote. */
+        const lose = (lane, failure) => {
+            lane.lost += 1;
+            counted.add({ receiver: lane.receiver.name });
+            lane.losing += 1;
+            if (lane.losing === 1) {
+                c.log.warn("audit receiver losing events", {
+                    receiver: lane.receiver.name,
+                    lost: 1,
+                    failure,
+                });
+            }
+        };
+        const took = (lane) => {
+            if (lane.losing === 0)
+                return;
+            c.log.warn("audit receiver recovered", { receiver: lane.receiver.name, lost: lane.losing });
+            lane.losing = 0;
+        };
+        // At stop, deliveries under way get until the deadline; what is still under way then is lost.
+        c.onStop(async (signal) => {
+            await Promise.race([Promise.allSettled([...underWay]), abortOf(signal)]);
+            closed = true;
+            for (const lane of lanes) {
+                for (; lane.pending > 0; lane.pending -= 1)
+                    lose(lane, "stopped");
+            }
+        });
+        return Object.freeze({
+            record: (event) => {
+                const { attributes, ...rest } = event;
+                // Copied, so freezing the event leaves the emitter's own attributes as they were.
+                const copied = attributes
+                    ? {
+                        attributes: Object.fromEntries(Object.entries(attributes).map(([k, v]) => [k, k === requestText ? bounded(v) : v])),
+                    }
+                    : {};
+                const stamped = deepFreeze({ ...rest, ...copied, at: c.clock.now() });
+                for (const lane of lanes) {
+                    if (lane.pending >= max) {
+                        lose(lane, "backlog");
+                        continue;
+                    }
+                    lane.pending += 1;
+                    // Deferred, so record returns first, and a receiver that throws at once fails like one that rejects.
+                    const delivery = Promise.resolve()
+                        .then(() => lane.receiver.receive(stamped))
+                        .then(() => {
+                        if (!closed)
+                            took(lane);
+                    }, (error) => {
+                        if (!closed)
+                            lose(lane, error instanceof Error ? error.name : "thrown");
+                    })
+                        .finally(() => {
+                        if (!closed)
+                            lane.pending -= 1;
+                        underWay.delete(delivery);
+                    });
+                    underWay.add(delivery);
+                }
+            },
+            lost: () => Object.freeze(Object.fromEntries(lanes.map((l) => [l.receiver.name, l.lost]))),
+        });
+    }),
+]);

package/audit/src/section.d.ts

@@ -0,0 +1,5 @@
+import { z } from "zod";
+export declare const section: z.ZodObject<{
+    receivers: z.ZodUnion<readonly [z.ZodLiteral<"none">, z.ZodArray<z.ZodString>]>;
+    "max-pending": z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;

package/audit/src/section.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+export const section = z.strictObject({
+    receivers: z
+        .union([
+        z.literal("none"),
+        z
+            .array(z.string().min(1))
+            .min(1)
+            .refine((names) => new Set(names).size === names.length, "names must differ"),
+    ])
+        .describe("The receivers events go to, by name, or `none` to state that events go nowhere."),
+    "max-pending": z
+        .number()
+        .int()
+        .min(1)
+        .max(1_000_000)
+        .default(1000)
+        .describe("Each receiver's deliveries under way at once; an event past it is lost."),
+});

package/audit/src/testing.d.ts

@@ -0,0 +1,16 @@
+import type { z } from "zod";
+import { type AuditEvent } from "./contract.js";
+import type { section } from "./section.js";
+export type AuditSettings = z.input<typeof section>;
+/** An audit section for tests: no receivers, stated, unless the test names some. */
+export declare function auditConfig(settings?: Partial<AuditSettings>): {
+    audit: {
+        receivers: string | string[];
+        "max-pending"?: number | undefined;
+    };
+};
+/** A stand-in for tests of emitters: it keeps every event, stamped with the composition's clock. */
+export declare function auditStandIn(): {
+    module: import("@o3co/auth-provider-foundation/kernel").Module;
+    events: AuditEvent[];
+};

package/audit/src/testing.js

@@ -0,0 +1,19 @@
+import { defineModule } from "@o3co/auth-provider-foundation/kernel";
+import { audit } from "./contract.js";
+/** An audit section for tests: no receivers, stated, unless the test names some. */
+export function auditConfig(settings = {}) {
+    return { audit: { receivers: "none", ...settings } };
+}
+/** A stand-in for tests of emitters: it keeps every event, stamped with the composition's clock. */
+export function auditStandIn() {
+    const events = [];
+    const module = defineModule({ name: "audit" }, (m) => [
+        m.provide(audit).by((c) => ({
+            record: (event) => {
+                events.push({ ...event, at: c.clock.now() });
+            },
+            lost: () => ({}),
+        })),
+    ]);
+    return { module, events };
+}

package/client-certificate/README.md

@@ -0,0 +1,27 @@
+# client-certificate
+
+## Responsibilities
+- Reads the client's certificate that a trusted proxy forwards, in the form the operator names.
+
+## Not here
+- Which peers are trusted proxies (`request-source`); what a certificate holds (its reader).
+
+## Offers
+- The forwarded certificate: its leaf and chain, or `malformed`, as `request-source`'s source carries it.
+- `certificateForwarding`: whether the operator named where certificates are forwarded.
+- `certificateSettings`, the schema part `http`'s section takes as `client-certificate` (its keys in the settings list).
+
+## Invariants
+- No client's certificate is read unless `client-certificate` is set.
+- The client's certificate is read only from a direct peer that is a trusted proxy, each header at most 16 KiB.
+- A certificate sent by another peer is ignored, and logged at most once a minute.
+- Whether the proxy removes the header a client sends is the proxy's to ensure.
+- A certificate read is handed on as copies of its bytes, frozen.
+- PEM: one certificate block, URL-encoded or not, with nothing but whitespace beside it.
+- XFCC: exactly one element; several, repeated header lines among them, are `malformed`.
+- XFCC: outside quotes, `,` parts elements and `;` fields; a quoted value takes `\` before any character; a field needs `=`, and only spaces follow a closing quote.
+- XFCC: Hash, Cert, Chain and Subject come at most once, in any case.
+- XFCC: Cert is one URL-encoded certificate block and nothing else, Chain is certificate blocks only, and Hash is the leaf's SHA-256.
+
+## Depends on
+- `kernel` (the clock of the warning), `zod`.

package/client-certificate/src/certificate.d.ts

@@ -0,0 +1,9 @@
+import type { CertificateHeaders, ForwardedCertificate } from "./contract.js";
+export type CertificateRead = {
+    readonly kind: "none";
+} | ForwardedCertificate;
+/**
+ * The client certificate a trusted proxy forwards, decoded from its transport form only: what the
+ * certificate holds, and whether it is any good, is for its reader to judge.
+ */
+export declare function certificateOf(headers: ReadonlyMap<string, string>, at: CertificateHeaders): CertificateRead;

package/client-certificate/src/certificate.js

@@ -0,0 +1,40 @@
+import { base64, certificateBlocks } from "./pem.js";
+import { xfccOf } from "./xfcc.js";
+const malformed = Object.freeze({ kind: "malformed" });
+/** The certificate as a request hands it on: copied out of the Buffers, frozen. */
+const certificate = (leaf, chain) => Object.freeze({
+    kind: "certificate",
+    leaf: new Uint8Array(leaf),
+    chain: Object.freeze(chain.map((part) => new Uint8Array(part))),
+});
+const rawLimit = 16_384;
+/** One structured-field byte sequence (`:base64:`). */
+const byteSequence = (item) => {
+    const found = /^:([A-Za-z0-9+/=]*):$/.exec(item.trim());
+    return found?.[1] && base64.test(found[1]) ? Buffer.from(found[1], "base64") : undefined;
+};
+/** The one certificate block of a PEM text that holds nothing else. */
+function pemBlock(text) {
+    const blocks = certificateBlocks(text);
+    return blocks?.length === 1 ? blocks[0] : undefined;
+}
+/**
+ * The client certificate a trusted proxy forwards, decoded from its transport form only: what the
+ * certificate holds, and whether it is any good, is for its reader to judge.
+ */
+export function certificateOf(headers, at) {
+    const leafText = headers.get(at.header);
+    if (leafText === undefined)
+        return { kind: "none" };
+    const chainText = at["chain-header"] ? headers.get(at["chain-header"]) : undefined;
+    if (leafText.length > rawLimit || (chainText?.length ?? 0) > rawLimit)
+        return malformed;
+    if (at.dialect === "xfcc") {
+        const found = xfccOf(leafText);
+        return found ? certificate(found.leaf, found.chain) : malformed;
+    }
+    const leaf = at.dialect === "rfc9440" ? byteSequence(leafText) : pemBlock(leafText);
+    const chain = chainText?.split(",").map(byteSequence) ?? [];
+    const whole = (part) => (part?.length ?? 0) > 0;
+    return whole(leaf) && chain.every(whole) ? certificate(leaf, chain) : malformed;
+}

package/client-certificate/src/contract.d.ts

@@ -0,0 +1,23 @@
+export { type CertificateRead, certificateOf } from "./certificate.js";
+export { certificateSettings } from "./settings.js";
+export { ignoredCertificates } from "./warnings.js";
+/** Where a trusted proxy puts the client's certificate, and in what form. */
+export interface CertificateHeaders {
+    /** "rfc9440": byte sequences; "pem": one PEM block; "xfcc": Envoy's, the chain in the same header. */
+    readonly dialect: "rfc9440" | "pem" | "xfcc";
+    readonly header: string;
+    readonly "chain-header"?: string;
+}
+/** What a trusted proxy forwarded of the client's certificate: it, or that it was malformed. */
+export type ForwardedCertificate = {
+    readonly kind: "certificate";
+    readonly leaf: Uint8Array;
+    readonly chain: readonly Uint8Array[];
+} | {
+    readonly kind: "malformed";
+};
+/** Whether the operator named where a trusted proxy forwards the client's certificate. */
+export interface CertificateForwarding {
+    readonly configured: boolean;
+}
+export declare const certificateForwarding: import("@o3co/auth-provider-foundation/kernel").Contract<CertificateForwarding>;

package/client-certificate/src/contract.js

@@ -0,0 +1,5 @@
+import { contract } from "@o3co/auth-provider-foundation/kernel";
+export { certificateOf } from "./certificate.js";
+export { certificateSettings } from "./settings.js";
+export { ignoredCertificates } from "./warnings.js";
+export const certificateForwarding = contract("client-certificate.certificate-forwarding");

package/client-certificate/src/pem.d.ts

@@ -0,0 +1,4 @@
+/** Padded standard base64. */
+export declare const base64: RegExp;
+/** The certificate blocks a PEM text holds, URL-encoded or not, when it holds nothing else. */
+export declare function certificateBlocks(encoded: string): Buffer[] | undefined;

package/client-certificate/src/pem.js

@@ -0,0 +1,19 @@
+/** Padded standard base64. */
+export const base64 = /^[A-Za-z0-9+/]+={0,2}$/;
+const block = /-----BEGIN CERTIFICATE-----([^-]*)-----END CERTIFICATE-----/g;
+/** The certificate blocks a PEM text holds, URL-encoded or not, when it holds nothing else. */
+export function certificateBlocks(encoded) {
+    let text;
+    try {
+        text = decodeURIComponent(encoded);
+    }
+    catch {
+        return undefined;
+    }
+    const bodies = [...text.matchAll(block)].map((found) => found[1]?.replace(/\s+/g, "") ?? "");
+    if (text.replace(block, "").trim() !== "" || bodies.length === 0)
+        return undefined;
+    if (bodies.some((body) => !base64.test(body)))
+        return undefined;
+    return bodies.map((body) => Buffer.from(body, "base64"));
+}

package/client-certificate/src/settings.d.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+/** Where a trusted proxy forwards the client's certificate, and in what form. */
+export declare const certificateSettings: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    dialect: z.ZodLiteral<"rfc9440">;
+    header: z.ZodDefault<z.ZodString>;
+    "chain-header": z.ZodDefault<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    dialect: z.ZodLiteral<"pem">;
+    header: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    dialect: z.ZodLiteral<"xfcc">;
+    header: z.ZodDefault<z.ZodString>;
+}, z.core.$strict>], "dialect">;

package/client-certificate/src/settings.js

@@ -0,0 +1,22 @@
+import { z } from "zod";
+const headerName = z.string().regex(/^[a-z0-9-]+$/);
+const headerText = "The header holding the client's certificate: lower-case letters, digits and `-`; `pem` has no default header.";
+const dialectText = "The form a trusted proxy forwards the client's certificate in: `rfc9440` (byte sequences) with `header` and `chain-header`, `pem` (one PEM block, URL-encoded or not) with `header`, or `xfcc` (Envoy's form, the chain in the same header) with `header`.";
+/** Where a trusted proxy forwards the client's certificate, and in what form. */
+export const certificateSettings = z.discriminatedUnion("dialect", [
+    z.strictObject({
+        dialect: z.literal("rfc9440").describe(dialectText),
+        header: headerName.default("client-cert").describe(headerText),
+        "chain-header": headerName
+            .default("client-cert-chain")
+            .describe("The header holding the chain behind the certificate, for `rfc9440`: lower-case letters, digits and `-`."),
+    }),
+    z.strictObject({
+        dialect: z.literal("pem").describe(dialectText),
+        header: headerName.describe(headerText),
+    }),
+    z.strictObject({
+        dialect: z.literal("xfcc").describe(dialectText),
+        header: headerName.default("x-forwarded-client-cert").describe(headerText),
+    }),
+]);

package/client-certificate/src/warnings.d.ts

@@ -0,0 +1,7 @@
+import type { Clock } from "@o3co/auth-provider-foundation/kernel";
+import type { CertificateHeaders, ForwardedCertificate } from "./contract.js";
+/**
+ * Whether to warn now of a certificate header that was sent but not taken (its peer is no trusted
+ * proxy): at most once a minute.
+ */
+export declare function ignoredCertificates(at: CertificateHeaders | undefined, clock: Clock): (headers: ReadonlyMap<string, string>, taken: ForwardedCertificate | undefined) => boolean;

package/client-certificate/src/warnings.js

@@ -0,0 +1,17 @@
+const minute = 60_000;
+/**
+ * Whether to warn now of a certificate header that was sent but not taken (its peer is no trusted
+ * proxy): at most once a minute.
+ */
+export function ignoredCertificates(at, clock) {
+    let last = Number.NEGATIVE_INFINITY;
+    return (headers, taken) => {
+        if (!at || !headers.has(at.header) || taken)
+            return false;
+        const now = clock.now();
+        if (now - last <= minute)
+            return false;
+        last = now;
+        return true;
+    };
+}

package/client-certificate/src/xfcc.d.ts

@@ -0,0 +1,5 @@
+/** The client certificate in Envoy's `x-forwarded-client-cert`, held to its one element's Hash. */
+export declare function xfccOf(text: string): {
+    leaf: Buffer;
+    chain: Buffer[];
+} | undefined;

package/client-certificate/src/xfcc.js

@@ -0,0 +1,72 @@
+import { createHash } from "node:crypto";
+import { certificateBlocks } from "./pem.js";
+/** The elements of an XFCC header, each its key=value fields; undefined where its grammar breaks. */
+function elementsOf(text) {
+    const elements = [[]];
+    let at = 0;
+    for (;;) {
+        const end = text.slice(at).search(/[=;,"]/);
+        if (end === -1 || text[at + end] !== "=")
+            return undefined;
+        const key = text.slice(at, at + end).trim();
+        if (key === "")
+            return undefined;
+        at += end + 1;
+        while (text[at] === " " || text[at] === "\t")
+            at++;
+        let value = "";
+        if (text[at] === '"') {
+            for (at++; text[at] !== '"'; at++) {
+                if (text[at] === "\\")
+                    at++;
+                if (at >= text.length)
+                    return undefined;
+                value += text[at];
+            }
+            at++;
+            while (text[at] === " " || text[at] === "\t")
+                at++;
+            if (at < text.length && text[at] !== ";" && text[at] !== ",")
+                return undefined;
+        }
+        else {
+            const stop = text.slice(at).search(/[;,]/);
+            const raw = stop === -1 ? text.slice(at) : text.slice(at, at + stop);
+            if (raw.includes('"'))
+                return undefined;
+            value = raw.trim();
+            at += raw.length;
+        }
+        elements[elements.length - 1]?.push({ key, value });
+        if (at >= text.length)
+            return elements;
+        if (text[at] === ",")
+            elements.push([]);
+        at++;
+    }
+}
+/** Fields that count, each at most once in an element, in any case. */
+const counted = new Set(["hash", "cert", "chain", "subject"]);
+/** The client certificate in Envoy's `x-forwarded-client-cert`, held to its one element's Hash. */
+export function xfccOf(text) {
+    const elements = elementsOf(text);
+    if (elements?.length !== 1)
+        return undefined;
+    const fields = new Map();
+    for (const { key, value } of elements[0] ?? []) {
+        const name = key.toLowerCase();
+        if (!counted.has(name))
+            continue;
+        if (fields.has(name))
+            return undefined;
+        fields.set(name, value);
+    }
+    const leaf = certificateBlocks(fields.get("cert") ?? "");
+    const chain = fields.has("chain") ? certificateBlocks(fields.get("chain") ?? "") : [];
+    if (leaf?.length !== 1 || !leaf[0] || !chain)
+        return undefined;
+    const sum = createHash("sha256").update(leaf[0]).digest("hex");
+    if (fields.get("hash")?.toLowerCase() !== sum)
+        return undefined;
+    return { leaf: leaf[0], chain };
+}

package/cookies/README.md

@@ -0,0 +1,34 @@
+# cookies
+
+## Responsibilities
+- Builds `Set-Cookie` values for the names routes give, by one rule for this deployment.
+- Reads a request's cookies by those names, by the same rule.
+
+## Not here
+- Whether cookies can be made secure (`http`'s `site`, from the public origin).
+- A request's scheme (`request-source`).
+- What a cookie holds (the route's).
+
+## Offers
+- `cookies.write`: a name, a value, a lifetime in seconds, and whether the cookie is cross-site → a `Set-Cookie` value.
+- `cookies.read`: a request and a name → the cookie's value.
+- `cookiesFor`: whether cookies can be made secure → cookies by the same rule, for a stand-in that builds them without composing this module.
+
+## Invariants
+- Where cookies can be made secure, a cookie's name gets the `__Host-` prefix.
+- Where cookies can be made secure, a cookie gets Secure.
+- Every cookie gets Path=/ and HttpOnly.
+- No cookie gets a Domain.
+- A cookie that is not cross-site gets SameSite=Lax.
+- A lifetime of zero seconds removes a cookie.
+- A cross-site cookie gets SameSite=None.
+- A cross-site cookie is only ever `__Host-`, Secure, Path=/ and without Domain, so no related site can set it.
+- Where cookies cannot be made secure, writing a cross-site cookie throws.
+- Writing a name that is not an HTTP token, or a value with anything but cookie-octets (RFC 6265), throws, so a write sets one cookie and no attribute of its own.
+- Each write takes its attributes from the rule of the deployment writing it; nothing of a cookie is kept between writes.
+- A request's cookie is read only when exactly one cookie has that name.
+- Where cookies can be made secure, the cookies of a request not over HTTPS are not read.
+- The cookies offered are frozen.
+
+## Depends on
+- `kernel`, `http` (the request type, `site`), `request-source` (the scheme).