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

package/kernel/src/handles.js

@@ -0,0 +1,6 @@
+export function contract(label) {
+    return Object.freeze({ kind: "contract", label });
+}
+export function extensionPoint(label, rule) {
+    return Object.freeze({ kind: "extension-point", label, rule: Object.freeze(rule) });
+}

package/kernel/src/log.d.ts

@@ -0,0 +1,12 @@
+import type { Clock, Log, LogSink } from "./runtime.js";
+/** In order: a threshold lets through its own level and those after it. */
+export declare const thresholds: readonly ["trace", "debug", "info", "warn", "error", "fatal", "silent"];
+export type Threshold = (typeof thresholds)[number];
+export declare const logSinks: import("./handles.js").ExtensionPoint<LogSink>;
+/** The same log, its calls never throwing. */
+export declare function guardedLog(log: Log): Log;
+/**
+ * A log handing each line at or above `threshold` to every sink, in order. `sinks` answers
+ * undefined while the sinks are being built, and those lines are dropped.
+ */
+export declare function routedLog(threshold: Threshold, clock: Clock, sinks: () => readonly LogSink[] | undefined): Log;

package/kernel/src/log.js

@@ -0,0 +1,55 @@
+import { extensionPoint } from "./handles.js";
+/** In order: a threshold lets through its own level and those after it. */
+export const thresholds = ["trace", "debug", "info", "warn", "error", "fatal", "silent"];
+export const logSinks = extensionPoint("logSinks", { multiplicity: "many" });
+/** A Log whose calls never throw, whatever `write` does. */
+function logOf(write) {
+    const method = (level) => (event, fields) => {
+        try {
+            write(level, event, fields);
+        }
+        catch {
+            // Log's contract: a call never throws, so no caller guards one.
+        }
+    };
+    return Object.freeze({
+        trace: method("trace"),
+        debug: method("debug"),
+        info: method("info"),
+        warn: method("warn"),
+        error: method("error"),
+        fatal: method("fatal"),
+    });
+}
+/** The same log, its calls never throwing. */
+export function guardedLog(log) {
+    return logOf((level, event, fields) => log[level](event, fields));
+}
+/**
+ * A log handing each line at or above `threshold` to every sink, in order. `sinks` answers
+ * undefined while the sinks are being built, and those lines are dropped.
+ */
+export function routedLog(threshold, clock, sinks) {
+    const floor = thresholds.indexOf(threshold);
+    return logOf((level, event, fields) => {
+        if (thresholds.indexOf(level) < floor)
+            return;
+        const list = sinks();
+        if (list === undefined)
+            return;
+        const line = Object.freeze({
+            level,
+            event,
+            at: clock.now(),
+            fields: Object.freeze({ ...fields }),
+        });
+        for (const sink of list) {
+            try {
+                sink.write(line);
+            }
+            catch {
+                // A failing sink must not keep the line from the next sink.
+            }
+        }
+    });
+}

package/kernel/src/module.d.ts

