@opengeni/api-router 0.5.7 → 0.9.0

package/src/routes/enrollments.ts

@@ -1,5 +1,5 @@
 // apps/api/src/routes/enrollments.ts — the bring-your-own-compute enrollment
-// device-flow routes (M5; dossier §10.2 + §18). Mirrors the other sandbox route
+// device-flow routes (M5). Mirrors the other sandbox route
 // modules (registerSessionRoutes / registerApiKeyRoutes): a thin route over a
 // focused service (../sandbox/enrollment.ts), requireAccessGrant BEFORE any Zod
 // parse on the USER-authenticated routes, explicit HTTPException(400) on a parse
@@ -69,7 +69,7 @@ export function registerEnrollmentRoutes(app: Hono, deps: ApiRouteDeps): void {
   }
 
   // A tiny in-process IP token-bucket for the UNAUTHENTICATED agent routes (start/
-  // poll). The relay tier owns the heavy stream rate-limiting (dossier §10.5); this
+  // poll). The relay tier owns the heavy stream rate-limiting; this
   // is the application-tier abuse cap on the device-flow endpoints. Per-IP buckets
   // are pruned lazily. Not a distributed limiter (one replica per bucket) — that is
   // acceptable for a bounded, access-key-gated, short-TTL flow.

package/src/routes/files.ts

