@opengeni/api-router 2.3.2-canary.2 → 2.5.0

package/src/auth/managed-auth-session-adapter.ts

@@ -0,0 +1,205 @@
+import type {
+  ManagedAuthResolvedSession,
+  ManagedAuthSessionAdapter,
+} from "@opengeni/core/managed-auth-session-sets";
+import { sql } from "drizzle-orm";
+import type { Database } from "@opengeni/db";
+import type { ManagedAuth } from "@opengeni/core";
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { runManagedAuthAttempt } from "./managed-auth-attempt-context";
+
+export function createBetterAuthSessionAdapter(
+  auth: ManagedAuth,
+  db: Database,
+): ManagedAuthSessionAdapter {
+  return {
+    async authenticate(input) {
+      if (input.provider !== "email_password") {
+        throw new Error("unsupported managed authentication provider");
+      }
+      const result = await runManagedAuthAttempt(
+        input.transactionId,
+        async () =>
+          await auth.api.signInEmail({
+            body: {
+              email: input.credentials.email,
+              password: input.credentials.password,
+              rememberMe: true,
+            },
+            headers: input.headers,
+            returnHeaders: true,
+          }),
+      );
+      const token = result.response?.token;
+      if (typeof token !== "string") {
+        throw new Error("managed authentication did not create an isolated session");
+      }
+      const resolved = await (await auth.$context).internalAdapter.findSession(token);
+      if (!resolved?.session?.id) {
+        throw new Error("managed authentication session could not be resolved");
+      }
+      return { authSessionId: resolved.session.id };
+    },
+
+    async resolveSelectedSession(input): Promise<ManagedAuthResolvedSession | null> {
+      const resolved = await (await auth.$context).internalAdapter.findSession(input.token);
+      return liveResolvedSession(resolved);
+    },
+
+    async resolveAmbientSession(headers): Promise<ManagedAuthResolvedSession | null> {
+      const context = await auth.$context;
+      const signed = cookieValue(headers.get("cookie"), context.authCookies.sessionToken.name);
+      const token = signed ? verifiedSignedCookieValue(signed, context.secret) : null;
+      if (!token) return null;
+      const resolved = await context.internalAdapter.findSession(token);
+      return liveResolvedSession(resolved);
+    },
+
+    async refreshSelectedSession(input): Promise<ManagedAuthResolvedSession | null> {
+      const context = await auth.$context;
+      const cookie = context.authCookies.sessionToken;
+      const headers = new Headers({
+        cookie: `${cookie.name}=${signedCookieValue(input.token, context.secret)}`,
+      });
+      const resolved = await auth.api.getSession({ headers, returnHeaders: true });
+      if (!resolved.response) return null;
+      // The provider may renew its durable expiry and emit token/cache cookies;
+      // this server-side selected-slot resolution intentionally discards them.
+      return resolved.response as ManagedAuthResolvedSession;
+    },
+
+    async revokeSession(input) {
+      await db.execute(sql`delete from auth_sessions where id = ${input.authSessionId}`);
+    },
+
+    async createLegacySelectedSessionCookies(input, currentCookieHeader) {
+      const context = await auth.$context;
+      const cookie = context.authCookies.sessionToken;
+      const value = input ? signedCookieValue(input.token, context.secret) : "";
+      const headers = [
+        serializeCookieHeader(cookie.name, value, {
+          ...cookie.attributes,
+          ...(input ? {} : { maxAge: 0, expires: new Date(0) }),
+        }),
+      ];
+      for (const cacheCookie of [
+        context.authCookies.sessionData,
+        context.authCookies.accountData,
+        context.authCookies.dontRememberToken,
+      ]) {
+        for (const name of cacheCookieNames(cacheCookie.name, currentCookieHeader)) {
+          headers.push(
+            serializeCookieHeader(name, "", {
+              ...cacheCookie.attributes,
+              maxAge: 0,
+              expires: new Date(0),
+            }),
+          );
+        }
+      }
+      return headers;
+    },
+  };
+}
+
+function liveResolvedSession(value: unknown): ManagedAuthResolvedSession | null {
+  if (!value || typeof value !== "object") return null;
+  const session = (value as { session?: { expiresAt?: unknown } }).session;
+  const expiresAt = session?.expiresAt;
+  const expiryMillis =
+    expiresAt instanceof Date
+      ? expiresAt.getTime()
+      : typeof expiresAt === "string" || typeof expiresAt === "number"
+        ? new Date(expiresAt).getTime()
+        : Number.NaN;
+  if (!Number.isFinite(expiryMillis) || expiryMillis <= Date.now()) return null;
+  return value as ManagedAuthResolvedSession;
+}
+
+function cookieValue(header: string | null, name: string): string | null {
+  if (!header) return null;
+  for (const part of header.split(";")) {
+    const separator = part.indexOf("=");
+    if (separator < 0 || part.slice(0, separator).trim() !== name) continue;
+    return part.slice(separator + 1).trim() || null;
+  }
+  return null;
+}
+
+function verifiedSignedCookieValue(value: string, secret: string): string | null {
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(value);
+  } catch {
+    return null;
+  }
+  const separator = decoded.lastIndexOf(".");
+  if (separator <= 0) return null;
+  const token = decoded.slice(0, separator);
+  const signature = decoded.slice(separator + 1);
+  const expected = createHmac("sha256", secret).update(token, "utf8").digest("base64");
+  const actualBytes = Buffer.from(signature, "utf8");
+  const expectedBytes = Buffer.from(expected, "utf8");
+  return actualBytes.length === expectedBytes.length && timingSafeEqual(actualBytes, expectedBytes)
+    ? token
+    : null;
+}
+
+function signedCookieValue(value: string, secret: string): string {
+  return encodeURIComponent(
+    `${value}.${createHmac("sha256", secret).update(value, "utf8").digest("base64")}`,
+  );
+}
+
+function serializeCookieHeader(
+  name: string,
+  value: string,
+  attributes: {
+    domain?: string;
+    expires?: Date;
+    httpOnly?: boolean;
+    maxAge?: number;
+    path?: string;
+    partitioned?: boolean;
+    prefix?: "secure" | "host";
+    sameSite?: string;
+    secure?: boolean;
+  },
+): string {
+  let cookieName = name;
+  if (attributes.prefix === "secure" && !cookieName.startsWith("__Secure-")) {
+    cookieName = `__Secure-${cookieName}`;
+  } else if (attributes.prefix === "host" && !cookieName.startsWith("__Host-")) {
+    cookieName = `__Host-${cookieName}`;
+  }
+  if (cookieName.startsWith("__Secure-")) attributes.secure = true;
+  if (cookieName.startsWith("__Host-")) {
+    attributes.secure = true;
+    attributes.path = "/";
+    delete attributes.domain;
+  }
+  let header = `${cookieName}=${value}`;
+  if (attributes.maxAge !== undefined)
+    header += `; Max-Age=${Math.max(0, Math.floor(attributes.maxAge))}`;
+  if (attributes.domain) header += `; Domain=${attributes.domain}`;
+  if (attributes.path) header += `; Path=${attributes.path}`;
+  if (attributes.expires) header += `; Expires=${attributes.expires.toUTCString()}`;
+  if (attributes.httpOnly) header += "; HttpOnly";
+  if (attributes.secure) header += "; Secure";
+  if (attributes.sameSite) {
+    header += `; SameSite=${attributes.sameSite[0]?.toUpperCase()}${attributes.sameSite.slice(1)}`;
+  }
+  if (attributes.partitioned) header += "; Partitioned";
+  return header;
+}
+
+function cacheCookieNames(baseName: string, cookieHeader?: string | null): string[] {
+  const names = new Set([baseName]);
+  for (const part of cookieHeader?.split(";") ?? []) {
+    const separator = part.indexOf("=");
+    if (separator < 0) continue;
+    const name = part.slice(0, separator).trim();
+    if (name === baseName || name.startsWith(`${baseName}.`)) names.add(name);
+  }
+  return [...names].sort();
+}

