@openparachute/hub 0.7.4-rc.8 → 0.7.4

package/src/cli.ts

@@ -22,6 +22,7 @@ import type { setup } from "./commands/setup.ts";
 import type { upgrade } from "./commands/upgrade.ts";
 import { ExposeStateError } from "./expose-state.ts";
 import {
+  doctorHelp,
   exposeHelp,
   initHelp,
   installHelp,
@@ -574,6 +575,34 @@ async function main(argv: string[]): Promise<number> {
         return await mod.status({ supervisor: {} });
       }
 
+    case "doctor": {
+      if (isHelpFlag(rest[0])) {
+        console.log(doctorHelp());
+        return 0;
+      }
+      const json = rest.includes("--json");
+      const fix = rest.includes("--fix");
+      const yes = rest.includes("--yes") || rest.includes("-y");
+      const known = new Set(["--json", "--fix", "--yes", "-y"]);
+      const unknown = rest.find((a) => !known.has(a));
+      if (unknown !== undefined) {
+        console.error(`parachute doctor: unknown argument "${unknown}"`);
+        console.error("usage: parachute doctor [--json] [--fix [--yes]]");
+        return 1;
+      }
+      if (json && fix) {
+        console.error("parachute doctor: --json and --fix are mutually exclusive");
+        return 1;
+      }
+      if (yes && !fix) {
+        console.error("parachute doctor: --yes has no effect without --fix");
+        return 1;
+      }
+      const mod = await loadCommand("doctor", () => import("./commands/doctor.ts"));
+      if (!mod) return 1;
+      return await mod.doctor({ json, fix, yes });
+    }
+
     case "expose": {
       const hubExtract = extractHubOrigin(rest);
       if (hubExtract.error) {

package/src/clients.ts

@@ -203,6 +203,170 @@ 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;
+  })();
+}
+
+/**
+ * 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, 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";
@@ -96,6 +105,8 @@ const HUB_LOCAL_SUBCOMMANDS = new Set([
   "revoke-token",
   "pending-clients",
   "approve-client",
+  "revoke-client",
+  "reap-clients",
   "list-grants",
   "revoke-grant",
 ]);
@@ -135,6 +146,15 @@ 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 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>]
@@ -238,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
@@ -619,6 +652,217 @@ 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 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[];
@@ -1405,6 +1649,24 @@ 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 === "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);