@opengeni/api-router 0.23.1 → 0.30.0

package/src/auth/canonical-human-session-admission.ts

@@ -0,0 +1,116 @@
+import type {
+  CanonicalHumanIdentityStatus,
+  CanonicalHumanLoginBindingStatus,
+  CanonicalHumanRecoveryState,
+} from "@opengeni/contracts/canonical-human-identities";
+
+export type CanonicalHumanSessionAdmissionIntent =
+  | "ordinary_session"
+  | "binding_synchronization"
+  | "recovery_completion";
+
+export type CanonicalHumanIdentityAdmissionSnapshot = {
+  readonly id: string;
+  readonly status: CanonicalHumanIdentityStatus;
+  readonly recoveryState: CanonicalHumanRecoveryState;
+  readonly activeLoginBindingId: string | null;
+};
+
+export type CanonicalHumanLoginBindingAdmissionSnapshot = {
+  readonly id: string;
+  readonly identityId: string;
+  readonly status: CanonicalHumanLoginBindingStatus;
+};
+
+export type CanonicalHumanSessionAdmissionDenialCode =
+  | "identity_binding_mismatch"
+  | "ordinary_identity_not_active"
+  | "ordinary_identity_not_ready"
+  | "ordinary_binding_missing"
+  | "ordinary_binding_not_active"
+  | "ordinary_active_binding_missing"
+  | "recovery_identity_not_required"
+  | "recovery_state_not_required"
+  | "recovery_active_binding_present"
+  | "recovery_binding_missing"
+  | "recovery_binding_not_pending";
+
+export type CanonicalHumanSessionAdmissionDecision =
+  | {
+      allowed: true;
+      intent: CanonicalHumanSessionAdmissionIntent;
+    }
+  | {
+      allowed: false;
+      intent: CanonicalHumanSessionAdmissionIntent;
+      code: CanonicalHumanSessionAdmissionDenialCode;
+    };
+
+export function decideCanonicalHumanSessionAdmission(input: {
+  intent: CanonicalHumanSessionAdmissionIntent;
+  identity: CanonicalHumanIdentityAdmissionSnapshot;
+  binding: CanonicalHumanLoginBindingAdmissionSnapshot | null;
+}): CanonicalHumanSessionAdmissionDecision {
+  if (input.binding && input.binding.identityId !== input.identity.id) {
+    return denied(input.intent, "identity_binding_mismatch");
+  }
+
+  if (input.intent === "recovery_completion") {
+    return decideRecoveryCompletion(input.identity, input.binding);
+  }
+
+  if (input.identity.status !== "active") {
+    return denied(input.intent, "ordinary_identity_not_active");
+  }
+  if (input.identity.recoveryState !== "ready") {
+    return denied(input.intent, "ordinary_identity_not_ready");
+  }
+  if (input.intent === "binding_synchronization" && input.binding === null) {
+    return allowed(input.intent);
+  }
+  if (input.binding === null) {
+    return denied(input.intent, "ordinary_binding_missing");
+  }
+  if (input.binding.status !== "active") {
+    return denied(input.intent, "ordinary_binding_not_active");
+  }
+  if (input.identity.activeLoginBindingId === null) {
+    return denied(input.intent, "ordinary_active_binding_missing");
+  }
+  return allowed(input.intent);
+}
+
+function decideRecoveryCompletion(
+  identity: CanonicalHumanIdentityAdmissionSnapshot,
+  binding: CanonicalHumanLoginBindingAdmissionSnapshot | null,
+): CanonicalHumanSessionAdmissionDecision {
+  if (identity.status !== "recovery_required") {
+    return denied("recovery_completion", "recovery_identity_not_required");
+  }
+  if (identity.recoveryState !== "recovery_required" && identity.recoveryState !== "lost_factor") {
+    return denied("recovery_completion", "recovery_state_not_required");
+  }
+  if (identity.activeLoginBindingId !== null) {
+    return denied("recovery_completion", "recovery_active_binding_present");
+  }
+  if (binding === null) {
+    return denied("recovery_completion", "recovery_binding_missing");
+  }
+  if (binding.status !== "recovery_pending") {
+    return denied("recovery_completion", "recovery_binding_not_pending");
+  }
+  return allowed("recovery_completion");
+}
+
+function allowed(
+  intent: CanonicalHumanSessionAdmissionIntent,
+): CanonicalHumanSessionAdmissionDecision {
+  return { allowed: true, intent };
+}
+
+function denied(
+  intent: CanonicalHumanSessionAdmissionIntent,
+  code: CanonicalHumanSessionAdmissionDenialCode,
+): CanonicalHumanSessionAdmissionDecision {
+  return { allowed: false, intent, code };
+}

