@openparachute/hub 0.7.4-rc.11 → 0.7.4-rc.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.7.4-rc.11",
+  "version": "0.7.4-rc.13",
   "description": "parachute — the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {

package/src/__tests__/admin-clients.test.ts

@@ -12,8 +12,9 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { handleApproveClient, handleGetClient } from "../admin-clients.ts";
+import { handleApproveClient, handleDeleteClient, handleGetClient } from "../admin-clients.ts";
 import { approveClient, getClient, registerClient } from "../clients.ts";
+import { findGrant, recordGrant } from "../grants.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
 import { signAccessToken } from "../jwt-sign.ts";
 import { createUser } from "../users.ts";
@@ -83,6 +84,23 @@ function approveReq(clientId: string, bearer?: string, method = "POST"): Request
   return new Request(`${ISSUER}/api/oauth/clients/${encodeURIComponent(clientId)}/approve`, init);
 }
 
+// DELETE hits the TOP-LEVEL /oauth/clients/<id> prefix (the path the surface
+// remove-flow calls), not the /api/... admin prefix the GET/approve use.
+function deleteReq(clientId: string, bearer?: string, method = "DELETE"): Request {
+  const init: RequestInit = { method };
+  if (bearer) init.headers = { authorization: `Bearer ${bearer}` };
+  return new Request(`${ISSUER}/oauth/clients/${encodeURIComponent(clientId)}`, init);
+}
+
+function regApproved(name?: string): string {
+  const r = registerClient(harness.db, {
+    redirectUris: ["https://app.example/cb"],
+    scopes: ["vault:work:read"],
+    ...(name !== undefined ? { clientName: name } : {}),
+  });
+  return r.client.clientId;
+}
+
 describe("handleGetClient", () => {
   test("401 without Bearer", async () => {
     const id = regPending("App");
@@ -460,3 +478,87 @@ describe("handleApproveClient", () => {
     });
   });
 });
+
+// hub#640 — RFC 7592 client deregistration. The surface fires DELETE on the
+// top-level /oauth/clients/<id> path; the handler is operator-bearer-gated,
+// returns 204 on delete (cascading grants + auth_codes), 404 when absent.
+describe("handleDeleteClient", () => {
+  test("401 without Bearer (row survives)", async () => {
+    const id = regApproved("App");
+    const res = await handleDeleteClient(deleteReq(id), id, {
+      db: harness.db,
+      issuer: ISSUER,
+    });
+    expect(res.status).toBe(401);
+    expect(getClient(harness.db, id)).not.toBeNull();
+  });
+
+  test("403 with the wrong scope (row survives)", async () => {
+    const { bearer } = await makeOperatorBearer(["parachute:host:auth"]);
+    const id = regApproved("App");
+    const res = await handleDeleteClient(deleteReq(id, bearer), id, {
+      db: harness.db,
+      issuer: ISSUER,
+    });
+    expect(res.status).toBe(403);
+    expect(getClient(harness.db, id)).not.toBeNull();
+  });
+
+  test("204 on an existing client + cascade gone + audit line", async () => {
+    const { bearer, userId } = await makeOperatorBearer();
+    const id = regApproved("Notes");
+    // Plant a grant so the cascade has something to remove.
+    recordGrant(harness.db, userId, id, ["vault:work:read"]);
+    expect(findGrant(harness.db, userId, id)).not.toBeNull();
+
+    const logs: string[] = [];
+    const originalLog = console.log;
+    console.log = (...args: unknown[]) => {
+      logs.push(args.map(String).join(" "));
+    };
+    let res: Response;
+    try {
+      res = await handleDeleteClient(deleteReq(id, bearer), id, {
+        db: harness.db,
+        issuer: ISSUER,
+      });
+    } finally {
+      console.log = originalLog;
+    }
+    expect(res.status).toBe(204);
+    // 204 carries no body.
+    expect(await res.text()).toBe("");
+    // Client + its grant are gone.
+    expect(getClient(harness.db, id)).toBeNull();
+    expect(findGrant(harness.db, userId, id)).toBeNull();
+
+    const line = logs.find((l) => l.startsWith("client deleted:"));
+    expect(line).toBeDefined();
+    expect(line).toContain(`client_id=${id}`);
+    expect(line).toContain("client_name=Notes");
+    expect(line).toContain(`remover_sub=${userId}`);
+  });
+
+  test("404 on an absent client_id", async () => {
+    const { bearer } = await makeOperatorBearer();
+    const res = await handleDeleteClient(deleteReq("nope", bearer), "nope", {
+      db: harness.db,
+      issuer: ISSUER,
+    });
+    expect(res.status).toBe(404);
+    const body = (await res.json()) as Record<string, unknown>;
+    expect(body.error).toBe("not_found");
+  });
+
+  test("405 on a non-DELETE method", async () => {
+    const { bearer } = await makeOperatorBearer();
+    const id = regApproved();
+    const res = await handleDeleteClient(deleteReq(id, bearer, "GET"), id, {
+      db: harness.db,
+      issuer: ISSUER,
+    });
+    expect(res.status).toBe(405);
+    // Row untouched.
+    expect(getClient(harness.db, id)).not.toBeNull();
+  });
+});

