@opengeni/core 0.24.1 → 0.28.0

package/src/managed-session.ts

@@ -1,5 +1,7 @@
 import type { Context } from "hono";
 import type { ManagedAuth } from "./managed-auth-type";
+import type { Database } from "@opengeni/db";
+import { validateCanonicalHumanSession } from "@opengeni/db/canonical-human-identities";
 
 /**
  * Read a Better Auth session without bypassing its sliding-cookie renewal.
@@ -8,7 +10,11 @@ import type { ManagedAuth } from "./managed-auth-type";
  * Programmatic callers must explicitly request and forward the returned cookie
  * headers; the HTTP handler does this automatically, but direct API calls do not.
  */
-export async function getManagedSession(c: Context, auth: ManagedAuth) {
+export async function getManagedSession(
+  c: Context,
+  auth: ManagedAuth,
+  options?: { db?: Database; allowIdentityRecovery?: boolean },
+) {
   const result = await auth.api.getSession({
     headers: c.req.raw.headers,
     returnHeaders: true,
@@ -18,7 +24,18 @@ export async function getManagedSession(c: Context, auth: ManagedAuth) {
     c.header("set-cookie", cookie, { append: true });
   }
 
-  return result.response;
+  const session = result.response;
+  if (!session?.user || !options?.db) return session;
+  const authSessionId = session.session?.id;
+  if (typeof authSessionId !== "string") return null;
+  const valid = await validateCanonicalHumanSession(options.db, {
+    authSessionId,
+    authUserId: session.user.id,
+    ...(options.allowIdentityRecovery === undefined
+      ? {}
+      : { allowRecovery: options.allowIdentityRecovery }),
+  });
+  return valid ? session : null;
 }
 
 function setCookieHeaders(headers: Headers): string[] {

package/src/sandbox/fleet.ts

@@ -37,7 +37,6 @@ import {
   type SelfhostedRelayConfig,
   type SelfhostedOpStreamDeps,
 } from "@opengeni/runtime/sandbox";
-import { HTTPException } from "hono/http-exception";
 import { relayConfigFromSettings } from "./routing";
 
 export type FleetServices = {
@@ -69,8 +68,9 @@ export type FleetContext = {
 
 /**
  * Build a session-scoped {@link FleetContext}: load the session (workspace-
- * scoped), reject a session with no box (backend:none — the fleet is only
- * meaningful for a sandboxed session), and project its group backend/id. Shared
+ * scoped) and project its group backend/id. A backend:none session has no home
+ * box, but it may still discover, run on, and attach an owned Connected Machine.
+ * Shared
  * by the worker-signed MCP fleet tools and the user-authenticated swap REST
  * route so both resolve the SAME context (no drift). The `accountId`/`workspaceId`/
  * `sessionId` come from the trusted grant/route; the backend + group id come from
@@ -81,11 +81,6 @@ export async function buildFleetContextForSession(
   ctx: { accountId: string; workspaceId: string; sessionId: string },
 ): Promise<FleetContext> {
   const session = await requireSession(deps.db, ctx.workspaceId, ctx.sessionId);
-  if (session.sandboxBackend === "none") {
-    throw new HTTPException(422, {
-      message: "this session has no sandbox (backend: none); the fleet is unavailable",
-    });
-  }
   return {
     accountId: ctx.accountId,
     workspaceId: ctx.workspaceId,
@@ -229,9 +224,11 @@ async function probeEnrollment(
 }
 
 /**
- * List the fleet: the session's own Modal group box (a synthetic entry) + the
- * workspace's first-class selfhosted sandboxes (each probed for liveness), each
- * with an `active` marker derived from the session's active pointer.
+ * List the fleet: the session's own group box when it has one (a synthetic
+ * entry) + the workspace's first-class selfhosted sandboxes (each probed for
+ * liveness), each with an `active` marker derived from the session's active
+ * pointer. A backend:none session has no synthetic home entry; a null pointer
+ * then means no compute is attached.
  */
 export async function listFleet(
   services: FleetServices,
@@ -245,61 +242,63 @@ export async function listFleet(
 
   const entries: FleetSandboxEntry[] = [];
 
-  // The session's own group box (the default/home sandbox; null active pointer ==
-  // this box). A session/group row is not provider existence. Online requires a
-  // warm lease, observed provider existence, and verified workspace readiness.
-  const groupActive = pointer.activeSandboxId === null;
-  const groupLease = await readLease(db, ctx.workspaceId, ctx.sessionGroupId);
-  const groupOnline = Boolean(
-    groupLease?.liveness === "warm" &&
-    groupLease.recovery.provider.status === "exists" &&
-    groupLease.recovery.workspace.status === "ready",
-  );
-  const groupRecovering = Boolean(
-    groupLease &&
-    (groupLease.liveness === "warming" ||
-      groupLease.recovery.restore.status === "pending" ||
-      groupLease.recovery.restore.status === "restoring" ||
-      groupLease.recovery.restore.status === "verifying"),
-  );
-  const groupRecoveryUnavailable = Boolean(
-    groupLease &&
-    (groupLease.recovery.restore.status === "degraded" ||
-      groupLease.recovery.restore.status === "unrecoverable" ||
-      groupLease.recovery.workspace.status === "degraded" ||
-      groupLease.recovery.workspace.status === "unrecoverable"),
-  );
-  const groupOperationAvailability: FleetOperationAvailability = groupOnline
-    ? "ready"
-    : groupRecoveryUnavailable
-      ? "unavailable"
-      : groupRecovering
-        ? "recovering"
-        : ctx.sessionBackend === "selfhosted"
-          ? "unavailable"
-          : "wakeable";
-  entries.push({
-    id: ctx.sessionGroupId,
-    kind: ctx.sessionBackend === "selfhosted" ? "selfhosted" : "modal",
-    name: "session sandbox",
-    liveness: groupOnline ? "online" : groupRecovering ? "reconnecting" : "offline",
-    active: groupActive,
-    isSessionGroup: true,
-    enrollmentId: null,
-    attachable: groupOnline,
-    operationAvailability: groupOperationAvailability,
-    providerStatus: groupLease?.recovery.provider.status ?? "not_created",
-    leaseLiveness: groupLease?.liveness ?? null,
-    routeStatus: groupActive ? "attached" : "detached",
-    archiveStatus: groupLease?.recovery.archive.status ?? "none",
-    restoreStatus: groupLease?.recovery.restore.status ?? "not_required",
-    workspaceStatus: groupLease?.recovery.workspace.status ?? "unknown",
-    leaseEpoch: groupLease?.leaseEpoch ?? null,
-    routeEpoch: pointer.activeEpoch,
-    workspaceGeneration: groupLease?.workspaceGeneration ?? null,
-    archiveGeneration: groupLease?.archiveGeneration ?? null,
-    archiveComplete: groupLease?.archiveComplete ?? false,
-  });
+  if (ctx.sessionBackend !== "none") {
+    // The session's own group box (the default/home sandbox; null active pointer ==
+    // this box). A session/group row is not provider existence. Online requires a
+    // warm lease, observed provider existence, and verified workspace readiness.
+    const groupActive = pointer.activeSandboxId === null;
+    const groupLease = await readLease(db, ctx.workspaceId, ctx.sessionGroupId);
+    const groupOnline = Boolean(
+      groupLease?.liveness === "warm" &&
+      groupLease.recovery.provider.status === "exists" &&
+      groupLease.recovery.workspace.status === "ready",
+    );
+    const groupRecovering = Boolean(
+      groupLease &&
+      (groupLease.liveness === "warming" ||
+        groupLease.recovery.restore.status === "pending" ||
+        groupLease.recovery.restore.status === "restoring" ||
+        groupLease.recovery.restore.status === "verifying"),
+    );
+    const groupRecoveryUnavailable = Boolean(
+      groupLease &&
+      (groupLease.recovery.restore.status === "degraded" ||
+        groupLease.recovery.restore.status === "unrecoverable" ||
+        groupLease.recovery.workspace.status === "degraded" ||
+        groupLease.recovery.workspace.status === "unrecoverable"),
+    );
+    const groupOperationAvailability: FleetOperationAvailability = groupOnline
+      ? "ready"
+      : groupRecoveryUnavailable
+        ? "unavailable"
+        : groupRecovering
+          ? "recovering"
+          : ctx.sessionBackend === "selfhosted"
+            ? "unavailable"
+            : "wakeable";
+    entries.push({
+      id: ctx.sessionGroupId,
+      kind: ctx.sessionBackend === "selfhosted" ? "selfhosted" : "modal",
+      name: "session sandbox",
+      liveness: groupOnline ? "online" : groupRecovering ? "reconnecting" : "offline",
+      active: groupActive,
+      isSessionGroup: true,
+      enrollmentId: null,
+      attachable: groupOnline,
+      operationAvailability: groupOperationAvailability,
+      providerStatus: groupLease?.recovery.provider.status ?? "not_created",
+      leaseLiveness: groupLease?.liveness ?? null,
+      routeStatus: groupActive ? "attached" : "detached",
+      archiveStatus: groupLease?.recovery.archive.status ?? "none",
+      restoreStatus: groupLease?.recovery.restore.status ?? "not_required",
+      workspaceStatus: groupLease?.recovery.workspace.status ?? "unknown",
+      leaseEpoch: groupLease?.leaseEpoch ?? null,
+      routeEpoch: pointer.activeEpoch,
+      workspaceGeneration: groupLease?.workspaceGeneration ?? null,
+      archiveGeneration: groupLease?.archiveGeneration ?? null,
+      archiveComplete: groupLease?.archiveComplete ?? false,
+    });
+  }
 
   // The workspace's first-class selfhosted sandboxes (enrolled machines). Probe
   // each for liveness; a missing enrollment is offline.
@@ -374,6 +373,13 @@ async function resolveTarget(
 > {
   // The session's own group box → the default pointer (null).
   if (target === ctx.sessionGroupId || target === "session" || target === "default") {
+    if (ctx.sessionBackend === "none") {
+      return {
+        ok: false,
+        reason: "this session has no home sandbox; attach a Connected Machine",
+        code: "unsupported_backend_context",
+      };
+    }
     return { ok: true, targetSandboxId: null };
   }
   const sandbox = await getSandbox(services.db, ctx.workspaceId, target);

package/src/session-authorization.ts

@@ -8,11 +8,13 @@ import {
   type SessionAuthorizationTarget,
 } from "@opengeni/contracts";
 import {
+  getSessionAuthorityProjection,
   getSession,
-  getSessionRootId,
   getSessionTurnForAttempt,
   getSlackInteractionSessionAccessForSession,
+  withSessionRlsActorContext,
   type Database,
+  type SessionRlsActorContext,
 } from "@opengeni/db";
 import type { AppDependencies } from "./dependencies";
 
@@ -46,6 +48,91 @@ export type ResolvedSessionAuthorization = {
   reauthorizeAfterMs: number | null;
 };
 
+type ResolvedSessionAuthorizationActor = {
+  actor: SessionAuthorizationActor;
+  callerParentSessionId: string | null;
+};
+
+type ResolvedSessionAuthorizationTarget = {
+  target: SessionAuthorizationTarget;
+  parentSessionId: string | null;
+};
+
+function grantHasAgentAttemptAuthority(grant: AccessGrant): boolean {
+  const hasAgentAttemptClaim =
+    grant.metadata?.["turnId"] !== undefined ||
+    grant.metadata?.["attemptId"] !== undefined ||
+    grant.metadata?.["executionGeneration"] !== undefined;
+  return grant.principalKind ? grant.principalKind === "agent_attempt" : hasAgentAttemptClaim;
+}
+
+/**
+ * Read-only access an immediate child may use against its parent. Upstream
+ * mutation is deliberately limited to `session.append`: letting a child Pause,
+ * Steer, or otherwise mutate its parent would let it influence siblings through
+ * the parent's recursive control and shared state.
+ */
+const AGENT_PARENT_READ_OPERATIONS = new Set<SessionAuthorizationOperation>([
+  "session.read",
+  "session.events.read",
+  "session.stream.read",
+  "session.turns.read",
+  "session.queue.read",
+  "session.composer.read",
+  "session.lineage.read",
+  "session.capture.read",
+  "session.files.read",
+  "session.git.read",
+  "session.terminal.read",
+  "session.viewer.read",
+  "session.goal.read",
+  "session.human_input.read",
+]);
+
+function enforceAgentSessionHierarchy(
+  actor: Extract<SessionAuthorizationActor, { kind: "agent_attempt" }>,
+  callerParentSessionId: string | null,
+  target: ResolvedSessionAuthorizationTarget,
+  operation: SessionAuthorizationOperation,
+): "target" | "root" {
+  if (target.target.sessionId === actor.callerSessionId) return "root";
+
+  // A manager may inspect and operate an immediate child. Existing permission
+  // and host-policy checks still apply; lineage never grants a capability.
+  if (target.parentSessionId === actor.callerSessionId) return "target";
+
+  // A child may report to and inspect its immediate parent, but cannot mutate
+  // the parent except through the canonical machine-input message boundary.
+  if (callerParentSessionId === target.target.sessionId) {
+    if (operation === "session.append" || AGENT_PARENT_READ_OPERATIONS.has(operation)) {
+      return "target";
+    }
+    throw new SessionAuthorizationDeniedError("forbidden");
+  }
+
+  // Siblings, skipped generations, other branches, and unrelated roots are
+  // never cross-session authority for a live agent attempt.
+  throw new SessionAuthorizationDeniedError("forbidden");
+}
+
+export function sessionRlsActorForAuthorization(
+  authorization: ResolvedSessionAuthorization,
+): SessionRlsActorContext {
+  return authorization.actor.kind === "agent_attempt"
+    ? {
+        subjectId: authorization.actor.subjectId,
+        initiatingHumanSubjectId: authorization.actor.initiatingHumanSubjectId,
+      }
+    : { subjectId: authorization.actor.subjectId };
+}
+
+export async function withResolvedSessionAuthorization<T>(
+  authorization: ResolvedSessionAuthorization,
+  fn: () => Promise<T>,
+): Promise<T> {
+  return await withSessionRlsActorContext(sessionRlsActorForAuthorization(authorization), fn);
+}
+
 /**
  * Prove that a first-party request belongs to the exact currently active
  * attempt of the named caller session. Unlike the optional embedding-host ACL
@@ -56,7 +143,7 @@ export async function requireLiveAgentAttemptAuthorization(
   grant: AccessGrant,
   callerSessionId: string,
 ): Promise<Extract<SessionAuthorizationActor, { kind: "agent_attempt" }>> {
-  const actor = await resolveSessionAuthorizationActor(db, grant);
+  const { actor } = await resolveSessionAuthorizationActor(db, grant);
   if (actor.kind !== "agent_attempt" || actor.callerSessionId !== callerSessionId) {
     throw new SessionAuthorizationDeniedError("caller_stale");
   }
@@ -84,17 +171,52 @@ export async function requireSessionAuthorization(
   },
 ): Promise<ResolvedSessionAuthorization | null> {
   const port = deps.sessionAuthorization;
-  const slackAccess = await getSlackInteractionSessionAccessForSession(deps.db, {
-    accountId: grant.accountId,
-    workspaceId: grant.workspaceId,
-    sessionId: input.sessionId,
-  });
-  if (!port && slackAccess?.visibility !== "private") return null;
-
-  const actor = await resolveSessionAuthorizationActor(deps.db, grant);
-  const target = slackAccess
-    ? { sessionId: input.sessionId, rootSessionId: slackAccess.rootSessionId }
-    : await resolveSessionAuthorizationTarget(deps.db, grant, input.sessionId);
+  const isAgentAttempt = grantHasAgentAttemptAuthority(grant);
+  const [slackAccess, authority] = await Promise.all([
+    getSlackInteractionSessionAccessForSession(deps.db, {
+      accountId: grant.accountId,
+      workspaceId: grant.workspaceId,
+      sessionId: input.sessionId,
+    }),
+    getSessionAuthorityProjection(deps.db, grant.workspaceId, input.sessionId),
+  ]);
+
+  // Preserve the standalone workspace-shared path. Private sessions continue
+  // through the durable actor and ownership checks even without a host port.
+  if (
+    !port &&
+    !isAgentAttempt &&
+    slackAccess?.visibility !== "private" &&
+    authority?.visibility !== "user_private"
+  ) {
+    return null;
+  }
+  if (!authority) throw new SessionAuthorizationDeniedError("not_found");
+
+  const [resolvedActor, resolvedTarget] = await Promise.all([
+    resolveSessionAuthorizationActor(deps.db, grant),
+    resolveSessionAuthorizationTarget(deps.db, grant, input.sessionId),
+  ]);
+  const actor = resolvedActor.actor;
+  const target = resolvedTarget.target;
+  const agentRelatedSessionAccess =
+    actor.kind === "agent_attempt"
+      ? enforceAgentSessionHierarchy(
+          actor,
+          resolvedActor.callerParentSessionId,
+          resolvedTarget,
+          input.operation,
+        )
+      : null;
+
+  if (authority.visibility === "user_private") {
+    const allowed =
+      authority.ownerSubjectId !== null &&
+      (actor.kind === "subject"
+        ? actor.subjectId === authority.ownerSubjectId
+        : actor.initiatingHumanSubjectId === authority.ownerSubjectId);
+    if (!allowed) throw new SessionAuthorizationDeniedError("forbidden");
+  }
   if (slackAccess?.visibility === "private") {
     const allowed =
       actor.kind === "subject"
@@ -102,7 +224,14 @@ export async function requireSessionAuthorization(
         : actor.callerRootSessionId === target.rootSessionId;
     if (!allowed) throw new SessionAuthorizationDeniedError("forbidden");
   }
-  if (!port) return null;
+  if (!port) {
+    return {
+      actor,
+      target,
+      relatedSessionAccess: agentRelatedSessionAccess ?? "root",
+      reauthorizeAfterMs: null,
+    };
+  }
 
   let rawDecision: unknown;
   try {
@@ -127,7 +256,10 @@ export async function requireSessionAuthorization(
   return {
     actor,
     target,
-    relatedSessionAccess: parsed.data.relatedSessionAccess ?? "target",
+    relatedSessionAccess:
+      agentRelatedSessionAccess === "target"
+        ? "target"
+        : (parsed.data.relatedSessionAccess ?? "target"),
     reauthorizeAfterMs: parsed.data.reauthorizeAfterMs ?? null,
   };
 }
@@ -139,8 +271,12 @@ export async function requireSessionAuthorizationListScope(
   surface: SessionAuthorizationSurface,
 ): Promise<SessionAuthorizationListScope | null> {
   const port = deps.sessionAuthorization;
+  const isAgentAttempt = grantHasAgentAttemptAuthority(grant);
+  if (!port && !isAgentAttempt) return null;
+  const { actor } = await resolveSessionAuthorizationActor(deps.db, grant);
+  // Standalone agents may retain compact workspace discovery, but only while
+  // the signed caller attempt is still the exact live attempt.
   if (!port) return null;
-  const actor = await resolveSessionAuthorizationActor(deps.db, grant);
   let rawScope: unknown;
   try {
     rawScope = await port.resolveListScope({
@@ -168,39 +304,34 @@ async function resolveSessionAuthorizationTarget(
   db: Database,
   grant: AccessGrant,
   sessionId: string,
-): Promise<SessionAuthorizationTarget> {
+): Promise<ResolvedSessionAuthorizationTarget> {
   const session = await getSession(db, grant.workspaceId, sessionId);
   if (!session || session.accountId !== grant.accountId) {
     throw new SessionAuthorizationDeniedError("not_found");
   }
-  let rootSessionId: string | null;
-  try {
-    rootSessionId = await getSessionRootId(db, grant.workspaceId, session.id);
-  } catch (error) {
-    throw new SessionAuthorizationUnavailableError({ cause: error });
-  }
-  if (!rootSessionId) {
-    throw new SessionAuthorizationDeniedError("not_found");
-  }
-  return { sessionId: session.id, rootSessionId };
+  return {
+    target: { sessionId: session.id, rootSessionId: session.rootSessionId },
+    parentSessionId: session.parentSessionId,
+  };
 }
-
 async function resolveSessionAuthorizationActor(
   db: Database,
   grant: AccessGrant,
-): Promise<SessionAuthorizationActor> {
+): Promise<ResolvedSessionAuthorizationActor> {
   const callerSessionId = grant.metadata?.["sessionId"];
   const turnId = grant.metadata?.["turnId"];
   const attemptId = grant.metadata?.["attemptId"];
   const executionGeneration = grant.metadata?.["executionGeneration"];
-  const hasAttemptClaim =
-    turnId !== undefined || attemptId !== undefined || executionGeneration !== undefined;
-  if (!hasAttemptClaim) {
-    return SessionAuthorizationActor.parse({
-      kind: "subject",
-      subjectId: grant.subjectId,
-      ...(grant.subjectLabel ? { subjectLabel: grant.subjectLabel } : {}),
-    });
+  const isAgentAttempt = grantHasAgentAttemptAuthority(grant);
+  if (!isAgentAttempt) {
+    return {
+      actor: SessionAuthorizationActor.parse({
+        kind: "subject",
+        subjectId: grant.subjectId,
+        ...(grant.subjectLabel ? { subjectLabel: grant.subjectLabel } : {}),
+      }),
+      callerParentSessionId: null,
+    };
   }
   if (
     typeof callerSessionId !== "string" ||
@@ -212,10 +343,9 @@ async function resolveSessionAuthorizationActor(
   ) {
     throw new SessionAuthorizationDeniedError("caller_stale");
   }
-  const [callerSession, turn, callerRootSessionId] = await Promise.all([
+  const [callerSession, turn] = await Promise.all([
     getSession(db, grant.workspaceId, callerSessionId),
     getSessionTurnForAttempt(db, grant.workspaceId, callerSessionId, attemptId),
-    getSessionRootId(db, grant.workspaceId, callerSessionId).catch(() => null),
   ]);
   if (
     !callerSession ||
@@ -223,23 +353,25 @@ async function resolveSessionAuthorizationActor(
     !turn ||
     turn.id !== turnId ||
     turn.executionGeneration !== executionGeneration ||
-    callerSession.activeTurnId !== turn.id ||
-    !callerRootSessionId
+    callerSession.activeTurnId !== turn.id
   ) {
     throw new SessionAuthorizationDeniedError("caller_stale");
   }
-  return SessionAuthorizationActor.parse({
-    kind: "agent_attempt",
-    subjectId: grant.subjectId,
-    callerSessionId,
-    callerRootSessionId,
-    turnId,
-    attemptId,
-    executionGeneration,
-    initiator: turn.initiator,
-    initiatorContext: turn.initiatorContext,
-    initiatingHumanSubjectId:
-      turn.initiatingHumanSubjectId ??
-      (turn.initiator.kind === "subject" ? turn.initiator.subjectId : null),
-  });
+  return {
+    actor: SessionAuthorizationActor.parse({
+      kind: "agent_attempt",
+      subjectId: grant.subjectId,
+      callerSessionId,
+      callerRootSessionId: callerSession.rootSessionId,
+      turnId,
+      attemptId,
+      executionGeneration,
+      initiator: turn.initiator,
+      initiatorContext: turn.initiatorContext,
+      initiatingHumanSubjectId:
+        turn.initiatingHumanSubjectId ??
+        (turn.initiator.kind === "subject" ? turn.initiator.subjectId : null),
+    }),
+    callerParentSessionId: callerSession.parentSessionId,
+  };
 }

package/src/transcription.ts

@@ -19,6 +19,8 @@ export type TranscriptionLimits = {
 export type TranscriptionRequest = {
   workspaceId: string;
   accountId: string;
+  /** Authenticated human/service subject used for provider-account authority. */
+  subjectId: string;
   audio: Uint8Array;
   mimeType: string;
   /** Optional client-reported duration; enforced as a soft ceiling before upstream. */
@@ -87,6 +89,7 @@ export function statusForVoiceInputError(code: VoiceInputErrorCode): number {
 /** Optional workspace scope for readiness checks during provider selection. */
 export type TranscriptionAvailabilityContext = {
   workspaceId?: string | undefined;
+  subjectId?: string | undefined;
 };
 
 /**
@@ -109,6 +112,8 @@ export type TranscriptionProvider = {
     mimeType: string;
     filename: string;
     workspaceId: string;
+    accountId: string;
+    subjectId: string;
     requestId: string;
     signal?: AbortSignal | undefined;
   }): Promise<{ text: string; languages: string[] }>;