package/src/auth/managed-auth.ts

@@ -2,11 +2,18 @@ import type { Settings } from "@opengeni/config";
 import { type ManagedAuth } from "@opengeni/core";
 import type { Database } from "@opengeni/db";
 import { ensureManagedAccessForUser } from "@opengeni/db";
+import {
+  ensureCanonicalHumanIdentityForAuthUser,
+  getCanonicalHumanIdentityProjection,
+  synchronizeCanonicalHumanLoginBindings,
+} from "@opengeni/db/canonical-human-identities";
 import { betterAuth } from "better-auth";
 import { createEmailVerificationToken } from "better-auth/api";
 import { Pool } from "pg";
 import { Resend } from "resend";
 
+import { decideCanonicalHumanSessionAdmission } from "./canonical-human-session-admission";
+
 // `ManagedAuth` (the Better Auth `Auth<any>` alias) is owned by @opengeni/core
 // (`managed-auth-type.ts`) — `dependencies.ts`/`access` reference it as a
 // type-only slot. We re-export it from this construction site so existing
@@ -65,6 +72,28 @@ export function createManagedAuth(settings: Settings, db: Database): ManagedAuth
         createdAt: "created_at",
         updatedAt: "updated_at",
       },
+      additionalFields: {
+        identityId: {
+          type: "string",
+          fieldName: "identity_id",
+          input: false,
+          returned: false,
+        },
+        identityRevision: {
+          type: "number",
+          fieldName: "identity_revision",
+          input: false,
+          returned: false,
+          bigint: true,
+        },
+        authRevision: {
+          type: "number",
+          fieldName: "auth_revision",
+          input: false,
+          returned: false,
+          bigint: true,
+        },
+      },
     },
     account: {
       modelName: "auth_identities",
@@ -136,6 +165,78 @@ export function createManagedAuth(settings: Settings, db: Database): ManagedAuth
       },
     },
     databaseHooks: {
+      session: {
+        create: {
+          before: async (session) => {
+            await ensureCanonicalHumanIdentityForAuthUser(db, session.userId);
+            const preflightProjection = await getCanonicalHumanIdentityProjection(
+              db,
+              session.userId,
+            );
+            const preflight = decideCanonicalHumanSessionAdmission({
+              intent: "binding_synchronization",
+              identity: preflightProjection.activeIdentity,
+              binding: null,
+            });
+            if (!preflight.allowed) {
+              const recoveryBinding = preflightProjection.loginBindings.find(
+                (binding) => binding.status === "recovery_pending",
+              );
+              const recoveryAdmission = decideCanonicalHumanSessionAdmission({
+                intent: "recovery_completion",
+                identity: preflightProjection.activeIdentity,
+                binding: recoveryBinding
+                  ? {
+                      id: recoveryBinding.id,
+                      identityId: preflightProjection.activeIdentity.id,
+                      status: recoveryBinding.status,
+                    }
+                  : null,
+              });
+              if (!recoveryAdmission.allowed) {
+                return false;
+              }
+              return {
+                data: {
+                  ...session,
+                  identityId: preflightProjection.activeIdentity.id,
+                  identityRevision: preflightProjection.activeIdentity.identityRevision,
+                  authRevision: preflightProjection.activeIdentity.authRevision,
+                },
+              };
+            }
+
+            await synchronizeCanonicalHumanLoginBindings(db, session.userId);
+            const projection = await getCanonicalHumanIdentityProjection(db, session.userId);
+            const activeBinding = projection.loginBindings.find(
+              (binding) => binding.id === projection.activeIdentity.activeLoginBindingId,
+            );
+            const admission = decideCanonicalHumanSessionAdmission({
+              intent: "ordinary_session",
+              identity: projection.activeIdentity,
+              binding: activeBinding
+                ? {
+                    id: activeBinding.id,
+                    identityId: projection.activeIdentity.id,
+                    status: activeBinding.status,
+                  }
+                : null,
+            });
+            if (!admission.allowed) {
+              return false;
+            }
+
+            return {
+              data: {
+                ...session,
+                identityId: projection.activeIdentity.id,
+                identityRevision: projection.activeIdentity.identityRevision,
+                authRevision: projection.activeIdentity.authRevision,
+              },
+            };
+          },
+        },
+      },
       user: {
         create: {
           after: async (user) => {

package/src/browser-auth-broker.ts

@@ -0,0 +1,155 @@
+import { createHmac } from "node:crypto";
+import type {
+  BrowserProtectedAuthFieldValue,
+  ProtectedAuthField,
+  SiteAuthAuthority,
+} from "@opengeni/contracts";
+
+type ConnectionFieldsAuthority = Extract<SiteAuthAuthority, { kind: "connection_fields" }>;
+
+export class BrowserAuthCredentialError extends Error {
+  readonly name = "BrowserAuthCredentialError";
+}
+
+export function resolveProtectedAuthFieldValues(input: {
+  authority: ConnectionFieldsAuthority;
+  requestedFields: readonly ProtectedAuthField[];
+  credential: Readonly<Record<string, unknown>>;
+  nowMs?: number;
+}): BrowserProtectedAuthFieldValue[] {
+  const configured = new Map(input.authority.fields.map((field) => [field.id, field]));
+  return input.requestedFields.map((requested) => {
+    const field = configured.get(requested.fieldId);
+    if (!field) {
+      throw new BrowserAuthCredentialError(
+        `Protected auth field ${requested.fieldId} is not configured`,
+      );
+    }
+    const stored = Object.prototype.hasOwnProperty.call(input.credential, field.credentialKey)
+      ? input.credential[field.credentialKey]
+      : undefined;
+    if (typeof stored !== "string" || stored.length === 0) {
+      throw new BrowserAuthCredentialError(
+        `Credential field ${field.credentialKey} is unavailable`,
+      );
+    }
+    const value =
+      field.purpose === "totp"
+        ? totpCode(stored, {
+            ...(field.digits === undefined ? {} : { digits: field.digits }),
+            ...(field.periodSeconds === undefined ? {} : { periodSeconds: field.periodSeconds }),
+            ...(field.algorithm === undefined ? {} : { algorithm: field.algorithm }),
+            ...(input.nowMs === undefined ? {} : { nowMs: input.nowMs }),
+          })
+        : stored;
+    return {
+      fieldId: requested.fieldId,
+      locator: requested.locator,
+      purpose: field.purpose,
+      value,
+    };
+  });
+}
+
+export function totpCode(
+  secretValue: string,
+  options: {
+    digits?: number;
+    periodSeconds?: number;
+    algorithm?: "sha1" | "sha256" | "sha512";
+    nowMs?: number;
+  } = {},
+): string {
+  const uri = secretValue.startsWith("otpauth://") ? parseOtpAuthUri(secretValue) : null;
+  const digits = options.digits ?? uri?.digits ?? 6;
+  const periodSeconds = options.periodSeconds ?? uri?.periodSeconds ?? 30;
+  const algorithm = options.algorithm ?? uri?.algorithm ?? "sha1";
+  if (!Number.isInteger(digits) || digits < 6 || digits > 10) {
+    throw new BrowserAuthCredentialError("TOTP digits must be between 6 and 10");
+  }
+  if (!Number.isInteger(periodSeconds) || periodSeconds < 15 || periodSeconds > 300) {
+    throw new BrowserAuthCredentialError("TOTP period is outside the supported range");
+  }
+  const nowMs = options.nowMs ?? Date.now();
+  if (!Number.isFinite(nowMs) || nowMs < 0) {
+    throw new BrowserAuthCredentialError("TOTP time is invalid");
+  }
+  const secret = decodeBase32(uri?.secret ?? secretValue);
+  const counter = Buffer.alloc(8);
+  counter.writeBigUInt64BE(BigInt(Math.floor(nowMs / (periodSeconds * 1_000))));
+  const digest = createHmac(algorithm, secret).update(counter).digest();
+  const offset = digest[digest.length - 1]! & 0x0f;
+  const binary =
+    ((digest[offset]! & 0x7f) << 24) |
+    (digest[offset + 1]! << 16) |
+    (digest[offset + 2]! << 8) |
+    digest[offset + 3]!;
+  const code = String(binary % 10 ** digits).padStart(digits, "0");
+  secret.fill(0);
+  counter.fill(0);
+  digest.fill(0);
+  return code;
+}
+
+function parseOtpAuthUri(value: string): {
+  secret: string;
+  digits?: number;
+  periodSeconds?: number;
+  algorithm?: "sha1" | "sha256" | "sha512";
+} {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new BrowserAuthCredentialError("TOTP credential contains an invalid otpauth URI");
+  }
+  if (url.protocol !== "otpauth:" || url.hostname !== "totp") {
+    throw new BrowserAuthCredentialError("Only otpauth TOTP credentials are supported");
+  }
+  const secret = url.searchParams.get("secret")?.trim();
+  if (!secret) throw new BrowserAuthCredentialError("TOTP credential has no secret");
+  const digits = optionalIntegerParameter(url, "digits");
+  const periodSeconds = optionalIntegerParameter(url, "period");
+  const rawAlgorithm = url.searchParams.get("algorithm")?.toLowerCase();
+  if (rawAlgorithm && !["sha1", "sha256", "sha512"].includes(rawAlgorithm)) {
+    throw new BrowserAuthCredentialError("TOTP credential uses an unsupported algorithm");
+  }
+  return {
+    secret,
+    ...(digits === undefined ? {} : { digits }),
+    ...(periodSeconds === undefined ? {} : { periodSeconds }),
+    ...(rawAlgorithm ? { algorithm: rawAlgorithm as "sha1" | "sha256" | "sha512" } : {}),
+  };
+}
+
+function optionalIntegerParameter(url: URL, name: string): number | undefined {
+  const value = url.searchParams.get(name);
+  if (value === null) return undefined;
+  if (!/^\d+$/u.test(value)) {
+    throw new BrowserAuthCredentialError(`TOTP ${name} is invalid`);
+  }
+  return Number(value);
+}
+
+function decodeBase32(value: string): Buffer {
+  const normalized = value.toUpperCase().replace(/[\s=-]/gu, "");
+  if (!normalized || /[^A-Z2-7]/u.test(normalized)) {
+    throw new BrowserAuthCredentialError("TOTP secret is not valid Base32");
+  }
+  let accumulator = 0;
+  let bits = 0;
+  const bytes: number[] = [];
+  for (const character of normalized) {
+    const code = character.charCodeAt(0);
+    const digit = code >= 65 && code <= 90 ? code - 65 : code - 50 + 26;
+    accumulator = (accumulator << 5) | digit;
+    bits += 5;
+    if (bits >= 8) {
+      bits -= 8;
+      bytes.push((accumulator >>> bits) & 0xff);
+      accumulator &= (1 << bits) - 1;
+    }
+  }
+  if (bytes.length === 0) throw new BrowserAuthCredentialError("TOTP secret is empty");
+  return Buffer.from(bytes);
+}

package/src/browser-controller-authority.ts

@@ -0,0 +1,186 @@
+import { createHmac } from "node:crypto";
+import type {
+  InteractionPlacement,
+  NetworkRouteConfiguration,
+  NetworkRouteConsistency,
+} from "@opengeni/contracts";
+
+type BrowserControllerAuthorityScope = {
+  rootSecret: string;
+  accountId: string;
+  workspaceId: string;
+  placement: InteractionPlacement;
+  placementInstanceId: string;
+};
+
+type BrowserSessionAuthorityScope = BrowserControllerAuthorityScope & {
+  browserSessionId: string;
+  controllerGeneration: string;
+  tokenGeneration: number;
+};
+
+type ComputerSessionAuthorityScope = BrowserControllerAuthorityScope & {
+  computerSessionId: string;
+  controllerGeneration: string;
+  tokenGeneration: number;
+};
+
+/** Stable placement-admin authority. This token is installed owner-only inside
+ * the exact placement and is never persisted or returned by the public API. */
+export function deriveBrowserControllerAdminToken(scope: BrowserControllerAuthorityScope): string {
+  return derive(scope.rootSecret, "placement-admin.v1", [
+    scope.accountId,
+    scope.workspaceId,
+    placementKey(scope.placement),
+    scope.placementInstanceId,
+  ]);
+}
+
+/** Deterministic controller credentials. The durable generations are the only
+ * stored authority; plaintext tokens can be reconstructed only by API replicas
+ * holding the deployment HMAC root. */
+export function deriveBrowserSessionControllerTokens(scope: BrowserSessionAuthorityScope): {
+  controlToken: string;
+  viewToken: string;
+} {
+  const fields = [
+    scope.accountId,
+    scope.workspaceId,
+    placementKey(scope.placement),
+    scope.placementInstanceId,
+    scope.browserSessionId,
+    scope.controllerGeneration,
+    scope.tokenGeneration,
+  ] as const;
+  return {
+    controlToken: derive(scope.rootSecret, "session-control.v1", fields),
+    viewToken: derive(scope.rootSecret, "session-view.v1", fields),
+  };
+}
+
+/** Secret-safe durable identity for one exact route launch. The digest binds
+ * the route snapshot and proxy credential without making a password-verifier
+ * hash available to database readers. */
+export function deriveBrowserNetworkRouteAuthorityDigest(scope: {
+  rootSecret: string;
+  accountId: string;
+  workspaceId: string;
+  browserSessionId: string;
+  routeId: string;
+  routeVersion: number;
+  credentialVersion: number | null;
+  configuration: NetworkRouteConfiguration;
+  consistency: NetworkRouteConsistency;
+  proxyCredential: { username: string; password: string } | null;
+}): string {
+  return derive(scope.rootSecret, "network-route-launch.v1", [
+    scope.accountId,
+    scope.workspaceId,
+    scope.browserSessionId,
+    scope.routeId,
+    scope.routeVersion,
+    scope.credentialVersion ?? "none",
+    canonicalJson(scope.configuration),
+    canonicalJson(scope.consistency),
+    scope.proxyCredential?.username ?? "none",
+    scope.proxyCredential?.password ?? "none",
+  ]).replace(/^ogb\./u, "ogr.");
+}
+
+export function deriveBrowserViewGrantToken(
+  scope: BrowserSessionAuthorityScope & { grantId: string; expiresAt: string },
+): string {
+  return derive(scope.rootSecret, "frame-view-grant.v1", [
+    scope.accountId,
+    scope.workspaceId,
+    placementKey(scope.placement),
+    scope.placementInstanceId,
+    scope.browserSessionId,
+    scope.controllerGeneration,
+    scope.tokenGeneration,
+    scope.grantId,
+    scope.expiresAt,
+  ]);
+}
+
+/** ComputerSession credentials share the placement controller root while using
+ * resource-specific domains. Browser and computer authority cannot collide. */
+export function deriveComputerSessionControllerTokens(scope: ComputerSessionAuthorityScope): {
+  controlToken: string;
+  viewToken: string;
+} {
+  const fields = [
+    scope.accountId,
+    scope.workspaceId,
+    placementKey(scope.placement),
+    scope.placementInstanceId,
+    scope.computerSessionId,
+    scope.controllerGeneration,
+    scope.tokenGeneration,
+  ] as const;
+  return {
+    controlToken: derive(scope.rootSecret, "computer-session-control.v1", fields),
+    viewToken: derive(scope.rootSecret, "computer-session-view.v1", fields),
+  };
+}
+
+export function deriveComputerViewGrantToken(
+  scope: ComputerSessionAuthorityScope & { grantId: string; expiresAt: string },
+): string {
+  return derive(scope.rootSecret, "computer-frame-view-grant.v1", [
+    scope.accountId,
+    scope.workspaceId,
+    placementKey(scope.placement),
+    scope.placementInstanceId,
+    scope.computerSessionId,
+    scope.controllerGeneration,
+    scope.tokenGeneration,
+    scope.grantId,
+    scope.expiresAt,
+  ]);
+}
+
+function derive(rootSecret: string, domain: string, fields: readonly (string | number)[]): string {
+  if (!rootSecret) throw new Error("browser controller authority root is unavailable");
+  const hmac = createHmac("sha256", rootSecret);
+  hmac.update("opengeni.browser-controller-authority\0", "utf8");
+  writeField(hmac, domain);
+  for (const field of fields) writeField(hmac, String(field));
+  return `ogb.${hmac.digest("base64url")}`;
+}
+
+function writeField(hmac: ReturnType<typeof createHmac>, value: string): void {
+  const bytes = Buffer.from(value, "utf8");
+  hmac.update(String(bytes.byteLength), "utf8");
+  hmac.update(":", "utf8");
+  hmac.update(bytes);
+}
+
+function canonicalJson(value: unknown): string {
+  return JSON.stringify(canonicalJsonValue(value));
+}
+
+function canonicalJsonValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonicalJsonValue);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, entry]) => [key, canonicalJsonValue(entry)]),
+    );
+  }
+  return value;
+}
+
+function placementKey(placement: InteractionPlacement): string {
+  switch (placement.kind) {
+    case "sandbox_group":
+      return `sandbox_group:${placement.sandboxGroupId}`;
+    case "connected_machine":
+      return `connected_machine:${placement.sandboxId}`;
+    case "attached_device":
+      return `attached_device:${placement.deviceId}`;
+    case "external_provider":
+      return `external_provider:${placement.providerId}:${placement.placementId}`;
+  }
+}

