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

package/http/src/bodies/README.md

@@ -0,0 +1,31 @@
+# bodies
+
+Internal module of `http`: the values a request is sent with, by name, from its body as its route takes it and from its query alike.
+
+## Responsibilities
+- Tells a body's kind from its type, and reads a form or a JSON object up to the size limit.
+- Gives the received values by name as read-only maps.
+
+## Not here
+- Which bodies a route takes (the route's declaration).
+- What a value means, and whether it must be single (the route's).
+- What a mistyped member means (the route's).
+
+## Offers
+- A request's body as its route takes it: its form, its fields, the JSON object and its mistyped names, or the status that refuses it.
+- Values by name, read-only, from a map, a query, a form, or a JSON object's fields: `single` gives a name's value when it holds exactly one, and `repeated` the names that hold more.
+
+## Invariants
+- 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`.
+- A route may take a form, JSON, none, or several.
+- A request's fields are its body's values by name.
+- A JSON member that is not a string is no field, and its name is mistyped.
+- A body the route does not declare is `415`, and gives no fields.
+- A route that declares no bodies reads a form when one is sent, and ignores any other body.
+- No type and nothing sent is no body.
+- The values of a name keep the order sent.
+- The maps, their value lists and the mistyped names cannot be written to, and a write to a map throws.
+
+## Depends on
+- `http` (its contract: the body kinds), and `kernel` (freezing).

package/http/src/bodies/body.d.ts

@@ -0,0 +1,6 @@
+import type { IncomingMessage } from "node:http";
+import type { BodyKind, HttpRequest } from "../contract.js";
+/** A request's body as a route that takes these kinds reads it; `refused` is the status refusing it. */
+export declare function bodyOf(takes: readonly BodyKind[] | undefined, message: IncomingMessage): Promise<Pick<HttpRequest, "form" | "fields" | "json" | "mistyped"> & {
+    refused?: number;
+}>;

package/http/src/bodies/body.js

@@ -0,0 +1,69 @@
+import { deepFreeze } from "@o3co/auth-provider-foundation/kernel";
+import { repeatsName } from "./json.js";
+import { fieldsOf, paramsOf, valuesOf } from "./values.js";
+const limit = 64 * 1024;
+const typeOf = (message) => message.headers["content-type"]?.split(";")[0]?.trim().toLowerCase();
+/** The body up to the limit; undefined past it. */
+async function bytesOf(message) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of message) {
+        size += chunk.length;
+        if (size > limit)
+            return undefined;
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks);
+}
+/** Whether a request has no body: no type, and nothing sent. Reads, and so consumes, an untyped body. */
+const isEmpty = async (message) => typeOf(message) === undefined && (await bytesOf(message))?.length === 0;
+/** A form body up to the limit; anything else, or too large, leaves the form empty. */
+async function formOf(message) {
+    if (typeOf(message) !== "application/x-www-form-urlencoded")
+        return valuesOf(new Map());
+    const bytes = await bytesOf(message);
+    return bytes ? paramsOf(new URLSearchParams(bytes.toString("utf8"))) : valuesOf(new Map());
+}
+const kinds = new Map([
+    ["application/x-www-form-urlencoded", "form"],
+    ["application/json", "json"],
+]);
+/** Throws on bytes that are not UTF-8, instead of replacing them; a BOM is kept, so refused. */
+const utf8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+/** A JSON object body, or the status that answers one that cannot be read. */
+async function jsonOf(message) {
+    const bytes = await bytesOf(message);
+    if (!bytes)
+        return 413;
+    try {
+        const text = utf8.decode(bytes);
+        const value = JSON.parse(text);
+        const object = typeof value === "object" && value !== null && !Array.isArray(value);
+        // A name given twice is read as either value by one parser or another.
+        return object && !repeatsName(text) ? deepFreeze(value) : 400;
+    }
+    catch {
+        return 400;
+    }
+}
+/** A body read as a form, its fields the form's; `refused` when the request is answered instead. */
+const asForm = (form, refused) => ({
+    form,
+    fields: form,
+    ...(refused === undefined ? {} : { refused }),
+});
+/** A request's body as a route that takes these kinds reads it; `refused` is the status refusing it. */
+export async function bodyOf(takes, message) {
+    const kind = (await isEmpty(message)) ? "none" : kinds.get(typeOf(message));
+    // A route that declares no bodies reads a form when one is sent, and ignores any other.
+    if (takes === undefined)
+        return asForm(await formOf(message));
+    if (kind === undefined || !takes.includes(kind))
+        return asForm(valuesOf(new Map()), 415);
+    if (kind !== "json")
+        return asForm(await formOf(message));
+    const json = await jsonOf(message);
+    if (typeof json === "number")
+        return asForm(valuesOf(new Map()), json);
+    return { form: valuesOf(new Map()), ...fieldsOf(json), json };
+}

package/http/src/bodies/json.d.ts

@@ -0,0 +1,2 @@
+/** Whether a JSON text, one that parses, names a member twice in one object, at any depth. */
+export declare function repeatsName(text: string): boolean;

package/http/src/bodies/json.js

@@ -0,0 +1,35 @@
+/** Where the string starting at `at` closes. */
+function closing(text, at) {
+    let end = at + 1;
+    while (end < text.length && text[end] !== '"')
+        end += text[end] === "\\" ? 2 : 1;
+    return end;
+}
+/** Whether a JSON text, one that parses, names a member twice in one object, at any depth. */
+export function repeatsName(text) {
+    // Per open object its names so far; none for an open array.
+    const open = [];
+    let atName = false;
+    for (let at = 0; at < text.length; at++) {
+        const c = text[at];
+        if (c === "{" || c === "[")
+            open.push(c === "{" ? new Set() : undefined);
+        if (c === "}" || c === "]")
+            open.pop();
+        if (c === "{" || c === ",")
+            atName = true;
+        if (c !== '"')
+            continue;
+        const end = closing(text, at);
+        const names = open.at(-1);
+        if (atName && names) {
+            const name = JSON.parse(text.slice(at, end + 1));
+            if (names.has(name))
+                return true;
+            names.add(name);
+        }
+        atName = false;
+        at = end;
+    }
+    return false;
+}

package/http/src/bodies/values.d.ts

@@ -0,0 +1,20 @@
+/** A map whose writes throw; freezing a Map does not stop them. */
+export declare function readOnly<K, V>(map: Map<K, V>): ReadonlyMap<K, V>;
+/** Values received under names (query, form, fields): read-only, in the order sent. */
+export interface Values extends ReadonlyMap<string, readonly string[]> {
+    /** The value when the name holds exactly one; undefined when it is absent or repeated. */
+    single(name: string): string | undefined;
+    /** The names holding more than one value, in order; empty when none. */
+    repeated(): readonly string[];
+}
+export declare function valuesOf(map: ReadonlyMap<string, readonly string[]>): Values;
+/** A query's or a form's values, grouped by name in the order sent. */
+export declare function paramsOf(search: URLSearchParams): Values;
+/**
+ * A JSON object's string members, as fields, and the names of its other members, as mistyped (none
+ * when every member is a string). Neither can be written to.
+ */
+export declare function fieldsOf(json: Readonly<Record<string, unknown>>): {
+    mistyped?: ReadonlySet<string>;
+    fields: Values;
+};

package/http/src/bodies/values.js

@@ -0,0 +1,45 @@
+const throwOnWrite = () => {
+    throw new TypeError("a request is read-only");
+};
+/** A map whose writes throw; freezing a Map does not stop them. */
+export function readOnly(map) {
+    return Object.freeze(Object.assign(map, { set: throwOnWrite, delete: throwOnWrite, clear: throwOnWrite }));
+}
+export function valuesOf(map) {
+    const values = new Map([...map].map(([name, list]) => [name, Object.freeze([...list])]));
+    const single = (name) => {
+        const list = values.get(name);
+        return list?.length === 1 ? list[0] : undefined;
+    };
+    const repeated = () => Object.freeze([...values].filter(([, list]) => list.length > 1).map(([name]) => name));
+    return Object.freeze(Object.assign(values, {
+        set: throwOnWrite,
+        delete: throwOnWrite,
+        clear: throwOnWrite,
+        single,
+        repeated,
+    }));
+}
+/** A query's or a form's values, grouped by name in the order sent. */
+export function paramsOf(search) {
+    const grouped = Map.groupBy(search, ([name]) => name);
+    return valuesOf(new Map([...grouped].map(([name, pairs]) => [name, pairs.map(([, v]) => v)])));
+}
+/**
+ * A JSON object's string members, as fields, and the names of its other members, as mistyped (none
+ * when every member is a string). Neither can be written to.
+ */
+export function fieldsOf(json) {
+    const members = Object.entries(json);
+    const strings = members.flatMap(([name, value]) => typeof value === "string" ? [[name, [value]]] : []);
+    const others = members.filter(([, value]) => typeof value !== "string").map(([name]) => name);
+    const fields = valuesOf(new Map(strings));
+    const mistyped = others.length === 0
+        ? undefined
+        : Object.freeze(Object.assign(new Set(others), {
+            add: throwOnWrite,
+            delete: throwOnWrite,
+            clear: throwOnWrite,
+        }));
+    return { fields, ...(mistyped ? { mistyped } : {}) };
+}

package/http/src/contract.d.ts

@@ -0,0 +1,113 @@
+import type { Source } from "@o3co/auth-provider-foundation/request-source";
+import type { Values } from "./bodies/values.js";
+export type { Values } from "./bodies/values.js";
+export type Method = "GET" | "POST" | "PUT" | "DELETE";
+export interface HttpRequest {
+    readonly method: string;
+    readonly path: string;
+    readonly query: Values;
+    /** An `application/x-www-form-urlencoded` body; empty for other bodies. */
+    readonly form: Values;
+    /** A JSON object body, frozen, for a route that takes JSON. */
+    readonly json?: Readonly<Record<string, unknown>>;
+    /** The body's values by name: a form's fields, or a JSON object's strings. */
+    readonly fields: Values;
+    /** The names of a JSON object's members that are not strings, so no field; none when there are none. */
+    readonly mistyped?: ReadonlySet<string>;
+    /** Lower-case names; repeated headers are joined with ", ". */
+    readonly headers: ReadonlyMap<string, string>;
+    readonly source: Source;
+}
+export type Body = string | Uint8Array | {
+    readonly json: unknown;
+};
+/** What a page loads: its answer's policy allows these and nothing else. */
+export interface Loads {
+    /** The origins it frames, as `scheme://host[:port]`. */
+    readonly frames?: readonly string[];
+    /** The text of each inline script it runs. */
+    readonly scripts?: readonly string[];
+}
+export interface HttpResponse {
+    readonly status: number;
+    readonly headers?: Readonly<Record<string, string>>;
+    /** `Set-Cookie` values, one header each. */
+    readonly cookies?: readonly string[];
+    readonly body?: Body;
+    readonly loads?: Loads;
+}
+/** A rule a route can ask http to apply before its handler. Its owner makes it; it is unique as a value. */
+export interface Policy<O = undefined> {
+    readonly kind: "policy";
+    readonly label: string;
+    readonly __options?: O;
+}
+export declare function policy<O = undefined>(label: string): Policy<O>;
+/** A route's use of a policy, with what the route gives it. */
+export interface PolicyUse {
+    readonly policy: Policy<unknown>;
+    readonly options: unknown;
+}
+export declare function use<O>(policy: Policy<O>, ...options: O extends undefined ? [] : [O]): PolicyUse;
+/** How a policy applies: pass the request on to the next, or answer it. Throws Unavailable when it cannot tell. */
+export interface PolicyRule {
+    readonly policy: Policy<unknown>;
+    apply(request: HttpRequest, options: unknown): "pass" | HttpResponse | Promise<"pass" | HttpResponse>;
+}
+export declare function applying<O>(policy: Policy<O>, apply: (request: HttpRequest, options: O) => "pass" | HttpResponse | Promise<"pass" | HttpResponse>): PolicyRule;
+/** The rules of the policies, one per policy; http matches them to policies by value. */
+export declare const policies: import("@o3co/auth-provider-foundation/kernel").ExtensionPoint<PolicyRule>;
+/** A form is `application/x-www-form-urlencoded`; JSON is `application/json`; none is no body at all. */
+export type BodyKind = "form" | "json" | "none";
+/** A route that takes cross-origin requests from the origins the operator lists; never with credentials. */
+export interface CorsRule {
+    /** Request headers a page may send beyond the safelisted ones, lower case. */
+    readonly headers?: readonly string[];
+    /** Response headers a page may read beyond the safelisted ones, lower case. */
+    readonly exposes?: readonly string[];
+}
+export interface Route {
+    readonly method: Method;
+    readonly path: string;
+    /** Applied in this order before `handle`; the first that answers ends the request. */
+    readonly uses?: readonly PolicyUse[];
+    /** The bodies the route takes, by type; any other is `415`. Without it, only a form is read. */
+    readonly takes?: readonly BodyKind[];
+    /** Takes cross-origin requests; without it, none is answered as one. */
+    readonly cors?: CorsRule;
+    handle(request: HttpRequest): HttpResponse | Promise<HttpResponse>;
+}
+export interface Listening {
+    port(): number;
+}
+export declare const routes: import("@o3co/auth-provider-foundation/kernel").ExtensionPoint<Route>;
+export declare const listening: import("@o3co/auth-provider-foundation/kernel").Contract<Listening>;
+/** Where browsers reach this deployment. */
+export interface Site {
+    /** Undefined when the operator did not state it. */
+    readonly origin: string | undefined;
+    /** Whether cookies can be made secure (`__Host-` and Secure): false only for a plain-http origin. */
+    readonly secureCookies: boolean;
+}
+export declare const site: import("@o3co/auth-provider-foundation/kernel").Contract<Site>;
+/** A request's end, once per request, when it was answered or its connection closed. */
+export interface RequestEnd {
+    /** The method as sent. */
+    readonly method: string;
+    /** The declared path of the route the request reached; none when it reached none. */
+    readonly route?: string;
+    /** The status written, or `closed` when the client closed before any answer was written. */
+    readonly status: number | "closed";
+    /** Milliseconds from the request's arrival to its end; never negative. */
+    readonly ms: number;
+}
+/** Hears each request's end, after the request and asynchronously; what it throws or rejects is dropped, never reaching the request or the others. */
+export interface RequestEndObserver {
+    ended(end: RequestEnd): void;
+}
+export declare const requestEnds: import("@o3co/auth-provider-foundation/kernel").ExtensionPoint<RequestEndObserver>;
+/** Headers keeping an answer out of every cache, HTTP/1.0 ones included (RFC 6749 §5.1). */
+export declare const noStore: Readonly<{
+    "cache-control": "no-store";
+    pragma: "no-cache";
+}>;

package/http/src/contract.js

@@ -0,0 +1,23 @@
+import { contract, extensionPoint } from "@o3co/auth-provider-foundation/kernel";
+export function policy(label) {
+    return Object.freeze({ kind: "policy", label });
+}
+export function use(policy, ...options) {
+    return Object.freeze({ policy: policy, options: options[0] });
+}
+export function applying(policy, apply) {
+    return { policy: policy, apply: apply };
+}
+/** The rules of the policies, one per policy; http matches them to policies by value. */
+export const policies = extensionPoint("http.policies", { multiplicity: "many" });
+export const routes = extensionPoint("http.routes", {
+    multiplicity: "keyed",
+    keyOf: (route) => `${route.method} ${route.path}`,
+});
+export const listening = contract("http.listening");
+export const site = contract("http.site");
+export const requestEnds = extensionPoint("http.request-ends", {
+    multiplicity: "many",
+});
+/** Headers keeping an answer out of every cache, HTTP/1.0 ones included (RFC 6749 §5.1). */
+export const noStore = Object.freeze({ "cache-control": "no-store", pragma: "no-cache" });

package/http/src/cors/README.md

@@ -0,0 +1,24 @@
+# cors
+
+Internal module of `http`: the answers to cross-origin requests, for the routes that declare them.
+
+## Responsibilities
+- Lets the origins the operator lists read the routes that take cross-origin requests.
+
+## Not here
+- Which routes take cross-origin requests (the route's declaration), and which origins are listed (the operator's).
+
+## Offers
+- `crossOrigin`: a declared route's answer, made readable by a listed origin.
+- `preflight`: the answer to a preflight on a path with a declared route.
+
+## Invariants
+- Answers vary by `Origin`, a route's own `Vary` kept.
+- An answer names the request's origin only when it is listed.
+- An answer never names `*`.
+- An answer never allows 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.
+
+## Depends on
+- `http` (its contract).

package/http/src/cors/cors.d.ts

@@ -0,0 +1,5 @@
+import type { CorsRule, HttpResponse, Route } from "../contract.js";
+/** A declared route's answer: varies by origin, and lets a listed origin read it. */
+export declare function crossOrigin(rule: CorsRule, origin: string | undefined, origins: ReadonlySet<string>, response: HttpResponse): HttpResponse;
+/** A preflight's answer where a route of the path takes cross-origin requests; else undefined. */
+export declare function preflight(reached: readonly Route[], method: string, origin: string | undefined, origins: ReadonlySet<string>): HttpResponse | undefined;

package/http/src/cors/cors.js

@@ -0,0 +1,35 @@
+const maxAge = "600";
+function varyingByOrigin(headers) {
+    const vary = headers.vary;
+    return { ...headers, vary: vary ? `${vary}, Origin` : "Origin" };
+}
+/** A declared route's answer: varies by origin, and lets a listed origin read it. */
+export function crossOrigin(rule, origin, origins, response) {
+    const headers = varyingByOrigin(response.headers ?? {});
+    if (origin !== undefined && origins.has(origin)) {
+        headers["access-control-allow-origin"] = origin;
+        if (rule.exposes?.length)
+            headers["access-control-expose-headers"] = rule.exposes.join(", ");
+    }
+    return { ...response, headers };
+}
+/** A preflight's answer where a route of the path takes cross-origin requests; else undefined. */
+export function preflight(reached, method, origin, origins) {
+    const declared = reached.filter((r) => r.cors);
+    if (declared.length === 0)
+        return undefined;
+    const route = declared.find((r) => r.method === (method === "HEAD" ? "GET" : method));
+    if (!route?.cors || origin === undefined || !origins.has(origin)) {
+        return { status: 204, headers: { vary: "Origin" } };
+    }
+    const headers = {
+        vary: "Origin",
+        "access-control-allow-origin": origin,
+        "access-control-allow-methods": declared.map((r) => r.method).join(", "),
+        "access-control-max-age": maxAge,
+    };
+    if (route.cors.headers?.length) {
+        headers["access-control-allow-headers"] = route.cors.headers.join(", ");
+    }
+    return { status: 204, headers };
+}

package/http/src/ending/README.md

@@ -0,0 +1,23 @@
+# ending
+
+Internal module of `http`: tells the observers of `requestEnds` each request's end.
+
+## Responsibilities
+- Tells each request's end, once, answered or closed.
+
+## Not here
+- What an observer does with an end (its owner's).
+
+## Offers
+- `ending`: a request and its answer → the observers told at its end, and the function naming the route it reached.
+
+## Invariants
+- An end names the method sent.
+- An end names the declared path of the route reached (none when none).
+- An end names the status written, or `closed` when the client closed first.
+- An end names the milliseconds taken (never negative).
+- Observers are told after the request, asynchronously.
+- What an observer throws or rejects is dropped.
+
+## Depends on
+- `http` (its contract), `kernel` (the clock).

package/http/src/ending/ending.d.ts

@@ -0,0 +1,5 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Clock } from "@o3co/auth-provider-foundation/kernel";
+import type { RequestEndObserver } from "../contract.js";
+/** Tells each observer of one request's end, once, answered or closed, after the request; gives the function naming the route it reached. */
+export declare function ending(observers: readonly RequestEndObserver[], clock: Clock, req: IncomingMessage, res: ServerResponse): (path: string) => void;

package/http/src/ending/ending.js

@@ -0,0 +1,27 @@
+/** Tells each observer of one request's end, once, answered or closed, after the request; gives the function naming the route it reached. */
+export function ending(observers, clock, req, res) {
+    const started = clock.now();
+    const method = req.method ?? "GET";
+    let route;
+    // An answered request emits finish, then close; the first one ends it.
+    let ended = false;
+    const end = (status) => {
+        if (ended)
+            return;
+        ended = true;
+        // A clock set back gives 0, never a negative time.
+        const ms = Math.max(0, clock.now() - started);
+        const told = Object.freeze({ method, ...(route && { route }), status, ms });
+        for (const observer of observers) {
+            // After the listener; nothing above it catches, and an unhandled rejection stops the process.
+            void Promise.resolve()
+                .then(() => observer.ended(told))
+                .catch(() => { });
+        }
+    };
+    res.once("finish", () => end(res.statusCode));
+    res.once("close", () => end(res.headersSent ? res.statusCode : "closed"));
+    return (path) => {
+        route = path;
+    };
+}

package/http/src/guards/README.md

@@ -0,0 +1,20 @@
+# guards
+
+Internal module of `http`: the policies each route uses, matched to the rules modules contribute.
+
+## Responsibilities
+- Guards each route with the rules of the policies it uses.
+
+## Not here
+- What a policy decides and answers (its owner's).
+- Refusing boot (the package's module, from what this finds).
+
+## Offers
+- `withPolicies`: the routes and the rules → the routes guarded, the routes using a policy with no rule, or a policy with two rules.
+
+## Invariants
+- A route's policies run in its order before its handler, and the first answer ends the request.
+- Policies match by value, and a label only names one in a report.
+
+## Depends on
+- `http` (its contract).

package/http/src/guards/guards.d.ts

@@ -0,0 +1,19 @@
+import type { HttpRequest, HttpResponse, PolicyRule, Route } from "../contract.js";
+/** A route with its guard: the policies it uses, in its order; the first that answers ends the request. */
+export type GuardedRoute = Route & {
+    readonly guard?: (request: HttpRequest) => Promise<HttpResponse | "pass">;
+};
+/** Routes guarded by their policies, matched by value (never label); or a policy with no rule, or two. */
+export declare function withPolicies(routes: readonly Route[], rules: readonly PolicyRule[]): {
+    readonly kind: "applied";
+    readonly routes: readonly GuardedRoute[];
+} | {
+    readonly kind: "missing";
+    readonly missing: readonly {
+        route: Route;
+        label: string;
+    }[];
+} | {
+    readonly kind: "twice";
+    readonly label: string;
+};

package/http/src/guards/guards.js

@@ -0,0 +1,31 @@
+/** Routes guarded by their policies, matched by value (never label); or a policy with no rule, or two. */
+export function withPolicies(routes, rules) {
+    const ruleOf = new Map(rules.map((rule) => [rule.policy, rule]));
+    const twice = rules.find((rule, at) => rules.findIndex((r) => r.policy === rule.policy) !== at);
+    if (twice)
+        return { kind: "twice", label: twice.policy.label };
+    const missing = routes.flatMap((route) => (route.uses ?? [])
+        .filter((use) => !ruleOf.has(use.policy))
+        .map((use) => ({ route, label: use.policy.label })));
+    if (missing.length > 0)
+        return { kind: "missing", missing };
+    return {
+        kind: "applied",
+        routes: routes.map((route) => {
+            const uses = route.uses ?? [];
+            if (uses.length === 0)
+                return route;
+            return {
+                ...route,
+                guard: async (request) => {
+                    for (const use of uses) {
+                        const answer = await ruleOf.get(use.policy).apply(request, use.options);
+                        if (answer !== "pass")
+                            return answer;
+                    }
+                    return "pass";
+                },
+            };
+        }),
+    };
+}

package/http/src/module.d.ts

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

package/http/src/module.js

@@ -0,0 +1,46 @@
+import { once } from "node:events";
+import { certificateForwarding } from "@o3co/auth-provider-foundation/client-certificate";
+import { defineModule } from "@o3co/auth-provider-foundation/kernel";
+import { proxiesOf } from "@o3co/auth-provider-foundation/request-source";
+import { listening, policies, requestEnds, routes, site } from "./contract.js";
+import { withPolicies } from "./guards/guards.js";
+import { drain, serve } from "./serving/server.js";
+import { section } from "./settings/section.js";
+export default defineModule({ name: "http", section }, (m) => [
+    m.provide(site).by((c) => {
+        const origin = c.section["public-origin"];
+        return Object.freeze({ origin, secureCookies: !origin?.startsWith("http:") });
+    }),
+    m
+        .provide(certificateForwarding)
+        .by((c) => Object.freeze({ configured: c.section["client-certificate"] !== undefined })),
+    m.provide(listening).by(async (c) => {
+        const applied = withPolicies(await c.collect(routes), await c.collect(policies));
+        if (applied.kind === "twice") {
+            return c.refuse("http.policies", `more than one rule for a policy: ${applied.label}`);
+        }
+        if (applied.kind === "missing") {
+            return c.refuseAll(applied.missing.map(({ route, label }) => ({
+                where: `http.routes:${route.method} ${route.path}`,
+                reason: `uses a policy no module applies: ${label}`,
+            })));
+        }
+        const certificate = c.section["client-certificate"];
+        const server = serve({
+            routes: applied.routes,
+            proxies: proxiesOf(c.section, certificate),
+            origins: new Set(c.section["cors-origins"]),
+            ends: await c.collect(requestEnds),
+            log: c.log,
+            clock: c.clock,
+        });
+        const port = () => server.address().port;
+        c.onStart(async () => {
+            server.listen(c.section.port, c.section.host);
+            await once(server, "listening");
+            c.log.info("http.listening", { port: port() });
+        });
+        c.onStop((signal) => drain(server, signal));
+        return { port };
+    }),
+]);

package/http/src/security-headers/README.md

@@ -0,0 +1,23 @@
+# security-headers
+
+Internal module of `http`: the security headers every answer carries, and a page's policy.
+
+## Responsibilities
+- Sets the security headers of every answer in one place.
+
+## Not here
+- What a page loads (the route's `loads`).
+
+## Offers
+- `secured`: an answer's headers → the same with the security headers, the policy in place of the route's.
+
+## Invariants
+- 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.
+- A page's policy allows the frames and scripts it declares and nothing else.
+- A frame a policy cannot name makes the answer `500`.
+
+## Depends on
+- `http` (its contract).

package/http/src/security-headers/security-headers.d.ts

@@ -0,0 +1,3 @@
+import type { Loads } from "../contract.js";
+/** The answer's headers, the security headers and the policy in place of the route's. */
+export declare function secured<V>(headers: Readonly<Record<string, V>>, loads?: Loads): Record<string, V | string>;