@app-vitals/agent-admin 1.13.0 → 1.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@app-vitals/agent-admin",
-  "version": "1.13.0",
+  "version": "1.14.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.13.0",
+    "@app-vitals/agent-lib": "1.14.0",
     "@hono/zod-openapi": "^1.0.0",
     "@prisma/adapter-pg": "^7.10.0",
     "@prisma/client": "^7.10.0",

package/src/admin-boot.ts

@@ -99,6 +99,8 @@ import { CronRunNowService } from "./cron-run-now.ts";
 import { parseCronRunNowConfig } from "./cron-run-now-config.ts";
 import { CronRunTranscriptService } from "./cron-run-transcripts.ts";
 import { isDevAuthAllowed } from "./dev-auth-guard.ts";
+import { createGithubEnterpriseApp } from "./github-enterprise-api.ts";
+import { GitHubEnterpriseAppService } from "./github-enterprise-apps.ts";
 import { HttpGithubAppProvisioningClient } from "./github-app-provisioning-client.ts";
 import { HttpGoogleAuthClient } from "./google-auth-client.ts";
 import { HttpChatClient } from "./http-chat-client.ts";
@@ -113,7 +115,7 @@ import { parseSelfServeConfig } from "./self-serve-config.ts";
 import { HttpSlackProvisioningClient } from "./slack-provisioning-client.ts";
 import { SpecialtyTypes } from "./specialty-types.ts";
 import { runStartupPolicyReconcile } from "./startup-policy-reconcile.ts";
-import { makeTokenCrypto } from "./token-crypto.ts";
+import { makeStrictTokenCrypto, makeTokenCrypto } from "./token-crypto.ts";
 import { parseTranscriptConfig } from "./transcript-config.ts";
 import {
   resolveTrialExpirySweepIntervalMs,
@@ -530,6 +532,24 @@ export async function startAdmin(
     }),
   );
 
+  // 3b'. GitHub Enterprise Apps API — /github-enterprise/* — admin-only,
+  //      optional (GHE-1.3). With no rows configured it reports unconfigured
+  //      and does nothing else. Strict crypto: no plain-text key storage.
+  root.route(
+    "/",
+    createGithubEnterpriseApp({
+      appService: new GitHubEnterpriseAppService(
+        prisma,
+        makeStrictTokenCrypto(),
+      ),
+      agentService,
+      agentEnvService,
+      sessionSecret,
+      adminApiKeys,
+      agentTokenService,
+    }),
+  );
+
   // 3c. Extension API routes — after every platform API, before the admin UI
   //     (same no-shadowing rule as the admin CRUD API above).
   mountRouteContributions(root, resolvedExtensions.apiRoutes);

package/src/admin-spec.ts

@@ -24,6 +24,7 @@ import {
   parseAdminApiKeys,
 } from "./agents-api.ts";
 import { createAgentRuntimeApp } from "./api.ts";
+import { createGithubEnterpriseApp } from "./github-enterprise-api.ts";
 
 /** The admin OpenAPI document shape the spec builders and generators share. */
 export interface AdminOpenApiDocument {
@@ -172,6 +173,23 @@ export function buildPlatformAdminSpec(): AdminOpenApiDocument {
     }
   }
 
+  // GHE-1.3: the /github-enterprise routes live in their own app (mounted at
+  // the root in admin-boot.ts); fold their paths and schemas in.
+  const gheSpec = createGithubEnterpriseApp({
+    appService: {} as never,
+    agentService: {} as never,
+    agentEnvService: {} as never,
+    sessionSecret: SESSION_SECRET,
+    adminApiKeys,
+    agentTokenService: { validate: async () => null },
+  }).getOpenAPI31Document({
+    openapi: "3.1.0",
+    info: { title: "github-enterprise (internal)", version: "0.1.0" },
+  });
+  for (const [path, def] of Object.entries(gheSpec.paths ?? {})) {
+    mergedPaths[path] = def as Record<string, unknown>;
+  }
+
   return {
     ...adminSpec,
     paths: mergedPaths,
@@ -180,6 +198,7 @@ export function buildPlatformAdminSpec(): AdminOpenApiDocument {
       schemas: {
         ...(adminSpec.components?.schemas ?? {}),
         ...(runtimeSpec.components?.schemas ?? {}),
+        ...(gheSpec.components?.schemas ?? {}),
       },
     },
   };

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

@@ -606,5 +606,70 @@
     "body": {
       "message": "Service Unavailable"
     }
+  },
+  "public_app_success": {
+    "status": 200,
+    "body": {
+      "id": 777,
+      "slug": "example-agent-app",
+      "client_id": "Iv1.targetapp0001",
+      "name": "Example Agent App",
+      "permissions": {
+        "contents": "read",
+        "metadata": "read"
+      }
+    }
+  },
+  "public_app_private_404": {
+    "status": 404,
+    "body": {
+      "message": "Not Found",
+      "documentation_url": "https://docs.github.com/rest/apps/apps#get-an-app"
+    }
+  },
+  "public_app_no_client_id": {
+    "status": 200,
+    "body": {
+      "id": 777,
+      "slug": "example-agent-app"
+    }
+  },
+  "app_get_success": {
+    "status": 200,
+    "body": {
+      "id": 555,
+      "slug": "example-lookup-app",
+      "permissions": {
+        "metadata": "read"
+      }
+    }
+  },
+  "app_get_no_metadata": {
+    "status": 200,
+    "body": {
+      "id": 555,
+      "slug": "example-lookup-app",
+      "permissions": {
+        "issues": "read"
+      }
+    }
+  },
+  "app_get_401": {
+    "status": 401,
+    "body": {
+      "message": "A JSON web token could not be decoded",
+      "documentation_url": "https://docs.github.com/rest"
+    }
+  },
+  "access_token_no_installer_permission": {
+    "status": 201,
+    "body": {
+      "token": "ghs_cassetteInstallationToken0000000000",
+      "expires_at": "2026-11-09T13:00:00Z",
+      "permissions": {
+        "metadata": "read"
+      },
+      "repository_selection": "all"
+    }
   }
 }

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-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);
+  });
+});