@app-vitals/agent-admin 1.3.0 → 1.5.0

package/src/agent-marketplaces.unit.test.ts

@@ -0,0 +1,72 @@
+/**
+ * admin/src/agent-marketplaces.unit.test.ts
+ * Unit tests for marketplace input validation (source, name, ref).
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+  validateMarketplaceName,
+  validateMarketplaceRef,
+  validateMarketplaceSource,
+} from "./agent-marketplaces.ts";
+import { UnprocessableEntityError } from "./errors.ts";
+
+describe("validateMarketplaceSource", () => {
+  it.each([
+    "app-vitals/shipwright",
+    "owner/repo.name",
+    "Org_1/repo-2",
+    "https://github.com/app-vitals/shipwright.git",
+    "https://gitlab.example.com/group/sub/repo",
+  ])("accepts %s", (source) => {
+    expect(() => validateMarketplaceSource(source)).not.toThrow();
+  });
+
+  it.each([
+    "",
+    "   ",
+    "repo",
+    "owner/",
+    "/repo",
+    "owner/repo/extra",
+    "owner/re po",
+    "http://github.com/o/r",
+    "git@github.com:o/r.git",
+    "ssh://git@github.com/o/r",
+    "file:///etc/passwd",
+    "../etc",
+    "./local/path",
+    "-owner/repo",
+    "https://",
+    "https://user:pass@github.com/o/r",
+    "https://github.com/o/r with space",
+    "https://-evil.com/x",
+  ])("rejects %p with a 422", (source) => {
+    expect(() => validateMarketplaceSource(source)).toThrow(
+      UnprocessableEntityError,
+    );
+  });
+});
+
+describe("validateMarketplaceName", () => {
+  it("accepts simple names", () => {
+    expect(() => validateMarketplaceName("shipwright")).not.toThrow();
+    expect(() => validateMarketplaceName("my.market_place-2")).not.toThrow();
+  });
+  it.each(["", "a b", "a@b", "a/b", "-x"])("rejects %p", (name) => {
+    expect(() => validateMarketplaceName(name)).toThrow(
+      UnprocessableEntityError,
+    );
+  });
+});
+
+describe("validateMarketplaceRef", () => {
+  it("accepts branches, tags, shas and absent refs", () => {
+    for (const ref of [undefined, null, "main", "v1.2.3", "feat/x", "abc123"]) {
+      expect(() => validateMarketplaceRef(ref)).not.toThrow();
+    }
+  });
+  it.each(["", "-x", "a b", "a..b", "x;rm"])("rejects %p", (ref) => {
+    expect(() => validateMarketplaceRef(ref)).toThrow(UnprocessableEntityError);
+  });
+});

package/src/agents-api.ts

@@ -41,8 +41,8 @@ import {
 } from "./account-agent-create.ts";
 import {
   reconcileAgentAfterAccountChange,
-  reconcileAgentAfterSpecialtyChange,
   reconcileAgentAfterPodServiceAccountChange,
+  reconcileAgentAfterSpecialtyChange,
 } from "./agent-account-assignment.ts";
 import {
   type AgentAskDeps,
@@ -60,6 +60,7 @@ import type { DeleteAgentFullyDeps } from "./agent-deletion.ts";
 import { deleteAgentFully } from "./agent-deletion.ts";
 import type { AgentEnvService } from "./agent-envs.ts";
 import type { AgentGitHubInstallationsService } from "./agent-github-installations.ts";
+import { AgentMarketplaceService } from "./agent-marketplaces.ts";
 import type { AgentMemberService } from "./agent-members.ts";
 import type { AgentPluginService } from "./agent-plugins.ts";
 import {
@@ -116,6 +117,7 @@ import {
   AgentEnvResponseSchema,
   AgentGitHubInstallationsSnapshotSchema,
   AgentIdParamSchema,
+  AgentMarketplaceSchema,
   AgentPluginSchema,
   AgentRepoParamSchema,
   AgentSummarySchema,
@@ -143,6 +145,7 @@ import {
   EnvKeyParamSchema,
   ErrorSchema,
   ListCronRunsQuerySchema,
+  MarketplaceIdParamSchema,
   type ModelBreakdownEntry,
   OkSchema,
   PatchAgentBodySchema,
@@ -154,6 +157,7 @@ import {
   PutGitHubInstallationsBodySchema,
   TokenIdParamSchema,
   ToolIdParamSchema,
+  UpsertAgentMarketplaceBodySchema,
   UpsertChatTokenDailyBodySchema,
 } from "./openapi-schemas.ts";
 import type { SelfServeConfig } from "./self-serve-config.ts";
@@ -212,6 +216,14 @@ export interface AdminDeps {
     AgentPluginService,
     "list" | "add" | "remove" | "removeByName"
   >;
+  /**
+   * PMK-1.2: remote plugin marketplaces. Optional (additive to the exported
+   * AdminDeps): defaults to an AgentMarketplaceService over `prisma`.
+   */
+  agentMarketplaceService?: Pick<
+    AgentMarketplaceService,
+    "list" | "upsert" | "remove"
+  >;
   agentMemberService: Pick<
     AgentMemberService,
     "add" | "listByAgentId" | "exists" | "listByEmail"
