@openparachute/hub 0.6.5-rc.7 → 0.7.0

package/src/admin-module-token.ts

@@ -0,0 +1,197 @@
+/**
+ * `GET /admin/module-token/<short>` — exchange a valid admin session cookie for
+ * a short-lived JWT carrying `<short>:admin` (audience = the bare module short).
+ *
+ * Why this exists (2026-06-09 modular-UI architecture, P3): modules now own
+ * their config/admin UIs and declare `configUiUrl` in `module.json` (scribe
+ * `/scribe/admin`, runner `/runner/admin`, surface `/surface/admin/`, …). The
+ * 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
+ * `/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`
+ * 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
+ * difference is this endpoint hands the token to the module's OWN UI rather
+ * than proxying a hub-side config form.
+ *
+ * Multi-vault note: VAULT is excluded here. Vault's admin scope is per-instance
+ * (`vault:<name>:admin`, audience `vault.<name>`), which needs a vault-name
+ * parameter and a known-vault check — that lives in `/admin/vault-admin-token/
+ * <name>` (`admin-vault-admin-token.ts`). A request for `vault` here returns a
+ * 400 pointing at that endpoint, so a caller can't accidentally mint a useless
+ * bare `vault:admin`.
+ *
+ * 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
+ * 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 { signAccessToken } from "./jwt-sign.ts";
+import {
+  type ModuleManifest,
+  readModuleManifest as defaultReadModuleManifest,
+} from "./module-manifest.ts";
+import { findServiceByShort, isKnownModuleShort } from "./service-spec.ts";
+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. */
+export const MODULE_TOKEN_TTL_SECONDS = 10 * 60;
+const MODULE_TOKEN_CLIENT_ID = "parachute-hub-spa";
+
+/** Lowercase short-name charset, matching the module-name rule + path parsing. */
+const MODULE_SHORT_RE = /^[a-z][a-z0-9-]*$/;
+
+export interface MintModuleTokenDeps {
+  db: Database;
+  /** Hub origin — written into JWT `iss`. */
+  issuer: string;
+  /**
+   * Snapshot of services.json rows, read at request time so a module that
+   * self-registered since hub boot is mintable without a restart. Used by the
+   * self-registration gate (boundary C5) — see {@link isSelfRegisteredModule}.
+   */
+  readServices: () => readonly ServiceEntry[];
+  /** Test seam — defaults to the real `readModuleManifest` (disk read). */
+  readModuleManifest?: (installDir: string) => Promise<ModuleManifest | null>;
+}
+
+/**
+ * The self-registration gate (C5 of the 2026-06-09 hub-module-boundary
+ * migration): a short is mintable when it resolves to a services.json row
+ * whose `installDir` carries a readable `.parachute/module.json`.
+ *
+ * Resolution mirrors the rest of the hub (`/api/modules`,
+ * `collectInstalledModules`): first-party rows resolve through
+ * `findServiceByShort` (manifest name ↔ short map); a genuinely third-party
+ * row matches by its literal services.json `name` — the same
+ * `shortNameForManifest(name) ?? name` convention the catalog uses.
+ *
+ * Why this is enough against a forged short: services.json is written only by
+ * same-disk modules, which the charter's trust statement already covers — an
+ * installed module runs a daemon on the operator's machine, strictly more
+ * power than an admin Bearer. Requiring the registered row AND a readable
+ * manifest still keeps a typo'd short from minting `<anything>:admin` and
+ * masquerading as a real (but unusable) credential.
+ */
+async function isSelfRegisteredModule(short: string, deps: MintModuleTokenDeps): Promise<boolean> {
+  const services = deps.readServices();
+  const row =
+    findServiceByShort(services, short) ?? services.find((s): boolean => s.name === short);
+  if (!row?.installDir) return false;
+  const readManifest = deps.readModuleManifest ?? defaultReadModuleManifest;
+  try {
+    const manifest = await readManifest(row.installDir);
+    return manifest !== null;
+  } catch {
+    // Malformed manifest — treat as not-a-module rather than 500ing the mint.
+    return false;
+  }
+}
+
+export async function handleModuleToken(
+  req: Request,
+  short: string,
+  deps: MintModuleTokenDeps,
+): Promise<Response> {
+  if (req.method !== "GET") {
+    return jsonError(405, "method_not_allowed", "use GET");
+  }
+  if (!MODULE_SHORT_RE.test(short)) {
+    return jsonError(400, "invalid_request", `module short "${short}" is not a valid identifier`);
+  }
+  // Vault is per-instance — its admin scope needs a vault name. Route the caller
+  // to the dedicated per-vault endpoint rather than minting a useless bare
+  // `vault:admin` (no vault validates that audience).
+  if (short === "vault") {
+    return jsonError(
+      400,
+      "use_vault_admin_token",
+      "vault admin tokens are per-instance — use GET /admin/vault-admin-token/<name>",
+    );
+  }
+  // Only mint for modules the hub can verify exist. Two paths (boundary C5 —
+  // closes the charter's third-party-test gap, where this endpoint used to
+  // require bootstrap-registry presence):
+  //   1. SELF-REGISTERED: the short resolves to a services.json row whose
+  //      installDir carries a readable module.json. This is the canonical
+  //      gate — any module (first- or third-party) that completed
+  //      self-registration mints with zero hub code changes, per
+  //      `parachute-patterns/patterns/hub-module-boundary.md` (the seam,
+  //      mechanism 1).
+  //   2. KNOWN bootstrap short (KNOWN_MODULES ∪ FIRST_PARTY_FALLBACKS): kept
+  //      as a fallback so a first-party module mid-install (row not yet
+  //      written) still mints.
+  // Either way a forged/typo'd short can't mint `<anything>:admin` and mask
+  // itself as a real (but unusable) credential.
+  if (!isKnownModuleShort(short) && !(await isSelfRegisteredModule(short, deps))) {
+    return jsonError(404, "not_found", `no module "${short}" known to this hub`);
+  }
+  const sid = parseSessionCookie(req.headers.get("cookie"));
+  const session = sid ? findSession(deps.db, sid) : null;
+  if (!session) {
+    return jsonError(401, "unauthenticated", "no admin session — sign in at /login first");
+  }
+  // First-admin gate (mirrors host/vault/channel-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)) {
+    return jsonError(
+      403,
+      "not_admin",
+      "module admin token mint is restricted to the hub admin — your account home is at /account/",
+    );
+  }
+  const scope = `${short}:admin`;
+  const minted = await signAccessToken(deps.db, {
+    sub: session.userId,
+    scopes: [scope],
+    // Bare service audience — modules validate `aud === <short>`, the same
+    // shape `inferAudience` stamps for the OAuth flow.
+    audience: short,
+    clientId: MODULE_TOKEN_CLIENT_ID,
+    issuer: deps.issuer,
+    ttlSeconds: MODULE_TOKEN_TTL_SECONDS,
+    // No per-user vault pin — this Bearer talks to a module-scoped endpoint,
+    // not a single vault. Empty `vault_scope` is the "no per-user restriction"
+    // sentinel, matching host-admin / channel tokens.
+    vaultScope: [],
+  });
+  return new Response(
+    JSON.stringify({
+      token: minted.token,
+      expires_at: minted.expiresAt,
+      scopes: [scope],
+    }),
+    {
+      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-vaults.ts

@@ -1,5 +1,7 @@
 /**
  * `POST /vaults` — provision a new vault on the host.
+ * `DELETE /vaults/<name>` — destroy a vault WITH the identity cascade
+ * (B1, 2026-06-09 hub-module-boundary migration — see `handleDeleteVault`).
  *
  * The hub's first authenticated, mutating endpoint. Until now the hub has
  * been a pure issuer; Phase 1 of the vault-config-and-scopes design (D1)
@@ -57,30 +59,29 @@
  */
 import type { Database } from "bun:sqlite";
 import { type AdminAuthError, adminAuthErrorResponse, requireScope } from "./admin-auth.ts";
+import { type ConnectionsDeps, teardownConnection } from "./admin-connections.ts";
 import { SERVICES_MANIFEST_PATH } from "./config.ts";
+import { readConnections } from "./connections-store.ts";
+import { rewriteGrantsRemovingVault } from "./grants.ts";
+import { revokeInvitesForVault } from "./invites.ts";
+import { revokeTokensNamingVault, signAccessToken } from "./jwt-sign.ts";
 import { findService, type readManifest, readManifestLenient } from "./services-manifest.ts";
 import { enrichedPath } from "./spawn-path.ts";
-import { VAULT_NAME_CHARSET_RE } from "./vault-name.ts";
+import { removeVaultAssignments } from "./users.ts";
+import { RESERVED_VAULT_NAMES, VAULT_NAME_CHARSET_RE } from "./vault-name.ts";
 import { type WellKnownVaultEntry, isVaultEntry, vaultInstanceNameFor } from "./well-known.ts";
 
 /** Scope required to call POST /vaults. */
 export const HOST_ADMIN_SCOPE = "parachute:host:admin";
 
-/**
- * Mirror parachute-vault's `cmdCreate` validation rules, plus hub-only
- * reservations for SPA-route shadowing. `list` matches the CLI; `new` and
- * `assets` would collide with `/vault/new` (the SPA's create-vault route)
- * and `/vault/assets/*` (the SPA's static asset bundle) respectively, so
- * the hub rejects them at the API edge before a vault under those names
- * can register and capture the proxy path.
- */
 // Lowercase-only (item I) — single source of truth in vault-name.ts. Vault's
 // init enforces `[a-z0-9_-]`; a hub-side `[a-zA-Z0-9_-]` superset let an
 // uppercased name through that vault would then lowercase or reject, drifting
-// the hub's idea of the vault from vault's. The hub-only reservations (`new`,
-// `assets`) shadow SPA routes and stay on top of vault's `list`.
+// the hub's idea of the vault from vault's. The reserved set is the ONE
+// consolidated `RESERVED_VAULT_NAMES` from vault-name.ts (B2h) — this file
+// used to carry its own `{list, new, assets}` copy that drifted from the
+// `{list}`-only set gating the wizard + invite redemption.
 const VAULT_NAME_PATTERN = VAULT_NAME_CHARSET_RE;
-const RESERVED_VAULT_NAMES = new Set(["list", "new", "assets"]);
 
 export interface CreateVaultRequest {
   name: string;
@@ -504,3 +505,380 @@ export async function handleCreateVault(req: Request, deps: CreateVaultDeps): Pr
     headers: { "content-type": "application/json" },
   });
 }
