toolroll 0.9.63 → 0.9.65

package/dist/terminal-catalog.js

@@ -0,0 +1,129 @@
+/**
+ * Live terminals, written down for the updater (docs/plans/live-terminal.md, review round 2 finding 7). Terminals live
+ * in the console's memory, but an update is decided by another process, so each one is a row in a small catalog
+ * beside the database (`<db>.terminals.sqlite`), as the coding workspace keeps its own:
+ *
+ * - a start inserts its row before any work, and an update's gate (a trigger) refuses that insert while the update
+ *   owns admission: no terminal starts during a drain;
+ * - a row is `starting` or `running` until the terminal's sweep ends, then deleted — or kept as `uncertain` when the
+ *   sweep couldn't prove its processes gone, until the terminal is removed; the updater counts rows whose console is
+ *   still alive as active work, so "update when idle" waits for running and unproved terminals;
+ * - rows of a console that is gone are stale (its programs went with it, or are swept at its next start).
+ */
+import { chmodSync, lstatSync } from "node:fs";
+import { processMayBeAlive } from "./process-liveness.js";
+import { sqliteRuntime } from "./sqlite-runtime.js";
+const gatePrefix = "so_terminal_update_";
+const PAUSED = "Toolroll is updating. Running terminals keep going; new ones can start after the update.";
+const SCHEMA = "CREATE TABLE IF NOT EXISTS live_terminal (id TEXT PRIMARY KEY, console_pid INTEGER NOT NULL, state TEXT NOT NULL CHECK (state IN ('starting','running','uncertain')), at TEXT NOT NULL)";
+export function terminalCatalogPath(orders) {
+    const main = orders.prepare("PRAGMA database_list").all().find(row => row["name"] === "main")?.["file"];
+    return typeof main === "string" && main !== "" ? `${main}.terminals.sqlite` : null;
+}
+function exists(file) {
+    try {
+        return lstatSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function open(file, readOnly) {
+    if (exists(file) && lstatSync(file).isSymbolicLink())
+        throw Error("The terminal catalog is linked, not a regular database.");
+    const db = new (sqliteRuntime().DatabaseSync)(file, { readOnly });
+    db.exec("PRAGMA busy_timeout=1000");
+    return db;
+}
+/** The updater's read: never creates the catalog. */
+function withCatalog(orders, absent, readOnly, action) {
+    const file = terminalCatalogPath(orders);
+    if (file === null || !exists(file))
+        return absent;
+    const db = open(file, readOnly);
+    try {
+        return action(db);
+    }
+    finally {
+        db.close();
+    }
+}
+/** The console's ledger: creates the catalog, drops rows of consoles that are gone, and writes its own. */
+export function openTerminalLedger(orders, alive = pid => processMayBeAlive(pid, false)) {
+    const file = terminalCatalogPath(orders);
+    if (file === null)
+        return null;
+    const db = open(file, false);
+    chmodSync(file, 0o600);
+    db.exec(SCHEMA);
+    for (const row of db.prepare("SELECT DISTINCT console_pid FROM live_terminal").all()) {
+        const pid = Number(row["console_pid"]);
+        if (pid !== process.pid && !alive(pid))
+            db.prepare("DELETE FROM live_terminal WHERE console_pid=?").run(pid);
+    }
+    return {
+        reserve(id) {
+            // Fail closed even where this catalog had no gate to install (it didn't exist yet when the update began): the main
+            // database's own admission pause refuses too.
+            if (orders.prepare("SELECT 1 FROM sqlite_master WHERE type='trigger' AND name GLOB 'so_desktop_update_*' LIMIT 1").get() !== undefined)
+                throw new Error(PAUSED);
+            try {
+                db.prepare("INSERT INTO live_terminal (id, console_pid, state, at) VALUES (?, ?, 'starting', ?)").run(id, process.pid, new Date().toISOString());
+            }
+            catch (error) {
+                throw new Error(error instanceof Error && error.message.includes(PAUSED) ? PAUSED : "No terminal can start right now (its record couldn't be written).");
+            }
+        },
+        running(id) { db.prepare("UPDATE live_terminal SET state='running', at=? WHERE id=?").run(new Date().toISOString(), id); },
+        // A sweep that couldn't prove its processes gone stays written down: the updater counts it while this console lives.
+        release(id, cleanup) {
+            try {
+                if (cleanup === "uncertain")
+                    db.prepare("UPDATE live_terminal SET state='uncertain', at=? WHERE id=?").run(new Date().toISOString(), id);
+                else
+                    db.prepare("DELETE FROM live_terminal WHERE id=?").run(id);
+            }
+            catch { /* the next start drops it as stale */ }
+        },
+        forget(id) { try {
+            db.prepare("DELETE FROM live_terminal WHERE id=?").run(id);
+        }
+        catch { /* stale later */ } },
+    };
+}
+function gateStatement(id) {
+    if (!/^[a-f0-9-]{36}$/.test(id))
+        throw Error("Invalid update identity.");
+    return `CREATE TRIGGER ${gatePrefix}start BEFORE INSERT ON live_terminal BEGIN SELECT RAISE(ABORT, '${PAUSED} [${id}]'); END`;
+}
+function changeGate(db, id, install) {
+    const wanted = gateStatement(id);
+    db.exec("BEGIN IMMEDIATE");
+    try {
+        db.exec(SCHEMA);
+        const rows = db.prepare("SELECT name, sql FROM sqlite_master WHERE type='trigger' AND name GLOB 'so_terminal_update_*'").all();
+        if (rows.some(row => String(row["sql"]) !== wanted))
+            throw Error("Another or unrecognized update owns terminal admission. Its gate was preserved.");
+        if (install && rows.length === 0)
+            db.exec(wanted);
+        if (!install)
+            for (const row of rows)
+                db.exec(`DROP TRIGGER "${String(row["name"])}"`);
+        db.exec("COMMIT");
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+    }
+}
+export function installTerminalUpdateGate(orders, id) { withCatalog(orders, undefined, false, db => changeGate(db, id, true)); }
+export function removeTerminalUpdateGate(orders, id) { withCatalog(orders, undefined, false, db => changeGate(db, id, false)); }
+/** Terminals starting or running in a console that is still alive: active work an update waits for. */
+export function activeTerminalUpdateWork(orders, alive = pid => processMayBeAlive(pid, false)) {
+    return withCatalog(orders, { terminals: 0 }, true, db => {
+        if (!db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='live_terminal'").get())
+            return { terminals: 0 };
+        const rows = db.prepare("SELECT console_pid FROM live_terminal").all();
+        return { terminals: rows.filter(row => alive(Number(row["console_pid"]))).length };
+    });
+}

package/dist/text-limits.d.ts

@@ -68,6 +68,8 @@ export declare const TEXT_LIMITS: {
     readonly triggerState: 40;
     readonly triggerWebhookTitle: 120;
     readonly triggerWebhookField: 80;
+    /** v126: a Sentry or Vercel project (or Vercel team) a signed webhook is scoped to. */
+    readonly triggerWebhookScope: 120;
     readonly triggerFolder: 100;
     readonly triggerSender: 300;
     readonly triggerSubject: 100;

package/dist/text-limits.js

@@ -68,6 +68,8 @@ export const TEXT_LIMITS = {
     triggerState: 40,
     triggerWebhookTitle: 120,
     triggerWebhookField: 80,
+    /** v126: a Sentry or Vercel project (or Vercel team) a signed webhook is scoped to. */
+    triggerWebhookScope: 120,
     triggerFolder: 100,
     triggerSender: 300,
     triggerSubject: 100,

package/dist/tool-broker.d.ts

@@ -22,6 +22,8 @@ export type ToolBroker = {
     /** The launch's token: the agent's only key to its tools. */
     token: string;
     url: (name: string) => string;
+    /** Its loopback port: the one a confined network leaves reachable for its agent (agent-fence.ts NetworkFence). */
+    port: number;
     /** The local servers running now (the fence tests read them). */
     pids: () => number[];
     /** Revoke the token, stop every server, close the port. */

package/dist/tool-broker.js

@@ -357,6 +357,7 @@ export async function startToolBroker(tools, options = {}) {
     return {
         token,
         url: name => `http://127.0.0.1:${port}/mcp/${name}`,
+        port,
         pids: () => [...local.values()].map(one => one.pid()).filter((pid) => pid !== null),
         close: () => {
             revoked = true;

package/dist/toolroll-update-ui.js

@@ -4,7 +4,7 @@
  * and a one-time "What's new" card afterwards. The work itself is the
  * `toolroll update` command (toolroll-update.ts), started as its own job.
  */
-import { html, postForm, replaceMarkup } from "./html.js";
+import { html, postForm, replaceMarkup, reauth } from "./html.js";
 import { STEP_WORDS, UPDATE_STEPS, runtimeUpdateTerminal } from "./toolroll-update.js";
 const clock = (iso) => { const d = new Date(iso); return `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`; };
 export const UPDATES_CSS = `.updates{max-width:640px;min-width:0;overflow-wrap:anywhere}.updates .card{margin:0 0 16px}.updates h2{margin:0;font-size:1.0625rem}.updates .card>p{margin:4px 0 0}` +
@@ -69,7 +69,7 @@ export function updatesHtml(view, notice) {
                         : latest === null ? html `<h2>Toolroll ${view.current}</h2><p class="meta">Couldn’t check for a newer release: ${"problem" in view.latest ? view.latest.problem : ""}</p>`
                             : html `<h2>Toolroll ${view.current} is up to date</h2>`;
     const form = newer && !["npx", "source", "desktop"].includes(view.method.kind)
-        ? postForm("/settings/updates", html `<label class="step-up">Your Toolroll password<input type="password" name="password" autocomplete="current-password" required></label><div class="update-actions"><button type="submit" name="when" value="now" class="primary">Update now</button><button type="submit" name="when" value="when-idle">When idle</button><button type="submit" name="when" value="tonight">Tonight (03:00)</button></div>`, { hidden: { version: latest } })
+        ? postForm("/settings/updates", html `${reauth(html `<label class="step-up">Your Toolroll password<input type="password" name="password" autocomplete="current-password" required></label>`)}<div class="update-actions"><button type="submit" name="when" value="now" class="primary">Update now</button><button type="submit" name="when" value="when-idle">When idle</button><button type="submit" name="when" value="tonight">Tonight (03:00)</button></div>`, { hidden: { version: latest } })
         : "";
     const rollback = view.rollbackTo !== null ? html `<p class="meta">To go back to ${view.rollbackTo}: <code>toolroll update --rollback</code></p>` : "";
     return html `<section class="updates">${note}${whatsNew}${j ? outcomeHtml(j) : ""}<div class="card" data-update-state="${newer ? "available" : "current"}">${state}${form}${rollback}</div></section>`;

package/dist/toolroll-update.js

@@ -32,10 +32,11 @@ import { createRequire } from "node:module";
 import { clearWords, durableJson, LINGERING_LIMIT_MS, lingeringRun, lingeringWords, settleLeftoverRecords, sqliteLock, desktopUpdateWaitingOf, stoppedWaitingWords, updateWaitingWords, verifiedDatabaseBackup } from "./desktop-update.js";
 import { activeUpdateWork, freezeUpdateGate, installUpdateGate, removeUpdateGate, updateAdmissionPaused, updateGateOwned } from "./desktop-update-gate.js";
 import { processMayBeAlive } from "./process-liveness.js";
+import { removeTerminalUpdateGate } from "./terminal-catalog.js";
 import { assertCodingUpdateStopped, backupCodingCatalog, codingCatalogExists, releaseStaleCodingOwner, removeCodingUpdateGate } from "./coding-update.js";
 import { installLaunchdService, launchdPlist, stopLaunchdService, writeFileDurably } from "./daemon.js";
 import { NAME } from "./names.js";
-import { orphanKey, updateSafeSchema, V117_RENAMED_COLUMNS, V117_RENAMED_TABLES, V118_MERGED_TABLES, V119_ADDED_COLUMNS, V120_ADDED_COLUMNS, V121_ADDED_COLUMNS, V122_ADDED_COLUMNS, V123_ADDED_COLUMNS } from "./store.js";
+import { orphanKey, updateSafeSchema, V117_RENAMED_COLUMNS, V117_RENAMED_TABLES, V118_MERGED_TABLES, V119_ADDED_COLUMNS, V120_ADDED_COLUMNS, V121_ADDED_COLUMNS, V122_ADDED_COLUMNS, V123_ADDED_COLUMNS, V125_ADDED_COLUMNS, V126_ADDED_COLUMNS, V128_ADDED_COLUMNS, V129_ADDED_COLUMNS } from "./store.js";
 import { isNewer, REGISTRY } from "./releases.js";
 import { markNeverIndex } from "./never-index.js";
 import { readRuntimeUpdateJournal, RUNTIME_PHASES, RUNTIME_UPDATE_STEPS, stagedStartedAt, updaterStartingOf } from "./contracts/update-journal.js";
@@ -373,6 +374,8 @@ function addedColumns(...versions) {
     }
     return rules;
 }
+/** Rules on tables that later gained declared columns (addedColumns merges into these instead of replacing them). */
+const EARLIER_RULES = { flow_trigger: { fromRoutines: "trigger" } };
 const HISTORY_RULES = {
     ...Object.fromEntries(Object.entries(CHAT_MOVES).map(([table, moved]) => [table, { moved }])),
     action_ledger: { appendOnly: true }, ledger_seal: { appendOnly: true }, ledger_checkpoint: { appendOnly: true },
@@ -401,7 +404,11 @@ const HISTORY_RULES = {
     // v121: live steering's columns and a run's attempt key read none, and no sends, the same way.
     // v122: a project's recorded remote reads none the same way.
     // v123: a plan authorization's basis reads the operating mode, and a trigger firing reads not on time and no script ran.
-    ...addedColumns(V119_ADDED_COLUMNS, V120_ADDED_COLUMNS, V121_ADDED_COLUMNS, V122_ADDED_COLUMNS, V123_ADDED_COLUMNS),
+    // v126: a receipt's state, acceptance time and held item, a trigger's credential generation and turned-away count,
+    // and who made a card read none, 0, or none. A table with an earlier rule (flow_trigger's v115 move) keeps it too.
+    // v128: a lead message's pending flag reads waiting exactly for a team queue's unadmitted operator message.
+    ...Object.fromEntries(Object.entries(addedColumns(V119_ADDED_COLUMNS, V120_ADDED_COLUMNS, V121_ADDED_COLUMNS, V122_ADDED_COLUMNS, V123_ADDED_COLUMNS, V125_ADDED_COLUMNS, V126_ADDED_COLUMNS, V128_ADDED_COLUMNS, V129_ADDED_COLUMNS))
+        .map(([table, rule]) => [table, { ...EARLIER_RULES[table], ...rule }])),
 };
 /** The tables a migration may remove whole (v115's removed features). */
 export const RETIRED_TABLES = Object.freeze(Object.keys(HISTORY_RULES).filter(name => HISTORY_RULES[name].retired));
@@ -908,8 +915,10 @@ function ungate(j) {
         db.exec("PRAGMA busy_timeout=5000");
         if (updateGateOwned(db, j.id))
             removeUpdateGate(db, j.id);
-        else
+        else {
             removeCodingUpdateGate(db, j.id);
+            removeTerminalUpdateGate(db, j.id);
+        }
     }
     finally {
         db.close();
@@ -920,6 +929,7 @@ function ungateCoding(j) {
     try {
         db.exec("PRAGMA busy_timeout=5000");
         removeCodingUpdateGate(db, j.id);
+        removeTerminalUpdateGate(db, j.id);
     }
     finally {
         db.close();

package/dist/tools-ui.js

@@ -1,6 +1,6 @@
 /** Settings → Tools: one project's MCP servers, in plain words. Secrets are
  * entered here and nowhere else, and never shown again. */
-import { html, postForm } from "./html.js";
+import { html, postForm, reauth } from "./html.js";
 import { brandMarkHtml, TILE_PHONE } from "./brand-mark.js";
 import { signedIn } from "./oauth-run-token.js";
 import { credentialModeOf, toolCommandLine, toolStanding } from "./project-tools.js";
@@ -15,7 +15,7 @@ export function toolsProjectPicker(projects, chosen, keep = {}) {
 }
 /** Choosing another project marks every form on the page as stale before it reloads, so a tap racing the reload is refused. */
 export const TOOLS_PROJECT_SCRIPT = `(function(){var s=document.querySelector('select[data-tools-project]');if(!s)return;s.addEventListener('change',function(){document.querySelectorAll('input[name=shown]').forEach(function(i){i.value=s.value;});});})();`;
-const password = html `<label>Your Toolroll password<input type="password" name="password" autocomplete="current-password" required></label>`;
+const password = html `${reauth(html `<label>Your Toolroll password<input type="password" name="password" autocomplete="current-password" required></label>`)}`;
 function toolCard(one, base, manage, project, research = null) {
     const { tool, secretsSet } = one;
     const standing = toolStanding(tool, secretsSet);

package/dist/webhook-limits.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Webhook floods (docs/plans/webhook-tasks.md §4): how many deliveries a trigger's address may fail in a minute. Held
+ * in memory per store (a restart forgets it, which is harmless: it protects the process and the database's write rate,
+ * not anything durable). It counts only what doesn't prove itself — a bad, missing or stale signature, an address that
+ * isn't set up, an unknown address, and every delivery to an unsigned webhook (nothing proves those) — so a stranger
+ * holding a leaked address can't crowd out the deliveries that are signed.
+ */
+import type { Store } from "./store.js";
+/** At most this many unproven deliveries per address a minute; over it, further ones are answered 429 and do nothing. */
+export declare const UNPROVEN_PER_MINUTE = 60;
+/** Addresses that match no trigger share one count. */
+export declare const UNKNOWN_ADDRESS = "unknown";
+/** Count one unproven delivery to `address` at `now`. Whether it is over the minute's limit, and when to try again. */
+export declare function countUnproven(store: Store, address: string, now: Date): {
+    over: false;
+} | {
+    over: true;
+    retryAfterSeconds: number;
+};
+/** At most this many cards a trigger makes in a rolling hour (counted when each card is made). */
+export declare const CARDS_PER_HOUR = 30;
+/** At most this many signed deliveries a trigger holds while it waits for room; beyond it, deliveries are turned away. */
+export declare const HELD_AT_MOST = 200;

package/dist/webhook-limits.js

@@ -0,0 +1,30 @@
+/** At most this many unproven deliveries per address a minute; over it, further ones are answered 429 and do nothing. */
+export const UNPROVEN_PER_MINUTE = 60;
+const WINDOW_MS = 60_000;
+/** Addresses that match no trigger share one count. */
+export const UNKNOWN_ADDRESS = "unknown";
+const counters = new WeakMap();
+/** Count one unproven delivery to `address` at `now`. Whether it is over the minute's limit, and when to try again. */
+export function countUnproven(store, address, now) {
+    let counter = counters.get(store);
+    if (counter === undefined) {
+        counter = new Map();
+        counters.set(store, counter);
+    }
+    const at = now.getTime();
+    const recent = (counter.get(address) ?? []).filter(one => one > at - WINDOW_MS);
+    recent.push(at);
+    // Keep at most one over the limit: the count only needs to know it is over, and memory stays bounded per address.
+    counter.set(address, recent.slice(-(UNPROVEN_PER_MINUTE + 1)));
+    // Bounded across addresses too: the oldest addresses are forgotten first.
+    if (counter.size > 10_000)
+        counter.delete(counter.keys().next().value);
+    if (recent.length <= UNPROVEN_PER_MINUTE)
+        return { over: false };
+    const oldest = recent[recent.length - UNPROVEN_PER_MINUTE - 1];
+    return { over: true, retryAfterSeconds: Math.max(1, Math.ceil((oldest + WINDOW_MS - at) / 1000)) };
+}
+/** At most this many cards a trigger makes in a rolling hour (counted when each card is made). */
+export const CARDS_PER_HOUR = 30;
+/** At most this many signed deliveries a trigger holds while it waits for room; beyond it, deliveries are turned away. */
+export const HELD_AT_MOST = 200;

package/dist/webhook-readers.d.ts

@@ -0,0 +1,56 @@
+import type { WebhookSender } from "./webhook-signing.js";
+/** A webhook trigger's reading settings (its saved config, defaults filled). */
+export type ReaderSettings = {
+    sender: WebhookSender;
+    title: string;
+    titleField: string | null;
+    bodyField: string | null;
+    idField: string | null;
+    urlField: string | null;
+    project: string | null;
+    team: string | null;
+};
+/** What one delivery is, once read: an item (with the outside thing's identity and link, when it has them), a delivery
+ * whose configured identity couldn't be used (made into nothing, with why), or one that isn't for this flow. */
+export type ReadDelivery = {
+    kind: "item";
+    identity: string | null;
+    url: string | null;
+    title: string;
+    description: string;
+    label: string;
+} | {
+    kind: "skip";
+    why: string;
+} | {
+    kind: "ignored";
+    why: string;
+};
+/** Whether outside words could hold a key or password (the same check cards' words get). */
+export declare const looksSecret: (value: string) => boolean;
+/** Where a sender's links may point: its own host, and (for Sentry) the organisation subdomains under it. */
+export type LinkHosts = readonly {
+    host: string;
+    subdomains: boolean;
+}[];
+export declare const SENTRY_HOSTS: LinkHosts;
+export declare const VERCEL_HOSTS: LinkHosts;
+/**
+ * A link kept from a delivery: absolute https, at most 2,000 characters, no user information, and with its query and
+ * fragment dropped (where tokens travel). `hosts` narrows it to a sender's own site (and its subdomains). Null when it
+ * isn't one, or when what is left could still hold a secret.
+ */
+export declare function safeLink(value: unknown, hosts: LinkHosts | null): string | null;
+/** The identity words a key may carry: at most 120 characters, nothing hidden, and nothing that looks like a secret. */
+export declare function identityOf(value: unknown): {
+    ok: true;
+    id: string;
+} | {
+    ok: false;
+    why: string;
+};
+/** Whether each provider's reader has read a real, captured delivery (test/fixtures/webhooks/*.captured.json), or only
+ * its sender's documented examples so far: the panel says which until a captured one is in the suite. */
+export declare const READER_CAPTURED: Record<"sentry" | "vercel", boolean>;
+/** What a proven delivery says, by its sender's reader. */
+export declare function readDelivery(body: unknown, settings: ReaderSettings): ReadDelivery;

package/dist/webhook-readers.js

@@ -0,0 +1,138 @@
+/**
+ * What a proven webhook delivery says, read by its sender's reader (docs/plans/webhook-tasks.md §2). A signature proves
+ * who sent a delivery, not that it belongs in this flow: Sentry's and Vercel's readers check its shape, its action and
+ * the configured scope first, and only then give it an identity. Anything else is ignored, with why, and claims no
+ * identity. The generic senders pick their fields by dot-paths. Every outside value is screened for secrets before it
+ * is used anywhere (a key, a held item, a card, a task), and every link is made safe before it is kept.
+ */
+import { scanForSecrets } from "./evidence.js";
+const HIDDEN = /[\u0000-\u001f\u007f​-‏‪-‮⁦-⁩]/;
+const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+const pick = (body, path) => path.split(".").reduce((node, part) => record(node)[part], body);
+const text = (value) => typeof value === "string" && value.trim() !== "" ? value.trim() : null;
+/** A string or a safe integer, as an identity's words exactly as sent; anything else isn't one. */
+const idWords = (value) => typeof value === "string" ? value : typeof value === "number" && Number.isSafeInteger(value) ? String(value) : null;
+/** Whether outside words could hold a key or password (the same check cards' words get). */
+export const looksSecret = (value) => scanForSecrets(value).length > 0;
+export const SENTRY_HOSTS = [{ host: "sentry.io", subdomains: true }];
+export const VERCEL_HOSTS = [{ host: "vercel.com", subdomains: false }];
+/**
+ * A link kept from a delivery: absolute https, at most 2,000 characters, no user information, and with its query and
+ * fragment dropped (where tokens travel). `hosts` narrows it to a sender's own site (and its subdomains). Null when it
+ * isn't one, or when what is left could still hold a secret.
+ */
+export function safeLink(value, hosts) {
+    if (typeof value !== "string" || value.length > 2000 || HIDDEN.test(value))
+        return null;
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== "https:" || url.username !== "" || url.password !== "")
+        return null;
+    const host = url.hostname.toLowerCase();
+    if (hosts !== null && !hosts.some(one => host === one.host || (one.subdomains && host.endsWith(`.${one.host}`))))
+        return null;
+    const kept = `${url.origin}${url.pathname}`;
+    // Judged as it will be kept: an address that only normalises past 2,000 characters (escaped non-ASCII) isn't kept.
+    if (kept.length > 2000)
+        return null;
+    // Screened as kept and as read: a token spelled with percent-escapes is the same token. A path that won't decode isn't kept.
+    let decoded;
+    try {
+        decoded = decodeURIComponent(url.pathname);
+    }
+    catch {
+        return null;
+    }
+    return looksSecret(kept) || looksSecret(decoded) || HIDDEN.test(decoded) ? null : kept;
+}
+/** The identity words a key may carry: at most 120 characters, nothing hidden, and nothing that looks like a secret. */
+export function identityOf(value) {
+    const sent = idWords(value);
+    if (sent === null || sent.trim() === "")
+        return { ok: false, why: "its identity is missing" };
+    // Judged as sent, before anything is trimmed: padding, hidden characters or length make it unusable, never another id.
+    if (sent.length > 120 || HIDDEN.test(sent) || sent !== sent.trim())
+        return { ok: false, why: "its identity isn't usable" };
+    if (looksSecret(sent))
+        return { ok: false, why: "it looked like it held a key or password" };
+    return { ok: true, id: sent };
+}
+/** Sentry's API address for an event names its project's slug (…/api/0/projects/<org>/<project>/events/<id>/): read
+ * only from that exact shape on Sentry's own host. */
+function sentrySlugOf(value) {
+    const link = typeof value === "string" ? value : "";
+    const match = /^https:\/\/(?:[a-z0-9-]+\.)?sentry\.io\/api\/0\/projects\/[a-z0-9_-]+\/([a-z0-9_-]+)\/events\/[A-Za-z0-9-]+\/?$/.exec(link);
+    return match?.[1] ?? null;
+}
+/** Sentry: an issue alert (action "triggered", with the event) or a new issue (action "created", with the issue). */
+function readSentry(body, settings) {
+    const action = text(record(body)["action"]);
+    const data = record(record(body)["data"]);
+    const alert = action === "triggered" && Object.keys(record(data["event"])).length > 0;
+    const created = action === "created" && Object.keys(record(data["issue"])).length > 0;
+    // A fixed reason: nothing the sender wrote is kept for an event Toolroll doesn't take.
+    if (!alert && !created)
+        return { kind: "ignored", why: "not an issue alert or a new issue" };
+    const thing = record(alert ? data["event"] : data["issue"]);
+    // Scope from the body alone (the resource header isn't signed): the project's id or slug, as Sentry sends it.
+    if (settings.project !== null) {
+        const project = record(thing["project"]);
+        // An alert's event names its project by number, and by slug only in its API address; a new issue names both.
+        const names = [idWords(thing["project"]), idWords(project["id"]), text(project["slug"]), sentrySlugOf(thing["url"])].filter((one) => one !== null);
+        if (!names.some(one => one.toLowerCase() === settings.project.toLowerCase()))
+            return { kind: "ignored", why: "from another Sentry project" };
+    }
+    const identity = identityOf(alert ? thing["issue_id"] : thing["id"]);
+    if (!identity.ok)
+        return { kind: "skip", why: identity.why };
+    const title = text(thing["title"]) ?? settings.title;
+    const culprit = text(thing["culprit"]);
+    return { kind: "item", identity: identity.id, url: safeLink(thing["web_url"], SENTRY_HOSTS), title, description: culprit === null ? "From a Sentry issue." : `From a Sentry issue, in ${culprit}.`, label: "Sentry issue" };
+}
+/** Vercel: a failed deployment only, from the configured project and team. */
+function readVercel(body, settings) {
+    const type = text(record(body)["type"]);
+    if (type !== "deployment.error")
+        return { kind: "ignored", why: "not a failed deployment" };
+    const payload = record(record(body)["payload"]);
+    if (settings.project !== null && idWords(record(payload["project"])["id"]) !== settings.project)
+        return { kind: "ignored", why: "from another Vercel project" };
+    if (settings.team !== null && idWords(record(payload["team"])["id"]) !== settings.team)
+        return { kind: "ignored", why: "from another Vercel team" };
+    const deployment = record(payload["deployment"]);
+    const identity = identityOf(deployment["id"]);
+    if (!identity.ok)
+        return { kind: "skip", why: identity.why };
+    const name = text(deployment["name"]);
+    return { kind: "item", identity: identity.id, url: safeLink(record(payload["links"])["deployment"], VERCEL_HOSTS), title: name === null ? settings.title : `${name} failed to deploy`,
+        description: "From a failed Vercel deployment.", label: "Vercel deployment" };
+}
+/** Any JSON: the trigger's own paths, then the usual names; shown whole when they find no text. */
+function readGeneric(body, settings) {
+    const at = (path) => path === null ? undefined : pick(body, path);
+    let identity = null;
+    if (settings.idField !== null) {
+        const read = identityOf(at(settings.idField));
+        // A configured identity that can't be used makes nothing: it never falls back to some other identity.
+        if (!read.ok)
+            return { kind: "skip", why: read.why };
+        identity = read.id;
+    }
+    const title = at(settings.titleField ?? "title") ?? at("summary") ?? at("message");
+    const details = at(settings.bodyField ?? "description") ?? at("body") ?? at("text");
+    return { kind: "item", identity, url: settings.urlField === null ? null : safeLink(at(settings.urlField), null),
+        title: typeof title === "string" && title.trim() !== "" ? title : settings.title,
+        description: `From a webhook:\n\n${typeof details === "string" ? details : JSON.stringify(body, null, 2)}`.slice(0, 4000), label: "Webhook" };
+}
+/** Whether each provider's reader has read a real, captured delivery (test/fixtures/webhooks/*.captured.json), or only
+ * its sender's documented examples so far: the panel says which until a captured one is in the suite. */
+export const READER_CAPTURED = { sentry: false, vercel: false };
+/** What a proven delivery says, by its sender's reader. */
+export function readDelivery(body, settings) {
+    return settings.sender === "sentry" ? readSentry(body, settings) : settings.sender === "vercel" ? readVercel(body, settings) : readGeneric(body, settings);
+}

package/dist/webhook-signing.d.ts

@@ -0,0 +1,27 @@
+import { WEBHOOK_SENDERS } from "./contracts/flow.js";
+export { WEBHOOK_SENDERS };
+export type WebhookSender = (typeof WEBHOOK_SENDERS)[number];
+/** The senders whose deliveries carry a signature (everything but `none`). */
+export type SigningSender = Exclude<WebhookSender, "none">;
+export declare const SENDER_WORDS: Record<WebhookSender, string>;
+/** Node's `headersDistinct`: every header's values, one per line it arrived on. */
+export type DistinctHeaders = Record<string, string[] | undefined>;
+export type Proof = {
+    ok: true;
+    signedId: string | null;
+} | {
+    ok: false;
+    said: string;
+};
+/** A Standard Webhooks timestamp may be this far from now, either way. */
+export declare const STANDARD_TOLERANCE_MS: number;
+/** A `whsec_` secret's key bytes, or null when it isn't one. */
+export declare function standardKey(secret: string): Buffer | null;
+/** Whether a delivery was signed with this secret by this sender. `none` proves nothing and is never passed here. */
+export declare function proveDelivery(sender: SigningSender, secret: string, headers: DistinctHeaders, body: Buffer, now: Date): Proof;
+/** Whether a pasted secret has its sender's shape (Sentry's and Vercel's come from them; the others can be made here). */
+export declare function secretShapeOk(sender: SigningSender, secret: string): boolean;
+/** A new secret for a sender Toolroll can make one for; Sentry's and Vercel's are pasted from them. */
+export declare function makeSecret(sender: "standard" | "github-style"): string;
+/** Whether Toolroll makes this sender's secret (and shows it once), rather than asking for the sender's own. */
+export declare const makesSecret: (sender: SigningSender) => sender is "standard" | "github-style";