@earendil-works/chord 1.5.0 → 1.5.1

package/dist/node/app/pairing.js

@@ -0,0 +1,183 @@
+// Device pairing (slice 13 §2, decision "The app kit, point 3" (c)): a command-line or terminal client on another
+// machine asks for a code (`POST /_chord/pair`, public) and polls with a secret it got with it; the owner (the
+// principal the app names) opens `/_chord/pair/<code>` in a signed-in browser and approves; the next poll returns a
+// token of the owner's new device session, once. Codes are short, random, single use and expire after 10 minutes; the
+// poll secret is kept only hashed. Asking is public, so pairings anonymous clients start are capped: `maxPending` in
+// all (100 by default) and `perAddress` per client address (10). The trade: a party filling the caps locks pairing out
+// for others for up to 10 minutes (behind a tunnel every remote client has the tunnel's address), instead of growing
+// the server's memory without bound; a signed-in owner's pairings are not counted, so the owner can always pair.
+import { randomInt } from "node:crypto";
+import { samePrincipal } from "../../data/principal.js";
+import { defineFacet } from "../../host/index.js";
+import { Http } from "../http/index.js";
+import { hashToken, newToken } from "./secrets.js";
+import { Sessions } from "./sessions.js";
+/** How long a pairing code is valid: 10 minutes. */
+const PAIRING_MS = 10 * 60_000;
+/** The code's letters: no 0/O, 1/I/L. */
+const ALPHABET = "ABCDEFGHJKMNPQRSTUVWXYZ23456789";
+/** The pairings under way, by code and by their poll secret's hash, with the anonymous ones counted. */
+export class Pairings {
+    #byCode = new Map();
+    #byPoll = new Map();
+    #perAddress = new Map();
+    #anonymous = 0;
+    #maxPending;
+    #maxPerAddress;
+    constructor(limits = {}) {
+        this.#maxPending = limits.maxPending ?? 100;
+        this.#maxPerAddress = limits.perAddress ?? 10;
+    }
+    /**
+     * A new pairing for a device labelled `label`, started `by` the owner or an anonymous client: its code (for the
+     * owner) and its poll secret (for the device); `undefined` when an anonymous client reached a limit.
+     */
+    begin(label, by) {
+        this.#expire();
+        if (by.kind === "anonymous") {
+            const full = this.#anonymous >= this.#maxPending;
+            if (full || (this.#perAddress.get(by.address) ?? 0) >= this.#maxPerAddress)
+                return undefined;
+            this.#anonymous++;
+            this.#perAddress.set(by.address, (this.#perAddress.get(by.address) ?? 0) + 1);
+        }
+        let code;
+        do
+            code = `${letters(4)}-${letters(4)}`;
+        while (this.#byCode.has(code));
+        const poll = newToken();
+        const pairing = { code, label, by, expires: Date.now() + PAIRING_MS };
+        this.#byCode.set(code, pairing);
+        this.#byPoll.set(hashToken(poll), pairing);
+        return { code, poll };
+    }
+    /** The pairing waiting for approval under `code` (any case), unexpired. */
+    waiting(code) {
+        this.#expire();
+        const pairing = this.#byCode.get(code.toUpperCase());
+        return pairing?.token === undefined ? pairing : undefined;
+    }
+    /** What a poll with `poll` learns: still waiting, the device's token (once: the pairing ends), or nothing. */
+    poll(poll) {
+        this.#expire();
+        const hash = hashToken(poll);
+        const pairing = this.#byPoll.get(hash);
+        if (pairing === undefined)
+            return undefined;
+        if (pairing.token === undefined)
+            return { kind: "waiting" };
+        this.#end(hash, pairing);
+        return { kind: "approved", token: pairing.token };
+    }
+    /** Drops the expired pairings. */
+    #expire() {
+        const now = Date.now();
+        for (const [hash, pairing] of this.#byPoll) {
+            if (pairing.expires <= now)
+                this.#end(hash, pairing);
+        }
+    }
+    /** Ends `pairing` (its poll secret's hash `hash`). */
+    #end(hash, pairing) {
+        this.#byPoll.delete(hash);
+        this.#byCode.delete(pairing.code);
+        const { by } = pairing;
+        if (by.kind === "owner")
+            return;
+        this.#anonymous--;
+        const left = (this.#perAddress.get(by.address) ?? 1) - 1;
+        if (left === 0)
+            this.#perAddress.delete(by.address);
+        else
+            this.#perAddress.set(by.address, left);
+    }
+}
+/** `count` random letters of `ALPHABET` (`crypto.randomInt`). */
+function letters(count) {
+    let text = "";
+    for (let index = 0; index < count; index++)
+        text += ALPHABET[randomInt(ALPHABET.length)];
+    return text;
+}
+/** The pairing routes' prefix. */
+export const PAIR_PATH = "/_chord/pair";
+/**
+ * The kit's facet for device pairing: `POST /_chord/pair` (public: `{ label? }` → `{ code, poll }`, 429 past a limit
+ * unless the owner asks), `POST /_chord/pair/poll` (public: `{ poll }` → `{ status: "waiting" }`, `{ status:
+ * "approved", token }` once, else 404), `GET` and `POST /_chord/pair/:code` (`owner`'s confirm page and approval: a
+ * device session of `owner`).
+ */
+export function pairingFacet(pairings, owner) {
+    return defineFacet((_host, self) => self.contribute(Http, {
+        routes: {
+            [`POST ${PAIR_PATH}`]: {
+                public: true,
+                handler: async (request, ctx) => {
+                    const label = await labelOf(request);
+                    const by = samePrincipal(ctx.principal, owner, ctx)
+                        ? { kind: "owner" }
+                        : { kind: "anonymous", address: request.remoteAddress ?? "" };
+                    const begun = pairings.begin(label, by);
+                    return begun === undefined ? { kind: "error", status: 429 } : { kind: "json", value: begun };
+                },
+            },
+            [`POST ${PAIR_PATH}/poll`]: {
+                public: true,
+                handler: async (request) => {
+                    // A trust boundary: anyone may poll.
+                    const body = (await request.json());
+                    const polled = typeof body?.poll === "string" ? pairings.poll(body.poll) : undefined;
+                    if (polled === undefined)
+                        return { kind: "error", status: 404 };
+                    if (polled.kind === "waiting")
+                        return { kind: "json", value: { status: "waiting" } };
+                    return { kind: "json", value: { status: "approved", token: polled.token } };
+                },
+            },
+            [`GET ${PAIR_PATH}/:code`]: async (request, ctx) => {
+                if (!samePrincipal(ctx.principal, owner, ctx))
+                    return { kind: "error", status: 403 };
+                const pairing = pairings.waiting(request.params.code ?? "");
+                if (pairing === undefined)
+                    return { kind: "html", status: 404, body: "<p>No such pairing (or it expired).</p>" };
+                return { kind: "html", body: confirmPage(pairing.code, pairing.label) };
+            },
+            [`POST ${PAIR_PATH}/:code`]: async (request, ctx) => {
+                if (!samePrincipal(ctx.principal, owner, ctx))
+                    return { kind: "error", status: 403 };
+                const pairing = pairings.waiting(request.params.code ?? "");
+                if (pairing === undefined)
+                    return { kind: "html", status: 404, body: "<p>No such pairing (or it expired).</p>" };
+                const sessions = await ctx.get(Sessions, {});
+                const { token } = await sessions.issue({ principal: owner, label: pairing.label, kind: "device" }, ctx);
+                pairing.token = token;
+                return {
+                    kind: "html",
+                    body: `<p>Approved: ${escapeHtml(pairing.label)} is signed in as the owner.</p>`,
+                };
+            },
+        },
+    }));
+}
+/** The device's label from a pairing request's body (`{ label }`, at most 100 characters), else `device`. */
+async function labelOf(request) {
+    const declared = Number(request.headers.get("content-length") ?? "0");
+    if (declared === 0 && request.headers.get("transfer-encoding") === null)
+        return "device";
+    // A trust boundary: anyone may ask for a code.
+    const body = (await request.json(4096));
+    return typeof body?.label === "string" && body.label.trim() !== "" ? body.label.trim().slice(0, 100) : "device";
+}
+/** The owner's confirm page for pairing `code` (a form posting to itself: same origin, the session cookie). */
+function confirmPage(code, label) {
+    return [
+        "<!doctype html><title>Pair a device</title>",
+        `<p>Sign in <b>${escapeHtml(label)}</b> as the owner? Its code: <b>${escapeHtml(code)}</b> (compare it with the device).</p>`,
+        '<form method="post"><button>Approve</button></form>',
+    ].join("\n");
+}
+/** `text` safe in HTML. */
+function escapeHtml(text) {
+    return text.replace(/[&<>"']/g, (char) => `&#${char.charCodeAt(0)};`);
+}
+//# sourceMappingURL=pairing.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pairing.js","sourceRoot":"","sources":["../../../src/node/app/pairing.ts"],"names":[],"mappings":"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","sourcesContent":["// Device pairing (slice 13 §2, decision \"The app kit, point 3\" (c)): a command-line or terminal client on another\n// machine asks for a code (`POST /_chord/pair`, public) and polls with a secret it got with it; the owner (the\n// principal the app names) opens `/_chord/pair/<code>` in a signed-in browser and approves; the next poll returns a\n// token of the owner's new device session, once. Codes are short, random, single use and expire after 10 minutes; the\n// poll secret is kept only hashed. Asking is public, so pairings anonymous clients start are capped: `maxPending` in\n// all (100 by default) and `perAddress` per client address (10). The trade: a party filling the caps locks pairing out\n// for others for up to 10 minutes (behind a tunnel every remote client has the tunnel's address), instead of growing\n// the server's memory without bound; a signed-in owner's pairings are not counted, so the owner can always pair.\n\nimport { randomInt } from \"node:crypto\";\nimport type { Principal } from \"../../data/index.ts\";\nimport { samePrincipal } from \"../../data/principal.ts\";\nimport { defineFacet, type Facet } from \"../../host/index.ts\";\nimport { Http, type HttpRequest, type HttpResponse } from \"../http/index.ts\";\nimport { hashToken, newToken } from \"./secrets.ts\";\nimport { Sessions } from \"./sessions.ts\";\n\n/** How long a pairing code is valid: 10 minutes. */\nconst PAIRING_MS = 10 * 60_000;\n\n/** The code's letters: no 0/O, 1/I/L. */\nconst ALPHABET = \"ABCDEFGHJKMNPQRSTUVWXYZ23456789\";\n\n/** Who starts a pairing: the signed-in owner (not counted), or an anonymous client at an address (counted). */\nexport type PairingStarter = { readonly kind: \"owner\" } | { readonly kind: \"anonymous\"; readonly address: string };\n\n/** One pairing under way: its code, the device's label, who started it, its expiry, its token once approved. */\ntype Pairing = {\n\treadonly code: string;\n\treadonly label: string;\n\treadonly by: PairingStarter;\n\treadonly expires: number;\n\ttoken?: string;\n};\n\n/** The limits of pairings under way: in all (100 by default) and per client address (10 by default). */\nexport type PairingLimits = { readonly maxPending?: number; readonly perAddress?: number };\n\n/** The pairings under way, by code and by their poll secret's hash, with the anonymous ones counted. */\nexport class Pairings {\n\treadonly #byCode = new Map<string, Pairing>();\n\treadonly #byPoll = new Map<string, Pairing>();\n\treadonly #perAddress = new Map<string, number>();\n\t#anonymous = 0;\n\treadonly #maxPending: number;\n\treadonly #maxPerAddress: number;\n\n\tconstructor(limits: PairingLimits = {}) {\n\t\tthis.#maxPending = limits.maxPending ?? 100;\n\t\tthis.#maxPerAddress = limits.perAddress ?? 10;\n\t}\n\n\t/**\n\t * A new pairing for a device labelled `label`, started `by` the owner or an anonymous client: its code (for the\n\t * owner) and its poll secret (for the device); `undefined` when an anonymous client reached a limit.\n\t */\n\tbegin(label: string, by: PairingStarter): { readonly code: string; readonly poll: string } | undefined {\n\t\tthis.#expire();\n\t\tif (by.kind === \"anonymous\") {\n\t\t\tconst full = this.#anonymous >= this.#maxPending;\n\t\t\tif (full || (this.#perAddress.get(by.address) ?? 0) >= this.#maxPerAddress) return undefined;\n\t\t\tthis.#anonymous++;\n\t\t\tthis.#perAddress.set(by.address, (this.#perAddress.get(by.address) ?? 0) + 1);\n\t\t}\n\t\tlet code: string;\n\t\tdo code = `${letters(4)}-${letters(4)}`;\n\t\twhile (this.#byCode.has(code));\n\t\tconst poll = newToken();\n\t\tconst pairing: Pairing = { code, label, by, expires: Date.now() + PAIRING_MS };\n\t\tthis.#byCode.set(code, pairing);\n\t\tthis.#byPoll.set(hashToken(poll), pairing);\n\t\treturn { code, poll };\n\t}\n\n\t/** The pairing waiting for approval under `code` (any case), unexpired. */\n\twaiting(code: string): Pairing | undefined {\n\t\tthis.#expire();\n\t\tconst pairing = this.#byCode.get(code.toUpperCase());\n\t\treturn pairing?.token === undefined ? pairing : undefined;\n\t}\n\n\t/** What a poll with `poll` learns: still waiting, the device's token (once: the pairing ends), or nothing. */\n\tpoll(\n\t\tpoll: string,\n\t): { readonly kind: \"waiting\" } | { readonly kind: \"approved\"; readonly token: string } | undefined {\n\t\tthis.#expire();\n\t\tconst hash = hashToken(poll);\n\t\tconst pairing = this.#byPoll.get(hash);\n\t\tif (pairing === undefined) return undefined;\n\t\tif (pairing.token === undefined) return { kind: \"waiting\" };\n\t\tthis.#end(hash, pairing);\n\t\treturn { kind: \"approved\", token: pairing.token };\n\t}\n\n\t/** Drops the expired pairings. */\n\t#expire(): void {\n\t\tconst now = Date.now();\n\t\tfor (const [hash, pairing] of this.#byPoll) {\n\t\t\tif (pairing.expires <= now) this.#end(hash, pairing);\n\t\t}\n\t}\n\n\t/** Ends `pairing` (its poll secret's hash `hash`). */\n\t#end(hash: string, pairing: Pairing): void {\n\t\tthis.#byPoll.delete(hash);\n\t\tthis.#byCode.delete(pairing.code);\n\t\tconst { by } = pairing;\n\t\tif (by.kind === \"owner\") return;\n\t\tthis.#anonymous--;\n\t\tconst left = (this.#perAddress.get(by.address) ?? 1) - 1;\n\t\tif (left === 0) this.#perAddress.delete(by.address);\n\t\telse this.#perAddress.set(by.address, left);\n\t}\n}\n\n/** `count` random letters of `ALPHABET` (`crypto.randomInt`). */\nfunction letters(count: number): string {\n\tlet text = \"\";\n\tfor (let index = 0; index < count; index++) text += ALPHABET[randomInt(ALPHABET.length)];\n\treturn text;\n}\n\n/** The pairing routes' prefix. */\nexport const PAIR_PATH = \"/_chord/pair\";\n\n/**\n * The kit's facet for device pairing: `POST /_chord/pair` (public: `{ label? }` → `{ code, poll }`, 429 past a limit\n * unless the owner asks), `POST /_chord/pair/poll` (public: `{ poll }` → `{ status: \"waiting\" }`, `{ status:\n * \"approved\", token }` once, else 404), `GET` and `POST /_chord/pair/:code` (`owner`'s confirm page and approval: a\n * device session of `owner`).\n */\nexport function pairingFacet<P extends Principal>(pairings: Pairings, owner: P): Facet<P> {\n\treturn defineFacet<P>((_host, self) =>\n\t\tself.contribute(Http, {\n\t\t\troutes: {\n\t\t\t\t[`POST ${PAIR_PATH}`]: {\n\t\t\t\t\tpublic: true,\n\t\t\t\t\thandler: async (request, ctx): Promise<HttpResponse> => {\n\t\t\t\t\t\tconst label = await labelOf(request);\n\t\t\t\t\t\tconst by: PairingStarter = samePrincipal(ctx.principal, owner, ctx)\n\t\t\t\t\t\t\t? { kind: \"owner\" }\n\t\t\t\t\t\t\t: { kind: \"anonymous\", address: request.remoteAddress ?? \"\" };\n\t\t\t\t\t\tconst begun = pairings.begin(label, by);\n\t\t\t\t\t\treturn begun === undefined ? { kind: \"error\", status: 429 } : { kind: \"json\", value: begun };\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t\t[`POST ${PAIR_PATH}/poll`]: {\n\t\t\t\t\tpublic: true,\n\t\t\t\t\thandler: async (request): Promise<HttpResponse> => {\n\t\t\t\t\t\t// A trust boundary: anyone may poll.\n\t\t\t\t\t\tconst body = (await request.json()) as { readonly poll?: unknown } | null;\n\t\t\t\t\t\tconst polled = typeof body?.poll === \"string\" ? pairings.poll(body.poll) : undefined;\n\t\t\t\t\t\tif (polled === undefined) return { kind: \"error\", status: 404 };\n\t\t\t\t\t\tif (polled.kind === \"waiting\") return { kind: \"json\", value: { status: \"waiting\" } };\n\t\t\t\t\t\treturn { kind: \"json\", value: { status: \"approved\", token: polled.token } };\n\t\t\t\t\t},\n\t\t\t\t},\n\t\t\t\t[`GET ${PAIR_PATH}/:code`]: async (request, ctx) => {\n\t\t\t\t\tif (!samePrincipal(ctx.principal, owner, ctx)) return { kind: \"error\", status: 403 };\n\t\t\t\t\tconst pairing = pairings.waiting(request.params.code ?? \"\");\n\t\t\t\t\tif (pairing === undefined)\n\t\t\t\t\t\treturn { kind: \"html\", status: 404, body: \"<p>No such pairing (or it expired).</p>\" };\n\t\t\t\t\treturn { kind: \"html\", body: confirmPage(pairing.code, pairing.label) };\n\t\t\t\t},\n\t\t\t\t[`POST ${PAIR_PATH}/:code`]: async (request, ctx) => {\n\t\t\t\t\tif (!samePrincipal(ctx.principal, owner, ctx)) return { kind: \"error\", status: 403 };\n\t\t\t\t\tconst pairing = pairings.waiting(request.params.code ?? \"\");\n\t\t\t\t\tif (pairing === undefined)\n\t\t\t\t\t\treturn { kind: \"html\", status: 404, body: \"<p>No such pairing (or it expired).</p>\" };\n\t\t\t\t\tconst sessions = await ctx.get(Sessions, {});\n\t\t\t\t\tconst { token } = await sessions.issue({ principal: owner, label: pairing.label, kind: \"device\" }, ctx);\n\t\t\t\t\tpairing.token = token;\n\t\t\t\t\treturn {\n\t\t\t\t\t\tkind: \"html\",\n\t\t\t\t\t\tbody: `<p>Approved: ${escapeHtml(pairing.label)} is signed in as the owner.</p>`,\n\t\t\t\t\t};\n\t\t\t\t},\n\t\t\t},\n\t\t}),\n\t);\n}\n\n/** The device's label from a pairing request's body (`{ label }`, at most 100 characters), else `device`. */\nasync function labelOf(request: HttpRequest): Promise<string> {\n\tconst declared = Number(request.headers.get(\"content-length\") ?? \"0\");\n\tif (declared === 0 && request.headers.get(\"transfer-encoding\") === null) return \"device\";\n\t// A trust boundary: anyone may ask for a code.\n\tconst body = (await request.json(4096)) as { readonly label?: unknown } | null;\n\treturn typeof body?.label === \"string\" && body.label.trim() !== \"\" ? body.label.trim().slice(0, 100) : \"device\";\n}\n\n/** The owner's confirm page for pairing `code` (a form posting to itself: same origin, the session cookie). */\nfunction confirmPage(code: string, label: string): string {\n\treturn [\n\t\t\"<!doctype html><title>Pair a device</title>\",\n\t\t`<p>Sign in <b>${escapeHtml(label)}</b> as the owner? Its code: <b>${escapeHtml(code)}</b> (compare it with the device).</p>`,\n\t\t'<form method=\"post\"><button>Approve</button></form>',\n\t].join(\"\\n\");\n}\n\n/** `text` safe in HTML. */\nfunction escapeHtml(text: string): string {\n\treturn text.replace(/[&<>\"']/g, (char) => `&#${char.charCodeAt(0)};`);\n}\n"]}

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

@@ -0,0 +1,16 @@
+/** A fresh random token of `bytes` bytes, base64url. */
+export declare function newToken(bytes?: number): string;
+/** The hash a token is kept as (SHA-256, hex): what leaks from a store is no credential. */
+export declare function hashToken(token: string): string;
+/** Whether `token` hashes to `hash`, compared in constant time. */
+export declare function matchesHash(token: string, hash: string): boolean;
+/** The secret in the file at `path`, created (mode 0600, in one step) with a fresh token when it does not exist yet. */
+export declare function secretFile(path: string): Promise<string>;
+/** The text of the secret file at `path`, or `undefined` when it does not exist. */
+export declare function readSecret(path: string): Promise<string | undefined>;
+/**
+ * Writes `text` to `path` with mode 0600 in one step: a temporary file of the same directory (made exclusively, 0600)
+ * linked into place (`create`: refused when `path` exists, `"exists"` returned) or renamed over it (`replace`).
+ */
+export declare function writeSecret(path: string, text: string, mode: "create" | "replace"): Promise<"written" | "exists">;
+//# sourceMappingURL=secrets.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../../../src/node/app/secrets.ts"],"names":[],"mappings":"AAQA,wDAAwD;AACxD,wBAAgB,QAAQ,CAAC,KAAK,SAAK,GAAG,MAAM,CAE3C;AAED,4FAA4F;AAC5F,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C;AAED,mEAAmE;AACnE,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAIhE;AAED,wHAAwH;AACxH,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAM9D;AAED,oFAAoF;AACpF,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAO1E;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAChC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,QAAQ,GAAG,SAAS,GACxB,OAAO,CAAC,SAAS,GAAG,QAAQ,CAAC,CAsB/B"}

package/dist/node/app/secrets.js

@@ -0,0 +1,72 @@
+// Secrets of the app kit (slice 13 §2): tokens from `crypto.randomBytes`, kept only as their SHA-256 hashes and
+// compared in constant time, and secret files (the cookie key, the owner token file) created with mode 0600 in one
+// step, so no other OS user and no half-written file ever reads them.
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { link, open, readFile, rename, unlink } from "node:fs/promises";
+import { dirname, join } from "node:path";
+/** A fresh random token of `bytes` bytes, base64url. */
+export function newToken(bytes = 32) {
+    return randomBytes(bytes).toString("base64url");
+}
+/** The hash a token is kept as (SHA-256, hex): what leaks from a store is no credential. */
+export function hashToken(token) {
+    return createHash("sha256").update(token).digest("hex");
+}
+/** Whether `token` hashes to `hash`, compared in constant time. */
+export function matchesHash(token, hash) {
+    const given = Buffer.from(hashToken(token), "hex");
+    const kept = Buffer.from(hash, "hex");
+    return given.length === kept.length && timingSafeEqual(given, kept);
+}
+/** The secret in the file at `path`, created (mode 0600, in one step) with a fresh token when it does not exist yet. */
+export async function secretFile(path) {
+    const existing = await readSecret(path);
+    if (existing !== undefined)
+        return existing;
+    const secret = newToken();
+    const written = await writeSecret(path, secret, "create");
+    return written === "exists" ? ((await readSecret(path)) ?? secret) : secret;
+}
+/** The text of the secret file at `path`, or `undefined` when it does not exist. */
+export async function readSecret(path) {
+    try {
+        return (await readFile(path, "utf8")).trim();
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+/**
+ * Writes `text` to `path` with mode 0600 in one step: a temporary file of the same directory (made exclusively, 0600)
+ * linked into place (`create`: refused when `path` exists, `"exists"` returned) or renamed over it (`replace`).
+ */
+export async function writeSecret(path, text, mode) {
+    const temporary = join(dirname(path), `.${newToken(9)}.tmp`);
+    const handle = await open(temporary, "wx", 0o600);
+    try {
+        await handle.writeFile(`${text}\n`);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    try {
+        if (mode === "replace") {
+            await rename(temporary, path);
+            return "written";
+        }
+        await link(temporary, path);
+        return "written";
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            return "exists";
+        throw error;
+    }
+    finally {
+        await unlink(temporary).catch(() => { });
+    }
+}
+//# sourceMappingURL=secrets.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.js","sourceRoot":"","sources":["../../../src/node/app/secrets.ts"],"names":[],"mappings":"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","sourcesContent":["// Secrets of the app kit (slice 13 §2): tokens from `crypto.randomBytes`, kept only as their SHA-256 hashes and\n// compared in constant time, and secret files (the cookie key, the owner token file) created with mode 0600 in one\n// step, so no other OS user and no half-written file ever reads them.\n\nimport { createHash, randomBytes, timingSafeEqual } from \"node:crypto\";\nimport { link, open, readFile, rename, unlink } from \"node:fs/promises\";\nimport { dirname, join } from \"node:path\";\n\n/** A fresh random token of `bytes` bytes, base64url. */\nexport function newToken(bytes = 32): string {\n\treturn randomBytes(bytes).toString(\"base64url\");\n}\n\n/** The hash a token is kept as (SHA-256, hex): what leaks from a store is no credential. */\nexport function hashToken(token: string): string {\n\treturn createHash(\"sha256\").update(token).digest(\"hex\");\n}\n\n/** Whether `token` hashes to `hash`, compared in constant time. */\nexport function matchesHash(token: string, hash: string): boolean {\n\tconst given = Buffer.from(hashToken(token), \"hex\");\n\tconst kept = Buffer.from(hash, \"hex\");\n\treturn given.length === kept.length && timingSafeEqual(given, kept);\n}\n\n/** The secret in the file at `path`, created (mode 0600, in one step) with a fresh token when it does not exist yet. */\nexport async function secretFile(path: string): Promise<string> {\n\tconst existing = await readSecret(path);\n\tif (existing !== undefined) return existing;\n\tconst secret = newToken();\n\tconst written = await writeSecret(path, secret, \"create\");\n\treturn written === \"exists\" ? ((await readSecret(path)) ?? secret) : secret;\n}\n\n/** The text of the secret file at `path`, or `undefined` when it does not exist. */\nexport async function readSecret(path: string): Promise<string | undefined> {\n\ttry {\n\t\treturn (await readFile(path, \"utf8\")).trim();\n\t} catch (error) {\n\t\tif ((error as NodeJS.ErrnoException).code === \"ENOENT\") return undefined;\n\t\tthrow error;\n\t}\n}\n\n/**\n * Writes `text` to `path` with mode 0600 in one step: a temporary file of the same directory (made exclusively, 0600)\n * linked into place (`create`: refused when `path` exists, `\"exists\"` returned) or renamed over it (`replace`).\n */\nexport async function writeSecret(\n\tpath: string,\n\ttext: string,\n\tmode: \"create\" | \"replace\",\n): Promise<\"written\" | \"exists\"> {\n\tconst temporary = join(dirname(path), `.${newToken(9)}.tmp`);\n\tconst handle = await open(temporary, \"wx\", 0o600);\n\ttry {\n\t\tawait handle.writeFile(`${text}\\n`);\n\t\tawait handle.sync();\n\t} finally {\n\t\tawait handle.close();\n\t}\n\ttry {\n\t\tif (mode === \"replace\") {\n\t\t\tawait rename(temporary, path);\n\t\t\treturn \"written\";\n\t\t}\n\t\tawait link(temporary, path);\n\t\treturn \"written\";\n\t} catch (error) {\n\t\tif ((error as NodeJS.ErrnoException).code === \"EEXIST\") return \"exists\";\n\t\tthrow error;\n\t} finally {\n\t\tawait unlink(temporary).catch(() => {});\n\t}\n}\n"]}

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

@@ -0,0 +1,72 @@
+import type { Principal } from "../../data/index.ts";
+import { type Facet } from "../../host/index.ts";
+import { type HttpRequest } from "../http/index.ts";
+/** What a session is for: a browser (its cookie), a device (a command-line client's token), an ephemeral login. */
+export type SessionKind = "browser" | "device" | "ephemeral";
+/** A browser or device session as `Sessions.list` shows it: never its token or hash. */
+export type SessionInfo = {
+    readonly id: string;
+    readonly label: string;
+    readonly kind: "browser" | "device";
+    readonly principal: unknown;
+    readonly created: number;
+    readonly lastUsed: number;
+};
+/** The kit's sessions (one per server): issue, verify, revoke, and the watchable list of persisted ones. */
+export declare const Sessions: import("../../contracts/contract.ts").Contract<{
+    kind: "local";
+    name: "chord.app.sessions";
+    params: {};
+    history: [{
+        version: "1";
+        variants: {
+            members: {
+                state: {
+                    readonly list: import("../../contracts/index.ts").Schema<{
+                        id: string;
+                        label: string;
+                        kind: "browser" | "device";
+                        principal: unknown;
+                        created: number;
+                        lastUsed: number;
+                    }[]>;
+                };
+                methods: {
+                    readonly issue: import("../../contracts/schema.ts").Method<import("../../contracts/index.ts").Schema<{
+                        principal: unknown;
+                        label: string;
+                        kind: "browser" | "device" | "ephemeral";
+                        secure?: boolean | undefined;
+                    }>, import("../../contracts/index.ts").Schema<{
+                        id: string;
+                        token: string;
+                        cookie: string;
+                    }>>;
+                    readonly verify: import("../../contracts/schema.ts").Method<import("../../contracts/schema.ts").StringSchema, import("../../contracts/index.ts").Schema<unknown>>;
+                    readonly revoke: import("../../contracts/schema.ts").Method<import("../../contracts/schema.ts").StringSchema, import("../../contracts/schema.ts").NullSchema>;
+                };
+                keyed: {};
+            };
+        };
+        changes: never;
+    }];
+}>;
+/** The name of the kit's session cookie. */
+export declare const SESSION_COOKIE = "chord-session";
+/** The sessions' limits: how many ephemeral sessions live at once (1,000 by default; past it the oldest ends). */
+export type SessionLimits = {
+    readonly maxEphemeral?: number;
+};
+/** The kit's sessions: the facet for the server's core facets, and the links endpoint's `opened` hook. */
+export type KitSessions<P extends Principal> = {
+    readonly facet: Facet<P>;
+    /** A link opened with `request`'s credentials: an ephemeral session's links are counted (it ends with its last). */
+    readonly opened: (request: HttpRequest) => (() => void) | undefined;
+};
+/**
+ * The kit's sessions: its facet serving `Sessions` (a host-lifetime object) and contributing its authenticator (the
+ * bearer token first, else the session cookie signed with `cookieSecret`), and the links hook ending an ephemeral
+ * session with its client's connection.
+ */
+export declare function createSessions<P extends Principal>(cookieSecret: string, limits?: SessionLimits): KitSessions<P>;
+//# sourceMappingURL=sessions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.d.ts","sourceRoot":"","sources":["../../../src/node/app/sessions.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,EAAe,KAAK,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAE9D,OAAO,EAIN,KAAK,WAAW,EAKhB,MAAM,kBAAkB,CAAC;AAI1B,mHAAmH;AACnH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE7D,wFAAwF;AACxF,MAAM,MAAM,WAAW,GAAG;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,QAAQ,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,4GAA4G;AAC5G,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiCnB,CAAC;AAEH,4CAA4C;AAC5C,eAAO,MAAM,cAAc,kBAAkB,CAAC;AA4B9C,kHAAkH;AAClH,MAAM,MAAM,aAAa,GAAG;IAAE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/D,0GAA0G;AAC1G,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,SAAS,IAAI;IAC9C,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IACzB,oHAAoH;IACpH,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAC;CACpE,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,GAAE,aAAkB,GAAG,WAAW,CAAC,CAAC,CAAC,CAQpH"}

package/dist/node/app/sessions.js

@@ -0,0 +1,222 @@
+// Sessions (slice 13 §2, decision "The app kit, point 3: authentication"): the kit's object on the server that issues
+// and revokes sessions, and its authenticator. A session is a principal behind a token `<id>.<secret>` (random); only
+// the secret's hash is kept. A browser carries its token in the kit's signed session cookie (`HttpOnly`,
+// `SameSite=Strict`), a command-line client in `Authorization: Bearer <token>`. Browser and device sessions persist in
+// the server's store and expire after 400 days unused; ephemeral sessions (a pick-a-name login, a public route) live
+// in memory only (`EphemeralSessions`), at most `maxEphemeral` of them (past it the oldest ends), so a public login
+// costs the same whatever came before; each ends with its client's connection (its last link closed, a grace period
+// passed: the links endpoint's `opened` hook counts them), and none outlives the server's run.
+import { arr, bool, local, map, method, num, obj, oneOf, opt, str, unknown } from "../../contracts/index.js";
+import { defineState } from "../../documents/index.js";
+import { defineFacet } from "../../host/index.js";
+import { Authenticators, cookie, Http, readCookie, readSignedCookie, } from "../http/index.js";
+import { EphemeralSessions } from "./ephemeral-sessions.js";
+import { hashToken, matchesHash, newToken } from "./secrets.js";
+/** The kit's sessions (one per server): issue, verify, revoke, and the watchable list of persisted ones. */
+export const Sessions = local("chord.app.sessions", {
+    version: 1,
+    params: {},
+    members: {
+        /** The browser and device sessions (ephemeral ones are not listed: there may be many, and they are short). */
+        list: arr(obj({
+            id: str(),
+            label: str(),
+            kind: oneOf("browser", "device"),
+            principal: unknown(),
+            created: num(),
+            lastUsed: num(),
+        })),
+        /**
+         * A new session for `principal`: its id, its token (shown once, kept only hashed) and the session cookie carrying
+         * it for a browser (`Set-Cookie`; `secure` for a remote one).
+         */
+        issue: method(obj({
+            principal: unknown(),
+            label: str(),
+            kind: oneOf("browser", "device", "ephemeral"),
+            secure: opt(bool()),
+        }), obj({ id: str(), token: str(), cookie: str() })),
+        /** The principal `token` authenticates as, or `null` (unknown, revoked, expired, malformed). */
+        verify: method(str(), unknown()),
+        /** Ends session `id` at once: its token authenticates nothing more. */
+        revoke: method(str()),
+    },
+});
+/** The name of the kit's session cookie. */
+export const SESSION_COOKIE = "chord-session";
+/** The stored sessions: by id, each with its secret's hash and its principal (as JSON text: any of the app's). */
+const SessionsDocument = defineState("chord.app.sessions", {
+    schema: obj({
+        sessions: map(obj({
+            hash: str(),
+            label: str(),
+            kind: oneOf("browser", "device"),
+            principal: str(),
+            created: num(),
+            lastUsed: num(),
+        })),
+    }),
+    version: 1,
+    initial: () => ({ sessions: {} }),
+    persist: true,
+    checkpointWhen: (_value, _ops, { deltasSinceBase }) => deltasSinceBase >= 50,
+});
+/** How often a session's `lastUsed` is written at most: once a minute (not one commit per request). */
+const TOUCH_MS = 60_000;
+/** How long a persisted session lives unused: 400 days, as its cookie. */
+const SESSION_IDLE_MS = 400 * 24 * 60 * 60_000;
+/**
+ * The kit's sessions: its facet serving `Sessions` (a host-lifetime object) and contributing its authenticator (the
+ * bearer token first, else the session cookie signed with `cookieSecret`), and the links hook ending an ephemeral
+ * session with its client's connection.
+ */
+export function createSessions(cookieSecret, limits = {}) {
+    const ephemeral = new EphemeralSessions(limits.maxEphemeral ?? 1000);
+    const opened = (request) => {
+        const token = bearerToken(request) ?? readCookie(request, SESSION_COOKIE, cookieSecret);
+        const dot = token?.indexOf(".") ?? -1;
+        return dot > 0 ? ephemeral.linkOpened(token.slice(0, dot)) : undefined;
+    };
+    return { facet: sessionsFacet(cookieSecret, ephemeral), opened };
+}
+/** The facet of `createSessions`. */
+function sessionsFacet(cookieSecret, ephemeral) {
+    return defineFacet((host) => host.serve(Sessions, (_params, self) => {
+        const document = self.state(SessionsDocument);
+        const change = (fn, context) => 
+        // Not awaited by authentication: the request goes on; a write that fails is made again by a later request.
+        void document.change((draft) => fn(draft.sessions), context).catch(() => { });
+        /** The principal of `token`, or `undefined`; touches or lazily removes the persisted session it names. */
+        const authenticate = (token, context) => {
+            const dot = token.indexOf(".");
+            if (dot <= 0)
+                return undefined;
+            const id = token.slice(0, dot);
+            const secret = token.slice(dot + 1);
+            const short = ephemeral.get(id);
+            if (short !== undefined)
+                return matchesHash(secret, short.hash) ? short.principal : undefined;
+            // A trust boundary: `id` is the client's (`Object.hasOwn`: no inherited member is a session).
+            const sessions = document.value.sessions;
+            if (!Object.hasOwn(sessions, id))
+                return undefined;
+            const session = sessions[id];
+            if (!matchesHash(secret, session.hash))
+                return undefined;
+            const now = Date.now();
+            if (now - session.lastUsed > SESSION_IDLE_MS) {
+                change((draft) => {
+                    delete draft[id];
+                }, context);
+                return undefined;
+            }
+            if (now - session.lastUsed > TOUCH_MS) {
+                change((draft) => {
+                    if (Object.hasOwn(draft, id))
+                        draft[id].lastUsed = now;
+                }, context);
+            }
+            // Stored by `issue` from a principal of the app's type.
+            return JSON.parse(session.principal);
+        };
+        self.contribute(Authenticators, (request, context) => {
+            const token = bearerToken(request) ?? readCookie(request, SESSION_COOKIE, cookieSecret);
+            return token === undefined ? undefined : authenticate(token, context);
+        });
+        self.contribute(Http, { wraps: [rollingCookie(cookieSecret, authenticate)] });
+        return {
+            list: self.derive([document], ([value]) => Object.entries(value.sessions).map(([id, { label, kind, principal, created, lastUsed }]) => ({
+                id,
+                label,
+                kind,
+                // Stored by `issue` as JSON text.
+                principal: JSON.parse(principal),
+                created,
+                lastUsed,
+            }))),
+            issue: async ({ principal, label, kind, secure }, ctx) => {
+                const id = newToken(12);
+                const secret = newToken(32);
+                if (kind === "ephemeral") {
+                    // Principals are the app's: `issue`'s callers pass one of its type.
+                    ephemeral.issue(id, hashToken(secret), principal);
+                }
+                else {
+                    const now = Date.now();
+                    const stored = JSON.stringify(principal);
+                    await document.change((draft) => {
+                        draft.sessions[id] = {
+                            hash: hashToken(secret),
+                            label,
+                            kind,
+                            principal: stored,
+                            created: now,
+                            lastUsed: now,
+                        };
+                    }, ctx);
+                }
+                const token = `${id}.${secret}`;
+                // Only whether the browser is remote matters to the cookie (`Secure`).
+                const provenance = secure === true ? { kind: "remote", host: "" } : { kind: "local" };
+                const set = sessionCookie(token, kind, { provenance }, cookieSecret);
+                return { id, token, cookie: set };
+            },
+            verify: async (token, ctx) => authenticate(token, ctx) ?? null,
+            revoke: async (id, ctx) => {
+                if (ephemeral.revoke(id))
+                    return null;
+                await document.change((draft) => {
+                    delete draft.sessions[id];
+                }, ctx);
+                return null;
+            },
+        };
+    }));
+}
+/**
+ * The session cookie carrying `token` (a session of `kind`) for a browser of `request`'s provenance: a persisted
+ * session's lives as long as the session does unused (400 days, renewed by `rollingCookie`), an ephemeral one's only
+ * while the browser runs.
+ */
+function sessionCookie(token, kind, request, secret) {
+    const maxAge = kind === "ephemeral" ? undefined : SESSION_IDLE_MS / 1000;
+    return cookie(SESSION_COOKIE, token, { secret, request, maxAge });
+}
+/** How old a session cookie gets before a response renews it: a day. */
+const ROLL_MS = 24 * 60 * 60_000;
+/**
+ * The wrap around every route renewing the session cookie a request signed in with once it is older than a day: the
+ * response sets it again with a fresh signed expiry, so a browser used within every 400 days stays signed in. Not when
+ * the route sets a cookie itself, nor for an ephemeral session's (it has no expiry) or a token that no longer
+ * authenticates.
+ */
+function rollingCookie(secret, authenticate) {
+    return {
+        name: "chord.app.rolling-cookie",
+        phase: "headers",
+        scope: "all",
+        wrap: async (request, next, ctx) => {
+            const response = await next(request);
+            if (ctx.principal === undefined || Object.keys(response.headers ?? {}).some(isSetCookie))
+                return response;
+            const signed = readSignedCookie(request, SESSION_COOKIE, secret);
+            if (signed?.expires === undefined || signed.expires - Date.now() > SESSION_IDLE_MS - ROLL_MS)
+                return response;
+            if (authenticate(signed.value, ctx) === undefined)
+                return response;
+            const renewed = sessionCookie(signed.value, "browser", request, secret);
+            return { ...response, headers: { ...response.headers, "Set-Cookie": renewed } };
+        },
+    };
+}
+/** Whether a header name is `Set-Cookie` (any case). */
+function isSetCookie(name) {
+    return name.toLowerCase() === "set-cookie";
+}
+/** The token of an `Authorization: Bearer <token>` header. */
+function bearerToken(request) {
+    const header = request.headers.get("authorization");
+    const match = header === null ? null : /^Bearer\s+(\S+)$/i.exec(header);
+    return match?.[1];
+}
+//# sourceMappingURL=sessions.js.map