@openparachute/agent 0.2.3-rc.4 → 0.2.3-rc.6

package/src/step-up.ts

@@ -0,0 +1,316 @@
+/**
+ * Step-up auth (PIN) for high-privilege agent-admin actions (agent#80).
+ *
+ * ## The risk this closes
+ *
+ * A single authenticated `agent:admin` session (the operator's hub cookie traded
+ * for an `agent:admin` Bearer) can today do ANYTHING dangerous with no re-confirm:
+ *   - set/rotate credentials (the Claude OAuth token + the generic env store)
+ *     → exfiltrate vault / channel / Claude tokens,
+ *   - open a TERMINAL → a raw host shell,
+ *   - spawn a `filesystem: full` (unsandboxed) agent → read the whole disk.
+ * "One session = total control over the operator's vault + tokens."
+ *
+ * ## The design (mirrors hub's admin-lock PIN, design `2026-06-17-admin-ui-lock.md`)
+ *
+ * A SECOND factor on top of `agent:admin`: an operator-set PIN, exchanged for a
+ * short-lived **step-up token**. The dangerous endpoints require BOTH a valid
+ * `agent:admin` Bearer AND a valid step-up token; everything else stays
+ * frictionless.
+ *
+ *   1. **PIN, set once by the operator** (`setStepUpPin`). Stored HASHED + SALTED
+ *      (`Bun.password.hash`, argon2id — salt is embedded in the PHC string) in
+ *      `~/.parachute/agent/step-up.json`, mode 0600. NEVER plaintext, NEVER logged,
+ *      NEVER returned. Setting/changing it requires the current `agent:admin`
+ *      session and, if a PIN already exists, the current PIN.
+ *   2. **Step-up exchange** (`mintStepUpToken` after `verifyStepUpPin`): an opaque
+ *      256-bit CSPRNG nonce, TTL ~5min, held server-side in a TTL'd map. REUSABLE
+ *      within its window (unlike the single-use SSE ticket) — one PIN entry buys a
+ *      short working window across several gated actions.
+ *   3. **Gate** (`requireStepUp` in `auth.ts`): the dangerous endpoints assert a
+ *      valid step-up token (header `X-Step-Up-Token`, or `?step_up=` for the
+ *      terminal WebSocket which can't set a header) in addition to `agent:admin`.
+ *      A missing/expired token → `403 { error: "step_up_required" }`, distinct from
+ *      a plain 401 (no/invalid Bearer), so the UI knows to PROMPT vs RE-AUTH.
+ *
+ * ## Security properties (all load-bearing)
+ *
+ *   - PIN hashed + salted (argon2id); never logged / returned. The hash never
+ *     leaves this module — the only readers are `verifyStepUpPin` + `setStepUpPin`.
+ *   - Rate-limited with LOCKOUT ({@link stepUpLimiter}): a compromised `agent:admin`
+ *     session can't brute-force the PIN. 5 wrong PINs / 5 min, mirroring hub's
+ *     `unlockLimiter`.
+ *   - Step-up token: opaque (256-bit nonce), short TTL, SERVER-SIDE only. It NEVER
+ *     widens scope — it's a second factor ON TOP of `agent:admin`, never a
+ *     substitute. A request still needs its own valid `agent:admin` Bearer.
+ *   - No secret in any log: neither the PIN nor the hash nor the token is ever
+ *     written to a log line.
+ *
+ * Process-local in-memory token state by design (mirrors `ui-ticket.ts` + the
+ * daemon's other in-process registries). The daemon is single-instance per
+ * machine; tokens live ≤5min and are cheap to lose on restart (the UI re-prompts).
+ */
+
+import { readFileSync, writeFileSync, existsSync, chmodSync, mkdirSync } from "fs";
+import { join } from "path";
+import { defaultStateDir } from "./registry.ts";
+
+// ---------------------------------------------------------------------------
+// PIN storage (argon2id hash in step-up.json, mode 0600)
+// ---------------------------------------------------------------------------
+
+/**
+ * PIN format: 4–12 digits. A numeric PIN is the phone-lock affordance (mirrors
+ * hub's `ADMIN_LOCK_PIN_RE`). The real defense is the rate-limiter + the fact the
+ * session is already `agent:admin`-authenticated — this is a second, convenience-
+ * grade re-confirm gate, not a high-entropy secret.
+ */
+export const STEP_UP_PIN_RE = /^[0-9]{4,12}$/;
+
+/** Whether a candidate string is a well-formed PIN (format check only). */
+export function isValidPinFormat(pin: unknown): pin is string {
+  return typeof pin === "string" && STEP_UP_PIN_RE.test(pin);
+}
+
+/** The on-disk `step-up.json` shape. Namespaced so a future field can coexist. */
+interface StepUpFile {
+  /** argon2id PHC hash of the operator PIN (salt embedded). Never plaintext. */
+  pinHash?: string;
+}
+
+/** Absolute path to the step-up.json store in a state dir. */
+export function stepUpFilePath(stateDir?: string): string {
+  return join(stateDir ?? defaultStateDir(), "step-up.json");
+}
+
+/** Read `step-up.json`. Returns `{}` when absent. */
+function readStepUpFile(stateDir?: string): StepUpFile {
+  const file = stepUpFilePath(stateDir);
+  if (!existsSync(file)) return {};
+  const parsed = JSON.parse(readFileSync(file, "utf8")) as StepUpFile;
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error(`step-up: ${file} must be a JSON object`);
+  }
+  return parsed;
+}
+
+/**
+ * Persist `step-up.json` 0600 — it holds the PIN hash. Creates the state dir if
+ * needed; `chmod`s 0600 unconditionally (writeFileSync's `mode` only applies on
+ * CREATE, so an existing file under a looser umask is tightened on every write) —
+ * the exact discipline `credentials.ts` / `registry.ts` keep for secrets.
+ */
+function writeStepUpFile(file: StepUpFile, stateDir?: string): void {
+  const dir = stateDir ?? defaultStateDir();
+  mkdirSync(dir, { recursive: true });
+  const path = stepUpFilePath(dir);
+  writeFileSync(path, JSON.stringify(file, null, 2) + "\n", { mode: 0o600 });
+  chmodSync(path, 0o600);
+}
+
+/** True iff a step-up PIN is configured (the feature is set up for this install). */
+export function isStepUpConfigured(stateDir?: string): boolean {
+  const h = readStepUpFile(stateDir).pinHash;
+  return typeof h === "string" && h.length > 0;
+}
+
+/** Thrown by {@link setStepUpPin} when the PIN format is rejected. */
+export class StepUpPinFormatError extends Error {
+  constructor() {
+    super("PIN must be 4–12 digits");
+    this.name = "StepUpPinFormatError";
+  }
+}
+
+/**
+ * Set (first-time) or rotate the step-up PIN. Hashes with argon2id
+ * (`Bun.password.hash` — salted, salt embedded in the PHC string). The CALLER
+ * must enforce that:
+ *   - the request is `agent:admin`-authenticated, and
+ *   - if a PIN ALREADY exists, the current PIN was verified first
+ *     ({@link verifyStepUpPin}) — rotating a PIN needs the old one.
+ * This function trusts that gating; it only validates format + writes the hash.
+ *
+ * Returns nothing. Throws {@link StepUpPinFormatError} on a malformed PIN.
+ */
+export async function setStepUpPin(newPin: string, stateDir?: string): Promise<void> {
+  if (!isValidPinFormat(newPin)) throw new StepUpPinFormatError();
+  const hash = await Bun.password.hash(newPin, "argon2id");
+  const file = readStepUpFile(stateDir);
+  file.pinHash = hash;
+  writeStepUpFile(file, stateDir);
+}
+
+/**
+ * Verify a submitted PIN against the stored hash. Returns false when no PIN is
+ * configured (defensive — callers gate on {@link isStepUpConfigured} first) or the
+ * hash is malformed. The CALLER must run the rate-limiter BEFORE this (a wrong PIN
+ * must count toward the lockout). The PIN is never logged.
+ */
+export async function verifyStepUpPin(pin: string, stateDir?: string): Promise<boolean> {
+  if (typeof pin !== "string" || pin.length === 0) return false;
+  const hash = readStepUpFile(stateDir).pinHash;
+  if (typeof hash !== "string" || hash.length === 0) return false;
+  try {
+    return await Bun.password.verify(pin, hash);
+  } catch {
+    // Corrupt / unparseable hash — fail closed.
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Step-up token store — opaque nonce, TTL'd, REUSABLE within its window
+// ---------------------------------------------------------------------------
+
+/**
+ * Default step-up token lifetime — 5 min (the issue's ~5min). Long enough for an
+ * operator to set a credential / open a terminal / spawn after one PIN entry,
+ * short enough that a stolen token (or a walk-away) is bounded.
+ */
+export const STEP_UP_TOKEN_TTL_MS = 5 * 60 * 1000;
+
+/** Nonce entropy: 32 bytes = 256 bits, matching the SSE ticket's floor. */
+const STEP_UP_TOKEN_BYTES = 32;
+
+/** A minted step-up token's server-side record. Never leaves the process. */
+interface StepUpTokenRecord {
+  /** Epoch ms after which the token is expired (treated as absent). */
+  expiresAt: number;
+}
+
+/** The process-local step-up token store. nonce → record. */
+const stepUpTokens = new Map<string, StepUpTokenRecord>();
+
+/** base64url-encode bytes (no padding) — URL-safe, no `+`/`/`/`=`. */
+function base64url(bytes: Uint8Array): string {
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function pruneExpiredStepUpTokens(now = Date.now()): void {
+  for (const [k, rec] of stepUpTokens) {
+    if (now >= rec.expiresAt) stepUpTokens.delete(k);
+  }
+}
+
+/**
+ * Mint a step-up token valid for `ttlMs` (default {@link STEP_UP_TOKEN_TTL_MS}).
+ * The CALLER must have already verified the PIN — this never authenticates. The
+ * token is opaque (no scope/claims rides in it); it is purely a "the PIN was
+ * entered recently" capability checked alongside the `agent:admin` Bearer.
+ * Returns the nonce + its absolute expiry.
+ */
+export function mintStepUpToken(ttlMs = STEP_UP_TOKEN_TTL_MS): {
+  token: string;
+  expiresAt: number;
+} {
+  pruneExpiredStepUpTokens();
+  const bytes = new Uint8Array(STEP_UP_TOKEN_BYTES);
+  crypto.getRandomValues(bytes);
+  const token = base64url(bytes);
+  const expiresAt = Date.now() + ttlMs;
+  stepUpTokens.set(token, { expiresAt });
+  return { token, expiresAt };
+}
+
+/**
+ * Whether a step-up token is currently valid. REUSABLE within its window (does NOT
+ * delete on read — unlike the single-use SSE ticket), so one PIN entry buys a short
+ * window across several gated actions. An absent / expired token returns false (and
+ * an expired one is lazily pruned). Pure in-memory lookup — no I/O, no secret log.
+ */
+export function isStepUpTokenValid(token: string | null | undefined, now = Date.now()): boolean {
+  if (!token) return false;
+  const rec = stepUpTokens.get(token);
+  if (!rec) return false;
+  if (now >= rec.expiresAt) {
+    stepUpTokens.delete(token);
+    return false;
+  }
+  return true;
+}
+
+/** Explicitly revoke a step-up token ("lock now"). Idempotent. */
+export function revokeStepUpToken(token: string | null | undefined): void {
+  if (token) stepUpTokens.delete(token);
+}
+
+/** Test seam: clear the in-memory token store. */
+export function _resetStepUpTokensForTest(): void {
+  stepUpTokens.clear();
+}
+
+/** Test seam: the live step-up token count. */
+export function _stepUpTokenCountForTest(): number {
+  return stepUpTokens.size;
+}
+
+// ---------------------------------------------------------------------------
+// PIN brute-force limiter (lockout) — mirrors hub's admin-lock unlockLimiter
+// ---------------------------------------------------------------------------
+
+/**
+ * 5 wrong PINs / 5-min sliding window before lockout. The step-up exchange is
+ * already `agent:admin`-gated, so the threat is a COMPROMISED session (stolen
+ * cookie → minted Bearer) grinding argon2id PIN verifications without bound. Keyed
+ * per-session (the validated token's subject) so an attacker can't get a fresh
+ * bucket by rotating something cheap. Same floor + posture as hub's `unlockLimiter`.
+ */
+export const STEP_UP_MAX_ATTEMPTS = 5;
+export const STEP_UP_WINDOW_MS = 5 * 60 * 1000;
+
+export interface RateLimitResult {
+  /** True if the attempt is admitted; the caller proceeds to the PIN check. */
+  allowed: boolean;
+  /** Seconds until the bucket frees up (only set when denied). Always >= 1. */
+  retryAfterSeconds?: number;
+}
+
+/**
+ * A small sliding-window rate limiter (the shape mirrors hub's `RateLimiter`,
+ * inlined here to keep the agent module dependency-free). Each key keeps the last
+ * N admitted attempt timestamps; on a new attempt we prune anything older than the
+ * window, count what remains, and allow/deny. `now` is injectable for tests.
+ */
+export class StepUpRateLimiter {
+  private readonly buckets = new Map<string, number[]>();
+
+  constructor(
+    private readonly maxAttempts: number,
+    private readonly windowMs: number,
+  ) {}
+
+  /**
+   * Record an attempt and return whether it's admitted. A DENIED attempt is NOT
+   * recorded (so a flood of denials can't push the reset further out). `now` is
+   * epoch ms (injectable).
+   */
+  checkAndRecord(key: string, now = Date.now()): RateLimitResult {
+    const cutoff = now - this.windowMs;
+    const pruned = (this.buckets.get(key) ?? []).filter((t) => t > cutoff);
+    if (pruned.length >= this.maxAttempts) {
+      const resetAtMs = (pruned[0] ?? now) + this.windowMs;
+      const retryAfterSeconds = Math.max(1, Math.ceil((resetAtMs - now) / 1000));
+      this.buckets.set(key, pruned);
+      return { allowed: false, retryAfterSeconds };
+    }
+    pruned.push(now);
+    this.buckets.set(key, pruned);
+    return { allowed: true };
+  }
+
+  /** Clear a key's bucket (called on a SUCCESSFUL PIN entry so it resets). */
+  clear(key: string): void {
+    this.buckets.delete(key);
+  }
+
+  /** Test seam: wipe all buckets. */
+  reset(): void {
+    this.buckets.clear();
+  }
+}
+
+/** The singleton PIN-attempt limiter (all step-up exchanges share one bucket map). */
+export const stepUpLimiter = new StepUpRateLimiter(STEP_UP_MAX_ATTEMPTS, STEP_UP_WINDOW_MS);

package/src/terminal-ui.ts

@@ -164,6 +164,65 @@ ${SHELL_JS}
     });
   }
 
