@openparachute/hub 0.7.1 → 0.7.2

package/src/admin-agent-token.ts

@@ -0,0 +1,147 @@
+/**
+ * `GET /admin/agent-token` — exchange a valid admin session cookie for a
+ * short-lived JWT carrying `agent:read agent:send agent:admin`.
+ *
+ * Renamed from `/admin/channel-token` 2026-06-17 (parachute-channel →
+ * parachute-agent). The old path keeps working via a 301 redirect in
+ * hub-server.ts for one release cycle.
+ *
+ * Why this exists: two agent-owned UIs, both served behind hub's proxy to a
+ * logged-in portal operator, need a Bearer to talk to agent's API the same
+ * way the vault-management and scribe-config SPAs do, without running the
+ * public `/oauth/authorize` flow:
+ *   - The **chat UI** (`/agent/ui`) receives replies over SSE
+ *     (`agent:read`) and posts a message (`agent:send`).
+ *   - The **config/admin UI** (`/agent/admin`, the 2026-06-09 modular-UI
+ *     architecture P3/P4 config surface) lists + edits configured channels via
+ *     `agent:admin`-gated endpoints (`requireScope(SCOPE_ADMIN)` in agent's
+ *     daemon).
+ *
+ * Both UIs fetch this single endpoint (`fetchToken()` against
+ * `/admin/agent-token`), so the minted token carries the union of the scopes
+ * either UI needs. The chat UI simply ignores the extra `agent:admin` scope;
+ * `requireScope` checks for the *presence* of a specific scope, so extra
+ * scopes never break a read/send call. This is what makes the agent config
+ * UI work without re-touching the agent repo — the hub endpoint the config
+ * UI already calls now mints the admin scope it needs (2026-06-09 modular-UI
+ * architecture, P3).
+ *
+ * Scope choice — `agent:read agent:send agent:admin`, deliberately NOT
+ * `agent:write`:
+ *   - `agent:read`  — receive replies over SSE.
+ *   - `agent:send`  — post a message into the channel.
+ *   - `agent:admin` — list + edit channel config (the config UI).
+ *   - `agent:write` is the *session-reply* scope (a connected Claude Code
+ *     session replying on a channel). A UI token must not be able to
+ *     impersonate a session, so we never mint `agent:write` here.
+ *
+ * Audience: `agent` (the bare service prefix). Agent validates the JWT's
+ * `aud` claim against the literal string `"agent"` (parachute-agent
+ * `src/hub-jwt.ts`), the same shape `inferAudience` in oauth-handlers.ts
+ * stamps for the public OAuth flow — so hub-minted and OAuth-minted agent
+ * tokens are indistinguishable to agent. Unlike the per-vault admin token
+ * (`vault.<name>`), agent has a single bare audience. (During the rename
+ * transition window the agent daemon dual-accepts both `aud: "channel"` and
+ * `aud: "agent"`, so pre-rename tokens keep validating until re-minted — see
+ * the channel→agent migration doc; that back-compat lives in the daemon, not
+ * here.)
+ *
+ * Multi-user Phase 1 gate: the session must belong to the first admin (the
+ * single hub admin under the Phase 1 model — see `users.ts:isFirstAdmin`),
+ * mirroring host-admin-token and vault-admin-token. Friends pinned to a vault
+ * use the OAuth flow for their assigned scopes; they don't get an agent
+ * Bearer via this endpoint.
+ *
+ * Tokens minted here are short-lived (10 min — matches host/vault admin
+ * tokens); the UI re-fetches on near-expiry.
+ */
+import type { Database } from "bun:sqlite";
+import { lockedResponse, requireUnlocked } from "./admin-lock.ts";
+import { signAccessToken } from "./jwt-sign.ts";
+import { findSession, parseSessionCookie } from "./sessions.ts";
+import { isFirstAdmin } from "./users.ts";
+
+/** Short TTL — matches host/vault admin-token. UI re-fetches on near-expiry. */
+export const AGENT_TOKEN_TTL_SECONDS = 10 * 60;
+const AGENT_AUDIENCE = "agent";
+const AGENT_CLIENT_ID = "parachute-hub-spa";
+/**
+ * `agent:read` (SSE replies) + `agent:send` (post a message) +
+ * `agent:admin` (list + edit channel config — the config UI). Deliberately
+ * NOT `agent:write` — that's the session-reply scope, and a UI token must
+ * not be able to impersonate a connected session. The chat UI ignores the
+ * extra `agent:admin`; the config UI needs it (2026-06-09 modular-UI
+ * architecture, P3 — the hub endpoint the agent config UI already calls
+ * mints the admin scope so the agent repo doesn't have to change).
+ */
+export const AGENT_TOKEN_SCOPES = ["agent:read", "agent:send", "agent:admin"] as const;
+
+export interface MintAgentTokenDeps {
+  db: Database;
+  /** Hub origin — written into JWT `iss`. */
+  issuer: string;
+}
+
+export async function handleAgentToken(req: Request, deps: MintAgentTokenDeps): Promise<Response> {
+  if (req.method !== "GET") {
+    return jsonError(405, "method_not_allowed", "use GET");
+  }
+  const sid = parseSessionCookie(req.headers.get("cookie"));
+  const session = sid ? findSession(deps.db, sid) : null;
+  if (!session || !sid) {
+    return jsonError(401, "unauthenticated", "no admin session — sign in at /login first");
+  }
+  // First-admin gate (mirrors host/vault-admin-token). A friend account
+  // (non-first-admin user created via `/api/users`) holds a valid session but
+  // must not mint an agent Bearer. Without this check, any signed-in friend
+  // hitting `GET /admin/agent-token` would walk away with a token carrying
+  // `agent:read agent:send`.
+  if (!isFirstAdmin(deps.db, session.userId)) {
+    return jsonError(
+      403,
+      "not_admin",
+      "agent token mint is restricted to the hub admin — your account home is at /account/",
+    );
+  }
+  // Admin screen-lock gate (see admin-host-admin-token.ts). A locked admin
+  // session can't mint an agent Bearer, so agent's config + chat UIs show
+  // the lock screen / fail closed until the operator unlocks. Off by default.
+  if (!requireUnlocked(deps.db, sid).ok) {
+    return lockedResponse();
+  }
+  const minted = await signAccessToken(deps.db, {
+    sub: session.userId,
+    scopes: [...AGENT_TOKEN_SCOPES],
+    audience: AGENT_AUDIENCE,
+    clientId: AGENT_CLIENT_ID,
+    issuer: deps.issuer,
+    ttlSeconds: AGENT_TOKEN_TTL_SECONDS,
+    // Agent tokens carry no per-user vault pin — the UI Bearer talks to an
+    // agent-scoped endpoint, not to a single vault. Empty `vault_scope` is
+    // the "no per-user restriction" sentinel matching host-admin tokens.
+    vaultScope: [],
+  });
+  return new Response(
+    JSON.stringify({
+      token: minted.token,
+      expires_at: minted.expiresAt,
+      scopes: AGENT_TOKEN_SCOPES,
+    }),
+    {
+      status: 200,
+      headers: {
+        "content-type": "application/json",
+        // No browser cache — token rotates per-fetch, and a stale 200 from a
+        // back/forward navigation could hand the UI a long-expired JWT.
+        "cache-control": "no-store",
+      },
+    },
+  );
+}
+
+function jsonError(status: number, error: string, description: string): Response {
+  return new Response(JSON.stringify({ error, error_description: description }), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}

package/src/admin-connections.ts

@@ -4,7 +4,7 @@
  * architecture, P5). Generalizes the channel-specific `/admin/channels`
  * endpoint (hub#624 era; retired in boundary D1): "add a vault-backed channel"
  * is just the first connection, `vault.note.created (filter
- * #channel-message/inbound) → channel.message.deliver`.
+ * #agent-message/inbound) → agent.message.deliver`.
  *
  * THE CONCEPT. A connection wires "when [EVENT] in [source module] (filter) →
  * do [ACTION] in [sink module]". The sink is ALWAYS an action. Modules declare
@@ -17,7 +17,7 @@
  *   - the SINK action's `endpoint` → the hub-proxied webhook the vault calls
  *     (`<hub-origin>/<sink-mount><endpoint>`). NOT a hardcoded channel path.
  *   - the SINK action's `scope` → the OAuth scope minted into the webhook's
- *     `Authorization: Bearer`. NOT a hardcoded `channel:send`.
+ *     `Authorization: Bearer`. NOT a hardcoded `agent:send`.
  *   - the SOURCE event key → the vault trigger's `events` (`note.created` →
  *     `["created"]`, `note.updated` → `["updated"]`).
  *   - the SOURCE filter → the vault trigger's `when` predicate (`tags` /
