@opengeni/api-router 3.0.1 → 3.1.2

package/src/auth/managed-auth.ts

@@ -1,5 +1,8 @@
-import { canonicalPublicOrigin, type Settings } from "@opengeni/config";
+import { canonicalPublicOrigin, managedUserEmailAllowed, type Settings } from "@opengeni/config";
+import { MANAGED_AUTH_NEW_SIGNUPS_PAUSED_CODE } from "@opengeni/contracts";
 import {
+  configureManagedUserAdmission,
+  recordManagedAuthLoggedFailure,
   type ManagedAuth,
   type ManagedEmailMessage,
   type ManagedEmailTransport,
@@ -12,20 +15,37 @@ 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 } from "better-auth/crypto";
+import { APIError, 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 {
+  createManagedAuthNewSignupsGate,
+  type ManagedAuthNewSignupsGate,
+} from "./new-signups-gate";
+import { createSignupFunnelMetrics } from "./signup-funnel-metrics";
 import {
   currentManagedAuthProviderId,
   currentManagedAuthAttemptId,
   recordCurrentManagedAuthSession,
   shouldDiscardCurrentManagedAuthProviderSession,
+  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
@@ -33,26 +53,61 @@ import {
 export type { ManagedAuth };
 
 export function managedAuthRequiresEmailVerification(
-  settings: Pick<Settings, "environment">,
+  settings: Pick<Settings, "environment" | "managedAuthRequireEmailVerification">,
 ): boolean {
-  return settings.environment !== "local";
+  return settings.managedAuthRequireEmailVerification ?? settings.environment !== "local";
 }
 
 export function managedAuthUserCreateOverride(
-  settings: Pick<Settings, "environment">,
+  settings: Pick<Settings, "environment" | "managedAuthRequireEmailVerification">,
   user: { emailVerified: boolean } & Record<string, unknown>,
 ): { data: typeof user } | undefined {
   if (managedAuthRequiresEmailVerification(settings)) return undefined;
   return { data: { ...user, emailVerified: true } };
 }
 
+export 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 function managedAuthNewSignupsPausedResponse(): Response {
+  return Response.json(
+    {
+      code: MANAGED_AUTH_NEW_SIGNUPS_PAUSED_CODE,
+      message: MANAGED_AUTH_NEW_SIGNUPS_PAUSED_MESSAGE,
+    },
+    { status: 403, headers: { "cache-control": "no-store" } },
+  );
+}
+
+/**
+ * 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 class ManagedAuthNewSignupsPausedError extends APIError {
+  constructor() {
+    super("FORBIDDEN", { code: MANAGED_AUTH_NEW_SIGNUPS_PAUSED_CODE, message: "signup disabled" });
+  }
+}
+
 export function managedAuthUserCreateAdmission(
-  settings: Pick<Settings, "environment">,
+  settings: Pick<Settings, "environment" | "allowedUserEmails"> &
+    Partial<Pick<Settings, "managedAuthNewSignupsEnabled" | "managedAuthRequireEmailVerification">>,
   user: { emailVerified: boolean } & Record<string, unknown>,
   providerId: string,
 ): { data: typeof user } | false | undefined {
+  // Backstop for every Better Auth user-create path. Invited-user account
+  // setup does not create users through Better Auth, so it is unaffected.
+  if (settings.managedAuthNewSignupsEnabled === false) return false;
+  if (!managedUserEmailAllowed(settings.allowedUserEmails, user.email)) return false;
   if (
-    managedAuthRequiresEmailVerification(settings) &&
+    (settings.environment !== "local" || managedAuthRequiresEmailVerification(settings)) &&
     providerId !== "credential" &&
     !user.emailVerified
   ) {
@@ -61,29 +116,168 @@ export function managedAuthUserCreateAdmission(
   return managedAuthUserCreateOverride(settings, user);
 }
 
+/**
+ * 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 function managedAuthSocialSignupOptions(
+  settings: Pick<Settings, "managedAuthNewSignupsEnabled">,
+): { disableImplicitSignUp?: true; disableSignUp?: true } {
+  return settings.managedAuthNewSignupsEnabled
+    ? {}
+    : { disableImplicitSignUp: true, disableSignUp: true };
+}
+
 /** Keep Better Auth password policy and storage format behind this boundary. */
 export async function hashManagedAuthPassword(password: string): Promise<string> {
   return await hashPassword(password);
 }
 
+export async function verifyManagedAuthPassword(password: string, hash: string): Promise<boolean> {
+  return await verifyPassword({ password, hash });
+}
+
+type ManagedAuthPoolObservability = Pick<Observability, "warn" | "incrementCounter">;
+
+/**
+ * Better Auth's default console output, plus handing logged failures to the
+ * session-lookup boundary so a lost database connection behind its generic
+ * INTERNAL_SERVER_ERROR stays recognizable (see `withManagedAuthSessionLookup`).
+ */
+function logBetterAuthMessage(
+  level: "debug" | "info" | "warn" | "error",
+  message: string,
+  ...args: unknown[]
+): void {
+  if (level === "error") recordManagedAuthLoggedFailure(args);
+  const line = `${new Date().toISOString()} ${level.toUpperCase()} [Better Auth]: ${message}`;
+  if (level === "error") console.error(line, ...args);
+  else if (level === "warn") console.warn(line, ...args);
+  else console.log(line, ...args);
+}
+
+/**
+ * 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;
+    newSignupsGate?: ManagedAuthNewSignupsGate;
+  } = {},
 ): 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 });
-  return betterAuth({
-    appName: "OpenGeni",
+  const pool = createManagedAuthDatabasePool(settings.databaseUrl, options.observability);
+  // The deployment ceiling is static Better Auth configuration; the runtime
+  // switch is checked per user create in the hook below.
+  const newSignupsSocialProviderOptions = managedAuthSocialSignupOptions(settings);
+  const newSignupsGate =
+    options.newSignupsGate ??
+    createManagedAuthNewSignupsGate({ db, settings, observability: options.observability });
+  const auth = betterAuth({
+    appName: "Opengeni",
     baseURL: betterAuthBaseUrl(settings),
     basePath: "/v1/auth",
     secret: settings.betterAuthSecret,
     database: pool,
     trustedOrigins: betterAuthTrustedOrigins(settings),
+    logger: { log: logBetterAuthMessage },
+    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
         ? {
@@ -104,6 +298,7 @@ export function createManagedAuth(
       fields: {
         lastRequest: "last_request",
       },
+      customRules: MANAGED_AUTH_CLIENT_RATE_LIMIT_RULES,
     },
     user: {
       modelName: "auth_users",
@@ -180,7 +375,18 @@ export function createManagedAuth(
         updatedAt: "updated_at",
       },
       accountLinking: {
-        enabled: false,
+        enabled: true,
+        requireLocalEmailVerified: true,
+        trustedProviders: [],
+        allowDifferentEmails: false,
+      },
+      additionalFields: {
+        managedLinkIntentId: {
+          type: "string",
+          fieldName: "managed_link_intent_id",
+          input: false,
+          returned: false,
+        },
       },
       encryptOAuthTokens: true,
       storeStateStrategy: "database",
@@ -192,6 +398,7 @@ export function createManagedAuth(
               clientId: settings.managedAuthGoogleClientId,
               clientSecret: settings.managedAuthGoogleClientSecret,
               prompt: "select_account" as const,
+              ...newSignupsSocialProviderOptions,
             },
           }
         : {}),
@@ -200,6 +407,7 @@ export function createManagedAuth(
             github: {
               clientId: settings.managedAuthGithubClientId,
               clientSecret: settings.managedAuthGithubClientSecret,
+              ...newSignupsSocialProviderOptions,
             },
           }
         : {}),
@@ -215,45 +423,48 @@ export function createManagedAuth(
     },
     emailAndPassword: {
       enabled: true,
+      // Sign-in, password reset, and verification stay enabled; only new
+      // account creation is refused while sign-ups are paused.
+      disableSignUp: !settings.managedAuthNewSignupsEnabled,
       // Local managed mode exists so the complete human/org tenancy flow can
       // be exercised without first configuring a transactional-email vendor.
-      // Every non-local deployment retains the verified-email boundary.
+      // Non-local deployments require verification unless explicitly overridden.
       requireEmailVerification,
       revokeSessionsOnPasswordReset: true,
       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 }) => {
         await sendManagedAuthEmail(managedEmailTransport, {
           kind: "password_reset",
           to: user.email,
-          subject: "Reset your OpenGeni password",
-          text: `Reset your OpenGeni password: ${url}`,
-          html: `<p>Reset your OpenGeni password:</p><p><a href="${escapeHtml(url)}">Reset password</a></p>`,
+          subject: "Reset your Opengeni password",
+          text: `Reset your Opengeni password: ${url}`,
+          html: `<p>Reset your Opengeni password:</p><p><a href="${escapeHtml(url)}">Reset password</a></p>`,
         });
       },
     },
     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,
@@ -264,9 +475,41 @@ export function createManagedAuth(
       },
     },
     databaseHooks: {
+      account: {
+        create: {
+          before: async (account) => ({
+            data: {
+              ...account,
+              ...(currentManagedSignInConnectIntent()
+                ? { managedLinkIntentId: currentManagedSignInConnectIntent() }
+                : {}),
+            },
+          }),
+          after: async (account) => {
+            if (
+              !["google", "github"].includes(account.providerId) ||
+              currentManagedSignInConnectIntent()
+            )
+              return;
+            await deliverManagedSignInNotification(db, managedEmailTransport, account.id);
+          },
+        },
+      },
       session: {
         create: {
           before: async (session) => {
+            if (settings.allowedUserEmails !== undefined) {
+              const result = await pool.query<{ email: string; email_verified: boolean }>(
+                "select email, email_verified from auth_users where id = $1",
+                [session.userId],
+              );
+              const user = result.rows[0];
+              if (
+                !user?.email_verified ||
+                !managedUserEmailAllowed(settings.allowedUserEmails, user.email)
+              )
+                return false;
+            }
             const providerId = currentManagedAuthProviderId();
             await ensureCanonicalHumanIdentityForAuthUser(db, session.userId);
             const preflightProjection = await getCanonicalHumanIdentityProjection(
@@ -357,6 +600,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}`);
@@ -365,9 +609,18 @@ export function createManagedAuth(
       },
       user: {
         create: {
-          before: async (user) =>
-            managedAuthUserCreateAdmission(settings, user, currentManagedAuthProviderId()),
-          after: async (user) => {
+          before: async (user) => {
+            const admission = managedAuthUserCreateAdmission(
+              settings,
+              user,
+              currentManagedAuthProviderId(),
+            );
+            if (admission === false) return false;
+            if (!(await newSignupsGate.signupsOpen())) throw new ManagedAuthNewSignupsPausedError();
+            return admission;
+          },
+          after: async (user, context) => {
+            await funnel?.recordSignUp(context);
             if (!user.emailVerified) return;
             await ensureManagedAccessForUser(db, {
               userId: user.id,
@@ -381,6 +634,8 @@ export function createManagedAuth(
       },
     },
   }) as ManagedAuth;
+  configureManagedUserAdmission(auth, settings.allowedUserEmails);
+  return auth;
 }
 
 export type ManagedAuthOAuthAttempt = {
@@ -393,7 +648,7 @@ export type ManagedAuthOAuthAttempt = {
 };
 
 /**
- * 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 async function resolveManagedAuthOAuthAttempt(
@@ -533,6 +788,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/managed-email.ts

@@ -33,7 +33,7 @@ export class InMemoryManagedEmailTransport implements ManagedEmailTransport {
       idempotency?: ManagedEmailTransport["idempotency"];
     } = {},
   ) {
-    this.sender = options.sender ?? "OpenGeni <auth@mail.opengeni.ai>";
+    this.sender = options.sender ?? "Opengeni <auth@mail.opengeni.ai>";
     this.idempotency = options.idempotency ?? {
       scope: "opengeni-in-memory-v1",
       retentionSeconds: 86_400,
@@ -88,6 +88,20 @@ class UnconfiguredManagedEmailTransport implements ManagedEmailTransport {
   }
 }
 
+/** Operator-selected OPENGENI_MANAGED_EMAIL_DELIVERY=disabled: never contacts a provider. */
+class DisabledManagedEmailTransport implements ManagedEmailTransport {
+  readonly idempotency = {
+    scope: "opengeni-disabled-v1",
+    retentionSeconds: 0,
+  } as const;
+
+  constructor(readonly sender: string) {}
+
+  async send(): Promise<ManagedEmailDeliveryResult> {
+    return { status: "failed", errorClass: "delivery_disabled" };
+  }
+}
+
 class ResendManagedEmailTransport implements ManagedEmailTransport {
   private readonly client: Resend;
   readonly idempotency: ManagedEmailTransport["idempotency"];
@@ -144,6 +158,9 @@ class ResendManagedEmailTransport implements ManagedEmailTransport {
 }
 
 export function createManagedEmailTransport(settings: Settings): ManagedEmailTransport {
+  if (settings.managedEmailDelivery === "disabled") {
+    return new DisabledManagedEmailTransport(settings.emailFrom);
+  }
   if (settings.resendApiKey) {
     if (!settings.betterAuthSecret) {
       throw new Error("OPENGENI_BETTER_AUTH_SECRET is required for managed email delivery");

package/src/auth/managed-sign-in-notifications.ts

@@ -0,0 +1,81 @@
+import type { ManagedEmailTransport } from "@opengeni/core";
+import type { Database } from "@opengeni/db";
+import { sql } from "drizzle-orm";
+import { z } from "zod";
+
+const Claim = z.object({
+  operationId: z.string().uuid(),
+  leaseId: z.string().uuid(),
+  email: z.string().email(),
+  provider: z.enum(["password", "google", "github"]),
+  sender: z.string(),
+});
+const started = new WeakSet<object>();
+
+export async function deliverManagedSignInNotification(
+  db: Database,
+  transport: ManagedEmailTransport,
+  operationId: string | null = null,
+): Promise<"sent" | "failed" | "outcome_unknown"> {
+  try {
+    const result = await db.execute(
+      sql`select claim_managed_sign_in_notification(${operationId}::uuid,${transport.sender},${transport.idempotency.scope},${transport.idempotency.retentionSeconds}::integer) as claim`,
+    );
+    const row = (Array.isArray(result) ? result : result.rows)[0] as { claim: unknown } | undefined;
+    if (!row?.claim) return "outcome_unknown";
+    const claim = Claim.parse(row.claim);
+    let status: "sent" | "failed" | "outcome_unknown" = "outcome_unknown";
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      const response = await Promise.race([
+        transport.send({
+          kind: "sign_in_method_changed",
+          from: claim.sender,
+          to: claim.email,
+          idempotencyKey: `sign-in-method:${claim.operationId}`,
+          subject: "Your Opengeni sign-in methods changed",
+          text: `Your Opengeni ${claim.provider} sign-in method changed. If this was not you, reset your password and contact your administrator.`,
+          html: `<p>Your Opengeni ${claim.provider} sign-in method changed. If this was not you, reset your password and contact your administrator.</p>`,
+        }),
+        new Promise<{ status: "outcome_unknown" }>((resolve) => {
+          timer = setTimeout(() => resolve({ status: "outcome_unknown" }), 5_000);
+        }),
+      ]);
+      status = response.status;
+    } catch {
+      /* Retain the durable unknown claim for idempotent retry. */
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+    await db.execute(
+      sql`select settle_managed_sign_in_notification(${claim.operationId}::uuid,${claim.leaseId}::uuid,${status})`,
+    );
+    return status;
+  } catch {
+    // Security state is already committed. A failed claim/ack must never be
+    // reported as a failed method change; its durable obligation remains live.
+    return "outcome_unknown";
+  }
+}
+
+export function startManagedSignInNotificationDelivery(
+  db: Database,
+  transport: ManagedEmailTransport,
+): void {
+  if (started.has(db as object)) return;
+  started.add(db as object);
+  let active = false;
+  const drain = async () => {
+    if (active) return;
+    active = true;
+    try {
+      for (let count = 0; count < 10; count++)
+        if ((await deliverManagedSignInNotification(db, transport)) === "outcome_unknown") break;
+    } finally {
+      active = false;
+    }
+  };
+  const timer = setInterval(() => void drain(), 60_000);
+  (timer as ReturnType<typeof setInterval> & { unref?: () => void }).unref?.();
+  void drain();
+}

package/src/auth/new-signups-gate.ts

@@ -0,0 +1,49 @@
+import type { Settings } from "@opengeni/config";
+import { readManagedAuthNewSignupsSwitch, 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 function createManagedAuthNewSignupsGate(input: {
+  db: Database;
+  settings: Pick<Settings, "managedAuthNewSignupsEnabled">;
+  observability?: Pick<Observability, "warn"> | undefined;
+}): ManagedAuthNewSignupsGate {
+  const ceiling = input.settings.managedAuthNewSignupsEnabled !== false;
+  let lastKnown: boolean | null = null;
+  return {
+    async signupsOpen() {
+      if (!ceiling) return false;
+      try {
+        const current = await readManagedAuthNewSignupsSwitch(input.db);
+        lastKnown = current ? current.signupsEnabled : true;
+        return lastKnown;
+      } catch (error) {
+        try {
+          input.observability?.warn("Managed auth new signups switch read failed", {
+            dependency: "managed_auth_new_signups_switch",
+            fallback: lastKnown === null ? "deployment_ceiling" : "last_known",
+            errorClass: error instanceof Error ? error.name : "UnknownError",
+          });
+        } catch {
+          // An observer failure must not decide a sign-up.
+        }
+        return lastKnown ?? ceiling;
+      }
+    },
+  };
+}