@@ -0,0 +1,67 @@
+import type { ZodType } from "zod";
+import type { Contract, ExtensionPoint } from "./handles.js";
+import type { ReadinessReport } from "./readiness.js";
+import type { Refusal } from "./refusal.js";
+import type { Runtime } from "./runtime.js";
+export interface BuildContext<S> extends Runtime {
+    readonly section: S;
+    get<T>(contract: Contract<T>): Promise<T>;
+    collect<T>(point: ExtensionPoint<T>): Promise<readonly T[]>;
+    /**
+     * The interface a contract names, for use once assembly is done; it builds nothing now, so a
+     * contributor may hold its owner's. Called during assembly, or after a refused one, it throws.
+     */
+    late<T>(contract: Contract<T>): () => T;
+    /**
+     * Whether every contribution to `probes` passes within `deadlineMs` (1 to 2^31-1, else it
+     * rejects with a TypeError), with each probe's result by name; unready and all down once stop
+     * begins. It rejects until assembly is done.
+     */
+    readinessReport(deadlineMs: number): Promise<ReadinessReport>;
+    onStart(hook: () => Promise<void> | void): void;
+    /**
+     * Hooks run in reverse order, each awaited; one that fails is logged and the next runs. At the
+     * stop deadline the signal aborts, and the hooks left are called without waiting.
+     */
+    onStop(hook: (signal: AbortSignal) => Promise<void> | void): void;
+    /**
+     * Runs `task` every `intervalMs` from the start, never two runs at once. Stopping aborts the
+     * running run's signal and waits for it, before the stop hooks. A failed run is logged, and the
+     * next one comes as usual.
+     */
+    every(intervalMs: number, task: (signal: AbortSignal) => Promise<void>): void;
+    refuse(where: string, reason: string): never;
+    /** Refuses with every problem found at once, so the operator sees them together. */
+    refuseAll(refusals: readonly Refusal[]): never;
+}
+export type Factory<S, T> = (context: BuildContext<S>) => T | Promise<T>;
+export interface Provision<S> {
+    readonly contract: Contract<unknown>;
+    readonly create: Factory<S, unknown>;
+}
+export interface Contribution<S> {
+    readonly point: ExtensionPoint<unknown>;
+    readonly create: Factory<S, unknown>;
+}
+export interface ModuleHead<S> {
+    readonly name: string;
+    readonly section?: ZodType<S>;
+    /** A function is asked only with a section that passed its schema. */
+    readonly replicaSafe?: boolean | ((section: S) => boolean);
+}
+export interface ModuleDefinition<S = unknown> extends ModuleHead<S> {
+    readonly provides?: readonly Provision<S>[];
+    readonly contributes?: readonly Contribution<S>[];
+}
+/** A module with its section type erased, as assembly sees it. */
+export type Module = ModuleDefinition<unknown>;
+/** Two steps, so the value type is fixed by the handle before the factory is checked. */
+export interface Parts<S> {
+    provide<T>(contract: Contract<T>): {
+        by(create: Factory<S, T>): Provision<S>;
+    };
+    contribute<T>(point: ExtensionPoint<T>): {
+        by(create: Factory<S, T>): Contribution<S>;
+    };
+}
+export declare function defineModule<S = undefined>(head: ModuleHead<S>, body?: (parts: Parts<S>) => readonly (Provision<S> | Contribution<S>)[]): Module;

package/kernel/src/module.js

@@ -0,0 +1,18 @@
+const parts = {
+    provide: (contract) => ({
+        by: (create) => ({ contract: contract, create }),
+    }),
+    contribute: (point) => ({
+        // keyOf takes T, so a point is not assignable to the unknown one directly.
+        by: (create) => ({ point: point, create }),
+    }),
+};
+export function defineModule(head, body = () => []) {
+    const all = body(parts);
+    const definition = {
+        ...head,
+        provides: all.filter((part) => "contract" in part),
+        contributes: all.filter((part) => "point" in part),
+    };
+    return Object.freeze(definition);
+}

package/kernel/src/readiness.d.ts

@@ -0,0 +1,24 @@
+import type { Runtime } from "./runtime.js";
+export interface Probe {
+    /** The resource's name, as the log shows it; the key at `probes`. */
+    readonly name: string;
+    /** Resolves when the resource answers, rejects when it does not. Aborted at the deadline. */
+    check(signal: AbortSignal): Promise<void>;
+}
+export type Readiness = "ready" | "unready";
+/** One run's answer with each probe's result, in contribution order. */
+export interface ReadinessReport {
+    readonly answer: Readiness;
+    readonly probes: readonly {
+        readonly name: string;
+        readonly up: boolean;
+    }[];
+}
+export declare const probes: import("./handles.js").ExtensionPoint<Probe>;
+/** A timer's delay in whole ms, from 1 to the longest a timer takes (2^31-1). */
+export declare function isTimerMs(ms: number): boolean;
+/**
+ * Answers whether every probe passes within the caller's deadline, joining a check still running.
+ * A check is aborted once no caller waits for it.
+ */
+export declare function readinessOf(list: readonly Probe[], runtime: Runtime, stopping: () => boolean): (deadlineMs: number) => Promise<ReadinessReport>;

package/kernel/src/readiness.js

