@openparachute/agent 0.2.2 → 0.2.3-rc.11

package/.parachute/module.json

@@ -52,7 +52,7 @@
         "module": "vault",
         "event": "note.created",
         "filter": {
-          "tags": ["#agent/message/inbound"],
+          "tags": ["agent/message/inbound"],
           "has_metadata": ["channel"],
           "missing_metadata": ["channel_inbound_rendered_at"]
         }
@@ -85,7 +85,7 @@
         "module": "vault",
         "event": "note.created",
         "filter": {
-          "tags": ["#agent/definition"]
+          "tags": ["agent/definition"]
         }
       },
       "sink": {
@@ -110,7 +110,7 @@
         "module": "vault",
         "event": "note.updated",
         "filter": {
-          "tags": ["#agent/definition"]
+          "tags": ["agent/definition"]
         }
       },
       "sink": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/agent",
-  "version": "0.2.2",
+  "version": "0.2.3-rc.11",
   "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",
@@ -24,6 +24,8 @@
     "test:spa": "cd web/ui && bun run test",
     "test:all": "bun run test && bun run test:spa",
     "test:e2e": "bun e2e/llm/run.ts",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
     "typecheck": "tsc --noEmit",
     "build:spa": "cd web/ui && bun install --frozen-lockfile && bun run build",
     "prepack": "bun run build:spa"
