@plurnk/plurnk-web 0.0.0-stage → 1.1.0

package/ai.plurnk/module.js

@@ -0,0 +1,326 @@
+import { readFile } from "node:fs/promises";
+import { MIMEType } from "node:util";
+import { ConfigurationError, Knob } from "@plurnk/plurnk-meta";
+import { Problems } from "@plurnk/plurnk-contracts";
+import indexDocument from "./index-document.js";
+import { directoryPath, parseDirectory } from "./directory-addresses.js";
+import Documents from "./documents.js";
+import Session, { CALLBACK, CLIENT } from "./session.js";
+import { ownNavigation, privateHeaders, redirect, refusal, RequestError, sameOriginFetch } from "./http.js";
+import { readAsset, sendAsset } from "./static-assets.js";
+import Creations from "./creations.js";
+import Diagrams from "./diagrams.js";
+
+/** @typedef {{ credentials?: Pick<import("@plurnk/plurnk-contracts/port").ApplicationPort["credentials"], "registerClient"> | null }} SetupPort */
+/**
+ * @typedef {{
+ *   credentials?: (import("./session.js").SessionCredentials & Pick<import("@plurnk/plurnk-contracts/port").ApplicationPort["credentials"], "face">) | null,
+ *   registerHttpRoute: import("@plurnk/plurnk-contracts/port").ApplicationPort["registerHttpRoute"],
+ *   listWorkspaces: () => Promise<readonly import("./documents.js").DirectoryWorkspace[]>,
+ *   listSessions: (workspaceId: number) => Promise<readonly import("./documents.js").DirectorySession[]>,
+ *   readSessionOverview?: import("@plurnk/plurnk-contracts/port").ApplicationPort["readSessionOverview"],
+ *   createWorkspace: (args: { name?: string, projectRoot: string | null }) => Promise<string | { workspaceName: string, projectRoot: string | null }>,
+ *   renameWorkspace: (workspaceId: number, name: string) => Promise<{ name: string }>,
+ *   createSession: (args: { workspaceId: number, name?: string }) => Promise<{ sessionName: string }>,
+ *   setWorkspaceArchived: (args: { workspaceId: number, archived: boolean }) => Promise<unknown>,
+ *   setSessionArchived: (args: { workspaceId: number, sessionId: number, archived: boolean }) => Promise<unknown>,
+ * }} Port
+ */
+/** {§web-host} {§web-configuration} {§web-package} @returns {import("@plurnk/plurnk-modules").DaemonModule<SetupPort, Port>} */
+export default function createModule() {
+    if (!Knob.flag("PLURNK_WEB_ENABLED")) return {};
+    /** @type {import("@plurnk/plurnk-modules").ContainedConfiguration[]} */
+    const contained = [];
+    /** @template T @param {() => T} read @returns {T | null} */
+    const contain = (read) => {
+        try { return read(); }
+        catch (error) {
+            if (!(error instanceof ConfigurationError)) throw error;
+            contained.push({ key: error.key, message: error.message });
+            return null;
+        }
+    };
+    const yolo = contain(() => Knob.flag("PLURNK_WEB_YOLO"));
+    const reasoningPreviewChars = contain(() => Knob.integer("PLURNK_WEB_REASONING_PREVIEW_CHARS", 1));
+    const limits = { ttl: contain(() => Knob.integer("PLURNK_WEB_LOGIN_TTL_SEC", 1)) };
+    const createTtl = contain(() => Knob.integer("PLURNK_WEB_CREATE_TTL_SEC", 1));
+    const createTokens = contain(() => Knob.integer("PLURNK_WEB_CREATE_TOKENS", 1));
+    const formBytes = contain(() => Knob.integer("PLURNK_WEB_FORM_BYTES", 1));
+    const creations = createTtl !== null && createTokens !== null ? new Creations({ ttl: createTtl, tokens: createTokens }) : null;
+    const diagrams = Diagrams.create(contain);
+    /** @type {{ clientId: string, clientSecret: string } | null} */
+    let registration = null;
+    /** @type {Session | null} */
+    let session = null;
+    let stopped = false;
+    /** @type {Set<Promise<void>>} */
+    const requests = new Set();
+    const stop = () => { stopped = true; };
+
+    return {
+        mounts: ["/"],
+        contained: Object.freeze(contained),
+        async setup({ credentials }) {
+            if (!credentials) return;
+            // {§web-authorization-style} The same built stylesheet serves both document owners.
+            /** @type {import("./static-assets.js").AssetEntry[]} */
+            const inventory = JSON.parse(await readFile(new URL("assets.json", import.meta.url), "utf8"));
+            const root = inventory.find(([path]) => path === "/index.html");
+            if (!root) throw new Error("The web asset inventory must include index.html.");
+            const stylesheetPath = Documents.stylesheet((await readAsset(root[1], root[2], root[3])).body.toString("utf8"));
+            if (!inventory.some(([path, , type]) => path === stylesheetPath && type === "text/css")) throw new Error("The application stylesheet is absent from the web asset inventory.");
+            registration = credentials.registerClient({ id: CLIENT, redirectPaths: [CALLBACK], scopes: ["acp"], stylesheetPath });
+        },
+        async start(seam) {
+            const credentials = seam.credentials;
+            const face = credentials?.face() ?? null;
+            if (face !== null && credentials) {
+                if (registration === null) throw new Error("Web sign-in requires the daemon's credential authority and completed module setup.");
+                session = new Session(credentials, registration, face, limits);
+            }
+            // {§web-assets} Requests select entries, never filesystem paths.
+            /** @type {import("./static-assets.js").AssetEntry[]} */
+            const inventory = JSON.parse(await readFile(new URL("assets.json", import.meta.url), "utf8"));
+            const resources = new Map(await Promise.all(inventory.map(async ([pathname, file, mediaType, encoded]) => /** @type {const} */ ([
+                pathname,
+                await readAsset(file, mediaType, encoded),
+            ]))));
+
+            const root = resources.get("/index.html");
+            if (root === undefined) throw new Error("The web asset inventory must include index.html.");
+            const documents = new Documents(root.body.toString("utf8"), yolo, reasoningPreviewChars);
+
+            /** @param {import("node:http").IncomingMessage} req @param {import("node:http").ServerResponse} res */
+            const serve = async (req, res) => {
+                const pathname = (req.url ?? "").split("?")[0];
+                const directory = parseDirectory(pathname);
+                const home = indexDocument(pathname) === "/index.html";
+                const account = indexDocument(pathname) === "/account/index.html";
+                const sessions = indexDocument(pathname) === "/account/sessions/index.html";
+                const revoke = /^\/account\/sessions\/([^/]+)\/revoke$/u.exec(pathname);
+                const others = pathname === "/account/sessions/revoke-others";
+                const token = pathname === "/auth/token";
+                const creation = pathname === "/workspaces/new";
+                const rename = pathname === "/workspaces/rename";
+                const sessionCreation = pathname === "/sessions/new";
+                const workspaceArchive = pathname === "/workspaces/archive";
+                const sessionArchive = pathname === "/sessions/archive";
+                const diagram = pathname === "/render/mermaid";
+                const auth = token || ["/auth/login", CALLBACK, "/auth/logout"].includes(pathname);
+                let admitted = false;
+                try {
+                    const inventory = sessions ? session?.account(req) : null;
+                    admitted = sessions ? inventory != null : session?.admitted(req) ?? false;
+                    if (diagram) {
+                        if (session !== null && !admitted) throw new RequestError(401, "Sign in to render diagrams.");
+                        if (diagrams === null) throw new RequestError(503, "Diagram compilation is unavailable because its configuration is invalid.");
+                        await diagrams.serve(req, res);
+                        return;
+                    }
+                    if (token && session === null) throw new RequestError(404, "Access credentials are unavailable while authentication is disabled.");
+                    if (auth && session !== null) {
+                        const expected = token || pathname === "/auth/logout" ? "POST" : "GET";
+                        if (req.method !== expected) {
+                            res.setHeader("allow", expected);
+                            throw new RequestError(405, "Method not allowed.");
+                        }
+                        if (pathname === "/auth/login") await session.login(req, res);
+                        else if (pathname === CALLBACK) await session.callback(req, res);
+                        else if (token) await session.token(req, res);
+                        else session.logout(req, res);
+                        return;
+                    }
+                    if (creation || rename || sessionCreation || workspaceArchive || sessionArchive) {
+                        const actionName = creation ? "create a workspace" : rename ? "rename a workspace" : sessionCreation ? "create a session" : workspaceArchive ? "archive a workspace" : "archive a session";
+                        if (req.method !== "POST") {
+                            res.setHeader("allow", "POST");
+                            throw new RequestError(405, `Use POST to ${actionName}.`);
+                        }
+                        if (session !== null && !admitted) throw new RequestError(401, `Sign in again before ${actionName}.`);
+                        if (session !== null) session.sameOriginForm(req);
+                        else {
+                            const origin = req.headers.origin;
+                            if (typeof origin !== "string") throw new RequestError(403, "Same-origin form required.");
+                            let host;
+                            try { host = new URL(origin).host; }
+                            catch (cause) { throw new RequestError(403, "Same-origin form required.", { cause }); }
+                            if (host !== req.headers.host) throw new RequestError(403, "Same-origin form required.");
+                            sameOriginFetch(req);
+                        }
+                        let type;
+                        try { type = new MIMEType(req.headers["content-type"] ?? ""); }
+                        catch (cause) { throw new RequestError(415, "Use UTF-8 application/x-www-form-urlencoded.", { cause }); }
+                        if (type.essence !== "application/x-www-form-urlencoded"
+                            || (type.params.has("charset") && type.params.get("charset")?.toLowerCase() !== "utf-8")) {
+                            throw new RequestError(415, "Use UTF-8 application/x-www-form-urlencoded.");
+                        }
+                        if (formBytes === null) {
+                            req.resume();
+                            throw new RequestError(503, "Form submissions are unavailable because PLURNK_WEB_FORM_BYTES is invalid.");
+                        }
+                        if ((creation || sessionCreation) && creations === null) {
+                            req.resume();
+                            throw new RequestError(503, "Creation forms are unavailable because their configuration is invalid.");
+                        }
+                        let size = 0;
+                        const chunks = [];
+                        for await (const chunk of req.iterator({ destroyOnReturn: false })) {
+                            size += chunk.byteLength;
+                            if (size > formBytes) { req.resume(); throw new RequestError(413, "Form exceeds its bound."); }
+                            chunks.push(chunk);
+                        }
+                        let fields;
+                        try { fields = new URLSearchParams(new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks))); }
+                        catch (cause) { throw new RequestError(400, "Invalid form data.", { cause }); }
+                        if (creation && creations !== null) {
+                            const formToken = fields.getAll("token").length === 1 ? fields.get("token") : null;
+                            if (!formToken) throw new RequestError(400, "Expected the form's workspace creation token.");
+                            // An empty name is no name: the daemon names the workspace.
+                            const name = fields.get("name") ?? "";
+                            redirect(res, await creations.submit(formToken, async () => {
+                                try { return await seam.createWorkspace({ ...(name === "" ? {} : { name }), projectRoot: null }); }
+                                catch (cause) { throw refusal(cause, "The daemon could not create the workspace.", documents.retryCreation(name)); }
+                            }));
+                            return;
+                        }
+                        if (rename) {
+                            const targetName = fields.get("workspace");
+                            const newName = fields.get("name");
+                            if (!targetName || !newName) throw new RequestError(400, "Expected current workspace and new name.");
+                            const workspaces = await seam.listWorkspaces();
+                            const ws = workspaces.find(({ name }) => name === targetName);
+                            if (!ws) throw new RequestError(404, "Workspace not found.");
+                            let renamed;
+                            try { renamed = await seam.renameWorkspace(ws.id, newName); }
+                            catch (cause) { throw refusal(cause, "The daemon could not rename the workspace.", documents.retryRename(ws.name, newName)); }
+                            const path = directoryPath({ kind: "workspace", workspace: renamed.name });
+                            if (path === null) throw new Error("The daemon returned a workspace name without a directory address.");
+                            redirect(res, path);
+                            return;
+                        }
+                        if (sessionCreation && creations !== null) {
+                            const formToken = fields.getAll("token").length === 1 ? fields.get("token") : null;
+                            const targetName = fields.get("workspace");
+                            if (!formToken || !targetName) throw new RequestError(400, "Expected session creation token and workspace name.");
+                            // An empty name is no name: the daemon names the session.
+                            const sessionName = fields.get("name") ?? "";
+                            const workspaces = await seam.listWorkspaces();
+                            const ws = workspaces.find(({ name }) => name === targetName);
+                            if (!ws) throw new RequestError(404, "Workspace not found.");
+                            redirect(res, await creations.submit(formToken, async () => {
+                                let createdSession;
+                                try { createdSession = await seam.createSession({ workspaceId: ws.id, ...(sessionName === "" ? {} : { name: sessionName }) }); }
+                                catch (cause) { throw refusal(cause, "The daemon could not create the session.", documents.retrySession(ws.name, sessionName)); }
+                                // An internal fault, not a refusal: the session exists.
+                                const path = directoryPath({ kind: "session", workspace: ws.name, session: createdSession.sessionName });
+                                if (path === null) throw new Error("The daemon returned a session name without a directory address.");
+                                return path;
+                            }));
+                            return;
+                        }
+                        if (workspaceArchive) {
+                            const targetName = fields.get("workspace");
+                            if (!targetName) throw new RequestError(400, "Expected workspace name.");
+                            const workspaces = await seam.listWorkspaces();
+                            const ws = workspaces.find(({ name }) => name === targetName);
+                            if (!ws) throw new RequestError(404, "Workspace not found.");
+                            try { await seam.setWorkspaceArchived({ workspaceId: ws.id, archived: true }); }
+                            catch (cause) { throw refusal(cause, "The daemon could not archive the workspace."); }
+                            redirect(res, "/~/");
+                            return;
+                        }
+                        if (sessionArchive) {
+                            const targetName = fields.get("workspace");
+                            const targetSession = fields.get("session");
+                            if (!targetName || !targetSession) throw new RequestError(400, "Expected workspace and session name.");
+                            const workspaces = await seam.listWorkspaces();
+                            const ws = workspaces.find(({ name }) => name === targetName);
+                            if (!ws) throw new RequestError(404, "Workspace not found.");
+                            const workspaceSessions = await seam.listSessions(ws.id);
+                            const target = workspaceSessions.find(({ name }) => name === targetSession);
+                            if (!target) throw new RequestError(404, "Session not found.");
+                            try { await seam.setSessionArchived({ workspaceId: ws.id, sessionId: target.id, archived: true }); }
+                            catch (cause) { throw refusal(cause, "The daemon could not archive the session."); }
+                            const path = directoryPath({ kind: "workspace", workspace: ws.name });
+                            if (path === null) throw new Error("The daemon returned a workspace name without a directory address.");
+                            redirect(res, path);
+                            return;
+                        }
+                    }
+                    if (account || sessions || revoke !== null || others) {
+                        if (session === null) throw new RequestError(404, "Account is unavailable while authentication is disabled.");
+                        if (revoke !== null || others) {
+                            if (req.method !== "POST") {
+                                res.setHeader("allow", "POST");
+                                throw new RequestError(405, "Method not allowed.");
+                            }
+                            if (others) session.revokeOthers(req, res);
+                            else if (revoke !== null) {
+                                let family;
+                                try { family = decodeURIComponent(revoke[1]); }
+                                catch (cause) { throw new RequestError(400, "Invalid session address.", { cause }); }
+                                session.revoke(req, res, family);
+                            }
+                            return;
+                        }
+                    }
+                    if (directory !== null || home || account || sessions) {
+                        if (req.method !== "GET" && req.method !== "HEAD") {
+                            res.setHeader("allow", "GET, HEAD");
+                            throw new RequestError(405, "Method not allowed.");
+                        }
+                        if (!home && session !== null && !admitted) {
+                            redirect(res, session.signIn(req, req.url ?? "/~/"));
+                            return;
+                        }
+                        const body = home ? await documents.home(admitted, session === null || admitted ? seam : undefined) : account ? documents.account() : inventory ? documents.sessions(inventory)
+                            : directory === null ? null : await documents.read(directory, seam, admitted, ownNavigation(req));
+                        if (body === null) throw new RequestError(404, "Workspace or session not found.");
+                        res.writeHead(200, { ...privateHeaders, "content-type": "text/html; charset=utf-8", "content-length": body.byteLength });
+                        res.end(req.method === "HEAD" ? undefined : body);
+                        return;
+                    }
+                    if (req.method !== "GET" && req.method !== "HEAD") {
+                        res.setHeader("allow", "GET, HEAD");
+                        throw new RequestError(405, "Use GET or HEAD for this resource.");
+                    }
+                    const resource = resources.get(indexDocument(pathname));
+                    if (resource === undefined) throw new RequestError(404, "The requested page or resource does not exist.");
+                    sendAsset(req, res, resource);
+                } catch (error) {
+                    if (!(error instanceof RequestError)) throw error;
+                    const body = token || diagram ? Buffer.from(JSON.stringify(Problems.create("web", diagram ? "diagram-request-rejected" : "token-request-rejected", error.status, error.message)))
+                        : documents.error(error.status, error.message, admitted, { recovery: error.recovery, retry: error.retry });
+                    res.writeHead(error.status, { ...privateHeaders, "content-type": token || diagram ? "application/problem+json" : "text/html; charset=utf-8", "content-length": body.byteLength });
+                    res.end(req.method === "HEAD" ? undefined : body);
+                } finally {
+                    if (diagram) req.resume();
+                }
+            };
+
+            // {§web-route-settlement} Every admitted handler retains its host resources until settlement.
+            seam.registerHttpRoute("/", async (req, res) => {
+                if (stopped) {
+                    const body = Buffer.from(JSON.stringify(Problems.create("web", "service-stopping", 503, "The PLURNK service is shutting down.")));
+                    res.writeHead(503, { ...privateHeaders, "content-type": "application/problem+json", "content-length": body.byteLength });
+                    res.end(req.method === "HEAD" ? undefined : body);
+                    req.resume();
+                    return;
+                }
+                const request = serve(req, res);
+                requests.add(request);
+                try { await request; }
+                finally { requests.delete(request); }
+            });
+        },
+        stop,
+        async close() {
+            stop();
+            const cleanup = new AsyncDisposableStack();
+            cleanup.defer(() => session?.close());
+            cleanup.defer(async () => { await Promise.allSettled(requests); });
+            cleanup.defer(() => diagrams?.close());
+            await cleanup.disposeAsync();
+        },
+    };
+}

