toolroll 0.9.44 → 0.9.46

package/dist/operate.d.ts

@@ -39,6 +39,8 @@ export type OperateOptions = {
     releaseIo?: ReleaseIo;
     /** Injected by tests: the bin whose real path says how Toolroll was installed. */
     installBin?: string;
+    /** Tests: what `serve check-public` fetches with instead of the network. */
+    publicProbe?: import("./public-check.js").Probe;
     /** Injected by tests: where `storage` looks for leftover test temp folders (default: the temp folder and /tmp). */
     tempRoots?: readonly string[];
     openDatabase?: (file: string) => Store;
@@ -142,6 +144,7 @@ export declare function runOperateAs(argv: string[], opts: {
     write: (s: string) => void;
     files?: Record<string, string>;
     source?: RemoteSource;
+    tool?: string;
     options?: OperateOptions;
 }): Promise<number>;
 /** Durably create the login file BEFORE the bootstrap commits (arc 2

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";
@@ -154,7 +158,7 @@ import { ask as promptAsk, askHidden as promptHidden, confirm as promptConfirm,
 import { runMateCli, answerContextLines } from "./mate-cli.js";
 import { confirmCoordinatorProposal, dismissCoordinatorProposal } from "./mate-doors.js";
 import { verifyApproverByPassword as approverByPassword } from "./principal.js";
-import { activeRemote, REMOTE_MESSAGES, REMOTE_REFUSED_FLAGS, REMOTE_SCOPES, RemoteRefusal, remoteAllows, remoteProjectOf, remoteRowOf, remoteSecret, reproveRemote, withRemote } from "./operate-remote.js";
+import { activeRemote, REMOTE_MESSAGES, REMOTE_REFUSED_FLAGS, REMOTE_SCOPES, RemoteRefusal, remoteAllows, remoteLensOf, remoteProjectOf, remoteRowOf, remoteSecret, reproveRemote, withRemote } from "./operate-remote.js";
 import { projectAuthority } from "./project-access.js";
 import { authorizedProject, canonicalProject, projectName, resolveCeiling } from "./project.js";
 import { tally, spendLine } from "./summary.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);
@@ -975,17 +994,20 @@ export async function runOperateAs(argv, opts) {
     const file = store.databaseFile() ?? options.databaseFile;
     if (file === undefined)
         return refuse("failed", "The server's database has no file.", project.repo, project.taskId);
-    const run = Object.freeze({ account: principal.account, scope: proved.scope, tokenName: proved.tokenName, source, secret: remoteSecret(), allows, files: Object.freeze({ ...(opts.files ?? {}) }) });
+    // The task a `task add` filed is only known once it runs; the final history line names it.
+    let filed = null;
+    const run = Object.freeze({ account: principal.account, scope: proved.scope, tokenName: proved.tokenName, source, secret: remoteSecret(), allows,
+        lens: remoteLensOf(store, scope, allows), noteTask: (taskId) => { filed = taskId; }, files: Object.freeze({ ...(opts.files ?? {}) }) });
     record("requested", project.repo, project.taskId, null);
     let code;
     try {
         code = await withRemote(run, () => dispatchOn(root, parsed.positional, parsed.flags, parsed.repoList, { store, write, json, file, now }, options, go => withActor({ account: principal.account, lead: false }, () => projectAuthority.run({ actor: principal.account, repo: project.repo }, go))));
     }
     catch (error) {
-        record("failed", project.repo, project.taskId, null);
+        record("failed", project.repo, filed ?? project.taskId, null);
         throw error;
     }
-    record(code === EXIT.ok ? "done" : code === EXIT.refused ? "refused" : code === EXIT.usage ? "usage" : "failed", project.repo, project.taskId, null);
+    record(code === EXIT.ok ? "done" : code === EXIT.refused ? "refused" : code === EXIT.usage ? "usage" : "failed", project.repo, filed ?? project.taskId, null);
     return code;
 }
 /** A file a remote caller sent with the request, by the argument that names it; never a path on this machine. */
@@ -1067,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":
@@ -1200,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":
@@ -1307,7 +1338,9 @@ async function readyCommand(flags, context) {
             write(`  ${task.id}  ${task.title}`);
         return EXIT.ok;
     }
-    const ready = store.listReady(now);
+    // A remote person limited to some projects (remoteLensOf) sees only theirs, counted over those alone.
+    const lens = context.principal?.lens ?? null;
+    const ready = store.listReady(now).filter(ref => lens === null || ref.repo !== null && lens.includes(ref.repo));
     const described = ready.map(ref => describeRef(store, ref, now));
     const dispatchableCount = described.filter(one => diagnosisIsDispatchable(one.dispatch)).length;
     const pauses = openAuthPauses(store);
@@ -5073,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.
@@ -8632,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")
@@ -8858,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,
@@ -10097,6 +10135,13 @@ async function statusCommand(positional, flags, context) {
         return fail(context.write, context.json, command, "usage", "Use `toolroll status [--json]`.", EXIT.usage);
     // Whose lead the status line follows: the lead's own person, else the remembered login; nobody shows no lead.
     const viewer = currentActor()?.account ?? readLoginFile(join(dirname(context.databaseFile), UP_LOGIN_FILE))?.name ?? null;
+    // A remote person limited to some projects sees only those (remoteLensOf): their tasks and counts, and nothing
+    // that belongs to the installation or other projects (updates, integrations, builds by project, unsent replies).
+    const lens = context.principal?.lens ?? null;
+    if (lens !== null) {
+        const status = installationStatus(context.store, context.clock(), viewer, lens);
+        return succeed(context.write, context.json, command, { ...status, projects: [] }, () => renderInstallationStatus(status, true));
+    }
     const status = installationStatus(context.store, context.clock(), viewer);
     // One line, only when a newer Toolroll exists; offline or switched off says nothing.
     const current = PACKAGE_VERSION;
@@ -10427,6 +10472,7 @@ async function addTask(positional, flags, context) {
             throw new RemoteRefusal("not-found", "Not found.");
         }
     }
+    remote?.noteTask(filedId);
     store.stampFiledVia(store.refFor(BUILT_IN, filedId).id, "cli");
     // Placement is explicit, never inferred from where the command happened to
     // run: a task filed from the wrong directory would silently bind to it.
@@ -10707,7 +10753,9 @@ function listTasks(flags, context) {
     }
     let page;
     try {
-        page = workIndexPage(store, now, { principal: 'operator', repos: null, includeUnplaced: true }, {
+        // A remote person limited to some projects (remoteLensOf) pages and counts only theirs.
+        const lens = context.principal?.lens ?? null;
+        page = workIndexPage(store, now, { principal: 'operator', repos: lens, includeUnplaced: lens === null }, {
             view: parseWorkView(rawView ?? null), limit, cursor: text(flags, 'cursor') ?? null,
             ...(wanted === undefined ? {} : { state: wanted }),
             ...(text(flags, 'repo') === undefined ? {} : { project: text(flags, 'repo') }),
@@ -10754,13 +10802,21 @@ function showTask(positional, context) {
     // whatever readiness this task's runners have reported.
     const routed = routeOfTask(store, id, ref, now);
     const readiness = store.readinessLookupFor(ref.repo, ref.assignedRunner, now);
+    const lens = context.principal?.lens ?? null;
+    const access = { principal: "operator", repos: lens, includeUnplaced: lens === null, dependencyRepos: lens };
+    const blockers = store.blockers(id);
+    const visibleBlockers = lens === null ? blockers : blockers.filter(blocker => {
+        const repo = store.lookupRef(blocker)?.repo;
+        return repo != null && lens.includes(repo);
+    });
     const detail = {
         task,
-        work: taskWorkSummaryOf(store, id, now, { principal: "operator", repos: null, includeUnplaced: true }),
-        assignment: assignmentBrief(assignmentOf(store, id, now, { principal: "operator", repos: null, includeUnplaced: true }, context.evidenceRoot)),
+        work: taskWorkSummaryOf(store, id, now, access),
+        assignment: assignmentBrief(assignmentOf(store, id, now, access, context.evidenceRoot)),
         ref: ref.id,
-        blockedBy: store.blockers(id),
-        position: store.queuePosition(id),
+        // One phrase for every inaccessible blocker, so even their number stays private.
+        blockedBy: visibleBlockers.length === blockers.length ? visibleBlockers : [...visibleBlockers, "a task in another project"],
+        position: lens === null ? store.queuePosition(id) : null,
         reservedFor: ref.assignedRunner,
         hold: store.activeHold(ref.id, now),
         claim: currentClaim(store, ref.id, now),
@@ -10785,7 +10841,7 @@ function showTask(positional, context) {
         // The one automatic review of the latest build: HIGH findings, suggested
         // follow-ups (MEDIUM/LOW), or why it was not reviewed.
         automaticReview: latestFinished === null ? null : buildReviewOf(store, latestFinished.id),
-        dispatch: diagnoseTaskDispatch(store, id, now),
+        dispatch: diagnoseTaskDispatch(store, id, now, lens),
         // v52: the exact-run control the console shows — Stop, Stopping,
         // Paused (resume), or the review-retry door — and every stop on record.
         control: taskControlOf(store, ref.id, now),
@@ -12186,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>;