@openparachute/hub 0.7.0 → 0.7.2-rc.1

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],

package/src/admin-lock.ts

@@ -0,0 +1,281 @@
+/**
+ * Optional idle screen-lock for the hub ADMIN UI (phone-style lock).
+ *
+ * ## What this guards (and what it deliberately doesn't)
+ *
+ * The hub admin UI is reachable remotely once `parachute expose` is up
+ * (Tailscale / Cloudflare). A grabbed or left-logged-in admin browser session
+ * is a real risk: the password-login session cookie lasts 24h, so an
+ * unattended tab is a standing admin console. This adds an OPTIONAL operator
+ * PIN that LOCKS THE WHOLE ADMIN SURFACE — one lock over everything, not
+ * per-action gating (per-action would friction-up configuration, which is the
+ * dangerous stuff we most want behind the lock anyway). Unlock with the PIN →
+ * a frictionless working window; admin activity refreshes it; idle re-locks.
+ *
+ * THREAT MODEL: this is a WEB/UI-layer guard for the EXPOSED admin portal. It
+ * does NOT protect against someone with a SHELL on the box — they read
+ * `~/.parachute/operator.token` / the vault DB directly and bypass the hub
+ * entirely. That's an OS concern (disk encryption, a locked OS screen, SSH-key
+ * hygiene). The lock shuts the *portal* door — the one the internet can reach —
+ * which is the point.
+ *
+ * ## The single chokepoint
+ *
+ * The admin SPA + every module config UI get their working Bearer from one of
+ * the cookie-gated mint endpoints:
+ *   - `GET /admin/host-admin-token`        (the SPA's own Bearer)
+ *   - `GET /admin/agent-token`             (agent chat + config UIs)
+ *   - `GET /admin/vault-admin-token/<name>`(per-vault admin SPA)
+ *   - `GET /admin/module-token/<short>`    (generic module config UI Bearer)
+ *
+ * All four share the exact `parseSessionCookie → findSession → [isFirstAdmin]
+ * → signAccessToken` shape. Inserting {@link requireUnlocked} into each makes
+ * the lock cascade to EVERY admin surface with no per-module changes: when
+ * locked, the mint returns 423 and the relevant UI shows the lock screen / its
+ * admin calls fail closed (no Bearer). A surface OAuth'ing in via `/oauth/*`
+ * never touches these endpoints, so the OAuth issuer is untouched — see the
+ * design note (`design/2026-06-17-admin-ui-lock.md`).
+ *
+ * ## Unlock state — per-session, in-memory, "unlocked-until"
+ *
+ * Simplest workable model. A successful PIN unlock records `unlockedUntil` for
+ * the session id (the cookie value) in a process-local Map. The session is
+ * UNLOCKED iff a future `unlockedUntil` exists; genuine USER activity (the SPA's
+ * debounced `/heartbeat`, fired on pointer/key/scroll) slides it forward by the
+ * idle window. Token mints do NOT slide it — the SPA polls some endpoints in the
+ * background, and letting a poll's re-mint extend the window would keep an
+ * idle-but-open tab unlocked forever. LOCKED when:
+ *   - no PIN is set → feature OFF, never locked (today's behavior);
+ *   - PIN set + no unlock recorded (fresh load / first visit);
+ *   - PIN set + the recorded unlock is in the past (idle-expired);
+ *   - a hub restart wipes the Map → re-lock (a feature, not a bug).
+ *
+ * The unlock state is NEVER persisted and NEVER put in the cookie — a stolen
+ * cookie alone can't carry an unlocked window; the attacker still needs the
+ * PIN. (The cookie already authenticates the password session; the PIN is the
+ * second, idle-bounded gate on top.)
+ */
+import type { Database } from "bun:sqlite";
+import { hash as argonHash, verify as argonVerify } from "@node-rs/argon2";
+import { deleteSetting, getSetting, setSetting } from "./hub-settings.ts";
+import { RateLimiter } from "./rate-limit.ts";
+
+/** Default idle window before a session re-locks. Phone-lock territory. */
+export const DEFAULT_ADMIN_LOCK_IDLE_SECONDS = 15 * 60;
+
+/** Clamp on the operator-configurable idle window: 1 min … 24h. */
+export const MIN_ADMIN_LOCK_IDLE_SECONDS = 60;
+export const MAX_ADMIN_LOCK_IDLE_SECONDS = 24 * 60 * 60;
+
+/**
+ * PIN format: 4–12 digits. A numeric PIN is the phone-lock affordance the
+ * feature is named for; the real defense is the idle window + brute-force
+ * limiter, not PIN entropy (the session is already password-authenticated —
+ * this is a second, convenience-grade gate). Operators wanting a full secret
+ * use the OS lock / a strong account password; this is the "don't leave the
+ * console open on the train" guard.
+ */
+export const ADMIN_LOCK_PIN_RE = /^[0-9]{4,12}$/;
+
+export type ValidatePinResult = { valid: true } | { valid: false; reason: "format" };
+
+export function validatePin(pin: string): ValidatePinResult {
+  return ADMIN_LOCK_PIN_RE.test(pin) ? { valid: true } : { valid: false, reason: "format" };
+}
+
+// --- PIN storage (argon2id hash in hub_settings) ---------------------------
+
+/** True iff an admin-lock PIN is configured (feature is ON). */
+export function isLockConfigured(db: Database): boolean {
+  const h = getSetting(db, "admin_lock_pin_hash");
+  return typeof h === "string" && h.length > 0;
+}
+
+/**
+ * Store (or rotate) the PIN. Hashes with argon2id — the same family the hub
+ * already uses for passwords + TOTP backup codes (`@node-rs/argon2`). The
+ * caller MUST have validated the PIN format first; this trusts its input.
+ */
+export async function setPin(db: Database, pin: string): Promise<void> {
+  const h = await argonHash(pin);
+  setSetting(db, "admin_lock_pin_hash", h);
+}
+
+/** Remove the PIN (turn the feature OFF). Idempotent. Also clears idle config. */
+export function clearPin(db: Database): void {
+  deleteSetting(db, "admin_lock_pin_hash");
+  deleteSetting(db, "admin_lock_idle_seconds");
+}
+
+/**
+ * Verify a submitted PIN against the stored hash. Returns false when no PIN is
+ * configured (defensive — callers gate on {@link isLockConfigured} first) or
+ * the hash is malformed.
+ */
+export async function verifyPin(db: Database, pin: string): Promise<boolean> {
+  const h = getSetting(db, "admin_lock_pin_hash");
+  if (typeof h !== "string" || h.length === 0) return false;
+  try {
+    return await argonVerify(h, pin);
+  } catch {
+    // Corrupt/unparseable hash — fail closed.
+    return false;
+  }
+}
+
+// --- idle window config ----------------------------------------------------
+
+/** Read the configured idle window (clamped). Falls back to the default. */
+export function getIdleSeconds(db: Database): number {
+  const raw = getSetting(db, "admin_lock_idle_seconds");
+  if (typeof raw !== "string") return DEFAULT_ADMIN_LOCK_IDLE_SECONDS;
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isFinite(n)) return DEFAULT_ADMIN_LOCK_IDLE_SECONDS;
+  return clampIdleSeconds(n);
+}
+
+export function clampIdleSeconds(n: number): number {
+  if (n < MIN_ADMIN_LOCK_IDLE_SECONDS) return MIN_ADMIN_LOCK_IDLE_SECONDS;
+  if (n > MAX_ADMIN_LOCK_IDLE_SECONDS) return MAX_ADMIN_LOCK_IDLE_SECONDS;
+  return Math.floor(n);
+}
+
+/** Persist the operator's idle-window choice (clamped). */
+export function setIdleSeconds(db: Database, seconds: number): void {
+  setSetting(db, "admin_lock_idle_seconds", String(clampIdleSeconds(seconds)));
+}
+
+// --- per-session unlock state (in-memory, never persisted) -----------------
+
+/**
+ * sessionId → unlockedUntil epoch ms. Process-local; a restart wipes it (which
+ * is the re-lock-on-fresh-process behavior we want). Bounded by an
+ * opportunistic prune of expired rows on every touch, so an attacker churning
+ * session ids can't grow it unboundedly.
+ */
+const unlockedUntil = new Map<string, number>();
+
+function pruneExpired(now: number): void {
+  for (const [sid, until] of unlockedUntil) {
+    if (until <= now) unlockedUntil.delete(sid);
+  }
+}
+
+/**
+ * Record a fresh unlock for `sessionId`, valid for `idleSeconds` from now.
+ * Called after a successful PIN verify.
+ */
+export function recordUnlock(
+  sessionId: string,
+  idleSeconds: number,
+  now: number = Date.now(),
+): void {
+  pruneExpired(now);
+  unlockedUntil.set(sessionId, now + idleSeconds * 1000);
+}
+
+/**
+ * Slide the unlock window forward by `idleSeconds` IF the session is currently
+ * unlocked. Called on admin activity (heartbeat + every successful mint) so an
+ * actively-used console doesn't lock mid-work. Does NOT create an unlock for a
+ * locked session — only an explicit PIN entry can do that.
+ */
+export function refreshActivity(
+  sessionId: string,
+  idleSeconds: number,
+  now: number = Date.now(),
+): void {
+  const until = unlockedUntil.get(sessionId);
+  if (until === undefined || until <= now) return; // locked — activity doesn't unlock
+  unlockedUntil.set(sessionId, now + idleSeconds * 1000);
+}
+
+/** Is this session currently within an unlock window? */
+export function isSessionUnlocked(sessionId: string, now: number = Date.now()): boolean {
+  const until = unlockedUntil.get(sessionId);
+  return until !== undefined && until > now;
+}
+
+/** Force-lock a session immediately ("Lock now"). Idempotent. */
+export function lockSession(sessionId: string): void {
+  unlockedUntil.delete(sessionId);
+}
+
+/** Remaining unlock seconds for a session (0 when locked). For status UI. */
+export function unlockSecondsRemaining(sessionId: string, now: number = Date.now()): number {
+  const until = unlockedUntil.get(sessionId);
+  if (until === undefined || until <= now) return 0;
+  return Math.ceil((until - now) / 1000);
+}
+
+/** Test seam: wipe all in-memory unlock state. */
+export function _resetUnlockStateForTest(): void {
+  unlockedUntil.clear();
+}
+
+// --- the gate the four token-mint chokepoints call -------------------------
+
+/**
+ * The single lock gate. Returns whether the mint may proceed.
+ *
+ *   - feature OFF (no PIN) → ALWAYS allow (today's behavior, byte-for-byte).
+ *   - feature ON + session unlocked → allow.
+ *   - feature ON + session locked → DENY (the caller returns 423 Locked).
+ *
+ * Deliberately a PURE CHECK — it does NOT slide the idle window. Sliding is
+ * driven exclusively by genuine USER activity (the SPA's debounced
+ * `/heartbeat`, fired on pointer/key/scroll), NOT by token mints. The SPA polls
+ * some endpoints in the background (e.g. the version badge every 30s), and each
+ * such poll re-mints a host-admin Bearer; if a mint extended the window, a
+ * left-open-but-idle tab would never lock — defeating the whole feature. The
+ * heartbeat is the one thing that means "a human is here."
+ *
+ * `now` is injectable for tests.
+ */
+export function requireUnlocked(
+  db: Database,
+  sessionId: string,
+  now: number = Date.now(),
+): { ok: true } | { ok: false; reason: "locked" } {
+  if (!isLockConfigured(db)) return { ok: true };
+  if (isSessionUnlocked(sessionId, now)) {
+    return { ok: true };
+  }
+  return { ok: false, reason: "locked" };
+}
+
+/** RFC-shaped 423 the mint chokepoints return when locked. */
+export function lockedResponse(): Response {
+  return new Response(
+    JSON.stringify({
+      error: "locked",
+      error_description:
+        "the admin UI is locked — enter your PIN to unlock (POST /api/admin-lock/unlock)",
+    }),
+    {
+      status: 423,
+      headers: {
+        "content-type": "application/json",
+        "cache-control": "no-store",
+      },
+    },
+  );
+}
+
+// --- unlock brute-force limiter --------------------------------------------
+
+/**
+ * Per-session unlock-attempt limiter. The unlock endpoint is session-gated, so
+ * the threat is a compromised session (stolen cookie) grinding argon2id PIN
+ * verifications without bound — keyed by session id, same posture as
+ * `/account/change-password` (keyed by user). 5 wrong PINs / 5 min is the
+ * floor; the idle window + the limiter together are the real defense (the PIN
+ * itself is convenience-grade — see the module header).
+ */
+export const ADMIN_LOCK_UNLOCK_MAX_ATTEMPTS = 5;
+export const ADMIN_LOCK_UNLOCK_WINDOW_MS = 5 * 60 * 1000;
+
+export const unlockLimiter = new RateLimiter(
+  ADMIN_LOCK_UNLOCK_MAX_ATTEMPTS,
+  ADMIN_LOCK_UNLOCK_WINDOW_MS,
+);