package/src/auth/managed-auth.ts

@@ -9,14 +9,20 @@ import { ensureManagedAccessForUser } from "@opengeni/db";
 import {
   ensureCanonicalHumanIdentityForAuthUser,
   getCanonicalHumanIdentityProjection,
+  getCanonicalHumanExactLoginBindingForAuthUser,
   synchronizeCanonicalHumanLoginBindings,
 } from "@opengeni/db/canonical-human-identities";
 import { betterAuth } from "better-auth";
 import { createEmailVerificationToken } from "better-auth/api";
 import { hashPassword } from "better-auth/crypto";
+import { sql } from "drizzle-orm";
 import { Pool } from "pg";
 
 import { decideCanonicalHumanSessionAdmission } from "./canonical-human-session-admission";
+import {
+  currentManagedAuthAttemptId,
+  shouldDiscardCurrentManagedAuthProviderSession,
+} from "./managed-auth-attempt-context";
 
 // `ManagedAuth` (the Better Auth `Auth<any>` alias) is owned by @opengeni/core
 // (`managed-auth-type.ts`) — `dependencies.ts`/`access` reference it as a
@@ -121,6 +127,25 @@ export function createManagedAuth(
           returned: false,
           bigint: true,
         },
+        loginBindingId: {
+          type: "string",
+          fieldName: "login_binding_id",
+          input: false,
+          returned: false,
+        },
+        loginBindingRevision: {
+          type: "number",
+          fieldName: "login_binding_revision",
+          input: false,
+          returned: false,
+          bigint: true,
+        },
+        managedAuthLoginTransactionId: {
+          type: "string",
+          fieldName: "managed_auth_login_transaction_id",
+          input: false,
+          returned: false,
+        },
       },
     },
     account: {
@@ -215,8 +240,13 @@ export function createManagedAuth(
               binding: null,
             });
             if (!preflight.allowed) {
+              const exactRecoveryBinding = await getCanonicalHumanExactLoginBindingForAuthUser(db, {
+                authUserId: session.userId,
+                providerId: "credential",
+              });
               const recoveryBinding = preflightProjection.loginBindings.find(
-                (binding) => binding.status === "recovery_pending",
+                (binding) =>
+                  binding.id === exactRecoveryBinding.id && binding.status === "recovery_pending",
               );
               const recoveryAdmission = decideCanonicalHumanSessionAdmission({
                 intent: "recovery_completion",
@@ -235,17 +265,27 @@ export function createManagedAuth(
               return {
                 data: {
                   ...session,
+                  ...(shouldDiscardCurrentManagedAuthProviderSession()
+                    ? { expiresAt: new Date(0) }
+                    : {}),
                   identityId: preflightProjection.activeIdentity.id,
                   identityRevision: preflightProjection.activeIdentity.identityRevision,
                   authRevision: preflightProjection.activeIdentity.authRevision,
+                  loginBindingId: recoveryBinding!.id,
+                  loginBindingRevision: recoveryBinding!.revision,
+                  managedAuthLoginTransactionId: currentManagedAuthAttemptId(),
                 },
               };
             }
 
             await synchronizeCanonicalHumanLoginBindings(db, session.userId);
             const projection = await getCanonicalHumanIdentityProjection(db, session.userId);
+            const exactBinding = await getCanonicalHumanExactLoginBindingForAuthUser(db, {
+              authUserId: session.userId,
+              providerId: "credential",
+            });
             const activeBinding = projection.loginBindings.find(
-              (binding) => binding.id === projection.activeIdentity.activeLoginBindingId,
+              (binding) => binding.id === exactBinding.id,
             );
             const admission = decideCanonicalHumanSessionAdmission({
               intent: "ordinary_session",
@@ -265,12 +305,22 @@ export function createManagedAuth(
             return {
               data: {
                 ...session,
+                ...(shouldDiscardCurrentManagedAuthProviderSession()
+                  ? { expiresAt: new Date(0) }
+                  : {}),
                 identityId: projection.activeIdentity.id,
                 identityRevision: projection.activeIdentity.identityRevision,
                 authRevision: projection.activeIdentity.authRevision,
+                loginBindingId: exactBinding.id,
+                loginBindingRevision: exactBinding.revision,
+                managedAuthLoginTransactionId: currentManagedAuthAttemptId(),
               },
             };
           },
+          after: async (session) => {
+            if (!shouldDiscardCurrentManagedAuthProviderSession()) return;
+            await db.execute(sql`delete from auth_sessions where id = ${session.id}`);
+          },
         },
       },
       user: {

package/src/fatal-process-boundary.ts

@@ -0,0 +1,231 @@
+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">;
+
+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);
+    const message = apiFatalMessage(diagnostic);
+    const activeObservability = observability;
+    try {
+      if (activeObservability) {
+        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/http/sse.ts

@@ -19,6 +19,7 @@ import {
   type EventBus,
 } from "@opengeni/events";
 import type { Observability } from "@opengeni/observability";
+import { MANAGED_AUTH_ACTOR_EPOCH_HEADER } from "@opengeni/core/managed-auth-session-sets";
 
 const SESSION_REPLAY_PAGE_SIZE = 100;
 const WORKSPACE_CONTROL_REPLAY_PAGE_SIZE = 100;
@@ -463,6 +464,7 @@ export async function sseSessionStream(
       "Content-Type": "text/event-stream; charset=utf-8",
       "Cache-Control": "no-cache, no-transform",
       Connection: "keep-alive",
+      ...(options.actorEpoch ? { [MANAGED_AUTH_ACTOR_EPOCH_HEADER]: options.actorEpoch } : {}),
     },
   });
 }
@@ -636,6 +638,7 @@ export async function sseWorkspaceControlStream(
       "Content-Type": "text/event-stream; charset=utf-8",
       "Cache-Control": "no-cache, no-transform",
       Connection: "keep-alive",
+      ...(options.actorEpoch ? { [MANAGED_AUTH_ACTOR_EPOCH_HEADER]: options.actorEpoch } : {}),
     },
   });
 }
