@app-vitals/agent-admin 1.14.0 → 1.16.0

package/src/admin-ui-github-enterprise.smoke.test.ts

@@ -0,0 +1,323 @@
+/**
+ * admin/src/admin-ui-github-enterprise.smoke.test.ts
+ * Smoke tests for /admin/settings/github-enterprise (GHE-1.4) via
+ * app.request(), backed by the real GHE-1.3 API app with an in-memory app
+ * service and a stubbed fetch. No DB, no network.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { generateKeyPairSync } from "node:crypto";
+import type { MiddlewareHandler } from "hono";
+import { Hono } from "hono";
+import { type AdminUIEnv, createAdminUIApp } from "./admin-ui.ts";
+import { makeMockDeps, makeSessionCookie } from "./admin-ui.fixtures.ts";
+import { registerAdminGithubEnterpriseRoutes } from "./admin-ui-github-enterprise.ts";
+import { parseAdminApiKeys } from "./api-auth.ts";
+import { createGithubEnterpriseApp } from "./github-enterprise-api.ts";
+import type {
+  GitHubEnterpriseAppMetadata,
+  GitHubEnterpriseAppRole,
+  SaveGitHubEnterpriseAppInput,
+} from "./github-enterprise-apps.ts";
+
+const { privateKey: PEM } = generateKeyPairSync("rsa", {
+  modulusLength: 2048,
+  privateKeyEncoding: { type: "pkcs8", format: "pem" },
+  publicKeyEncoding: { type: "spki", format: "pem" },
+});
+
+function fakeAppService() {
+  const rows = new Map<string, GitHubEnterpriseAppMetadata & { pem: string }>();
+  const now = new Date("2026-11-09T12:00:00Z");
+  const strip = ({
+    pem: _p,
+    ...m
+  }: GitHubEnterpriseAppMetadata & { pem: string }) => m;
+  return {
+    async list() {
+      return [...rows.values()].map(strip);
+    },
+    async get(role: GitHubEnterpriseAppRole) {
+      const r = rows.get(role);
+      return r ? strip(r) : null;
+    },
+    async save(input: SaveGitHubEnterpriseAppInput) {
+      const row = {
+        role: input.role,
+        appId: input.appId,
+        slug: input.slug,
+        enterpriseSlug: input.enterpriseSlug ?? null,
+        keySet: true,
+        lastValidationStatus: null,
+        lastValidatedAt: null,
+        lastValidationError: null,
+        createdAt: now,
+        updatedAt: now,
+        pem: input.privateKey,
+      } as GitHubEnterpriseAppMetadata & { pem: string };
+      rows.set(input.role, row);
+      return strip(row);
+    },
+    async delete(role: GitHubEnterpriseAppRole) {
+      rows.delete(role);
+    },
+    async getPrivateKey(role: GitHubEnterpriseAppRole) {
+      return rows.get(role)?.pem ?? null;
+    },
+    async recordValidation(
+      role: GitHubEnterpriseAppRole,
+      r: { status: string; error: string | null },
+    ) {
+      const row = rows.get(role);
+      if (row) {
+        row.lastValidationStatus = r.status;
+        row.lastValidationError = r.error;
+        row.lastValidatedAt = now;
+      }
+    },
+  };
+}
+
+function setup(opts: { isAdmin?: boolean; fetchStatus?: number } = {}) {
+  const appService = fakeAppService();
+  const fetchCalls: string[] = [];
+  const fetchFn = (async (input: RequestInfo | URL) => {
+    const url = String(input);
+    fetchCalls.push(url);
+    const fail = opts.fetchStatus;
+    if (fail) return new Response("{}", { status: fail });
+    const json = (b: unknown) =>
+      new Response(JSON.stringify(b), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    if (url.includes("/access_tokens"))
+      return json({
+        token: "t",
+        expires_at: "2099-01-01T00:00:00Z",
+        permissions: { enterprise_organization_installations: "write" },
+      });
+    return json({});
+  }) as unknown as typeof fetch;
+  const api = createGithubEnterpriseApp({
+    appService,
+    agentService: { getSummary: async () => null } as never,
+    agentEnvService: { getByAgentId: async () => null } as never,
+    sessionSecret: "test-secret-32chars-for-ghe-api!!",
+    adminApiKeys: parseAdminApiKeys("root:tok-admin:*"),
+    agentTokenService: { validate: async () => null } as never,
+    fetchFn,
+  });
+  const app = new Hono<AdminUIEnv>();
+  registerAdminGithubEnterpriseRoutes(app, {
+    requireAuth: (async (c, next) => {
+      c.set("userEmail", "admin@x.com");
+      c.set("isAdmin", opts.isAdmin ?? true);
+      await next();
+    }) as MiddlewareHandler<AdminUIEnv>,
+    html: (content, o) =>
+      new Response(content, {
+        status: o?.status ?? 200,
+        headers: { "Content-Type": "text/html" },
+      }),
+    // The UI calls the GHE-1.3 API with a server-held admin bearer.
+    api: (path, init) =>
+      api.request(path, {
+        ...init,
+        headers: {
+          ...(init?.headers ?? {}),
+          Authorization: "Bearer tok-admin",
+        },
+      }),
+  });
+  return { app, appService, fetchCalls };
+}
+
+const BASE = "/admin/settings/github-enterprise";
+const form = (fields: Record<string, string>) => ({
+  method: "POST",
+  headers: { "Content-Type": "application/x-www-form-urlencoded" },
+  body: new URLSearchParams(fields).toString(),
+});
+
+describe("GET /admin/settings/github-enterprise", () => {
+  it("403s for a non-admin", async () => {
+    const { app } = setup({ isAdmin: false });
+    expect((await app.request(BASE)).status).toBe(403);
+    expect((await app.request(`${BASE}/apps/lookup`, form({}))).status).toBe(
+      403,
+    );
+  });
+
+  it("renders the empty state when nothing is configured", async () => {
+    const { app } = setup();
+    const res = await app.request(BASE);
+    expect(res.status).toBe(200);
+    const html = await res.text();
+    expect(html).toContain("optional");
+    expect(html).toContain("Installer app");
+  });
+});
+
+describe("form posts", () => {
+  it("saves an app, then shows status without the key", async () => {
+    const { app, appService } = setup();
+    const res = await app.request(
+      `${BASE}/apps/lookup`,
+      form({ appId: "42", slug: "acme-lookup", privateKey: PEM }),
+    );
+    expect(res.status).toBe(302);
+    expect(res.headers.get("location")).toContain(BASE);
+    expect((await appService.get("lookup"))?.slug).toBe("acme-lookup");
+    const html = await (await app.request(BASE)).text();
+    expect(html).toContain("acme-lookup");
+    expect(html).toContain("Key set");
+    expect(html).not.toContain("PRIVATE KEY");
+  });
+
+  it("surfaces a typed error for an invalid key and does not echo it", async () => {
+    const { app } = setup();
+    const res = await app.request(
+      `${BASE}/apps/lookup`,
+      form({
+        appId: "42",
+        slug: "acme-lookup",
+        privateKey: "not-a-pem-SECRET",
+      }),
+    );
+    expect(res.status).toBe(422);
+    const html = await res.text();
+    expect(html).toContain("privateKey is not a valid PEM private key");
+    expect(html).not.toContain("not-a-pem-SECRET");
+  });
+
+  it("surfaces validation errors for a missing installer enterprise slug", async () => {
+    const { app } = setup();
+    const res = await app.request(
+      `${BASE}/apps/installer`,
+      form({ appId: "42", slug: "acme-inst", privateKey: PEM }),
+    );
+    expect(res.status).toBe(422);
+    expect(await res.text()).toContain("enterpriseSlug is required");
+  });
+
+  it("validates the installer and shows the persisted result", async () => {
+    const { app } = setup();
+    await app.request(
+      `${BASE}/apps/installer`,
+      form({
+        appId: "42",
+        slug: "acme-inst",
+        enterpriseSlug: "acme",
+        privateKey: PEM,
+      }),
+    );
+    const res = await app.request(`${BASE}/apps/installer/validate`, form({}));
+    expect(res.status).toBe(302);
+    const html = await (await app.request(BASE)).text();
+    expect(html).toContain("valid");
+    expect(html).not.toContain("Not validated yet");
+  });
+
+  it("validate on an unconfigured role is a readable 404 message", async () => {
+    const { app } = setup();
+    const res = await app.request(`${BASE}/apps/lookup/validate`, form({}));
+    expect(res.status).toBe(404);
+    expect(await res.text()).toContain("no &#39;lookup&#39; App is configured");
+  });
+
+  it("deletes an app", async () => {
+    const { app, appService } = setup();
+    await app.request(
+      `${BASE}/apps/lookup`,
+      form({ appId: "42", slug: "acme-lookup", privateKey: PEM }),
+    );
+    const res = await app.request(`${BASE}/apps/lookup/delete`, form({}));
+    expect(res.status).toBe(302);
+    expect(await appService.get("lookup")).toBeNull();
+  });
+
+  it("rejects an unknown role", async () => {
+    const { app } = setup();
+    expect((await app.request(`${BASE}/apps/bogus`, form({}))).status).toBe(
+      404,
+    );
+  });
+
+  it("install without a configured installer surfaces the 409 message", async () => {
+    const { app } = setup();
+    const res = await app.request(
+      `${BASE}/orgs/org-a/install`,
+      form({ agentId: "agent-1" }),
+    );
+    expect(res.status).toBe(409);
+    expect(await res.text()).toContain("the installer App is not configured");
+  });
+
+  it("install with an empty agent id is a readable 400", async () => {
+    const { app } = setup();
+    const res = await app.request(`${BASE}/orgs/org-a/install`, form({}));
+    expect(res.status).toBe(400);
+    expect(await res.text()).toContain("Agent ID is required");
+  });
+
+  it("org list failure from GitHub renders a message, not a 500", async () => {
+    const { app } = setup({ fetchStatus: 401 });
+    await app.request(
+      `${BASE}/apps/installer`,
+      form({
+        appId: "42",
+        slug: "acme-inst",
+        enterpriseSlug: "acme",
+        privateKey: PEM,
+      }),
+    );
+    const res = await app.request(BASE);
+    expect(res.status).toBe(200);
+    expect(await res.text()).toContain(
+      "GitHub rejected the configured App credentials",
+    );
+  });
+});
+
+describe("nav entry in the full admin UI", () => {
+  const api = async () =>
+    new Response(
+      JSON.stringify({ configured: false, installer: null, lookup: null }),
+      {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      },
+    );
+  const NAV = 'href="/admin/settings/github-enterprise"';
+
+  it("shows Settings to admins and serves the page", async () => {
+    const app = createAdminUIApp(makeMockDeps({ githubEnterpriseApi: api }));
+    const cookie = `admin_session=${await makeSessionCookie()}`;
+    const nav = await (
+      await app.request("/admin/agents", { headers: { cookie } })
+    ).text();
+    expect(nav).toContain(NAV);
+    const page = await app.request(BASE, { headers: { cookie } });
+    expect(page.status).toBe(200);
+    expect(await page.text()).toContain("optional");
+  });
+
+  it("hides Settings and 403s the page for non-admins", async () => {
+    const app = createAdminUIApp(makeMockDeps({ githubEnterpriseApi: api }));
+    const cookie = `admin_session=${await makeSessionCookie(undefined, "u2", "other@example.com", false)}`;
+    const nav = await app.request("/admin/agents", { headers: { cookie } });
+    expect(await nav.text()).not.toContain(NAV);
+    expect((await app.request(BASE, { headers: { cookie } })).status).toBe(403);
+  });
+
+  it("leaves nav and routes untouched when the API is not wired", async () => {
+    const app = createAdminUIApp(makeMockDeps());
+    const cookie = `admin_session=${await makeSessionCookie()}`;
+    const nav = await (
+      await app.request("/admin/agents", { headers: { cookie } })
+    ).text();
+    expect(nav).not.toContain(NAV);
+    expect((await app.request(BASE, { headers: { cookie } })).status).toBe(404);
+  });
+});

package/src/admin-ui-github-enterprise.ts

@@ -0,0 +1,221 @@
+/**
+ * admin/src/admin-ui-github-enterprise.ts
+ * GET/POST /admin/settings/github-enterprise — admin-only settings page for
+ * the optional enterprise GitHub Apps (GHE-1.4). A thin UI over the GHE-1.3
+ * /github-enterprise API: every action calls that API (with the caller's
+ * session cookie, so its own admin check applies) and surfaces its typed
+ * `{ error }` bodies as readable messages. No key is ever read back.
+ */
+
+import type { Context, Hono, MiddlewareHandler } from "hono";
+import type { AdminUIEnv } from "./admin-ui.ts";
+import {
+  ADMIN_GITHUB_ENTERPRISE_PATH as BASE,
+  type GheOrgs,
+  type GheStatus,
+  renderGithubEnterpriseSettingsPage,
+} from "./admin-ui-github-enterprise-pages.ts";
+
+export interface AdminGithubEnterpriseRouteDeps {
+  requireAuth: MiddlewareHandler<AdminUIEnv>;
+  /** Calls the GHE-1.3 API app (its `.request`), e.g. `/github-enterprise/apps`. */
+  api: (path: string, init?: RequestInit) => Response | Promise<Response>;
+  html: (content: string, opts?: { status?: number }) => Response;
+}
+
+const NOTICES: Record<string, string> = {
+  saved: "Credentials saved. Validate the app to check its permissions.",
+  deleted: "App removed.",
+  validated: "Validation finished; see the status below.",
+  installed: "Agent app installed.",
+  already: "The agent app was already installed on that organization.",
+};
+
+// Deliberately not imported from the enterprise credential service: that
+// key-bearing module stays out of the UI layer (see the isolation test).
+const ROLES = ["installer", "lookup"] as const;
+const isRole = (v: string): v is (typeof ROLES)[number] =>
+  (ROLES as readonly string[]).includes(v);
+
+interface ApiResult<T> {
+  ok: boolean;
+  status: number;
+  data?: T;
+  error?: string;
+}
+
+export function registerAdminGithubEnterpriseRoutes(
+  app: Hono<AdminUIEnv>,
+  deps: AdminGithubEnterpriseRouteDeps,
+): void {
+  const requireAdmin: MiddlewareHandler<AdminUIEnv> = async (c, next) =>
+    c.var.isAdmin === true
+      ? next()
+      : new Response("Forbidden", { status: 403 });
+
+  async function call<T>(
+    c: Context<AdminUIEnv>,
+    method: string,
+    path: string,
+    body?: unknown,
+  ): Promise<ApiResult<T>> {
+    const headers: Record<string, string> = {};
+    const cookie = c.req.header("cookie");
+    if (cookie) headers.cookie = cookie;
+    if (body !== undefined) headers["content-type"] = "application/json";
+    let res: Response;
+    try {
+      res = await deps.api(path, {
+        method,
+        headers,
+        ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+      });
+    } catch {
+      return { ok: false, status: 500, error: "The request failed." };
+    }
+    if (res.ok) {
+      const data = res.status === 204 ? undefined : ((await res.json()) as T);
+      return { ok: true, status: res.status, data };
+    }
+    let error = `The request failed (HTTP ${res.status}).`;
+    try {
+      const j = (await res.json()) as { error?: unknown };
+      if (typeof j.error === "string" && j.error) error = j.error;
+    } catch {
+      // keep the generic message
+    }
+    return { ok: false, status: res.status, error };
+  }
+
+  async function renderPage(
+    c: Context<AdminUIEnv>,
+    flash: { error?: string; notice?: string; status?: number } = {},
+  ): Promise<Response> {
+    const agentId = c.req.query("agentId")?.trim() || undefined;
+    const statusRes = await call<GheStatus>(
+      c,
+      "GET",
+      "/github-enterprise/apps",
+    );
+    if (!statusRes.ok || !statusRes.data) {
+      return deps.html(
+        renderGithubEnterpriseSettingsPage({
+          userEmail: c.var.userEmail,
+          status: { configured: false, installer: null, lookup: null },
+          error: flash.error ?? statusRes.error,
+        }),
+        { status: statusRes.status >= 400 ? statusRes.status : 500 },
+      );
+    }
+    const status = statusRes.data;
+    let orgs: GheOrgs | undefined;
+    let orgsError: string | undefined;
+    if (status.installer) {
+      const qs = agentId ? `?agentId=${encodeURIComponent(agentId)}` : "";
+      const r = await call<GheOrgs>(c, "GET", `/github-enterprise/orgs${qs}`);
+      if (r.ok) orgs = r.data;
+      else orgsError = r.error;
+    }
+    const noticeKey = c.req.query("notice");
+    const notice = flash.notice ?? (noticeKey ? NOTICES[noticeKey] : undefined);
+    return deps.html(
+      renderGithubEnterpriseSettingsPage({
+        userEmail: c.var.userEmail,
+        status,
+        orgs,
+        orgsError,
+        agentId,
+        error: flash.error,
+        notice,
+      }),
+      { status: flash.status ?? 200 },
+    );
+  }
+
+  const field = (form: FormData, name: string) =>
+    (form.get(name)?.toString() ?? "").trim();
+  async function readForm(c: Context<AdminUIEnv>): Promise<FormData> {
+    try {
+      return await c.req.formData();
+    } catch {
+      return new FormData();
+    }
+  }
+  const back = (c: Context<AdminUIEnv>, notice: string, agentId?: string) =>
+    c.redirect(
+      `${BASE}?notice=${notice}${agentId ? `&agentId=${encodeURIComponent(agentId)}` : ""}`,
+      302,
+    );
+  const fail = (c: Context<AdminUIEnv>, r: ApiResult<unknown>) =>
+    renderPage(c, { error: r.error, status: r.status >= 400 ? r.status : 400 });
+
+  app.get(BASE, deps.requireAuth, requireAdmin, (c) => renderPage(c));
+
+  app.post(`${BASE}/apps/:role`, deps.requireAuth, requireAdmin, async (c) => {
+    const role = c.req.param("role");
+    if (!isRole(role)) return new Response("Not Found", { status: 404 });
+    const form = await readForm(c);
+    const enterpriseSlug = field(form, "enterpriseSlug");
+    const r = await call(c, "PUT", `/github-enterprise/apps/${role}`, {
+      appId: field(form, "appId"),
+      slug: field(form, "slug"),
+      ...(enterpriseSlug ? { enterpriseSlug } : {}),
+      // Pasted as-is; never trimmed away from or echoed back to the page.
+      privateKey: form.get("privateKey")?.toString() ?? "",
+    });
+    return r.ok ? back(c, "saved") : fail(c, r);
+  });
+
+  app.post(
+    `${BASE}/apps/:role/validate`,
+    deps.requireAuth,
+    requireAdmin,
+    async (c) => {
+      const role = c.req.param("role");
+      if (!isRole(role)) return new Response("Not Found", { status: 404 });
+      const r = await call(
+        c,
+        "POST",
+        `/github-enterprise/apps/${role}/validate`,
+      );
+      return r.ok ? back(c, "validated") : fail(c, r);
+    },
+  );
+
+  app.post(
+    `${BASE}/apps/:role/delete`,
+    deps.requireAuth,
+    requireAdmin,
+    async (c) => {
+      const role = c.req.param("role");
+      if (!isRole(role)) return new Response("Not Found", { status: 404 });
+      const r = await call(c, "DELETE", `/github-enterprise/apps/${role}`);
+      return r.ok ? back(c, "deleted") : fail(c, r);
+    },
+  );
+
+  app.post(
+    `${BASE}/orgs/:org/install`,
+    deps.requireAuth,
+    requireAdmin,
+    async (c) => {
+      const org = c.req.param("org");
+      const agentId = field(await readForm(c), "agentId");
+      if (!agentId) {
+        return renderPage(c, { error: "Agent ID is required.", status: 400 });
+      }
+      const r = await call<{ created: boolean }>(
+        c,
+        "POST",
+        `/github-enterprise/orgs/${encodeURIComponent(org)}/install`,
+        { agentId },
+      );
+      if (!r.ok) return fail(c, r);
+      return back(
+        c,
+        r.data?.created === false ? "already" : "installed",
+        agentId,
+      );
+    },
+  );
+}

