@openparachute/agent 0.1.1 → 0.2.0

package/src/agents.ts

@@ -0,0 +1,379 @@
+/**
+ * Agent management — the daemon-facing layer behind the web spawn UI
+ * (`POST/GET /api/agents`) for the PROGRAMMATIC backend.
+ *
+ * Two live backends drive an agent (design 2026-06-16-pluggable-agent-backend.md +
+ * 2026-06-18-channel-backend.md): `programmatic` (the daemon runs `claude -p` turns,
+ * the default) and `channel` (a Claude Code session the operator connects handles the
+ * turn). The `interactive` (tmux) backend was RETIRED 2026-06-19 (design
+ * 2026-06-19-retire-interactive-backend.md) — its tmux SPAWNER + SESSION ADMIN were
+ * parked to `src/_parked/interactive-spawn.ts` (future terminal/process-mgmt), and
+ * the daemon no longer routes to it.
+ *
+ * What this module owns now:
+ *   1. {@link buildSpecFromBody} — turn an untrusted JSON request body into a
+ *      validated {@link AgentSpec} (or a {@link SpawnRequestError} mapped to 400).
+ *      `backend` defaults to `"programmatic"`; only `"programmatic"` is accepted as
+ *      a literal value (a `channel` agent is vault-native — define it as an
+ *      `#agent/definition` note, not via this POST).
+ *   2. {@link setupProgrammaticSpawn} — the spawn-time, non-turn setup for a
+ *      programmatic agent (slug-guard, require a wake channel, resolve the Claude
+ *      credential early, persist spec.json).
+ */
+
+import { statSync } from "node:fs";
+import type {
+  AgentSpec,
+  AgentChannel,
+  AgentVaultSpec,
+  AgentMount,
+} from "./sandbox/types.ts";
+import {
+  sessionWorkspace,
+  persistSpec,
+  readPersistedSpec,
+} from "./spawn-agent.ts";
+import { sessionsDir as defaultSessionsDir } from "./spawn-deps.ts";
+import { normalizeChannel } from "./sandbox/types.ts";
+import { resolveClaudeCredential } from "./credentials.ts";
+
+/** Same slug shape spawn enforces — validated early so a bad name 400s. */
+export const AGENT_NAME_SLUG = /^[a-z0-9_-]+$/i;
+
+/**
+ * One agent as the `/api/agents` list returns it — a PROGRAMMATIC or ATTACHED agent
+ * (the only two live backends; interactive was retired 2026-06-19). Neither has a
+ * tmux session, so `session` is the conventional `<name>-agent` display label and
+ * liveness rides in `status` (`idle` | `working` | `queued:N`) rather than the old
+ * tmux `attached`/`mcp_sessions` flags. Built by `listProgrammaticAgents` /
+ * `listAttachedAgents` (daemon.ts). NEVER carries a secret.
+ */
+export interface AgentInfo {
+  /** Agent slug. */
+  name: string;
+  /** Conventional `<name>-agent` display label (no tmux session backs it). */
+  session: string;
+  /** Per-session workspace dir (where spec.json lives). */
+  workspace: string;
+  /** Whether the session's workspace (with its spec.json) is present on disk. */
+  hasWorkspace: boolean;
+  /** Which backend drives this agent. */
+  backend: "programmatic" | "attached";
+  /** Live status — `idle` | `working` | `queued:N`. */
+  status?: string;
+  /** The wake channel this agent serves (present for channel agents). */
+  channel?: string;
+  /** The vault backing this agent's conversation, when known. */
+  vault?: string;
+  /** The system-prompt COMPOSITION mode when a per-channel system prompt is set. */
+  systemPromptMode?: "append" | "replace";
+  /** The agent's WORKING directory when the spec sets one (absent = private dir). */
+  workingDir?: string;
+}
+
+/** A malformed spawn request body — the caller maps `.message` to a 400. */
+export class SpawnRequestError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SpawnRequestError";
+  }
+}
+
+/**
+ * Build a validated {@link AgentSpec} from an untrusted JSON request body. Throws
+ * {@link SpawnRequestError} on any malformed field — the daemon maps it to a 400.
+ *
+ * Accepts channels as either `["name"]` (write) or `[{ name, access }]`. The
+ * spawn slug guard is the authority on the name, but we check it here too so a bad
+ * name fails before any dep resolution / mint side effect.
+ */
+export function buildSpecFromBody(body: unknown): AgentSpec {
+  if (!body || typeof body !== "object") {
+    throw new SpawnRequestError("request body must be a JSON object");
+  }
+  const b = body as Record<string, unknown>;
+
+  const name = b.name;
+  if (typeof name !== "string" || name.length === 0) {
+    throw new SpawnRequestError("body.name (non-empty string) is required");
+  }
+  if (!AGENT_NAME_SLUG.test(name)) {
+    throw new SpawnRequestError(
+      `body.name "${name}" must be a slug (alphanumeric, dash, underscore only)`,
+    );
+  }
+
+  if (!Array.isArray(b.channels) || b.channels.length === 0) {
+    throw new SpawnRequestError("body.channels must be a non-empty array (the first is the wake channel)");
+  }
+  const channels: AgentChannel[] = b.channels.map((raw, i) => parseChannelEntry(raw, i));
+
+  const spec: AgentSpec = { name, channels };
+
+  if (b.vault !== undefined && b.vault !== null) {
+    spec.vault = parseVaultEntry(b.vault);
+  }
+
+  if (b.filesystem !== undefined && b.filesystem !== null) {
+    if (b.filesystem !== "workspace" && b.filesystem !== "full") {
+      throw new SpawnRequestError('body.filesystem must be "workspace" or "full"');
+    }
+    spec.filesystem = b.filesystem;
+  }
+
+  if (b.network !== undefined && b.network !== null) {
+    if (b.network !== "open" && b.network !== "restricted") {
+      throw new SpawnRequestError('body.network must be "open" or "restricted"');
+    }
+    spec.network = b.network;
+  }
+
+  if (b.egress !== undefined && b.egress !== null) {
+    if (!Array.isArray(b.egress)) {
+      throw new SpawnRequestError("body.egress must be an array of host strings");
+    }
+    const egress = b.egress
+      .map((h) => {
+        if (typeof h !== "string") throw new SpawnRequestError("body.egress entries must be strings");
+        return h.trim();
+      })
+      .filter((h) => h.length > 0);
+    // Additional allowed hosts — only take effect under `network: "restricted"`
+    // (open = fully open network); harmless to carry otherwise.
+    if (egress.length > 0) spec.egress = egress;
+  }
+
+  if (b.mounts !== undefined && b.mounts !== null) {
+    if (!Array.isArray(b.mounts)) {
+      throw new SpawnRequestError("body.mounts must be an array");
+    }
+    const mounts = b.mounts.map((raw, i) => parseMountEntry(raw, i));
+    if (mounts.length > 0) spec.mounts = mounts;
+  }
+
+  // Working directory — the WORKING-DIRECTORY axis (design
+  // 2026-06-16-agent-filesystem-and-sharing.md). When set, this absolute host path
+  // is the agent's cwd + an rw working-root; it's shareable across agents. Require
+  // an ABSOLUTE path. Trimmed. A blank/whitespace-only value is treated as unset.
+  // The credential-bearing private home (`.mcp.json` etc.) is NEVER this dir.
+  if (b.workspace !== undefined && b.workspace !== null) {
+    if (typeof b.workspace !== "string") {
+      throw new SpawnRequestError("body.workspace must be a string (an absolute host path)");
+    }
+    const workspace = b.workspace.trim();
+    if (workspace.length > 0) {
+      if (!workspace.startsWith("/")) {
+        throw new SpawnRequestError('body.workspace must be an absolute path (start with "/")');
+      }
+      // The working dir becomes the agent's cwd — it MUST pre-exist as a directory.
+      let st: ReturnType<typeof statSync> | undefined;
+      try {
+        st = statSync(workspace);
+      } catch {
+        throw new SpawnRequestError(
+          `body.workspace "${workspace}" does not exist — the working directory must be a real ` +
+            `directory on disk (the agent's cwd).`,
+        );
+      }
+      if (!st.isDirectory()) {
+        throw new SpawnRequestError(`body.workspace "${workspace}" is not a directory.`);
+      }
+      spec.workspace = workspace;
+    }
+  }
+
+  // Backend selector. Only `"programmatic"` is accepted via this web spawn POST
+  // (the default when omitted). `"attached"` (the backend value formerly named
+  // `"channel"`) is VAULT-NATIVE — define an attached agent as a #agent/definition note,
+  // not via this endpoint. `"interactive"` was RETIRED (design 2026-06-19-retire-
+  // interactive-backend.md) — it is no longer a selectable backend anywhere.
+  if (b.backend !== undefined && b.backend !== null) {
+    if (b.backend !== "programmatic") {
+      throw new SpawnRequestError(
+        // Accept the legacy `"channel"` value in the diagnostic branch (dual-read of the
+        // renamed backend value) — both map to the same vault-native guidance.
+        b.backend === "attached" || b.backend === "channel"
+          ? "attached-backend agents are vault-native — define them as an #agent/definition note, not via this endpoint"
+          : b.backend === "interactive"
+            ? 'the "interactive" backend is retired — use "programmatic" (the default) or define an "attached" agent as a #agent/definition note'
+            : 'body.backend must be "programmatic"',
+      );
+    }
+    spec.backend = b.backend;
+  } else {
+    spec.backend = "programmatic";
+  }
+
+  // Per-channel system prompt — the operator gives the channel a role (design
+  // 2026-06-16-channel-system-prompt.md). `systemPromptMode` decides composition with
+  // CC's default: "append" (default) or "replace". A blank prompt is treated as unset.
+  if (b.systemPrompt !== undefined && b.systemPrompt !== null) {
+    if (typeof b.systemPrompt !== "string") {
+      throw new SpawnRequestError("body.systemPrompt must be a string");
+    }
+  }
+  if (b.systemPromptMode !== undefined && b.systemPromptMode !== null) {
+    if (b.systemPromptMode !== "append" && b.systemPromptMode !== "replace") {
+      throw new SpawnRequestError('body.systemPromptMode must be "append" or "replace"');
+    }
+  }
+  const promptText = typeof b.systemPrompt === "string" ? b.systemPrompt.trim() : "";
+  if (promptText.length > 0) {
+    spec.systemPrompt = promptText;
+    spec.systemPromptMode = b.systemPromptMode === "replace" ? "replace" : "append";
+  }
+
+  return spec;
+}
+
+function parseChannelEntry(raw: unknown, i: number): AgentChannel {
+  if (typeof raw === "string") {
+    if (raw.length === 0) throw new SpawnRequestError(`body.channels[${i}] is an empty string`);
+    return raw;
+  }
+  if (!raw || typeof raw !== "object") {
+    throw new SpawnRequestError(`body.channels[${i}] must be a string or { name, access }`);
+  }
+  const c = raw as Record<string, unknown>;
+  if (typeof c.name !== "string" || c.name.length === 0) {
+    throw new SpawnRequestError(`body.channels[${i}].name (non-empty string) is required`);
+  }
+  if (c.access !== undefined && c.access !== "read" && c.access !== "write") {
+    throw new SpawnRequestError(`body.channels[${i}].access must be "read" or "write"`);
+  }
+  return c.access === undefined
+    ? { name: c.name }
+    : { name: c.name, access: c.access as "read" | "write" };
+}
+
+function parseVaultEntry(raw: unknown): AgentVaultSpec {
+  if (!raw || typeof raw !== "object") {
+    throw new SpawnRequestError("body.vault must be { name, access, tags? }");
+  }
+  const v = raw as Record<string, unknown>;
+  if (typeof v.name !== "string" || v.name.length === 0) {
+    throw new SpawnRequestError("body.vault.name (non-empty string) is required");
+  }
+  if (v.access !== "read" && v.access !== "write" && v.access !== "admin") {
+    throw new SpawnRequestError('body.vault.access must be "read", "write", or "admin"');
+  }
+  const spec: AgentVaultSpec = { name: v.name, access: v.access as "read" | "write" | "admin" };
+  if (v.tags !== undefined && v.tags !== null) {
+    if (!Array.isArray(v.tags)) throw new SpawnRequestError("body.vault.tags must be an array of strings");
+    const tags = v.tags
+      .map((t) => {
+        if (typeof t !== "string") throw new SpawnRequestError("body.vault.tags entries must be strings");
+        return t.trim();
+      })
+      .filter((t) => t.length > 0);
+    if (tags.length > 0) spec.tags = tags;
+  }
+  return spec;
+}
+
+function parseMountEntry(raw: unknown, i: number): AgentMount {
+  if (!raw || typeof raw !== "object") {
+    throw new SpawnRequestError(`body.mounts[${i}] must be { hostPath, mountPath, mode, shared? }`);
+  }
+  const m = raw as Record<string, unknown>;
+  if (typeof m.hostPath !== "string" || m.hostPath.length === 0) {
+    throw new SpawnRequestError(`body.mounts[${i}].hostPath (non-empty string) is required`);
+  }
+  if (typeof m.mountPath !== "string" || m.mountPath.length === 0) {
+    throw new SpawnRequestError(`body.mounts[${i}].mountPath (non-empty string) is required`);
+  }
+  // Require ABSOLUTE paths — make the trust boundary explicit with a clean 400 here
+  // rather than a confusing sandbox behavior downstream.
+  if (!m.hostPath.startsWith("/")) {
+    throw new SpawnRequestError(`body.mounts[${i}].hostPath must be an absolute path (start with "/")`);
+  }
+  if (!m.mountPath.startsWith("/")) {
+    throw new SpawnRequestError(`body.mounts[${i}].mountPath must be an absolute path (start with "/")`);
+  }
+  if (m.mode !== "ro" && m.mode !== "rw") {
+    throw new SpawnRequestError(`body.mounts[${i}].mode must be "ro" or "rw"`);
+  }
+  const mount: AgentMount = {
+    hostPath: m.hostPath,
+    mountPath: m.mountPath,
+    mode: m.mode as "ro" | "rw",
+  };
+  if (m.shared !== undefined && m.shared !== null) {
+    if (typeof m.shared !== "string" || m.shared.length === 0) {
+      throw new SpawnRequestError(`body.mounts[${i}].shared must be a non-empty string`);
+    }
+    mount.shared = m.shared;
+  }
+  return mount;
+}
+
+/**
+ * The redacted result a PROGRAMMATIC spawn returns to the wire — there is no tmux
+ * session and no per-launch minted-token set (the programmatic backend mints the
+ * vault token per-turn, not at spawn), so this is a thin "registered" acknowledgment.
+ */
+export interface ProgrammaticSpawnResult {
+  /** The agent slug. */
+  name: string;
+  /** The wake channel the agent serves. */
+  channel: string;
+  /** Always "programmatic" — lets the page render the right status affordances. */
+  backend: "programmatic";
+  /** Per-session workspace dir (where .mcp.json is written per-turn + spec.json lives). */
+  workspace: string;
+  /** Whether an agent was already registered under this name (idempotent replace). */
+  alreadyRunning: boolean;
+}
+
+/**
+ * Validate + set up a PROGRAMMATIC agent spawn (design 2026-06-16 step 2). It does
+ * the spawn-time, NON-turn work: slug-guard the name, require a wake channel, resolve
+ * the Claude credential EARLY (a missing one throws {@link CredentialNotConfiguredError}
+ * BEFORE registering — so a programmatic agent never registers without auth), and
+ * persist spec.json (carrying `backend: "programmatic"`) so a daemon restart
+ * re-registers it on boot.
+ *
+ * It does NOT itself register the agent in the live registry or mint any token — the
+ * daemon owns the {@link ProgrammaticAgentRegistry} instance and calls
+ * `registry.register(spec)` after this returns.
+ *
+ * `resolveClaudeToken` + `sessionsDirPath` are injectable so tests run hermetically.
+ */
+export function setupProgrammaticSpawn(
+  spec: AgentSpec,
+  opts?: {
+    resolveClaudeToken?: (channel: string) => string;
+    sessionsDirPath?: string;
+  },
+): ProgrammaticSpawnResult {
+  if (!AGENT_NAME_SLUG.test(spec.name)) {
+    throw new SpawnRequestError(
+      `agent name "${spec.name}" must be a slug (alphanumeric, dash, underscore only)`,
+    );
+  }
+  if (spec.channels.length === 0) {
+    throw new SpawnRequestError(`spec "${spec.name}" declares no channels (the first is the wake channel)`);
+  }
+  const channel = normalizeChannel(spec.channels[0]!).name;
+  const dir = opts?.sessionsDirPath ?? defaultSessionsDir();
+  const workspace = sessionWorkspace(dir, spec.name);
+
+  // Resolve the Claude credential EARLY — a missing one throws
+  // CredentialNotConfiguredError, which the daemon maps to a 400 with the fix, so a
+  // programmatic agent never registers (and never runs a turn) without auth.
+  const resolveToken = opts?.resolveClaudeToken ?? ((ch: string) => resolveClaudeCredential(ch));
+  resolveToken(channel);
+
+  // Was a spec already persisted (an idempotent re-spawn)? Persist the (possibly
+  // updated) spec carrying backend:"programmatic" so a restart re-registers it.
+  const prior = readPersistedSpec(workspace);
+  persistSpec(workspace, { ...spec, backend: "programmatic" });
+
+  return {
+    name: spec.name,
+    channel,
+    backend: "programmatic",
+    workspace,
+    alreadyRunning: prior !== null,
+  };
+}

