@opengeni/api-router 3.0.1 → 3.0.2-canary.38894290271001

package/dist/access-grant-rls.d.ts

@@ -1,3 +1,10 @@
 import type { AccessGrant } from "@opengeni/contracts";
 import { type ApiRouteDeps } from "@opengeni/core";
-export declare function withAccessGrantSessionRlsContext<T>(deps: ApiRouteDeps, grant: AccessGrant, fn: () => Promise<T>): Promise<T>;
+import { type CreditDebitAttribution } from "@opengeni/db";
+/**
+ * Trusted payer for a non-agent grant: an authenticated human session pays as
+ * that human; keys and services are service work. An agent attempt must be
+ * resolved through the validated middleware context installed below.
+ */
+export declare function creditDebitAttributionForGrant(grant: AccessGrant): CreditDebitAttribution;
+export declare function withAccessGrantSessionRlsContext<T>(deps: Pick<ApiRouteDeps, "db">, grant: AccessGrant, fn: () => Promise<T>): Promise<T>;

package/dist/admission-trace.d.ts

@@ -0,0 +1,8 @@
+import type { Observability } from "@opengeni/observability";
+/** Only committed, non-replayed server event identities mint admission anchors. */
+export declare function recordAcceptedApiAdmission(observability: Observability | undefined, result: {
+    accepted: {
+        id: string;
+    };
+    replay: boolean;
+}): void;

package/dist/app.d.ts

@@ -1,4 +1,5 @@
-import { type AccessGrant, type ErrorCode } from "@opengeni/contracts";
+import { type FirstPartyMcpToolPolicySettings } from "@opengeni/config";
+import { type AccessGrant, type ErrorCode, type FirstPartyMcpToolName, type Session } from "@opengeni/contracts";
 import { Hono } from "hono";
 import type { ApiRouteDeps, AppDependencies } from "@opengeni/core";
 export { allowedCorsOrigin } from "./http/cors.js";
@@ -20,11 +21,57 @@ export declare function createAppComposition(deps: AppDependencies): {
 };
 export declare function appendVary(current: string | null, value: string): string;
 export declare function workspaceActorContextExempt(method: string, pathname: string): boolean;
+/** Configured SDK credentials cannot regain tools from widened legacy columns. */
+export declare function configuredCodemodeSessionProxyTools(settings: FirstPartyMcpToolPolicySettings, session: Pick<Session, "agent">): FirstPartyMcpToolName[] | null;
+/**
+ * Permissions span capabilities: project_create grants sessions:create,
+ * and runtime titling grants sessions:control. Fence the endpoint family
+ * too, without changing null-config routing or ordinary REST authorization.
+ */
+export declare function assertConfiguredCodemodeSessionProxyPath(session: Pick<Session, "id" | "agent">, path: string, method: string): void;
 export declare function httpStatusForError(error: unknown): number;
 export declare function errorCodeForStatus(status: number): ErrorCode;
-export declare function routeLabel(pathname: string): string;
 /**
- * State-changing OpenGeni HTTP calls must never cross an incompatible rollout
+ * Bounded route label for metrics, spans, and request logs. Explicit patterns
+ * keep established label spellings stable; any other request answered by a
+ * registered handler uses that handler's code-owned path template (see
+ * `registeredHandlerRoutePath`). Only unregistered paths fall into `unknown`.
+ */
+export declare function routeLabel(pathname: string, registeredRoutePath?: string | null): string;
+/**
+ * API contract revisions no longer admitted from ANY caller, including bearer
+ * integrations that would otherwise be accepted across revisions. Add a
+ * revision here only for a truly breaking wire change (which also requires a
+ * major release-train change); ordinary revision bumps stay additive.
+ */
+export declare const REFUSED_API_CONTRACT_REVISIONS: ReadonlySet<string>;
+/**
+ * The rollout fence for state-changing product calls.
+ *
+ * The exact-revision check exists to stop a stale first-party browser tab
+ * (cookie session, or unauthenticated local mode) from writing with an old
+ * request shape after a deployment; it answers 409 so the page reloads onto
+ * the matching bundle. That tab never sends `Authorization`, so this is not a
+ * header a stale bundle can choose to bypass it with.
+ *
+ * Bearer-authenticated callers (organization/workspace API keys, delegated
+ * tokens, the deployment key sent as a bearer) are integrations pinned to an
+ * SDK version: reloading cannot upgrade them, and the API is additive within a
+ * major release train. They are admitted with an older revision or with no
+ * revision claim at all. Only a revision listed in
+ * `REFUSED_API_CONTRACT_REVISIONS` is refused for them.
+ *
+ * This is a compatibility fence, not an authorization boundary: every route
+ * still authenticates and authorizes the request independently.
+ */
+export declare function apiContractAdmission(input: {
+    method: string;
+    pathname: string;
+    authorization: string | undefined;
+    claimedRevision: string | undefined;
+}, refusedRevisions?: ReadonlySet<string>): "admit" | "reject";
+/**
+ * State-changing Opengeni HTTP calls must never cross an incompatible rollout
  * boundary. Standard third-party protocols and externally initiated callbacks
  * are intentionally outside this product API contract.
  */

