toolroll 0.9.44 → 0.9.46

package/dist/store.d.ts

@@ -2,6 +2,7 @@ import type { DecisionOption } from "./contracts/decision.js";
 import { type SavedToolAction, type SavedToolRule } from "./contracts/store-json.js";
 import type { FlowCardChange, FlowCardFields } from "./contracts/flow-card.js";
 import { type Actor } from "./actor.js";
+import { type TokenPurpose } from "./api-tokens.js";
 import { type CriterionMatrixRow, type CriterionJudgementWord } from "./proof.js";
 import { type ExecutionProfile, type ChainEntry, type UnattendedPermissionMode, type AcceptanceCriterion } from "./scope.js";
 import { type ProviderRoom, type CandidateTier, type TaskSize, type TaskSizing, type PhaseRoute, type PublicationAuthority, type RouteStamp, type ReadinessLookup, type ReadinessObservation, type RiskLevel, type RouteOverride } from "./phase-routing.js";
@@ -145,7 +146,7 @@ export type SealedLedgerEntry = LedgerEntry & {
         hash: string;
     } | null;
 };
-export declare const SCHEMA_VERSION = 110;
+export declare const SCHEMA_VERSION = 113;
 /**
  * The migrations `toolroll update` may carry a database through in place: each
  * one only adds (a table, a column, an accepted value) and leaves every saved row
@@ -155,11 +156,43 @@ export declare const SCHEMA_VERSION = 110;
  * migrates and does not read this list.
  *
  * v110 rebuilds action_ledger only to widen its source check ('api', 'mcp'):
- * every row, id and hash-chain link is copied unchanged.
+ * every row, id and hash-chain link is copied unchanged. v111 adds nullable
+ * api_token columns (project limit, rotation); existing tokens read as before.
+ * v112 only adds the two request-budget tables.
+ * v113 adds MCP sign-in tables and API-token purpose metadata.
  */
 export declare const UPDATE_SAFE_MIGRATIONS: readonly number[];
 /** Whether a database settled at `version` reaches this build's schema through update-safe migrations alone. */
 export declare function updateSafeSchema(version: number | null): boolean;
