@opengeni/api-router 0.30.3 → 1.0.0

package/src/sandbox/enrollment.ts

@@ -28,7 +28,7 @@
 // FLAG GATE: the whole feature is behind sandboxSelfhostedEnabled (default OFF) —
 // when off the routes 404 (the surface is invisible) and boot is unaffected.
 
-import { randomBytes } from "node:crypto";
+import { createPublicKey, randomBytes, verify } from "node:crypto";
 import {
   resolveEnrollmentSigningSecret,
   resolveRelayTokenSecret,
@@ -36,10 +36,13 @@ import {
 } from "@opengeni/config";
 import {
   DeviceEnrollmentState,
+  enrollmentRenewalProof,
   signEnrollmentBearer,
   signEnrollToken,
   signRelayToken,
   verifyEnrollToken,
+  verifyEnrollmentBearer,
+  type RenewEnrollmentRequest,
   type DeviceEnrollmentLookupResponse,
   type DeviceEnrollmentPollResponse,
   type DeviceEnrollmentStartResponse,
@@ -71,7 +74,8 @@ export const DEVICE_POLL_INTERVAL_SECONDS = 5;
 // The bearer the agent presents to the NATS auth-callout. A bring-your-own-compute
 // machine is PERSISTENT (unlike an ephemeral Modal box, whose lifetime ~= an agent
 // token's hour), so this is long-lived — 30 days, matching the relay token below —
-// and re-minted on every poll/re-enroll. The old 1-hour value (sized for a Modal
+// and renewed automatically by install-key proof, or re-minted on poll/re-enroll.
+// The old 1-hour value (sized for a Modal
 // box) caused a self-hosted agent to drop PERMANENTLY one hour after connecting: the
 // bearer expired and the auth-callout rejected every reconnect ("re-enroll may be
 // required"). A long-lived bearer is safe because the auth-callout RE-CHECKS the
@@ -83,10 +87,69 @@ export const ENROLLMENT_BEARER_TTL_SECONDS = 30 * 24 * 3600;
 // 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
-// poll/re-enroll. The relay re-verifies it (authenticity + the channel-key ws+agent
+// renewal/poll/re-enroll. The relay re-verifies it (authenticity + the channel-key ws+agent
 // scope) on every StreamOpen; a revoked enrollment's machine goes offline at the
 // control plane regardless, so a long-lived relay token cannot reach a dead agent.
 export const RELAY_TOKEN_TTL_SECONDS = 30 * 24 * 3600;
+
+/** Renew an existing grant, including after a long offline interval. The expired
+ * bearer is only an authenticated enrollment/generation locator here: current
+ * install-key possession and live enrollment authority are both required. Normal
+ * NATS/relay authentication continues to reject expired transport credentials.
+ * Nothing creates/reactivates an enrollment or changes its consent or scope. */
+export async function renewEnrollmentCredentials(
+  services: EnrollmentServices,
+  input: RenewEnrollmentRequest,
+  nowSeconds = Math.floor(Date.now() / 1000),
+): Promise<EnrollmentCredentialsResponse | null> {
+  if (Math.abs(nowSeconds - input.signedAt) > 120) return null;
+  const secret = resolveEnrollmentSigningSecret(services.settings);
+  if (!secret) return null;
+  const claims = await verifyEnrollmentBearer(secret, input.bearer, 0);
+  if (
+    !claims ||
+    claims.agentId !== claims.enrollmentId ||
+    claims.subjectPrefix !== `agent.${claims.workspaceId}.${claims.agentId}`
+  )
+    return null;
+  const enrollment = await getEnrollment(services.db, claims.workspaceId, claims.enrollmentId);
+  if (
+    !enrollment ||
+    enrollment.status !== "active" ||
+    enrollment.credentialGeneration !== claims.credentialGeneration
+  )
+    return null;
+  try {
+    const rawKey = Buffer.from(enrollment.pubkey, "base64");
+    const signature = Buffer.from(input.signature, "base64");
+    if (rawKey.length !== 32 || signature.length !== 64) return null;
+    const key = createPublicKey({
+      key: Buffer.concat([Buffer.from("302a300506032b6570032100", "hex"), rawKey]),
+      format: "der",
+      type: "spki",
+    });
+    if (
+      !verify(
+        null,
+        Buffer.from(enrollmentRenewalProof(input.bearer, input.signedAt)),
+        key,
+        signature,
+      )
+    )
+      return null;
+  } catch {
+    return null;
+  }
+  // A concurrent revoke/re-enrollment still wins: issued credentials retain the
+  // captured generation, which the control-plane claim rechecks transactionally.
+  return buildEnrollmentCredentials(services, {
+    secret,
+    workspaceId: enrollment.workspaceId,
+    agentId: enrollment.id,
+    credentialGeneration: enrollment.credentialGeneration,
+    consentedScreenControl: enrollment.allowScreenControl,
+  });
+}
 // The headless enroll token (`oget_`; design 11 §A2.1) TTL. 1h: long enough to
 // script a fleet rollout, short enough to bound exposure of a workspace-scoped
 // secret that IS the grant (no human approve). Re-mintable by an authorized user.
@@ -172,7 +235,7 @@ export async function startDeviceEnrollment(
     throw lastError instanceof Error ? lastError : new Error("failed to start device enrollment");
   }
 
-  const base = input.verificationOrigin.replace(/\/$/, "");
+  const base = input.verificationOrigin.replace(/\/+$/, "");
   const verificationUri = `${base}/device`;
   const verificationUriComplete = `${verificationUri}?user_code=${encodeURIComponent(request.userCode)}`;
   return {
@@ -193,12 +256,18 @@ export async function approveDeviceEnrollment(
   input: {
     accountId: string;
     workspaceId: string;
+    scope?: "organization" | "workspace" | "user";
+    allowOrganization?: boolean;
     userCode: string;
     allowScreenControl: boolean;
     approvedBySubjectId: string;
     approvedBySubjectLabel?: string | null;
   },
-): Promise<{ enrollmentId: string; sandboxId: string; allowScreenControl: boolean } | null> {
+): Promise<{
+  enrollmentId: string;
+  sandboxId: string;
+  allowScreenControl: boolean;
+} | null> {
   const { db } = services;
   const pending = await getPendingDeviceEnrollmentRequestByUserCode(
     db,
@@ -213,6 +282,8 @@ export async function approveDeviceEnrollment(
   const result = await approveDeviceEnrollmentRequest(db, {
     accountId: input.accountId,
     workspaceId: input.workspaceId,
+    ...(input.scope ? { scope: input.scope } : {}),
+    allowOrganization: input.allowOrganization === true,
     requestId: pending.id,
     allowScreenControl: input.allowScreenControl,
     approvedBySubjectId: input.approvedBySubjectId,
@@ -291,7 +362,11 @@ export async function denyDeviceEnrollment(
  *  mirror poll's "disabled" handling. The token value is NEVER logged. */
 export async function mintEnrollToken(
   services: EnrollmentServices,
-  input: { accountId: string; workspaceId: string; allowScreenControl: boolean },
+  input: {
+    accountId: string;
+    workspaceId: string;
+    allowScreenControl: boolean;
+  },
 ): Promise<MintEnrollTokenResponse | null> {
   const { settings } = services;
   const secret = resolveEnrollmentSigningSecret(settings);

package/src/sandbox/machines.ts

@@ -1,16 +1,17 @@
 // 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
-//     enrollment-derived consent/display reasons (consent_required /
-//     display_unavailable) — a real ControlRpc ping (the subject IS the registry),
-//     reusing the M7 fleet probe;
+//   * STATE — heartbeat + goodbye liveness (online/offline) overlaid with the
+//     enrollment-derived display reason (display_unavailable). This list does
+//     not ControlRpc-ping; attach, capability negotiation, and fleet tools
+//     still probe when they need a live responder.
 //   * METRICS — the latest machine_metrics_latest row (or null before a first
 //     heartbeat), projected to the contract's MetricSample;
 //   * sharedSessionCount — the lease refcount (how many sessions share this one
 //     whole machine, the maxSandboxes:1 disclosure).
-// PLUS, when a session context is supplied, the session's synthetic Modal group
-// box (isSessionGroup:true) + the active-sandbox pointer (activeSandboxId/Epoch).
+// PLUS, when a session context is supplied, the session's synthetic managed
+// group box (isSessionGroup:true) + the active-sandbox pointer
+// (activeSandboxId/Epoch).
 //
 // This is workspace-scoped (perm enrollments:read) and flag-gated upstream
 // (sandboxSelfhostedEnabled). It deliberately does NOT depend on a FleetContext
@@ -21,6 +22,7 @@
 import type { Settings } from "@opengeni/config";
 import {
   getSession,
+  getLiveEnrollmentConnection,
   listEnrollments,
   listSandboxes,
   readActiveSandbox,
@@ -30,32 +32,129 @@ import {
   type EnrollmentRecord,
   type MachineMetricsRow,
 } from "@opengeni/db";
-import type { EventBus } from "@opengeni/events";
 import { MachineView, MetricSample, type MachinesResponse } from "@opengeni/contracts";
-import {
-  NatsControlRpc,
-  selfhostedLiveness,
-  SelfhostedSession,
-  type ControlRpc,
-  type NatsRequestConnection,
-} from "@opengeni/runtime/sandbox";
-import { relayConfigFromSettings } from "@opengeni/core";
+import { managedSessionGroupBackend, sessionGroupMachinePresentation } from "@opengeni/core";
+import { selfhostedHeartbeatLiveness } from "@opengeni/runtime/sandbox";
 
 export type MachinesServices = {
   db: Database;
   settings: Settings;
-  bus?: EventBus;
 };
 
-const PROBE_TIMEOUT_MS = 5_000;
+const ACTIVE_UPDATE_STATUSES = new Set([
+  "requested",
+  "accepted",
+  "waiting_for_idle",
+  "downloading",
+  "verifying",
+  "applying",
+  "restarting",
+]);
 
-function controlRpc(bus: EventBus | undefined): ControlRpc {
-  return new NatsControlRpc(async (): Promise<NatsRequestConnection | null> => {
-    if (!bus) {
-      return null;
-    }
-    return bus.getRequestConnection();
-  });
+function compareAgentVersions(left: string, right: string): number | null {
+  const parse = (value: string): { core: number[]; prerelease: string | null } | null => {
+    const match = /^(?:v)?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(value.trim());
+    if (!match) return null;
+    return {
+      core: [Number(match[1]), Number(match[2]), Number(match[3])],
+      prerelease: match[4] ?? null,
+    };
+  };
+  const a = parse(left);
+  const b = parse(right);
+  if (!a || !b) return null;
+  for (let index = 0; index < 3; index += 1) {
+    const delta = a.core[index]! - b.core[index]!;
+    if (delta !== 0) return Math.sign(delta);
+  }
+  if (a.prerelease === b.prerelease) return 0;
+  if (a.prerelease === null) return 1;
+  if (b.prerelease === null) return -1;
+  return a.prerelease.localeCompare(b.prerelease);
+}
+
+/** Older Mac updaters replace a single file inside a sealed app. They must
+ * bootstrap once through the official whole-app installer, never an RPC swap. */
+export function machineUpdateBlockedReason(os: string, version: string | null): string | null {
+  if (os !== "macos") return null;
+  const order = version ? compareAgentVersions(version, "0.1.29") : null;
+  return order !== null && order >= 0
+    ? null
+    : "Install Opengeni Agent 0.1.29 or newer with the official Mac installer first. This older updater cannot preserve the signed application.";
+}
+
+function runtimeFor(settings: Settings, enrollment: EnrollmentRecord): MachineView["runtime"] {
+  const desiredVersion =
+    enrollment.agentUpdateChannel === "beta"
+      ? (settings.agentBetaVersion ?? settings.agentStableVersion)
+      : settings.agentStableVersion;
+  const update = enrollment.agentUpdate;
+  const activeUpdate = update ? ACTIVE_UPDATE_STATUSES.has(update.status) : false;
+  const order =
+    enrollment.agentVersion && desiredVersion
+      ? compareAgentVersions(enrollment.agentVersion, desiredVersion)
+      : null;
+  const versionState = activeUpdate
+    ? "updating"
+    : update?.status === "failed"
+      ? "update_failed"
+      : order === null
+        ? "unknown"
+        : order === 0
+          ? "current"
+          : order < 0
+            ? "outdated"
+            : "ahead";
+  const capability = (name: string): boolean => enrollment.agentCapabilities[name] === true;
+  return {
+    installedVersion: enrollment.agentVersion,
+    binarySha256: enrollment.agentBinarySha256,
+    updateChannel: enrollment.agentUpdateChannel,
+    desiredVersion,
+    versionState,
+    updateBlockedReason: machineUpdateBlockedReason(enrollment.os, enrollment.agentVersion),
+    capabilities: {
+      exec: capability("exec"),
+      filesystem: capability("filesystem"),
+      git: capability("git"),
+      pty: capability("pty"),
+      desktop: capability("desktop"),
+      opStream: capability("opStream"),
+      browserBridge: capability("browserBridge"),
+      operationResourcePolicy: capability("operationResourcePolicy"),
+      operationCpuQuota: capability("operationCpuQuota"),
+      transactionalFsWrite: capability("transactionalFsWrite"),
+    },
+    update,
+  };
+}
+
+function connectionAuthorityFor(
+  enrollment: EnrollmentRecord | null,
+  liveConnection: EnrollmentRecord | null,
+): MachineView["connectionAuthority"] {
+  if (!enrollment) {
+    return {
+      state: "not_applicable",
+      generation: 0,
+      supersededCount: 0,
+      leaseExpiresAt: null,
+      duplicateRunnerDeniedCount: 0,
+      duplicateRunnerDeniedAt: null,
+    };
+  }
+  return {
+    state: liveConnection
+      ? "active"
+      : enrollment.connectionInstanceId && enrollment.connectionLeaseExpiresAt
+        ? "expired"
+        : "unclaimed",
+    generation: enrollment.connectionGeneration,
+    supersededCount: Math.max(0, enrollment.connectionGeneration - 1),
+    leaseExpiresAt: enrollment.connectionLeaseExpiresAt,
+    duplicateRunnerDeniedCount: enrollment.connectionDuplicateDeniedCount,
+    duplicateRunnerDeniedAt: enrollment.connectionDuplicateDeniedAt,
+  };
 }
 
 /**
@@ -83,36 +182,8 @@ export function metricRowToSample(row: MachineMetricsRow): MetricSample {
   });
 }
 
-/** Probe an enrolled machine's liveness — a real ControlRpc ping mapped through
- *  `selfhostedLiveness` (the enrollment status/consent/display + lastSeenAt
- *  disambiguate a probe-miss into reconnecting vs offline). Mirrors the M7 fleet
- *  probe. A non-active enrollment is offline without a probe. */
-async function probeEnrollment(
-  services: MachinesServices,
-  workspaceId: string,
-  enrollment: EnrollmentRecord,
-): Promise<{
-  state: "online" | "reconnecting" | "offline";
-  consented: boolean;
-  hasDisplay: boolean;
-}> {
-  const { settings, bus } = services;
-  let probeResponded = false;
-  if (enrollment.status === "active") {
-    const session = new SelfhostedSession({
-      workspaceId,
-      agentId: enrollment.id,
-      controlRpc: controlRpc(bus),
-      relay: relayConfigFromSettings(settings),
-      timeoutMs: PROBE_TIMEOUT_MS,
-    });
-    try {
-      probeResponded = await session.ping();
-    } catch {
-      probeResponded = false;
-    }
-  }
-  const derived = selfhostedLiveness({
+function enrollmentLiveness(enrollment: EnrollmentRecord) {
+  return selfhostedHeartbeatLiveness({
     enrollment: {
       status: enrollment.status,
       exposure: enrollment.exposure,
@@ -122,16 +193,15 @@ async function probeEnrollment(
       wentOfflineAt: enrollment.wentOfflineAt,
       wentOfflineReason: enrollment.wentOfflineReason,
     },
-    probeResponded,
   });
-  return { state: derived.state, consented: derived.consented, hasDisplay: derived.hasDisplay };
 }
 
 /**
  * Resolve the dashboard STATE of a machine. State reflects REACHABILITY + the
  * VIEW plane only: an online machine with no display → `display_unavailable` (no
  * desktop stream, but compute — exec/fs/git/terminal — still works); otherwise
- * the liveness state (online/reconnecting/offline). It deliberately does NOT fold
+ * the liveness state (online/offline; list heartbeat never yields reconnecting).
+ * It deliberately does NOT fold
  * in screen-control consent: a displayed machine can be VIEWED (read-only) and
  * used for compute regardless of `allowScreenControl` — only INPUT (ComputerUse /
  * an interactive stream) needs that consent, which is a per-capability concern
@@ -163,7 +233,12 @@ function machineStateFor(
  */
 export async function listMachines(
   services: MachinesServices,
-  input: { workspaceId: string; sessionId?: string | null },
+  input: {
+    accountId?: string;
+    workspaceId: string;
+    subjectId?: string;
+    sessionId?: string | null;
+  },
 ): Promise<MachinesResponse> {
   const { db } = services;
   const { workspaceId } = input;
@@ -183,45 +258,92 @@ export async function listMachines(
   }
 
   const machines: MachineView[] = [];
+  const groupBackend = session
+    ? managedSessionGroupBackend(services.settings.sandboxBackend, session.sandboxBackend)
+    : null;
 
-  // The session's own group box (synthetic): the default/home sandbox a null
-  // active pointer routes to. A backend:none session has no home box.
-  if (session && session.sandboxBackend !== "none") {
+  // The session's own managed group box (synthetic): the sandbox a null active
+  // pointer routes to. A machine-home session uses the deployment's managed
+  // backend only after an explicit switch; none/selfhosted-only deployments do
+  // not invent a group they cannot establish.
+  if (session && groupBackend) {
     const groupActive = activeSandboxId === null;
     const groupLease = await readLease(db, workspaceId, session.sandboxGroupId);
+    const presentation = sessionGroupMachinePresentation(groupBackend);
+    const localHost = groupBackend === "local";
     machines.push(
       MachineView.parse({
         sandboxId: session.sandboxGroupId,
         enrollmentId: null,
-        name: "session sandbox",
-        kind: session.sandboxBackend === "selfhosted" ? "selfhosted" : "modal",
+        name: presentation.name,
+        kind: presentation.kind,
         state: "online",
         active: groupActive,
         isSessionGroup: true,
         workspaceGeneration: groupLease?.workspaceGeneration ?? null,
         archiveGeneration: groupLease?.archiveGeneration ?? null,
         archiveComplete: groupLease?.archiveComplete ?? false,
-        // The Modal group box is a cloud Linux box; its precise OS/arch is not
-        // surfaced as a metric, so the dashboard shows the canonical linux/x86_64.
-        os: "linux",
-        arch: "x86_64",
-        hasDisplay: false,
+        // A local sandbox is this machine. Other managed providers run a Linux box.
+        os: localHost ? process.platform : "linux",
+        arch: localHost ? process.arch : "x86_64",
+        hasDisplay: localHost,
         desktopUnavailableReason: null,
         allowScreenControl: false,
         sharedSessionCount: 1,
         lastSeenAt: null,
+        connectionAuthority: connectionAuthorityFor(null, null),
+        runtime: null,
+        operationPolicy: null,
         metrics: null,
       }),
     );
   }
 
   // The workspace's enrolled selfhosted machines. One bulk metrics read joined
-  // onto the machines (no N+1). Each machine is probed for liveness.
-  const [sandboxes, enrollments, metricsByEnrollment] = await Promise.all([
+  // onto the machines (no N+1). Liveness is the durable heartbeat cursor.
+  const [legacySandboxes, enrollments] = await Promise.all([
     listSandboxes(db, workspaceId),
-    listEnrollments(db, workspaceId, { status: "active" }),
-    readMachineMetricsLatestForWorkspace(db, workspaceId),
+    listEnrollments(
+      db,
+      input.accountId && input.subjectId
+        ? {
+            accountId: input.accountId,
+            workspaceId,
+            subjectId: input.subjectId,
+          }
+        : workspaceId,
+      { status: "active" },
+    ),
   ]);
+  const metricsByEnrollment = new Map<string, MachineMetricsRow>();
+  for (const originWorkspaceId of new Set(enrollments.map((entry) => entry.workspaceId))) {
+    const originMetrics = await readMachineMetricsLatestForWorkspace(db, originWorkspaceId);
+    for (const [enrollmentId, metrics] of originMetrics) {
+      metricsByEnrollment.set(enrollmentId, metrics);
+    }
+  }
+  const scopedSandboxes = enrollments.flatMap((enrollment) =>
+    enrollment.sandboxId
+      ? [
+          {
+            id: enrollment.sandboxId,
+            accountId: enrollment.accountId,
+            workspaceId: enrollment.workspaceId,
+            kind: "selfhosted" as const,
+            name: enrollment.sandboxName ?? `${enrollment.os} machine`,
+            enrollmentId: enrollment.id,
+            createdAt: enrollment.createdAt,
+            updatedAt: enrollment.updatedAt,
+          },
+        ]
+      : [],
+  );
+  const sandboxes = [
+    ...legacySandboxes.filter(
+      (sandbox) => !scopedSandboxes.some((scoped) => scoped.id === sandbox.id),
+    ),
+    ...scopedSandboxes,
+  ];
   const enrollmentById = new Map(enrollments.map((e) => [e.id, e]));
 
   const machineViews = await Promise.all(
@@ -233,11 +355,26 @@ export async function listMachines(
       if (!enrollment) {
         return null;
       }
-      const [probe, lease] = await Promise.all([
-        probeEnrollment(services, workspaceId, enrollment),
-        readLease(db, workspaceId, sandbox.id),
+      const [liveConnection, lease] = await Promise.all([
+        enrollment.connectionInstanceId &&
+        enrollment.connectionLeaseExpiresAt &&
+        Date.parse(enrollment.connectionLeaseExpiresAt) > Date.now()
+          ? Promise.resolve(enrollment)
+          : getLiveEnrollmentConnection(
+              db,
+              input.accountId && input.subjectId
+                ? {
+                    accountId: input.accountId,
+                    workspaceId,
+                    subjectId: input.subjectId,
+                  }
+                : enrollment.workspaceId,
+              enrollment.id,
+            ),
+        readLease(db, enrollment.workspaceId, sandbox.id),
       ]);
-      const state = machineStateFor(probe.state, probe.hasDisplay);
+      const liveness = enrollmentLiveness(enrollment);
+      const state = machineStateFor(liveness.state, liveness.hasDisplay);
 
       // sharedSessionCount = the lease refcount for this machine's group. The
       // selfhosted sandbox id IS the lease group key (maxSandboxes:1, N sessions
@@ -248,6 +385,8 @@ export async function listMachines(
       return MachineView.parse({
         sandboxId: sandbox.id,
         enrollmentId: enrollment.id,
+        scope: enrollment.scope,
+        generation: enrollment.generation,
         name: sandbox.name,
         kind: "selfhosted",
         state,
@@ -263,6 +402,9 @@ export async function listMachines(
         allowScreenControl: enrollment.allowScreenControl,
         sharedSessionCount,
         lastSeenAt: enrollment.lastSeenAt,
+        connectionAuthority: connectionAuthorityFor(enrollment, liveConnection),
+        runtime: runtimeFor(services.settings, enrollment),
+        operationPolicy: enrollment.operationPolicy,
         metrics: metricsRow ? metricRowToSample(metricsRow) : null,
       });
     }),