@openparachute/hub 0.7.1 → 0.7.2-rc.1

package/src/hub-server.ts

@@ -51,7 +51,8 @@
  *                                                 supervisor restart)
  *   /admin/host-admin-token       (GET)        → SPA bearer mint (cookie-gated)
  *   /admin/vault-admin-token/<n>  (GET)        → per-vault bearer mint (cookie-gated)
- *   /admin/channel-token          (GET)        → channel UI bearer mint (cookie-gated)
+ *   /admin/agent-token            (GET)        → agent UI bearer mint (cookie-gated)
+ *   /admin/channel-token          (GET)        → 301 → /admin/agent-token (legacy; channel→agent rename 2026-06-17)
  *   /admin/module-token/<short>   (GET)        → generic module config-UI bearer mint <short>:admin (cookie-gated)
  *   /api/connections/catalog      (GET)        → events/actions across installed modules (cookie-gated)
  *   /admin/connections            (POST/GET)   → connection provision/list (cookie-gated; POST CSRF-belted)
@@ -59,11 +60,18 @@
  *   /admin/connections/<id>/renew (POST)       → credential renewal (H4; Bearer = the credential itself, proof of possession)
  *   /admin/connections/<id>/claim (POST)       → claim/reconcile a directly-delivered credential → pending record (surface#113; Bearer = the credential itself)
  *   /admin/connections/<id>/approve (POST)     → operator approval of a pending claim (cookie-gated; CSRF-belted)
+ *   /admin/grants                 (PUT/GET)    → agent-connector grant upsert/list (4b-1; host-admin Bearer)
+ *   /admin/grants/<id>/material   (GET)        → injectable secret for an APPROVED grant (4b-1; host-admin Bearer)
+ *   /admin/grants/<id>/approve    (POST)       → operator approves a grant — mint (vault) / store (service) / static-bearer-or-start-OAuth (mcp, 4b-2) (cookie-gated; CSRF-belted)
+ *   /admin/grants/<id>/revoke     (POST)       → operator revokes a grant — drop the stored secret + best-effort issuer revoke (mcp, 4b-2) (cookie-gated; CSRF-belted)
+ *   /oauth/agent-grant/callback   (GET)        → OAuth-client redirect target for an mcp grant consent (4b-2; single-use state, no Bearer, NOT same-origin-belted — cross-site redirect in)
  *
  *   # "CSRF-belted" = strict same-origin Origin check on cookie-authed
  *   # mutations (hub#632, boundary C1) — origin-check.ts
  *   # `assertSameOriginForCookieMutation` carries the canonical enumeration.
  *   /api/me                       (GET)        → who-am-I (session+CSRF or hasSession:false)
+ *   /api/admin-lock               (GET)        → screen-lock status (cookie-gated; first-admin)
+ *   /api/admin-lock/{set,change,remove,unlock,lock,heartbeat} (POST) → manage the optional admin idle PIN lock (cookie-gated; CSRF)
  *   /api/hub                      (GET)        → hub version + uptime + install-source (host:admin)
  *   /api/hub/upgrade              (POST)       → SPA-driven hub self-upgrade → 202 + detached helper (host:admin, §5.3/D4)
  *   /api/hub/upgrade/status       (GET)        → poll the on-disk hub-upgrade status (host:admin)
@@ -153,7 +161,12 @@ import pkg from "../package.json" with { type: "json" };
 import { handleAccountSetupGet, handleAccountSetupPost } from "./account-setup.ts";
 import { handleAccountVaultAdminTokenPost } from "./account-vault-admin-token.ts";
 import { handleAccountVaultTokenPost } from "./account-vault-token.ts";
-import { handleChannelToken } from "./admin-channel-token.ts";
+import {
+  type AgentGrantsDeps,
+  handleAgentGrants,
+  handleOAuthGrantCallback,
+} from "./admin-agent-grants.ts";
+import { handleAgentToken } from "./admin-agent-token.ts";
 import { handleApproveClient, handleGetClient } from "./admin-clients.ts";
 import {
   type ConnectionsDeps,
@@ -176,6 +189,7 @@ import {
   handleAccountChangePasswordPost,
   handleAccountHomeGet,
 } from "./api-account.ts";
+import { handleAdminLock } from "./api-admin-lock.ts";
 import { handleHubUpgrade, handleHubUpgradeStatus } from "./api-hub-upgrade.ts";
 import { handleApiHub } from "./api-hub.ts";
 import { handleCreateInvite, handleListInvites, handleRevokeInvite } from "./api-invites.ts";
@@ -458,7 +472,7 @@ function hasVaultInstalled(manifestPath: string): boolean {
  * posture as `/api/modules`.
  *
  * `mount` is the first non-`.parachute` services.json path (the proxied
- * user-facing prefix, e.g. `/channel`), which the engine joins with a sink
+ * user-facing prefix, e.g. `/agent`), which the engine joins with a sink
  * action's `endpoint` to build the hub-proxied webhook.
  */
 async function collectInstalledModules(
@@ -929,7 +943,7 @@ async function proxyToVault(
  * hub-module-boundary migration), NOT a per-instance path.
  *
  * Resolution is via `findServiceByShort(services, "vault")` (the canonical
- * self-registered `parachute-vault` row — same shape as the channelEntry
+ * self-registered `parachute-vault` row — same shape as the agentEntry
  * lookup in the Connections deps), deliberately NOT `findVaultUpstream`:
  * vault must NOT self-register `/vault/admin` in `paths[]`, because every
  * consumer that derives instance names from paths (`vaultInstanceNameFor`,
@@ -1055,7 +1069,8 @@ async function proxyToService(
   }
   // Consult FIRST_PARTY_FALLBACKS / KNOWN_MODULES as a fallback for
   // `stripPrefix` (#196). Pre-hub#310, scribe's `stripPrefix: true` lived
-  // only in hub's vendored fallback; post-#310 scribe (and post-D3 channel)
+  // only in hub's vendored fallback; post-#310 scribe (and post-D3 agent,
+  // renamed from channel 2026-06-17)
   // self-register with `stripPrefix: true` on their rows, so the entry-based
   // path is authoritative. The registry consultation now matters only for
   // notes (the remaining FALLBACK short) and legacy rows written before the
@@ -1077,12 +1092,12 @@ async function proxyToService(
  * Resolve effective `stripPrefix` for a service entry. Explicit on-entry
  * wins; otherwise consult `FIRST_PARTY_FALLBACKS` keyed by short name (for
  * notes — vault/scribe/runner retired their FALLBACK entries in hub#310,
- * channel in boundary D3; all self-register with the canonical `stripPrefix`
- * declaration on their services.json row).
+ * agent (renamed from channel 2026-06-17) in boundary D3; all self-register
+ * with the canonical `stripPrefix` declaration on their services.json row).
  * `KNOWN_MODULES[short]?.canonicalStripPrefix` is the next fallback — covers
  * the edge case where a self-registering module wrote its row before the
  * `stripPrefix` field was being emitted (e.g. pre-scribe#50 or pre-D3
- * channel services.json rows). Defaults to `false` — keep the prefix —
+ * agent services.json rows). Defaults to `false` — keep the prefix —
  * matching the pre-#196 dispatch behavior for unknown / third-party
  * services.
  *
@@ -1148,6 +1163,17 @@ export interface HubFetchDeps {
    * at a tmpdir; production defaults to `<CONFIG_DIR>/connections.json`.
    */
   connectionsStorePath?: string;
+  /**
+   * Path to `agent-grants.json` (the agent-connector grant store, 4b-1). Tests
+   * point this at a tmpdir; production defaults to `<CONFIG_DIR>/agent-grants.json`.
+   */
+  agentGrantsStorePath?: string;
+  /**
+   * Path to `agent-oauth-flows.json` (the in-flight agent-grant OAuth consents,
+   * 4b-2). Tests point this at a tmpdir; production defaults to
+   * `<CONFIG_DIR>/agent-oauth-flows.json`.
+   */
+  agentOAuthFlowsStorePath?: string;
   /**
    * Directory containing the built SPA bundle (`index.html` + `assets/`). When
    * absent, the hub auto-resolves to `<repo>/web/ui/dist/` — handy for the
@@ -2143,6 +2169,27 @@ export function hubFetch(
         }
       }
 
+      // `/channel/*` 301-redirects to `/agent/*` — back-compat for the
+      // 2026-06-17 channel→agent module rename. Operator bookmarks, an
+      // un-upgraded chat/config UI's deep links, and any externally-shared
+      // `/channel/mcp/<name>` URL keep resolving for one release cycle while
+      // the module's canonical mount moves to `/agent`. Method-agnostic, same
+      // shape as the `/notes/*` redirect above (the agent's read-write surface
+      // is its own daemon API, not the hub mount, so a re-issued GET is fine).
+      // Matches `/channel` exactly and any `/channel/...` subpath, but NOT a
+      // longer-prefix module like a hypothetical `/channelthing` — the guard is
+      // exact-or-slash-delimited. Query string is preserved. (The generic
+      // services-proxy fallthrough below would otherwise 404 a `/channel/*`
+      // request once the module self-registers under `/agent`.)
+      if (pathname === "/channel" || pathname.startsWith("/channel/")) {
+        const dest = new URL(req.url);
+        dest.pathname = `/agent${pathname.slice("/channel".length)}`;
+        return new Response("", {
+          status: 301,
+          headers: { location: dest.pathname + dest.search },
+        });
+      }
+
       // CORS preflight for the public OAuth + discovery surface. Browsers
       // issue OPTIONS before any non-simple cross-origin request — third-party
       // SPAs hitting `/oauth/register` (RFC 7591 DCR), `/oauth/token`,
@@ -2314,6 +2361,41 @@ export function hubFetch(
         }
       }
 
+      // Fresh-hub `/login` funnel (hub#644). `/login` is a browser-facing,
+      // server-rendered HTML surface (the sign-in form) — but on a no-admin
+      // box there is no account to sign in as, so the JSON-503 gate below
+      // would render as raw `{"error":"setup_required",...}` text in the
+      // visitor's tab. This is exactly the path a visitor takes when they
+      // load an open module surface (e.g. /vault/admin/) and click its
+      // "Sign in" banner, which links to `/login?next=<surface>`. Funnel the
+      // GET to the wizard instead, mirroring the `/` + `/hub.html` redirect
+      // above (same shape, same justification: never emit a JSON body on an
+      // HTML surface). 302 (not 301) so it disappears the moment setup
+      // completes and the real sign-in form takes over.
+      //
+      // Scoped to `userCount === 0` (the true no-admin state), NOT the
+      // broader `needsWizard`: once an admin exists, that operator must be
+      // able to reach the sign-in form even if no vault is installed yet
+      // (env-seed deploys). Only GET is funneled — a POST to `/login`
+      // pre-admin has no account to authenticate and falls through to the
+      // JSON-503 gate, the right shape for a stray non-browser caller.
+      //
+      // The `?next=<surface>` param is intentionally dropped: there's no
+      // account yet to return the visitor to, and the open surface they came
+      // from likely can't function until setup completes. They land on the
+      // wizard, not back on that surface.
+      //
+      // `cache-control: no-store` (the `/` + `/hub.html` funnel above omits
+      // it) — this 302 reflects transient pre-setup state that flips the
+      // moment an admin is created, so it must never be cached by a CDN or
+      // bfcache and serve a stale "go finish setup" to a now-set-up hub.
+      if (getDb && pathname === "/login" && req.method === "GET" && userCount(getDb()) === 0) {
+        return new Response(null, {
+          status: 302,
+          headers: { location: "/admin/setup", "cache-control": "no-store" },
+        });
+      }
+
       // Pre-admin lockout. When the hub has booted with no admin row (the
       // fresh-container case before PARACHUTE_INITIAL_ADMIN_* is set or
       // /admin/setup is walked), every operator-facing surface that requires
@@ -2633,6 +2715,38 @@ export function hubFetch(
         return applyCorsHeaders(req, await handleRevoke(getDb(), req, oauthDeps(req)));
       }
 
+      // Agent-connector OAuth-client callback (Phase 4b-2). The operator's
+      // browser is redirected here by a REMOTE issuer after consenting to a
+      // `kind:mcp` grant. Standalone server-rendered route — NOT under /admin/*,
+      // so the SPA catch-all never swallows it. GET, no Bearer: the single-use
+      // `state` it carries is the CSRF defense (this is a cross-site redirect IN
+      // from the remote issuer, so the same-origin belt does NOT apply). The
+      // handler looks up the pending flow by `state`, exchanges the code at the
+      // remote token endpoint, stores the grant material, and renders a tiny
+      // HTML "connected" / error page (never a token).
+      if (pathname === "/oauth/agent-grant/callback") {
+        if (!getDb) return dbNotConfigured();
+        if (req.method !== "GET") {
+          return new Response("method not allowed", { status: 405 });
+        }
+        const resolveVaultOrigin = (vaultName: string): string | null => {
+          const match = findVaultUpstream(
+            readManifestLenient(manifestPath).services,
+            `/vault/${vaultName}`,
+          );
+          return match ? `http://127.0.0.1:${match.port}` : null;
+        };
+        const agentGrantsDeps: AgentGrantsDeps = {
+          db: getDb(),
+          hubOrigin: oauthDeps(req).issuer,
+          storePath: deps?.agentGrantsStorePath ?? join(CONFIG_DIR, "agent-grants.json"),
+          flowsStorePath:
+            deps?.agentOAuthFlowsStorePath ?? join(CONFIG_DIR, "agent-oauth-flows.json"),
+          resolveVaultOrigin,
+        };
+        return handleOAuthGrantCallback(req, agentGrantsDeps);
+      }
+
       if (pathname === "/vaults") {
         if (!getDb) return dbNotConfigured();
         return handleCreateVault(req, {
@@ -2649,10 +2763,10 @@ export function hubFetch(
         if (!getDb) return dbNotConfigured();
         const name = decodeURIComponent(pathname.slice("/vaults/".length));
         const services = readManifestLenient(manifestPath).services;
-        // Channel's row carries its MANIFEST name — resolve via
+        // Agent's row carries its MANIFEST name — resolve via
         // findServiceByShort (see the /admin/connections note below).
-        const channelEntry = findServiceByShort(services, "channel");
-        const channelOrigin = channelEntry ? `http://127.0.0.1:${channelEntry.port}` : null;
+        const agentEntry = findServiceByShort(services, "agent");
+        const agentOrigin = agentEntry ? `http://127.0.0.1:${agentEntry.port}` : null;
         const resolveVaultOrigin = (vaultName: string): string | null => {
           const match = findVaultUpstream(
             readManifestLenient(manifestPath).services,
@@ -2666,7 +2780,7 @@ export function hubFetch(
           issuer: oauthDeps(req).issuer,
           manifestPath,
           connectionsStorePath: deps?.connectionsStorePath ?? join(CONFIG_DIR, "connections.json"),
-          channelOrigin,
+          agentOrigin,
           resolveVaultOrigin,
           resolveModuleOrigin: makeResolveModuleOrigin(manifestPath),
           // Daemon eviction — the same in-process supervisor the lifecycle
@@ -2695,9 +2809,19 @@ export function hubFetch(
         });
       }
 
+      // Back-compat: the agent module's admin-token mint moved from
+      // `/admin/channel-token` to `/admin/agent-token` in the 2026-06-17
+      // channel→agent rename. 301-redirect the old path so operator bookmarks
+      // + any un-upgraded UI fallback keep working for one release cycle.
       if (pathname === "/admin/channel-token") {
+        const dest = new URL(req.url);
+        dest.pathname = "/admin/agent-token";
+        return Response.redirect(dest.toString(), 301);
+      }
+
+      if (pathname === "/admin/agent-token") {
         if (!getDb) return dbNotConfigured();
-        return handleChannelToken(req, {
+        return handleAgentToken(req, {
           db: getDb(),
           issuer: oauthDeps(req).issuer,
         });
@@ -2707,7 +2831,7 @@ export function hubFetch(
       // architecture, P3). `<short>:admin` for any single-audience module —
       // the admin scope each module-owned config UI needs to call its own
       // endpoints. Cookie-gated to the first-admin operator, exactly like
-      // /admin/channel-token + /admin/vault-admin-token. Gated on
+      // /admin/agent-token + /admin/vault-admin-token. Gated on
       // self-registration (services.json row + readable module.json) with the
       // bootstrap registries as a fallback (boundary C5) — a genuinely
       // third-party module mints here with zero hub code changes. Vault is
@@ -2727,8 +2851,9 @@ export function hubFetch(
 
       // Note: the legacy `/admin/channels` bespoke vault-channel orchestration
       // endpoint (pre-Connections, hub#624 era) was retired in boundary D1 —
-      // superseded by the general engine below. Channel's own admin page
-      // drives `/admin/connections` + `/admin/channel-token`.
+      // superseded by the general engine below. The agent module's own admin
+      // page (renamed from channel 2026-06-17) drives `/admin/connections` +
+      // `/admin/agent-token`.
 
       // Connections — the GENERAL module event→action engine (2026-06-09
       // modular-UI architecture, P5). `/api/connections/catalog` (GET) returns
@@ -2737,7 +2862,7 @@ export function hubFetch(
       // `/admin/connections/:id` (DELETE) tears down. Cookie-gated to the
       // first-admin operator. The provisioning engine derives the vault
       // trigger's webhook + scope from the SINK action's declaration —
-      // nothing is channel-hardcoded.
+      // nothing is agent-hardcoded.
       if (
         pathname === "/api/connections/catalog" ||
         pathname === "/admin/connections" ||
@@ -2745,13 +2870,14 @@ export function hubFetch(
       ) {
         if (!getDb) return dbNotConfigured();
         const services = readManifestLenient(manifestPath).services;
-        // Channel's services.json row carries its MANIFEST name
-        // (`parachute-channel`), not the bare short `channel` — resolve via
+        // Agent's services.json row carries its MANIFEST name
+        // (`parachute-agent`), not the bare short `agent` — resolve via
         // findServiceByShort so the lookup matches the on-disk row. (A bare
-        // `s.name === "channel"` never matched, leaving channelOrigin null →
-        // "channel not installed".)
-        const channelEntry = findServiceByShort(services, "channel");
-        const channelOrigin = channelEntry ? `http://127.0.0.1:${channelEntry.port}` : null;
+        // `s.name === "agent"` never matched, leaving agentOrigin null →
+        // "agent not installed".) A legacy un-upgraded `parachute-channel` row
+        // still resolves here via the LEGACY_MANIFEST_ALIASES fallback.
+        const agentEntry = findServiceByShort(services, "agent");
+        const agentOrigin = agentEntry ? `http://127.0.0.1:${agentEntry.port}` : null;
         const resolveVaultOrigin = (vaultName: string): string | null => {
           const match = findVaultUpstream(
             readManifestLenient(manifestPath).services,
@@ -2767,15 +2893,15 @@ export function hubFetch(
           modules,
           resolveVaultOrigin,
           resolveModuleOrigin: makeResolveModuleOrigin(manifestPath),
-          channelOrigin,
+          agentOrigin,
           storePath: deps?.connectionsStorePath ?? join(CONFIG_DIR, "connections.json"),
         };
         if (pathname === "/api/connections/catalog") {
           return handleConnectionsCatalog(req, connectionsDeps);
         }
         // CSRF belt (hub#632, boundary C1): cookie-authed POST/DELETE must
-        // carry a matching Origin. The seam's canonical consumer — channel's
-        // admin page POSTing link-vault with `credentials: "include"` — is a
+        // carry a matching Origin. The seam's canonical consumer — the agent
+        // module's admin page POSTing link-vault with `credentials: "include"` — is a
         // same-origin fetch() and passes; see origin-check.ts
         // `assertSameOriginForCookieMutation` for the belted-endpoint
         // enumeration.
@@ -2787,6 +2913,43 @@ export function hubFetch(
         return handleConnections(req, subPath, connectionsDeps);
       }
 
+      // Agent-connector GRANTS — the approval-gated resource-grant subsystem
+      // (Phase 4b-1, agent-connectors design 2026-06-17). Generalizes the
+      // Connections engine from "event→action triggers" to "approval-gated
+      // resource grants": an agent declares connections it WANTS beyond its
+      // def-vault; the agent module registers each as a pending grant (PUT,
+      // host-admin Bearer); the operator approves per-connection (POST
+      // /approve, first-admin cookie); the hub mints (vault) / stores (service)
+      // the secret; the agent module fetches it at spawn (GET /material,
+      // host-admin Bearer). Two auth classes split by route inside the handler.
+      if (pathname === "/admin/grants" || pathname.startsWith("/admin/grants/")) {
+        if (!getDb) return dbNotConfigured();
+        const resolveVaultOrigin = (vaultName: string): string | null => {
+          const match = findVaultUpstream(
+            readManifestLenient(manifestPath).services,
+            `/vault/${vaultName}`,
+          );
+          return match ? `http://127.0.0.1:${match.port}` : null;
+        };
+        const agentGrantsDeps: AgentGrantsDeps = {
+          db: getDb(),
+          hubOrigin: oauthDeps(req).issuer,
+          storePath: deps?.agentGrantsStorePath ?? join(CONFIG_DIR, "agent-grants.json"),
+          flowsStorePath:
+            deps?.agentOAuthFlowsStorePath ?? join(CONFIG_DIR, "agent-oauth-flows.json"),
+          resolveVaultOrigin,
+        };
+        // CSRF belt (same posture as /admin/connections, hub#632): a no-op for
+        // the host-admin-Bearer PUT/GET (Bearer → not a browser CSRF), and the
+        // real gate on the cookie-authed POST /approve + /revoke.
+        {
+          const rejected = assertSameOriginForCookieMutation(req, oauthDeps(req).hubBoundOrigins());
+          if (rejected) return rejected;
+        }
+        const subPath = pathname.slice("/admin/grants".length);
+        return handleAgentGrants(req, subPath, agentGrantsDeps);
+      }
+
       if (pathname.startsWith("/admin/vault-admin-token/")) {
         if (!getDb) return dbNotConfigured();
         const vaultName = decodeURIComponent(pathname.slice("/admin/vault-admin-token/".length));
@@ -2813,6 +2976,25 @@ export function hubFetch(
         return handleApiMe(req, { db: getDb() });
       }
 
+      // Admin screen-lock management (optional idle PIN lock for the admin
+      // UI). Session-cookie-gated to the first admin; these manage the lock
+      // itself so they are NOT behind the lock gate. The lock GATE lives in
+      // the four `/admin/*-token` mint handlers (admin-lock.ts:requireUnlocked)
+      // — it does NOT touch `/oauth/*`, so the OAuth issuer is unaffected.
+      if (pathname === "/api/admin-lock" || pathname.startsWith("/api/admin-lock/")) {
+        if (!getDb) return dbNotConfigured();
+        // CSRF belt (same posture as /admin/connections): these are
+        // cookie-authed JSON mutations. The handler ALSO checks a double-
+        // submit `__csrf` token; the Origin belt is defense-in-depth on the
+        // POST paths (GET status is read-shaped and skips it).
+        {
+          const rejected = assertSameOriginForCookieMutation(req, oauthDeps(req).hubBoundOrigins());
+          if (rejected) return rejected;
+        }
+        const subpath = pathname.slice("/api/admin-lock".length);
+        return handleAdminLock(req, subpath, { db: getDb() });
+      }
+
       // SPA-driven hub self-upgrade (design 2026-06-01 §5.3 / D4). Dedicated
       // endpoint — the hub is NOT a supervised module (no /api/modules/hub/*),
       // so it gets its own route. Checked BEFORE the `/api/hub` exact match
@@ -2934,7 +3116,7 @@ export function hubFetch(
       // the 2026-06-09 modular-UI architecture P3. Config is module-owned +
       // hub-framed now: the Modules page "Configure" action opens the module's
       // OWN config UI (`configUiUrl`), which mints its admin Bearer from the
-      // cookie-gated `/admin/module-token/<short>` (or `/admin/channel-token`).
+      // cookie-gated `/admin/module-token/<short>` (or `/admin/agent-token`).
 
       // Per-module action endpoints: /api/modules/:short/{install,restart,upgrade,uninstall}.
       if (pathname.startsWith("/api/modules/")) {

package/src/hub-settings.ts

@@ -28,13 +28,14 @@ import type { Database } from "bun:sqlite";
 export type HubSettingKey =
   | "setup_expose_mode"
   | "pending_first_client_auto_approve_until"
-  // hub#272: auto-minted operator token surfaced once on the wizard's
-  // done screen. Single-use — the done-step renderer reads + deletes the
-  // row so a subsequent GET (page refresh, back button) doesn't re-show
-  // the secret. Lives in hub_settings rather than tokens because it's a
-  // wizard-flow ephemeral, not a persistent issued credential — the
-  // mintOperatorToken call still records the jti in the `tokens`
-  // registry, so revocation works as usual.
+  // hub#272: DEPRECATED 2026-06-23 (Austen's report). Used to hold an
+  // auto-minted operator token surfaced once on the wizard's done screen
+  // so the MCP command could pre-fill a `--header "Authorization: Bearer
+  // <token>"` flag. The auto-mint was removed when vault went OAuth-
+  // default (parachute-vault #491) — nothing writes this row anymore.
+  // The key is retained so the done-step GET can defensively clear any
+  // stale row a pre-upgrade hub left behind (it never renders the value).
+  // Drop the member once no live hub_settings tables carry the row.
   | "setup_minted_token"
   // hub#267: the typed vault name. Persisted at vault POST time so the
   // done step can render the operator's choice in the MCP URL +
@@ -91,7 +92,21 @@ export type HubSettingKey =
   // the deprecation window. Stored as the literal string "true" /
   // "false"; any other value parses as "redirect on" (the migration
   // default — operators must opt out, not opt in).
-  | "notes_redirect_disabled";
+  | "notes_redirect_disabled"
+  // Admin-UI screen-lock PIN (hub admin-lock feature). The argon2id hash of
+  // the operator's lock PIN. Absent row = lock feature OFF (today's behavior
+  // exactly — the admin UI is gated only by the password-login session). When
+  // set, the admin token-mint chokepoints refuse to mint while the operator's
+  // session is "locked" (no fresh unlock, or idle-expired). NEVER plaintext;
+  // the hash sits at the same operator-local trust boundary as the password
+  // hashes + signing keys already in hub.db (see migration v11's note on
+  // at-rest encryption). The "unlocked-until" state is per-session + in-memory
+  // (admin-lock.ts) — never persisted, never in the cookie.
+  | "admin_lock_pin_hash"
+  // Idle timeout for the admin screen-lock, in seconds. Optional override of
+  // the built-in default (DEFAULT_ADMIN_LOCK_IDLE_SECONDS). Stored as a
+  // stringified integer; absent / unparseable falls back to the default.
+  | "admin_lock_idle_seconds";
 
 export type SetupExposeMode = "localhost" | "tailnet" | "public";
 

package/src/jwt-sign.ts

@@ -152,7 +152,11 @@ export type TokenCreatedVia =
   | "cli_mint"
   | "operator_mint"
   | "connection_provision"
-  | "connection_credential";
+  | "connection_credential"
+  // Agent-connector grants (Phase 4b-1) — a vault token the hub mints when the
+  // operator approves an agent's `vault:<name>:<verb>` connection grant. Stored
+  // in the agent-grants store; registered here so revoke can drop it.
+  | "agent_grant";
 
 export interface SignedRefreshToken {
   /** Opaque token to return to the client. NOT recoverable from the DB. */

package/src/module-manifest.ts

@@ -124,7 +124,7 @@ export interface ModuleAction {
    * Bearer` (P5). For a `vault-trigger`, this is persisted as the trigger's
    * long-lived `action.auth.bearer` scope — the credential the sink module
    * validates on every callback. Sourced from the action declaration so the
-   * hub never hardcodes a per-module scope. Channel ships `"channel:send"`.
+   * hub never hardcodes a per-module scope. Agent ships `"agent:send"`.
    */
   readonly scope?: string;
   /** Opaque (P1) descriptor of how the hub provisions this action. */
@@ -777,7 +777,7 @@ function asActions(
       // `scope` is minted by the hub into a 90-day webhook bearer presented to
       // THIS module's own endpoint, which validates `aud:<name>` + a scope in
       // its own namespace. A legitimate `action.scope` is therefore always in
-      // the declaring module's namespace (channel.message.deliver → channel:send).
+      // the declaring module's namespace (agent.message.deliver → agent:send).
       // Enforcing `<ns> === name` blocks a malicious module declaring e.g.
       // `vault:default:admin` and tricking the hub into minting a cross-module
       // privilege-escalating token when an operator wires a Connection to it.