toolroll 0.9.89 → 0.9.90

package/dist/server/mutation-key.d.ts

@@ -0,0 +1,70 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Session, Who } from "./session.js";
+/** The request header a fetch carries the key in. */
+export declare const KEY_HEADER = "x-toolroll-key";
+/** The form field a server-rendered form carries it in (not `key`: forms already use that for idempotency and API keys). */
+export declare const KEY_FIELD = "toolroll-key";
+/** A terminal socket offers `toolroll` (the protocol the server selects) and `toolroll.key.<key>` (never echoed back). */
+export declare const KEY_PROTOCOL = "toolroll";
+export declare const KEY_PROTOCOL_PREFIX = "toolroll.key.";
+/** Where the browser keeps it: `{ epoch, key }` in the console origin's localStorage. */
+export declare const KEY_STORAGE = "toolroll.key";
+/** How a person gets a fresh key: their password again (a full session), or the terminal (a local owner). */
+export type Reconnect = {
+    kind: "password";
+    href: string;
+} | {
+    kind: "command";
+    command: string;
+};
+export type KeyRefusal = {
+    status: 403 | 409;
+    message: string;
+    reconnect: Reconnect;
+};
+export declare const RESTARTED = "Toolroll restarted \u2014 reconnect to make changes.";
+export declare const RESTARTED_LOCAL = "Toolroll restarted \u2014 run `toolroll open` to reconnect.";
+export declare const NOT_CONNECTED = "This tab isn't connected to Toolroll \u2014 reconnect to make changes.";
+export declare const NOT_CONNECTED_LOCAL = "This tab isn't connected to Toolroll \u2014 run `toolroll open` to reconnect.";
+/** The page a request reads, without the workspace read's own parameters: where a reconnect comes back to. */
+export declare function pagePathOf(url: URL): string;
+export declare const keyHashOf: (key: string) => string;
+/** The one key a request presents (header, form field or socket protocol), or null for none, a malformed one, or two
+ * different ones: two keys in one request is a smuggling attempt, never a preference. */
+export declare function presentedKey(request: IncomingMessage, body: {
+    getAll(name: string): string[];
+} | null): string | null;
+/** Constant-time: the presented key's hash against the session's. */
+export declare function keyMatches(presented: string, hash: string | null): boolean;
+export type BrowserKeys = {
+    /** Whether mutations need the key now (a protected loopback install, with the key turned on for this console). */
+    required(): boolean;
+    /** The console's one browser origin (http://127.0.0.1:<port>) while required, else null. */
+    canonicalHost(): string | null;
+    /** The one mutation check: null to proceed, else the refusal (with how to reconnect). Bearer callers pass. */
+    check(who: Who, request: IncomingMessage, body: {
+        getAll(name: string): string[];
+    } | null): KeyRefusal | null;
+    /** A browser session whose key is from an earlier console start (or none at all) while the key is required. */
+    stale(who: Who, back?: string): Reconnect | null;
+    /** Gives a session being made (or reconnected) a fresh key: its hash and this start's epoch go on the session, the key
+     * comes back to deliver once. Null while not required, or off the canonical origin (that origin's storage would hold it). */
+    issue(session: Pick<Session, "keyEpoch" | "keyHash">, request: IncomingMessage): string | null;
+    /** The no-store page that puts the key in this origin's storage and moves on to `to` (a same-site path). */
+    deliver(response: ServerResponse, key: string, to: string, cookies?: readonly string[]): void;
+};
+export declare function createBrowserKeys(deps: {
+    /** The console turned the key on (a real console start; tests and the demo leave it off unless they ask). */
+    enabled: boolean;
+    epoch: string;
+    /** On a protected loopback install (bound to loopback only, no --allow-host, no public URL, no tailnet names), read
+     * per request: the console's one browser host (`127.0.0.1:<port>`, or `[::1]:<port>` for an IPv6-only bind). Else null. */
+    protectedHost: () => string | null;
+}): BrowserKeys;
+/**
+ * Every page that can post, while the key is required: fills the key into each same-origin POST form's data (the
+ * `formdata` event fires for a native submit, requestSubmit(), submit() and `new FormData(form)` alike) and offers
+ * `window.soKeyHeaders(headers)` to the page's own fetches. It reads nothing on the page and sends the key nowhere but
+ * this origin. Without a stored key it does nothing, and the server answers "reconnect".
+ */
+export declare const KEY_FILL_SCRIPT: string;

package/dist/server/mutation-key.js

