@opengeni/api-router 4.1.0 → 4.1.2-canary.36199476632001

package/src/auth/managed-auth.ts

@@ -12,14 +12,21 @@ import {
   getCanonicalHumanExactLoginBindingForAuthUser,
   synchronizeCanonicalHumanLoginBindings,
 } from "@opengeni/db/canonical-human-identities";
+import type { Observability } from "@opengeni/observability";
 import { betterAuth } from "better-auth";
 import { createEmailVerificationToken } from "better-auth/api";
 import { hashPassword, verifyPassword } from "better-auth/crypto";
 import { sql } from "drizzle-orm";
-import { Pool } from "pg";
+import { Pool, type PoolConfig } from "pg";
 
+import { TRUSTED_CLIENT_ADDRESS_HEADER } from "../http/request-source";
 import { decideCanonicalHumanSessionAdmission } from "./canonical-human-session-admission";
+import {
+  createManagedAuthEmailThrottleHook,
+  MANAGED_AUTH_CLIENT_RATE_LIMIT_RULES,
+} from "./managed-auth-rate-limits";
 import { deliverManagedSignInNotification } from "./managed-sign-in-notifications";
+import { createSignupFunnelMetrics } from "./signup-funnel-metrics";
 import {
   currentManagedAuthProviderId,
   currentManagedAuthAttemptId,
@@ -28,6 +35,10 @@ import {
   currentManagedSignInConnectIntent,
 } from "./managed-auth-attempt-context";
 
+// Only used when no Better Auth secret is configured (local development);
+// the email throttle key is a content-free digest either way.
+const MANAGED_AUTH_EMAIL_THROTTLE_FALLBACK_KEY = "opengeni:managed-auth:email-throttle:local";
+
 // `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
@@ -72,16 +83,94 @@ export async function verifyManagedAuthPassword(password: string, hash: string):
   return await verifyPassword({ password, hash });
 }
 
