toolroll 0.9.45 → 0.9.46

package/dist/operate.js

@@ -1,4 +1,5 @@
 import { UNSENT_REPLY_MS } from "./telegram-settings.js";
+import { checkPublicCommand } from "./public-check.js";
 import { leadNameOf } from "./lead-identity.js";
 import { maybeTriggerRepair } from "./dispose.js";
 import { CHECK_LEVEL_HINTS, CHECK_LEVEL_WORDS, isCheckLevel, liveQuickCommand, projectCheckLevel, quickVerifyKey, setProjectCheckLevel, setTaskCheckLevel, suggestQuickCommand } from "./check-levels.js";
@@ -23,6 +24,8 @@ import { billingOf, budgetHoldWords, budgetLabel, budgetStates, monthNamed, mont
 import { spendCsv } from "./spend-ui.js";
 import { buildExport, exportSummary, exportZip, writeExportFolder } from "./export.js";
 import { startBudgetAlerts } from "./budget-alerts.js";
+import { runTokensCommand } from "./tokens-cli.js";
+import { startTokenNotices } from "./token-notices.js";
 import { liftAuthPause, openAuthPauses, signInGate, signInWords, startSignInProbes } from "./provider-auth.js";
 import { createConnectionChecker } from "./provider-connection.js";
 import { checkIntegrations, integrationsBrokenLine, integrationsNow, renderIntegrations } from "./integrations.js";
@@ -100,6 +103,7 @@ import { createServer as createNetServer } from "node:net";
 import { spawn as spawnChild } from "node:child_process";
 // Every envelope is checked against its command's schema (logged, never refused), then serialized unchanged.
 import { checkedEnvelopeJson as envelopeJson } from "./contracts/cli.js";
+import { auditCommand } from "./audit-cli.js";
 import { hasDisguisedText, hasForbiddenControls, validateNote } from "./decision.js";
 import { readVerifiedArtifact, readVerifiedReport, storeEvidence } from "./evidence.js";
 import { contractChangesOf, decodePlanContractRecord, describeContractChanges, encodePlannerSource, plannerSourceOf } from "./planner-source.js";
@@ -273,6 +277,9 @@ export const OPERATE_HELP = `toolroll — operating the queue
   toolroll ledger checkpoint         record the chain's head to copy off this machine (instance operator)
   toolroll ledger export --from <YYYY-MM-DD> --to <YYYY-MM-DD> [--out <file>]
                                         every sealed entry in the range, with an evidence pack per task
+  toolroll audit [--person <p>] [--token <name>] [--source api|mcp] [--since 7d]
+                                        what people did here with their API tokens, newest first (--limit, --cursor;
+                                        remotely, name a token with --token-name)
   toolroll task complete <id>        mark the current result complete (--digest for JSON/agents);
       [--pull-request]                  --pull-request also opens its pull request
   toolroll task merge <id> --as <you> --token <t>
@@ -671,6 +678,10 @@ export const OPERATE_VALUE_FLAGS = new Set([
     "quick", "level", "checks",
     // lead say: the task the lead's words are about.
     "task",
+    // tokens: an API token's terms, and a rotation's overlap in minutes.
+    "access", "projects", "overlap",
+    // audit: a token by name where --token is a credential (remote).
+    "token-name",
 ]);
 export const OPERATE_BOOLEAN_FLAGS = new Set([
     "json", "yes", "all", "brief", "local", "history", "latest-watch", "dry-run", "file", "allow-paid-fallback",
@@ -692,6 +703,8 @@ export const OPERATE_BOOLEAN_FLAGS = new Set([
     "anyway",
     // config set/clear: another provider's candidate on the same tier.
     "also",
+    // tokens: the person's password, piped (never an argument).
+    "password-stdin",
 ]);
 export function parseOperateArgs(argv, ownValues = new Set()) {
     const positional = [];
@@ -793,6 +806,10 @@ export async function runOperate(command, argv, write, options = {}) {
     if (command === "mcp") {
         return mcpCommand(file, flags, write, json);
     }
+    // The public-address readiness check reads no database: it only asks the network.
+    if (command === "serve" && positional[0] === "check-public") {
+        return checkPublicCommand(flags, { write, json, envelope: envelopeJson, ...(options.publicProbe === undefined ? {} : { probe: options.publicProbe }) });
+    }
     // Restore replaces the database file itself, so it opens (and closes) the database on its own.
     if (command === "restore") {
         return restoreCommand(file, positional, flags, write, json, now);
@@ -927,10 +944,12 @@ export async function runOperateAs(argv, opts) {
     const json = rest.includes("--json");
     let invocation = root;
     let tokenName = null;
+    // An MCP call names the gateway tool it came from, so the history tells a tool from the command it ran.
+    const tool = source === "mcp" && typeof opts.tool === "string" && /^[a-z][a-z0-9_]{0,40}$/.test(opts.tool) ? opts.tool : null;
     const record = (outcome, repo, taskId, why) => {
         store.recordAction({ at: (options.now ?? new Date()).toISOString(), actor: principal.account, repo, taskId, runId: null,
             action: `remote command: ${invocation === "" ? "(none)" : invocation}`.slice(0, 200), outcome, source,
-            detail: `token ${tokenName ?? principal.tokenId}${why === null ? "" : ` · ${why}`}` });
+            detail: `token ${tokenName ?? principal.tokenId}${why === null ? "" : ` · ${why}`}${tool === null ? "" : ` · tool ${tool}`}` });
     };
     const refuse = (reason, message, repo = null, taskId = null) => {
         record("refused", repo, taskId, reason);
@@ -1070,6 +1089,8 @@ async function dispatch(command, positional, flags, context) {
             return taskCommand(positional, flags, context);
         case "ledger":
             return ledgerCommand(positional, flags, context);
+        case "audit":
+            return auditCommand(positional, flags, { store: context.store, write: context.write, json: context.json, now: context.clock(), ...(context.principal === undefined ? {} : { principal: context.principal }) });
         case "spend":
             return spendCommand(flags, context);
         case "budget":
@@ -1203,6 +1224,13 @@ async function dispatch(command, positional, flags, context) {
             return chatApprovalCommand(positional, flags, context);
         case "people":
             return peopleCommand(positional, flags, context);
+        case "tokens":
+            return runTokensCommand(positional, flags, {
+                store: context.store, write: context.write, json: context.json, clock: context.clock,
+                caller: activeRemote() !== null ? "remote" : currentActor()?.lead === true || context.leadToken !== undefined ? "lead" : "local",
+                rememberedName: readLoginFile(join(dirname(context.databaseFile), UP_LOGIN_FILE))?.name ?? null,
+                interactive, ask, askHidden, readStdin: readBoundedStdin,
+            });
         case "keys":
             return keysCommand(positional, flags, context);
         case "setup":
@@ -5078,6 +5106,8 @@ async function startConsole(options) {
     server.on("close", stopMonitoring);
     // v105: budget alerts at 50/80/100 %, a pass a minute.
     server.on("close", startBudgetAlerts(context.store));
+    // v111: API tokens: 7- and 1-day expiry notices to their person, and the end of each rotated token, a pass a minute.
+    server.on("close", startTokenNotices(context.store));
     // A paused provider's sign-in is checked every two minutes (no model, nothing spent); the pause lifts when it works.
     server.on("close", startSignInProbes(context.store, createConnectionChecker()));
     // Sprint 8: scheduled backups, a pass a minute; its lease also tells a restore that the console is running.
@@ -8637,6 +8667,8 @@ async function upCommand(flags, context) {
         return fail(write, json, "up", "usage", "--host is an address or a name", EXIT.usage);
     }
     const allowFlag = text(flags, "allow-host");
+    // --public-url: `up` serves a real domain exactly as `serve` does (one process is the whole team server).
+    const publicUrlFlag = text(flags, "public-url");
     const progress = (line) => {
         // v99: with TOOLROLL_LOG_FORMAT=json, each line is one JSON event on stderr for a log shipper.
         if (envValue(process.env, "LOG_FORMAT") === "json")
@@ -8863,6 +8895,7 @@ async function upCommand(flags, context) {
             host: hostFlag,
             port,
             ...(allowFlag === undefined ? {} : { allowedHosts: allowFlag.split(",").map(one => one.trim()).filter(one => one !== "") }),
+            ...(publicUrlFlag === undefined ? {} : { publicUrl: publicUrlFlag }),
             localRunner: runnerName,
             poolRoot: pool,
             repos,
@@ -12209,6 +12242,24 @@ function verifyApproverByPassword(store, name, token, repos) {
     const remote = activeRemote();
     return approverByPassword(store, name, token, remote === null ? repos : repos.filter(repo => remote.allows(repo)));
 }
+/** Standard input, whole, up to `limit` bytes (null past it): never from a terminal, and never inside a remote run. */
+async function readBoundedStdin(limit) {
+    refusePrompt();
+    if (process.stdin.isTTY)
+        return null;
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of process.stdin) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+        size += bytes.length;
+        if (size > limit) {
+            process.stdin.pause();
+            return null;
+        }
+        chunks.push(bytes);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
 /** Prompts: never inside a remote run — there is nobody at this machine's terminal to answer for the person. */
 function interactive() {
     return activeRemote() === null && promptInteractive();

package/dist/people-audit-ui.d.ts

@@ -0,0 +1,14 @@
+import { type AuditAction } from "./remote-audit.js";
+import type { ApiTokenRow } from "./store.js";
+export declare const PEOPLE_AUDIT_CSS: string;
+export type PersonAuditView = {
+    name: string;
+    tokens: readonly ApiTokenRow[];
+    actions: readonly AuditAction[];
+    /** The token name the actions are filtered to, if any. */
+    token: string | null;
+    nextCursor: string | null;
+    now: Date;
+};
+export declare const personHref: (name: string, more?: Record<string, string>) => string;
+export declare function personAuditHtml(view: PersonAuditView): string;

package/dist/people-audit-ui.js

@@ -0,0 +1,38 @@
+/**
+ * People → a person: their API tokens, each with its standing and last use, and their recent remote actions
+ * (remote-audit.ts). A token's name filters the actions to it (`token-name`: a `token` query is always refused). Read-only: making, revoking and rotating tokens stay
+ * in Settings → Sessions & tokens. Never a token's secret or a ledger line's raw detail.
+ */
+import { basename } from "node:path";
+import { tokenStatus } from "./remote-audit.js";
+const e = (value) => String(value ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+const stamp = (value) => `${value.slice(0, 16).replace("T", " ")} UTC`;
+export const PEOPLE_AUDIT_CSS = `.person-audit{max-width:820px;min-width:0;overflow-wrap:anywhere}.person-audit h2{font-size:1.05rem;margin:1.25rem 0 8px}` +
+    `.person-audit .rows{display:grid;border:1px solid var(--so-line);border-radius:10px;overflow:hidden}.person-audit .row-item{padding:10px 14px;border-bottom:1px solid var(--so-line);min-width:0}` +
+    `.person-audit .row-item:last-child{border-bottom:0}.person-audit .row-item p{margin:0}.person-audit .row-item .meta{font-size:.85rem}` +
+    `.person-audit a{display:inline-flex;align-items:center;min-height:44px}.person-audit .row-item a{min-height:32px}.person-audit a:focus-visible{outline:2px solid var(--so-accent);outline-offset:2px;border-radius:4px}` +
+    `.person-audit .outcome{display:inline-block;font-size:.8rem;font-weight:600;padding:1px 8px;border-radius:999px;margin-right:8px}` +
+    `.person-audit .outcome-ok{background:var(--so-success-soft);color:var(--so-success)}.person-audit .outcome-refused{background:var(--so-warning-soft);color:var(--so-ink)}` +
+    `.person-audit .outcome-error{background:var(--so-danger-soft);color:var(--so-danger)}` +
+    `@media(max-width:600px){.person-audit .row-item a{min-height:44px}}`;
+export const personHref = (name, more = {}) => `/people?${new URLSearchParams({ person: name, ...more }).toString()}`;
+export function personAuditHtml(view) {
+    const tokens = view.tokens.length === 0 ? `<p class="meta">No API tokens.</p>` : `<div class="rows">${view.tokens.map(one => {
+        const status = tokenStatus(one, view.now);
+        return `<div class="row-item" data-token-name="${e(one.name)}"><p><a href="${e(personHref(view.name, { "token-name": one.name }))}">${e(one.name)}</a></p>` +
+            `<p class="meta">${status === "active" ? "Active" : status === "expired" ? "Expired" : "Revoked"} · ${one.access === "act" ? "Can act" : "Read only"} · ` +
+            `last used ${one.lastUsedAt === null ? "never" : e(stamp(one.lastUsedAt))}</p></div>`;
+    }).join("")}</div>`;
+    const filtered = view.token === null ? "" : `<p class="meta">With ${e(view.token)}</p><p><a href="${e(personHref(view.name))}">All tokens</a></p>`;
+    const actions = view.actions.length === 0 ? `<p class="meta">No remote actions${view.token === null ? "" : " with this token"}.</p>` : `<div class="rows">${view.actions.map(actionHtml).join("")}</div>`;
+    const older = view.nextCursor === null ? "" : `<p><a href="${e(personHref(view.name, { ...(view.token === null ? {} : { "token-name": view.token }), before: view.nextCursor }))}">Older actions</a></p>`;
+    return `<p><a href="/people">People</a></p><h1>${e(view.name)}</h1><section class="person-audit"><h2>API tokens</h2>${tokens}` +
+        `<h2>Remote activity</h2>${filtered}${actions}${older}</section>`;
+}
+function actionHtml(action) {
+    const label = action.outcome === "ok" ? "OK" : action.outcome === "refused" ? "Refused" : "Error";
+    const detail = [stamp(action.at), action.token ?? "unknown token", action.source === "mcp" ? "Agent (MCP)" : "CLI",
+        ...(action.repo === null ? [] : [basename(action.repo)]), ...(action.reason === null ? [] : [action.reason])];
+    return `<div class="row-item" data-action="${action.id}"><p><span class="outcome outcome-${action.outcome}">${label}</span>${e(action.name)}` +
+        `${action.taskId === null ? "" : ` · <a href="/t/${encodeURIComponent(action.taskId)}">${e(action.taskId)}</a>`}</p><p class="meta">${detail.map(e).join(" · ")}</p></div>`;
+}

package/dist/public-access.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Serving on a real domain (remote team, phase 3): which requests arrived safely enough to carry an API token,
+ * and when the console sends Strict-Transport-Security. Pure rules over what the socket and the one trusted proxy
+ * say; serve.ts applies them right after its Host check, and `toolroll serve check-public` probes for them.
+ *
+ * Trust comes from the socket first. Only a LOOPBACK peer is the documented same-host TLS proxy (Caddy, Cloudflare
+ * Tunnel), and only then are X-Forwarded-For (its last hop, via serve.ts's joinSourceOf) and X-Forwarded-Proto
+ * believed. Any other peer's forwarded headers are ignored: it reached us over plain HTTP from where it stands.
+ */
+/** One year, this exact host only: no includeSubDomains, no preload, so sibling names are never pinned. */
+export declare const HSTS_VALUE = "max-age=31536000";
+/** What a token-bearing request over plain HTTP from elsewhere is told. */
+export declare const USE_HTTPS = "Use HTTPS. API tokens are accepted over plain HTTP only from this computer or your tailnet; connect with the server's https:// address.";
+/**
+ * The exact loopback peers serve.ts trusts as the same-host proxy (joinSourceOf, fromThisComputer). Not all of
+ * 127/8: a proxy listening on 127.0.0.2 must not make public callers look like this computer.
+ */
+export declare const LOOPBACK_PEERS: ReadonlySet<string>;
+/** One of LOOPBACK_PEERS (brackets, an IPv6 zone and case ignored). The only loopback test that grants trust. */
+export declare function isLoopbackPeer(address: string): boolean;
+/** 127.0.0.0/8, ::1 and their IPv4-mapped forms. For naming hosts only (public-check.ts); trust uses isLoopbackPeer. */
+export declare function isLoopbackAddress(address: string): boolean;
+/** Tailscale's ranges: 100.64.0.0/10 (and its IPv4-mapped form) and fd7a:115c:a1e0::/48. */
+export declare function isTailnetAddress(address: string): boolean;
+/** How one request reached the server, as far as it can be proved. */
+export type Transport = {
+    /** The caller's address: the socket peer, or the trusted proxy's last X-Forwarded-For hop. */
+    source: string;
+    /** Proved to have arrived over HTTPS at a same-host proxy. */
+    https: boolean;
+    /** The caller is this computer or a tailnet address (WireGuard already encrypts it). */
+    privatePath: boolean;
+};
+/**
+ * The request's transport from its socket peer, the source serve.ts's joinSourceOf derived (`fwd:<hop>` only for a
+ * loopback peer) and the proxy headers. A loopback peer that forwards with `Forwarded` but no X-Forwarded-For names
+ * no caller we can read, so it is not treated as this computer.
+ */
+export declare function transportOf(request: {
+    peer: string | undefined;
+    joinSource: string;
+    forwardedProto: string | string[] | undefined;
+    forwarded: string | string[] | undefined;
+}): Transport;
+/** Requests that carry, or exist to carry, an API token: the remote CLI, the MCP gateway, and any bearer credential. */
+export declare function carriesToken(pathname: string, authorization: string | undefined): boolean;
+/** The refusal for a token sent over plain HTTP from outside this computer and the tailnet, else null. */
+export declare function plainHttpRefusal(transport: Transport, pathname: string, authorization: string | undefined): string | null;
+/** The Strict-Transport-Security value for a request to the configured public https host that arrived over HTTPS. */
+export declare function hstsFor(publicHost: string | null, host: string | undefined, transport: Transport): string | null;

package/dist/public-access.js

@@ -0,0 +1,87 @@
+/**
+ * Serving on a real domain (remote team, phase 3): which requests arrived safely enough to carry an API token,
+ * and when the console sends Strict-Transport-Security. Pure rules over what the socket and the one trusted proxy
+ * say; serve.ts applies them right after its Host check, and `toolroll serve check-public` probes for them.
+ *
+ * Trust comes from the socket first. Only a LOOPBACK peer is the documented same-host TLS proxy (Caddy, Cloudflare
+ * Tunnel), and only then are X-Forwarded-For (its last hop, via serve.ts's joinSourceOf) and X-Forwarded-Proto
+ * believed. Any other peer's forwarded headers are ignored: it reached us over plain HTTP from where it stands.
+ */
+/** One year, this exact host only: no includeSubDomains, no preload, so sibling names are never pinned. */
+export const HSTS_VALUE = "max-age=31536000";
+/** What a token-bearing request over plain HTTP from elsewhere is told. */
+export const USE_HTTPS = "Use HTTPS. API tokens are accepted over plain HTTP only from this computer or your tailnet; connect with the server's https:// address.";
+/** IPv4 dotted quad from an IPv4 or IPv4-mapped IPv6 address, else null. */
+function ipv4Of(address) {
+    const bare = address.replace(/^::ffff:/i, "");
+    const match = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(bare);
+    if (match === null)
+        return null;
+    const parts = match.slice(1).map(Number);
+    return parts.every(part => part <= 255) ? parts : null;
+}
+/** Strips brackets and an IPv6 zone so `[::1]` and `fe80::1%en0` compare as addresses. */
+const bareAddress = (address) => address.trim().replace(/^\[(.*)\]$/, "$1").replace(/%.*$/, "").toLowerCase();
+/**
+ * The exact loopback peers serve.ts trusts as the same-host proxy (joinSourceOf, fromThisComputer). Not all of
+ * 127/8: a proxy listening on 127.0.0.2 must not make public callers look like this computer.
+ */
+export const LOOPBACK_PEERS = new Set(["127.0.0.1", "::1", "::ffff:127.0.0.1"]);
+/** One of LOOPBACK_PEERS (brackets, an IPv6 zone and case ignored). The only loopback test that grants trust. */
+export function isLoopbackPeer(address) {
+    return LOOPBACK_PEERS.has(bareAddress(address));
+}
+/** 127.0.0.0/8, ::1 and their IPv4-mapped forms. For naming hosts only (public-check.ts); trust uses isLoopbackPeer. */
+export function isLoopbackAddress(address) {
+    const bare = bareAddress(address);
+    const v4 = ipv4Of(bare);
+    if (v4 !== null)
+        return v4[0] === 127;
+    return bare === "::1" || bare === "0:0:0:0:0:0:0:1";
+}
+/** Tailscale's ranges: 100.64.0.0/10 (and its IPv4-mapped form) and fd7a:115c:a1e0::/48. */
+export function isTailnetAddress(address) {
+    const bare = bareAddress(address);
+    const v4 = ipv4Of(bare);
+    if (v4 !== null)
+        return v4[0] === 100 && v4[1] >= 64 && v4[1] <= 127;
+    return /^fd7a:115c:a1e0(:|$)/.test(bare);
+}
+/** The last value of a possibly repeated, comma-separated header (the one the trusted proxy itself set). */
+const lastValue = (header) => {
+    const joined = Array.isArray(header) ? header.join(",") : header ?? "";
+    return joined.split(",").pop()?.trim().toLowerCase() ?? "";
+};
+/**
+ * The request's transport from its socket peer, the source serve.ts's joinSourceOf derived (`fwd:<hop>` only for a
+ * loopback peer) and the proxy headers. A loopback peer that forwards with `Forwarded` but no X-Forwarded-For names
+ * no caller we can read, so it is not treated as this computer.
+ */
+export function transportOf(request) {
+    const peer = request.peer ?? "";
+    if (!isLoopbackPeer(peer)) {
+        return { source: peer, https: false, privatePath: isTailnetAddress(peer) };
+    }
+    const relayed = request.joinSource.startsWith("fwd:");
+    const source = relayed ? request.joinSource.slice(4) : peer;
+    const https = lastValue(request.forwardedProto) === "https";
+    if (!relayed && request.forwarded !== undefined)
+        return { source: "unknown", https, privatePath: false };
+    return { source, https, privatePath: isLoopbackPeer(source) || isTailnetAddress(source) };
+}
+/** Requests that carry, or exist to carry, an API token: the remote CLI, the MCP gateway, and any bearer credential. */
+export function carriesToken(pathname, authorization) {
+    if (pathname === "/api/cli" || pathname.startsWith("/api/cli/") || pathname === "/mcp" || pathname.startsWith("/mcp/"))
+        return true;
+    return authorization !== undefined && /^bearer\s/i.test(authorization);
+}
+/** The refusal for a token sent over plain HTTP from outside this computer and the tailnet, else null. */
+export function plainHttpRefusal(transport, pathname, authorization) {
+    if (transport.https || transport.privatePath)
+        return null;
+    return carriesToken(pathname, authorization) ? USE_HTTPS : null;
+}
+/** The Strict-Transport-Security value for a request to the configured public https host that arrived over HTTPS. */
+export function hstsFor(publicHost, host, transport) {
+    return publicHost !== null && host === publicHost && transport.https ? HSTS_VALUE : null;
+}

package/dist/public-check.d.ts

@@ -0,0 +1,37 @@
+export type ProbeRequest = {
+    url: string;
+    headers: Record<string, string>;
+};
+export type ProbeAnswer = {
+    status: number;
+    headers: Record<string, string | string[] | undefined>;
+    body: string;
+} | {
+    error: string;
+};
+/** One bounded GET: no credentials, no redirects. */
+export type Probe = (request: ProbeRequest) => Promise<ProbeAnswer>;
+export type Finding = {
+    check: "public-url" | "allow-host" | "local" | "host" | "forwarding" | "certificate" | "proxy" | "hsts";
+    message: string;
+};
+/** The default probe: node's http/https with the platform trust store, a timeout and a 4 KB body cap. */
+export declare const networkProbe: Probe;
+/** The exact https origin --public-url must be, as serve.ts requires it; else what is wrong with it. */
+export declare function publicOriginOf(value: string | undefined): URL | string;
+/** Every problem with serving on --public-url, in a fixed order; an empty list means ready. */
+export declare function checkPublic(options: {
+    publicUrl: string | undefined;
+    port: number;
+    allowHosts: readonly string[];
+}, probe?: Probe): Promise<Finding[]>;
+/** The command: findings as lines (or one envelope), exit 0 when ready, 1 when not, 2 for a malformed --port. */
+export declare function checkPublicCommand(flags: Map<string, string | true>, context: {
+    write: (line: string) => void;
+    json: boolean;
+    envelope: (payload: {
+        ok: boolean;
+        command: string;
+    } & Record<string, unknown>) => string;
+    probe?: Probe;
+}): Promise<number>;

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";