@earendil-works/chord 1.4.0 → 1.5.1

package/dist/node/app/worker.d.ts

@@ -0,0 +1,18 @@
+import type { Principal } from "../../data/index.ts";
+import { type PrincipalAttributes } from "../../host/index.ts";
+import type { Watchable } from "../../watch.ts";
+import type { AppApi, AppKind } from "./app.ts";
+/** What `startWorker` takes: the app's API and kinds as the server's `startServer` has them, this process's modules. */
+export type WorkerOptions<P extends Principal = Principal> = {
+    readonly api: AppApi;
+    readonly kinds: Readonly<Record<string, AppKind>>;
+    /** Extra keep-alive counts of the app (a record of numbers, all zero when idle). */
+    readonly busy?: Watchable<Readonly<Record<string, number>>>;
+    /** Who a span was for (`createHost`'s `principalAttributes`): this worker's hook, as the server's is its own. */
+    readonly principalAttributes?: PrincipalAttributes<P>;
+    /** The worker host's errors (`HostError`) and a failed start's. */
+    readonly onError: (error: unknown) => void;
+};
+/** Runs this process as a worker of the app: once the start message arrived, its host is up and its plugins loaded. */
+export declare function startWorker<P extends Principal>(options: WorkerOptions<P>): void;
+//# sourceMappingURL=worker.d.ts.map

package/dist/node/app/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../../src/node/app/worker.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAc,KAAK,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAM3E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAY,MAAM,UAAU,CAAC;AAM1D,wHAAwH;AACxH,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,SAAS,GAAG,SAAS,IAAI;IAC5D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAClD,oFAAoF;IACpF,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAC5D,iHAAiH;IACjH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAC;IACtD,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3C,CAAC;AAQF,uHAAuH;AACvH,wBAAgB,WAAW,CAAC,CAAC,SAAS,SAAS,EAAE,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI,CAiEhF"}

package/dist/node/app/worker.js