package/src/auth.test.ts

@@ -0,0 +1,46 @@
+/**
+ * Unit tests for the dual-accept scope helpers (channel→agent rename, back-compat
+ * rule 1). `grantsScope` is the single chokepoint every scope gate routes through;
+ * an isolated test locks the legacy-alias logic so a future edit can't silently
+ * drop pre-rename `channel:*` acceptance (the class of bug the mcp-http write-gate
+ * fix caught). Pure functions — no mocks, no JWKS.
+ */
+import { describe, test, expect } from "bun:test";
+import { grantsScope, legacyScopeAlias } from "./auth.ts";
+
+describe("legacyScopeAlias", () => {
+  test("maps an agent:<verb> scope to its pre-rename channel:<verb> form", () => {
+    expect(legacyScopeAlias("agent:read")).toBe("channel:read");
+    expect(legacyScopeAlias("agent:write")).toBe("channel:write");
+    expect(legacyScopeAlias("agent:send")).toBe("channel:send");
+    expect(legacyScopeAlias("agent:admin")).toBe("channel:admin");
+  });
+
+  test("returns undefined for a scope with no agent: prefix (no legacy alias)", () => {
+    expect(legacyScopeAlias("vault:read")).toBeUndefined();
+    expect(legacyScopeAlias("channel:read")).toBeUndefined();
+    expect(legacyScopeAlias("agentfoo")).toBeUndefined();
+  });
+});
+
+describe("grantsScope — dual-accept (new agent:* OR legacy channel:*)", () => {
+  test("grants when the new agent:<verb> scope is present", () => {
+    expect(grantsScope(["agent:write"], "agent:write")).toBe(true);
+  });
+
+  test("grants when only the legacy channel:<verb> scope is present (pre-rename token)", () => {
+    expect(grantsScope(["channel:write"], "agent:write")).toBe(true);
+    expect(grantsScope(["channel:read", "channel:send"], "agent:send")).toBe(true);
+  });
+
+  test("denies when neither the new nor the legacy scope is present", () => {
+    expect(grantsScope(["agent:read"], "agent:write")).toBe(false);
+    expect(grantsScope(["vault:write"], "agent:write")).toBe(false);
+    expect(grantsScope([], "agent:read")).toBe(false);
+  });
+
+  test("does NOT cross-grant a different verb via the alias", () => {
+    // channel:read must not satisfy agent:write — the alias is per-verb only.
+    expect(grantsScope(["channel:read"], "agent:write")).toBe(false);
+  });
+});