@@ -763,6 +766,7 @@ export async function sseWorkspaceLiveStream(
       "Content-Type": "text/event-stream; charset=utf-8",
       "Cache-Control": "no-cache, no-transform",
       Connection: "keep-alive",
+      ...(options.actorEpoch ? { [MANAGED_AUTH_ACTOR_EPOCH_HEADER]: options.actorEpoch } : {}),
     },
   });
 }
@@ -851,6 +855,7 @@ export async function sseWorkspaceInteractionRevisionStream(
       "Content-Type": "text/event-stream; charset=utf-8",
       "Cache-Control": "no-cache, no-transform",
       Connection: "keep-alive",
+      ...(options.actorEpoch ? { [MANAGED_AUTH_ACTOR_EPOCH_HEADER]: options.actorEpoch } : {}),
     },
   });
 }
@@ -922,6 +927,8 @@ export type SseDeliveryOptions = {
   /** Current ACL re-check, run even while the event stream is idle. */
   reauthorize?: (() => Promise<void>) | undefined;
   reauthorizeAfterMs?: number | undefined;
+  /** Exact selected actor emitted on the stream response for cross-tab fencing. */
+  actorEpoch?: string | undefined;
 };
 
 export type SessionSseDeliveryOptions = SseDeliveryOptions;