package/dist/app.js

@@ -1,8 +1,12 @@
 import {
   API_MAX_REQUEST_BODY_BYTES,
+  REFUSED_API_CONTRACT_REVISIONS,
   allowedCorsOrigin,
+  apiContractAdmission,
   apiRequestBodyLimitBytes,
   appendVary,
+  assertConfiguredCodemodeSessionProxyPath,
+  configuredCodemodeSessionProxyTools,
   createApp,
   createAppComposition,
   errorCodeForStatus,
@@ -24,12 +28,17 @@ import {
   withDefaultEnabledCapabilityMcpTools,
   workflowIdForSession,
   workspaceActorContextExempt
-} from "./chunk-AJ62T5QN.js";
+} from "./chunk-GBUJ2DYZ.js";
+import "./chunk-OGQDXVXY.js";
 export {
   API_MAX_REQUEST_BODY_BYTES,
+  REFUSED_API_CONTRACT_REVISIONS,
   allowedCorsOrigin,
+  apiContractAdmission,
   apiRequestBodyLimitBytes,
   appendVary,
+  assertConfiguredCodemodeSessionProxyPath,
+  configuredCodemodeSessionProxyTools,
   createApp,
   createAppComposition,
   errorCodeForStatus,

package/dist/artifact-catalog-cursor.d.ts

@@ -14,6 +14,7 @@ declare const Cursor: z.ZodObject<{
             spreadsheet: "spreadsheet";
         }>;
         id: z.ZodString;
+        pinned: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>;
 }, z.core.$strict>;
 export type ArtifactCatalogCursor = z.infer<typeof Cursor>;

package/dist/attached-browser-viewer.d.ts

@@ -0,0 +1,11 @@
+import type { AccessGrant } from "@opengeni/contracts";
+import { type ApiRouteDeps } from "@opengeni/core";
+import type { AttachedBrowserViewer } from "@opengeni/db";
+/**
+ * The person whose machine access decides which attached browsers a caller
+ * may see and control. Personal (Only me) machines belong to one person, so a
+ * human sees and controls their own; an agent acts for the person who started
+ * its turn (never merely for the workspace). Other callers (keys, services)
+ * reach only machines that are not personal.
+ */
+export declare function attachedBrowserViewer(deps: Pick<ApiRouteDeps, "db">, grant: AccessGrant, workspaceId: string): Promise<AttachedBrowserViewer>;

package/dist/auth/managed-auth-attempt-context.d.ts

@@ -1,3 +1,5 @@
+export declare function runManagedSignInConnect<T>(intentId: string, action: () => T): T;
+export declare function currentManagedSignInConnectIntent(): string | undefined;
 export declare function runManagedAuthAttempt<T>(transactionId: string, providerId: "credential" | "google" | "github", action: () => T): T;
 export declare function runManagedAuthProvider<T>(providerId: "credential" | "google" | "github", action: () => T): T;
 export declare function runManagedAuthDiscardedProviderSession<T>(action: () => T): T;

package/dist/auth/managed-auth-rate-limits.d.ts