package/src/admin-login-ui.ts

@@ -161,8 +161,18 @@ export interface InviteSetupProps {
   /**
    * When the invite pins a vault name the redeemer can't choose one — we show
    * it read-only. When null the redeemer names their own vault (a text field).
+   * With `provisionVault: false` a pinned name is a SHARED-VAULT invite: the
+   * redeemer is being given `role` access to the operator's existing vault.
    */
   pinnedVaultName: string | null;
+  /**
+   * When the invite pre-names the account, the username is shown read-only
+   * and ENFORCED server-side (the redeem handler ignores the form field).
+   * Null = the redeemer picks their own.
+   */
+  pinnedUsername: string | null;
+  /** The `user_vaults` role redemption grants ('read' | 'write') — shown on the shared-vault row. */
+  role: string;
   /** Whether redemption provisions a vault at all (shows the vault row iff true). */
   provisionVault: boolean;
   username?: string;
@@ -177,15 +187,55 @@ export interface InviteSetupProps {
  * same `/account/setup/<token>` path. Reuses the shared login chrome.
  */
 export function renderInviteSetup(props: InviteSetupProps): string {
-  const { token, csrfToken, pinnedVaultName, provisionVault, username, vaultName, errorMessage } =
-    props;
+  const {
+    token,
+    csrfToken,
+    pinnedVaultName,
+    pinnedUsername,
+    role,
+    provisionVault,
+    username,
+    vaultName,
+    errorMessage,
+  } = props;
   const error = errorMessage ? `<p class="error-banner">${escapeHtml(errorMessage)}</p>` : "";
   const usernameAttr = username ? ` value="${escapeAttr(username)}"` : "";
 
-  // Vault row: shown only when the invite provisions a vault. Pinned → a
-  // read-only display of the name the admin chose (redeemer can't squat names).
-  // Unpinned → a text field the redeemer fills.
+  // Username row: pre-named → read-only display (the server ENFORCES the
+  // invite's username; the disabled input never submits and the handler
+  // ignores the field anyway). Unpinned → the normal pick-a-name field.
+  const usernameRow =
+    pinnedUsername !== null
+      ? `
+        <label class="field">
+          <span class="field-label">Username</span>
+          <input type="text" value="${escapeAttr(pinnedUsername)}" readonly disabled />
+          <span class="field-hint">Your hub operator chose this username for you.</span>
+        </label>`
+      : `
+        <label class="field">
+          <span class="field-label">Username</span>
+          <input type="text" name="username" id="username" autocomplete="username" autofocus
+            required minlength="2" maxlength="32"
+            pattern="[a-z0-9_-]+" title="lowercase letters, digits, _ - (2–32 chars)"
+            spellcheck="false" autocapitalize="off"${usernameAttr} />
+          <span class="field-hint">lowercase letters, digits, <code>_</code>, <code>-</code></span>
+        </label>`;
+
+  // Vault row. Provisioning invites show the new vault's name (pinned →
+  // read-only; unpinned → a text field the redeemer fills). A shared-vault
+  // invite (no provisioning + a pinned name) shows what the redeemer is
+  // being given access to, including the role.
   let vaultRow = "";
+  if (!provisionVault && pinnedVaultName !== null) {
+    const roleLabel = role === "read" ? "read-only" : "read &amp; write";
+    vaultRow = `
+        <label class="field">
+          <span class="field-label">Shared vault</span>
+          <input type="text" value="${escapeAttr(pinnedVaultName)}" readonly disabled />
+          <span class="field-hint">You're being given ${roleLabel} access to this existing vault.</span>
+        </label>`;
+  }
   if (provisionVault) {
     if (pinnedVaultName !== null) {
       vaultRow = `
@@ -240,21 +290,20 @@ export function renderInviteSetup(props: InviteSetupProps): string {
       <div class="card-header">
         ${header()}
         <h1>Claim your invite</h1>
-        <p class="subtitle">Pick a username and password to create your Parachute account${
-          provisionVault ? " and your own vault" : ""
+        <p class="subtitle">${
+          pinnedUsername !== null ? "Pick a password" : "Pick a username and password"
+        } to create your Parachute account${
+          provisionVault
+            ? " and your own vault"
+            : pinnedVaultName !== null
+              ? " with access to a shared vault"
+              : ""
         }.</p>
       </div>
       ${error}
       <form method="POST" action="/account/setup/${escapeAttr(token)}" class="auth-form">
         ${renderCsrfHiddenInput(csrfToken)}
-        <label class="field">
-          <span class="field-label">Username</span>
-          <input type="text" name="username" id="username" autocomplete="username" autofocus
-            required minlength="2" maxlength="32"
-            pattern="[a-z0-9_-]+" title="lowercase letters, digits, _ - (2–32 chars)"
-            spellcheck="false" autocapitalize="off"${usernameAttr} />
-          <span class="field-hint">lowercase letters, digits, <code>_</code>, <code>-</code></span>
-        </label>
+        ${usernameRow}
         <label class="field">
           <span class="field-label">Password</span>
           <input type="password" name="password" autocomplete="new-password"

package/src/admin-module-token.ts

@@ -8,15 +8,15 @@
  * hub frames/links those surfaces consistently (the Modules page "Configure"
  * action). Each module-owned config UI, served behind the hub proxy to a
  * logged-in portal operator, needs an admin-scoped hub Bearer to call its own
- * `<short>:admin`-gated endpoints — the same shape the channel config UI gets
- * from `/admin/channel-token` and the vault admin SPA gets from
+ * `<short>:admin`-gated endpoints — the same shape the agent config UI gets
+ * from `/admin/agent-token` and the vault admin SPA gets from
  * `/admin/vault-admin-token/<name>`. This is the GENERIC mint that covers every
  * other self-registered single-audience module, so the hub doesn't grow a
  * bespoke per-module mint endpoint as each module ships a config UI.
  *
  * Scope + audience: `<short>:admin`, audience = `<short>` (the bare service
  * prefix). Modules validate the JWT's `aud` against their literal short name
- * (`scribe`, `runner`, `surface`, `channel`) — the same shape `inferAudience`
+ * (`scribe`, `runner`, `surface`, `agent`) — the same shape `inferAudience`
  * stamps for the public OAuth flow, so a hub-minted and an OAuth-minted admin
  * token are indistinguishable to the module. This mirrors the per-request
  * `<short>:admin` proxy token `api-modules-config.ts` used to mint; the
@@ -32,13 +32,14 @@
  *
  * Gate: the session must belong to the first admin (the single hub admin under
  * the Phase 1 multi-user model — `users.ts:isFirstAdmin`), exactly like
- * host-admin-token / vault-admin-token / channel-token. A friend account holds
+ * host-admin-token / vault-admin-token / agent-token. A friend account holds
  * a valid session but must not mint a module admin Bearer.
  *
  * Tokens are short-lived (10 min — matches the sibling admin-token mints); the
  * config 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 {
   type ModuleManifest,
@@ -49,7 +50,7 @@ import type { ServiceEntry } from "./services-manifest.ts";
 import { findSession, parseSessionCookie } from "./sessions.ts";
 import { isFirstAdmin } from "./users.ts";
 
-/** Short TTL — matches host/vault/channel admin-token. UI re-fetches on near-expiry. */
+/** Short TTL — matches host/vault/agent admin-token. UI re-fetches on near-expiry. */
 export const MODULE_TOKEN_TTL_SECONDS = 10 * 60;
 const MODULE_TOKEN_CLIENT_ID = "parachute-hub-spa";
 
@@ -143,10 +144,10 @@ export async function handleModuleToken(
   }
   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 (mirrors host/vault/channel-admin-token). A friend account
+  // First-admin gate (mirrors host/vault/agent-admin-token). A friend account
   // (non-first-admin user) holds a valid session but must not mint a module
   // admin Bearer.
   if (!isFirstAdmin(deps.db, session.userId)) {
@@ -156,6 +157,13 @@ export async function handleModuleToken(
       "module admin 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 a module admin Bearer, so every module-owned config UI
+  // fails closed until the operator unlocks. This is what makes the lock
+  // cascade to ALL modules with zero per-module changes. Off by default.
+  if (!requireUnlocked(deps.db, sid).ok) {
+    return lockedResponse();
+  }
   const scope = `${short}:admin`;
   const minted = await signAccessToken(deps.db, {
     sub: session.userId,

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

@@ -25,6 +25,7 @@
  * for their assigned vault; they don't get vault admin via this endpoint.
  */
 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";
@@ -66,7 +67,7 @@ export async function handleVaultAdminToken(
   }
   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");
   }
   // Multi-user Phase 1 privesc gate (mirrors host-admin-token). vault:<name>:admin
@@ -80,6 +81,12 @@ export async function handleVaultAdminToken(
       "vault admin 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 a vault admin Bearer, so the vault admin SPA fails
+  // closed until the operator unlocks. Off by default.
+  if (!requireUnlocked(deps.db, sid).ok) {
+    return lockedResponse();
+  }
   const scope = `vault:${vaultName}:admin`;
   // Per-vault audience: vault validates the JWT's `aud` claim against
   // `vault.<name>` derived from its own URL-bound config (vault src/auth.ts

package/src/admin-vaults.ts

@@ -537,10 +537,16 @@ export interface DeleteVaultDeps {
   manifestPath?: string;
   /** Absolute path to `connections.json` in the hub state dir. */
   connectionsStorePath: string;
-  /** 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;
   /** Resolve a vault's loopback origin from services.json (trigger teardown). */
   resolveVaultOrigin: (vaultName: string) => string | null;
+  /**
+   * Resolve a module's loopback origin by short name (H4 — best-effort
+   * credential-removal notification during connection teardown). Optional:
+   * absent → the notification step records a warning, revocation still runs.
+   */
+  resolveModuleOrigin?: (short: string) => string | null;
   /** Test seam: run `parachute-vault remove` — same Runner seam as create. */
   runCommand?: CreateVaultDeps["runCommand"];
   /**
@@ -645,7 +651,7 @@ function listVaultInstanceNames(manifestPath: string): Set<string> {
  *      the name);
  *   5. connections whose source/provisioned vault is the deleted vault
  *      (via `teardownConnection`, which post-B0 also revokes the registered
- *      long-lived mints) + a report-only scan of channel's `/api/channels`
+ *      long-lived mints) + a report-only scan of the agent's `/api/channels`
  *      for legacy vault-backed entries (`orphaned_channels`);
  *   6. mechanics: shell to `parachute-vault remove <name> --yes` (the module
  *      CLI stays the single source of truth for vault destruction,
@@ -755,7 +761,10 @@ export async function handleDeleteVault(
     hubOrigin: deps.issuer,
     modules: [], // teardown never consults the catalog
     resolveVaultOrigin: deps.resolveVaultOrigin,
-    channelOrigin: deps.channelOrigin,
+    ...(deps.resolveModuleOrigin !== undefined
+      ? { resolveModuleOrigin: deps.resolveModuleOrigin }
+      : {}),
+    agentOrigin: deps.agentOrigin,
     storePath: deps.connectionsStorePath,
     ...(deps.fetchImpl !== undefined ? { fetchImpl: deps.fetchImpl } : {}),
     ...(deps.now !== undefined ? { now: deps.now } : {}),
@@ -788,9 +797,9 @@ export async function handleDeleteVault(
 
   // Legacy channel scan — vault-backed channel entries still referencing the
   // vault after connection teardown (pre-Connections wiring). REPORT ONLY:
-  // channel's config is the channel module's domain; the operator removes
-  // them from channel's own UI.
-  if (deps.channelOrigin !== null) {
+  // the channel config is the agent module's domain; the operator removes
+  // them from the agent's own UI.
+  if (deps.agentOrigin !== null) {
     try {
       const fetchImpl = deps.fetchImpl ?? fetch;
       // Short-lived (60s) — stays below the registered-mint threshold by
@@ -799,8 +808,8 @@ export async function handleDeleteVault(
       const scanToken = (
         await signAccessToken(deps.db, {
           sub: adminSub,
-          scopes: ["channel:admin"],
-          audience: "channel",
+          scopes: ["agent:admin"],
+          audience: "agent",
           clientId: DELETE_VAULT_CLIENT_ID,
           issuer: deps.issuer,
           ttlSeconds: DELETE_VAULT_PROVISION_TTL_SECONDS,
@@ -808,7 +817,7 @@ export async function handleDeleteVault(
           ...(deps.now !== undefined ? { now: deps.now } : {}),
         })
       ).token;
-      const res = await fetchImpl(`${deps.channelOrigin}/api/channels`, {
+      const res = await fetchImpl(`${deps.agentOrigin}/api/channels`, {
         headers: { authorization: `Bearer ${scanToken}`, accept: "application/json" },
       });
       if (res.ok) {
@@ -821,11 +830,11 @@ export async function handleDeleteVault(
           }
         }
       } else {
-        warnings.push({ step: "channel_scan", detail: `channel list returned ${res.status}` });
+        warnings.push({ step: "agent_scan", detail: `agent channel list returned ${res.status}` });
       }
     } catch (err) {
       warnings.push({
-        step: "channel_scan",
+        step: "agent_scan",
         detail: err instanceof Error ? err.message : String(err),
       });
     }