@openparachute/vault 0.6.0-rc.1 → 0.6.1

package/src/github-device-flow.ts

@@ -1,66 +1,110 @@
 /**
- * GitHub OAuth Device Flow client + supporting API calls.
+ * GitHub Device Flow client + supporting API calls.
  *
  * Why Device Flow (not Web Flow): self-hosted vault origins are
  * unpredictable (localhost:1940, random Tailscale FQDN, custom domain). Web
- * Flow needs a pre-registered callback URL per OAuth app; Device Flow needs
- * only a public `client_id` and the operator authorizes by typing a code at
+ * Flow needs a pre-registered callback URL; Device Flow needs only a public
+ * `client_id` and the operator authorizes by typing a code at
  * github.com/login/device from any device. Same UX as `gh auth login`.
  *
- * Spec: https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#device-flow
+ * Spec: https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app#using-the-device-flow-to-generate-a-user-access-token
  *
  * All HTTP calls accept an injectable `fetch` so tests can mock the wire
  * without spawning a real GitHub round-trip. Production wiring uses the
  * platform `fetch` (Bun's native).
  *
- * **GITHUB_CLIENT_ID setup (REQUIRED before this works in production):**
+ * **The registered app (2026-06-10)**: the default client_id below belongs
+ * to the shared Parachute **GitHub App** (not a classic OAuth App) that
+ * every self-hosted install uses — the same model as `gh` CLI shipping its
+ * client_id in source. Registration decisions (rationale in vault#480):
+ * fine-grained permissions = Contents read/write ONLY (treat as frozen —
+ * permission changes prompt every installer to re-approve); device flow
+ * enabled; user-token expiration disabled (non-expiring `ghu_` tokens — an
+ * unattended mirror daemon can't babysit single-use refresh tokens);
+ * installable on any account; webhook inactive; no OAuth-on-install.
  *
- *   1. Visit https://github.com/settings/developers
- *   2. "OAuth Apps" → "New OAuth App"
- *   3. Application name: "Parachute Vault" (or operator-chosen)
- *      Homepage URL: https://parachute.computer
- *      Authorization callback URL: https://parachute.computer/oauth/github
- *      (callback URL is required by GitHub's form but unused in Device Flow)
- *   4. After creating: open the app's settings page
- *   5. Tick the "Enable Device Flow" checkbox
- *   6. Copy the Client ID (looks like `Iv1.abc123...` or `Ov23li...`)
- *   7. Set the `GITHUB_CLIENT_ID` constant below to that value
+ * GitHub-App token semantics that shape the connect flow:
+ *   - The `scope` param is IGNORED. Token abilities = app permissions ∩
+ *     the user's own access ∩ the repos selected when INSTALLING the app.
+ *   - Authorization (this device flow) and installation are separate,
+ *     order-independent steps. A granted token reaches no repos until the
+ *     operator also installs the app on their account and selects repos
+ *     (github.com/apps/<app-slug>/installations/new).
+ *   - Every GitHub App can read ALL public repos — never infer "installed"
+ *     from repo visibility. `GET /user/installations` (which requires NO
+ *     permissions) is the canonical install probe: an empty array means
+ *     "authorized but not installed yet."
  *
- * The placeholder ships with this PR. Production builds are gated on a real
- * client_id; the PR body flags Aaron as the action owner.
+ * **Bring-your-own-app (BYO)**: operators who want their own GitHub App
+ * (own rate-limit budget, full sovereignty) must override BOTH env vars as
+ * a pair — `PARACHUTE_GITHUB_CLIENT_ID` (their app's client_id, used for
+ * the device flow) AND `PARACHUTE_GITHUB_APP_SLUG` (their app's URL slug,
+ * used to build the install link). Overriding only one mixes two apps:
+ * tokens would be minted for one app while the install link points at the
+ * other, and `GET /user/installations` (which lists installations of the
+ * TOKEN's app) would never agree with the link.
  */
 
 // ---------------------------------------------------------------------------
-// Client ID — REPLACE BEFORE TAGGING A RELEASE.
+// Client ID — the shared Parachute GitHub App (public; safe to commit).
 //
