@opengeni/api-router 0.30.1 → 1.0.0

package/src/editable-artifact-source-session.ts

@@ -0,0 +1,123 @@
+import {
+  hasPermission,
+  requireExternalContinuationAuthority,
+  requireSessionAuthorization,
+  type ApiRouteDeps,
+  type OpenEditableArtifactLiveInput,
+} from "@opengeni/core";
+import {
+  findActiveWorkspaceApiKeyById,
+  getSession,
+  getWorkspaceGrant,
+  hasEditableArtifactSessionLink,
+  lockExternalWorkspaceMembershipLifecycle,
+  withRlsContext,
+} from "@opengeni/db";
+import { withAccessGrantSessionRlsContext } from "./access-grant-rls";
+import { sql } from "drizzle-orm";
+
+/** Supplied by the API adapter, so mounted hosts use their canonical live port. */
+export function editableArtifactSourceSessionAuthorizer(
+  deps: ApiRouteDeps,
+): NonNullable<OpenEditableArtifactLiveInput["authorizeSourceSession"]> {
+  return async (ticket, permission, transaction, signal) => {
+    signal?.throwIfAborted();
+    const authority = ticket.sourceSessionAuthority;
+    if (!authority) return true;
+    const { grant } = authority;
+    const required = permission === "edit" ? "artifacts:publish" : "artifacts:read";
+    if (
+      !hasPermission(grant.permissions, required) ||
+      !hasPermission(grant.permissions, "sessions:read")
+    ) {
+      return false;
+    }
+    // An external audit shape without the verified continuation is not authority.
+    if (grant.metadata?.externalActor && !authority.externalContinuation) return false;
+    try {
+      const scopedDeps = transaction ? { ...deps, db: transaction } : deps;
+      // Source-bound stores invoke us before their tenancy/aggregate locks.
+      // Match lifecycle writers' organization -> tenancy -> session prefix.
+      if (transaction) {
+        await lockExternalWorkspaceMembershipLifecycle(transaction, ticket.scope.accountId);
+        signal?.throwIfAborted();
+        // Tenancy writers acquire this fence before source session rows.
+        await transaction.execute(sql`select pg_advisory_xact_lock_shared(
+          hashtextextended(${`session-tenancy:${ticket.scope.workspaceId}`}, 0))`);
+        signal?.throwIfAborted();
+      }
+      return await withAccessGrantSessionRlsContext(scopedDeps, grant, async () => {
+        return await withRlsContext(scopedDeps.db, ticket.scope, async (tx) => {
+          if (authority.externalContinuation) {
+            await requireExternalContinuationAuthority(
+              tx,
+              authority.externalContinuation,
+              { ...ticket.scope, subjectId: grant.subjectId },
+              ["sessions:read", required],
+            );
+            signal?.throwIfAborted();
+          } else if (transaction) {
+            // The authenticated ticket grant is a ceiling, not proof that
+            // source-read permission still exists at the commit boundary.
+            const actor = ticket.actor;
+            if (
+              actor.kind === "human" ||
+              (actor.kind === "service" && actor.service === "configured_key")
+            ) {
+              await tx.execute(sql`select subject_id from workspace_memberships
+                where account_id = ${ticket.scope.accountId}::uuid
+                  and workspace_id = ${ticket.scope.workspaceId}::uuid
+                  and subject_id = ${grant.subjectId} for share`);
+              const live = await getWorkspaceGrant(tx, grant.subjectId, ticket.scope.workspaceId);
+              if (!live || !hasPermission(live.permissions, "sessions:read")) return false;
+            } else if (actor.kind === "service" && actor.service === "api_key") {
+              await tx.execute(sql`select id from api_keys
+                where account_id = ${ticket.scope.accountId}::uuid
+                  and id::text = ${grant.subjectId.slice("api_key:".length)}
+                for share`);
+              const live = await findActiveWorkspaceApiKeyById(tx, {
+                ...ticket.scope,
+                apiKeyId: grant.subjectId.slice("api_key:".length),
+              });
+              if (!live || !hasPermission(live.permissions, "sessions:read")) return false;
+            } else if (actor.kind === "agent") {
+              const live = await getSession(tx, ticket.scope.workspaceId, actor.sessionId);
+              if (
+                !live ||
+                (live.firstPartyMcpPermissions !== null &&
+                  !hasPermission(live.firstPartyMcpPermissions, "sessions:read"))
+              ) {
+                return false;
+              }
+            } else {
+              return false;
+            }
+            signal?.throwIfAborted();
+          }
+          // Locks protect visibility and removal of the exact association
+          // until the enclosing mutation transaction commits.
+          const linked = await hasEditableArtifactSessionLink(
+            tx,
+            ticket.scope,
+            authority.sessionId,
+            ticket.artifactId,
+            { lockForCommit: transaction !== undefined },
+          );
+          signal?.throwIfAborted();
+          if (!linked) return false;
+          await requireSessionAuthorization({ ...scopedDeps, db: tx }, grant, {
+            sessionId: authority.sessionId,
+            operation: "session.read",
+            surface: "http",
+          });
+          signal?.throwIfAborted();
+          return true;
+        });
+      });
+    } catch {
+      // Denial or an unavailable authority must stop data/writes, never fall
+      // back to artifact-only scope. The live loop closes denied readers.
+      return false;
+    }
+  };
+}

