@opengeni/api-router 0.30.3 → 2.2.0-canary.0

package/src/sandbox/viewer.ts

@@ -33,6 +33,7 @@ import { githubAppBotIdentity } from "@opengeni/github";
 import { type Session, type StreamUrlRotatedPayload } from "@opengeni/contracts";
 import {
   acquireLease,
+  getLiveEnrollmentConnection,
   getSandbox,
   getSandboxSessionEnvelope,
   heartbeatLeaseHolder,
@@ -48,6 +49,8 @@ import {
   type Database,
   type LeaseSnapshot,
   type SandboxRecord,
+  getSessionAuthorityEpoch,
+  namedSubjectHasLiveWorkspaceAuthority,
 } from "@opengeni/db";
 import { appendAndPublishEvents, type EventBus } from "@opengeni/events";
 import { HTTPException } from "hono/http-exception";
@@ -71,11 +74,16 @@ import {
   TerminalServerUnsupportedError,
   verifySandboxExecReadiness,
   StreamPortUnavailableError,
+  renewSandboxProviderExpiration,
   type ControlRpc,
   type EstablishedSandboxSession,
   type NatsRequestConnection,
 } from "@opengeni/runtime/sandbox";
-import { relayConfigFromSettings } from "@opengeni/core";
+import {
+  providerSettingsForSessionSandboxRuntime,
+  relayConfigFromSettings,
+  resolveSessionSandboxRuntime,
+} from "@opengeni/core";
 import { establishApiSandboxSpawner } from "./rematerialize";
 import { establishCachedChannelAHandle } from "./channel-a";
 
@@ -137,12 +145,19 @@ export async function sessionAttachEnvironment(
   services: ViewerServices,
   workspaceId: string,
   session: Session,
+  /** The authenticated route subject driving this attach (0282); recorded on
+   *  the materialization audit fact. Null records the legacy service sentinel. */
+  attachSubjectId: string | null,
 ): Promise<Record<string, string>> {
   const workspaceEnvironment = await loadWorkspaceEnvironmentForRun(
     services.db,
     services.settings,
-    workspaceId,
-    session.environmentId,
+    {
+      accountId: session.accountId,
+      workspaceId,
+      variableSetId: session.environmentId,
+      authority: { kind: "session_attach", sessionId: session.id, subjectId: attachSubjectId },
+    },
   );
   // Build the env with the SESSION's backend, not the deployment default: the
   // stable base is backend-aware (HOME = the descriptor workspaceRoot, and the
@@ -187,6 +202,9 @@ export async function attachViewer(
     workspaceId: string;
     session: Session;
     viewerId?: string;
+    /** The authenticated subject attaching this viewer (0281): recorded on
+     *  the holder row together with the live session authority epoch. */
+    viewerSubjectId?: string;
     /** Cancel lifecycle waiting when the originating HTTP request disconnects. */
     waitSignal?: AbortSignal;
   },
@@ -194,8 +212,13 @@ export async function attachViewer(
   const { db, settings } = services;
   const { accountId, workspaceId, session } = input;
   const viewerId = input.viewerId ?? crypto.randomUUID();
+  const attachSubjectId = claimableSubjectId(input.viewerSubjectId ?? null);
+  const attachAuthorityEpoch = attachSubjectId
+    ? await getSessionAuthorityEpoch(db, { accountId, workspaceId, sessionId: session.id })
+    : null;
   const leaseTtlMs = settings.sandboxLeaseTtlMs;
   const sandboxGroupId = session.sandboxGroupId;
+  const sandboxRuntime = await resolveSessionSandboxRuntime(db, settings, session);
 
   const release = async (): Promise<void> => {
     await releaseLeaseHolder(db, {
@@ -217,8 +240,12 @@ export async function attachViewer(
       kind: "viewer",
       holderId: viewerId,
       subjectId: session.id,
+      ...(attachSubjectId ? { viewerSubjectId: attachSubjectId } : {}),
+      ...(attachAuthorityEpoch !== null ? { viewerAuthorityEpoch: attachAuthorityEpoch } : {}),
       backend: session.sandboxBackend,
       os: session.sandboxOs,
+      image: sandboxRuntime.image,
+      rigVersionId: session.rigVersionId,
       leaseTtlMs,
       warmingLeaseTtlMs: settings.sandboxWarmingTimeoutMs,
       captureWaitMs: sandboxLifecycleTransitionWaitMs(settings),
@@ -270,7 +297,16 @@ export async function attachViewer(
       // so the next turn's agent-manifest apply finds an EMPTY environment delta in
       // the SDK's validateNoEnvironmentDelta (otherwise: "Live sandbox sessions
       // cannot change manifest environment variables").
-      const environment = await sessionAttachEnvironment(services, workspaceId, session);
+      const environment = await sessionAttachEnvironment(
+        services,
+        workspaceId,
+        session,
+        input.viewerSubjectId ?? null,
+      );
+      const providerSettings = await providerSettingsForSessionSandboxRuntime(
+        sandboxRuntime,
+        session.sandboxBackend,
+      );
       // Prefer the COLD lease's preserved resume_state when it carries a persisted
       // /workspace snapshot (confirmDrainCold keeps a minimal archive-only envelope
       // across draining->cold). establishSandboxSessionFromEnvelope cold-creates a
@@ -279,7 +315,7 @@ export async function attachViewer(
       // session envelope (a never-warmed cold start).
       const result = await establishApiSandboxSpawner({
         db,
-        settings,
+        settings: providerSettings,
         accountId,
         workspaceId,
         sandboxGroupId,
@@ -353,11 +389,16 @@ export async function attachViewer(
         message: `sandbox is ${live.recovery.restore.status} at epoch ${live.leaseEpoch}`,
       });
     }
-    const environment = await sessionAttachEnvironment(services, workspaceId, session);
+    const environment = await sessionAttachEnvironment(
+      services,
+      workspaceId,
+      session,
+      input.viewerSubjectId ?? null,
+    );
     let observed: EstablishedSandboxSession | undefined;
     try {
       const establish = services.establishSandboxSession ?? establishSandboxSessionFromEnvelope;
-      observed = await establish(settings, live.resumeState, {
+      observed = await establish(sandboxRuntime.settings, live.resumeState, {
         sessionId: session.id,
         recovery: "resume-only",
         backendOverride: session.sandboxBackend,
@@ -430,13 +471,26 @@ export type SessionGroupReadinessHold = {
  * it. */
 export async function ensureSessionGroupReady(
   services: ViewerServices,
-  input: { accountId: string; workspaceId: string; session: Session },
+  input: {
+    accountId: string;
+    workspaceId: string;
+    session: Session;
+    /** The authenticated subject driving the fleet attach/swap (0282): recorded
+     *  on the viewer holder and the materialization audit fact. Omitting it
+     *  records the explicit service sentinel, so forward the route subject. */
+    subjectId?: string | null;
+  },
 ): Promise<SessionGroupReadinessHold> {
   let lastError: unknown;
   for (let attempt = 0; attempt < 2; attempt += 1) {
     let release: (() => Promise<void>) | undefined;
     try {
-      const attached = await attachViewer(services, input);
+      const attached = await attachViewer(services, {
+        accountId: input.accountId,
+        workspaceId: input.workspaceId,
+        session: input.session,
+        ...(input.subjectId ? { viewerSubjectId: input.subjectId } : {}),
+      });
       let releasePromise: Promise<void> | undefined;
       release = () =>
         (releasePromise ??= detachViewer(services, {
@@ -480,7 +534,7 @@ export async function heartbeatViewer(
     expectedEpoch: number;
   },
 ): Promise<boolean> {
-  return await heartbeatLeaseHolder(services.db, {
+  const alive = await heartbeatLeaseHolder(services.db, {
     accountId: input.accountId,
     workspaceId: input.workspaceId,
     sandboxGroupId: input.sandboxGroupId,
@@ -489,6 +543,16 @@ export async function heartbeatViewer(
     leaseTtlMs: services.settings.sandboxLeaseTtlMs,
     expectedEpoch: input.expectedEpoch,
   });
+  if (!alive) return false;
+  const lease = await readLease(services.db, input.workspaceId, input.sandboxGroupId);
+  if (lease?.liveness === "warm" && lease.leaseEpoch === input.expectedEpoch && lease.instanceId) {
+    await renewSandboxProviderExpiration({
+      backend: lease.backend as Settings["sandboxBackend"],
+      settings: services.settings,
+      instanceId: lease.instanceId,
+    }).catch(() => false);
+  }
+  return true;
 }
 
 /**
@@ -498,7 +562,12 @@ export async function heartbeatViewer(
  */
 export async function detachViewer(
   services: ViewerServices,
-  input: { accountId: string; workspaceId: string; sandboxGroupId: string; viewerId: string },
+  input: {
+    accountId: string;
+    workspaceId: string;
+    sandboxGroupId: string;
+    viewerId: string;
+  },
 ): Promise<{ liveness: LeaseSnapshot["liveness"]; refcount: number } | null> {
   return await releaseLeaseHolder(services.db, {
     accountId: input.accountId,
@@ -625,7 +694,11 @@ export function resolveActiveDesktopTransport(
   if (selfhostedActive) {
     return { transport: "relay-frames", client: "frames", mode: "read-only" };
   }
-  return { transport: "vnc-ws", client: "novnc", mode: interactive ? "interactive" : "read-only" };
+  return {
+    transport: "vnc-ws",
+    client: "novnc",
+    mode: interactive ? "interactive" : "read-only",
+  };
 }
 
 /** The minted pixel cell the handshake/attach folds into the DesktopStream
@@ -639,9 +712,73 @@ export type DesktopStreamMint = {
   leaseEpoch: number;
 };
 
+/** A subject claim must satisfy the StreamTokenPayload bounds and the 0281
+ *  holder CHECK (non-blank, <= 512). An out-of-bounds subject (possible only
+ *  from a host-signed delegated token) is omitted from the claims rather than
+ *  turning the mint into a 500. */
+function claimableSubjectId(subjectId: string | null): string | null {
+  if (!subjectId) return null;
+  const trimmed = subjectId.trim();
+  return trimmed.length >= 1 && subjectId.length <= 512 ? subjectId : null;
+}
+
+/**
+ * Resolve the viewer-facing authority claims stamped into a scoped stream
+ * token and recorded on the viewer holder (0281): the authenticated viewer
+ * subject and the session's LIVE authority epoch. Re-verifies a human
+ * (`user:`) subject's current workspace authority at mint time through the
+ * same model the route-time access builder uses - a membership row with an
+ * active owning organization membership, or an active organization
+ * membership's personal-workspace pointer - so a viewer whose authority was
+ * revoked since the route authorized them degrades to null (transport:null)
+ * instead of receiving a fresh token. Delegated token-borne grants
+ * (`subjectDelegated`) are authorized by their signed token, not by rows this
+ * check can see; they keep their route authorization, as do API-key and
+ * service principals. Identity and epoch only - never a secret value.
+ */
+async function resolveViewerAuthorityClaims(
+  db: ViewerServices["db"],
+  input: {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    subjectId: string | null;
+    subjectDelegated?: boolean;
+  },
+): Promise<{ subjectId?: string; authorityEpoch: number } | null> {
+  const authorityEpoch = await getSessionAuthorityEpoch(db, {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    sessionId: input.sessionId,
+  });
+  if (authorityEpoch === null) {
+    return null;
+  }
+  if (input.subjectId?.startsWith("user:") && input.subjectDelegated !== true) {
+    const live = await namedSubjectHasLiveWorkspaceAuthority(db, {
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
+      subjectId: input.subjectId,
+    });
+    if (!live) {
+      return null;
+    }
+  }
+  const subjectId = claimableSubjectId(input.subjectId);
+  return {
+    ...(subjectId ? { subjectId } : {}),
+    authorityEpoch,
+  };
+}
+
 export type MintDesktopStreamInput = {
   accountId: string;
   workspaceId: string;
+  resourceSubjectId?: string;
+  /** True when the route grant is a signed delegated token (metadata.delegated):
+   *  its authority is the token, not membership rows, so the mint-time
+   *  live-authority recheck does not apply. */
+  resourceSubjectDelegated?: boolean;
   session: Session;
   /** The viewer holder id the scoped token is minted for. */
   viewerId: string;
@@ -704,20 +841,44 @@ export async function mintDesktopStream(
     return null;
   }
 
+  // 0281: the viewer's authority claims. A missing epoch (session not
+  // visible) or a removed human membership degrades the mint instead of
+  // issuing a fresh token.
+  const viewerAuthority = await resolveViewerAuthorityClaims(db, {
+    accountId,
+    workspaceId,
+    sessionId: session.id,
+    subjectId: input.resourceSubjectId ?? null,
+    ...(input.resourceSubjectDelegated !== undefined
+      ? { subjectDelegated: input.resourceSubjectDelegated }
+      : {}),
+  });
+  if (!viewerAuthority) {
+    return null;
+  }
+
   // SELFHOSTED ACTIVE: when the session's active sandbox is a selfhosted machine,
   // route to the relay (NOT the Modal group-box path — it would resume the wrong
   // box and return a Modal URL). No Modal lease required.
   if (session.activeSandboxId) {
-    const active = await getSandbox(db, workspaceId, session.activeSandboxId);
+    const active = await getSandbox(
+      db,
+      input.resourceSubjectId
+        ? { accountId, workspaceId, subjectId: input.resourceSubjectId }
+        : workspaceId,
+      session.activeSandboxId,
+    );
     if (active?.kind === "selfhosted") {
       const m = await tryMintActiveSelfhostedStream(
         services,
         {
           session,
           viewerId: input.viewerId,
-          workspaceId,
+          workspaceId: active.workspaceId,
+          ...(input.resourceSubjectId ? { resourceSubjectId: input.resourceSubjectId } : {}),
           port: DESKTOP_STREAM_PORT,
           sandbox: active,
+          viewerAuthority,
         },
         input.resolveSelfhostedSession,
       );
@@ -749,7 +910,12 @@ export async function mintDesktopStream(
   try {
     // On a cold-restore (the lease's box is gone) this create() must carry the
     // SAME stable run-env the turn declares, so a later turn finds no env delta.
-    const environment = await sessionAttachEnvironment(services, workspaceId, session);
+    const environment = await sessionAttachEnvironment(
+      services,
+      workspaceId,
+      session,
+      input.resourceSubjectId ?? null,
+    );
     try {
       const establish = () =>
         (services.establishSandboxSession ?? establishSandboxSessionFromEnvelope)(
@@ -799,6 +965,7 @@ export async function mintDesktopStream(
         leaseEpoch: lease.leaseEpoch,
         streamTokenSecret: secret,
         resolution: defaultResolution(settings),
+        ...viewerAuthority,
       });
     } catch (error) {
       // A transient/headless provider failure degrades the desktop cell.
@@ -899,6 +1066,9 @@ type SelfhostedStreamMint = Omit<TerminalStreamMint, "transport">;
 export type MintTerminalStreamInput = {
   accountId: string;
   workspaceId: string;
+  resourceSubjectId?: string;
+  /** See MintDesktopStreamInput.resourceSubjectDelegated. */
+  resourceSubjectDelegated?: boolean;
   session: Session;
   /** The viewer holder / principal id the scoped token is minted for. */
   viewerId: string;
@@ -947,20 +1117,44 @@ export async function mintTerminalStream(
     return null;
   }
 
+  // 0281: the viewer's authority claims. A missing epoch (session not
+  // visible) or a removed human membership degrades the mint instead of
+  // issuing a fresh token.
+  const viewerAuthority = await resolveViewerAuthorityClaims(db, {
+    accountId,
+    workspaceId,
+    sessionId: session.id,
+    subjectId: input.resourceSubjectId ?? null,
+    ...(input.resourceSubjectDelegated !== undefined
+      ? { subjectDelegated: input.resourceSubjectDelegated }
+      : {}),
+  });
+  if (!viewerAuthority) {
+    return null;
+  }
+
   // SELFHOSTED ACTIVE: when the session's active sandbox is a selfhosted machine,
   // route to the relay. NEVER fall through to the Modal group-box path (it would
   // resume the wrong box / return a Modal URL).
   if (session.activeSandboxId) {
-    const active = await getSandbox(db, workspaceId, session.activeSandboxId);
+    const active = await getSandbox(
+      db,
+      input.resourceSubjectId
+        ? { accountId, workspaceId, subjectId: input.resourceSubjectId }
+        : workspaceId,
+      session.activeSandboxId,
+    );
     if (active?.kind === "selfhosted") {
       const stream = await tryMintActiveSelfhostedStream(
         services,
         {
           session,
           viewerId: input.viewerId,
-          workspaceId,
+          workspaceId: active.workspaceId,
+          ...(input.resourceSubjectId ? { resourceSubjectId: input.resourceSubjectId } : {}),
           port: TERMINAL_STREAM_PORT,
           sandbox: active,
+          viewerAuthority,
         },
         input.resolveSelfhostedSession,
       );
@@ -982,7 +1176,12 @@ export async function mintTerminalStream(
   try {
     // On a cold-restore this create() must carry the SAME stable run-env the turn
     // declares, so a later turn finds no manifest-env delta.
-    const environment = await sessionAttachEnvironment(services, workspaceId, session);
+    const environment = await sessionAttachEnvironment(
+      services,
+      workspaceId,
+      session,
+      input.resourceSubjectId ?? null,
+    );
     try {
       const establish = () =>
         (services.establishSandboxSession ?? establishSandboxSessionFromEnvelope)(
@@ -1008,7 +1207,9 @@ export async function mintTerminalStream(
     // Idempotent ttyd launch (flock-guarded; a no-op when already up). A box that
     // genuinely can't run it degrades to the sse-events firehose, not a throw.
     try {
-      await ensureTerminalServer(established.session, { port: TERMINAL_STREAM_PORT });
+      await ensureTerminalServer(established.session, {
+        port: TERMINAL_STREAM_PORT,
+      });
     } catch (error) {
       if (error instanceof TerminalServerUnsupportedError) {
         return null;
@@ -1029,6 +1230,7 @@ export async function mintTerminalStream(
         leaseEpoch: lease.leaseEpoch,
         streamTokenSecret: secret,
         port: TERMINAL_STREAM_PORT,
+        ...viewerAuthority,
       });
     } catch (error) {
       if (error instanceof StreamPortUnavailableError) {
@@ -1104,8 +1306,11 @@ async function tryMintActiveSelfhostedStream(
     session: Session;
     viewerId: string;
     workspaceId: string;
+    resourceSubjectId?: string;
     port: number;
     sandbox: SandboxRecord;
+    /** 0281 viewer authority claims stamped into the relay stream token. */
+    viewerAuthority?: { subjectId?: string; authorityEpoch: number };
   },
   // optional test seam (mirrors the existing `establish?` seam pattern): inject a
   // fake relay-resolving session; production NEVER passes it.
@@ -1127,11 +1332,26 @@ async function tryMintActiveSelfhostedStream(
     if (resolveSelfhostedSession) {
       shSession = await resolveSelfhostedSession(sandbox);
     } else {
+      const enrollment = await getLiveEnrollmentConnection(
+        services.db,
+        input.resourceSubjectId
+          ? {
+              accountId: input.session.accountId,
+              workspaceId: input.session.workspaceId,
+              subjectId: input.resourceSubjectId,
+            }
+          : workspaceId,
+        sandbox.enrollmentId,
+      );
+      if (!enrollment?.connectionInstanceId) return null;
+      if (!enrollment.workspaceRoot) return null;
       const client = new SelfhostedSandboxClient({
         workspaceId,
+        workspaceRoot: enrollment.workspaceRoot,
         relay: relayConfigFromSettings(settings),
         controlRpcFactory: () => controlRpc(bus),
         agentId: sandbox.enrollmentId,
+        connectionInstanceId: enrollment.connectionInstanceId,
         epoch: session.activeEpoch,
         // Stream authority rotates; terminal process identity does not.
         terminalScopeId: session.id,
@@ -1151,6 +1371,7 @@ async function tryMintActiveSelfhostedStream(
     sessionId: session.id,
     viewerId: input.viewerId,
     activeEpoch: session.activeEpoch,
+    ...(input.viewerAuthority ? { viewerAuthority: input.viewerAuthority } : {}),
     port,
     session: shSession,
   });
@@ -1170,6 +1391,8 @@ export type MintSelfhostedStreamInput = {
    *  THIS as its leaseEpoch claim so the relay rejects a stale-epoch (swapped-away)
    *  viewer. */
   activeEpoch: number;
+  /** 0281 viewer authority claims stamped into the relay stream token. */
+  viewerAuthority?: { subjectId?: string; authorityEpoch: number };
   /** The exposed stream port (6080 desktop / 7681 terminal). */
   port: number;
   /** The resolvable selfhosted session (the routing proxy resolves the active
@@ -1213,6 +1436,7 @@ export async function mintSelfhostedStream(
       leaseEpoch: input.activeEpoch,
       streamTokenSecret: secret,
       port: input.port,
+      ...(input.viewerAuthority ?? {}),
     });
     return {
       url: exposed.url,