@@ -0,0 +1,72 @@
+import { deepFreeze } from "./freeze.js";
+import { extensionPoint } from "./handles.js";
+export const probes = extensionPoint("probes", {
+    multiplicity: "keyed",
+    keyOf: (probe) => probe.name,
+});
+/** A timer's delay in whole ms, from 1 to the longest a timer takes (2^31-1). */
+export function isTimerMs(ms) {
+    return Number.isInteger(ms) && ms >= 1 && ms <= 2 ** 31 - 1;
+}
+/**
+ * Answers whether every probe passes within the caller's deadline, joining a check still running.
+ * A check is aborted once no caller waits for it.
+ */
+export function readinessOf(list, runtime, stopping) {
+    const running = new Map();
+    const begin = (probe) => {
+        const existing = running.get(probe);
+        if (existing)
+            return existing;
+        const controller = new AbortController();
+        // Started inside a promise, so a check that throws at once fails like one that rejects.
+        const done = Promise.resolve().then(() => probe.check(controller.signal));
+        const clear = () => running.delete(probe);
+        // This also handles the rejection when nobody waits for the check any more.
+        done.then(clear, clear);
+        const entry = { done, controller, waiting: 0 };
+        running.set(probe, entry);
+        return entry;
+    };
+    const one = async (probe, deadline) => {
+        const started = runtime.clock.now();
+        const entry = begin(probe);
+        entry.waiting++;
+        const result = await Promise.race([
+            entry.done.then(() => ({ outcome: "passed" }), (error) => ({
+                outcome: "failed",
+                kind: error instanceof Error ? error.name : typeof error,
+            })),
+            deadline,
+        ]);
+        entry.waiting--;
+        if (result.outcome === "passed")
+            return true;
+        if (result.outcome === "late" && entry.waiting === 0)
+            entry.controller.abort();
+        runtime.log.warn("kernel.probe_failed", {
+            probe: probe.name,
+            ...result,
+            ms: runtime.clock.now() - started,
+        });
+        return false;
+    };
+    return (deadlineMs) => {
+        if (!isTimerMs(deadlineMs)) {
+            return Promise.reject(new TypeError("the readiness deadline must be a whole number of ms, 1 to 2^31-1"));
+        }
+        const report = (passed, answer) => deepFreeze({
+            answer,
+            probes: list.map((probe, i) => ({ name: probe.name, up: passed[i] === true })),
+        });
+        // Once stop begins, no probe runs and every one reads down.
+        if (stopping())
+            return Promise.resolve(report([], "unready"));
+        const { promise: deadline, resolve } = Promise.withResolvers();
+        const timer = setTimeout(() => resolve({ outcome: "late" }), deadlineMs);
+        timer.unref();
+        return Promise.all(list.map((probe) => one(probe, deadline)))
+            .then((passed) => report(passed, passed.every(Boolean) ? "ready" : "unready"))
+            .finally(() => clearTimeout(timer));
+    };
+}

package/kernel/src/refusal.d.ts

@@ -0,0 +1,19 @@
+export interface Refusal {
+    readonly where: string;
+    readonly reason: string;
+}
+/** Raised by assembly when anything refuses; nothing is served after it. */
+export declare class BootRefused extends Error {
+    readonly refusals: readonly Refusal[];
+    constructor(refusals: readonly Refusal[]);
+}
+/** Thrown by refuse and refuseAll inside a factory; assembly records its refusals. Never leaves the kernel. */
+export declare class RefusalSignal extends Error {
+    readonly refusals: readonly Refusal[];
+    constructor(refusals: readonly Refusal[]);
+}
+export declare class Unavailable extends Error {
+    readonly what: string;
+    constructor(what: string);
+}
+export declare function isUnavailable(error: unknown): error is Unavailable;

package/kernel/src/refusal.js

