@app-vitals/agent-admin 1.16.0 → 1.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@app-vitals/agent-admin",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/app-vitals/agent.git",
@@ -42,7 +42,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "0.135.0",
-    "@app-vitals/agent-lib": "1.16.0",
+    "@app-vitals/agent-lib": "1.17.0",
     "@hono/zod-openapi": "^1.0.0",
     "@prisma/adapter-pg": "^7.10.0",
     "@prisma/client": "^7.10.0",

package/src/fixtures/github-lookup-cassette.json

@@ -0,0 +1,499 @@
+{
+  "org_installation_success": {
+    "status": 200,
+    "body": {
+      "id": 7001,
+      "app_id": 555,
+      "app_slug": "example-lookup",
+      "target_type": "Organization",
+      "account": {
+        "login": "acme-eng",
+        "id": 11,
+        "type": "Organization"
+      },
+      "repository_selection": "all",
+      "permissions": {
+        "metadata": "read"
+      }
+    }
+  },
+  "org_installation_403": {
+    "status": 403,
+    "body": {
+      "message": "Resource not accessible by integration",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "org_installation_404": {
+    "status": 404,
+    "body": {
+      "message": "Not Found",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "org_installation_422": {
+    "status": 422,
+    "body": {
+      "message": "Validation Failed",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "org_installation_429": {
+    "status": 429,
+    "headers": {
+      "retry-after": "30"
+    },
+    "body": {
+      "message": "API rate limit exceeded",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "org_installation_500": {
+    "status": 500,
+    "body": {
+      "message": "Server Error",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "org_installation_503": {
+    "status": 503,
+    "body": {
+      "message": "Service Unavailable",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "lookup_token_success": {
+    "status": 201,
+    "body": {
+      "token": "ghs_lookupInstallationTokenSecret",
+      "expires_at": "2026-11-09T13:00:00Z",
+      "permissions": {
+        "metadata": "read"
+      },
+      "repository_selection": "all"
+    }
+  },
+  "lookup_token_403": {
+    "status": 403,
+    "body": {
+      "message": "Resource not accessible by integration",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "lookup_token_404": {
+    "status": 404,
+    "body": {
+      "message": "Not Found",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "lookup_token_422": {
+    "status": 422,
+    "body": {
+      "message": "Validation Failed",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "lookup_token_429": {
+    "status": 429,
+    "headers": {
+      "retry-after": "30"
+    },
+    "body": {
+      "message": "API rate limit exceeded",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "lookup_token_500": {
+    "status": 500,
+    "body": {
+      "message": "Server Error",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "lookup_token_503": {
+    "status": 503,
+    "body": {
+      "message": "Service Unavailable",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "repos_success": {
+    "status": 200,
+    "body": {
+      "total_count": 2,
+      "repositories": [
+        {
+          "id": 1,
+          "name": "api",
+          "full_name": "acme-eng/api",
+          "private": false,
+          "archived": false
+        },
+        {
+          "id": 2,
+          "name": "web",
+          "full_name": "acme-eng/web",
+          "private": true,
+          "archived": false
+        }
+      ]
+    }
+  },
+  "repos_page_1": {
+    "status": 200,
+    "headers": {
+      "link": "<https://ghe.test/installation/repositories?per_page=100&page=2>; rel=\"next\""
+    },
+    "body": {
+      "total_count": 3,
+      "repositories": [
+        {
+          "id": 1,
+          "name": "api",
+          "full_name": "acme-eng/api",
+          "private": false,
+          "archived": false
+        },
+        {
+          "id": 2,
+          "name": "web",
+          "full_name": "acme-eng/web",
+          "private": true,
+          "archived": false
+        }
+      ]
+    }
+  },
+  "repos_page_2": {
+    "status": 200,
+    "body": {
+      "total_count": 3,
+      "repositories": [
+        {
+          "id": 3,
+          "name": "infra",
+          "full_name": "acme-eng/infra",
+          "private": false,
+          "archived": false
+        }
+      ]
+    }
+  },
+  "repos_empty": {
+    "status": 200,
+    "body": {
+      "total_count": 0,
+      "repositories": []
+    }
+  },
+  "repos_403": {
+    "status": 403,
+    "body": {
+      "message": "Resource not accessible by integration",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "repos_404": {
+    "status": 404,
+    "body": {
+      "message": "Not Found",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "repos_422": {
+    "status": 422,
+    "body": {
+      "message": "Validation Failed",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "repos_429": {
+    "status": 429,
+    "headers": {
+      "retry-after": "30"
+    },
+    "body": {
+      "message": "API rate limit exceeded",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "repos_500": {
+    "status": 500,
+    "body": {
+      "message": "Server Error",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "repos_503": {
+    "status": 503,
+    "body": {
+      "message": "Service Unavailable",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "permission_admin": {
+    "status": 200,
+    "body": {
+      "permission": "admin",
+      "role_name": "admin",
+      "user": {
+        "login": "octocat",
+        "id": 583231,
+        "type": "User"
+      }
+    }
+  },
+  "permission_maintain": {
+    "status": 200,
+    "body": {
+      "permission": "write",
+      "role_name": "maintain",
+      "user": {
+        "login": "octocat",
+        "id": 583231,
+        "type": "User"
+      }
+    }
+  },
+  "permission_write": {
+    "status": 200,
+    "body": {
+      "permission": "write",
+      "role_name": "write",
+      "user": {
+        "login": "octocat",
+        "id": 583231,
+        "type": "User"
+      }
+    }
+  },
+  "permission_triage": {
+    "status": 200,
+    "body": {
+      "permission": "read",
+      "role_name": "triage",
+      "user": {
+        "login": "octocat",
+        "id": 583231,
+        "type": "User"
+      }
+    }
+  },
+  "permission_read": {
+    "status": 200,
+    "body": {
+      "permission": "read",
+      "role_name": "read",
+      "user": {
+        "login": "octocat",
+        "id": 583231,
+        "type": "User"
+      }
+    }
+  },
+  "permission_none": {
+    "status": 200,
+    "body": {
+      "permission": "none",
+      "role_name": "none",
+      "user": {
+        "login": "octocat",
+        "id": 583231,
+        "type": "User"
+      }
+    }
+  },
+  "permission_legacy_only": {
+    "status": 200,
+    "body": {
+      "permission": "write",
+      "user": {
+        "login": "octocat",
+        "id": 583231,
+        "type": "User"
+      }
+    }
+  },
+  "permission_unknown_role": {
+    "status": 200,
+    "body": {
+      "permission": "write",
+      "role_name": "custom-release-manager",
+      "user": {
+        "login": "octocat",
+        "id": 583231,
+        "type": "User"
+      }
+    }
+  },
+  "permission_403": {
+    "status": 403,
+    "body": {
+      "message": "Resource not accessible by integration",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "permission_404": {
+    "status": 404,
+    "body": {
+      "message": "Not Found",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "permission_422": {
+    "status": 422,
+    "body": {
+      "message": "Validation Failed",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "permission_429": {
+    "status": 429,
+    "headers": {
+      "retry-after": "30"
+    },
+    "body": {
+      "message": "API rate limit exceeded",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "permission_500": {
+    "status": 500,
+    "body": {
+      "message": "Server Error",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "permission_503": {
+    "status": 503,
+    "body": {
+      "message": "Service Unavailable",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "user_success": {
+    "status": 200,
+    "body": {
+      "login": "octocat",
+      "id": 583231,
+      "type": "User",
+      "name": "The Octocat"
+    }
+  },
+  "user_nonexistent": {
+    "status": 404,
+    "body": {
+      "message": "Not Found",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "user_403": {
+    "status": 403,
+    "body": {
+      "message": "Resource not accessible by integration",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "user_404": {
+    "status": 404,
+    "body": {
+      "message": "Not Found",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "user_422": {
+    "status": 422,
+    "body": {
+      "message": "Validation Failed",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "user_429": {
+    "status": 429,
+    "headers": {
+      "retry-after": "30"
+    },
+    "body": {
+      "message": "API rate limit exceeded",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "user_500": {
+    "status": 500,
+    "body": {
+      "message": "Server Error",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "user_503": {
+    "status": 503,
+    "body": {
+      "message": "Service Unavailable",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "member_yes": {
+    "status": 204,
+    "body": null
+  },
+  "member_no": {
+    "status": 404,
+    "body": {
+      "message": "Not Found",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "member_redirect": {
+    "status": 302,
+    "headers": {
+      "location": "https://api.github.com/orgs/acme-eng/public_members/octocat"
+    },
+    "body": null
+  },
+  "member_403": {
+    "status": 403,
+    "body": {
+      "message": "Resource not accessible by integration",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "member_404": {
+    "status": 404,
+    "body": {
+      "message": "Not Found",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "member_422": {
+    "status": 422,
+    "body": {
+      "message": "Validation Failed",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "member_429": {
+    "status": 429,
+    "headers": {
+      "retry-after": "30"
+    },
+    "body": {
+      "message": "API rate limit exceeded",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "member_500": {
+    "status": 500,
+    "body": {
+      "message": "Server Error",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "member_503": {
+    "status": 503,
+    "body": {
+      "message": "Service Unavailable",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  }
+}

package/src/github-lookup-client.integration.test.ts

@@ -0,0 +1,313 @@
+/**
+ * admin/src/github-lookup-client.integration.test.ts
+ * Integration tests for GithubLookupClient against hand-authored cassettes
+ * (fixtures/github-lookup-cassette.json, derived from GitHub's REST OpenAPI
+ * description; nothing was recorded live).
+ *
+ * Replays through an INJECTED fetchFn: no global.fetch override, no
+ * mock.module(). The RSA key is generated in-test.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { generateKeyPairSync } from "node:crypto";
+import { readFileSync } from "node:fs";
+import type { GithubEnterpriseErrorKind } from "./github-enterprise-client.ts";
+import { GithubLookupClient, type RepoRole } from "./github-lookup-client.ts";
+
+interface CassetteEntry {
+  status: number;
+  headers?: Record<string, string>;
+  body: unknown;
+}
+
+const cassette: Record<string, CassetteEntry> = JSON.parse(
+  readFileSync(
+    new URL("./fixtures/github-lookup-cassette.json", import.meta.url).pathname,
+    "utf-8",
+  ),
+);
+
+const { privateKey } = generateKeyPairSync("rsa", {
+  modulusLength: 2048,
+  privateKeyEncoding: { type: "pkcs8", format: "pem" },
+  publicKeyEncoding: { type: "spki", format: "pem" },
+});
+
+const NOW = new Date("2026-11-09T12:00:00Z");
+const API = "https://ghe.test";
+const INST = "GET /orgs/acme-eng/installation";
+const MINT = "POST /app/installations/7001/access_tokens";
+const REPOS = "GET /installation/repositories";
+const PERM = "GET /repos/acme-eng/api/collaborators/octocat/permission";
+const USER = "GET /users/octocat";
+const MEMBER = "GET /orgs/acme-eng/members/octocat";
+
+interface Recorded {
+  method: string;
+  path: string;
+  headers: Headers;
+}
+
+/** routes: "METHOD /path[?page=N]" or "METHOD /path" -> cassette key. */
+function replay(routes: Record<string, string>) {
+  const calls: Recorded[] = [];
+  const fetchFn = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const u = new URL(input.toString());
+    const method = init?.method ?? "GET";
+    const page = u.searchParams.get("page");
+    const base = `${method} ${u.pathname}`;
+    calls.push({
+      method,
+      path: `${u.pathname}${u.search}`,
+      headers: new Headers(init?.headers),
+    });
+    const key = (page && routes[`${base}?page=${page}`]) || routes[base];
+    if (!key) throw new Error(`no route for ${base} page=${page}`);
+    const entry = cassette[key];
+    if (!entry) throw new Error(`cassette key not found: ${key}`);
+    const bodyless = entry.status === 204 || entry.status === 302;
+    return new Response(bodyless ? null : JSON.stringify(entry.body), {
+      status: entry.status,
+      headers: { "Content-Type": "application/json", ...(entry.headers ?? {}) },
+    });
+  }) as typeof fetch;
+  return { fetchFn, calls };
+}
+
+const OK = {
+  [INST]: "org_installation_success",
+  [MINT]: "lookup_token_success",
+};
+
+function makeClient(routes: Record<string, string>) {
+  const { fetchFn, calls } = replay({ ...OK, ...routes });
+  const client = new GithubLookupClient({
+    appId: "555",
+    privateKey,
+    apiBase: API,
+    fetchFn,
+    now: () => NOW,
+  });
+  return { client, calls };
+}
+
+const ERRORS: Array<[string, GithubEnterpriseErrorKind, number]> = [
+  ["403", "permission", 403],
+  ["404", "not_found", 404],
+  ["422", "validation", 422],
+  ["429", "rate_limit", 429],
+  ["500", "server", 500],
+  ["503", "server", 503],
+];
+
+async function errOf(p: Promise<unknown>) {
+  try {
+    await p;
+  } catch (e) {
+    return e as Error & {
+      kind: GithubEnterpriseErrorKind;
+      status?: number;
+      retryAfterSeconds?: number;
+    };
+  }
+  throw new Error("expected rejection");
+}
+
+function expectNoSecrets(e: Error) {
+  expect(e.message).not.toContain("PRIVATE KEY");
+  expect(e.message).not.toContain("ghs_lookup");
+  expect(e.message).not.toContain("Bearer");
+}
+
+describe("getOrgToken", () => {
+  it("looks up the org installation with a JWT then mints a token", async () => {
+    const { client, calls } = makeClient({});
+    expect(await client.getOrgToken("acme-eng")).toEqual({
+      token: "ghs_lookupInstallationTokenSecret",
+      expiresAt: "2026-11-09T13:00:00Z",
+      installationId: 7001,
+    });
+    expect(calls.map((c) => `${c.method} ${c.path}`)).toEqual([INST, MINT]);
+    for (const c of calls) {
+      expect(c.headers.get("authorization")).toMatch(
+        /^Bearer [\w-]+\.[\w-]+\.[\w-]+$/,
+      );
+    }
+  });
+
+  it("caches per org until near expiry", async () => {
+    const { client, calls } = makeClient({});
+    await client.getOrgToken("acme-eng");
+    await client.getOrgToken("ACME-ENG");
+    expect(calls).toHaveLength(2);
+  });
+
+  for (const [suffix, kind, status] of ERRORS) {
+    it(`maps installation lookup ${suffix} to ${kind}`, async () => {
+      const { client } = makeClient({ [INST]: `org_installation_${suffix}` });
+      const e = await errOf(client.getOrgToken("acme-eng"));
+      expect(e.kind).toBe(kind);
+      expect(e.status).toBe(status);
+      expectNoSecrets(e);
+    });
+
+    it(`maps token mint ${suffix} to ${kind}`, async () => {
+      const { client } = makeClient({ [MINT]: `lookup_token_${suffix}` });
+      const e = await errOf(client.getOrgToken("acme-eng"));
+      expect(e.kind).toBe(kind);
+      expect(e.status).toBe(status);
+      expectNoSecrets(e);
+    });
+  }
+
+  it("surfaces retry-after on 429", async () => {
+    const { client } = makeClient({ [MINT]: "lookup_token_429" });
+    expect(
+      (await errOf(client.getOrgToken("acme-eng"))).retryAfterSeconds,
+    ).toBe(30);
+  });
+});
+
+describe("listInstallationRepositories", () => {
+  it("lists a single page with the installation token", async () => {
+    const { client, calls } = makeClient({ [REPOS]: "repos_success" });
+    const repos = await client.listInstallationRepositories("acme-eng");
+    expect(repos).toEqual([
+      {
+        id: 1,
+        name: "api",
+        fullName: "acme-eng/api",
+        private: false,
+        archived: false,
+      },
+      {
+        id: 2,
+        name: "web",
+        fullName: "acme-eng/web",
+        private: true,
+        archived: false,
+      },
+    ]);
+    expect(calls.at(-1)?.headers.get("authorization")).toBe(
+      "Bearer ghs_lookupInstallationTokenSecret",
+    );
+  });
+
+  it("follows the Link header across pages", async () => {
+    const { client, calls } = makeClient({
+      [`${REPOS}?page=1`]: "repos_page_1",
+      [`${REPOS}?page=2`]: "repos_page_2",
+    });
+    const repos = await client.listInstallationRepositories("acme-eng");
+    expect(repos.map((r) => r.name)).toEqual(["api", "web", "infra"]);
+    expect(
+      calls.filter((c) => c.path.startsWith("/installation/repositories")),
+    ).toHaveLength(2);
+  });
+
+  it("returns an empty list", async () => {
+    const { client } = makeClient({ [REPOS]: "repos_empty" });
+    expect(await client.listInstallationRepositories("acme-eng")).toEqual([]);
+  });
+
+  for (const [suffix, kind] of ERRORS) {
+    it(`maps ${suffix} to ${kind}`, async () => {
+      const { client } = makeClient({ [REPOS]: `repos_${suffix}` });
+      const e = await errOf(client.listInstallationRepositories("acme-eng"));
+      expect(e.kind).toBe(kind);
+      expectNoSecrets(e);
+    });
+  }
+});
+
+describe("getCollaboratorPermission", () => {
+  const roles: Array<[string, RepoRole]> = [
+    ["permission_admin", "admin"],
+    ["permission_maintain", "maintain"],
+    ["permission_write", "write"],
+    ["permission_triage", "triage"],
+    ["permission_read", "read"],
+    ["permission_none", "none"],
+    ["permission_legacy_only", "write"],
+  ];
+  for (const [key, role] of roles) {
+    it(`maps ${key} to ${role}`, async () => {
+      const { client } = makeClient({ [PERM]: key });
+      expect(
+        await client.getCollaboratorPermission("acme-eng", "api", "octocat"),
+      ).toBe(role);
+    });
+  }
+
+  it("rejects an unknown role as an error, not none", async () => {
+    const { client } = makeClient({ [PERM]: "permission_unknown_role" });
+    const e = await errOf(
+      client.getCollaboratorPermission("acme-eng", "api", "octocat"),
+    );
+    expect(e.kind).toBe("unexpected");
+  });
+
+  for (const [suffix, kind] of ERRORS) {
+    it(`maps ${suffix} to ${kind}`, async () => {
+      const { client } = makeClient({ [PERM]: `permission_${suffix}` });
+      const e = await errOf(
+        client.getCollaboratorPermission("acme-eng", "api", "octocat"),
+      );
+      expect(e.kind).toBe(kind);
+      expectNoSecrets(e);
+    });
+  }
+});
+
+describe("getUser", () => {
+  it("returns the user", async () => {
+    const { client } = makeClient({ [USER]: "user_success" });
+    expect(await client.getUser("acme-eng", "octocat")).toEqual({
+      id: 583231,
+      login: "octocat",
+      type: "User",
+    });
+  });
+
+  it("reports a nonexistent user as not_found", async () => {
+    const { client } = makeClient({ [USER]: "user_nonexistent" });
+    const e = await errOf(client.getUser("acme-eng", "octocat"));
+    expect(e.kind).toBe("not_found");
+  });
+
+  for (const [suffix, kind] of ERRORS) {
+    it(`maps ${suffix} to ${kind}`, async () => {
+      const { client } = makeClient({ [USER]: `user_${suffix}` });
+      const e = await errOf(client.getUser("acme-eng", "octocat"));
+      expect(e.kind).toBe(kind);
+      expectNoSecrets(e);
+    });
+  }
+});
+
+describe("isOrgMember", () => {
+  it("is true on 204", async () => {
+    const { client } = makeClient({ [MEMBER]: "member_yes" });
+    expect(await client.isOrgMember("acme-eng", "octocat")).toBe(true);
+  });
+
+  it("is false on 404", async () => {
+    const { client } = makeClient({ [MEMBER]: "member_no" });
+    expect(await client.isOrgMember("acme-eng", "octocat")).toBe(false);
+  });
+
+  it("treats a 302 as an error, not as non-membership", async () => {
+    const { client } = makeClient({ [MEMBER]: "member_redirect" });
+    const e = await errOf(client.isOrgMember("acme-eng", "octocat"));
+    expect(e.kind).toBe("unexpected");
+  });
+
+  for (const [suffix, kind] of ERRORS.filter(([s]) => s !== "404")) {
+    it(`maps ${suffix} to ${kind}`, async () => {
+      const { client } = makeClient({ [MEMBER]: `member_${suffix}` });
+      const e = await errOf(client.isOrgMember("acme-eng", "octocat"));
+      expect(e.kind).toBe(kind);
+      expectNoSecrets(e);
+    });
+  }
+});

package/src/github-lookup-client.ts

@@ -0,0 +1,308 @@
+/**
+ * admin/src/github-lookup-client.ts
+ * GithubLookupClient: read-only lookups through the admin-level "lookup"
+ * GitHub App (GHE-1.1), installed on each organization it needs to read.
+ *
+ * Flow per org: sign app JWT -> GET /orgs/{org}/installation (JWT) ->
+ * POST /app/installations/{id}/access_tokens (JWT) -> read calls with the
+ * installation token. Sibling of GithubEnterpriseClient: it shares the JWT
+ * signer and the typed error (kinds keep rate limits and server errors
+ * distinguishable from not-found), and never puts a token or key in a message.
+ *
+ * Endpoints follow GitHub's published REST OpenAPI description
+ * (api.github.com.json); nothing here was verified live.
+ */
+
+import { signGithubAppJwt } from "./github-app-jwt.ts";
+import {
+  GithubEnterpriseError,
+  mapGithubEnterpriseError,
+} from "./github-enterprise-client.ts";
+
+export type RepoRole =
+  | "admin"
+  | "maintain"
+  | "write"
+  | "triage"
+  | "read"
+  | "none";
+
+export const REPO_ROLES: readonly RepoRole[] = [
+  "admin",
+  "maintain",
+  "write",
+  "triage",
+  "read",
+  "none",
+];
+
+/**
+ * Map GitHub's role string to a RepoRole. Exhaustive: an unknown role (for
+ * example a custom repository role) is an error, never silently "none".
+ */
+export function mapRepoRole(role: unknown): RepoRole {
+  if (
+    typeof role === "string" &&
+    (REPO_ROLES as readonly string[]).includes(role)
+  ) {
+    return role as RepoRole;
+  }
+  throw new GithubEnterpriseError(
+    "unexpected",
+    `GitHub collaborator permission: unknown role ${
+      typeof role === "string" ? JSON.stringify(role.slice(0, 40)) : typeof role
+    }`,
+  );
+}
+
+export interface LookupRepository {
+  id: number;
+  name: string;
+  fullName: string;
+  private: boolean;
+  archived: boolean;
+}
+
+export interface LookupUser {
+  id: number;
+  login: string;
+  type: string;
+}
+
+export interface LookupToken {
+  token: string;
+  expiresAt: string;
+  installationId: number;
+}
+
+export interface GithubLookupClientOptions {
+  appId: string;
+  privateKey: string;
+  apiBase?: string;
+  fetchFn?: typeof fetch;
+  now?: () => Date;
+}
+
+const PER_PAGE = 100;
+const MAX_PAGES = 100;
+/** Refresh a cached installation token this long before it expires. */
+const TOKEN_REFRESH_SKEW_MS = 60_000;
+
+export class GithubLookupClient {
+  private readonly appId: string;
+  private readonly privateKey: string;
+  private readonly apiBase: string;
+  private readonly fetchFn: typeof fetch;
+  private readonly now: () => Date;
+  private readonly cached = new Map<string, LookupToken>();
+
+  constructor(opts: GithubLookupClientOptions) {
+    this.appId = opts.appId;
+    this.privateKey = opts.privateKey;
+    this.apiBase = opts.apiBase ?? "https://api.github.com";
+    this.fetchFn = opts.fetchFn ?? fetch;
+    this.now = opts.now ?? (() => new Date());
+  }
+
+  /** Mint (or reuse a still-fresh) installation token for the lookup App on `org`. */
+  async getOrgToken(org: string): Promise<LookupToken> {
+    const key = org.toLowerCase();
+    const hit = this.cached.get(key);
+    if (
+      hit &&
+      Date.parse(hit.expiresAt) - this.now().getTime() > TOKEN_REFRESH_SKEW_MS
+    ) {
+      return hit;
+    }
+    const jwt = signGithubAppJwt({
+      appId: this.appId,
+      privateKey: this.privateKey,
+      now: this.now(),
+    });
+    const inst = await this.request<{ id?: number }>(
+      "GET",
+      `/orgs/${encodeURIComponent(org)}/installation`,
+      jwt,
+      "GitHub org installation lookup",
+    );
+    if (typeof inst.data?.id !== "number") {
+      throw new GithubEnterpriseError(
+        "unexpected",
+        "GitHub org installation lookup: response missing id",
+      );
+    }
+    const minted = await this.request<{ token?: string; expires_at?: string }>(
+      "POST",
+      `/app/installations/${inst.data.id}/access_tokens`,
+      jwt,
+      "GitHub installation access token",
+    );
+    if (!minted.data?.token || !minted.data.expires_at) {
+      throw new GithubEnterpriseError(
+        "unexpected",
+        "GitHub installation access token: response missing token or expires_at",
+      );
+    }
+    const token: LookupToken = {
+      token: minted.data.token,
+      expiresAt: minted.data.expires_at,
+      installationId: inst.data.id,
+    };
+    this.cached.set(key, token);
+    return token;
+  }
+
+  /** List every repository the lookup App can see on `org` (paginated). */
+  async listInstallationRepositories(org: string): Promise<LookupRepository[]> {
+    const { token } = await this.getOrgToken(org);
+    const all: LookupRepository[] = [];
+    for (let page = 1; page <= MAX_PAGES; page++) {
+      const res = await this.request<{ repositories?: RawRepository[] }>(
+        "GET",
+        `/installation/repositories?per_page=${PER_PAGE}&page=${page}`,
+        token,
+        "GitHub installation repositories",
+      );
+      const rows = res.data?.repositories;
+      if (!Array.isArray(rows)) {
+        throw new GithubEnterpriseError(
+          "unexpected",
+          "GitHub installation repositories: response is not a repository list",
+        );
+      }
+      for (const r of rows) all.push(toRepository(r));
+      const link = res.headers.get("link");
+      const hasNext =
+        link !== null ? /rel="next"/.test(link) : rows.length >= PER_PAGE;
+      if (!hasNext) break;
+    }
+    return all;
+  }
+
+  /**
+   * A user's role on `owner/repo`. Prefers `role_name` (carries maintain and
+   * triage), falling back to the legacy `permission` field.
+   */
+  async getCollaboratorPermission(
+    owner: string,
+    repo: string,
+    username: string,
+  ): Promise<RepoRole> {
+    const { token } = await this.getOrgToken(owner);
+    const res = await this.request<{
+      permission?: unknown;
+      role_name?: unknown;
+    }>(
+      "GET",
+      `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/collaborators/${encodeURIComponent(username)}/permission`,
+      token,
+      "GitHub collaborator permission",
+    );
+    return mapRepoRole(res.data?.role_name ?? res.data?.permission);
+  }
+
+  /** Look up a user. A nonexistent login throws kind "not_found". */
+  async getUser(org: string, login: string): Promise<LookupUser> {
+    const { token } = await this.getOrgToken(org);
+    const res = await this.request<{
+      id?: number;
+      login?: string;
+      type?: string;
+    }>(
+      "GET",
+      `/users/${encodeURIComponent(login)}`,
+      token,
+      "GitHub user lookup",
+    );
+    if (
+      typeof res.data?.id !== "number" ||
+      typeof res.data.login !== "string"
+    ) {
+      throw new GithubEnterpriseError(
+        "unexpected",
+        "GitHub user lookup: response missing id or login",
+      );
+    }
+    return {
+      id: res.data.id,
+      login: res.data.login,
+      type: res.data.type ?? "User",
+    };
+  }
+
+  /**
+   * Whether `username` is a member of `org`. GitHub answers 204 (member) or
+   * 404 (not a member, or no such org); a 302 means the requester cannot see
+   * the member list and is reported as an error, not as "not a member".
+   */
+  async isOrgMember(org: string, username: string): Promise<boolean> {
+    const { token } = await this.getOrgToken(org);
+    try {
+      await this.request(
+        "GET",
+        `/orgs/${encodeURIComponent(org)}/members/${encodeURIComponent(username)}`,
+        token,
+        "GitHub org membership",
+      );
+      return true;
+    } catch (err) {
+      if (err instanceof GithubEnterpriseError && err.kind === "not_found")
+        return false;
+      throw err;
+    }
+  }
+
+  private async request<T>(
+    method: "GET" | "POST",
+    path: string,
+    bearer: string,
+    context: string,
+  ): Promise<{ status: number; headers: Headers; data: T }> {
+    let resp: Response;
+    try {
+      resp = await this.fetchFn(`${this.apiBase}${path}`, {
+        method,
+        redirect: "manual",
+        headers: {
+          Accept: "application/vnd.github+json",
+          Authorization: `Bearer ${bearer}`,
+          "X-GitHub-Api-Version": "2022-11-28",
+        },
+      });
+    } catch {
+      // The underlying error is dropped on purpose: it must never echo headers.
+      throw new GithubEnterpriseError("network", `${context}: network error`);
+    }
+    let data: unknown;
+    try {
+      data = await resp.json();
+    } catch {
+      data = undefined;
+    }
+    if (!resp.ok) {
+      throw mapGithubEnterpriseError(resp.status, resp.headers, data, context, [
+        bearer,
+        this.privateKey,
+      ]);
+    }
+    return { status: resp.status, headers: resp.headers, data: data as T };
+  }
+}
+
+interface RawRepository {
+  id: number;
+  name: string;
+  full_name: string;
+  private?: boolean;
+  archived?: boolean;
+}
+
+function toRepository(r: RawRepository): LookupRepository {
+  return {
+    id: r.id,
+    name: r.name,
+    fullName: r.full_name,
+    private: r.private === true,
+    archived: r.archived === true,
+  };
+}

package/src/github-lookup-client.unit.test.ts

@@ -0,0 +1,93 @@
+/**
+ * admin/src/github-lookup-client.unit.test.ts
+ * Unit tests for role mapping and error handling of GithubLookupClient.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { generateKeyPairSync } from "node:crypto";
+import { GithubEnterpriseError } from "./github-enterprise-client.ts";
+import {
+  GithubLookupClient,
+  mapRepoRole,
+  REPO_ROLES,
+} from "./github-lookup-client.ts";
+
+describe("mapRepoRole", () => {
+  it.each([...REPO_ROLES])("maps %s to itself", (role) => {
+    expect(mapRepoRole(role)).toBe(role);
+  });
+
+  it.each(["custom-role", "ADMIN", "", "owner"])(
+    "rejects unknown role %p instead of treating it as none",
+    (role) => {
+      try {
+        mapRepoRole(role);
+      } catch (e) {
+        expect(e).toBeInstanceOf(GithubEnterpriseError);
+        expect((e as GithubEnterpriseError).kind).toBe("unexpected");
+        return;
+      }
+      throw new Error("expected rejection");
+    },
+  );
+
+  it.each([undefined, null, 5, {}])("rejects non-string role %p", (role) => {
+    expect(() => mapRepoRole(role)).toThrow(GithubEnterpriseError);
+  });
+});
+
+describe("GithubLookupClient errors", () => {
+  const { privateKey } = generateKeyPairSync("rsa", {
+    modulusLength: 2048,
+    privateKeyEncoding: { type: "pkcs8", format: "pem" },
+    publicKeyEncoding: { type: "spki", format: "pem" },
+  });
+
+  it("reports a network failure as kind network without the underlying message", async () => {
+    const client = new GithubLookupClient({
+      appId: "555",
+      privateKey,
+      fetchFn: (async () => {
+        throw new Error("connect failed Authorization: Bearer ghs_leak");
+      }) as unknown as typeof fetch,
+    });
+    try {
+      await client.getOrgToken("acme-eng");
+    } catch (e) {
+      const err = e as GithubEnterpriseError;
+      expect(err.kind).toBe("network");
+      expect(err.message).not.toContain("ghs_leak");
+      return;
+    }
+    throw new Error("expected rejection");
+  });
+
+  it("redacts an echoed token from an error message", async () => {
+    let n = 0;
+    const client = new GithubLookupClient({
+      appId: "555",
+      privateKey,
+      fetchFn: (async (_u: unknown, init?: RequestInit) => {
+        n++;
+        if (n === 1) return Response.json({ id: 1 });
+        const bearer = String(
+          new Headers(init?.headers).get("authorization"),
+        ).slice(7);
+        return Response.json(
+          { message: `bad credentials ${bearer}` },
+          { status: 401 },
+        );
+      }) as unknown as typeof fetch,
+    });
+    try {
+      await client.getOrgToken("acme-eng");
+    } catch (e) {
+      const err = e as GithubEnterpriseError;
+      expect(err.kind).toBe("unauthorized");
+      expect(err.message).toContain("[redacted]");
+      expect(err.message).not.toMatch(/eyJ/);
+      return;
+    }
+    throw new Error("expected rejection");
+  });
+});