@@ -4,6 +4,13 @@ import {
   CreateFileUploadResponse,
   FileAsset,
   FileDownloadUrlResponse,
+  RETAINED_OUTPUT_DEFAULT_PAGE_BYTES,
+  RETAINED_OUTPUT_MAX_PAGE_BYTES,
+  RetainedArtifactMetadataSchema,
+  retainedArtifactReferenceFromFile,
+  resolveRetainedOutputRange,
+  type RetainedArtifactMetadata,
+  type RetainedOutputUnavailableReason,
 } from "@opengeni/contracts";
 import {
   claimFileUploadCleanup,
@@ -11,7 +18,9 @@ import {
   completeFileUpload,
   createFileUpload,
   getFileUpload,
+  getRetainedFileArtifact,
   requireFile,
+  type RetainedFileArtifact,
 } from "@opengeni/db";
 import type { Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
@@ -235,6 +244,90 @@ export function registerFileRoutes(app: Hono, deps: ApiRouteDeps): void {
     return c.json(FileAsset.parse(file));
   });
 
+  app.get("/v1/workspaces/:workspaceId/artifacts/:artifactId", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "files:read");
+    const artifactId = retainedArtifactId(c.req.param("artifactId"));
+    const artifact = await getRetainedFileArtifact(db, workspaceId, artifactId);
+    if (!artifact) {
+      return c.json(retainedArtifactUnavailable(artifactId, "deleted"), 404);
+    }
+    return c.json(retainedArtifactMetadata(artifact));
+  });
+
+  app.get("/v1/workspaces/:workspaceId/artifacts/:artifactId/content", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "files:read");
+    const artifactId = retainedArtifactId(c.req.param("artifactId"));
+    const artifact = await getRetainedFileArtifact(db, workspaceId, artifactId);
+    if (!artifact) {
+      return c.json(retainedArtifactUnavailable(artifactId, "deleted"), 404);
+    }
+
+    const metadata = retainedArtifactMetadata(artifact);
+    if (!metadata.available) {
+      return c.json(metadata, retainedArtifactUnavailableStatus(metadata.reason));
+    }
+    if (!objectStorage) {
+      return c.json(retainedArtifactUnavailable(artifactId, "missing_storage"), 503);
+    }
+
+    const rangeHeader = c.req.header("range");
+    const range = resolveRetainedOutputRange(
+      rangeHeader,
+      metadata.originalBytes,
+      rangeHeader ? RETAINED_OUTPUT_MAX_PAGE_BYTES : RETAINED_OUTPUT_DEFAULT_PAGE_BYTES,
+    );
+    if (range.kind === "invalid") {
+      return c.json(
+        {
+          message: "invalid retained artifact byte range",
+          reason: range.reason,
+          maxRangeBytes: RETAINED_OUTPUT_MAX_PAGE_BYTES,
+        },
+        400,
+      );
+    }
+    if (range.kind === "unsatisfiable") {
+      return c.json(
+        { message: "retained artifact byte range is not satisfiable", reason: range.reason },
+        416,
+        {
+          "Accept-Ranges": "bytes",
+          "Content-Range": range.contentRange,
+          "Cache-Control": "private, no-store",
+        },
+      );
+    }
+
+    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",
+      ...(range.contentRange ? { "Content-Range": range.contentRange } : {}),
+    };
+    if (range.kind === "empty") {
+      if (!(await objectStorage.fileExists(artifact.file))) {
+        return c.json(retainedArtifactUnavailable(artifactId, "missing_storage"), 410);
+      }
+      return c.body(null, 200, headers);
+    }
+
+    const bytes = await objectStorage.getFileRange(artifact.file, {
+      start: range.start,
+      end: range.end,
+    });
+    if (!bytes) {
+      return c.json(retainedArtifactUnavailable(artifactId, "missing_storage"), 410);
+    }
+    if (bytes.byteLength !== range.length) {
+      throw new HTTPException(502, { message: "object storage returned an invalid byte range" });
+    }
+    return c.body(new Uint8Array(bytes), range.status, headers);
+  });
+
   app.post("/v1/workspaces/:workspaceId/files/:fileId/download-url", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     await requireAccessGrant(c, deps, workspaceId, "files:read");
@@ -271,3 +364,63 @@ function sanitizeFilename(filename: string): string {
 function publicFileUploadStatus(status: string): string {
   return status === "cleanup_pending" ? "failed" : status;
 }
+
+function retainedArtifactId(value: string): string {
+  const parsed = FileAsset.shape.id.safeParse(value);
+  if (!parsed.success) {
+    throw new HTTPException(404, { message: "artifact not found" });
+  }
+  return parsed.data;
+}
+
+function retainedArtifactUnavailable(
+  artifactId: string,
+  reason: RetainedOutputUnavailableReason,
+): RetainedArtifactMetadata {
+  return RetainedArtifactMetadataSchema.parse({ available: false, artifactId, reason });
+}
+
+function retainedArtifactMetadata(artifact: RetainedFileArtifact): RetainedArtifactMetadata {
+  const reference = retainedArtifactReferenceFromFile(artifact.file);
+  if (reference) return reference;
+
+  const { file, uploadStatus, uploadExpiresAt } = artifact;
+  if (file.status === "deleted") {
+    return retainedArtifactUnavailable(file.id, "deleted");
+  }
+  if (
+    file.status === "expired" ||
+    uploadStatus === "expired" ||
+    (uploadStatus === "pending" &&
+      uploadExpiresAt !== null &&
+      uploadExpiresAt.getTime() < Date.now())
+  ) {
+    return retainedArtifactUnavailable(file.id, "expired");
+  }
+  if (file.status === "failed" || uploadStatus === "failed" || uploadStatus === "cleanup_pending") {
+    return retainedArtifactUnavailable(file.id, "failed");
+  }
+  if (file.status === "pending_upload" || uploadStatus === "pending") {
+    return retainedArtifactUnavailable(file.id, "pending");
+  }
+  return retainedArtifactUnavailable(file.id, "unsupported");
+}
+
+function retainedArtifactUnavailableStatus(
+  reason: RetainedOutputUnavailableReason,
+): 404 | 409 | 410 | 422 {
+  switch (reason) {
+    case "deleted":
+      return 404;
+    case "expired":
+    case "missing_storage":
+      return 410;
+    case "unsupported":
+    case "not_retained":
+    case "storage_write_failed":
+      return 422;
+    case "pending":
+    case "failed":
+      return 409;
+  }
+}

package/src/routes/github.ts

@@ -1,5 +1,5 @@
 import { GitHubAppManifestCreate } from "@opengeni/contracts";
-import { listGitHubInstallationIdsForWorkspace, upsertGitHubInstallation } from "@opengeni/db";
+import { deleteGitHubInstallationBinding } from "@opengeni/db";
 import {
   buildGitHubAppManifest,
   convertGitHubAppManifest,
@@ -7,56 +7,52 @@ import {
   envLinesFromGitHubManifestConversion,
   GitHubAppApiError,
   GitHubAppConfigurationError,
-  githubOAuthAuthorizeUrl,
   githubAppMissingSettings,
-  listGitHubAppRepositories,
   organizationAppManifestUrl,
   personalAppManifestUrl,
   readSignedState,
   stateMaxAgeSeconds,
-  verifyGitHubInstallationAccessForUser,
   verifySignedState,
 } from "@opengeni/github";
 import type { Context, Hono } from "hono";
-import { deleteCookie, getCookie, setCookie } from "hono/cookie";
+import { setCookie } from "hono/cookie";
 import { HTTPException } from "hono/http-exception";
 import { requireAccessGrant } from "@opengeni/core";
 import type { ApiRouteDeps } from "@opengeni/core";
+import {
+  listWorkspaceGitHubInstallationBindings,
+  listWorkspaceGitHubRepositories,
+} from "../github-access";
 
 const githubStateCookie = "opengeni_github_state";
+const installationBindingDisabledMessage =
+  "Connecting a GitHub App installation is disabled until GitHub installation authority can be proven";
 
 export function registerGitHubRoutes(app: Hono, deps: ApiRouteDeps): void {
-  const { settings, githubStateSecret } = deps;
+  const { db, settings, githubStateSecret } = deps;
 
   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 missing = githubAppMissingSettings(settings);
     const slug = settings.githubAppSlug?.trim() || null;
-    const state = createSignedState(githubStateSecret, {
-      accountId: grant.accountId,
-      workspaceId: grant.workspaceId,
-    });
-    setGitHubStateCookie(c, deps, state);
     return c.json({
       configured: missing.length === 0,
       appId: settings.githubAppId ?? null,
       clientId: settings.githubClientId ?? null,
       appSlug: slug,
-      installUrl: slug
-        ? `https://github.com/apps/${slug}/installations/new?state=${encodeURIComponent(state)}`
-        : null,
+      // Kept nullable for SDK compatibility. GitHub's setup callback contains
+      // a spoofable installation_id, while user-installation visibility and
+      // repository admin permission do not prove that this human may bind it.
+      installUrl: null,
+      linkUrl: null,
+      installations: await listWorkspaceGitHubInstallationBindings(deps, grant.workspaceId),
       missing,
     });
   });
 
-  // Browser entry point for install links issued outside a browser context
-  // (the first-party MCP github_connect_link tool): it plants the CSRF state
-  // cookie the install/OAuth callbacks require and forwards to GitHub.
-  // Deliberately unauthenticated: the signed state is only ever minted for
-  // grants holding github:use, expires after stateMaxAgeSeconds, and is bound
-  // to this workspace; completing the installation binding still requires an
-  // authenticated github:manage grant in the same browser at the callback.
+  // Retain the entry route so already-issued links fail closed with an
+  // explicit terminal response instead of falling through to another intent.
   app.get("/v1/workspaces/:workspaceId/github/connect", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const state = c.req.query("state");
@@ -67,19 +63,7 @@ export function registerGitHubRoutes(app: Hono, deps: ApiRouteDeps): void {
     if (!statePayload || statePayload.workspaceId !== workspaceId) {
       throw new HTTPException(400, { message: "invalid or expired GitHub installation state" });
     }
-    const slug = settings.githubAppSlug?.trim();
-    if (!slug) {
-      throw new HTTPException(409, {
-        message: JSON.stringify({
-          message: "GitHub App is not configured",
-          missing: githubAppMissingSettings(settings),
-        }),
-      });
-    }
-    setGitHubStateCookie(c, deps, state);
-    return c.redirect(
-      `https://github.com/apps/${slug}/installations/new?state=${encodeURIComponent(state)}`,
-    );
+    throw installationBindingDisabled();
   });
 
   app.get("/v1/workspaces/:workspaceId/github/repositories", async (c) => {
@@ -116,6 +100,24 @@ export function registerGitHubRoutes(app: Hono, deps: ApiRouteDeps): void {
     }
   });
 
+  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");
+    const installationId = parsePositiveInteger(c.req.param("installationId"));
+    if (installationId === null) {
+      throw new HTTPException(400, { message: "invalid GitHub installation id" });
+    }
+    const deleted = 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);
+  });
+
   app.post("/v1/workspaces/:workspaceId/github/app-manifest", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "github:manage");
