@openparachute/hub 0.7.4-rc.16 → 0.7.4-rc.17

package/package.json

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

package/src/__tests__/auth.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 { issueAuthCode } from "../auth-codes.ts";
 import { registerClient } from "../clients.ts";
 import { type AuthDeps, type Runner, auth, authHelp } from "../commands/auth.ts";
 import { findGrant, recordGrant } from "../grants.ts";
@@ -269,6 +270,16 @@ describe("authHelp", () => {
     expect(h).toContain("parachute auth list-users");
     expect(h).toContain("parachute auth 2fa");
     expect(h).toContain("parachute auth rotate-key");
+    expect(h).toContain("parachute auth reap-clients");
+  });
+
+  test("reap-clients help documents dry-run-by-default + the conservative gate (#640)", () => {
+    expect(h).toContain("reap-clients");
+    expect(h).toContain("Dry-run by DEFAULT");
+    expect(h).toContain("--apply");
+    expect(h).toContain("--older-than");
+    expect(h).toContain("PROVABLY-DEAD");
+    expect(h).toContain("#640");
   });
 
   test("2fa help documents the real hub-login TOTP subcommands (#473)", () => {
@@ -918,6 +929,262 @@ describe("parachute auth revoke-client", () => {
   });
 });
 
+// closes #640 — OAuth client GC reaper. Dry-run by default; only provably-dead
+// clients are reapable. The deep gate coverage lives in clients.test.ts; these
+// exercise the CLI surface (dry-run safety, --apply, --json, empty case).
+describe("parachute auth reap-clients", () => {
+  const DAY_MS = 24 * 60 * 60 * 1000;
+
+  /** Register a client `daysAgo` days before now (relative to wall clock). */
+  function oldClient(db: ReturnType<typeof openHubDb>, daysAgo: number, name?: string): string {
+    const when = new Date(Date.now() - daysAgo * DAY_MS);
+    return registerClient(db, {
+      redirectUris: ["https://app.example/cb"],
+      ...(name !== undefined ? { clientName: name } : {}),
+      now: () => when,
+    }).client.clientId;
+  }
+
+  test("empty case: clean message, exit 0, no false alarm", async () => {
+    const tmp = makeTmp();
+    try {
+      const deps: AuthDeps = { dbPath: tmp.dbPath };
+      const { code, stdout } = await captureOutput(() => auth(["reap-clients"], deps));
+      expect(code).toBe(0);
+      expect(stdout).toContain("No abandoned clients to reap.");
+    } finally {
+      tmp.cleanup();
+    }
+  });
+
+  test("dry-run by DEFAULT lists candidates but deletes NOTHING", async () => {
+    const tmp = makeTmp();
+    let deadId: string;
+    try {
+      const db = openHubDb(tmp.dbPath);
+      try {
+        deadId = oldClient(db, 60, "DeadApp");
+      } finally {
+        db.close();
+      }
+      const deps: AuthDeps = { dbPath: tmp.dbPath };
+      const { code, stdout } = await captureOutput(() => auth(["reap-clients"], deps));
+      expect(code).toBe(0);
+      expect(stdout).toContain(deadId);
+      expect(stdout).toContain("DeadApp");
+      expect(stdout).toContain("--apply");
+      expect(stdout).toContain("nothing deleted");
+
+      // Count unchanged: the client is still there.
+      const db2 = openHubDb(tmp.dbPath);
+      try {
+        const n = db2.query<{ n: number }, []>("SELECT COUNT(*) AS n FROM clients").get()?.n;
+        expect(n).toBe(1);
+      } finally {
+        db2.close();
+      }
+    } finally {
+      tmp.cleanup();
+    }
+  });
+
+  test("--apply actually reaps + emits an audit line, dry-run is a no-op before it", async () => {
+    const tmp = makeTmp();
+    let deadId: string;
+    try {
+      const db = openHubDb(tmp.dbPath);
+      try {
+        deadId = oldClient(db, 60, "DeadApp");
+      } finally {
+        db.close();
+      }
+      const deps: AuthDeps = { dbPath: tmp.dbPath };
+
+      // Dry-run first: count before == count after.
+      await captureOutput(() => auth(["reap-clients"], deps));
+      const db2 = openHubDb(tmp.dbPath);
+      try {
+        expect(db2.query<{ n: number }, []>("SELECT COUNT(*) AS n FROM clients").get()?.n).toBe(1);
+      } finally {
+        db2.close();
+      }
+
+      // --apply deletes.
+      const { code, stdout } = await captureOutput(() => auth(["reap-clients", "--apply"], deps));
+      expect(code).toBe(0);
+      expect(stdout).toContain("Reaped 1 abandoned OAuth client");
+      expect(stdout).toContain(`client reaped: client_id=${deadId}`);
+      expect(stdout).toContain("client_name=DeadApp");
+
+      const db3 = openHubDb(tmp.dbPath);
+      try {
+        expect(db3.query<{ n: number }, []>("SELECT COUNT(*) AS n FROM clients").get()?.n).toBe(0);
+      } finally {
+        db3.close();
+      }
+    } finally {
+      tmp.cleanup();
+    }
+  });
+
+  test("NEVER reaps a client with a live grant (--apply leaves it intact)", async () => {
+    const tmp = makeTmp();
+    let liveId: string;
+    let userId: string;
+    try {
+      const db = openHubDb(tmp.dbPath);
+      try {
+        const user = await createUser(db, "owner", "pw");
+        userId = user.id;
+        liveId = oldClient(db, 60, "GrantedApp");
+        recordGrant(db, userId, liveId, ["vault:work:read"]);
+      } finally {
+        db.close();
+      }
+      const deps: AuthDeps = { dbPath: tmp.dbPath };
+      const { code, stdout } = await captureOutput(() => auth(["reap-clients", "--apply"], deps));
+      expect(code).toBe(0);
+      expect(stdout).toContain("No abandoned clients to reap.");
+
+      const db2 = openHubDb(tmp.dbPath);
+      try {
+        expect(
+          db2.query("SELECT client_id FROM clients WHERE client_id = ?").get(liveId),
+        ).not.toBeNull();
+        expect(findGrant(db2, userId, liveId)).not.toBeNull();
+      } finally {
+        db2.close();
+      }
+    } finally {
+      tmp.cleanup();
+    }
+  });
+
+  test("NEVER reaps a freshly-registered client (inside the 30d floor)", async () => {
+    const tmp = makeTmp();
+    try {
+      const db = openHubDb(tmp.dbPath);
+      try {
+        oldClient(db, 5); // 5 days old
+      } finally {
+        db.close();
+      }
+      const deps: AuthDeps = { dbPath: tmp.dbPath };
+      const { code, stdout } = await captureOutput(() => auth(["reap-clients"], deps));
+      expect(code).toBe(0);
+      expect(stdout).toContain("No abandoned clients to reap.");
+    } finally {
+      tmp.cleanup();
+    }
+  });
+
+  test("--older-than tunes the age floor", async () => {
+    const tmp = makeTmp();
+    let id: string;
+    try {
+      const db = openHubDb(tmp.dbPath);
+      try {
+        id = oldClient(db, 15); // 15 days old
+      } finally {
+        db.close();
+      }
+      const deps: AuthDeps = { dbPath: tmp.dbPath };
+      // Default 30d → not reapable.
+      const def = await captureOutput(() => auth(["reap-clients"], deps));
+      expect(def.stdout).toContain("No abandoned clients to reap.");
+      // 10d floor → reapable.
+      const tuned = await captureOutput(() => auth(["reap-clients", "--older-than", "10"], deps));
+      expect(tuned.stdout).toContain(id);
+    } finally {
+      tmp.cleanup();
+    }
+  });
+
+  test("--json emits machine output; applied=false in dry-run, true with --apply", async () => {
+    const tmp = makeTmp();
+    let deadId: string;
+    try {
+      const db = openHubDb(tmp.dbPath);
+      try {
+        deadId = oldClient(db, 60, "JsonApp");
+      } finally {
+        db.close();
+      }
+      const deps: AuthDeps = { dbPath: tmp.dbPath };
+      const dry = await captureOutput(() => auth(["reap-clients", "--json"], deps));
+      expect(dry.code).toBe(0);
+      const parsed = JSON.parse(dry.stdout) as {
+        applied: boolean;
+        count: number;
+        clients: Array<{ clientId: string }>;
+      };
+      expect(parsed.applied).toBe(false);
+      expect(parsed.count).toBe(1);
+      expect(parsed.clients[0]?.clientId).toBe(deadId);
+      // dry-run JSON deleted nothing.
+      const db2 = openHubDb(tmp.dbPath);
+      try {
+        expect(db2.query<{ n: number }, []>("SELECT COUNT(*) AS n FROM clients").get()?.n).toBe(1);
+      } finally {
+        db2.close();
+      }
+
+      const wet = await captureOutput(() => auth(["reap-clients", "--json", "--apply"], deps));
+      const wetParsed = JSON.parse(wet.stdout) as {
+        applied: boolean;
+        clients: Array<{ reaped?: boolean }>;
+      };
+      expect(wetParsed.applied).toBe(true);
+      expect(wetParsed.clients[0]?.reaped).toBe(true);
+    } finally {
+      tmp.cleanup();
+    }
+  });
+
+  test("a client with only an in-flight auth_code is NEVER reaped", async () => {
+    const tmp = makeTmp();
+    let id: string;
+    try {
+      const db = openHubDb(tmp.dbPath);
+      try {
+        const user = await createUser(db, "owner", "pw");
+        id = oldClient(db, 60);
+        issueAuthCode(db, {
+          clientId: id,
+          userId: user.id,
+          redirectUri: "https://app.example/cb",
+          scopes: ["vault:work:read"],
+          codeChallenge: "x".repeat(43),
+          codeChallengeMethod: "S256",
+        });
+      } finally {
+        db.close();
+      }
+      const deps: AuthDeps = { dbPath: tmp.dbPath };
+      const { stdout } = await captureOutput(() => auth(["reap-clients"], deps));
+      expect(stdout).toContain("No abandoned clients to reap.");
+    } finally {
+      tmp.cleanup();
+    }
+  });
+
+  test("rejects --older-than 0 / negative / non-integer", async () => {
+    const tmp = makeTmp();
+    try {
+      const deps: AuthDeps = { dbPath: tmp.dbPath };
+      for (const bad of ["0", "-5", "abc"]) {
+        const { code, stderr } = await captureOutput(() =>
+          auth(["reap-clients", "--older-than", bad], deps),
+        );
+        expect(code).toBe(1);
+        expect(stderr).toContain("--older-than");
+      }
+    } 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

@@ -8,9 +8,11 @@ import {
   approveClient,
   deleteClient,
   expandRedirectUrisForHubOrigins,
+  findReapableClients,
   getClient,
   isValidRedirectUri,
   listClientsByStatus,
+  reapClient,
   registerClient,
   requireRegisteredRedirectUri,
   verifyClientSecret,
@@ -430,6 +432,213 @@ describe("deleteClient cascade (hub#640 RFC 7592 deregistration)", () => {
   });
 });
 
+describe("findReapableClients / reapClient — the GC safety gate (hub#640)", () => {
+  const DAY_MS = 24 * 60 * 60 * 1000;
+  // A fixed "now" so age math is deterministic. All planted clients register
+  // 60 days before this unless a test overrides.
+  const NOW = new Date("2026-06-27T00:00:00Z");
+  const now = () => NOW;
+  const OLD = new Date(NOW.getTime() - 60 * DAY_MS); // 60d old → past 30d floor
+  const oldNow = () => OLD;
+
+  /** Plant a `tokens` row with precise expiry/revocation for a client. */
+  function plantToken(
+    db: ReturnType<typeof openHubDb>,
+    opts: {
+      clientId: string;
+      userId: string;
+      jti: string;
+      expiresAt: string;
+      revokedAt?: string | null;
+    },
+  ): void {
+    db.prepare(
+      `INSERT INTO tokens
+       (jti, user_id, client_id, scopes, refresh_token_hash, family_id,
+        expires_at, revoked_at, created_at, created_via, subject)
+       VALUES (?, ?, ?, '', NULL, NULL, ?, ?, ?, 'oauth_refresh', NULL)`,
+    ).run(
+      opts.jti,
+      opts.userId,
+      opts.clientId,
+      opts.expiresAt,
+      opts.revokedAt ?? null,
+      OLD.toISOString(),
+    );
+  }
+
+  test("a genuinely-dead old client IS reaped (no grants, only expired/revoked tokens, no live codes)", async () => {
+    const { db, cleanup } = makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const dead = registerClient(db, { redirectUris: ["https://dead.example/cb"], now: oldNow });
+      const id = dead.client.clientId;
+      // An expired token + a revoked token — both dead.
+      plantToken(db, {
+        clientId: id,
+        userId: user.id,
+        jti: "jti-expired",
+        expiresAt: new Date(NOW.getTime() - DAY_MS).toISOString(),
+      });
+      plantToken(db, {
+        clientId: id,
+        userId: user.id,
+        jti: "jti-revoked",
+        expiresAt: new Date(NOW.getTime() + DAY_MS).toISOString(), // unexpired...
+        revokedAt: new Date(NOW.getTime() - DAY_MS).toISOString(), // ...but revoked → dead
+      });
+
+      const reapable = findReapableClients(db, { now });
+      expect(reapable.map((c) => c.clientId)).toEqual([id]);
+      expect(reapable[0]?.ageDays).toBe(60);
+
+      // reapClient removes the client AND its dead token rows.
+      expect(reapClient(db, id)).toBe(true);
+      expect(getClient(db, id)).toBeNull();
+      expect(db.query("SELECT jti FROM tokens WHERE client_id = ?").all(id)).toEqual([]);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("a client WITH a live grant is NEVER reaped, even when old", async () => {
+    const { db, cleanup } = makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const c = registerClient(db, { redirectUris: ["https://granted.example/cb"], now: oldNow });
+      recordGrant(db, user.id, c.client.clientId, ["vault:work:read"]);
+      const reapable = findReapableClients(db, { now });
+      expect(reapable.map((x) => x.clientId)).not.toContain(c.client.clientId);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("a client with a live (unexpired, unrevoked) token is NEVER reaped, even when old", async () => {
+    const { db, cleanup } = makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const c = registerClient(db, { redirectUris: ["https://live.example/cb"], now: oldNow });
+      plantToken(db, {
+        clientId: c.client.clientId,
+        userId: user.id,
+        jti: "jti-live",
+        expiresAt: new Date(NOW.getTime() + 7 * DAY_MS).toISOString(),
+        revokedAt: null,
+      });
+      const reapable = findReapableClients(db, { now });
+      expect(reapable.map((x) => x.clientId)).not.toContain(c.client.clientId);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("a client with an unexpired auth_code is NEVER reaped (in-flight OAuth)", async () => {
+    const { db, cleanup } = makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const c = registerClient(db, { redirectUris: ["https://inflight.example/cb"], now: oldNow });
+      // issueAuthCode mints a code expiring AUTH_CODE_TTL after `now` → unexpired.
+      issueAuthCode(db, {
+        clientId: c.client.clientId,
+        userId: user.id,
+        redirectUri: "https://inflight.example/cb",
+        scopes: ["vault:work:read"],
+        codeChallenge: "x".repeat(43),
+        codeChallengeMethod: "S256",
+        now,
+      });
+      const reapable = findReapableClients(db, { now });
+      expect(reapable.map((x) => x.clientId)).not.toContain(c.client.clientId);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("a freshly-registered client is NEVER reaped, even with zero grants/tokens/codes", () => {
+    const { db, cleanup } = makeDb();
+    try {
+      // Registered 5 days ago — inside the default 30d floor.
+      const fresh = registerClient(db, {
+        redirectUris: ["https://fresh.example/cb"],
+        now: () => new Date(NOW.getTime() - 5 * DAY_MS),
+      });
+      const reapable = findReapableClients(db, { now });
+      expect(reapable.map((x) => x.clientId)).not.toContain(fresh.client.clientId);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("an expired auth_code does NOT protect a client (only LIVE codes do)", async () => {
+    const { db, cleanup } = makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const c = registerClient(db, { redirectUris: ["https://stale.example/cb"], now: oldNow });
+      // Code issued 60d ago → long expired.
+      issueAuthCode(db, {
+        clientId: c.client.clientId,
+        userId: user.id,
+        redirectUri: "https://stale.example/cb",
+        scopes: ["vault:work:read"],
+        codeChallenge: "x".repeat(43),
+        codeChallengeMethod: "S256",
+        now: oldNow,
+      });
+      const reapable = findReapableClients(db, { now });
+      expect(reapable.map((x) => x.clientId)).toContain(c.client.clientId);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("--older-than threshold is honored (a 20d-old client falls under a 10d floor but not 30d)", () => {
+    const { db, cleanup } = makeDb();
+    try {
+      const c = registerClient(db, {
+        redirectUris: ["https://midage.example/cb"],
+        now: () => new Date(NOW.getTime() - 20 * DAY_MS),
+      });
+      // Default 30d floor → not yet reapable.
+      expect(findReapableClients(db, { now }).map((x) => x.clientId)).not.toContain(
+        c.client.clientId,
+      );
+      // 10d floor → now reapable.
+      expect(
+        findReapableClients(db, { now, olderThanMs: 10 * DAY_MS }).map((x) => x.clientId),
+      ).toContain(c.client.clientId);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("reapClient on a still-protected client deletes nothing the gate excluded (callers pass only gated ids)", async () => {
+    // Belt-and-suspenders: reapClient itself doesn't re-check the gate (the
+    // caller is contractually responsible). This asserts the realistic flow —
+    // a live client is simply NOT in the findReapableClients output, so the
+    // apply loop never calls reapClient on it.
+    const { db, cleanup } = makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const live = registerClient(db, { redirectUris: ["https://keep.example/cb"], now: oldNow });
+      recordGrant(db, user.id, live.client.clientId, ["vault:work:read"]);
+      const dead = registerClient(db, { redirectUris: ["https://gone.example/cb"], now: oldNow });
+
+      const reapable = findReapableClients(db, { now });
+      const ids = reapable.map((x) => x.clientId);
+      expect(ids).toEqual([dead.client.clientId]);
+      for (const c of reapable) reapClient(db, c.clientId);
+
+      // Live client + its grant survive; only the dead one is gone.
+      expect(getClient(db, live.client.clientId)).not.toBeNull();
+      expect(findGrant(db, user.id, live.client.clientId)).not.toBeNull();
+      expect(getClient(db, dead.client.clientId)).toBeNull();
+    } finally {
+      cleanup();
+    }
+  });
+});
+
 describe("isValidRedirectUri", () => {
   test("accepts http and https", () => {
     expect(isValidRedirectUri("http://localhost:3000/cb")).toBe(true);

package/src/clients.ts

@@ -238,6 +238,135 @@ export function deleteClient(db: Database, clientId: string): boolean {
   })();
 }
 
+/**
+ * Default reaper age threshold: 30 days. A client registered more recently
+ * than this is NEVER reaped — it may be mid-first-OAuth-flow (registered →
+ * user is on the consent screen → no grant/token/code written yet). The
+ * threshold buys generous headroom over the worst-case human consent latency.
+ */
+export const DEFAULT_REAP_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+
+/** A client the reaper has proven dead. Carries enough to display a dry-run row. */
+export interface ReapableClient {
+  clientId: string;
+  clientName: string | null;
+  registeredAt: string;
+  status: ClientStatus;
+  /** Whole days since registration, floored. For the dry-run/`--json` display. */
+  ageDays: number;
+}
+
+export interface FindReapableOpts {
+  /** Reap only clients older than this many ms. Defaults to 30 days. */
+  olderThanMs?: number;
+  /** Injectable clock — all age + liveness comparisons use this. */
+  now?: () => Date;
+}
+
+/**
+ * Find OAuth clients that are PROVABLY DEAD and safe to garbage-collect.
+ *
+ * THE SAFETY GATE (maximally conservative — see hub#640). DCR churn (Notes /
+ * Claude mint a fresh `client_id` per reconnect) accumulates dead `clients`
+ * rows; this reaps them. But a reaper that deletes a LIVE client breaks a
+ * user's active connection, and we've been bitten by over-eager pruning
+ * before (a derived-key divergence wrongly pruned still-wanted grants). So a
+ * client is reapable IFF **ALL** of:
+ *
+ *   1. ZERO rows in `grants` — no standing consent. A grant means the user
+ *      approved this client; never touch it.
+ *   2. ZERO live tokens — no row in `tokens` with `expires_at > now AND
+ *      revoked_at IS NULL`. A live token means an active session.
+ *   3. ZERO live auth_codes — no row in `auth_codes` with `expires_at > now`.
+ *      A live code means an OAuth exchange is in flight RIGHT NOW.
+ *   4. `registered_at` older than `olderThanMs` (default 30d) — a freshly-
+ *      registered client may be mid-first-flow before any of the above rows
+ *      land.
+ *
+ * This reaps abandoned-never-consented `pending` DCR registrations and fully-
+ * dead (revoked/expired) clients, and NEVER a client with a live grant, live
+ * token, or in-flight code. Pure read — touches nothing. `reapClient` does the
+ * deletion.
+ *
+ * Implemented as a single `NOT EXISTS` SELECT so the gate is evaluated
+ * atomically per row against one consistent DB snapshot (no read-modify-write
+ * window where a token could land between the check and a later delete — the
+ * delete re-derives nothing; callers re-run the gate, see below).
+ */
+export function findReapableClients(db: Database, opts: FindReapableOpts = {}): ReapableClient[] {
+  const now = opts.now?.() ?? new Date();
+  const olderThanMs = opts.olderThanMs ?? DEFAULT_REAP_AGE_MS;
+  const nowIso = now.toISOString();
+  // Registered strictly before this cutoff to qualify on age (condition 4).
+  const cutoffIso = new Date(now.getTime() - olderThanMs).toISOString();
+
+  const rows = db
+    .query<Row, [string, string, string]>(
+      `SELECT c.* FROM clients c
+       WHERE c.registered_at < ?1
+         AND NOT EXISTS (SELECT 1 FROM grants g WHERE g.client_id = c.client_id)
+         AND NOT EXISTS (
+           SELECT 1 FROM tokens t
+           WHERE t.client_id = c.client_id
+             AND t.revoked_at IS NULL
+             AND t.expires_at > ?2
+         )
+         AND NOT EXISTS (
+           SELECT 1 FROM auth_codes a
+           WHERE a.client_id = c.client_id
+             AND a.expires_at > ?3
+         )
+       ORDER BY c.registered_at`,
+    )
+    .all(cutoffIso, nowIso, nowIso);
+
+  return rows.map((r) => {
+    const client = rowToClient(r);
+    const ageMs = now.getTime() - new Date(client.registeredAt).getTime();
+    return {
+      clientId: client.clientId,
+      clientName: client.clientName,
+      registeredAt: client.registeredAt,
+      status: client.status,
+      ageDays: Math.floor(ageMs / (24 * 60 * 60 * 1000)),
+    };
+  });
+}
+
+/**
+ * Garbage-collect a single PROVABLY-DEAD client. Wraps the `deleteClient`
+ * cascade (grants + auth_codes + client row) AND a `DELETE FROM tokens` for
+ * the same client_id, all in ONE transaction.
+ *
+ * Why also delete tokens here when `deleteClient` deliberately leaves them?
+ * `deleteClient` is the general deregistration path — it can run against a
+ * client that still has LIVE tokens (an operator force-removing an app mid-
+ * session), so it leaves the `tokens` rows to expire on their own (they carry
+ * no FK to `clients`). The reaper, by contrast, only ever runs on a client the
+ * gate has PROVEN has no live tokens — every remaining `tokens` row for it is
+ * already expired or revoked (dead). Deleting them completes the GC instead of
+ * leaving dead registry rows behind forever. Callers MUST pass only client_ids
+ * returned by `findReapableClients` (the safety gate); see the CLI's reap loop.
+ *
+ * TOCTOU note: `reapClient` does NOT re-check the gate — it trusts the caller's
+ * list. There is a theoretical window where a grant/token lands between the
+ * `findReapableClients` snapshot and this delete, reaping a client that just
+ * went live. On the single-operator hub this is cosmetically impossible: the
+ * OAuth flow that would create a grant runs synchronously on the same SQLite
+ * connection and never races a CLI invocation. Re-running `findReapableClients`
+ * immediately before each call would close the window at the cost of N extra
+ * round-trips; not worth it under the current trust model.
+ */
+export function reapClient(db: Database, clientId: string): boolean {
+  return db.transaction(() => {
+    // Dead token rows first — the gate proved none are live; this completes
+    // the GC (deleteClient leaves tokens alone for the general delete path).
+    db.prepare("DELETE FROM tokens WHERE client_id = ?").run(clientId);
+    // The cascade: auth_codes + grants (both dead per the gate) + the client.
+    return deleteClient(db, clientId);
+  })();
+}
+
 /**
  * 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,16 @@
 
 import { join } from "node:path";
 import { createInterface } from "node:readline/promises";
-import { approveClient, deleteClient, getClient, listClientsByStatus } from "../clients.ts";
+import {
+  DEFAULT_REAP_AGE_MS,
+  type ReapableClient,
+  approveClient,
+  deleteClient,
+  findReapableClients,
+  getClient,
+  listClientsByStatus,
+  reapClient,
+} from "../clients.ts";
 import { CONFIG_DIR } from "../config.ts";
 import { readExposeState } from "../expose-state.ts";
 import { listGrantsForUser, revokeGrant } from "../grants.ts";
@@ -97,6 +106,7 @@ const HUB_LOCAL_SUBCOMMANDS = new Set([
   "pending-clients",
   "approve-client",
   "revoke-client",
+  "reap-clients",
   "list-grants",
   "revoke-grant",
 ]);
@@ -139,6 +149,12 @@ Usage:
   parachute auth revoke-client <id>    Deregister (delete) an OAuth client,
                                        cascading its grants + auth codes
                                        (RFC 7592 deregistration)
+  parachute auth reap-clients [--older-than <days>] [--apply] [--json]
+                                       Garbage-collect abandoned/dead OAuth
+                                       clients (DCR reconnect churn). Dry-run
+                                       by default — lists what WOULD be reaped
+                                       and deletes nothing; pass --apply to
+                                       actually delete.
   parachute auth list-grants [--username <name>]
                                        Show OAuth scope grants on record
   parachute auth revoke-grant <client_id> [--username <name>]
@@ -242,6 +258,19 @@ and cannot OAuth until you run \`parachute auth approve-client <id>\`.
 First-party install flows that present \`Authorization: Bearer
 <operator-token>\` with \`hub:admin\` scope land as 'approved' immediately.
 
+reap-clients garbage-collects abandoned/dead OAuth clients (closes #640).
+DCR churn — Notes/Claude mint a FRESH client_id per reconnect — accumulates
+dead \`clients\` rows in the operator's hub.db. reap-clients deletes only the
+PROVABLY-DEAD ones: a client is reapable iff it has ZERO grants (no standing
+consent), ZERO live tokens (none unexpired+unrevoked), ZERO in-flight auth
+codes, AND was registered more than --older-than days ago (default 30). A
+client with a live grant, a live token, or an in-flight code is NEVER touched.
+
+Dry-run by DEFAULT: prints the clients that WOULD be reaped and deletes
+nothing — review before deleting. Pass \`--apply\` to actually delete them
+(grants + auth codes + dead tokens cascade). \`--older-than <days>\` tunes the
+age floor; \`--json\` emits machine-readable output.
+
 list-grants + revoke-grant manage the OAuth consent skip-list (closes
 #75). When you approve a scope-set on the consent screen, the hub
 records it so re-running the same flow goes straight to the auth-code
@@ -661,6 +690,179 @@ function runRevokeClient(args: readonly string[], deps: AuthDeps): number {
   }
 }
 
+interface ReapClientsFlags {
+  /** Age floor in days. Defaults to DEFAULT_REAP_AGE_MS / day. */
+  olderThanDays?: number;
+  /** --apply: actually delete. Without it, dry-run (default). */
+  apply: boolean;
+  /** --json: machine-readable output. */
+  json: boolean;
+  error?: string;
+}
+
+function parseReapClientsFlags(args: readonly string[]): ReapClientsFlags {
+  let olderThanDays: number | undefined;
+  let apply = false;
+  let json = false;
+  const parseDays = (raw: string | undefined): number | undefined | "error" => {
+    if (!raw) return "error";
+    // Whole, positive day count. Reject 0 / negatives / non-integers — an
+    // --older-than 0 would reap freshly-registered clients (the exact thing
+    // condition 4 of the gate exists to prevent).
+    if (!/^\d+$/.test(raw)) return "error";
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n <= 0) return "error";
+    return n;
+  };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--older-than") {
+      const parsed = parseDays(args[++i]);
+      if (parsed === "error")
+        return { apply, json, error: "--older-than requires a positive integer (days)" };
+      olderThanDays = parsed;
+    } else if (a?.startsWith("--older-than=")) {
+      const parsed = parseDays(a.slice("--older-than=".length));
+      if (parsed === "error")
+        return { apply, json, error: "--older-than requires a positive integer (days)" };
+      olderThanDays = parsed;
+    } else if (a === "--apply") {
+      apply = true;
+    } else if (a === "--json") {
+      json = true;
+    } else {
+      return { apply, json, error: `unknown flag "${a}"` };
+    }
+  }
+  return olderThanDays !== undefined ? { olderThanDays, apply, json } : { apply, json };
+}
+
+/**
+ * `parachute auth reap-clients` — garbage-collect abandoned/dead OAuth clients
+ * (closes hub#640). DCR churn (Notes/Claude mint a fresh client_id per
+ * reconnect) accumulates dead `clients` rows; this reaps the PROVABLY-DEAD
+ * ones via the conservative `findReapableClients` gate (zero grants, zero live
+ * tokens, zero in-flight auth_codes, older than the age floor).
+ *
+ * DRY-RUN BY DEFAULT — the load-bearing safety choice. A reaper that deletes a
+ * live client breaks a user's active connection, so the default run only
+ * REPORTS what it would delete and touches nothing; `--apply` performs the
+ * deletion. The same `findReapableClients` snapshot drives both the dry-run
+ * listing and the --apply loop, so what's printed is exactly what gets reaped.
+ */
+function runReapClients(args: readonly string[], deps: AuthDeps): number {
+  const flags = parseReapClientsFlags(args);
+  if (flags.error) {
+    console.error(`parachute auth reap-clients: ${flags.error}`);
+    console.error("usage: parachute auth reap-clients [--older-than <days>] [--apply] [--json]");
+    return 1;
+  }
+  const olderThanMs =
+    flags.olderThanDays !== undefined
+      ? flags.olderThanDays * 24 * 60 * 60 * 1000
+      : DEFAULT_REAP_AGE_MS;
+  const olderThanDays = olderThanMs / (24 * 60 * 60 * 1000);
+
+  const db = deps.dbPath ? openHubDb(deps.dbPath) : openHubDb();
+  try {
+    const reapable = findReapableClients(db, { olderThanMs });
+
+    if (flags.json) {
+      // Machine-readable: the candidate set + whether we actually deleted.
+      // In --apply mode each row carries `reaped: true` after deletion. Audit
+      // lines route to stderr so stdout stays pure JSON for piping into `jq`.
+      const deleted = flags.apply ? applyReap(db, reapable, console.error) : [];
+      console.log(
+        JSON.stringify(
+          {
+            applied: flags.apply,
+            olderThanDays,
+            count: reapable.length,
+            clients: reapable.map((c) => ({
+              clientId: c.clientId,
+              clientName: c.clientName,
+              registeredAt: c.registeredAt,
+              status: c.status,
+              ageDays: c.ageDays,
+              ...(flags.apply ? { reaped: deleted.includes(c.clientId) } : {}),
+            })),
+          },
+          null,
+          2,
+        ),
+      );
+      return 0;
+    }
+
+    if (reapable.length === 0) {
+      console.log("No abandoned clients to reap.");
+      return 0;
+    }
+
+    printReapTable(reapable);
+
+    if (!flags.apply) {
+      const plural = reapable.length === 1 ? "client" : "clients";
+      console.log("");
+      console.log(
+        `Dry run — nothing deleted. Run with --apply to delete ${reapable.length} ${plural}.`,
+      );
+      return 0;
+    }
+
+    const deleted = applyReap(db, reapable);
+    console.log("");
+    const plural = deleted.length === 1 ? "client" : "clients";
+    console.log(
+      `Reaped ${deleted.length} abandoned OAuth ${plural} (grants + auth codes + dead tokens cascaded).`,
+    );
+    return 0;
+  } finally {
+    db.close();
+  }
+}
+
+/** Print the dry-run / apply table of reapable clients. */
+function printReapTable(reapable: readonly ReapableClient[]): void {
+  console.log(
+    "CLIENT_ID                              NAME                 STATUS    AGE_DAYS  REGISTERED",
+  );
+  for (const c of reapable) {
+    const id = c.clientId.padEnd(36).slice(0, 36);
+    const name = (c.clientName ?? "").padEnd(20).slice(0, 20);
+    const status = c.status.padEnd(8).slice(0, 8);
+    const age = String(c.ageDays).padStart(8);
+    console.log(`${id}  ${name} ${status}  ${age}  ${c.registeredAt}`);
+  }
+}
+
+/**
+ * Delete each reapable client via `reapClient`, emitting one audit line per
+ * deletion (`client reaped:` — greppable in hub.log alongside `client
+ * deleted:` from the manual revoke path). Returns the client_ids actually
+ * removed. Callers pass ONLY the `findReapableClients` output, so every id
+ * here has already cleared the safety gate.
+ *
+ * `audit` is the sink for the per-deletion lines — `console.log` for the human
+ * table path, `console.error` for `--json` (keeps stdout pure JSON for `jq`).
+ */
+function applyReap(
+  db: ReturnType<typeof openHubDb>,
+  reapable: readonly ReapableClient[],
+  audit: (line: string) => void = console.log,
+): string[] {
+  const deleted: string[] = [];
+  for (const c of reapable) {
+    if (reapClient(db, c.clientId)) {
+      deleted.push(c.clientId);
+      audit(
+        `client reaped: client_id=${c.clientId} client_name=${c.clientName ?? ""} age_days=${c.ageDays} status=${c.status}`,
+      );
+    }
+  }
+  return deleted;
+}
+
 interface UsernameFlag {
   username?: string;
   rest: string[];
@@ -1456,6 +1658,15 @@ export async function auth(args: readonly string[], deps: AuthDeps | Runner = {}
         return 1;
       }
     }
+    if (sub === "reap-clients") {
+      try {
+        return runReapClients(args.slice(1), normalized);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`parachute auth reap-clients: ${msg}`);
+        return 1;
+      }
+    }
     if (sub === "list-grants") {
       try {
         return runListGrants(args.slice(1), normalized);

package/src/hub-db.ts

@@ -558,6 +558,20 @@ const MIGRATIONS: readonly Migration[] = [
       );
     `,
   },
+  {
+    version: 16,
+    sql: `
+      -- Index tokens by client_id for the OAuth client GC reaper (#640). The
+      -- reaper's gate runs a correlated NOT EXISTS (SELECT 1 FROM tokens WHERE
+      -- client_id = ? AND ...) per candidate client; tokens previously had no
+      -- client_id index (only user_id / refresh_token_hash / family_id /
+      -- revoked_at / subject), so each check was a full tokens-table walk. Under
+      -- the DCR reconnect churn this GC targets — thousands of dead token rows
+      -- accumulating before a sweep — that is O(total tokens) per client. This
+      -- makes it O(tokens for that client). IF NOT EXISTS so re-opens are inert.
+      CREATE INDEX IF NOT EXISTS tokens_client ON tokens (client_id);
+    `,
+  },
 ];
 
 export function openHubDb(path: string = hubDbPath()): Database {