toolroll 0.9.44 → 0.9.46

package/dist/public-check.js

@@ -0,0 +1,170 @@
+/**
+ * `toolroll serve check-public` (remote team, phase 3): is this server ready to be reached on its real domain?
+ * Read-only: it sends no credentials, follows no redirects and changes nothing. It checks the --public-url and
+ * --allow-host values, asks the console on this computer what it does with relayed requests, then fetches the public
+ * address with the platform's own certificate checks and reads what comes back. Each problem is one line saying
+ * what to change.
+ */
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { HSTS_VALUE, isLoopbackAddress, isTailnetAddress, USE_HTTPS } from "./public-access.js";
+const TIMEOUT_MS = 10_000;
+/** A documentation address (RFC 5737): the remote caller the local probe pretends to relay for. */
+const SAMPLE_CALLER = "203.0.113.10";
+const HOST_GRAMMAR = /^[A-Za-z0-9.-]{1,253}(:[0-9]{1,5})?$|^\[[0-9A-Fa-f:.]{2,45}\](:[0-9]{1,5})?$/;
+/** The default probe: node's http/https with the platform trust store, a timeout and a 4 KB body cap. */
+export const networkProbe = ({ url, headers }) => new Promise(resolve => {
+    const target = new URL(url);
+    const send = target.protocol === "https:" ? httpsRequest : httpRequest;
+    const outgoing = send(target, { method: "GET", headers, timeout: TIMEOUT_MS }, incoming => {
+        let body = "";
+        incoming.setEncoding("utf8");
+        incoming.on("data", (chunk) => { if (body.length < 4096)
+            body += chunk; });
+        incoming.on("end", () => resolve({ status: incoming.statusCode ?? 0, headers: incoming.headers, body }));
+        incoming.on("error", error => resolve({ error: codeOf(error) }));
+    });
+    outgoing.on("timeout", () => { outgoing.destroy(); resolve({ error: "ETIMEDOUT" }); });
+    outgoing.on("error", error => resolve({ error: codeOf(error) }));
+    outgoing.end();
+});
+const codeOf = (error) => typeof error === "object" && error !== null && typeof error.code === "string" ? error.code : "EUNKNOWN";
+/** The exact https origin --public-url must be, as serve.ts requires it; else what is wrong with it. */
+export function publicOriginOf(value) {
+    if (value === undefined)
+        return "--public-url is missing. Pass the address engineers will use, like --public-url https://toolroll.example.com.";
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        return `--public-url ${value} is not a URL. Use https://<your domain>.`;
+    }
+    if (parsed.protocol !== "https:")
+        return `--public-url must start with https:// (got ${parsed.protocol}//).`;
+    if (parsed.username !== "" || parsed.password !== "" || parsed.hash !== "" || parsed.search !== "" || (parsed.pathname !== "/" && parsed.pathname !== "")) {
+        return "--public-url must be just https://<host>, with no path, query or credentials.";
+    }
+    return parsed;
+}
+/** Names a plain-HTTP browser can reasonably use: this computer, the tailnet, a LAN or a single-label name. */
+function privateName(host) {
+    const name = host.replace(/:[0-9]{1,5}$/, "").replace(/^\[(.*)\]$/, "$1").toLowerCase();
+    if (name === "localhost" || name.endsWith(".ts.net") || name.endsWith(".local") || !name.includes(".") && !name.includes(":"))
+        return true;
+    if (isLoopbackAddress(name) || isTailnetAddress(name))
+        return true;
+    const v4 = /^(\d+)\.(\d+)\.\d+\.\d+$/.exec(name);
+    if (v4 !== null) {
+        const [a, b] = [Number(v4[1]), Number(v4[2])];
+        return a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 169 && b === 254);
+    }
+    return /^f[cd][0-9a-f]{2}:|^fe80:/.test(name);
+}
+const header = (answer, name) => {
+    const value = answer.headers[name];
+    return Array.isArray(value) ? value.join(", ") : value;
+};
+/** The HSTS max-age a response sets, or null when it sets none. */
+const hstsAge = (value) => {
+    const match = value === undefined ? null : /(?:^|;)\s*max-age\s*=\s*"?(\d+)"?/i.exec(value);
+    return match === null ? null : Number(match[1]);
+};
+const refusedForHttp = (answer) => !("error" in answer) && answer.status === 403 && answer.body.trim() === USE_HTTPS;
+function certificateProblem(host, code) {
+    if (code === "ENOTFOUND" || code === "EAI_AGAIN")
+        return `${host} does not resolve. Point its DNS at this server or your tunnel.`;
+    if (code === "ECONNREFUSED")
+        return `Nothing answers HTTPS at ${host}. Start Caddy or the tunnel.`;
+    if (code === "ETIMEDOUT" || code === "ECONNRESET")
+        return `${host} did not answer over HTTPS within ${TIMEOUT_MS / 1000} seconds. Check the firewall, Caddy or the tunnel.`;
+    if (code === "CERT_HAS_EXPIRED")
+        return `The certificate for ${host} has expired. Renew it.`;
+    if (code === "ERR_TLS_CERT_ALTNAME_INVALID")
+        return `The certificate does not name ${host}. Issue one for this exact host.`;
+    if (/SELF_SIGNED|UNABLE_TO_VERIFY|UNABLE_TO_GET_ISSUER|CERT_UNTRUSTED/.test(code))
+        return `The certificate for ${host} is not trusted (${code}). Use a publicly trusted certificate, such as Caddy's automatic one.`;
+    return `Could not reach https://${host} (${code}).`;
+}
+/** Every problem with serving on --public-url, in a fixed order; an empty list means ready. */
+export async function checkPublic(options, probe = networkProbe) {
+    const origin = publicOriginOf(options.publicUrl);
+    if (typeof origin === "string")
+        return [{ check: "public-url", message: origin }];
+    const host = origin.host;
+    const findings = [];
+    for (const allowed of options.allowHosts) {
+        if (!HOST_GRAMMAR.test(allowed))
+            findings.push({ check: "allow-host", message: `--allow-host ${allowed} is not a host name or host:port.` });
+        else if (allowed !== host && !privateName(allowed)) {
+            findings.push({ check: "allow-host", message: `--allow-host ${allowed} is a public name served over plain HTTP, so passwords would cross the internet unencrypted. Remove it: --public-url already admits ${host}.` });
+        }
+    }
+    // The console on this computer, asked as the same-host proxy would ask it.
+    const local = `http://127.0.0.1:${options.port}`;
+    const relayed = { host, "x-forwarded-for": SAMPLE_CALLER };
+    const page = await probe({ url: `${local}/login`, headers: { ...relayed, "x-forwarded-proto": "https" } });
+    if ("error" in page) {
+        findings.push({ check: "local", message: `Nothing answers on 127.0.0.1:${options.port}. Start Toolroll there, or pass the --port it uses.` });
+    }
+    else if (page.status === 421) {
+        findings.push({ check: "host", message: `The server on port ${options.port} does not answer as ${host}. Restart it with --public-url ${origin.origin}.` });
+    }
+    else {
+        if (header(page, "strict-transport-security") !== HSTS_VALUE) {
+            findings.push({ check: "hsts", message: `The server sends no Strict-Transport-Security for ${host} over HTTPS. Update Toolroll and restart it with --public-url ${origin.origin}.` });
+        }
+        const plain = await probe({ url: `${local}/api/cli`, headers: { ...relayed, "x-forwarded-proto": "http" } });
+        if (!refusedForHttp(plain)) {
+            findings.push({ check: "forwarding", message: "The server does not refuse API tokens relayed over plain HTTP from another computer. Update Toolroll." });
+        }
+    }
+    // The public address, with the platform's certificate checks.
+    const outside = await probe({ url: `${origin.origin}/login`, headers: {} });
+    if ("error" in outside) {
+        findings.push({ check: "certificate", message: certificateProblem(host, outside.error) });
+        return findings;
+    }
+    if (outside.status === 421) {
+        findings.push({ check: "proxy", message: `The proxy changes the Host header, so Toolroll refuses ${host}. Pass the original Host through.` });
+        return findings;
+    }
+    const age = hstsAge(header(outside, "strict-transport-security"));
+    if (age === null) {
+        findings.push({ check: "hsts", message: `https://${host} sends no Strict-Transport-Security. Run the proxy on this computer and have it send X-Forwarded-Proto: https.` });
+    }
+    else if (age < 31_536_000) {
+        findings.push({ check: "hsts", message: `https://${host} sets Strict-Transport-Security max-age=${age}; use at least 31536000 (one year).` });
+    }
+    const api = await probe({ url: `${origin.origin}/api/cli`, headers: {} });
+    if (refusedForHttp(api)) {
+        findings.push({ check: "proxy", message: `Requests through https://${host} reach Toolroll as plain HTTP from another computer. Run the proxy on this computer, pointed at 127.0.0.1:${options.port}, sending X-Forwarded-For and X-Forwarded-Proto.` });
+    }
+    return findings;
+}
+/** The command: findings as lines (or one envelope), exit 0 when ready, 1 when not, 2 for a malformed --port. */
+export async function checkPublicCommand(flags, context) {
+    const command = "serve check-public";
+    const value = (name) => { const one = flags.get(name); return typeof one === "string" ? one : undefined; };
+    const portGiven = value("port");
+    const port = Number(portGiven ?? 4180);
+    if (!Number.isInteger(port) || port < 1 || port >= 65536) {
+        const message = "--port is a whole number under 65536";
+        context.write(context.json ? context.envelope({ ok: false, command, reason: "usage", message }) : message);
+        return 2;
+    }
+    const publicUrl = value("public-url");
+    const allowHosts = (value("allow-host") ?? "").split(",").map(one => one.trim()).filter(one => one !== "");
+    const findings = await checkPublic({ publicUrl, port, allowHosts }, context.probe);
+    const ready = findings.length === 0;
+    const message = ready ? `${publicUrl} is ready: valid certificate, HSTS, and API tokens only over HTTPS.` : `${findings.length === 1 ? "1 problem" : `${findings.length} problems`} serving ${publicUrl ?? "on a public address"}:`;
+    if (context.json) {
+        context.write(context.envelope({ ok: ready, command, ...(ready ? {} : { reason: "not-ready", message }), publicUrl: publicUrl ?? null, port, findings }));
+    }
+    else {
+        context.write(message);
+        for (const finding of findings)
+            context.write(`- ${finding.message}`);
+    }
+    return ready ? 0 : 1;
+}