@@ -159,12 +161,8 @@ export function registerGitHubRoutes(app: Hono, deps: ApiRouteDeps): void {
     try {
       const conversion = await convertGitHubAppManifest(code);
       const envLines = envLinesFromGitHubManifestConversion(conversion);
-      const slug = String(conversion.slug ?? "");
-      const installUrl = slug
-        ? `https://github.com/apps/${slug}/installations/new?state=${encodeURIComponent(state)}`
-        : "";
       setGitHubStateCookie(c, deps, state);
-      return c.html(githubSuccessHtml(envLines, installUrl));
+      return c.html(githubSuccessHtml(envLines));
     } catch (error) {
       const message = error instanceof GitHubAppApiError ? error.message : String(error);
       throw new HTTPException(502, { message });
@@ -172,10 +170,7 @@ export function registerGitHubRoutes(app: Hono, deps: ApiRouteDeps): void {
   });
 
   const handleGitHubInstallCallback = async (c: Context) => {
-    const code = c.req.query("code");
     const state = c.req.query("state");
-    const installationIdRaw = c.req.query("installation_id");
-    const setupAction = c.req.query("setup_action") ?? null;
     if (!state) {
       throw new HTTPException(400, { message: "missing GitHub installation state" });
     }
@@ -187,147 +182,50 @@ export function registerGitHubRoutes(app: Hono, deps: ApiRouteDeps): void {
     ) {
       throw new HTTPException(400, { message: "invalid or expired GitHub installation state" });
     }
-    requireGitHubStateCookie(c, state);
-    const grant = await requireAccessGrant(c, deps, statePayload.workspaceId, "github:manage");
-    if (grant.accountId !== statePayload.accountId) {
-      throw new HTTPException(403, {
-        message: "GitHub installation state does not match this workspace",
-      });
-    }
-    if (setupAction === "request" && !installationIdRaw) {
-      return c.html(githubSetupPendingHtml());
-    }
-    const installationId = parsePositiveInteger(installationIdRaw);
-    if (installationId === null) {
-      throw new HTTPException(400, { message: "missing or invalid GitHub installation_id" });
-    }
-    if (!code) {
-      const clientId = settings.githubClientId?.trim();
-      if (!clientId) {
-        throw new HTTPException(409, {
-          message: JSON.stringify({
-            message: "GitHub App is not configured",
-            missing: ["OPENGENI_GITHUB_CLIENT_ID"],
-          }),
-        });
-      }
-      const oauthState = createSignedState(githubStateSecret, {
-        accountId: grant.accountId,
-        workspaceId: grant.workspaceId,
-        installationId,
-      });
-      const baseUrl = (
-        settings.githubAppManifestBaseUrl ??
-        settings.publicBaseUrl ??
-        new URL(c.req.url).origin
-      ).replace(/\/+$/, "");
-      setGitHubStateCookie(c, deps, oauthState);
-      return c.redirect(
-        githubOAuthAuthorizeUrl({
-          clientId,
-          state: oauthState,
-          redirectUri: `${baseUrl}/v1/github/oauth/callback`,
-        }),
-      );
-    }
-    return await completeGitHubInstallationBinding(deps, c, {
-      code,
-      statePayload,
-      installationId,
-    });
+    throw installationBindingDisabled();
   };
 
   app.get("/v1/github/setup", handleGitHubInstallCallback);
   app.get("/v1/github/install/callback", handleGitHubInstallCallback);
 
   app.get("/v1/github/oauth/callback", async (c) => {
-    const code = c.req.query("code");
     const state = c.req.query("state");
-    if (!code) {
-      throw new HTTPException(400, { message: "missing GitHub OAuth code" });
-    }
     if (!state) {
       throw new HTTPException(400, { message: "missing GitHub OAuth state" });
     }
     const statePayload = readSignedState(state, githubStateSecret);
-    const installationId = parsePositiveInteger(String(statePayload?.installationId ?? ""));
     if (
       !statePayload ||
       typeof statePayload.accountId !== "string" ||
-      typeof statePayload.workspaceId !== "string" ||
-      installationId === null
+      typeof statePayload.workspaceId !== "string"
     ) {
       throw new HTTPException(400, { message: "invalid or expired GitHub OAuth state" });
     }
-    requireGitHubStateCookie(c, state);
-    return await completeGitHubInstallationBinding(deps, c, {
-      code,
-      statePayload,
-      installationId,
-    });
+    throw installationBindingDisabled();
   });
-}
 