@@ -39,6 +41,7 @@
     "typescript": "^5"
   },
   "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
     "@types/bun": "latest"
   },
   "repository": {

package/src/agent-defs.ts

@@ -389,6 +389,15 @@ export function parseAgentDef(note: {
   }
 
   // Filesystem read scope.
+  //
+  // NOTE (step-up, agent#80): `filesystem: "full"` is the dangerous, full-disk
+  // case. The step-up PIN gate is enforced on the HTTP spawn path only
+  // (`POST /api/agents` in daemon.ts). This VAULT-NATIVE path (a #agent/definition
+  // note with `filesystem: full`) is NOT step-up-gated — registering it requires
+  // `vault:write` to author the note, which is itself separately scope-gated, so a
+  // step-up challenge here would gate a capability the caller already had to hold a
+  // write credential to reach. If the threat model is ever revisited (e.g. less-
+  // trusted note authors), this is the gap to close.
   const filesystem = metaStr(meta.filesystem);
   if (filesystem !== undefined) {
     if (filesystem !== "workspace" && filesystem !== "full") {

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,8 @@
 
 import { validateHubJwt, HubJwtError } from "./hub-jwt.ts";
 import { extractBearer } from "@openparachute/scope-guard";
+import { consumeTicket } from "./ui-ticket.ts";
+import { isStepUpTokenValid, isStepUpConfigured } from "./step-up.ts";
 
 /** Agent scopes, declared here so callers share one spelling. */
 export const SCOPE_READ = "agent:read" as const;
@@ -79,15 +94,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 +117,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 +157,152 @@ 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;
+}
+
+/**
+ * The header a request carries the step-up token on (agent#80). The terminal
+ * WebSocket — which `new WebSocket()` can't set a header on — uses the
+ * `?step_up=` query param instead (mirroring the `?token=` exception).
+ */
+export const STEP_UP_TOKEN_HEADER = "x-step-up-token";
+
+/** Extract a presented step-up token: the header first, then `?step_up=` when allowed. */
+export function extractStepUpToken(req: Request, url: URL, allowQueryParam = false): string | null {
+  const header = req.headers.get(STEP_UP_TOKEN_HEADER);
+  if (header && header.length > 0) return header;
+  if (allowQueryParam) {
+    const q = url.searchParams.get("step_up");
+    if (q && q.length > 0) return q;
+  }
+  return null;
+}
+
+/**
+ * SECOND-FACTOR gate (agent#80) for the genuinely dangerous `agent:admin` actions:
+ * set/rotate credentials, open a terminal, spawn a `filesystem: full` agent. The
+ * caller runs {@link requireScope}(`agent:admin`) FIRST; this asserts — IN ADDITION —
+ * a valid step-up token (the operator entered their PIN recently).
+ *
+ *   - Step-up NOT configured (no PIN set) → returns `{ ok: false, reason: "setup" }`.
+ *     The caller maps it to `403 { error: "step_up_required", reason: "setup" }` so
+ *     the UI runs its FIRST-TIME PIN-setup flow before the action.
+ *   - PIN configured + valid token → `{ ok: true }` (the action proceeds).
+ *   - PIN configured + missing/expired token → `{ ok: false, reason: "token" }` →
+ *     `403 { error: "step_up_required" }` so the UI PROMPTS for the PIN.
+ *
+ * The 403 is deliberately DISTINCT from `requireScope`'s 401 (no/invalid Bearer):
+ * a 401 means "re-authenticate", a 403 `step_up_required` means "enter your PIN".
+ * The step-up token NEVER widens scope — the request already passed `agent:admin`;
+ * this is purely a recency re-confirm on top.
+ *
+ * `allowQueryParam: true` accepts `?step_up=` for the terminal WebSocket only.
+ * Pure in-memory token check — no I/O on the gated request path, no secret logged.
+ */
+export function requireStepUp(
+  req: Request,
+  url: URL,
+  allowQueryParam = false,
+  opts?: { configured?: () => boolean; valid?: (token: string | null) => boolean },
+): { ok: true } | { ok: false; response: Response } {
+  const isConfigured = opts?.configured ?? (() => isStepUpConfigured());
+  const isValid = opts?.valid ?? ((t: string | null) => isStepUpTokenValid(t));
+  if (!isConfigured()) {
+    // No PIN yet — the UI must set one before this action can proceed.
+    return {
+      ok: false,
+      response: json(
+        {
+          error: "step_up_required",
+          reason: "setup",
+          message: "set a step-up PIN before performing this action",
+        },
+        403,
+      ),
+    };
+  }
+  const token = extractStepUpToken(req, url, allowQueryParam);
+  if (!isValid(token)) {
+    return {
+      ok: false,
+      response: json(
+        {
+          error: "step_up_required",
+          reason: "token",
+          message: "enter your step-up PIN to confirm this action",
+        },
+        403,
+      ),
+    };
+  }
+  return { ok: true };
+}

package/src/backends/programmatic.ts

@@ -85,6 +85,7 @@ import type {
   DeliverResult,
   DeliverUsage,
   InterimSink,
+  RunContext,
   TurnSession,
 } from "./types.ts";
 
@@ -327,6 +328,32 @@ export function buildProgrammaticClaudeArgs(opts: {
   return argv;
 }
 
+/**
+ * Render the {@link RunContext} as a concise, clearly-LABELED preamble to PREPEND to a turn's
+ * message (agent#162). A headless `claude -p` turn has no clock + no notion of which run it is,
+ * so the daemon hands it these facts (the real wall-clock, new-vs-resumed, why it fired, the
+ * prior turn count) — the agent then stamps ACCURATE times instead of fabricating them.
+ *
+ * It is a single fenced block clearly marked as daemon-injected runtime context (NOT the
+ * agent's own system prompt — that's untouched), then a blank line, then the real message. The
+ * `now` is always present; the rest are appended only when known. Returns the message UNCHANGED
+ * when `rc` is absent (additive — no behavior change for a caller that doesn't pass one).
+ */
+export function renderRunContext(message: string, rc: RunContext | undefined): string {
+  if (!rc) return message;
+  const parts: string[] = [`now=${rc.now}`, `session=${rc.session}`];
+  if (typeof rc.priorTurnCount === "number" && rc.priorTurnCount >= 0) {
+    // The NUMBER of this turn (1-based) = completed turns + 1 — what an agent stamps as "turn N".
+    parts.push(`turn=${rc.priorTurnCount + 1}`);
+  }
+  if (rc.firedBy) parts.push(`fired-by=${rc.firedBy}`);
+  const preamble =
+    `[Run context — injected by the agent daemon (this is the real runtime state, NOT your ` +
+    `system prompt). Use these for any timestamp/clock or "which run is this" reasoning instead ` +
+    `of guessing: ${parts.join(", ")}]`;
+  return `${preamble}\n\n${message}`;
+}
+
 /** Read the full text of a (possibly null) byte stream; null/error → "". */
 async function drainStream(stream: ReadableStream<Uint8Array> | null): Promise<string> {
   if (!stream) return "";
@@ -414,6 +441,7 @@ export class ProgrammaticBackend implements AgentBackend {
     session: TurnSession,
     onInterim?: InterimSink,
     attachments?: InboundAttachment[],
+    runContext?: RunContext,
   ): Promise<DeliverResult> {
     const spec = handle.spec;
     if (!spec) {
@@ -537,13 +565,18 @@ export class ProgrammaticBackend implements AgentBackend {
     // per-agent even when the working dir is shared. Best-effort + isolated: a single
     // attachment's fetch/stage failure logs + is SKIPPED (the turn still runs with the rest
     // + the text). Absent/empty → no staging, no prompt change (today's behavior exactly).
-    let turnMessage = message;
+    // RUN CONTEXT (agent#162): prepend the daemon-injected runtime preamble (the real
+    // wall-clock + new/resumed + why-it-fired) so the headless turn reads ACCURATE facts
+    // instead of fabricating a clock. Done FIRST so the preamble sits at the very top of the
+    // prompt; attachments append after the (already-prefixed) message. Absent runContext →
+    // the message is unchanged (additive).
+    let turnMessage = renderRunContext(message, runContext);
     if (attachments && attachments.length > 0) {
       const staged = await this.stageAttachments(workspace, attachments, vaultArg);
       if (staged.length > 0) {
         const lines = staged.map((s) => `- ${s.absPath} (${s.mimeType})`);
         turnMessage =
-          `${message}\n\n[Attached files — read them as needed:\n${lines.join("\n")}\n]`;
+          `${turnMessage}\n\n[Attached files — read them as needed:\n${lines.join("\n")}\n]`;
       }
     }