@@ -0,0 +1,84 @@
+// `startWorker` (slice 13 §1): a worker of an app built with the kit, in its entry module. `workerMain` plus the kit's
+// part: the worker's directory under its kind and address with its store, the host at the worker's address acting as
+// the principal the server gave it, connected to the server first, its plugins loaded with the kit's worker facets
+// (`WorkerInfo`, `Files`, `Translations` for a worker that renders final text); when the server has a telemetry store,
+// the host records in memory and sends its spans and metrics to the server every second (decision "The server is the
+// one place telemetry is stored").
+import { join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { createHost } from "../../host/index.js";
+import { openNodeSqliteDatabase } from "../../sqlite/node.js";
+import { openStore, sqliteBackend } from "../../store/index.js";
+import { translationsFacet } from "../../surfaces/index.js";
+import { sendWorkerTelemetry, TelemetryRecorder } from "../../telemetry-ingest/index.js";
+import { workerMain } from "../workers/child.js";
+import { hostDataFacet } from "./data.js";
+import { filesFacet } from "./files.js";
+import { workerInfoFacet } from "./info.js";
+import { privateDirectory, privateStore } from "./layout.js";
+/** How many finished spans a worker keeps while it cannot send (past it new ones are dropped). */
+const WORKER_QUEUE = 10_000;
+/** How often a worker sends what it recorded. */
+const WORKER_SEND_MS = 1000;
+/** Runs this process as a worker of the app: once the start message arrived, its host is up and its plugins loaded. */
+export function startWorker(options) {
+    // The worker's facet kind comes with the start message: every kind's packages are offered, its own are imported.
+    const packages = Object.assign({}, ...Object.values(options.kinds).map((kind) => kind.packages ?? {}));
+    workerMain(async ({ address, start, parent, plugins, onClose }, context) => {
+        // The server's `startServer` sends `{ kit, app }`.
+        const { kit, app } = start;
+        await privateDirectory(kit.dir);
+        await privateStore(join(kit.dir, "store.sqlite"));
+        const store = await openStore(sqliteBackend(await openNodeSqliteDatabase(join(kit.dir, "store.sqlite"))), context);
+        onClose((ctx) => store.close(ctx));
+        const scope = crypto.randomUUID();
+        const recorder = kit.telemetry ? new TelemetryRecorder(() => scope, WORKER_QUEUE) : undefined;
+        const { principalAttributes } = options;
+        // Principals are the app's: the server made these with its `principal` options.
+        const host = createHost({
+            address,
+            principal: kit.principal,
+            store,
+            telemetry: recorder,
+            ...(principalAttributes === undefined ? {} : { principalAttributes }),
+            ...kit.timeouts,
+            onError: options.onError,
+        });
+        onClose((ctx) => host.close(ctx));
+        // First: the server sees the worker started, then the load runs.
+        host.connect(parent, { principal: kit.server, trusted: true }, context);
+        const info = {
+            address: { kind: address.kind, key: address.key, params: address.params },
+            start: app,
+        };
+        const core = [
+            { name: "chord.app.worker-info", facet: workerInfoFacet(info) },
+            { name: "chord.app.files", facet: filesFacet(join(kit.dir, "files"), kit.files, kit.uploads) },
+            {
+                name: "chord.app.data",
+                facet: hostDataFacet(store, join(kit.dir, "files"), kit.server),
+            },
+            { name: "chord.translations", facet: translationsFacet() },
+        ];
+        await plugins.load(host, { kind: kit.facet, core }, context);
+        if (recorder !== undefined) {
+            const sender = sendWorkerTelemetry(host, recorder, context);
+            const timer = setInterval(() => void sender.send(false), WORKER_SEND_MS);
+            timer.unref();
+            // Held after the load (a host holds nothing before). Closers run in reverse: this one before the host
+            // closes, the last spans and partial metrics sent while the link is up, for at most a second.
+            onClose(async () => {
+                clearInterval(timer);
+                await Promise.race([sender.send(true), sleep(WORKER_SEND_MS, undefined, { ref: false })]);
+                sender.stop();
+            });
+        }
+        return options.busy === undefined ? {} : { busy: options.busy };
+    }, {
+        hostPackages: { ...options.api.modules, ...packages },
+        // Worker errors are public (decision "worker errors in public"): a fixed message, never the error's own.
+        redact: () => ({ message: "worker failed" }),
+        onError: options.onError,
+    });
+}
+//# sourceMappingURL=worker.js.map

package/dist/node/app/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["../../../src/node/app/worker.ts"],"names":[],"mappings":"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","sourcesContent":["// `startWorker` (slice 13 §1): a worker of an app built with the kit, in its entry module. `workerMain` plus the kit's\n// part: the worker's directory under its kind and address with its store, the host at the worker's address acting as\n// the principal the server gave it, connected to the server first, its plugins loaded with the kit's worker facets\n// (`WorkerInfo`, `Files`, `Translations` for a worker that renders final text); when the server has a telemetry store,\n// the host records in memory and sends its spans and metrics to the server every second (decision \"The server is the\n// one place telemetry is stored\").\n\nimport { join } from \"node:path\";\nimport { setTimeout as sleep } from \"node:timers/promises\";\nimport type { Principal } from \"../../data/index.ts\";\nimport { createHost, type PrincipalAttributes } from \"../../host/index.ts\";\nimport type { JsonValue } from \"../../json.ts\";\nimport { openNodeSqliteDatabase } from \"../../sqlite/node.ts\";\nimport { openStore, sqliteBackend } from \"../../store/index.ts\";\nimport { translationsFacet } from \"../../surfaces/index.ts\";\nimport { sendWorkerTelemetry, TelemetryRecorder } from \"../../telemetry-ingest/index.ts\";\nimport type { Watchable } from \"../../watch.ts\";\nimport { workerMain } from \"../workers/child.ts\";\nimport type { AppApi, AppKind, KitStart } from \"./app.ts\";\nimport { hostDataFacet } from \"./data.ts\";\nimport { filesFacet } from \"./files.ts\";\nimport { workerInfoFacet } from \"./info.ts\";\nimport { privateDirectory, privateStore } from \"./layout.ts\";\n\n/** What `startWorker` takes: the app's API and kinds as the server's `startServer` has them, this process's modules. */\nexport type WorkerOptions<P extends Principal = Principal> = {\n\treadonly api: AppApi;\n\treadonly kinds: Readonly<Record<string, AppKind>>;\n\t/** Extra keep-alive counts of the app (a record of numbers, all zero when idle). */\n\treadonly busy?: Watchable<Readonly<Record<string, number>>>;\n\t/** Who a span was for (`createHost`'s `principalAttributes`): this worker's hook, as the server's is its own. */\n\treadonly principalAttributes?: PrincipalAttributes<P>;\n\t/** The worker host's errors (`HostError`) and a failed start's. */\n\treadonly onError: (error: unknown) => void;\n};\n\n/** How many finished spans a worker keeps while it cannot send (past it new ones are dropped). */\nconst WORKER_QUEUE = 10_000;\n\n/** How often a worker sends what it recorded. */\nconst WORKER_SEND_MS = 1000;\n\n/** Runs this process as a worker of the app: once the start message arrived, its host is up and its plugins loaded. */\nexport function startWorker<P extends Principal>(options: WorkerOptions<P>): void {\n\t// The worker's facet kind comes with the start message: every kind's packages are offered, its own are imported.\n\tconst packages = Object.assign({}, ...Object.values(options.kinds).map((kind) => kind.packages ?? {}));\n\tworkerMain(\n\t\tasync ({ address, start, parent, plugins, onClose }, context) => {\n\t\t\t// The server's `startServer` sends `{ kit, app }`.\n\t\t\tconst { kit, app } = start as { readonly kit: KitStart; readonly app: JsonValue };\n\t\t\tawait privateDirectory(kit.dir);\n\t\t\tawait privateStore(join(kit.dir, \"store.sqlite\"));\n\t\t\tconst store = await openStore(\n\t\t\t\tsqliteBackend(await openNodeSqliteDatabase(join(kit.dir, \"store.sqlite\"))),\n\t\t\t\tcontext,\n\t\t\t);\n\t\t\tonClose((ctx) => store.close(ctx));\n\t\t\tconst scope = crypto.randomUUID();\n\t\t\tconst recorder = kit.telemetry ? new TelemetryRecorder(() => scope, WORKER_QUEUE) : undefined;\n\t\t\tconst { principalAttributes } = options;\n\t\t\t// Principals are the app's: the server made these with its `principal` options.\n\t\t\tconst host = createHost<P>({\n\t\t\t\taddress,\n\t\t\t\tprincipal: kit.principal as unknown as P,\n\t\t\t\tstore,\n\t\t\t\ttelemetry: recorder,\n\t\t\t\t...(principalAttributes === undefined ? {} : { principalAttributes }),\n\t\t\t\t...kit.timeouts,\n\t\t\t\tonError: options.onError,\n\t\t\t});\n\t\t\tonClose((ctx) => host.close(ctx));\n\t\t\t// First: the server sees the worker started, then the load runs.\n\t\t\thost.connect(parent, { principal: kit.server as unknown as P, trusted: true }, context);\n\t\t\tconst info = {\n\t\t\t\taddress: { kind: address.kind, key: address.key, params: address.params as JsonValue },\n\t\t\t\tstart: app,\n\t\t\t};\n\t\t\tconst core = [\n\t\t\t\t{ name: \"chord.app.worker-info\", facet: workerInfoFacet<P>(info) },\n\t\t\t\t{ name: \"chord.app.files\", facet: filesFacet<P>(join(kit.dir, \"files\"), kit.files, kit.uploads) },\n\t\t\t\t{\n\t\t\t\t\tname: \"chord.app.data\",\n\t\t\t\t\tfacet: hostDataFacet<P>(store, join(kit.dir, \"files\"), kit.server as unknown as P),\n\t\t\t\t},\n\t\t\t\t{ name: \"chord.translations\", facet: translationsFacet<P>() },\n\t\t\t];\n\t\t\tawait plugins.load(host, { kind: kit.facet, core }, context);\n\t\t\tif (recorder !== undefined) {\n\t\t\t\tconst sender = sendWorkerTelemetry(host, recorder, context);\n\t\t\t\tconst timer = setInterval(() => void sender.send(false), WORKER_SEND_MS);\n\t\t\t\ttimer.unref();\n\t\t\t\t// Held after the load (a host holds nothing before). Closers run in reverse: this one before the host\n\t\t\t\t// closes, the last spans and partial metrics sent while the link is up, for at most a second.\n\t\t\t\tonClose(async () => {\n\t\t\t\t\tclearInterval(timer);\n\t\t\t\t\tawait Promise.race([sender.send(true), sleep(WORKER_SEND_MS, undefined, { ref: false })]);\n\t\t\t\t\tsender.stop();\n\t\t\t\t});\n\t\t\t}\n\t\t\treturn options.busy === undefined ? {} : { busy: options.busy };\n\t\t},\n\t\t{\n\t\t\thostPackages: { ...options.api.modules, ...packages },\n\t\t\t// Worker errors are public (decision \"worker errors in public\"): a fixed message, never the error's own.\n\t\t\tredact: () => ({ message: \"worker failed\" }),\n\t\t\tonError: options.onError,\n\t\t},\n\t);\n}\n"]}

package/dist/node/compression.d.ts

@@ -0,0 +1,7 @@
+import type { Compression } from "../link/index.ts";
+/**
+ * Raw deflate at level 1 (`deflateRawSync`), and inflate bounded by `maxOutputLength` (`inflateRawSync`): past the
+ * limit `too_large`, data that is no raw deflate stream `corrupt`.
+ */
+export declare const nodeCompression: Compression;
+//# sourceMappingURL=compression.d.ts.map