-async function completeGitHubInstallationBinding(
-  deps: ApiRouteDeps,
-  c: Context,
-  input: {
-    code: string;
-    statePayload: { accountId?: string; workspaceId?: string };
-    installationId: number;
-  },
-) {
-  const { db, settings } = deps;
-  if (!input.statePayload.workspaceId || !input.statePayload.accountId) {
-    throw new HTTPException(400, { message: "invalid or expired GitHub installation state" });
-  }
-  const grant = await requireAccessGrant(c, deps, input.statePayload.workspaceId, "github:manage");
-  if (grant.accountId !== input.statePayload.accountId) {
-    throw new HTTPException(403, {
-      message: "GitHub installation state does not match this workspace",
-    });
-  }
-  try {
-    const installation = await verifyGitHubInstallationAccessForUser(settings, {
-      code: input.code,
-      installationId: input.installationId,
-    });
-    if (!installation) {
-      throw new HTTPException(404, {
-        message: "GitHub App installation was not found for this app",
-      });
-    }
-    if (installation.suspended) {
-      throw new HTTPException(409, { message: "GitHub App installation is suspended" });
-    }
-    await upsertGitHubInstallation(db, {
-      accountId: grant.accountId,
-      workspaceId: grant.workspaceId,
-      installationId: input.installationId,
-      accountLogin: installation.accountLogin,
-      accountType: installation.accountType,
-    });
-    const returnUrl = openGeniReturnUrl(settings, c, input.statePayload.workspaceId);
-    deleteCookie(c, githubStateCookie, { path: "/v1/github" });
-    return c.html(
-      githubSetupSuccessHtml(
-        installation.accountLogin ?? `installation ${input.installationId}`,
-        returnUrl,
-      ),
-    );
-  } catch (error) {
-    if (error instanceof HTTPException) {
-      throw error;
+  app.post("/v1/workspaces/:workspaceId/github/installations", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const form = new URLSearchParams(await c.req.text());
+    const state = form.get("oauth_state");
+    if (!state) {
+      throw new HTTPException(400, { message: "missing GitHub OAuth state" });
     }
-    if (error instanceof GitHubAppConfigurationError) {
-      throw new HTTPException(409, {
-        message: JSON.stringify({ message: error.message, missing: error.missing }),
-      });
+    const statePayload = readSignedState(state, githubStateSecret);
+    if (
+      !statePayload ||
+      typeof statePayload.accountId !== "string" ||
+      statePayload.accountId.length === 0 ||
+      statePayload.workspaceId !== workspaceId
+    ) {
+      throw new HTTPException(400, { message: "invalid or expired GitHub OAuth state" });
     }
-    throw new HTTPException(502, {
-      message: error instanceof Error ? error.message : String(error),
-    });
-  }
+    throw installationBindingDisabled();
+  });
+}
+
+function installationBindingDisabled(): HTTPException {
+  return new HTTPException(410, { message: installationBindingDisabledMessage });
 }
 
 function setGitHubStateCookie(c: Context, deps: ApiRouteDeps, state: string): void {
@@ -335,19 +233,11 @@ function setGitHubStateCookie(c: Context, deps: ApiRouteDeps, state: string): vo
     httpOnly: true,
     sameSite: "Lax",
     secure: isSecureRequest(c, deps),
-    path: "/v1/github",
+    path: "/v1",
     maxAge: stateMaxAgeSeconds,
   });
 }
 