@@ -0,0 +1,142 @@
+/**
+ * The browser mutation key (easy-start C2, amendment A1): the second factor every browser mutation carries on a
+ * protected loopback install, beside the session's CSRF token.
+ *
+ * Why: cookies are not isolated by port (RFC 6265 §8.5). Any server on another port of this computer receives the
+ * session cookie and can read every page, CSRF token included. So on a console that only this computer can reach, a
+ * mutation also needs a key that lives only in the browser's storage for the console's own origin
+ * (http://127.0.0.1:<port>): 32 random bytes per session, of which the server keeps only a hash and the console start
+ * (key epoch) it was issued under. The key is delivered once, in a response that cannot be fetched again (a one-time
+ * link, a password sign-in, an identity-provider finish, a password reconnect), by a no-store page whose one nonce'd
+ * script writes it to localStorage and moves on. It is never rendered into a page or JSON.
+ *
+ * The key is bound to the console start (N3): a process that held the port while Toolroll was stopped could read the
+ * saved key, so every restart mints a new epoch and every older key reads as "Toolroll restarted — reconnect".
+ *
+ * A protected loopback install: the console is bound to a loopback address only, with no --allow-host, no public URL
+ * and no tailnet names. Everywhere else nothing here applies.
+ */
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { html, htmlString, scriptElement } from "../html.js";
+import { HANDOFF_STYLE } from "./http.js";
+/** The request header a fetch carries the key in. */
+export const KEY_HEADER = "x-toolroll-key";
+/** The form field a server-rendered form carries it in (not `key`: forms already use that for idempotency and API keys). */
+export const KEY_FIELD = "toolroll-key";
+/** A terminal socket offers `toolroll` (the protocol the server selects) and `toolroll.key.<key>` (never echoed back). */
+export const KEY_PROTOCOL = "toolroll";
+export const KEY_PROTOCOL_PREFIX = "toolroll.key.";
+/** Where the browser keeps it: `{ epoch, key }` in the console origin's localStorage. */
+export const KEY_STORAGE = "toolroll.key";
+const KEY_SHAPE = /^[0-9a-f]{64}$/;
+export const RESTARTED = "Toolroll restarted — reconnect to make changes.";
+export const RESTARTED_LOCAL = "Toolroll restarted — run `toolroll open` to reconnect.";
+export const NOT_CONNECTED = "This tab isn't connected to Toolroll — reconnect to make changes.";
+export const NOT_CONNECTED_LOCAL = "This tab isn't connected to Toolroll — run `toolroll open` to reconnect.";
+/** The page a request reads, without the workspace read's own parameters: where a reconnect comes back to. */
+export function pagePathOf(url) {
+    const page = new URL(url.pathname + url.search, "http://standing-orders.local");
+    page.searchParams.delete("format");
+    page.searchParams.delete("request");
+    return page.pathname + page.search;
+}
+export const keyHashOf = (key) => createHash("sha256").update(key, "utf8").digest("hex");
+/** The one key a request presents (header, form field or socket protocol), or null for none, a malformed one, or two
+ * different ones: two keys in one request is a smuggling attempt, never a preference. */
+export function presentedKey(request, body) {
+    const found = [];
+    const header = request.headers[KEY_HEADER];
+    if (Array.isArray(header))
+        return null;
+    if (typeof header === "string" && header !== "")
+        found.push(header);
+    if (body !== null)
+        found.push(...body.getAll(KEY_FIELD).filter(one => one !== ""));
+    const protocols = request.headers["sec-websocket-protocol"];
+    if (typeof protocols === "string") {
+        for (const one of protocols.split(",").map(part => part.trim()))
+            if (one.startsWith(KEY_PROTOCOL_PREFIX))
+                found.push(one.slice(KEY_PROTOCOL_PREFIX.length));
+    }
+    // The same key by two roads (a form's field and its fetch's header) is one key; two different keys is none.
+    const distinct = [...new Set(found)];
+    if (distinct.length !== 1)
+        return null;
+    const key = distinct[0];
+    return KEY_SHAPE.test(key) ? key : null;
+}
+/** Constant-time: the presented key's hash against the session's. */
+export function keyMatches(presented, hash) {
+    if (hash === null || !KEY_SHAPE.test(hash))
+        return false;
+    const a = Buffer.from(keyHashOf(presented), "hex"), b = Buffer.from(hash, "hex");
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+export function createBrowserKeys(deps) {
+    const canonicalHost = () => deps.enabled ? deps.protectedHost() : null;
+    const required = () => canonicalHost() !== null;
+    // A refused post comes back to Home (its own address may answer only posts); a page's notice, to that page.
+    const reconnectOf = (who, back = "/") => who.authority === "full"
+        ? { kind: "password", href: back === "/" ? "/login/rekey" : `/login/rekey?return=${encodeURIComponent(back)}` }
+        : { kind: "command", command: "toolroll open" };
+    const stale = (who, back) => {
+        if (!required() || who.via !== "cookie")
+            return null;
+        const session = who.session;
+        return session.keyEpoch !== deps.epoch || session.keyHash === null ? reconnectOf(who, back) : null;
+    };
+    return {
+        required,
+        canonicalHost,
+        check(who, request, body) {
+            if (!required() || who.via !== "cookie")
+                return null;
+            const local = who.authority !== "full";
+            const reconnect = reconnectOf(who);
+            if (stale(who) !== null)
+                return { status: 409, message: local ? RESTARTED_LOCAL : RESTARTED, reconnect };
+            const presented = presentedKey(request, body);
+            if (presented === null || !keyMatches(presented, who.session.keyHash))
+                return { status: 403, message: local ? NOT_CONNECTED_LOCAL : NOT_CONNECTED, reconnect };
+            return null;
+        },
+        stale,
+        issue(session, request) {
+            const canonical = canonicalHost();
+            if (canonical === null || request.headers.host !== canonical)
+                return null;
+            const key = randomBytes(32).toString("hex");
+            session.keyHash = keyHashOf(key);
+            session.keyEpoch = deps.epoch;
+            return key;
+        },
+        deliver(response, key, to, cookies = []) {
+            const nonce = randomBytes(16).toString("base64");
+            const target = /^\/(?![/\\])/.test(to) ? to : "/";
+            // JSON inside a script: `<` escaped so nothing in it can close the element.
+            const data = JSON.stringify({ storage: KEY_STORAGE, value: JSON.stringify({ epoch: deps.epoch, key }), to: target }).replace(/</g, "\\u003c");
+            response.writeHead(200, {
+                "content-type": "text/html; charset=utf-8", "cache-control": "no-store", pragma: "no-cache", "referrer-policy": "no-referrer",
+                "x-content-type-options": "nosniff", "x-frame-options": "DENY",
+                "content-security-policy": `default-src 'none'; script-src 'nonce-${nonce}'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'`,
+                ...(cookies.length === 0 ? {} : { "set-cookie": [...cookies] }),
+            });
+            const script = `(function(){var d=${data};try{localStorage.setItem(d.storage,d.value)}catch(e){}location.replace(d.to)})();`;
+            response.end(htmlString(html `<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Toolroll</title>${HANDOFF_STYLE}<p>Opening Toolroll… <a href="${target}">Continue</a></p>${scriptElement(script, { nonce })}</html>`));
+        },
+    };
+}
+/**
+ * Every page that can post, while the key is required: fills the key into each same-origin POST form's data (the
+ * `formdata` event fires for a native submit, requestSubmit(), submit() and `new FormData(form)` alike) and offers
+ * `window.soKeyHeaders(headers)` to the page's own fetches. It reads nothing on the page and sends the key nowhere but
+ * this origin. Without a stored key it does nothing, and the server answers "reconnect".
+ */
+export const KEY_FILL_SCRIPT = `(function(){if(window.soKeyHeaders)return;` +
+    `function k(){try{var v=JSON.parse(localStorage.getItem(${JSON.stringify(KEY_STORAGE)})||"null");return v&&typeof v.key==="string"&&/^[0-9a-f]{64}$/.test(v.key)?v.key:null}catch(e){return null}}` +
+    `window.soKeyHeaders=function(h){h=h||{};var x=k();if(x)h[${JSON.stringify(KEY_HEADER)}]=x;return h};` +
+    // The form's own method and action through HTMLFormElement's getters: a control named "method" or "action" (the
+    // skill form's <select name="method">) shadows f.method / f.action, which would skip the key or misread the target.
+    `var P=HTMLFormElement.prototype,G=function(n){return Object.getOwnPropertyDescriptor(P,n).get};var M=G("method"),A=G("action");` +
+    `document.addEventListener("formdata",function(e){var f=e.target,m,a;try{m=M.call(f);a=A.call(f)}catch(x){return}if(String(m).toLowerCase()!=="post")return;` +
+    `try{if(new URL(a,location.href).origin!==location.origin)return}catch(x){return}var x=k();if(x)e.formData.set(${JSON.stringify(KEY_FIELD)},x)},true);})();`;

package/dist/server/pages.js

@@ -29,7 +29,6 @@ import { LEDGER_CSV_HEADER, ledgerCsvRows } from "../ledger-csv.js";
 import { ledgerBody } from "../ledger-view.js";
 import { agentRowOf, agentsListOf, agentFactsFor, sealedDiffOf } from "../agents-board.js";
 import { computersOf, phasesOf, systemOf } from "./agents-computers.js";
-import { markAgentSeen } from "../agent-board.js";
 import { agentsLiveOf } from "../agents-live.js";
 import { readChildWindow } from "../live-children-read.js";
 import { leadFiledLinks } from "./agents-live-filed.js";
@@ -192,7 +191,9 @@ export function createPagesHandlers(runtime) {
         // One scope for the page and the chrome around it: the project its address names (proved by the router), else all.
         const chrome = chromeFor(project, "none");
         const projects = chrome.projects ?? [];
-        const view = homeView({ store, now, access: workAccess(), evidenceRoot, project, projects, chat: chrome.chat === true, canAnswer: who.role === "approver" });
+        const view = { ...homeView({ store, now, access: workAccess(), evidenceRoot, project, projects, chat: chrome.chat === true, canAnswer: who.role === "approver" }),
+            // Until the first result: the welcome's three steps stay one link away.
+            setup: firstRunStepsNow(now) !== null ? "/welcome" : null };
         return sendScreen(response, 200, screen("Home", html `<div data-kit-page><h1>Home</h1><p>${view.say}</p><p><a href="/work">Tasks</a></p></div>`, { chrome, workspace: { view } }));
     }
     // Search (UI revamp wave B): the ⌘K menu's "See all results". The places come from the page; the tasks here are the
@@ -450,9 +451,8 @@ export function createPagesHandlers(runtime) {
             const run = store.getRun(Number(asked));
             const facts = run === null || !runVisible(run) ? null : agentFactsFor(store, run.id, access, who.name);
             if (facts !== null) {
-                // Opening a finished agent is viewing it: it leaves this person's unread Done.
-                if (facts.outcome !== null && markAgentSeen(store, who.name, facts.runId, now))
-                    facts.seen = true;
+                // Opening a finished agent is viewing it: the shell says so with a keyed POST /agents/seen (easy-start N1: a page
+                // load never writes), which leaves this person's unread Done.
                 const live = facts.outcome === null;
                 const composer = live ? steerControlsFor(store, facts.taskId, facts.runId, now, who.role === "approver") : null;
                 const sealed = live ? null : sealedDiffOf(store, evidenceRoot, facts.runId);
@@ -843,7 +843,10 @@ export function createPagesHandlers(runtime) {
             return projectsScreen(response, who, "naming where repositories live takes --project-root", 400, "/", "clone");
         // CONFIRM: password, then session liveness AGAIN via lookupSession
         // (finding 22/33) — the record is consumed from the RETURNED live
-        // session, synchronously, before the first await.
+        // session, synchronously, before the first await. A full session types
+        // its password (or Passwordless stands in); a laptop's local owner has
+        // none: inside this row's add-project admission the prover's local-owner
+        // branch proves it (scope.ts proveAccountNow), whatever the field holds.
         const password = body.get("token") ?? "";
         if (!authenticateApprover(who, password).ok) {
             return projectsScreen(response, who, "cloning takes your password, typed again", 403, "/", "clone");
@@ -953,7 +956,7 @@ export function createPagesHandlers(runtime) {
                                 ? "Choose a projects folder once: toolroll up --project-root <dir>"
                                 : "choose which folder this server may use with --project-root <dir>",
                         }
-                        : { enabled: true, roots: ceiling.roots, record: [...(who.session.onboard?.entries() ?? [])][0] ?? null };
+                        : { enabled: true, roots: ceiling.roots, localOwner: who.authority !== "full", record: [...(who.session.onboard?.entries() ?? [])][0] ?? null };
         const peeks = {};
         for (const one of recent)
             peeks[one.path] = peekOf(one.path, now);

package/dist/server/people-tokens.js

@@ -3,7 +3,7 @@ import { adapterPolicy } from "./route-policy.js";
 /** settings handlers, moved without changing their route bodies. */
 import { mintApiToken, TOKEN_DAYS } from "../api-tokens.js";
 import { CONSOLE_FORMS, readForm } from "../contracts/console-api.js";
-import { html, htmlString, joinHtml, postForm, reauth } from "../html.js";
+import { html, htmlString, joinHtml, postForm, reauth, replaceMarkup, scriptElement } from "../html.js";
 import { credentialsHtml, tokenShownHtml } from "../credentials-ui.js";
 import { projectName } from "../project.js";
 import { requestLimitsHtml, tokenLimitWords } from "../request-budget-ui.js";
@@ -22,10 +22,13 @@ import { accessFromGroups, accountNameFor, exchangeOidcCode, newOidcVisit, oidcA
 import { personAuditHtml, personHref } from "../people-audit-ui.js";
 import { cursorOf as auditCursorOf, remoteAudit } from "../remote-audit.js";
 import { credentialProof, hashPassword, proveAccountNow } from "../scope.js";
-import { form, HANDOFF_STYLE, loginHref, loginReturn, page, SIGN_IN_COOKIE, signInSpent, startedHere } from "./http.js";
-import { joinDeadPage, joinFormPage, loginPage, SIGNUP_NAME, SIGNUP_PASSWORD_MIN, signupPage } from "./render-people.js";
-import { liveInviteTerms } from "../store.js";
-import { SESSION_COOKIE, SIGN_IN_LINK_PATH } from "./session.js";
+import { form, HANDOFF_STYLE, loginHref, loginReturn, page, passwordSetNext, SIGN_IN_COOKIE, signInSpent, startedHere } from "./http.js";
+import { joinDeadPage, joinFormPage, loginPage, passwordAlreadySetPage, passwordSetPage, reconnectPage, SIGNUP_NAME, SIGNUP_PASSWORD_MIN, signupPage } from "./render-people.js";
+import { enrollOwnerPassword, liveInviteTerms, localOwnerBinding } from "../store.js";
+import { KEY_FILL_SCRIPT } from "./mutation-key.js";
+import { LOCAL_OWNER_LAPSED } from "../local-owner.js";
+import { withFormToken } from "./request-context.js";
+import { FULL_SESSION, SESSION_COOKIE, SIGN_IN_LINK_PATH } from "./session.js";
 import { setupCodeMatches, signupCookie, signupFromHere } from "./signup-gate.js";
 /** Clock skew allowed between the provider and this server when reading auth_time — forward only (a provider clock
  * running ahead). auth_time is in whole seconds, so a check made in the visit's own second is floored below startedAt:
@@ -42,7 +45,7 @@ export function sameVisitCheck(authTime, startedAt, now) {
     return Math.min(Math.max(at, startedAt), now);
 }
 export function createPeopleHandlers(runtime) {
-    const { joinBySource, ssoOffer, ssoVisits, ssoSettings, options, clock, ssoHandoffs, managedRepos, store, visible, admissionList, sendScreen, chromeFor, restricted, sessions, consoleProjects, authenticateApprover, authenticateCredential, bustBadge, projectOf, signInLinks, linkKey, fromThisComputer, recordSignIn, passwordAllowed, arrival, cookieSecure, consoleOrigin, providerFor, providerKnown, joinSourceOf, signInBudget, signInActor, minutesWords } = runtime;
+    const { joinBySource, ssoOffer, ssoVisits, ssoSettings, options, clock, ssoHandoffs, managedRepos, store, visible, admissionList, sendScreen, chromeFor, restricted, sessions, consoleProjects, authenticateApprover, authenticateCredential, bustBadge, projectOf, signInLinks, linkKey, fromThisComputer, recordSignIn, passwordAllowed, arrival, cookieSecure, consoleOrigin, providerFor, providerKnown, joinSourceOf, signInBudget, signInActor, minutesWords, browserKeys } = runtime;
     // v101: Settings → Sessions & tokens: where you're signed in, and your API tokens. An instance operator can see everyone's.
     async function sessionsPage(ctx) {
         const { url, who, response, project } = ctx;
@@ -279,11 +282,29 @@ export function createPeopleHandlers(runtime) {
         if (!passwordAllowed(held.account))
             return page(response, 403, loginPage(`Sign in with ${ssoSettings()?.label ?? "your identity provider"}.`, "/chat", ssoOffer()));
         const id = randomBytes(32).toString("hex");
-        sessions.set(id, { ...arrival(request), name: held.account, csrf: randomBytes(32).toString("hex"), role: account.role, generation: account.generation, createdAt: Date.now(), sawBoardAt: null, lastSeen: Date.now(),
-            project: runtime.defaultProject, projectRevision: 1 });
-        recordSignIn(held.account, "signed in", "one-time link");
-        response.setHeader("Set-Cookie", `${SESSION_COOKIE}=${id}; HttpOnly; SameSite=Strict; Path=/${cookieSecure}`);
-        return redirect(response, "/chat");
+        const keyed = keyFor(request);
+        const base = { ...arrival(request), name: held.account, csrf: randomBytes(32).toString("hex"), role: account.role, generation: account.generation, createdAt: Date.now(), sawBoardAt: null, lastSeen: Date.now(),
+            project: runtime.defaultProject, projectRevision: 1 };
+        if (held.kind === "local-owner") {
+            // Easy-start C4: a local owner's link becomes only a local-owner session, and only if local mode, read again in
+            // the same transaction as the session is saved, is still on at the link's generation for the same owner, and the
+            // owner's account generation hasn't moved (a password set since ended this road).
+            const made = store.transact(() => {
+                const now = localOwnerBinding(store);
+                if (now === null || now.account !== held.account || now.localGeneration !== held.localGeneration || now.accountGeneration !== held.accountGeneration)
+                    return false;
+                sessions.set(id, { ...base, generation: now.accountGeneration, authority: "local-owner", localGeneration: now.localGeneration, ...keyed.fields });
+                return true;
+            });
+            if (!made)
+                return page(response, 410, loginPage("That sign-in link no longer works. Run toolroll again to open Toolroll.", "/chat", ssoOffer()));
+            recordSignIn(held.account, "signed in", "local link");
+        }
+        else {
+            sessions.set(id, { ...base, ...FULL_SESSION, ...keyed.fields });
+            recordSignIn(held.account, "signed in", "one-time link");
+        }
+        return signedInTo(response, keyed.key, "/chat", [`${SESSION_COOKIE}=${id}; HttpOnly; SameSite=Strict; Path=/${cookieSecure}`]);
     }
     // v100: sign-in with the identity provider. ?reauth=1 asks it to check the person again (a step-up);
     // ?link=1 links the signed-in account to it. The browser that starts it holds the visit's state.
@@ -374,11 +395,11 @@ export function createPeopleHandlers(runtime) {
         }
         const account = store.accountOf(signedIn.account);
         const id = randomBytes(32).toString("hex");
-        sessions.set(id, { ...arrival(request), name: signedIn.account, csrf: randomBytes(32).toString("hex"), role: account.role, generation: account.generation, createdAt: Date.now(), sawBoardAt: null, lastSeen: Date.now(),
+        const keyed = keyFor(request);
+        sessions.set(id, { ...arrival(request), ...FULL_SESSION, ...keyed.fields, name: signedIn.account, csrf: randomBytes(32).toString("hex"), role: account.role, generation: account.generation, createdAt: Date.now(), sawBoardAt: null, lastSeen: Date.now(),
             project: runtime.defaultProject, projectRevision: 1, sso: { at: handoff.checkedAt ?? 0 } });
         recordSignIn(signedIn.account, "signed in", settings.label);
-        response.setHeader("Set-Cookie", [signInSpent("/login/sso/finish"), `${SESSION_COOKIE}=${id}; HttpOnly; SameSite=Strict; Path=/${cookieSecure}`]);
-        return redirect(response, handoff.returnTo);
+        return signedInTo(response, keyed.key, handoff.returnTo, [signInSpent("/login/sso/finish"), `${SESSION_COOKIE}=${id}; HttpOnly; SameSite=Strict; Path=/${cookieSecure}`]);
     }
     async function signupSend(ctx) {
         const { request, response } = ctx;
@@ -428,8 +449,11 @@ export function createPeopleHandlers(runtime) {
         if (authenticated === null || !authenticated.ok)
             return page(response, 500, loginPage("The account was created, but signing in failed. Sign in with it now."));
         const id = randomBytes(32).toString("hex");
+        const keyed = keyFor(request);
         sessions.set(id, {
             ...arrival(request),
+            ...FULL_SESSION,
+            ...keyed.fields,
             name,
             csrf: randomBytes(32).toString("hex"),
             role: authenticated.role,
@@ -442,8 +466,7 @@ export function createPeopleHandlers(runtime) {
             // A password typed on this computer starts this session's freshness window (cockpit B2); from anywhere else, never.
             ...(fromThisComputer(request) ? { passwordAt: Date.now() } : {}),
         });
-        response.setHeader("Set-Cookie", `${SESSION_COOKIE}=${id}; HttpOnly; SameSite=Strict; Path=/${cookieSecure}`);
-        return redirect(response, "/");
+        return signedInTo(response, keyed.key, "/", [`${SESSION_COOKIE}=${id}; HttpOnly; SameSite=Strict; Path=/${cookieSecure}`]);
     }
     async function loginSend(ctx) {
         const { request, response } = ctx;
@@ -479,8 +502,11 @@ export function createPeopleHandlers(runtime) {
         }
         recordSignIn(name, "signed in", "browser");
         const id = randomBytes(32).toString("hex");
+        const keyed = keyFor(request);
         sessions.set(id, {
             ...arrival(request),
+            ...FULL_SESSION,
+            ...keyed.fields,
             name: name,
             csrf: randomBytes(32).toString("hex"),
             role: authenticated.role,
@@ -494,8 +520,7 @@ export function createPeopleHandlers(runtime) {
             // else (a phone, a proxy) it signs in and proves nothing more.
             ...(fromThisComputer(request) ? { passwordAt: Date.now() } : {}),
         });
-        response.setHeader("Set-Cookie", `${SESSION_COOKIE}=${id}; HttpOnly; SameSite=Strict; Path=/${cookieSecure}`);
-        return redirect(response, returnTo);
+        return signedInTo(response, keyed.key, returnTo, [`${SESSION_COOKIE}=${id}; HttpOnly; SameSite=Strict; Path=/${cookieSecure}`]);
     }
     async function logout(ctx) {
         const { request, response } = ctx;
@@ -567,8 +592,11 @@ export function createPeopleHandlers(runtime) {
         }
         // The cookie mints only AFTER the commit — same shape as login.
         const id = randomBytes(32).toString("hex");
+        const keyed = keyFor(request);
         sessions.set(id, {
             ...arrival(request),
+            ...FULL_SESSION,
+            ...keyed.fields,
             name,
             csrf: randomBytes(32).toString("hex"),
             role: made.role,
@@ -579,8 +607,7 @@ export function createPeopleHandlers(runtime) {
             project: runtime.defaultProject,
             projectRevision: 1,
         });
-        response.setHeader("Set-Cookie", `${SESSION_COOKIE}=${id}; HttpOnly; SameSite=Strict; Path=/${cookieSecure}`);
-        return redirect(response, "/");
+        return signedInTo(response, keyed.key, "/", [`${SESSION_COOKIE}=${id}; HttpOnly; SameSite=Strict; Path=/${cookieSecure}`]);
     }
     /** The invite code in /join/:code (the route's pattern has already proven its shape). */
     function joinCodeOf(url) {
@@ -674,6 +701,195 @@ export function createPeopleHandlers(runtime) {
             return { ok: false, message: "Choose projects available on this instance." };
         return { ok: true, projects };
     }
+    /** Easy-start C2: a session's key fields when it is made: on a protected loopback install, a fresh key (only its hash
+     * and this start's epoch kept) to deliver once; else none. */
+    function keyFor(request) {
+        const fields = { keyEpoch: null, keyHash: null };
+        const key = browserKeys.issue(fields, request);
+        return { fields, key };
+    }
+    /** A sign-in's answer: its cookies, then on to `to` — through the key's one delivery when there is a key. */
+    function signedInTo(response, key, to, cookies) {
+        if (key !== null)
+            return browserKeys.deliver(response, key, to, cookies);
+        response.setHeader("Set-Cookie", cookies.length === 1 ? cookies[0] : [...cookies]);
+        return redirect(response, to);
+    }
+    // Easy-start C2: Reconnect. A browser session keeps reading after a restart, but its mutation key was bound to the
+    // console start that issued it. A full session gets a fresh key here by typing its password again (a cookie alone
+    // never does: a cookie holder on another port has the cookie); a local owner, by running `toolroll open`.
+    async function rekeyPage(ctx) {
+        const { url, who, response } = ctx;
+        const returnTo = loginReturn(url.searchParams.get("return"));
+        if (who?.via !== "cookie")
+            return redirect(response, loginHref(returnTo));
+        if (!browserKeys.required())
+            return redirect(response, returnTo);
+        return page(response, 200, reconnectPage(null, returnTo, howToReconnect(who)));
+    }
+    function howToReconnect(who) {
+        if (who.authority !== "full")
+            return { kind: "command" };
+        if (!passwordAllowed(who.name))
+            return { kind: "sso", label: ssoSettings()?.label ?? "your identity provider" };
+        return { kind: "password", name: who.name };
+    }
+    async function rekeySend(ctx) {
+        const { who, request, response } = ctx;
+        const body = readForm(await form(request), CONSOLE_FORMS.rekey);
+        const returnTo = loginReturn(body.get("return"));
+        if (who?.via !== "cookie")
+            return redirect(response, loginHref(returnTo));
+        if (!browserKeys.required())
+            return redirect(response, returnTo);
+        // Only this console's own page: a present Origin must name it (the password below is the proof either way).
+        const origin = request.headers.origin;
+        if (typeof origin === "string" && origin !== "null" && origin !== `http://${browserKeys.canonicalHost()}`) {
+            return page(response, 403, reconnectPage("Reconnect from Toolroll's own page.", returnTo, howToReconnect(who)));
+        }
+        const how = howToReconnect(who);
+        if (how.kind !== "password")
+            return page(response, 403, reconnectPage(null, returnTo, how));
+        const source = joinSourceOf(request), at = Date.now();
+        const wait = signInBudget.waitFor(source, at);
+        if (wait > 0) {
+            recordSignIn(who.name, "sign-in refused", "too many tries", "reconnect");
+            response.setHeader("Retry-After", String(Math.ceil(wait / 1000)));
+            return page(response, 429, reconnectPage(`Too many tries. Try again in ${minutesWords(wait)}.`, returnTo, how));
+        }
+        // Only a password typed now: never a session, Passwordless or a remembered password (an empty one simply fails).
+        const proved = authenticateAccount(store, who.name, body.get("token") ?? "");
+        if (!proved.ok) {
+            if (proved.reason === "locked") {
+                recordSignIn(who.name, "sign-in refused", "locked", "reconnect");
+                response.setHeader("Retry-After", String(Math.ceil(proved.retryAfterMs / 1000)));
+                return page(response, 429, reconnectPage(`Too many wrong passwords. Try again in ${minutesWords(proved.retryAfterMs)}.`, returnTo, how));
+            }
+            signInBudget.failed(source, at);
+            recordSignIn(who.name, "sign-in refused", "wrong password", "reconnect");
+            return page(response, 403, reconnectPage("That password isn't right.", returnTo, how));
+        }
+        // The same person under the same credential generation and standing this session signed in with; anything else
+        // signs in again instead.
+        if (proved.generation !== who.session.generation || proved.role !== who.session.role)
+            return redirect(response, loginHref(returnTo));
+        const key = browserKeys.issue(who.session, request);
+        if (key === null)
+            return page(response, 421, reconnectPage(`Open Toolroll at http://${browserKeys.canonicalHost()} to reconnect.`, returnTo, how));
+        sessions.persist(who.session);
+        recordSignIn(who.name, "reconnected", "browser");
+        return browserKeys.deliver(response, key, returnTo);
+    }
+    // Easy-start C4: /password/set, the one credential act a local owner's session may make: its first password, only
+    // while the account has none. The answer is a fresh full session (and a fresh browser key), and on to the act that
+    // was refused. Every other session, and an account that has a password, is told to sign in with it.
+    /** A /password/set page: no-store, and on a protected loopback install the key fill rides it (its form posts the key). */
+    function passwordSetAnswer(response, status, document) {
+        response.setHeader("Cache-Control", "no-store");
+        if (!browserKeys.required())
+            return page(response, status, document);
+        const nonce = randomBytes(16).toString("base64");
+        return page(response, status, replaceMarkup(document, /<\/body><\/html>$/, () => html `${scriptElement(KEY_FILL_SCRIPT, { nonce })}</body></html>`), nonce);
+    }
+    async function passwordSetForm(ctx) {
+        const { url, who, response } = ctx;
+        // Where to go once it is set: `next` (a refusal's link), or `return` (older links), checked either way.
+        const returnTo = passwordSetNext(url.searchParams.get("next") ?? url.searchParams.get("return"));
+        if (who === null || who === undefined)
+            return redirect(response, loginHref(returnTo));
+        if (who.via !== "cookie")
+            return respond(response, 403, "text/plain; charset=utf-8", "This address needs a browser sign-in.");
+        if (who.authority === "full" || store.accountOf(who.name)?.passwordSet !== false)
+            return passwordSetAnswer(response, 200, passwordAlreadySetPage("A password is already set", returnTo, who.authority === "full"));
+        return passwordSetAnswer(response, 200, withFormToken(who.session.csrf, () => passwordSetPage({ returnTo, problem: null })));
+    }
+    async function passwordSetSend(ctx) {
+        const { who, request, response } = ctx;
+        const media = String(request.headers["content-type"] ?? "").split(";")[0]?.trim().toLowerCase();
+        if (media !== "application/x-www-form-urlencoded") {
+            request.resume();
+            return respond(response, 415, "text/plain; charset=utf-8", "forms only");
+        }
+        const body = readForm(await form(request), CONSOLE_FORMS.passwordSet);
+        const returnTo = passwordSetNext(body.get("next") ?? body.get("return"));
+        if (who === null || who === undefined)
+            return redirect(response, loginHref(returnTo));
+        if (who.via !== "cookie")
+            return respond(response, 403, "text/plain; charset=utf-8", "This address needs a browser sign-in.");
+        for (const field of ["csrf", "password", "again", "next", "return"]) {
+            if (body.getAll(field).length > 1)
+                return respond(response, 400, "text/plain; charset=utf-8", `duplicated ${field} field`);
+        }
+        const account = store.accountOf(who.name);
+        // A full session, or an account that has a password: only signing in with it.
+        if (who.authority === "full" || account === null || account.passwordSet)
+            return passwordSetAnswer(response, 409, passwordAlreadySetPage("A password is already set", returnTo, who.authority === "full"));
+        const again = (problem, status) => passwordSetAnswer(response, status, withFormToken(who.session.csrf, () => passwordSetPage({ returnTo, problem })));
+        // The console's own page only: a present Origin (or Referer) must name it; the session's CSRF token and (on a protected
+        // loopback install) its browser key are proved as for every other mutation.
+        const origin = request.headers.origin, referer = request.headers.referer;
+        const named = typeof origin === "string" && origin !== "null" ? origin : typeof referer === "string" ? referer : null;
+        if (named !== null && !runtime.allowedHost(named.replace(/^https?:\/\//, "").split("/")[0]))
+            return again({ field: null, text: "Set your password from Toolroll's own page." }, 403);
+        if (body.get("csrf") !== who.session.csrf)
+            return again({ field: null, text: "This form had expired, so it was reloaded. Enter the password again." }, 403);
+        const keyed = browserKeys.check(who, request, body.sent);
+        if (keyed !== null)
+            return again({ field: null, text: keyed.message }, keyed.status);
+        if (account.revokedAt !== null || account.generation !== who.session.generation || !sessions.savedNow(who.session) || who.session.localGeneration === null) {
+            return again({ field: null, text: LOCAL_OWNER_LAPSED }, 409);
+        }
+        // Rate-limited like signing in: the same per-address budget, and each refused try spends from it.
+        const source = joinSourceOf(request), at = Date.now();
+        const wait = signInBudget.waitFor(source, at);
+        if (wait > 0) {
+            response.setHeader("Retry-After", String(Math.ceil(wait / 1000)));
+            return again({ field: null, text: `Too many tries. Try again in ${minutesWords(wait)}.` }, 429);
+        }
+        const password = body.get("password") ?? "";
+        // The strength rule sign-up and joining use.
+        if (password.length < SIGNUP_PASSWORD_MIN) {
+            signInBudget.failed(source, at);
+            return again({ field: "password", text: `Use at least ${SIGNUP_PASSWORD_MIN} characters.` }, 400);
+        }
+        if ((body.get("again") ?? "") !== password) {
+            signInBudget.failed(source, at);
+            return again({ field: "again", text: "The two passwords don't match. Type them again." }, 400);
+        }
+        // Hashed before the transaction (scrypt is slow); enrollOwnerPassword then checks and writes in one IMMEDIATE
+        // transaction: still no password, local mode on at this session's generation, the account its active owner. It ends
+        // every session the account had (this one included).
+        const enrolled = enrollOwnerPassword(store, who.name, hashPassword(password), who.session.localGeneration, clock());
+        if (!enrolled.ok) {
+            if (enrolled.reason === "already-set")
+                return passwordSetAnswer(response, 409, passwordAlreadySetPage("A password was just set", returnTo));
+            return again({ field: null, text: LOCAL_OWNER_LAPSED }, 409);
+        }
+        const cookieId = new RegExp(`(?:^|;\\s*)${SESSION_COOKIE}=([0-9a-f]{64})`).exec(request.headers.cookie ?? "")?.[1];
+        if (cookieId !== undefined)
+            sessions.delete(cookieId);
+        recordSignIn(who.name, "signed in", "browser", "first password set");
+        // A fresh full session, made only after the commit, with a fresh key delivered once (no-store) on a protected install.
+        const id = randomBytes(32).toString("hex");
+        const issued = keyFor(request);
+        sessions.set(id, {
+            ...arrival(request),
+            ...FULL_SESSION,
+            ...issued.fields,
+            name: who.name,
+            csrf: randomBytes(32).toString("hex"),
+            role: account.role,
+            generation: enrolled.generation,
+            createdAt: Date.now(),
+            sawBoardAt: null,
+            lastSeen: Date.now(),
+            project: who.session.project ?? runtime.defaultProject,
+            projectRevision: 1,
+            // A password typed on this computer starts this session's freshness window (cockpit B2), as signing in does.
+            ...(fromThisComputer(request) ? { passwordAt: Date.now() } : {}),
+        });
+        return signedInTo(response, issued.key, returnTo, [`${SESSION_COOKIE}=${id}; HttpOnly; SameSite=Strict; Path=/${cookieSecure}`]);
+    }
     const registrations = handlersOf("people", {
         "people.page": peoplePage,
         "settings.sessions": sessionsPage,
@@ -691,8 +907,12 @@ export function createPeopleHandlers(runtime) {
         "edge.signup": signupSend,
         "edge.login": loginSend,
         "edge.logout": logout,
+        "edge.rekey-page": rekeyPage,
+        "edge.rekey": rekeySend,
         "edge.join": joinPage,
         "edge.join-send": joinSend,
+        "edge.password-set-page": passwordSetForm,
+        "edge.password-set": passwordSetSend,
     });
     return { registrations, takeJoinAttempt, ssoCallback, readAccessForm };
 }

package/dist/server/remote.d.ts

@@ -51,6 +51,8 @@ export interface RemoteRuntime {
     teamsSourceBudget: SourceAdmission;
     teamsTenantBudget: SourceAdmission;
     freshFactsOf: (request: IncomingMessage, who: Who | null) => FreshFacts | null;
+    /** Easy-start C2: the browser mutation key (server/mutation-key.ts). */
+    browserKeys: import("./mutation-key.js").BrowserKeys;
 }
 export declare function createRemoteHandlers(runtime: RemoteRuntime): {
     registrations: import("./handler-registry.js").Registration[];