package/dist/node/compression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compression.d.ts","sourceRoot":"","sources":["../../src/node/compression.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,WAY7B,CAAC"}

package/dist/node/compression.js

@@ -0,0 +1,25 @@
+// Compression for Chord v2 hosts on Node (§22, slice 4b): the synchronous compressor `createHost({ compression })`
+// takes, over Node's zlib. Node-only, so it lives in `src/node`, outside the portable core (which imports no Node
+// module).
+import { constants as buffer } from "node:buffer";
+import { deflateRawSync, inflateRawSync } from "node:zlib";
+/**
+ * Raw deflate at level 1 (`deflateRawSync`), and inflate bounded by `maxOutputLength` (`inflateRawSync`): past the
+ * limit `too_large`, data that is no raw deflate stream `corrupt`.
+ */
+export const nodeCompression = {
+    deflate: (bytes) => deflateRawSync(bytes, { level: 1 }),
+    inflate: (bytes, limit) => {
+        try {
+            // zlib refuses a bound of 0: inflate at most one byte, and one byte is past a limit of 0.
+            const inflated = inflateRawSync(bytes, { maxOutputLength: Math.max(1, Math.min(limit, buffer.MAX_LENGTH)) });
+            return inflated.byteLength > limit ? { kind: "too_large" } : { kind: "bytes", bytes: inflated };
+        }
+        catch (error) {
+            if (error.code === "ERR_BUFFER_TOO_LARGE")
+                return { kind: "too_large" };
+            return { kind: "corrupt", error };
+        }
+    },
+};
+//# sourceMappingURL=compression.js.map

package/dist/node/compression.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compression.js","sourceRoot":"","sources":["../../src/node/compression.ts"],"names":[],"mappings":"AAAA,mHAAmH;AACnH,kHAAkH;AAClH,WAAW;AAEX,OAAO,EAAE,SAAS,IAAI,MAAM,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAG3D;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAgB;IAC3C,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,cAAc,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IACvD,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;QACzB,IAAI,CAAC;YACJ,0FAA0F;YAC1F,MAAM,QAAQ,GAAG,cAAc,CAAC,KAAK,EAAE,EAAE,eAAe,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC;YAC7G,OAAO,QAAQ,CAAC,UAAU,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;QACjG,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,IAAK,KAAqC,CAAC,IAAI,KAAK,sBAAsB;gBAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;YACzG,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;QACnC,CAAC;IACF,CAAC;CACD,CAAC","sourcesContent":["// Compression for Chord v2 hosts on Node (§22, slice 4b): the synchronous compressor `createHost({ compression })`\n// takes, over Node's zlib. Node-only, so it lives in `src/node`, outside the portable core (which imports no Node\n// module).\n\nimport { constants as buffer } from \"node:buffer\";\nimport { deflateRawSync, inflateRawSync } from \"node:zlib\";\nimport type { Compression } from \"../link/index.ts\";\n\n/**\n * Raw deflate at level 1 (`deflateRawSync`), and inflate bounded by `maxOutputLength` (`inflateRawSync`): past the\n * limit `too_large`, data that is no raw deflate stream `corrupt`.\n */\nexport const nodeCompression: Compression = {\n\tdeflate: (bytes) => deflateRawSync(bytes, { level: 1 }),\n\tinflate: (bytes, limit) => {\n\t\ttry {\n\t\t\t// zlib refuses a bound of 0: inflate at most one byte, and one byte is past a limit of 0.\n\t\t\tconst inflated = inflateRawSync(bytes, { maxOutputLength: Math.max(1, Math.min(limit, buffer.MAX_LENGTH)) });\n\t\t\treturn inflated.byteLength > limit ? { kind: \"too_large\" } : { kind: \"bytes\", bytes: inflated };\n\t\t} catch (error) {\n\t\t\tif ((error as { readonly code?: unknown }).code === \"ERR_BUFFER_TOO_LARGE\") return { kind: \"too_large\" };\n\t\t\treturn { kind: \"corrupt\", error };\n\t\t}\n\t},\n};\n"]}

package/dist/node/http/admission.d.ts

@@ -0,0 +1,63 @@
+import type { Incoming } from "./incoming.ts";
+import type { HttpRelay } from "./router.ts";
+/** Where an admitted request came from. */
+export type Provenance = {
+    readonly kind: "local";
+} | {
+    readonly kind: "remote";
+    readonly host: string;
+} | {
+    readonly kind: "relayed";
+    readonly relay: string;
+    readonly origin: string;
+};
+/** The connection a request arrived on, as its listener knows it (a mounted handler passes what it has). */
+export type Connection = {
+    readonly localAddress?: string;
+    readonly localPort?: number;
+    readonly remoteAddress?: string;
+};
+/** An admitted request: its provenance, its own origin, the origin allowed to frame it (a relay's), how it came. */
+export type Admitted = {
+    readonly provenance: Provenance;
+    readonly origin: string;
+    readonly framer: string | undefined;
+    /** The allowed host it came through: its connections end when that host leaves. */
+    readonly allowed: string | undefined;
+    /** The relay that verified it: its connections end when that relay leaves. */
+    readonly relay: HttpRelay | undefined;
+};
+/** What admission refuses, and the relay hook that threw (reported by the caller). */
+export type Refused = {
+    readonly kind: "refused";
+    readonly failed?: {
+        readonly relay: string;
+        readonly error: unknown;
+    };
+};
+/**
+ * Admits `request` arriving on `connection` with the allowed `hosts` and contributed `relays`, or refuses it (403):
+ * no or several `Host`s, a host neither loopback nor allowed, a loopback `Host` on another connection, forwarded
+ * headers no relay verifies.
+ */
+export declare function admit(request: Incoming, connection: Connection, hosts: ReadonlySet<string>, relays: readonly HttpRelay[]): Admitted | Refused;
+/** What the Fetch Metadata and `Origin` checks read: a request's headers by name. */
+export type HeaderSource = Pick<Incoming, "header">;
+/** Whether `admission` refused its request. */
+export declare function refused(admission: Admitted | Refused): admission is Refused;
+/**
+ * Whether a request is another site's (Fetch Metadata, p2's rule): `Sec-Fetch-Site` neither `same-origin` nor `none`,
+ * or a frame or embed not from this origin. A request without the headers (a script, the TUI) is not.
+ */
+export declare function isForeign(headers: HeaderSource): boolean;
+/**
+ * Whether a foreign request is a top-level navigation (a link followed to a page): `GET`, `navigate`, a `document` (or
+ * `empty`: Chrome on Android launching an installed app).
+ */
+export declare function isNavigation(method: string, headers: HeaderSource): boolean;
+/**
+ * Whether `headers`' `Origin` is acceptable for a request whose own origin is `origin`: absent or equal, and for an
+ * unsafe method from a browser (one sending Fetch Metadata) present and equal.
+ */
+export declare function originAccepted(method: string, headers: HeaderSource, origin: string): boolean;
+//# sourceMappingURL=admission.d.ts.map

