@openparachute/vault 0.6.0 → 0.6.2-rc.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 {