@@ -0,0 +1,28 @@
+/** Raised by assembly when anything refuses; nothing is served after it. */
+export class BootRefused extends Error {
+    refusals;
+    constructor(refusals) {
+        super(`boot refused (${refusals.length})`);
+        this.name = "BootRefused";
+        this.refusals = Object.freeze([...refusals]);
+    }
+}
+/** Thrown by refuse and refuseAll inside a factory; assembly records its refusals. Never leaves the kernel. */
+export class RefusalSignal extends Error {
+    refusals;
+    constructor(refusals) {
+        super(`${refusals.length} refusal(s)`);
+        this.refusals = refusals;
+    }
+}
+export class Unavailable extends Error {
+    what;
+    constructor(what) {
+        super(`${what} unavailable`);
+        this.name = "Unavailable";
+        this.what = what;
+    }
+}
+export function isUnavailable(error) {
+    return error instanceof Unavailable;
+}

package/kernel/src/runtime.d.ts

@@ -0,0 +1,35 @@
+export interface Clock {
+    now(): number;
+}
+export interface Random {
+    bytes(length: number): Uint8Array;
+}
+export type LogFields = Readonly<Record<string, string | number | boolean>>;
+/** A call never throws: kernel guards every log it hands out, so no caller wraps one in try. */
+export interface Log {
+    trace(event: string, fields?: LogFields): void;
+    debug(event: string, fields?: LogFields): void;
+    info(event: string, fields?: LogFields): void;
+    warn(event: string, fields?: LogFields): void;
+    error(event: string, fields?: LogFields): void;
+    fatal(event: string, fields?: LogFields): void;
+}
+export type LogLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+export interface LogLine {
+    readonly level: LogLevel;
+    readonly event: string;
+    /** Epoch ms, on the kernel's clock. */
+    readonly at: number;
+    readonly fields: LogFields;
+}
+/** Where log lines go; contributed to `logSinks`. */
+export interface LogSink {
+    write(line: LogLine): void;
+}
+export interface Runtime {
+    readonly clock: Clock;
+    readonly random: Random;
+    readonly log: Log;
+}
+export declare const systemClock: Clock;
+export declare const systemRandom: Random;

package/kernel/src/runtime.js

@@ -0,0 +1,5 @@
+import { randomBytes } from "node:crypto";
+export const systemClock = Object.freeze({ now: () => Date.now() });
+export const systemRandom = Object.freeze({
+    bytes: (length) => new Uint8Array(randomBytes(length)),
+});

package/kernel/src/secret.d.ts

@@ -0,0 +1,2 @@
+/** Whether two secrets (strings as UTF-8) hold the same bytes; only equal lengths are compared, in constant time. */
+export declare function sameSecret(a: string | Uint8Array, b: string | Uint8Array): boolean;

package/kernel/src/secret.js

@@ -0,0 +1,7 @@
+import { timingSafeEqual } from "node:crypto";
+/** Whether two secrets (strings as UTF-8) hold the same bytes; only equal lengths are compared, in constant time. */
+export function sameSecret(a, b) {
+    const x = typeof a === "string" ? Buffer.from(a, "utf8") : a;
+    const y = typeof b === "string" ? Buffer.from(b, "utf8") : b;
+    return x.byteLength === y.byteLength && timingSafeEqual(x, y);
+}

package/kernel/src/settings.d.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+export declare const kernelSection: z.ZodObject<{
+    deployment: z.ZodEnum<{
+        single: "single";
+        multi: "multi";
+    }>;
+    logging: z.ZodDefault<z.ZodObject<{
+        level: z.ZodDefault<z.ZodEnum<{
+            trace: "trace";
+            debug: "debug";
+            info: "info";
+            warn: "warn";
+            error: "error";
+            fatal: "fatal";
+            silent: "silent";
+        }>>;
+    }, z.core.$strict>>;
+    "stop-seconds": z.ZodDefault<z.ZodInt>;
+}, z.core.$strict>;
+export type KernelSettings = z.output<typeof kernelSection>;

package/kernel/src/settings.js

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import { thresholds } from "./log.js";
+const stopRange = { error: "whole seconds from 1 to 3600" };
+export const kernelSection = z.strictObject({
+    deployment: z
+        .enum(["single", "multi"], { error: "single or multi" })
+        .describe("single or multi; multi refuses a module unsafe on multiple instances"),
+    logging: z
+        .strictObject({
+        level: z
+            .enum(thresholds, { error: thresholds.join(", ") })
+            .default("info")
+            .describe("the lowest level logged (trace to fatal), or silent for none"),
+    }, { error: "holds only level" })
+        .default({ level: "info" })
+        .describe("the log"),
+    "stop-seconds": z
+        .int(stopRange)
+        .min(1, stopRange)
+        .max(3600, stopRange)
+        .default(30)
+        .describe("whole seconds a stop given no deadline waits for its hooks; an orchestrator's grace period must be longer"),
+}, { error: "needs a section holding only deployment, logging and stop-seconds" });