+  // --- step-up PIN (agent#80) --------------------------------------------
+  // A terminal is a raw host shell — the most dangerous capability — so the WS
+  // upgrade requires a STEP-UP TOKEN on top of the agent:admin Bearer. The WS
+  // can't set a header, so we present it as a step_up query param. We fetch the step-up
+  // status, prompt for the PIN (or set one first), exchange it for a short-TTL
+  // token, and cache it on window.__stepUp. Re-prompt on expiry / WS auth-fail.
+  // This page is server-rendered (no React) so the prompt is a native dialog.
+  function authedJson(suffix, init) {
+    init = init || {};
+    var headers = init.headers || {};
+    headers["accept"] = "application/json";
+    if (window.__token) headers["authorization"] = "Bearer " + window.__token;
+    init.headers = headers;
+    return fetch(MOUNT + "/api" + suffix, init);
+  }
+  function ensureStepUp() {
+    if (window.__stepUp && window.__stepUpExp && Date.now() < window.__stepUpExp - 5000) {
+      return Promise.resolve(window.__stepUp);
+    }
+    return authedJson("/step-up").then(function (r) {
+      return r.json();
+    }).then(function (s) {
+      if (!s.configured) {
+        var np = window.prompt("Set a step-up PIN (4-12 digits) — required to open a terminal:");
+        if (!np) return null;
+        var confirm = window.prompt("Confirm the PIN:");
+        if (confirm !== np) { showNotice("The PINs didn't match — try again.", true); return null; }
+        return authedJson("/step-up/pin", {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ newPin: np }),
+        }).then(function (r) {
+          if (!r.ok) { showNotice("Could not set the PIN (must be 4-12 digits).", true); return null; }
+          return exchangePin(np);
+        });
+      }
+      var pin = window.prompt("Enter your step-up PIN to open a terminal:");
+      if (!pin) return null;
+      return exchangePin(pin);
+    });
+  }
+  function exchangePin(pin) {
+    return authedJson("/step-up", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ pin: pin }),
+    }).then(function (r) {
+      if (r.status === 401) { showNotice("Incorrect PIN.", true); return null; }
+      if (r.status === 429) { showNotice("Too many PIN attempts — wait a minute.", true); return null; }
+      if (!r.ok) { showNotice("Step-up failed (" + r.status + ").", true); return null; }
+      return r.json();
+    }).then(function (body) {
+      if (!body || !body.stepUpToken) return null;
+      window.__stepUp = body.stepUpToken;
+      window.__stepUpExp = body.expires_at ? new Date(body.expires_at).getTime() : Date.now() + 5 * 60000;
+      return window.__stepUp;
+    });
+  }
+
   // --- WebSocket relay ----------------------------------------------------
   // The path segment is the AGENT name — the daemon attaches to that agent's tmux
   // session (<name>-agent). NOT a channel.
