@opengeni/api-router 4.1.2 → 5.0.0-canary.36239117573001

package/dist/app.d.ts

@@ -22,7 +22,13 @@ export declare function appendVary(current: string | null, value: string): strin
 export declare function workspaceActorContextExempt(method: string, pathname: string): boolean;
 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;
 /**
  * State-changing OpenGeni HTTP calls must never cross an incompatible rollout
  * boundary. Standard third-party protocols and externally initiated callbacks

package/dist/app.js

@@ -24,7 +24,7 @@ import {
   withDefaultEnabledCapabilityMcpTools,
   workflowIdForSession,
   workspaceActorContextExempt
-} from "./chunk-2SSU5KWV.js";
+} from "./chunk-QDIBJSM4.js";
 export {
   API_MAX_REQUEST_BODY_BYTES,
   allowedCorsOrigin,

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.d.ts

@@ -1,6 +1,8 @@
 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 { Pool } from "pg";
 export type { ManagedAuth };
 export declare function managedAuthRequiresEmailVerification(settings: Pick<Settings, "environment">): boolean;
 export declare function managedAuthUserCreateOverride(settings: Pick<Settings, "environment">, user: {
@@ -16,7 +18,41 @@ export declare function managedAuthUserCreateAdmission(settings: Pick<Settings,
 /** 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>;
-export declare function createManagedAuth(settings: Settings, db: Database, managedEmailTransport: ManagedEmailTransport): ManagedAuth | null;
+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;
+}): ManagedAuth | null;
 export type ManagedAuthOAuthAttempt = {
     transactionId: string;
     provider: "google" | "github";

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