@openparachute/agent 0.1.2 → 0.2.0

package/src/mint-token.test.ts

@@ -0,0 +1,152 @@
+import { describe, test, expect } from "bun:test";
+import {
+  mintScopedToken,
+  agentScope,
+  vaultScope,
+  MintError,
+  type MintTokenDeps,
+} from "./mint-token.ts";
+
+/** A fake hub mint endpoint. Records the request; returns a scripted response. */
+function fakeHub(
+  handler: (body: Record<string, unknown>, headers: Headers) => { status: number; json: unknown },
+): { fetchFn: typeof fetch; calls: Array<{ body: Record<string, unknown>; auth: string | null }> } {
+  const calls: Array<{ body: Record<string, unknown>; auth: string | null }> = [];
+  const fetchFn = (async (url: string | URL | Request, init?: RequestInit) => {
+    const headers = new Headers(init?.headers);
+    const body = JSON.parse(String(init?.body ?? "{}")) as Record<string, unknown>;
+    calls.push({ body, auth: headers.get("authorization") });
+    const { status, json } = handler(body, headers);
+    return new Response(JSON.stringify(json), {
+      status,
+      headers: { "content-type": "application/json" },
+    });
+  }) as unknown as typeof fetch;
+  return { fetchFn, calls };
+}
+
+function depsWith(fetchFn: typeof fetch): MintTokenDeps {
+  return { hubOrigin: "https://hub.example.com", managerBearer: "MANAGER-BEARER", fetchFn };
+}
+
+describe("scope string helpers", () => {
+  test("agentScope", () => {
+    expect(agentScope({ write: false })).toBe("agent:read");
+    expect(agentScope({ write: true })).toBe("agent:read agent:write");
+  });
+  test("vaultScope", () => {
+    expect(vaultScope("default", "read")).toBe("vault:default:read");
+    expect(vaultScope("work", "write")).toBe("vault:work:write");
+  });
+});
+
+describe("mintScopedToken — happy path", () => {
+  test("POSTs to /api/auth/mint-token with the manager bearer + scope, returns the token", async () => {
+    const hub = fakeHub((body) => ({
+      status: 200,
+      json: {
+        jti: "j1",
+        token: "MINTED-TOKEN",
+        expires_at: "2026-09-01T00:00:00Z",
+        scope: body.scope,
+      },
+    }));
+    const res = await mintScopedToken({ scope: "agent:read agent:write" }, depsWith(hub.fetchFn));
+    expect(res.token).toBe("MINTED-TOKEN");
+    expect(res.jti).toBe("j1");
+    // Presented the MANAGER's bearer (the attenuation principal).
+    expect(hub.calls[0]!.auth).toBe("Bearer MANAGER-BEARER");
+    expect(hub.calls[0]!.body.scope).toBe("agent:read agent:write");
+  });
+
+  test("passes audience + permissions (scoped_tags) through to the hub", async () => {
+    const hub = fakeHub(() => ({
+      status: 200,
+      json: { jti: "j", token: "T", expires_at: "", scope: "vault:default:read" },
+    }));
+    await mintScopedToken(
+      {
+        scope: "vault:default:read",
+        audience: "vault.default",
+        permissions: { scoped_tags: ["#agent/message"] },
+      },
+      depsWith(hub.fetchFn),
+    );
+    expect(hub.calls[0]!.body.audience).toBe("vault.default");
+    expect(hub.calls[0]!.body.permissions).toEqual({ scoped_tags: ["#agent/message"] });
+  });
+});
+
+describe("mintScopedToken — attenuation + error surfacing", () => {
+  test("CAPABILITY ATTENUATION: the hub's 400 invalid_scope (over-broad request) becomes a MintError", async () => {
+    // Simulate the hub's canGrant guard: a vault:default:read manager bearer
+    // requests vault:default:write → the hub refuses 400 invalid_scope. The
+    // attenuation bound lives in the hub; this asserts the client surfaces the
+    // refusal as a hard error (never launches a session with an ungrantable cred).
+    const hub = fakeHub((body) => {
+      // Manager bearer in this scenario only holds vault:default:read; a write
+      // request exceeds it → hub returns 400.
+      if (String(body.scope).includes(":write")) {
+        return {
+          status: 400,
+          json: {
+            error: "invalid_scope",
+            error_description:
+              "scope vault:default:write is not grantable by this bearer; use OAuth flow or operator rotation",
+          },
+        };
+      }
+      return { status: 200, json: { jti: "j", token: "ok", expires_at: "", scope: body.scope } };
+    });
+
+    // The grantable read mint succeeds.
+    const ok = await mintScopedToken({ scope: "vault:default:read" }, depsWith(hub.fetchFn));
+    expect(ok.token).toBe("ok");
+
+    // The over-broad write mint is refused — surfaced as a MintError carrying the code.
+    let err: unknown;
+    try {
+      await mintScopedToken({ scope: "vault:default:write" }, depsWith(hub.fetchFn));
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeInstanceOf(MintError);
+    expect((err as MintError).status).toBe(400);
+    expect((err as MintError).code).toBe("invalid_scope");
+  });
+
+  test("a 403 insufficient_scope (no minting authority) becomes a MintError", async () => {
+    const hub = fakeHub(() => ({
+      status: 403,
+      json: { error: "insufficient_scope", error_description: "bearer holds no minting authority" },
+    }));
+    let err: unknown;
+    try {
+      await mintScopedToken({ scope: "agent:read" }, depsWith(hub.fetchFn));
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeInstanceOf(MintError);
+    expect((err as MintError).status).toBe(403);
+    expect((err as MintError).code).toBe("insufficient_scope");
+  });
+
+  test("a 200 with no token becomes a MintError (never returns a credential-less success)", async () => {
+    const hub = fakeHub(() => ({ status: 200, json: { jti: "j", expires_at: "" } }));
+    await expect(mintScopedToken({ scope: "agent:read" }, depsWith(hub.fetchFn))).rejects.toBeInstanceOf(MintError);
+  });
+
+  test("a network failure to reach the hub becomes a MintError (status 0)", async () => {
+    const fetchFn = (async () => {
+      throw new Error("ECONNREFUSED");
+    }) as unknown as typeof fetch;
+    let err: unknown;
+    try {
+      await mintScopedToken({ scope: "agent:read" }, depsWith(fetchFn));
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeInstanceOf(MintError);
+    expect((err as MintError).status).toBe(0);
+  });
+});

package/src/mint-token.ts

@@ -0,0 +1,139 @@
+/**
+ * Scoped-token minting for a sandboxed agent session (design §4.2 step 1, §4.3).
+ *
+ * A hub-issued JWT's `aud` is single-valued, so each resource an arm reaches gets
+ * its OWN token: `agent:read agent:write` per channel, `vault:<name>:<verb>`
+ * (optionally tag-scoped via `permissions.scoped_tags`) for the vault. The
+ * spawn-manager mints these by attenuating its own grant — it presents its OWN
+ * operator bearer to the hub's `POST /api/auth/mint-token`, which enforces
+ * capability attenuation server-side (`parachute-hub/src/api-mint-token.ts`,
+ * `canGrant`): the manager CANNOT mint a child token exceeding its own authority.
+ * A `vault:default:read` manager bearer cannot mint a child `vault:default:write`
+ * — the hub returns 400 `invalid_scope` (§4.3). This module is the client of that
+ * server-enforced bound; the bound itself lives in the hub.
+ *
+ * One token per `aud`: a multi-resource spec calls this once per resource, each
+ * with the resource's scope (and the hub infers `aud` from the scope, or the
+ * caller pins it). Tokens are ephemeral by default for one-shot helpers; the TTL
+ * is the hub's default unless overridden.
+ */
+
+export interface MintRequest {
+  /** Space-joined scope string, e.g. "agent:read agent:write". */
+  scope: string;
+  /** Pin the audience. Omitted = hub infers it from the scope. */
+  audience?: string;
+  /** TTL in seconds. Omitted = hub default (~90d non-ephemeral). */
+  expiresIn?: number;
+  /**
+   * Extra JWT claims, e.g. `{ scoped_tags: ["#agent/message"] }` for a
+   * tag-scoped vault token. Passed through as the mint API's `permissions`.
+   */
+  permissions?: Record<string, unknown>;
+}
+
+export interface MintResult {
+  jti: string;
+  token: string;
+  expiresAt: string;
+  scope: string;
+  permissions?: Record<string, unknown>;
+}
+
+/** A failed mint — carries the hub's error code + the HTTP status. */
+export class MintError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    readonly code: string | undefined,
+  ) {
+    super(message);
+    this.name = "MintError";
+  }
+}
+
+export interface MintTokenDeps {
+  /** Hub public origin. */
+  hubOrigin: string;
+  /**
+   * The spawn-manager's OWN operator bearer, presented to the hub. The hub
+   * attenuates against THIS bearer's authority — child tokens can never exceed it.
+   */
+  managerBearer: string;
+  /** Inject fetch for tests. Defaults to global fetch. */
+  fetchFn?: typeof fetch;
+}
+
+function stripTrailingSlash(url: string): string {
+  return url.replace(/\/$/, "");
+}
+
+/**
+ * Mint ONE scoped token against the hub, attenuated to the manager's bearer.
+ * Throws {@link MintError} on any non-200 (the hub's attenuation 400, an auth
+ * 401/403, etc.) so the caller fails loud rather than launching a session with a
+ * missing/over-broad credential.
+ */
+export async function mintScopedToken(
+  req: MintRequest,
+  deps: MintTokenDeps,
+): Promise<MintResult> {
+  const fetchFn = deps.fetchFn ?? fetch;
+  const url = `${stripTrailingSlash(deps.hubOrigin)}/api/auth/mint-token`;
+
+  const body: Record<string, unknown> = { scope: req.scope };
+  if (req.audience) body.audience = req.audience;
+  if (req.expiresIn !== undefined) body.expires_in = req.expiresIn;
+  if (req.permissions) body.permissions = req.permissions;
+
+  let res: Response;
+  try {
+    res = await fetchFn(url, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${deps.managerBearer}`,
+      },
+      body: JSON.stringify(body),
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new MintError(`mint request failed to reach hub: ${msg}`, 0, undefined);
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = await res.json();
+  } catch {
+    parsed = undefined;
+  }
+
+  if (!res.ok) {
+    const e = (parsed ?? {}) as { error?: string; error_description?: string; message?: string };
+    const code = e.error;
+    const detail = e.error_description ?? e.message ?? `HTTP ${res.status}`;
+    throw new MintError(`mint refused (${code ?? "error"}): ${detail}`, res.status, code);
+  }
+
+  const r = (parsed ?? {}) as Partial<MintResult> & { expires_at?: string };
+  if (typeof r.token !== "string" || r.token.length === 0) {
+    throw new MintError("mint succeeded but response had no token", res.status, undefined);
+  }
+  return {
+    jti: typeof r.jti === "string" ? r.jti : "",
+    token: r.token,
+    expiresAt: typeof r.expires_at === "string" ? r.expires_at : "",
+    scope: typeof r.scope === "string" ? r.scope : req.scope,
+    ...(r.permissions ? { permissions: r.permissions } : {}),
+  };
+}
+
+/** Build the space-joined agent scope string for a read[+write] grant. */
+export function agentScope(opts: { write: boolean }): string {
+  return opts.write ? "agent:read agent:write" : "agent:read";
+}
+
+/** Build the vault scope string for a named verb, e.g. `vault:default:read`. */
+export function vaultScope(name: string, verb: "read" | "write" | "admin"): string {
+  return `vault:${name}:${verb}`;
+}

package/src/module-manifest.test.ts

@@ -0,0 +1,158 @@
+/**
+ * `.parachute/module.json` manifest contract tests.
+ *
+ * Moved out of the (now-deleted) admin-ui.test.ts in Phase 4c — the admin PAGE
+ * retired into the SPA, but the manifest declarations it validated (modular-UI
+ * fields, channel events, vault-trigger actions, connectionTemplates, the
+ * existing name/port/scopes contract) are still load-bearing for the hub.
+ */
+import { describe, expect, test } from "bun:test";
+import { join } from "node:path";
+
+describe("module.json — modular-UI declaration", () => {
+  // The manifest sits at <repo>/.parachute/module.json; this test file is in
+  // <repo>/src, so go up one.
+  const manifestPath = join(import.meta.dir, "..", ".parachute", "module.json");
+
+  test("parses as JSON and carries the modular-UI fields (SPA mount after Phase 4c)", async () => {
+    const raw = await Bun.file(manifestPath).text();
+    const m = JSON.parse(raw) as Record<string, unknown>;
+    // Phase 4c retired the server-rendered config page; configUiUrl now points
+    // at the SPA app mount the hub frames.
+    expect(m.configUiUrl).toBe("/agent/app/");
+    expect(m.focus).toBe("experimental");
+    expect(m.adminCapabilities).toEqual(["config"]);
+  });
+
+  test("declares the channel events (message.received / message.sent)", async () => {
+    const m = JSON.parse(await Bun.file(manifestPath).text()) as {
+      events?: Array<{ key: string; title: string }>;
+    };
+    const keys = (m.events ?? []).map((e) => e.key);
+    expect(keys).toContain("message.received");
+    expect(keys).toContain("message.sent");
+    for (const e of m.events ?? []) expect(typeof e.title).toBe("string");
+  });
+
+  test("declares the message.deliver action with a vault-trigger provision", async () => {
+    const m = JSON.parse(await Bun.file(manifestPath).text()) as {
+      actions?: Array<{ key: string; title: string; provision?: { type?: string } }>;
+    };
+    const deliver = (m.actions ?? []).find((a) => a.key === "message.deliver");
+    expect(deliver).toBeDefined();
+    expect(deliver?.provision?.type).toBe("vault-trigger");
+  });
+
+  test("message.deliver declares the hub-connection wiring (endpoint + scope)", async () => {
+    // The hub's general Connections engine (P5) wires a `vault-trigger` action
+    // GENERICALLY: the webhook the vault calls back on is derived from the sink
+    // action's `endpoint` (hub-proxied under the module's mount), and the bearer
+    // the vault re-presents is minted at the action's declared `scope` — NOT a
+    // channel-hardcoded path in hub code. So the deliver action must carry both.
+    const m = JSON.parse(await Bun.file(manifestPath).text()) as {
+      actions?: Array<{ key: string; endpoint?: string; scope?: string }>;
+    };
+    const deliver = (m.actions ?? []).find((a) => a.key === "message.deliver");
+    expect(deliver?.endpoint).toBe("/api/vault/inbound");
+    expect(deliver?.scope).toBe("agent:send");
+  });
+
+  test("declares a connectionTemplate for the parameterized link-to-vault connection (R2)", async () => {
+    const m = JSON.parse(await Bun.file(manifestPath).text()) as {
+      connectionTemplates?: Array<{
+        key: string;
+        requestedBy?: string;
+        source?: { module?: string; event?: string; filter?: { tags?: string[] } };
+        sink?: { module?: string; action?: string };
+        parameters?: Array<{ key: string; target: string }>;
+      }>;
+    };
+    const tmpl = (m.connectionTemplates ?? []).find((t) => t.key === "link-to-vault");
+    expect(tmpl).toBeDefined();
+    // The module declares WHAT it wants: vault.note.created (inbound tag) →
+    // agent.message.deliver, labeled module-initiated.
+    expect(tmpl?.requestedBy).toBe("agent");
+    expect(tmpl?.source?.module).toBe("vault");
+    expect(tmpl?.source?.event).toBe("note.created");
+    expect(tmpl?.source?.filter?.tags).toContain("#agent/message/inbound");
+    expect(tmpl?.sink?.module).toBe("agent");
+    expect(tmpl?.sink?.action).toBe("message.deliver");
+    // It's PARAMETERIZED — the operator picks the vault + names the channel.
+    const paramKeys = (tmpl?.parameters ?? []).map((p) => p.key);
+    expect(paramKeys).toContain("vault");
+    expect(paramKeys).toContain("channel");
+    // The parameters point at the connection-body targets the UI fills in.
+    const vaultParam = (tmpl?.parameters ?? []).find((p) => p.key === "vault");
+    expect(vaultParam?.target).toBe("source.vault");
+    const channelParam = (tmpl?.parameters ?? []).find((p) => p.key === "channel");
+    expect(channelParam?.target).toBe("sink.params.channel");
+  });
+
+  test("declares the definition.reload action with a vault-trigger provision (Connector 1)", async () => {
+    // Make a vault #agent/definition change flow LIVE into the registry: the
+    // hub provisions a vault trigger that webhooks /api/vault/agent-def with an
+    // agent:send bearer, and the daemon re-reads + re-instantiates that one def.
+    const m = JSON.parse(await Bun.file(manifestPath).text()) as {
+      actions?: Array<{ key: string; provision?: { type?: string }; endpoint?: string; scope?: string }>;
+    };
+    const reload = (m.actions ?? []).find((a) => a.key === "definition.reload");
+    expect(reload).toBeDefined();
+    expect(reload?.provision?.type).toBe("vault-trigger");
+    // Wiring mirrors message.deliver: the webhook endpoint the daemon already
+    // serves, and the agent:send scope that endpoint gates on (daemon.ts).
+    expect(reload?.endpoint).toBe("/api/vault/agent-def");
+    expect(reload?.scope).toBe("agent:send");
+  });
+
+  test("declares TWO def-reload templates (created + updated) — the hub binds one event per connection", async () => {
+    // A connection carries a single `source.event` (admin-connections.ts:
+    // eventsForSourceEvent maps one note.<verb> → one trigger verb), so create
+    // and edit reactivity are two connections / two templates. note.deleted is
+    // deliberately ABSENT — the hub rejects it (Connector 2, platform-blocked).
+    const m = JSON.parse(await Bun.file(manifestPath).text()) as {
+      connectionTemplates?: Array<{
+        key: string;
+        requestedBy?: string;
+        source?: { module?: string; event?: string; filter?: { tags?: string[] } };
+        sink?: { module?: string; action?: string };
+        parameters?: Array<{ key: string; target: string }>;
+      }>;
+    };
+    const templates = m.connectionTemplates ?? [];
+    const onCreate = templates.find((t) => t.key === "reload-defs-on-create");
+    const onEdit = templates.find((t) => t.key === "reload-defs-on-edit");
+    expect(onCreate).toBeDefined();
+    expect(onEdit).toBeDefined();
+
+    for (const tmpl of [onCreate, onEdit]) {
+      expect(tmpl?.requestedBy).toBe("agent");
+      expect(tmpl?.source?.module).toBe("vault");
+      // Filters on the def tag — and ONLY that tag (no inbound-message keys).
+      expect(tmpl?.source?.filter?.tags).toEqual(["#agent/definition"]);
+      expect(tmpl?.sink?.module).toBe("agent");
+      expect(tmpl?.sink?.action).toBe("definition.reload");
+      // Parameterized: the operator picks which def-vault. No channel param
+      // (a def-vault connection has no reply path — it's read-driven reload).
+      const paramKeys = (tmpl?.parameters ?? []).map((p) => p.key);
+      expect(paramKeys).toEqual(["vault"]);
+      const vaultParam = (tmpl?.parameters ?? []).find((p) => p.key === "vault");
+      expect(vaultParam?.target).toBe("source.vault");
+    }
+
+    // The two halves differ ONLY in the source event.
+    expect(onCreate?.source?.event).toBe("note.created");
+    expect(onEdit?.source?.event).toBe("note.updated");
+    // No template subscribes deleted (would 400 at the hub).
+    expect(templates.some((t) => t.source?.event === "note.deleted")).toBe(false);
+  });
+
+  test("preserves the existing manifest contract (name, port, uiUrl, scopes)", async () => {
+    const m = JSON.parse(await Bun.file(manifestPath).text()) as Record<string, unknown>;
+    expect(m.name).toBe("agent");
+    expect(m.port).toBe(1941);
+    // Phase 4c: uiUrl points at the SPA app root (the retired /home page is gone).
+    expect(m.uiUrl).toBe("/agent/app/");
+    const scopes = m.scopes as { defines?: string[] } | undefined;
+    expect(scopes?.defines).toContain("agent:admin");
+  });
+});

package/src/oauth-discovery.ts

@@ -0,0 +1,134 @@
+/**
+ * OAuth discovery endpoints for parachute-agent's HTTP MCP surface — the
+ * *resource server* side of the authorization story.
+ *
+ * Mirrors `parachute-vault/src/oauth-discovery.ts` exactly. The agent is a
+ * resource server, not an authorization server: the hub is the OAuth issuer
+ * (see the hub-as-portal-oauth design doc). These endpoints advertise that
+ * contract to clients per RFC 9728 + RFC 8414 so a Claude Code HTTP-MCP client
+ * adding the agent by URL can auto-discover the hub and run the OAuth flow —
+ * the same way it discovers a vault.
+ *
+ *   - `handleProtectedResource` — RFC 9728: "this is the protected resource at
+ *     `<channel>/mcp/<channel>`; the authorization server lives at <hub>".
+ *   - `handleAuthorizationServer` — RFC 8414: "go to <hub>/oauth/* for the
+ *     authorization endpoints" (forwarded shape — issuer + every endpoint name
+ *     the hub).
+ *
+ * The agent resource lives at `/mcp/<channel>` on the daemon, externally
+ * `<hub>/agent/mcp/<channel>` (hub's stripPrefix removes `/agent`). The
+ * metadata `resource` value is built from the request's forwarded host so the
+ * advertised URL is the public one, not loopback.
+ *
+ * `PARACHUTE_HUB_ORIGIN` (via `getHubOrigin()`) is required for these endpoints
+ * to advertise the right issuer URL — the hub stamps that origin as the token
+ * `iss`. The loopback fallback is for a co-located, never-exposed dev daemon.
+ */
+
+import { getHubOrigin } from "./hub-jwt.ts";
+import { SCOPE_READ, SCOPE_WRITE } from "./auth.ts";
+
+/**
+ * OAuth scopes the agent publishes through discovery. These are the agent
+ * session scopes: a session needs `agent:read` to connect + receive the wake,
+ * and `agent:write` to send (reply/react/edit). A spec-following MCP client
+ * reads `scopes_supported` from this PRM and requests exactly these scopes.
+ */
+function scopesSupported(): string[] {
+  return [SCOPE_READ, SCOPE_WRITE];
+}
+
+/**
+ * Public-facing base URL of the daemon. Honors `x-forwarded-*` headers so a
+ * Cloudflare Tunnel / Tailscale Funnel / reverse-proxied (hub) deployment
+ * advertises the right external origin in the `resource` URL. Mirrors vault's
+ * `getBaseUrl`.
+ *
+ * Exported so the daemon can build a `WWW-Authenticate` challenge header that
+ * points at the same origin as the `/.well-known/*` metadata documents.
+ */
+export function getBaseUrl(req: Request): string {
+  const forwardedHost = req.headers.get("x-forwarded-host");
+  const forwardedProto = req.headers.get("x-forwarded-proto");
+  if (forwardedHost) {
+    return `${forwardedProto || "https"}://${forwardedHost}`;
+  }
+  const url = new URL(req.url);
+  return url.origin;
+}
+
+/**
+ * The mount prefix the module sits under when served through the hub expose.
+ * Hub reverse-proxies `<expose>/agent/*` → the loopback daemon with
+ * `stripPrefix:true`, so the daemon itself never sees `/agent`. But the
+ * PUBLIC resource URL a client must address is `<hub>/agent/mcp/<channel>`.
+ *
+ * When the request carries `x-forwarded-host` (i.e. it came through the hub),
+ * the public URL needs the `/agent` prefix re-added; a direct loopback
+ * request (no forwarded host) addresses `/mcp/<channel>` with no prefix. We key
+ * off the forwarded-host presence to decide.
+ */
+function mountPrefix(req: Request): string {
+  return req.headers.get("x-forwarded-host") ? "/agent" : "";
+}
+
+/**
+ * OAuth 2.0 Protected Resource Metadata (RFC 9728).
+ *
+ * Advertises the agent's `/mcp/<channel>` endpoint as the protected resource
+ * and names the hub as the authorization server. Clients following the spec
+ * fetch this, then fetch the AS metadata at
+ * `<hub>/.well-known/oauth-authorization-server` to drive the full flow.
+ */
+export function handleProtectedResource(req: Request, channel: string): Response {
+  const base = getBaseUrl(req);
+  const prefix = mountPrefix(req);
+  return Response.json({
+    resource: `${base}${prefix}/mcp/${channel}`,
+    authorization_servers: [getHubOrigin()],
+    scopes_supported: scopesSupported(),
+    bearer_methods_supported: ["header"],
+  });
+}
+
+/**
+ * OAuth 2.0 Authorization Server Metadata (RFC 8414).
+ *
+ * The agent is a resource server, not an authorization server — but we serve
+ * this document as a *forwarding* metadata document: issuer + every endpoint
+ * name the hub. Clients that follow the PRM pointer land here and discover the
+ * hub's actual endpoints; conformant clients that probe AS metadata directly at
+ * the agent path get the same answer. Mirrors vault.
+ */
+export function handleAuthorizationServer(_req: Request, _channel: string): Response {
+  const hub = getHubOrigin();
+  return Response.json({
+    issuer: hub,
+    authorization_endpoint: `${hub}/oauth/authorize`,
+    token_endpoint: `${hub}/oauth/token`,
+    registration_endpoint: `${hub}/oauth/register`,
+    jwks_uri: `${hub}/.well-known/jwks.json`,
+    response_types_supported: ["code"],
+    code_challenge_methods_supported: ["S256"],
+    grant_types_supported: ["authorization_code", "refresh_token"],
+    token_endpoint_auth_methods_supported: ["none", "client_secret_post"],
+    scopes_supported: scopesSupported(),
+  });
+}
+
+/**
+ * RFC 9728 `WWW-Authenticate` challenge value pointing at the protected-resource
+ * metadata document for `channel`. When a Claude Code HTTP-MCP client hits
+ * `/mcp/<channel>` with no/invalid bearer and gets a 401 carrying this header,
+ * it knows where to fetch the OAuth discovery metadata and start the flow.
+ *
+ * The advertised metadata URL uses the path-insertion form Claude Code probes
+ * (`/.well-known/oauth-protected-resource/mcp/<channel>`) so the client's first
+ * fetch off this header lands on a route the daemon actually serves. Built from
+ * the same `getBaseUrl` as the metadata document so the origins match.
+ */
+export function mcpWwwAuthenticate(req: Request, channel: string): string {
+  const base = getBaseUrl(req);
+  const prefix = mountPrefix(req);
+  return `Bearer resource_metadata="${base}${prefix}/.well-known/oauth-protected-resource/mcp/${channel}"`;
+}