package/dist/remote-audit.d.ts

@@ -0,0 +1,79 @@
+import type { ApiTokenRow, Store } from "./store.js";
+export declare const AUDIT_SOURCES: readonly ["api", "mcp"];
+export type AuditSource = typeof AUDIT_SOURCES[number];
+export type AuditOutcome = "ok" | "refused" | "error";
+export declare const AUDIT_LIMIT: {
+    readonly default: 20;
+    readonly max: 100;
+};
+export type AuditFilters = {
+    person: string | null;
+    token: string | null;
+    source: AuditSource | null;
+    since: string | null;
+};
+/** One remote action. `kind` says whether a person's CLI ran a command or their agent called a tool over MCP. */
+export type AuditAction = {
+    id: number;
+    at: string;
+    person: string;
+    token: string | null;
+    source: AuditSource;
+    kind: "command" | "tool";
+    /** The command row (`task show`), or for a tool call the tool's name when the line recorded it. */
+    name: string;
+    command: string;
+    tool: string | null;
+    repo: string | null;
+    taskId: string | null;
+    outcome: AuditOutcome;
+    /** A refusal's stable reason (`read-only`, `not-found`, ...), never free text. */
+    reason: string | null;
+};
+/**
+ * Who is reading. `self` null: the machine's own owner, reading the database here. Otherwise a person:
+ * `everyone` when they approve; `repos` their project ceiling (null: every project); `unplaced` whether lines in no
+ * project (refused before a project was known) are theirs to see for other people.
+ */
+export type AuditReader = {
+    self: string | null;
+    everyone: boolean;
+    repos: readonly string[] | null;
+    unplaced: boolean;
+};
+export declare const OWNER_READER: AuditReader;
+export type AuditPage = {
+    ok: true;
+    actions: AuditAction[];
+    nextCursor: string | null;
+    limit: number;
+} | {
+    ok: false;
+    reason: "not-found";
+    message: string;
+};
+/** The old final words, in the vocabulary people read. Anything unrecognized reads as an error, never as ok. */
+export declare function auditOutcome(outcome: string): AuditOutcome | null;
+/** `7d` → the instant that many days before `now`; null for anything else (no zero, sign, fraction or other unit). */
+export declare function sinceOf(value: string, now: Date): string | null;
+export declare const cursorOf: (value: string) => number | null;
+/**
+ * A line's token, tool and reason. The detail is `token <name>` then ` · `-separated parts: the token name is the
+ * longest of this person's token names (or ids, for a line written before the token was proved) that matches up to a
+ * separator, since a name may itself contain ` · `. Unmatched text is never echoed.
+ */
+export declare function readDetail(detail: string | null, tokens: readonly Pick<ApiTokenRow, "id" | "name">[]): {
+    token: string | null;
+    tool: string | null;
+    reason: string | null;
+};
+/**
+ * One page of remote actions, newest first, keyed by entry id so new lines never shift an older page. The reader's
+ * visibility and every filter are applied before the page is cut; the token filter is an exact name match.
+ */
+export declare function remoteAudit(store: Store, reader: AuditReader, filters: AuditFilters, page?: {
+    limit?: number;
+    before?: number | null;
+}): AuditPage;
+/** A token's standing, for People. */
+export declare function tokenStatus(token: Pick<ApiTokenRow, "revokedAt" | "expiresAt">, now: Date): "active" | "expired" | "revoked";

