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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/agent",
-  "version": "0.2.3-rc.4",
+  "version": "0.2.3-rc.5",
   "description": "Vault-native agents for Claude Code — a #agent/definition note + an inbound message becomes a sandboxed claude turn; the reply is written back as a note. Messaging gateway on :1941.",
   "license": "AGPL-3.0",
   "type": "module",

package/src/auth.ts

@@ -7,13 +7,26 @@
  *   - Layer 1 (bridge / session↔channel): the bridge presents the token as an
  *     `Authorization: Bearer` header on `/events` + `/api/*`.
  *   - Layer 2 (human / chat UI): the page fetches a short-lived token from the
- *     hub (`/admin/agent-token`) and attaches it — as a Bearer header on the
- *     `send` POST, and as a `?token=` query param on the `/ui/events` SSE
- *     (EventSource can't set headers).
+ *     hub (`/admin/agent-token`) and attaches it as a Bearer header on the
+ *     `send` POST. For the browser SSE streams (`/ui/events`,
+ *     `/api/channels/<ch>/turn-events`) — which an `EventSource` can't set a
+ *     header on — the page does NOT put the JWT in the URL. Instead it mints a
+ *     one-time SSE TICKET (`POST /api/ui/sse-ticket`, Bearer-authenticated) and
+ *     opens `…?ticket=<nonce>`. See `requireSseTicket` below + `ui-ticket.ts`.
  *
- * `requireScope` accepts the token from EITHER source so one helper guards both
- * layers. The no-token path short-circuits before any JWKS fetch, keeping it
- * unit-testable without a live hub (same approach Layer 1 used).
+ * `requireScope` accepts the token from a Bearer header (and, for the
+ * agent:admin terminal WebSocket only, a `?token=` query param). The no-token
+ * path short-circuits before any JWKS fetch, keeping it unit-testable without a
+ * live hub (same approach Layer 1 used).
+ *
+ * WHY THE TICKET (agent#25). A full hub JWT in a `?token=` URL lands in any
+ * access/proxy log, browser history, or network trace — a credential leak
+ * mitigated before only by the token's short TTL. The browser SSE endpoints now
+ * trade the JWT for an opaque, single-use, ≤60s ticket (`requireSseTicket`); the
+ * JWT only ever travels in a `fetch` Bearer header. The legacy `?token=` SSE
+ * path was REMOVED (pre-1.0, no deprecation window). The terminal WebSocket
+ * (`agent:admin`) still uses `?token=` — a separate, operator-gated mechanism
+ * out of this change's scope.
  *
  * DUAL-ACCEPT (channel→agent rename transition,
  * `parachute-patterns/migrations/2026-06-17-channel-to-agent.md` rule 1). New
@@ -26,6 +39,7 @@
 
 import { validateHubJwt, HubJwtError } from "./hub-jwt.ts";
 import { extractBearer } from "@openparachute/scope-guard";
+import { consumeTicket } from "./ui-ticket.ts";
 
 /** Agent scopes, declared here so callers share one spelling. */
 export const SCOPE_READ = "agent:read" as const;
@@ -79,15 +93,18 @@ export function json(data: unknown, status = 200): Response {
 
 /**
  * Extract a presented token from a request: the `Authorization: Bearer` header
- * first (the bridge + the UI's POST), falling back to a `?token=` query param
- * (the SSE case — `EventSource` can't set headers). Returns null if neither is
- * present.
+ * first (the bridge, the UI's POST, the SSE-ticket mint), falling back to a
+ * `?token=` query param only when `allowQueryParam` is set. The ONLY caller that
+ * opts into the query param is the agent:admin terminal WebSocket
+ * (`new WebSocket()` can't set headers); the browser SSE streams moved to the
+ * one-time-ticket path (`requireSseTicket`) so a JWT never rides in a URL. Returns
+ * null if neither source is present.
  */
 export function extractToken(req: Request, url: URL, allowQueryParam = false): string | null {
   const bearer = extractBearer(req.headers.get("authorization"));
   if (bearer) return bearer;
-  // `?token=` is opt-in (the SSE case only). The bridge + the UI POST present a
-  // Bearer header, so they never enable it — keeps query-param tokens off every
+  // `?token=` is opt-in (the terminal WebSocket only). Every other caller presents
+  // a Bearer header, so they leave it false — keeping query-param JWTs off every
   // endpoint that doesn't strictly need them (and out of those access logs).
   if (allowQueryParam) {
     const q = url.searchParams.get("token");
@@ -99,9 +116,10 @@ export function extractToken(req: Request, url: URL, allowQueryParam = false): s
 /**
  * Guard an HTTP endpoint on a hub-issued JWT carrying `scope`. The token arrives
  * as an `Authorization: Bearer` header; pass `allowQueryParam: true` to also
- * accept a `?token=` query param (the SSE case only — `EventSource` can't set
- * headers). Bridge + UI-POST callers leave it false, so query-param tokens are
- * confined to the one endpoint that needs them.
+ * accept a `?token=` query param (the agent:admin terminal WebSocket only —
+ * `new WebSocket()` can't set headers). All other callers leave it false, so
+ * query-param JWTs are confined to that one endpoint. Browser SSE streams use
+ * `requireSseTicket` (the one-time ticket), not this.
  *
  * Returns `null` when the request is authorized (caller proceeds), or a
  * `Response` (401/403) the caller must return as-is.
@@ -138,3 +156,74 @@ export async function requireScope(
     );
   }
 }
+
+/**
+ * Mint endpoint for a one-time SSE ticket (agent#25). Authenticate the presented
+ * Bearer JWT for `scope` (the SAME validation `requireScope` runs — no-token →
+ * 401 pre-JWKS, bad/insufficient → 401/403), then issue a single-use, ≤60s
+ * opaque ticket carrying ONLY the token's validated scopes. The ticket — never
+ * the JWT — goes in the SSE URL. Returns the mint `Response` (200 `{ ticket,
+ * expires_at }`, or the gate's 401/403) for the caller to return as-is.
+ *
+ * `mintTicket` is injected (defaults to the real `ui-ticket.ts` store) so unit
+ * tests can assert what scopes get carried without reaching into the singleton.
+ * Critically, an UNAUTHENTICATED mint is impossible: the scope gate runs first
+ * and short-circuits before any ticket is created — minting without a valid
+ * bearer would be an auth bypass.
+ */
+export async function mintSseTicket(
+  req: Request,
+  url: URL,
+  scope: string,
+  mint: (scopes: readonly string[]) => { ticket: string; expiresAt: number },
+): Promise<Response> {
+  const token = extractToken(req, url); // Bearer header ONLY — never a query param.
+  if (!token) {
+    return json({ error: "unauthorized", message: "Bearer token required" }, 401);
+  }
+  let scopes: string[];
+  try {
+    const claims = await validateHubJwt(token);
+    if (!grantsScope(claims.scopes, scope)) {
+      return json(
+        { error: "insufficient_scope", message: `requires ${scope}`, granted: claims.scopes },
+        403,
+      );
+    }
+    // Carry the token's OWN validated scopes — never widen beyond what it holds.
+    scopes = claims.scopes;
+  } catch (err) {
+    return json(
+      { error: "unauthorized", message: err instanceof HubJwtError ? err.message : "invalid token" },
+      401,
+    );
+  }
+  const { ticket, expiresAt } = mint(scopes);
+  return json({ ticket, expires_at: new Date(expiresAt).toISOString() });
+}
+
+/**
+ * Guard a browser SSE endpoint on a one-time `?ticket=<nonce>` (agent#25 — the
+ * EventSource auth path that replaced the leaky `?token=<JWT>`). Look up + CONSUME
+ * the ticket (single-use: a second connect 401s), then assert the ticket's carried
+ * scopes include `scope` (the ticket can never authorize more than the JWT that
+ * minted it — `mintSseTicket` stored exactly that JWT's scopes). Returns `null`
+ * when authorized (caller opens the stream) or a 401 `Response` to return as-is.
+ *
+ * No JWKS fetch on this path — the JWT was validated at MINT time and its scopes
+ * captured in the ticket; consume is a pure in-memory lookup. So an absent /
+ * expired / already-used / under-scoped ticket all map to 401 with no network I/O.
+ */
+export function requireSseTicket(url: URL, scope: string): Response | null {
+  const consumed = consumeTicket(url.searchParams.get("ticket"));
+  if (!consumed) {
+    return json({ error: "unauthorized", message: "valid one-time SSE ticket required" }, 401);
+  }
+  if (!grantsScope(consumed.scopes, scope)) {
+    return json(
+      { error: "insufficient_scope", message: `ticket lacks ${scope}`, granted: consumed.scopes },
+      403,
+    );
+  }
+  return null;
+}

package/src/daemon.ts

@@ -85,6 +85,8 @@ import { ClientRegistry, sseFrame } from "./routing.ts";
 import { DeliveryState } from "./delivery-state.ts";
 import {
   requireScope,
+  mintSseTicket,
+  requireSseTicket,
   extractToken,
   json as authJson,
   SCOPE_READ,
@@ -93,6 +95,7 @@ import {
   SCOPE_ADMIN,
   SCOPE_TERMINAL,
 } from "./auth.ts";
+import { mintTicket } from "./ui-ticket.ts";
 import {
   createTerminalWsHandlers,
   type TerminalWsData,
@@ -1124,8 +1127,13 @@ function redirect(location: string): Response {
 // is `agent:write`.
 //
 // Layer 2 — human / chat UI — gates the http-ui transport's `send` (POST,
-// `agent:send`) + `/ui/events` SSE (`?token=` query, `agent:read`) inside
-// `http-ui.ts`'s ingestHttp using the same `requireScope`.
+// `agent:send`, Bearer) with `requireScope`. The browser SSE streams
+// (`/ui/events`, `/api/channels/<ch>/turn-events`, `agent:read`) gate on a
+// ONE-TIME ticket (`requireSseTicket`) instead of a `?token=<JWT>` query —
+// `EventSource` can't set a header, and a JWT in a URL leaks into access logs
+// (agent#25). The page mints the ticket at `POST /api/ui/sse-ticket` (Bearer,
+// agent:read) and opens `…?ticket=<nonce>`; the ticket is single-use + ≤60s and
+// carries only the minting token's scopes.
 //
 // Discovery + the page itself (/health, /.parachute/config[/schema], /ui) stay
 // OPEN — non-sensitive, and /ui must load to bootstrap its token fetch.
@@ -2745,8 +2753,21 @@ export function createFetchHandler(
       return json({ ok: true, reloaded: result });
     }
 
+    // One-time SSE ticket mint — POST /api/ui/sse-ticket (agent#25). The chat
+    // page can't put its hub JWT in an EventSource URL without leaking it into
+    // access logs, so it trades the JWT (presented HERE as a Bearer header — no
+    // leak) for a single-use, ≤60s opaque ticket it puts in the SSE URL instead.
+    // Bearer-gated on `agent:read` (the scope both browser SSE streams require);
+    // the minted ticket carries ONLY the token's own validated scopes, so it can
+    // never authorize more than the JWT did. An unauthenticated mint is impossible
+    // — `mintSseTicket` runs the scope gate before issuing anything. Returns
+    // `{ ticket, expires_at }`. Externally `<hub>/agent/api/ui/sse-ticket`.
+    if (req.method === "POST" && url.pathname === "/api/ui/sse-ticket") {
+      return mintSseTicket(req, url, SCOPE_READ, mintTicket);
+    }
+
     // Turn-event SSE — GET /api/channels/<ch>/turn-events (chat-facing; gated on
-    // `agent:read`, same scope as the transcript poll + /ui/events). The streaming
+    // a one-time SSE ticket carrying `agent:read`). The streaming
     // view (design 2026-06-16 build item #1): the chat subscribes here to watch a
     // PROGRAMMATIC turn work in real time — interim assistant text + tool_use, then a
     // done/error lifecycle event. EPHEMERAL by design: no backlog/replay (the durable
@@ -2758,11 +2779,12 @@ export function createFetchHandler(
     {
       const turnMatch = url.pathname.match(/^\/api\/channels\/([^/]+)\/turn-events$/);
       if (req.method === "GET" && turnMatch) {
-        // allowQueryParam=true: this SSE is consumed by a browser EventSource, which
-        // cannot set an Authorization header — it authenticates via ?token=. Without
-        // this the live-streaming view 401s in the browser and never connects. (The
-        // stdio-bridge /events SSE uses a Bearer header, so it doesn't need this.)
-        const denied = await requireScope(req, url, SCOPE_READ, true);
+        // Browser EventSource can't set an Authorization header, so this SSE
+        // authenticates via a one-time `?ticket=<nonce>` (agent#25) — minted by
+        // POST /api/ui/sse-ticket (Bearer-gated) and consumed single-use here. The
+        // hub JWT never rides in this URL. (The stdio-bridge /events SSE uses a
+        // Bearer header, so it never needed a query credential at all.)
+        const denied = requireSseTicket(url, SCOPE_READ);
         if (denied) return denied;
         const channelName = decodeURIComponent(turnMatch[1]!);
         const clientId = crypto.randomUUID();

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;
+}