@opengeni/api-router 0.30.3 → 1.0.0

package/src/routes/files.ts

@@ -1,8 +1,12 @@
+import { readSessionAttachmentFiles } from "@opengeni/core";
+import { ZodError } from "zod";
 import {
   CompleteFileUploadResponse,
   CreateFileUploadRequest,
   CreateFileUploadResponse,
   FileAsset,
+  FileListRequest,
+  FileListResponse,
   FileDownloadUrlResponse,
   RETAINED_OUTPUT_DEFAULT_PAGE_BYTES,
   RETAINED_OUTPUT_MAX_PAGE_BYTES,
@@ -11,20 +15,24 @@ import {
   retainedGeneratedImageReferenceFromFile,
   retainedGeneratedVideoReferenceFromFile,
   retainedScreenshotReferenceFromFile,
+  retainedSessionScreenshotKindFromObjectKey,
   VideoArtifactPlaybackSource,
   resolveRetainedOutputRange,
   type RetainedArtifactMetadata,
   type RetainedOutputUnavailableReason,
 } from "@opengeni/contracts";
 import {
+  withSessionRlsActorContext,
   claimFileUploadCleanup,
   completeFileUploadCleanup,
   completeFileUpload,
   createFileUpload,
   getFileUpload,
   getGeneratedImageArtifact,
+  recordAuditEvent,
   getGeneratedVideoArtifact,
   getFilesForSubject,
+  listFilesForSubject,
   getRetainedFileArtifact,
   getRetainedScreenshotArtifact,
   requireFileForSubject,
@@ -36,27 +44,110 @@ import {
 import type { Context, Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
 import {
+  fileOwnerContextForAccess,
+  requireAccessGrantAuthorization,
+  grantHasAgentAttemptAuthority,
   requireAccessGrant,
   requireLiveAgentAttemptAuthorization,
+  requireSessionAuthorization,
   SessionAuthorizationDeniedError,
+  SessionAuthorizationUnavailableError,
 } from "@opengeni/core";
 import { recordWorkspaceUsage, requireLimit } from "@opengeni/core";
 import type { ApiRouteDeps } from "@opengeni/core";
+import { retryWhileMissing } from "@opengeni/storage";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import { buildFilesMcpServer } from "../mcp/files";
+import { userContentResponseHeaders, userContentSignedGetUrlOptions } from "../http/user-content";
+import { mcpOAuthAuthenticateHeader, resolveMcpOAuthRouteAccess } from "../mcp-oauth";
+import { withAccessGrantSessionRlsContext } from "../access-grant-rls";
+import {
+  buildWorkspaceToolGatewayMcpServer,
+  prepareMcpOAuthWorkspaceToolGateway,
+} from "../workspace-tool-gateway";
+import { parseRequestJson } from "../http/request-body";
 
 export function registerFileRoutes(app: Hono, deps: ApiRouteDeps): void {
   const { db, objectStorage } = deps;
 
+  const fileRequestAuthority = new WeakMap<Request, { owner: string | null; agent: boolean }>();
+  // This scope covers metadata, original bytes, range reads and finalization.
+  // A service/agent subject string alone cannot unlock a personal attachment.
+  for (const path of [
+    "/v1/workspaces/:workspaceId/files",
+    "/v1/workspaces/:workspaceId/files/*",
+    "/v1/workspaces/:workspaceId/artifacts/*",
+    "/v1/workspaces/:workspaceId/sessions/:sessionId/artifacts/*",
+  ]) {
+    app.use(path, async (c, next) => {
+      const permission = c.req.path.includes("/files/uploads") ? "files:upload" : "files:read";
+      const access = await requireAccessGrantAuthorization(
+        c,
+        deps,
+        c.req.param("workspaceId") ?? "",
+        permission,
+      );
+      const actor = await fileOwnerContextForAccess(deps, access, permission);
+      fileRequestAuthority.set(c.req.raw, {
+        owner: actor.privateFileOwnerSubjectId ?? null,
+        agent: access.grant.principalKind === "agent_attempt",
+      });
+      return withSessionRlsActorContext(actor, next);
+    });
+  }
+
   app.all("/v1/workspaces/:workspaceId/mcp/files", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    const grant = await requireAccessGrant(c, deps, workspaceId, "files:read");
-    const transport = new WebStandardStreamableHTTPServerTransport({
-      enableJsonResponse: true,
+    let oauthAccess: Awaited<ReturnType<typeof resolveMcpOAuthRouteAccess>>;
+    try {
+      oauthAccess = await resolveMcpOAuthRouteAccess(deps, c.req.raw, workspaceId);
+    } catch (error) {
+      if (error instanceof HTTPException && error.status === 401) {
+        c.header("www-authenticate", mcpOAuthAuthenticateHeader(deps, new URL(c.req.url).pathname));
+      }
+      throw error;
+    }
+    if (oauthAccess) {
+      return await withAccessGrantSessionRlsContext(deps, oauthAccess.grant, async () => {
+        const prepared = await prepareMcpOAuthWorkspaceToolGateway(
+          deps,
+          oauthAccess.grant,
+          oauthAccess.allowedToolIdentities,
+        );
+        const transport = new WebStandardStreamableHTTPServerTransport({
+          enableJsonResponse: true,
+        });
+        const server = buildWorkspaceToolGatewayMcpServer(
+          prepared,
+          oauthAccess.grant,
+          deps.observability,
+        );
+        try {
+          await server.connect(transport);
+          return await transport.handleRequest(c.req.raw);
+        } finally {
+          await Promise.allSettled([server.close(), prepared.close()]);
+        }
+      });
+    }
+    let access: Awaited<ReturnType<typeof requireAccessGrantAuthorization>>;
+    try {
+      access = await requireAccessGrantAuthorization(c, deps, workspaceId, "files:read");
+    } catch (error) {
+      if (deps.settings.mcpOauthEnabled && error instanceof HTTPException && error.status === 401) {
+        c.header("www-authenticate", mcpOAuthAuthenticateHeader(deps, new URL(c.req.url).pathname));
+      }
+      throw error;
+    }
+    const { grant } = access;
+    return await withAccessGrantSessionRlsContext(deps, grant, async () => {
+      const transport = new WebStandardStreamableHTTPServerTransport({
+        enableJsonResponse: true,
+      });
+      const server = buildFilesMcpServer(deps, access);
+      await server.connect(transport);
+      return await transport.handleRequest(c.req.raw);
     });
-    const server = buildFilesMcpServer(deps, grant);
-    await server.connect(transport);
-    return await transport.handleRequest(c.req.raw);
   });
 
   app.post("/v1/workspaces/:workspaceId/files/uploads", async (c) => {
@@ -67,7 +158,13 @@ export function registerFileRoutes(app: Hono, deps: ApiRouteDeps): void {
         message: "object storage is not configured",
       });
     }
-    const payload = CreateFileUploadRequest.parse(await c.req.json());
+    const payload = await parseRequestJson(c, CreateFileUploadRequest);
+    const privateOwner = fileRequestAuthority.get(c.req.raw)?.owner ?? null;
+    const personal =
+      payload.scope === "personal" ||
+      (fileRequestAuthority.get(c.req.raw)?.agent && privateOwner !== null);
+    if (personal && !privateOwner)
+      throw new HTTPException(403, { message: "Personal uploads require the authenticated owner" });
     await requireLimit(deps, {
       accountId: grant.accountId,
       workspaceId,
@@ -91,6 +188,7 @@ export function registerFileRoutes(app: Hono, deps: ApiRouteDeps): void {
       accountId: grant.accountId,
       workspaceId,
       fileId,
+      privateOwnerSubjectId: personal ? privateOwner : null,
       filename: payload.filename,
       safeFilename,
       contentType: payload.contentType,
@@ -100,6 +198,23 @@ export function registerFileRoutes(app: Hono, deps: ApiRouteDeps): void {
       objectKey,
       expiresAt: signed.expiresAt,
     });
+    // Every principal-facing signed URL issuance is a
+    // metadata-only audit fact. Awaited before the URL leaves the platform:
+    // no recorded fact, no bearer capability. Never the URL or object key.
+    await recordAuditEvent(db, {
+      accountId: grant.accountId,
+      workspaceId,
+      subjectId: grant.subjectId,
+      action: "file.signed_upload.issued",
+      targetType: "workspace_file",
+      targetId: fileId,
+      metadata: {
+        fileId,
+        contentType: payload.contentType,
+        sizeBytes: payload.sizeBytes,
+        expiresAt: signed.expiresAt.toISOString(),
+      },
+    });
     return c.json(
       CreateFileUploadResponse.parse({
         fileId: upload.file.id,
@@ -231,11 +346,13 @@ export function registerFileRoutes(app: Hono, deps: ApiRouteDeps): void {
       const file = await rejectAndCleanObject(409, "file upload has expired", "expired");
       return c.json(CompleteFileUploadResponse.parse({ file }));
     }
-    const head = await objectStorage.headFile(upload.file).catch((error) => {
-      throw new HTTPException(409, {
-        message: `uploaded object is not available: ${error instanceof Error ? error.message : String(error)}`,
-      });
+    const head = await retryWhileMissing(async () => {
+      if (!(await objectStorage.fileExists(upload.file))) return null;
+      return await objectStorage.headFile(upload.file);
     });
+    if (!head) {
+      throw new HTTPException(409, { message: "uploaded object is not available" });
+    }
     if (Number(head.ContentLength ?? -1) !== upload.file.sizeBytes) {
       const file = await rejectAndCleanObject(
         422,
@@ -268,15 +385,53 @@ export function registerFileRoutes(app: Hono, deps: ApiRouteDeps): void {
     return c.json(CompleteFileUploadResponse.parse({ file }));
   });
 
-  app.get("/v1/workspaces/:workspaceId/files/:fileId", async (c) => {
+  app.get("/v1/workspaces/:workspaceId/files", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "files:read");
-    const file = await requireFileForSubject(db, {
+    const parsed = FileListRequest.safeParse({
+      ...c.req.query(),
+      ...(c.req.query("limit") !== undefined ? { limit: Number(c.req.query("limit")) } : {}),
+    });
+    if (!parsed.success) throw new HTTPException(422, { message: "Invalid file list request" });
+    c.header("cache-control", "private, no-store");
+    return c.json(
+      FileListResponse.parse(
+        await listFilesForSubject(db, {
+          accountId: grant.accountId,
+          workspaceId,
+          subjectId: grant.subjectId,
+          ...parsed.data,
+        }).catch((error: unknown) => {
+          if (error instanceof ZodError)
+            throw new HTTPException(422, { message: "Invalid file cursor" });
+          throw error;
+        }),
+      ),
+    );
+  });
+
+  const readRequestedFile = async (
+    c: Context,
+    grant: Awaited<ReturnType<typeof requireAccessGrant>>,
+  ) => {
+    const fileId = c.req.param("fileId") ?? "";
+    const sessionId = c.req.query("sessionId");
+    if (sessionId) {
+      if (!/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/iu.test(sessionId)) return null;
+      return (await readSessionAttachmentFiles(deps, grant, sessionId, [fileId]))[0] ?? null;
+    }
+    return requireFileForSubject(db, {
       accountId: grant.accountId,
-      workspaceId,
+      workspaceId: grant.workspaceId,
       subjectId: grant.subjectId,
-      fileId: c.req.param("fileId"),
+      fileId,
     }).catch(() => null);
+  };
+
+  app.get("/v1/workspaces/:workspaceId/files/:fileId", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "files:read");
+    const file = await readRequestedFile(c, grant).catch(() => null);
     if (!file) {
       throw new HTTPException(404, { message: "file not found" });
     }
@@ -324,7 +479,7 @@ export function registerFileRoutes(app: Hono, deps: ApiRouteDeps): void {
 
   app.post("/v1/workspaces/:workspaceId/artifacts/:artifactId/playback-source", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "files:read");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "files:read");
     if (!objectStorage) {
       throw new HTTPException(503, { message: "object storage is not configured" });
     }
@@ -337,10 +492,29 @@ export function registerFileRoutes(app: Hono, deps: ApiRouteDeps): void {
       throw new HTTPException(409, { message: `generated video is ${retained.file.status}` });
     }
     const file = generatedVideoFileAsset(retained.file);
-    if (!(await objectStorage.fileExists(file))) {
+    const videoPresent = await retryWhileMissing(async () =>
+      (await objectStorage.fileExists(file)) ? true : null,
+    );
+    if (!videoPresent) {
       throw new HTTPException(410, { message: "generated video bytes are unavailable" });
     }
-    const signed = await objectStorage.createGetUrl({ key: file.objectKey });
+    const signed = await objectStorage.createGetUrl({
+      key: file.objectKey,
+      ...userContentSignedGetUrlOptions(file.contentType, file.filename),
+    });
+    await recordAuditEvent(db, {
+      accountId: grant.accountId,
+      workspaceId,
+      subjectId: grant.subjectId,
+      action: "file.signed_url.issued",
+      targetType: "retained_artifact",
+      targetId: artifactId,
+      metadata: {
+        artifactId,
+        kind: "video_playback",
+        expiresAt: signed.expiresAt.toISOString(),
+      },
+    });
     return c.json(
       VideoArtifactPlaybackSource.parse({
         schemaVersion: 1,
@@ -355,9 +529,40 @@ export function registerFileRoutes(app: Hono, deps: ApiRouteDeps): void {
     );
   });
 
+  // These two retained-screenshot routes are registered before the session
+  // route module, so its `/sessions/:sessionId/*` authorization middleware
+  // does not cover them: an agent attempt must pass the same core seam here
+  // (private sessions, Slack ownership, and the 0426 agent-access scope) so a
+  // known artifact id cannot read into a tree the attempt may not reach.
+  const requireAgentSessionAccess = async (
+    c: Context,
+    grant: Awaited<ReturnType<typeof requireAccessGrant>>,
+  ): Promise<void> => {
+    if (!grantHasAgentAttemptAuthority(grant)) return;
+    try {
+      await requireSessionAuthorization(deps, grant, {
+        sessionId: c.req.param("sessionId") ?? "",
+        operation: "session.read",
+        surface: "http",
+      });
+    } catch (error) {
+      if (error instanceof SessionAuthorizationDeniedError) {
+        throw new HTTPException(404, { message: "session not found", cause: error });
+      }
+      if (error instanceof SessionAuthorizationUnavailableError) {
+        throw new HTTPException(503, {
+          message: "session authorization is unavailable",
+          cause: error,
+        });
+      }
+      throw error;
+    }
+  };
+
   app.get("/v1/workspaces/:workspaceId/sessions/:sessionId/artifacts/:artifactId", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "files:read");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "files:read");
+    await requireAgentSessionAccess(c, grant);
     const artifactId = retainedArtifactId(c.req.param("artifactId"));
     const artifact = await getRetainedScreenshotArtifact(
       db,
@@ -375,7 +580,8 @@ export function registerFileRoutes(app: Hono, deps: ApiRouteDeps): void {
     "/v1/workspaces/:workspaceId/sessions/:sessionId/artifacts/:artifactId/content",
     async (c) => {
       const workspaceId = c.req.param("workspaceId");
-      await requireAccessGrant(c, deps, workspaceId, "files:read");
+      const grant = await requireAccessGrant(c, deps, workspaceId, "files:read");
+      await requireAgentSessionAccess(c, grant);
       const artifactId = retainedArtifactId(c.req.param("artifactId"));
       const artifact = await getRetainedScreenshotArtifact(
         db,
@@ -404,19 +610,36 @@ export function registerFileRoutes(app: Hono, deps: ApiRouteDeps): void {
         message: "object storage is not configured",
       });
     }
-    const file = await requireFileForSubject(db, {
-      accountId: grant.accountId,
-      workspaceId,
-      subjectId: grant.subjectId,
-      fileId: c.req.param("fileId"),
-    }).catch(() => null);
+    const file = await readRequestedFile(c, grant).catch(() => null);
     if (!file) {
       throw new HTTPException(404, { message: "file not found" });
     }
     if (file.status !== "ready") {
       throw new HTTPException(409, { message: `file is ${file.status}` });
     }
-    const signed = await objectStorage.createGetUrl({ key: file.objectKey });
+    const present = await retryWhileMissing(async () =>
+      (await objectStorage.fileExists(file)) ? true : null,
+    );
+    if (!present) {
+      throw new HTTPException(410, { message: "file bytes are unavailable" });
+    }
+    const signed = await objectStorage.createGetUrl({
+      key: file.objectKey,
+      ...userContentSignedGetUrlOptions(file.contentType, file.filename),
+    });
+    await recordAuditEvent(db, {
+      accountId: grant.accountId,
+      workspaceId,
+      subjectId: grant.subjectId,
+      action: "file.signed_url.issued",
+      targetType: "workspace_file",
+      targetId: file.id,
+      metadata: {
+        fileId: file.id,
+        kind: "download",
+        expiresAt: signed.expiresAt.toISOString(),
+      },
+    });
     return c.json(
       FileDownloadUrlResponse.parse({
         url: signed.url,
@@ -471,25 +694,33 @@ async function serveRetainedArtifactContent(
     );
   }
 
+  // Stored bytes and their content type are user- or agent-chosen; this origin
+  // also serves the console, so the response is a sandboxed, non-embeddable
+  // document and active markup downloads instead of rendering.
   const headers = {
     "Accept-Ranges": range.acceptRanges,
     "Cache-Control": "private, no-store",
     "Content-Length": String(range.length),
     "Content-Type": metadata.contentType,
-    "X-Content-Type-Options": "nosniff",
+    ...userContentResponseHeaders(metadata.contentType, file.filename),
     ...(range.contentRange ? { "Content-Range": range.contentRange } : {}),
   };
   if (range.kind === "empty") {
-    if (!(await objectStorage.fileExists(file))) {
+    const present = await retryWhileMissing(async () =>
+      (await objectStorage.fileExists(file)) ? true : null,
+    );
+    if (!present) {
       return c.json(retainedArtifactUnavailable(artifactId, "missing_storage"), 410);
     }
     return c.body(null, 200, headers);
   }
 
-  const bytes = await objectStorage.getFileRange(file, {
-    start: range.start,
-    end: range.end,
-  });
+  const bytes = await retryWhileMissing(async () =>
+    objectStorage.getFileRange(file, {
+      start: range.start,
+      end: range.end,
+    }),
+  );
   if (!bytes) {
     return c.json(retainedArtifactUnavailable(artifactId, "missing_storage"), 410);
   }
@@ -669,12 +900,15 @@ function retainedScreenshotMetadata(
     artifact.sessionId &&
     artifact.retentionExpiresAt.getTime() > Date.now()
   ) {
+    const kind = retainedSessionScreenshotKindFromObjectKey(artifact.file.objectKey);
+    if (!kind) return retainedArtifactUnavailable(artifact.artifactId, "invalid_content");
     const reference = retainedScreenshotReferenceFromFile({
       ...artifact.file,
       sessionId: artifact.sessionId,
       width: artifact.width,
       height: artifact.height,
       expiresAt: artifact.retentionExpiresAt.toISOString(),
+      kind,
     });
     if (reference) return reference;
   }

package/src/routes/github-browser-pages.ts

@@ -0,0 +1,162 @@
+import type { GitHubInstallationBindingCandidate } from "@opengeni/contracts";
+
+// GitHub redirects can land on an API-only host. Keep these pages self-contained
+// while using the same dark palette and typography as @opengeni/react.
+const pageStyle = `
+  :root{color-scheme:dark;--bg:oklch(.155 .012 260);--surface:oklch(.19 .014 260);--raised:oklch(.225 .015 260);--border:oklch(.3 .014 260);--border-strong:oklch(.42 .016 260);--fg:oklch(.955 .005 260);--muted:oklch(.73 .012 260);--blue:oklch(.54 .18 255);--blue-light:oklch(.72 .15 255)}
+  *{box-sizing:border-box}
+  html{min-height:100%;background:var(--bg)}
+  body{margin:0;min-height:100vh;min-height:100dvh;color:var(--fg);background:var(--bg);font-family:"Inter Variable",Inter,ui-sans-serif,system-ui,sans-serif;font-feature-settings:"cv11","ss01","ss03";-webkit-font-smoothing:antialiased}
+  .shell{width:min(100% - 48px,700px);margin:0 auto}
+  header{height:84px;display:flex;align-items:center;justify-content:space-between;gap:16px;border-bottom:1px solid var(--border)}
+  .brand{font-size:16px;font-weight:670;letter-spacing:-.045em;color:var(--fg);text-decoration:none}
+  .context{font-size:12px;color:var(--muted)}
+  main{padding:clamp(48px,10vh,100px) 0 96px}
+  h1{margin:0 0 14px;font-size:clamp(27px,4vw,36px);font-weight:640;letter-spacing:-.05em;line-height:1.17}
+  p{margin:0;color:var(--muted);font-size:14px;line-height:1.65;max-width:59ch}
+  .intro{margin-bottom:32px}
+  .options{display:grid;gap:10px;margin:0 0 24px;padding:0;border:0;max-height:min(390px,52vh);overflow:auto}
+  .option{display:flex;gap:14px;align-items:center;min-height:70px;padding:14px 16px;border:1px solid var(--border);border-radius:10px;background:var(--surface);cursor:pointer;transition:background .15s,border-color .15s}
+  .option:hover{background:var(--raised)}
+  .option:has(input:checked){border-color:var(--blue-light);background:var(--raised)}
+  .option:has(input:focus-visible){outline:2px solid var(--blue-light);outline-offset:3px}
+  .option input{margin:0;flex:none;width:17px;height:17px;accent-color:var(--blue-light)}
+  .option-text{min-width:0;display:grid;gap:3px}
+  .option strong{overflow-wrap:anywhere;font-size:14px;font-weight:600}
+  .option small{font-size:12px;color:var(--muted)}
+  .actions{display:flex;align-items:center;flex-wrap:wrap;gap:12px;margin-top:24px}
+  .button{display:inline-flex;min-height:42px;align-items:center;justify-content:center;padding:0 17px;border:1px solid var(--blue);border-radius:8px;background:var(--blue);color:#fff;font-family:inherit;font-size:13px;font-weight:600;text-decoration:none;cursor:pointer}
+  .button:hover{background:oklch(.6 .18 255)}
+  .button:disabled{cursor:wait;opacity:.7}
+  .secondary{border-color:var(--border);background:transparent;color:var(--fg)}
+  .secondary:hover{background:var(--raised)}
+  :is(button,a):focus-visible{outline:2px solid var(--blue-light);outline-offset:3px}
+  .note{margin-top:30px;padding-top:20px;border-top:1px solid var(--border);font-size:12px}
+  .env-header{display:flex;justify-content:space-between;align-items:center;gap:14px;margin-top:36px}
+  h2{margin:0;font-size:14px;font-weight:600}
+  pre{white-space:pre-wrap;overflow-wrap:anywhere;max-height:380px;overflow:auto;padding:18px;border:1px solid var(--border);border-radius:10px;background:var(--surface);font:12px/1.6 ui-monospace,SFMono-Regular,Menlo,monospace}
+  @media(max-width:480px){.shell{width:calc(100% - 32px)}header{height:70px}main{padding-top:56px}.actions{align-items:stretch;flex-direction:column}.actions form,.actions .button{width:100%}}
+  @media(prefers-reduced-motion:reduce){.option{transition:none}}
+`;
+
+function page(title: string, content: string): string {
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${escapeHtml(title)} · Opengeni</title><style>${pageStyle}</style></head><body><div class="shell"><header><span class="brand">Opengeni</span><span class="context">GitHub connection</span></header><main>${content}</main></div></body></html>`;
+}
+
+export 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 }, index) => {
+      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${candidates.length === 1 && index === 0 ? " checked" : ""}><span class="option-text"><strong>${account}</strong><small>${label}</small></span></label>`;
+    })
+    .join("");
+  return page(
+    "Choose a GitHub account",
+    `<h1>Choose a GitHub account</h1><p class="intro">Connect an account where the Opengeni GitHub App is already installed, or install it on another account.</p><form id="existing-account" method="get" action="${escapeHtml(action)}"><input type="hidden" name="state" value="${escapeHtml(state)}"><fieldset class="options" aria-label="Available GitHub accounts">${options}</fieldset></form><div class="actions"><button class="button" type="submit" form="existing-account">Connect selected account</button><form method="get" action="${escapeHtml(action)}"><input type="hidden" name="state" value="${escapeHtml(state)}"><input type="hidden" name="installation_id" value="new"><button class="button secondary" type="submit">Install on another account</button></form></div><p class="note">Only accounts GitHub has confirmed you own or manage appear here.</p>`,
+  );
+}
+
+export function githubSetupSuccessHtml(account: string, returnUrl: string): string {
+  return page(
+    "GitHub connected",
+    `<h1>GitHub connected</h1><p class="intro"><strong>${escapeHtml(account)}</strong> is now available in this Opengeni workspace. Opengeni can access only the repositories allowed for this installation.</p><a class="button" href="${escapeHtml(returnUrl)}">Back to Opengeni</a>`,
+  );
+}
+
+export function githubSetupPendingHtml(): string {
+  return page(
+    "GitHub approval pending",
+    `<h1>Waiting for an organization owner</h1><p>An owner needs to approve your GitHub App request before you can connect. Opengeni has not created a workspace binding.</p>`,
+  );
+}
+
+/**
+ * Why a GitHub browser step could not continue. Browser navigation (a stale
+ * page-load link, GitHub's Cancel button, a non-owner) must land on a readable
+ * page with a way back, never on a raw JSON error body.
+ */
+export type GitHubConnectFailure =
+  | "expired"
+  | "cancelled"
+  | "not_owner"
+  | "forbidden"
+  | "policy_denied"
+  | "signed_out"
+  | "failed";
+
+const GITHUB_CONNECT_FAILURE_COPY: Record<GitHubConnectFailure, { title: string; body: string }> = {
+  expired: {
+    title: "This GitHub link expired",
+    body: "GitHub connection links stay valid for 10 minutes, and each one works once. Go back to Opengeni and select Connect again to get a fresh link.",
+  },
+  cancelled: {
+    title: "GitHub connection cancelled",
+    body: "You cancelled on GitHub, so nothing was connected. Go back to Opengeni and select Connect when you are ready.",
+  },
+  not_owner: {
+    title: "An owner needs to connect this account",
+    body: "Only the owner of the GitHub account, or an owner of the GitHub organization, can connect it to Opengeni. Ask an owner to connect it, or install the app on an account you own.",
+  },
+  forbidden: {
+    title: "You can't manage GitHub here",
+    body: "Your Opengeni access doesn't allow connecting GitHub for this workspace. Ask a workspace admin to connect it.",
+  },
+  policy_denied: {
+    title: "GitHub is turned off for your organization",
+    body: "Your organization's integration policy doesn't allow connecting GitHub. Ask an organization admin to allow it, then select Connect again.",
+  },
+  signed_out: {
+    title: "Sign in to continue",
+    body: "Your Opengeni sign-in wasn't available when GitHub sent you back. Sign in to Opengeni and select Connect again.",
+  },
+  failed: {
+    title: "GitHub couldn't finish connecting",
+    body: "Nothing was connected. Go back to Opengeni and select Connect to try again.",
+  },
+};
+
+export function githubConnectFailureHtml(
+  failure: GitHubConnectFailure,
+  returnUrl: string,
+  detail?: string | null,
+): string {
+  const copy = GITHUB_CONNECT_FAILURE_COPY[failure];
+  const note = detail?.trim()
+    ? `<p class="note">Details: ${escapeHtml(detail.trim().slice(0, 300))}</p>`
+    : "";
+  return page(
+    copy.title,
+    `<h1>${escapeHtml(copy.title)}</h1><p class="intro">${escapeHtml(copy.body)}</p><a class="button" href="${escapeHtml(returnUrl)}">Back to Opengeni</a>${note}`,
+  );
+}
+
+export function githubSuccessHtml(envLines: string[]): string {
+  const escaped = escapeHtml(envLines.join("\n"));
+  return page(
+    "GitHub App created",
+    `<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 class="button secondary" 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>`,
+  );
+}
+
+function escapeHtml(value: string): string {
+  return value.replace(
+    /[&<>"']/g,
+    (char) =>
+      ({
+        "&": "&amp;",
+        "<": "&lt;",
+        ">": "&gt;",
+        '"': "&quot;",
+        "'": "&#39;",
+      })[char] ?? char,
+  );
+}