package/dist/remote-audit.js

@@ -0,0 +1,161 @@
+/**
+ * Remote activity (phase 3, docs/plans/remote-team.md): what people did on this server with their API tokens, read
+ * from the action history runOperateAs already writes — one `requested` line when a command starts, and a final line
+ * (`done`, `refused`, `usage`, `failed`) when it ends or is refused. The history is append-only and sealed, so old
+ * words are never rewritten: this projection maps them to `ok`, `refused` and `error` as it reads, and leaves out the
+ * `requested` lines. It never shows a line's raw detail; the token's name, an MCP tool and a refusal reason are
+ * recovered from it by exact match.
+ *
+ * Who sees what is decided inside the query, before a page is cut: the machine's owner (a local run) sees everyone;
+ * an approver sees everyone within their project ceiling and all of their own lines; a viewer sees only their own.
+ * Another person the reader may not see answers exactly like a person who doesn't exist.
+ */
+import { IN_RANGE } from "./ledger-chain.js";
+export const AUDIT_SOURCES = ["api", "mcp"];
+export const AUDIT_LIMIT = { default: 20, max: 100 };
+const SINCE_MAX_DAYS = 3650;
+export const OWNER_READER = Object.freeze({ self: null, everyone: true, repos: null, unplaced: true });
+/** The old final words, in the vocabulary people read. Anything unrecognized reads as an error, never as ok. */
+export function auditOutcome(outcome) {
+    if (outcome === "requested")
+        return null;
+    if (outcome === "done")
+        return "ok";
+    if (outcome === "refused" || outcome === "usage")
+        return "refused";
+    return "error";
+}
+/** `7d` → the instant that many days before `now`; null for anything else (no zero, sign, fraction or other unit). */
+export function sinceOf(value, now) {
+    const match = /^([1-9][0-9]{0,3})d$/.exec(value);
+    if (match === null || Number(match[1]) > SINCE_MAX_DAYS)
+        return null;
+    return new Date(now.getTime() - Number(match[1]) * 86_400_000).toISOString();
+}
+export const cursorOf = (value) => /^[1-9][0-9]{0,15}$/.test(value) && Number.isSafeInteger(Number(value)) ? Number(value) : null;
+const REASON = /^[a-z][a-z0-9-]{0,40}$/;
+const TOOL = /^[a-z][a-z0-9_]{0,40}$/;
+const COMMAND = "remote command: ";
+/**
+ * A line's token, tool and reason. The detail is `token <name>` then ` · `-separated parts: the token name is the
+ * longest of this person's token names (or ids, for a line written before the token was proved) that matches up to a
+ * separator, since a name may itself contain ` · `. Unmatched text is never echoed.
+ */
+export function readDetail(detail, tokens) {
+    const none = { token: null, tool: null, reason: null };
+    if (detail === null || !detail.startsWith("token "))
+        return none;
+    const body = detail.slice("token ".length);
+    let token = null, rest = "", matched = -1;
+    for (const one of tokens) {
+        for (const label of [one.name, one.id]) {
+            if ((body === label || body.startsWith(`${label} · `)) && label.length > matched) {
+                token = one.name;
+                rest = body.slice(label.length);
+                matched = label.length;
+            }
+        }
+    }
+    if (token === null)
+        return none;
+    let tool = null, reason = null;
+    for (const part of rest.split(" · ").slice(1)) {
+        if (part.startsWith("tool ") && TOOL.test(part.slice(5)))
+            tool = part.slice(5);
+        else if (REASON.test(part))
+            reason ??= part;
+    }
+    return { token, tool, reason };
+}
+/**
+ * One page of remote actions, newest first, keyed by entry id so new lines never shift an older page. The reader's
+ * visibility and every filter are applied before the page is cut; the token filter is an exact name match.
+ */
+export function remoteAudit(store, reader, filters, page = {}) {
+    const notFound = { ok: false, reason: "not-found", message: "Not found." };
+    const limit = Math.max(1, Math.min(AUDIT_LIMIT.max, Math.trunc(page.limit ?? AUDIT_LIMIT.default)));
+    if (filters.person !== null) {
+        if (store.accountOf(filters.person) === null)
+            return notFound;
+        if (reader.self !== null && !reader.everyone && filters.person !== reader.self)
+            return notFound;
+    }
+    const clauses = ["source IN ('api','mcp')", "outcome <> 'requested'", `action LIKE '${COMMAND}%'`];
+    const args = [];
+    if (reader.self !== null) {
+        if (!reader.everyone) {
+            clauses.push("actor = ?");
+            args.push(reader.self);
+        }
+        else if (reader.repos !== null || !reader.unplaced) {
+            const placed = reader.repos === null ? "repo IS NOT NULL" : reader.repos.length === 0 ? "0" : `repo IN (${reader.repos.map(() => "?").join(",")})`;
+            clauses.push(`(actor = ? OR ${placed}${reader.unplaced ? " OR repo IS NULL" : ""})`);
+            args.push(reader.self, ...(reader.repos ?? []));
+        }
+    }
+    if (filters.person !== null) {
+        clauses.push("actor = ?");
+        args.push(filters.person);
+    }
+    if (filters.source !== null) {
+        clauses.push("source = ?");
+        args.push(filters.source);
+    }
+    if (filters.since !== null) {
+        clauses.push("at >= ?");
+        args.push(filters.since);
+    }
+    const tokens = new Map();
+    for (const one of store.apiTokens(null))
+        tokens.set(one.account, [...(tokens.get(one.account) ?? []), one]);
+    if (filters.token !== null) {
+        // Narrow by every label a line for this name could start with; the exact owner of the line is decided below.
+        const labels = [...new Set([...tokens.values()].flat().filter(one => one.name === filters.token).flatMap(one => [one.name, one.id]))];
+        if (labels.length === 0)
+            return { ok: true, actions: [], nextCursor: null, limit };
+        clauses.push(`(${labels.map(() => "(detail = ? OR substr(detail, 1, ?) = ?)").join(" OR ")})`);
+        for (const label of labels)
+            args.push(`token ${label}`, `token ${label} · `.length, `token ${label} · `);
+    }
+    const statement = store.handle.prepare(`SELECT id, at, actor, repo, task_id, action, outcome, source, detail FROM action_ledger
+    WHERE id ${IN_RANGE} AND id < ? AND ${clauses.join(" AND ")} ORDER BY id DESC LIMIT ?`);
+    const actions = [];
+    let before = page.before ?? Number.MAX_SAFE_INTEGER, more = false;
+    const batch = limit + 1;
+    while (actions.length <= limit) {
+        const rows = statement.all(before, ...args, batch);
+        for (const row of rows) {
+            before = Number(row["id"]);
+            const action = actionOf(row, tokens.get(String(row["actor"])) ?? []);
+            if (action === null || filters.token !== null && action.token !== filters.token)
+                continue;
+            if (actions.length === limit) {
+                more = true;
+                break;
+            }
+            actions.push(action);
+        }
+        if (more || rows.length < batch)
+            break;
+    }
+    return { ok: true, actions, nextCursor: more ? String(actions.at(-1).id) : null, limit };
+}
+function actionOf(row, tokens) {
+    const outcome = auditOutcome(String(row["outcome"]));
+    const source = String(row["source"]);
+    if (outcome === null || (source !== "api" && source !== "mcp"))
+        return null;
+    const command = String(row["action"]).slice(COMMAND.length);
+    const read = readDetail(row["detail"] == null ? null : String(row["detail"]), tokens);
+    const tool = source === "mcp" ? read.tool : null;
+    return {
+        id: Number(row["id"]), at: String(row["at"]), person: String(row["actor"]), token: read.token, source,
+        kind: source === "mcp" ? "tool" : "command", name: tool ?? command, command, tool,
+        repo: row["repo"] == null ? null : String(row["repo"]), taskId: row["task_id"] == null ? null : String(row["task_id"]),
+        outcome, reason: outcome === "ok" ? null : read.reason ?? (String(row["outcome"]) === "usage" ? "usage" : null),
+    };
+}
+/** A token's standing, for People. */
+export function tokenStatus(token, now) {
+    return token.revokedAt !== null ? "revoked" : Date.parse(token.expiresAt) <= now.getTime() ? "expired" : "active";
+}