@@ -0,0 +1,167 @@
+import type { Database } from "@opengeni/db";
+import { APIError } from "better-auth/api";
+export type ManagedAuthClientRateLimitRule = {
+    window: number;
+    max: number;
+};
+/**
+ * Better Auth's per-client-address limits, keyed by endpoint path relative to
+ * `/v1/auth`. The client address is the trusted source address stamped by the
+ * API (see `TRUSTED_CLIENT_ADDRESS_HEADER`), never a caller-supplied header.
+ *
+ * Better Auth keys each counter on `(client address, path)` and resets it only
+ * after `window` seconds pass without an admitted request. Its database store
+ * prunes rows idle for longer than 60 s, so no window here exceeds 60 s; a
+ * longer window would silently shrink to that pruning horizon. The limits are
+ * sized for launch traffic that shares one address (office and carrier NAT)
+ * while bounding scripted credential guessing and mail sending from one
+ * source. Per-email throttles below cap the same abuse across many addresses.
+ *
+ * Email sign-in and sign-up allow 20 per minute, at least Better Auth's
+ * previous default (3 per 10 s, about 18 per minute). Until the edge forwards
+ * real client addresses (for example ingress-nginx behind a cloud load
+ * balancer with `externalTrafficPolicy: Cluster`), every user shares a few
+ * node addresses, and these two limits then bound the whole deployment's
+ * email sign-in and sign-up rate; they must not fall below that default.
+ */
+export declare const MANAGED_AUTH_CLIENT_RATE_LIMIT_RULES: {
+    readonly "/sign-in/email": {
+        readonly window: 60;
+        readonly max: 20;
+    };
+    readonly "/sign-up/email": {
+        readonly window: 60;
+        readonly max: 20;
+    };
+    readonly "/sign-in/social": {
+        readonly window: 60;
+        readonly max: 20;
+    };
+    readonly "/callback/*": {
+        readonly window: 60;
+        readonly max: 30;
+    };
+    readonly "/request-password-reset": {
+        readonly window: 60;
+        readonly max: 5;
+    };
+    readonly "/send-verification-email": {
+        readonly window: 60;
+        readonly max: 5;
+    };
+    readonly "/verify-email": {
+        readonly window: 60;
+        readonly max: 20;
+    };
+    readonly "/reset-password": {
+        readonly window: 60;
+        readonly max: 10;
+    };
+    readonly "/reset-password/*": {
+        readonly window: 60;
+        readonly max: 20;
+    };
+};
+export type ManagedAuthEmailThrottle = {
+    purpose: "sign_in" | "sign_up" | "password_reset" | "verification_email";
+    windowSeconds: number;
+    /** Attempts one client address (an IPv6 /64) may make against one email. */
+    perSourceMax: number;
+    /** Attempts all client addresses together may make against one email. */
+    perEmailMax: number;
+};
+/**
+ * Per-email throttles for the endpoints that verify a password or send mail
+ * to an address. They bound password guessing against one account and mail
+ * bombing of one inbox regardless of how many client addresses an attacker
+ * rotates through. Every attempt counts, including successful sign-ins.
+ *
+ * Each email has two fixed windows. The tight one is per (email, client
+ * address); an attempt it refuses never reaches the looser per-email window.
+ * One source can therefore spend only its own share of an email's budget:
+ * locking a person out of email/password sign-in, sign-up, password reset, or
+ * verification mail takes at least `perEmailMax / perSourceMax` (5) distinct
+ * client addresses (IPv6: /64 blocks) inside the window, while one address
+ * can exhaust that email's budget only for requests from the same address.
+ * Social sign-in is never throttled per email. The accepted cost is that a
+ * distributed attacker may make up to `perEmailMax` attempts per window
+ * against one email, and can deny that email's password sign-in for the rest
+ * of the window once it spends them.
+ */
+export declare const MANAGED_AUTH_EMAIL_THROTTLES: {
+    readonly "/sign-in/email": {
+        readonly purpose: "sign_in";
+        readonly windowSeconds: number;
+        readonly perSourceMax: 10;
+        readonly perEmailMax: 50;
+    };
+    readonly "/sign-up/email": {
+        readonly purpose: "sign_up";
+        readonly windowSeconds: number;
+        readonly perSourceMax: 5;
+        readonly perEmailMax: 25;
+    };
+    readonly "/request-password-reset": {
+        readonly purpose: "password_reset";
+        readonly windowSeconds: number;
+        readonly perSourceMax: 5;
+        readonly perEmailMax: 25;
+    };
+    readonly "/send-verification-email": {
+        readonly purpose: "verification_email";
+        readonly windowSeconds: number;
+        readonly perSourceMax: 5;
+        readonly perEmailMax: 25;
+    };
+};
+export declare const MANAGED_AUTH_EMAIL_THROTTLE_KEY_PREFIX = "opengeni:email-throttle:v1:";
+/** A per-email throttle refusal; an ordinary Better Auth 429 on the wire. */
+export declare class ManagedAuthEmailThrottleError extends APIError {
+    readonly retryAfterSeconds: number;
+    constructor(retryAfterSeconds: number);
+}
+export declare function managedAuthEmailThrottleFor(path: string): ManagedAuthEmailThrottle | null;
+/**
+ * Content-free counter key for one email. The address is normalized the way
+ * Better Auth stores it and keyed-hashed so the rate-limit table never holds
+ * an email.
+ */
+export declare function managedAuthEmailThrottleKey(secret: string, purpose: ManagedAuthEmailThrottle["purpose"], email: string): string;
+/**
+ * Content-free counter key for one (email, client address) pair; `source` is
+ * a {@link requestSourceRateLimitKey}. Neither value is stored.
+ */
+export declare function managedAuthEmailSourceThrottleKey(secret: string, purpose: ManagedAuthEmailThrottle["purpose"], email: string, source: string): string;
+/**
+ * The limiter source for a Better Auth request: the trusted address the API
+ * stamped on it, as a rate-limit key. The API strips caller-supplied copies,
+ * so a request without one (an in-process call without a transport peer)
+ * shares the unknown-source bucket.
+ */
+export declare function managedAuthThrottleSource(headers: Headers | null | undefined): string;
+/**
+ * Atomically count one attempt in a fixed window shared by every API replica.
+ *
+ * Rows live in Better Auth's `auth_rate_limits` table. For these keys
+ * `last_request` holds the window deadline (epoch milliseconds) rather than
+ * the last request time: Better Auth prunes rows whose `last_request` is more
+ * than 60 s in the past, so storing the deadline keeps an active window alive
+ * and lets pruning reclaim it 60 s after it expires. Database time is the only
+ * clock, so replicas with skewed clocks agree.
+ */
+export declare function consumeManagedAuthEmailThrottle(db: Pick<Database, "execute">, input: {
+    key: string;
+    windowSeconds: number;
+    max: number;
+}): Promise<{
+    allowed: boolean;
+    retryAfterSeconds: number;
+}>;
+/**
+ * Better Auth `hooks.before` middleware. It runs after Better Auth's own
+ * per-client-address limiter and for both HTTP requests and server-side
+ * `auth.api.*` calls, so the product session-set sign-in is covered too. The
+ * per-(email, address) window is consumed first; only an attempt it admits
+ * counts toward the email's shared window.
+ */
+export declare function createManagedAuthEmailThrottleHook(db: Pick<Database, "execute">, secret: string): (inputContext: import("better-auth").MiddlewareInputContext<import("better-auth").MiddlewareOptions>) => Promise<void>;