package/src/index.ts

@@ -21,7 +21,11 @@ import {
   type Database,
 } from "@opengeni/db";
 import { createNatsEventBus, type ResponderConnection } from "@opengeni/events";
-import { createObservability, logStartupDependencyRetry } from "@opengeni/observability";
+import {
+  createObservability,
+  logStartupDependencyRetry,
+  type Observability,
+} from "@opengeni/observability";
 import { createObjectStorage } from "@opengeni/storage";
 import { isArtifactRuntimeConfigured } from "@opengeni/artifact-tool/runtime/development";
 import { SESSION_WORKFLOW_WAKE_DISPATCHER_SCHEDULE_ID } from "@opengeni/core";
@@ -51,6 +55,7 @@ import {
   createStandaloneEditableArtifactApplication,
   type StandaloneEditableArtifactApplication,
 } from "./editable-artifact-production";
+import { installApiFatalProcessBoundary } from "./fatal-process-boundary";
 
 /**
  * A REJECT_DUPLICATE start collides on the deterministic workflowId when the
@@ -299,9 +304,15 @@ export async function createTemporalWorkflowClient(
   };
 }
 
-export async function startApi() {
-  const settings = getSettings();
-  const observability = createObservability(settings, { component: "api" });
+export async function startApi(
+  options: {
+    settings?: ReturnType<typeof getSettings>;
+    observability?: Observability;
+  } = {},
+) {
+  const settings = options.settings ?? getSettings();
+  const observability =
+    options.observability ?? createObservability(settings, { component: "api" });
   // Step I: standalone → dbSchema unset → searchPath undefined → today's plain
   // handle (public). Embedded → scoped to the dedicated schema + the host's RLS
   // strategy.
@@ -531,7 +542,16 @@ export async function startApi() {
 }
 
 if (import.meta.main) {
-  await startApi();
+  const fatalBoundary = installApiFatalProcessBoundary();
+  try {
+    const settings = getSettings();
+    const observability = createObservability(settings, { component: "api" });
+    fatalBoundary.attachObservability(observability);
+    await startApi({ settings, observability });
+    fatalBoundary.markRunning();
+  } catch (error) {
+    await fatalBoundary.reportStartupFailure(error);
+  }
 }
 
 export function temporalOverlapPolicy(policy: ScheduledTaskOverlapPolicy): ScheduleOverlapPolicy {