-function requireGitHubStateCookie(c: Context, state: string): void {
-  if (getCookie(c, githubStateCookie) !== state) {
-    throw new HTTPException(400, {
-      message: "invalid or expired GitHub installation browser state",
-    });
-  }
-}
-
 function isSecureRequest(c: Context, deps: ApiRouteDeps): boolean {
   return (
     deps.settings.publicBaseUrl?.startsWith("https://") ||
@@ -356,26 +246,10 @@ function isSecureRequest(c: Context, deps: ApiRouteDeps): boolean {
   );
 }
 
-export async function listWorkspaceGitHubRepositories(deps: ApiRouteDeps, workspaceId: string) {
-  const installationIds = await listGitHubInstallationIdsForWorkspace(deps.db, workspaceId);
-  return await listGitHubAppRepositories(deps.settings, { installationIds });
-}
-
-function githubSuccessHtml(envLines: string[], installUrl: string): string {
+function githubSuccessHtml(envLines: string[]): string {
   const envText = envLines.join("\n");
   const escaped = escapeHtml(envText);
-  const install = installUrl
-    ? `<a class="button secondary" href="${escapeHtml(installUrl)}">Install on repositories</a>`
-    : "";
-  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}.actions{display:flex;flex-wrap:wrap;gap:10px;margin-top:18px}.button,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;cursor:pointer}.button.secondary{background:transparent;color:#fafafa}.button.secondary:hover,button.secondary:hover{background:#27272a}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><div class="actions">${install}</div><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}.button:hover{background:#e4e4e7}</style></head><body><main><h1>GitHub App connected</h1><p>${escapeHtml(account)} is now available to this OpenGeni workspace.</p><a class="button" href="${escapeHtml(returnUrl)}">Back to OpenGeni</a></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>An organization administrator must approve the installation before OpenGeni can connect it to this workspace.</p></main></body></html>`;
+  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 parsePositiveInteger(value: string | undefined | null): number | null {
@@ -399,16 +273,3 @@ function escapeHtml(value: string): string {
       })[char] ?? char,
   );
 }