package/src/admin-ui-styles.ts

@@ -3,7 +3,10 @@ import {
   renderShipwrightToolbar,
   baseStyles as toolbarBaseStyles,
 } from "@app-vitals/agent-lib/web/toolbar.ts";
-import { shouldShowAccountNav } from "./admin-ui-account-nav.ts";
+import {
+  shouldShowAccountNav,
+  shouldShowSettingsNav,
+} from "./admin-ui-account-nav.ts";
 
 export { escapeHtml };
 
@@ -652,5 +655,6 @@ export function renderAdminToolbar(userName: string, activePath = ""): string {
     logoutAction: "/admin/logout",
     metricsUrl: process.env.METRICS_DASHBOARD_URL ?? "/dashboard",
     showAccount: shouldShowAccountNav(),
+    showSettings: shouldShowSettingsNav(),
   });
 }

package/src/admin-ui.ts

@@ -45,9 +45,13 @@ import {
   renderAgentDetailCardSlots,
 } from "./admin-extension.ts";
 import { registerAccountRoutes } from "./admin-ui-account.ts";
-import { runWithAccountNav } from "./admin-ui-account-nav.ts";
+import {
+  runWithAccountNav,
+  runWithSettingsNav,
+} from "./admin-ui-account-nav.ts";
 import { renderZeroQuotaNotice } from "./admin-ui-account-pages.ts";
 import { registerAdminAccountsRoutes } from "./admin-ui-accounts.ts";
