@openparachute/hub 0.7.4-rc.2 → 0.7.4-rc.21

package/src/admin-agent-grants.ts

@@ -131,6 +131,16 @@ export interface AgentGrantsDeps {
    * (`<hubOrigin>/oauth/agent-grant/callback`).
    */
   hubOrigin: string;
+  /**
+   * SET of origins the hub answers on (loopback ∪ expose-state ∪ platform ∪
+   * per-request issuer), built via `buildHubBoundOrigins`. The module's
+   * host-admin bearer `iss` is validated against THIS set rather than the
+   * single `hubOrigin`, so the agent module's credential minted under a
+   * still-valid prior origin keeps working across an origin switch (hub#516
+   * parity). Minted tokens still carry `hubOrigin`. Absent → falls back to
+   * `[hubOrigin]` (the prior strict per-request behavior).
+   */
+  knownIssuers?: readonly string[];
   /** Absolute path to `agent-grants.json` in the hub state dir. */
   storePath: string;
   /** Absolute path to `agent-oauth-flows.json` (the in-flight OAuth consents, 4b-2). */
@@ -249,7 +259,12 @@ async function requireModuleAuth(
   deps: AgentGrantsDeps,
 ): Promise<AdminAuthContext | Response> {
   try {
-    return await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.hubOrigin);
+    return await requireScope(
+      deps.db,
+      req,
+      HOST_ADMIN_SCOPE,
+      deps.knownIssuers ?? [deps.hubOrigin],
+    );
   } catch (err) {
     return adminAuthErrorResponse(err as AdminAuthError);
   }

package/src/admin-auth.ts

@@ -59,15 +59,24 @@ export function extractBearerToken(req: Request): string {
  * and check it carries `requiredScope`. Returns surfaced claims on success;
  * throws `AdminAuthError` (401 or 403) otherwise.
  *
- * `expectedIssuer` MUST be the hub's own origin — the same value baked into
- * tokens we sign. Defense in depth: even though we can only verify our own
- * keys, the `iss` mismatch reject keeps cross-issuer confusion impossible.
+ * `expectedIssuer` is the hub's own origin(s) — the same value(s) baked into
+ * tokens we sign. Pass a single string for a single-origin hub, or the SET of
+ * origins the hub legitimately answers on (`buildHubBoundOrigins`: loopback ∪
+ * expose-state ∪ platform ∪ per-request issuer) so a credential minted under
+ * a still-valid prior origin keeps validating across an origin switch — the
+ * same multi-origin posture the OAuth path and `validateHostAdminToken`
+ * already use. Defense in depth: even though we can only verify our own keys,
+ * the `iss`-∈-set reject keeps cross-issuer confusion impossible. SECURITY:
+ * the set is ONLY an additive `iss` membership relaxation — `validateAccessToken`
+ * verifies the signature against the hub's own key FIRST, so only tokens this
+ * hub minted ever reach the `iss` check; never pass a raw request Host, only a
+ * `buildHubBoundOrigins`-derived set.
  */
 export async function requireScope(
   db: Database,
   req: Request,
   requiredScope: string,
-  expectedIssuer: string,
+  expectedIssuer: string | readonly string[],
 ): Promise<AdminAuthContext> {
   const token = extractBearerToken(req);
 

package/src/admin-clients.ts

@@ -4,8 +4,11 @@
  * without round-tripping through the `/oauth/authorize` flow (whose
  * `POST /oauth/authorize/approve` requires a `return_to` authorize URL).
  *
- *   GET  /api/oauth/clients/<client_id>            client details
- *   POST /api/oauth/clients/<client_id>/approve    flip status to approved
+ *   GET    /api/oauth/clients/<client_id>          client details
+ *   POST   /api/oauth/clients/<client_id>/approve  flip status to approved
+ *   DELETE /oauth/clients/<client_id>              deregister (RFC 7592) — note
+ *                                                  the TOP-LEVEL prefix, see
+ *                                                  handleDeleteClient
  *
  * Both gated by `parachute:host:admin` Bearer (same shape as /api/grants,
  * /api/auth/tokens, etc.). The SPA mints one via the session cookie at
@@ -54,13 +57,22 @@ import {
   requireScope,
 } from "./admin-auth.ts";
 import { HOST_ADMIN_SCOPE } from "./admin-vaults.ts";
-import { approveClient, getClient } from "./clients.ts";
+import { approveClient, deleteClient, getClient } from "./clients.ts";
 import { isSafeAuthorizeReturnTo } from "./oauth-handlers.ts";
 
 export interface AdminClientsDeps {
   db: Database;
   /** Hub origin — passed through to JWT validation as the expected `iss`. */
   issuer: string;
+  /**
+   * SET of origins the hub answers on (loopback ∪ expose-state ∪ platform ∪
+   * per-request `issuer`), built via `buildHubBoundOrigins`. The bearer's
+   * `iss` is validated against THIS set rather than the single `issuer`, so a
+   * credential minted under a still-valid prior origin keeps working across an
+   * origin switch (hub#516 parity). Absent → falls back to `[issuer]` (the
+   * prior strict per-request behavior; tests/non-HTTP callers unaffected).
+   */
+  knownIssuers?: readonly string[];
 }
 
 export interface AdminClientView {
@@ -90,7 +102,7 @@ export async function handleGetClient(
     return jsonError(405, "method_not_allowed", "use GET");
   }
   try {
-    await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.issuer);
+    await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.knownIssuers ?? [deps.issuer]);
   } catch (err) {
     return adminAuthErrorResponse(err as AdminAuthError);
   }
@@ -126,7 +138,7 @@ export async function handleApproveClient(
   }
   let ctx: AdminAuthContext;
   try {
-    ctx = await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.issuer);
+    ctx = await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.knownIssuers ?? [deps.issuer]);
   } catch (err) {
     return adminAuthErrorResponse(err as AdminAuthError);
   }