package/ai.plurnk/session.js

@@ -0,0 +1,319 @@
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import * as oauth from "oauth4webapi";
+import { cookie, redirect, RequestError, privateHeaders, sameOriginFetch } from "./http.js";
+import { directoryPath, parseDirectory } from "./directory-addresses.js";
+import indexDocument from "./index-document.js";
+
+const SESSION = "plurnk_web_session";
+// A sign-in transaction's cookie: this prefix and the transaction's state.
+const TRANSACTION = "plurnk_web_login_";
+// {§web-session} Under HTTPS the names carry the browser's prefixes that no sibling host can set: the session is host-only
+// at `/`, and a transaction, scoped to `/auth`, is Secure.
+const HOST_ONLY = "__Host-";
+const SECURE_ONLY = "__Secure-";
+export const CALLBACK = "/auth/callback";
+export const CLIENT = "plurnk-web";
+
+/** @typedef {{ access: string, refresh: string, claims: import("@plurnk/plurnk-contracts").CredentialClaims, refreshing: Promise<void> | null }} Grant */
+/** @typedef {{ verifier: string, target: string, redirectUri: string, expires: number }} Transaction */
+/** @typedef {import("@plurnk/plurnk-contracts").RequestHeaders & { url?: string }} SessionRequest */
+/** @typedef {import("./http.js").HttpResponse} SessionResponse */
+/** @typedef {Pick<import("@plurnk/plurnk-contracts").CredentialAuthority, "verify" | "issue" | "revokeFamily" | "sessions" | "onRevoked">} SessionCredentials */
+
+/** {§web-session} A consumer of the daemon's authority, never an independent issuer or session inventory. */
+export default class Session {
+    #credentials;
+    #client;
+    #authenticate;
+    #face;
+    /** @type {{ server: oauth.AuthorizationServer, options: { [oauth.allowInsecureRequests]: boolean } } | null} */
+    #authority = null;
+    #limits;
+    // {§web-session} Seals sign-in transactions; it lives and ends with this module instance.
+    #key = randomBytes(32);
+    /** @type {Map<string, Grant>} */
+    #grants = new Map();
+    #unsubscribe;
+
+    /**
+     * @param {SessionCredentials} credentials
+     * @param {{ clientId: string, clientSecret: string }} registration
+     * @param {import("@plurnk/plurnk-contracts").CredentialFace} face
+     * @param {{ ttl: number | null }} limits
+     */
+    constructor(credentials, registration, face, limits) {
+        this.#credentials = credentials;
+        this.#client = { client_id: registration.clientId };
+        this.#authenticate = oauth.ClientSecretBasic(registration.clientSecret);
+        this.#face = face;
+        this.#limits = limits;
+        this.#unsubscribe = credentials.onRevoked((family) => this.#grants.delete(family));
+    }
+
+    /** {§web-session} The daemon's issuer for this request: its configured origin, else the address the browser reached.
+     * @param {SessionRequest} req
+     */
+    #issuer(req) { return this.#face.issuer(req); }
+
+    // {§web-session} This module's own calls go to the daemon's answer for no request, never to an address a
+    // browser named. Discovery is after admission, not module startup: the listener is not serving yet at start.
+    async #metadata() {
+        if (this.#authority !== null) return this.#authority;
+        const issuer = new URL(this.#face.issuer());
+        const options = { [oauth.allowInsecureRequests]: issuer.protocol === "http:" };
+        const response = await oauth.discoveryRequest(issuer, { ...options, algorithm: "oauth2" });
+        this.#authority = { server: await oauth.processDiscoveryResponse(issuer, response), options };
+        return this.#authority;
+    }
+
+    /** @param {SessionRequest} req */
+    #claims(req) {
+        const token = cookie(req, this.#session(req));
+        const claims = token === null ? null : this.#credentials.verify(token);
+        return claims?.kind === "session" && claims.clientId === this.#client.client_id && claims.scopes.includes("acp") ? claims : null;
+    }
+
+    /** @param {SessionRequest} req */
+    admitted(req) { return this.#claims(req) !== null; }
+
+    /** {§web-account} The authority owns the inventory; the cookie identifies its current family.
+     * @param {SessionRequest} req
+     */
+    account(req) {
+        const claims = this.#claims(req);
+        return claims === null ? null : {
+            family: claims.family, sessions: this.#credentials.sessions(claims.subject),
+        };
+    }
+
+    /** @param {SessionRequest} req */
+    #mutation(req) {
+        const account = this.account(req);
+        if (account === null) throw new RequestError(401, "Sign in again before managing sessions.");
+        this.sameOriginForm(req);
+        return account;
+    }
+
+    /** @param {SessionRequest} req @param {SessionResponse} res @param {string} family */
+    revoke(req, res, family) {
+        const account = this.#mutation(req);
+        if (!account.sessions.some((entry) => entry.family === family)) throw new RequestError(404, "Session not found.");
+        if (family === account.family) { this.logout(req, res); return; }
+        this.#credentials.revokeFamily(family);
+        redirect(res, "/account/sessions/");
+    }
+    /** {§web-workspace-creation} Module-owned form mutations use the daemon's own origin.
+     * @param {SessionRequest} req
+     */
+    sameOriginForm(req) {
+        if (req.headers.origin !== this.#issuer(req)) throw new RequestError(403, "Same-origin form required.");
+        sameOriginFetch(req);
+    }
+
+    /** @param {SessionRequest} req @param {SessionResponse} res */
+    revokeOthers(req, res) {
+        const account = this.#mutation(req);
+        for (const entry of account.sessions) if (entry.family !== account.family) this.#credentials.revokeFamily(entry.family);
+        redirect(res, "/account/sessions/");
+    }
+
+    /** @param {SessionRequest} req */
+    #secure(req) { return this.#issuer(req).startsWith("https:"); }
+
+    /** @param {SessionRequest} req */
+    #session(req) { return `${this.#secure(req) ? HOST_ONLY : ""}${SESSION}`; }
+
+    /** @param {SessionRequest} req @param {string} state */
+    #transaction(req, state) { return `${this.#secure(req) ? SECURE_ONLY : ""}${TRANSACTION}${state}`; }
+
+    /** @param {SessionRequest} req @param {string} name @param {string} value @param {string} path @param {number} ttl */
+    #cookie(req, name, value, path, ttl) {
+        return `${name}=${value}; Path=${path}; HttpOnly; SameSite=Lax; Max-Age=${Math.max(0, Math.ceil(ttl))}`
+            + (this.#secure(req) ? "; Secure" : "");
+    }
+
+    /** {§web-session} Where a browser starts sign-in: the issuer's own address, so its transaction and callback share one host.
+     * @param {SessionRequest} req @param {string} returnTo
+     */
+    signIn(req, returnTo) {
+        const location = new URL(`/auth/login?${new URLSearchParams({ return: returnTo })}`, this.#issuer(req));
+        return location.host === req.headers.host ? `${location.pathname}${location.search}` : location.href;
+    }
+
+    /** @param {SessionRequest} req @param {SessionResponse} res */
+    async login(req, res) {
+        const issuer = this.#issuer(req);
+        const requested = new URL(req.url ?? "/", issuer).searchParams.get("return") ?? "/~/";
+        const directory = parseDirectory(requested);
+        const document = indexDocument(requested.split(/[?#]/u)[0]);
+        const target = ["/account/index.html", "/account/sessions/index.html"].includes(document) ? document.slice(0, -"index.html".length)
+            : directory === null ? null : directoryPath(directory);
+        if (target === null) throw new RequestError(400, "Invalid return page.");
+        if (this.admitted(req)) { redirect(res, target); return; }
+        if (this.#limits.ttl === null) throw new RequestError(503, "Browser sign-in is unavailable because PLURNK_WEB_LOGIN_TTL_SEC is invalid.");
+        const { server } = await this.#metadata();
+        if (!server.authorization_endpoint) throw new Error("The daemon's authorization metadata omits its authorization endpoint.");
+
+        const state = oauth.generateRandomState();
+        const verifier = oauth.generateRandomCodeVerifier();
+        const challenge = await oauth.calculatePKCECodeChallenge(verifier);
+        const redirectUri = `${issuer}${CALLBACK}`;
+        const name = this.#transaction(req, state);
+        const sealed = this.#seal(name, { verifier, target, redirectUri, expires: Date.now() + this.#limits.ttl * 1000 });
+        res.setHeader("set-cookie", this.#cookie(req, name, sealed, "/auth", this.#limits.ttl));
+        // The browser signs in at the daemon's authorization endpoint on the address it reached.
+        const url = new URL(new URL(server.authorization_endpoint).pathname, issuer);
+        url.search = new URLSearchParams({
+            client_id: this.#client.client_id, redirect_uri: redirectUri,
+            response_type: "code", scope: "acp", code_challenge_method: "S256", code_challenge: challenge, state,
+        }).toString();
+        redirect(res, url.href);
+    }
+
+    /** @param {SessionRequest} req @param {SessionResponse} res */
+    async callback(req, res) {
+        const url = new URL(req.url ?? "/", this.#issuer(req));
+        const state = url.searchParams.get("state") ?? "";
+        const expired = new RequestError(400, "This browser holds no current sign-in for this callback. Start sign-in again.");
+        if (!/^[\w-]+$/u.test(state)) throw expired;
+        const name = this.#transaction(req, state);
+        const sealed = cookie(req, name);
+        // Single use: the browser drops the transaction whatever this callback's outcome.
+        const cleared = this.#cookie(req, name, "", "/auth", 0);
+        res.setHeader("set-cookie", cleared);
+        const transaction = sealed === null ? null : this.#open(name, sealed);
+        if (transaction === null || transaction.expires <= Date.now()) throw expired;
+        const { server, options } = await this.#metadata();
+        let params;
+        try {
+            params = oauth.validateAuthResponse(server, this.#client, url, state);
+        } catch (cause) {
+            throw new RequestError(400, "Sign-in was not completed. Start sign-in again.", { cause });
+        }
+        const response = await oauth.authorizationCodeGrantRequest(server, this.#client, this.#authenticate,
+            params, transaction.redirectUri, transaction.verifier, options);
+        let result;
+        try {
+            result = await oauth.processAuthorizationCodeResponse(server, this.#client, response);
+        } catch (cause) {
+            // The authority redeems a code once: a replayed callback is the browser's to restart.
+            if (cause instanceof oauth.ResponseBodyError && cause.error === "invalid_grant") {
+                throw new RequestError(400, "Sign-in was not completed. Start sign-in again.", { cause });
+            }
+            throw new RequestError(502, "The daemon did not complete sign-in. Start sign-in again.", { cause });
+        }
+        const grant = this.#grant(result);
+        const { claims } = grant;
+        const ttlMs = claims.expiresAt - Date.now();
+        const issued = this.#credentials.issue({ kind: "session", subject: claims.subject, clientId: claims.clientId,
+            scopes: claims.scopes, family: claims.family, ttlMs });
+        const old = this.#claims(req);
+        if (old !== null && old.family !== claims.family) this.#credentials.revokeFamily(old.family);
+        this.#prune();
+        this.#grants.set(claims.family, grant);
+        res.setHeader("set-cookie", [cleared, this.#cookie(req, this.#session(req), issued.token, "/", ttlMs / 1000)]);
+        redirect(res, transaction.target);
+    }
+
+    /** {§web-session} A sign-in transaction travels sealed in its own browser cookie, named for its state.
+     * @param {string} name @param {Transaction} transaction
+     */
+    #seal(name, transaction) {
+        const iv = randomBytes(12);
+        const cipher = createCipheriv("aes-256-gcm", this.#key, iv, { authTagLength: 16 }).setAAD(Buffer.from(name));
+        const body = Buffer.concat([cipher.update(JSON.stringify(transaction)), cipher.final()]);
+        return Buffer.concat([iv, body, cipher.getAuthTag()]).toString("base64url");
+    }
+
+    /** A cookie this module instance did not seal for this name opens to nothing.
+     * @param {string} name @param {string} sealed @returns {Transaction | null}
+     */
+    #open(name, sealed) {
+        const bytes = Buffer.from(sealed, "base64url");
+        try {
+            const decipher = createDecipheriv("aes-256-gcm", this.#key, bytes.subarray(0, 12), { authTagLength: 16 }).setAAD(Buffer.from(name));
+            decipher.setAuthTag(bytes.subarray(-16));
+            return JSON.parse(Buffer.concat([decipher.update(bytes.subarray(12, -16)), decipher.final()]).toString("utf8"));
+        } catch {
+            return null;
+        }
+    }
+
+    /** @param {oauth.TokenEndpointResponse} result @returns {Grant} */
+    #grant(result) {
+        const access = this.#credentials.verify(result.access_token);
+        const refresh = result.refresh_token === undefined ? null : this.#credentials.verify(result.refresh_token);
+        if (access?.kind !== "access" || refresh?.kind !== "refresh" || access.family !== refresh.family
+            || access.clientId !== this.#client.client_id || refresh.clientId !== access.clientId
+            || access.subject !== refresh.subject || !access.scopes.includes("acp") || !refresh.scopes.includes("acp")) {
+            throw new Error("The authorization server returned credentials outside the registered web grant.");
+        }
+        return { access: result.access_token, refresh: /** @type {string} */ (result.refresh_token), claims: refresh, refreshing: null };
+    }
+
+    #prune() {
+        for (const [family, grant] of this.#grants) {
+            if (grant.refreshing === null && this.#credentials.verify(grant.refresh) === null) this.#grants.delete(family);
+        }
+    }
+
+    /** @param {Grant} grant */
+    async #refresh(grant) {
+        const { server, options } = await this.#metadata();
+        let result;
+        try {
+            const response = await oauth.refreshTokenGrantRequest(server, this.#client, this.#authenticate, grant.refresh, options);
+            result = await oauth.processRefreshTokenResponse(server, this.#client, response);
+        } catch (cause) {
+            if (cause instanceof oauth.ResponseBodyError && cause.error === "invalid_grant") {
+                this.#credentials.revokeFamily(grant.claims.family);
+                throw new RequestError(401, "Sign in again to connect.", { cause });
+            }
+            throw new RequestError(502, "The daemon could not refresh the connection credential.", { cause });
+        }
+        // Logout or a later callback must not be undone by an in-flight refresh.
+        if (this.#grants.get(grant.claims.family) !== grant) throw new RequestError(401, "Sign in again to connect.");
+        const next = this.#grant(result);
+        if (next.claims.family !== grant.claims.family || next.claims.subject !== grant.claims.subject) {
+            throw new Error("The authorization server changed the web grant during refresh.");
+        }
+        grant.access = next.access;
+        grant.refresh = next.refresh;
+        grant.claims = next.claims;
+    }
+
+    /** {§web-access-token} Share one standard refresh across concurrent tabs; authority owns validity.
+     * @param {SessionRequest} req @param {SessionResponse} res
+     */
+    async token(req, res) {
+        const claims = this.#claims(req);
+        if (claims === null) throw new RequestError(401, "Sign in again to connect.");
+        if (req.headers.origin !== this.#issuer(req)) throw new RequestError(403, "Same-origin request required.");
+        this.#prune();
+        const grant = this.#grants.get(claims.family);
+        if (grant === undefined) throw new RequestError(401, "Sign in again to connect.");
+        if (this.#credentials.verify(grant.access) === null) {
+            grant.refreshing ??= this.#refresh(grant).finally(() => { grant.refreshing = null; });
+            await grant.refreshing;
+        }
+        const access = this.#credentials.verify(grant.access);
+        if (this.#claims(req) === null || this.#grants.get(claims.family) !== grant || access === null) {
+            throw new RequestError(401, "Sign in again to connect.");
+        }
+        const body = Buffer.from(JSON.stringify({ access_token: grant.access, token_type: "Bearer",
+            expires_in: Math.max(0, Math.floor((access.expiresAt - Date.now()) / 1000)) }));
+        res.writeHead(200, { ...privateHeaders, "content-type": "application/json", "content-length": body.byteLength });
+        res.end(body);
+    }
+
+    /** @param {SessionRequest} req @param {SessionResponse} res */
+    logout(req, res) {
+        this.sameOriginForm(req);
+        const claims = this.#claims(req);
+        if (claims !== null) this.#credentials.revokeFamily(claims.family);
+        res.setHeader("set-cookie", this.#cookie(req, this.#session(req), "", "/", 0));
+        redirect(res, "/");
+    }
+
+    close() { this.#grants.clear(); this.#unsubscribe(); }
+}