+import { registerAdminGithubEnterpriseRoutes } from "./admin-ui-github-enterprise.ts";
 import {
   type AgentDetail,
   type AgentOption,
@@ -407,6 +411,15 @@ export interface AdminUIDeps {
    * callback only, and only when selfServe.enabled; absent → no auto-create.
    */
   accountOnboarding?: Pick<AccountOnboardingService, "provisionForEmail">;
+  /**
+   * GHE-1.4: the GHE-1.3 /github-enterprise API app's `request`. Optional
+   * (additive): when absent the Settings page and its nav entry are not
+   * registered.
+   */
+  githubEnterpriseApi?: (
+    path: string,
+    init?: RequestInit,
+  ) => Response | Promise<Response>;
   /** Best-effort operator push on auto-created accounts (SSP-3.3). */
   accountCreatedNotifier?: AccountCreatedNotifier;
   /**
@@ -795,6 +808,7 @@ export function createAdminUIApp(deps: AdminUIDeps): Hono<AdminUIEnv> {
     accountOnboarding,
     accountCreatedNotifier,
     accountServices,
+    githubEnterpriseApi,
     specialtyRegistry = new SpecialtyTypes(),
     specialtyDefaults,
     callerScopeResolver = memberOnlyCallerScopeResolver(agentMemberService),
@@ -837,6 +851,16 @@ export function createAdminUIApp(deps: AdminUIDeps): Hono<AdminUIEnv> {
     devAuthEnabled,
   });
 
+  // GHE-1.4: the admin-only "Settings" toolbar entry. Registered before the
+  // Account middleware; the two merge their flags in the shared store.
+  if (githubEnterpriseApi) {
+    app.use("/admin/*", async (c, next) => {
+      const token = getCookie(c, SESSION_COOKIE);
+      const user = token ? await getSessionUser(token, sessionSecret) : null;
+      return runWithSettingsNav(user?.isAdmin === true, () => next());
+    });
+  }
+
   // SSP-3.2: show the toolbar's "Account" entry only for signed-in users who
   // belong to an account, and only while self-serve is on. The flag is carried
   // in AsyncLocalStorage so renderAdminToolbar() needs no extra parameter.
@@ -3182,6 +3206,16 @@ export function createAdminUIApp(deps: AdminUIDeps): Hono<AdminUIEnv> {
     return c.redirect(`/admin/agents/${agentId}`, 302);
   });
 
+  // ─── Enterprise GitHub apps settings (GHE-1.4) ───────────────────────────
+
+  if (githubEnterpriseApi) {
+    registerAdminGithubEnterpriseRoutes(app, {
+      requireAuth,
+      api: githubEnterpriseApi,
+      html,
+    });
+  }
+
   // ─── Account page (SSP-3.2) ───────────────────────────────────────────────
 
   if (accountServices) {