-
-function openGeniReturnUrl(
-  settings: ApiRouteDeps["settings"],
-  c: Context,
-  workspaceId: string | undefined,
-): string {
-  const base = (settings.publicBaseUrl ?? new URL(c.req.url).origin).replace(/\/+$/, "");
-  const url = new URL(base || new URL(c.req.url).origin);
-  if (workspaceId) {
-    url.searchParams.set("workspaceId", workspaceId);
-  }
-  return url.toString();
-}

package/src/routes/install.ts

@@ -3,7 +3,7 @@ import type { Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
 import type { ApiRouteDeps } from "@opengeni/core";
 
-// The get.<domain> install-serving routes (dossier §23.1). These are
+// The get.<domain> install-serving routes. These are
 // UNAUTHENTICATED (see http/auth.ts isAuthExempt — the `installExemptPaths` set)
 // so a fresh machine with no credentials can `curl -fsSL https://get.<domain>/install.sh`,
 // read it first, then pipe to sh. They serve the IN-REPO committed script bodies

package/src/routes/machines.ts

@@ -1,5 +1,5 @@
 // apps/api/src/routes/machines.ts — the M10 Machines-dashboard + per-machine
-// metrics-series ROUTES (dossier §10.7). Mirrors registerEnrollmentRoutes: thin
+// metrics-series ROUTES. Mirrors registerEnrollmentRoutes: thin
 // routes over a focused service (../sandbox/machines.ts), requireAccessGrant
 // BEFORE any work, the whole router gated behind sandboxSelfhostedEnabled
 // (default OFF → 404, invisible). Both routes need perm enrollments:read.
@@ -28,7 +28,7 @@ import { buildFleetContextForSession, swapActiveSandbox } from "@opengeni/core";
 import { listMachines, metricRowToSample } from "../sandbox/machines";
 
 // The supported series windows → milliseconds. An unknown/absent window defaults
-// to 1h (the dossier default). Bounded so a caller cannot request an unbounded
+// to 1h (the default). Bounded so a caller cannot request an unbounded
 // scan; longer ranges are a later concern (retention is ~N days).
 const SERIES_WINDOWS_MS: Record<string, number> = {
   "15m": 15 * 60_000,