-// This is the public OAuth app client_id. No secret is needed for Device
-// Flow (the operator's typed code is the proof-of-presence factor). Safe to
-// commit + ship in client builds. But: tied to ONE registered GitHub OAuth
-// App, which Aaron owns under the Parachute org / his account. Set this
-// after running the setup checklist above.
-//
-// TODO(aaron): replace with the real client_id from the registered OAuth
-// app. Until then, the device-flow endpoints return a clear-error response
-// instead of attempting GitHub's API with an invalid id (which surfaces an
-// opaque "Not Found" that's hard to debug).
+// No secret is needed for Device Flow (the operator's typed code is the
+// proof-of-presence factor), and a client_id is not a credential — GitHub
+// treats public clients as trivially spoofable by design. Operators who
+// want their own app (own rate-limit budget — the device-flow verification
+// cap is 50/hour PER APP fleet-wide — or full sovereignty) set
+// PARACHUTE_GITHUB_CLIENT_ID, which takes precedence. See vault#480.
 // ---------------------------------------------------------------------------
 
-export const GITHUB_CLIENT_ID_PLACEHOLDER =
-  "Iv1.PLACEHOLDER_REPLACE_ME_BEFORE_RELEASE" as const;
+export const GITHUB_CLIENT_ID_DEFAULT = "Iv23livaRF4VcvPhu3uB" as const;
 
 /**
- * The active client id at runtime. Resolved from the env (preferred — lets
- * operators override per-deploy) or the constant above (for tests +
- * defaults). Defaults to the placeholder; the route handlers check for the
- * placeholder and return an actionable error before hitting GitHub.
+ * The active client id at runtime. Resolved from the env (preferred — the
+ * bring-your-own-app path) or the shared-app default above.
  */
 export function getGithubClientId(): string {
-  return process.env.PARACHUTE_GITHUB_CLIENT_ID || GITHUB_CLIENT_ID_PLACEHOLDER;
+  return process.env.PARACHUTE_GITHUB_CLIENT_ID || GITHUB_CLIENT_ID_DEFAULT;
 }
 
-/** Returns true when no real client id has been configured. */
+/**
+ * Returns true when the configured client id is a placeholder rather than a
+ * real id — only reachable via a misconfigured PARACHUTE_GITHUB_CLIENT_ID
+ * override now that a real default ships. Route handlers keep the check so
+ * a junk override surfaces an actionable error instead of GitHub's opaque
+ * "Not Found".
+ */
 export function isPlaceholderClientId(clientId: string): boolean {
-  return clientId === GITHUB_CLIENT_ID_PLACEHOLDER || clientId.includes("PLACEHOLDER");
+  return clientId.includes("PLACEHOLDER");
+}
+
+// ---------------------------------------------------------------------------
+// App slug — the shared Parachute GitHub App's URL slug. Drives the install
+// link (github.com/apps/<slug>/installations/new), which the connect flow
+// surfaces when the operator is authorized-but-not-installed. BYO-app
+// operators override PARACHUTE_GITHUB_APP_SLUG *together with*
+// PARACHUTE_GITHUB_CLIENT_ID (see the header comment — the pair must come
+// from the same app).
+// ---------------------------------------------------------------------------
+
+export const GITHUB_APP_SLUG_DEFAULT = "parachute-computer" as const;
+
+/**
+ * The active app slug at runtime. Resolved from the env (the BYO-app path,
+ * paired with PARACHUTE_GITHUB_CLIENT_ID) or the shared-app default above.
+ */
+export function getGithubAppSlug(): string {
+  return process.env.PARACHUTE_GITHUB_APP_SLUG || GITHUB_APP_SLUG_DEFAULT;
+}
+
+/**
+ * The "install this app / pick repos" URL for an app slug. Installation is
+ * the second, separate step of the connect flow (authorization being the
+ * first); the same URL also serves "add another account/org" and "change
+ * repo selection" — GitHub routes already-installed accounts to the
+ * configure screen.
+ */
+export function installUrlForSlug(slug: string): string {
+  return `https://github.com/apps/${encodeURIComponent(slug)}/installations/new`;
 }
 
 // ---------------------------------------------------------------------------
