@opengeni/api-router 0.30.3 → 1.0.0

package/src/auth/managed-auth.ts

@@ -1,18 +1,49 @@
-import type { Settings } from "@opengeni/config";
-import { type ManagedAuth } from "@opengeni/core";
+import { canonicalPublicOrigin, managedUserEmailAllowed, type Settings } from "@opengeni/config";
+import { MANAGED_AUTH_NEW_SIGNUPS_PAUSED_CODE } from "@opengeni/contracts";
+import {
+  configureManagedUserAdmission,
+  type ManagedAuth,
+  type ManagedEmailMessage,
+  type ManagedEmailTransport,
+} from "@opengeni/core";
 import type { Database } from "@opengeni/db";
 import { ensureManagedAccessForUser } from "@opengeni/db";
 import {
   ensureCanonicalHumanIdentityForAuthUser,
   getCanonicalHumanIdentityProjection,
+  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 { Pool } from "pg";
-import { Resend } from "resend";
+import { APIError, createEmailVerificationToken } from "better-auth/api";
+import { hashPassword, verifyPassword } from "better-auth/crypto";
+import { sql } from "drizzle-orm";
+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
@@ -20,19 +51,214 @@ import { decideCanonicalHumanSessionAdmission } from "./canonical-human-session-
 // importers (`app.ts`) keep the same import path.
 export type { ManagedAuth };
 
-export function createManagedAuth(settings: Settings, db: Database): ManagedAuth | null {
+export function managedAuthRequiresEmailVerification(
+  settings: Pick<Settings, "environment">,
+): boolean {
+  return settings.environment !== "local";
+}
+
+export function managedAuthUserCreateOverride(
+  settings: Pick<Settings, "environment">,
+  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" | "allowedUserEmails"> &
+    Partial<Pick<Settings, "managedAuthNewSignupsEnabled">>,
+  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) &&
+    providerId !== "credential" &&
+    !user.emailVerified
+  ) {
+    return false;
+  }
+  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">;
+
+/**
+ * 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;
   }
-  const pool = new Pool({ connectionString: settings.databaseUrl });
-  return betterAuth({
-    appName: "OpenGeni",
+  // 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 = 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),
+    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
         ? {
@@ -53,6 +279,7 @@ export function createManagedAuth(settings: Settings, db: Database): ManagedAuth
       fields: {
         lastRequest: "last_request",
       },
+      customRules: MANAGED_AUTH_CLIENT_RATE_LIMIT_RULES,
     },
     user: {
       modelName: "auth_users",
@@ -93,6 +320,25 @@ export function createManagedAuth(settings: Settings, db: Database): ManagedAuth
           returned: false,
           bigint: true,
         },
+        loginBindingId: {
+          type: "string",
+          fieldName: "login_binding_id",
+          input: false,
+          returned: false,
+        },
+        loginBindingRevision: {
+          type: "number",
+          fieldName: "login_binding_revision",
+          input: false,
+          returned: false,
+          bigint: true,
+        },
+        managedAuthLoginTransactionId: {
+          type: "string",
+          fieldName: "managed_auth_login_transaction_id",
+          input: false,
+          returned: false,
+        },
       },
     },
     account: {
@@ -110,8 +356,42 @@ export function createManagedAuth(settings: Settings, db: Database): ManagedAuth
         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",
+    },
+    socialProviders: {
+      ...(settings.managedAuthGoogleClientId && settings.managedAuthGoogleClientSecret
+        ? {
+            google: {
+              clientId: settings.managedAuthGoogleClientId,
+              clientSecret: settings.managedAuthGoogleClientSecret,
+              prompt: "select_account" as const,
+              ...newSignupsSocialProviderOptions,
+            },
+          }
+        : {}),
+      ...(settings.managedAuthGithubClientId && settings.managedAuthGithubClientSecret
+        ? {
+            github: {
+              clientId: settings.managedAuthGithubClientId,
+              clientSecret: settings.managedAuthGithubClientSecret,
+              ...newSignupsSocialProviderOptions,
+            },
+          }
+        : {}),
     },
     verification: {
       modelName: "auth_verifications",
@@ -124,50 +404,94 @@ export function createManagedAuth(settings: Settings, db: Database): ManagedAuth
     },
     emailAndPassword: {
       enabled: true,
-      requireEmailVerification: 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.
+      requireEmailVerification,
       revokeSessionsOnPasswordReset: true,
       onExistingUserSignUp: async ({ user }) => {
-        if (!user.emailVerified) {
+        if (requireEmailVerification && !user.emailVerified) {
           const url = await verificationUrl(settings, user.email);
-          await sendEmail(settings, {
-            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 sendEmail(settings, {
+        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: true,
+      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 sendEmail(settings, {
-          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,
           name: user.name,
+          emailVerified: true,
+          provisionFallbackOrganization: false,
         });
       },
     },
     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(
               db,
@@ -179,8 +503,13 @@ export function createManagedAuth(settings: Settings, db: Database): ManagedAuth
               binding: null,
             });
             if (!preflight.allowed) {
+              const exactRecoveryBinding = await getCanonicalHumanExactLoginBindingForAuthUser(db, {
+                authUserId: session.userId,
+                providerId,
+              });
               const recoveryBinding = preflightProjection.loginBindings.find(
-                (binding) => binding.status === "recovery_pending",
+                (binding) =>
+                  binding.id === exactRecoveryBinding.id && binding.status === "recovery_pending",
               );
               const recoveryAdmission = decideCanonicalHumanSessionAdmission({
                 intent: "recovery_completion",
@@ -199,17 +528,27 @@ export function createManagedAuth(settings: Settings, db: Database): ManagedAuth
               return {
                 data: {
                   ...session,
+                  ...(shouldDiscardCurrentManagedAuthProviderSession()
+                    ? { expiresAt: new Date(0) }
+                    : {}),
                   identityId: preflightProjection.activeIdentity.id,
                   identityRevision: preflightProjection.activeIdentity.identityRevision,
                   authRevision: preflightProjection.activeIdentity.authRevision,
+                  loginBindingId: recoveryBinding!.id,
+                  loginBindingRevision: recoveryBinding!.revision,
+                  managedAuthLoginTransactionId: currentManagedAuthAttemptId(),
                 },
               };
             }
 
             await synchronizeCanonicalHumanLoginBindings(db, session.userId);
             const projection = await getCanonicalHumanIdentityProjection(db, session.userId);
+            const exactBinding = await getCanonicalHumanExactLoginBindingForAuthUser(db, {
+              authUserId: session.userId,
+              providerId,
+            });
             const activeBinding = projection.loginBindings.find(
-              (binding) => binding.id === projection.activeIdentity.activeLoginBindingId,
+              (binding) => binding.id === exactBinding.id,
             );
             const admission = decideCanonicalHumanSessionAdmission({
               intent: "ordinary_session",
@@ -229,27 +568,174 @@ export function createManagedAuth(settings: Settings, db: Database): ManagedAuth
             return {
               data: {
                 ...session,
+                ...(shouldDiscardCurrentManagedAuthProviderSession()
+                  ? { expiresAt: new Date(0) }
+                  : {}),
                 identityId: projection.activeIdentity.id,
                 identityRevision: projection.activeIdentity.identityRevision,
                 authRevision: projection.activeIdentity.authRevision,
+                loginBindingId: exactBinding.id,
+                loginBindingRevision: exactBinding.revision,
+                managedAuthLoginTransactionId: currentManagedAuthAttemptId(),
               },
             };
           },
+          after: async (session) => {
+            funnel?.recordSignIn();
+            recordCurrentManagedAuthSession(session.id);
+            if (!shouldDiscardCurrentManagedAuthProviderSession()) return;
+            await db.execute(sql`delete from auth_sessions where id = ${session.id}`);
+          },
         },
       },
       user: {
         create: {
-          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,
               email: user.email,
               name: user.name,
+              emailVerified: true,
+              provisionFallbackOrganization: false,
             });
           },
         },
       },
     },
   }) as ManagedAuth;
+  configureManagedUserAdmission(auth, settings.allowedUserEmails);
+  return auth;
+}
+
+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 async function resolveManagedAuthOAuthAttempt(
+  auth: ManagedAuth,
+  request: Request,
+  provider: "google" | "github",
+  publicBaseUrl: string,
+): Promise<ManagedAuthOAuthAttempt | null> {
+  const expectedOrigin = canonicalPublicOrigin(publicBaseUrl);
+  if (!expectedOrigin) return null;
+  const state = new URL(request.url).searchParams.get("state");
+  if (!state) return null;
+  const verification = await (await auth.$context).internalAdapter.findVerificationValue(state);
+  if (!verification?.value) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(verification.value);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") return null;
+  const stateData = parsed as Record<string, unknown>;
+  const proof = stateData.opengeniManagedAuth;
+  if (!proof || typeof proof !== "object") return null;
+  const value = proof as Record<string, unknown>;
+  if (
+    value.version !== 1 ||
+    value.provider !== provider ||
+    typeof value.transactionId !== "string" ||
+    typeof value.authorityHash !== "string" ||
+    typeof value.transactionSecretHash !== "string" ||
+    typeof value.expectedGeneration !== "string" ||
+    typeof value.expectedActorEpoch !== "string" ||
+    !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu.test(
+      value.transactionId,
+    ) ||
+    !/^[0-9a-f]{64}$/u.test(value.authorityHash) ||
+    !/^[0-9a-f]{64}$/u.test(value.transactionSecretHash) ||
+    !/^[1-9][0-9]*$/u.test(value.expectedGeneration) ||
+    !/^[1-9][0-9]*$/u.test(value.expectedActorEpoch)
+  ) {
+    return null;
+  }
+  const callbackURL = typeof stateData.callbackURL === "string" ? stateData.callbackURL : null;
+  const errorURL = typeof stateData.errorURL === "string" ? stateData.errorURL : null;
+  if (
+    !callbackURL ||
+    !errorURL ||
+    !managedAuthOAuthReturnMatches(callbackURL, expectedOrigin, value.transactionId, "complete") ||
+    !managedAuthOAuthReturnMatches(errorURL, expectedOrigin, value.transactionId, "error")
+  ) {
+    return null;
+  }
+  return {
+    transactionId: value.transactionId,
+    provider,
+    authorityHash: value.authorityHash,
+    transactionSecretHash: value.transactionSecretHash,
+    expectedGeneration: value.expectedGeneration,
+    expectedActorEpoch: value.expectedActorEpoch,
+  };
+}
+
+export async function isolatedManagedAuthOAuthCallbackRequest(
+  auth: ManagedAuth,
+  request: Request,
+): Promise<{ request: Request; stateCookieName: string }> {
+  const context = await auth.$context;
+  const stateCookieName = context.createAuthCookie("state").name;
+  const headers = new Headers(request.headers);
+  const stateCookie = cookiePair(headers.get("cookie"), stateCookieName);
+  if (stateCookie) headers.set("cookie", stateCookie);
+  else headers.delete("cookie");
+  headers.delete("authorization");
+  headers.delete("x-forwarded-user");
+  return { request: new Request(request, { headers }), stateCookieName };
+}
+
+export function managedAuthOAuthReturnMatches(
+  raw: string,
+  expectedOrigin: string,
+  transactionId: string,
+  outcome: "complete" | "error",
+): boolean {
+  try {
+    const url = new URL(raw);
+    return (
+      url.origin === expectedOrigin &&
+      url.pathname === "/account-auth" &&
+      url.searchParams.size === 2 &&
+      url.searchParams.get("transaction") === transactionId &&
+      url.searchParams.get("social") === outcome &&
+      !url.hash
+    );
+  } catch {
+    return false;
+  }
+}
+
+function cookiePair(header: string | null, name: string): string | null {
+  for (const part of header?.split(";") ?? []) {
+    const separator = part.indexOf("=");
+    if (separator < 0 || part.slice(0, separator).trim() !== name) continue;
+    return `${name}=${part.slice(separator + 1).trim()}`;
+  }
+  return null;
 }
 
 function betterAuthBaseUrl(settings: Settings) {
@@ -275,35 +761,25 @@ function betterAuthTrustedOrigins(settings: Settings): string[] {
   return [...origins];
 }
 
-async function sendEmail(
-  settings: Settings,
-  input: {
-    to: string;
-    subject: string;
-    text: string;
-    html: string;
-  },
+export async function sendManagedAuthEmail(
+  transport: ManagedEmailTransport,
+  input: Omit<ManagedEmailMessage, "from">,
 ): Promise<void> {
-  if (!settings.resendApiKey) {
-    if (settings.environment === "local" || settings.environment === "test") {
-      console.warn(
-        `[opengeni] Skipping email to ${input.to}: OPENGENI_RESEND_API_KEY is not configured`,
-      );
-      return;
-    }
-    throw new Error("OPENGENI_RESEND_API_KEY is required to send managed auth email");
-  }
-  const resend = new Resend(settings.resendApiKey);
-  const result = await resend.emails.send({
-    from: settings.emailFrom,
-    to: input.to,
-    subject: input.subject,
-    text: input.text,
-    html: input.html,
-  });
-  if (result.error) {
-    throw new Error(result.error.message);
-  }
+  const result = await transport.send({ ...input, from: transport.sender });
+  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> {