package/dist/auth/managed-auth-session-adapter.d.ts

@@ -1,4 +1,12 @@
 import type { ManagedAuthSessionAdapter } from "@opengeni/core/managed-auth-session-sets";
 import type { Database } from "@opengeni/db";
-import type { ManagedAuth } from "@opengeni/core";
+import { type ManagedAuth } from "@opengeni/core";
+/** Server-only proof for a product-owned endpoint; never returned to a browser. */
+export declare function managedAuthSelectedProofHeaders(auth: ManagedAuth, token: string): Promise<Headers>;
 export declare function createBetterAuthSessionAdapter(auth: ManagedAuth, db: Database): ManagedAuthSessionAdapter;
+/**
+ * The provider's own session cookie for an exact session token (or its
+ * expiry when `token` is null), plus invalidation of stale provider cache
+ * cookies, exactly as a browser sign-in would set them.
+ */
+export declare function managedAuthSessionCookieHeaders(auth: ManagedAuth, token: string | null, currentCookieHeader?: string | null): Promise<string[]>;

package/dist/auth/managed-auth.d.ts

@@ -1,21 +1,88 @@
 import { type Settings } from "@opengeni/config";
 import { type ManagedAuth, type ManagedEmailMessage, type ManagedEmailTransport } from "@opengeni/core";
 import type { Database } from "@opengeni/db";