@@ -118,6 +162,45 @@ export interface ListReposResult {
   truncated: boolean;
 }
 
+/**
+ * One installation of the app, as returned by `GET /user/installations`.
+ * That endpoint lists installations OF THE TOKEN'S APP that the token's
+ * user can access — user-account installs and org installs alike — and
+ * requires NO permissions, so it works with the Contents-only shared app.
+ * An empty list means "authorized but not installed yet" (the device-flow
+ * grant alone reaches no repos).
+ */
+export interface GitHubInstallation {
+  id: number;
+  /** The app's URL slug (e.g. "parachute-computer"). Always this app's —
+   *  the endpoint is app-scoped by the token — but carried for display +
+   *  defensive checks. */
+  app_slug: string;
+  account: {
+    login: string;
+    /** "User" or "Organization". */
+    type: string;
+  };
+  /** "all" or "selected" — whether the installation covers every repo on
+   *  the account or an operator-picked subset. */
+  repository_selection: string;
+}
+
+/**
+ * Error thrown by the GitHub API helpers when GitHub returns a non-2xx
+ * response. Carries the HTTP status so route handlers can branch on
+ * specific failure classes (e.g. createRepo's 403 = the app lacks
+ * Administration:write) without string-matching the message.
+ */
+export class GitHubApiError extends Error {
+  readonly status: number;
+  constructor(message: string, status: number) {
+    super(message);
+    this.name = "GitHubApiError";
+    this.status = status;
+  }
+}
+
 /** Minimal fetch-like surface — injectable for tests. */
 export type FetchLike = (
   input: string,
@@ -139,8 +222,12 @@ function defaultFetch(): FetchLike {
 
 /**
  * Start a device-flow authorization. POSTs to GitHub's `/login/device/code`
- * with the public client_id + the `repo` scope (the minimum we need to push
- * to the operator's private repos).
+ * with the public client_id.
+ *
+ * No `scope` param: GitHub Apps ignore it entirely. Token abilities come
+ * from the app's fine-grained permissions (Contents read/write) intersected
+ * with the repos the operator selects when installing the app — push access
+ * to private repos comes from that install-time selection, not a scope.
  *
  * Throws on transport or shape error — the route handler catches + returns
  * a 502. Successful return is the four-tuple GitHub spec calls for
@@ -158,11 +245,6 @@ export async function requestDeviceCode(
     },
     body: new URLSearchParams({
       client_id: clientId,
-      // `repo` is the broad-private-repo scope. Read-only push isn't a
-      // thing on GitHub; if we want to push, we need write access to repo
-      // contents, which `repo` includes. The narrower scope `public_repo`
-      // wouldn't cover private repos — most operator vaults are private.
-      scope: "repo",
     }).toString(),
   });
   if (!res.ok) {
@@ -292,6 +374,15 @@ export async function fetchUser(
  * Truncates after `maxPages * perPage` repos (default 3 * 100 = 300) — most
  * operators have far fewer, the truncation signals the UI to prompt for a
  * search filter.
+ *
+ * **No longer the repo-picker source** (vault#480): `type=owner` excludes
+ * org-owned repos by construction, and with a GitHub-App token an
+ * uninstalled app still sees all PUBLIC repos — so this list silently
+ * misleads ("looks connected, shows the wrong repos"). The picker now goes
+ * `listInstallations` → `listInstallationRepos`, which enumerates exactly
+ * what the operator granted. No production callers remain — kept exported
+ * for its test coverage and as a building block for potential external /
+ * non-App callers.
  */
 export async function listRepos(
   token: string,
@@ -354,11 +445,171 @@ export async function listRepos(
   return { repos, truncated };
 }
 
+// ---------------------------------------------------------------------------
+// Installation APIs — the honest sources for the connect flow (vault#480).
+// ---------------------------------------------------------------------------
+
+/**
+ * List the token-user's installations of this app — `GET /user/installations`.
+ *
+ * Requires NO permissions (works with the Contents-only shared app), and is
+ * the canonical "is the app installed?" probe: an empty array means the
+ * operator authorized via device flow but hasn't installed the app on any
+ * account yet, so the token reaches no repos. Items cover both user-account
+ * and org installs, which is how org-owned mirror repos become reachable.
+ *
+ * Single page at per_page=100 — more than 100 installations of one app for
+ * one user is beyond any plausible operator; truncating there is acceptable.
+ *
+ * Throws `GitHubApiError` on a non-2xx response, plain Error on a bad shape.
+ */
+export async function listInstallations(
+  token: string,
+  fetchImpl: FetchLike = defaultFetch(),
+): Promise<GitHubInstallation[]> {
+  const res = await fetchImpl("https://api.github.com/user/installations?per_page=100", {
+    headers: {
+      accept: "application/vnd.github+json",
+      authorization: `token ${token}`,
+      "X-GitHub-Api-Version": "2022-11-28",
+    },
+  });
+  if (!res.ok) {
+    const body = await res.text();
+    throw new GitHubApiError(
+      `GitHub /user/installations fetch failed (${res.status}): ${body.slice(0, 200)}`,
+      res.status,
+    );
+  }
+  const parsed = (await res.json()) as { installations?: unknown };
+  if (!parsed || !Array.isArray(parsed.installations)) {
+    throw new Error(
+      `GitHub /user/installations response missing installations array: ${JSON.stringify(parsed).slice(0, 200)}`,
+    );
+  }
+  const installations: GitHubInstallation[] = [];
+  for (const item of parsed.installations as Array<Record<string, unknown>>) {
+    const account = item.account as Record<string, unknown> | null | undefined;
+    if (
+      typeof item.id !== "number" ||
+      !account ||
+      typeof account.login !== "string" ||
+      typeof account.type !== "string"
+    ) {
+      throw new Error(
+        `GitHub /user/installations item missing required fields: ${JSON.stringify(item).slice(0, 200)}`,
+      );
+    }
+    installations.push({
+      id: item.id,
+      app_slug: typeof item.app_slug === "string" ? item.app_slug : "",
+      account: { login: account.login, type: account.type },
+      repository_selection:
+        typeof item.repository_selection === "string" ? item.repository_selection : "selected",
+    });
+  }
+  return installations;
+}
+
+/**
+ * Paginated list of the repos one installation grants access to —
+ * `GET /user/installations/{id}/repositories`. Metadata-read suffices (our
+ * Contents permission implies it); private repos within the installation
+ * are included, which is exactly the set the repo picker should show.
+ * Pagination + truncation semantics match `listRepos` (per_page=100,
+ * `maxPages` cap, `truncated` flag for the UI).
+ *
+ * Throws `GitHubApiError` on a non-2xx response, plain Error on a bad shape.
+ */
+export async function listInstallationRepos(
+  token: string,
+  installationId: number,
+  opts: { maxPages?: number; perPage?: number } = {},
+  fetchImpl: FetchLike = defaultFetch(),
+): Promise<ListReposResult> {
+  const perPage = opts.perPage ?? 100;
+  const maxPages = opts.maxPages ?? 3;
+  const repos: GitHubRepoInfo[] = [];
+  let truncated = false;
+  for (let page = 1; page <= maxPages; page++) {
+    const res = await fetchImpl(
+      `https://api.github.com/user/installations/${installationId}/repositories?per_page=${perPage}&page=${page}`,
+      {
+        headers: {
+          accept: "application/vnd.github+json",
+          authorization: `token ${token}`,
+          "X-GitHub-Api-Version": "2022-11-28",
+        },
+      },
+    );
+    if (!res.ok) {
+      const body = await res.text();
+      throw new GitHubApiError(
+        `GitHub /user/installations/${installationId}/repositories fetch failed (${res.status}, page ${page}): ${body.slice(0, 200)}`,
+        res.status,
+      );
+    }
+    const parsed = (await res.json()) as { repositories?: unknown };
+    if (!parsed || !Array.isArray(parsed.repositories)) {
+      throw new Error(
+        `GitHub /user/installations/${installationId}/repositories response missing repositories array: ${JSON.stringify(parsed).slice(0, 200)}`,
+      );
+    }
+    const items = parsed.repositories as Array<{
+      name: string;
+      full_name: string;
+      private: boolean;
+      html_url: string;
+      description: string | null;
+      updated_at: string;
+      clone_url: string;
+      owner: { login: string };
+    }>;
+    for (const item of items) {
+      if (
+        typeof item.name !== "string" ||
+        typeof item.full_name !== "string" ||
+        !item.owner ||
+        typeof item.owner.login !== "string"
+      ) {
+        throw new Error(
+          `GitHub /user/installations/${installationId}/repositories item missing required fields: ${JSON.stringify(item).slice(0, 200)}`,
+        );
+      }
+      repos.push({
+        owner: item.owner.login,
+        name: item.name,
+        full_name: item.full_name,
+        private: item.private,
+        html_url: item.html_url,
+        description: item.description,
+        updated_at: item.updated_at,
+        clone_url: item.clone_url,
+      });
+    }
+    // No more pages.
+    if (items.length < perPage) {
+      return { repos, truncated: false };
+    }
+    if (page === maxPages) {
+      truncated = true;
+    }
+  }
+  return { repos, truncated };
+}
+
 /**
  * Create a new repo on the authenticated user's account. Defaults to private
  * because the operator's vault is more likely sensitive than public. The
  * repo gets initialized empty (no README) so the first `git push` from the
  * mirror lands the operator's vault as commit 1.
+ *
+ * **403 with the shared app is EXPECTED** (vault#480): `POST /user/repos`
+ * requires the Administration repository permission (write); the shared
+ * Parachute app is frozen at Contents-only, so this call only succeeds for
+ * BYO-app operators whose app grants Administration:write. Throws
+ * `GitHubApiError` carrying the status so the route can map the 403 to the
+ * guided-manual-creation error rather than a generic failure.
  */
 export async function createRepo(
   token: string,
@@ -388,8 +639,9 @@ export async function createRepo(
     } catch {
       // not JSON
     }
-    throw new Error(
+    throw new GitHubApiError(
       `GitHub /user/repos create failed (${res.status}): ${parsed.message ?? body.slice(0, 200)}`,
+      res.status,
     );
   }
   const item = (await res.json()) as {

package/src/hub-jwt.test.ts

@@ -14,7 +14,14 @@
  */
 import { describe, test, expect, beforeAll, afterAll, beforeEach } from "bun:test";
 import { generateKeyPair, exportJWK, SignJWT } from "jose";
-import { resetJwksCache, resetRevocationCache, validateHubJwt, looksLikeJwt } from "./hub-jwt.ts";
+import {
+  resetJwksCache,
+  resetRevocationCache,
+  validateHubJwt,
+  looksLikeJwt,
+  getHubOrigin,
+  getJwksOrigin,
+} from "./hub-jwt.ts";
 
 interface Keypair {
   privateKey: CryptoKey;
@@ -113,6 +120,7 @@ async function signJwt(kp: Keypair, opts: SignOpts): Promise<string> {
 let fixture: JwksFixture;
 let kp: Keypair;
 let prevHubOrigin: string | undefined;
+let prevJwksOrigin: string | undefined;
 
 beforeAll(async () => {
   fixture = startJwksFixture();
@@ -124,12 +132,19 @@ afterAll(() => {
   fixture.stop();
   if (prevHubOrigin === undefined) delete process.env.PARACHUTE_HUB_ORIGIN;
   else process.env.PARACHUTE_HUB_ORIGIN = prevHubOrigin;
+  if (prevJwksOrigin === undefined) delete process.env.PARACHUTE_HUB_JWKS_ORIGIN;
+  else process.env.PARACHUTE_HUB_JWKS_ORIGIN = prevJwksOrigin;
 });
 
 beforeEach(() => {
-  // Each test sets its own origin for clarity.
+  // Each test sets its own origin for clarity. Post-vault#464 the JWKS *fetch*
+  // origin is resolved separately from the iss-validation origin, so point the
+  // JWKS fetch at the fixture too — otherwise the guard would read keys from
+  // the loopback default (no JWKS server there) and every case would fail.
   prevHubOrigin = process.env.PARACHUTE_HUB_ORIGIN;
+  prevJwksOrigin = process.env.PARACHUTE_HUB_JWKS_ORIGIN;
   process.env.PARACHUTE_HUB_ORIGIN = fixture.origin;
+  process.env.PARACHUTE_HUB_JWKS_ORIGIN = fixture.origin;
   fixture.setUnreachable(false);
   fixture.setKeys([kp]);
   resetJwksCache();
@@ -153,6 +168,64 @@ describe("looksLikeJwt", () => {
   });
 });
 
+describe("origin resolvers — iss/jwks split (vault#464)", () => {
+  test("getHubOrigin honors PARACHUTE_HUB_ORIGIN (iss-validation origin)", () => {
+    process.env.PARACHUTE_HUB_ORIGIN = "https://vault.example.com/";
+    expect(getHubOrigin()).toBe("https://vault.example.com");
+  });
+
+  test("getHubOrigin falls back to loopback when unset", () => {
+    delete process.env.PARACHUTE_HUB_ORIGIN;
+    expect(getHubOrigin()).toBe("http://127.0.0.1:1939");
+  });
+
+  test("getJwksOrigin defaults to loopback (no env override)", () => {
+    delete process.env.PARACHUTE_HUB_JWKS_ORIGIN;
+    expect(getJwksOrigin()).toBe("http://127.0.0.1:1939");
+  });
+
+  test("getJwksOrigin honors PARACHUTE_HUB_JWKS_ORIGIN and strips trailing slash", () => {
+    process.env.PARACHUTE_HUB_JWKS_ORIGIN = "http://10.0.0.5:1939/";
+    expect(getJwksOrigin()).toBe("http://10.0.0.5:1939");
+  });
+
+  test("jwks fetch is decoupled from the iss origin: keys served ONLY at the jwks origin still validate a token whose iss is the (separate) public origin", async () => {
+    // Mirrors the vault#464 deploy shape: iss + revocation live at the public
+    // origin (the default `fixture` here), while the JWKS is reachable only at
+    // a SEPARATE jwks origin (a second fixture standing in for loopback). The
+    // guard must fetch keys from the jwks origin, not the iss origin.
+    const jwksOnly = startJwksFixture();
+    jwksOnly.setKeys([kp]);
+    // The public iss origin (default fixture) serves revocation but NOT keys —
+    // if the guard fetched JWKS from here, verification would fail "no key".
+    fixture.setKeys([]);
+    try {
+      process.env.PARACHUTE_HUB_ORIGIN = fixture.origin; // iss + revocation
+      process.env.PARACHUTE_HUB_JWKS_ORIGIN = jwksOnly.origin; // keys only
+      resetJwksCache();
+      const token = await signJwt(kp, { iss: fixture.origin });
+      const claims = await validateHubJwt(token);
+      expect(claims.sub).toBe("user-1");
+    } finally {
+      jwksOnly.stop();
+    }
+  });
+
+  test("token whose iss does NOT match the iss origin is rejected even when keys resolve at the jwks origin", async () => {
+    const jwksOnly = startJwksFixture();
+    jwksOnly.setKeys([kp]);
+    try {
+      process.env.PARACHUTE_HUB_ORIGIN = fixture.origin;
+      process.env.PARACHUTE_HUB_JWKS_ORIGIN = jwksOnly.origin;
+      resetJwksCache();
+      const token = await signJwt(kp, { iss: "https://attacker.example" });
+      await expect(validateHubJwt(token)).rejects.toThrow(/verification failed/);
+    } finally {
+      jwksOnly.stop();
+    }
+  });
+});
+
 describe("validateHubJwt — happy path", () => {
   test("valid JWT with correct iss → claims surface", async () => {
     const token = await signJwt(kp, { iss: fixture.origin, scope: "vault:work:read vault:work:write" });

package/src/hub-jwt.ts

@@ -23,13 +23,18 @@ import {
 const DEFAULT_HUB_LOOPBACK = "http://127.0.0.1:1939";
 
 /**
- * Resolve the hub origin used to fetch JWKS and validate `iss`. Strips a
+ * Resolve the hub origin used to validate the token's `iss` claim. Strips a
  * trailing slash so we get a single canonical form.
  *
  * Order: env var → loopback fallback. We deliberately don't read
  * `~/.parachute/services.json` — the hub is the dispatcher, not a registered
  * service in that file. If a deployment exposes the hub on a non-default
  * origin, the env var is the contract.
+ *
+ * `parachute expose` pins `PARACHUTE_HUB_ORIGIN` to the PUBLIC FQDN so the
+ * `iss` we validate against matches what the hub stamps on the tokens it
+ * mints — keep using this origin for iss-validation. The JWKS *fetch* origin
+ * is resolved separately by `getJwksOrigin()`; see vault#464.
  */
 export function getHubOrigin(): string {
   const env = process.env.PARACHUTE_HUB_ORIGIN?.replace(/\/$/, "");
@@ -37,12 +42,44 @@ export function getHubOrigin(): string {
   return DEFAULT_HUB_LOOPBACK;
 }
 
+/**
+ * Resolve the origin used to FETCH the hub's JWKS — kept distinct from
+ * `getHubOrigin()` (the iss-validation origin) per vault#464.
+ *
+ * Vault is co-located with its hub (the hub supervises vault on the same box,
+ * the common deploy). After `parachute expose --cloudflare`, `getHubOrigin()`
+ * is the public Cloudflare FQDN. If we fetched JWKS from that public origin we
+ * would hairpin out through the tunnel and back to the same box — a round-trip
+ * that times out (hard fail under Docker NAT-loopback, slow/flaky on a real
+ * VPS) and 401s the first MCP connect after expose. So we always read keys
+ * from the LOCAL hub on loopback instead.
+ *
+ * Order: `PARACHUTE_HUB_JWKS_ORIGIN` override → loopback default. The override
+ * exists for the rare non-co-located case — a vault running on a DIFFERENT box
+ * than its hub sets `PARACHUTE_HUB_JWKS_ORIGIN` to the hub's reachable
+ * internal address. Trailing-slash-stripped, matching `getHubOrigin()`.
+ */
+export function getJwksOrigin(): string {
+  const env = process.env.PARACHUTE_HUB_JWKS_ORIGIN?.replace(/\/$/, "");
+  if (env && env.length > 0) return env;
+  return DEFAULT_HUB_LOOPBACK;
+}
+
 // Process-wide guard. The resolver form lets tests flip
-// `PARACHUTE_HUB_ORIGIN` between cases — the lib re-resolves on every
-// `validateHubJwt` and `resetJwksCache` call so the env-var change picks up
-// without a server restart. JWKS cache (5min/30s defaults) lives inside the
-// guard, shared across requests.
-const guard = createScopeGuard({ hubOrigin: () => getHubOrigin() });
+// `PARACHUTE_HUB_ORIGIN` / `PARACHUTE_HUB_JWKS_ORIGIN` between cases — the lib
+// re-resolves on every `validateHubJwt` and `resetJwksCache` call so the
+// env-var change picks up without a server restart. JWKS cache (5min/30s
+// defaults) lives inside the guard, shared across requests.
+//
+// The iss/jwks split (vault#464): `hubOrigin` validates the token's `iss`
+// (public FQDN post-expose, via PARACHUTE_HUB_ORIGIN); `jwksOrigin` fetches
+// the keys from the local hub (loopback by default, via
+// PARACHUTE_HUB_JWKS_ORIGIN). Co-located vault never egresses to read its own
+// hub's keys, so no tunnel hairpin.
+const guard = createScopeGuard({
+  hubOrigin: () => getHubOrigin(),
+  jwksOrigin: () => getJwksOrigin(),
+});
 
 /**
  * Verify a presented JWT against the hub's JWKS. Throws `HubJwtError` on any