@app-vitals/agent-admin 1.12.1 → 1.14.0

package/src/github-app-api.ts

@@ -0,0 +1,111 @@
+/**
+ * admin/src/github-app-api.ts
+ * Two small GitHub App reads that sit beside GithubEnterpriseClient:
+ *
+ *  - fetchPublicApp(slug): GET /apps/{slug}, unauthenticated. Returns the App's
+ *    client id. A private App is 404 here (no credentials are sent).
+ *  - fetchAuthenticatedApp(): GET /app with an app JWT. Returns the App's
+ *    declared permissions; used to validate the 'lookup' role.
+ *
+ * Errors are GithubEnterpriseError (message redacted of the key); the key
+ * never appears in a result or an error.
+ */
+
+import {
+  GithubEnterpriseError,
+  mapGithubEnterpriseError,
+} from "./github-enterprise-client.ts";
+import { signGithubAppJwt } from "./github-app-jwt.ts";
+
+interface FetchOpts {
+  apiBase?: string;
+  fetchFn?: typeof fetch;
+}
+
+export interface PublicApp {
+  slug: string;
+  clientId: string | null;
+}
+
+async function getJson(
+  url: string,
+  headers: Record<string, string>,
+  context: string,
+  fetchFn: typeof fetch,
+  secrets: readonly string[],
+): Promise<unknown> {
+  let resp: Response;
+  try {
+    resp = await fetchFn(url, {
+      method: "GET",
+      headers: {
+        Accept: "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+        ...headers,
+      },
+    });
+  } catch {
+    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,
+      secrets,
+    );
+  }
+  return data;
+}
+
+/** GET /apps/{slug} (public). `slug` must already be validated. */
+export async function fetchPublicApp(
+  slug: string,
+  opts: FetchOpts = {},
+): Promise<PublicApp> {
+  const data = (await getJson(
+    `${opts.apiBase ?? "https://api.github.com"}/apps/${encodeURIComponent(slug)}`,
+    {},
+    "GitHub public App lookup",
+    opts.fetchFn ?? fetch,
+    [],
+  )) as { slug?: unknown; client_id?: unknown } | undefined;
+  return {
+    slug: typeof data?.slug === "string" ? data.slug : slug,
+    clientId:
+      typeof data?.client_id === "string" && data.client_id
+        ? data.client_id
+        : null,
+  };
+}
+
+/** GET /app with an app JWT: the App's own declared permissions. */
+export async function fetchAuthenticatedApp(
+  opts: FetchOpts & { appId: string; privateKey: string; now?: () => Date },
+): Promise<{ permissions: Record<string, string> }> {
+  const jwt = signGithubAppJwt({
+    appId: opts.appId,
+    privateKey: opts.privateKey,
+    now: opts.now?.(),
+  });
+  const data = (await getJson(
+    `${opts.apiBase ?? "https://api.github.com"}/app`,
+    { Authorization: `Bearer ${jwt}` },
+    "GitHub App lookup",
+    opts.fetchFn ?? fetch,
+    [jwt, opts.privateKey],
+  )) as { permissions?: Record<string, string> } | undefined;
+  return {
+    permissions:
+      data?.permissions && typeof data.permissions === "object"
+        ? data.permissions
+        : {},
+  };
+}

package/src/github-app-jwt.ts