@@ -177,6 +189,55 @@ export async function handleApproveClient(
   });
 }
 
+/**
+ * RFC 7592 Dynamic Client Registration *deletion* (deregistration).
+ *
+ *   DELETE /oauth/clients/<client_id>    remove the client + its cascade
+ *
+ * Mounted at the TOP-LEVEL `/oauth/clients/` prefix (NOT under `/api/...`)
+ * because that's the path parachute-surface's remove-flow actually calls
+ * (`packages/surface-host/src/dcr.ts` → `DELETE <hub>/oauth/clients/<id>`),
+ * carrying the operator token as a Bearer. Before this route existed the
+ * hub 404'd every such DELETE, so every Notes/Claude reconnect orphaned a
+ * `clients` row in the operator's DB (closes hub#640, 4/5 boxes — the GC
+ * reaper for legacy orphans is a separate follow-up).
+ *
+ * Auth mirrors `handleGetClient`: `parachute:host:admin` Bearer via
+ * `requireScope`. Returns 204 (no content) on a successful delete, 404 when
+ * the client isn't registered — the same shape the surface already tolerates
+ * (`hubDeleteStatus: "ok"` on 200/204, `"not_found"` on a JSON 404).
+ *
+ * Audit: emits a `client deleted: ...` line in the same `key=value` shape as
+ * the `client approved: ...` line, so cross-machine "who removed this client"
+ * is greppable in hub.log.
+ */
+export async function handleDeleteClient(
+  req: Request,
+  clientId: string,
+  deps: AdminClientsDeps,
+): Promise<Response> {
+  if (req.method !== "DELETE") {
+    return jsonError(405, "method_not_allowed", "use DELETE");
+  }
+  let ctx: AdminAuthContext;
+  try {
+    ctx = await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.knownIssuers ?? [deps.issuer]);
+  } catch (err) {
+    return adminAuthErrorResponse(err as AdminAuthError);
+  }
+  // Capture the name BEFORE deleting so the audit line can carry it.
+  const before = getClient(deps.db, clientId);
+  const removed = deleteClient(deps.db, clientId);
+  if (!removed) {
+    return jsonError(404, "not_found", `no client registered with id ${clientId}`);
+  }
+  console.log(
+    `client deleted: client_id=${clientId} client_name=${before?.clientName ?? ""} remover_sub=${ctx.sub}`,
+  );
+  // 204 No Content — RFC 7592 §2.3 prescribes 204 for a successful delete.
+  return new Response(null, { status: 204, headers: { "cache-control": "no-store" } });
+}
+
 interface ApproveClientResponse {
   client_id: string;
   status: "approved";

package/src/admin-grants.ts

@@ -38,6 +38,15 @@ export interface AdminGrantsDeps {
   db: Database;
   /** Hub origin — passed through to JWT validation as the expected `iss`. */
   issuer: string;
+  /**
+   * SET of origins the hub answers on (loopback ∪ expose-state ∪ platform ∪
+   * per-request `issuer`), built via `buildHubBoundOrigins`. The bearer's
+   * `iss` is validated against THIS set rather than the single `issuer`, so a
+   * credential minted under a still-valid prior origin keeps working across an
+   * origin switch (hub#516 parity). Absent → falls back to `[issuer]` (the
+   * prior strict per-request behavior; tests/non-HTTP callers unaffected).
+   */
+  knownIssuers?: readonly string[];
 }
 
 export interface AdminGrantListing {
@@ -55,7 +64,7 @@ export async function handleListGrants(req: Request, deps: AdminGrantsDeps): Pro
   }
   let ctx: AdminAuthContext;
   try {
-    ctx = await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.issuer);
+    ctx = await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.knownIssuers ?? [deps.issuer]);
   } catch (err) {
     return adminAuthErrorResponse(err as AdminAuthError);
   }
