toolroll 0.9.45 → 0.9.46

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.9.46 — 2026-10-07
+
+- **Tokens from the terminal.** `toolroll tokens create|list|revoke|rotate`.
+  Creating or rotating asks for your password and shows the secret once.
+  Tokens can be limited to projects and always expire; rotating never
+  extends one. You're warned 7 days and 1 day before expiry.
+- **Request limits per token.** Too many requests get a 429 with
+  Retry-After. Owners change the limits in the console.
+- **`toolroll audit`** and the People page show who did what remotely, with
+  which token, and how it went. People see only their own.
+- **A real domain, safely.** HSTS only on the https public host. Tokens are
+  refused over plain HTTP from outside this machine or your tailnet.
+  `toolroll serve check-public` checks the setup; see docs/team-server.md.
+- **Agents sign in instead of pasting a token.** OAuth with PKCE and a
+  consent screen, short-lived tokens, and reuse detection. Pasted tokens
+  still work.
+- Still to come: `brief` and `spend` remotely for limited access.
+
 ## 0.9.45 — 2026-10-07
 
 - **Your projects, your lists.** People with access to some projects can now

package/dist/api-tokens.d.ts

@@ -1,4 +1,11 @@
 export type TokenAccess = "read" | "act";
+export type TokenPurpose = "api" | "mcp";
+export declare const MCP_ROTATION_REFUSAL = "Reconnect the MCP client to renew this token. You can still revoke it here.";
+/** Missing purpose is an old ordinary token; an unrecognised stored purpose is never treated as ordinary. */
+export declare const tokenPurpose: (value: unknown) => TokenPurpose;
+export declare const tokenRotationProblem: (token: {
+    purpose: TokenPurpose;
+}) => string | null;
 export declare const TOKEN_DAYS: readonly [30, 90, 365];
 export declare function mintApiToken(): {
     id: string;
@@ -14,3 +21,29 @@ export declare function parseApiToken(presented: string): {
 } | null;
 /** Whether the secret is the one whose hash was kept, in constant time. */
 export declare function secretMatches(secret: string, keptHash: string): boolean;
+/** v111: how long a rotated token keeps working beside its replacement, by default and at most. */
+export declare const ROTATION_OVERLAP_MINUTES = 10;
+export declare const ROTATION_OVERLAP_MAX_MINUTES = 60;
+/** v111: the person is told this many days before a token expires, once each. */
+export declare const EXPIRY_NOTICE_DAYS: readonly [7, 1];
+type TokenState = {
+    revokedAt: string | null;
+    expiresAt: string;
+    overlapUntil: string | null;
+};
+/** Whether a token signs anyone in at `now`: unrevoked, unexpired, and (once replaced) inside its overlap. */
+export declare function tokenLive(token: TokenState, now: number): boolean;
+/**
+ * The projects a token's person may use through it now: the person's current access, narrowed by the token's limit.
+ * Null is every project. A limit never widens access, and a project the person has lost stays lost.
+ */
+export declare function tokenProjects(account: readonly string[] | null, token: readonly string[] | null): string[] | null;
+/** Whether `projects` (a principal's) stays inside the token's limit. A limited token never stands for every project. */
+export declare function withinTokenLimit(projects: readonly string[] | null, limit: readonly string[] | null): boolean;
+/** Whole days until a token expires, rounded up (0 once it has). */
+export declare const daysLeft: (expiresAt: string, now: number) => number;
+/** The expiry notice a token is due at `now` (7 or 1 days), or null. Replaced and revoked tokens get none. */
+export declare function expiryNoticeDue(token: TokenState & {
+    replacedBy: string | null;
+}, now: number): (typeof EXPIRY_NOTICE_DAYS)[number] | null;
+export {};

package/dist/api-tokens.js

@@ -8,6 +8,10 @@
  * stay a person's act in the console.
  */
 import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+export const MCP_ROTATION_REFUSAL = "Reconnect the MCP client to renew this token. You can still revoke it here.";
+/** Missing purpose is an old ordinary token; an unrecognised stored purpose is never treated as ordinary. */
+export const tokenPurpose = (value) => value === undefined || value === "api" ? "api" : "mcp";
+export const tokenRotationProblem = (token) => token.purpose === "api" ? null : MCP_ROTATION_REFUSAL;
 export const TOKEN_DAYS = [30, 90, 365];
 const SHAPE = /^so_([a-f0-9]{12})_([A-Za-z0-9_-]{43})$/;
 export function mintApiToken() {
@@ -25,3 +29,38 @@ export function secretMatches(secret, keptHash) {
     const a = Buffer.from(hashSecret(secret), "hex"), b = Buffer.from(keptHash, "hex");
     return a.length === b.length && timingSafeEqual(a, b);
 }
+/** v111: how long a rotated token keeps working beside its replacement, by default and at most. */
+export const ROTATION_OVERLAP_MINUTES = 10;
+export const ROTATION_OVERLAP_MAX_MINUTES = 60;
+/** v111: the person is told this many days before a token expires, once each. */
+export const EXPIRY_NOTICE_DAYS = [7, 1];
+/** Whether a token signs anyone in at `now`: unrevoked, unexpired, and (once replaced) inside its overlap. */
+export function tokenLive(token, now) {
+    if (token.revokedAt !== null || !(Date.parse(token.expiresAt) > now))
+        return false;
+    return token.overlapUntil === null || Date.parse(token.overlapUntil) > now;
+}
+/**
+ * The projects a token's person may use through it now: the person's current access, narrowed by the token's limit.
+ * Null is every project. A limit never widens access, and a project the person has lost stays lost.
+ */
+export function tokenProjects(account, token) {
+    if (token === null)
+        return account === null ? null : [...account];
+    return token.filter(repo => account === null || account.includes(repo));
+}
+/** Whether `projects` (a principal's) stays inside the token's limit. A limited token never stands for every project. */
+export function withinTokenLimit(projects, limit) {
+    if (limit === null)
+        return true;
+    return projects !== null && projects.every(repo => limit.includes(repo));
+}
+/** Whole days until a token expires, rounded up (0 once it has). */
+export const daysLeft = (expiresAt, now) => Math.max(0, Math.ceil((Date.parse(expiresAt) - now) / 86_400_000));
+/** The expiry notice a token is due at `now` (7 or 1 days), or null. Replaced and revoked tokens get none. */
+export function expiryNoticeDue(token, now) {
+    if (token.replacedBy !== null || !tokenLive(token, now))
+        return null;
+    const left = Date.parse(token.expiresAt) - now;
+    return EXPIRY_NOTICE_DAYS.filter(days => left <= days * 86_400_000).at(-1) ?? null;
+}

package/dist/audit-cli.d.ts

@@ -0,0 +1,17 @@
+import type { RemoteRun } from "./remote-run.js";
+import { type AuditAction, type AuditReader } from "./remote-audit.js";
+import type { Store } from "./store.js";
+export declare const AUDIT_USAGE = "Use audit [--person <name>] [--token <name>] [--source api|mcp] [--since <days>d] [--limit <n>] [--cursor <id>] [--json].";
+type AuditContext = {
+    store: Store;
+    write: (s: string) => void;
+    json: boolean;
+    now: Date;
+    principal?: RemoteRun;
+};
+/** The reader a run is: the machine's owner locally, else the remote caller with their role and projects. */
+export declare function readerOf(store: Store, remote: RemoteRun | undefined): AuditReader;
+export declare function auditCommand(positional: readonly string[], flags: Map<string, string | true>, context: AuditContext): number;
+/** One line per action: outcome first, then who, token, source, what and where. */
+export declare function auditLine(action: AuditAction): string;
+export {};

package/dist/audit-cli.js

@@ -0,0 +1,86 @@
+/**
+ * `toolroll audit`: who did what on this server with their API tokens (remote-audit.ts). On the server's own machine
+ * it lists everyone; run remotely it is the caller's own view — an approver sees everyone within their projects, a
+ * viewer only themselves. `--token` names a token locally; remotely, where `--token` is always a refused credential
+ * flag, the same filter is `--token-name`.
+ */
+import { basename } from "node:path";
+import { checkedEnvelopeJson } from "./contracts/cli.js";
+import { AUDIT_LIMIT, AUDIT_SOURCES, cursorOf, OWNER_READER, remoteAudit, sinceOf } from "./remote-audit.js";
+const EXIT = { ok: 0, usage: 2, refused: 3 };
+const COMMAND = "audit";
+const FLAGS = new Set(["person", "token", "token-name", "source", "since", "limit", "cursor", "json", "db"]);
+export const AUDIT_USAGE = "Use audit [--person <name>] [--token <name>] [--source api|mcp] [--since <days>d] [--limit <n>] [--cursor <id>] [--json].";
+/** The reader a run is: the machine's owner locally, else the remote caller with their role and projects. */
+export function readerOf(store, remote) {
+    if (remote === undefined)
+        return OWNER_READER;
+    const role = store.accountOf(remote.account)?.role ?? "viewer";
+    const all = remote.allows(null);
+    return { self: remote.account, everyone: role === "approver", repos: all ? null : store.knownRepos().filter(repo => remote.allows(repo)), unplaced: all };
+}
+export function auditCommand(positional, flags, context) {
+    const fail = (reason, message, code) => {
+        context.write(context.json ? checkedEnvelopeJson({ ok: false, command: COMMAND, reason, message }) : message);
+        return code;
+    };
+    const usage = (message) => fail("usage", `${message} ${AUDIT_USAGE}`, EXIT.usage);
+    for (const name of flags.keys())
+        if (!FLAGS.has(name))
+            return usage(`--${name} is not an audit option.`);
+    if (positional.length > 0)
+        return usage("audit takes no arguments.");
+    const value = (name) => {
+        const one = flags.get(name);
+        return one === undefined ? null : typeof one === "string" && one !== "" ? one : undefined;
+    };
+    const person = value("person"), source = value("source"), since = value("since"), limit = value("limit"), cursor = value("cursor");
+    const tokenFlag = value("token"), tokenName = value("token-name");
+    for (const [name, one] of [["person", person], ["token", tokenFlag], ["token-name", tokenName], ["source", source], ["since", since], ["limit", limit], ["cursor", cursor]]) {
+        if (one === undefined)
+            return usage(`--${name} needs a value.`);
+    }
+    if (tokenFlag !== null && tokenName !== null && tokenFlag !== tokenName)
+        return usage("Name one token.");
+    const token = tokenFlag ?? tokenName ?? null;
+    if (token !== null && /^so_[a-f0-9]{12}_/.test(token))
+        return usage("Name the token (as shown in Settings), never its secret.");
+    if (source !== null && !AUDIT_SOURCES.includes(source))
+        return usage("--source is api or mcp.");
+    const from = since === null ? null : sinceOf(since, context.now);
+    if (since !== null && from === null)
+        return usage("--since is a number of days, like 7d.");
+    const size = limit === null ? AUDIT_LIMIT.default : /^[1-9][0-9]{0,2}$/.test(limit) && Number(limit) <= AUDIT_LIMIT.max ? Number(limit) : null;
+    if (size === null)
+        return usage(`--limit is 1 to ${AUDIT_LIMIT.max}.`);
+    const before = cursor === null ? null : cursorOf(cursor);
+    if (cursor !== null && before === null)
+        return usage("--cursor is the nextCursor of an earlier page.");
+    const filters = { person: person ?? null, token, source: (source ?? null), since: from };
+    const page = remoteAudit(context.store, readerOf(context.store, context.principal), filters, { limit: size, before });
+    if (!page.ok)
+        return fail(page.reason, page.message, EXIT.refused);
+    if (context.json) {
+        context.write(checkedEnvelopeJson({ ok: true, command: COMMAND, filters, actions: page.actions, limit: page.limit, nextCursor: page.nextCursor }));
+        return EXIT.ok;
+    }
+    const lines = page.actions.length === 0 ? ["No remote actions."] : page.actions.map(auditLine);
+    if (page.nextCursor !== null)
+        lines.push(`Older: toolroll audit --cursor ${page.nextCursor}${flagsAgain(flags)}`);
+    context.write(lines.join("\n"));
+    return EXIT.ok;
+}
+/** One line per action: outcome first, then who, token, source, what and where. */
+export function auditLine(action) {
+    const outcome = action.outcome === "ok" ? "ok" : `${action.outcome}${action.reason === null ? "" : ` (${action.reason})`}`;
+    const where = action.repo === null ? "" : `  ${basename(action.repo)}`;
+    return `${action.at.slice(0, 16).replace("T", " ")}  ${outcome}  ${action.person}  ${action.token ?? "unknown token"}  ${action.source}  ${action.name}${where}`;
+}
+/** The filters again for the next page, quoted when they need it. */
+function flagsAgain(flags) {
+    const quote = (one) => /^[A-Za-z0-9_./:@-]+$/.test(one) ? one : `'${one.replaceAll("'", "'\\''")}'`;
+    return ["person", "token", "token-name", "source", "since", "limit"].flatMap(name => {
+        const one = flags.get(name);
+        return typeof one === "string" ? [` --${name} ${quote(one)}`] : [];
+    }).join("");
+}

package/dist/cli-http.d.ts

@@ -2,6 +2,7 @@ import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { Store } from './store.js';
 import type { Principal } from './operate.js';
 import { type RemoteCommandLookup } from './remote-command.js';
+import { type Admission, type BudgetLimit } from './request-budget.js';
 /**
  * `POST /api/cli` (remote CLI, Phase 1): a teammate's laptop sends the argv it would have run locally, and the central
  * server runs that same command as that person. There is no per-resource API here and no second policy: the transport
@@ -28,6 +29,8 @@ export type CliFailure = {
     ok: false;
     code: string;
     message: string;
+    limit?: BudgetLimit;
+    retryAfter?: number;
 };
 /** Inlined file contents, summed as UTF-8 bytes. */
 export declare const CLI_FILES_BYTES: number;
@@ -40,6 +43,8 @@ export type CliHttpOptions = {
     run: () => Promise<RunOperateAs | null>;
     /** Tests: command policy while the parallel command contract is not yet available. Defaults to COMMAND_GUIDE. */
     modeOf?: RemoteCommandLookup | undefined;
+    /** The token's request budget (request-budget.ts), charged once per request before its body is read. */
+    admit?: ((principal: Principal) => Admission) | undefined;
     store: Store;
 };
 /** Decode the request's shape and byte limits. The endpoint checks file references against its command policy. */

package/dist/cli-http.js

@@ -1,4 +1,5 @@
 import { contractRow, fileArguments, STEP_UP_MESSAGE } from './remote-command.js';
+import { limitWords } from './request-budget.js';
 /** Inlined file contents, summed as UTF-8 bytes. */
 export const CLI_FILES_BYTES = 256 * 1024;
 /** The whole JSON body: the files plus argv and JSON escaping headroom. */
@@ -6,10 +7,10 @@ export const CLI_REQUEST_BYTES = 2 * CLI_FILES_BYTES;
 const ARGV_MAX = 256;
 const ARG_BYTES = 16 * 1024;
 const FILES_MAX = 16;
-function send(response, status, value) {
+function send(response, status, value, headers = {}) {
     if (response.destroyed || response.writableEnded)
         return;
-    response.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store', 'x-content-type-options': 'nosniff' });
+    response.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store', 'x-content-type-options': 'nosniff', ...headers });
     response.end(JSON.stringify(value));
 }
 async function body(request) {
@@ -95,6 +96,15 @@ export async function handleCliHttp(request, response, options) {
     }
     if (!principal)
         return reject(401, 'unauthenticated', 'This API token is not valid (expired, revoked or its person removed).');
+    // Counted once here, however long the command then holds the request (a task wait is one request).
+    const admitted = options.admit === undefined ? { ok: true } : options.admit(principal);
+    if (!admitted.ok && admitted.status === 503)
+        return reject(503, 'limits-unavailable', 'Request limits could not be checked; nothing ran. Try again shortly.');
+    if (!admitted.ok) {
+        send(response, 429, { ok: false, code: 'rate-limited', message: limitWords(admitted.limit, admitted.retryAfter), limit: admitted.limit, retryAfter: admitted.retryAfter }, { 'retry-after': String(admitted.retryAfter) });
+        request.resume();
+        return true;
+    }
     let value;
     try {
         value = await body(request);

package/dist/cli.js

@@ -208,6 +208,7 @@ export const OPERATE_COMMANDS = new Set([
     "task",
     "project",
     "ledger",
+    "audit",
     "storage",
     "monitoring",
     "integrations",
@@ -254,7 +255,7 @@ export const OPERATE_COMMANDS = new Set([
     "run",
     "routine",
     "flows",
-    "config", "chat", "proposals", "mode", "chat-approval", "people", "keys",
+    "config", "chat", "proposals", "mode", "chat-approval", "people", "tokens", "keys",
     "setup",
     "verify",
     "intake",
@@ -304,6 +305,11 @@ export async function main(argv, write = line => console.log(line), mainOptions
         write("-o requires --json — the output file receives the machine envelope");
         return USAGE_EXIT;
     }
+    // A new API token is shown once, on screen: never saved to a file by the entry point.
+    if (outputFile !== undefined && args.find(one => !one.startsWith("-")) === "tokens") {
+        write("-o isn't used with tokens: a new token is shown once, never saved to a file");
+        return USAGE_EXIT;
+    }
     resetCapturedEnvelope();
     // Long-running commands (serve, up) emit their ONE envelope at startup,
     // when its URL is useful — so -o is preflighted BEFORE dispatch (an

package/dist/contracts/cli.d.ts

@@ -714,6 +714,53 @@ export declare const COMMAND_OUTPUTS: {
         reason: z.ZodString;
         message: z.ZodOptional<z.ZodString>;
     }, z.core.$loose>], "ok">;
+    readonly audit: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        envelopeVersion: z.ZodLiteral<1>;
+        ok: z.ZodLiteral<true>;
+        command: z.ZodLiteral<"audit">;
+        filters: z.ZodObject<{
+            person: z.ZodNullable<z.ZodString>;
+            token: z.ZodNullable<z.ZodString>;
+            source: z.ZodNullable<z.ZodEnum<{
+                api: "api";
+                mcp: "mcp";
+            }>>;
+            since: z.ZodNullable<z.ZodString>;
+        }, z.core.$loose>;
+        actions: z.ZodArray<z.ZodObject<{
+            id: z.ZodNumber;
+            at: z.ZodString;
+            person: z.ZodString;
+            token: z.ZodNullable<z.ZodString>;
+            source: z.ZodEnum<{
+                api: "api";
+                mcp: "mcp";
+            }>;
+            kind: z.ZodEnum<{
+                command: "command";
+                tool: "tool";
+            }>;
+            name: z.ZodString;
+            command: z.ZodString;
+            tool: z.ZodNullable<z.ZodString>;
+            repo: z.ZodNullable<z.ZodString>;
+            taskId: z.ZodNullable<z.ZodString>;
+            outcome: z.ZodEnum<{
+                error: "error";
+                ok: "ok";
+                refused: "refused";
+            }>;
+            reason: z.ZodNullable<z.ZodString>;
+        }, z.core.$loose>>;
+        limit: z.ZodNumber;
+        nextCursor: z.ZodNullable<z.ZodString>;
+    }, z.core.$loose>, z.ZodObject<{
+        envelopeVersion: z.ZodLiteral<1>;
+        ok: z.ZodLiteral<false>;
+        command: z.ZodLiteral<"audit">;
+        reason: z.ZodString;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>], "ok">;
     readonly "skills list": z.ZodDiscriminatedUnion<[z.ZodObject<{
         envelopeVersion: z.ZodLiteral<1>;
         ok: z.ZodLiteral<true>;

package/dist/contracts/cli.js

@@ -148,6 +148,16 @@ const taskShowOutput = answers("task show", {
     proofAccepted: z.boolean(),
     stops: list,
 });
+/** `audit` (remote-audit.ts): one page of remote actions, newest first, and the filters it applied. */
+const auditOutput = answers("audit", {
+    filters: z.looseObject({ person: nullable(str), token: nullable(str), source: nullable(z.enum(["api", "mcp"])), since: nullable(str) }),
+    actions: rows({
+        id: int, at: str, person: str, token: nullable(str), source: z.enum(["api", "mcp"]), kind: z.enum(["command", "tool"]), name: str, command: str,
+        tool: nullable(str), repo: nullable(str), taskId: nullable(str), outcome: z.enum(["ok", "refused", "error"]), reason: nullable(str),
+    }),
+    limit: int,
+    nextCursor: nullable(str),
+});
 const flowListed = z.looseObject({ id: int, name: str, repo: str, project: str, zones: z.array(str), triggers: int, cardsWaiting: int, needDecision: int });
 /**
  * The commands whose answers name their fields: the most-used ones (contract, the no-verb scan, status,
@@ -189,6 +199,7 @@ export const COMMAND_OUTPUTS = {
     "cap list": answers("cap list", { repo: str, capabilities: list }),
     gaps: answers("gaps", { repo: str, gaps: list }),
     reap: answers("reap", { count: int, released: list }),
+    audit: auditOutput,
     "skills list": answers("skills list", { guides: rows({ name: str, title: str, oneLiner: str }) }),
 };
 const declared = new Map(Object.entries(COMMAND_OUTPUTS));

package/dist/contracts/console-api.d.ts

@@ -80,6 +80,7 @@ export declare const CONSOLE_FORMS: {
     readonly policy: FormContract<"ceiling" | "models" | "password" | "provider" | "tools">;
     readonly approval: FormContract<"not_requester" | "password" | "paths" | "protect" | "repo">;
     readonly sessions: FormContract<"access" | "action" | "days" | "everyone" | "name" | "password" | "session" | "token">;
+    readonly requestLimits: FormContract<"act-per-minute" | "action" | "password" | "per-day" | "per-minute" | "read-per-minute" | "target">;
     readonly signIn: FormContract<"action" | "client-id" | "client-secret" | "groups-claim" | "issuer" | "label" | "password" | "passwords" | "scopes" | `group-${string}` | `projects-${string}` | `role-${string}`>;
     readonly updates: FormContract<"password" | "version" | "when">;
     readonly retention: FormContract<"chat" | "checkouts" | "evidence" | "notifications" | "password">;

package/dist/contracts/console-api.js

@@ -89,6 +89,7 @@ export const CONSOLE_FORMS = {
     policy: formContract("POST /settings/policy", ["password", "provider", "models", "tools", "ceiling"]),
     approval: formContract("POST /settings/approval", ["repo", "password", "protect", "paths", "not_requester"]),
     sessions: formContract("POST /settings/sessions", ["everyone", "action", "session", "token", "name", "access", "days", "password"]),
+    requestLimits: formContract("POST /settings/request-limits", ["target", "action", "read-per-minute", "act-per-minute", "per-minute", "per-day", "password"]),
     signIn: formContract("POST /settings/sign-in", ["action", "password", "issuer", "client-id", "client-secret", "label", "scopes", "groups-claim", "passwords"], { prefixes: ["group-", "role-", "projects-"] }),
     updates: formContract("POST /settings/updates, /settings/updates/seen, /settings/updates/cancel", ["password", "version", "when"]),
     retention: formContract("POST /settings/retention", ["password", "evidence", "checkouts", "chat", "notifications"]),

package/dist/contracts/mcp-oauth.d.ts

@@ -0,0 +1,53 @@
+/**
+ * MCP sign-in (mcp-oauth.ts): what an MCP client may send when it registers itself (RFC 7591) and when it trades a
+ * code or a refresh secret for tokens (RFC 6749 §4.1.3, §6, with PKCE, RFC 7636).
+ *
+ * A registration is read strictly for the fields Toolroll uses and ignores the rest (RFC 7591 §2: unknown metadata
+ * is ignored). Only public clients register: no secret is issued, so `token_endpoint_auth_method` is `none` when
+ * given. Whether a redirect is https, or http on 127.0.0.1 / [::1], is checked by mcp-oauth.ts after reading.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+/** The most redirects one client registers, and how long each and the client's name may be. */
+export declare const OAUTH_LIMITS: {
+    readonly redirects: 5;
+    readonly redirect: 512;
+    readonly name: 100;
+};
+export declare const OAUTH_GRANTS: readonly ["authorization_code", "refresh_token"];
+export declare const oauthRegistrationSchema: z.ZodObject<{
+    redirect_uris: z.ZodArray<z.ZodString>;
+    client_name: z.ZodOptional<z.ZodString>;
+    token_endpoint_auth_method: z.ZodOptional<z.ZodLiteral<"none">>;
+    grant_types: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        authorization_code: "authorization_code";
+        refresh_token: "refresh_token";
+    }>>>;
+    response_types: z.ZodOptional<z.ZodArray<z.ZodLiteral<"code">>>;
+}, z.core.$strip>;
+/** A PKCE verifier (RFC 7636 §4.1) and a S256 challenge (43 base64url characters). */
+export declare const PKCE_VERIFIER: RegExp;
+export declare const PKCE_CHALLENGE: RegExp;
+/** A token request, by grant type. Every value is one form field. */
+export declare const oauthTokenRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    grant_type: z.ZodLiteral<"authorization_code">;
+    code: z.ZodString;
+    redirect_uri: z.ZodString;
+    client_id: z.ZodString;
+    code_verifier: z.ZodString;
+    resource: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    grant_type: z.ZodLiteral<"refresh_token">;
+    refresh_token: z.ZodString;
+    client_id: z.ZodString;
+    resource: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "grant_type">;
+export type OAuthRegistration = z.infer<typeof oauthRegistrationSchema>;
+export type OAuthTokenRequest = z.infer<typeof oauthTokenRequestSchema>;
+export declare const readOAuthRegistration: (input: unknown) => ContractResult<OAuthRegistration>;
+/** A token request's form: a field given twice is refused (RFC 6749 §3.2); fields this grant doesn't take are ignored. */
+export declare function readOAuthTokenRequest(form: URLSearchParams): ContractResult<OAuthTokenRequest> | {
+    ok: false;
+    repeated: true;
+};

package/dist/contracts/mcp-oauth.js

@@ -0,0 +1,40 @@
+/**
+ * MCP sign-in (mcp-oauth.ts): what an MCP client may send when it registers itself (RFC 7591) and when it trades a
+ * code or a refresh secret for tokens (RFC 6749 §4.1.3, §6, with PKCE, RFC 7636).
+ *
+ * A registration is read strictly for the fields Toolroll uses and ignores the rest (RFC 7591 §2: unknown metadata
+ * is ignored). Only public clients register: no secret is issued, so `token_endpoint_auth_method` is `none` when
+ * given. Whether a redirect is https, or http on 127.0.0.1 / [::1], is checked by mcp-oauth.ts after reading.
+ */
+import { z } from "zod";
+import { parseContract } from "./contract.js";
+/** The most redirects one client registers, and how long each and the client's name may be. */
+export const OAUTH_LIMITS = { redirects: 5, redirect: 512, name: 100 };
+export const OAUTH_GRANTS = ["authorization_code", "refresh_token"];
+export const oauthRegistrationSchema = z.object({
+    redirect_uris: z.array(z.string().min(1).max(OAUTH_LIMITS.redirect)).min(1).max(OAUTH_LIMITS.redirects),
+    client_name: z.string().max(OAUTH_LIMITS.name).optional(),
+    token_endpoint_auth_method: z.literal("none").optional(),
+    grant_types: z.array(z.enum(OAUTH_GRANTS)).min(1).max(2).optional(),
+    response_types: z.array(z.literal("code")).min(1).max(1).optional(),
+});
+/** A PKCE verifier (RFC 7636 §4.1) and a S256 challenge (43 base64url characters). */
+export const PKCE_VERIFIER = /^[A-Za-z0-9._~-]{43,128}$/;
+export const PKCE_CHALLENGE = /^[A-Za-z0-9_-]{43}$/;
+const bounded = z.string().min(1).max(2048);
+/** A token request, by grant type. Every value is one form field. */
+export const oauthTokenRequestSchema = z.discriminatedUnion("grant_type", [
+    z.object({ grant_type: z.literal("authorization_code"), code: bounded, redirect_uri: bounded, client_id: bounded, code_verifier: z.string().regex(PKCE_VERIFIER), resource: bounded.optional() }),
+    z.object({ grant_type: z.literal("refresh_token"), refresh_token: bounded, client_id: bounded, resource: bounded.optional(), scope: bounded.optional() }),
+]);
+export const readOAuthRegistration = (input) => parseContract(oauthRegistrationSchema, input);
+/** A token request's form: a field given twice is refused (RFC 6749 §3.2); fields this grant doesn't take are ignored. */
+export function readOAuthTokenRequest(form) {
+    const fields = {};
+    for (const [key, value] of form) {
+        if (Object.hasOwn(fields, key))
+            return { ok: false, repeated: true };
+        fields[key] = value;
+    }
+    return parseContract(oauthTokenRequestSchema, fields);
+}

package/dist/credentials-ui.d.ts

@@ -16,6 +16,11 @@ export type CredentialsView = {
     })[];
     tokens: ApiTokenRow[];
     now: number;
+    /** Request limits (request-budget-ui.ts): words for each token's line, and the operator's disclosure. */
+    limits?: {
+        note: (token: ApiTokenRow) => string;
+        section: string;
+    };
 };
 export declare function credentialsHtml(view: CredentialsView, csrf: string, notice: {
     said?: string | null;

package/dist/credentials-ui.js

@@ -1,9 +1,11 @@
-import { TOKEN_DAYS } from "./api-tokens.js";
+import { daysLeft, expiryNoticeDue, TOKEN_DAYS, tokenLive } from "./api-tokens.js";
+import { projectName } from "./project.js";
 const e = (value) => String(value ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
 export const CREDENTIALS_CSS = `.credentials{max-width:820px;min-width:0}.credentials .card{padding:14px 16px;margin:12px 0}.credentials h2{font-size:1.05rem;margin:0 0 8px}` +
     `.credentials .rows{display:grid;gap:0;border:1px solid var(--so-line);border-radius:10px;overflow:hidden}.credentials .row-item{display:flex;align-items:center;justify-content:space-between;gap:12px;padding:10px 14px;border-bottom:1px solid var(--so-line)}` +
     `.credentials .row-item:last-child{border-bottom:0}.credentials .row-item p{margin:0}.credentials .row-item .meta{font-size:.85rem}.credentials form{margin:0}.credentials button{min-height:40px;white-space:nowrap}` +
     `.credentials .create{display:grid;gap:10px}.credentials .create label{display:grid;gap:6px}.credentials .create input,.credentials .create select{box-sizing:border-box;width:100%}.credentials .badge-here{font-size:.75rem;padding:1px 6px;border-radius:999px;background:var(--so-success-soft);color:var(--so-success);margin-left:6px}` +
+    `.credentials .row-item>div{min-width:0}.credentials .row-item p{overflow-wrap:anywhere}.credentials .soon{color:var(--so-warning,#9a6700);font-weight:600}` +
     `@media(max-width:600px){.credentials .row-item{flex-wrap:wrap}.credentials .create input,.credentials .create select{font-size:16px}}`;
 /** "Chrome on macOS", from a user agent, for a person to recognise a session. */
 export function deviceWords(agent) {
@@ -30,16 +32,26 @@ export function credentialsHtml(view, csrf, notice) {
         `${one.here ? "" : post({ action: "end-session", session: one.idHash }, "Sign out")}</div>`).join("")}</div>`;
     const others = view.sessions.filter(one => !one.here && one.account === view.who).length;
     const endOthers = others > 0 && !view.everyone ? post({ action: "end-others" }, `Sign out everywhere else (${others})`) : "";
-    const live = view.tokens.filter(one => one.revokedAt === null && Date.parse(one.expiresAt) > view.now);
+    const live = view.tokens.filter(one => tokenLive(one, view.now));
+    // v111: its projects, and one state: when it stops (soon, said once and marked) or, once replaced, when it ends.
+    const ends = (one) => {
+        if (one.replacedBy !== null && one.overlapUntil !== null)
+            return `<span class="soon">Replaced · stops ${e(one.overlapUntil.slice(11, 16))} UTC</span>`;
+        if (expiryNoticeDue(one, view.now) === null)
+            return `Expires ${e(one.expiresAt.slice(0, 10))}`;
+        const days = daysLeft(one.expiresAt, view.now);
+        return `<span class="soon">Expires ${days <= 1 ? "within a day" : `in ${days} days`}</span>`;
+    };
+    const scope = (one) => one.projects === null ? "All projects" : one.projects.length === 0 ? "No projects" : one.projects.map(repo => e(projectName(repo))).join(", ");
     const tokens = live.length === 0 ? `<p class="meta">No API tokens.</p>` : `<div class="rows">${live.map(one => `<div class="row-item" data-token="${e(one.id)}"><div><p>${view.everyone ? `<strong>${e(one.account)}</strong> · ` : ""}${e(one.name)} · ${one.access === "act" ? "Can act" : "Read only"}</p>` +
-        `<p class="meta">Expires ${e(one.expiresAt.slice(0, 10))} · last used ${e(when(one.lastUsedAt, view.now))}</p></div>${post({ action: "revoke-token", token: one.id }, "Revoke")}</div>`).join("")}</div>`;
+        `<p class="meta">${scope(one)} · ${ends(one)} · last used ${e(when(one.lastUsedAt, view.now))}${view.limits === undefined ? "" : ` · ${e(view.limits.note(one))}`}</p></div>${post({ action: "revoke-token", token: one.id }, "Revoke")}</div>`).join("")}</div>`;
     const create = `<details class="card"><summary>New API token</summary><form method="post" action="/settings/sessions" class="create">${hidden({ csrf, action: "create-token" })}` +
         `<label>Name<input type="text" name="name" maxlength="60" required placeholder="for example: CI"></label>` +
         `<label>It can<select name="access"><option value="read">Read (tasks, results, the ledger)</option><option value="act">Act as you (file and manage work; never approve)</option></select></label>` +
         `<label>Expires in<select name="days">${TOKEN_DAYS.map(days => `<option value="${days}"${days === 90 ? " selected" : ""}>${days} days</option>`).join("")}</select></label>` +
         `<label>Your Toolroll password<input type="password" name="password" autocomplete="current-password" required></label><button>Make the token</button></form></details>`;
     return `<section class="credentials">${note}${toggle}<h2>Signed in</h2>${sessions}${endOthers}<h2 style="margin-top:1.5rem">API tokens</h2>` +
-        `<p class="meta">For scripts and CI: send <code>Authorization: Bearer &lt;token&gt;</code>. A token can't approve anything.</p>${tokens}${view.everyone ? "" : create}</section>`;
+        `<p class="meta">For scripts and CI: send <code>Authorization: Bearer &lt;token&gt;</code>. A token can't approve anything.</p>${tokens}${view.everyone ? "" : create}${view.limits?.section ?? ""}</section>`;
 }
 /** The token, once: a focused page with no script. */
 export function tokenShownHtml(name, token, access, expiresAt) {

package/dist/desktop-update.d.ts

@@ -94,6 +94,7 @@ export declare function prepareDesktopUpdate(stateDir: string, installed: string
 export declare function sqliteLock(file: string, busyTimeoutMs?: number): DatabaseSync | null;
 export declare const installationLock: (j: UpdateJournal) => DatabaseSync | null;
 export declare function desktopUpdateStatus(stateDir: string): {
+    version?: never;
     active: boolean;
     phase: string;
     detail: string;
@@ -107,7 +108,6 @@ export declare function desktopUpdateStatus(stateDir: string): {
     wasRunning?: never;
     backupPath?: never;
     updateId?: never;
-    version?: never;
     buildId?: never;
     workDir?: never;
 } | {

package/dist/export.js

@@ -29,14 +29,14 @@ import { readEmailSettings } from "./email-settings.js";
 import { SUBSCRIPTION_CAPABLE, readAuthMode } from "./keys.js";
 export const EXPORT_FORMAT = "standing-orders/export/v1";
 /** Tables that hold nothing but secrets or short-lived sign-in material, and derived search indexes. */
-const SECRET_TABLES = new Set(["web_session", "ceremony_nonce", "telegram_pairing", "slack_pair", "discord_pair", "teams_pair"]);
+const SECRET_TABLES = new Set(["web_session", "ceremony_nonce", "telegram_pairing", "slack_pair", "discord_pair", "teams_pair", "oauth_code", "oauth_refresh"]);
 const DERIVED_TABLE = /^(sqlite_|memory_search)/;
 /** Columns that hold a secret (or what stands in for one): never exported. */
 const SECRET_COLUMNS = new Set([
     "api_token.secret_hash", "lead_credential.secret_hash", "approver.credential_hash", "coordinator_credential.credential_hash", "runner.credential_hash", "invite.token_hash",
     "flow_trigger.hook_hash", "held_session.cookie", "push_subscription.endpoint", "push_subscription.p256dh", "push_subscription.auth",
     "chat_turn.credential_key", "mate_session.credential_key", "mate_turn.credential_key", "bridge_lease.push_url", "workflow_preview.token",
-    "quota.credential_fp",
+    "quota.credential_fp", "oauth_grant.renew_hash", "oauth_client.source_hash",
 ]);
 /** A column named like this holds a secret unless it is reviewed below; an unreviewed one is dropped. */
 const SECRET_NAME = /hash|secret|token|passw|cookie|csrf|credential|p256dh|^auth$|key|nonce|endpoint|url/i;
@@ -56,7 +56,7 @@ export function categoryOf(table) {
         [/^teammate/, "teammates"],
         [/^(flow|routine|workflow_)/, "flows"],
         [/^(chat_|mate_|team_|telegram_|slack_|discord_|teams_|notification|push_|bridge_lease)/, "chats"],
-        [/^(approver|api_token|lead_credential|invite|sso_identity|coordinator_)/, "people"],
+        [/^(approver|api_token|lead_credential|invite|sso_identity|coordinator_|oauth_)/, "people"],
         [/^(run|artifact|claim|worktree$|execution_slot|contest|tournament_terms|fallback_cycle|fallback_transition|held_session|session_turn|attended_authorization|criterion_review|diff_comment|proof_|review_request|repair_chain|incident|publication$|merge_|side_spend|knowledge_snapshot|learning_snapshot|skill_snapshot)/, "runs"],
         [/^(task|hold$|plan_|scope_|tool_seal|decision|external_|skill_test)/, "tasks"],
         [/^(project|approval_policy|capability|verify_command|worktree_setup|backend_grant|intake_grant|publication_grant|operating_mode|knowledge_|learning_|memory_|skill_)/, "projects"],
@@ -67,6 +67,7 @@ export function categoryOf(table) {
 /** Extra shapes beside the evidence scanner's: this installation's own tokens and password hashes, and bearer headers. */
 const EXTRA_SHAPES = [
     /\bso_[a-f0-9]{12}_[A-Za-z0-9_-]{43}/g,
+    /\bsor_[a-f0-9]{12}_[A-Za-z0-9_-]{43}/g,
     /\blt_[a-f0-9]{12}_[A-Za-z0-9_-]{43}/g,
     /\bscrypt\$[^\s"',;]+/g,
     /\bBearer\s+[A-Za-z0-9._~+/-]{16,}=*/gi,