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

package/http/src/security-headers/security-headers.js

@@ -0,0 +1,58 @@
+import { createHash } from "node:crypto";
+/** Every answer's policy: nothing loads but from this origin, and no one frames it. */
+const policy = [
+    "default-src 'none'",
+    "base-uri 'self'",
+    "font-src 'self' https: data:",
+    "form-action 'self'",
+    "frame-ancestors 'none'",
+    "img-src 'self' data:",
+    "object-src 'none'",
+    "script-src 'self'",
+    "script-src-attr 'none'",
+    "style-src 'self' https: 'unsafe-inline'",
+    "upgrade-insecure-requests",
+].join(";");
+/** The headers besides the policy that every answer carries, as http sets them. */
+const fixed = Object.freeze({
+    "cross-origin-opener-policy": "same-origin",
+    "cross-origin-resource-policy": "same-origin",
+    "origin-agent-cluster": "?1",
+    "referrer-policy": "no-referrer",
+    "strict-transport-security": "max-age=31536000; includeSubDomains",
+    "x-content-type-options": "nosniff",
+    "x-dns-prefetch-control": "off",
+    "x-download-options": "noopen",
+    "x-frame-options": "SAMEORIGIN",
+    "x-permitted-cross-domain-policies": "none",
+    "x-xss-protection": "0",
+});
+/** An origin a policy's host source can name: no IPv6 literal, no `_`, nothing after the port. */
+const framable = /^https?:\/\/[A-Za-z0-9.-]+(?::\d{1,5})?$/;
+/** A page's policy: its frames and scripts, and nothing else. Throws on a frame it cannot name. */
+function pagePolicy(loads) {
+    const frames = [...new Set(loads.frames)];
+    if (!frames.every((frame) => framable.test(frame)))
+        throw new TypeError("unnamable frame");
+    const scripts = (loads.scripts ?? []).map((text) => `'sha256-${createHash("sha256").update(text).digest("base64")}'`);
+    return [
+        "default-src 'none'",
+        "base-uri 'none'",
+        "form-action 'none'",
+        "frame-ancestors 'none'",
+        ...(frames.length ? [`frame-src ${frames.join(" ")}`] : []),
+        ...(scripts.length ? [`script-src ${scripts.join(" ")}`] : []),
+    ].join("; ");
+}
+/** The answer's headers, the security headers and the policy in place of the route's. */
+export function secured(headers, loads) {
+    const own = Object.entries(headers).filter(([name]) => {
+        const lower = name.toLowerCase();
+        return !Object.hasOwn(fixed, lower) && lower !== "content-security-policy";
+    });
+    return {
+        ...fixed,
+        "content-security-policy": loads ? pagePolicy(loads) : policy,
+        ...Object.fromEntries(own),
+    };
+}

package/http/src/serving/README.md

@@ -0,0 +1,33 @@
+# serving
+
+Internal module of `http`: the server that answers each request with the route it reaches.
+
+## Responsibilities
+- Reads a request's head, finds the route its path reaches, has the route's policies and handler answer, and writes the answer.
+
+## Not here
+- What a request's body holds (`bodies`), how policies apply (`guards`), cross-origin answers (`cors`), the security headers (`security-headers`), and telling a request's end (`ending`).
+- Checking the segments under a `/*` path: a `/*` handler checks them by its own rules.
+
+## Offers
+- `serve`: the routes, guarded by their policies, answered on a Node HTTP server.
+- `drain`: stops the server, cutting what is left once the stop's deadline passes.
+
+## Invariants
+- 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).
+- A GET route also answers HEAD, with the same headers and no body.
+- A path no route reaches gets `404`, and a path whose routes take other methods gets `405` naming them in `Allow`.
+- A preflight to a cross-origin route is answered before the policies.
+- A body the route does not take is refused only after the route's policies have seen the request.
+- The request a policy or handler gets is frozen, and its maps cannot be written to.
+- A policy's or handler's failure is logged by its kind only, never its message.
+- Any other failure is answered `500` and logged as a warning, `http.unexpected_failure`, by the route reached (when known) and its kind only, never its message.
+- A request target that is not a URL gets `400`.
+- An answer whose headers cannot be written gets `500`, with none of its own headers.
+- An answer's length is stated in bytes, so a HEAD answer carries the length its GET would.
+- Stop refuses new connections and closes idle ones.
+- Requests in flight finish (`Connection: close`) until stop's deadline cuts them.
+
+## Depends on
+- `http` (its contract), `kernel`, `request-source`, `client-certificate`; `bodies`, `guards`, `cors`, `security-headers`, `ending`.