@@ -172,6 +231,7 @@ ${SHELL_JS}
     var dims = "cols=" + term.cols + "&rows=" + term.rows;
     var u = proto + "//" + location.host + MOUNT + "/terminal/" + encodeURIComponent(agent) + "?" + dims;
     if (window.__token) u += "&token=" + encodeURIComponent(window.__token);
+    if (window.__stepUp) u += "&step_up=" + encodeURIComponent(window.__stepUp);
     return u;
   }
 
@@ -181,6 +241,19 @@ ${SHELL_JS}
     if (ws) { manualClose = true; try { ws.close(); } catch (_e) {} ws = null; }
     manualClose = false;
     clearNotice();
+    // Step-up FIRST — a terminal needs the PIN-minted token (agent#80). Only open
+    // the socket once we hold one; a cancelled prompt leaves the page idle.
+    setStatus("step-up…");
+    ensureStepUp().then(function (tok) {
+      if (!tok) { setStatus("step-up required", "err"); return; }
+      openSocket(agent);
+    }).catch(function () {
+      setStatus("step-up failed", "err");
+      showNotice("Could not complete step-up. Reload and try again.", true);
+    });
+  }
+
+  function openSocket(agent) {
     setStatus("connecting…");
     doFit();
     var socket = new WebSocket(wsUrl(agent));

package/src/transports/http-ui.ts

@@ -16,8 +16,9 @@
  *    to them (mirroring the daemon's `/events` SSE pattern for bridges).
  *
  * It owns two HTTP surfaces via `ingestHttp` (scoped to ITS OWN channel name):
- *   1. POST /api/channels/<name>/send   — body {text} → ctx.emit(...) → {ok:true}
- *   2. GET  /ui/events?channel=<name>    — SSE stream the browser subscribes to
+ *   1. POST /api/channels/<name>/send         — body {text} → ctx.emit(...) → {ok:true}
+ *   2. GET  /ui/events?channel=<name>&ticket=  — SSE stream the browser subscribes to
+ *      (one-time ticket auth — agent#25; the JWT never rides in this URL)
  * The static `/ui` chat page itself is global and served by the daemon, since
  * it's a channel picker across all http-ui channels.
  */
@@ -30,7 +31,7 @@ import type {
   PermissionArgs,
 } from "../transport.ts";
 import { sseFrame } from "../routing.ts";
-import { requireScope, json, SCOPE_SEND, SCOPE_READ } from "../auth.ts";
+import { requireScope, requireSseTicket, json, SCOPE_SEND, SCOPE_READ } from "../auth.ts";
 
 /** A connected browser SSE client (one per open chat page on this channel). */
 interface UiClient {
@@ -168,11 +169,12 @@ export class HttpUiTransport implements Transport {
       url.pathname === "/ui/events" &&
       url.searchParams.get("channel") === channel
     ) {
-      // Layer 2: gate on `agent:read`. EventSource can't set headers, so the
-      // token rides in as a `?token=` query param — the ONLY endpoint that opts
-      // into the query-param fallback (allowQueryParam: true). No-token → 401
-      // before the stream opens.
-      const denied = await requireScope(req, url, SCOPE_READ, true);
+      // Layer 2: EventSource can't set headers, so this gates on a one-time
+      // `?ticket=<nonce>` (agent#25) — minted by POST /api/ui/sse-ticket
+      // (Bearer-gated) and consumed single-use here, carrying `agent:read`. The
+      // hub JWT never appears in this URL (the leak the ticket closes). Absent /
+      // expired / already-used ticket → 401 before the stream opens.
+      const denied = requireSseTicket(url, SCOPE_READ);
       if (denied) return denied;
       const clientId = crypto.randomUUID();
       const clients = this.uiClients;

package/src/ui-kit.ts

@@ -376,9 +376,12 @@ export const SHELL_JS = `
     el.className = "app-status" + (kind ? " " + kind : "");
   }
   // Hub-minted agent token (cookie-gated to the logged-in operator). Cached on
-  // window.__token; pages attach it as a Bearer header and/or ?token= param.
-  // (Endpoint renamed /admin/channel-token → /admin/agent-token in the
-  // channel→agent rename; the hub 301-redirects the old path for old bookmarks.)
+  // window.__token; pages attach it as a Bearer header. (Browser SSE auth moved
+  // off the query-param token to a one-time ticket in agent#25, so the JWT never
+  // lands in a URL; this template is the retired server-rendered shell, superseded
+  // by the SPA.) Endpoint renamed /admin/channel-token to /admin/agent-token in
+  // the channel-to-agent rename; the hub 301-redirects the old path for old
+  // bookmarks.
   function fetchToken() {
     return fetch(window.location.origin + "/admin/agent-token", { credentials: "include" })
       .then(function (r) { if (!r.ok) throw new Error("token " + r.status); return r.json(); })

package/src/ui-ticket.ts

@@ -0,0 +1,121 @@
+/**
+ * One-time SSE tickets for the browser EventSource auth path (Layer 2, human↔UI).
+ *
+ * THE LEAK THIS CLOSES. A browser `EventSource` can't set an `Authorization`
+ * header, so the agent SPA used to put the hub JWT directly in the SSE URL
+ * (`/ui/events?token=<JWT>`, `/api/channels/<ch>/turn-events?token=<JWT>`). A
+ * full bearer JWT in a URL lands in any access log, proxy log, browser history,
+ * or network trace — mitigated before only by the token's ~10min TTL. That's a
+ * credential-in-a-URL leak.
+ *
+ * THE FIX. Trade the JWT for an opaque, single-use, very-short-lived TICKET that
+ * goes in the URL instead. The SPA presents its bearer JWT to a normal
+ * authenticated endpoint (a Bearer header on a `fetch`, no leak), which mints a
+ * ticket: a crypto-random 256-bit nonce (base64url) stored ONLY server-side in
+ * this TTL'd map, carrying the validated scope(s)/audience of the presenting
+ * token. The SPA opens `/ui/events?ticket=<nonce>`; the SSE consume path looks
+ * the nonce up, CONSUMES it (deletes immediately — single-use), and establishes
+ * the stream with the ticket's scopes. The JWT never appears in a URL or log.
+ *
+ * SECURITY PROPERTIES (all load-bearing):
+ *  - Unguessable: 32 random bytes (256 bits) from `crypto.getRandomValues`,
+ *    base64url-encoded. Far above the issue's 128-bit floor.
+ *  - Single-use: `consume` DELETES the entry before returning, so a replayed
+ *    ticket (a second connect, or a stolen URL) finds nothing → 401.
+ *  - Short TTL: default 60s — just long enough to open the connection. An
+ *    expired entry is treated as absent (and lazily pruned).
+ *  - No scope widening: the ticket stores EXACTLY the scopes the minting token
+ *    presented (validated upstream by `requireScope` before `mint` is called).
+ *    The consume path asserts the required scope against the stored set, so a
+ *    ticket can never authorize more than the JWT that minted it.
+ *
+ * This is process-local in-memory state by design (mirrors the daemon's other
+ * in-process registries). The daemon is single-instance per machine; tickets
+ * live ≤60s and are cheap to lose on restart (the SPA just re-mints). A
+ * module-level singleton is used because the two consume paths live in different
+ * modules (`http-ui.ts`'s `ingestHttp` and the daemon's turn-events route) and
+ * both must hit the SAME store — `ingestHttp(req, url)` has no place to thread an
+ * instance through. `_resetTicketsForTest` isolates unit tests.
+ */
+
+/** A minted ticket's server-side record. Never leaves the process. */
+interface TicketRecord {
+  /** The validated scopes carried from the minting JWT (the ceiling — never widened). */
+  scopes: string[];
+  /** Epoch ms after which the ticket is expired (treated as absent). */
+  expiresAt: number;
+}
+
+/** Default ticket lifetime — long enough to open an EventSource, no longer. */
+export const TICKET_TTL_MS = 60_000;
+
+/** Nonce entropy: 32 bytes = 256 bits, well above the 128-bit floor. */
+const TICKET_BYTES = 32;
+
+/** The process-local ticket store. nonce → record. */
+const tickets = new Map<string, TicketRecord>();
+
+/** base64url-encode bytes (no padding) — URL-safe, no `+`/`/`/`=`. */
+function base64url(bytes: Uint8Array): string {
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/**
+ * Mint a single-use ticket carrying `scopes` (a COPY of the validated scopes from
+ * the presenting JWT — the caller must have already authenticated + scope-checked
+ * the token, so this never widens authority). Returns the opaque nonce + its
+ * absolute expiry. TTL defaults to {@link TICKET_TTL_MS}.
+ */
+export function mintTicket(scopes: readonly string[], ttlMs = TICKET_TTL_MS): {
+  ticket: string;
+  expiresAt: number;
+} {
+  pruneExpiredTickets();
+  const bytes = new Uint8Array(TICKET_BYTES);
+  crypto.getRandomValues(bytes);
+  const ticket = base64url(bytes);
+  const expiresAt = Date.now() + ttlMs;
+  tickets.set(ticket, { scopes: [...scopes], expiresAt });
+  return { ticket, expiresAt };
+}
+
+/**
+ * Consume a ticket: look it up, and if present + unexpired, DELETE it (single-use)
+ * and return its scopes. Returns `null` for an absent / expired / already-consumed
+ * ticket — the caller maps that to a 401. Deletion happens before return, so two
+ * concurrent consumes of the same nonce can't both succeed.
+ */
+export function consumeTicket(ticket: string | null | undefined): { scopes: string[] } | null {
+  if (!ticket) return null;
+  const rec = tickets.get(ticket);
+  if (!rec) return null;
+  // Single-use: remove FIRST, so even an expired hit can't be retried and a
+  // concurrent second consume finds nothing.
+  tickets.delete(ticket);
+  if (Date.now() >= rec.expiresAt) return null;
+  return { scopes: rec.scopes };
+}
+
+/**
+ * Drop every expired ticket. Called opportunistically on each mint so the map
+ * can't grow unbounded if some tickets are never consumed; not on a timer (no
+ * background work in a possibly-idle daemon). O(n) over a map that's tiny in
+ * practice (≤ a handful of live tickets at 60s TTL).
+ */
+export function pruneExpiredTickets(now = Date.now()): void {
+  for (const [k, rec] of tickets) {
+    if (now >= rec.expiresAt) tickets.delete(k);
+  }
+}
+
+/** Test seam: clear all tickets so unit tests start from a clean store. */
+export function _resetTicketsForTest(): void {
+  tickets.clear();
+}
+
+/** Test seam: the current live ticket count (asserts single-use deletion). */
+export function _ticketCountForTest(): number {
+  return tickets.size;
+}