@opengeni/api-router 0.30.1 → 1.0.0

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

@@ -0,0 +1,3 @@
+import type { AccessGrant } from "@opengeni/contracts";
+import { type ApiRouteDeps } from "@opengeni/core";
+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/api-websocket.d.ts

@@ -0,0 +1,18 @@
+export type ApiWebSocketConnection = Readonly<{
+    attach(socket: ApiWebSocketLike): void;
+    receive(message: string | Uint8Array | ArrayBuffer): void;
+    transportClosed(): void;
+}>;
+export type ApiWebSocketLike = Readonly<{
+    data: ApiWebSocketConnection;
+    send(data: Uint8Array, compress?: boolean): number;
+    close(code?: number, reason?: string): void;
+    readonly bufferedAmount?: number;
+    getBufferedAmount?(): number;
+}>;
+export type ApiWebSocketUpgradeServer = Readonly<{
+    upgrade(request: Request, options: Readonly<{
+        data: ApiWebSocketConnection;
+        headers: HeadersInit;
+    }>): boolean;
+}>;

package/dist/app.d.ts

@@ -1,4 +1,5 @@
-import { type ErrorCode } from "@opengeni/contracts";
+import { type Settings } 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";
@@ -13,15 +14,62 @@ export declare function apiRequestBodyLimitBytes(settings: {
     voiceInputResumableMaxChunkSizeBytes?: number;
 }): number;
 export declare function createApp(deps: AppDependencies): Hono;
+export declare function resolveWorkspaceMcpRouteDeps(routeDeps: ApiRouteDeps, grant: AccessGrant): Promise<ApiRouteDeps>;
 export declare function createAppComposition(deps: AppDependencies): {
     app: Hono;
     routeDeps: ApiRouteDeps;
 };
 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: Pick<Settings, "defaultFirstPartyMcpTools" | "allowedFirstPartyMcpTools">, 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;
+/**
+ * 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

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,
@@ -12,6 +16,7 @@ import {
   mergeToolRefs,
   normalizeResources,
   replaySessionEvents,
+  resolveWorkspaceMcpRouteDeps,
   routeLabel,
   sseSessionStream,
   sseWorkspaceControlStream,
@@ -23,12 +28,17 @@ import {
   withDefaultEnabledCapabilityMcpTools,
   workflowIdForSession,
   workspaceActorContextExempt
-} from "./chunk-2PQMSRCB.js";
+} from "./chunk-6TZ5LG3O.js";
+import "./chunk-OGQDXVXY.js";
 export {
   API_MAX_REQUEST_BODY_BYTES,
+  REFUSED_API_CONTRACT_REVISIONS,
   allowedCorsOrigin,
+  apiContractAdmission,
   apiRequestBodyLimitBytes,
   appendVary,
+  assertConfiguredCodemodeSessionProxyPath,
+  configuredCodemodeSessionProxyTools,
   createApp,
   createAppComposition,
   errorCodeForStatus,
@@ -38,6 +48,7 @@ export {
   mergeToolRefs,
   normalizeResources,
   replaySessionEvents,
+  resolveWorkspaceMcpRouteDeps,
   routeLabel,
   sseSessionStream,
   sseWorkspaceControlStream,

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

@@ -0,0 +1,27 @@
+import { z } from "zod";
+declare const Cursor: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    snapshotAt: z.ZodString;
+    expiresAt: z.ZodNumber;
+    after: z.ZodObject<{
+        key: z.ZodString;
+        kind: z.ZodEnum<{
+            document: "document";
+            file: "file";
+            image: "image";
+            presentation: "presentation";
+            site: "site";
+            spreadsheet: "spreadsheet";
+        }>;
+        id: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type ArtifactCatalogCursor = z.infer<typeof Cursor>;
+/** Encrypted as well as authenticated: a scan frontier may name a denied row.
+ * Binding includes principal, workspace, owner context, permissions and filters.
+ */
+export declare function artifactCatalogCursorCodec(secret: string, binding: string): {
+    encode(value: ArtifactCatalogCursor): string;
+    decode(value: string): ArtifactCatalogCursor;
+};
+export {};

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

@@ -0,0 +1,10 @@
+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;
+export declare function currentManagedAuthAttemptId(): string | null;
+export declare function currentManagedAuthProviderId(): "credential" | "google" | "github";
+export declare function recordCurrentManagedAuthSession(authSessionId: string): void;
+export declare function currentManagedAuthCreatedSessionId(): string | null;
+export declare function shouldDiscardCurrentManagedAuthProviderSession(): boolean;

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

@@ -0,0 +1,6 @@
+import type { ManagedAuthSessionAdapter } from "@opengeni/core/managed-auth-session-sets";
+import type { Database } from "@opengeni/db";
+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;

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