package/src/editable-artifact-websocket.ts

@@ -8,32 +8,24 @@ import {
   type EditableArtifactLiveServerFrame,
   type EditableArtifactLiveSession,
   type EditableArtifactLiveSinkPort,
+  type OpenEditableArtifactLiveInput,
 } from "@opengeni/core";
+import type {
+  ApiWebSocketConnection,
+  ApiWebSocketLike,
+  ApiWebSocketUpgradeServer,
+} from "./api-websocket";
 
 export const EDITABLE_ARTIFACT_LIVE_WEBSOCKET_PATH = "/v1/editable-artifacts/live";
-export const EDITABLE_ARTIFACT_LIVE_WEBSOCKET_PROTOCOL = "opengeni-artifact-v1";
+export const EDITABLE_ARTIFACT_LIVE_WEBSOCKET_PROTOCOL = "opengeni-artifact-v2";
 export const EDITABLE_ARTIFACT_LIVE_WEBSOCKET_MAX_MESSAGE_BYTES = 8 * 1024 * 1024 + 64 * 1024;
 
 const MAX_QUEUED_MESSAGES = 64;
 const MAX_QUEUED_BYTES = 12 * 1024 * 1024;
 
-export type EditableArtifactWebSocketLike = Readonly<{
-  data: EditableArtifactWebSocketConnection;
-  send(data: Uint8Array, compress?: boolean): number;
-  close(code?: number, reason?: string): void;
-  readonly bufferedAmount?: number;
-  getBufferedAmount?(): number;
-}>;
+export type EditableArtifactWebSocketLike = ApiWebSocketLike;
 
