@opengeni/api-router 0.5.6 → 0.7.3

package/src/routes/workspace-capture.ts

@@ -1,4 +1,4 @@
-// Workbench v2 — capture READ serving (dossier §10.3).
+// Workbench v2 — capture READ serving.
 //
 // The two GET capture routes in `sessions.ts` are thin: grant-first (files:read),
 // load the row (DB, RLS-scoped), then delegate the response SHAPING to the two
@@ -46,13 +46,24 @@ function signedUrl(signed: { url: string; expiresAt: Date }): { url: string; exp
 // manifest key, the blob is gone (GC'd), or the bytes fail to parse/validate — a
 // malformed capture is treated as "no capture available" (the list route degrades
 // to {available:false}, the file route to 404). Capture reads must NEVER be worse
-// than the status-quo live/wake fallback (dossier §10.10), so a poison row can
+// than the status-quo live/wake fallback, so a poison row can
 // never 500 the workbench; it degrades and logs.
 async function loadManifest(
   row: WorkspaceCaptureRow,
   storage: CaptureStoragePort,
-): Promise<{ manifest: WorkspaceCaptureManifest; byteLength: number } | null> {
+): Promise<{
+  manifest: WorkspaceCaptureManifest;
+  byteLength: number;
+  stats: WorkspaceCaptureStats;
+} | null> {
   if (!row.manifestKey) return null;
+  const stats = WorkspaceCaptureStats.safeParse(row.stats);
+  if (!stats.success) {
+    console.warn(
+      `workspace capture read — row stats failed schema validation (session=${row.sessionId} rev=${row.revision})`,
+    );
+    return null;
+  }
   const blob = await storage.getObjectBytes(row.manifestKey);
   if (!blob) return null;
   let json: unknown;
@@ -71,7 +82,39 @@ async function loadManifest(
     );
     return null;
   }
-  return { manifest: parsed.data, byteLength: blob.bytes.byteLength };
+  const manifest = parsed.data;
+  const servedStats = stats.data;
+  const statsMatch =
+    manifest.stats.repoCount === servedStats.repoCount &&
+    manifest.stats.fileCount === servedStats.fileCount &&
+    manifest.stats.additions === servedStats.additions &&
+    manifest.stats.deletions === servedStats.deletions &&
+    manifest.stats.totalBytes === servedStats.totalBytes &&
+    manifest.stats.tooLargeCount === servedStats.tooLargeCount &&
+    manifest.stats.binaryCount === servedStats.binaryCount &&
+    manifest.stats.treeEntryCount === servedStats.treeEntryCount &&
+    manifest.stats.treeTruncated === servedStats.treeTruncated &&
+    manifest.stats.durationMs === servedStats.durationMs &&
+    (manifest.stats.fingerprint ?? null) === (servedStats.fingerprint ?? null);
+  if (
+    manifest.revision !== row.revision ||
+    manifest.capturedAt !== row.capturedAt ||
+    manifest.turnId !== row.turnId ||
+    manifest.leaseEpoch !== row.leaseEpoch ||
+    !statsMatch ||
+    manifest.repos.length !== manifest.stats.repoCount ||
+    manifest.files.length !== manifest.stats.fileCount ||
+    manifest.treeTruncated !== manifest.stats.treeTruncated
+  ) {
+    // A valid blob under the wrong row/key is still poison: row metadata drives
+    // cache identity and revision pinning in the client. Never combine two
+    // different captures into one apparently authoritative response.
+    console.warn(
+      `workspace capture read — manifest identity did not match row (session=${row.sessionId} rev=${row.revision})`,
+    );
+    return null;
+  }
+  return { manifest, byteLength: blob.bytes.byteLength, stats: servedStats };
 }
 
 /**
@@ -105,15 +148,12 @@ export async function serveWorkspaceCapture(
     });
   }
   if (row.state !== "available" || !row.manifestKey) return { available: false };
-  const stats = WorkspaceCaptureStats.safeParse(row.stats);
-  if (!stats.success) {
-    // A row with malformed stats (or a synthetic/partial row) degrades to the
-    // cold-fallback state rather than 500.
-    console.warn(
-      `workspace capture read — row stats failed schema validation (session=${row.sessionId} rev=${row.revision})`,
-    );
-    return { available: false };
-  }
+  // Validate every manifest before serving it, including the rare >2MB signed
+  // path. Previously that branch signed arbitrary bytes merely because they
+  // exceeded the inline cap, allowing a poison/mis-keyed blob to bypass both the
+  // schema and row-identity checks.
+  const loaded = await loadManifest(row, storage);
+  if (!loaded) return { available: false };
   const meta = {
     available: true as const,
     revision: row.revision,
@@ -121,34 +161,12 @@ export async function serveWorkspaceCapture(
     turnId: row.turnId,
     leaseEpoch: row.leaseEpoch,
     sizeBytes: row.sizeBytes ?? 0,
-    stats: stats.data,
+    stats: loaded.stats,
   };
-  const blob = await storage.getObjectBytes(row.manifestKey);
-  if (!blob) {
-    // Manifest raced GC between the row read and the blob fetch — degrade to the
-    // cold-fallback state rather than 500.
-    return { available: false };
-  }
-  if (blob.bytes.byteLength <= CAPTURE_INLINE_MANIFEST_MAX_BYTES) {
-    let json: unknown;
-    try {
-      json = JSON.parse(new TextDecoder().decode(blob.bytes));
-    } catch {
-      console.warn(
-        `workspace capture read — manifest blob is not valid JSON (session=${row.sessionId} rev=${row.revision})`,
-      );
-      return { available: false };
-    }
-    const manifest = WorkspaceCaptureManifest.safeParse(json);
-    if (!manifest.success) {
-      console.warn(
-        `workspace capture read — manifest failed schema validation (session=${row.sessionId} rev=${row.revision})`,
-      );
-      return { available: false };
-    }
+  if (loaded.byteLength <= CAPTURE_INLINE_MANIFEST_MAX_BYTES) {
     return GetWorkspaceCaptureResponse.parse({
       ...meta,
-      manifest: manifest.data,
+      manifest: loaded.manifest,
       manifestUrl: null,
     });
   }

package/src/routes/workspaces.ts

@@ -7,9 +7,11 @@ import {
   UpdateWorkspaceModelPolicyRequest,
   UpdateWorkspaceRequest,
   UpdateWorkspaceSettingsRequest,
+  WORKSPACE_CONTROL_ACTOR_MAX_BYTES,
   WorkspaceInferenceControlRequest,
   Workspace,
   WorkspaceMember,
+  workspaceControlUtf8Bytes,
   type AccessContext,
   type Permission,
 } from "@opengeni/contracts";
@@ -34,6 +36,7 @@ import {
   updateWorkspaceSettings,
   upsertWorkspaceModelPolicy,
 } from "@opengeni/db";
+import { boundWorkspaceControlHttpPage } from "@opengeni/events";
 import type { Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
 import { hasPermission, requireAccessContext, requireAccessGrant } from "@opengeni/core";
@@ -171,12 +174,18 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
   app.post("/v1/workspaces/:workspaceId/inference-control", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
-    const payload = WorkspaceInferenceControlRequest.parse(await c.req.json());
+    if (workspaceControlUtf8Bytes(grant.subjectId) > WORKSPACE_CONTROL_ACTOR_MAX_BYTES) {
+      throw new HTTPException(400, { message: "workspace-control actor is too large" });
+    }
+    const parsed = WorkspaceInferenceControlRequest.safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) {
+      throw new HTTPException(400, { message: "invalid workspace inference-control request" });
+    }
     return c.json(
       await controlHumanWorkspace(
         { db: deps.db, bus: deps.bus, workflowClient: deps.workflowClient },
         { accountId: grant.accountId, workspaceId, subjectId: grant.subjectId },
-        payload,
+        parsed.data,
       ),
     );
   });
@@ -185,21 +194,31 @@ export function registerWorkspaceRoutes(app: Hono, deps: ApiRouteDeps): void {
     const workspaceId = c.req.param("workspaceId");
     await requireAccessGrant(c, deps, workspaceId, "workspace:read");
     const after = Math.max(0, Number.parseInt(c.req.query("after") ?? "0", 10) || 0);
-    return c.json(
-      await listWorkspaceControlEvents(
-        deps.db,
-        workspaceId,
-        after,
-        boundedLimit(c.req.query("limit")),
-      ),
-    );
+    const limit = boundedLimit(c.req.query("limit"));
+    const fetched = await listWorkspaceControlEvents(deps.db, workspaceId, after, limit + 1);
+    const countHasMore = fetched.length > limit;
+    const page = boundWorkspaceControlHttpPage(fetched.slice(0, limit));
+    const truncated = countHasMore || page.truncated;
+    c.header("X-OpenGeni-Page-Bytes", String(page.bytes));
+    c.header("X-OpenGeni-Page-Truncated", String(truncated));
+    if (page.nextSequence !== null) {
+      c.header("X-OpenGeni-Next-After", String(page.nextSequence));
+    }
+    return c.json(page.events);
   });
 
   app.get("/v1/workspaces/:workspaceId/control-events/stream", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     await requireAccessGrant(c, deps, workspaceId, "workspace:read");
     const after = Math.max(0, Number.parseInt(c.req.query("after") ?? "0", 10) || 0);
-    return await sseWorkspaceControlStream(deps.db, deps.bus, workspaceId, after, c.req.raw.signal);
+    return await sseWorkspaceControlStream(
+      deps.db,
+      deps.bus,
+      workspaceId,
+      after,
+      c.req.raw.signal,
+      { observability: deps.observability },
+    );
   });
 
   app.put("/v1/workspaces/:workspaceId/default-rig", async (c) => {

package/src/sandbox/access.ts

@@ -1,7 +1,7 @@
 // apps/api/src/sandbox/access.ts — the API-tier sandbox access seam.
 //
 // This is the foundation of the API-DIRECT control plane
-// (docs/design/sandbox-surfacing): the apps/api process constructs its OWN
+// (docs/connected-machines.md): the apps/api process constructs its OWN
 // sandbox client and resumes boxes by id IN-PROCESS, so non-turn ops (viewer
 // attach, FS/git reads, tunnel URL mint) never touch Temporal or a worker.
 //

package/src/sandbox/auth-callout.ts

@@ -1,5 +1,5 @@
 // apps/api/src/sandbox/auth-callout.ts — the NATS AUTH-CALLOUT responder (the
-// bring-your-own-compute M-AUTH tenancy boundary; dossier §10.1 NATS Accounts per
+// bring-your-own-compute M-AUTH tenancy boundary; NATS Accounts per
 // workspace + §17 the isolation smoke + §19 the NATS-Accounts-misconfig leak risk).
 //
 // THE BOUNDARY THIS CLOSES: an external agent connects to NATS presenting its

package/src/sandbox/channel-a.ts

@@ -50,7 +50,11 @@ import {
   ChannelAConflictError,
   ChannelANotFoundError,
   ChannelAUnsupportedError,
+  ChannelAUnavailableError,
   ChannelAValidationError,
+  toolspaceTokenFileFromEnvironment,
+  withToolspaceTokenSession,
+  withRunCredentialsSession,
   type ChannelASession,
   type EstablishedSandboxSession,
 } from "@opengeni/runtime/sandbox";
@@ -293,9 +297,16 @@ export async function withChannelA<T>(
           established,
         ).session
       : established.session;
+    const credentialSession = withRunCredentialsSession(routedSession as object, session.id);
+    const scopedSession = environment.OPENGENI_TOOLSPACE_TOKEN_FILE
+      ? withToolspaceTokenSession(
+          credentialSession,
+          toolspaceTokenFileFromEnvironment(environment, session.id),
+        )
+      : credentialSession;
 
     const service = new SandboxChannelAService({
-      session: routedSession as ChannelASession,
+      session: scopedSession as ChannelASession,
       leaseEpoch: leaseSnapshot.leaseEpoch,
       emit,
     });
@@ -313,6 +324,8 @@ export async function withChannelA<T>(
  *  already-HTTPException unchanged. */
 export function mapChannelAError(error: unknown): unknown {
   if (error instanceof HTTPException) return error;
+  if (error instanceof ChannelAUnavailableError)
+    return new HTTPException(503, { message: error.message });
   if (error instanceof ChannelAValidationError)
     return new HTTPException(400, { message: error.message });
   if (error instanceof ChannelANotFoundError)

package/src/sandbox/enrollment.ts

@@ -1,5 +1,5 @@
 // apps/api/src/sandbox/enrollment.ts — the API-DIRECT enrollment device-flow seam
-// (M5 of the bring-your-own-compute mega-PR; dossier §10.2 enrollment + §18 LOUD
+// (M5 of the bring-your-own-compute mega-PR; enrollment + §18 LOUD
 // consent). This is the service layer the routes (routes/enrollments.ts) call — it
 // mirrors the channel-a.ts / viewer.ts split (a thin route over a focused service).
 //
@@ -20,7 +20,7 @@
 //      placeholder for the per-workspace NATS Account creds [infra-deferred]);
 //      denied/expired/disabled → the typed state.
 //
-// SECURITY (dossier §18): device_code/user_code are CSPRNG-unguessable + short-TTL +
+// SECURITY: device_code/user_code are CSPRNG-unguessable + short-TTL +
 // single-use; approve is strictly workspace-gated (the route asserts the grant); the
 // signing secret value is NEVER logged. Rate-limiting of start/poll is enforced at
 // the route. The consent record (who/when/what) lives on the request row.
@@ -78,7 +78,7 @@ export const DEVICE_POLL_INTERVAL_SECONDS = 5;
 // enrollment status on every (re)connect (auth-callout.ts) — a revoked machine is
 // denied regardless of bearer life — exactly as the long-lived relay token relies on.
 export const ENROLLMENT_BEARER_TTL_SECONDS = 30 * 24 * 3600;
-// The relay PRODUCER token (the `ogr_` token; M8b/dossier §10.5) is ENROLLMENT-scoped,
+// The relay PRODUCER token (the `ogr_` token; M8b) is ENROLLMENT-scoped,
 // NOT per-stream: the agent presents it on every channel registration for the life
 // of its run, and the producer side has no per-viewer epoch fence (that is the
 // VIEWER's `ogs_` token's job). So it is long-lived — 30 days — re-minted on every
@@ -492,7 +492,7 @@ async function buildEnrollmentCredentials(
     // Hand the agent the canonical `/stream` dial base, NOT the raw configured URL.
     // The agent's relay producer appends only its routing query and assumes the base
     // already carries the relay's `/stream` route; a path-less base 400s the dial and
-    // makes the terminal/desktop streams unreachable (dossier §V5/§V6).
+    // makes the terminal/desktop streams unreachable.
     relayUrl: relayDialBaseFromSettings(settings),
     relayToken,
     // M-AUTH closes the placeholder: there is NO per-machine NATS Account creds

package/src/sandbox/machines.ts

@@ -1,4 +1,4 @@
-// apps/api/src/sandbox/machines.ts — the M10 Machines-DASHBOARD service (dossier
+// apps/api/src/sandbox/machines.ts — the M10 Machines-DASHBOARD service (design
 // §10.7). Builds the `MachinesResponse` the dashboard renders: the workspace's
 // enrolled selfhosted machines, each enriched with
 //   * STATE — the M3 liveness (online/reconnecting/offline) overlaid with the

package/src/sandbox/metrics-ingestion.ts

@@ -1,5 +1,5 @@
 // apps/api/src/sandbox/metrics-ingestion.ts — the M10 metrics INGESTION consumer
-// (dossier §10.7 + §10.6) + the connect-Hello DISPLAY-REFRESH consumer. The
+// + the connect-Hello DISPLAY-REFRESH consumer. The
 // enrolled agent piggybacks a `MetricsSample` on its ~5s heartbeat (an
 // `AgentEvent` published one-way on `agent.<ws>.<id>.events`) and publishes a
 // `Hello` (its live self-description) on `agent.<ws>.<id>.hello` on every connect

package/src/sandbox/viewer.ts

@@ -141,7 +141,7 @@ export async function sessionAttachEnvironment(
   // the same env from runSettings.sandboxBackend = the session's backend. An
   // attach env keyed off the deployment default would cold-create e.g. an e2b
   // session's box with /workspace-rooted values while its turn declares
-  // /home/user-rooted ones — the same guard-killed first turn all over again.
+  // /home/user ones — the same guard-killed first turn all over again.
   const settingsForSession =
     session.sandboxBackend !== services.settings.sandboxBackend
       ? { ...services.settings, sandboxBackend: session.sandboxBackend }