@opengeni/api-router 0.30.1 → 1.0.0

package/src/routes/github.ts

@@ -1,13 +1,24 @@
 import {
+  GitHubActionPoliciesResponse,
+  GitHubActionPolicyActorState,
   GitHubAppManifestCreate,
+  OrganizationIntegrationDeniedError,
+  UpdateGitHubActionPolicyRequest,
   type AccessGrant,
   type GitHubInstallationBindingCandidate,
-  type GitHubInstallationBindingProof,
 } from "@opengeni/contracts";
+import { PersonalGitHubConnectionMetadata } from "@opengeni/contracts/personal-github";
+import { withOrganizationIntegrationAcquisition } from "@opengeni/db/organization-integration-policy";
+import {
+  ListGitHubRepositoryBranchesQuery,
+  VerifyPublicGitHubRepositoryRefRequest,
+} from "@opengeni/contracts/github-repository-contracts";
+import { parseCanonicalGitHubRepositoryUrl } from "@opengeni/contracts/github-repository";
 import {
   bindAuthorizedGitHubInstallationRepositories,
   deleteGitHubInstallationBinding,
   GitHubInstallationAuthorityCommitError,
+  listGitHubInstallationAccessForWorkspace,
 } from "@opengeni/db";
 import {
   authorizeGitHubInstallationBinding,
@@ -19,19 +30,32 @@ import {
   GitHubAppApiError,
   GitHubAppConfigurationError,
   GitHubInstallationAuthorityError,
+  GitHubPublicRepositoryVerificationError,
   githubAppMissingSettings,
   githubOAuthAuthorizeUrl,
+  inspectSignedState,
   organizationAppManifestUrl,
   personalAppManifestUrl,
   readSignedState,
   stateMaxAgeSeconds,
+  verifyPublicGitHubRepositoryRef,
   type GitHubSignedStatePayload,
   verifySignedState,
 } from "@opengeni/github";
-import type { Context, Hono } from "hono";
+import type { Context, Hono, MiddlewareHandler } from "hono";
 import { deleteCookie, setCookie } from "hono/cookie";
 import { HTTPException } from "hono/http-exception";
-import { hasPermission, requireAccessGrant } from "@opengeni/core";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+import {
+  githubAppActionPolicyActor,
+  hasPermission,
+  listGitHubActionPolicyActors,
+  personalGitHubActionPolicyActor,
+  requireAccessGrant,
+  requireAccessGrantAuthorization,
+  externalActorContinuationForAuthorization,
+  updateGitHubActionPolicyGroup,
+} from "@opengeni/core";
 import type { ApiRouteDeps } from "@opengeni/core";
 import {
   continuedGitHubBrowserGrantClaims,
@@ -42,20 +66,103 @@ import {
 } from "../github-browser-flow";
 import {
   githubBindingStatus,
+  GitHubRepositoryBranchAuthorityError,
   listWorkspaceGitHubInstallationBindings,
+  listWorkspaceGitHubRepositoryBranches,
   listWorkspaceGitHubRepositories,
 } from "../github-access";
+import {
+  assertPersonalConnectionOwnerPrincipal,
+  requireLegacyOAuthActor,
+} from "../connection-ownership";
+import { workspaceIntegrationsPathForUntrusted } from "../integrations/oauth-client";
+import { listPersonalGitHubConnections } from "../integrations/personal-github";
+import {
+  integrationCommitGrant,
+  type IntegrationCommitGrant,
+} from "../integrations/integration-commit-authority";
+import {
+  isConsistentGitHubBindingCandidates,
+  isConsistentGitHubBindingProof,
+} from "../integrations/github-installation-proof";
+import {
+  githubConnectFailureHtml,
+  githubInstallationChooserHtml,
+  githubSetupPendingHtml,
+  githubSetupSuccessHtml,
+  githubSuccessHtml,
+  type GitHubConnectFailure,
+} from "./github-browser-pages";
+import {
+  completeGitHubAppConnect,
+  isGitHubAppConnectState,
+} from "../integrations/github-app-connect";
+import { parseRequestJson } from "../http/request-body";
 
 const githubStateCookie = "opengeni_github_state";
 const githubBindingStateMaxAgeSeconds = 10 * 60;
 const legacyInstallationChooserDisabledMessage =
   "The legacy repository-admin GitHub installation chooser is disabled; use the GitHub owner-consent connect flow";
+/**
+ * GitHub routes a browser navigates to (not the JSON API). A page-load link
+ * opened after it expired, GitHub's Cancel button, or a non-owner all land on
+ * one of these, so their failures render a readable page instead of JSON.
+ */
+const GITHUB_BROWSER_ROUTES = [
+  "/v1/workspaces/:workspaceId/github/connect",
+  "/v1/workspaces/:workspaceId/github/installations/select",
+  "/v1/workspaces/:workspaceId/github/installations/:installationId/configure",
+  "/v1/github/app-manifest/callback",
+  "/v1/github/setup",
+  "/v1/github/install/callback",
+  "/v1/github/oauth/callback",
+] as const;
+
+/** An HTTP failure that already knows which browser page explains it. */
+class GitHubBrowserFailure extends HTTPException {
+  constructor(
+    status: 400 | 403,
+    message: string,
+    readonly failure: GitHubConnectFailure,
+  ) {
+    super(status, { message });
+    this.name = "GitHubBrowserFailure";
+  }
+}
+
 export function registerGitHubRoutes(app: Hono, deps: ApiRouteDeps): void {
   const { db, settings, githubStateSecret } = deps;
+  // Registered before the routes so it wraps them. The status code is kept, so
+  // automation still sees the same outcome; only the body becomes a page. Every
+  // failure is rendered, not only HTTP ones: an organization policy denial or an
+  // unexpected fault must not reach the browser as the JSON error envelope.
+  const browserFailurePage: MiddlewareHandler = async (c, next) => {
+    let failure: unknown;
+    let handledStatus: number | undefined;
+    try {
+      await next();
+      if (!c.error) return;
+      failure = c.error;
+      // The app error handler has already answered this failure.
+      handledStatus = c.res.status;
+    } catch (error) {
+      failure = error;
+    }
+    c.res = c.html(
+      githubConnectFailureHtml(
+        githubBrowserFailureKind(failure),
+        githubFailureReturnUrl(deps, c),
+        githubBrowserFailureDetail(failure),
+      ),
+      githubBrowserFailureStatus(failure, handledStatus) as ContentfulStatusCode,
+    );
+  };
+  for (const path of GITHUB_BROWSER_ROUTES) app.use(path, browserFailurePage);
 
   app.get("/v1/workspaces/:workspaceId/github/app", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "github:use");
+    const access = await requireAccessGrantAuthorization(c, deps, workspaceId, "github:use");
+    const grant = access.grant;
     const missing = githubAppMissingSettings(settings);
     const slug = settings.githubAppSlug?.trim() || null;
     const installations =
@@ -64,7 +171,9 @@ export function registerGitHubRoutes(app: Hono, deps: ApiRouteDeps): void {
         : [];
     const status = githubBindingStatus(missing.length === 0, installations);
     const setupMode = settings.productAccessMode === "managed" ? "platform" : "operator";
-    const canManage = hasPermission(grant.permissions, "github:manage");
+    const canManage =
+      !externalActorContinuationForAuthorization(access) &&
+      hasPermission(grant.permissions, "github:manage");
     const returnPath = githubSessionReturnPath(c.req.query("returnPath"), grant.workspaceId);
     const connectState =
       missing.length === 0 && slug && canManage
@@ -99,6 +208,95 @@ export function registerGitHubRoutes(app: Hono, deps: ApiRouteDeps): void {
     });
   });
 
+  app.get("/v1/workspaces/:workspaceId/github/action-policies", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "github:use");
+    const [installations, personalConnections] = await Promise.all([
+      listGitHubInstallationAccessForWorkspace(db, grant.workspaceId),
+      listPersonalGitHubConnections(deps, {
+        workspaceId: grant.workspaceId,
+        subjectId: grant.subjectId,
+      }),
+    ]);
+    const personalConnection = canonicalPersonalGitHubPolicyConnection(personalConnections);
+    const actors = [
+      ...installations.map(githubAppActionPolicyActor),
+      ...(personalConnection
+        ? [
+            personalGitHubActionPolicyActor({
+              connectionId: personalConnection.id,
+              githubLogin: PersonalGitHubConnectionMetadata.parse(personalConnection.metadata)
+                .githubLogin,
+            }),
+          ]
+        : []),
+    ];
+    return c.json(
+      GitHubActionPoliciesResponse.parse({
+        enabled: settings.githubRestMcpEnabled,
+        actors: await listGitHubActionPolicyActors(db, {
+          accountId: grant.accountId,
+          workspaceId: grant.workspaceId,
+          actors,
+        }),
+      }),
+    );
+  });
+
+  app.patch("/v1/workspaces/:workspaceId/github/action-policies", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const payload = await parseRequestJson(c, UpdateGitHubActionPolicyRequest);
+    const actor = payload.actor;
+    if (actor.kind === "workspace_app") {
+      const grant = await requireAccessGrant(c, deps, workspaceId, "github:manage");
+      const installations = await listGitHubInstallationAccessForWorkspace(db, grant.workspaceId);
+      const installation = installations.find(
+        (candidate) => candidate.installationId === actor.installationId,
+      );
+      if (!installation || installation.accountId !== grant.accountId) {
+        throw new HTTPException(404, { message: "GitHub installation not found" });
+      }
+      return c.json(
+        GitHubActionPolicyActorState.parse(
+          await updateGitHubActionPolicyGroup(db, {
+            accountId: grant.accountId,
+            workspaceId: grant.workspaceId,
+            subjectId: grant.subjectId,
+            actor: githubAppActionPolicyActor(installation),
+            group: payload.group,
+            decision: payload.decision,
+          }),
+        ),
+      );
+    }
+
+    const access = await requireAccessGrantAuthorization(c, deps, workspaceId, "connections:write");
+    assertPersonalConnectionOwnerPrincipal(access, "My GitHub action policy");
+    const connections = await listPersonalGitHubConnections(deps, {
+      workspaceId: access.grant.workspaceId,
+      subjectId: access.grant.subjectId,
+    });
+    const connection = connections.find((candidate) => candidate.id === actor.connectionId);
+    if (!connection) {
+      throw new HTTPException(404, { message: "personal GitHub connection not found" });
+    }
+    return c.json(
+      GitHubActionPolicyActorState.parse(
+        await updateGitHubActionPolicyGroup(db, {
+          accountId: access.grant.accountId,
+          workspaceId: access.grant.workspaceId,
+          subjectId: access.grant.subjectId,
+          actor: personalGitHubActionPolicyActor({
+            connectionId: connection.id,
+            githubLogin: PersonalGitHubConnectionMetadata.parse(connection.metadata).githubLogin,
+          }),
+          group: payload.group,
+          decision: payload.decision,
+        }),
+      ),
+    );
+  });
+
   // Start with user authorization, not GitHub's install/configure selector.
   // This lets an owner link an already-installed App without relying on
   // GitHub's Configure page to preserve or return OpenGeni state.
