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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.7.4-rc.16",
+  "version": "0.7.4-rc.18",
   "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);