package/kernel/src/testing.d.ts

@@ -0,0 +1,31 @@
+import type { Contract } from "./handles.js";
+import type { Module } from "./module.js";
+import { type Log, type LogLine, type Runtime } from "./runtime.js";
+/** A log that writes nothing. */
+export declare const quietLog: Log;
+/** A runtime for tests: the system clock and randomness and a quiet log, unless the test sets one. */
+export declare function quietRuntime(parts?: Partial<Runtime>): Runtime;
+export interface RecordingLog {
+    readonly log: Log;
+    /** The lines so far, in order, with their level; fields are empty when the call gave none. */
+    lines(): readonly Omit<LogLine, "at">[];
+}
+export declare function recordingLog(): RecordingLog;
+/** Names of T's members that are functions answering a promise. Sync methods and values are not switchable. */
+export type AsyncMethodOf<T> = {
+    [K in keyof T]-?: T[K] extends (...args: never[]) => Promise<unknown> ? K : never;
+}[keyof T] & string;
+export interface UnavailableSwitch<T extends object> {
+    /** T with each async method going through this switch; other members read through to `implementation`. */
+    wrap(implementation: T): T;
+    /** The next call of `method` rejects with Unavailable and does not reach the implementation. Called n times, the next n calls do. */
+    failNext(method: AsyncMethodOf<T>): void;
+    /** From now on, every call of these methods rejects with Unavailable and does not reach the implementation. */
+    unavailable(method: AsyncMethodOf<T>, ...more: AsyncMethodOf<T>[]): void;
+    /** Calls reach the implementation again; pending failNext calls are dropped. */
+    restore(): void;
+}
+/** `what` goes into each Unavailable it throws. */
+export declare function unavailableSwitch<T extends object>(what?: string): UnavailableSwitch<T>;
+/** The same module, its provision of `provided` built and then wrapped by `by`; every other part unchanged. Throws TypeError at once if the module does not provide `provided`. */
+export declare function switchedModule<T extends object>(module: Module, provided: Contract<T>, by: UnavailableSwitch<T>): Module;

package/kernel/src/testing.js