package/src/browser-network-route.ts

@@ -0,0 +1,34 @@
+import type {
+  InteractionPlacement,
+  NetworkRouteConfiguration,
+  NetworkRouteConsistency,
+} from "@opengeni/contracts";
+import { networkRoutePlacementCompatibilityIssue } from "@opengeni/contracts";
+import { BrowserSessionStateError } from "@opengeni/db";
+import type { PlacementBrowserNetworkRoute } from "@opengeni/runtime/sandbox";
+
+/** Resolve one provider-neutral managed route into the exact private selector
+ * accepted by the chosen external browser placement. Unsupported guarantees
+ * fail before lifecycle dispatch; no provider API key enters this value. */
+export function managedNetworkRouteForPlacement(
+  configuration: Extract<NetworkRouteConfiguration, { kind: "managed" }>,
+  consistency: NetworkRouteConsistency,
+  placement: InteractionPlacement,
+): NonNullable<PlacementBrowserNetworkRoute["providerRoute"]> {
+  const compatibilityIssue = networkRoutePlacementCompatibilityIssue(
+    configuration,
+    consistency,
+    placement,
+  );
+  if (compatibilityIssue) throw new BrowserSessionStateError(compatibilityIssue);
+  if (placement.kind !== "external_provider") throw new Error("unreachable managed placement");
+  if (configuration.providerId !== "browserbase" && configuration.providerId !== "kernel") {
+    throw new Error("unreachable managed provider");
+  }
+  return {
+    providerId: configuration.providerId,
+    routeId: configuration.routeId,
+    egressClass: configuration.egressClass,
+    region: configuration.region,
+  };
+}