@opengeni/api-router 0.26.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

@@ -1,5 +1,9 @@
 import { createHmac } from "node:crypto";
-import type { InteractionPlacement } from "@opengeni/contracts";
+import type {
+  InteractionPlacement,
+  NetworkRouteConfiguration,
+  NetworkRouteConsistency,
+} from "@opengeni/contracts";
 
 type BrowserControllerAuthorityScope = {
   rootSecret: string;
@@ -54,6 +58,35 @@ export function deriveBrowserSessionControllerTokens(scope: BrowserSessionAuthor
   };
 }
 
+/** 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 {
@@ -123,6 +156,22 @@ function writeField(hmac: ReturnType<typeof createHmac>, value: string): void {
   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":

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,
+  };
+}

package/src/controller-data-plane.ts

@@ -0,0 +1,35 @@
+import {
+  BrowserControlRequestError,
+  BrowserControlTransportError,
+} from "@opengeni/runtime/sandbox";
+
+/** Prefer a lease-fenced controller endpoint for the idempotent create path.
+ * Only a transport-class failure invalidates the cache and provisions once;
+ * semantic failures belong to the caller and must never be replayed. */
+export async function withCachedController<C, T>(options: {
+  cachedUrl: string | null;
+  createCachedClient: (url: string) => C;
+  prepareCachedClient?: (client: C) => Promise<void>;
+  invalidateCachedUrl: () => Promise<unknown>;
+  provisionClient: () => Promise<C>;
+  use: (client: C) => Promise<T>;
+}): Promise<T> {
+  if (options.cachedUrl) {
+    try {
+      const client = options.createCachedClient(options.cachedUrl);
+      await options.prepareCachedClient?.(client);
+      return await options.use(client);
+    } catch (error) {
+      if (!isRetryableControllerTransport(error)) throw error;
+      await options.invalidateCachedUrl().catch(() => undefined);
+    }
+  }
+  return await options.use(await options.provisionClient());
+}
+
+export function isRetryableControllerTransport(error: unknown): boolean {
+  return (
+    error instanceof BrowserControlTransportError ||
+    (error instanceof BrowserControlRequestError && error.retryable)
+  );
+}

package/src/http/auth.ts

@@ -1,4 +1,5 @@
-import type { Settings } from "@opengeni/config";
+import { resolveFirstPartyDelegationSecret, type Settings } from "@opengeni/config";
+import { verifyDelegatedAccessToken } from "@opengeni/contracts";
 import type { Context, MiddlewareHandler } from "hono";
 import { installExactPaths, isInstallRedirectPath } from "../routes/install";
 
@@ -17,7 +18,7 @@ export function requireAccessKey(settings: Settings): MiddlewareHandler {
       await next();
       return;
     }
-    if (isAuthorized(c, settings.accessKey)) {
+    if (await isAuthorized(c, settings)) {
       await next();
       return;
     }
@@ -55,7 +56,10 @@ function isAuthExempt(c: Context, settings: Settings): boolean {
     path === "/v1/integrations/slack/callback" ||
     path === "/v1/integrations/slack/events" ||
     path === "/v1/integrations/slack/commands" ||
-    path === "/v1/integrations/slack/interactions"
+    path === "/v1/integrations/slack/interactions" ||
+    // Fiken OAuth browser redirect: exact path only, protected by signed
+    // single-use state plus a callback-time grant recheck.
+    path === "/v1/integrations/fiken/callback"
   ) {
     return true;
   }
@@ -100,19 +104,33 @@ function isAuthExempt(c: Context, settings: Settings): boolean {
   return false;
 }
 
-function isAuthorized(c: Context, expected: string | undefined): boolean {
-  if (!expected) {
-    return false;
-  }
+async function isAuthorized(c: Context, settings: Settings): Promise<boolean> {
+  const expected = settings.accessKey;
   const explicit = c.req.header("x-opengeni-access-key");
-  if (constantTimeEqual(explicit, expected)) {
+  if (expected && constantTimeEqual(explicit, expected)) {
     return true;
   }
   const authorization = c.req.header("authorization");
   const bearer = authorization?.startsWith("Bearer ")
     ? authorization.slice("Bearer ".length)
     : undefined;
-  return constantTimeEqual(bearer, expected);
+  if (expected && constantTimeEqual(bearer, expected)) {
+    return true;
+  }
+
+  // This middleware is only the deployment perimeter. A valid first-party
+  // delegated bearer is already authenticated with the deployment's separate
+  // delegation authority, so admit it only to the product API's route-level
+  // access resolver. Deployment-only surfaces such as /metrics still require
+  // the static deployment key. The resolver enforces exact account, workspace,
+  // principal, and permissions; attempt-bound surfaces add live-attempt fences.
+  const delegationSecret = resolveFirstPartyDelegationSecret(settings);
+  return Boolean(
+    c.req.path.startsWith("/v1/") &&
+    bearer &&
+    delegationSecret &&
+    (await verifyDelegatedAccessToken(delegationSecret, bearer)),
+  );
 }
 
 function constantTimeEqual(actual: string | undefined, expected: string): boolean {