@@ -1,5 +1,104 @@
-import type { Settings } from "@opengeni/config";
-import { type ManagedAuth } from "@opengeni/core";
+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 createManagedAuth(settings: Settings, db: Database): ManagedAuth | null;
+export declare function managedAuthRequiresEmailVerification(settings: Pick<Settings, "environment">): boolean;
+export declare function managedAuthUserCreateOverride(settings: Pick<Settings, "environment">, user: {
+    emailVerified: boolean;
+} & Record<string, unknown>): {
+    data: typeof user;
+} | undefined;
+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">>, 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 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";
+    authorityHash: string;
+    transactionSecretHash: string;
+    expectedGeneration: string;
+    expectedActorEpoch: string;
+};
+/**
+ * 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>;
+export declare function isolatedManagedAuthOAuthCallbackRequest(auth: ManagedAuth, request: Request): Promise<{
+    request: Request;
+    stateCookieName: string;
+}>;
+export declare function managedAuthOAuthReturnMatches(raw: string, expectedOrigin: string, transactionId: string, outcome: "complete" | "error"): boolean;
+export declare function sendManagedAuthEmail(transport: ManagedEmailTransport, input: Omit<ManagedEmailMessage, "from">): Promise<void>;

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

@@ -0,0 +1,29 @@
+import type { Settings } from "@opengeni/config";
+import type { ManagedEmailDeliveryResult, ManagedEmailMessage, ManagedEmailTransport } from "@opengeni/core";
+export type CapturedManagedEmail = ManagedEmailMessage & {
+    capturedAt: string;
+};
+/**
+ * Process-local test/development transport. Captures are count/TTL bounded and
+ * one-time readable; there is deliberately no route, disk, database, or log
+ * projection for message bodies or setup bearers.
+ */
+export declare class InMemoryManagedEmailTransport implements ManagedEmailTransport {
+    private readonly options;
+    private readonly messages;
+    readonly sender: string;
+    readonly idempotency: ManagedEmailTransport["idempotency"];
+    constructor(options?: {
+        maxMessages?: number;
+        ttlMs?: number;
+        now?: () => number;
+        sender?: string;
+        idempotency?: ManagedEmailTransport["idempotency"];
+    });
+    send(message: ManagedEmailMessage): Promise<ManagedEmailDeliveryResult>;
+    take(predicate: (message: CapturedManagedEmail) => boolean): CapturedManagedEmail | null;
+    size(): number;
+    private prune;
+    private now;
+}
+export declare function createManagedEmailTransport(settings: Settings): ManagedEmailTransport;

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/organization-user-setup.d.ts

@@ -0,0 +1,80 @@
+import type { Settings } from "@opengeni/config";
+import type { ManagedEmailTransport } from "@opengeni/core";
+export type OrganizationUserSetupEmailTokenTransport = "fragment" | "query";
+/**
+ * Prove that the stable invited-user setup bearer can be constructed before an
+ * invitation commits. Provider availability is intentionally outside this
+ * precondition: the durable delivery journal records a failed or ambiguous
+ * transport outcome after the invitation exists.
+ */
+export declare function assertOrganizationUserSetupDeliveryConfigured(settings: Settings, transport: ManagedEmailTransport): void;
+/** Enforce the query-bearing edge proof for env and embedded settings alike. */
+export declare function assertOrganizationUserSetupQueryTransportConfigured(settings: Pick<Settings, "organizationUserSetupEmailTokenTransport" | "organizationUserSetupQueryEdgeSanitizationConfirmed">): void;
+/** Reject an invalid embedded-provider contract before any durable boundary. */
+export declare function assertManagedEmailTransportMetadata(transport: ManagedEmailTransport): void;
+export declare function deriveOrganizationUserSetupToken(settings: Settings, input: {
+    invitationId: string;
+    deliveryId: string;
+    transport?: OrganizationUserSetupEmailTokenTransport;
+}): Promise<{
+    token: string;
+    digest: string;
+    url: string;
+}>;
+export type OrganizationUserSetupEmailSnapshot = {
+    senderEmail: string;
+    recipientEmail: string;
+    recipientName: string | null;
+    organizationName: string;
+    organizationRole: "owner" | "admin" | "member";
+    sharedWorkspaceAccess: Array<{
+        workspaceId: string;
+        workspaceName: string;
+        role: "viewer" | "member" | "admin";
+    }>;
+    setupUrl: string;
+};
+export declare function renderOrganizationUserSetupEmail(input: OrganizationUserSetupEmailSnapshot): {
+    from: string;
+    to: string;
+    subject: string;
+    text: string;
+    html: string;
+};
+export declare function organizationUserSetupPayloadDigest(input: {
+    from: string;
+    to: string;
+    subject: string;
+    text: string;
+    html: string;
+    providerIdempotencyScope: string;
+}): Promise<string>;
+export declare function resolveOrganizationUserSetupDeliveryEmail(settings: Settings, input: {
+    invitationId: string;
+    deliveryId: string;
+    senderEmail: string;
+    recipientEmail: string;
+    recipientName: string | null;
+    organizationName: string;
+    organizationRole: "owner" | "admin" | "member";
+    sharedWorkspaceAccess: OrganizationUserSetupEmailSnapshot["sharedWorkspaceAccess"];
+    providerIdempotencyScope: string;
+    frozenTransport: OrganizationUserSetupEmailTokenTransport | null;
+    frozenPayloadDigest: string | null;
+}): Promise<{
+    transport: OrganizationUserSetupEmailTokenTransport;
+    token: string;
+    tokenDigest: string;
+    payloadDigest: string;
+    message: ReturnType<typeof renderOrganizationUserSetupEmail>;
+}>;
+export declare function organizationUserSetupRequestFingerprint(settings: Settings, input: {
+    tokenDigest: string;
+    name: string;
+    password: string;
+}): Promise<string>;
+export declare function selfServiceOrganizationSetupRequestFingerprint(input: {
+    authUserId: string;
+    organizationName: string;
+}): Promise<string>;
+export declare function organizationUserSetupTokenDigest(token: string): Promise<string>;

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>;