package/http/src/serving/server.d.ts

@@ -0,0 +1,17 @@
+import { type Server } from "node:http";
+import { type Clock, type Log } from "@o3co/auth-provider-foundation/kernel";
+import { type TrustedProxies } from "@o3co/auth-provider-foundation/request-source";
+import { type RequestEndObserver } from "../contract.js";
+import type { GuardedRoute } from "../guards/guards.js";
+/** What the server answers with. */
+export interface Serving {
+    readonly routes: readonly GuardedRoute[];
+    readonly proxies: TrustedProxies;
+    readonly origins: ReadonlySet<string>;
+    readonly ends: readonly RequestEndObserver[];
+    readonly log: Log;
+    readonly clock: Clock;
+}
+export declare function serve(serving: Serving): Server;
+/** Accepts nothing new and lets requests in flight finish; once `signal` aborts, closes the rest. */
+export declare function drain(server: Server, signal: AbortSignal): Promise<void>;

package/http/src/serving/server.js

@@ -0,0 +1,174 @@
+import { createServer, validateHeaderName, validateHeaderValue, } from "node:http";
+import { ignoredCertificates } from "@o3co/auth-provider-foundation/client-certificate";
+import { isUnavailable } from "@o3co/auth-provider-foundation/kernel";
+import { ignoredForwarding, sourceOf } from "@o3co/auth-provider-foundation/request-source";
+import { bodyOf } from "../bodies/body.js";
+import { paramsOf, readOnly } from "../bodies/values.js";
+import { noStore, } from "../contract.js";
+import { crossOrigin, preflight } from "../cors/cors.js";
+import { ending } from "../ending/ending.js";
+import { secured } from "../security-headers/security-headers.js";
+/** The request's head; undefined when the request target is not a URL. */
+function frozenHead(message, proxies) {
+    const url = URL.parse(message.url ?? "/", "http://placeholder");
+    if (url === null)
+        return undefined;
+    const headers = new Map();
+    for (const [key, value] of Object.entries(message.headers)) {
+        if (value !== undefined)
+            headers.set(key, Array.isArray(value) ? value.join(", ") : value);
+    }
+    return Object.freeze({
+        method: message.method ?? "GET",
+        path: url.pathname,
+        query: paramsOf(url.searchParams),
+        headers: readOnly(headers),
+        source: sourceOf(proxies, message.socket.remoteAddress ?? "", headers),
+    });
+}
+/** Writes the answer; one whose headers cannot be written becomes a bare 500, as does any failure. */
+function write(res, response, log) {
+    try {
+        const { headers, payload } = serialized(response);
+        for (const [name, value] of Object.entries(headers)) {
+            validateHeaderName(name);
+            for (const v of [value].flat())
+                validateHeaderValue(name, v);
+        }
+        res.writeHead(response.status, headers);
+        res.end(payload);
+    }
+    catch (error) {
+        log.error("http.unwritable", { kind: error instanceof Error ? error.name : typeof error });
+        if (!res.headersSent)
+            res.writeHead(500, secured(noStore));
+        res.end();
+    }
+}
+/** The answer as written: its header fields, security headers, cookies and length included, and its payload. */
+function serialized(response) {
+    const headers = secured(response.headers ?? {}, response.loads);
+    if (response.cookies?.length)
+        headers["set-cookie"] = [...response.cookies];
+    const body = response.body;
+    const isJson = typeof body === "object" && "json" in body;
+    if (isJson)
+        headers["content-type"] ??= "application/json";
+    const payload = isJson ? JSON.stringify(body.json) : body;
+    // Stated, not chunked, so a HEAD answer carries the length its GET would.
+    if (payload !== undefined)
+        headers["content-length"] = String(Buffer.byteLength(payload));
+    return { headers, payload };
+}
+const bare = (status) => ({ status, headers: noStore });
+/** The routes a path reaches: those of exactly that path, or else of the longest `/*` above it. */
+function reaching(routes, path) {
+    const exact = routes.filter((r) => r.path === path);
+    if (exact.length > 0)
+        return exact;
+    const under = routes.filter((r) => r.path.endsWith("/*") && path.startsWith(r.path.slice(0, -1)));
+    const longest = Math.max(0, ...under.map((r) => r.path.length));
+    return under.filter((r) => r.path.length === longest);
+}
+function routeFor(reached, method) {
+    const route = reached.find((r) => r.method === method);
+    return route ?? (method === "HEAD" ? reached.find((r) => r.method === "GET") : undefined);
+}
+async function answer(serving, head, message, nameRoute) {
+    const reaches = reaching(serving.routes, head.path);
+    const origin = head.headers.get("origin");
+    const asked = head.headers.get("access-control-request-method");
+    if (head.method === "OPTIONS" && asked !== undefined) {
+        const answered = preflight(reaches, asked, origin, serving.origins);
+        if (answered)
+            return answered;
+    }
+    const route = routeFor(reaches, head.method);
+    if (!route) {
+        if (reaches.length === 0)
+            return bare(404);
+        const allowed = reaches.flatMap((r) => (r.method === "GET" ? ["GET", "HEAD"] : [r.method]));
+        return { status: 405, headers: { ...noStore, allow: allowed.join(", ") } };
+    }
+    nameRoute(route.path);
+    const response = await handled(route, head, message, serving.log);
+    return route.cors ? crossOrigin(route.cors, origin, serving.origins, response) : response;
+}
+async function handled(route, head, message, log) {
+    const { refused, ...body } = await bodyOf(route.takes, message);
+    const request = Object.freeze({ ...head, ...body });
+    try {
+        const guarded = (await route.guard?.(request)) ?? "pass";
+        if (guarded !== "pass")
+            return guarded;
+        if (refused)
+            return bare(refused);
+        return await route.handle(request);
+    }
+    catch (error) {
+        if (isUnavailable(error)) {
+            log.warn("http.unavailable", { what: error.what });
+            return bare(503);
+        }
+        log.error("http.failed", { kind: error instanceof Error ? error.name : typeof error });
+        return bare(500);
+    }
+}
+/** Warns of the forwarded headers a request's peer sent and were ignored, in http's words. */
+function ignoredHeaders({ proxies, log, clock }) {
+    const forwarding = ignoredForwarding(proxies, clock);
+    const certificates = ignoredCertificates(proxies.certificate, clock);
+    return (head, peer) => {
+        const fields = { peer: head.source.address };
+        if (forwarding(peer, head.headers))
+            log.warn("http.forwarded_from_untrusted_peer", fields);
+        if (certificates(head.headers, head.source.clientCertificate)) {
+            log.warn("http.client_certificate_ignored", fields);
+        }
+    };
+}
+export function serve(serving) {
+    const { proxies, log, clock } = serving;
+    const warn = ignoredHeaders(serving);
+    const server = createServer((req, res) => {
+        // Outside the chain, so it must never throw: it reads the clock and adds listeners; observers
+        // are told later. Every other step runs inside, so a throw there is answered.
+        const told = ending(serving.ends, clock, req, res);
+        let route;
+        const nameRoute = (path) => {
+            route = path;
+            told(path);
+        };
+        const reply = (response) => {
+            const stopping = !server.listening;
+            if (stopping)
+                res.setHeader("connection", "close");
+            write(res, response, log);
+        };
+        void Promise.resolve()
+            .then(() => {
+            const head = frozenHead(req, proxies);
+            if (head === undefined)
+                return bare(400);
+            warn(head, req.socket.remoteAddress ?? "");
+            return answer(serving, head, req, nameRoute);
+        })
+            .then(reply)
+            .catch((error) => {
+            const kind = error instanceof Error ? error.name : typeof error;
+            log.warn("http.unexpected_failure", { ...(route && { route }), kind });
+            reply(bare(500));
+        });
+    });
+    return server;
+}
+/** Accepts nothing new and lets requests in flight finish; once `signal` aborts, closes the rest. */
+export function drain(server, signal) {
+    const closed = new Promise((resolve) => server.close(() => resolve()));
+    const cut = () => server.closeAllConnections();
+    if (signal.aborted)
+        cut();
+    else
+        signal.addEventListener("abort", cut, { once: true });
+    return closed;
+}