package/dist/node/http/admission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admission.d.ts","sourceRoot":"","sources":["../../../src/node/http/admission.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,2CAA2C;AAC3C,MAAM,MAAM,UAAU,GACnB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC1B;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjF,4GAA4G;AAC5G,MAAM,MAAM,UAAU,GAAG;IACxB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF,oHAAoH;AACpH,MAAM,MAAM,QAAQ,GAAG;IACtB,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,mFAAmF;IACnF,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAAC;CACtC,CAAC;AAEF,sFAAsF;AACtF,MAAM,MAAM,OAAO,GAAG;IACrB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;CACtE,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,KAAK,CACpB,OAAO,EAAE,QAAQ,EACjB,UAAU,EAAE,UAAU,EACtB,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,EAC1B,MAAM,EAAE,SAAS,SAAS,EAAE,GAC1B,QAAQ,GAAG,OAAO,CAyBpB;AAED,qFAAqF;AACrF,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAEpD,+CAA+C;AAC/C,wBAAgB,OAAO,CAAC,SAAS,EAAE,QAAQ,GAAG,OAAO,GAAG,SAAS,IAAI,OAAO,CAE3E;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAIxD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAK3E;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAI7F"}

package/dist/node/http/admission.js

@@ -0,0 +1,134 @@
+// Admission (slice 10 §2, R4; decision "The HTTP component's security baseline" (1)-(3), "Relays"): where a request
+// comes from, decided before anything else. Local only when the connection arrived on a loopback address, its `Host`
+// is a loopback name with the listening port, and it carries no forwarded header; a forwarded request on loopback only
+// when a contributed relay verifies it; otherwise only through an allowed host (https); else refused. Foreign requests
+// (another site's, by Fetch Metadata) and a foreign `Origin` are classified here; the handler applies them per route.
+/**
+ * Admits `request` arriving on `connection` with the allowed `hosts` and contributed `relays`, or refuses it (403):
+ * no or several `Host`s, a host neither loopback nor allowed, a loopback `Host` on another connection, forwarded
+ * headers no relay verifies.
+ */
+export function admit(request, connection, hosts, relays) {
+    const host = request.header("host")?.toLowerCase();
+    // Several `Host` headers arrive joined with commas.
+    if (host === undefined || host === "" || host.includes(","))
+        return REFUSED;
+    const { localAddress, localPort } = connection;
+    if (isLoopbackName(host, localPort)) {
+        if (localAddress === undefined || !isLoopbackAddress(localAddress))
+            return REFUSED;
+        if (!request.forwarded())
+            return {
+                provenance: LOCAL,
+                origin: `http://${host}`,
+                framer: undefined,
+                allowed: undefined,
+                relay: undefined,
+            };
+        return relayed(request, relays);
+    }
+    if (!hosts.has(host))
+        return REFUSED;
+    return {
+        provenance: { kind: "remote", host },
+        origin: `https://${host}`,
+        framer: undefined,
+        allowed: host,
+        relay: undefined,
+    };
+}
+/** Whether `admission` refused its request. */
+export function refused(admission) {
+    return "kind" in admission;
+}
+/**
+ * Whether a request is another site's (Fetch Metadata, p2's rule): `Sec-Fetch-Site` neither `same-origin` nor `none`,
+ * or a frame or embed not from this origin. A request without the headers (a script, the TUI) is not.
+ */
+export function isForeign(headers) {
+    const site = headers.header("sec-fetch-site");
+    if (site !== null && site !== "same-origin" && site !== "none")
+        return true;
+    return site !== "same-origin" && FRAMES.has(headers.header("sec-fetch-dest") ?? "");
+}
+/**
+ * Whether a foreign request is a top-level navigation (a link followed to a page): `GET`, `navigate`, a `document` (or
+ * `empty`: Chrome on Android launching an installed app).
+ */
+export function isNavigation(method, headers) {
+    const dest = headers.header("sec-fetch-dest");
+    return (method === "GET" && headers.header("sec-fetch-mode") === "navigate" && (dest === "document" || dest === "empty"));
+}
+/**
+ * Whether `headers`' `Origin` is acceptable for a request whose own origin is `origin`: absent or equal, and for an
+ * unsafe method from a browser (one sending Fetch Metadata) present and equal.
+ */
+export function originAccepted(method, headers, origin) {
+    const sent = headers.header("origin");
+    if (sent !== null)
+        return sent === origin;
+    return SAFE.has(method) || headers.header("sec-fetch-site") === null;
+}
+const REFUSED = { kind: "refused" };
+const LOCAL = { kind: "local" };
+const LOOPBACK_NAMES = ["127.0.0.1", "localhost", "[::1]"];
+/** Whether `host` (lowercased) names this server on loopback with `port` (without it on port 80). */
+function isLoopbackName(host, port) {
+    if (port === undefined)
+        return false;
+    for (const name of LOOPBACK_NAMES) {
+        if (host === `${name}:${port}`)
+            return true;
+        if (port === 80 && host === name)
+            return true;
+    }
+    return false;
+}
+/** Whether `address` is a loopback address: 127.0.0.0/8, ::1, or 127.x mapped into IPv6. */
+function isLoopbackAddress(address) {
+    return address === "::1" || address.startsWith("127.") || address.startsWith("::ffff:127.");
+}
+/** A forwarded request on loopback: admitted as relayed when a relay verifies it, else refused. */
+function relayed(request, relays) {
+    for (const relay of relays) {
+        let verified;
+        try {
+            verified = relay.verify(request.request());
+        }
+        catch (error) {
+            return { kind: "refused", failed: { relay: relay.name, error } };
+        }
+        if (verified === undefined)
+            continue;
+        // Its origins reach the CSP: each must be one origin and nothing else (Fable's recheck N2).
+        for (const origin of [verified.origin, verified.framer]) {
+            if (origin === undefined || isOrigin(origin))
+                continue;
+            const error = new Error(`relay ${relay.name}: ${JSON.stringify(origin)} is no origin`);
+            return { kind: "refused", failed: { relay: relay.name, error } };
+        }
+        return {
+            provenance: { kind: "relayed", relay: relay.name, origin: verified.origin },
+            origin: verified.origin,
+            framer: verified.framer,
+            allowed: undefined,
+            relay,
+        };
+    }
+    return REFUSED;
+}
+/** Whether `text` is exactly an origin (`https://host[:port]`): what the URL parser serializes it to. */
+function isOrigin(text) {
+    try {
+        const url = new URL(text);
+        return (url.protocol === "https:" || url.protocol === "http:") && url.origin === text;
+    }
+    catch {
+        return false;
+    }
+}
+/** The `Sec-Fetch-Dest` of a frame or an embed. */
+const FRAMES = new Set(["iframe", "frame", "embed", "object", "fencedframe"]);
+/** The methods that change nothing. */
+const SAFE = new Set(["GET", "HEAD", "OPTIONS"]);
+//# sourceMappingURL=admission.js.map