@@ -111,7 +120,7 @@ export async function handleRevokeGrant(
   }
   let ctx: AdminAuthContext;
   try {
-    ctx = await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.issuer);
+    ctx = await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.knownIssuers ?? [deps.issuer]);
   } catch (err) {
     return adminAuthErrorResponse(err as AdminAuthError);
   }

package/src/admin-vaults.ts

@@ -129,6 +129,15 @@ export interface CreateVaultDeps {
   db: Database;
   /** Hub origin used to validate JWT `iss` and to build the response `url`. */
   issuer: string;
+  /**
+   * SET of origins the hub legitimately answers on (loopback ∪ expose-state ∪
+   * platform ∪ per-request `issuer`), built via `buildHubBoundOrigins`. The
+   * admin bearer's `iss` is validated against THIS set rather than the single
+   * `issuer`, so a host-admin credential minted under a still-valid prior
+   * origin keeps working across an origin switch (hub#516 parity). Absent →
+   * falls back to `[issuer]` (the prior strict per-request behavior).
+   */
+  knownIssuers?: readonly string[];
   /** Override the services.json path. Defaults to `~/.parachute/services.json`. */
   manifestPath?: string;
   /**
@@ -207,15 +216,11 @@ function findExistingVault(
   } catch {
     return null;
   }
-  const target = `/vault/${name}`;
   for (const svc of manifest.services) {
     if (!isVaultEntry(svc)) continue;
-    if (svc.paths.length === 0) {
-      if (vaultInstanceNameFor(svc.name, undefined) === name) {
-        return { url: target, version: svc.version, path: target };
-      }
-      continue;
-    }
+    // #478: an empty-paths vault row means "installed but no servable vault
+    // instance" — skip it entirely so it never resolves to a phantom "default".
+    if (svc.paths.length === 0) continue;
     for (const path of svc.paths) {
       if (vaultInstanceNameFor(svc.name, path) === name) {
         return { url: path, version: svc.version, path };
@@ -446,7 +451,7 @@ export async function handleCreateVault(req: Request, deps: CreateVaultDeps): Pr
   // Auth gate: parachute:host:admin scope. Maps an AdminAuthError straight
   // to an RFC 6750 401/403 — the route handler doesn't care which.
   try {
-    await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.issuer);
+    await requireScope(deps.db, req, HOST_ADMIN_SCOPE, deps.knownIssuers ?? [deps.issuer]);
   } catch (err) {
     return adminAuthErrorResponse(err as AdminAuthError);
   }
@@ -534,6 +539,15 @@ export interface DeleteVaultDeps {
   db: Database;
   /** Hub origin — JWT `iss` validation + cascade mint issuer. */
   issuer: string;
+  /**
+   * SET of origins the hub legitimately answers on (loopback ∪ expose-state ∪
+   * platform ∪ per-request `issuer`), built via `buildHubBoundOrigins`. The
+   * admin bearer's `iss` is validated against THIS set rather than the single
+   * `issuer`, so a host-admin credential minted under a still-valid prior
+   * origin keeps working across an origin switch (hub#516 parity). Absent →
+   * falls back to `[issuer]` (the prior strict per-request behavior).
+   */
+  knownIssuers?: readonly string[];
   /** Override the services.json path. Defaults to `~/.parachute/services.json`. */
   manifestPath?: string;
   /** Absolute path to `connections.json` in the hub state dir. */
@@ -607,7 +621,7 @@ function emptyCascadeSummary(): CascadeSummary {
 }
 
 /** Every vault instance name currently registered in services.json. */
-function listVaultInstanceNames(manifestPath: string): Set<string> {
+export function listVaultInstanceNames(manifestPath: string): Set<string> {
   const names = new Set<string>();
   let manifest: ReturnType<typeof readManifest>;
   try {
@@ -617,10 +631,9 @@ function listVaultInstanceNames(manifestPath: string): Set<string> {
   }
   for (const svc of manifest.services) {
     if (!isVaultEntry(svc)) continue;
-    if (svc.paths.length === 0) {
-      names.add(vaultInstanceNameFor(svc.name, undefined));
-      continue;
-    }
+    // #478: an empty-paths vault row means "installed but no servable vault
+    // instance" — skip it so no phantom "default" is synthesized.
+    if (svc.paths.length === 0) continue;
     for (const path of svc.paths) names.add(vaultInstanceNameFor(svc.name, path));
   }
   return names;
@@ -635,15 +648,22 @@ function listVaultInstanceNames(manifestPath: string): Set<string> {
  *
  * 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.
  *
+ * Last-vault handling (#678): deleting the LAST remaining vault runs the SAME
+ * cascade-then-delete as any other vault — it is NOT refused. The old 409 that
+ * steered the operator to the raw `parachute-vault remove` CLI was a
+ * correctness defect: that escape hatch SKIPS this cascade, orphaning tokens +
+ * grants that named the last vault. The resurrection risk the refusal once
+ * guarded (vault boot auto-creating a fresh-credentialed first vault at zero
+ * vaults) is handled downstream instead: the vault CLI writes an
+ * `auto_create: false` marker on last-vault removal and the vault boot gate
+ * honors it, so the server won't silently resurrect. Detection stays
+ * count-based + name-agnostic (no `name === "default"` special case); the last
+ * vault just adds a `last_vault` warning to the 200 response.
+ *
  * 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);
@@ -666,6 +686,15 @@ function listVaultInstanceNames(manifestPath: string): Set<string> {
  * 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.
+ *
+ * Bounded residual: the cascade revokes every *registered* token row naming
+ * the vault, but an UNREGISTERED interactive-mint (a host-admin browser
+ * session minting a short-lived vault token at ≤10-min TTL — see
+ * REGISTERED_MINT_TTL_THRESHOLD_SECONDS in admin-connections.ts) that was
+ * issued just before the delete leaves no registry row to sweep. Such a token
+ * stays valid for at most its remaining ≤10-min TTL, against a vault whose
+ * daemon is evicted in step 7 anyway. Same bound the auth-codes note below
+ * relies on; not eliminated, just bounded.
  */
 export async function handleDeleteVault(
   req: Request,
@@ -682,7 +711,12 @@ export async function handleDeleteVault(
   // 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);
+    const auth = await requireScope(
+      deps.db,
+      req,
+      HOST_ADMIN_SCOPE,
+      deps.knownIssuers ?? [deps.issuer],
+    );
     adminSub = auth.sub;
   } catch (err) {
     return adminAuthErrorResponse(err as AdminAuthError);
@@ -719,16 +753,20 @@ export async function handleDeleteVault(
     return jsonError(404, "not_found", `no vault named "${name}" on this hub`);
   }
 
-  // Last-vault refusal (resurrection guard).
+  // Last-vault detection (count-based, name-agnostic). Deleting the LAST
+  // vault used to refuse with 409 and steer the operator to the raw
+  // `parachute-vault remove` CLI — but that path SKIPS this whole identity
+  // cascade, orphaning tokens + grants that named the vault. The resurrection
+  // risk the refusal guarded against is already handled downstream: the vault
+  // CLI writes an `auto_create: false` marker when it removes the last vault
+  // (vault `cli.ts` cmdRemove) and the vault boot gate honors it
+  // (`bootAutoCreateAllowed` in vault `config.ts`), so the server won't
+  // silently resurrect a fresh-credentialed first vault. We therefore run the
+  // cascade-then-delete for the last vault exactly as for any other — the
+  // count is informational only (no refusal).
   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 isLastVault = instanceNames.size === 0;
 
   const summary = emptyCascadeSummary();
   const warnings: { step: string; detail: string }[] = [];
@@ -870,6 +908,18 @@ export async function handleDeleteVault(
     );
   }
 
+  // Last-vault heads-up. The vault CLI's remove wrote `auto_create: false`, so
+  // the next vault boot won't resurrect a fresh-credentialed first vault — the
+  // hub is now deliberately empty. Surface that so the operator knows to create
+  // one when they want the hub serving again.
+  if (isLastVault) {
+    warnings.push({
+      step: "last_vault",
+      detail:
+        "the deleted vault was the last one on this hub — no vaults remain. The vault CLI wrote auto_create: false, so boot won't recreate a default vault. Create one with: parachute-vault create <name>",
+    });
+  }
+
   // --- 7. Daemon eviction: supervisor-restart the vault module. -------------
   if (deps.restartVaultModule) {
     try {