+
+// ===========================================================================
+// DELETE /vaults/<name> — the identity cascade (B1, 2026-06-09
+// hub-module-boundary migration: lifecycle symmetry)
+// ===========================================================================
+//
+// "Every provision flow must have a deprovision flow that cascades the
+// identity artifacts it created." Mechanics deletion without identity
+// cascade is a security hole: before B1, vault deletion was CLI-only
+// (`parachute-vault remove`) and left every hub-side identity artifact
+// naming the vault alive — scoped tokens, grants, user assignments, pinned
+// invites, connections. This handler enumerates the full artifact list and
+// handles every entry.
+//
+// Documented bound: short-lived (≤10-min) unregistered interactive mints
+// ride to expiry by design — the cascade revokes persisted registry rows
+// and publishes the revocation list; it does not claim instant revocation
+// of in-flight interactive JWTs.
+
+/** Client id stamped on the short-lived channel-scan mint. */
+const DELETE_VAULT_CLIENT_ID = "parachute-hub-spa";
+/** TTL for the cascade's interactive provisioning mints (channel scan). */
+const DELETE_VAULT_PROVISION_TTL_SECONDS = 60;
+
+export interface DeleteVaultDeps {
+  db: Database;
+  /** Hub origin — JWT `iss` validation + cascade mint issuer. */
+  issuer: string;
+  /** Override the services.json path. Defaults to `~/.parachute/services.json`. */
+  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;
+  /** Resolve a vault's loopback origin from services.json (trigger teardown). */
+  resolveVaultOrigin: (vaultName: string) => string | null;
+  /** Test seam: run `parachute-vault remove` — same Runner seam as create. */
+  runCommand?: CreateVaultDeps["runCommand"];
+  /**
+   * Supervisor-restart the vault module — the daemon-eviction cascade step.
+   * The running daemon caches open store handles, so rmSync alone leaves the
+   * deleted vault SERVING from the open fd; and vault's boot `selfRegister`
+   * rebuilds services.json paths from `listVaults()`, dropping the deleted
+   * path. Wired to the same supervisor machinery the lifecycle verbs use.
+   * Absent (no supervisor — CLI-mode hub, tests) → recorded as a warning in
+   * the response, not silently skipped. (The boundary-conformant per-daemon
+   * store-eviction endpoint is tracked as E9.)
+   */
+  restartVaultModule?: () => Promise<void>;
+  /** Test seam — `globalThis.fetch` in production. */
+  fetchImpl?: typeof fetch;
+  /** Test seam for the clock. */
+  now?: () => Date;
+}
+
+interface DeleteVaultBody {
+  confirm?: unknown;
+}
+
+/** Wire shape of the cascade summary in the 200/500 response. */
+interface CascadeSummary {
+  tokens_revoked: number;
+  grants_rewritten: number;
+  grants_dropped: number;
+  user_vaults_removed: number;
+  invites_invalidated: number;
+  connections_torn_down: number;
+  /**
+   * Vault-backed channel-daemon entries still referencing the deleted vault
+   * AFTER connection teardown (legacy pre-Connections wiring). Surfaced for
+   * the operator — the hub does NOT silently delete channel's config; remove
+   * them from channel's own UI.
+   */
+  orphaned_channels: string[];
+  vault_removed: boolean;
+  module_restarted: boolean;
+}
+
+function emptyCascadeSummary(): CascadeSummary {
+  return {
+    tokens_revoked: 0,
+    grants_rewritten: 0,
+    grants_dropped: 0,
+    user_vaults_removed: 0,
+    invites_invalidated: 0,
+    connections_torn_down: 0,
+    orphaned_channels: [],
+    vault_removed: false,
+    module_restarted: false,
+  };
+}
+
+/** Every vault instance name currently registered in services.json. */
+function listVaultInstanceNames(manifestPath: string): Set<string> {
+  const names = new Set<string>();
+  let manifest: ReturnType<typeof readManifest>;
+  try {
+    manifest = readManifestLenient(manifestPath);
+  } catch {
+    return names;
+  }
+  for (const svc of manifest.services) {
+    if (!isVaultEntry(svc)) continue;
+    if (svc.paths.length === 0) {
+      names.add(vaultInstanceNameFor(svc.name, undefined));
+      continue;
+    }
+    for (const path of svc.paths) names.add(vaultInstanceNameFor(svc.name, path));
+  }
+  return names;
+}
+
+/**
+ * `DELETE /vaults/<name>` — destroy a vault with the full identity cascade.
+ *
+ * Gate: Bearer `parachute:host:admin` (same gate as create). Body MUST carry
+ * `{"confirm": "<name>"}` — a deliberate retype-the-name guard against
+ * fat-finger disasters (mismatch → 400).
+ *
+ * Refusals:
+ *   - unknown vault → 404;
+ *   - LAST remaining vault → 409. Vault's boot auto-creates `default` at
+ *     zero vaults, so deleting the last one would silently resurrect a fresh
+ *     `default` (with a fresh global API key) — refusing sidesteps the
+ *     resurrection class entirely. The CLI (`parachute-vault remove`) is the
+ *     escape hatch for an operator who really means it.
+ *   - RESERVED names are deliberately ALLOWED (no reserved-name gate): a
+ *     squatted `admin`/`new`/`assets` vault created before the B2h
+ *     reservation must be removable through this endpoint.
+ *
+ * Cascade, in order (identity first, mechanics last — revocation is the safe
+ * direction if a later step fails):
+ *   1. tokens-registry sweep (exact scope-segment match — never SQL LIKE);
+ *   2. grants rewrite (drop `vault:<name>:*` entries; drop the row only when
+ *      it empties — a (user,client) grant can span multiple vaults);
+ *   3. `user_vaults` rows;
+ *   4. unredeemed invites pinned to the vault (redemption would resurrect
+ *      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`
+ *      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,
+ *      mirroring create);
+ *   7. daemon eviction: supervisor-restart the vault module (open
+ *      store-handle eviction + `selfRegister` services.json path rebuild).
+ *
+ * Response: 200 with a structured per-step summary (counts +
+ * `orphaned_channels` + warnings). A mechanics failure responds 500 with
+ * the partial summary — the identity artifacts already revoked stay revoked.
+ */
+export async function handleDeleteVault(
+  req: Request,
+  rawName: string,
+  deps: DeleteVaultDeps,
+): Promise<Response> {
+  if (req.method !== "DELETE") {
+    return new Response("method not allowed", { status: 405 });
+  }
+  const manifestPath = deps.manifestPath ?? SERVICES_MANIFEST_PATH;
+  const runCommand = deps.runCommand ?? defaultRunCommand;
+  const now = deps.now?.() ?? new Date();
+
+  // Auth gate: parachute:host:admin — the same gate as POST /vaults.
+  let adminSub: string;
+  try {
+    const auth = await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.issuer);
+    adminSub = auth.sub;
+  } catch (err) {
+    return adminAuthErrorResponse(err as AdminAuthError);
+  }
+
+  // Name shape guard. NOTE: no reserved-name check — see docstring.
+  const name = rawName.trim();
+  if (!VAULT_NAME_PATTERN.test(name)) {
+    return jsonError(
+      400,
+      "invalid_request",
+      "vault name must contain only lowercase letters, numbers, hyphens, and underscores",
+    );
+  }
+
+  // Confirm body — the retype-the-name guard.
+  let body: DeleteVaultBody;
+  try {
+    body = (await req.json()) as DeleteVaultBody;
+  } catch {
+    return jsonError(400, "confirm_mismatch", `body must be JSON: {"confirm": "${name}"}`);
+  }
+  if (!body || typeof body !== "object" || body.confirm !== name) {
+    return jsonError(
+      400,
+      "confirm_mismatch",
+      `deleting a vault requires the body {"confirm": "${name}"} (retype the vault name)`,
+    );
+  }
+
+  // Existence.
+  const existing = findExistingVault(manifestPath, name);
+  if (!existing) {
+    return jsonError(404, "not_found", `no vault named "${name}" on this hub`);
+  }
+
+  // Last-vault refusal (resurrection guard).
+  const instanceNames = listVaultInstanceNames(manifestPath);
+  instanceNames.delete(name);
+  if (instanceNames.size === 0) {
+    return jsonError(
+      409,
+      "last_vault",
+      `"${name}" is the last vault on this hub. Vault's boot auto-creates "default" at zero vaults, so deleting the last one would silently resurrect it with fresh credentials. Create another vault first, or use the CLI (parachute-vault remove ${name} --yes) if you really mean to empty the hub.`,
+    );
+  }
+
+  const summary = emptyCascadeSummary();
+  const warnings: { step: string; detail: string }[] = [];
+
+  // --- 1. Registry sweep: revoke every tokens row naming the vault. --------
+  summary.tokens_revoked = revokeTokensNamingVault(deps.db, name, now);
+
+  // NOTE on `auth_codes.scopes` — the one identity-artifact column from the
+  // charter's enumeration deliberately NOT swept here. Authorization codes
+  // are transient by construction: AUTH_CODE_TTL_SECONDS = 60 (auth-codes.ts)
+  // and single-use. A code naming the deleted vault either (a) expires
+  // unredeemed within the minute, or (b) redeems into tokens whose registry
+  // rows the sweep above already governs — and whose requests the evicted
+  // daemon no longer serves. Sweeping a 60-second-lived table adds a step
+  // with no security delta; same class as the documented ≤10-min
+  // unregistered interactive-mint bound.
+
+  // --- 2. Grants rewrite (drop rows only when emptied). ---------------------
+  const grants = rewriteGrantsRemovingVault(deps.db, name);
+  summary.grants_rewritten = grants.rewritten;
+  summary.grants_dropped = grants.dropped;
+
+  // --- 3. user_vaults assignments. ------------------------------------------
+  summary.user_vaults_removed = removeVaultAssignments(deps.db, name);
+
+  // --- 4. Unredeemed invites pinned to the vault. ----------------------------
+  summary.invites_invalidated = revokeInvitesForVault(deps.db, name, now);
+
+  // --- 5. Connections teardown (+ legacy channel scan, report-only). --------
+  // Runs BEFORE the CLI remove so the vault daemon is still alive to accept
+  // the trigger-deregister calls.
+  const connectionsDeps: ConnectionsDeps = {
+    db: deps.db,
+    hubOrigin: deps.issuer,
+    modules: [], // teardown never consults the catalog
+    resolveVaultOrigin: deps.resolveVaultOrigin,
+    channelOrigin: deps.channelOrigin,
+    storePath: deps.connectionsStorePath,
+    ...(deps.fetchImpl !== undefined ? { fetchImpl: deps.fetchImpl } : {}),
+    ...(deps.now !== undefined ? { now: deps.now } : {}),
+  };
+  const records = readConnections(deps.connectionsStorePath).filter(
+    (r) => r.source.vault === name || r.provisioned?.vault === name,
+  );
+  for (const record of records) {
+    try {
+      const res = await teardownConnection(record.id, adminSub, connectionsDeps);
+      if (res.status === 200) {
+        summary.connections_torn_down++;
+      } else {
+        // 207 partial — the record is removed + mints revoked; remote steps
+        // failed. Surface as warnings, count as torn down (the identity side
+        // is done; the operator can clean the remote residue).
+        summary.connections_torn_down++;
+        const out = (await res.json()) as { errors?: { step: string; detail: string }[] };
+        for (const e of out.errors ?? []) {
+          warnings.push({ step: `connection_${record.id}_${e.step}`, detail: e.detail });
+        }
+      }
+    } catch (err) {
+      warnings.push({
+        step: `connection_${record.id}`,
+        detail: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  // 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) {
+    try {
+      const fetchImpl = deps.fetchImpl ?? fetch;
+      // Short-lived (60s) — stays below the registered-mint threshold by
+      // design (the documented ≤10-min interactive bound; see B0's
+      // REGISTERED_MINT_TTL_THRESHOLD_SECONDS in admin-connections.ts).
+      const scanToken = (
+        await signAccessToken(deps.db, {
+          sub: adminSub,
+          scopes: ["channel:admin"],
+          audience: "channel",
+          clientId: DELETE_VAULT_CLIENT_ID,
+          issuer: deps.issuer,
+          ttlSeconds: DELETE_VAULT_PROVISION_TTL_SECONDS,
+          vaultScope: [],
+          ...(deps.now !== undefined ? { now: deps.now } : {}),
+        })
+      ).token;
+      const res = await fetchImpl(`${deps.channelOrigin}/api/channels`, {
+        headers: { authorization: `Bearer ${scanToken}`, accept: "application/json" },
+      });
+      if (res.ok) {
+        const listed = (await res.json()) as { channels?: unknown };
+        const rawList = Array.isArray(listed?.channels) ? listed.channels : [];
+        for (const c of rawList) {
+          const row = (c ?? {}) as Record<string, unknown>;
+          if (row.transport === "vault" && row.vault === name && typeof row.name === "string") {
+            summary.orphaned_channels.push(row.name);
+          }
+        }
+      } else {
+        warnings.push({ step: "channel_scan", detail: `channel list returned ${res.status}` });
+      }
+    } catch (err) {
+      warnings.push({
+        step: "channel_scan",
+        detail: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  // --- 6. Mechanics: the module CLI is the source of truth for destruction. -
+  try {
+    const result = await runCommand(["parachute-vault", "remove", name, "--yes"]);
+    if (result.exitCode !== 0) {
+      const stderrTail = result.stderr.trim();
+      const tailSuffix = stderrTail ? `: ${stderrTail.slice(-500)}` : "";
+      return jsonError(
+        500,
+        "server_error",
+        `parachute-vault remove ${name} --yes exited with code ${result.exitCode}${tailSuffix} — identity artifacts already revoked (summary: ${JSON.stringify(summary)})`,
+      );
+    }
+    summary.vault_removed = true;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return jsonError(
+      500,
+      "server_error",
+      `orchestration failed: ${msg} — identity artifacts already revoked (summary: ${JSON.stringify(summary)})`,
+    );
+  }
+
+  // --- 7. Daemon eviction: supervisor-restart the vault module. -------------
+  if (deps.restartVaultModule) {
+    try {
+      await deps.restartVaultModule();
+      summary.module_restarted = true;
+    } catch (err) {
+      warnings.push({
+        step: "module_restart",
+        detail: `vault module restart failed: ${err instanceof Error ? err.message : String(err)} — the running daemon may still serve the deleted vault from its open store handle until restarted (parachute restart vault)`,
+      });
+    }
+  } else {
+    warnings.push({
+      step: "module_restart",
+      detail:
+        "no supervisor available — restart the vault module (parachute restart vault) to evict the deleted vault's open store handle and refresh services.json",
+    });
+  }
+
+  return new Response(
+    JSON.stringify({
+      ok: true,
+      name,
+      cascade: summary,
+      ...(warnings.length > 0 ? { warnings } : {}),
+    }),
+    { status: 200, headers: { "content-type": "application/json" } },
+  );
+}

package/src/api-hub-upgrade.ts

@@ -4,9 +4,10 @@
  *
  * ── WHY A DEDICATED ENDPOINT (not /api/modules/hub/*) ──────────────────────
  *
- * The hub is NOT a supervised module — `CURATED_MODULES` rejects `hub`, so
- * `parseModulesPath("/api/modules/hub/upgrade")` returns undefined and the
- * module-ops switch never reaches a hub case. The hub needs its OWN endpoint
+ * The hub is NOT a supervised module — `parseModulesPath` rejects `hub`
+ * (`isKnownModuleShort("hub")` is false: hub isn't in KNOWN_MODULES /
+ * FIRST_PARTY_FALLBACKS), so `parseModulesPath("/api/modules/hub/upgrade")`
+ * returns undefined and the module-ops switch never reaches a hub case. The hub needs its OWN endpoint
  * because the constraint is unique: the hub can't restart itself synchronously
  * (the request dies with the old process before it can report success). So:
  *