@@ -0,0 +1,44 @@
+/**
+ * admin/src/github-app-jwt.ts
+ * RS256 signer for GitHub App JWTs (node:crypto only, no dependencies).
+ * https://docs.github.com/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-json-web-token-jwt-for-a-github-app
+ *
+ * Errors never include the private key material.
+ */
+
+import { createPrivateKey, sign } from "node:crypto";
+
+/** Backdate iat to absorb clock drift (GitHub's recommendation). */
+const IAT_BACKDATE_SECONDS = 60;
+/** exp - now. GitHub rejects a JWT whose exp is more than 10 minutes out. */
+const EXP_SECONDS = 540;
+
+function b64url(input: string | Buffer): string {
+  return Buffer.from(input).toString("base64url");
+}
+
+export function signGithubAppJwt(opts: {
+  appId: string;
+  privateKey: string;
+  now?: Date;
+}): string {
+  if (!opts.appId) throw new Error("GitHub App JWT: appId is required");
+  const nowS = Math.floor((opts.now ?? new Date()).getTime() / 1000);
+  const header = b64url(JSON.stringify({ alg: "RS256", typ: "JWT" }));
+  const payload = b64url(
+    JSON.stringify({
+      iss: opts.appId,
+      iat: nowS - IAT_BACKDATE_SECONDS,
+      exp: nowS + EXP_SECONDS,
+    }),
+  );
+  const signingInput = `${header}.${payload}`;
+  try {
+    const key = createPrivateKey(opts.privateKey);
+    const sig = sign("RSA-SHA256", Buffer.from(signingInput), key);
+    return `${signingInput}.${b64url(sig)}`;
+  } catch {
+    // Deliberately drop the underlying error: it can carry key details.
+    throw new Error("GitHub App JWT: invalid or unusable RSA private key");
+  }
+}

package/src/github-app-jwt.unit.test.ts