@@ -0,0 +1,99 @@
+import { Unavailable } from "./refusal.js";
+import { systemClock, systemRandom, } from "./runtime.js";
+/** A log that writes nothing. */
+export const quietLog = Object.freeze({
+    trace: () => { },
+    debug: () => { },
+    info: () => { },
+    warn: () => { },
+    error: () => { },
+    fatal: () => { },
+});
+/** A runtime for tests: the system clock and randomness and a quiet log, unless the test sets one. */
+export function quietRuntime(parts = {}) {
+    return Object.freeze({ clock: systemClock, random: systemRandom, log: quietLog, ...parts });
+}
+export function recordingLog() {
+    const kept = [];
+    const writer = (level) => (event, fields) => {
+        kept.push(Object.freeze({ level, event, fields: Object.freeze({ ...fields }) }));
+    };
+    return Object.freeze({
+        log: Object.freeze({
+            trace: writer("trace"),
+            debug: writer("debug"),
+            info: writer("info"),
+            warn: writer("warn"),
+            error: writer("error"),
+            fatal: writer("fatal"),
+        }),
+        lines: () => [...kept],
+    });
+}
+function memberKeys(implementation) {
+    const keys = new Set();
+    for (let at = implementation; at !== null && at !== Object.prototype; at = Object.getPrototypeOf(at)) {
+        for (const key of Reflect.ownKeys(at))
+            if (key !== "constructor")
+                keys.add(key);
+    }
+    return [...keys];
+}
+/** `what` goes into each Unavailable it throws. */
+export function unavailableSwitch(what = "test") {
+    const pending = new Map();
+    const down = new Set();
+    const fails = (method) => {
+        if (down.has(method))
+            return true;
+        const left = pending.get(method) ?? 0;
+        if (left === 0)
+            return false;
+        pending.set(method, left - 1);
+        return true;
+    };
+    return Object.freeze({
+        wrap(implementation) {
+            const source = implementation;
+            const wrapped = {};
+            for (const key of memberKeys(implementation)) {
+                if (typeof source[key] === "function") {
+                    wrapped[key] = (...args) => fails(key)
+                        ? Promise.reject(new Unavailable(what))
+                        : Reflect.apply(source[key], implementation, args);
+                }
+                else {
+                    Object.defineProperty(wrapped, key, { enumerable: true, get: () => source[key] });
+                }
+            }
+            return Object.freeze(wrapped);
+        },
+        failNext(method) {
+            pending.set(method, (pending.get(method) ?? 0) + 1);
+        },
+        unavailable(method, ...more) {
+            for (const name of [method, ...more])
+                down.add(name);
+        },
+        restore() {
+            pending.clear();
+            down.clear();
+        },
+    });
+}
+/** The same module, its provision of `provided` built and then wrapped by `by`; every other part unchanged. Throws TypeError at once if the module does not provide `provided`. */
+export function switchedModule(module, provided, by) {
+    const provides = module.provides ?? [];
+    if (!provides.some((part) => part.contract === provided)) {
+        throw new TypeError(`${module.name} does not provide ${provided.label}`);
+    }
+    return Object.freeze({
+        ...module,
+        provides: provides.map((part) => part.contract !== provided
+            ? part
+            : {
+                contract: part.contract,
+                create: async (context) => by.wrap((await part.create(context))),
+            }),
+    });
+}

package/keys/README.md

@@ -0,0 +1,39 @@
+# keys
+
+## Responsibilities
+- Reads the provider's signing key ring at boot, signs and verifies with it, and publishes its public key set (JWKS).
+- Reads public key material from outside (PEM and JWK) by one set of rules, for every module that verifies another party's signature.
+
+## Not here
+- The meaning of what is signed. Which outside keys a module trusts, and where it gets them.
+
+## Offers
+- `keys`: sign claims under a `typ` (adding the `kid`), and verify a token, answering valid with frozen claims or why not (`malformed`, `typ`, `kid_unknown`, `kid_expired`, `signature`).
+- Whether signing is asymmetric, the `alg` it signs with, and the path of the public key set, a route contributed to `http` that answers its listed origins.
+- `publicJwk`: a JWK the platform reads as a public key, kept as given.
+- `publicPem`: a public key written as PEM.
+- `verifiesUnder`: whether a JWK may verify, under an algorithm or any of `verifyAlgorithms`.
+- `publicMembers`: a JWK rebuilt from its type's public members alone, without reading it.
+- `isCanonicalJws`: whether a compact JWS is written in its one form; `verify` answers any other as `malformed`. `secretBytes` (exactly or at least n): the setting of a secret's bytes every module takes, strict base64 of at least 8 byte values, never a `REPLACE-` sample; a refusal never names the value.
+- Operator section: `signing` (`kid`, `alg`, and a PKCS8 PEM `private-key`, or for HS256 a hex or base64 `secret`), `next` (`kid`, `alg`, `public-key`), `previous` (`kid`, `alg`, `public-key`, `expires-at`).
+- Test configuration builders (`./testing`), with a new Ed25519 signing key unless a test sets one.
+
+## Invariants
+- Key material has no default; a missing or unreadable key, or one not of its `alg`'s kind, refuses boot.
+- A signing `private-key` not written as PEM is refused by the section, before it is read; so is the fragment's `REPLACE-` placeholder.
+- EdDSA takes Ed25519, ES256 takes P-256, RS256 takes RSA of 2048 bits or more; an HMAC secret is 32 bytes or more.
+- A previous or next key is the provider's own: a private PEM is taken too, and only its public half is used. The next key is published and verifies, but never signs, so verifiers hold it before it signs.
+- A `kid` is 1–128 of letters, digits and `. _ ~ -`, unique in the ring.
+- A token is verified by the key its `kid` names, after its `typ`, and refused once that key's `expires-at` is reached.
+- A payload the key signed that is no JSON is answered as a bad signature.
+- The published set holds public members alone, of unexpired keys; with nothing to publish, it answers 404 `no-store`.
+- The set carries a strong ETag, answers 304 to it, and is cached five minutes.
+- An outside JWK with a private member, a `kid` that is no string, or a key member not in its one form, is refused; so is a private PEM.
+- An outside key may verify only for signatures (`use`, `key_ops`) and only under an algorithm its kind and curve fit.
+
+## Depends on
+- `kernel`, `http`
+
+## Vocabulary
+- key ring: the current signing key, the next key, and past verification keys still within their expiry.
+- claim / `typ`: the content and type of a JWT being signed, owned by the side that asks for the signature.

