@openparachute/hub 0.5.13-rc.46 → 0.5.13-rc.47

package/package.json

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

package/src/__tests__/grants.test.ts

@@ -5,7 +5,9 @@ import { join } from "node:path";
 import { registerClient } from "../clients.ts";
 import {
   findGrant,
+  findGrantByClientName,
   isCoveredByGrant,
+  isCoveredByGrantForClientName,
   listGrantsForUser,
   recordGrant,
   revokeGrant,
@@ -162,3 +164,144 @@ describe("grants module (#75)", () => {
     }
   });
 });
+
+describe("findGrantByClientName / isCoveredByGrantForClientName (hub#409)", () => {
+  test("returns the most recent grant across any client_id with the matching name", async () => {
+    // Closes hub#409: CLI MCP clients re-DCR each session, each landing
+    // fresh client_ids. Operator approves once by name; future DCRs of
+    // the same name should auto-trust.
+    const h = await harness();
+    try {
+      // First DCR: client_name="claude-code", scope a+b
+      const reg1 = registerClient(h.db, {
+        redirectUris: ["https://app.example/cb"],
+        clientName: "claude-code",
+      });
+      recordGrant(h.db, h.userId, reg1.client.clientId, ["a", "b"], new Date("2026-04-10T00:00:00Z"));
+      // Second DCR: same client_name="claude-code", fresh client_id, no grant yet
+      const reg2 = registerClient(h.db, {
+        redirectUris: ["https://app.example/cb"],
+        clientName: "claude-code",
+      });
+      // findGrantByClientName should return the prior grant
+      const grant = findGrantByClientName(h.db, h.userId, "claude-code");
+      expect(grant).not.toBeNull();
+      expect(grant?.clientId).toBe(reg1.client.clientId);
+      expect(grant?.scopes).toEqual(["a", "b"]);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("returns null when no client with that name has any grant", async () => {
+    const h = await harness();
+    try {
+      registerClient(h.db, {
+        redirectUris: ["https://app.example/cb"],
+        clientName: "claude-code",
+      });
+      // No grants recorded
+      expect(findGrantByClientName(h.db, h.userId, "claude-code")).toBeNull();
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("returns null when client_name is empty string", async () => {
+    const h = await harness();
+    try {
+      expect(findGrantByClientName(h.db, h.userId, "")).toBeNull();
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("returns null for a different user (per-user isolation)", async () => {
+    const h = await harness();
+    try {
+      const reg = registerClient(h.db, {
+        redirectUris: ["https://app.example/cb"],
+        clientName: "claude-code",
+      });
+      recordGrant(h.db, h.userId, reg.client.clientId, ["a"]);
+      // Another user — should NOT see the grant. (hub is single-user-by-
+      // default; pass allowMulti for the test.)
+      const other = await createUser(h.db, "other-user", "pw", { allowMulti: true });
+      expect(findGrantByClientName(h.db, other.id, "claude-code")).toBeNull();
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("picks the most recent when multiple clients share the name", async () => {
+    const h = await harness();
+    try {
+      const reg1 = registerClient(h.db, {
+        redirectUris: ["https://app.example/cb"],
+        clientName: "claude-code",
+      });
+      const reg2 = registerClient(h.db, {
+        redirectUris: ["https://app.example/cb"],
+        clientName: "claude-code",
+      });
+      const reg3 = registerClient(h.db, {
+        redirectUris: ["https://app.example/cb"],
+        clientName: "claude-code",
+      });
+      recordGrant(h.db, h.userId, reg1.client.clientId, ["a"], new Date("2026-04-01T00:00:00Z"));
+      recordGrant(h.db, h.userId, reg3.client.clientId, ["a", "c"], new Date("2026-04-15T00:00:00Z"));
+      recordGrant(h.db, h.userId, reg2.client.clientId, ["a", "b"], new Date("2026-04-10T00:00:00Z"));
+      const grant = findGrantByClientName(h.db, h.userId, "claude-code");
+      // Most recent = reg3's grant (2026-04-15)
+      expect(grant?.clientId).toBe(reg3.client.clientId);
+      expect(grant?.scopes).toEqual(["a", "c"]);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("isCoveredByGrantForClientName: subset of stored scopes → true", async () => {
+    const h = await harness();
+    try {
+      const reg = registerClient(h.db, {
+        redirectUris: ["https://app.example/cb"],
+        clientName: "claude-code",
+      });
+      recordGrant(h.db, h.userId, reg.client.clientId, ["vault:default:read", "vault:default:write"]);
+      expect(isCoveredByGrantForClientName(h.db, h.userId, "claude-code", ["vault:default:read"])).toBe(true);
+      expect(isCoveredByGrantForClientName(h.db, h.userId, "claude-code", ["vault:default:read", "vault:default:write"])).toBe(true);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("isCoveredByGrantForClientName: superset of stored scopes → false", async () => {
+    const h = await harness();
+    try {
+      const reg = registerClient(h.db, {
+        redirectUris: ["https://app.example/cb"],
+        clientName: "claude-code",
+      });
+      recordGrant(h.db, h.userId, reg.client.clientId, ["vault:default:read"]);
+      // Asking for write — not previously granted
+      expect(isCoveredByGrantForClientName(h.db, h.userId, "claude-code", ["vault:default:write"])).toBe(false);
+      expect(isCoveredByGrantForClientName(h.db, h.userId, "claude-code", ["vault:default:read", "vault:default:write"])).toBe(false);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("isCoveredByGrantForClientName: empty scopes → false (matches isCoveredByGrant contract)", async () => {
+    const h = await harness();
+    try {
+      const reg = registerClient(h.db, {
+        redirectUris: ["https://app.example/cb"],
+        clientName: "claude-code",
+      });
+      recordGrant(h.db, h.userId, reg.client.clientId, ["a"]);
+      expect(isCoveredByGrantForClientName(h.db, h.userId, "claude-code", [])).toBe(false);
+    } finally {
+      h.cleanup();
+    }
+  });
+});

package/src/__tests__/oauth-handlers.test.ts

@@ -13,6 +13,7 @@ import {
   setSetting,
 } from "../hub-settings.ts";
 import { findTokenRowByJti, validateAccessToken } from "../jwt-sign.ts";
+import { findGrant, recordGrant } from "../grants.ts";
 import {
   authorizationServerMetadata,
   buildServicesCatalog,
@@ -6392,3 +6393,198 @@ describe("handleAuthorizeGet — stale assignment gates both fast-paths (hub#284
     }
   });
 });
+
+describe("handleAuthorizeGet — trust-by-client_name auto-approve (hub#409)", () => {
+  test("happy path: session + same-origin + prior grant for client_name → 302 to redirect_uri with code", async () => {
+    // The exact scenario hub#409 closes: operator approved "claude-code"
+    // last session; this session, Claude re-DCRs a fresh client_id with
+    // the same client_name; operator should NOT see the approve-pending
+    // screen — the flow goes straight to the authorize-code redirect.
+    const { db, cleanup } = await makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const session = createSession(db, { userId: user.id });
+      // 1. Prior client + grant (the "previously approved" state)
+      const prior = registerClient(db, {
+        redirectUris: ["https://app.example/cb"],
+        status: "approved",
+        clientName: "claude-code",
+      });
+      recordGrant(db, user.id, prior.client.clientId, ["vault:default:read"]);
+      // 2. Fresh DCR — same client_name, fresh client_id, status=pending
+      const fresh = registerClient(db, {
+        redirectUris: ["https://app.example/cb"],
+        status: "pending",
+        clientName: "claude-code",
+      });
+      const { challenge } = makePkce();
+      const req = new Request(
+        authorizeUrl({
+          client_id: fresh.client.clientId,
+          redirect_uri: "https://app.example/cb",
+          response_type: "code",
+          code_challenge: challenge,
+          code_challenge_method: "S256",
+          scope: "vault:default:read",
+          state: "trust-by-name",
+        }),
+        {
+          headers: {
+            cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000))}`,
+            origin: ISSUER,
+          },
+        },
+      );
+      const res = handleAuthorizeGet(db, req, {
+        issuer: ISSUER,
+        loadServicesManifest: fixtureLoadServicesManifest,
+      });
+      // 302 to redirect_uri with code — NOT a 403 with approve-pending HTML.
+      expect(res.status).toBe(302);
+      const loc = new URL(res.headers.get("location") ?? "");
+      expect(loc.origin + loc.pathname).toBe("https://app.example/cb");
+      expect(loc.searchParams.get("code")?.length).toBeGreaterThan(20);
+      expect(loc.searchParams.get("state")).toBe("trust-by-name");
+      // The fresh client_id is now approved
+      const after = getClient(db, fresh.client.clientId);
+      expect(after?.status).toBe("approved");
+      // A grant was recorded for the new client_id
+      expect(findGrant(db, user.id, fresh.client.clientId)).not.toBeNull();
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("falls through to approve-pending when requested scope is NOT covered by prior grant (superset)", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const session = createSession(db, { userId: user.id });
+      const prior = registerClient(db, {
+        redirectUris: ["https://app.example/cb"],
+        status: "approved",
+        clientName: "claude-code",
+      });
+      // Prior grant covers READ only
+      recordGrant(db, user.id, prior.client.clientId, ["vault:default:read"]);
+      const fresh = registerClient(db, {
+        redirectUris: ["https://app.example/cb"],
+        status: "pending",
+        clientName: "claude-code",
+      });
+      const { challenge } = makePkce();
+      // Asking for WRITE — not in prior grant
+      const req = new Request(
+        authorizeUrl({
+          client_id: fresh.client.clientId,
+          redirect_uri: "https://app.example/cb",
+          response_type: "code",
+          code_challenge: challenge,
+          code_challenge_method: "S256",
+          scope: "vault:default:write",
+        }),
+        {
+          headers: {
+            cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000))}`,
+            origin: ISSUER,
+          },
+        },
+      );
+      const res = handleAuthorizeGet(db, req, {
+        issuer: ISSUER,
+        loadServicesManifest: fixtureLoadServicesManifest,
+      });
+      // Approve-pending render — 403 — because the new scope wasn't trusted
+      expect(res.status).toBe(403);
+      expect(await res.text()).toContain("App not yet approved");
+      // The fresh client_id stays pending
+      expect(getClient(db, fresh.client.clientId)?.status).toBe("pending");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("falls through when no session (unauthenticated client re-DCR can't ride a session's trust)", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const prior = registerClient(db, {
+        redirectUris: ["https://app.example/cb"],
+        status: "approved",
+        clientName: "claude-code",
+      });
+      recordGrant(db, user.id, prior.client.clientId, ["vault:default:read"]);
+      const fresh = registerClient(db, {
+        redirectUris: ["https://app.example/cb"],
+        status: "pending",
+        clientName: "claude-code",
+      });
+      const { challenge } = makePkce();
+      // No session cookie
+      const req = new Request(
+        authorizeUrl({
+          client_id: fresh.client.clientId,
+          redirect_uri: "https://app.example/cb",
+          response_type: "code",
+          code_challenge: challenge,
+          code_challenge_method: "S256",
+          scope: "vault:default:read",
+        }),
+        { headers: { origin: ISSUER } },
+      );
+      const res = handleAuthorizeGet(db, req, {
+        issuer: ISSUER,
+        loadServicesManifest: fixtureLoadServicesManifest,
+      });
+      expect(res.status).toBe(403);
+      expect(await res.text()).toContain("App not yet approved");
+      expect(getClient(db, fresh.client.clientId)?.status).toBe("pending");
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("falls through when client_name is missing/empty (can't match a prior grant)", async () => {
+    const { db, cleanup } = await makeDb();
+    try {
+      const user = await createUser(db, "owner", "pw");
+      const session = createSession(db, { userId: user.id });
+      const prior = registerClient(db, {
+        redirectUris: ["https://app.example/cb"],
+        status: "approved",
+        clientName: "claude-code",
+      });
+      recordGrant(db, user.id, prior.client.clientId, ["vault:default:read"]);
+      // Fresh DCR omits client_name
+      const fresh = registerClient(db, {
+        redirectUris: ["https://app.example/cb"],
+        status: "pending",
+      });
+      const { challenge } = makePkce();
+      const req = new Request(
+        authorizeUrl({
+          client_id: fresh.client.clientId,
+          redirect_uri: "https://app.example/cb",
+          response_type: "code",
+          code_challenge: challenge,
+          code_challenge_method: "S256",
+          scope: "vault:default:read",
+        }),
+        {
+          headers: {
+            cookie: `${CSRF_COOKIE}; ${buildSessionCookie(session.id, Math.floor(SESSION_TTL_MS / 1000))}`,
+            origin: ISSUER,
+          },
+        },
+      );
+      const res = handleAuthorizeGet(db, req, {
+        issuer: ISSUER,
+        loadServicesManifest: fixtureLoadServicesManifest,
+      });
+      expect(res.status).toBe(403);
+      expect(getClient(db, fresh.client.clientId)?.status).toBe("pending");
+    } finally {
+      cleanup();
+    }
+  });
+});

package/src/grants.ts

@@ -117,6 +117,77 @@ export function isCoveredByGrant(
   return true;
 }
 
+/**
+ * Find the most-recent grant for a user across any client matching the
+ * given client_name. Used to support "trust an app by name" — once a
+ * user approves a `client_name` like `"claude-code"`, future DCRs with
+ * the same name auto-trust without re-asking. Returns null when no
+ * grant exists for any client of this name.
+ *
+ * Why: CLI MCP clients (Claude Code et al.) re-DCR on every `mcp add`
+ * (or every session), each landing a fresh `client_id`. Strict
+ * (user, client_id) grants force re-approval every time even though
+ * the operator has approved the same app many times before. Matching
+ * by client_name reflects the operator's actual mental model — "I
+ * approved Claude" — not the protocol's mental model — "I approved
+ * this specific client_id."
+ *
+ * Tradeoff: an attacker who can register a client with a known-trusted
+ * name (e.g. `"claude-code"`) gets auto-trust on first authorize. The
+ * defenses we kept:
+ *   1. Admin-scope flows still show consent (handled by the caller,
+ *      not this helper).
+ *   2. The audit log records each auto-trust event with both client_ids
+ *      (the original trusted one + the freshly auto-trusted one).
+ *   3. The Permissions admin SPA shows trusted client_names so the
+ *      operator can revoke trust by name.
+ *
+ * Closes hub#409 (Aaron 2026-05-26: "asking for approval every time…
+ * once we've approved something like Claude once it should not need
+ * admin approval every other time").
+ */
+export function findGrantByClientName(
+  db: Database,
+  userId: string,
+  clientName: string,
+): Grant | null {
+  if (!clientName) return null;
+  const row = db
+    .prepare(
+      `SELECT g.user_id, g.client_id, g.scopes, g.granted_at
+       FROM grants g
+       JOIN clients c ON g.client_id = c.client_id
+       WHERE g.user_id = ? AND c.client_name = ?
+       ORDER BY g.granted_at DESC
+       LIMIT 1`,
+    )
+    .get(userId, clientName) as GrantRow | undefined;
+  return row ? rowToGrant(row) : null;
+}
+
+/**
+ * Test whether `requestedScopes` is covered by ANY grant for the given
+ * client_name + user. The client_name-keyed counterpart to
+ * `isCoveredByGrant`. Used by /oauth/authorize to skip BOTH the
+ * approve-pending screen + the consent screen when the operator has
+ * previously approved a same-named client with sufficient scopes.
+ */
+export function isCoveredByGrantForClientName(
+  db: Database,
+  userId: string,
+  clientName: string,
+  requestedScopes: readonly string[],
+): boolean {
+  if (requestedScopes.length === 0) return false;
+  const grant = findGrantByClientName(db, userId, clientName);
+  if (!grant) return false;
+  const granted = new Set(grant.scopes);
+  for (const s of requestedScopes) {
+    if (!granted.has(s)) return false;
+  }
+  return true;
+}
+
 /** All grants for a user, ordered most-recent first. Used by `parachute auth list-grants`. */
 export function listGrantsForUser(db: Database, userId: string): Grant[] {
   const rows = db

package/src/oauth-handlers.ts

@@ -44,7 +44,7 @@ import {
   verifyClientSecret,
 } from "./clients.ts";
 import { CSRF_FIELD_NAME, ensureCsrfToken, verifyCsrfToken } from "./csrf.ts";
-import { isCoveredByGrant, recordGrant } from "./grants.ts";
+import { isCoveredByGrant, isCoveredByGrantForClientName, recordGrant } from "./grants.ts";
 import { consumeFirstClientAutoApproveWindow } from "./hub-settings.ts";
 import { VAULT_VERBS, inferAudience } from "./jwt-audience.ts";
 import {
@@ -506,6 +506,73 @@ function pendingClientResponse(
   const requestedVault = vaultParam && vaultParam.length > 0 ? vaultParam : undefined;
   const session = findActiveSession(db, req, deps.now ?? (() => new Date()));
   const sameOrigin = isSameOriginRequest(req, resolveBoundOrigins(deps));
+
+  // Trust-by-client_name auto-approve (closes hub#409). When the requesting
+  // user has previously approved a client with the SAME client_name AND the
+  // current request's scopes are covered by that prior grant, auto-promote
+  // this pending client to approved + carry on as if status had been
+  // approved from the start.
+  //
+  // Motivation: CLI MCP clients (Claude Code et al.) re-DCR each session,
+  // each landing a fresh client_id. Strict (user, client_id) approval forces
+  // the operator to click Approve every single time even though they
+  // already approved the same client by name on every prior session. Aaron
+  // 2026-05-26: "once we've approved something like claude once it should
+  // not need admin approval every other time."
+  //
+  // Constraints (security guardrails kept):
+  //   1. Requires an active operator session — anonymous DCR can't ride
+  //      another operator's prior trust.
+  //   2. Requires same-origin — defends against an attacker registering a
+  //      malicious "claude-code" client on a different hub and tricking
+  //      the operator into authorizing it.
+  //   3. Requires a non-empty client_name — DCR allows omitting it, in
+  //      which case the prior-grant lookup has nothing to match against.
+  //   4. Requires scope coverage — a strict superset (the new request asks
+  //      for scopes the prior grant didn't cover) falls through to the
+  //      approve-pending screen so the operator explicitly approves the
+  //      addition.
+  //   5. Non-admin scopes only — `*:admin` scopes (hub:admin, vault:*:admin
+  //      if it ever becomes requestable) require explicit per-session
+  //      consent. This guard mirrors the same-hub-auto-trust gate's
+  //      treatment of admin scopes (handleAuthorizeGet ~line 854).
+  //      NOTE: `scopeIsAdmin` has a documented blind spot for
+  //      module-declared admin scopes (e.g. a hypothetical `runner:admin`
+  //      registered via a module manifest's scopes.defines). See
+  //      `src/scope-explanations.ts:191`. A future module that makes a
+  //      module-admin scope requestable via public DCR would silently
+  //      bypass this guard. Worth a tighter scope-classification helper
+  //      when that becomes a real risk.
+  if (
+    session &&
+    sameOrigin &&
+    client.clientName &&
+    requestedScopes.length > 0 &&
+    !requestedScopes.some(scopeIsAdmin) &&
+    isCoveredByGrantForClientName(db, session.userId, client.clientName, requestedScopes)
+  ) {
+    console.log(
+      `[oauth] auto-approved pending client by prior client_name trust client_id=${client.clientId} client_name=${JSON.stringify(client.clientName)} user_id=${session.userId} scopes=${requestedScopes.join(" ")} (hub#409)`,
+    );
+    approveClient(db, client.clientId);
+    // Re-record the grant for this fresh client_id so the standard
+    // (user, client_id) consent-skip path also fires on the IMMEDIATE
+    // continuation below — without this, the very next /oauth/authorize
+    // dispatch would re-enter the "is grant covered?" check against the
+    // new client_id, find nothing (we matched by name, not id), and
+    // render the consent screen anyway.
+    recordGrant(db, session.userId, client.clientId, requestedScopes, deps.now?.() ?? new Date());
+    // Fall through to the standard approved-client flow: re-fetch the
+    // refreshed row + let handleAuthorizeGet continue past the
+    // status-check + into the consent-skip / same-hub auto-trust path.
+    const refreshed = getClient(db, client.clientId);
+    if (refreshed && refreshed.status === "approved") {
+      return handleAuthorizeGet(db, req, deps);
+    }
+    // If for some reason the refresh failed, fall through to render the
+    // approve-pending page (defensive — should never happen given the
+    // approveClient call just above).
+  }
   const csrf = ensureCsrfToken(req);
   const extra: Record<string, string> = csrf.setCookie ? { "set-cookie": csrf.setCookie } : {};
   // Hub-relative URL of the original `/oauth/authorize?...` request. Used in