package/dist/remote-run.d.ts

@@ -8,6 +8,10 @@ export type RemoteRun = {
     readonly secret: string;
     /** Whether the person may use `repo` now (their token's projects and their account's current access). */
     readonly allows: (repo: string | null) => boolean;
+    /** The projects listings and task references may disclose (remoteLensOf); null shows every project. */
+    readonly lens: readonly string[] | null;
+    /** Called with the task a remote `task add` filed (or replayed), so its action history names it. */
+    readonly noteTask: (taskId: string) => void;
     /** Files the caller sent, keyed by the argument that names them. Nothing else is read for input. */
     readonly files: Readonly<Record<string, string>>;
 };

package/dist/request-budget-ui.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Settings → Sessions & tokens: each token's request limits in its line, and — for an instance operator — one
+ * disclosure to change them for everyone's tokens or for one token (request-budget.ts). Saving takes the operator's
+ * password (or a fresh identity-provider sign-in), in a browser only.
+ */
+import type { ApiTokenRow, Database } from "./store.js";
+export declare const REQUEST_LIMITS_CSS: string;
+/** "120 requests a minute · 10,000 a day" for one token's line. */
+export declare function tokenLimitWords(db: Database, token: ApiTokenRow): string;
+/** The operator's disclosure: everyone's tokens, or one token. Blank fields use the default shown. */
+export declare function requestLimitsHtml(db: Database, tokens: readonly ApiTokenRow[], csrf: string, now: number): string;