package/src/__tests__/admin-vaults.test.ts

@@ -940,27 +940,70 @@ describe("DELETE /vaults/<name> — gates", () => {
     }
   });
 
-  test("409 last_vault on the only remaining vault (CLI never runs)", async () => {
+  test("#678: deleting the LAST vault cascades + deletes (no 409), with a last_vault warning", async () => {
     const h = makeHarness();
     try {
       const db = openHubDb(hubDbPath(h.dir));
       try {
         rotateSigningKey(db);
-        writeVaults(h.manifestPath, ["default"]);
+        // Only one vault on the hub — the previously-refused last-vault case.
+        writeVaults(h.manifestPath, ["solo"]);
+
+        // Seed identity artifacts naming the soon-to-be-deleted last vault.
+        registryRow(db, "jti-solo", ["vault:solo:write"]);
+        const carol = await createUser(db, "carol", "carol-passphrase-123");
+        const client = registerClient(db, { redirectUris: ["https://d.example/cb"] }).client
+          .clientId;
+        recordGrant(db, carol.id, client, ["vault:solo:admin"]);
+        setUserVaults(db, carol.id, ["solo"]);
+
         const runner = stubRun();
         const res = await callDelete({
-          name: "default",
+          name: "solo",
           db,
           manifestPath: h.manifestPath,
           connectionsStorePath: join(h.dir, "connections.json"),
           runCommand: runner.run,
         });
-        expect(res.status).toBe(409);
-        const out = (await res.json()) as { error: string; error_description: string };
-        expect(out.error).toBe("last_vault");
-        // Guidance names the CLI escape hatch + the resurrection reason.
-        expect(out.error_description).toContain("parachute-vault remove");
-        expect(runner.calls.length).toBe(0);
+
+        // No 409 — the delete completes.
+        expect(res.status).toBe(200);
+        const out = (await res.json()) as {
+          ok: boolean;
+          cascade: {
+            tokens_revoked: number;
+            grants_dropped: number;
+            user_vaults_removed: number;
+            vault_removed: boolean;
+          };
+          warnings?: { step: string; detail: string }[];
+        };
+        expect(out.ok).toBe(true);
+
+        // The cascade ran for the last vault: tokens/grants/assignments gone.
+        expect(out.cascade.tokens_revoked).toBe(1);
+        expect(findTokenRowByJti(db, "jti-solo")?.revokedAt).not.toBeNull();
+        expect(out.cascade.grants_dropped).toBe(1);
+        expect(findGrant(db, carol.id, client)).toBeNull();
+        expect(out.cascade.user_vaults_removed).toBe(1);
+        expect(
+          db
+            .query<{ vault_name: string }, [string]>(
+              "SELECT vault_name FROM user_vaults WHERE user_id = ?",
+            )
+            .all(carol.id),
+        ).toEqual([]);
+
+        // The underlying vault remove ran (the cascade no longer skips it).
+        expect(runner.calls).toContainEqual(["parachute-vault", "remove", "solo", "--yes"]);
+        expect(out.cascade.vault_removed).toBe(true);
+
+        // A last_vault heads-up warning is surfaced (name-agnostic — does not
+        // assume "default"); the auto_create:false marker prevents resurrection.
+        const lastVaultWarning = out.warnings?.find((w) => w.step === "last_vault");
+        expect(lastVaultWarning).toBeDefined();
+        expect(lastVaultWarning?.detail).toContain("auto_create: false");
+        expect(lastVaultWarning?.detail).not.toContain('"default"');
       } finally {
         db.close();
       }

package/src/__tests__/auth.test.ts

@@ -849,6 +849,75 @@ describe("parachute auth pending-clients / approve-client", () => {
   });
 });
 
+// hub#640 — RFC 7592 deregistration from the terminal.
+describe("parachute auth revoke-client", () => {
+  test("revoke-client without an arg is a usage error", async () => {
+    const tmp = makeTmp();
+    try {
+      const deps: AuthDeps = { dbPath: tmp.dbPath };
+      const { code, stderr } = await captureOutput(() => auth(["revoke-client"], deps));
+      expect(code).toBe(1);
+      expect(stderr).toContain("missing client_id");
+    } finally {
+      tmp.cleanup();
+    }
+  });
+
+  test("revoke-client <unknown> exits 1 with a friendly message", async () => {
+    const tmp = makeTmp();
+    try {
+      const deps: AuthDeps = { dbPath: tmp.dbPath };
+      const { code, stderr } = await captureOutput(() => auth(["revoke-client", "no-such"], deps));
+      expect(code).toBe(1);
+      expect(stderr).toContain("no OAuth client");
+    } finally {
+      tmp.cleanup();
+    }
+  });
+
+  test("revoke-client deletes the client + cascades its grant + emits audit line", async () => {
+    const tmp = makeTmp();
+    try {
+      const db = openHubDb(tmp.dbPath);
+      let userId: string;
+      let clientId: string;
+      try {
+        const user = await createUser(db, "owner", "pw");
+        userId = user.id;
+        clientId = registerClient(db, {
+          redirectUris: ["https://app.example/cb"],
+          clientName: "MyApp",
+        }).client.clientId;
+        recordGrant(db, userId, clientId, ["vault:work:read"]);
+        expect(findGrant(db, userId, clientId)).not.toBeNull();
+      } finally {
+        db.close();
+      }
+      const deps: AuthDeps = { dbPath: tmp.dbPath };
+      const { code, stdout } = await captureOutput(() => auth(["revoke-client", clientId], deps));
+      expect(code).toBe(0);
+      expect(stdout).toContain("Deregistered OAuth client");
+      // Audit line for greppability (matches the route's shape, remover_sub=cli).
+      expect(stdout).toContain(`client deleted: client_id=${clientId}`);
+      expect(stdout).toContain("client_name=MyApp");
+      expect(stdout).toContain("remover_sub=cli");
+
+      // Verify the cascade actually landed in the db.
+      const db2 = openHubDb(tmp.dbPath);
+      try {
+        expect(
+          db2.query("SELECT client_id FROM clients WHERE client_id = ?").get(clientId),
+        ).toBeNull();
+        expect(findGrant(db2, userId, clientId)).toBeNull();
+      } finally {
+        db2.close();
+      }
+    } finally {
+      tmp.cleanup();
+    }
+  });
+});
+
 // closes #75 — operator-facing controls for the OAuth consent skip-list.
 describe("parachute auth list-grants / revoke-grant", () => {
   test("list-grants shows the seeding hint when no users exist", async () => {

package/src/__tests__/clients.test.ts

@@ -2,9 +2,11 @@ import { describe, expect, test } from "bun:test";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { issueAuthCode } from "../auth-codes.ts";
 import {
   InvalidRedirectUriError,
   approveClient,
+  deleteClient,
   expandRedirectUrisForHubOrigins,
   getClient,
   isValidRedirectUri,
@@ -13,7 +15,9 @@ import {
   requireRegisteredRedirectUri,
   verifyClientSecret,
 } from "../clients.ts";
+import { findGrant, recordGrant } from "../grants.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
+import { createUser } from "../users.ts";
 
 function makeDb() {
   const configDir = mkdtempSync(join(tmpdir(), "phub-clients-"));
@@ -341,6 +345,91 @@ describe("approval gate (#74)", () => {
   });
 });
 
+describe("deleteClient cascade (hub#640 RFC 7592 deregistration)", () => {
+  test("returns false for an unknown client_id (nothing to delete)", () => {
+    const { db, cleanup } = makeDb();
+    try {
+      expect(deleteClient(db, "no-such-client")).toBe(false);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("deletes the client row and reports true", () => {
+    const { db, cleanup } = makeDb();
+    try {
+      const r = registerClient(db, { redirectUris: ["https://app.example/cb"] });
+      expect(getClient(db, r.client.clientId)).not.toBeNull();
+      expect(deleteClient(db, r.client.clientId)).toBe(true);
+      expect(getClient(db, r.client.clientId)).toBeNull();
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("cascades dependent grants + auth_codes (FK ON, no ON DELETE CASCADE)", async () => {
+    const { db, cleanup } = makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const r = registerClient(db, {
+        redirectUris: ["https://app.example/cb"],
+        scopes: ["vault:work:read"],
+      });
+      const clientId = r.client.clientId;
+
+      // Plant a live grant + auth_code that reference the client. Without the
+      // cascade, the bare DELETE FROM clients would throw a FK violation while
+      // these rows exist (PRAGMA foreign_keys = ON).
+      recordGrant(db, user.id, clientId, ["vault:work:read"]);
+      const ac = issueAuthCode(db, {
+        clientId,
+        userId: user.id,
+        redirectUri: "https://app.example/cb",
+        scopes: ["vault:work:read"],
+        codeChallenge: "x".repeat(43),
+        codeChallengeMethod: "S256",
+      });
+      // Sanity: the dependents are present before the delete.
+      expect(findGrant(db, user.id, clientId)).not.toBeNull();
+      expect(db.query("SELECT code FROM auth_codes WHERE code = ?").get(ac.code)).not.toBeNull();
+
+      // Delete cascades — no FK throw, true returned.
+      expect(deleteClient(db, clientId)).toBe(true);
+
+      // Client + both dependents are gone.
+      expect(getClient(db, clientId)).toBeNull();
+      expect(findGrant(db, user.id, clientId)).toBeNull();
+      expect(db.query("SELECT code FROM auth_codes WHERE code = ?").get(ac.code)).toBeNull();
+      // The user row is untouched — only client-keyed rows cascade.
+      expect(db.query("SELECT id FROM users WHERE id = ?").get(user.id)).not.toBeNull();
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("transactional: deleting one client leaves a sibling client's grants intact", async () => {
+    const { db, cleanup } = makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const keep = registerClient(db, { redirectUris: ["https://keep.example/cb"] });
+      const drop = registerClient(db, { redirectUris: ["https://drop.example/cb"] });
+      recordGrant(db, user.id, keep.client.clientId, ["vault:work:read"]);
+      recordGrant(db, user.id, drop.client.clientId, ["vault:work:read"]);
+
+      expect(deleteClient(db, drop.client.clientId)).toBe(true);
+
+      // The kept client + its grant survive; only the dropped client's
+      // grant cascaded.
+      expect(getClient(db, keep.client.clientId)).not.toBeNull();
+      expect(findGrant(db, user.id, keep.client.clientId)).not.toBeNull();
+      expect(getClient(db, drop.client.clientId)).toBeNull();
+      expect(findGrant(db, user.id, drop.client.clientId)).toBeNull();
+    } finally {
+      cleanup();
+    }
+  });
+});
+
 describe("isValidRedirectUri", () => {
   test("accepts http and https", () => {
     expect(isValidRedirectUri("http://localhost:3000/cb")).toBe(true);

package/src/__tests__/cors.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { getClient, registerClient } from "../clients.ts";
 import {
   CORS_PREFLIGHT_HEADERS,
   CORS_RESPONSE_HEADERS,
@@ -11,7 +12,9 @@ import {
 } from "../cors.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
 import { hubFetch } from "../hub-server.ts";
+import { signAccessToken } from "../jwt-sign.ts";
 import { writeManifest } from "../services-manifest.ts";
+import { createUser } from "../users.ts";
 
 const GITCOIN_BRAIN_ORIGIN = "https://unforced-dev.github.io";
 const EXAMPLE_ORIGIN = "https://example.com";
@@ -51,10 +54,12 @@ describe("cors helper module", () => {
     expect(CORS_RESPONSE_HEADERS["access-control-expose-headers"]).toContain("WWW-Authenticate");
   });
 
-  test("CORS_PREFLIGHT_HEADERS announces GET + POST + OPTIONS and standard request headers", () => {
+  test("CORS_PREFLIGHT_HEADERS announces GET + POST + DELETE + OPTIONS and standard request headers", () => {
     const methods = CORS_PREFLIGHT_HEADERS["access-control-allow-methods"] ?? "";
     expect(methods).toContain("GET");
     expect(methods).toContain("POST");
+    // DELETE for RFC 7592 client deregistration (hub#640).
+    expect(methods).toContain("DELETE");
     expect(methods).toContain("OPTIONS");
     const headers = CORS_PREFLIGHT_HEADERS["access-control-allow-headers"] ?? "";
     expect(headers).toContain("Authorization");
@@ -585,3 +590,135 @@ describe("hubFetch CORS scope discipline — out-of-scope routes stay same-origi
     }
   });
 });
+
+// hub#640 — confirm the TOP-LEVEL DELETE /oauth/clients/<id> route is wired
+// into the real dispatch (not just the handler in isolation). This is the
+// load-bearing "right prefix" check: the surface remove-flow fires DELETE at
+// exactly this path, and before this route the hub 404'd it. Goes through
+// hubFetch so the dispatch order + the path-prefix branch are exercised.
+describe("hub#640 DELETE /oauth/clients/<id> dispatch (RFC 7592)", () => {
+  async function operatorBearer(db: ReturnType<typeof openHubDb>): Promise<string> {
+    const user = await createUser(db, "owner", "pw");
+    const minted = await signAccessToken(db, {
+      sub: user.id,
+      scopes: ["parachute:host:admin"],
+      audience: "hub",
+      clientId: "parachute-hub-spa",
+      issuer: ISSUER,
+      ttlSeconds: 600,
+    });
+    return minted.token;
+  }
+
+  test("204 + row gone with a valid operator Bearer (the surface remove-flow path)", async () => {
+    const h = makeHarness();
+    try {
+      writeManifest({ services: [] }, h.manifestPath);
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const bearer = await operatorBearer(db);
+        const id = registerClient(db, {
+          redirectUris: ["https://app.example/cb"],
+          clientName: "Notes",
+        }).client.clientId;
+
+        const res = await hubFetch(h.dir, {
+          getDb: () => db,
+          issuer: ISSUER,
+          manifestPath: h.manifestPath,
+        })(
+          new Request(`${ISSUER}/oauth/clients/${encodeURIComponent(id)}`, {
+            method: "DELETE",
+            headers: { authorization: `Bearer ${bearer}` },
+          }),
+        );
+        expect(res.status).toBe(204);
+        expect(getClient(db, id)).toBeNull();
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("401 without a Bearer — the route is auth-gated, not open", async () => {
+    const h = makeHarness();
+    try {
+      writeManifest({ services: [] }, h.manifestPath);
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const id = registerClient(db, {
+          redirectUris: ["https://app.example/cb"],
+        }).client.clientId;
+        const res = await hubFetch(h.dir, {
+          getDb: () => db,
+          issuer: ISSUER,
+          manifestPath: h.manifestPath,
+        })(
+          new Request(`${ISSUER}/oauth/clients/${encodeURIComponent(id)}`, {
+            method: "DELETE",
+          }),
+        );
+        expect(res.status).toBe(401);
+        // Row survives an unauthenticated DELETE.
+        expect(getClient(db, id)).not.toBeNull();
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("404 for an absent client_id through dispatch (matches surface 'not_found')", async () => {
+    const h = makeHarness();
+    try {
+      writeManifest({ services: [] }, h.manifestPath);
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const bearer = await operatorBearer(db);
+        const res = await hubFetch(h.dir, {
+          getDb: () => db,
+          issuer: ISSUER,
+          manifestPath: h.manifestPath,
+        })(
+          new Request(`${ISSUER}/oauth/clients/no-such-client`, {
+            method: "DELETE",
+            headers: { authorization: `Bearer ${bearer}` },
+          }),
+        );
+        expect(res.status).toBe(404);
+        // The surface keys off a JSON 404 → hubDeleteStatus "not_found".
+        const body = (await res.json()) as Record<string, unknown>;
+        expect(body.error).toBe("not_found");
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("OPTIONS preflight on the DELETE path advertises DELETE in Allow-Methods", async () => {
+    const h = makeHarness();
+    try {
+      writeManifest({ services: [] }, h.manifestPath);
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        const res = await hubFetch(h.dir, {
+          getDb: () => db,
+          issuer: ISSUER,
+          manifestPath: h.manifestPath,
+        })(preflight("/oauth/clients/some-id", EXAMPLE_ORIGIN));
+        expect(res.status).toBe(204);
+        expect(res.headers.get("access-control-allow-methods")).toContain("DELETE");
+        expect(res.headers.get("access-control-allow-origin")).toBe(EXAMPLE_ORIGIN);
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+});

package/src/__tests__/vault-remove.test.ts

@@ -83,6 +83,7 @@ const SUCCESS_BODY = {
     grants_dropped: 2,
     user_vaults_removed: 4,
     invites_invalidated: 1,
+    vault_cap_removed: true,
     connections_torn_down: 1,
     orphaned_channels: [],
     vault_removed: true,
@@ -156,6 +157,7 @@ describe("vaultRemove — 200 success", () => {
     expect(text).toContain("3");
     expect(text).toContain("user_vaults removed:");
     expect(text).toContain("4");
+    expect(text).toContain("storage cap removed:");
     expect(text).toContain("vault removed:");
   });
 
@@ -194,19 +196,35 @@ describe("vaultRemove — 200 success", () => {
   });
 });
 
-describe("vaultRemove — 409 last_vault GUARDRAIL", () => {
-  test("returns NON-ZERO and NEVER spawns parachute-vault", async () => {
+describe("vaultRemove — last vault (#678: cascade-then-delete, no 409)", () => {
+  test("the last vault deletes via the cascade (200) and NEVER spawns parachute-vault directly", async () => {
     await withSpawnSpy(async (spawned) => {
-      const { fetch, calls } = fakeFetch([
-        {
-          status: 409,
-          body: {
-            error: "last_vault",
-            error_description:
-              '"scratch" is the last vault on this hub. Create another vault first, or use the CLI.',
-          },
+      // The endpoint no longer refuses the last vault — it returns 200 with the
+      // cascade summary, identical to any other delete. The CLI just renders it.
+      const lastVaultBody = {
+        ok: true,
+        name: "scratch",
+        cascade: {
+          tokens_revoked: 2,
+          grants_rewritten: 0,
+          grants_dropped: 1,
+          user_vaults_removed: 1,
+          invites_invalidated: 0,
+          vault_cap_removed: true,
+          connections_torn_down: 0,
+          orphaned_channels: [],
+          vault_removed: true,
+          module_restarted: true,
         },
-      ]);
+        warnings: [
+          {
+            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>",
+          },
+        ],
+      };
+      const { fetch, calls } = fakeFetch([{ status: 200, body: lastVaultBody }]);
       const sinks = makeSinks();
       const code = await vaultRemove(["scratch"], {
         resolveBearer: async () => BEARER,
@@ -214,17 +232,20 @@ describe("vaultRemove — 409 last_vault GUARDRAIL", () => {
         log: sinks.log,
         logError: sinks.logError,
       });
-      // Non-zero exit.
-      expect(code).not.toBe(0);
-      // Exactly ONE fetch (the DELETE) — no fall-through retry path.
+      // 200 → success exit; the cascade did its work.
+      expect(code).toBe(0);
+      // Exactly ONE fetch (the DELETE) — the cascade runs server-side over loopback.
       expect(calls).toHaveLength(1);
       expect(calls[0]?.method).toBe("DELETE");
-      // The load-bearing invariant: no `parachute-vault` spawn.
+      // The load-bearing invariant still holds: the CLI never spawns
+      // `parachute-vault` itself — destruction goes through the hub endpoint.
       expect(spawned.count).toBe(0);
-      // Surfaces the endpoint message + the cascade-skip warning on the escape hatch.
-      const errText = sinks.errText();
-      expect(errText).toContain("last vault");
-      expect(errText).toContain("SKIPS the identity cascade");
+      // The cascade summary renders, including the last_vault heads-up warning.
+      const text = sinks.text();
+      expect(text).toContain("tokens revoked:");
+      expect(text).toContain("vault removed:");
+      expect(text).toContain("last_vault");
+      expect(text).toContain("auto_create: false");
     });
   });
 });

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,7 +57,7 @@ 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 {
@@ -177,6 +180,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.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-vaults.ts

@@ -630,15 +630,22 @@ export 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);
@@ -661,6 +668,15 @@ export 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,
@@ -714,16 +730,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 }[] = [];
@@ -865,6 +885,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 {

package/src/clients.ts

@@ -203,6 +203,41 @@ export function getClient(db: Database, clientId: string): OAuthClient | null {
   return row ? rowToClient(row) : null;
 }
 
+/**
+ * Delete an OAuth client and everything that references it. Returns true when
+ * a client row was removed, false when no such client existed.
+ *
+ * Backs the RFC 7592 `DELETE /oauth/clients/<id>` deregistration endpoint
+ * (closes hub#640): parachute-surface fires a best-effort DELETE on every
+ * Notes/Claude remove-flow, so without this helper + route every reconnect
+ * orphaned a `clients` row in the operator's hub DB.
+ *
+ * CASCADE-BY-HAND. `auth_codes.client_id` and `grants.client_id` both
+ * `REFERENCES clients(client_id)` with NO `ON DELETE CASCADE`, and the hub
+ * opens its DB with `PRAGMA foreign_keys = ON` — so a bare
+ * `DELETE FROM clients` while a dependent auth_code or grant row exists
+ * throws a FOREIGN KEY constraint violation. We delete the dependents FIRST,
+ * then the client row, all inside a single transaction so a mid-cascade
+ * failure rolls the whole thing back (no half-deleted client). Modelled on
+ * `grants.revokeGrant` + the vault-delete cascade in `admin-vaults`.
+ *
+ * Note on tokens: access tokens already minted for this client are NOT
+ * touched here (the `tokens` registry is keyed by jti, not client_id, and
+ * carries no FK to `clients`). They expire on their own; an operator who
+ * wants to kill live sessions runs `/oauth/revoke` separately. Same posture
+ * `revokeGrant` documents.
+ */
+export function deleteClient(db: Database, clientId: string): boolean {
+  return db.transaction(() => {
+    // Delete dependents first — FK ON, no cascade, so the client row can't
+    // go while an auth_code or grant still points at it.
+    db.prepare("DELETE FROM auth_codes WHERE client_id = ?").run(clientId);
+    db.prepare("DELETE FROM grants WHERE client_id = ?").run(clientId);
+    const res = db.prepare("DELETE FROM clients WHERE client_id = ?").run(clientId);
+    return res.changes > 0;
+  })();
+}
+
 /**
  * Returns the registered redirect URI matching `candidate` exactly, or throws.
  * RFC 8252 + 6749 require exact-match for redirect URIs (no wildcards, no

package/src/commands/auth.ts

@@ -25,7 +25,7 @@
 
 import { join } from "node:path";
 import { createInterface } from "node:readline/promises";
-import { approveClient, getClient, listClientsByStatus } from "../clients.ts";
+import { approveClient, deleteClient, getClient, listClientsByStatus } from "../clients.ts";
 import { CONFIG_DIR } from "../config.ts";
 import { readExposeState } from "../expose-state.ts";
 import { listGrantsForUser, revokeGrant } from "../grants.ts";
@@ -96,6 +96,7 @@ const HUB_LOCAL_SUBCOMMANDS = new Set([
   "revoke-token",
   "pending-clients",
   "approve-client",
+  "revoke-client",
   "list-grants",
   "revoke-grant",
 ]);
@@ -135,6 +136,9 @@ Usage:
                                        exits 0.
   parachute auth pending-clients       List OAuth clients awaiting approval
   parachute auth approve-client <id>   Approve a pending OAuth client
+  parachute auth revoke-client <id>    Deregister (delete) an OAuth client,
+                                       cascading its grants + auth codes
+                                       (RFC 7592 deregistration)
   parachute auth list-grants [--username <name>]
                                        Show OAuth scope grants on record
   parachute auth revoke-grant <client_id> [--username <name>]
@@ -619,6 +623,44 @@ function runApproveClient(args: readonly string[], deps: AuthDeps): number {
   }
 }
 
+/**
+ * `parachute auth revoke-client <id>` — RFC 7592 deregistration from the
+ * terminal. The CLI complement to the `DELETE /oauth/clients/<id>` route
+ * parachute-surface fires automatically; an operator runs this to clean up
+ * an orphaned / stale client by hand (closes hub#640). Calls the
+ * `deleteClient` cascade helper directly (same db, no round-trip through the
+ * HTTP route) and emits the same `client deleted:` audit line the route does
+ * so browser-driven and terminal-driven deletions are uniformly greppable in
+ * hub.log. `remover_sub=cli` distinguishes the terminal path (which has no
+ * authenticated JWT subject) from the route's `remover_sub=<jwt sub>`.
+ */
+function runRevokeClient(args: readonly string[], deps: AuthDeps): number {
+  const clientId = args[0];
+  if (!clientId) {
+    console.error("parachute auth revoke-client: missing client_id argument");
+    console.error("usage: parachute auth revoke-client <client_id>");
+    return 1;
+  }
+  const db = deps.dbPath ? openHubDb(deps.dbPath) : openHubDb();
+  try {
+    // Read the name before deleting so the audit line + confirmation can
+    // carry it. getClient also gives us the "exists?" answer for the 404 path.
+    const before = getClient(db, clientId);
+    const removed = deleteClient(db, clientId);
+    if (!removed) {
+      console.error(`no OAuth client registered with client_id "${clientId}"`);
+      return 1;
+    }
+    console.log(
+      `client deleted: client_id=${clientId} client_name=${before?.clientName ?? ""} remover_sub=cli`,
+    );
+    console.log(`Deregistered OAuth client "${clientId}" (grants + auth codes cascaded).`);
+    return 0;
+  } finally {
+    db.close();
+  }
+}
+
 interface UsernameFlag {
   username?: string;
   rest: string[];
@@ -1405,6 +1447,15 @@ export async function auth(args: readonly string[], deps: AuthDeps | Runner = {}
         return 1;
       }
     }
+    if (sub === "revoke-client") {
+      try {
+        return runRevokeClient(args.slice(1), normalized);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`parachute auth revoke-client: ${msg}`);
+        return 1;
+      }
+    }
     if (sub === "list-grants") {
       try {
         return runListGrants(args.slice(1), normalized);

package/src/commands/vault-remove.ts

@@ -31,14 +31,18 @@
  * `parachute:host:admin` — exactly the scope the endpoint gates on. This is the
  * same read-never-mint credential path `parachute start/stop/restart <svc>` use.
  *
- * ## The 409 guardrail (load-bearing)
+ * ## Last-vault handling (#678)
  *
- * On a `409 last_vault` the endpoint refuses (deleting the last vault would let
- * vault's boot silently resurrect a fresh `default`). We print the endpoint's
- * message + note the raw escape hatch (`parachute-vault remove <name> --yes`)
- * which SKIPS the cascade, then return NON-ZERO. We MUST NOT fall through to
- * spawning `parachute-vault` ourselves: a "helpful" fall-through would re-open
- * the exact orphaning bug B3 closes. The test locks this invariant.
+ * The last/only vault is deleted IDENTICALLY to any other vault: the endpoint
+ * runs the full cascade-then-delete and returns 200. There is no special-case
+ * here. (Older builds refused the last vault with a `409 last_vault` and steered
+ * the operator to the raw `parachute-vault remove --yes` — but that escape hatch
+ * SKIPS the cascade, orphaning the very identity artifacts B3 set out to clean
+ * up. hub#678 removed that refusal: vault's boot can no longer silently
+ * resurrect a fresh first vault because vault's CLI writes an
+ * `auto_create: false` marker on last-vault removal and the boot gate honors
+ * it.) This command therefore needs no 409 branch — the 200 path renders the
+ * cascade summary for the last vault just like every other delete.
  */
 
 import { CONFIG_DIR } from "../config.ts";
@@ -56,8 +60,9 @@ import {
 
 /**
  * Injectable seams. Production wires the real operator-token bearer resolver +
- * the global `fetch`; tests inject fakes to assert the request shape + lock the
- * 409 guardrail without a live hub or a real socket.
+ * the global `fetch`; tests inject fakes to assert the request shape + that
+ * destruction always goes through the hub endpoint (never a direct
+ * `parachute-vault` spawn) without a live hub or a real socket.
  */
 export interface VaultRemoveDeps {
   /**
@@ -84,6 +89,7 @@ interface CascadeSummaryWire {
   grants_dropped?: number;
   user_vaults_removed?: number;
   invites_invalidated?: number;
+  vault_cap_removed?: boolean;
   connections_torn_down?: number;
   orphaned_channels?: unknown;
   vault_removed?: boolean;
@@ -151,6 +157,7 @@ function renderCascadeSummary(
   log(`  grants dropped:        ${n(c.grants_dropped)}`);
   log(`  user_vaults removed:   ${n(c.user_vaults_removed)}`);
   log(`  invites invalidated:   ${n(c.invites_invalidated)}`);
+  log(`  storage cap removed:   ${c.vault_cap_removed === true ? "yes" : "no"}`);
   log(`  connections torn down: ${n(c.connections_torn_down)}`);
   log(`  vault removed:         ${c.vault_removed === true ? "yes" : "no"}`);
   log(`  vault module restarted:${c.module_restarted === true ? " yes" : " no"}`);
@@ -302,21 +309,6 @@ export async function vaultRemove(args: string[], deps: VaultRemoveDeps = {}): P
     return 0;
   }
 
-  if (res.status === 409 && error === "last_vault") {
-    // CRITICAL GUARDRAIL: print + exit non-zero. Do NOT fall through to spawning
-    // `parachute-vault` — that would re-open the orphaned-identity bug B3 closes.
-    logError(`parachute vault remove: ${error_description}`);
-    logError("");
-    logError(
-      `The raw mechanics-only path \`parachute-vault remove ${name} --yes\` can delete the last vault,`,
-    );
-    logError(
-      "but it SKIPS the identity cascade — live tokens, grants, and user_vaults rows for that",
-    );
-    logError("vault would be left orphaned. Create another vault first if you can.");
-    return 1;
-  }
-
   if (res.status === 400 && error === "confirm_mismatch") {
     // Pass the hub's confirm message through.
     logError(`parachute vault remove: ${error_description}`);

package/src/cors.ts

@@ -89,8 +89,9 @@
  *     leaking the wrong ACAO and breaking CORS in unpredictable ways.
  *     Critical for cache correctness.
  *
- *   Access-Control-Allow-Methods: GET, POST, OPTIONS
- *     The union of methods the in-scope route family supports. Per-route
+ *   Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
+ *     The union of methods the in-scope route family supports (DELETE for the
+ *     RFC 7592 `DELETE /oauth/clients/<id>` deregistration, hub#640). Per-route
  *     could be narrower (e.g. /oauth/token is POST-only), but advertising
  *     the union is the simpler shape and browsers don't enforce a per-route
  *     check anyway — the *actual* request method gates execution at the
@@ -137,7 +138,10 @@ const CORS_STATIC_RESPONSE_HEADERS: Readonly<Record<string, string>> = {
  * `corsPreflightResponse`.
  */
 const CORS_STATIC_PREFLIGHT_HEADERS: Readonly<Record<string, string>> = {
-  "access-control-allow-methods": "GET, POST, OPTIONS",
+  // DELETE is in the union for RFC 7592 client deregistration
+  // (`DELETE /oauth/clients/<id>`, hub#640). A cross-origin browser caller
+  // (vs the server-side surface daemon) would otherwise fail the preflight.
+  "access-control-allow-methods": "GET, POST, DELETE, OPTIONS",
   "access-control-allow-headers": "Authorization, Content-Type, X-Requested-With",
   "access-control-max-age": "86400",
 };

package/src/hub-server.ts

@@ -171,7 +171,7 @@ import {
   handleOAuthGrantCallback,
 } from "./admin-agent-grants.ts";
 import { handleAgentToken } from "./admin-agent-token.ts";
-import { handleApproveClient, handleGetClient } from "./admin-clients.ts";
+import { handleApproveClient, handleDeleteClient, handleGetClient } from "./admin-clients.ts";
 import {
   type ConnectionsDeps,
   handleConnections,
@@ -2767,6 +2767,33 @@ export function hubFetch(
         return applyCorsHeaders(req, await handleRevoke(getDb(), req, oauthDeps(req)));
       }
 
+      // RFC 7592 client deregistration: DELETE /oauth/clients/<id> (hub#640).
+      // Mounted at this TOP-LEVEL `/oauth/clients/` prefix — NOT under
+      // `/api/oauth/clients/` — because that's the path parachute-surface's
+      // remove-flow actually calls (`packages/surface-host/src/dcr.ts` fires a
+      // best-effort DELETE on every Notes/Claude reconnect, carrying the
+      // operator token as a Bearer). Without it the hub 404'd every such
+      // DELETE and orphaned a `clients` row per reconnect. Operator-bearer-
+      // gated (parachute:host:admin) inside handleDeleteClient; 204 on delete,
+      // 404 if absent. CORS-wrapped + OPTIONS-preflighted like its OAuth
+      // siblings (the top-of-dispatch isCorsAllowedRoute("/oauth/") preempts
+      // the preflight). The GET/approve sub-paths stay on `/api/oauth/clients/`
+      // (the SPA-facing admin surface) below.
+      if (pathname.startsWith("/oauth/clients/")) {
+        if (!getDb) return applyCorsHeaders(req, dbNotConfigured());
+        const clientId = decodeURIComponent(pathname.slice("/oauth/clients/".length));
+        if (!clientId || clientId.includes("/")) {
+          return applyCorsHeaders(req, new Response("not found", { status: 404 }));
+        }
+        return applyCorsHeaders(
+          req,
+          await handleDeleteClient(req, clientId, {
+            db: getDb(),
+            issuer: oauthDeps(req).issuer,
+          }),
+        );
+      }
+
       // 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/*,