@@ -177,6 +375,65 @@ export function registerGitHubRoutes(app: Hono, deps: ApiRouteDeps): void {
     }
   });
 
+  app.post("/v1/workspaces/:workspaceId/github/public-repositories/verify", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId);
+    requirePublicGitHubRepositoryVerificationPermission(grant);
+    const request = await parseRequestJson(c, VerifyPublicGitHubRepositoryRefRequest);
+    let repository: ReturnType<typeof parseCanonicalGitHubRepositoryUrl>;
+    try {
+      repository = parseCanonicalGitHubRepositoryUrl(request.url);
+    } catch (error) {
+      throw new HTTPException(422, {
+        message: error instanceof Error ? error.message : "GitHub repository URL is invalid.",
+      });
+    }
+    try {
+      return c.json(
+        await verifyPublicGitHubRepositoryRef(
+          { repository, ref: request.ref },
+          deps.githubAnonymousFetch ?? fetch,
+        ),
+      );
+    } catch (error) {
+      if (error instanceof GitHubPublicRepositoryVerificationError) {
+        throw new HTTPException(error.code === "provider_unavailable" ? 503 : 422, {
+          message: error.message,
+        });
+      }
+      throw new HTTPException(503, {
+        message: "GitHub public repository verification is temporarily unavailable.",
+      });
+    }
+  });
+
+  app.get(
+    "/v1/workspaces/:workspaceId/github/installations/:installationId/repositories/:repositoryId/branches",
+    async (c) => {
+      const workspaceId = c.req.param("workspaceId");
+      const grant = await requireAccessGrant(c, deps, workspaceId, "github:use");
+      const installationId = parsePositiveInteger(c.req.param("installationId"));
+      const repositoryId = parsePositiveInteger(c.req.param("repositoryId"));
+      if (installationId === null || repositoryId === null) {
+        throw new HTTPException(400, { message: "invalid GitHub repository identity" });
+      }
+      const query = ListGitHubRepositoryBranchesQuery.parse(c.req.query());
+      try {
+        return c.json(
+          await listWorkspaceGitHubRepositoryBranches(deps, {
+            accountId: grant.accountId,
+            workspaceId: grant.workspaceId,
+            installationId,
+            repositoryId,
+            query,
+          }),
+        );
+      } catch (error) {
+        throw githubRepositoryBranchesRouteError(error);
+      }
+    },
+  );
+
   app.delete("/v1/workspaces/:workspaceId/github/installations/:installationId", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "github:manage");
