toolroll 0.9.104 → 0.9.105

package/dist/server/people-tokens.js

@@ -1,6 +1,5 @@
 import { handlersOf } from './handler-registry.js';
 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, replaceMarkup, scriptElement } from "../html.js";
@@ -12,7 +11,6 @@ import { SSO_CALLBACK } from "../sso-settings.js";
 import { personChip, refuse, screen } from "./chrome.js";
 import { inviteLinkHtml, ownAccessHtml, peopleHtml, settingsSubPage } from "../settings-groups-ui.js";
 import { redirect, respond, sayTo } from "./http.js";
-/** people handlers, moved without changing their route bodies. */
 import { randomBytes } from "node:crypto";
 import {} from "node:http";
 import {} from "../contracts/console-api.js";
@@ -30,12 +28,7 @@ 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:
- * the one allowance backward is that rounding, never a check made before the visit began. */
 const AUTH_TIME_SKEW_MS = 60_000;
-/** When the provider checked the person, in ms, if its auth_time is a check made for this visit: present, no earlier
- * than the second the visit began, and not in the future beyond the skew. Null otherwise. */
 export function sameVisitCheck(authTime, startedAt, now) {
     if (authTime === null || !Number.isFinite(authTime))
         return null;
@@ -46,7 +39,6 @@ export function sameVisitCheck(authTime, 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, 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;
         if (who.via !== "cookie")
@@ -60,8 +52,6 @@ export function createPeopleHandlers(runtime) {
     }
     async function peoplePage(ctx) {
         const { url, who, response, now, project } = ctx;
-        // People → a person: their API tokens and remote activity (people-audit-ui.ts). An approver may open anyone, within
-        // their projects; anyone else only themselves. Another person reads exactly like nobody.
         const person = url.searchParams.get("person");
         if (person !== null) {
             const token = (url.searchParams.get("token-name") ?? "").slice(0, 60) || null, before = url.searchParams.get("before");
@@ -75,8 +65,6 @@ export function createPeopleHandlers(runtime) {
                 return refuse(response, who, 404, "No such person.", "/people");
             return sendScreen(response, 200, screen("people", personAuditHtml({ name: person, tokens: store.apiTokens(person), actions: page.actions, token, nextCursor: page.nextCursor, now }), { chrome: chromeFor(project, "people") }));
         }
-        // Approvers see everyone (D7's ceiling: every fact already passed
-        // the process admission); a viewer sees exactly themselves (U3).
         if (restricted()) {
             const projects = admissionList() ?? [];
             return sendScreen(response, 200, screen("Your access", ownAccessHtml({ name: who.name, approver: who.role === "approver", projects: projects.map(repo => projectName(repo)), activity: personHref(who.name) }), { chrome: chromeFor(project, "people") }));
@@ -158,10 +146,7 @@ export function createPeopleHandlers(runtime) {
                 return back("problem", "Choose when it expires.");
             if (access === "act" && who.role !== "approver")
                 return back("problem", "A viewer's token can only read.");
-            // A token is a credential: made with the person's password typed now (or an explicit identity-provider re-check,
-            // spent by it), counted once. Never a remembered password: this act is outside every freshness allowlist.
             const typed = body.get("password") ?? "";
-            // Passwordless never covers it (docs/plans/passwordless.md: a credential act).
             const viewerProof = who.role === "approver" || who.via !== "cookie" ? null : proveAccountNow(store, who.name, typed, { credential: true });
             const confirmed = who.role === "approver" ? authenticateCredential(who, typed).ok
                 : viewerProof !== null && viewerProof.ok && credentialProof(viewerProof.method);
@@ -170,7 +155,6 @@ export function createPeopleHandlers(runtime) {
             const minted = mintApiToken();
             const expiresAt = new Date(now.getTime() + days * 86_400_000).toISOString();
             store.createApiToken({ id: minted.id, account: who.name, name, secretHash: minted.hash, access, expiresAt, by: who.name }, now);
-            // The token, once, on a page with no script.
             return sendScreen(response, 200, screen("API token", tokenShownHtml(name, minted.token, access, expiresAt), { chrome: chromeFor(projectOf(who, request) ?? null, "settings"), forceSensitive: true }));
         }
         return back("problem", "Choose an action.");
@@ -178,7 +162,6 @@ export function createPeopleHandlers(runtime) {
     async function peopleProjects(ctx) {
         const { who, response, now, posted } = ctx;
         const body = readForm(posted, CONSOLE_FORMS.peopleProjects);
-        // Widening access (up to instance operator) is a credential act: a password typed now, Passwordless or not.
         if (!authenticateCredential(who, body.get("token") ?? "", null).ok)
             return refuse(response, who, 403, "Saving access requires your password.", "/people");
         const access = readAccessForm(body);
@@ -196,8 +179,6 @@ export function createPeopleHandlers(runtime) {
         if (who.via !== "cookie")
             return refuse(response, who, 403, "inviting is a browser surface");
         const token = body.get("token") ?? "";
-        // RAISING authority is a password ceremony (the doctrine): adding a
-        // person to the instance is exactly that.
         if (!authenticateCredential(who, token).ok) {
             return refuse(response, who, 403, "making an invite takes your password, typed again", "/people");
         }
@@ -209,9 +190,7 @@ export function createPeopleHandlers(runtime) {
             return refuse(response, who, 400, "Select at least one project for this invitation.", "/people");
         const minted = store.mintInvite(role, who.name, now, undefined, access.projects);
         const origin = options.publicUrl !== undefined ? options.publicUrl.replace(/\/$/, "") : `http://${request.headers.host ?? "this-console"}`;
-        const linkScreen = screen("Invite link", inviteLinkHtml({ link: `${origin}/join/${minted.token}`, approver: role === "approver", projects: access.projects === null ? "all projects" : access.projects.map(repo => projectName(repo)).join(", "), expires: `${minted.expiresAt.slice(0, 16).replace("T", " ")} UTC` }), 
-        // A one-time secret on screen: no script of any kind rides along.
-        { chrome: chromeFor(projectOf(who, request) ?? null, "people"), forceSensitive: true });
+        const linkScreen = screen("Invite link", inviteLinkHtml({ link: `${origin}/join/${minted.token}`, approver: role === "approver", projects: access.projects === null ? "all projects" : access.projects.map(repo => projectName(repo)).join(", "), expires: `${minted.expiresAt.slice(0, 16).replace("T", " ")} UTC` }), { chrome: chromeFor(projectOf(who, request) ?? null, "people"), forceSensitive: true });
         return sendScreen(response, 200, linkScreen);
     }
     async function peopleInviteRevoke(ctx) {
@@ -251,17 +230,13 @@ export function createPeopleHandlers(runtime) {
     async function signInPage(ctx) {
         const { url, response } = ctx;
         if (options.setupCode !== undefined && store.listApprovers().length === 0) {
-            // The form's same-site proof (signup-gate.ts): a post without it never reaches the setup code.
             if (runtime.setupAttemptsLeft > 0)
                 response.setHeader("Set-Cookie", signupCookie(cookieSecure));
-            // Its own post then carries this console's Origin (the console's default no-referrer sends `null`).
             response.setHeader("Referrer-Policy", "same-origin");
             return page(response, 200, signupPage(null, runtime.setupAttemptsLeft));
         }
         return page(response, 200, loginPage(null, loginReturn(url.searchParams.get("return")), ssoOffer()));
     }
-    // The one-time link `up` opens (onboarding): it signs the browser on this computer in and lands on Chat. Spent on
-    // the first visit whatever happens; the ledger notes the sign-in, never the link.
     async function signInLink(ctx) {
         const { url, request, response } = ctx;
         const code = url.pathname.slice(SIGN_IN_LINK_PATH.length);
@@ -274,7 +249,7 @@ export function createPeopleHandlers(runtime) {
             return page(response, 403, loginPage("That sign-in link works only in a browser on the computer running Toolroll. Sign in with your password.", "/chat", ssoOffer()));
         }
         if (held === undefined || held.expires < Date.now()) {
-            return page(response, 410, loginPage("That sign-in link has been used or has expired. Sign in with your password, or run toolroll up again.", "/chat", ssoOffer()));
+            return page(response, 410, loginPage(html `That sign-in link has been used or has expired. Sign in with your password, or run <code>toolroll</code> again.`, "/chat", ssoOffer()));
         }
         const account = store.accountOf(held.account);
         if (account === null || account.role !== "approver" || account.revokedAt !== null)
@@ -286,9 +261,6 @@ export function createPeopleHandlers(runtime) {
         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)
@@ -297,7 +269,7 @@ export function createPeopleHandlers(runtime) {
                 return true;
             });
             if (!made)
-                return page(response, 410, loginPage("That sign-in link no longer works. Run toolroll again to open Toolroll.", "/chat", ssoOffer()));
+                return page(response, 410, loginPage(html `That sign-in link has been used or has expired. Run <code>toolroll</code> again to open Toolroll.`, "/chat", ssoOffer()));
             recordSignIn(held.account, "signed in", "local link");
         }
         else {
@@ -306,8 +278,6 @@ export function createPeopleHandlers(runtime) {
         }
         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.
     async function ssoStart(ctx) {
         const { url, who, request, response } = ctx;
         const settings = ssoSettings();
@@ -320,8 +290,6 @@ export function createPeopleHandlers(runtime) {
         const origin = consoleOrigin(request.headers.host);
         if (origin === null)
             return page(response, 400, loginPage("Sign in from this computer (localhost) or from your https address.", returnTo, ssoOffer()));
-        // Discovered as the console starts and in the background (docs/plans/get-side-effects.md): following this link
-        // fetches nothing.
         const known = providerKnown(settings.issuer);
         if (known === null)
             return page(response, 503, loginPage(`${settings.label} isn't answering yet. Try again in a moment.`, returnTo, ssoOffer()));
@@ -330,7 +298,6 @@ export function createPeopleHandlers(runtime) {
         for (const [key, one] of ssoVisits)
             if (one.expires < Date.now())
                 ssoVisits.delete(key);
-        // Bounded: anyone may start a sign-in, so the oldest waiting ones give way.
         while (ssoVisits.size >= 1000)
             ssoVisits.delete(ssoVisits.keys().next().value);
         const asker = intent === "sign-in" || who?.via !== "cookie" ? null : sessions.hashOf(who.session);
@@ -360,7 +327,6 @@ export function createPeopleHandlers(runtime) {
         if (handoff.intent === "link" || handoff.intent === "reauth") {
             if (who?.via !== "cookie")
                 return redirect(response, loginHref(handoff.returnTo));
-            // Only the session that asked: same kept session, same credential generation.
             if (handoff.session === null || sessions.hashOf(who.session) !== handoff.session.hash || who.session.generation !== handoff.session.generation) {
                 return page(response, 403, loginPage(`That ${settings.label} check was started by another sign-in. Start it again from this page.`, handoff.returnTo, ssoOffer()));
             }
@@ -372,12 +338,9 @@ export function createPeopleHandlers(runtime) {
                 sessions.persist(who.session);
                 return redirect(response, `/settings/sign-in?said=${encodeURIComponent(`This account signs in with ${settings.label} now.`)}`);
             }
-            // A step-up: the provider checked the same person again.
             if (store.ssoAccount(identity.issuer, identity.subject) !== who.name)
                 return page(response, 403, loginPage(`That ${settings.label} account isn't the one signed in here.`, handoff.returnTo, ssoOffer()));
             who.session.sso = { at: handoff.checkedAt ?? 0 };
-            // An explicit re-check on request: the one identity-provider event that stands in for a password typed now (for ONE
-            // step-up, spent by it) and may start a freshness window (B2). Kept in memory only: a restart forgets it.
             if (handoff.checkedAt !== null) {
                 who.session.ssoReauthAt = handoff.checkedAt;
                 who.session.ssoNowAt = handoff.checkedAt;
@@ -403,18 +366,13 @@ export function createPeopleHandlers(runtime) {
     }
     async function signupSend(ctx) {
         const { request, response } = ctx;
-        // A re-shown form posts again: its Origin must name this console too (signup-gate.ts).
         response.setHeader("Referrer-Policy", "same-origin");
-        // Only while the table is empty, only with the printed code, only
-        // five tries: the bootstrap door underneath is atomic, so two first
-        // visitors serialize to one owner.
         if (options.setupCode === undefined || store.listApprovers().length > 0) {
             return page(response, 409, loginPage("An account already exists. Sign in."));
         }
         if (runtime.setupAttemptsLeft <= 0) {
             return page(response, 403, signupPage(null, 0));
         }
-        // Another site's post (or one without this page's cookie) is refused before it can spend a try.
         if (!signupFromHere(request, runtime.allowedHost)) {
             request.resume();
             response.setHeader("Set-Cookie", signupCookie(cookieSecure));
@@ -424,14 +382,11 @@ export function createPeopleHandlers(runtime) {
         const code = (body.get("code") ?? "").trim();
         const name = (body.get("name") ?? "").trim();
         const password = body.get("password") ?? "";
-        // Re-read after the body: concurrent posts all waited above, and only the tries still left may be compared.
-        // From here to the decrement nothing awaits, so check and spend are one step.
         if (runtime.setupAttemptsLeft <= 0) {
             return page(response, 403, signupPage(null, 0));
         }
         if (!setupCodeMatches(code, options.setupCode)) {
             runtime.setupAttemptsLeft -= 1;
-            // What was typed comes back except the code and the password (never echoed); the count rides the code's note.
             return page(response, 403, signupPage(runtime.setupAttemptsLeft > 0
                 ? { field: "code", text: "That isn't the setup code Toolroll printed. Check the terminal and try again." }
                 : "That wasn't the setup code, and that was the last try. Restart Toolroll to get a new code.", runtime.setupAttemptsLeft, name));
@@ -463,7 +418,6 @@ export function createPeopleHandlers(runtime) {
             lastSeen: Date.now(),
             project: runtime.defaultProject,
             projectRevision: 1,
-            // A password typed on this computer starts this session's freshness window (cockpit B2); from anywhere else, never.
             ...(fromThisComputer(request) ? { passwordAt: Date.now() } : {}),
         });
         return signedInTo(response, keyed.key, "/", [`${SESSION_COOKIE}=${id}; HttpOnly; SameSite=Strict; Path=/${cookieSecure}`]);
@@ -473,9 +427,6 @@ export function createPeopleHandlers(runtime) {
         const body = readForm(await form(request), CONSOLE_FORMS.login);
         const name = body.get("name");
         const token = body.get("token");
-        // The destination a deep link asked for rides the form as a same-site
-        // path, re-checked here on both roads: a failed sign-in keeps it, a
-        // successful one lands on it. Nothing about the sign-in itself changes.
         const returnTo = loginReturn(body.get("return"));
         const source = joinSourceOf(request), at = Date.now();
         const wait = signInBudget.waitFor(source, at);
@@ -516,8 +467,6 @@ export function createPeopleHandlers(runtime) {
             lastSeen: Date.now(),
             project: runtime.defaultProject,
             projectRevision: 1,
-            // A password typed to sign in on this computer starts this session's freshness window (cockpit B2); from anywhere
-            // else (a phone, a proxy) it signs in and proves nothing more.
             ...(fromThisComputer(request) ? { passwordAt: Date.now() } : {}),
         });
         return signedInTo(response, keyed.key, returnTo, [`${SESSION_COOKIE}=${id}; HttpOnly; SameSite=Strict; Path=/${cookieSecure}`]);
@@ -535,11 +484,6 @@ export function createPeopleHandlers(runtime) {
         response.setHeader("Set-Cookie", `${SESSION_COOKIE}=; HttpOnly; SameSite=Strict; Path=/; Max-Age=0${cookieSecure}`);
         return redirect(response, "/login");
     }
-    // THE JOIN ROAD (v29, D6/E3): a single-use invite is the only door
-    // that creates an account from the outside. Cookie-free, script-free,
-    // and every dead token shape — unknown, expired, revoked, consumed,
-    // attempts spent — answers with ONE indistinguishable page. GET spends
-    // nothing; a POST spends one metered attempt BEFORE the KDF runs.
     async function joinPage(ctx) {
         const { url, response } = ctx;
         const joinToken = joinCodeOf(url);
@@ -549,8 +493,6 @@ export function createPeopleHandlers(runtime) {
     async function joinSend(ctx) {
         const { url, request, response } = ctx;
         const joinToken = joinCodeOf(url);
-        // EXACT media type (Codex people round 2, finding 5): parameters may
-        // follow a semicolon; a merely prefix-shaped type is not a form.
         const media = String(request.headers["content-type"] ?? "").split(";")[0]?.trim().toLowerCase();
         if (media !== "application/x-www-form-urlencoded") {
             return respond(response, 415, "text/plain; charset=utf-8", "forms only");
@@ -575,8 +517,6 @@ export function createPeopleHandlers(runtime) {
             return page(response, 200, joinDeadPage());
         const name = (body.get("name") ?? "").trim();
         const password = body.get("password") ?? "";
-        // Possession of a LIVE token earns real words (D6's disclosure
-        // ruling) — the attempt is already spent either way (E3).
         if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,39}$/.test(name)) {
             return page(response, 400, joinFormPage(joinToken, { field: "name", text: "Use 1\u201340 letters, digits, dots, dashes or underscores, starting with a letter or digit." }, name, liveInviteTerms(store, joinToken, clock())));
         }
@@ -590,7 +530,6 @@ export function createPeopleHandlers(runtime) {
             }
             return page(response, 200, joinDeadPage());
         }
-        // The cookie mints only AFTER the commit — same shape as login.
         const id = randomBytes(32).toString("hex");
         const keyed = keyFor(request);
         sessions.set(id, {
@@ -609,7 +548,6 @@ export function createPeopleHandlers(runtime) {
         });
         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) {
         return url.pathname.slice("/join/".length);
     }
@@ -634,12 +572,6 @@ export function createPeopleHandlers(runtime) {
         joinBySource.set(source, { tokens: tokens - 1, refilledAt: refill > 0 ? at : bucket.refilledAt });
         return true;
     }
-    /**
-     * Back from a service's sign-in: the code becomes the tool's tokens,
-     * kept in its secrets file, and a page sends the person back to Tools (or
-     * to the kit the Connect came from, whose subagent may then use the tool).
-     */
-    /** v100: back from the identity provider. Proves the person, then hands them to /login/sso/finish on this site. */
     async function ssoCallback(request, response, url) {
         const back = (words) => page(response, 400, loginPage(words, "/", ssoOffer()));
         const state = url.searchParams.get("state") ?? "";
@@ -666,9 +598,6 @@ export function createPeopleHandlers(runtime) {
             logEvent("warn", "sso.refused", { reason: verified.said });
             return back(verified.said);
         }
-        // When the provider checked the person (its auth_time), proved against this visit (cockpit B2, N18): no earlier than
-        // this visit began, and not in the future beyond a minute of clock skew. A step-up must carry one that holds — a
-        // check made for this request, never a remembered one; any other sign-in without one signs in, but is never fresh.
         const checkedAt = sameVisitCheck(verified.claims.authTime, held.startedAt, Date.now());
         if (held.intent === "reauth" && checkedAt === null)
             return back(`${settings.label} didn't check you again. Try once more.`);
@@ -681,7 +610,6 @@ export function createPeopleHandlers(runtime) {
         ssoHandoffs.set(key, { claims: verified.claims, issuer: held.provider.issuer, intent: held.intent, returnTo: held.returnTo, expires: Date.now() + 60_000, checkedAt, session: held.session });
         const to = `/login/sso/finish?h=${key}`;
         response.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store", "referrer-policy": "no-referrer", "x-content-type-options": "nosniff", "x-frame-options": "DENY",
-            // The hand-off key is this browser's alone, like the visit's state: its cookie rides to /login/sso/finish.
             "set-cookie": [signInSpent(SSO_CALLBACK), `${SIGN_IN_COOKIE}=${key}; Path=/login/sso/finish; Max-Age=60; HttpOnly; SameSite=Lax${held.redirect.startsWith("https:") ? "; Secure" : ""}`],
             "content-security-policy": "default-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'none'; base-uri 'none'" });
         response.end(htmlString(html `<!doctype html><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta http-equiv="refresh" content="0;url=${to}"><title>Toolroll</title>${HANDOFF_STYLE}<p>Signing you in… <a href="${to}">Continue</a></p>`));
@@ -690,7 +618,6 @@ export function createPeopleHandlers(runtime) {
         if (body.getAll("access").length > 1)
             return { ok: false, message: "Choose one access setting." };
         const mode = body.get("access");
-        // Older clients omitted this field and explicitly used instance roles.
         if ((mode === null && body.getAll("projects").length === 0) || mode === "all")
             return { ok: true, projects: null };
         if (mode !== "selected")
@@ -701,23 +628,17 @@ 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"));
@@ -742,7 +663,6 @@ export function createPeopleHandlers(runtime) {
             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)));
@@ -757,7 +677,6 @@ export function createPeopleHandlers(runtime) {
             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") {
@@ -769,8 +688,6 @@ export function createPeopleHandlers(runtime) {
             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);
@@ -780,10 +697,6 @@ export function createPeopleHandlers(runtime) {
         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())
@@ -793,7 +706,6 @@ export function createPeopleHandlers(runtime) {
     }
     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));
@@ -821,12 +733,9 @@ export function createPeopleHandlers(runtime) {
                 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]))
@@ -839,7 +748,6 @@ export function createPeopleHandlers(runtime) {
         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) {
@@ -847,7 +755,6 @@ export function createPeopleHandlers(runtime) {
             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);
@@ -856,9 +763,6 @@ export function createPeopleHandlers(runtime) {
             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")
@@ -869,7 +773,6 @@ export function createPeopleHandlers(runtime) {
         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, {
@@ -885,7 +788,6 @@ export function createPeopleHandlers(runtime) {
             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}`]);

package/dist/server/remote-hooks.js

@@ -1,15 +1,6 @@
 import { adapterPolicy } from "./route-policy.js";
 import { flowFormPage, FORM_PATH, HOOK_PATH, hookRefusedUnread, receiveFlowForm, receiveFlowHook } from "../flow-triggers.js";
 import { keepPushedUpdate, loadBotToken, pushedByTelegram, telegramHookSecret } from "../telegram.js";
-/** Flow webhooks (v82): the one road a public relay may expose. The secret
- * address proves nothing about the sender on its own for GitHub and Linear:
- * their signatures are checked too. Nothing runs here; cards wait for a pass. */
-/**
- * v98: Telegram pushes this bot's updates here. Only a request carrying our
- * secret header is Telegram's; each update is kept for the bridge (which
- * applies it through the same door as a polled one), and answered at once so
- * Telegram doesn't send it again. An update already kept or applied is fine.
- */
 export async function telegramHook(ctx, request, response) {
     const { store, options, clock } = ctx;
     const reply = (status) => { response.writeHead(status, { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" }); response.end(status === 200 ? "ok" : "no"); request.resume(); };
@@ -59,7 +50,6 @@ export async function flowHook(ctx, request, response, url) {
         return reply(404, "No such address.");
     if (request.method !== "POST")
         return reply(405, "Send a POST.");
-    // Refused before it is read (v126): it still counts toward its address's minute, as anything unproven does.
     const refused = (status, said) => { const over = hookRefusedUnread(store, url.pathname.slice(HOOK_PATH.length), clock()); return over === null ? reply(status, said) : reply(over.status, over.said, over.retryAfter); };
     if (Number(request.headers["content-length"] ?? 0) > 1_000_000)
         return refused(413, "Too large.");
@@ -86,7 +76,6 @@ export async function flowHook(ctx, request, response, url) {
         return reply(500, "Not saved.");
     }
 }
-/** A shared button as a public form (v84): its questions, and one card per submission. No sign-in, no session, nothing about the flow shown. */
 export async function flowForm(ctx, request, response, url) {
     const { store, clock } = ctx;
     const page = (answer) => {
@@ -130,8 +119,6 @@ export function healthz(store, response, head, draining = false) {
     catch {
         healthy = false;
     }
-    // A draining console (its `up` is stopping) still answers pages, but says so here at once: a probe moves on instead
-    // of waiting for it to disappear.
     const body = JSON.stringify(draining && healthy ? { status: "draining", message: "Toolroll is restarting (draining)" } : { status: healthy ? "ok" : "unavailable" });
     response.writeHead(healthy && !draining ? 200 : 503, { "content-type": "application/json", "cache-control": "no-store", "x-content-type-options": "nosniff" });
     response.end(head ? undefined : body);

package/dist/server/remote.js

@@ -1,6 +1,5 @@
 import { credentialProof, freshFacts, proveAccountNow, ssoNowAvailable } from "../scope.js";
 import { handlersOf } from './handler-registry.js';
-/** tasks handlers, moved without changing their route bodies. */
 import {} from "node:http";
 import { handleCliHttp } from '../cli-http.js';
 import { CodingWorkspace } from '../coding-workspace.js';
@@ -16,17 +15,11 @@ import { respond } from "./http.js";
 import {} from "./session.js";
 export function createRemoteHandlers(runtime) {
     const { identify, store, admitPasswordSource, admitBearer, allowedHost, team, teamBrowserReply, requestBudget, options, clock, evidenceRoot, consoleOrigin, managedRepos, joinSourceOf, ssoSettings, oauthTokenBudget, hookContext, teamsSourceBudget, teamsTenantBudget } = runtime;
-    /**
-     * The full principal a live `so_` API token stands for: its person and their generation, the token's own read/act
-     * scope, its project limit narrowed by the person's current access, and its id. Every route that accepts an API token
-     * builds its identity here and carries it whole, so no route can drop the token's narrower scope or projects.
-     */
     const tokenPrincipalOf = (request) => {
         const who = identify(request, false, true);
         return who?.via === "bearer" ? who.principal ?? null : null;
     };
     const presentsToken = (request) => /^Bearer so_\S+$/.test(request.headers.authorization ?? "");
-    /** When each live request's password bearer last proved its password: kept only while the request is. */
     const passwordProvedAt = new WeakMap();
     const teamEndpoint = (request, response) => handleTeamHttp(request, response, {
         authenticate: request => {
@@ -38,7 +31,6 @@ export function createRemoteHandlers(runtime) {
             const account = who === null ? null : store.accountOf(who.name);
             if (!who || !account || account.revokedAt !== null)
                 return null;
-            // Easy-start C1: team conversations are a remote feature; a laptop's local owner (no password) never reaches them.
             if (who.via === 'cookie' && who.authority !== 'full')
                 return null;
             if (who.via === 'bearer')
@@ -51,18 +43,13 @@ export function createRemoteHandlers(runtime) {
             const account = store.accountOf(actor.name);
             if (!account || account.revokedAt !== null || account.generation !== actor.generation)
                 return false;
-            // An API token is re-proved against the store every time: unrevoked, unexpired, inside its project limit.
             if (actor.principal !== undefined) {
                 const live = reproveRemote(store, actor.principal, new Date());
                 if (!live.ok)
                     return false;
-                // The post-body mutation check must see a scope lowered since authentication, too.
                 actor.principal = { ...actor.principal, scope: live.scope };
                 return true;
             }
-            // A password bearer was proved when this connection opened, and is proved again (the password checked, through
-            // the same per-source tries and locks) once TEAM_PASSWORD_REVERIFY_MS has passed since. Cookie expiry/revocation
-            // is rechecked without allowing a passive stream to extend its lifetime.
             if (request.headers.authorization) {
                 const now = clock().getTime(), provedAt = passwordProvedAt.get(request);
                 if (provedAt !== undefined && now - provedAt < TEAM_PASSWORD_REVERIFY_MS)
@@ -90,8 +77,6 @@ export function createRemoteHandlers(runtime) {
             const named = typeof origin === 'string' && origin !== 'null' ? origin : typeof referer === 'string' ? referer : null;
             if (named !== null && !allowedHost(named.replace(/^https?:\/\//, '').split('/')[0]))
                 return false;
-            // Easy-start C2: and, on a protected loopback install, the session's key (its header), which a cookie holder on
-            // another port can't read.
             return request.headers['x-csrf-token'] === who.session.csrf && runtime.browserKeys.check(who, request, null) === null;
         },
         execute: async (actor, input) => {
@@ -102,7 +87,6 @@ export function createRemoteHandlers(runtime) {
             return who?.via === 'cookie' ? teamBrowserReply(reply, actor, who.session.csrf) : reply;
         },
     });
-    // Remote CLI: one live API token names the person; the shared command boundary decides everything else.
     const cliEndpoint = (request, response) => handleCliHttp(request, response, {
         admit: principal => requestBudget.admit(principal.tokenId, "api"),
         authenticate: tokenPrincipalOf,
@@ -113,13 +97,11 @@ export function createRemoteHandlers(runtime) {
     const mcpHttp = createMcpHttp({ store, clock, evidenceRoot, ...(options.requestBudgetClock === undefined ? {} : { requestBudgetClock: options.requestBudgetClock }), signedIn: request => identify(request, true, true) !== null, admit: person => requestBudget.admit(person.principal.tokenId, "mcp"),
         resourceMetadata: request => { const origin = consoleOrigin(request.headers.host); return origin === null ? null : resourceMetadataUrl(origin); },
         enrolled: () => [...new Set([...managedRepos(), ...store.listProjects().map(project => project.path)])], ...(options.runOperateAs === undefined ? {} : { runAs: options.runOperateAs }) });
-    // MCP sign-in: the console's own sign-in and step-up, a same-site consent form, and the person's current projects.
     const oauthHttp = createOAuthHttp({ store, clock,
         originOf: request => consoleOrigin(request.headers.host),
         requesterKey: joinSourceOf,
         session: request => {
             const who = identify(request, false);
-            // Easy-start C1: connecting an outside app is a credential act; a local owner's session is never one that consents.
             if (who === null || who.via !== "cookie" || who.authority !== "full")
                 return null;
             return { name: who.name, role: who.role, csrf: who.session.csrf, generation: who.session.generation,
@@ -131,22 +113,15 @@ export function createRemoteHandlers(runtime) {
             const named = typeof origin === "string" && origin !== "null" ? origin : typeof referer === "string" ? referer : null;
             return named !== null && allowedHost(named.replace(/^https?:\/\//, "").split("/")[0]);
         },
-        // Easy-start C2: the consent's own post presents the session's key too (its form carries it, filled by the page's
-        // one nonce'd script while the key is required).
         keyed: (request, form) => {
             const who = identify(request, false);
             return who !== null && who.via === "cookie" && runtime.browserKeys.check(who, request, form) === null;
         },
         keyFill: () => runtime.browserKeys.required(),
-        // The step-up for a credential: the person's password, or (empty) a fresh identity-provider check. What they may
-        // grant (their role, their projects) is checked beside it.
-        // Proved on this request's live session at the moment of consent (signed in here still, same generation), through
-        // the one account step-up: a password typed now, or an explicit re-check (spent). Never a remembered password.
         confirm: (request, session, typed) => {
             const who = identify(request, false);
             if (who === null || who.via !== "cookie" || who.authority !== "full" || who.name !== session.name || who.session.generation !== session.generation)
                 return false;
-            // Connecting an outside app is a credential act: never a session (Passwordless) or a remembered password.
             return freshFacts.run(runtime.freshFactsOf(request, who), () => { const proved = proveAccountNow(store, who.name, typed, { credential: true }); return proved.ok && credentialProof(proved.method); });
         },
         projectsFor: account => store.knownRepos().filter(repo => store.accountCanAccess(account, repo)).sort(),
@@ -158,9 +133,6 @@ export function createRemoteHandlers(runtime) {
             return;
         return respond(response, 404, 'text/plain; charset=utf-8', 'No such address.');
     };
-    // D5: the central team service is deprecated (still served this release); each answer says so in a Deprecation
-    // header (RFC 9745).
-    // Each protocol adapter keeps its own operation boundary; every row still names its own entry.
     const registrations = handlersOf("remote", {}, {
         "edge.telegram-hook": async ({ request, response }) => { await telegramHook(hookContext, request, response); },
         "edge.flow-form": async ({ request, response, url }) => { await flowHook(hookContext, request, response, url); },