package/keys/config.example

@@ -0,0 +1,7 @@
+keys {
+	signing {
+		kid = signing-1
+		alg = EdDSA
+		private-key = "REPLACE-PKCS8-PEM-PRIVATE-KEY"
+	}
+}

package/keys/src/contract.d.ts

@@ -0,0 +1,21 @@
+export type VerifyResult = {
+    readonly kind: "valid";
+    readonly claims: Readonly<Record<string, unknown>>;
+} | {
+    readonly kind: "invalid";
+    readonly reason: "malformed" | "typ" | "kid_unknown" | "kid_expired" | "signature";
+};
+export interface Keys {
+    /** True when signatures can be checked with a public key; false for a shared secret. */
+    asymmetric(): boolean;
+    /** The JWS `alg` signatures are made with (the current signing key's). */
+    algorithm(): string;
+    /** The path on `http`'s origin the public key set is published at. */
+    keySetPath(): string;
+    sign(claims: Readonly<Record<string, unknown>>, typ: string): Promise<string>;
+    verify(token: string, typ: string): Promise<VerifyResult>;
+}
+export declare const keys: import("@o3co/auth-provider-foundation/kernel").Contract<Keys>;
+export { isCanonicalJws } from "./jws.js";
+export { type Jwk, publicJwk, publicMembers, publicPem, verifiesUnder, verifyAlgorithms, } from "./public.js";
+export { secretBytes } from "./secret.js";

package/keys/src/contract.js

@@ -0,0 +1,5 @@
+import { contract } from "@o3co/auth-provider-foundation/kernel";
+export const keys = contract("keys");
+export { isCanonicalJws } from "./jws.js";
+export { publicJwk, publicMembers, publicPem, verifiesUnder, verifyAlgorithms, } from "./public.js";
+export { secretBytes } from "./secret.js";

package/keys/src/jwks.d.ts

@@ -0,0 +1,3 @@
+import { type HttpRequest, type HttpResponse } from "@o3co/auth-provider-foundation/http";
+import { type Ring } from "./ring.js";
+export declare function jwksResponse(ring: Ring, now: number, request: HttpRequest): HttpResponse;

package/keys/src/jwks.js

@@ -0,0 +1,26 @@
+import { createHash } from "node:crypto";
+import { noStore } from "@o3co/auth-provider-foundation/http";
+import { expired } from "./ring.js";
+const cacheControl = "public, max-age=300";
+function etagMatches(header, etag) {
+    return header?.split(",").some((tag) => tag.trim() === etag) ?? false;
+}
+export function jwksResponse(ring, now, request) {
+    const published = ring.publicKeys.filter((k) => !expired(k, () => now));
+    if (published.length === 0) {
+        return { status: 404, headers: noStore, body: { json: { error: "jwks_not_published" } } };
+    }
+    const body = JSON.stringify({
+        keys: published.map((k) => ({
+            ...k.key.export({ format: "jwk" }),
+            kid: k.kid,
+            alg: k.alg,
+            use: "sig",
+        })),
+    });
+    const etag = `"${createHash("sha256").update(body).digest("base64url")}"`;
+    const headers = { etag, "cache-control": cacheControl };
+    if (etagMatches(request.headers.get("if-none-match"), etag))
+        return { status: 304, headers };
+    return { status: 200, headers: { ...headers, "content-type": "application/json" }, body };
+}