@openparachute/agent 0.2.0 → 0.2.3-rc.10

package/src/daemon.ts

@@ -66,6 +66,7 @@ import {
   DEFAULT_HUB_ORIGIN,
 } from "./def-vaults.ts";
 import { mintScopedToken, vaultScope } from "./mint-token.ts";
+import { registerAllDefVaultTriggers } from "./def-vault-triggers.ts";
 import { GrantsClient } from "./grants.ts";
 import { resolveEffectiveEnv } from "./effective-env.ts";
 import { VaultJobStore, validateJob, vaultTransportFor, type Job } from "./jobs.ts";
@@ -85,6 +86,10 @@ import { ClientRegistry, sseFrame } from "./routing.ts";
 import { DeliveryState } from "./delivery-state.ts";
 import {
   requireScope,
+  mintSseTicket,
+  requireSseTicket,
+  requireStepUp,
+  grantsScope,
   extractToken,
   json as authJson,
   SCOPE_READ,
@@ -93,6 +98,16 @@ import {
   SCOPE_ADMIN,
   SCOPE_TERMINAL,
 } from "./auth.ts";
+import {
+  isStepUpConfigured,
+  isValidPinFormat,
+  setStepUpPin,
+  verifyStepUpPin,
+  mintStepUpToken,
+  stepUpLimiter,
+  StepUpPinFormatError,
+} from "./step-up.ts";
+import { mintTicket } from "./ui-ticket.ts";
 import {
   createTerminalWsHandlers,
   type TerminalWsData,
@@ -100,6 +115,7 @@ import {
 import { TERMINAL_UI_HTML } from "./terminal-ui.ts";
 import { serveTerminalAsset } from "./terminal-assets.ts";
 import { isSpaPath, serveSpa, spaDistDir } from "./spa-serve.ts";
+import { runBootPreflight, type PreflightResult } from "./preflight.ts";
 import {
   buildSpecFromBody,
   setupProgrammaticSpawn,
@@ -719,7 +735,7 @@ export function buildWriteThread(channels: Map<string, Channel>): WriteThread {
     }
     // Only a transport with a durable store implements writeThread (the VaultTransport).
     if (!ch.transport.writeThread) return;
-    await ch.transport.writeThread({
+    const written = await ch.transport.writeThread({
       channel: thread.channel,
       ...(thread.name ? { name: thread.name } : {}),
       ...(thread.definition ? { definition: thread.definition } : {}),
@@ -743,6 +759,13 @@ export function buildWriteThread(channels: Map<string, Channel>): WriteThread {
       ...(thread.sameTurn ? { sameTurn: true } : {}),
       ...(thread.phase ? { phase: thread.phase } : {}),
     });
+    // Surface the WRITTEN note id so the drain can set a RESOLVABLE callback `source_thread`
+    // (agent#124). `writeThread` returns `{ sent: [id] }` — the id is the actual note an
+    // orchestrator can pull with `query-notes { id }` for BOTH modes (single-threaded: the
+    // deterministic `Threads/<safeChannel>/<safeName>` note; multi-threaded: the per-fire
+    // `Threads/<safeChannel>/<uuid>` note). Empty/absent → undefined (the drain falls back).
+    const id = written?.sent?.[0];
+    return id ? { id } : undefined;
   };
 }
 
@@ -1124,8 +1147,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.
@@ -1182,6 +1210,12 @@ export async function authorizeTerminalUpgrade(
   const denied = await requireScope(req, url, SCOPE_TERMINAL, true);
   if (denied) return { ok: false, response: denied };
 
+  // STEP-UP required (agent#80): a terminal is a raw host shell — the single most
+  // dangerous capability. allowQueryParam: true so the WS presents the step-up
+  // token as `?step_up=` (it can't set the `X-Step-Up-Token` header).
+  const step = requireStepUp(req, url, true);
+  if (!step.ok) return { ok: false, response: step.response };
+
   // tmux session name convention: `<name>-agent`. Attach a viewer pty to THIS
   // session; the session itself is created by the spawn path.
   const session = `${agentName}-agent`;
@@ -1286,6 +1320,13 @@ export function createFetchHandler(
       url: string;
       tokenPresent: boolean;
     }>;
+    /**
+     * The boot dependency-PREFLIGHT result (agent#156) — surfaced on `/health` so the
+     * admin UI can show that programmatic turns will fail until the missing deps
+     * (`bwrap`/`rg`/`socat`/`claude`) are installed. `main` passes the boot check;
+     * absent (a plain createFetchHandler / tests) → omitted from `/health`.
+     */
+    preflight?: PreflightResult;
   },
 ): (req: Request, server?: { upgrade: (req: Request, opts: { data: TerminalWsData }) => boolean }) => Promise<Response> {
   // The per-channel turn-event SSE registry — subscribers of the live "watch it
@@ -1478,6 +1519,10 @@ export function createFetchHandler(
     // (`programmatic · idle|working|queued:N`) instead of `mcp_sessions` — a
     // programmatic agent has no live subscriber, so SSE/MCP counts don't describe it.
     if (url.pathname === "/health") {
+      // Surface the boot dependency-preflight (agent#156) so the admin UI can show
+      // that programmatic turns will fail until the missing deps are installed. Only
+      // present when `main` passed the boot check (absent in a plain handler/tests).
+      const preflight = opts?.preflight;
       return json({
         status: "ok",
         channels: [...channels.values()].map((c) => ({
@@ -1496,6 +1541,15 @@ export function createFetchHandler(
             status: s.state === "queued" ? `queued:${s.queued}` : s.state,
           };
         }),
+        ...(preflight
+          ? {
+              dependencies: {
+                ok: preflight.ok,
+                // The binary names missing on PATH — what programmatic turns need installed.
+                missing: preflight.missing.map((d) => d.bin),
+              },
+            }
+          : {}),
       });
     }
 
@@ -1783,6 +1837,169 @@ export function createFetchHandler(
       }
     }
 
+    // ---------------------------------------------------------------------
+    // STEP-UP AUTH (PIN) — second factor for high-privilege actions (agent#80).
+    //
+    // The dangerous `agent:admin` actions (set credentials, open a terminal,
+    // spawn a `filesystem: full` agent) require a step-up token IN ADDITION to
+    // the `agent:admin` Bearer. This block is the PIN setup + exchange surface;
+    // the gating lives at each dangerous endpoint (via `requireStepUp`).
+    //
+    //   GET  /api/step-up          → { configured } — is a PIN set? (UI: setup vs prompt)
+    //   POST /api/step-up { pin }  → validate PIN (rate-limited) → { stepUpToken, expires_at }
+    //   POST /api/step-up/pin { newPin, currentPin? } → set/rotate the PIN
+    //
+    // All `agent:admin`-gated (the operator's cookie-minted Bearer). The PIN is
+    // hashed+salted server-side (step-up.ts); it is NEVER returned or logged.
+    // Externally hub strips `/agent`, so these are `<hub>/agent/api/step-up`.
+    // ---------------------------------------------------------------------
+    if (url.pathname === "/api/step-up" && req.method === "GET") {
+      const denied = await requireScope(req, url, SCOPE_ADMIN);
+      if (denied) return denied;
+      // Whether a PIN is configured — the UI branches setup-flow vs PIN-prompt.
+      return json({ configured: isStepUpConfigured() });
+    }
+
+    if (url.pathname === "/api/step-up" && req.method === "POST") {
+      // Exchange: validate the PIN, then mint a short-lived step-up token. The
+      // session must already hold `agent:admin` (this is a SECOND factor on top,
+      // never a substitute — the token carries no scope of its own).
+      let claims;
+      try {
+        const token = extractToken(req, url);
+        if (!token) return json({ error: "unauthorized", message: "Bearer token required" }, 401);
+        claims = await validateHubJwt(token);
+      } catch (err) {
+        return json(
+          { error: "unauthorized", message: err instanceof Error ? err.message : "invalid token" },
+          401,
+        );
+      }
+      if (!grantsScope(claims.scopes, SCOPE_ADMIN)) {
+        return json(
+          { error: "insufficient_scope", message: `requires ${SCOPE_ADMIN}`, granted: claims.scopes },
+          403,
+        );
+      }
+      // No PIN configured yet — there's nothing to exchange. Tell the UI to run
+      // its first-time setup (distinct from a wrong-PIN 401).
+      if (!isStepUpConfigured()) {
+        return json(
+          { error: "step_up_not_configured", message: "set a step-up PIN first (POST /api/step-up/pin)" },
+          409,
+        );
+      }
+      let body: { pin?: unknown };
+      try {
+        body = (await req.json()) as typeof body;
+      } catch {
+        return json({ error: "invalid JSON body" }, 400);
+      }
+      if (typeof body.pin !== "string" || body.pin.length === 0) {
+        return json({ error: "body.pin (non-empty string) is required" }, 400);
+      }
+      // Rate-limit BEFORE the (expensive, brute-forceable) argon2 verify, keyed by
+      // the operator subject — a stolen-cookie attacker can't grind the PIN. A
+      // DENIED attempt returns 429 (the limiter does not count it again).
+      const limited = stepUpLimiter.checkAndRecord(`step-up:${claims.sub}`);
+      if (!limited.allowed) {
+        return new Response(
+          JSON.stringify({
+            error: "rate_limited",
+            message: "too many PIN attempts — wait before retrying",
+            retry_after_seconds: limited.retryAfterSeconds,
+          }),
+          {
+            status: 429,
+            headers: {
+              "content-type": "application/json",
+              "retry-after": String(limited.retryAfterSeconds ?? 60),
+            },
+          },
+        );
+      }
+      const ok = await verifyStepUpPin(body.pin);
+      if (!ok) {
+        // Wrong PIN — 401. The attempt already counted toward the lockout above.
+        // Never echo the PIN back.
+        return json({ error: "invalid_pin", message: "incorrect PIN" }, 401);
+      }
+      // Correct PIN — clear the attempt bucket (a fresh window for the next time)
+      // and mint a reusable, short-TTL step-up token.
+      stepUpLimiter.clear(`step-up:${claims.sub}`);
+      const { token: stepUpToken, expiresAt } = mintStepUpToken();
+      return json({ stepUpToken, expires_at: new Date(expiresAt).toISOString() });
+    }
+
+    if (url.pathname === "/api/step-up/pin" && req.method === "POST") {
+      // Set (first time) or rotate the step-up PIN. agent:admin-gated; if a PIN
+      // already exists, the CURRENT PIN must be supplied + verified (rotation
+      // needs the old PIN, so a hijacked session can't silently replace it).
+      let claims;
+      try {
+        const token = extractToken(req, url);
+        if (!token) return json({ error: "unauthorized", message: "Bearer token required" }, 401);
+        claims = await validateHubJwt(token);
+      } catch (err) {
+        return json(
+          { error: "unauthorized", message: err instanceof Error ? err.message : "invalid token" },
+          401,
+        );
+      }
+      if (!grantsScope(claims.scopes, SCOPE_ADMIN)) {
+        return json(
+          { error: "insufficient_scope", message: `requires ${SCOPE_ADMIN}`, granted: claims.scopes },
+          403,
+        );
+      }
+      let body: { newPin?: unknown; currentPin?: unknown };
+      try {
+        body = (await req.json()) as typeof body;
+      } catch {
+        return json({ error: "invalid JSON body" }, 400);
+      }
+      if (!isValidPinFormat(body.newPin)) {
+        return json({ error: "body.newPin must be 4–12 digits" }, 400);
+      }
+      // Rotation: a PIN already exists → require + verify the current one (rate-limited).
+      // SHARES the exchange bucket (same `step-up:<sub>` key) on purpose: both verify
+      // the PIN, so an attacker can't get a fresh grind window by alternating endpoints.
+      if (isStepUpConfigured()) {
+        const limited = stepUpLimiter.checkAndRecord(`step-up:${claims.sub}`);
+        if (!limited.allowed) {
+          return new Response(
+            JSON.stringify({
+              error: "rate_limited",
+              message: "too many PIN attempts — wait before retrying",
+              retry_after_seconds: limited.retryAfterSeconds,
+            }),
+            {
+              status: 429,
+              headers: {
+                "content-type": "application/json",
+                "retry-after": String(limited.retryAfterSeconds ?? 60),
+              },
+            },
+          );
+        }
+        if (typeof body.currentPin !== "string" || !(await verifyStepUpPin(body.currentPin))) {
+          return json(
+            { error: "invalid_pin", message: "the current PIN is required to change it" },
+            401,
+          );
+        }
+        stepUpLimiter.clear(`step-up:${claims.sub}`);
+      }
+      try {
+        await setStepUpPin(body.newPin);
+      } catch (err) {
+        if (err instanceof StepUpPinFormatError) return json({ error: err.message }, 400);
+        return json({ error: `failed to set PIN: ${(err as Error).message}` }, 500);
+      }
+      // Echo back only the fact of the write — never the PIN.
+      return json({ ok: true, configured: true });
+    }
+
     // ---------------------------------------------------------------------
     // Claude OAuth credential store (design §6) — the per-channel secret a
     // launched agent session runs on (`CLAUDE_CODE_OAUTH_TOKEN`). Same
@@ -1802,11 +2019,15 @@ export function createFetchHandler(
 
       if (req.method === "GET") {
         // Inspect WITHOUT leaking the secret: whether a default is set + which
-        // channels carry an override (names only).
+        // channels carry an override (names only). A status read — no step-up.
         return json(describeClaudeCredentials(defaultStateDir()));
       }
 
-      // POST — set the default / operator-level token.
+      // POST — set the default / operator-level token. STEP-UP required (agent#80):
+      // setting a credential can exfiltrate the operator's Claude token.
+      const step = requireStepUp(req, url);
+      if (!step.ok) return step.response;
+
       let credBody: { token?: unknown };
       try {
         credBody = (await req.json()) as typeof credBody;
@@ -1829,6 +2050,10 @@ export function createFetchHandler(
     if (credMatch && (req.method === "POST" || req.method === "DELETE")) {
       const denied = await requireScope(req, url, SCOPE_ADMIN);
       if (denied) return denied;
+      // STEP-UP required (agent#80): both set + remove of a per-channel Claude
+      // credential are high-privilege credential-store mutations.
+      const step = requireStepUp(req, url);
+      if (!step.ok) return step.response;
       const channel = decodeURIComponent(credMatch[1]!);
 
       if (req.method === "DELETE") {
@@ -1883,9 +2108,15 @@ export function createFetchHandler(
 
       if (req.method === "GET") {
         // Inspect WITHOUT leaking values: names per channel + the default layer.
+        // A status read — no step-up.
         return json(describeChannelEnv(defaultStateDir()));
       }
 
+      // STEP-UP required (agent#80): set/remove of an env secret (GH_TOKEN,
+      // CLOUDFLARE_API_TOKEN, …) is a credential-store mutation.
+      const step = requireStepUp(req, url);
+      if (!step.ok) return step.response;
+
       let envBody: { channel?: unknown; name?: unknown; value?: unknown };
       try {
         envBody = (await req.json()) as typeof envBody;
@@ -1979,6 +2210,15 @@ export function createFetchHandler(
         throw err;
       }
 
+      // STEP-UP required (agent#80) ONLY for the dangerous filesystem case: a
+      // `filesystem: "full"` agent runs UNSANDBOXED with read access to the whole
+      // disk. Ordinary sandboxed (workspace-confined) spawns stay frictionless —
+      // gate just the high-blast-radius case.
+      if (spec.filesystem === "full") {
+        const step = requireStepUp(req, url);
+        if (!step.ok) return step.response;
+      }
+
       // CHANNEL EXCLUSION: a channel routes inbound to at most one agent. Refuse a
       // spawn for a DIFFERENT programmatic agent onto an already-occupied wake channel
       // (re-spawning the SAME name onto its OWN channel is the idempotent-replace path).
@@ -2120,6 +2360,14 @@ export function createFetchHandler(
     // ---------------------------------------------------------------------
     if (url.pathname === "/api/agent-defs" && (req.method === "GET" || req.method === "POST")) {
       // GET is READ-scoped (a listing, no secrets); POST is admin (it mints/writes).
+      //
+      // NOTE (step-up, agent#80/#154): POST is intentionally NOT step-up-gated, even
+      // though a `#agent/definition` note can carry `filesystem: "full"`. Authoring a
+      // def already requires the scope-gated `vault:write` (the daemon writes the note
+      // with a vault token), so a step-up challenge here would gate a capability the
+      // caller already had to hold a write credential to reach — mirrors the carve-out
+      // comment on the vault-native parse path in agent-defs.ts. The `filesystem:full`
+      // SPAWN path (`POST /api/agents`) IS step-up-gated; this AUTHORING path is not.
       const scope = req.method === "GET" ? SCOPE_READ : SCOPE_ADMIN;
       const denied = await requireScope(req, url, scope);
       if (denied) return denied;
@@ -2273,6 +2521,12 @@ export function createFetchHandler(
       // GET is READ-scoped to mirror GET /api/agent-defs — the listing is non-sensitive
       // ({vault,url,tokenPresent}); `tokenPresent` is a boolean, NEVER the token value.
       // POST is admin (it mints a token + writes config).
+      //
+      // NOTE (step-up, agent#80/#154): POST is intentionally NOT step-up-gated. It mints
+      // a VAULT-SCOPED token (`vault:<name>:write`) — a lower blast radius than the
+      // Claude OAuth credential / terminal / full-fs spawn the step-up PIN guards (those
+      // can exfiltrate every token or open a raw host shell). A def-vault token only
+      // reaches the named vault's notes, so `agent:admin` alone is the right bar here.
       const scope = req.method === "GET" ? SCOPE_READ : SCOPE_ADMIN;
       const denied = await requireScope(req, url, scope);
       if (denied) return denied;
@@ -2745,8 +2999,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 +3025,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();
@@ -3008,6 +3276,14 @@ function main(): void {
   mkdirSync(STATE_DIR, { recursive: true });
   mkdirSync(INBOX_DIR, { recursive: true });
 
+  // BOOT DEPENDENCY PREFLIGHT (agent#156). A fresh box can't run a programmatic
+  // `claude -p` turn until bwrap/rg/socat + the claude CLI are on PATH — pre-#156
+  // each surfaced only as a failed *turn*, one at a time. Check them ONCE at boot and
+  // log a single clear warning (with the install one-liners) when any is missing. It's
+  // advisory, never fatal: the daemon may run only attached-backend agents that need
+  // none of these, so we warn + keep serving. The result is also surfaced on /health.
+  const preflight = runBootPreflight();
+
   // Verify the one MCP SDK internal our HTTP-MCP delivery accounting reads
   // (`_streamMapping['_GET_stream']`, see assertMcpSdkStreamContract). A screaming
   // boot error on SDK drift beats discovering it as silent message loss later.
@@ -3124,7 +3400,7 @@ function main(): void {
     buildInstantiateDeps(channels, registry, deliveryState, programmatic, attachedQueue),
   );
 
-  const fetchHandler = createFetchHandler(channels, registry, { deliveryState, programmatic, attachedQueue, turnEvents, jobStore, runner, agentDefs });
+  const fetchHandler = createFetchHandler(channels, registry, { deliveryState, programmatic, attachedQueue, turnEvents, jobStore, runner, agentDefs, preflight });
   const server = Bun.serve<TerminalWsData, never>({
     port: PORT,
     hostname: "127.0.0.1",
@@ -3277,6 +3553,29 @@ function main(): void {
     const bindings = await resolveDefVaults({ hubOrigin: getHubOrigin(), managerBearer });
     for (const b of bindings) agentDefs.addVault(b);
     if (bindings.length === 0) return; // nothing bound — vault-native path idle.
+
+    // AUTO-REGISTER the per-def-vault runtime triggers (agent#157) so "define an
+    // agent → it runs" needs NO manual trigger setup + NO restart-to-pick-up:
+    //   - the def-watch create/edit triggers, BARE-keyed (`agent/definition`) so a
+    //     created/edited def auto-fires the rescan — upsert-by-name REPLACES any
+    //     stale `#agent/definition`-keyed `conn_agentdefs-*` row the hub provisioned;
+    //   - the inbound trigger (`agent/message/inbound` + has_metadata:[agent]) so a
+    //     new inbound note wakes the agent without a hand-registered trigger.
+    // Mints the admin (triggers API) + agent:send (webhook bearer) tokens the same
+    // way the hub's Connections engine does (attenuated to the operator bearer).
+    // Best-effort: a mint refusal / unreachable vault is logged, never fatal — the
+    // 60s loadAll poll below stays the correctness floor. Skipped with no operator
+    // bearer (can't mint) — the vault-native path still runs own-vault.
+    if (managerBearer) {
+      await registerAllDefVaultTriggers(bindings, { hubOrigin: getHubOrigin(), managerBearer }).catch(
+        (err) => {
+          console.warn(
+            `parachute-agent: def-vault trigger auto-registration failed (continuing): ${(err as Error).message}`,
+          );
+        },
+      );
+    }
+
     const n = await agentDefs.loadAll();
     console.log(
       `parachute-agent: vault-native agent defs — ${n} instantiated from ${bindings.length} def-vault(s).`,