@@ -184,14 +441,11 @@ export function registerGitHubRoutes(app: Hono, deps: ApiRouteDeps): void {
     if (installationId === null) {
       throw new HTTPException(400, { message: "invalid GitHub installation id" });
     }
-    const deleted = await deleteGitHubInstallationBinding(db, {
+    await deleteGitHubInstallationBinding(db, {
       accountId: grant.accountId,
       workspaceId: grant.workspaceId,
       installationId,
     });
-    if (!deleted) {
-      throw new HTTPException(404, { message: "GitHub installation binding not found" });
-    }
     return c.body(null, 204);
   });
 
@@ -245,8 +499,10 @@ export function registerGitHubRoutes(app: Hono, deps: ApiRouteDeps): void {
   app.post("/v1/workspaces/:workspaceId/github/app-manifest", async (c) => {
     assertOperatorGitHubAppSetup(settings);
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "github:manage");
-    const payload = GitHubAppManifestCreate.parse(await c.req.json());
+    const access = await requireAccessGrantAuthorization(c, deps, workspaceId, "github:manage");
+    requireLegacyOAuthActor(access);
+    const grant = access.grant;
+    const payload = await parseRequestJson(c, GitHubAppManifestCreate);
     const baseUrl = (settings.githubAppManifestBaseUrl ?? new URL(c.req.url).origin).replace(
       /\/+$/,
       "",
@@ -296,6 +552,14 @@ export function registerGitHubRoutes(app: Hono, deps: ApiRouteDeps): void {
   });
 
   const handleGitHubInstallCallback = async (c: Context) => {
+    if (isGitHubAppConnectState(deps, c.req.query("state")))
+      return completeGitHubAppConnect(deps, {
+        state: c.req.query("state"),
+        installationId: c.req.query("installation_id"),
+        setupAction: c.req.query("setup_action"),
+        error: c.req.query("error"),
+        requestUrl: c.req.url,
+      });
     const state =
       c.req.query("state") ??
       allCookieValues(c, githubStateCookie).find((candidate) => {
@@ -373,8 +637,18 @@ export function registerGitHubRoutes(app: Hono, deps: ApiRouteDeps): void {
   app.get("/v1/github/install/callback", handleGitHubInstallCallback);
 
   app.get("/v1/github/oauth/callback", async (c) => {
+    if (isGitHubAppConnectState(deps, c.req.query("state")))
+      return completeGitHubAppConnect(deps, {
+        state: c.req.query("state"),
+        code: c.req.query("code"),
+        error: c.req.query("error"),
+        requestUrl: c.req.url,
+      });
     const code = c.req.query("code");
     const state = c.req.query("state");
+    if (c.req.query("error") === "access_denied") {
+      throw new GitHubBrowserFailure(400, "GitHub authorization was cancelled", "cancelled");
+    }
     if (!code) {
       throw new HTTPException(400, { message: "missing GitHub OAuth code" });
     }
@@ -398,6 +672,7 @@ export function registerGitHubRoutes(app: Hono, deps: ApiRouteDeps): void {
           message: "GitHub OAuth state does not match this workspace",
         });
       }
+      await withOrganizationIntegrationAcquisition(db, grant, ["github-app"], async () => {});
       let candidates: GitHubInstallationBindingCandidate[] | null;
       try {
         candidates = deps.githubAppApi?.discoverInstallationBindingCandidates
@@ -428,14 +703,6 @@ export function registerGitHubRoutes(app: Hono, deps: ApiRouteDeps): void {
       if (candidates.length === 0) {
         return redirectToGitHubInstallation(c, deps, selectionState);
       }
-      if (candidates.length === 1) {
-        return redirectToExactGitHubAuthorization(
-          c,
-          deps,
-          selectionState,
-          candidates[0]!.installation.installationId,
-        );
-      }
       setGitHubStateCookie(c, deps, selectionState);
       return c.html(
         githubInstallationChooserHtml(
@@ -460,6 +727,7 @@ export function registerGitHubRoutes(app: Hono, deps: ApiRouteDeps): void {
         message: "GitHub OAuth state does not match this workspace",
       });
     }
+    await withOrganizationIntegrationAcquisition(db, grant, ["github-app"], async () => {});
     let proof;
     try {
       proof = deps.githubAppApi?.authorizeInstallationBinding
@@ -489,22 +757,30 @@ export function registerGitHubRoutes(app: Hono, deps: ApiRouteDeps): void {
     const expiresAt = new Date((statePayload.iat + githubBindingStateMaxAgeSeconds) * 1_000);
     let bound;
     try {
-      bound = await bindAuthorizedGitHubInstallationRepositories(db, {
-        accountId: grant.accountId,
-        workspaceId: grant.workspaceId,
-        installationId,
-        githubAccountId: proof.installation.accountId,
-        accountLogin: proof.installation.accountLogin,
-        accountType: proof.installation.accountType,
-        linkedBySubjectId: grant.subjectId,
-        githubActorId: proof.actorId,
-        githubActorLogin: proof.actorLogin,
-        authorityKind: proof.authorityKind,
-        authorityCheckedAt,
-        authorityExpiresAt: expiresAt,
-        authorityNonce: statePayload.nonce,
-        repositoryIds,
-      });
+      bound = await withOrganizationIntegrationAcquisition(
+        db,
+        grant,
+        ["github-app"],
+        async (tx) => {
+          await grant.authorizeCommit(tx);
+          return bindAuthorizedGitHubInstallationRepositories(tx, {
+            accountId: grant.accountId,
+            workspaceId: grant.workspaceId,
+            installationId,
+            githubAccountId: proof.installation.accountId,
+            accountLogin: proof.installation.accountLogin,
+            accountType: proof.installation.accountType,
+            linkedBySubjectId: grant.subjectId,
+            githubActorId: proof.actorId,
+            githubActorLogin: proof.actorLogin,
+            authorityKind: proof.authorityKind,
+            authorityCheckedAt,
+            authorityExpiresAt: expiresAt,
+            authorityNonce: statePayload.nonce,
+            repositoryIds,
+          });
+        },
+      );
     } catch (error) {
       if (error instanceof GitHubInstallationAuthorityCommitError) {
         throw new HTTPException(409, { message: error.message });
@@ -646,6 +922,25 @@ function githubInstallationSettingsUrl(installation: {
   return new URL(`https://github.com/settings/installations/${installation.installationId}`);
 }
 
+function canonicalPersonalGitHubPolicyConnection<
+  T extends { id: string; status: string; updatedAt: string },
+>(connections: T[]): T | null {
+  const statusRank: Record<string, number> = {
+    active: 0,
+    needs_reauth: 1,
+    error: 2,
+    revoked: 3,
+  };
+  return (
+    [...connections].sort((left, right) => {
+      const rank = (statusRank[left.status] ?? 4) - (statusRank[right.status] ?? 4);
+      if (rank !== 0) return rank;
+      const updated = right.updatedAt.localeCompare(left.updatedAt);
+      return updated !== 0 ? updated : right.id.localeCompare(left.id);
+    })[0] ?? null
+  );
+}
+
 function redirectToExactGitHubAuthorization(
   c: Context,
   deps: ApiRouteDeps,
@@ -702,16 +997,32 @@ async function requireGitHubManageGrant(
   deps: ApiRouteDeps,
   workspaceId: string,
   expectedState: GitHubSignedStatePayload,
-): Promise<AccessGrant> {
+): Promise<IntegrationCommitGrant> {
   try {
-    return await requireAccessGrant(c, deps, workspaceId, "github:manage");
+    const access = await requireAccessGrantAuthorization(c, deps, workspaceId, "github:manage");
+    requireLegacyOAuthActor(access);
+    return integrationCommitGrant(access, ["github:manage"], {
+      settings: deps.settings,
+      authorizationHeader: c.req.header("authorization"),
+    });
   } catch (error) {
     if (!(error instanceof HTTPException) || error.status !== 401) {
       throw error;
     }
     const grant = githubBrowserGrantFromState(deps.settings, expectedState, workspaceId);
     if (grant) {
-      return grant;
+      return {
+        ...grant,
+        authorizeCommit: async () => {
+          const current = githubBrowserGrantFromState(deps.settings, expectedState, workspaceId);
+          if (
+            !current ||
+            current.accountId !== grant.accountId ||
+            current.subjectId !== grant.subjectId
+          )
+            throw new HTTPException(403, { message: "GitHub browser handoff expired or changed" });
+        },
+      };
     }
     throw error;
   }
@@ -739,7 +1050,7 @@ function githubAuthorityHttpError(error: unknown): HTTPException {
   }
   if (error instanceof GitHubInstallationAuthorityError) {
     if (error.reason === "authority_denied") {
-      return new HTTPException(403, { message: error.message });
+      return new GitHubBrowserFailure(403, error.message, "not_owner");
     }
     if (error.reason === "installation_missing") {
       return new HTTPException(404, { message: error.message });
@@ -757,6 +1068,50 @@ function githubAuthorityHttpError(error: unknown): HTTPException {
   return new HTTPException(502, { message: "GitHub authority verification failed" });
 }
 
+function githubRepositoryBranchesRouteError(error: unknown): Error {
+  if (error instanceof HTTPException) {
+    return error;
+  }
+  if (error instanceof GitHubRepositoryBranchAuthorityError) {
+    return error.code === "not_authorized"
+      ? new HTTPException(404, {
+          message: "GitHub repository is not authorized for this workspace",
+        })
+      : new HTTPException(409, {
+          message: "GitHub repository authorization changed; refresh and try again",
+        });
+  }
+  if (error instanceof GitHubAppConfigurationError) {
+    return new HTTPException(409, { message: "GitHub App is not configured" });
+  }
+  if (error instanceof GitHubAppApiError) {
+    if (error.status === 429) {
+      return new HTTPException(503, { message: "GitHub is temporarily rate limited" });
+    }
+    if (error.status === 401 || error.status === 403 || error.status === 404) {
+      return new HTTPException(409, {
+        message: "GitHub repository access changed; refresh and try again",
+      });
+    }
+    return new HTTPException(502, { message: "GitHub branch discovery is unavailable" });
+  }
+  return new HTTPException(502, { message: "GitHub branch discovery is unavailable" });
+}
+
+export function requirePublicGitHubRepositoryVerificationPermission(
+  grant: Pick<AccessGrant, "permissions">,
+): void {
+  if (
+    hasPermission(grant.permissions, "sessions:create") ||
+    hasPermission(grant.permissions, "sessions:control")
+  ) {
+    return;
+  }
+  throw new HTTPException(403, {
+    message: "missing permission: sessions:create or sessions:control",
+  });
+}
+
 function isSecureRequest(c: Context, deps: ApiRouteDeps): boolean {
   return (
     deps.settings.publicBaseUrl?.startsWith("https://") ||
@@ -765,62 +1120,6 @@ function isSecureRequest(c: Context, deps: ApiRouteDeps): boolean {
   );
 }
 
-function githubSuccessHtml(envLines: string[]): string {
-  const envText = envLines.join("\n");
-  const escaped = escapeHtml(envText);
-  return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>GitHub App Created</title><style>body{font-family:system-ui,sans-serif;margin:0;min-height:100vh;display:grid;place-items:center;background:#0b0b0d;color:#f4f4f5}main{width:min(760px,calc(100vw - 32px));border:1px solid #27272a;border-radius:8px;padding:28px;background:#111114}h1{margin:0 0 10px;font-size:24px;line-height:1.2}p{margin:0 0 18px;color:#d4d4d8}.env-header{display:flex;align-items:center;justify-content:space-between;gap:12px;margin:22px 0 8px}.env-header h2{margin:0;font-size:13px;line-height:1.2;text-transform:uppercase;letter-spacing:.08em;color:#a1a1aa}pre{white-space:pre-wrap;word-break:break-word;max-height:380px;overflow:auto;background:#09090b;border:1px solid #27272a;border-radius:8px;padding:16px;font-size:13px;line-height:1.5}button{display:inline-flex;align-items:center;justify-content:center;min-height:36px;border-radius:6px;border:1px solid #3f3f46;padding:0 12px;background:#f4f4f5;color:#09090b;font:600 14px system-ui,sans-serif;cursor:pointer}button:disabled{cursor:not-allowed;opacity:.7}</style></head><body><main><h1>GitHub App created</h1><p>Add these values to .env, then restart API and worker.</p><div class="env-header"><h2>Environment variables</h2><button id="copy-env" type="button">Copy env</button></div><pre id="env-lines">${escaped}</pre><script>(()=>{const button=document.getElementById("copy-env");const env=document.getElementById("env-lines");async function copyText(text){if(navigator.clipboard&&window.isSecureContext){await navigator.clipboard.writeText(text);return;}const area=document.createElement("textarea");area.value=text;area.setAttribute("readonly","");area.style.position="fixed";area.style.inset="-9999px";document.body.append(area);area.select();document.execCommand("copy");area.remove();}button?.addEventListener("click",async()=>{try{await copyText(env?.textContent||"");button.textContent="Copied";setTimeout(()=>button.textContent="Copy env",1600);}catch{button.textContent="Copy failed";setTimeout(()=>button.textContent="Copy env",2200);}});})();</script></main></body></html>`;
-}
-
-function githubSetupSuccessHtml(account: string, returnUrl: string): string {
-  return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>GitHub App Connected</title><style>body{font-family:system-ui,sans-serif;margin:0;min-height:100vh;display:grid;place-items:center;background:#0b0b0d;color:#f4f4f5}main{width:min(640px,calc(100vw - 32px));border:1px solid #27272a;border-radius:8px;padding:28px;background:#111114}h1{margin:0 0 10px;font-size:24px;line-height:1.2}p{margin:0 0 18px;color:#d4d4d8}.button{display:inline-flex;align-items:center;justify-content:center;min-height:36px;border-radius:6px;border:1px solid #3f3f46;padding:0 12px;background:#f4f4f5;color:#09090b;font:600 14px system-ui,sans-serif;text-decoration:none}</style></head><body><main><h1>GitHub App connected</h1><p>${escapeHtml(account)} is now available to this OpenGeni workspace through an explicit repository allowlist.</p><a class="button" href="${escapeHtml(returnUrl)}">Back to OpenGeni</a></main></body></html>`;
-}
-
-function githubInstallationChooserHtml(
-  candidates: GitHubInstallationBindingCandidate[],
-  state: string,
-  workspaceId: string,
-  baseUrl: string,
-): string {
-  const action = `${baseUrl}/v1/workspaces/${encodeURIComponent(workspaceId)}/github/installations/select`;
-  const options = candidates
-    .map(({ installation, authorityKind }) => {
-      const account = escapeHtml(
-        installation.accountLogin ?? `installation ${installation.installationId}`,
-      );
-      const label = authorityKind === "personal_owner" ? "Personal account" : "Organization owner";
-      return `<label class="option"><input type="radio" name="installation_id" value="${installation.installationId}" required><span><strong>${account}</strong><small>${label}</small></span></label>`;
-    })
-    .join("");
-  return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Choose GitHub installation</title><style>body{font-family:system-ui,sans-serif;margin:0;min-height:100vh;display:grid;place-items:center;background:#0b0b0d;color:#f4f4f5}main{width:min(640px,calc(100vw - 32px));border:1px solid #27272a;border-radius:12px;padding:28px;background:#111114}h1{margin:0 0 10px;font-size:24px}p{margin:0 0 18px;color:#d4d4d8}.options{display:grid;gap:8px;margin-bottom:18px}.option{display:flex;align-items:center;gap:12px;border:1px solid #3f3f46;border-radius:8px;padding:12px;cursor:pointer}.option span{display:grid;gap:2px}.option small{color:#a1a1aa}button{min-height:38px;border-radius:7px;border:1px solid #3f3f46;padding:0 14px;background:#f4f4f5;color:#09090b;font:600 14px system-ui,sans-serif;cursor:pointer}.secondary{margin-left:8px;background:transparent;color:#f4f4f5}</style></head><body><main><h1>Choose a GitHub account</h1><p>Only installations where GitHub proved you are the personal owner or an active organization owner are shown.</p><form method="get" action="${escapeHtml(action)}"><input type="hidden" name="state" value="${escapeHtml(state)}"><div class="options">${options}</div><button type="submit">Connect selected</button><button class="secondary" type="submit" name="installation_id" value="new" formnovalidate>Install on another account</button></form></main></body></html>`;
-}
-
-function githubSetupPendingHtml(): string {
-  return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>GitHub App Requested</title><style>body{font-family:system-ui,sans-serif;margin:0;min-height:100vh;display:grid;place-items:center;background:#0b0b0d;color:#f4f4f5}main{width:min(640px,calc(100vw - 32px));border:1px solid #27272a;border-radius:8px;padding:28px;background:#111114}h1{margin:0 0 10px;font-size:24px;line-height:1.2}p{margin:0;color:#d4d4d8}</style></head><body><main><h1>GitHub App request sent</h1><p>A GitHub organization owner must approve the installation. OpenGeni has not created a workspace binding.</p></main></body></html>`;
-}
-
-function isConsistentGitHubBindingCandidates(
-  candidates: GitHubInstallationBindingCandidate[],
-): boolean {
-  const ids = new Set<number>();
-  return candidates.every(({ installation, authorityKind }) => {
-    if (
-      !Number.isSafeInteger(installation.installationId) ||
-      installation.installationId <= 0 ||
-      !Number.isSafeInteger(installation.accountId) ||
-      installation.accountId <= 0 ||
-      !installation.accountLogin?.trim() ||
-      installation.suspended ||
-      ids.has(installation.installationId)
-    ) {
-      return false;
-    }
-    ids.add(installation.installationId);
-    return authorityKind === "personal_owner"
-      ? installation.accountType === "User"
-      : installation.accountType === "Organization";
-  });
-}
-
 function parsePositiveInteger(value: string | undefined | null): number | null {
   if (!value || !/^\d+$/.test(value)) {
     return null;
@@ -834,55 +1133,6 @@ function isFreshGitHubBindingState(payload: GitHubSignedStatePayload): boolean {
   return age >= 0 && age < githubBindingStateMaxAgeSeconds;
 }
 
-function isConsistentGitHubBindingProof(
-  proof: GitHubInstallationBindingProof,
-  installationId: number,
-): boolean {
-  const installation = proof.installation;
-  if (
-    installation.installationId !== installationId ||
-    !Number.isSafeInteger(installation.accountId) ||
-    installation.accountId <= 0 ||
-    !installation.accountLogin?.trim() ||
-    installation.suspended ||
-    !Number.isSafeInteger(proof.actorId) ||
-    proof.actorId <= 0 ||
-    !proof.actorLogin.trim() ||
-    proof.repositories.length === 0
-  ) {
-    return false;
-  }
-  if (
-    proof.authorityKind === "personal_owner"
-      ? installation.accountType !== "User" || proof.actorId !== installation.accountId
-      : installation.accountType !== "Organization"
-  ) {
-    return false;
-  }
-  return proof.repositories.every(
-    (repository) =>
-      Number.isSafeInteger(repository.id) &&
-      repository.id > 0 &&
-      repository.installationId === installationId &&
-      repository.accountLogin === installation.accountLogin &&
-      repository.accountType === installation.accountType,
-  );
-}
-
-function escapeHtml(value: string): string {
-  return value.replace(
-    /[&<>"']/g,
-    (char) =>
-      ({
-        "&": "&amp;",
-        "<": "&lt;",
-        ">": "&gt;",
-        '"': "&quot;",
-        "'": "&#39;",
-      })[char] ?? char,
-  );
-}
-
 function openGeniReturnUrl(
   settings: ApiRouteDeps["settings"],
   c: Context,
@@ -904,3 +1154,55 @@ function openGeniReturnUrl(
 function openGeniBaseUrl(settings: ApiRouteDeps["settings"], c: Context): string {
   return githubBrowserBaseUrl(settings, new URL(c.req.url).origin);
 }
+
+/** The status the app error handler gives this failure; the page keeps it. */
+function githubBrowserFailureStatus(error: unknown, handledStatus: number | undefined): number {
+  if (error instanceof HTTPException) return error.status;
+  if (error instanceof OrganizationIntegrationDeniedError) return 403;
+  // An unexpected fault keeps whatever the error handler answered (500 by default).
+  return handledStatus ?? 500;
+}
+
+function githubBrowserFailureKind(error: unknown): GitHubConnectFailure {
+  if (error instanceof OrganizationIntegrationDeniedError) return "policy_denied";
+  if (!(error instanceof HTTPException)) return "failed";
+  if (error instanceof GitHubBrowserFailure) return error.failure;
+  if (error.status === 401) return "signed_out";
+  if (error.status === 403) return "forbidden";
+  // Every signed-state rejection names its state; they all mean "start again".
+  if (error.status === 400 && /\bstate\b/iu.test(error.message)) return "expired";
+  return "failed";
+}
+
+/**
+ * Human-authored HTTP messages only; configuration errors carry a JSON
+ * envelope. Anything else (an unexpected fault) shows no detail.
+ */
+function githubBrowserFailureDetail(error: unknown): string | null {
+  if (!(error instanceof HTTPException)) return null;
+  if (error instanceof GitHubBrowserFailure && error.failure === "cancelled") return null;
+  try {
+    const parsed = JSON.parse(error.message) as { message?: unknown };
+    return typeof parsed?.message === "string" ? parsed.message : null;
+  } catch {
+    return error.message || null;
+  }
+}
+
+/**
+ * The failure page links back to the workspace integrations page when the
+ * request names a workspace (its path, or a correctly signed state even if it
+ * aged out); otherwise to the OpenGeni home. This is only a link target, so an
+ * expired state is acceptable evidence of where the user came from.
+ */
+function githubFailureReturnUrl(deps: ApiRouteDeps, c: Context): string {
+  const baseUrl = (
+    deps.settings.webBaseUrl ??
+    (openGeniBaseUrl(deps.settings, c) || new URL(c.req.url).origin)
+  ).replace(/\/+$/u, "");
+  const rawState = c.req.query("state");
+  const candidate =
+    c.req.param("workspaceId") ??
+    (rawState ? inspectSignedState(rawState, deps.githubStateSecret)?.workspaceId : undefined);
+  return `${baseUrl}${workspaceIntegrationsPathForUntrusted(candidate) ?? "/"}`;
+}