package/dist/node/http/admission.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admission.js","sourceRoot":"","sources":["../../../src/node/http/admission.ts"],"names":[],"mappings":"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","sourcesContent":["// Admission (slice 10 §2, R4; decision \"The HTTP component's security baseline\" (1)-(3), \"Relays\"): where a request\n// comes from, decided before anything else. Local only when the connection arrived on a loopback address, its `Host`\n// is a loopback name with the listening port, and it carries no forwarded header; a forwarded request on loopback only\n// when a contributed relay verifies it; otherwise only through an allowed host (https); else refused. Foreign requests\n// (another site's, by Fetch Metadata) and a foreign `Origin` are classified here; the handler applies them per route.\n\nimport type { Incoming } from \"./incoming.ts\";\nimport type { HttpRelay } from \"./router.ts\";\n\n/** Where an admitted request came from. */\nexport type Provenance =\n\t| { readonly kind: \"local\" }\n\t| { readonly kind: \"remote\"; readonly host: string }\n\t| { readonly kind: \"relayed\"; readonly relay: string; readonly origin: string };\n\n/** The connection a request arrived on, as its listener knows it (a mounted handler passes what it has). */\nexport type Connection = {\n\treadonly localAddress?: string;\n\treadonly localPort?: number;\n\treadonly remoteAddress?: string;\n};\n\n/** An admitted request: its provenance, its own origin, the origin allowed to frame it (a relay's), how it came. */\nexport type Admitted = {\n\treadonly provenance: Provenance;\n\treadonly origin: string;\n\treadonly framer: string | undefined;\n\t/** The allowed host it came through: its connections end when that host leaves. */\n\treadonly allowed: string | undefined;\n\t/** The relay that verified it: its connections end when that relay leaves. */\n\treadonly relay: HttpRelay | undefined;\n};\n\n/** What admission refuses, and the relay hook that threw (reported by the caller). */\nexport type Refused = {\n\treadonly kind: \"refused\";\n\treadonly failed?: { readonly relay: string; readonly error: unknown };\n};\n\n/**\n * Admits `request` arriving on `connection` with the allowed `hosts` and contributed `relays`, or refuses it (403):\n * no or several `Host`s, a host neither loopback nor allowed, a loopback `Host` on another connection, forwarded\n * headers no relay verifies.\n */\nexport function admit(\n\trequest: Incoming,\n\tconnection: Connection,\n\thosts: ReadonlySet<string>,\n\trelays: readonly HttpRelay[],\n): Admitted | Refused {\n\tconst host = request.header(\"host\")?.toLowerCase();\n\t// Several `Host` headers arrive joined with commas.\n\tif (host === undefined || host === \"\" || host.includes(\",\")) return REFUSED;\n\tconst { localAddress, localPort } = connection;\n\tif (isLoopbackName(host, localPort)) {\n\t\tif (localAddress === undefined || !isLoopbackAddress(localAddress)) return REFUSED;\n\t\tif (!request.forwarded())\n\t\t\treturn {\n\t\t\t\tprovenance: LOCAL,\n\t\t\t\torigin: `http://${host}`,\n\t\t\t\tframer: undefined,\n\t\t\t\tallowed: undefined,\n\t\t\t\trelay: undefined,\n\t\t\t};\n\t\treturn relayed(request, relays);\n\t}\n\tif (!hosts.has(host)) return REFUSED;\n\treturn {\n\t\tprovenance: { kind: \"remote\", host },\n\t\torigin: `https://${host}`,\n\t\tframer: undefined,\n\t\tallowed: host,\n\t\trelay: undefined,\n\t};\n}\n\n/** What the Fetch Metadata and `Origin` checks read: a request's headers by name. */\nexport type HeaderSource = Pick<Incoming, \"header\">;\n\n/** Whether `admission` refused its request. */\nexport function refused(admission: Admitted | Refused): admission is Refused {\n\treturn \"kind\" in admission;\n}\n\n/**\n * Whether a request is another site's (Fetch Metadata, p2's rule): `Sec-Fetch-Site` neither `same-origin` nor `none`,\n * or a frame or embed not from this origin. A request without the headers (a script, the TUI) is not.\n */\nexport function isForeign(headers: HeaderSource): boolean {\n\tconst site = headers.header(\"sec-fetch-site\");\n\tif (site !== null && site !== \"same-origin\" && site !== \"none\") return true;\n\treturn site !== \"same-origin\" && FRAMES.has(headers.header(\"sec-fetch-dest\") ?? \"\");\n}\n\n/**\n * Whether a foreign request is a top-level navigation (a link followed to a page): `GET`, `navigate`, a `document` (or\n * `empty`: Chrome on Android launching an installed app).\n */\nexport function isNavigation(method: string, headers: HeaderSource): boolean {\n\tconst dest = headers.header(\"sec-fetch-dest\");\n\treturn (\n\t\tmethod === \"GET\" && headers.header(\"sec-fetch-mode\") === \"navigate\" && (dest === \"document\" || dest === \"empty\")\n\t);\n}\n\n/**\n * Whether `headers`' `Origin` is acceptable for a request whose own origin is `origin`: absent or equal, and for an\n * unsafe method from a browser (one sending Fetch Metadata) present and equal.\n */\nexport function originAccepted(method: string, headers: HeaderSource, origin: string): boolean {\n\tconst sent = headers.header(\"origin\");\n\tif (sent !== null) return sent === origin;\n\treturn SAFE.has(method) || headers.header(\"sec-fetch-site\") === null;\n}\n\nconst REFUSED: Refused = { kind: \"refused\" };\n\nconst LOCAL: Provenance = { kind: \"local\" };\n\nconst LOOPBACK_NAMES = [\"127.0.0.1\", \"localhost\", \"[::1]\"];\n\n/** Whether `host` (lowercased) names this server on loopback with `port` (without it on port 80). */\nfunction isLoopbackName(host: string, port: number | undefined): boolean {\n\tif (port === undefined) return false;\n\tfor (const name of LOOPBACK_NAMES) {\n\t\tif (host === `${name}:${port}`) return true;\n\t\tif (port === 80 && host === name) return true;\n\t}\n\treturn false;\n}\n\n/** Whether `address` is a loopback address: 127.0.0.0/8, ::1, or 127.x mapped into IPv6. */\nfunction isLoopbackAddress(address: string): boolean {\n\treturn address === \"::1\" || address.startsWith(\"127.\") || address.startsWith(\"::ffff:127.\");\n}\n\n/** A forwarded request on loopback: admitted as relayed when a relay verifies it, else refused. */\nfunction relayed(request: Incoming, relays: readonly HttpRelay[]): Admitted | Refused {\n\tfor (const relay of relays) {\n\t\tlet verified: ReturnType<HttpRelay[\"verify\"]>;\n\t\ttry {\n\t\t\tverified = relay.verify(request.request());\n\t\t} catch (error) {\n\t\t\treturn { kind: \"refused\", failed: { relay: relay.name, error } };\n\t\t}\n\t\tif (verified === undefined) continue;\n\t\t// Its origins reach the CSP: each must be one origin and nothing else (Fable's recheck N2).\n\t\tfor (const origin of [verified.origin, verified.framer]) {\n\t\t\tif (origin === undefined || isOrigin(origin)) continue;\n\t\t\tconst error = new Error(`relay ${relay.name}: ${JSON.stringify(origin)} is no origin`);\n\t\t\treturn { kind: \"refused\", failed: { relay: relay.name, error } };\n\t\t}\n\t\treturn {\n\t\t\tprovenance: { kind: \"relayed\", relay: relay.name, origin: verified.origin },\n\t\t\torigin: verified.origin,\n\t\t\tframer: verified.framer,\n\t\t\tallowed: undefined,\n\t\t\trelay,\n\t\t};\n\t}\n\treturn REFUSED;\n}\n\n/** Whether `text` is exactly an origin (`https://host[:port]`): what the URL parser serializes it to. */\nfunction isOrigin(text: string): boolean {\n\ttry {\n\t\tconst url = new URL(text);\n\t\treturn (url.protocol === \"https:\" || url.protocol === \"http:\") && url.origin === text;\n\t} catch {\n\t\treturn false;\n\t}\n}\n\n/** The `Sec-Fetch-Dest` of a frame or an embed. */\nconst FRAMES: ReadonlySet<string> = new Set([\"iframe\", \"frame\", \"embed\", \"object\", \"fencedframe\"]);\n\n/** The methods that change nothing. */\nconst SAFE: ReadonlySet<string> = new Set([\"GET\", \"HEAD\", \"OPTIONS\"]);\n"]}