@@ -0,0 +1,95 @@
+/**
+ * admin/src/github-app-jwt.unit.test.ts
+ * Unit tests for the RS256 GitHub App JWT signer. The RSA key is generated
+ * in-test; no network, no fixtures.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { createPublicKey, generateKeyPairSync, verify } from "node:crypto";
+import { signGithubAppJwt } from "./github-app-jwt.ts";
+
+const { privateKey, publicKey } = generateKeyPairSync("rsa", {
+  modulusLength: 2048,
+  privateKeyEncoding: { type: "pkcs1", format: "pem" },
+  publicKeyEncoding: { type: "spki", format: "pem" },
+});
+const pkcs8 = generateKeyPairSync("rsa", {
+  modulusLength: 2048,
+  privateKeyEncoding: { type: "pkcs8", format: "pem" },
+  publicKeyEncoding: { type: "spki", format: "pem" },
+});
+
+const NOW = new Date("2026-11-09T12:00:00Z");
+const NOW_S = Math.floor(NOW.getTime() / 1000);
+
+function decode(part: string): Record<string, unknown> {
+  return JSON.parse(Buffer.from(part, "base64url").toString("utf-8"));
+}
+
+describe("signGithubAppJwt", () => {
+  const jwt = signGithubAppJwt({ appId: "12345", privateKey, now: NOW });
+  const [h, p, s] = jwt.split(".") as [string, string, string];
+
+  it("has three base64url segments with an RS256 header", () => {
+    expect(jwt.split(".")).toHaveLength(3);
+    expect(jwt).not.toMatch(/[+/=]/);
+    expect(decode(h)).toEqual({ alg: "RS256", typ: "JWT" });
+  });
+
+  it("sets iss to the app id, iat backdated 60s and exp within GitHub's 10 minute cap", () => {
+    const claims = decode(p) as { iss: string; iat: number; exp: number };
+    expect(claims.iss).toBe("12345");
+    expect(claims.iat).toBe(NOW_S - 60);
+    expect(claims.exp).toBe(NOW_S + 540);
+    expect(claims.exp - NOW_S).toBeLessThanOrEqual(600);
+  });
+
+  it("verifies against the matching public key", () => {
+    expect(
+      verify(
+        "RSA-SHA256",
+        Buffer.from(`${h}.${p}`),
+        createPublicKey(publicKey),
+        Buffer.from(s, "base64url"),
+      ),
+    ).toBe(true);
+  });
+
+  it("fails verification against a different key", () => {
+    expect(
+      verify(
+        "RSA-SHA256",
+        Buffer.from(`${h}.${p}`),
+        createPublicKey(pkcs8.publicKey),
+        Buffer.from(s, "base64url"),
+      ),
+    ).toBe(false);
+  });
+
+  it("accepts PKCS#8 keys", () => {
+    const j = signGithubAppJwt({
+      appId: "1",
+      privateKey: pkcs8.privateKey,
+      now: NOW,
+    });
+    expect(j.split(".")).toHaveLength(3);
+  });
+
+  it("throws a key-free error for an invalid key", () => {
+    const bad = "-----BEGIN RSA PRIVATE KEY-----\nSECRETGARBAGE\n-----END RSA PRIVATE KEY-----";
+    let msg = "";
+    try {
+      signGithubAppJwt({ appId: "1", privateKey: bad, now: NOW });
+    } catch (e) {
+      msg = (e as Error).message;
+    }
+    expect(msg).toContain("private key");
+    expect(msg).not.toContain("SECRETGARBAGE");
+  });
+
+  it("rejects an empty app id", () => {
+    expect(() =>
+      signGithubAppJwt({ appId: "", privateKey, now: NOW }),
+    ).toThrow();
+  });
+});

package/src/github-enterprise-api.integration.test.ts

@@ -0,0 +1,264 @@
+/**
+ * admin/src/github-enterprise-api.integration.test.ts
+ * Integration tests for the /github-enterprise routes against a real
+ * PostgreSQL DB and the GHE-1.2 cassettes (replayed through an injected
+ * fetchFn): the validate flow end to end, plus the isolation guarantee that
+ * no agent-facing path can return a stored key.
+ *
+ * Requires DATABASE_URL_ADMIN_TEST to be set; skips otherwise.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { generateKeyPairSync } from "node:crypto";
+import { readFileSync } from "node:fs";
+import type { PrismaClient } from "../prisma/client/client.ts";
+import { AgentEnvService } from "./agent-envs.ts";
+import { AgentPluginService } from "./agent-plugins.ts";
+import { AgentService } from "./agents.ts";
+import { createAgentRuntimeApp } from "./api.ts";
+import { parseAdminApiKeys } from "./api-auth.ts";
+import { createGithubEnterpriseApp } from "./github-enterprise-api.ts";
+import { GitHubEnterpriseAppService } from "./github-enterprise-apps.ts";
+import { createAdminPrismaClient } from "./prisma-client.ts";
+import { identityCrypto, makeStrictTokenCrypto } from "./token-crypto.ts";
+
+const TEST_DB = process.env.DATABASE_URL_ADMIN_TEST;
+const describeOrSkip = TEST_DB ? describe : describe.skip;
+
+const cassette: Record<
+  string,
+  { status: number; headers?: Record<string, string>; body: unknown }
+> = JSON.parse(
+  readFileSync(
+    new URL("./fixtures/github-enterprise-cassette.json", import.meta.url)
+      .pathname,
+    "utf-8",
+  ),
+);
+
+const { privateKey: PEM } = generateKeyPairSync("rsa", {
+  modulusLength: 2048,
+  privateKeyEncoding: { type: "pkcs8", format: "pem" },
+  publicKeyEncoding: { type: "spki", format: "pem" },
+});
+const PEM_BODY = PEM.split("\n")[1] as string;
+const ENC_KEY = "c".repeat(64);
+const ADMIN = { Authorization: "Bearer tok-admin" };
+
+function replay(routes: Record<string, string>): typeof fetch {
+  return (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const u = new URL(input.toString());
+    const key = routes[`${init?.method ?? "GET"} ${u.pathname}`];
+    if (!key) throw new Error(`no route for ${init?.method} ${u.pathname}`);
+    const e = cassette[key];
+    return new Response(JSON.stringify(e?.body), {
+      status: e?.status,
+      headers: { "Content-Type": "application/json" },
+    });
+  }) as typeof fetch;
+}
+
+describeOrSkip("github-enterprise API (integration)", () => {
+  let prisma: PrismaClient;
+  let appService: GitHubEnterpriseAppService;
+
+  const build = (routes: Record<string, string> = {}) =>
+    createGithubEnterpriseApp({
+      appService,
+      agentService: new AgentService(prisma),
+      agentEnvService: new AgentEnvService(prisma, identityCrypto),
+      sessionSecret: "test-secret-32chars-for-ghe-api!!",
+      adminApiKeys: parseAdminApiKeys("root:tok-admin:*"),
+      agentTokenService: { validate: async () => null },
+      fetchFn: replay({
+        "GET /enterprises/acme/installation": "enterprise_installation_success",
+        "POST /app/installations/4242/access_tokens": "access_token_success",
+        ...routes,
+      }),
+      apiBase: "https://ghe.test",
+      now: () => new Date("2026-11-09T12:00:00Z"),
+    });
+
+  const put = (app: ReturnType<typeof build>) =>
+    app.request("/github-enterprise/apps/installer", {
+      method: "PUT",
+      headers: { ...ADMIN, "Content-Type": "application/json" },
+      body: JSON.stringify({
+        appId: "12345",
+        slug: "example-installer",
+        enterpriseSlug: "acme",
+        privateKey: PEM,
+      }),
+    });
+
+  beforeEach(async () => {
+    prisma = createAdminPrismaClient(TEST_DB as string);
+    await prisma.gitHubEnterpriseApp.deleteMany();
+    await prisma.agentEnv.deleteMany();
+    await prisma.agentToken.deleteMany();
+    await prisma.agentCronJob.deleteMany();
+    await prisma.agentTool.deleteMany();
+    await prisma.agent.deleteMany();
+    appService = new GitHubEnterpriseAppService(
+      prisma,
+      makeStrictTokenCrypto(ENC_KEY),
+    );
+  });
+
+  afterEach(async () => {
+    await prisma.$disconnect();
+  });
+
+  it("unconfigured: status is empty and nothing is written", async () => {
+    const app = build();
+    const res = await app.request("/github-enterprise/apps", {
+      headers: ADMIN,
+    });
+    expect(await res.json()).toEqual({
+      configured: false,
+      installer: null,
+      lookup: null,
+    });
+    expect(await prisma.gitHubEnterpriseApp.count()).toBe(0);
+  });
+
+  it("PUT then validate persists the result; the key is encrypted and never returned", async () => {
+    const app = build();
+    const saved = await put(app);
+    expect(saved.status).toBe(200);
+    expect(await saved.text()).not.toContain(PEM_BODY);
+
+    const res = await app.request(
+      "/github-enterprise/apps/installer/validate",
+      {
+        method: "POST",
+        headers: ADMIN,
+      },
+    );
+    expect(res.status).toBe(200);
+    const text = await res.text();
+    expect(text).not.toContain(PEM_BODY);
+    expect(text).not.toContain("ghs_cassette");
+    expect(JSON.parse(text)).toMatchObject({ ok: true, status: "valid" });
+
+    const row = await prisma.gitHubEnterpriseApp.findUnique({
+      where: { role: "installer" },
+    });
+    expect(row?.lastValidationStatus).toBe("valid");
+    expect(row?.lastValidatedAt).toBeInstanceOf(Date);
+    expect(row?.privateKeyEncrypted).not.toContain(PEM_BODY);
+
+    const status = await app.request("/github-enterprise/apps", {
+      headers: ADMIN,
+    });
+    const st = await status.text();
+    expect(st).not.toContain(PEM_BODY);
+    expect(st).not.toContain(row?.privateKeyEncrypted as string);
+    expect(JSON.parse(st).installer.lastValidationStatus).toBe("valid");
+  });
+
+  it("validate against a cassette 403 records an error status", async () => {
+    const app = build({
+      "GET /enterprises/acme/installation": "enterprise_installation_403",
+    });
+    await put(app);
+    const res = await app.request(
+      "/github-enterprise/apps/installer/validate",
+      {
+        method: "POST",
+        headers: ADMIN,
+      },
+    );
+    expect(await res.json()).toMatchObject({ ok: false, status: "error" });
+    const row = await prisma.gitHubEnterpriseApp.findUnique({
+      where: { role: "installer" },
+    });
+    expect(row?.lastValidationStatus).toBe("error");
+    expect(row?.lastValidationError).not.toContain("Resource not accessible");
+  });
+
+  it("PUT without SHIPWRIGHT_ENCRYPTION_KEY is refused with 422 and stores nothing", async () => {
+    appService = new GitHubEnterpriseAppService(
+      prisma,
+      makeStrictTokenCrypto(undefined),
+    );
+    const res = await put(build());
+    expect(res.status).toBe(422);
+    expect(await prisma.gitHubEnterpriseApp.count()).toBe(0);
+  });
+
+  it("install resolves the agent's slug from its stored env against the cassettes", async () => {
+    const agent = await prisma.agent.create({ data: { name: "Ghe Agent" } });
+    await new AgentEnvService(prisma, identityCrypto).upsert(agent.id, {
+      GH_APP_SLUG: "example-agent-app",
+    });
+    const app = build({
+      "GET /apps/example-agent-app": "public_app_success",
+      "POST /enterprises/acme/apps/organizations/org-1/installations":
+        "install_created",
+    });
+    await put(app);
+    const res = await app.request("/github-enterprise/orgs/org-1/install", {
+      method: "POST",
+      headers: { ...ADMIN, "Content-Type": "application/json" },
+      body: JSON.stringify({ agentId: agent.id }),
+    });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toMatchObject({ created: true, org: "org-1" });
+  });
+
+  it("isolation: no agent-facing path returns the stored key", async () => {
+    const agent = await prisma.agent.create({ data: { name: "Iso Agent" } });
+    const envService = new AgentEnvService(prisma, identityCrypto);
+    await envService.upsert(agent.id, { GH_APP_SLUG: "example-agent-app" });
+    await put(build());
+    const row = await prisma.gitHubEnterpriseApp.findUnique({
+      where: { role: "installer" },
+    });
+    const needles = [
+      PEM_BODY,
+      "PRIVATE KEY",
+      row?.privateKeyEncrypted as string,
+    ];
+
+    const surfaces: unknown[] = [
+      await envService.getConfigBundle(agent.id),
+      await envService.getByAgentId(agent.id),
+    ];
+    const runtime = createAgentRuntimeApp({
+      agentEnvService: envService,
+      agentCronJobService: { list: async () => [] },
+      agentService: new AgentService(prisma),
+      agentPluginService: new AgentPluginService(prisma),
+      adminApiKeys: parseAdminApiKeys(`agent-key:agent-tok:${agent.id}`),
+      agentTokenService: { validate: async () => null },
+      sessionSecret: "test-secret-32chars-for-ghe-api!!",
+    });
+    for (const path of [`/${agent.id}/config`, `/${agent.id}/crons`]) {
+      const res = await runtime.request(path, {
+        headers: { Authorization: "Bearer agent-tok" },
+      });
+      expect(res.status).toBe(200);
+      surfaces.push(await res.text());
+    }
+    for (const surface of surfaces) {
+      const text =
+        typeof surface === "string" ? surface : JSON.stringify(surface);
+      for (const needle of needles) expect(text).not.toContain(needle);
+    }
+
+    // The agent-bearer key cannot reach the key-bearing admin routes either.
+    const app = createGithubEnterpriseApp({
+      appService,
+      agentService: new AgentService(prisma),
+      agentEnvService: envService,
+      sessionSecret: "test-secret-32chars-for-ghe-api!!",
+      adminApiKeys: parseAdminApiKeys(`agent-key:agent-tok:${agent.id}`),
+      agentTokenService: { validate: async () => null },
+    });
+    const denied = await app.request("/github-enterprise/apps", {
+      headers: { Authorization: "Bearer agent-tok" },
+    });
+    expect(denied.status).toBe(403);
+  });
+});