package/http/src/settings/README.md

@@ -0,0 +1,16 @@
+# settings
+
+Internal module of `http`: the schema of `http`'s operator section.
+
+## Responsibilities
+- Decides which settings boot, and says what each means in its description (the settings list).
+
+## Not here
+- The trusted proxies and hops (`request-source`'s `sourceSettings`) and where the client's certificate is forwarded (`client-certificate`'s `certificateSettings`): the section takes their parts under its own keys.
+- What the settings drive: listening, a request's source, cookies, cross-origin answers.
+
+## Offers
+- The section's schema, each key described.
+
+## Depends on
+- `zod`, `request-source`, `client-certificate`.

package/http/src/settings/section.d.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+export declare const section: z.ZodObject<{
+    host: z.ZodDefault<z.ZodString>;
+    port: z.ZodDefault<z.ZodNumber>;
+    "trusted-proxies": z.ZodDefault<z.ZodArray<z.ZodString>>;
+    "public-origin": z.ZodOptional<z.ZodURL>;
+    "cors-origins": z.ZodDefault<z.ZodArray<z.ZodURL>>;
+    "insecure-origin": z.ZodDefault<z.ZodBoolean>;
+    "proxy-hops": z.ZodDefault<z.ZodNumber>;
+    "client-certificate": z.ZodOptional<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">>;
+}, z.core.$strict>;

package/http/src/settings/section.js

@@ -0,0 +1,37 @@
+import { certificateSettings } from "@o3co/auth-provider-foundation/client-certificate";
+import { sourceSettings } from "@o3co/auth-provider-foundation/request-source";
+import { z } from "zod";
+export const section = z
+    .strictObject({
+    host: z.string().default("127.0.0.1").describe("The address it listens on."),
+    port: z
+        .number()
+        .int()
+        .min(0)
+        .max(65535)
+        .default(8080)
+        .describe("The port it listens on; 0 takes a free one."),
+    "trusted-proxies": sourceSettings.shape["trusted-proxies"],
+    "public-origin": z
+        .url({ protocol: /^https?$/ })
+        .refine((s) => new URL(s).origin === s, "origin only (no path)")
+        .optional()
+        .describe("The scheme, host and port users reach this deployment at: an origin only, with no path."),
+    "cors-origins": z
+        .array(z
+        .url({ protocol: /^https$/ })
+        .refine((s) => !s.includes("*") && new URL(s).origin === s, "an https origin"))
+        .default([])
+        .describe("The https origins whose pages may read cross-origin routes: exact, without a pattern."),
+    "insecure-origin": z
+        .boolean()
+        .default(false)
+        .describe("Accepts a plain-http `public-origin`, knowing its cookies cannot be made secure: an http `public-origin` boots only with it."),
+    "proxy-hops": sourceSettings.shape["proxy-hops"],
+    /** Where a trusted proxy forwards the client's certificate; none is read without it. */
+    "client-certificate": certificateSettings.optional(),
+})
+    .refine((s) => !s["public-origin"]?.startsWith("http:") || s["insecure-origin"], {
+    message: "an http public origin needs insecure-origin set explicitly",
+    path: ["public-origin"],
+});

package/http/src/testing.d.ts

@@ -0,0 +1,37 @@
+import type { Source } from "@o3co/auth-provider-foundation/request-source";
+import type { z } from "zod";
+import type { HttpRequest } from "./contract.js";
+import type { section } from "./settings/section.js";
+export type HttpSettings = z.input<typeof section>;
+/** The http part of a test's configuration: any free port, unless the test sets one. */
+export declare function httpConfig(settings?: Partial<HttpSettings>): {
+    http: {
+        host?: string | undefined;
+        port: number | undefined;
+        "trusted-proxies"?: string[] | undefined;
+        "public-origin"?: string | undefined;
+        "cors-origins"?: string[] | undefined;
+        "insecure-origin"?: boolean | undefined;
+        "proxy-hops"?: number | undefined;
+        "client-certificate"?: {
+            dialect: "rfc9440";
+            header?: string | undefined;
+            "chain-header"?: string | undefined;
+        } | {
+            dialect: "pem";
+            header: string;
+        } | {
+            dialect: "xfcc";
+            header?: string | undefined;
+        } | undefined;
+    };
+};
+type Plain = ReadonlyMap<string, readonly string[]>;
+/** A test's request: an HTTPS GET of `/` from 127.0.0.1, empty unless said; read-only as the server gives it. */
+export declare function testRequest(parts?: Partial<Omit<HttpRequest, "source" | "query" | "form" | "fields">> & {
+    readonly query?: Plain;
+    readonly form?: Plain;
+    readonly fields?: Plain;
+    readonly source?: Partial<Source>;
+}): HttpRequest;
+export {};

package/http/src/testing.js

@@ -0,0 +1,24 @@
+import { deepFreeze } from "@o3co/auth-provider-foundation/kernel";
+import { fieldsOf, readOnly, valuesOf } from "./bodies/values.js";
+/** The http part of a test's configuration: any free port, unless the test sets one. */
+export function httpConfig(settings = {}) {
+    return { http: { port: 0, ...settings } };
+}
+/** A test's request: an HTTPS GET of `/` from 127.0.0.1, empty unless said; read-only as the server gives it. */
+export function testRequest(parts = {}) {
+    const { query, form: sentForm, fields, json: sentJson, headers, source, ...rest } = parts;
+    const form = valuesOf(sentForm ?? new Map());
+    const json = sentJson && deepFreeze(structuredClone(sentJson));
+    const read = json ? { ...fieldsOf(json), json } : { fields: form };
+    return Object.freeze({
+        method: "GET",
+        path: "/",
+        ...read,
+        ...rest,
+        headers: readOnly(new Map(headers)),
+        query: valuesOf(query ?? new Map()),
+        form,
+        fields: fields ? valuesOf(fields) : read.fields,
+        source: Object.freeze({ address: "127.0.0.1", scheme: "https", determined: true, ...source }),
+    });
+}

package/http-ops/README.md

@@ -0,0 +1,22 @@
+# http-ops
+
+## Responsibilities
+- Answers the liveness and readiness routes, and times each request for `metrics`.
+
+## Not here
+- What each readiness probe checks (the module holding the connection); running them under a deadline (`kernel`).
+- Serving the routes, and telling each request's end (`http`); publishing the counts (`metrics-prometheus`).
+
+## Offers
+- `GET /_healthcheck`: `200` `{"status":"ok"}`, checking no dependency; like `/readyz`, it uses no policy, takes no body (a body or a type is `415`, as anywhere) and answers `no-store`.
+- `GET /readyz`: `200` `{"status":"ready"}` or `503` `{"status":"unready"}` as the kernel's readiness answers within `readiness-deadline-ms`, never naming what failed; requests share one run, and an unready answer is reused for 1 s from its start. The gauge `auth_dependency_up` gives each probe 1 or 0 from that run, by the name its module chose (no series without probes).
+- The histogram `http_request_duration_seconds` counts each request once, answered or closed, by method (`other` outside the standard nine), the declared path of the route reached (`unmatched` when none) and the status written (`499` when the client closed first).
+- Section `http-ops`: `readiness-deadline-ms`, its key in the settings list.
+- Composition definition: comes by default with `http`.
+
+## Invariants
+- `/readyz` is ready only when every probe passed within the deadline; one failing, late or unanswered (the store's among them) makes it unready.
+- No label holds a value a request brought (its path, query, headers or body) or a user's: methods outside the nine are `other`, routes are declared paths, statuses are numbers, and dependencies are the names their modules chose.
+
+## Depends on
+- `kernel`, `http`, and `metrics` by its contract only (never needed).

package/http-ops/src/liveness.d.ts

@@ -0,0 +1,3 @@
+import { type Route } from "@o3co/auth-provider-foundation/http";
+/** `GET /_healthcheck`: 200 regardless of dependencies, checking none; like any route, 415 to a body. */
+export declare function liveness(): Route;

package/http-ops/src/liveness.js

@@ -0,0 +1,10 @@
+import { noStore } from "@o3co/auth-provider-foundation/http";
+/** `GET /_healthcheck`: 200 regardless of dependencies, checking none; like any route, 415 to a body. */
+export function liveness() {
+    return {
+        method: "GET",
+        path: "/_healthcheck",
+        takes: ["none"],
+        handle: () => ({ status: 200, headers: { ...noStore }, body: { json: { status: "ok" } } }),
+    };
+}

package/http-ops/src/module.d.ts

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

package/http-ops/src/module.js

@@ -0,0 +1,24 @@
+import { requestEnds, routes } from "@o3co/auth-provider-foundation/http";
+import { contract, defineModule, probes } from "@o3co/auth-provider-foundation/kernel";
+import { instruments } from "@o3co/auth-provider-foundation/metrics";
+import { liveness } from "./liveness.js";
+import { dependencyUp, readyz, sharedReadiness } from "./readiness.js";
+import { section } from "./section.js";
+import { requestDuration, timing } from "./timing.js";
+/** The request-duration histogram, labelled by the declared paths of every route. */
+const duration = contract("http-ops.request-duration");
+/** The readiness run `/readyz` and the dependency gauge share, one per assembly. */
+const readiness = contract("http-ops.shared-readiness");
+export default defineModule({ name: "http-ops", section }, (m) => [
+    m
+        .provide(readiness)
+        .by((c) => sharedReadiness((ms) => c.readinessReport(ms), c.section["readiness-deadline-ms"], c.clock)),
+    m.contribute(routes).by(async (c) => readyz(await c.get(readiness))),
+    m.contribute(instruments).by(async (c) => dependencyUp((await c.collect(probes)).map((probe) => probe.name), await c.get(readiness))),
+    m.contribute(routes).by(() => liveness()),
+    m
+        .provide(duration)
+        .by(async (c) => requestDuration((await c.collect(routes)).map((route) => route.path))),
+    m.contribute(instruments).by((c) => c.get(duration)),
+    m.contribute(requestEnds).by(async (c) => timing(await c.get(duration))),
+]);

package/http-ops/src/readiness.d.ts

@@ -0,0 +1,10 @@
+import { type Route } from "@o3co/auth-provider-foundation/http";
+import type { Clock, ReadinessReport } from "@o3co/auth-provider-foundation/kernel";
+import { type Gauge } from "@o3co/auth-provider-foundation/metrics";
+export type SharedReadiness = () => Promise<ReadinessReport>;
+/** One readiness run shared by `/readyz` and the dependency gauge: joined in flight, unready reused. */
+export declare function sharedReadiness(report: (deadlineMs: number) => Promise<ReadinessReport>, deadlineMs: number, clock: Clock): SharedReadiness;
+/** `GET /readyz`: the shared run's answer, never which probe failed. */
+export declare function readyz(shared: SharedReadiness): Route;
+/** `auth_dependency_up`, as legacy names it: 1 or 0 per probe, from the shared run at each sample. */
+export declare function dependencyUp(names: readonly string[], shared: SharedReadiness): Gauge;

package/http-ops/src/readiness.js

@@ -0,0 +1,54 @@
+import { noStore } from "@o3co/auth-provider-foundation/http";
+import { gauge } from "@o3co/auth-provider-foundation/metrics";
+/** How long an unready report serves later callers, counted from when its run started. */
+const reuseMs = 1000;
+/** One readiness run shared by `/readyz` and the dependency gauge: joined in flight, unready reused. */
+export function sharedReadiness(report, deadlineMs, clock) {
+    let last;
+    return () => {
+        const now = clock.now();
+        const fresh = (started) => now >= started && now - started < reuseMs;
+        // Ready is never reused, so a failure or a stop shows at once; a clock set back runs anew.
+        if (last && (!last.settled || (last.settled === "unready" && fresh(last.started)))) {
+            return last.report;
+        }
+        const run = { started: now, report: report(deadlineMs) };
+        run.report.then(({ answer }) => {
+            run.settled = answer;
+        }, () => {
+            run.settled = "unready";
+        });
+        last = run;
+        return run.report;
+    };
+}
+/** `GET /readyz`: the shared run's answer, never which probe failed. */
+export function readyz(shared) {
+    return {
+        method: "GET",
+        path: "/readyz",
+        takes: ["none"],
+        handle: async () => {
+            const { answer } = await shared();
+            return {
+                status: answer === "ready" ? 200 : 503,
+                headers: noStore,
+                body: { json: { status: answer } },
+            };
+        },
+    };
+}
+/** `auth_dependency_up`, as legacy names it: 1 or 0 per probe, from the shared run at each sample. */
+export function dependencyUp(names, shared) {
+    const spec = {
+        name: "auth_dependency_up",
+        help: "1 when a backing dependency answered its readiness probe, 0 otherwise.",
+    };
+    // A label needs one value at least; with no probes the gauge has no label and no series.
+    if (names.length === 0)
+        return gauge({ ...spec, labels: {} }, () => []);
+    return gauge({ ...spec, labels: { dependency: names } }, async () => (await shared()).probes.map((probe) => ({
+        labels: { dependency: probe.name },
+        value: probe.up ? 1 : 0,
+    })));
+}

package/http-ops/src/section.d.ts

@@ -0,0 +1,4 @@
+import { z } from "zod";
+export declare const section: z.ZodObject<{
+    "readiness-deadline-ms": z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;

package/http-ops/src/section.js

@@ -0,0 +1,10 @@
+import { z } from "zod";
+export const section = z.strictObject({
+    "readiness-deadline-ms": z
+        .number()
+        .int()
+        .min(1)
+        .max(2 ** 31 - 1)
+        .default(1000)
+        .describe("How long `GET /readyz` waits for the probes before it answers unready, in whole milliseconds; set it below the orchestrator's own timeout for the check."),
+});

package/http-ops/src/timing.d.ts

@@ -0,0 +1,9 @@
+import type { RequestEndObserver } from "@o3co/auth-provider-foundation/http";
+import { type Histogram } from "@o3co/auth-provider-foundation/metrics";
+type Label = "method" | "route" | "status";
+export type Duration = Histogram<Label>;
+/** Labels come from http's own decisions: the routes' declared paths, never a request's path. */
+export declare function requestDuration(paths: readonly string[]): Duration;
+/** Counts each request's end once by method, the declared route reached and the status written. */
+export declare function timing(duration: Duration): RequestEndObserver;
+export {};

package/http-ops/src/timing.js

@@ -0,0 +1,30 @@
+import { histogram } from "@o3co/auth-provider-foundation/metrics";
+const METHODS = ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "TRACE", "CONNECT"];
+// 100-599. Node writes up to 999; metrics drops a status above 599, warning once.
+const STATUSES = Array.from({ length: 500 }, (_, i) => String(100 + i));
+// No route's handler ran: 400, 404, 405 and preflight answers.
+const UNMATCHED = "unmatched";
+/** Labels come from http's own decisions: the routes' declared paths, never a request's path. */
+export function requestDuration(paths) {
+    return histogram({
+        name: "http_request_duration_seconds",
+        help: "HTTP request latency in seconds, by method, route and status.",
+        labels: {
+            method: [...METHODS, "other"],
+            route: [...new Set([...paths, UNMATCHED])],
+            status: STATUSES,
+        },
+        buckets: [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10],
+    });
+}
+/** Counts each request's end once by method, the declared route reached and the status written. */
+export function timing(duration) {
+    return {
+        ended: ({ method, route, status, ms }) => {
+            // 499: the client closed before any answer was written.
+            const written = status === "closed" ? "499" : String(status);
+            const known = METHODS.find((m) => m === method) ?? "other";
+            duration.observe({ method: known, route: route ?? UNMATCHED, status: written }, ms / 1000);
+        },
+    };
+}