@agent-native/core 0.5.0-dev.b51eaae → 0.7.1

package/dist/server/auth.js

@@ -1,54 +1,97 @@
 import crypto from "node:crypto";
-import { defineEventHandler, readBody, getMethod, getQuery, getRequestIP, setResponseHeader, setResponseStatus, getCookie, setCookie, deleteCookie, } from "h3";
+import path from "node:path";
+// Lazy fs — loaded via dynamic import() on first use.
+// Avoids static require() which crashes on CF Workers.
+let _fs;
+async function getFs() {
+    if (!_fs) {
+        _fs = await import("node:fs");
+    }
+    return _fs;
+}
+import { defineEventHandler, getMethod, getQuery, setResponseHeader, setResponseStatus, getCookie, setCookie, deleteCookie, } from "h3";
+// In h3 v2, `event.req` IS the web Request — no conversion needed.
+function toWebRequest(event) {
+    return event.req;
+}
 import { getDbExec, isPostgres, intType } from "../db/client.js";
+import { getBetterAuth, getBetterAuthSync } from "./better-auth-instance.js";
+import { getOnboardingHtml } from "./onboarding-html.js";
+import { migrateLocalUserData } from "./local-migration.js";
+import { readBody } from "../server/h3-helpers.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 const COOKIE_NAME = "an_session";
 const DEFAULT_MAX_AGE = 60 * 60 * 24 * 30; // 30 days
