@opengeni/api-router 0.2.0

package/src/routes/github.ts

@@ -0,0 +1,341 @@
+import { GitHubAppManifestCreate } from "@opengeni/contracts";
+import {
+  listGitHubInstallationIdsForWorkspace,
+  upsertGitHubInstallation,
+} from "@opengeni/db";
+import {
+  buildGitHubAppManifest,
+  convertGitHubAppManifest,
+  createSignedState,
+  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 { HTTPException } from "hono/http-exception";
+import { requireAccessGrant } from "@opengeni/core";
+import type { ApiRouteDeps } from "@opengeni/core";
+
+const githubStateCookie = "opengeni_github_state";
+
+export function registerGitHubRoutes(app: Hono, deps: ApiRouteDeps): void {
+  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,
+      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.
+  app.get("/v1/workspaces/:workspaceId/github/connect", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const state = c.req.query("state");
+    if (!state) {
+      throw new HTTPException(400, { message: "missing GitHub installation state" });
+    }
+    const statePayload = readSignedState(state, githubStateSecret);
+    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)}`);
+  });
+
+  app.get("/v1/workspaces/:workspaceId/github/repositories", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "github:use");
+    try {
+      return c.json({ repositories: await listWorkspaceGitHubRepositories(deps, workspaceId) });
+    } catch (error) {
+      if (error instanceof GitHubAppConfigurationError) {
+        throw new HTTPException(409, { message: JSON.stringify({ message: error.message, missing: error.missing }) });
+      }
+      throw new HTTPException(502, { message: error instanceof Error ? error.message : String(error) });
+    }
+  });
+
+  app.post("/v1/workspaces/:workspaceId/github/repositories/sync", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "github:use");
+    try {
+      return c.json({ repositories: await listWorkspaceGitHubRepositories(deps, workspaceId) });
+    } catch (error) {
+      if (error instanceof GitHubAppConfigurationError) {
+        throw new HTTPException(409, { message: JSON.stringify({ message: error.message, missing: error.missing }) });
+      }
+      throw new HTTPException(502, { message: error instanceof Error ? error.message : String(error) });
+    }
+  });
+
+  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");
+    const payload = GitHubAppManifestCreate.parse(await c.req.json());
+    const baseUrl = (settings.githubAppManifestBaseUrl ?? new URL(c.req.url).origin).replace(/\/+$/, "");
+    const state = createSignedState(githubStateSecret, {
+      accountId: grant.accountId,
+      workspaceId: grant.workspaceId,
+    });
+    setGitHubStateCookie(c, deps, state);
+    const appName = payload.appName?.trim() || "OpenGeni";
+    const manifest = buildGitHubAppManifest({
+      appName,
+      baseUrl,
+      public: payload.public,
+      includeCiPermissions: payload.includeCiPermissions,
+      setupUrl: `${baseUrl}/v1/github/setup`,
+    });
+    const organization = payload.organization?.trim();
+    return c.json({
+      actionUrl: organization ? organizationAppManifestUrl(organization, state) : personalAppManifestUrl(state),
+      state,
+      manifest,
+    });
+  });
+
+  app.get("/v1/github/app-manifest/callback", async (c) => {
+    const code = c.req.query("code");
+    const state = c.req.query("state");
+    if (!code) {
+      throw new HTTPException(400, { message: "missing GitHub manifest code" });
+    }
+    if (!state || !verifySignedState(state, githubStateSecret)) {
+      throw new HTTPException(400, { message: "invalid or expired GitHub manifest state" });
+    }
+    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));
+    } catch (error) {
+      const message = error instanceof GitHubAppApiError ? error.message : String(error);
+      throw new HTTPException(502, { message });
+    }
+  });
+
+  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" });
+    }
+    const statePayload = readSignedState(state, githubStateSecret);
+    if (!statePayload || typeof statePayload.accountId !== "string" || typeof statePayload.workspaceId !== "string") {
+      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,
+    });
+  };
+
+  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) {
+      throw new HTTPException(400, { message: "invalid or expired GitHub OAuth state" });
+    }
+    requireGitHubStateCookie(c, state);
+    return await completeGitHubInstallationBinding(deps, c, {
+      code,
+      statePayload,
+      installationId,
+    });
+  });
+}
+
+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;
+      }
+      if (error instanceof GitHubAppConfigurationError) {
+        throw new HTTPException(409, { message: JSON.stringify({ message: error.message, missing: error.missing }) });
+      }
+      throw new HTTPException(502, { message: error instanceof Error ? error.message : String(error) });
+    }
+}
+
+function setGitHubStateCookie(c: Context, deps: ApiRouteDeps, state: string): void {
+  setCookie(c, githubStateCookie, state, {
+    httpOnly: true,
+    sameSite: "Lax",
+    secure: isSecureRequest(c, deps),
+    path: "/v1/github",
+    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://")
+    || c.req.header("x-forwarded-proto") === "https"
+    || new URL(c.req.url).protocol === "https:";
+}
+
+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 {
+  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>`;
+}
+
+function parsePositiveInteger(value: string | undefined | null): number | null {
+  if (!value || !/^\d+$/.test(value)) {
+    return null;
+  }
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
+}
+
+function escapeHtml(value: string): string {
+  return value.replace(/[&<>"']/g, (char) => ({
+    "&": "&amp;",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&#39;",
+  }[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

@@ -0,0 +1,218 @@
+import { readFile, stat } from "node:fs/promises";
+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
+// 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
+// (agent/install/*) verbatim — a single branded, audit-greppable trust root.
+//
+// The script BODIES contain NO secrets (POSIX sh, the device-flow captures the
+// loud consent). The release-binary asset routes serve the agent BAKED into THIS
+// control-plane image (the per-SHA Linux musl binary + its `.sha256`/`.minisig`)
+// when present, and otherwise 302-redirect to the matching GitHub Release asset.
+//
+// "The agent ships inside the control-plane" (the owned decision): for every
+// deployed env (preview/staging/managed-prod) the API image — already built
+// per-SHA by GitHub Actions from the PR branch — bakes the SIGNED `opengeni-agent`
+// binary matching that EXACT control-plane SHA into agent/install/baked/ (a CI step
+// signs + COPYs; the signing key never enters the Docker build). install.sh then
+// pulls a binary that is guaranteed in lockstep with the API it enrolls against —
+// zero drift, zero new store. GitHub Releases remains the PUBLIC archive + the
+// self-update channel + the install.sh fallback (mac/windows, and any asset this
+// image did not bake), reached by the 302 below.
+
+// The committed install artifacts, resolved relative to this module so the API
+// (run from source under /app via bun) locates the sibling agent/install/ dir at
+// runtime. apps/api/src/routes -> ../../../../agent/install.
+const INSTALL_DIR = new URL("../../../../agent/install/", import.meta.url);
+
+// The baked release-binary dir (a sibling of the committed scripts). The build's
+// signing step writes the per-SHA Linux musl binaries + their `.sha256`/`.minisig`
+// siblings here; in a plain `docker build` (or a source checkout) it holds only a
+// `.gitkeep`, so every asset falls through to the GitHub-Releases redirect.
+const BAKED_DIR = new URL("baked/", INSTALL_DIR);
+
+// The static text artifacts served verbatim, with their content types. Each is
+// read once at first request and memoized (committed files; immutable per deploy).
+const TEXT_ASSETS: Record<string, { file: string; contentType: string }> = {
+  "/install.sh": { file: "install.sh", contentType: "text/x-shellscript; charset=utf-8" },
+  "/install.ps1": { file: "install.ps1", contentType: "text/plain; charset=utf-8" },
+  "/uninstall.sh": { file: "uninstall.sh", contentType: "text/x-shellscript; charset=utf-8" },
+  "/opengeni-agent-minisign.pub": { file: "opengeni-agent-minisign.pub", contentType: "text/plain; charset=utf-8" },
+};
+
+const assetCache = new Map<string, string>();
+
+async function loadAsset(file: string): Promise<string> {
+  const cached = assetCache.get(file);
+  if (cached !== undefined) {
+    return cached;
+  }
+  const body = await readFile(new URL(file, INSTALL_DIR), "utf8");
+  assetCache.set(file, body);
+  return body;
+}
+
+// "The agent ships inside the control-plane" (cont.): the committed install
+// scripts default their release-asset base URL to the public archive
+// (get.opengeni.ai) so a from-source / standalone copy still works. But a
+// DEPLOYED control plane must serve a script that pulls the agent from ITSELF —
+// the per-SHA binary baked into THIS image, via the /agent/* routes below — so
+// `curl https://<this-host>/install.sh | sh` installs the exact agent that
+// matches the API it enrolls against, with NO dependency on a public CDN (which a
+// private/air-gapped deploy may not even resolve). When a public base URL is
+// configured we therefore rewrite each script's default-base-URL marker line to
+// that origin before serving. The user's OPENGENI_INSTALL_BASE_URL env override
+// still wins at run time (the scripts use `:-default`); only the built-in DEFAULT
+// changes. The marker lines are kept shape-stable in agent/install/install.{sh,ps1}.
+const DEFAULT_BASE_REWRITES: Record<string, (base: string) => { from: string; to: string }> = {
+  "install.sh": (base) => ({
+    from: 'OPENGENI_INSTALL_DEFAULT_BASE_URL="https://get.opengeni.ai"',
+    to: `OPENGENI_INSTALL_DEFAULT_BASE_URL="${base}"`,
+  }),
+  "install.ps1": (base) => ({
+    from: "$OpengeniInstallDefaultBaseUrl = 'https://get.opengeni.ai'",
+    to: `$OpengeniInstallDefaultBaseUrl = '${base}'`,
+  }),
+};
+
+// Rewrite a served script's default release-asset base URL to this deployment's
+// own public origin. A no-op when no public base URL is configured (the public
+// archive default stands), when the URL is not absolute http(s) (never serve a
+// script with a broken base), or when the file has no marker (script drift — fail
+// safe to serving it verbatim rather than crashing the install surface).
+function rewriteDefaultBaseUrl(file: string, body: string, publicBaseUrl: string | undefined): string {
+  if (!publicBaseUrl || !/^https?:\/\//.test(publicBaseUrl)) {
+    return body;
+  }
+  const base = publicBaseUrl.replace(/\/+$/, "");
+  const rule = DEFAULT_BASE_REWRITES[file]?.(base);
+  if (!rule || !body.includes(rule.from)) {
+    return body;
+  }
+  return body.replace(rule.from, rule.to);
+}
+
+// The content type for a baked release asset. The binary is an
+// application/octet-stream download; its `.sha256`/`.minisig` sidecars are short
+// text the install script parses line-by-line.
+function bakedContentType(asset: string): string {
+  if (asset.endsWith(".sha256") || asset.endsWith(".minisig")) {
+    return "text/plain; charset=utf-8";
+  }
+  return "application/octet-stream";
+}
+
+// Read a baked asset's bytes, or `null` when it is not baked into THIS image (the
+// signal to fall through to the GitHub-Releases redirect). The asset name is
+// already validated against ASSET_NAME by the caller (no traversal possible), and
+// BAKED_DIR is a fixed sibling, so the resolved path cannot escape the dir.
+async function readBaked(asset: string): Promise<ArrayBuffer | null> {
+  const url = new URL(asset, BAKED_DIR);
+  try {
+    const info = await stat(url);
+    if (!info.isFile()) {
+      return null;
+    }
+  } catch {
+    return null;
+  }
+  // Return a standalone ArrayBuffer (a valid Response BodyInit). `readFile`'s
+  // Buffer may be a view into a larger pooled allocation, so copy out the exact
+  // byte range with `.slice` rather than handing over the backing store.
+  const buf = await readFile(url);
+  return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+}
+
+// `/agent/latest/<asset>` and `/agent/v<ver>/<asset>` (+ the `.sha256` / `.minisig`
+// siblings the install script fetches) — see agent/install/install.sh asset_url().
+// `<asset>` and the version segment are constrained so the redirect cannot be used
+// as an open redirector: only the agent asset-name shape + a `v`-prefixed version.
+const ASSET_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+// The install script's version path segment is the literal `v<ver>` (e.g. v1.2.3).
+const VERSION_SEG = /^v[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+export function registerInstallRoutes(app: Hono, deps: ApiRouteDeps): void {
+  const releasesBase = deps.settings.agentReleasesBaseUrl.replace(/\/+$/, "");
+
+  for (const [path, { file, contentType }] of Object.entries(TEXT_ASSETS)) {
+    app.get(path, async (c) => {
+      // Serve the committed body, but rewrite the install scripts' default
+      // asset base URL to THIS deployment's origin so the agent is pulled from
+      // the same control plane it enrolls against (see rewriteDefaultBaseUrl).
+      const body = rewriteDefaultBaseUrl(file, await loadAsset(file), deps.settings.publicBaseUrl);
+      return c.text(body, 200, {
+        "content-type": contentType,
+        // Short cache: the edge serves the latest committed copy; new installs
+        // should pick up script fixes promptly, but a brief cache absorbs bursts.
+        "cache-control": "public, max-age=300",
+      });
+    });
+  }
+
+  // Serve a release-binary asset: the BAKED per-SHA file if THIS image carries it
+  // (the Linux musl binary + sidecars that match the control plane exactly),
+  // otherwise 302 to the GitHub Release at `redirectUrl` (mac/windows + any
+  // un-baked asset). The baked path makes the agent the API enrolls against
+  // identical to the API that serves it — no version skew, no extra hop.
+  async function serveAsset(asset: string, redirectUrl: string): Promise<Response> {
+    const baked = await readBaked(asset);
+    if (baked !== null) {
+      return new Response(baked, {
+        status: 200,
+        headers: {
+          "content-type": bakedContentType(asset),
+          // The baked artifact is immutable for this image SHA: the binary, its
+          // checksum, and its signature never change once built. A long cache is
+          // safe; new installs land when a new image (new SHA) rolls out.
+          "cache-control": "public, max-age=3600",
+          "x-opengeni-agent-source": "baked",
+        },
+      });
+    }
+    // Not baked here → the GitHub Release is the source of truth (the public
+    // archive + the documented install.sh fallback). 302 so the client refetches.
+    return new Response(null, { status: 302, headers: { location: redirectUrl } });
+  }
+
+  // `latest` → the BAKED binary if present, else the dedicated moving
+  // `agent-latest` GitHub Release. We deliberately do NOT use GitHub's
+  // repo-global `releases/latest` alias here: in this monorepo that alias is
+  // perpetually shadowed by the frequent changesets package releases (e.g.
+  // `@opengeni/contracts@x.y.z`), which carry no agent binaries → 404. The
+  // `agent-latest` release is maintained by .github/workflows/agent-release.yml
+  // as a moving tag that always points at the newest signed mac/windows
+  // binaries (+ checksums, install scripts, minisign pubkey).
+  app.get("/agent/latest/:asset", async (c) => {
+    const asset = c.req.param("asset");
+    if (!ASSET_NAME.test(asset)) {
+      throw new HTTPException(400, { message: "invalid asset name" });
+    }
+    return serveAsset(asset, `${releasesBase}/download/agent-latest/${asset}`);
+  });
+
+  // The version segment is the literal `v<ver>` (e.g. `v1.2.3`) — Hono cannot bind
+  // a param glued to a literal prefix, so the whole segment is the param and the
+  // `v` prefix is validated/stripped here. The release tag is `agent-v<ver>`.
+  app.get("/agent/:versionSeg/:asset", async (c) => {
+    const versionSeg = c.req.param("versionSeg");
+    const asset = c.req.param("asset");
+    // `/agent/latest/<asset>` is handled by the more specific route above; any
+    // other version segment must be the `v<ver>` shape.
+    if (!VERSION_SEG.test(versionSeg) || !ASSET_NAME.test(asset)) {
+      throw new HTTPException(400, { message: "invalid version or asset name" });
+    }
+    return serveAsset(asset, `${releasesBase}/download/agent-${versionSeg}/${asset}`);
+  });
+}
+
+// The path prefixes/exact paths the install routes own — exported so the auth
+// middleware can exempt them (they must be reachable with no credentials).
+export const installExactPaths: ReadonlySet<string> = new Set(Object.keys(TEXT_ASSETS));
+
+export function isInstallRedirectPath(path: string): boolean {
+  return path.startsWith("/agent/latest/") || path.startsWith("/agent/v");
+}

package/src/routes/machines.ts

@@ -0,0 +1,107 @@
+// apps/api/src/routes/machines.ts — the M10 Machines-dashboard + per-machine
+// metrics-series ROUTES (dossier §10.7). 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.
+//
+//   GET /v1/workspaces/:ws/machines[?sessionId=...]  -> MachinesResponse
+//     The dashboard list: the workspace's enrolled selfhosted machines (state +
+//     latest metrics + sharedSessionCount) and, when sessionId is supplied, the
+//     session's synthetic Modal group box + the active-sandbox pointer.
+//
+//   GET /v1/workspaces/:ws/machines/:enrollmentId/metrics/series?window=1h
+//     -> { samples: MetricSample[] }
+//     The downsampled (~1/min) history for ONE machine over a time window.
+
+import {
+  MachineMetricsSeriesResponse,
+  MachinesResponse,
+  SwapActiveSandboxRequest,
+  SwapActiveSandboxResponse,
+} from "@opengeni/contracts";
+import {
+  getEnrollment,
+  readMachineMetricsSeries,
+} from "@opengeni/db";
+import type { Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+import { requireAccessGrant } from "@opengeni/core";
+import type { ApiRouteDeps } from "@opengeni/core";
+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
+// scan; longer ranges are a later concern (retention is ~N days).
+const SERIES_WINDOWS_MS: Record<string, number> = {
+  "15m": 15 * 60_000,
+  "1h": 60 * 60_000,
+  "6h": 6 * 60 * 60_000,
+  "24h": 24 * 60 * 60_000,
+};
+const DEFAULT_SERIES_WINDOW_MS = SERIES_WINDOWS_MS["1h"]!;
+
+export function registerMachineRoutes(app: Hono, deps: ApiRouteDeps): void {
+  const { settings, db, bus } = deps;
+
+  // The whole surface is behind sandboxSelfhostedEnabled. A 404 (not 403) keeps it
+  // invisible while disabled — it does not exist for this deployment yet.
+  function assertSelfhostedEnabled(): void {
+    if (!settings.sandboxSelfhostedEnabled) {
+      throw new HTTPException(404, { message: "selfhosted machines are not enabled for this deployment" });
+    }
+  }
+
+  // ── GET /workspaces/:ws/machines (the dashboard list) ───────────────────────
+  app.get("/v1/workspaces/:workspaceId/machines", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "enrollments:read");
+    assertSelfhostedEnabled();
+    // sessionId is OPTIONAL: present → an in-session view (synthetic group box +
+    // active pointer); absent → the pure workspace dashboard.
+    const sessionId = c.req.query("sessionId") ?? null;
+    const response = await listMachines({ db, settings, bus }, { workspaceId, sessionId });
+    return c.json(MachinesResponse.parse(response));
+  });
+
+  // ── GET /workspaces/:ws/machines/:enrollmentId/metrics/series ───────────────
+  app.get("/v1/workspaces/:workspaceId/machines/:enrollmentId/metrics/series", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "enrollments:read");
+    assertSelfhostedEnabled();
+    const enrollmentId = c.req.param("enrollmentId");
+    // Validate the machine belongs to this workspace (RLS already scopes the read,
+    // but a clear 404 beats an empty series for an unknown/cross-workspace id).
+    const enrollment = await getEnrollment(db, workspaceId, enrollmentId);
+    if (!enrollment) {
+      throw new HTTPException(404, { message: "machine not found in this workspace" });
+    }
+    const windowMs = SERIES_WINDOWS_MS[c.req.query("window") ?? ""] ?? DEFAULT_SERIES_WINDOW_MS;
+    const since = new Date(Date.now() - windowMs);
+    const rows = await readMachineMetricsSeries(db, { workspaceId, enrollmentId, since });
+    return c.json(MachineMetricsSeriesResponse.parse({
+      samples: rows.map(metricRowToSample),
+    }));
+  });
+
+  // ── POST /workspaces/:ws/sessions/:sessionId/active-sandbox (swap) ───────────
+  // The user-authenticated equivalent of the M7 `sandbox_swap` MCP tool: repoint
+  // a session's active sandbox under the epoch fence. Same perm as PATCH session
+  // (sessions:control); gated behind sandboxSelfhostedEnabled (404 when off, the
+  // surface is invisible). All ownership/liveness/epoch validation lives inside
+  // swapActiveSandbox — the route only builds the session-scoped FleetContext.
+  app.post("/v1/workspaces/:workspaceId/sessions/:sessionId/active-sandbox", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "sessions:control");
+    assertSelfhostedEnabled();
+    const sessionId = c.req.param("sessionId");
+    const body = SwapActiveSandboxRequest.parse(await c.req.json());
+    const ctx = await buildFleetContextForSession(deps, {
+      accountId: grant.accountId,
+      workspaceId,
+      sessionId,
+    });
+    const result = await swapActiveSandbox({ db, settings, bus }, ctx, body.target);
+    return c.json(SwapActiveSandboxResponse.parse(result));
+  });
+}