@useatlas/create 0.0.5 → 0.0.7

package/templates/nextjs-standalone/src/lib/auth/detect.ts

@@ -1,16 +1,19 @@
 /**
  * Auth mode detection.
  *
- * Resolves the active auth mode from environment variables.
+ * Resolves the active auth mode from environment variables and config.
  *
- * When `ATLAS_AUTH_MODE` is set, it is used directly (explicit mode).
- * When unset, auto-detection reads env vars with priority:
- *   JWKS (byot) > Better Auth (managed) > API key (simple-key) > none.
+ * Priority (highest → lowest):
+ *   1. `ATLAS_AUTH_MODE` env var (explicit override)
+ *   2. `auth` field in atlas.config.ts (when not "auto")
+ *   3. Auto-detection from env var presence:
+ *      JWKS (byot) > Better Auth (managed) > API key (simple-key) > none
  *
  * Result is cached — call resetAuthModeCache() in tests.
  */
 
 import type { AuthMode } from "@atlas/api/lib/auth/types";
+import { getConfig } from "@atlas/api/lib/config";
 import { createLogger } from "@atlas/api/lib/logger";
 
 const log = createLogger("auth");
@@ -24,14 +27,14 @@ const MODE_ALIASES: Record<string, AuthMode> = {
   "byot": "byot",
 };
 
-export type AuthModeSource = "explicit" | "auto-detected";
+export type AuthModeSource = "explicit" | "config" | "auto-detected";
 
 let _cached: AuthMode | null = null;
 let _source: AuthModeSource | null = null;
 
 /**
- * Detect auth mode from ATLAS_AUTH_MODE (explicit) or env var presence (auto).
- * Cached after first call.
+ * Detect auth mode using the three-tier priority chain:
+ * env var → config file → auto-detect. Cached after first call.
  */
 export function detectAuthMode(): AuthMode {
   if (_cached !== null) return _cached;
@@ -52,6 +55,23 @@ export function detectAuthMode(): AuthMode {
     );
   }
 