+import type { Observability } from "@opengeni/observability";
+import { APIError } from "better-auth/api";
+import { Pool } from "pg";
+import { type ManagedAuthNewSignupsGate } from "./new-signups-gate.js";
 export type { ManagedAuth };
-export declare function managedAuthRequiresEmailVerification(settings: Pick<Settings, "environment">): boolean;
-export declare function managedAuthUserCreateOverride(settings: Pick<Settings, "environment">, user: {
+export declare function managedAuthRequiresEmailVerification(settings: Pick<Settings, "environment" | "managedAuthRequireEmailVerification">): boolean;
+export declare function managedAuthUserCreateOverride(settings: Pick<Settings, "environment" | "managedAuthRequireEmailVerification">, user: {
     emailVerified: boolean;
 } & Record<string, unknown>): {
     data: typeof user;
 } | undefined;
-export declare function managedAuthUserCreateAdmission(settings: Pick<Settings, "environment">, user: {
+export declare const MANAGED_AUTH_NEW_SIGNUPS_PAUSED_MESSAGE = "We're at capacity for new accounts right now. Please try again later.";
+/**
+ * Typed refusal for a new account while the deployment has paused sign-ups.
+ * Existing accounts are unaffected; the body mirrors Better Auth's
+ * `{ code, message }` error shape so browser and SDK callers parse it alike.
+ */
+export declare function managedAuthNewSignupsPausedResponse(): Response;
+/**
+ * Thrown from the user-create hook while the runtime switch has paused new
+ * sign-ups. Better Auth returns it as `403 { code: "NEW_SIGNUPS_PAUSED" }` on
+ * email sign-up, and its OAuth callback turns the message into the
+ * `error=signup_disabled` redirect it also uses for a static provider refusal.
+ */
+export declare class ManagedAuthNewSignupsPausedError extends APIError {
+    constructor();
+}
+export declare function managedAuthUserCreateAdmission(settings: Pick<Settings, "environment" | "allowedUserEmails"> & Partial<Pick<Settings, "managedAuthNewSignupsEnabled" | "managedAuthRequireEmailVerification">>, user: {
     emailVerified: boolean;
 } & Record<string, unknown>, providerId: string): {
     data: typeof user;
 } | false | undefined;
+/**
+ * Per-provider Better Auth options while sign-ups are paused. A social sign-in
+ * for an existing human still signs in (and may link a verified provider);
+ * an unknown human is redirected back with `error=signup_disabled`.
+ * `disableSignUp` is the hard switch: `disableImplicitSignUp` alone can be
+ * overridden by a client-supplied `requestSignUp`.
+ */
+export declare function managedAuthSocialSignupOptions(settings: Pick<Settings, "managedAuthNewSignupsEnabled">): {
+    disableImplicitSignUp?: true;
+    disableSignUp?: true;
+};
 /** Keep Better Auth password policy and storage format behind this boundary. */
 export declare function hashManagedAuthPassword(password: string): Promise<string>;
-export declare function createManagedAuth(settings: Settings, db: Database, managedEmailTransport: ManagedEmailTransport): ManagedAuth | null;
+export declare function verifyManagedAuthPassword(password: string, hash: string): Promise<boolean>;
+type ManagedAuthPoolObservability = Pick<Observability, "warn" | "incrementCounter">;
+/**
+ * Bounded pool settings for Better Auth's dedicated `pg` pool. A connection
+ * attempt fails after 10 s instead of queueing requests indefinitely while the
+ * database is unreachable, and connections recycle like the main postgres-js
+ * pool so a pooler- or failover-replaced backend is not held forever.
+ */
+export declare const MANAGED_AUTH_DATABASE_POOL_OPTIONS: {
+    readonly max: 10;
+    readonly connectionTimeoutMillis: 10000;
+    readonly idleTimeoutMillis: 30000;
+    readonly maxLifetimeSeconds: 1800;
+    readonly keepAlive: true;
+};
+/**
+ * Better Auth's `pg` pool. When the server closes a connection (a restart,
+ * failover, or maintenance window) `pg` emits `error`: on the pool for an idle
+ * client, and on the client itself for one checked out by Better Auth's query
+ * layer. Without listeners either becomes an uncaught exception and the API's
+ * fatal process boundary exits. Both listeners record one content-free signal
+ * and keep serving. The pool has already discarded a failed idle client and
+ * opens a fresh connection for the next checkout; a checked-out client's
+ * in-flight query already rejects to its caller, and the pool discards the
+ * dead client on release. An idle client's error also reaches its own
+ * listener, so that listener records only while the client is checked out,
+ * and at most once per checkout.
+ */
+export declare function createManagedAuthDatabasePool(databaseUrl: string, observability?: ManagedAuthPoolObservability): Pool;
+export declare const MANAGED_AUTH_DATABASE_POOL_ERRORS_METRIC: {
+    readonly name: "opengeni_managed_auth_database_pool_errors_total";
+    readonly help: "Managed-auth database connections the server closed or lost, by pool state.";
+};
+export declare function createManagedAuth(settings: Settings, db: Database, managedEmailTransport: ManagedEmailTransport, options?: {
+    observability?: ManagedAuthPoolObservability;
+    newSignupsGate?: ManagedAuthNewSignupsGate;
+}): ManagedAuth | null;
 export type ManagedAuthOAuthAttempt = {
     transactionId: string;
     provider: "google" | "github";
@@ -25,7 +92,7 @@ export type ManagedAuthOAuthAttempt = {
     expectedActorEpoch: string;
 };
 /**
- * Resolve OpenGeni's server-only login transaction proof from Better Auth's
+ * Resolve Opengeni's server-only login transaction proof from Better Auth's
  * database-backed OAuth state before the provider callback consumes it.
  */
 export declare function resolveManagedAuthOAuthAttempt(auth: ManagedAuth, request: Request, provider: "google" | "github", publicBaseUrl: string): Promise<ManagedAuthOAuthAttempt | null>;

package/dist/auth/managed-sign-in-notifications.d.ts

@@ -0,0 +1,4 @@
+import type { ManagedEmailTransport } from "@opengeni/core";
+import type { Database } from "@opengeni/db";
+export declare function deliverManagedSignInNotification(db: Database, transport: ManagedEmailTransport, operationId?: string | null): Promise<"sent" | "failed" | "outcome_unknown">;
+export declare function startManagedSignInNotificationDelivery(db: Database, transport: ManagedEmailTransport): void;

package/dist/auth/new-signups-gate.d.ts

@@ -0,0 +1,23 @@
+import type { Settings } from "@opengeni/config";
+import { type Database } from "@opengeni/db";
+import type { Observability } from "@opengeni/observability";
+/**
+ * Decides whether a new managed account may be created right now.
+ *
+ * `OPENGENI_MANAGED_AUTH_NEW_SIGNUPS_ENABLED` is the deployment ceiling (read at
+ * startup). While it allows sign-ups, the newest revision of the operator
+ * runtime switch (migration 0585) decides, read on every call so a flip
+ * applies to the next request on every API replica without a restart.
+ *
+ * Fail-safe: if the read fails, the last value this process observed wins;
+ * before any successful read, the deployment ceiling wins. A missing revision
+ * (pre-0585 schema) also follows the ceiling.
+ */
+export type ManagedAuthNewSignupsGate = {
+    signupsOpen(): Promise<boolean>;
+};
+export declare function createManagedAuthNewSignupsGate(input: {
+    db: Database;
+    settings: Pick<Settings, "managedAuthNewSignupsEnabled">;
+    observability?: Pick<Observability, "warn"> | undefined;
+}): ManagedAuthNewSignupsGate;

package/dist/auth/signup-funnel-metrics.d.ts

@@ -0,0 +1,44 @@
+import type { Observability } from "@opengeni/observability";
+/**
+ * Content-free sign-up funnel counters. Every label is a closed set: no user,
+ * email, organization, workspace, or campaign value ever becomes a label.
+ */
+export declare const AUTH_FUNNEL_EVENTS: readonly ["sign_up", "email_verified", "sign_in"];
+export type AuthFunnelEvent = (typeof AUTH_FUNNEL_EVENTS)[number];
+export declare const AUTH_FUNNEL_METHODS: readonly ["email", "google", "github", "other"];
+export type AuthFunnelMethod = (typeof AUTH_FUNNEL_METHODS)[number];
+export declare const ORGANIZATION_SETUP_OUTCOMES: readonly ["created", "failed"];
+export type OrganizationSetupOutcome = (typeof ORGANIZATION_SETUP_OUTCOMES)[number];
+/** The only observability surface funnel telemetry uses. */
+export type SignupFunnelObservability = Pick<Observability, "incrementCounter">;
+/** Better Auth request-body / OAuth-state key that carries first-touch attribution. */
+export declare const SIGNUP_ATTRIBUTION_AUTH_FIELD = "opengeniAttribution";
+export type SignupFunnelMetrics = {
+    /** A managed auth user was created (Better Auth `user.create.after`). */
+    recordSignUp(authContext: unknown): Promise<void>;
+    /** A managed user verified their email address. */
+    recordEmailVerified(): void;
+    /**
+     * A provider session was created that is not an internally discarded one.
+     * In the legacy session-set mode this includes the session the first
+     * successful email-verification click creates: that is the new user's first
+     * sign-in, so it is counted rather than folded into `email_verified`.
+     */
+    recordSignIn(): void;
+};
+export declare function authFunnelMethod(providerId: string | null | undefined): AuthFunnelMethod;
+/**
+ * Publish every closed series at zero so dashboards and alerts can tell a quiet
+ * funnel from missing instrumentation. Never throws: a metric-registry failure
+ * must not stop managed auth (and with it API startup) from composing.
+ */
+export declare function registerSignupFunnelMetricBaselines(observability: SignupFunnelObservability): void;
+export declare function createSignupFunnelMetrics(observability: SignupFunnelObservability): SignupFunnelMetrics;
+/** Count one self-service organization setup request outcome. */
+export declare function recordOrganizationSetupOutcome(observability: SignupFunnelObservability | undefined, outcome: OrganizationSetupOutcome): void;
+/**
+ * Read untrusted first-touch attribution from the Better Auth endpoint that is
+ * creating the user: the email sign-up body, or the server-side OAuth state
+ * (`additionalData`) that the social start stored for its callback.
+ */
+export declare function signupAttributionFromAuthContext(authContext: unknown): Promise<unknown>;

package/dist/azure-live.d.ts

@@ -0,0 +1,28 @@
+import type { Settings } from "@opengeni/config";
+import type { CodexRealtimeWebrtcRequest } from "@opengeni/contracts";
+import { type Database } from "@opengeni/db";
+export declare const AZURE_LIVE_MODEL_ID: "opengeni-azure/gpt-live-1";
+export declare function azureLiveConfigured(settings: Settings): boolean;
+/** Server-authenticated SDP exchange. Never returns provider credentials. */
+export declare function brokerAzureLive(input: {
+    settings: Settings;
+    request: Pick<CodexRealtimeWebrtcRequest, "sdp" | "instructions" | "voice">;
+    initialItems: Array<{
+        role: string;
+        text: string;
+    }>;
+    signal?: AbortSignal | undefined;
+    fetch?: typeof fetch;
+}): Promise<{
+    sdp: string;
+    version: "v3";
+    model: "opengeni-azure/gpt-live-1";
+}>;
+export declare function buildSessionAzureLiveBroker(db: Database, settings: Settings, workspaceId: string, sessionId: string, fetchImpl?: typeof fetch): (input: {
+    request: Pick<CodexRealtimeWebrtcRequest, "sdp" | "instructions" | "voice">;
+    signal?: AbortSignal | undefined;
+}) => Promise<{
+    sdp: string;
+    version: "v3";
+    model: "opengeni-azure/gpt-live-1";
+}>;

package/dist/browser-action-fences.d.ts

@@ -0,0 +1,13 @@
+import type { BrowserActionRequest, BrowserTargetState } from "@opengeni/contracts";
+export type BrowserActionFences = {
+    expectedTargetGeneration: string;
+    expectedDocumentGeneration: string | null;
+    expectedFrameId: string | null;
+};
+/**
+ * Complete a browser action's causal fences. Supplied fences are kept exactly;
+ * any omitted one is the target's current value, read from the live controller
+ * only when needed. This keeps the "act on the current document" request to
+ * one API round trip instead of a separate target-state request before it.
+ */
+export declare function resolveBrowserActionFences(request: Pick<BrowserActionRequest, "expectedTargetGeneration" | "expectedDocumentGeneration" | "expectedFrameId">, readTargetState: () => Promise<Pick<BrowserTargetState, "targetGeneration" | "documentGeneration" | "frameId">>): Promise<BrowserActionFences>;

package/dist/browser-controller-authority.d.ts

@@ -1,61 +1 @@
-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 declare function deriveBrowserControllerAdminToken(scope: BrowserControllerAuthorityScope): string;
-/** 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 declare function deriveBrowserSessionControllerTokens(scope: BrowserSessionAuthorityScope): {
-    controlToken: string;
-    viewToken: string;
-};
-/** 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 declare 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;
-export declare function deriveBrowserViewGrantToken(scope: BrowserSessionAuthorityScope & {
-    grantId: string;
-    expiresAt: string;
-}): string;
-/** ComputerSession credentials share the placement controller root while using
- * resource-specific domains. Browser and computer authority cannot collide. */
-export declare function deriveComputerSessionControllerTokens(scope: ComputerSessionAuthorityScope): {
-    controlToken: string;
-    viewToken: string;
-};
-export declare function deriveComputerViewGrantToken(scope: ComputerSessionAuthorityScope & {
-    grantId: string;
-    expiresAt: string;
-}): string;
-export {};
+export * from "@opengeni/interaction/browser-controller-authority";

package/dist/browser-ephemeral.d.ts

@@ -0,0 +1,5 @@
+import type { BrowserSession, CreateBrowserSessionRequest } from "@opengeni/contracts";
+export declare function assertEphemeralBrowserCreateEnabled(request: CreateBrowserSessionRequest, enabled: boolean): void;
+/** Only persisted session identity and server-resolved physical placement enter
+ * this private controller partition. Public callers never supply a pool key. */
+export declare function ephemeralBrowserPartition(session: BrowserSession, placementInstanceId: string, rootSecret: string): string;

package/dist/browser-lost-runtime-end.d.ts

@@ -0,0 +1,24 @@
+import { type BrowserControlClient } from "@opengeni/runtime/sandbox";
+type BrowserEndClient = Pick<BrowserControlClient, "endSession">;
+/** A person ending a browser. When the browser's controller lost the running
+ * browser (it restarted, or the runtime vanished) it preserves the working
+ * runtime and refuses a plain end; the person's explicit end then discards
+ * it. Cleanup after a failed or expired resume never takes this path, so a
+ * possibly accepted launch stays preserved there. Controllers older than the
+ * discard flag reject it as an unknown field and keep their original refusal. */
+export declare function endBrowserDiscardingLostRuntime(client: BrowserEndClient, reference: {
+    browserSessionId: string;
+    controllerGeneration: string;
+}): Promise<void>;
+/** Return an expired resume to its checkpoint. A plain end of the expired
+ * generation succeeds when its launch provably never happened (or is already
+ * gone). When the controller instead preserves an interrupted launch (one that
+ * never recorded completion, so it can't be adopted), it is asked to move that
+ * launch's directory aside intact; nothing is discarded, and a launch that did
+ * complete, or whose profile may still be in use, keeps refusing. Controllers
+ * older than the set-aside flag reject it and keep their original refusal. */
+export declare function endExpiredResumeSettingAsideInterruptedLaunch(client: BrowserEndClient, reference: {
+    browserSessionId: string;
+    controllerGeneration: string;
+}): Promise<void>;
+export {};