package/dist/request-budget-ui.js

@@ -0,0 +1,31 @@
+import { effectiveLimits, limitOverrides, PER_DAY_MAX, PER_MINUTE_MAX, REQUEST_BUDGET_DEFAULTS } from "./request-budget.js";
+const e = (value) => String(value ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+const n = (value) => value.toLocaleString("en-US");
+export const REQUEST_LIMITS_CSS = `.credentials .limits{display:grid;gap:14px}.credentials .limits form{display:grid;gap:10px}.credentials .limits label{display:grid;gap:6px}` +
+    `.credentials .limits input,.credentials .limits select{box-sizing:border-box;width:100%;min-width:0}.credentials .limits .pair{display:grid;grid-template-columns:1fr 1fr;gap:10px}.credentials .limits .actions{display:flex;flex-wrap:wrap;gap:8px}` +
+    `.credentials .limits h3{font-size:.95rem;margin:4px 0 0}@media(max-width:600px){.credentials .limits .pair{grid-template-columns:1fr}.credentials .limits input,.credentials .limits select{font-size:16px}}`;
+/** "120 requests a minute · 10,000 a day" for one token's line. */
+export function tokenLimitWords(db, token) {
+    const limits = effectiveLimits(db, token.id, token.access);
+    return `${n(limits.perMinute)} requests a minute · ${n(limits.perDay)} a day`;
+}
+/** The operator's disclosure: everyone's tokens, or one token. Blank fields use the default shown. */
+export function requestLimitsHtml(db, tokens, csrf, now) {
+    const overrides = limitOverrides(db);
+    const everyone = overrides.get("*") ?? { readPerMinute: null, actPerMinute: null, perDay: null };
+    const field = (name, label, value, placeholder, max) => `<label>${label}<input type="number" name="${name}" min="1" max="${max}" step="1" inputmode="numeric" value="${value === null ? "" : value}" placeholder="${placeholder}"></label>`;
+    const password = `<label>Your Toolroll password<input type="password" name="password" autocomplete="current-password"></label>`;
+    const buttons = `<div class="actions"><button name="action" value="save">Save limits</button><button class="secondary" name="action" value="clear">Use defaults</button></div>`;
+    const live = tokens.filter(one => one.revokedAt === null && Date.parse(one.expiresAt) > now);
+    const installation = `<form method="post" action="/settings/request-limits"><input type="hidden" name="csrf" value="${e(csrf)}"><input type="hidden" name="target" value="*">` +
+        `<h3>Everyone's tokens</h3><div class="pair">${field("read-per-minute", "Read tokens, a minute", everyone.readPerMinute, String(REQUEST_BUDGET_DEFAULTS.read), PER_MINUTE_MAX)}` +
+        `${field("act-per-minute", "Act tokens, a minute", everyone.actPerMinute, String(REQUEST_BUDGET_DEFAULTS.act), PER_MINUTE_MAX)}</div>` +
+        `${field("per-day", "Each token, a day", everyone.perDay, String(REQUEST_BUDGET_DEFAULTS.day), PER_DAY_MAX)}${password}${buttons}</form>`;
+    const one = live.length === 0 ? "" : `<form method="post" action="/settings/request-limits"><input type="hidden" name="csrf" value="${e(csrf)}">` +
+        `<h3>One token</h3><label>Token<select name="target">${live.map(row => {
+            const set = overrides.get(row.id);
+            return `<option value="${e(row.id)}">${e(row.name)} (${e(row.account)}, ${row.access === "act" ? "act" : "read"})${set === undefined ? "" : " · own limits"}</option>`;
+        }).join("")}</select></label>` +
+        `<div class="pair">${field("per-minute", "A minute", null, "Everyone's", PER_MINUTE_MAX)}${field("per-day", "A day", null, "Everyone's", PER_DAY_MAX)}</div>${password}${buttons}</form>`;
+    return `<details class="card"><summary>Request limits</summary><div class="limits">${installation}${one}</div></details>`;
+}

package/dist/request-budget.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Request budgets for person API tokens (v112): how many requests one `so_` token may make to `/api/cli` and `/mcp`.
+ * One budget per token, keyed by its api_token row id (never the secret, its name or an address), shared by both
+ * routes. A read token gets 120 requests in any sliding minute, an act token 30, and either 10,000 in a rolling day;
+ * an instance operator may override any of these for the installation or for one token in the console (step-up).
+ *
+ * The token's saved access decides its class: nothing in a request body moves it. A request is counted once when it
+ * is admitted, however long it then holds the server (a task wait long-poll is one request, not one per second).
+ * Over budget answers 429 with Retry-After; the first refusal in each exhausted window is ledgered, never each one.
+ *
+ * Tracking is in memory and bounded: at most TRACKED_TOKENS tokens (least recently used goes first, saved before it
+ * goes), each with at most PER_MINUTE_MAX request times and one counter per minute of the day. It is saved every
+ * FLUSH_MS, on eviction, on server close and at once on a refusal, so a restart doesn't hand a client hammering the
+ * server a fresh budget. Anything unreadable (a policy or saved usage outside its bounds) refuses: fail closed.
+ */
+import type { Database, Store } from "./store.js";
+import type { TokenAccess } from "./api-tokens.js";
+export declare const REQUEST_BUDGET_SCHEMA = "\nCREATE TABLE IF NOT EXISTS request_budget_limit (\n  target          TEXT PRIMARY KEY CHECK (target = '*' OR (length(target) = 12 AND target NOT GLOB '*[^0-9a-f]*')),\n  read_per_minute INTEGER CHECK (read_per_minute IS NULL OR read_per_minute BETWEEN 1 AND 600),\n  act_per_minute  INTEGER CHECK (act_per_minute IS NULL OR act_per_minute BETWEEN 1 AND 600),\n  per_day         INTEGER CHECK (per_day IS NULL OR per_day BETWEEN 1 AND 100000),\n  set_by          TEXT NOT NULL,\n  set_at          TEXT NOT NULL\n);\nCREATE TABLE IF NOT EXISTS request_budget_usage (\n  token_id  TEXT PRIMARY KEY,\n  minute    TEXT NOT NULL,\n  day       TEXT NOT NULL,\n  noted     TEXT NOT NULL,\n  saved_at  INTEGER NOT NULL\n);\n";
+export declare const REQUEST_BUDGET_DEFAULTS: Readonly<{
+    read: 120;
+    act: 30;
+    day: 10000;
+}>;
+export declare const PER_MINUTE_MAX = 600;
+export declare const PER_DAY_MAX = 100000;
+export declare const TRACKED_TOKENS = 1024;
+export declare const FLUSH_MS = 5000;
+/** Which limit a refusal hit: the body of a 429 names only this and Retry-After. */
+export type BudgetLimit = "read-per-minute" | "act-per-minute" | "per-day";
+export type Admission = {
+    ok: true;
+} | {
+    ok: false;
+    status: 429;
+    limit: BudgetLimit;
+    retryAfter: number;
+} | {
+    ok: false;
+    status: 503;
+};
+export type BudgetRoute = "api" | "mcp";
+/** An override: null leaves that limit to the installation (for a token) or the default. */
+export type LimitOverride = {
+    readPerMinute: number | null;
+    actPerMinute: number | null;
+    perDay: number | null;
+};
+export type EffectiveLimits = {
+    perMinute: number;
+    perDay: number;
+    overridden: boolean;
+};
+/** The words for a 429, in one line. */
+export declare const limitWords: (limit: BudgetLimit, retryAfter: number) => string;
+/** A limit typed into a form: a whole number within bounds, "" for none, or a problem. */
+export declare function parseLimit(raw: string, max: number): number | null | {
+    problem: string;
+};
+/** Every override: the installation's under "*", each token's under its id. */
+export declare function limitOverrides(db: Database): Map<string, LimitOverride>;
+/** Token override, then the installation's, then the default — per limit. */
+export declare function effectiveLimits(db: Database, tokenId: string, access: TokenAccess): EffectiveLimits;
+/** Set (or, all null, clear) an override, with the change in the policy ledger. The caller checks who may. */
+export declare function setLimitOverride(store: Store, target: string, next: LimitOverride, by: string, now: Date): {
+    before: LimitOverride | null;
+    after: LimitOverride | null;
+};
+export type RequestBudgetOptions = {
+    store: Store;
+    /** Milliseconds since the epoch; tests inject their own. */
+    clock?: () => number;
+    tracked?: number;
+    flushMs?: number;
+};
+/** One per server: both routes share it, so a token's allowance is never doubled. */
+export declare class RequestBudget {
+    private readonly store;
+    private readonly clock;
+    private readonly tracked;
+    private readonly flushMs;
+    private readonly usage;
+    private lastFlush;
+    constructor(options: RequestBudgetOptions);
+    /** How many tokens are tracked in memory now (never more than `tracked`). */
+    get size(): number;
+    /**
+     * Admit one request by an authenticated token, or say why not. Called once per HTTP request, before its body is
+     * read. Anything unreadable refuses with 503 and nothing runs.
+     */
+    admit(tokenId: string, route: BudgetRoute): Admission;
+    /** Save every changed entry. A server calls this on a timer and when it closes. */
+    flush(): void;
+    private save;
+    /** The tracked entry (now the most recently used), from memory or as last saved; the least recently used is saved and let go. */
+    private load;
+}