+export type OAuthClientRow = {
+    id: string;
+    name: string;
+    redirectUris: string[];
+    createdAt: string;
+};
+export type OAuthCodeRow = {
+    client: string;
+    account: string;
+    generation: number;
+    access: "read" | "act";
+    projects: string[];
+    redirectUri: string;
+    resource: string;
+    challenge: string;
+    expiresAt: string;
+    usedAt: string | null;
+    token: string | null;
+};
+export type OAuthGrantRow = {
+    token: string;
+    client: string;
+    account: string;
+    generation: number;
+    projects: string[];
+    resource: string;
+    accessExpiresAt: string;
+    refreshHash: string;
+};
 export type ApiTokenRow = {
     id: string;
     account: string;
@@ -171,6 +204,14 @@ export type ApiTokenRow = {
     lastUsedAt: string | null;
     revokedAt: string | null;
     revokedBy: string | null;
+    /** v113: MCP manages its own access-secret rotation. */
+    purpose: TokenPurpose;
+    /** v111: the projects it is limited to (null: every project its person may use). */
+    projects: string[] | null;
+    /** v111: the token it replaced, the one that replaced it, and when this one stops after being replaced. */
+    replaces: string | null;
+    replacedBy: string | null;
+    overlapUntil: string | null;
 };
 export type WebSessionRow = {
     idHash: string;
@@ -2591,7 +2632,26 @@ export declare class Store {
         access: "read" | "act";
         expiresAt: string;
         by: string;
+        projects?: readonly string[] | null;
+        purpose?: TokenPurpose;
     }, now: Date): void;
+    /**
+     * v111: replace a live, not-yet-replaced token with a new secret on the same terms (access, projects, end date, so
+     * rotating never extends it). The old one keeps working until `overlapUntil` (never past its own end), then stops;
+     * every check reads that time, and endRotatedApiTokens records the end afterwards. Only the token's own person.
+     */
+    rotateApiToken(oldId: string, replacement: {
+        id: string;
+        secretHash: string;
+    }, by: string, now: Date, overlapMs: number): {
+        ok: true;
+        row: ApiTokenRow;
+    } | {
+        ok: false;
+        reason: "unknown" | "replaced" | "mcp-managed";
+    };
+    /** v111: record the end of each replaced token whose overlap has passed (it already signs no one in). */
+    endRotatedApiTokens(now: Date): number;
     /** A token by id with its kept hash (for the check), or null. */
     apiTokenSecret(id: string): {
         row: ApiTokenRow;
@@ -2602,6 +2662,62 @@ export declare class Store {
     /** Kept at most once a minute: a busy script doesn't write on every request. */
     touchApiToken(id: string, now: Date): void;
     revokeApiToken(id: string, by: string, now: Date, why?: string): boolean;
+    /** A registered client, or null. */
+    oauthClient(id: string): OAuthClientRow | null;
+    /** Expire unused registrations, retaining clients with a live code, grant or in-process consent. */
+    pruneOAuthClients(now: Date, pending?: readonly string[]): void;
+    /**
+     * Unused registrations expire after a day. Admission has a global and per-source bound; it never evicts a live
+     * registration. Repeating metadata from the same source returns its existing registration without spending a slot.
+     */
+    registerOAuthClient(client: {
+        id: string;
+        name: string;
+        redirectUris: string[];
+        source: string;
+    }, now: Date, cap: number, perSourceCap: number, pending?: readonly string[]): OAuthClientRow | null;
+    /** Keep a one-time code by its hash. */
+    saveOAuthCode(hash: string, code: Omit<OAuthCodeRow, "usedAt" | "token">): void;
+    /**
+     * Spend a code: the first caller gets it (`taken`), once, before it expires. A code spent before answers `used`
+     * with the token it made, so that token can be ended; anything else is null.
+     */
+    takeOAuthCode(hash: string, now: Date): {
+        taken: OAuthCodeRow;
+    } | {
+        used: string | null;
+    } | null;
+    /** Make a grant: its API token (created and recorded as any other) and its binding, together; the code notes the token. */
+    createOAuthGrant(code: string, token: {
+        id: string;
+        account: string;
+        name: string;
+        secretHash: string;
+        access: "read" | "act";
+        expiresAt: string;
+    }, grant: Omit<OAuthGrantRow, "token">, now: Date): void;
+    /** The grant an API token signs in for, or null when the token is an ordinary one. */
+    oauthGrant(token: string): OAuthGrantRow | null;
+    /**
+     * Classify, validate and rotate under one write transaction. Every issued hash remains in the family, so any
+     * older secret revokes even a concurrent winner. An unknown guess or the wrong client cannot end the family.
+     */
+    rotateOAuthGrant(token: string, ask: {
+        client: string;
+        resource: string;
+        refreshHash: string;
+        scope?: string;
+    }, next: {
+        refreshHash: string;
+        accessHash: string;
+        accessExpiresAt: string;
+    }, now: Date, projectsFor: (account: string) => readonly string[]): {
+        ok: true;
+        access: "read" | "act";
+    } | {
+        ok: false;
+        reason: "invalid_grant" | "invalid_scope";
+    };
     saveWebSession(session: WebSessionRow): void;
     webSession(idHash: string): WebSessionRow | null;
     webSessions(account: string | null): WebSessionRow[];

package/dist/store.js

@@ -12,6 +12,7 @@ import { cardOutputsForStore, cardOutputsFromStore } from "./contracts/stage-out
 import { chatControlHref, chatResultHref } from "./chat-controls.js";
 import { actorLabel, currentActor, leadSecretMatches, mintLeadToken, parseLeadToken } from "./actor.js";
 import { scanForSecrets } from "./evidence.js";
+import { tokenPurpose, tokenRotationProblem } from "./api-tokens.js";
 /**
  * The database: a small task store, and the operational overlay beside it.
  *
@@ -69,6 +70,7 @@ import { PLAN_AUTO_SCHEMA } from "./plan-auto.js";
 import { RECIPE_SCHEMA } from "./recipes.js";
 import { POLICY_SCHEMA, agentRefusal, approvalRefusal, attendedRefusal, policyParts, readPolicy, underCeiling, sessionCeilingRefusal } from "./policy.js";
 import { PROVIDER_AUTH_SCHEMA } from "./provider-auth.js";
+import { REQUEST_BUDGET_SCHEMA } from "./request-budget.js";
 import { REVIEW_SCHEMA, reviewSwitchWords } from "./review-switch.js";
 import { SPEND_SCHEMA, billingOf, budgetStates, canPrice, claudeMachineBilling, countsToward, filersOf, monthOf, priceWork, seenBilling as seenBillingOf, spendItems, teammateFilers, usd } from "./spend.js";
 import { DEFAULT_PERIODS, RETENTION_SCHEMA, periodWords, widenRetentionSchema } from "./retention.js";
@@ -564,7 +566,10 @@ const REGISTERED_AT_FILING = "again, as it was filed";
 // v108 keeps sign-in pauses: one incident per provider whose sign-in stopped working (provider_auth_pause).
 // v109 remembers which sign-in pause parked a task (task_ref.auth_wait_pause), so reviews and other runs outside the tick wait for it too.
 // v110 lets the action ledger record commands a person ran on this server with their API token (source 'api', or 'mcp' from their agent).
-export const SCHEMA_VERSION = 110;
+// v111 keeps an API token's project limit and its rotation: the token that replaced it, and when the old one stops.
+// v112 keeps request budgets for API tokens: owner overrides (request_budget_limit) and saved usage (request_budget_usage).
+// v113 keeps MCP sign-ins (OAuth): registered clients, one-time codes, and each grant's binding to its API token.
+export const SCHEMA_VERSION = 113;
 /**
  * The migrations `toolroll update` may carry a database through in place: each
  * one only adds (a table, a column, an accepted value) and leaves every saved row
@@ -574,9 +579,12 @@ export const SCHEMA_VERSION = 110;
  * migrates and does not read this list.
  *
  * v110 rebuilds action_ledger only to widen its source check ('api', 'mcp'):
- * every row, id and hash-chain link is copied unchanged.
+ * every row, id and hash-chain link is copied unchanged. v111 adds nullable
+ * api_token columns (project limit, rotation); existing tokens read as before.
+ * v112 only adds the two request-budget tables.
+ * v113 adds MCP sign-in tables and API-token purpose metadata.
  */
-export const UPDATE_SAFE_MIGRATIONS = Object.freeze([110]);
+export const UPDATE_SAFE_MIGRATIONS = Object.freeze([110, 111, 112, 113]);
 /** Whether a database settled at `version` reaches this build's schema through update-safe migrations alone. */
 export function updateSafeSchema(version) {
     if (version === null || !Number.isSafeInteger(version) || version <= 0 || version > SCHEMA_VERSION)
@@ -643,6 +651,58 @@ CREATE TABLE IF NOT EXISTS web_session (
 );
 CREATE INDEX IF NOT EXISTS web_session_account ON web_session (account);
 `;
+/**
+ * v113: MCP sign-in (OAuth 2.1, mcp-oauth.ts). A registered client, a one-time code (its hash, a minute at most), and
+ * each grant: the ordinary API token it signs in with (revoked like any other), the account generation and exact
+ * projects the person chose, and every issued refresh-secret hash (any replay ends the whole family).
+ */
+const OAUTH_SCHEMA = `
+CREATE TABLE IF NOT EXISTS oauth_client (
+  id            TEXT PRIMARY KEY,
+  name          TEXT NOT NULL,
+  redirect_json TEXT NOT NULL,
+  created_at    TEXT NOT NULL,
+  source_hash   TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS oauth_client_source ON oauth_client (source_hash);
+CREATE TABLE IF NOT EXISTS oauth_code (
+  hash         TEXT PRIMARY KEY,
+  client       TEXT NOT NULL REFERENCES oauth_client(id),
+  account      TEXT NOT NULL,
+  generation   INTEGER NOT NULL,
+  access       TEXT NOT NULL CHECK (access IN ('read','act')),
+  projects_json TEXT NOT NULL,
+  redirect_uri TEXT NOT NULL,
+  resource     TEXT NOT NULL,
+  challenge    TEXT NOT NULL,
+  expires_at   TEXT NOT NULL,
+  used_at      TEXT,
+  token        TEXT
+);
+CREATE TABLE IF NOT EXISTS oauth_grant (
+  token              TEXT PRIMARY KEY REFERENCES api_token(id),
+  client             TEXT NOT NULL REFERENCES oauth_client(id),
+  account            TEXT NOT NULL,
+  generation         INTEGER NOT NULL,
+  projects_json      TEXT NOT NULL,
+  resource           TEXT NOT NULL,
+  access_expires_at  TEXT NOT NULL,
+  renew_hash       TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS oauth_grant_client ON oauth_grant (client);
+CREATE TABLE IF NOT EXISTS oauth_refresh (
+  token TEXT NOT NULL REFERENCES oauth_grant(token),
+  hash  TEXT NOT NULL,
+  PRIMARY KEY (token, hash)
+);
+`;
+const stringList = (raw) => { try {
+    const value = JSON.parse(String(raw));
+    return Array.isArray(value) && value.every((one) => typeof one === "string") ? value : [];
+}
+catch {
+    return [];
+} };
 /** v100: which account each identity-provider identity (issuer + subject) signs in as. */
 const SSO_SCHEMA = `
 CREATE TABLE IF NOT EXISTS sso_identity (
@@ -4013,6 +4073,14 @@ function initializeStore(db, file) {
     db.exec(TEAM_SCHEMA);
     db.exec(SSO_SCHEMA);
     db.exec(CREDENTIALS_SCHEMA);
+    // v111: a token's project limit (null: every project its person may use) and its rotation.
+    addColumn(db, "api_token", "projects_json", "TEXT");
+    addColumn(db, "api_token", "replaces", "TEXT");
+    addColumn(db, "api_token", "replaced_by", "TEXT");
+    addColumn(db, "api_token", "overlap_until", "TEXT");
+    // v113: MCP sign-in (OAuth), and whether a token is an ordinary one or an MCP sign-in's.
+    db.exec(OAUTH_SCHEMA);
+    addColumn(db, "api_token", "purpose", "TEXT NOT NULL DEFAULT 'api' CHECK (purpose IN ('api','mcp'))");
     db.exec(APPROVAL_SCHEMA);
     db.exec(LEDGER_CHAIN_SCHEMA);
     db.exec(MONITORING_SCHEMA);
@@ -4028,6 +4096,8 @@ function initializeStore(db, file) {
     db.exec(SPEND_SCHEMA);
     // Sign-in pauses: one row per incident of a provider's sign-in no longer working.
     db.exec(PROVIDER_AUTH_SCHEMA);
+    // v112: request budgets for API tokens (request-budget.ts).
+    db.exec(REQUEST_BUDGET_SCHEMA);
     // The sign-in pause the dispatch gate last left this task waiting on (null: none), for the work index.
     addColumn(db, "task_ref", "auth_wait_pause", "INTEGER REFERENCES provider_auth_pause(id)");
     // Sized routing (no version bump: additive, and a wider tier check whose rows carry over): how big each task is,
@@ -5547,7 +5617,20 @@ function rebuildExact(db, table, oldDdl, targetDdl, columns) {
 function readApiToken(row) {
     const text = (key) => row[key] == null ? null : String(row[key]);
     return { id: String(row["id"]), account: String(row["account"]), name: String(row["name"]), access: row["access"] === "act" ? "act" : "read", createdAt: String(row["created_at"]), createdBy: String(row["created_by"]),
-        expiresAt: String(row["expires_at"]), lastUsedAt: text("last_used_at"), revokedAt: text("revoked_at"), revokedBy: text("revoked_by") };
+        expiresAt: String(row["expires_at"]), lastUsedAt: text("last_used_at"), revokedAt: text("revoked_at"), revokedBy: text("revoked_by"),
+        purpose: tokenPurpose(row["purpose"]), projects: tokenProjectsOf(row["projects_json"]), replaces: text("replaces"), replacedBy: text("replaced_by"), overlapUntil: text("overlap_until") };
+}
+/** A token's stored project limit. Anything unreadable limits it to no project at all: never wider. */
+function tokenProjectsOf(value) {
+    if (value == null)
+        return null;
+    try {
+        const parsed = JSON.parse(String(value));
+        return Array.isArray(parsed) && parsed.every(one => typeof one === "string") ? parsed : [];
+    }
+    catch {
+        return [];
+    }
 }
 function readWebSession(row) {
     return { idHash: String(row["id_hash"]), account: String(row["account"]), csrf: String(row["csrf"]), role: row["role"] === "viewer" ? "viewer" : "approver", generation: Number(row["generation"]),
@@ -9808,12 +9891,45 @@ export class Store {
     // ---- API tokens and browser sessions (v101) ------------------------------
     createApiToken(token, now) {
         this.transact(() => {
-            this.db.prepare("INSERT INTO api_token (id, account, name, secret_hash, access, created_at, created_by, expires_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)")
-                .run(token.id, token.account, token.name, token.secretHash, token.access, now.toISOString(), token.by, token.expiresAt);
+            const projects = token.projects ?? null;
+            this.db.prepare("INSERT INTO api_token (id, account, name, secret_hash, access, created_at, created_by, expires_at, projects_json, purpose) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)")
+                .run(token.id, token.account, token.name, token.secretHash, token.access, now.toISOString(), token.by, token.expiresAt, projects === null ? null : JSON.stringify(projects), token.purpose ?? "api");
             this.recordAction({ at: now.toISOString(), actor: token.by, repo: null, taskId: null, runId: null, action: `API token created: ${token.name}`, outcome: token.access, source: "access",
-                detail: `for ${token.account}, until ${token.expiresAt.slice(0, 10)}` });
+                detail: `for ${token.account}, until ${token.expiresAt.slice(0, 10)}${projects === null ? "" : ` · ${projects.length === 0 ? "no projects" : projects.join(", ")}`} · id ${token.id}` });
+        });
+    }
+    /**
+     * v111: replace a live, not-yet-replaced token with a new secret on the same terms (access, projects, end date, so
+     * rotating never extends it). The old one keeps working until `overlapUntil` (never past its own end), then stops;
+     * every check reads that time, and endRotatedApiTokens records the end afterwards. Only the token's own person.
+     */
+    rotateApiToken(oldId, replacement, by, now, overlapMs) {
+        return this.transact(() => {
+            const old = this.apiTokenSecret(oldId)?.row ?? null;
+            const at = now.getTime();
+            if (old === null || old.account !== by || old.revokedAt !== null || !(Date.parse(old.expiresAt) > at) || old.overlapUntil !== null && !(Date.parse(old.overlapUntil) > at))
+                return { ok: false, reason: "unknown" };
+            if (tokenRotationProblem(old) !== null || this.oauthGrant(oldId) !== null)
+                return { ok: false, reason: "mcp-managed" };
+            if (old.replacedBy !== null)
+                return { ok: false, reason: "replaced" };
+            const stamp = now.toISOString();
+            const until = new Date(Math.min(at + Math.max(0, overlapMs), Date.parse(old.expiresAt))).toISOString();
+            this.db.prepare("INSERT INTO api_token (id, account, name, secret_hash, access, created_at, created_by, expires_at, projects_json, replaces) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)")
+                .run(replacement.id, old.account, old.name, replacement.secretHash, old.access, stamp, by, old.expiresAt, old.projects === null ? null : JSON.stringify(old.projects), old.id);
+            this.db.prepare("UPDATE api_token SET replaced_by = ?, overlap_until = ? WHERE id = ? AND replaced_by IS NULL").run(replacement.id, until, old.id);
+            this.recordAction({ at: stamp, actor: by, repo: null, taskId: null, runId: null, action: `API token rotated: ${old.name}`, outcome: old.access, source: "access",
+                detail: `${old.account}'s · id ${old.id} → ${replacement.id}, the old one stops ${until.slice(0, 16).replace("T", " ")} UTC` });
+            return { ok: true, row: this.apiTokenSecret(replacement.id).row };
         });
     }
+    /** v111: record the end of each replaced token whose overlap has passed (it already signs no one in). */
+    endRotatedApiTokens(now) {
+        const due = this.db.prepare("SELECT id, overlap_until FROM api_token WHERE revoked_at IS NULL AND overlap_until IS NOT NULL AND overlap_until <= ?").all(now.toISOString());
+        for (const row of due)
+            this.revokeApiToken(String(row["id"]), "system", new Date(String(row["overlap_until"])), "replaced; its overlap ended");
+        return due.length;
+    }
     /** A token by id with its kept hash (for the check), or null. */
     apiTokenSecret(id) {
         const row = this.db.prepare("SELECT * FROM api_token WHERE id = ?").get(id);
@@ -9837,6 +9953,119 @@ export class Store {
             return true;
         });
     }
+    // ---- MCP sign-in (v113, mcp-oauth.ts) ---------------------------------------------------------------------------
+    /** A registered client, or null. */
+    oauthClient(id) {
+        const row = this.db.prepare("SELECT * FROM oauth_client WHERE id = ?").get(id);
+        return row === undefined ? null : { id: String(row["id"]), name: String(row["name"]), redirectUris: stringList(row["redirect_json"]), createdAt: String(row["created_at"]) };
+    }
+    /** Expire unused registrations, retaining clients with a live code, grant or in-process consent. */
+    pruneOAuthClients(now, pending = []) {
+        this.transact(() => {
+            const stale = new Date(now.getTime() - 86_400_000).toISOString();
+            this.db.prepare("DELETE FROM oauth_code WHERE expires_at <= ?").run(now.toISOString());
+            this.db.prepare(`DELETE FROM oauth_client WHERE created_at <= ? AND id NOT IN (SELECT client FROM oauth_grant)
+        AND id NOT IN (SELECT client FROM oauth_code) AND id NOT IN (SELECT value FROM json_each(?))`).run(stale, JSON.stringify(pending));
+        });
+    }
+    /**
+     * Unused registrations expire after a day. Admission has a global and per-source bound; it never evicts a live
+     * registration. Repeating metadata from the same source returns its existing registration without spending a slot.
+     */
+    registerOAuthClient(client, now, cap, perSourceCap, pending = []) {
+        return this.transact(() => {
+            const redirectJson = JSON.stringify(client.redirectUris);
+            this.pruneOAuthClients(now, pending);
+            const same = this.db.prepare("SELECT id FROM oauth_client WHERE name = ? AND redirect_json = ? AND source_hash = ?").get(client.name, redirectJson, client.source);
+            if (same !== undefined)
+                return this.oauthClient(String(same["id"]));
+            const unused = "FROM oauth_client WHERE id NOT IN (SELECT client FROM oauth_grant)";
+            if (Number(this.db.prepare(`SELECT COUNT(*) AS n ${unused}`).get()?.["n"] ?? 0) >= cap
+                || Number(this.db.prepare(`SELECT COUNT(*) AS n ${unused} AND source_hash = ?`).get(client.source)?.["n"] ?? 0) >= perSourceCap)
+                return null;
+            this.db.prepare("INSERT INTO oauth_client (id, name, redirect_json, created_at, source_hash) VALUES (?, ?, ?, ?, ?)").run(client.id, client.name, redirectJson, now.toISOString(), client.source);
+            return this.oauthClient(client.id);
+        });
+    }
+    /** Keep a one-time code by its hash. */
+    saveOAuthCode(hash, code) {
+        this.db.prepare("INSERT INTO oauth_code (hash, client, account, generation, access, projects_json, redirect_uri, resource, challenge, expires_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)")
+            .run(hash, code.client, code.account, code.generation, code.access, JSON.stringify(code.projects), code.redirectUri, code.resource, code.challenge, code.expiresAt);
+    }
+    /**
+     * Spend a code: the first caller gets it (`taken`), once, before it expires. A code spent before answers `used`
+     * with the token it made, so that token can be ended; anything else is null.
+     */
+    takeOAuthCode(hash, now) {
+        return this.transact(() => {
+            const row = this.db.prepare("SELECT * FROM oauth_code WHERE hash = ?").get(hash);
+            if (row === undefined)
+                return null;
+            if (row["used_at"] !== null)
+                return { used: row["token"] === null ? null : String(row["token"]) };
+            this.db.prepare("UPDATE oauth_code SET used_at = ? WHERE hash = ? AND used_at IS NULL").run(now.toISOString(), hash);
+            if (String(row["expires_at"]) <= now.toISOString())
+                return null;
+            return { taken: { client: String(row["client"]), account: String(row["account"]), generation: Number(row["generation"]), access: row["access"] === "act" ? "act" : "read", projects: stringList(row["projects_json"]),
+                    redirectUri: String(row["redirect_uri"]), resource: String(row["resource"]), challenge: String(row["challenge"]), expiresAt: String(row["expires_at"]), usedAt: null, token: null } };
+        });
+    }
+    /** Make a grant: its API token (created and recorded as any other) and its binding, together; the code notes the token. */
+    createOAuthGrant(code, token, grant, now) {
+        this.transact(() => {
+            this.createApiToken({ ...token, by: token.account, projects: grant.projects, purpose: "mcp" }, now);
+            this.db.prepare("INSERT INTO oauth_grant (token, client, account, generation, projects_json, resource, access_expires_at, renew_hash) VALUES (?, ?, ?, ?, ?, ?, ?, ?)")
+                .run(token.id, grant.client, grant.account, grant.generation, JSON.stringify(grant.projects), grant.resource, grant.accessExpiresAt, grant.refreshHash);
+            this.db.prepare("INSERT INTO oauth_refresh (token, hash) VALUES (?, ?)").run(token.id, grant.refreshHash);
+            this.db.prepare("UPDATE oauth_code SET token = ? WHERE hash = ?").run(token.id, code);
+        });
+    }
+    /** The grant an API token signs in for, or null when the token is an ordinary one. */
+    oauthGrant(token) {
+        const row = this.db.prepare("SELECT * FROM oauth_grant WHERE token = ?").get(token);
+        return row === undefined ? null : { token: String(row["token"]), client: String(row["client"]), account: String(row["account"]), generation: Number(row["generation"]), projects: stringList(row["projects_json"]),
+            resource: String(row["resource"]), accessExpiresAt: String(row["access_expires_at"]), refreshHash: String(row["renew_hash"]) };
+    }
+    /**
+     * Classify, validate and rotate under one write transaction. Every issued hash remains in the family, so any
+     * older secret revokes even a concurrent winner. An unknown guess or the wrong client cannot end the family.
+     */
+    rotateOAuthGrant(token, ask, next, now, projectsFor) {
+        return this.transact(() => {
+            const invalid = { ok: false, reason: "invalid_grant" };
+            const grant = this.oauthGrant(token), kept = this.apiTokenSecret(token)?.row;
+            if (grant === null || kept === undefined || grant.client !== ask.client || grant.resource !== ask.resource)
+                return invalid;
+            const issued = this.db.prepare("SELECT 1 FROM oauth_refresh WHERE token = ? AND hash = ?").get(token, ask.refreshHash);
+            if (issued === undefined)
+                return invalid;
+            if (grant.refreshHash !== ask.refreshHash) {
+                this.revokeApiToken(token, "toolroll", now, "its refresh secret was used twice");
+                return invalid;
+            }
+            if (kept.revokedAt !== null || !(Date.parse(kept.expiresAt) > now.getTime()))
+                return invalid;
+            const account = this.accountOf(grant.account);
+            if (account === null || account.revokedAt !== null || account.generation !== grant.generation || (kept.access === "act" && account.role !== "approver")) {
+                this.revokeApiToken(token, "toolroll", now, "the person's sign-in changed");
+                return invalid;
+            }
+            const mine = projectsFor(grant.account);
+            if (!grant.projects.some(project => mine.includes(project) && (kept.projects === null || kept.projects.includes(project)))) {
+                this.revokeApiToken(token, "toolroll", now, "its projects are no longer the person's");
+                return invalid;
+            }
+            if (ask.scope !== undefined && !ask.scope.split(" ").every(one => one === kept.access || one === "read"))
+                return { ok: false, reason: "invalid_scope" };
+            const moved = this.db.prepare("UPDATE oauth_grant SET renew_hash = ?, access_expires_at = ? WHERE token = ? AND renew_hash = ?")
+                .run(next.refreshHash, next.accessExpiresAt, token, ask.refreshHash);
+            if (Number(moved.changes) !== 1)
+                return invalid;
+            this.db.prepare("UPDATE api_token SET secret_hash = ? WHERE id = ? AND revoked_at IS NULL").run(next.accessHash, token);
+            this.db.prepare("INSERT INTO oauth_refresh (token, hash) VALUES (?, ?)").run(token, next.refreshHash);
+            return { ok: true, access: kept.access };
+        });
+    }
     saveWebSession(session) {
         this.db.prepare(`INSERT INTO web_session (id_hash, account, csrf, role, generation, created_at, last_seen, project, project_revision, sso_at, agent, address) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       ON CONFLICT(id_hash) DO UPDATE SET last_seen = excluded.last_seen, project = excluded.project, project_revision = excluded.project_revision, sso_at = excluded.sso_at`)

package/dist/surface.js

@@ -135,6 +135,16 @@ const GUIDE_ROWS = [
     { invocation: "brief", synopsis: "with a saved central profile, --lead <id> --conversation <id> reads messages, proposals and saved work; --request-id inspects your saved receipt without resending; --local uses local DB catch-up, where --history selects the older operational report", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
     { invocation: "gaps", synopsis: "requirement gaps blocking dispatch", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag, repoFlag] },
     { invocation: "grants", synopsis: "list authority grants", audience: "agent", agentMayInvoke: true, mutation: "none", flags: [jsonFlag, dbFlag] },
+    { invocation: "audit", synopsis: "what people did on this server with their API tokens, newest first: when, who, which token, from the CLI (api) or an agent (mcp), the command or tool, the project and the outcome (ok, refused, error); an approver sees everyone in their projects, anyone else only themselves",
+        audience: "agent", agentMayInvoke: true, mutation: "none",
+        flags: [jsonFlag, dbFlag,
+            { name: "person", takesValue: true, meaning: "only this person's actions" },
+            { name: "token", takesValue: true, meaning: "only actions with the token of this name (on the server's own machine)" },
+            { name: "token-name", takesValue: true, meaning: "the same, where --token would be a credential (remotely)" },
+            { name: "source", takesValue: true, meaning: "api (the CLI) or mcp (an agent)" },
+            { name: "since", takesValue: true, meaning: "only the last N days, as Nd (7d)" },
+            { name: "limit", takesValue: true, meaning: "actions per page (default 20, at most 100)" },
+            { name: "cursor", takesValue: true, meaning: "the nextCursor of the previous page" }] },
     { invocation: "sync", synopsis: "refresh external-tracker mirrors and deliver write-backs — safe to run; fails closed", audience: "agent", agentMayInvoke: true, mutation: "identity-idempotent",
         flags: [jsonFlag, dbFlag, repoFlag], notableReasons: ["no-op", "external"] },
     { invocation: "task add", synopsis: "queue work", audience: "agent", agentMayInvoke: true, mutation: "keyed",
@@ -377,6 +387,10 @@ const GUIDE_ROWS = [
     operator("people invite", "mint a single-use sign-in link for one person — their powers are pinned when you mint, never after"),
     operator("people projects", "set a person's project access — selected project, all projects, or no projects"),
     operator("people revoke", "end a person's access — their sessions, invites, and signed modes end with them; history stays"),
+    operator("tokens create", "make one of your API tokens: --name, --access read|act, --days 30|90|365, optional --projects a,b; your password at the prompt or --password-stdin; the token is shown once"),
+    operatorRead("tokens list", "your API tokens: name, access, projects, made, last used, expiry — never a secret; your password at the prompt or --password-stdin"),
+    operator("tokens revoke", "end one of your API tokens now, by name or id; your password at the prompt or --password-stdin"),
+    operator("tokens rotate", "replace one of your API tokens on the same terms; the old one works 10 more minutes (--overlap), then stops; the new one is shown once"),
     operatorRead("mode show", "the repository's operating mode, in full — or 'locked' when none is signed"),
     operator("mode set", "sign a per-repository operating mode (password ceremony; standard or hands-off, always expiring)"),
     operator("publish merge", "say yes to ONE waiting merge — it fires only when CI is seen green on the exact commit you authorized"),
@@ -411,6 +425,7 @@ const GUIDE_ROWS = [
     operator("publish unblock", "lift a repair's merge hold"),
     operator("publish rearm", "re-arm a refused merge after fixing the named cause"),
     operator("serve", "the operations console (HTTP)"),
+    operatorRead("serve check-public", "is this server ready on its --public-url? checks the URL, --allow-host, the console on --port, the certificate, HSTS and the proxy, and names each problem; sends no credentials"),
     operator("watch", "the unattended loop, kept running"),
     operator("up", "console + worker + browser, one command"),
     operator("onboard", "add this repository, report signed-in agents, install or --remove the operator skill (--yes), offer the starter flows (--starter <ids>), and print the handoff"),
@@ -436,7 +451,7 @@ const REMOTE_NO = [
     // Workers, the loop and the services that run here.
     "claim", "heartbeat", "release", "reap", "tick", "build", "reconcile",
     "runner register", "runner retire", "runner bind", "runner capacity", "coordinator mint", "coordinator revoke", "mcp", "outbox deliver", "peek",
-    "serve", "watch", "up", "onboard", "daemon", "bridge", "setup show", "setup clear",
+    "serve", "serve check-public", "watch", "up", "onboard", "daemon", "bridge", "setup show", "setup clear",
     // Provider keys and model tools on this machine.
     "providers", "keys status", "keys set", "keys clear", "keys verify", "keys auth", "models check", "models update", "models watch",
     // Publication and release.
@@ -452,11 +467,13 @@ const REMOTE_STEP_UP = [
     "proposals", "decide", "task regate", "task approve", "task accept", "task merge", "run settle", "routine approve", "knowledge apply", "memory apply",
     "flows card approve", "flows card send-back", "flows script approve",
     "approver list", "approver add", "people list", "people invite", "people projects", "people revoke",
+    // A person's own API tokens: a password step-up on the server's machine, or the console. Never with a token.
+    "tokens create", "tokens list", "tokens revoke", "tokens rotate",
     "mode show", "mode set", "mode revoke", "chat-approval on", "review on", "review off", "config set", "config clear",
     "verify set", "verify clear", "verify level", "project checks", "project concurrency", "intake grant", "intake clear", "webhook primary",
 ];
 const REMOTE_YES = [
-    "status", "integrations", "ready", "gaps", "grants", "sync",
+    "status", "integrations", "ready", "gaps", "grants", "sync", "audit",
     "task add", "task ask", "task checks", "task add-tests", "task list", "task show", "check-progress", "task wait", "task complete", "task revise",
     "task state", "task block", "task unblock", "task next", "task steer", "task assign", "task scope", "task plan", "task hold", "task unhold", "task require",
     "task requeue", "task review", "task repair", "task route", "task reopen", "task stop", "task resume",

package/dist/token-notices.d.ts

@@ -0,0 +1,22 @@
+/**
+ * API token notices (v111): 7 days and 1 day before a token expires, its person is told once each, in their own chats
+ * and browsers (a personal notification), and the ledger keeps it. Only the nearest notice newly due is sent, so a
+ * token made with a day left says so once. Replaced and revoked tokens get none. The same pass records the end of each
+ * rotated token whose overlap has passed; it already signs no one in (tokenLive), so a late pass grants nothing.
+ */
+import { tokenLive } from "./api-tokens.js";
+import type { Store } from "./store.js";
+export declare const TOKEN_NOTICE_KIND = "api-token-expiry";
+export declare function tokenNoticePass(store: Store, now: Date): {
+    sent: {
+        token: string;
+        days: number;
+    }[];
+    ended: number;
+};
+/** Whether a token's console card warns that it expires soon (within the first notice's days). */
+export declare function expiresSoon(token: Parameters<typeof tokenLive>[0] & {
+    replacedBy: string | null;
+}, now: number): boolean;
+/** The loop beside the console: a pass a minute. */
+export declare function startTokenNotices(store: Store, everyMs?: number): () => void;

package/dist/token-notices.js

@@ -0,0 +1,52 @@
+/**
+ * API token notices (v111): 7 days and 1 day before a token expires, its person is told once each, in their own chats
+ * and browsers (a personal notification), and the ledger keeps it. Only the nearest notice newly due is sent, so a
+ * token made with a day left says so once. Replaced and revoked tokens get none. The same pass records the end of each
+ * rotated token whose overlap has passed; it already signs no one in (tokenLive), so a late pass grants nothing.
+ */
+import { expiryNoticeDue, EXPIRY_NOTICE_DAYS, tokenLive } from "./api-tokens.js";
+export const TOKEN_NOTICE_KIND = "api-token-expiry";
+export function tokenNoticePass(store, now) {
+    const ended = store.endRotatedApiTokens(now);
+    const sent = [];
+    const at = now.getTime();
+    for (const token of store.apiTokens(null)) {
+        const days = expiryNoticeDue(token, at);
+        if (days === null)
+            continue;
+        const key = (one) => `${TOKEN_NOTICE_KIND}:${token.id}:${one}`;
+        // A nearer notice already sent covers this one.
+        if (EXPIRY_NOTICE_DAYS.filter(one => one <= days).some(one => store.handle.prepare("SELECT 1 AS hit FROM notification WHERE dedupe_key = ?").get(key(one)) !== undefined))
+            continue;
+        const fresh = store.enqueueNotification({
+            dedupeKey: key(days), kind: TOKEN_NOTICE_KIND, pushClass: "attention", link: "/settings/sessions", recipient: token.account,
+            subject: `Your API token ${token.name} expires ${days === 1 ? "tomorrow" : `in ${days} days`}`,
+            body: `It stops working ${token.expiresAt.slice(0, 16).replace("T", " ")} UTC. Rotate it with toolroll tokens rotate, or make a new one in Settings → Sessions & tokens.`,
+            source: { installation: true },
+        }, now);
+        if (!fresh)
+            continue;
+        store.recordAction({ at: now.toISOString(), actor: "system", repo: null, taskId: null, runId: null, action: `API token expiry notice: ${token.name}`, outcome: "notified", source: "access",
+            detail: `${token.account}'s · id ${token.id} · ${days} day${days === 1 ? "" : "s"} left` });
+        sent.push({ token: token.id, days });
+    }
+    return { sent, ended };
+}
+/** Whether a token's console card warns that it expires soon (within the first notice's days). */
+export function expiresSoon(token, now) {
+    return expiryNoticeDue(token, now) !== null;
+}
+/** The loop beside the console: a pass a minute. */
+export function startTokenNotices(store, everyMs = 60_000) {
+    let stopped = false;
+    const tick = () => { if (stopped)
+        return; try {
+        tokenNoticePass(store, new Date());
+    }
+    catch { /* the next pass tries again */ } };
+    const timer = setInterval(tick, everyMs);
+    timer.unref?.();
+    const first = setTimeout(tick, 5_000);
+    first.unref?.();
+    return () => { stopped = true; clearInterval(timer); clearTimeout(first); };
+}

package/dist/tokens-cli.d.ts

@@ -0,0 +1,21 @@
+import type { Store } from "./store.js";
+export declare const TOKENS_ACTIONS: readonly ["create", "list", "revoke", "rotate"];
+/** The most a piped password may be: a password, not a file. */
+export declare const PASSWORD_STDIN_BYTES = 4096;
+export type TokensCliContext = {
+    store: Store;
+    write: (line: string) => void;
+    json: boolean;
+    clock: () => Date;
+    /** Who runs this: a remote caller (an API token, over /api/cli or /mcp) and the lead never manage tokens. */
+    caller: "local" | "remote" | "lead";
+    /** The remembered local login's name only (never its password): the default for --as. */
+    rememberedName: string | null;
+    /** Whether someone is at this terminal to answer a prompt. */
+    interactive: () => boolean;
+    ask: (question: string) => Promise<string>;
+    askHidden: (question: string) => Promise<string>;
+    /** Standard input, read whole up to `limit` bytes; null past the limit. */
+    readStdin: (limit: number) => Promise<string | null>;
+};
+export declare function runTokensCommand(positional: readonly string[], flags: ReadonlyMap<string, string | true>, context: TokensCliContext): Promise<number>;