@agent-native/core 0.6.1 → 0.7.2

package/dist/server/auth.js

@@ -14,48 +14,82 @@ import { defineEventHandler, getMethod, getQuery, setResponseHeader, setResponse
 function toWebRequest(event) {
     return event.req;
 }
-import { getDbExec, isPostgres, intType } from "../db/client.js";
+import { getDbExec, isPostgres, intType, isLocalDatabase, } from "../db/client.js";
 import { getBetterAuth, getBetterAuthSync } from "./better-auth-instance.js";
-import { getOnboardingHtml } from "./onboarding-html.js";
+import { getOnboardingHtml, getResetPasswordHtml } from "./onboarding-html.js";
 import { migrateLocalUserData } from "./local-migration.js";
 import { readBody } from "../server/h3-helpers.js";
+import { readDesktopSso, writeDesktopSso, clearDesktopSso, } from "./desktop-sso.js";
+import { isElectron as isElectronRequest } from "./google-oauth.js";
+/**
+ * Get the configured session max age. Desktop SSO broker writes from
+ * OAuth flows read this so expiration stays consistent with the cookie.
+ */
+export function getSessionMaxAge() {
+    return sessionMaxAge;
+}
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
-const COOKIE_NAME = "an_session";
+/**
+ * Cookie name for the framework's session cookie.
+ *
+ * Browsers scope cookies by host (NOT host+port — RFC 6265), so two apps
+ * running on different localhost ports share one cookie jar. When multiple
+ * templates run side-by-side (`dev:all`, the desktop app, multi-template
+ * deploys on a shared domain), they would otherwise stomp on each other's
+ * `an_session` cookie and ping-pong each other into a logged-out state.
+ *
+ * When `APP_NAME` is set, suffix the cookie so each app gets its own slot.
+ */
+const APP_NAME_SLUG = (process.env.APP_NAME || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "");
+export const COOKIE_NAME = APP_NAME_SLUG
+    ? `an_session_${APP_NAME_SLUG}`
+    : "an_session";
 const DEFAULT_MAX_AGE = 60 * 60 * 24 * 30; // 30 days
+const LOCAL_MODE_MARKER_PATH = path.resolve(process.cwd(), ".agent-native", "auth-mode");
 // ---------------------------------------------------------------------------
 // AUTH_MODE detection
 // ---------------------------------------------------------------------------
+let _warnedRemoteLocalMode = false;
 /**
  * Check if the app is in local-only mode (no auth).
  *
- * Returns true when:
- * - AUTH_MODE=local is explicitly set (escape hatch)
- * - In dev environment (NODE_ENV=development) with no explicit auth token
- *   configured (no ACCESS_TOKEN, no BYOA). This makes dev "just work"
- *   without requiring auth setup, while still respecting auth when configured.
+ * 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.
  *
- * NOTE: GOOGLE_CLIENT_ID is intentionally NOT checked here — it is used for
- * Google Calendar / Gmail API access as well as Google Sign-In, and its
- * presence alone should not force authentication. Only ACCESS_TOKEN/ACCESS_TOKENS
- * (explicit token-based auth) or a custom getSession (BYOA) signal that the
- * developer has explicitly opted into requiring authentication.
+ * 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.
  *
- * BYOA (customGetSession) opts out of dev auto-local — templates that provide
- * their own auth (e.g. Supabase) shouldn't be silently bypassed in dev.
+ * Refuses to enable on any non-local database (Postgres, Turso, D1): local
+ * mode uses a single shared virtual user with no per-machine scoping, so on
+ * a shared DB every developer would land on the same account and collide.
  */
-function isLocalMode() {
+async function isLocalModeEnabled() {
+    if (!isLocalDatabase()) {
+        if (process.env.AUTH_MODE === "local" && !_warnedRemoteLocalMode) {
+            _warnedRemoteLocalMode = true;
+            console.warn("[agent-native] AUTH_MODE=local ignored: database is not local SQLite. " +
+                "local@localhost has no per-user scoping and would collide across developers on a shared DB.");
+        }
+        return false;
+    }
     if (process.env.AUTH_MODE === "local")
         return true;
-    // Default to local mode in dev when no explicit auth is configured
-    if (isDevEnvironment() &&
-        !process.env.ACCESS_TOKEN &&
-        !process.env.ACCESS_TOKENS &&
-        !customGetSession) {
-        return true;
+    try {
+        const fs = await getFs();
+        const mode = fs.readFileSync(LOCAL_MODE_MARKER_PATH, "utf-8").trim();
+        return mode === "local";
+    }
+    catch {
+        return false;
     }
-    return false;
 }
 /**
  * Check if we're in a development/test environment.
@@ -179,6 +213,15 @@ let _authGuardConfig = null;
  * /_agent-native/* routes).
  */
 let _authGuardFn = null;
+/**
+ * The H3 app the auth routes + guard were last mounted on. Module-level
+ * state survives Vite HMR restarts, but each HMR cycle creates a fresh
+ * nitroApp/H3 instance whose middleware array is empty again. Tracking the
+ * app here lets autoMountAuth detect "same module state, new app" and
+ * re-mount routes instead of silently skipping them because `_authGuardFn`
+ * looks populated from a previous cycle.
+ */
+let _mountedApp = 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.
@@ -212,9 +255,12 @@ function createAuthGuardFn() {
         const { loginHtml, publicPaths } = config;
         const url = event.node?.req?.url ?? event.path ?? "/";
         const p = url.split("?")[0];
-        // Skip auth routes (all /_agent-native/auth/* and /_agent-native/google/*)
+        // 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.startsWith("/_agent-native/google/")) {
+            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.)
@@ -267,10 +313,11 @@ function mapBetterAuthSession(baSession) {
  * 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) {
     // 1. AUTH_MODE=local — explicit local-only mode
-    if (isLocalMode() || authDisabledMode) {
+    if ((await isLocalModeEnabled()) || authDisabledMode) {
         // Check for a real session cookie first (e.g. from Google OAuth)
         try {
             const cookie = getCookie(event, COOKIE_NAME);
@@ -315,6 +362,14 @@ export async function getSession(event) {
         const session = await customGetSession(event);
         if (session)
             return session;
+        // Desktop SSO broker: even with BYOA auth, fall back to the broker
+        // for Electron requests so cross-template SSO works for custom-auth
+        // templates too.
+        if (isElectronRequest(event)) {
+            const sso = await readDesktopSso();
+            if (sso?.email)
+                return { email: sso.email, token: sso.token };
+        }
         // Fall through to mobile _session check
     }
     else {
@@ -326,6 +381,9 @@ export async function getSession(event) {
                     headers: event.headers,
                 });
                 if (baSession?.user?.email) {
+                    // Successful real sign-in — clear the upgrade-pending marker so
+                    // the dev fallback becomes reachable again for future local work.
+                    clearUpgradePendingCookie(event);
                     return mapBetterAuthSession(baSession);
                 }
             }
@@ -337,8 +395,24 @@ export async function getSession(event) {
         const cookie = getCookie(event, COOKIE_NAME);
         if (cookie) {
             const email = await getSessionEmail(cookie);
-            if (email)
+            if (email) {
+                clearUpgradePendingCookie(event);
                 return { email, token: cookie };
+            }
+        }
+        // 5b. Desktop SSO broker fallback.
+        // Each template in the Electron desktop app has its own database, so
+        // a session token created by one template doesn't resolve in another.
+        // When an Electron request has no resolvable session, trust the
+        // home-dir SSO record written by whichever template the user signed
+        // into. Gated on Electron user-agent so no non-desktop code path
+        // consults the file.
+        if (isElectronRequest(event)) {
+            const sso = await readDesktopSso();
+            if (sso?.email) {
+                clearUpgradePendingCookie(event);
+                return { email: sso.email, token: sso.token };
+            }
         }
     }
     // 6. Mobile WebView bridge — _session query param
@@ -348,8 +422,7 @@ export async function getSession(event) {
         if (email) {
             setCookie(event, COOKIE_NAME, qToken, {
                 httpOnly: true,
-                secure: !isDevEnvironment(),
-                sameSite: "lax",
+                ...crossSiteCookieAttrs(event),
                 path: "/",
                 maxAge: sessionMaxAge,
             });
@@ -357,8 +430,113 @@ export async function getSession(event) {
             return { email, token: qToken };
         }
     }
+    // 7. Dev-mode safety net — in development on a local SQLite database, 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.
+    //
+    // Gated on isLocalDatabase() because local@localhost has no per-user scoping:
+    // on a shared DB (Postgres, Turso, D1) this fallback would land every
+    // developer on the same account and expose each other's data.
+    //
+    // EXCEPTION: if the user has explicitly exited local mode (clicked "Upgrade
+    // to real account"), they've signaled they want real auth. The upgrade
+    // cookie suppresses this fallback so the onboarding/sign-in page is served
+    // instead of silently re-authenticating them as local@localhost.
+    if (isDevEnvironment() &&
+        isLocalDatabase() &&
+        !isUpgradePending(event) &&
+        !hasSignInFlag(event)) {
+        return LOCAL_SESSION;
+    }
     return null;
 }
+/**
+ * Cookie set by POST /_agent-native/auth/exit-local-mode so we know the user
+ * is in the middle of upgrading from local@localhost to a real account.
+ * While this cookie is present we skip the dev-mode "auto local session"
+ * fallback so the onboarding/sign-in page can actually render.
+ * Cleared on successful sign-in/sign-up.
+ */
+const UPGRADE_COOKIE = "an_upgrade_pending";
+function isUpgradePending(event) {
+    try {
+        return getCookie(event, UPGRADE_COOKIE) === "1";
+    }
+    catch {
+        return false;
+    }
+}
+function setUpgradePendingCookie(event) {
+    setCookie(event, UPGRADE_COOKIE, "1", {
+        httpOnly: true,
+        ...crossSiteCookieAttrs(event),
+        path: "/",
+        maxAge: 60 * 60, // 1 hour — enough to complete sign-in
+    });
+}
+/**
+ * URL-flag fallback for third-party iframe contexts (e.g. the Builder.io
+ * editor) where SameSite=Lax cookies from an exit-local-mode POST are not
+ * delivered on the subsequent reload. TeamPage reloads with ?signin=1 so
+ * we can reliably suppress the dev-mode local fallback without a cookie.
+ */
+function hasSignInFlag(event) {
+    try {
+        return getQuery(event)?.signin === "1";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Cookie attributes that work in both same-site and third-party iframe
+ * contexts. Over HTTPS we emit `SameSite=None; Secure` (required by browsers
+ * to ship the cookie back inside a cross-origin iframe); for plain HTTP dev
+ * we keep `SameSite=Lax` since `None` requires Secure.
+ */
+function crossSiteCookieAttrs(event) {
+    return isHttpsRequest(event)
+        ? { sameSite: "none", secure: true }
+        : { sameSite: "lax", secure: false };
+}
+function isHttpsRequest(event) {
+    try {
+        const req = event.req ?? event.node?.req;
+        const headers = req?.headers;
+        const get = (k) => {
+            if (!headers)
+                return undefined;
+            if (typeof headers.get === "function") {
+                return headers.get(k) ?? undefined;
+            }
+            const v = headers[k];
+            return Array.isArray(v) ? v[0] : v;
+        };
+        const xfProto = get("x-forwarded-proto");
+        if (xfProto && String(xfProto).split(",")[0].trim() === "https") {
+            return true;
+        }
+        const url = req?.url;
+        if (typeof url === "string" && url.startsWith("https://"))
+            return true;
+        const appUrl = process.env.APP_URL || process.env.BETTER_AUTH_URL || "";
+        if (appUrl.startsWith("https://"))
+            return true;
+    }
+    catch {
+        // ignore
+    }
+    return false;
+}
+function clearUpgradePendingCookie(event) {
+    try {
+        deleteCookie(event, UPGRADE_COOKIE, { path: "/" });
+    }
+    catch {
+        // ignore
+    }
+}
 // ---------------------------------------------------------------------------
 // Public path matching
 // ---------------------------------------------------------------------------
@@ -373,7 +551,7 @@ 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; }
@@ -458,21 +636,8 @@ const TOKEN_LOGIN_HTML = `<!DOCTYPE html>
 async function setAuthModeLocal() {
     try {
         const fs = await getFs();
-        const envPath = path.resolve(process.cwd(), ".env");
-        let content = "";
-        try {
-            content = fs.readFileSync(envPath, "utf-8");
-        }
-        catch {
-            // .env doesn't exist yet
-        }
-        if (content.includes("AUTH_MODE=")) {
-            content = content.replace(/AUTH_MODE=.*/g, "AUTH_MODE=local");
-        }
-        else {
-            content = content.trimEnd() + "\nAUTH_MODE=local\n";
-        }
-        fs.writeFileSync(envPath, content, "utf-8");
+        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;
     }
@@ -483,20 +648,12 @@ async function setAuthModeLocal() {
 async function removeAuthModeLocal() {
     try {
         const fs = await getFs();
-        const envPath = path.resolve(process.cwd(), ".env");
-        let content = "";
         try {
-            content = fs.readFileSync(envPath, "utf-8");
+            fs.unlinkSync(LOCAL_MODE_MARKER_PATH);
         }
         catch {
-            return true; // No .env file means nothing to remove
-        }
-        // Remove AUTH_MODE=local line entirely
-        content = content
-            .split("\n")
-            .filter((line) => !line.match(/^\s*AUTH_MODE\s*=/))
-            .join("\n");
-        fs.writeFileSync(envPath, content, "utf-8");
+            // Marker already absent
+        }
         delete process.env.AUTH_MODE;
         return true;
     }
@@ -504,6 +661,38 @@ async function removeAuthModeLocal() {
         return false;
     }
 }
+/**
+ * POST /_agent-native/auth/migrate-local-data handler. Exposed here (not
+ * inlined in a single mount function) because it must be registered from
+ * every auth-mount path — including local-mode and fallback — so the
+ * upgrade-from-local flow never 500s when BetterAuth init is skipped or
+ * failed. Previously this was only mounted inside mountBetterAuthRoutes()
+ * which meant that in local mode (or when BetterAuth failed to init) the
+ * request fell through to the Nitro SSR renderer and produced a 500.
+ */
+const migrateLocalDataHandler = defineEventHandler(async (event) => {
+    if (getMethod(event) !== "POST") {
+        setResponseStatus(event, 405);
+        return { error: "Method not allowed" };
+    }
+    const session = await getSession(event);
+    if (!session?.email || session.email === "local@localhost") {
+        setResponseStatus(event, 401);
+        return { error: "Not authenticated as a real account" };
+    }
+    try {
+        const result = await migrateLocalUserData(session.email);
+        return { ok: true, ...result };
+    }
+    catch (e) {
+        console.error("[migrate-local-data] Migration threw for", session.email, e);
+        setResponseStatus(event, 500);
+        return {
+            error: e?.message || "Migration failed",
+            stack: isDevEnvironment() ? e?.stack : undefined,
+        };
+    }
+});
 // ---------------------------------------------------------------------------
 // mountBetterAuthRoutes — Better Auth powered auth with backward-compat routes
 // ---------------------------------------------------------------------------
@@ -549,7 +738,7 @@ async function mountBetterAuthRoutes(app, options) {
         const ok = await setAuthModeLocal();
         if (!ok) {
             setResponseStatus(event, 500);
-            return { error: "Failed to set AUTH_MODE=local in .env" };
+            return { error: "Failed to enable local mode" };
         }
         return { ok: true };
     }));
@@ -562,8 +751,11 @@ async function mountBetterAuthRoutes(app, options) {
         const ok = await removeAuthModeLocal();
         if (!ok) {
             setResponseStatus(event, 500);
-            return { error: "Failed to remove AUTH_MODE from .env" };
+            return { error: "Failed to disable local mode" };
         }
+        // Mark the browser so getSession's dev-mode fallback won't silently
+        // re-authenticate the user as local@localhost on the next request.
+        setUpgradePendingCookie(event);
         return { ok: true };
     }));
     // Backward-compat: POST /_agent-native/auth/login
@@ -585,8 +777,7 @@ async function mountBetterAuthRoutes(app, options) {
             await addSession(sessionToken, "user");
             setCookie(event, COOKIE_NAME, sessionToken, {
                 httpOnly: true,
-                secure: !isDevEnvironment(),
-                sameSite: "lax",
+                ...crossSiteCookieAttrs(event),
                 path: "/",
                 maxAge: sessionMaxAge,
             });
@@ -606,12 +797,18 @@ async function mountBetterAuthRoutes(app, options) {
             if (result?.token) {
                 setCookie(event, COOKIE_NAME, result.token, {
                     httpOnly: true,
-                    secure: !isDevEnvironment(),
-                    sameSite: "lax",
+                    ...crossSiteCookieAttrs(event),
                     path: "/",
                     maxAge: sessionMaxAge,
                 });
                 await addSession(result.token, email);
+                if (isElectronRequest(event)) {
+                    await writeDesktopSso({
+                        email,
+                        token: result.token,
+                        expiresAt: Date.now() + sessionMaxAge * 1000,
+                    });
+                }
             }
             return { ok: true };
         }
@@ -660,6 +857,8 @@ async function mountBetterAuthRoutes(app, options) {
         catch {
             // Ignore if no Better Auth session
         }
+        if (isElectronRequest(event))
+            await clearDesktopSso();
         return { ok: true };
     }));
     // GET /_agent-native/auth/session
@@ -674,24 +873,18 @@ async function mountBetterAuthRoutes(app, options) {
     // 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") {
+    app.use("/_agent-native/auth/migrate-local-data", migrateLocalDataHandler);
+    // GET /_agent-native/auth/reset — HTML page shown when a user clicks the
+    // reset link in their email. Reads ?token=... and POSTs to Better Auth's
+    // /reset-password endpoint on submit.
+    app.use("/_agent-native/auth/reset", defineEventHandler((event) => {
+        if (getMethod(event) !== "GET") {
             setResponseStatus(event, 405);
             return { error: "Method not allowed" };
         }
-        const session = await getSession(event);
-        if (!session?.email || session.email === "local@localhost") {
-            setResponseStatus(event, 401);
-            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" };
-        }
+        return new Response(getResetPasswordHtml(), {
+            headers: { "Content-Type": "text/html; charset=utf-8" },
+        });
     }));
     // Auth guard — stored both in framework middleware registry AND in
     // _authGuardFn so the server middleware can enforce it on ALL routes.
@@ -721,8 +914,7 @@ function mountTokenOnlyRoutes(app, accessTokens, publicPaths = []) {
         await addSession(sessionToken, "user");
         setCookie(event, COOKIE_NAME, sessionToken, {
             httpOnly: true,
-            secure: !isDevEnvironment(),
-            sameSite: "lax",
+            ...crossSiteCookieAttrs(event),
             path: "/",
             maxAge: sessionMaxAge,
         });
@@ -733,6 +925,8 @@ function mountTokenOnlyRoutes(app, accessTokens, publicPaths = []) {
         if (cookie)
             await removeSession(cookie);
         deleteCookie(event, COOKIE_NAME, { path: "/" });
+        if (isElectronRequest(event))
+            await clearDesktopSso();
         return { ok: true };
     }));
     app.use("/_agent-native/auth/session", defineEventHandler(async (event) => {
@@ -743,6 +937,7 @@ function mountTokenOnlyRoutes(app, accessTokens, publicPaths = []) {
         const session = await getSession(event);
         return session ?? { error: "Not authenticated" };
     }));
+    app.use("/_agent-native/auth/migrate-local-data", migrateLocalDataHandler);
     _authGuardConfig = { loginHtml: TOKEN_LOGIN_HTML, publicPaths };
     const guardFn = createAuthGuardFn();
     _authGuardFn = guardFn;
@@ -770,10 +965,150 @@ function mountLocalModeRoutes(app) {
         const ok = await removeAuthModeLocal();
         if (!ok) {
             setResponseStatus(event, 500);
-            return { error: "Failed to remove AUTH_MODE from .env" };
+            return { error: "Failed to disable local mode" };
+        }
+        // Mark the browser so getSession's dev-mode fallback won't silently
+        // re-authenticate the user as local@localhost on the next request.
+        setUpgradePendingCookie(event);
+        return { ok: true };
+    }));
+    // Upgrade path: migrate-local-data must be reachable from local mode
+    // because the user is still in local mode when they trigger the upgrade.
+    app.use("/_agent-native/auth/migrate-local-data", migrateLocalDataHandler);
+}
+// ---------------------------------------------------------------------------
+// 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,
+                    ...crossSiteCookieAttrs(event),
+                    path: "/",
+                    maxAge: sessionMaxAge,
+                });
+                await addSession(result.token, email);
+                if (isElectronRequest(event)) {
+                    await writeDesktopSso({
+                        email,
+                        token: result.token,
+                        expiresAt: Date.now() + sessionMaxAge * 1000,
+                    });
+                }
+            }
+            return { ok: true };
+        }
+        catch (e) {
+            setResponseStatus(event, 401);
+            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" };
+        }
+    }));
+    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
+        }
+        if (isElectronRequest(event))
+            await clearDesktopSso();
+        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" };
         }
+        // Mark the browser so getSession's dev-mode fallback won't silently
+        // re-authenticate the user as local@localhost on the next request.
+        setUpgradePendingCookie(event);
         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" };
+    }));
+    // Must be reachable from fallback mode too — otherwise a user who
+    // upgrades-from-local on a server that couldn't init Better Auth gets a
+    // 500 instead of a clear 401.
+    app.use("/_agent-native/auth/migrate-local-data", migrateLocalDataHandler);
 }
 // ---------------------------------------------------------------------------
 // autoMountAuth — the recommended entry point
@@ -792,13 +1127,17 @@ function mountLocalModeRoutes(app) {
  * Returns true if auth was mounted, false if skipped.
  */
 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 auth is already mounted on THIS app (e.g., default plugin ran before
+    // custom plugin in the same server boot), don't re-mount routes — but DO
+    // update the live config if custom options like googleOnly or loginHtml
+    // were provided. createAuthGuardFn() reads from _authGuardConfig on every
+    // request, so updating it here takes effect immediately.
+    //
+    // We gate on `_mountedApp === app` because module-level state survives
+    // Vite HMR — without this check, an HMR-restarted Nitro instance (fresh
+    // H3 app, empty middleware) would short-circuit here and end up with no
+    // auth routes mounted at all.
+    if (_authGuardFn && _mountedApp === app) {
         if (_authGuardConfig) {
             if (options.googleOnly || options.loginHtml) {
                 _authGuardConfig.loginHtml =
@@ -814,8 +1153,13 @@ export async function autoMountAuth(app, options = {}) {
         }
         return true;
     }
+    // Fresh app (first boot, or HMR created a new Nitro instance) — reset
+    // the guard so the mount path below installs it on the new app.
+    _authGuardFn = null;
+    _authGuardConfig = null;
+    _mountedApp = app;
     if (!app) {
-        if (isLocalMode() || isDevEnvironment()) {
+        if ((await isLocalModeEnabled()) || isDevEnvironment()) {
             authDisabledMode = false;
             customGetSession = null;
             return false;
@@ -831,11 +1175,18 @@ export async function autoMountAuth(app, options = {}) {
         customGetSession = options.getSession;
     }
     // AUTH_MODE=local — explicit local-only mode (escape hatch)
-    if (isLocalMode()) {
-        mountLocalModeRoutes(app);
-        // Still init Better Auth in background so users can create accounts later
-        getBetterAuth(options.betterAuth).catch(() => { });
-        console.log("[agent-native] Auth mode: local (no auth required).");
+    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 — custom getSession provider
@@ -854,8 +1205,11 @@ export async function autoMountAuth(app, options = {}) {
             if (cookie)
                 await removeSession(cookie);
             deleteCookie(event, COOKIE_NAME, { path: "/" });
+            if (isElectronRequest(event))
+                await clearDesktopSso();
             return { ok: true };
         }));
+        app.use("/_agent-native/auth/migrate-local-data", migrateLocalDataHandler);
         const byoaLoginHtml = options.loginHtml ?? TOKEN_LOGIN_HTML;
         _authGuardConfig = { loginHtml: byoaLoginHtml, publicPaths };
         const guardFn = createAuthGuardFn();
@@ -886,6 +1240,7 @@ export async function autoMountAuth(app, options = {}) {
     }
     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.