+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 const MANAGED_AUTH_DATABASE_POOL_OPTIONS = {
+  max: 10,
+  connectionTimeoutMillis: 10_000,
+  idleTimeoutMillis: 30_000,
+  maxLifetimeSeconds: 1_800,
+  keepAlive: true,
+} as const satisfies PoolConfig;
+
+/**
+ * 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 function createManagedAuthDatabasePool(
+  databaseUrl: string,
+  observability?: ManagedAuthPoolObservability,
+): Pool {
+  const pool = new Pool({ connectionString: databaseUrl, ...MANAGED_AUTH_DATABASE_POOL_OPTIONS });
+  const checkedOut = new WeakSet<object>();
+  pool.on("acquire", (client) => checkedOut.add(client));
+  pool.on("release", (_error, client) => checkedOut.delete(client));
+  pool.on("connect", (client) => {
+    client.on("error", () => {
+      // One lost connection can emit twice (the server's termination
+      // message, then the socket end), so count it once.
+      if (checkedOut.delete(client)) {
+        recordManagedAuthPoolError(observability, "checked_out_connection_failed");
+      }
+    });
+  });
+  pool.on("error", () => recordManagedAuthPoolError(observability, "idle_connection_discarded"));
+  return pool;
+}
+
+export const MANAGED_AUTH_DATABASE_POOL_ERRORS_METRIC = {
+  name: "opengeni_managed_auth_database_pool_errors_total",
+  help: "Managed-auth database connections the server closed or lost, by pool state.",
+} as const;
+
+function recordManagedAuthPoolError(
+  observability: ManagedAuthPoolObservability | undefined,
+  outcome: "idle_connection_discarded" | "checked_out_connection_failed",
+): void {
+  try {
+    observability?.incrementCounter({
+      ...MANAGED_AUTH_DATABASE_POOL_ERRORS_METRIC,
+      labels: { outcome },
+    });
+    observability?.warn("Managed auth database connection failed", {
+      dependency: "managed_auth_database",
+      outcome,
+    });
+  } catch {
+    // An observer failure must not turn a recovered pool error into a crash.
+  }
+}
+
 export function createManagedAuth(
   settings: Settings,
   db: Database,
   managedEmailTransport: ManagedEmailTransport,
+  options: { observability?: ManagedAuthPoolObservability } = {},
 ): ManagedAuth | null {
   if (settings.productAccessMode !== "managed") {
     return null;
   }
+  // Content-free sign-up funnel counters; recording never fails an auth flow.
+  const funnel = options.observability
+    ? createSignupFunnelMetrics(options.observability)
+    : undefined;
   const requireEmailVerification = managedAuthRequiresEmailVerification(settings);
-  const pool = new Pool({ connectionString: settings.databaseUrl });
+  const pool = createManagedAuthDatabasePool(settings.databaseUrl, options.observability);
   return betterAuth({
     appName: "OpenGeni",
     baseURL: betterAuthBaseUrl(settings),
@@ -89,7 +178,22 @@ export function createManagedAuth(
     secret: settings.betterAuthSecret,
     database: pool,
     trustedOrigins: betterAuthTrustedOrigins(settings),
+    hooks: {
+      before: createManagedAuthEmailThrottleHook(
+        db,
+        settings.betterAuthSecret ?? MANAGED_AUTH_EMAIL_THROTTLE_FALLBACK_KEY,
+      ),
+    },
     advanced: {
+      // Better Auth reads client addresses only from request headers. The API
+      // strips this header from every inbound request and re-stamps it on
+      // managed-auth routes with the trusted source address (transport peer,
+      // or the forwarded client when OPENGENI_API_TRUSTED_PROXY_HOPS declares
+      // a proxy chain), so callers cannot choose their rate-limit bucket or
+      // recorded session address.
+      ipAddress: {
+        ipAddressHeaders: [TRUSTED_CLIENT_ADDRESS_HEADER],
+      },
       useSecureCookies: settings.publicBaseUrl?.startsWith("https://") ?? false,
       ...(settings.betterAuthCookieDomain
         ? {
@@ -110,6 +214,7 @@ export function createManagedAuth(
       fields: {
         lastRequest: "last_request",
       },
+      customRules: MANAGED_AUTH_CLIENT_RATE_LIMIT_RULES,
     },
     user: {
       modelName: "auth_users",
@@ -240,13 +345,10 @@ export function createManagedAuth(
       onExistingUserSignUp: async ({ user }) => {
         if (requireEmailVerification && !user.emailVerified) {
           const url = await verificationUrl(settings, user.email);
-          await sendManagedAuthEmail(managedEmailTransport, {
-            kind: "email_verification",
-            to: user.email,
-            subject: "Verify your OpenGeni email",
-            text: `Verify your OpenGeni email: ${url}`,
-            html: `<p>Verify your OpenGeni email:</p><p><a href="${escapeHtml(url)}">Verify email</a></p>`,
-          });
+          await sendManagedAuthEmail(
+            managedEmailTransport,
+            emailVerificationMessage(user.email, url),
+          );
         }
       },
       sendResetPassword: async ({ user, url }) => {
@@ -261,16 +363,19 @@ export function createManagedAuth(
     },
     emailVerification: {
       sendOnSignUp: requireEmailVerification,
+      // The first successful verification link click signs the user in (a
+      // reused link creates no session). Only legacy mode: session-set modes
+      // bind sign-in to an isolated browser transaction, and the provider
+      // session this would create is discarded there by design.
+      autoSignInAfterVerification: settings.managedAuthSessionSetMode === "legacy",
       sendVerificationEmail: async ({ user, url }) => {
-        await sendManagedAuthEmail(managedEmailTransport, {
-          kind: "email_verification",
-          to: user.email,
-          subject: "Verify your OpenGeni email",
-          text: `Verify your OpenGeni email: ${url}`,
-          html: `<p>Verify your OpenGeni email:</p><p><a href="${escapeHtml(url)}">Verify email</a></p>`,
-        });
+        await sendManagedAuthEmail(
+          managedEmailTransport,
+          emailVerificationMessage(user.email, url),
+        );
       },
       afterEmailVerification: async (user) => {
+        funnel?.recordEmailVerified();
         await ensureManagedAccessForUser(db, {
           userId: user.id,
           email: user.email,
@@ -394,6 +499,7 @@ export function createManagedAuth(
             };
           },
           after: async (session) => {
+            funnel?.recordSignIn();
             recordCurrentManagedAuthSession(session.id);
             if (!shouldDiscardCurrentManagedAuthProviderSession()) return;
             await db.execute(sql`delete from auth_sessions where id = ${session.id}`);
@@ -404,7 +510,8 @@ export function createManagedAuth(
         create: {
           before: async (user) =>
             managedAuthUserCreateAdmission(settings, user, currentManagedAuthProviderId()),
-          after: async (user) => {
+          after: async (user, context) => {
+            await funnel?.recordSignUp(context);
             if (!user.emailVerified) return;
             await ensureManagedAccessForUser(db, {
               userId: user.id,
@@ -570,6 +677,19 @@ export async function sendManagedAuthEmail(
   if (result.status !== "sent") throw new Error(`managed email ${result.status}`);
 }
 
+// Verification can sign the clicker in (autoSignInAfterVerification), so an
+// unsolicited verification email must say plainly that it can be ignored.
+function emailVerificationMessage(to: string, url: string): Omit<ManagedEmailMessage, "from"> {
+  const ignore = "If you did not create an OpenGeni account, ignore this email.";
+  return {
+    kind: "email_verification",
+    to,
+    subject: "Verify your OpenGeni email",
+    text: `Verify your OpenGeni email: ${url}\n\n${ignore}`,
+    html: `<p>Verify your OpenGeni email:</p><p><a href="${escapeHtml(url)}">Verify email</a></p><p>${ignore}</p>`,
+  };
+}
+
 async function verificationUrl(settings: Settings, email: string): Promise<string> {
   if (!settings.betterAuthSecret) {
     throw new Error(

package/src/auth/signup-funnel-metrics.ts

@@ -0,0 +1,164 @@
+import {
+  SIGNUP_ACQUISITION_SOURCES,
+  signupAcquisitionSource,
+  type SignupAcquisitionSource,
+} from "@opengeni/contracts";
+import type { Observability } from "@opengeni/observability";
+import { getOAuthState } from "better-auth/api";
+
+import {
+  currentManagedAuthProviderId,
+  shouldDiscardCurrentManagedAuthProviderSession,
+} from "./managed-auth-attempt-context";
+
+/**
+ * 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 const AUTH_FUNNEL_EVENTS = ["sign_up", "email_verified", "sign_in"] as const;
+export type AuthFunnelEvent = (typeof AUTH_FUNNEL_EVENTS)[number];
+export const AUTH_FUNNEL_METHODS = ["email", "google", "github", "other"] as const;
+export type AuthFunnelMethod = (typeof AUTH_FUNNEL_METHODS)[number];
+export const ORGANIZATION_SETUP_OUTCOMES = ["created", "failed"] as const;
+export type OrganizationSetupOutcome = (typeof ORGANIZATION_SETUP_OUTCOMES)[number];
+
+const AUTH_EVENTS_METRIC = {
+  name: "opengeni_auth_events_total",
+  help: "Managed authentication funnel events (sign-up, email verification, sign-in) by closed method.",
+} as const;
+const ORGANIZATION_SETUP_METRIC = {
+  name: "opengeni_organization_setup_total",
+  help: "Self-service post-sign-in organization setup outcomes.",
+} as const;
+const SIGNUP_ACQUISITION_METRIC = {
+  name: "opengeni_signup_acquisition_total",
+  help: "New managed users by normalized first-touch acquisition source.",
+} as const;
+
+/** 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 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 function authFunnelMethod(providerId: string | null | undefined): AuthFunnelMethod {
+  if (providerId === "credential") return "email";
+  if (providerId === "google" || providerId === "github") return providerId;
+  return "other";
+}
+
+/**
+ * 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 function registerSignupFunnelMetricBaselines(
+  observability: SignupFunnelObservability,
+): void {
+  const baseline = (
+    metric: { name: string; help: string },
+    labels: Record<string, string>,
+  ): void => {
+    try {
+      observability.incrementCounter({ ...metric, labels, amount: 0 });
+    } catch {
+      // Telemetry only; the series appears on its first real increment.
+    }
+  };
+  for (const event of AUTH_FUNNEL_EVENTS) {
+    for (const method of AUTH_FUNNEL_METHODS) baseline(AUTH_EVENTS_METRIC, { event, method });
+  }
+  for (const outcome of ORGANIZATION_SETUP_OUTCOMES) {
+    baseline(ORGANIZATION_SETUP_METRIC, { outcome });
+  }
+  for (const source of SIGNUP_ACQUISITION_SOURCES) baseline(SIGNUP_ACQUISITION_METRIC, { source });
+}
+
+export function createSignupFunnelMetrics(
+  observability: SignupFunnelObservability,
+): SignupFunnelMetrics {
+  registerSignupFunnelMetricBaselines(observability);
+  const authEvent = (event: AuthFunnelEvent, method: AuthFunnelMethod) => {
+    observability.incrementCounter({ ...AUTH_EVENTS_METRIC, labels: { event, method } });
+  };
+  return {
+    recordSignUp: async (authContext) => {
+      try {
+        authEvent("sign_up", authFunnelMethod(currentManagedAuthProviderId()));
+        const source: SignupAcquisitionSource = signupAcquisitionSource(
+          await signupAttributionFromAuthContext(authContext),
+        );
+        observability.incrementCounter({ ...SIGNUP_ACQUISITION_METRIC, labels: { source } });
+      } catch {
+        // Funnel telemetry must never fail account creation.
+      }
+    },
+    recordEmailVerified: () => {
+      try {
+        authEvent("email_verified", "email");
+      } catch {
+        /* Telemetry only. */
+      }
+    },
+    recordSignIn: () => {
+      try {
+        // Session-set mode discards the provider session of a non-callback
+        // Better Auth call; the product transaction then creates the real one.
+        if (shouldDiscardCurrentManagedAuthProviderSession()) return;
+        authEvent("sign_in", authFunnelMethod(currentManagedAuthProviderId()));
+      } catch {
+        /* Telemetry only. */
+      }
+    },
+  };
+}
+
+/** Count one self-service organization setup request outcome. */
+export function recordOrganizationSetupOutcome(
+  observability: SignupFunnelObservability | undefined,
+  outcome: OrganizationSetupOutcome,
+): void {
+  try {
+    observability?.incrementCounter({ ...ORGANIZATION_SETUP_METRIC, labels: { outcome } });
+  } catch {
+    // Telemetry must never change the setup response.
+  }
+}
+
+/**
+ * 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 async function signupAttributionFromAuthContext(authContext: unknown): Promise<unknown> {
+  const body =
+    authContext && typeof authContext === "object"
+      ? (authContext as { body?: unknown }).body
+      : undefined;
+  if (body && typeof body === "object" && SIGNUP_ATTRIBUTION_AUTH_FIELD in body) {
+    return (body as Record<string, unknown>)[SIGNUP_ATTRIBUTION_AUTH_FIELD];
+  }
+  try {
+    const state: unknown = await getOAuthState();
+    if (state && typeof state === "object" && SIGNUP_ATTRIBUTION_AUTH_FIELD in state) {
+      return (state as Record<string, unknown>)[SIGNUP_ATTRIBUTION_AUTH_FIELD];
+    }
+  } catch {
+    // Not inside a Better Auth OAuth callback.
+  }
+  return undefined;
+}

package/src/http/auth.ts

@@ -1,6 +1,7 @@
 import { resolveFirstPartyDelegationSecret, type Settings } from "@opengeni/config";
 import { verifyDelegatedAccessToken } from "@opengeni/contracts";
 import type { Context, MiddlewareHandler } from "hono";
+import { CLIENT_ERRORS_PATH } from "../routes/client-errors";
 import { installExactPaths, isInstallRedirectPath } from "../routes/install";
 import {
   isMcpOAuthPublicProtocolPath,
@@ -47,6 +48,11 @@ function isAuthExempt(c: Context, settings: Settings): boolean {
   if (path === "/v1/config/client") {
     return true;
   }
+  // The web error beacon must count failures before sign-in. Its payload is a
+  // closed, content-free report and the route bounds its own admission.
+  if (c.req.method === "POST" && path === CLIENT_ERRORS_PATH) {
+    return true;
+  }
   if (path === "/v1/auth" || path.startsWith("/v1/auth/")) {
     return true;
   }

package/src/http/cors.ts

@@ -26,13 +26,45 @@ export function validateInteractionRequestOrigin(
   ) {
     throw new HTTPException(400, { message: "invalid request origin" });
   }
-  if (
-    allowedCorsOrigin(input.corsAllowOriginRegex, url.origin) ||
+  if (isConfiguredBrowserOrigin(url.origin, input)) {
+    return url.origin;
+  }
+  throw new HTTPException(403, { message: "request origin is not allowed" });
+}
+
+type BrowserOriginSettings = {
+  corsAllowOriginRegex: string;
+  publicBaseUrl?: string | undefined;
+  webBaseUrl?: string | undefined;
+};
+
+function isConfiguredBrowserOrigin(origin: string, input: BrowserOriginSettings): boolean {
+  return (
+    allowedCorsOrigin(input.corsAllowOriginRegex, origin) ||
     [input.publicBaseUrl, input.webBaseUrl].some((baseUrl) =>
-      baseUrl ? new URL(baseUrl).origin === url.origin : false,
+      baseUrl ? new URL(baseUrl).origin === origin : false,
     )
+  );
+}
+
+/**
+ * Whether a present `Origin` header names a browser origin this deployment
+ * serves its web app from: the CORS allowlist, the public base URL, or the
+ * separate web base URL. `null` and malformed values are never allowed.
+ */
+export function isAllowedBrowserOrigin(value: string, input: BrowserOriginSettings): boolean {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    return false;
+  }
+  if (
+    url.origin === "null" ||
+    (url.protocol !== "http:" && url.protocol !== "https:") ||
+    url.origin !== value
   ) {
-    return url.origin;
+    return false;
   }
-  throw new HTTPException(403, { message: "request origin is not allowed" });
+  return isConfiguredBrowserOrigin(url.origin, input);
 }