@@ -492,6 +504,14 @@ const PluginWrapperSchema = z
   .object({ plugin: AgentPluginSchema })
   .openapi("PluginWrapper");
 
+const MarketplaceWrapperSchema = z
+  .object({ marketplace: AgentMarketplaceSchema })
+  .openapi("MarketplaceWrapper");
+
+const MarketplacesWrapperSchema = z
+  .object({ marketplaces: z.array(AgentMarketplaceSchema) })
+  .openapi("MarketplacesWrapper");
+
 const PluginsWrapperSchema = z
   .object({ plugins: z.array(AgentPluginSchema) })
   .openapi("PluginsWrapper");
@@ -1211,6 +1231,58 @@ const deletePluginRoute = createRoute({
   },
 });
 
+const listMarketplacesRoute = createRoute({
+  method: "get",
+  path: "/agents/{id}/marketplaces",
+  summary: "List marketplaces",
+  description:
+    "Returns every remote plugin marketplace configured for the agent.",
+  request: { params: AgentIdParamSchema },
+  responses: {
+    200: {
+      description: "List of marketplaces",
+      content: { "application/json": { schema: MarketplacesWrapperSchema } },
+    },
+  },
+});
+
+const upsertMarketplaceRoute = createRoute({
+  method: "post",
+  path: "/agents/{id}/marketplaces",
+  summary: "Add or update a marketplace",
+  description:
+    "Upserts a remote plugin marketplace by `name`. `source` must be a GitHub `owner/repo` or an https git URL (no credentials); `ref` optionally pins a branch, tag or sha. 422 on an invalid `name`, `source` or `ref`.",
+  request: {
+    params: AgentIdParamSchema,
+    body: {
+      content: {
+        "application/json": { schema: UpsertAgentMarketplaceBodySchema },
+      },
+    },
+  },
+  responses: {
+    201: {
+      description: "Marketplace added or updated",
+      content: { "application/json": { schema: MarketplaceWrapperSchema } },
+    },
+    400: { description: "Bad request", ...jsonError },
+    422: { description: "Invalid name, source or ref", ...jsonError },
+  },
+});
+
+const deleteMarketplaceRoute = createRoute({
+  method: "delete",
+  path: "/agents/{id}/marketplaces/{marketplaceId}",
+  summary: "Remove a marketplace",
+  description:
+    "Removes the marketplace row by id. 404 when the id does not exist or belongs to a different agent.",
+  request: { params: MarketplaceIdParamSchema },
+  responses: {
+    204: { description: "Marketplace removed" },
+    404: { description: "Marketplace not found", ...jsonError },
+  },
+});
+
 const upsertChatTokenDailyRoute = createRoute({
   method: "post",
   path: "/agents/{id}/chat-tokens/daily",
@@ -2532,6 +2604,34 @@ export function createAdminApp(deps: AdminDeps): OpenAPIHono<AdminAuthEnv> {
     return c.body(null, 204);
   });
 
+  // ─── Marketplaces (PMK-1.2) ────────────────────────────────────────────────
+  // Auth is the shared /agents/* middleware: the agent's own key, a platform
+  // admin and authorised session members pass; other agents' keys get 403.
+  // No route here writes the runtime-reported baked-marketplace list (PMK-1.4).
+
+  const agentMarketplaceService =
+    deps.agentMarketplaceService ??
+    new AgentMarketplaceService(prisma as PrismaClient);
+
+  app.openapi(listMarketplacesRoute, async (c) => {
+    const { id: agentId } = c.req.valid("param");
+    const rows = await agentMarketplaceService.list(agentId);
+    return c.json({ marketplaces: rows.map(serializeMarketplace) }, 200);
+  });
+
+  app.openapi(upsertMarketplaceRoute, async (c) => {
+    const { id: agentId } = c.req.valid("param");
+    const body = c.req.valid("json");
+    const row = await agentMarketplaceService.upsert(agentId, body);
+    return c.json({ marketplace: serializeMarketplace(row) }, 201);
+  });
+
+  app.openapi(deleteMarketplaceRoute, async (c) => {
+    const { id: agentId, marketplaceId } = c.req.valid("param");
+    await agentMarketplaceService.remove(agentId, marketplaceId);
+    return c.body(null, 204);
+  });
+
   // ─── Cron-run token stats ──────────────────────────────────────────────────
 
   // GET /agents/all/cron-runs/stats — aggregated token stats across all agents
@@ -2844,6 +2944,22 @@ function serializeTool(tool: {
   } as z.infer<typeof AgentToolSchema>;
 }
 
+function serializeMarketplace(row: {
+  id: string;
+  agentId: string;
+  name: string;
+  source: string;
+  ref: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+}): z.infer<typeof AgentMarketplaceSchema> {
+  return {
+    ...row,
+    createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString(),
+  };
+}
+
 function serializePlugin(plugin: {
   createdAt: Date;
   updatedAt: Date;

package/src/api.ts

@@ -44,6 +44,12 @@ export interface AgentConfigResponse {
   env: Record<string, string>;
   allowedTools: string[];
   plugins: AgentPlugin[];
+  /**
+   * PMK-1.2: remote plugin marketplaces to register before plugin install.
+   * Optional so existing fixtures/doubles built against this interface keep
+   * compiling; the live handler always populates it (empty when none).
+   */
+  marketplaces?: Array<{ name: string; source: string; ref: string | null }>;
   repos: string[];
   reviewAuthorAllowlist: string[];
   patchAuthorAllowlist: string[];
@@ -155,6 +161,12 @@ interface AgentPluginServiceLike {
   listEnabled(agentId: string): Promise<Array<{ name: string }>>;
 }
 
+interface AgentMarketplaceServiceLike {
+  list(
+    agentId: string,
+  ): Promise<Array<{ name: string; source: string; ref: string | null }>>;
+}
+
 export interface AgentPhaseMethodologyServiceLike {
   list(
     agentId: string,
@@ -166,6 +178,11 @@ export interface AgentRuntimeDeps {
   agentCronJobService: AgentCronJobServiceLike;
   agentService: AgentServiceLike;
   agentPluginService: AgentPluginServiceLike;
+  /**
+   * PMK-1.2: optional. Absent → GET /agents/:id/config reports
+   * `marketplaces: []`.
+   */
+  agentMarketplaceService?: AgentMarketplaceServiceLike;
   /**
    * Optional: supplied by an AdminExtension (the coding extension). Absent →
    * GET /agents/:id/config omits `phaseMethodology`.
@@ -290,11 +307,13 @@ export function createAgentRuntimeApp(deps: AgentRuntimeDeps): OpenAPIHono {
     }
 
     // Fetch env bundle, plugins, and phase-methodology overrides in parallel
-    const [bundle, plugins, phaseMethodologyRows] = await Promise.all([
-      agentEnvService.getConfigBundle(id),
-      agentPluginService.listEnabled(id),
-      agentPhaseMethodologyService?.list(id),
-    ]);
+    const [bundle, plugins, marketplaceRows, phaseMethodologyRows] =
+      await Promise.all([
+        agentEnvService.getConfigBundle(id),
+        agentPluginService.listEnabled(id),
+        deps.agentMarketplaceService?.list(id),
+        agentPhaseMethodologyService?.list(id),
+      ]);
 
     // WIF-2.1: with federation enabled, a non-self-hosted agent must never be
     // handed Anthropic credentials, even ones already stored in its bundle
@@ -341,6 +360,11 @@ export function createAgentRuntimeApp(deps: AgentRuntimeDeps): OpenAPIHono {
           ? { marketplace: "shipwright", plugin: p.name }
           : { plugin: p.name.slice(0, at), marketplace: p.name.slice(at + 1) };
       }),
+      marketplaces: (marketplaceRows ?? []).map((m) => ({
+        name: m.name,
+        source: m.source,
+        ref: m.ref,
+      })),
       repos: agent.repos,
       reviewAuthorAllowlist: agent.reviewAuthorAllowlist,
       patchAuthorAllowlist: agent.patchAuthorAllowlist,

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

@@ -0,0 +1,152 @@
+/**
+ * Integration tests for GitHubEnterpriseAppService against a real PostgreSQL DB.
+ *
+ * Requires DATABASE_URL_ADMIN_TEST to be set; skips otherwise.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import type { PrismaClient } from "../prisma/client/client.ts";
+import {
+  GitHubEnterpriseAppService,
+  PrivateKeyDecryptError,
+  PrivateKeyEncryptionUnavailableError,
+} from "./github-enterprise-apps.ts";
+import { createAdminPrismaClient } from "./prisma-client.ts";
+import { makeStrictTokenCrypto } from "./token-crypto.ts";
+
+const TEST_DB = process.env.DATABASE_URL_ADMIN_TEST;
+const describeOrSkip = TEST_DB ? describe : describe.skip;
+
+const KEY_A = "a".repeat(64);
+const KEY_B = "b".repeat(64);
+const PEM =
+  "-----BEGIN RSA PRIVATE KEY-----\nSUPERSECRETPEMBODY0123456789\n-----END RSA PRIVATE KEY-----";
+
+const installer = {
+  role: "installer" as const,
+  appId: "111",
+  slug: "inst-app",
+  enterpriseSlug: "acme",
+  privateKey: PEM,
+};
+
+describeOrSkip("GitHubEnterpriseAppService (integration)", () => {
+  let prisma: PrismaClient;
+  let service: GitHubEnterpriseAppService;
+
+  beforeEach(async () => {
+    prisma = createAdminPrismaClient(TEST_DB as string);
+    await prisma.gitHubEnterpriseApp.deleteMany();
+    service = new GitHubEnterpriseAppService(
+      prisma,
+      makeStrictTokenCrypto(KEY_A),
+    );
+  });
+
+  afterEach(async () => {
+    await prisma.$disconnect();
+  });
+
+  it("returns null when nothing is saved (feature off)", async () => {
+    expect(await service.get("installer")).toBeNull();
+    expect(await service.list()).toEqual([]);
+  });
+
+  it("saves and reads per role; metadata plus keySet only", async () => {
+    const saved = await service.save(installer);
+    expect(saved.keySet).toBe(true);
+    await service.save({
+      role: "lookup",
+      appId: "222",
+      slug: "look-app",
+      privateKey: PEM,
+    });
+    const got = await service.get("installer");
+    expect(got).toMatchObject({
+      role: "installer",
+      appId: "111",
+      slug: "inst-app",
+      enterpriseSlug: "acme",
+      keySet: true,
+    });
+    expect(JSON.stringify(got)).not.toContain("SUPERSECRETPEMBODY");
+    expect(JSON.stringify(await service.list())).not.toContain(
+      "SUPERSECRETPEMBODY",
+    );
+    expect((await service.list()).map((a) => a.role).sort()).toEqual([
+      "installer",
+      "lookup",
+    ]);
+  });
+
+  it("save again for the same role replaces the row (at most two rows)", async () => {
+    await service.save(installer);
+    await service.save({ ...installer, appId: "999" });
+    expect(await prisma.gitHubEnterpriseApp.count()).toBe(1);
+    expect((await service.get("installer"))?.appId).toBe("999");
+  });
+
+  it("stores the key encrypted and round-trips it via getPrivateKey", async () => {
+    await service.save(installer);
+    const row = await prisma.gitHubEnterpriseApp.findUnique({
+      where: { role: "installer" },
+    });
+    expect(row?.privateKeyEncrypted).not.toContain("SUPERSECRETPEMBODY");
+    expect(row?.privateKeyEncrypted.split(":")).toHaveLength(3);
+    expect(await service.getPrivateKey("installer")).toBe(PEM);
+  });
+
+  it("deletes per role", async () => {
+    await service.save(installer);
+    await service.delete("installer");
+    expect(await service.get("installer")).toBeNull();
+    await service.delete("installer"); // no-op
+  });
+
+  it("rejects an unknown role", async () => {
+    await expect(
+      service.save({ ...installer, role: "bogus" as never }),
+    ).rejects.toThrow(/role/);
+  });
+
+  it("refuses to save when no encryption key is configured, without echoing the PEM", async () => {
+    const noKey = new GitHubEnterpriseAppService(
+      prisma,
+      makeStrictTokenCrypto(undefined),
+    );
+    const err = await noKey.save(installer).catch((e) => e);
+    expect(err).toBeInstanceOf(PrivateKeyEncryptionUnavailableError);
+    expect(err.message).toContain("SHIPWRIGHT_ENCRYPTION_KEY");
+    expect(err.message).not.toContain("SUPERSECRETPEMBODY");
+    expect(await prisma.gitHubEnterpriseApp.count()).toBe(0);
+  });
+
+  it("strict decrypt: wrong key throws, never returning ciphertext or PEM", async () => {
+    await service.save(installer);
+    const wrong = new GitHubEnterpriseAppService(
+      prisma,
+      makeStrictTokenCrypto(KEY_B),
+    );
+    const err = await wrong.getPrivateKey("installer").catch((e) => e);
+    expect(err).toBeInstanceOf(PrivateKeyDecryptError);
+    expect(err.message).not.toContain("SUPERSECRETPEMBODY");
+  });
+
+  it("strict decrypt: tampered and legacy plain-text values throw", async () => {
+    await service.save(installer);
+    const row = await prisma.gitHubEnterpriseApp.findUnique({
+      where: { role: "installer" },
+    });
+    const [iv, ct, tag] = (row?.privateKeyEncrypted ?? "").split(":");
+    const flipped = (ct[0] === "0" ? "1" : "0") + ct.slice(1);
+    for (const bad of [`${iv}:${flipped}:${tag}`, PEM]) {
+      await prisma.gitHubEnterpriseApp.update({
+        where: { role: "installer" },
+        data: { privateKeyEncrypted: bad },
+      });
+      const err = await service.getPrivateKey("installer").catch((e) => e);
+      expect(err).toBeInstanceOf(PrivateKeyDecryptError);
+      expect(err.message).not.toContain("SUPERSECRETPEMBODY");
+    }
+  });
+});

package/src/github-enterprise-apps.ts

@@ -0,0 +1,204 @@
+/**
+ * admin/src/github-enterprise-apps.ts
+ * GitHubEnterpriseAppService — storage for the two optional admin-level GitHub
+ * Apps ('installer' and 'lookup'), at most one row per role. No rows means the
+ * feature is off.
+ *
+ * The private key is encrypted on write (AES-256-GCM via TokenCrypto) and is
+ * never returned by any read path: reads return metadata plus a `keySet` flag.
+ * Only getPrivateKey() decrypts, for server-side use by the app-token minter.
+ *
+ * Deliberate differences from AgentEnvService:
+ *  - save() refuses when no encryption key is configured (no plain-text fallback);
+ *  - decrypt is strict (failure throws; ciphertext is never passed on as a PEM);
+ *  - separate table, so the key can never reach the agent config bundle;
+ *  - no key rotation.
+ * Errors never include the PEM.
+ */
+
+import type { PrismaClient } from "../prisma/client/client.ts";
+import { type Clock, SystemClock } from "./clock.ts";
+import { ApiError, UnprocessableEntityError } from "./errors.ts";
+import type { TokenCrypto } from "./token-crypto.ts";
+
+export const GITHUB_ENTERPRISE_APP_ROLES = ["installer", "lookup"] as const;
+export type GitHubEnterpriseAppRole =
+  (typeof GITHUB_ENTERPRISE_APP_ROLES)[number];
+
+export interface GitHubEnterpriseAppMetadata {
+  role: string;
+  appId: string;
+  slug: string;
+  enterpriseSlug: string | null;
+  /** True when an encrypted private key is stored. The key itself is never returned. */
+  keySet: boolean;
+  lastValidationStatus: string | null;
+  lastValidatedAt: Date | null;
+  lastValidationError: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface SaveGitHubEnterpriseAppInput {
+  role: GitHubEnterpriseAppRole;
+  appId: string;
+  slug: string;
+  /** installer only */
+  enterpriseSlug?: string | null;
+  /** PEM; encrypted before it is stored. */
+  privateKey: string;
+}
+
+interface GitHubEnterpriseAppRow {
+  role: string;
+  appId: string;
+  slug: string;
+  enterpriseSlug: string | null;
+  privateKeyEncrypted: string;
+  lastValidationStatus: string | null;
+  lastValidatedAt: Date | null;
+  lastValidationError: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export class PrivateKeyEncryptionUnavailableError extends UnprocessableEntityError {
+  constructor() {
+    super(
+      "SHIPWRIGHT_ENCRYPTION_KEY is not configured; refusing to store a GitHub App private key unencrypted. Set it to a 64-character hex string (openssl rand -hex 32) and retry.",
+    );
+    this.name = "PrivateKeyEncryptionUnavailableError";
+  }
+}
+
+export class PrivateKeyDecryptError extends ApiError {
+  constructor(role: string) {
+    super(
+      500,
+      `failed to decrypt the stored private key for GitHub Enterprise App '${role}': the value is corrupt or SHIPWRIGHT_ENCRYPTION_KEY changed; re-save the key`,
+    );
+    this.name = "PrivateKeyDecryptError";
+  }
+}
+
+/** Serializer: metadata plus a keySet flag. Never includes key material. */
+export function toGitHubEnterpriseAppMetadata(
+  row: GitHubEnterpriseAppRow,
+): GitHubEnterpriseAppMetadata {
+  return {
+    role: row.role,
+    appId: row.appId,
+    slug: row.slug,
+    enterpriseSlug: row.enterpriseSlug,
+    keySet: row.privateKeyEncrypted.length > 0,
+    lastValidationStatus: row.lastValidationStatus,
+    lastValidatedAt: row.lastValidatedAt,
+    lastValidationError: row.lastValidationError,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+function assertRole(role: string): asserts role is GitHubEnterpriseAppRole {
+  if (!(GITHUB_ENTERPRISE_APP_ROLES as readonly string[]).includes(role)) {
+    throw new UnprocessableEntityError(
+      `role must be one of: ${GITHUB_ENTERPRISE_APP_ROLES.join(", ")}`,
+    );
+  }
+}
+
+export class GitHubEnterpriseAppService {
+  constructor(
+    private prisma: PrismaClient,
+    /** Strict crypto (see makeStrictTokenCrypto); null when no encryption key is configured. */
+    private crypto: TokenCrypto | null,
+    private clock: Clock = SystemClock(),
+  ) {}
+
+  /** Create or replace the app for a role. Resets validation state. */
+  async save(
+    input: SaveGitHubEnterpriseAppInput,
+  ): Promise<GitHubEnterpriseAppMetadata> {
+    assertRole(input.role);
+    if (!this.crypto) throw new PrivateKeyEncryptionUnavailableError();
+    if (!input.privateKey) {
+      throw new UnprocessableEntityError("privateKey is required");
+    }
+    const data = {
+      appId: input.appId,
+      slug: input.slug,
+      enterpriseSlug:
+        input.role === "installer" ? (input.enterpriseSlug ?? null) : null,
+      privateKeyEncrypted: this.crypto.encrypt(input.privateKey),
+      lastValidationStatus: null,
+      lastValidatedAt: null,
+      lastValidationError: null,
+      updatedAt: this.clock.now(),
+    };
+    const row = await this.prisma.gitHubEnterpriseApp.upsert({
+      where: { role: input.role },
+      create: { role: input.role, ...data },
+      update: data,
+    });
+    return toGitHubEnterpriseAppMetadata(row);
+  }
+
+  async get(
+    role: GitHubEnterpriseAppRole,
+  ): Promise<GitHubEnterpriseAppMetadata | null> {
+    assertRole(role);
+    const row = await this.prisma.gitHubEnterpriseApp.findUnique({
+      where: { role },
+    });
+    return row ? toGitHubEnterpriseAppMetadata(row) : null;
+  }
+
+  async list(): Promise<GitHubEnterpriseAppMetadata[]> {
+    const rows = await this.prisma.gitHubEnterpriseApp.findMany({
+      orderBy: { role: "asc" },
+    });
+    return rows.map(toGitHubEnterpriseAppMetadata);
+  }
+
+  /** Delete the app for a role. No-ops if absent. */
+  async delete(role: GitHubEnterpriseAppRole): Promise<void> {
+    assertRole(role);
+    await this.prisma.gitHubEnterpriseApp.deleteMany({ where: { role } });
+  }
+
+  /**
+   * Server-side only: decrypt the stored PEM. Strict — any failure throws
+   * PrivateKeyDecryptError (never includes the PEM or ciphertext). Returns
+   * null when the role has no row.
+   */
+  async getPrivateKey(role: GitHubEnterpriseAppRole): Promise<string | null> {
+    assertRole(role);
+    if (!this.crypto) throw new PrivateKeyEncryptionUnavailableError();
+    const row = await this.prisma.gitHubEnterpriseApp.findUnique({
+      where: { role },
+    });
+    if (!row) return null;
+    try {
+      return this.crypto.decrypt(row.privateKeyEncrypted);
+    } catch {
+      throw new PrivateKeyDecryptError(role);
+    }
+  }
+
+  /** Record the outcome of a validation attempt. The error text must not contain key material. */
+  async recordValidation(
+    role: GitHubEnterpriseAppRole,
+    result: { status: string; error?: string | null },
+  ): Promise<void> {
+    assertRole(role);
+    await this.prisma.gitHubEnterpriseApp.updateMany({
+      where: { role },
+      data: {
+        lastValidationStatus: result.status,
+        lastValidatedAt: this.clock.now(),
+        lastValidationError: result.error ?? null,
+        updatedAt: this.clock.now(),
+      },
+    });
+  }
+}