-const RATE_LIMIT_WINDOW = 15 * 60 * 1000; // 15 minutes
-const RATE_LIMIT_MAX = 10; // max attempts per window
-const rateLimitMap = new Map();
-// Prune stale entries every 5 minutes to prevent unbounded growth
-setInterval(() => {
-    const now = Date.now();
-    for (const [key, entry] of rateLimitMap) {
-        if (now > entry.resetAt)
-            rateLimitMap.delete(key);
+const LOCAL_MODE_MARKER_PATH = path.resolve(process.cwd(), ".agent-native", "auth-mode");
+// ---------------------------------------------------------------------------
+// AUTH_MODE detection
+// ---------------------------------------------------------------------------
+/**
+ * Check if the app is in local-only mode (no auth).
+ *
+ * Returns true when AUTH_MODE=local is explicitly set or when the dev
+ * onboarding flow has enabled local mode for the current workspace via
+ * a runtime marker file.
+ *
+ * Local mode is an explicit escape hatch for when you want to guarantee
+ * no auth is used. In development, getSession() also falls back to
+ * local@localhost automatically if no other auth method succeeds, so
+ * apps are always usable without configuration in dev.
+ */
+async function isLocalModeEnabled() {
+    if (process.env.AUTH_MODE === "local")
+        return true;
+    try {
+        const fs = await getFs();
+        const mode = fs.readFileSync(LOCAL_MODE_MARKER_PATH, "utf-8").trim();
+        return mode === "local";
+    }
+    catch {
+        return false;
     }
-}, 5 * 60 * 1000).unref();
-function getClientIp(event) {
-    return getRequestIP(event, { xForwardedFor: true }) ?? "unknown";
 }
 /**
- * Check rate limit for a given key (typically IP + route).
- * Returns null if allowed, or a response object if blocked.
+ * Check if we're in a development/test environment.
+ * Used for cookie security settings, not for auth bypass.
  */
-function checkRateLimit(event, key) {
-    const now = Date.now();
-    const entry = rateLimitMap.get(key);
-    if (!entry || now > entry.resetAt) {
-        rateLimitMap.set(key, { count: 1, resetAt: now + RATE_LIMIT_WINDOW });
-        return null;
-    }
-    entry.count++;
-    if (entry.count > RATE_LIMIT_MAX) {
-        const retryAfter = Math.ceil((entry.resetAt - now) / 1000);
-        setResponseStatus(event, 429);
-        setResponseHeader(event, "Retry-After", retryAfter);
-        return {
-            error: "Too many attempts. Please try again later.",
-            retryAfter,
-        };
+function isDevEnvironment() {
+    const env = process.env.NODE_ENV;
+    return env === "development" || env === "test";
+}
+// ---------------------------------------------------------------------------
+// ACCESS_TOKEN resolution
+// ---------------------------------------------------------------------------
+function getAccessTokens() {
+    const single = process.env.ACCESS_TOKEN;
+    const multi = process.env.ACCESS_TOKENS;
+    const tokens = [];
+    if (single)
+        tokens.push(single);
+    if (multi) {
+        for (const t of multi.split(",")) {
+            const trimmed = t.trim();
+            if (trimmed && !tokens.includes(trimmed))
+                tokens.push(trimmed);
+        }
     }
-    return null;
+    return tokens;
 }
-/** Reset rate limit on successful auth (so valid users aren't penalized). */
-function resetRateLimit(key) {
-    rateLimitMap.delete(key);
+function safeTokenMatch(input, tokens) {
+    const inputBuf = Buffer.from(input);
+    for (const token of tokens) {
+        const tokenBuf = Buffer.from(token);
+        if (inputBuf.length === tokenBuf.length &&
+            crypto.timingSafeEqual(inputBuf, tokenBuf)) {
+            return true;
+        }
+    }
+    return false;
 }
 // ---------------------------------------------------------------------------
-// Session store — SQL-backed
+// Legacy session store — kept for backward compat (addSession/getSessionEmail)
+// Used by google-oauth.ts for mobile deep linking session creation.
 // ---------------------------------------------------------------------------
 let _sessionInitPromise;
 let sessionMaxAge = DEFAULT_MAX_AGE;
@@ -63,29 +106,19 @@ async function ensureSessionTable() {
           created_at ${intType()} NOT NULL
         )
       `);
-            // Migration: add email column to existing tables that lack it
             try {
                 await client.execute(`ALTER TABLE sessions ADD COLUMN email TEXT`);
             }
             catch {
-                // Column already exists — ignore
+                // Column already exists
             }
         })();
     }
     return _sessionInitPromise;
 }
-async function pruneExpiredSessions() {
-    await ensureSessionTable();
-    const client = getDbExec();
-    const cutoff = Date.now() - sessionMaxAge * 1000;
-    await client.execute({
-        sql: `DELETE FROM sessions WHERE created_at < ?`,
-        args: [cutoff],
-    });
-}
 /**
- * Create a new session. Optionally associate it with an email address
- * (used by Google OAuth and other identity-aware auth providers).
+ * Create a new session in the legacy sessions table.
+ * Used by google-oauth.ts for mobile deep linking.
  */
 export async function addSession(token, email) {
     await ensureSessionTable();
@@ -97,7 +130,7 @@ export async function addSession(token, email) {
         args: [token, email ?? null, Date.now()],
     });
 }
-/** Remove a session by token. */
+/** Remove a session from the legacy sessions table. */
 export async function removeSession(token) {
     await ensureSessionTable();
     const client = getDbExec();
@@ -107,7 +140,7 @@ export async function removeSession(token) {
     });
 }
 /**
- * Look up the email associated with a session token.
+ * Look up the email associated with a legacy session token.
  * Returns null if the session doesn't exist, is expired, or has no email.
  */
 export async function getSessionEmail(token) {
@@ -129,71 +162,115 @@ export async function getSessionEmail(token) {
     }
     return rows[0].email ?? null;
 }
-async function hasSession(token) {
-    await ensureSessionTable();
-    const client = getDbExec();
-    const { rows } = await client.execute({
-        sql: `SELECT created_at FROM sessions WHERE token = ?`,
-        args: [token],
-    });
-    if (rows.length === 0)
-        return false;
-    const createdAt = rows[0].created_at;
-    if (Date.now() - createdAt > sessionMaxAge * 1000) {
-        await client.execute({
-            sql: `DELETE FROM sessions WHERE token = ?`,
-            args: [token],
-        });
-        return false;
-    }
-    return true;
-}
 // ---------------------------------------------------------------------------
-// Token resolution — supports ACCESS_TOKEN (single) or ACCESS_TOKENS (multi)
+// getSession — the auth contract
 // ---------------------------------------------------------------------------
-function getAccessTokens() {
-    const single = process.env.ACCESS_TOKEN;
-    const multi = process.env.ACCESS_TOKENS;
-    const tokens = [];
-    if (single)
-        tokens.push(single);
-    if (multi) {
-        for (const t of multi.split(",")) {
-            const trimmed = t.trim();
-            if (trimmed && !tokens.includes(trimmed))
-                tokens.push(trimmed);
-        }
-    }
-    return tokens;
+let customGetSession = null;
+let authDisabledMode = false;
+let _authGuardConfig = null;
+/**
+ * Module-level auth guard function. Set by autoMountAuth() when auth is active.
+ * Called by the server middleware to enforce auth on ALL requests (not just
+ * /_agent-native/* routes).
+ */
+let _authGuardFn = null;
+/**
+ * Run the auth guard on an event. Returns a Response/object to block the
+ * request (login page or 401), or undefined to allow it through.
+ *
+ * Called by the default server middleware (server/middleware/auth.ts) to
+ * enforce auth on page routes and API routes — not just framework routes.
+ */
+export async function runAuthGuard(event) {
+    if (!_authGuardFn)
+        return; // Auth not mounted (local mode, etc.)
+    return _authGuardFn(event);
 }
+const LOCAL_SESSION = { email: "local@localhost" };
 // ---------------------------------------------------------------------------
-// Dev mode detection
+// Auth guard factory
 // ---------------------------------------------------------------------------
-function isDevMode() {
-    // On edge runtimes (e.g. CF Workers), NODE_ENV may not be set.
-    // Treat undefined as production — dev mode must be explicitly opted in.
-    const env = process.env.NODE_ENV;
-    return env === "development" || env === "test";
+/**
+ * Create an auth guard function that checks session and blocks
+ * unauthenticated requests. Returns the login HTML for page routes
+ * or a 401 JSON response for API routes.
+ *
+ * Reads loginHtml and publicPaths from _authGuardConfig on every request
+ * so that a custom plugin can update them after the default has already
+ * installed this middleware (the production race condition fix).
+ */
+function createAuthGuardFn() {
+    return async (event) => {
+        const config = _authGuardConfig;
+        if (!config)
+            return;
+        const { loginHtml, publicPaths } = config;
+        const url = event.node?.req?.url ?? event.path ?? "/";
+        const p = url.split("?")[0];
+        // Skip auth routes and specific Google OAuth endpoints that must be public
+        // (callback and auth-url). Other Google endpoints like /status require auth.
+        if (p.startsWith("/_agent-native/auth/") ||
+            p === "/_agent-native/google/callback" ||
+            p === "/_agent-native/google/auth-url" ||
+            p === "/_agent-native/google/add-account/callback") {
+            return;
+        }
+        // Skip static assets (Vite chunks, fonts, images, etc.)
+        if (p.startsWith("/assets/") ||
+            p.startsWith("/_build/") ||
+            p.endsWith(".js") ||
+            p.endsWith(".css") ||
+            p.endsWith(".map") ||
+            p.endsWith(".ico") ||
+            p.endsWith(".png") ||
+            p.endsWith(".svg") ||
+            p.endsWith(".woff2") ||
+            p.endsWith(".woff")) {
+            return;
+        }
+        if (isPublicPath(url, publicPaths))
+            return;
+        const session = await getSession(event);
+        if (session)
+            return;
+        if (p.startsWith("/api/") || p.startsWith("/_agent-native/")) {
+            setResponseStatus(event, 401);
+            return { error: "Unauthorized" };
+        }
+        return new Response(loginHtml, {
+            status: 200,
+            headers: { "Content-Type": "text/html; charset=utf-8" },
+        });
+    };
+}
+/**
+ * Map a Better Auth session to our AuthSession type.
+ */
+function mapBetterAuthSession(baSession) {
+    return {
+        email: baSession.user.email,
+        userId: baSession.user.id,
+        token: baSession.session?.token,
+        orgId: baSession.session?.activeOrganizationId ?? undefined,
+    };
 }
-// ---------------------------------------------------------------------------
-// getSession — the auth contract
-// ---------------------------------------------------------------------------
-let customGetSession = null;
-let authDisabledMode = false;
-const DEV_SESSION = { email: "local@localhost" };
 /**
  * Get the current auth session for a request.
  *
- * - In dev mode: checks for a session cookie first (e.g. from Google OAuth),
- *   so the real email is used when sharing a DB with production.
- *   Falls back to { email: "local@localhost" } if no session cookie.
- * - In production with built-in auth: returns session if cookie is valid
- * - With custom auth (BYOA): delegates to the custom getSession
+ * Resolution chain:
+ * 1. AUTH_MODE=local → local@localhost (explicit escape hatch)
+ * 2. AUTH_DISABLED=true → local@localhost (infrastructure auth)
+ * 3. ACCESS_TOKEN → check legacy cookie-based token sessions
+ * 4. BYOA custom getSession → delegate to template callback
+ * 5. Better Auth → check session via Better Auth API (cookie or Bearer)
+ * 6. Legacy cookie → check an_session cookie in legacy sessions table
+ * 7. Mobile _session query param → promote to cookie
+ * 8. Dev-mode fallback → local@localhost (never block in development)
  */
 export async function getSession(event) {
-    if (isDevMode() || authDisabledMode) {
-        // Check for a real session cookie (created by Google OAuth callback)
-        // so dev and prod share the same identity on the same DB
+    // 1. AUTH_MODE=local — explicit local-only mode
+    if ((await isLocalModeEnabled()) || authDisabledMode) {
+        // Check for a real session cookie first (e.g. from Google OAuth)
         try {
             const cookie = getCookie(event, COOKIE_NAME);
             if (cookie) {
@@ -203,17 +280,59 @@ export async function getSession(event) {
             }
         }
         catch {
-            // DB not ready yet — fall back to dev session
+            // DB not ready yet
+        }
+        // Also try Better Auth session (for users who created an account then went local)
+        try {
+            const ba = getBetterAuthSync();
+            if (ba) {
+                const baSession = await ba.api.getSession({
+                    headers: event.headers,
+                });
+                if (baSession?.user?.email) {
+                    return mapBetterAuthSession(baSession);
+                }
+            }
+        }
+        catch {
+            // Better Auth not initialized yet
         }
-        return DEV_SESSION;
+        return LOCAL_SESSION;
     }
+    // 2. ACCESS_TOKEN check (programmatic/agent access)
+    const accessTokens = getAccessTokens();
+    if (accessTokens.length > 0) {
+        const cookie = getCookie(event, COOKIE_NAME);
+        if (cookie) {
+            const email = await getSessionEmail(cookie);
+            if (email)
+                return { email, token: cookie };
+        }
+    }
+    // 3. BYOA custom getSession
     if (customGetSession) {
         const session = await customGetSession(event);
         if (session)
             return session;
-        // Fall through to _session query param check (mobile WebView bridge)
+        // Fall through to mobile _session check
     }
     else {
+        // 4. Better Auth session (cookie or Bearer token)
+        try {
+            const ba = getBetterAuthSync();
+            if (ba) {
+                const baSession = await ba.api.getSession({
+                    headers: event.headers,
+                });
+                if (baSession?.user?.email) {
+                    return mapBetterAuthSession(baSession);
+                }
+            }
+        }
+        catch {
+            // Better Auth not ready
+        }
+        // 5. Legacy cookie fallback (for sessions created before migration)
         const cookie = getCookie(event, COOKIE_NAME);
         if (cookie) {
             const email = await getSessionEmail(cookie);
@@ -221,145 +340,46 @@ export async function getSession(event) {
                 return { email, token: cookie };
         }
     }
-    // Mobile WebViews have a separate cookie jar from Safari, so after OAuth
-    // completes in Safari the WebView won't have the session cookie.  The mobile
-    // app passes the token as a query parameter; if it's valid we promote it to
-    // an httpOnly cookie so subsequent requests work normally.
-    // This MUST run even with custom auth providers (e.g. createGoogleAuthPlugin).
+    // 6. Mobile WebView bridge — _session query param
     const qToken = getQuery(event)?._session;
     if (qToken) {
         const email = await getSessionEmail(qToken);
         if (email) {
             setCookie(event, COOKIE_NAME, qToken, {
                 httpOnly: true,
-                secure: process.env.NODE_ENV === "production",
+                secure: !isDevEnvironment(),
                 sameSite: "lax",
                 path: "/",
                 maxAge: sessionMaxAge,
             });
+            setResponseHeader(event, "Referrer-Policy", "no-referrer");
             return { email, token: qToken };
         }
     }
-    return null;
-}
-// ---------------------------------------------------------------------------
-// Constant-time token comparison
-// ---------------------------------------------------------------------------
-function safeTokenMatch(input, tokens) {
-    const inputBuf = Buffer.from(input);
-    for (const token of tokens) {
-        const tokenBuf = Buffer.from(token);
-        if (inputBuf.length === tokenBuf.length &&
-            crypto.timingSafeEqual(inputBuf, tokenBuf)) {
-            return true;
-        }
-    }
-    return false;
-}
-// ---------------------------------------------------------------------------
-// Password hashing — Web Crypto PBKDF2 (works on Node.js + CF Workers)
-// ---------------------------------------------------------------------------
-const PBKDF2_ITERATIONS = 100_000;
-function toHex(buf) {
-    return Array.from(buf)
-        .map((b) => b.toString(16).padStart(2, "0"))
-        .join("");
-}
-function fromHex(hex) {
-    const bytes = new Uint8Array(hex.length / 2);
-    for (let i = 0; i < hex.length; i += 2) {
-        bytes[i / 2] = parseInt(hex.slice(i, i + 2), 16);
+    // 7. Dev-mode safety net — in development, always fall back to local@localhost
+    // so the app is usable without any auth configuration. This prevents 401
+    // errors when Better Auth isn't configured, the marker file is missing, or
+    // the user simply wants to play around locally.
+    if (isDevEnvironment()) {
+        return LOCAL_SESSION;
     }
-    return bytes;
-}
-async function hashPassword(password) {
-    const salt = crypto.getRandomValues(new Uint8Array(16));
-    const encoded = new TextEncoder().encode(password);
-    const keyMaterial = await globalThis.crypto.subtle.importKey("raw", encoded.buffer, "PBKDF2", false, ["deriveBits"]);
-    const derived = await globalThis.crypto.subtle.deriveBits({
-        name: "PBKDF2",
-        salt: salt.buffer,
-        iterations: PBKDF2_ITERATIONS,
-        hash: "SHA-256",
-    }, keyMaterial, 256);
-    return `${PBKDF2_ITERATIONS}:${toHex(salt)}:${toHex(new Uint8Array(derived))}`;
-}
-async function verifyPassword(password, stored) {
-    const [iterStr, saltHex, hashHex] = stored.split(":");
-    const iterations = parseInt(iterStr, 10);
-    const salt = fromHex(saltHex);
-    const expectedHash = fromHex(hashHex);
-    const encoded = new TextEncoder().encode(password);
-    const keyMaterial = await globalThis.crypto.subtle.importKey("raw", encoded.buffer, "PBKDF2", false, ["deriveBits"]);
-    const derived = new Uint8Array(await globalThis.crypto.subtle.deriveBits({
-        name: "PBKDF2",
-        salt: salt.buffer,
-        iterations,
-        hash: "SHA-256",
-    }, keyMaterial, 256));
-    if (derived.length !== expectedHash.length)
-        return false;
-    // Constant-time comparison
-    let diff = 0;
-    for (let i = 0; i < derived.length; i++) {
-        diff |= derived[i] ^ expectedHash[i];
-    }
-    return diff === 0;
+    return null;
 }
 // ---------------------------------------------------------------------------
-// Users table — email/password accounts
+// Public path matching
 // ---------------------------------------------------------------------------
-let _usersTableReady = false;
-async function ensureUsersTable() {
-    if (_usersTableReady)
-        return;
-    const client = getDbExec();
-    await client.execute(`
-    CREATE TABLE IF NOT EXISTS users (
-      email TEXT PRIMARY KEY,
-      password_hash TEXT NOT NULL,
-      created_at ${intType()} NOT NULL
-    )
-  `);
-    _usersTableReady = true;
-}
-async function createUser(email, password) {
-    await ensureUsersTable();
-    const client = getDbExec();
-    // Check if user already exists
-    const { rows } = await client.execute({
-        sql: `SELECT email FROM users WHERE email = ?`,
-        args: [email],
-    });
-    if (rows.length > 0) {
-        return { ok: false, error: "An account with this email already exists" };
-    }
-    const passwordHash = await hashPassword(password);
-    await client.execute({
-        sql: `INSERT INTO users (email, password_hash, created_at) VALUES (?, ?, ?)`,
-        args: [email, passwordHash, Date.now()],
-    });
-    return { ok: true };
-}
-async function authenticateUser(email, password) {
-    await ensureUsersTable();
-    const client = getDbExec();
-    const { rows } = await client.execute({
-        sql: `SELECT password_hash FROM users WHERE email = ?`,
-        args: [email],
-    });
-    if (rows.length === 0)
-        return false;
-    return verifyPassword(password, rows[0].password_hash);
+function isPublicPath(url, publicPaths) {
+    const p = url.split("?")[0];
+    return publicPaths.some((pp) => p === pp || p.startsWith(pp + "/"));
 }
 // ---------------------------------------------------------------------------
-// Login page HTML
+// Login page HTML (ACCESS_TOKEN mode)
 // ---------------------------------------------------------------------------
-const LOGIN_HTML = `<!DOCTYPE html>
+const TOKEN_LOGIN_HTML = `<!DOCTYPE html>
 <html lang="en">
 <head>
 <meta charset="UTF-8">
-<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">
 <title>Sign in</title>
 <style>
   *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
@@ -391,7 +411,6 @@ const LOGIN_HTML = `<!DOCTYPE html>
     color: #e5e5e5;
     font-size: 0.9375rem;
     outline: none;
-    transition: border-color 0.15s;
   }
   input:focus { border-color: rgba(255,255,255,0.3); }
   button {
@@ -405,7 +424,6 @@ const LOGIN_HTML = `<!DOCTYPE html>
     font-size: 0.9375rem;
     font-weight: 500;
     cursor: pointer;
-    transition: opacity 0.15s;
   }
   button:hover { opacity: 0.85; }
   .error { margin-top: 0.75rem; font-size: 0.8125rem; color: #f87171; display: none; }
@@ -441,241 +459,106 @@ const LOGIN_HTML = `<!DOCTYPE html>
 </body>
 </html>`;
 // ---------------------------------------------------------------------------
-// Email/password auth HTML — combined login + register page
+// setAuthModeLocal — write AUTH_MODE=local to .env for the escape hatch
 // ---------------------------------------------------------------------------
-const EMAIL_AUTH_HTML = `<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="UTF-8">
-<meta name="viewport" content="width=device-width, initial-scale=1.0">
-<title>Sign in</title>
-<style>
-  *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
-  body {
-    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
-    background: #0a0a0a;
-    color: #e5e5e5;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    min-height: 100vh;
-  }
-  .card {
-    width: 100%;
-    max-width: 380px;
-    padding: 2rem;
-    background: #141414;
-    border: 1px solid rgba(255,255,255,0.08);
-    border-radius: 12px;
-  }
-  .tabs {
-    display: inline-flex;
-    width: 100%;
-    padding: 4px;
-    margin-bottom: 1.5rem;
-    background: rgba(255,255,255,0.06);
-    border-radius: 8px;
-  }
-  .tab {
-    flex: 1;
-    padding: 0.5rem 0.75rem;
-    background: none;
-    border: none;
-    color: #888;
-    font-size: 0.8125rem;
-    font-weight: 500;
-    cursor: pointer;
-    border-radius: 6px;
-  }
-  .tab.active {
-    background: #1e1e1e;
-    color: #fff;
-    box-shadow: 0 1px 2px rgba(0,0,0,0.3);
-  }
-  .tab:hover:not(.active) { color: #bbb; }
-  .form { display: none; }
-  .form.active { display: block; }
-  label { display: block; font-size: 0.8125rem; color: #888; margin-bottom: 0.375rem; }
-  input {
-    width: 100%;
-    padding: 0.5rem 0.75rem;
-    background: transparent;
-    border: 1px solid rgba(255,255,255,0.12);
-    border-radius: 6px;
-    color: #e5e5e5;
-    font-size: 0.875rem;
-    outline: none;
-    margin-bottom: 0.875rem;
-  }
-  input:focus { border-color: rgba(255,255,255,0.3); box-shadow: 0 0 0 1px rgba(255,255,255,0.1); }
-  input::placeholder { color: #555; }
-  button[type="submit"] {
-    width: 100%;
-    margin-top: 0.25rem;
-    padding: 0.5rem;
-    background: #fff;
-    color: #000;
-    border: none;
-    border-radius: 6px;
-    font-size: 0.875rem;
-    font-weight: 500;
-    cursor: pointer;
-  }
-  button[type="submit"]:hover { background: #e5e5e5; }
-  button[type="submit"]:disabled { opacity: 0.5; cursor: not-allowed; }
-  .msg { margin-top: 0.75rem; font-size: 0.8125rem; display: none; }
-  .msg.error { color: #f87171; }
-  .msg.success { color: #4ade80; }
-  .msg.show { display: block; }
-</style>
-</head>
-<body>
-<div class="card">
-  <div class="tabs">
-    <button class="tab active" data-tab="login">Sign in</button>
-    <button class="tab" data-tab="register">Create account</button>
-  </div>
-  <form id="login-form" class="form active">
-    <label for="l-email">Email</label>
-    <input id="l-email" type="email" autocomplete="email" autofocus placeholder="you@example.com" required />
-    <label for="l-pass">Password</label>
-    <input id="l-pass" type="password" autocomplete="current-password" placeholder="Enter password" required />
-    <button type="submit">Sign in</button>
-    <p class="msg error" id="l-err"></p>
-  </form>
-  <form id="register-form" class="form">
-    <label for="r-email">Email</label>
-    <input id="r-email" type="email" autocomplete="email" placeholder="you@example.com" required />
-    <label for="r-pass">Password</label>
-    <input id="r-pass" type="password" autocomplete="new-password" placeholder="At least 8 characters" required minlength="8" />
-    <label for="r-pass2">Confirm password</label>
-    <input id="r-pass2" type="password" autocomplete="new-password" placeholder="Confirm password" required minlength="8" />
-    <button type="submit">Create account</button>
-    <p class="msg" id="r-msg"></p>
-  </form>
-</div>
-<script>
-  const tabs = document.querySelectorAll('.tab');
-  const forms = document.querySelectorAll('.form');
-  tabs.forEach(t => t.addEventListener('click', () => {
-    tabs.forEach(x => x.classList.remove('active'));
-    forms.forEach(x => x.classList.remove('active'));
-    t.classList.add('active');
-    document.getElementById(t.dataset.tab + '-form').classList.add('active');
-  }));
-
-  document.getElementById('login-form').addEventListener('submit', async (e) => {
-    e.preventDefault();
-    const err = document.getElementById('l-err');
-    err.classList.remove('show');
-    const res = await fetch('/_agent-native/auth/login', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        email: document.getElementById('l-email').value,
-        password: document.getElementById('l-pass').value,
-      }),
-    });
-    if (res.ok) {
-      window.location.reload();
-    } else {
-      const data = await res.json().catch(() => ({}));
-      err.textContent = data.error || 'Invalid email or password';
-      err.classList.add('show');
+async function setAuthModeLocal() {
+    try {
+        const fs = await getFs();
+        fs.mkdirSync(path.dirname(LOCAL_MODE_MARKER_PATH), { recursive: true });
+        fs.writeFileSync(LOCAL_MODE_MARKER_PATH, "local\n", "utf-8");
+        process.env.AUTH_MODE = "local";
+        return true;
     }
-  });
-
-  document.getElementById('register-form').addEventListener('submit', async (e) => {
-    e.preventDefault();
-    const msg = document.getElementById('r-msg');
-    msg.classList.remove('show', 'error', 'success');
-    const pass = document.getElementById('r-pass').value;
-    const pass2 = document.getElementById('r-pass2').value;
-    if (pass !== pass2) {
-      msg.textContent = 'Passwords do not match';
-      msg.classList.add('show', 'error');
-      return;
+    catch {
+        return false;
     }
-    const res = await fetch('/_agent-native/auth/register', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        email: document.getElementById('r-email').value,
-        password: pass,
-      }),
-    });
-    const data = await res.json().catch(() => ({}));
-    if (res.ok) {
-      msg.textContent = 'Account created — signing you in...';
-      msg.classList.add('show', 'success');
-      // Auto-login after registration
-      const loginRes = await fetch('/_agent-native/auth/login', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({
-          email: document.getElementById('r-email').value,
-          password: pass,
-        }),
-      });
-      if (loginRes.ok) {
-        window.location.reload();
-      }
-    } else {
-      msg.textContent = data.error || 'Registration failed';
-      msg.classList.add('show', 'error');
+}
+async function removeAuthModeLocal() {
+    try {
+        const fs = await getFs();
+        try {
+            fs.unlinkSync(LOCAL_MODE_MARKER_PATH);
+        }
+        catch {
+            // Marker already absent
+        }
+        delete process.env.AUTH_MODE;
+        return true;
     }
-  });
-</script>
-</body>
-</html>`;
+    catch {
+        return false;
+    }
+}
 // ---------------------------------------------------------------------------
-// mountEmailAuthRoutes — email/password registration + login
+// mountBetterAuthRoutes — Better Auth powered auth with backward-compat routes
 // ---------------------------------------------------------------------------
-function mountEmailAuthRoutes(app, publicPaths = []) {
-    // Also support ACCESS_TOKEN login for backward compat (API callers, scripts)
+async function mountBetterAuthRoutes(app, options) {
+    const publicPaths = [...(options.publicPaths ?? [])];
+    // The A2A agent card is part of an open protocol — other agents must be
+    // able to discover it without auth. Same for favicons and similar probes.
+    for (const pp of ["/.well-known", "/favicon.ico", "/favicon.png"]) {
+        if (!publicPaths.includes(pp))
+            publicPaths.push(pp);
+    }
+    // Auto-add Google OAuth routes when credentials are configured
+    if (process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET) {
+        for (const gp of [
+            "/_agent-native/google/callback",
+            "/_agent-native/google/auth-url",
+        ]) {
+            if (!publicPaths.includes(gp))
+                publicPaths.push(gp);
+        }
+    }
     const accessTokens = getAccessTokens();
-    // POST /_agent-native/auth/register
-    app.use("/_agent-native/auth/register", defineEventHandler(async (event) => {
+    // Initialize Better Auth
+    const auth = await getBetterAuth(options.betterAuth);
+    // Mount Better Auth catch-all handler at /_agent-native/auth/ba/*
+    app.use("/_agent-native/auth/ba", defineEventHandler(async (event) => {
+        const response = await auth.handler(toWebRequest(event));
+        return response;
+    }));
+    // POST /_agent-native/auth/local-mode — switch to local mode (onboarding escape hatch)
+    // Only available in dev — production requires real accounts for usage tracking.
+    app.use("/_agent-native/auth/local-mode", defineEventHandler(async (event) => {
         if (getMethod(event) !== "POST") {
             setResponseStatus(event, 405);
             return { error: "Method not allowed" };
         }
-        const ip = getClientIp(event);
-        const limited = checkRateLimit(event, `register:${ip}`);
-        if (limited)
-            return limited;
-        const body = await readBody(event);
-        const email = body?.email?.trim?.()?.toLowerCase?.();
-        const password = body?.password;
-        if (!email || typeof email !== "string" || !email.includes("@")) {
-            setResponseStatus(event, 400);
-            return { error: "Valid email is required" };
+        if (!isDevEnvironment()) {
+            setResponseStatus(event, 403);
+            return {
+                error: "Local mode is not available in production. Create an account to continue.",
+            };
         }
-        if (!password || typeof password !== "string" || password.length < 8) {
-            setResponseStatus(event, 400);
-            return { error: "Password must be at least 8 characters" };
+        const ok = await setAuthModeLocal();
+        if (!ok) {
+            setResponseStatus(event, 500);
+            return { error: "Failed to enable local mode" };
         }
-        const result = await createUser(email, password);
-        if (!result.ok) {
-            setResponseStatus(event, 409);
-            return { error: result.error };
+        return { ok: true };
+    }));
+    // POST /_agent-native/auth/exit-local-mode — switch back to real auth
+    app.use("/_agent-native/auth/exit-local-mode", defineEventHandler(async (event) => {
+        if (getMethod(event) !== "POST") {
+            setResponseStatus(event, 405);
+            return { error: "Method not allowed" };
+        }
+        const ok = await removeAuthModeLocal();
+        if (!ok) {
+            setResponseStatus(event, 500);
+            return { error: "Failed to disable local mode" };
         }
-        resetRateLimit(`register:${ip}`);
         return { ok: true };
     }));
-    // POST /_agent-native/auth/login — email/password or legacy ACCESS_TOKEN
+    // Backward-compat: POST /_agent-native/auth/login
     app.use("/_agent-native/auth/login", defineEventHandler(async (event) => {
         if (getMethod(event) !== "POST") {
             setResponseStatus(event, 405);
             return { error: "Method not allowed" };
         }
-        const ip = getClientIp(event);
-        const rateLimitKey = `login:${ip}`;
-        const limited = checkRateLimit(event, rateLimitKey);
-        if (limited)
-            return limited;
         const body = await readBody(event);
-        // Legacy: ACCESS_TOKEN login (for API callers, scripts)
+        // Legacy ACCESS_TOKEN login
         if (body?.token &&
             typeof body.token === "string" &&
             accessTokens.length > 0) {
@@ -687,44 +570,81 @@ function mountEmailAuthRoutes(app, publicPaths = []) {
             await addSession(sessionToken, "user");
             setCookie(event, COOKIE_NAME, sessionToken, {
                 httpOnly: true,
-                secure: process.env.NODE_ENV === "production",
+                secure: !isDevEnvironment(),
                 sameSite: "lax",
                 path: "/",
                 maxAge: sessionMaxAge,
             });
-            resetRateLimit(rateLimitKey);
             return { ok: true };
         }
-        // Email/password login
+        // Email/password login via Better Auth
         const email = body?.email?.trim?.()?.toLowerCase?.();
         const password = body?.password;
         if (!email || !password) {
             setResponseStatus(event, 400);
             return { error: "Email and password are required" };
         }
-        const valid = await authenticateUser(email, password);
-        if (!valid) {
+        try {
+            const result = await auth.api.signInEmail({
+                body: { email, password },
+            });
+            if (result?.token) {
+                setCookie(event, COOKIE_NAME, result.token, {
+                    httpOnly: true,
+                    secure: !isDevEnvironment(),
+                    sameSite: "lax",
+                    path: "/",
+                    maxAge: sessionMaxAge,
+                });
+                await addSession(result.token, email);
+            }
+            return { ok: true };
+        }
+        catch (e) {
             setResponseStatus(event, 401);
-            return { error: "Invalid email or password" };
+            return { error: e?.message || "Invalid email or password" };
+        }
+    }));
+    // Backward-compat: POST /_agent-native/auth/register
+    app.use("/_agent-native/auth/register", defineEventHandler(async (event) => {
+        if (getMethod(event) !== "POST") {
+            setResponseStatus(event, 405);
+            return { error: "Method not allowed" };
+        }
+        const body = await readBody(event);
+        const email = body?.email?.trim?.()?.toLowerCase?.();
+        const password = body?.password;
+        if (!email || typeof email !== "string" || !email.includes("@")) {
+            setResponseStatus(event, 400);
+            return { error: "Valid email is required" };
+        }
+        if (!password || typeof password !== "string" || password.length < 8) {
+            setResponseStatus(event, 400);
+            return { error: "Password must be at least 8 characters" };
+        }
+        try {
+            await auth.api.signUpEmail({
+                body: { email, password, name: email.split("@")[0] },
+            });
+            return { ok: true };
+        }
+        catch (e) {
+            setResponseStatus(event, 409);
+            return { error: e?.message || "Registration failed" };
         }
-        const sessionToken = crypto.randomBytes(32).toString("hex");
-        await addSession(sessionToken, email);
-        setCookie(event, COOKIE_NAME, sessionToken, {
-            httpOnly: true,
-            secure: process.env.NODE_ENV === "production",
-            sameSite: "lax",
-            path: "/",
-            maxAge: sessionMaxAge,
-        });
-        resetRateLimit(rateLimitKey);
-        return { ok: true };
     }));
-    // POST /_agent-native/auth/logout
+    // Backward-compat: POST /_agent-native/auth/logout
     app.use("/_agent-native/auth/logout", defineEventHandler(async (event) => {
         const cookie = getCookie(event, COOKIE_NAME);
         if (cookie)
             await removeSession(cookie);
         deleteCookie(event, COOKIE_NAME, { path: "/" });
+        try {
+            await auth.api.signOut({ headers: event.headers });
+        }
+        catch {
+            // Ignore if no Better Auth session
+        }
         return { ok: true };
     }));
     // GET /_agent-native/auth/session
@@ -736,60 +656,45 @@ function mountEmailAuthRoutes(app, publicPaths = []) {
         const session = await getSession(event);
         return session ?? { error: "Not authenticated" };
     }));
-    // Auth guard
-    const loginHtml = EMAIL_AUTH_HTML;
-    app.use(defineEventHandler(async (event) => {
-        const url = event.node?.req?.url ?? event.path ?? "/";
-        const p = url.split("?")[0];
-        if (p === "/_agent-native/auth/login" ||
-            p === "/_agent-native/auth/logout" ||
-            p === "/_agent-native/auth/session" ||
-            p === "/_agent-native/auth/register") {
-            return;
+    // POST /_agent-native/auth/migrate-local-data — move local-mode data to
+    // the currently signed-in account. Called by the UI after a user upgrades
+    // from local mode to a real account so they don't lose their data.
+    app.use("/_agent-native/auth/migrate-local-data", defineEventHandler(async (event) => {
+        if (getMethod(event) !== "POST") {
+            setResponseStatus(event, 405);
+            return { error: "Method not allowed" };
         }
-        if (isPublicPath(url, publicPaths))
-            return;
         const session = await getSession(event);
-        if (session)
-            return;
-        if (p.startsWith("/api/") || p.startsWith("/_agent-native/")) {
+        if (!session?.email || session.email === "local@localhost") {
             setResponseStatus(event, 401);
-            return { error: "Unauthorized" };
+            return { error: "Not authenticated as a real account" };
+        }
+        try {
+            const result = await migrateLocalUserData(session.email);
+            return { ok: true, ...result };
+        }
+        catch (e) {
+            setResponseStatus(event, 500);
+            return { error: e?.message || "Migration failed" };
         }
-        setResponseStatus(event, 200);
-        setResponseHeader(event, "Content-Type", "text/html");
-        return loginHtml;
     }));
+    // Auth guard — stored both in framework middleware registry AND in
+    // _authGuardFn so the server middleware can enforce it on ALL routes.
+    const loginHtml = options.loginHtml ?? getOnboardingHtml({ googleOnly: options.googleOnly });
+    _authGuardConfig = { loginHtml, publicPaths };
+    const guardFn = createAuthGuardFn();
+    _authGuardFn = guardFn;
+    app.use(defineEventHandler(guardFn));
 }
 // ---------------------------------------------------------------------------
-// mountAuthMiddleware — mounts login/logout/session routes + auth guard
+// mountTokenOnlyRoutes — ACCESS_TOKEN-only auth (no Better Auth)
 // ---------------------------------------------------------------------------
-/**
- * Mount auth middleware + login/logout/session routes onto an H3 app.
- *
- * @deprecated Use `autoMountAuth(app, options?)` instead for automatic
- * dev/prod behavior. This function is kept for backwards compatibility
- * when you need explicit control over the access token.
- */
-export function mountAuthMiddleware(app, accessToken) {
-    mountAuthRoutes(app, [accessToken]);
-}
-function isPublicPath(url, publicPaths) {
-    const p = url.split("?")[0];
-    return publicPaths.some((pp) => p === pp || p.startsWith(pp + "/"));
-}
-function mountAuthRoutes(app, accessTokens, publicPaths = []) {
-    // POST /_agent-native/auth/login
+function mountTokenOnlyRoutes(app, accessTokens, publicPaths = []) {
     app.use("/_agent-native/auth/login", defineEventHandler(async (event) => {
         if (getMethod(event) !== "POST") {
             setResponseStatus(event, 405);
             return { error: "Method not allowed" };
         }
-        const ip = getClientIp(event);
-        const rateLimitKey = `login:${ip}`;
-        const limited = checkRateLimit(event, rateLimitKey);
-        if (limited)
-            return limited;
         const body = await readBody(event);
         if (!body?.token ||
             typeof body.token !== "string" ||
@@ -801,15 +706,13 @@ function mountAuthRoutes(app, accessTokens, publicPaths = []) {
         await addSession(sessionToken, "user");
         setCookie(event, COOKIE_NAME, sessionToken, {
             httpOnly: true,
-            secure: process.env.NODE_ENV === "production",
+            secure: !isDevEnvironment(),
             sameSite: "lax",
             path: "/",
             maxAge: sessionMaxAge,
         });
-        resetRateLimit(rateLimitKey);
         return { ok: true };
     }));
-    // POST /_agent-native/auth/logout
     app.use("/_agent-native/auth/logout", defineEventHandler(async (event) => {
         const cookie = getCookie(event, COOKIE_NAME);
         if (cookie)
@@ -817,7 +720,6 @@ function mountAuthRoutes(app, accessTokens, publicPaths = []) {
         deleteCookie(event, COOKIE_NAME, { path: "/" });
         return { ok: true };
     }));
-    // GET /_agent-native/auth/session — client session check
     app.use("/_agent-native/auth/session", defineEventHandler(async (event) => {
         if (getMethod(event) !== "GET") {
             setResponseStatus(event, 405);
@@ -826,68 +728,205 @@ function mountAuthRoutes(app, accessTokens, publicPaths = []) {
         const session = await getSession(event);
         return session ?? { error: "Not authenticated" };
     }));
-    // Auth guard — runs before all other handlers
-    app.use(defineEventHandler(async (event) => {
-        const url = event.node?.req?.url ?? event.path ?? "/";
-        const p = url.split("?")[0];
-        // Skip auth routes
-        if (p === "/_agent-native/auth/login" ||
-            p === "/_agent-native/auth/logout" ||
-            p === "/_agent-native/auth/session") {
-            return;
+    _authGuardConfig = { loginHtml: TOKEN_LOGIN_HTML, publicPaths };
+    const guardFn = createAuthGuardFn();
+    _authGuardFn = guardFn;
+    app.use(defineEventHandler(guardFn));
+}
+// ---------------------------------------------------------------------------
+// mountLocalModeRoutes — stub routes for AUTH_MODE=local
+// ---------------------------------------------------------------------------
+function mountLocalModeRoutes(app) {
+    app.use("/_agent-native/auth/session", defineEventHandler(async (event) => {
+        if (getMethod(event) !== "GET") {
+            setResponseStatus(event, 405);
+            return { error: "Method not allowed" };
         }
-        // Skip public paths
-        if (isPublicPath(url, publicPaths)) {
-            return;
+        return await getSession(event);
+    }));
+    app.use("/_agent-native/auth/login", defineEventHandler(() => ({ ok: true })));
+    app.use("/_agent-native/auth/logout", defineEventHandler(() => ({ ok: true })));
+    // Allow exiting local mode to switch to real auth
+    app.use("/_agent-native/auth/exit-local-mode", defineEventHandler(async (event) => {
+        if (getMethod(event) !== "POST") {
+            setResponseStatus(event, 405);
+            return { error: "Method not allowed" };
         }
-        // Use getSession() so BYOA custom auth is respected
-        const session = await getSession(event);
-        if (session) {
-            return; // Authenticated
+        const ok = await removeAuthModeLocal();
+        if (!ok) {
+            setResponseStatus(event, 500);
+            return { error: "Failed to disable local mode" };
         }
-        // Unauthenticated
-        if (p.startsWith("/api/") || p.startsWith("/_agent-native/")) {
+        return { ok: true };
+    }));
+}
+// ---------------------------------------------------------------------------
+// mountAuthFallbackRoutes — minimal auth endpoints when Better Auth init fails
+// ---------------------------------------------------------------------------
+function mountAuthFallbackRoutes(app) {
+    app.use("/_agent-native/auth/login", defineEventHandler(async (event) => {
+        if (getMethod(event) !== "POST") {
+            setResponseStatus(event, 405);
+            return { error: "Method not allowed" };
+        }
+        const body = await readBody(event);
+        const email = body?.email?.trim?.()?.toLowerCase?.();
+        const password = body?.password;
+        if (!email || !password) {
+            setResponseStatus(event, 400);
+            return { error: "Email and password are required" };
+        }
+        try {
+            const auth = await getBetterAuth();
+            const result = await auth.api.signInEmail({
+                body: { email, password },
+            });
+            if (result?.token) {
+                setCookie(event, COOKIE_NAME, result.token, {
+                    httpOnly: true,
+                    secure: !isDevEnvironment(),
+                    sameSite: "lax",
+                    path: "/",
+                    maxAge: sessionMaxAge,
+                });
+                await addSession(result.token, email);
+            }
+            return { ok: true };
+        }
+        catch (e) {
             setResponseStatus(event, 401);
-            return { error: "Unauthorized" };
+            return { error: e?.message || "Invalid email or password" };
+        }
+    }));
+    app.use("/_agent-native/auth/register", defineEventHandler(async (event) => {
+        if (getMethod(event) !== "POST") {
+            setResponseStatus(event, 405);
+            return { error: "Method not allowed" };
+        }
+        const body = await readBody(event);
+        const email = body?.email?.trim?.()?.toLowerCase?.();
+        const password = body?.password;
+        if (!email || typeof email !== "string" || !email.includes("@")) {
+            setResponseStatus(event, 400);
+            return { error: "Valid email is required" };
+        }
+        if (!password || typeof password !== "string" || password.length < 8) {
+            setResponseStatus(event, 400);
+            return { error: "Password must be at least 8 characters" };
+        }
+        try {
+            const auth = await getBetterAuth();
+            await auth.api.signUpEmail({
+                body: { email, password, name: email.split("@")[0] },
+            });
+            return { ok: true };
+        }
+        catch (e) {
+            setResponseStatus(event, 409);
+            return { error: e?.message || "Registration failed" };
         }
-        setResponseStatus(event, 200);
-        setResponseHeader(event, "Content-Type", "text/html");
-        return LOGIN_HTML;
+    }));
+    app.use("/_agent-native/auth/logout", defineEventHandler(async (event) => {
+        const cookie = getCookie(event, COOKIE_NAME);
+        if (cookie)
+            await removeSession(cookie);
+        deleteCookie(event, COOKIE_NAME, { path: "/" });
+        try {
+            const auth = await getBetterAuth();
+            await auth.api.signOut({ headers: event.headers });
+        }
+        catch {
+            // Ignore if Better Auth is still unavailable
+        }
+        return { ok: true };
+    }));
+    app.use("/_agent-native/auth/local-mode", defineEventHandler(async (event) => {
+        if (getMethod(event) !== "POST") {
+            setResponseStatus(event, 405);
+            return { error: "Method not allowed" };
+        }
+        if (!isDevEnvironment()) {
+            setResponseStatus(event, 403);
+            return {
+                error: "Local mode is not available in production. Create an account to continue.",
+            };
+        }
+        const ok = await setAuthModeLocal();
+        if (!ok) {
+            setResponseStatus(event, 500);
+            return { error: "Failed to enable local mode" };
+        }
+        return { ok: true };
+    }));
+    app.use("/_agent-native/auth/exit-local-mode", defineEventHandler(async (event) => {
+        if (getMethod(event) !== "POST") {
+            setResponseStatus(event, 405);
+            return { error: "Method not allowed" };
+        }
+        const ok = await removeAuthModeLocal();
+        if (!ok) {
+            setResponseStatus(event, 500);
+            return { error: "Failed to disable local mode" };
+        }
+        return { ok: true };
+    }));
+    app.use("/_agent-native/auth/session", defineEventHandler(async (event) => {
+        if (getMethod(event) !== "GET") {
+            setResponseStatus(event, 405);
+            return { error: "Method not allowed" };
+        }
+        const session = await getSession(event);
+        return session ?? { error: "Not authenticated" };
     }));
 }
 // ---------------------------------------------------------------------------
 // autoMountAuth — the recommended entry point
 // ---------------------------------------------------------------------------
 /**
- * Automatically configure auth based on the environment:
- *
- * - **Dev mode** (`NODE_ENV !== "production"`): Auth is skipped entirely.
- *   `getSession()` returns `{ email: "local@localhost" }` for all requests.
+ * Automatically configure auth based on environment and configuration:
  *
- * - **Production with ACCESS_TOKEN/ACCESS_TOKENS set**: Auth middleware is
- *   mounted. Unauthenticated requests see a login page. One env var is all
- *   you need.
- *
- * - **Production without tokens and AUTH_DISABLED !== "true"**: Refuses to
- *   start. Logs a clear error explaining what to do.
- *
- * - **Production with AUTH_DISABLED=true**: Auth is skipped (for apps behind
- *   infrastructure-level auth like Cloudflare Access or a VPN).
+ * - **AUTH_MODE=local**: Auth bypassed. `getSession()` returns `{ email: "local@localhost" }`.
+ *   This is the explicit escape hatch for solo local development.
+ * - **BYOA (custom getSession)**: Template-provided auth callback handles everything.
+ * - **AUTH_DISABLED=true**: Auth bypassed (for infrastructure-level auth like Cloudflare Access).
+ * - **ACCESS_TOKEN/ACCESS_TOKENS**: Simple token-based auth.
+ * - **Default**: Better Auth with email/password, social providers, organizations, and JWT.
+ *   Users see an onboarding page to create an account on first visit.
  *
  * Returns true if auth was mounted, false if skipped.
  */
-export function autoMountAuth(app, options = {}) {
-    // In Nitro 3.0 dev mode, the H3 app may not be available yet.
-    // In dev mode auth is bypassed anyway, so we can safely skip.
+export async function autoMountAuth(app, options = {}) {
+    // If auth is already mounted (e.g., default plugin ran before custom plugin),
+    // don't re-mount routes — but DO update the live config if custom options
+    // like googleOnly or loginHtml were provided. This fixes the production race
+    // where the default plugin (no googleOnly) mounts first, and the template's
+    // custom auth plugin runs later. Because createAuthGuardFn() reads from
+    // _authGuardConfig on every request, updating it here takes effect immediately.
+    if (_authGuardFn) {
+        if (_authGuardConfig) {
+            if (options.googleOnly || options.loginHtml) {
+                _authGuardConfig.loginHtml =
+                    options.loginHtml ??
+                        getOnboardingHtml({ googleOnly: options.googleOnly });
+            }
+            if (options.publicPaths) {
+                _authGuardConfig.publicPaths = [
+                    ...(_authGuardConfig.publicPaths ?? []),
+                    ...options.publicPaths,
+                ];
+            }
+        }
+        return true;
+    }
     if (!app) {
-        if (isDevMode()) {
+        if ((await isLocalModeEnabled()) || isDevEnvironment()) {
             authDisabledMode = false;
             customGetSession = null;
             return false;
         }
         throw new Error("autoMountAuth: H3 app is required. In Nitro plugins, pass nitroApp.h3App.");
     }
-    // Reset globals to avoid stale state from prior calls
+    // Reset globals
     customGetSession = null;
     authDisabledMode = false;
     sessionMaxAge = options.maxAge ?? DEFAULT_MAX_AGE;
@@ -895,24 +934,23 @@ export function autoMountAuth(app, options = {}) {
     if (options.getSession) {
         customGetSession = options.getSession;
     }
-    // Dev mode — skip auth entirely
-    if (isDevMode()) {
-        // Mount a session endpoint that checks for a real session first
-        app.use("/_agent-native/auth/session", defineEventHandler(async (event) => {
-            if (getMethod(event) !== "GET") {
-                setResponseStatus(event, 405);
-                return { error: "Method not allowed" };
-            }
-            return await getSession(event);
-        }));
-        // Mount no-op login/logout so client code doesn't break
-        app.use("/_agent-native/auth/login", defineEventHandler(() => ({ ok: true })));
-        app.use("/_agent-native/auth/logout", defineEventHandler(() => ({ ok: true })));
+    // AUTH_MODE=local — explicit local-only mode (escape hatch)
+    if (await isLocalModeEnabled()) {
+        try {
+            // Mount the standard auth endpoints and guard even in local mode so the
+            // app can switch back to real auth immediately after AUTH_MODE is
+            // cleared, without waiting for a server restart/remount.
+            await mountBetterAuthRoutes(app, options);
+        }
+        catch (err) {
+            console.error("[agent-native] Failed to initialize Better Auth in local mode:", err);
+            mountLocalModeRoutes(app);
+        }
+        console.log("[agent-native] Auth mode: local (upgrade path enabled).");
         return false;
     }
-    // BYOA with custom getSession — skip token check, mount session/guard routes
+    // BYOA — custom getSession provider
     if (customGetSession) {
-        // Mount session endpoint
         app.use("/_agent-native/auth/session", defineEventHandler(async (event) => {
             if (getMethod(event) !== "GET") {
                 setResponseStatus(event, 405);
@@ -929,65 +967,57 @@ export function autoMountAuth(app, options = {}) {
             deleteCookie(event, COOKIE_NAME, { path: "/" });
             return { ok: true };
         }));
-        // Mount auth guard that delegates to custom getSession
-        const byoaLoginHtml = options.loginHtml ?? LOGIN_HTML;
-        app.use(defineEventHandler(async (event) => {
-            // Use H3's getRequestURL for cross-platform compat (Node + Workers)
-            const url = event.node?.req?.url ?? event.path ?? "/";
-            const p = url.split("?")[0];
-            if (p === "/_agent-native/auth/login" ||
-                p === "/_agent-native/auth/logout" ||
-                p === "/_agent-native/auth/session") {
-                return;
-            }
-            // Skip public paths
-            if (isPublicPath(url, publicPaths)) {
-                return;
-            }
-            const session = await getSession(event);
-            if (session)
-                return;
-            if (p.startsWith("/api/") || p.startsWith("/_agent-native/")) {
-                setResponseStatus(event, 401);
-                return { error: "Unauthorized" };
-            }
-            setResponseStatus(event, 200);
-            setResponseHeader(event, "Content-Type", "text/html");
-            return byoaLoginHtml;
-        }));
+        const byoaLoginHtml = options.loginHtml ?? TOKEN_LOGIN_HTML;
+        _authGuardConfig = { loginHtml: byoaLoginHtml, publicPaths };
+        const guardFn = createAuthGuardFn();
+        _authGuardFn = guardFn;
+        app.use(defineEventHandler(guardFn));
         console.log("[agent-native] Auth enabled — custom getSession provider.");
         return true;
     }
-    // Production — check for tokens
+    // AUTH_DISABLED — skip auth (infrastructure-level auth)
+    if (process.env.AUTH_DISABLED === "true") {
+        authDisabledMode = true;
+        console.warn("[agent-native] AUTH_DISABLED=true — running without auth. " +
+            "Ensure this app is behind infrastructure-level auth (Cloudflare Access, VPN, etc.).");
+        mountLocalModeRoutes(app);
+        return false;
+    }
+    // ACCESS_TOKEN-only mode
     const tokens = getAccessTokens();
-    if (tokens.length === 0) {
-        // No tokens set — check if auth is explicitly disabled
-        if (process.env.AUTH_DISABLED === "true") {
-            authDisabledMode = true;
-            console.warn("[agent-native] AUTH_DISABLED=true — running in production without auth. " +
-                "Ensure this app is behind infrastructure-level auth (Cloudflare Access, VPN, etc.).");
-            // Mount session endpoint
-            app.use("/_agent-native/auth/session", defineEventHandler(async (event) => {
-                if (getMethod(event) !== "GET") {
-                    setResponseStatus(event, 405);
-                    return { error: "Method not allowed" };
-                }
-                return await getSession(event);
-            }));
-            app.use("/_agent-native/auth/login", defineEventHandler(() => ({ ok: true })));
-            app.use("/_agent-native/auth/logout", defineEventHandler(() => ({ ok: true })));
-            return false;
-        }
-        // No access tokens set — enable email/password authentication
-        pruneExpiredSessions().catch(() => { });
-        mountEmailAuthRoutes(app, publicPaths);
-        console.log("[agent-native] Auth enabled — email/password authentication.");
+    if (tokens.length > 0) {
+        mountTokenOnlyRoutes(app, tokens, publicPaths);
+        console.log(`[agent-native] Auth enabled — ${tokens.length} access token(s) configured.`);
         return true;
     }
-    // Production with tokens — mount auth
-    pruneExpiredSessions().catch(() => { });
-    mountAuthRoutes(app, tokens, publicPaths);
-    console.log(`[agent-native] Auth enabled — ${tokens.length} access token(s) configured.`);
+    // Default: Better Auth (account-first)
+    try {
+        await mountBetterAuthRoutes(app, options);
+        console.log("[agent-native] Auth enabled — Better Auth (accounts + organizations).");
+    }
+    catch (err) {
+        console.error("[agent-native] Failed to initialize Better Auth:", err);
+        mountAuthFallbackRoutes(app);
+        // CRITICAL: Even if Better Auth fails, register the auth guard so
+        // unauthenticated users can't access the app. They'll see the login
+        // page but won't be able to sign in until the DB is available.
+        const loginHtml = options.loginHtml ??
+            getOnboardingHtml({ googleOnly: options.googleOnly });
+        _authGuardConfig = { loginHtml, publicPaths };
+        const guardFn = createAuthGuardFn();
+        _authGuardFn = guardFn;
+        app.use(defineEventHandler(guardFn));
+        console.log("[agent-native] Auth guard registered despite init failure — app is locked.");
+    }
     return true;
 }
+// ---------------------------------------------------------------------------
+// Deprecated — kept for backward compat
+// ---------------------------------------------------------------------------
+/**
+ * @deprecated Use `autoMountAuth(app, options?)` instead.
+ */
+export function mountAuthMiddleware(app, accessToken) {
+    mountTokenOnlyRoutes(app, [accessToken]);
+}
 //# sourceMappingURL=auth.js.map