package/dist/node/http/authenticate.d.ts

@@ -0,0 +1,21 @@
+import type { Context } from "../../context/index.ts";
+import type { Principal } from "../../data/index.ts";
+import { type RegistryTable } from "../../registries/index.ts";
+import type { HttpRequest } from "./request.ts";
+/** Who `request` is, or `undefined` (anonymous here, maybe another authenticator knows). */
+export type Authenticator = (request: HttpRequest, context: Context) => Principal | undefined | Promise<Principal | undefined>;
+/** An authenticator with its plugin, as the component asks it. */
+export type AuthenticatorEntry = {
+    readonly plugin: string;
+    readonly authenticate: Authenticator;
+};
+/** The registry of authenticators (served by `http.facet`). */
+export declare const Authenticators: import("../../registries/registry.ts").Registry<Authenticator, readonly AuthenticatorEntry[]>;
+/** Composes `Authenticators`: every contribution in contributor order. */
+export declare function composeAuthenticators(table: RegistryTable<Authenticator>): readonly AuthenticatorEntry[];
+/**
+ * The principal of `request`: the first one an authenticator returns, in order; one that throws is reported through
+ * `failed` and skipped; none: `undefined` (anonymous). Once `context` is aborted no further authenticator starts.
+ */
+export declare function authenticate(authenticators: readonly AuthenticatorEntry[], request: HttpRequest, failed: (plugin: string, error: unknown) => void, context: Context): Promise<Principal | undefined>;
+//# sourceMappingURL=authenticate.d.ts.map

package/dist/node/http/authenticate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authenticate.d.ts","sourceRoot":"","sources":["../../../src/node/http/authenticate.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAkB,KAAK,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,4FAA4F;AAC5F,MAAM,MAAM,aAAa,GAAG,CAC3B,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,OAAO,KACZ,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAAC;AAE5D,kEAAkE;AAClE,MAAM,MAAM,kBAAkB,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAA;CAAE,CAAC;AAEnG,+DAA+D;AAC/D,eAAO,MAAM,cAAc,+FAK1B,CAAC;AAEF,0EAA0E;AAC1E,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,aAAa,CAAC,aAAa,CAAC,GAAG,SAAS,kBAAkB,EAAE,CAExG;AAED;;;GAGG;AACH,wBAAsB,YAAY,CACjC,cAAc,EAAE,SAAS,kBAAkB,EAAE,EAC7C,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,EAChD,OAAO,EAAE,OAAO,GACd,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAYhC"}

package/dist/node/http/authenticate.js