@@ -27,9 +27,9 @@
  *
  * THE ONE SINK-SPECIFIC PREREQUISITE. A vault-backed channel additionally needs
  * its reply path wired: a `vault:<v>:write` token + a `channels.json` entry so
- * the session can reply. That's a property of the channel SINK, not of the
- * engine — it runs only for `sink.module === "channel"` and is clearly fenced
- * (`prepareChannelSink`). Everything else is declaration-driven.
+ * the session can reply. That's a property of the agent SINK, not of the
+ * engine — it runs only for `sink.module === "agent"` and is clearly fenced
+ * (`prepareAgentSink`). Everything else is declaration-driven.
  *
  * AUTH. Same gate as the admin-token mints: a cookie-gated operator session
  * pinned to the first admin. The catalog (`/api/connections/catalog`) is
@@ -137,7 +137,7 @@ export interface InstalledModuleInfo {
   /** Parsed `.parachute/module.json`. */
   readonly manifest: ModuleManifest;
   /**
-   * The module's user-facing mount path under the hub origin (e.g. `/channel`),
+   * The module's user-facing mount path under the hub origin (e.g. `/agent`),
    * used to build a hub-proxied webhook from a sink action's `endpoint`.
    * `null` when the module declares no user-facing mount.
    */
@@ -169,8 +169,8 @@ export interface ConnectionsDeps {
    * teardown logs the skipped notification.
    */
   resolveModuleOrigin?: (short: string) => string | null;
-  /** Loopback origin for the channel daemon, or `null` when not installed. */
-  channelOrigin: string | null;
+  /** Loopback origin for the agent daemon, or `null` when not installed. */
+  agentOrigin: string | null;
   /** Absolute path to `connections.json` in the hub state dir. */
   storePath: string;
   /** Test seam — `globalThis.fetch` in production. */
@@ -452,7 +452,7 @@ interface CreateBody {
   /**
    * Provenance — WHO requested this connection (modular-UI R2). A module-owned
    * config UI calling this endpoint on the operator's behalf labels itself (e.g.
-   * `"channel"`); the hub's own builder omits it and falls back to `"custom"`.
+   * `"agent"`); the hub's own builder omits it and falls back to `"custom"`.
    */
   requestedBy?: unknown;
 }
@@ -601,20 +601,28 @@ async function createConnection(
   // the record so teardown can revoke them (registered-mint rule).
   const mintedJtis: string[] = [];
 
-  // --- Sink prerequisite (channel reply path), fenced to the channel sink. --
+  // --- Sink prerequisite (agent message-delivery reply path). --------------
   // Everything below this is general; THIS block is the only sink-specific step.
-  // The channel name comes from the action params (`sink.params.channel`) — it
-  // becomes a services.json key + an MCP server name, so it must be a slug.
-  if (sinkModule === "channel") {
+  // It is gated on the ACTION, not just the module: ONLY `message.deliver` needs
+  // a session reply path (a vault-backed channel's connected session replies via
+  // a `vault:<v>:write` token + a `channels.json` entry). Other agent actions —
+  // e.g. `definition.reload`, a pure inbound webhook with no session and no
+  // reply — need none of it. A module-level gate here 400'd every
+  // non-`message.deliver` agent sink for want of a `channel` param (agent#117:
+  // the def-reload connectors could never provision). The channel name comes
+  // from `sink.params.channel` — it becomes a services.json key + an MCP server
+  // name, so it must be a slug. (The session-channel concept is kept; only the
+  // MODULE renamed channel → agent in the 2026-06-17 rename.)
+  if (sinkModule === "agent" && sinkAction === "message.deliver") {
     const channelName = typeof sinkParams?.channel === "string" ? sinkParams.channel : "";
     if (!CHANNEL_NAME_RE.test(channelName)) {
       return jsonError(
         400,
         "invalid_request",
-        `channel sink requires sink.params.channel as a valid identifier; got "${channelName}"`,
+        `agent sink requires sink.params.channel as a valid identifier; got "${channelName}"`,
       );
     }
-    const prep = await prepareChannelSink(channelName, vault, vaultOrigin, userId, deps);
+    const prep = await prepareAgentSink(channelName, vault, vaultOrigin, userId, deps);
     if (prep.error) return prep.error;
     mintedJtis.push(prep.replyTokenJti);
   }
@@ -681,35 +689,33 @@ async function createConnection(
     connection: typeof record;
     connect?: { mcpAdd: string; launch: string };
   } = { ok: true, connection: record };
-  if (sinkModule === "channel" && typeof sinkParams?.channel === "string") {
+  if (sinkModule === "agent" && typeof sinkParams?.channel === "string") {
     out.connect = channelConnectLines(deps.hubOrigin, sinkParams.channel);
   }
   return json(200, out);
 }
 
 /**
- * The channel sink's reply-path prerequisite (mirrors hub#624). Mints a
+ * The agent sink's reply-path prerequisite (mirrors hub#624). Mints a
  * `vault:<v>:write` for the channel + writes the `channels.json` entry on the
- * channel daemon so the session can reply. Fenced to `sink.module === "channel"`
- * — this is sink-specific config, not part of the general vault-trigger engine.
+ * agent daemon so the session can reply. Fenced to the agent `message.deliver`
+ * action (the only one with a reply path) — sink-specific config, not part of
+ * the general vault-trigger engine.
  * Returns `{ error }` on failure, or `{ error: null, replyTokenJti }` on
  * success — the jti of the long-lived reply token, so the caller can persist
- * it for teardown revocation.
+ * it for teardown revocation. (Renamed from `prepareChannelSink` 2026-06-17;
+ * the agent daemon's session-channel CRUD is still `/api/channels`.)
  */
-async function prepareChannelSink(
+async function prepareAgentSink(
   channelName: string,
   vault: string,
   vaultOrigin: string,
   userId: string,
   deps: ConnectionsDeps,
 ): Promise<{ error: Response } | { error: null; replyTokenJti: string }> {
-  if (deps.channelOrigin === null) {
+  if (deps.agentOrigin === null) {
     return {
-      error: jsonError(
-        503,
-        "channel_unavailable",
-        "the channel module is not installed on this hub",
-      ),
+      error: jsonError(503, "agent_unavailable", "the agent module is not installed on this hub"),
     };
   }
   const fetchImpl = deps.fetchImpl ?? fetch;
@@ -718,17 +724,17 @@ async function prepareChannelSink(
       scopes: [`vault:${vault}:write`],
       audience: `vault.${vault}`,
       vaultScope: [vault],
-      ttlSeconds: WEBHOOK_BEARER_TTL_SECONDS, // channel keeps it for its lifetime
+      ttlSeconds: WEBHOOK_BEARER_TTL_SECONDS, // agent keeps it for its lifetime
     });
     const channelAdminToken = (
       await mint(deps, userId, {
-        scopes: ["channel:admin"],
-        audience: "channel",
+        scopes: ["agent:admin"],
+        audience: "agent",
         vaultScope: [],
         ttlSeconds: PROVISION_TOKEN_TTL_SECONDS,
       })
     ).token;
-    const res = await fetchImpl(`${deps.channelOrigin}/api/channels`, {
+    const res = await fetchImpl(`${deps.agentOrigin}/api/channels`, {
       method: "POST",
       headers: {
         authorization: `Bearer ${channelAdminToken}`,
@@ -740,10 +746,10 @@ async function prepareChannelSink(
         config: { vault, vaultUrl: vaultOrigin, token: vaultWriteSigned.token },
       }),
     });
-    if (!res.ok) return { error: stepError("channel_config", await describeRemote(res)) };
+    if (!res.ok) return { error: stepError("agent_config", await describeRemote(res)) };
     return { error: null, replyTokenJti: vaultWriteSigned.jti };
   } catch (err) {
-    return { error: stepError("channel_config", err) };
+    return { error: stepError("agent_config", err) };
   }
 }
 
@@ -1538,37 +1544,48 @@ export async function teardownConnection(
     }
   }
 
-  // --- Channel-sink teardown (remove the channel config entry). ------------
-  // Fenced to event→action records: a credential connection whose HOLDER is
-  // the channel module must not delete an unrelated channel config entry.
-  if (record.kind !== "credential" && record.sink.module === "channel" && deps.channelOrigin) {
+  // --- Agent-sink teardown (remove the channel config entry). --------------
+  // Fenced to event→action records (a credential connection whose HOLDER is the
+  // agent module must not delete an unrelated channel config entry) AND — like
+  // the create-side prerequisite — to the `message.deliver` action: only that
+  // action created a channel config entry, so only it has one to remove. A
+  // module-level gate here would issue a spurious DELETE /api/channels/<id> for
+  // a channel-less action (e.g. definition.reload — `record.id` as the channel
+  // fallback), wasting an agent:admin mint on a never-created channel and
+  // risking a real same-named channel. Symmetric to the create-side gate.
+  if (
+    record.kind !== "credential" &&
+    record.sink.module === "agent" &&
+    record.sink.action === "message.deliver" &&
+    deps.agentOrigin
+  ) {
     const channelName =
       typeof record.sink.params?.channel === "string" ? record.sink.params.channel : record.id;
     try {
       const channelAdminToken = (
         await mint(deps, userId, {
-          scopes: ["channel:admin"],
-          audience: "channel",
+          scopes: ["agent:admin"],
+          audience: "agent",
           vaultScope: [],
           ttlSeconds: PROVISION_TOKEN_TTL_SECONDS,
         })
       ).token;
       const res = await fetchImpl(
-        `${deps.channelOrigin}/api/channels/${encodeURIComponent(channelName)}`,
+        `${deps.agentOrigin}/api/channels/${encodeURIComponent(channelName)}`,
         { method: "DELETE", headers: { authorization: `Bearer ${channelAdminToken}` } },
       );
       if (!res.ok && res.status !== 404) {
-        errors.push({ step: "channel_config", detail: await remoteDetail(res) });
+        errors.push({ step: "agent_config", detail: await remoteDetail(res) });
       }
     } catch (err) {
-      errors.push({ step: "channel_config", detail: errMsg(err) });
+      errors.push({ step: "agent_config", detail: errMsg(err) });
     }
   }
 
   // --- Revoke the registered long-lived mints (B0, registered-mint rule). ---
   // Marks each tokens-registry row revoked → the revocation list at
   // `/.well-known/parachute-revocation.json` advertises the jtis, and every
-  // resource server (vault, channel) rejects the credential from its next
+  // resource server (vault, agent) rejects the credential from its next
   // poll. Runs regardless of remote-teardown outcome — revocation is the safe
   // direction. Legacy records (provisioned before B0) carry no jtis: teardown
   // proceeds, but their tokens were never registered and ride to expiry.
@@ -1695,8 +1712,8 @@ function readProvisionType(provision: unknown): string | null {
 
 /**
  * Audience for a minted sink bearer. A `<module>:<verb>` scope (e.g.
- * `channel:send`) takes the module namespace as its audience — matching how
- * the channel validates `aud: channel`. Falls back to the sink module name.
+ * `agent:send`) takes the module namespace as its audience — matching how
+ * the agent validates `aud: agent`. Falls back to the sink module name.
  */
 function audienceForScope(scope: string, sinkModule: string): string {
   const colon = scope.indexOf(":");
@@ -1717,15 +1734,15 @@ function str(v: unknown): string {
 }
 
 /**
- * Derive the connection id. Operator-supplied wins; else for a channel sink use
+ * Derive the connection id. Operator-supplied wins; else for an agent sink use
  * the channel name (so the trigger + channel-config share a stable key), else a
  * `<srcModule>-<event>-<sinkModule>-<action>` slug.
  */
 function deriveId(rawId: unknown, source: ConnectionSource, sink: ConnectionSink): string {
   const supplied = str(rawId);
   if (supplied) return supplied.toLowerCase();
-  if (sink.module === "channel" && typeof sink.params?.channel === "string") {
-    return `channel-${sink.params.channel}`.toLowerCase();
+  if (sink.module === "agent" && typeof sink.params?.channel === "string") {
+    return `agent-${sink.params.channel}`.toLowerCase();
   }
   const slug = `${source.module}-${source.event}-${sink.module}-${sink.action}`
     .toLowerCase()
@@ -1740,8 +1757,8 @@ function channelConnectLines(
 ): { mcpAdd: string; launch: string } {
   const origin = hubOrigin.replace(/\/+$/, "");
   return {
-    mcpAdd: `claude mcp add --transport http --scope user channel-${channelName} ${origin}/channel/mcp/${channelName}`,
-    launch: `claude --dangerously-load-development-channels=server:channel-${channelName} --dangerously-skip-permissions`,
+    mcpAdd: `claude mcp add --transport http --scope user agent-${channelName} ${origin}/agent/mcp/${channelName}`,
+    launch: `claude --dangerously-load-development-channels=server:agent-${channelName} --dangerously-skip-permissions`,
   };
 }
 

package/src/admin-host-admin-token.ts

@@ -47,6 +47,7 @@
  * in line with the admin scope-set semantics from hub#214 / #222.
  */
 import type { Database } from "bun:sqlite";
+import { lockedResponse, requireUnlocked } from "./admin-lock.ts";
 import { signAccessToken } from "./jwt-sign.ts";
 import { findSession, parseSessionCookie } from "./sessions.ts";
 import { isFirstAdmin } from "./users.ts";
@@ -72,7 +73,7 @@ export async function handleHostAdminToken(
   }
   const sid = parseSessionCookie(req.headers.get("cookie"));
   const session = sid ? findSession(deps.db, sid) : null;
-  if (!session) {
+  if (!session || !sid) {
     return jsonError(401, "unauthenticated", "no admin session — sign in at /login first");
   }
   // First-admin gate. A friend account (non-first-admin user created via
@@ -89,6 +90,18 @@ export async function handleHostAdminToken(
       "host-admin token mint is restricted to the hub admin — your account home is at /account/",
     );
   }
+  // Admin screen-lock gate (optional, off by default). When a lock PIN is set
+  // AND this session isn't within an unlock window, refuse to mint — the SPA
+  // shows the lock screen on the 423. No PIN configured → always allowed
+  // (today's behavior). This mint is a PURE CHECK — it does NOT slide the idle
+  // window; sliding is driven only by genuine user activity (the SPA's debounced
+  // `/heartbeat`), so a background re-mint (e.g. the 30s version-badge poll) can't
+  // keep an idle tab unlocked. See the `requireUnlocked` docblock in admin-lock.ts.
+  // The OAuth issuer (`/oauth/*`) never reaches this endpoint, so it's
+  // unaffected by the lock.
+  if (!requireUnlocked(deps.db, sid).ok) {
+    return lockedResponse();
+  }
   const minted = await signAccessToken(deps.db, {
     sub: session.userId,
     scopes: [...HOST_ADMIN_SCOPES],