-export type EditableArtifactWebSocketUpgradeServer = Readonly<{
-  upgrade(
-    request: Request,
-    options: Readonly<{
-      data: EditableArtifactWebSocketConnection;
-      headers: HeadersInit;
-    }>,
-  ): boolean;
-}>;
+export type EditableArtifactWebSocketUpgradeServer = ApiWebSocketUpgradeServer;
 
 export type EditableArtifactWebSocketHandler = Readonly<{
   open(socket: EditableArtifactWebSocketLike): void;
@@ -44,7 +36,10 @@ export type EditableArtifactWebSocketHandler = Readonly<{
 export class EditableArtifactWebSocketTransport {
   readonly websocket: EditableArtifactWebSocketHandler;
 
-  constructor(private readonly application: EditableArtifactApplicationPort | undefined) {
+  constructor(
+    private readonly application: EditableArtifactApplicationPort | undefined,
+    private readonly authorizeSourceSession?: OpenEditableArtifactLiveInput["authorizeSourceSession"],
+  ) {
     this.websocket = Object.freeze({
       open: (socket) => socket.data.attach(socket),
       message: (socket, message) => socket.data.receive(message),
@@ -69,7 +64,10 @@ export class EditableArtifactWebSocketTransport {
     if (!offeredProtocol(request.headers.get("sec-websocket-protocol"))) {
       return new Response("WebSocket protocol required", { status: 426 });
     }
-    const connection = new EditableArtifactWebSocketConnection(this.application);
+    const connection = new EditableArtifactWebSocketConnection(
+      this.application,
+      this.authorizeSourceSession,
+    );
     const upgraded = server.upgrade(request, {
       data: connection,
       headers: {
@@ -81,7 +79,9 @@ export class EditableArtifactWebSocketTransport {
 }
 
 /** One socket, one consumed ticket, one stream epoch. */
-export class EditableArtifactWebSocketConnection implements EditableArtifactLiveSinkPort {
+export class EditableArtifactWebSocketConnection
+  implements EditableArtifactLiveSinkPort, ApiWebSocketConnection
+{
   private socket: EditableArtifactWebSocketLike | null = null;
   private session: EditableArtifactLiveSession | null = null;
   private work: Promise<void> = Promise.resolve();
@@ -89,7 +89,10 @@ export class EditableArtifactWebSocketConnection implements EditableArtifactLive
   private queuedBytes = 0;
   private terminal = false;
 
-  constructor(private readonly application: EditableArtifactApplicationPort) {}
+  constructor(
+    private readonly application: EditableArtifactApplicationPort,
+    private readonly authorizeSourceSession?: OpenEditableArtifactLiveInput["authorizeSourceSession"],
+  ) {}
 
   attach(socket: EditableArtifactWebSocketLike): void {
     if (this.socket || this.terminal) {
@@ -184,6 +187,9 @@ export class EditableArtifactWebSocketConnection implements EditableArtifactLive
         protocolVersion: frame.protocolVersion,
         resume: frame.resume,
         sink: this,
+        ...(this.authorizeSourceSession
+          ? { authorizeSourceSession: this.authorizeSourceSession }
+          : {}),
       });
       if (this.terminal) {
         await session.close("transport_error");

package/src/editable-artifact-workspace-files.ts

@@ -5,7 +5,7 @@ import {
   type EditableArtifactDurableExportService,
 } from "@opengeni/core/editable-artifacts";
 import { completeFileUpload, prepareGeneratedWorkspaceFile, type Database } from "@opengeni/db";
-import type { ObjectHead, ObjectStorage } from "@opengeni/storage";
+import { retryWhileMissing, type ObjectHead, type ObjectStorage } from "@opengeni/storage";
 
 const UPLOAD_INTENT_TTL_MS = 60 * 60_000;
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
@@ -81,7 +81,7 @@ export class EditableArtifactWorkspaceFileAdapter implements EditableArtifactAge
         if (existing) {
           assertStoredExport(existing, download.byteSize, download.mimeType, sha256);
         } else {
-          await storage.putObjectStreamIfAbsent({
+          const created = await storage.putObjectStreamIfAbsent({
             key: objectKey,
             contentType: download.mimeType,
             chunks: download.chunks(input.signal ? { signal: input.signal } : {}),
@@ -89,18 +89,28 @@ export class EditableArtifactWorkspaceFileAdapter implements EditableArtifactAge
             sha256,
             ...(input.signal ? { signal: input.signal } : {}),
           });
-          const stored = await storage.headObject(objectKey);
-          assertStoredExport(stored, download.byteSize, download.mimeType, sha256);
+          if (!created) {
+            await assertVisibleExport(
+              storage,
+              objectKey,
+              download.byteSize,
+              download.mimeType,
+              sha256,
+              input.signal,
+            );
+          }
         }
         await download.assertUnchanged(input.signal);
         throwIfAborted(input.signal);
         file = await this.completeFile(this.dependencies.db, input.scope.workspaceId, uploadId);
       } else {
-        assertStoredExport(
-          await storage.headObject(objectKey),
+        await assertVisibleExport(
+          storage,
+          objectKey,
           download.byteSize,
           download.mimeType,
           sha256,
+          input.signal,
         );
         await download.assertUnchanged(input.signal);
       }
@@ -133,6 +143,21 @@ export class EditableArtifactWorkspaceFileAdapter implements EditableArtifactAge
   }
 }
 
+async function assertVisibleExport(
+  storage: ObjectStorage,
+  objectKey: string,
+  byteSize: number,
+  contentType: string,
+  sha256: string,
+  signal?: AbortSignal,
+): Promise<void> {
+  const head = await retryWhileMissing(
+    async () => await storage.headObject!(objectKey),
+    signal ? { signal } : {},
+  );
+  assertStoredExport(head, byteSize, contentType, sha256);
+}
+
 function assertStoredExport(
   head: ObjectHead | null,
   byteSize: number,

package/src/fatal-process-boundary.ts

@@ -0,0 +1,246 @@
+import { randomUUID } from "node:crypto";
+import type { Attributes, Observability, Span } from "@opengeni/observability";
+
+export type ApiFatalEvent = "startup_failure" | "unhandled_rejection" | "uncaught_exception";
+export type ApiFatalPhase = "startup" | "running";
+export type ApiFatalReasonKind =
+  | "bigint"
+  | "boolean"
+  | "error"
+  | "function"
+  | "null"
+  | "number"
+  | "object"
+  | "string"
+  | "symbol"
+  | "undefined";
+
+type ApiFatalObservability = Pick<Observability, "error" | "flush" | "startSpan"> &
+  Partial<Pick<Observability, "recordFailureDiagnostic">>;
+
+type ApiFatalProcess = {
+  on: (
+    event: "unhandledRejection" | "uncaughtException",
+    listener: (reason: unknown) => void,
+  ) => void;
+  off: (
+    event: "unhandledRejection" | "uncaughtException",
+    listener: (reason: unknown) => void,
+  ) => void;
+  exit: (code: number) => void;
+};
+
+export type ApiFatalProcessBoundaryOptions = {
+  process?: ApiFatalProcess;
+  observability?: ApiFatalObservability;
+  flushTimeoutMs?: number;
+  correlationId?: () => string;
+  fallbackLog?: (message: string) => void;
+};
+
+export type ApiFatalProcessBoundary = {
+  attachObservability: (observability: ApiFatalObservability) => void;
+  markRunning: () => void;
+  reportStartupFailure: (reason: unknown) => Promise<void>;
+  dispose: () => void;
+};
+
+const API_FATAL_FLUSH_TIMEOUT_MS = 1_000;
+const API_FATAL_CORRELATION_ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
+
+const FATAL_ERROR_CODES = {
+  startup_failure: "api_startup_failed",
+  unhandled_rejection: "api_unhandled_rejection",
+  uncaught_exception: "api_uncaught_exception",
+} as const;
+
+export function installApiFatalProcessBoundary(
+  options: ApiFatalProcessBoundaryOptions = {},
+): ApiFatalProcessBoundary {
+  const runtimeProcess = options.process ?? defaultProcessBoundary();
+  const flushTimeoutMs = options.flushTimeoutMs ?? API_FATAL_FLUSH_TIMEOUT_MS;
+  const correlationId = options.correlationId ?? (() => `api-fatal.${randomUUID()}`);
+  const fallbackLog = options.fallbackLog ?? ((message: string) => console.error(message));
+  let observability = options.observability;
+  let phase: ApiFatalPhase = "startup";
+  let reporting = false;
+
+  const report = async (event: ApiFatalEvent, reason: unknown): Promise<void> => {
+    if (reporting) return;
+    reporting = true;
+
+    const diagnostic = apiFatalDiagnostic(event, phase, reason, correlationId);
+    let message = apiFatalMessage(diagnostic);
+    const activeObservability = observability;
+    try {
+      if (activeObservability) {
+        try {
+          const diagnosticId = activeObservability.recordFailureDiagnostic?.({
+            code: FATAL_ERROR_CODES[event],
+            stage: phase,
+            retryDecision: "not_retryable",
+            error: reason,
+          });
+          if (diagnosticId) {
+            diagnostic.correlationId = diagnosticId;
+            message = apiFatalMessage(diagnostic);
+          }
+        } catch {
+          // Never replace the required fatal exit with an observer failure.
+        }
+        let logged = false;
+        try {
+          activeObservability.error(message, diagnostic);
+          logged = true;
+        } catch {
+          // The fatal boundary must still report and terminate if logging is unhealthy.
+        }
+        if (!logged) {
+          safeFallbackLog(fallbackLog, message);
+        }
+        try {
+          const span: Span = activeObservability.startSpan("api.process.fatal", diagnostic);
+          span.end({ error: true });
+        } catch {
+          // The synchronous log remains authoritative when span creation fails.
+        }
+        await flushWithin(activeObservability, flushTimeoutMs);
+      } else {
+        safeFallbackLog(fallbackLog, message);
+      }
+    } finally {
+      runtimeProcess.exit(1);
+    }
+  };
+
+  const onUnhandledRejection = (reason: unknown): void => {
+    void report("unhandled_rejection", reason);
+  };
+  const onUncaughtException = (reason: unknown): void => {
+    void report("uncaught_exception", reason);
+  };
+  runtimeProcess.on("unhandledRejection", onUnhandledRejection);
+  runtimeProcess.on("uncaughtException", onUncaughtException);
+
+  return {
+    attachObservability: (value) => {
+      observability = value;
+    },
+    markRunning: () => {
+      phase = "running";
+    },
+    reportStartupFailure: async (reason) => {
+      await report("startup_failure", reason);
+    },
+    dispose: () => {
+      runtimeProcess.off("unhandledRejection", onUnhandledRejection);
+      runtimeProcess.off("uncaughtException", onUncaughtException);
+    },
+  };
+}
+
+function apiFatalDiagnostic(
+  event: ApiFatalEvent,
+  phase: ApiFatalPhase,
+  reason: unknown,
+  correlationId: () => string,
+): Attributes & {
+  errorClass: "ApiFatalOperationError";
+  errorCode: (typeof FATAL_ERROR_CODES)[ApiFatalEvent];
+  origin: "api";
+  phase: ApiFatalPhase;
+  reasonKind: ApiFatalReasonKind;
+  correlationId: string;
+} {
+  let safeCorrelationId = "api-fatal.fallback";
+  try {
+    const candidate = correlationId();
+    if (API_FATAL_CORRELATION_ID_PATTERN.test(candidate)) {
+      safeCorrelationId = candidate;
+    }
+  } catch {
+    // A fixed valid fallback preserves the fatal report and nonzero exit.
+  }
+  return {
+    errorClass: "ApiFatalOperationError",
+    errorCode: FATAL_ERROR_CODES[event],
+    origin: "api",
+    phase,
+    reasonKind: apiFatalReasonKind(reason),
+    correlationId: safeCorrelationId,
+  };
+}
+
+function apiFatalReasonKind(reason: unknown): ApiFatalReasonKind {
+  if (reason === null) return "null";
+  const kind = typeof reason;
+  if (kind !== "object") return kind;
+  try {
+    return reason instanceof Error ? "error" : "object";
+  } catch {
+    return "object";
+  }
+}
+
+function apiFatalMessage(diagnostic: ReturnType<typeof apiFatalDiagnostic>): string {
+  return (
+    `OpenGeni API fatal process failure (${diagnostic.errorCode}; ` +
+    `phase=${diagnostic.phase}; reason_kind=${diagnostic.reasonKind}; ` +
+    `correlation_id=${diagnostic.correlationId})`
+  );
+}
+
+async function flushWithin(
+  observability: Pick<Observability, "flush">,
+  timeoutMs: number,
+): Promise<void> {
+  let flush: Promise<void>;
+  try {
+    flush = Promise.resolve(observability.flush()).catch(() => undefined);
+  } catch {
+    return;
+  }
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) return;
+
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  try {
+    await Promise.race([
+      flush,
+      new Promise<void>((resolve) => {
+        timeout = setTimeout(resolve, timeoutMs);
+      }),
+    ]);
+  } finally {
+    if (timeout !== undefined) clearTimeout(timeout);
+  }
+}
+
+function safeFallbackLog(fallbackLog: (message: string) => void, message: string): void {
+  try {
+    fallbackLog(message);
+  } catch {
+    // Process termination remains mandatory even when every diagnostic sink fails.
+  }
+}
+
+function defaultProcessBoundary(): ApiFatalProcess {
+  return {
+    on: (event, listener) => {
+      if (event === "unhandledRejection") {
+        process.on("unhandledRejection", listener);
+      } else {
+        process.on("uncaughtException", listener);
+      }
+    },
+    off: (event, listener) => {
+      if (event === "unhandledRejection") {
+        process.off("unhandledRejection", listener);
+      } else {
+        process.off("uncaughtException", listener);
+      }
+    },
+    exit: (code) => {
+      process.exit(code);
+    },
+  };
+}

package/src/gateway-realtime.ts

@@ -62,7 +62,7 @@ export async function createGatewayRealtimeConnectionSecret(input: {
     throw new GatewayRealtimeBrokerError(
       "credential_unavailable",
       resolved.source === "managed"
-        ? "OpenGeni Gateway voice is not configured"
+        ? "Opengeni Gateway voice is not configured"
         : "The workspace AI Gateway connection is unavailable",
     );
   }