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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.7.4-rc.11",
+  "version": "0.7.4-rc.12",
   "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__/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/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/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/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/*,