+  // Config file auth (middle priority)
+  const config = getConfig();
+  if (config?.auth && config.auth !== "auto") {
+    const resolved = MODE_ALIASES[config.auth];
+    if (resolved) {
+      _cached = resolved;
+      _source = "config";
+      log.info({ mode: _cached }, "Auth mode: %s (config)", _cached);
+      return _cached;
+    }
+    log.warn(
+      { configAuth: config.auth },
+      "Config auth value '%s' not recognized — falling through to auto-detection",
+      config.auth,
+    );
+  }
+
   // Auto-detection fallback
   if (process.env.ATLAS_AUTH_JWKS_URL) {
     _cached = "byot";
@@ -69,7 +89,8 @@ export function detectAuthMode(): AuthMode {
 }
 
 /**
- * Return how the auth mode was resolved: "explicit" or "auto-detected".
+ * Return how the auth mode was resolved: "explicit" (env var),
+ * "config" (atlas.config.ts), or "auto-detected" (env var presence).
  * Returns null if detectAuthMode() has not been called yet.
  */
 export function getAuthModeSource(): AuthModeSource | null {

package/templates/nextjs-standalone/src/lib/auth/managed.ts

@@ -9,30 +9,23 @@
  */
 
 import type { AuthResult } from "@atlas/api/lib/auth/types";
+import type { AtlasRole } from "@atlas/api/lib/auth/types";
 import { createAtlasUser } from "@atlas/api/lib/auth/types";
 import { parseRole } from "@atlas/api/lib/auth/permissions";
 import { getAuthInstance } from "@atlas/api/lib/auth/server";
 import { createLogger } from "@atlas/api/lib/logger";
+import { getSetting } from "@atlas/api/lib/settings";
+import { hasInternalDB, internalQuery } from "@atlas/api/lib/db/internal";
 
 const log = createLogger("auth:managed");
 
 export async function validateManaged(req: Request): Promise<AuthResult> {
   const auth = getAuthInstance();
 
-  // Debug: log whether cookies are present in the request
-  const cookieHeader = req.headers.get("cookie");
-  const hasSessionToken = cookieHeader?.includes("session_token") ?? false;
-  const hasAuthorization = !!req.headers.get("authorization");
-  if (!hasSessionToken && !hasAuthorization) {
-    log.info({ url: req.url }, "No session_token cookie or Authorization header in request");
-  } else {
-    log.info({ hasSessionToken, hasAuthorization, url: req.url }, "Auth headers present");
-  }
-
   const session = await auth.api.getSession({ headers: req.headers });
 
   if (!session) {
-    log.info({ hasSessionToken, hasAuthorization }, "getSession returned null");
+    log.debug("getSession returned null — no valid session");
     return { authenticated: false, mode: "managed", status: 401, error: "Not signed in" };
   }
 
@@ -44,7 +37,7 @@ export async function validateManaged(req: Request): Promise<AuthResult> {
   }
 
   // Extract role from session user (set by Better Auth admin plugin, stored in the `role` column).
-  // Falls back to default (viewer) when not present — see permissions.ts.
+  // Falls back to default (member) when not present — see permissions.ts.
   const sessionUser = session.user as Record<string, unknown>;
   // Better Auth can store multiple roles as comma-separated strings; Atlas uses only the first.
   const rawRoleField = sessionUser?.role;
@@ -53,7 +46,7 @@ export async function validateManaged(req: Request): Promise<AuthResult> {
   if (typeof rawRole === "string") {
     role = parseRole(rawRole);
     if (rawRole && !role) {
-      log.warn({ value: rawRole, validRoles: ["viewer", "analyst", "admin"] }, "Session user role is not a valid Atlas role — defaulting to 'viewer'");
+      log.warn({ value: rawRole, validRoles: ["member", "admin", "owner"] }, "Session user role is not a valid Atlas role — defaulting to 'member'");
     }
   } else {
     role = undefined;
@@ -62,12 +55,109 @@ export async function validateManaged(req: Request): Promise<AuthResult> {
     }
   }
 
+  // Session timeout enforcement (idle + absolute)
+  const sessionData = session.session as Record<string, unknown> | undefined;
+  if (sessionData) {
+    const now = Date.now();
+
+    const idleRaw = parseInt(getSetting("ATLAS_SESSION_IDLE_TIMEOUT") ?? "0", 10);
+    const idleTimeout = Number.isFinite(idleRaw) && idleRaw > 0 ? idleRaw : 0;
+    if (idleTimeout > 0 && sessionData.updatedAt) {
+      const updatedAt = new Date(sessionData.updatedAt as string).getTime();
+      if (Number.isNaN(updatedAt)) {
+        log.warn({ userId, updatedAt: sessionData.updatedAt }, "Session updatedAt is not a valid date — rejecting session");
+        return { authenticated: false, mode: "managed", status: 401, error: "Session data is invalid" };
+      }
+      if (now - updatedAt > idleTimeout * 1000) {
+        log.info({ userId, idleMs: now - updatedAt, idleTimeout }, "Session idle timeout exceeded");
+        return { authenticated: false, mode: "managed", status: 401, error: "Session expired (idle timeout)" };
+      }
+    }
+
+    const absRaw = parseInt(getSetting("ATLAS_SESSION_ABSOLUTE_TIMEOUT") ?? "0", 10);
+    const absoluteTimeout = Number.isFinite(absRaw) && absRaw > 0 ? absRaw : 0;
+    if (absoluteTimeout > 0 && sessionData.createdAt) {
+      const createdAt = new Date(sessionData.createdAt as string).getTime();
+      if (Number.isNaN(createdAt)) {
+        log.warn({ userId, createdAt: sessionData.createdAt }, "Session createdAt is not a valid date — rejecting session");
+        return { authenticated: false, mode: "managed", status: 401, error: "Session data is invalid" };
+      }
+      if (now - createdAt > absoluteTimeout * 1000) {
+        log.info({ userId, ageMs: now - createdAt, absoluteTimeout }, "Session absolute timeout exceeded");
+        return { authenticated: false, mode: "managed", status: 401, error: "Session expired" };
+      }
+    }
+  }
+
+  // Extract activeOrganizationId from session — set by Better Auth org plugin
+  // via POST /organization/set-active.
+  const activeOrganizationId = (sessionData?.activeOrganizationId as string) ?? undefined;
+
+  // Resolve effective role: the user-level role (from admin plugin) may be
+  // "member" even when the user is "owner" of their active org (org plugin
+  // stores membership roles in the `member` table, not the `user` table).
+  // Use the higher of the two so org owners/admins can access the admin console.
+  const effectiveRole = await resolveEffectiveRole(role, userId, activeOrganizationId);
+
   // Carry session user fields as claims for RLS policy evaluation
   const claims: Record<string, unknown> = { ...sessionUser, sub: userId };
+  if (activeOrganizationId) {
+    claims.org_id = activeOrganizationId;
+  }
 
   return {
     authenticated: true,
     mode: "managed",
-    user: createAtlasUser(userId, "managed", email || userId, role, claims),
+    user: createAtlasUser(userId, "managed", email || userId, { role: effectiveRole, activeOrganizationId, claims }),
   };
 }
+
+// ---------------------------------------------------------------------------
+// Org member role resolution
+// ---------------------------------------------------------------------------
+
+/** Role precedence — higher number wins. */
+const ROLE_LEVEL: Record<string, number> = {
+  member: 0,
+  admin: 1,
+  owner: 2,
+  platform_admin: 3,
+};
+
+/**
+ * Resolve the effective role by comparing the user-level role (from
+ * Better Auth's admin plugin, stored in the `user.role` column) with the
+ * org-level role (from the `member` table). Returns the higher of the two.
+ *
+ * This is necessary because Better Auth stores org membership roles
+ * separately from user-level roles, so an org owner whose user-level role
+ * is "member" would otherwise be locked out of the admin console.
+ */
+async function resolveEffectiveRole(
+  userRole: AtlasRole | undefined,
+  userId: string,
+  activeOrganizationId: string | undefined,
+): Promise<AtlasRole | undefined> {
+  if (!activeOrganizationId || !hasInternalDB()) return userRole;
+
+  try {
+    const rows = await internalQuery<{ role: string }>(
+      `SELECT role FROM member WHERE "userId" = $1 AND "organizationId" = $2 LIMIT 1`,
+      [userId, activeOrganizationId],
+    );
+    if (rows.length === 0) return userRole;
+
+    const orgRole = parseRole(rows[0].role);
+    if (!orgRole) return userRole;
+
+    const userLevel = ROLE_LEVEL[userRole ?? "member"] ?? 0;
+    const orgLevel = ROLE_LEVEL[orgRole] ?? 0;
+    return orgLevel > userLevel ? orgRole : (userRole ?? "member");
+  } catch (err) {
+    log.warn(
+      { err: err instanceof Error ? err.message : String(err), userId, orgId: activeOrganizationId },
+      "Failed to look up org member role — falling back to user-level role",
+    );
+    return userRole;
+  }
+}

package/templates/nextjs-standalone/src/lib/auth/middleware.ts

@@ -14,6 +14,8 @@ import { validateApiKey } from "@atlas/api/lib/auth/simple-key";
 import { validateManaged } from "@atlas/api/lib/auth/managed";
 import { validateBYOT } from "@atlas/api/lib/auth/byot";
 import { createLogger } from "@atlas/api/lib/logger";
+import { getSetting } from "@atlas/api/lib/settings";
+import { isSSOEnforcedForDomain, extractEmailDomain } from "@atlas/ee/auth/sso";
 
 const log = createLogger("auth");
 
@@ -26,16 +28,16 @@ const WINDOW_MS = 60_000; // 60 seconds
 /** Map of rate-limit key → array of request timestamps (ms). */
 const windows = new Map<string, number[]>();
 
-let warnedInvalidRpm = false;
+let lastWarnedRpmValue: string | undefined;
 
 function getRpmLimit(): number {
-  const raw = process.env.ATLAS_RATE_LIMIT_RPM;
+  const raw = getSetting("ATLAS_RATE_LIMIT_RPM");
   if (raw === undefined || raw === "") return 0; // disabled
   const n = Number(raw);
   if (!Number.isFinite(n) || n < 0) {
-    if (!warnedInvalidRpm) {
+    if (raw !== lastWarnedRpmValue) {
       log.warn({ value: raw }, "Invalid ATLAS_RATE_LIMIT_RPM; rate limiting disabled");
-      warnedInvalidRpm = true;
+      lastWarnedRpmValue = raw;
     }
     return 0;
   }
@@ -108,7 +110,7 @@ export function checkRateLimit(key: string): {
 /** Clear all rate limit state. For tests. */
 export function resetRateLimits(): void {
   windows.clear();
-  warnedInvalidRpm = false;
+  lastWarnedRpmValue = undefined;
 }
 
 /** Periodic cleanup — evict keys with no recent timestamps. */
@@ -178,6 +180,41 @@ function categorizeAuthError(err: unknown): string {
   return "unknown";
 }
 
+/**
+ * Check SSO enforcement for a user's email domain.
+ * Returns an AuthResult rejection if SSO is enforced, null otherwise.
+ * Fails closed on errors — returns a 500 AuthResult to block login.
+ */
+async function checkSSOEnforcement(userLabel: string): Promise<AuthResult | null> {
+  try {
+    const domain = extractEmailDomain(userLabel);
+    if (!domain) return null;
+
+    const enforcement = await isSSOEnforcedForDomain(domain);
+    if (!enforcement || !enforcement.enforced) return null;
+
+    log.warn({ domain, userId: userLabel }, "Password login blocked — SSO enforcement active for domain");
+    return {
+      authenticated: false,
+      mode: "managed",
+      status: 403,
+      error: "SSO is required for this workspace. Please sign in via your identity provider.",
+      ssoRedirectUrl: enforcement.ssoRedirectUrl,
+    };
+  } catch (err) {
+    log.error(
+      { err: err instanceof Error ? err : new Error(String(err)) },
+      "SSO enforcement check failed — blocking login (fail-closed)",
+    );
+    return {
+      authenticated: false,
+      mode: "managed" as const,
+      status: 500 as const,
+      error: "Unable to verify SSO enforcement status. Please retry or contact your administrator.",
+    };
+  }
+}
+
 /** Authenticate an incoming request based on the detected auth mode. */
 export async function authenticateRequest(req: Request): Promise<AuthResult> {
   const mode = detectAuthMode();
@@ -191,7 +228,17 @@ export async function authenticateRequest(req: Request): Promise<AuthResult> {
 
     case "managed":
       try {
-        return await (_managedOverride ?? validateManaged)(req);
+        const managedResult = await (_managedOverride ?? validateManaged)(req);
+
+        // SSO enforcement: if the user's email domain has SSO enforced,
+        // block password/session auth and require SSO login instead.
+        // Break-glass bypass: simple-key auth (API key) is not affected.
+        if (managedResult.authenticated && managedResult.user) {
+          const enforcementCheck = await checkSSOEnforcement(managedResult.user.label);
+          if (enforcementCheck) return enforcementCheck;
+        }
+
+        return managedResult;
       } catch (err) {
         const category = categorizeAuthError(err);
         log.error(

package/templates/nextjs-standalone/src/lib/auth/migrate.ts

@@ -7,8 +7,12 @@
  */
 
 import { detectAuthMode } from "@atlas/api/lib/auth/detect";
-import { hasInternalDB, internalQuery } from "@atlas/api/lib/db/internal";
+import { hasInternalDB, internalQuery, encryptUrl } from "@atlas/api/lib/db/internal";
 import { createLogger } from "@atlas/api/lib/logger";
+import { connections, detectDBType, resolveDatasourceUrl } from "@atlas/api/lib/db/connection";
+import { _resetWhitelists } from "@atlas/api/lib/semantic";
+import { importFromDisk } from "@atlas/api/lib/semantic/sync";
+import { getSemanticRoot } from "@atlas/api/lib/semantic/files";
 
 const log = createLogger("auth-migrate");
 
@@ -40,6 +44,31 @@ export async function migrateAuthTables(): Promise<void> {
       _migrationError = "Connected to the internal database but migration failed. Check database permissions (CREATE TABLE, CREATE INDEX).";
       // Don't block server start — audit will fall back to pino-only
     }
+
+    // Load admin-managed connections (separate from migration so failures don't conflate)
+    try {
+      const { loadSavedConnections } = await import("@atlas/api/lib/db/internal");
+      await loadSavedConnections();
+    } catch (err) {
+      log.error({ err }, "Failed to load saved connections at startup — admin-managed connections unavailable");
+    }
+
+    // Load plugin settings (enabled/disabled state from DB)
+    try {
+      const { loadPluginSettings } = await import("@atlas/api/lib/plugins/settings");
+      const { plugins } = await import("@atlas/api/lib/plugins/registry");
+      await loadPluginSettings(plugins);
+    } catch (err) {
+      log.error({ err }, "Failed to load plugin settings at startup — all plugins default to enabled");
+    }
+
+    // Restore abuse prevention state from DB
+    try {
+      const { restoreAbuseState } = await import("@atlas/api/lib/security/abuse");
+      await restoreAbuseState();
+    } catch (err) {
+      log.error({ err }, "Failed to restore abuse state at startup — starting with empty state");
+    }
   }
 
   // Better Auth migration — only in managed mode
@@ -96,7 +125,7 @@ async function bootstrapAdminUser(): Promise<void> {
 
   try {
     const existing = await internalQuery<{ count: string }>(
-      `SELECT COUNT(*) as count FROM "user" WHERE role = 'admin'`,
+      `SELECT COUNT(*) as count FROM "user" WHERE role IN ('admin', 'platform_admin')`,
     );
     if (parseInt(String(existing[0]?.count ?? "0"), 10) > 0) {
       log.debug("Bootstrap: admin user already exists — skipping promotion");
@@ -104,11 +133,11 @@ async function bootstrapAdminUser(): Promise<void> {
     }
 
     const result = await internalQuery<{ id: string; email: string }>(
-      `UPDATE "user" SET role = 'admin' WHERE LOWER(email) = $1 RETURNING id, email`,
+      `UPDATE "user" SET role = 'platform_admin' WHERE LOWER(email) = $1 RETURNING id, email`,
       [adminEmail],
     );
     if (result.length > 0) {
-      log.info({ email: result[0].email, id: result[0].id }, "Bootstrap: existing user promoted to admin via ATLAS_ADMIN_EMAIL");
+      log.info({ email: result[0].email, id: result[0].id }, "Bootstrap: existing user promoted to platform_admin via ATLAS_ADMIN_EMAIL");
     } else {
       log.warn({ adminEmail }, "Bootstrap: ATLAS_ADMIN_EMAIL is set but no user with that email exists yet — role will be assigned on first signup");
     }
@@ -118,10 +147,13 @@ async function bootstrapAdminUser(): Promise<void> {
 }
 
 /**
- * Seed a default dev admin account when no users exist.
- * Only runs when ATLAS_ADMIN_EMAIL is set — uses that email with a
- * well-known password ("atlas-dev"). The databaseHook in server.ts
- * promotes this user to admin on creation.
+ * Seed a complete dev environment when no users exist:
+ *   1. Platform admin user (ATLAS_ADMIN_EMAIL / atlas-dev)
+ *   2. "Atlas" organization with the admin as owner
+ *   3. Demo datasource connection + semantic layer import
+ *
+ * After `db:reset && dev`, the admin can sign in and see a fully
+ * working admin console with data — no manual onboarding steps.
  *
  * Skips silently if any users already exist (idempotent).
  */
@@ -135,33 +167,126 @@ async function seedDevUser(auth: { api: Record<string, unknown> }): Promise<void
     );
     if (parseInt(String(userCount[0]?.count ?? "0"), 10) > 0) return;
 
-    // Use Better Auth's createUser API (from the admin plugin)
+    // ── 1. Create user ──────────────────────────────────────────────
     const createUser = auth.api.createUser as (opts: {
       body: { email: string; password: string; name: string; role: string };
-    }) => Promise<unknown>;
+    }) => Promise<{ user?: { id: string } } | undefined>;
 
-    await createUser({
+    const result = await createUser({
       body: {
         email: adminEmail,
         password: "atlas-dev",
         name: "Atlas Admin",
-        role: "admin",
+        role: "platform_admin",
       },
     });
 
-    // Mark the seeded user as requiring a password change
+    const userId = result?.user?.id;
+    if (!userId) {
+      log.warn("Dev seed: createUser succeeded but returned no user id");
+      return;
+    }
+
+    // Mark as requiring password change
     await internalQuery(
-      `UPDATE "user" SET password_change_required = true WHERE LOWER(email) = $1`,
-      [adminEmail],
+      `UPDATE "user" SET password_change_required = true WHERE id = $1`,
+      [userId],
     );
 
     log.info({ email: adminEmail }, "Dev admin account seeded (password: atlas-dev)");
+
+    // ── 2. Create organization ──────────────────────────────────────
+    const createOrg = auth.api.createOrganization as ((opts: {
+      body: { name: string; slug: string; userId: string };
+    }) => Promise<{ id?: string } | undefined>) | undefined;
+
+    if (!createOrg) {
+      log.warn("Dev seed: organization API not available — skipping org creation");
+      return;
+    }
+
+    const org = await createOrg({
+      body: { name: "Atlas", slug: "atlas", userId },
+    });
+    const orgId = org?.id;
+    if (!orgId) {
+      log.warn("Dev seed: createOrganization returned no org id");
+      return;
+    }
+
+    // Set org as active for the user's sessions
+    const setActive = auth.api.setActiveOrganization as ((opts: {
+      body: { organizationId: string };
+      headers: Headers;
+    }) => Promise<unknown>) | undefined;
+
+    if (setActive) {
+      // We don't have a session yet, so directly update the session table
+      // once a session exists. For now, set it via DB — the user's first
+      // session will pick it up.
+    }
+
+    log.info({ orgId, orgName: "Atlas" }, "Dev organization created");
+
+    // ── 3. Connect demo datasource + import semantic layer ──────────
+    await seedDemoData(orgId);
+
   } catch (err) {
     // User might already exist from a previous partial boot — not fatal
     log.debug({ err }, "Dev user seed skipped or failed");
   }
 }
 
+/**
+ * Connect the demo datasource and import the semantic layer for an org.
+ * Extracted so it can be called from seedDevUser. Non-fatal — logs
+ * warnings on failure so the server still boots.
+ */
+async function seedDemoData(orgId: string): Promise<void> {
+  const url = resolveDatasourceUrl();
+  if (!url) {
+    log.debug("Dev seed: no ATLAS_DATASOURCE_URL — skipping demo data");
+    return;
+  }
+
+  let dbType: string;
+  try {
+    dbType = detectDBType(url);
+  } catch {
+    log.warn("Dev seed: unsupported datasource URL scheme — skipping demo data");
+    return;
+  }
+
+  // Encrypt and persist connection
+  try {
+    const encryptedUrl = encryptUrl(url);
+    await internalQuery(
+      `INSERT INTO connections (id, url, type, description, org_id)
+       VALUES ($1, $2, $3, $4, $5)
+       ON CONFLICT (id) DO UPDATE SET url = $2, type = $3, org_id = $5, updated_at = NOW()`,
+      ["default", encryptedUrl, dbType, `Demo ${dbType} datasource`, orgId],
+    );
+
+    // Register in runtime
+    if (connections.has("default")) connections.unregister("default");
+    connections.register("default", { url, description: `Demo ${dbType} datasource` });
+
+    log.info({ orgId, dbType }, "Dev seed: demo datasource connected");
+  } catch (err) {
+    log.warn({ err: err instanceof Error ? err.message : String(err) }, "Dev seed: failed to persist demo connection");
+    return;
+  }
+
+  // Import semantic layer from disk
+  try {
+    const result = await importFromDisk(orgId, { sourceDir: getSemanticRoot() });
+    _resetWhitelists();
+    log.info({ orgId, imported: result.imported, skipped: result.skipped }, "Dev seed: semantic layer imported");
+  } catch (err) {
+    log.warn({ err: err instanceof Error ? err.message : String(err) }, "Dev seed: semantic layer import failed");
+  }
+}
+
 /**
  * Backfill: if the dev admin user exists with the default password and
  * password_change_required is false, set the flag. Handles upgrades where

package/templates/nextjs-standalone/src/lib/auth/oauth-state.ts

@@ -0,0 +1,123 @@
+/**
+ * Shared OAuth CSRF state management.
+ *
+ * Stores nonces in the internal database when available (multi-instance safe).
+ * Falls back to an in-memory Map for single-instance self-hosted deployments
+ * without an internal database.
+ */
+
+import { hasInternalDB, internalQuery } from "@atlas/api/lib/db/internal";
+import { createLogger } from "@atlas/api/lib/logger";
+
+const log = createLogger("oauth-state");
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type OAuthProvider = "slack" | "teams" | "discord";
+
+interface MemoryState {
+  orgId: string | undefined;
+  provider: OAuthProvider;
+  expiresAt: number;
+}
+
+export interface OAuthStateResult {
+  orgId: string | undefined;
+  provider: OAuthProvider;
+}
+
+// ---------------------------------------------------------------------------
+// In-memory fallback (single-instance, no internal DB)
+// ---------------------------------------------------------------------------
+
+const memoryFallback = new Map<string, MemoryState>();
+
+let _warnedFallback = false;
+
+// Periodic sweep for the in-memory fallback (every 10 minutes)
+setInterval(() => {
+  const now = Date.now();
+  for (const [nonce, state] of memoryFallback) {
+    if (now > state.expiresAt) memoryFallback.delete(nonce);
+  }
+}, 600_000).unref();
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+const DEFAULT_TTL_MS = 600_000; // 10 minutes
+
+export async function saveOAuthState(
+  nonce: string,
+  opts: { orgId?: string; provider: OAuthProvider; ttlMs?: number },
+): Promise<void> {
+  const expiresAt = new Date(Date.now() + (opts.ttlMs ?? DEFAULT_TTL_MS));
+
+  if (hasInternalDB()) {
+    await internalQuery(
+      `INSERT INTO oauth_state (nonce, org_id, provider, expires_at) VALUES ($1, $2, $3, $4)`,
+      [nonce, opts.orgId ?? null, opts.provider, expiresAt.toISOString()],
+    );
+  } else {
+    if (!_warnedFallback && process.env.ATLAS_DEPLOY_MODE === "saas") {
+      log.warn(
+        "OAuth state using in-memory fallback — DATABASE_URL is not set. " +
+        "OAuth callbacks may fail in multi-instance deployments.",
+      );
+      _warnedFallback = true;
+    }
+    memoryFallback.set(nonce, {
+      orgId: opts.orgId,
+      provider: opts.provider,
+      expiresAt: expiresAt.getTime(),
+    });
+  }
+}
+
+export async function consumeOAuthState(
+  nonce: string,
+): Promise<OAuthStateResult | null> {
+  if (hasInternalDB()) {
+    const rows = await internalQuery<{ org_id: string | null; provider: string }>(
+      `DELETE FROM oauth_state WHERE nonce = $1 AND expires_at > now() RETURNING org_id, provider`,
+      [nonce],
+    );
+    if (rows.length === 0) return null;
+    return {
+      orgId: typeof rows[0].org_id === "string" ? rows[0].org_id : undefined,
+      provider: rows[0].provider as OAuthProvider,
+    };
+  }
+
+  const state = memoryFallback.get(nonce);
+  memoryFallback.delete(nonce);
+  if (!state || Date.now() > state.expiresAt) return null;
+  return { orgId: state.orgId, provider: state.provider };
+}
+
+export async function cleanExpiredOAuthState(): Promise<void> {
+  if (hasInternalDB()) {
+    try {
+      await internalQuery(`DELETE FROM oauth_state WHERE expires_at < now()`, []);
+    } catch (err) {
+      log.warn(
+        { err: err instanceof Error ? err.message : String(err) },
+        "Failed to clean expired OAuth state",
+      );
+    }
+  } else {
+    const now = Date.now();
+    for (const [nonce, state] of memoryFallback) {
+      if (now > state.expiresAt) memoryFallback.delete(nonce);
+    }
+  }
+}
+
+/** @internal Reset in-memory state — for testing only. */
+export function _resetMemoryFallback(): void {
+  memoryFallback.clear();
+  _warnedFallback = false;
+}