@@ -0,0 +1,34 @@
+// Who someone is (decision "The HTTP server is a native object", replacing the `authenticate` option): the registry
+// `Authenticators`, one function per contributor, asked in contributor order (plugin name: an order with no meaning, so
+// an app needing precedence between credentials contributes one authenticator that decides); the first principal
+// returned wins, a throwing one is reported and skipped.
+import { defineRegistry } from "../../registries/index.js";
+/** The registry of authenticators (served by `http.facet`). */
+export const Authenticators = defineRegistry("chord.http.authenticators", {
+    version: 1,
+});
+/** Composes `Authenticators`: every contribution in contributor order. */
+export function composeAuthenticators(table) {
+    return table.map(({ plugin, value }) => ({ plugin, authenticate: value }));
+}
+/**
+ * The principal of `request`: the first one an authenticator returns, in order; one that throws is reported through
+ * `failed` and skipped; none: `undefined` (anonymous). Once `context` is aborted no further authenticator starts.
+ */
+export async function authenticate(authenticators, request, failed, context) {
+    for (const { plugin, authenticate } of authenticators) {
+        // A request gone or sealed starts no new work (Sol's second recheck C).
+        if (context.abortSignal?.aborted)
+            return undefined;
+        try {
+            const principal = await authenticate(request, context);
+            if (principal !== undefined)
+                return principal;
+        }
+        catch (error) {
+            failed(plugin, error);
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=authenticate.js.map

package/dist/node/http/authenticate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authenticate.js","sourceRoot":"","sources":["../../../src/node/http/authenticate.ts"],"names":[],"mappings":"AAAA,oHAAoH;AACpH,wHAAwH;AACxH,iHAAiH;AACjH,yDAAyD;AAIzD,OAAO,EAAE,cAAc,EAAsB,MAAM,2BAA2B,CAAC;AAY/E,+DAA+D;AAC/D,MAAM,CAAC,MAAM,cAAc,GAAG,cAAc,CAC3C,2BAA2B,EAC3B;IACC,OAAO,EAAE,CAAC;CACV,CACD,CAAC;AAEF,0EAA0E;AAC1E,MAAM,UAAU,qBAAqB,CAAC,KAAmC;IACxE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;AAC5E,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CACjC,cAA6C,EAC7C,OAAoB,EACpB,MAAgD,EAChD,OAAgB;IAEhB,KAAK,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,cAAc,EAAE,CAAC;QACvD,wEAAwE;QACxE,IAAI,OAAO,CAAC,WAAW,EAAE,OAAO;YAAE,OAAO,SAAS,CAAC;QACnD,IAAI,CAAC;YACJ,MAAM,SAAS,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACvD,IAAI,SAAS,KAAK,SAAS;gBAAE,OAAO,SAAS,CAAC;QAC/C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QACvB,CAAC;IACF,CAAC;IACD,OAAO,SAAS,CAAC;AAClB,CAAC","sourcesContent":["// Who someone is (decision \"The HTTP server is a native object\", replacing the `authenticate` option): the registry\n// `Authenticators`, one function per contributor, asked in contributor order (plugin name: an order with no meaning, so\n// an app needing precedence between credentials contributes one authenticator that decides); the first principal\n// returned wins, a throwing one is reported and skipped.\n\nimport type { Context } from \"../../context/index.ts\";\nimport type { Principal } from \"../../data/index.ts\";\nimport { defineRegistry, type RegistryTable } from \"../../registries/index.ts\";\nimport type { HttpRequest } from \"./request.ts\";\n\n/** Who `request` is, or `undefined` (anonymous here, maybe another authenticator knows). */\nexport type Authenticator = (\n\trequest: HttpRequest,\n\tcontext: Context,\n) => Principal | undefined | Promise<Principal | undefined>;\n\n/** An authenticator with its plugin, as the component asks it. */\nexport type AuthenticatorEntry = { readonly plugin: string; readonly authenticate: Authenticator };\n\n/** The registry of authenticators (served by `http.facet`). */\nexport const Authenticators = defineRegistry<Authenticator, readonly AuthenticatorEntry[]>(\n\t\"chord.http.authenticators\",\n\t{\n\t\tversion: 1,\n\t},\n);\n\n/** Composes `Authenticators`: every contribution in contributor order. */\nexport function composeAuthenticators(table: RegistryTable<Authenticator>): readonly AuthenticatorEntry[] {\n\treturn table.map(({ plugin, value }) => ({ plugin, authenticate: value }));\n}\n\n/**\n * The principal of `request`: the first one an authenticator returns, in order; one that throws is reported through\n * `failed` and skipped; none: `undefined` (anonymous). Once `context` is aborted no further authenticator starts.\n */\nexport async function authenticate(\n\tauthenticators: readonly AuthenticatorEntry[],\n\trequest: HttpRequest,\n\tfailed: (plugin: string, error: unknown) => void,\n\tcontext: Context,\n): Promise<Principal | undefined> {\n\tfor (const { plugin, authenticate } of authenticators) {\n\t\t// A request gone or sealed starts no new work (Sol's second recheck C).\n\t\tif (context.abortSignal?.aborted) return undefined;\n\t\ttry {\n\t\t\tconst principal = await authenticate(request, context);\n\t\t\tif (principal !== undefined) return principal;\n\t\t} catch (error) {\n\t\t\tfailed(plugin, error);\n\t\t}\n\t}\n\treturn undefined;\n}\n"]}

package/dist/node/http/cookies.d.ts

@@ -0,0 +1,32 @@
+import type { HttpRequest } from "./request.ts";
+/** What `cookie` takes besides the name and the value. */
+export type CookieOptions = {
+    /** The key it is signed with (HMAC-SHA256). */
+    readonly secret: string;
+    /** The request it answers (its provenance): a remote one gets `Secure`. */
+    readonly request: Pick<HttpRequest, "provenance">;
+    /** `Strict` by default; `Lax` lets a top-level navigation from another site carry it. */
+    readonly sameSite?: "Strict" | "Lax";
+    /** Seconds until it expires; none: a session cookie. */
+    readonly maxAge?: number;
+};
+/**
+ * A signed `Set-Cookie` value for `name` and `value` (put it in a response's `headers`, `Set-Cookie`). With `maxAge`
+ * its expiry is signed with it: a copy read back later is refused (Opus's recheck R3); without, it holds until the
+ * secret changes.
+ */
+export declare function cookie(name: string, value: string, options: CookieOptions): string;
+/**
+ * The value of cookie `name` on `request` when its signature with `secret` holds and its signed expiry has not passed;
+ * `undefined` otherwise.
+ */
+export declare function readCookie(request: HttpRequest, name: string, secret: string): string | undefined;
+/**
+ * Cookie `name` on `request` as `readCookie` checks it, with its signed expiry (milliseconds since the epoch; none for
+ * a cookie without `maxAge`): what renewing a cookie before it expires needs.
+ */
+export declare function readSignedCookie(request: HttpRequest, name: string, secret: string): {
+    readonly value: string;
+    readonly expires: number | undefined;
+} | undefined;
+//# sourceMappingURL=cookies.d.ts.map

package/dist/node/http/cookies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookies.d.ts","sourceRoot":"","sources":["../../../src/node/http/cookies.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,0DAA0D;AAC1D,MAAM,MAAM,aAAa,GAAG;IAC3B,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;IAClD,yFAAyF;IACzF,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,CAAC;IACrC,wDAAwD;IACxD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,MAAM,CAalF;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEjG;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC/B,OAAO,EAAE,WAAW,EACpB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACZ;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GAAG,SAAS,CAuB9E"}

package/dist/node/http/cookies.js

@@ -0,0 +1,70 @@
+// Cookies (decision "The HTTP component's security baseline" (5)): `cookie` makes a signed `Set-Cookie` value with the
+// safe defaults (`HttpOnly`, `Path=/`, `SameSite=Strict`, `Secure` on a remote origin), `readCookie` reads one back,
+// its signature checked in constant time.
+import { createHmac, timingSafeEqual } from "node:crypto";
+/**
+ * A signed `Set-Cookie` value for `name` and `value` (put it in a response's `headers`, `Set-Cookie`). With `maxAge`
+ * its expiry is signed with it: a copy read back later is refused (Opus's recheck R3); without, it holds until the
+ * secret changes.
+ */
+export function cookie(name, value, options) {
+    const encoded = encodeURIComponent(value);
+    const expires = options.maxAge === undefined ? "" : String(Math.floor(Date.now() / 1000 + options.maxAge));
+    const payload = `${encoded}.${expires}`;
+    const parts = [
+        `${name}=${payload}.${signature(name, payload, options.secret)}`,
+        "HttpOnly",
+        "Path=/",
+        `SameSite=${options.sameSite ?? "Strict"}`,
+    ];
+    if (options.request.provenance.kind !== "local")
+        parts.push("Secure");
+    if (options.maxAge !== undefined)
+        parts.push(`Max-Age=${Math.floor(options.maxAge)}`);
+    return parts.join("; ");
+}
+/**
+ * The value of cookie `name` on `request` when its signature with `secret` holds and its signed expiry has not passed;
+ * `undefined` otherwise.
+ */
+export function readCookie(request, name, secret) {
+    return readSignedCookie(request, name, secret)?.value;
+}
+/**
+ * Cookie `name` on `request` as `readCookie` checks it, with its signed expiry (milliseconds since the epoch; none for
+ * a cookie without `maxAge`): what renewing a cookie before it expires needs.
+ */
+export function readSignedCookie(request, name, secret) {
+    for (const pair of (request.headers.get("cookie") ?? "").split(";")) {
+        const equals = pair.indexOf("=");
+        if (equals < 0 || pair.slice(0, equals).trim() !== name)
+            continue;
+        const signed = pair.slice(equals + 1).trim();
+        // From the right: the value may hold dots, the expiry and the signature never do.
+        const dot = signed.lastIndexOf(".");
+        const payload = signed.slice(0, dot);
+        const expiresAt = payload.lastIndexOf(".");
+        if (dot < 0 || expiresAt < 0)
+            return undefined;
+        const given = Buffer.from(signed.slice(dot + 1));
+        const expected = Buffer.from(signature(name, payload, secret));
+        if (given.length !== expected.length || !timingSafeEqual(given, expected))
+            return undefined;
+        const stamp = payload.slice(expiresAt + 1);
+        const expires = stamp === "" ? undefined : Number(stamp) * 1000;
+        if (expires !== undefined && expires <= Date.now())
+            return undefined;
+        try {
+            return { value: decodeURIComponent(payload.slice(0, expiresAt)), expires };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+/** The signature of a cookie's name and payload (its encoded value and expiry). */
+function signature(name, payload, secret) {
+    return createHmac("sha256", secret).update(`${name}=${payload}`).digest("base64url");
+}
+//# sourceMappingURL=cookies.js.map

package/dist/node/http/cookies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookies.js","sourceRoot":"","sources":["../../../src/node/http/cookies.ts"],"names":[],"mappings":"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","sourcesContent":["// Cookies (decision \"The HTTP component's security baseline\" (5)): `cookie` makes a signed `Set-Cookie` value with the\n// safe defaults (`HttpOnly`, `Path=/`, `SameSite=Strict`, `Secure` on a remote origin), `readCookie` reads one back,\n// its signature checked in constant time.\n\nimport { createHmac, timingSafeEqual } from \"node:crypto\";\nimport type { HttpRequest } from \"./request.ts\";\n\n/** What `cookie` takes besides the name and the value. */\nexport type CookieOptions = {\n\t/** The key it is signed with (HMAC-SHA256). */\n\treadonly secret: string;\n\t/** The request it answers (its provenance): a remote one gets `Secure`. */\n\treadonly request: Pick<HttpRequest, \"provenance\">;\n\t/** `Strict` by default; `Lax` lets a top-level navigation from another site carry it. */\n\treadonly sameSite?: \"Strict\" | \"Lax\";\n\t/** Seconds until it expires; none: a session cookie. */\n\treadonly maxAge?: number;\n};\n\n/**\n * A signed `Set-Cookie` value for `name` and `value` (put it in a response's `headers`, `Set-Cookie`). With `maxAge`\n * its expiry is signed with it: a copy read back later is refused (Opus's recheck R3); without, it holds until the\n * secret changes.\n */\nexport function cookie(name: string, value: string, options: CookieOptions): string {\n\tconst encoded = encodeURIComponent(value);\n\tconst expires = options.maxAge === undefined ? \"\" : String(Math.floor(Date.now() / 1000 + options.maxAge));\n\tconst payload = `${encoded}.${expires}`;\n\tconst parts = [\n\t\t`${name}=${payload}.${signature(name, payload, options.secret)}`,\n\t\t\"HttpOnly\",\n\t\t\"Path=/\",\n\t\t`SameSite=${options.sameSite ?? \"Strict\"}`,\n\t];\n\tif (options.request.provenance.kind !== \"local\") parts.push(\"Secure\");\n\tif (options.maxAge !== undefined) parts.push(`Max-Age=${Math.floor(options.maxAge)}`);\n\treturn parts.join(\"; \");\n}\n\n/**\n * The value of cookie `name` on `request` when its signature with `secret` holds and its signed expiry has not passed;\n * `undefined` otherwise.\n */\nexport function readCookie(request: HttpRequest, name: string, secret: string): string | undefined {\n\treturn readSignedCookie(request, name, secret)?.value;\n}\n\n/**\n * Cookie `name` on `request` as `readCookie` checks it, with its signed expiry (milliseconds since the epoch; none for\n * a cookie without `maxAge`): what renewing a cookie before it expires needs.\n */\nexport function readSignedCookie(\n\trequest: HttpRequest,\n\tname: string,\n\tsecret: string,\n): { readonly value: string; readonly expires: number | undefined } | undefined {\n\tfor (const pair of (request.headers.get(\"cookie\") ?? \"\").split(\";\")) {\n\t\tconst equals = pair.indexOf(\"=\");\n\t\tif (equals < 0 || pair.slice(0, equals).trim() !== name) continue;\n\t\tconst signed = pair.slice(equals + 1).trim();\n\t\t// From the right: the value may hold dots, the expiry and the signature never do.\n\t\tconst dot = signed.lastIndexOf(\".\");\n\t\tconst payload = signed.slice(0, dot);\n\t\tconst expiresAt = payload.lastIndexOf(\".\");\n\t\tif (dot < 0 || expiresAt < 0) return undefined;\n\t\tconst given = Buffer.from(signed.slice(dot + 1));\n\t\tconst expected = Buffer.from(signature(name, payload, secret));\n\t\tif (given.length !== expected.length || !timingSafeEqual(given, expected)) return undefined;\n\t\tconst stamp = payload.slice(expiresAt + 1);\n\t\tconst expires = stamp === \"\" ? undefined : Number(stamp) * 1000;\n\t\tif (expires !== undefined && expires <= Date.now()) return undefined;\n\t\ttry {\n\t\t\treturn { value: decodeURIComponent(payload.slice(0, expiresAt)), expires };\n\t\t} catch {\n\t\t\treturn undefined;\n\t\t}\n\t}\n\treturn undefined;\n}\n\n/** The signature of a cookie's name and payload (its encoded value and expiry). */\nfunction signature(name: string, payload: string, secret: string): string {\n\treturn createHmac(\"sha256\", secret).update(`${name}=${payload}`).digest(\"base64url\");\n}\n"]}