package/src/auth.ts

@@ -0,0 +1,140 @@
+/**
+ * Shared hub-JWT auth gate for parachute-agent's HTTP surfaces.
+ *
+ * Both auth layers run the same check — validate a hub-issued JWT against the
+ * hub's JWKS (via `hub-jwt.ts` → scope-guard) and assert a required scope:
+ *
+ *   - 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).
+ *
+ * `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).
+ *
+ * DUAL-ACCEPT (channel→agent rename transition,
+ * `parachute-patterns/migrations/2026-06-17-channel-to-agent.md` rule 1). New
+ * tokens carry `agent:*` scopes; tokens minted before the rename carry
+ * `channel:*`. The hub now MINTS `agent:*`, but live agent tokens minted earlier
+ * must keep validating until re-minted. So `requireScope` accepts a request that
+ * carries EITHER the required `agent:<verb>` scope OR its legacy `channel:<verb>`
+ * equivalent. A later contract cycle drops the legacy acceptance.
+ */
+
+import { validateHubJwt, HubJwtError } from "./hub-jwt.ts";
+import { extractBearer } from "@openparachute/scope-guard";
+
+/** Agent scopes, declared here so callers share one spelling. */
+export const SCOPE_READ = "agent:read" as const;
+export const SCOPE_WRITE = "agent:write" as const;
+export const SCOPE_SEND = "agent:send" as const;
+/** Config-management scope: create/list/delete channels (hub-orchestrated setup). */
+export const SCOPE_ADMIN = "agent:admin" as const;
+
+/**
+ * Legacy alias for a new `agent:<verb>` scope — its pre-rename `channel:<verb>`
+ * form. A token that carries the legacy scope is still accepted on read (the
+ * dual-accept transition). Returns `undefined` when the scope has no `agent:`
+ * prefix (a generic scope with no legacy alias).
+ */
+export function legacyScopeAlias(scope: string): string | undefined {
+  return scope.startsWith("agent:") ? `channel:${scope.slice("agent:".length)}` : undefined;
+}
+
+/**
+ * Whether a granted scope list authorizes `required` under dual-accept: it
+ * contains `required` itself OR its legacy `channel:<verb>` alias.
+ */
+export function grantsScope(granted: readonly string[], required: string): boolean {
+  if (granted.includes(required)) return true;
+  const legacy = legacyScopeAlias(required);
+  return legacy !== undefined && granted.includes(legacy);
+}
+
+/**
+ * The scope the in-page terminal requires. The terminal attaches to a session's
+ * live tmux pane — the MOST DANGEROUS capability the daemon exposes (full
+ * interactive control of the session's shell), so it is OPERATOR-GATED, not
+ * session-gated. We reuse `agent:admin`: the hub mints it ONLY for the
+ * logged-in operator's cookie session (`<hub>/admin/agent-token` →
+ * `agent:read agent:send agent:admin`), and never for a connecting Claude
+ * Code session (a session holds `agent:read`/`agent:write`, never
+ * `agent:admin`). So a session can never open a terminal onto itself or
+ * another — only the operator can. This is the design's "operator-gated"
+ * requirement expressed in the module's existing scope vocabulary (no new scope to
+ * mint, no hub change). See `design/2026-06-14-sandboxed-agent-sessions.md` §5.3.
+ */
+export const SCOPE_TERMINAL = SCOPE_ADMIN;
+
+/** JSON Response helper (shared spelling for the auth error bodies). */
+export function json(data: unknown, status = 200): Response {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+/**
+ * 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.
+ */
+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
+  // endpoint that doesn't strictly need them (and out of those access logs).
+  if (allowQueryParam) {
+    const q = url.searchParams.get("token");
+    if (q && q.length > 0) return q;
+  }
+  return null;
+}
+
+/**
+ * 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.
+ *
+ * Returns `null` when the request is authorized (caller proceeds), or a
+ * `Response` (401/403) the caller must return as-is.
+ *
+ * The no-token path short-circuits before any JWKS fetch, so it's unit-testable
+ * without a live hub. Real signature/issuer/audience validation is scope-guard's
+ * own tested surface.
+ */
+export async function requireScope(
+  req: Request,
+  url: URL,
+  scope: string,
+  allowQueryParam = false,
+): Promise<Response | null> {
+  const token = extractToken(req, url, allowQueryParam);
+  if (!token) {
+    return json({ error: "unauthorized", message: "Bearer token required" }, 401);
+  }
+  try {
+    const claims = await validateHubJwt(token);
+    // Dual-accept: the required `agent:<verb>` scope OR its legacy `channel:<verb>`
+    // alias authorizes the request (pre-rename tokens keep validating).
+    if (!grantsScope(claims.scopes, scope)) {
+      return json(
+        { error: "insufficient_scope", message: `requires ${scope}`, granted: claims.scopes },
+        403,
+      );
+    }
+    return null;
+  } catch (err) {
+    return json(
+      { error: "unauthorized", message: err instanceof HubJwtError ? err.message : "invalid token" },
+      401,
+    );
+  }
+}