@agent-native/core 0.176.1 → 0.176.2-nightly-20260831184159

package/dist/server/auth.js

@@ -56,6 +56,7 @@ import { extractOAuthStateAppId, extractOAuthStateProvider, } from "../shared/oa
 import { PASSWORD_MIN_LENGTH, PASSWORD_MAX_LENGTH, PASSWORD_MAX_LENGTH_MESSAGE, PASSWORD_MIN_LENGTH_MESSAGE, } from "../shared/password-policy.js";
 import { SIGN_IN_CONTINUATION_PARAM, SIGN_IN_ENTRY_PATH, SIGN_IN_LEGACY_ENTRY_PATH, SIGN_IN_LEGACY_RETURN_PARAM, decodeContinuation, normalizeAppPath, signInJourney, } from "../shared/sign-in-journey.js";
 import { AGENT_NATIVE_SOCIAL_IMAGE_ALT, AGENT_NATIVE_SOCIAL_IMAGE_HEIGHT, AGENT_NATIVE_SOCIAL_IMAGE_PATH, AGENT_NATIVE_SOCIAL_IMAGE_TYPE, AGENT_NATIVE_SOCIAL_IMAGE_WIDTH, withAgentNativeSocialImageCacheBuster, } from "../shared/social-meta.js";
+import { getSsrAuthRedirectScript } from "../shared/ssr-auth-redirect.js";
 import { normalizeWorkspaceAppAudience, workspaceAppAudienceFromEnv, workspaceAppRouteAccessFromEnv, } from "../shared/workspace-app-audience.js";
 import { isValidWorkspaceAppIdFormat } from "../shared/workspace-app-id.js";
 import { injectAnalyticsIntoHtml } from "./analytics.js";
@@ -66,13 +67,14 @@ import { getAuthLoginMode } from "./auth-login-mode.js";
 import { injectBetaOptOutPersistence } from "./beta-opt-out-html.js";
 import { createBetterAuthSessionForEmail, ensureGoogleAuthIdentity, getBetterAuthInternalAdapter, getBetterAuthUserIdForEmail, getAuthSecret, getBetterAuth, getBetterAuthSync, isDeployPreview, } from "./better-auth-instance.js";
 import { BUILDER_CONNECT_PARAM, BUILDER_RELAY_PATH, BUILDER_RELAY_STATE_PARAM, verifyBuilderConnectTokenAndGetOwner, verifyBuilderPreviewRelayStateForCallback, } from "./builder-browser.js";
-import { resolveAuthCookieNamespace } from "./cookie-namespace.js";
+import { frameworkSessionHintCookieName, resolveAuthCookieNamespace, } from "./cookie-namespace.js";
 import { getAllowedCorsOrigin, readCorsAllowedOrigins, } from "./cors-origins.js";
 import { readDesktopSso, writeDesktopSso, clearDesktopSso, } from "./desktop-sso.js";
 import { getDeploymentEmailReadiness } from "./email.js";
 import { resolveGoogleSignInCredentials } from "./google-oauth-credentials.js";
 import { isElectron as isElectronRequest, getAppBasePath, getAppUrl, getOrigin, encodeOAuthState, decodeOAuthState, createOAuthSession, oauthCallbackResponse, oauthDesktopExchangePage, oauthErrorPage, resolveOAuthRedirectUri, isAllowedOAuthRedirectUri, } from "./google-oauth.js";
 import { isCanonicalAgentNativeAppRequest, isCanonicalIdentitySsoClientRequest, isDesktopSsoUserAgent, isIdentitySsoExplicitlyEnabled, } from "./identity-sso-store.js";
+import { healUndecryptableJwks } from "./jwks-secret-rotation.js";
 import { resolveCanonicalUserForLegacySession, } from "./legacy-auth-migration.js";
 import { encodeMagicLinkSignupAttribution, MAGIC_LINK_ATTRIBUTION_PARAM, } from "./magic-link-attribution.js";
 import { safeOAuthReturnUrl } from "./oauth-return-url.js";
@@ -153,6 +155,7 @@ export function getCookieDomain() {
     return AUTH_COOKIE_NAMESPACE.frameworkCookieDomain;
 }
 export const COOKIE_NAME = AUTH_COOKIE_NAMESPACE.frameworkCookieName;
+export const SESSION_HINT_COOKIE = frameworkSessionHintCookieName(COOKIE_NAME);
 export const BETTER_AUTH_COOKIE_PREFIX = AUTH_COOKIE_NAMESPACE.betterAuthCookiePrefix;
 const AUTH_DISABLED_OPT_OUT_COOKIE = `${COOKIE_NAME}_auth_disabled_opt_out`;
 /**
@@ -242,15 +245,21 @@ async function enrichLegacySessionIdentity(session, canonicalUser) {
             : {}),
     };
 }
-function deleteCookieFromEveryScope(event, name) {
+function deleteCookieFromEveryScope(event, name, attributes = {}) {
     // Clear host-only cookies first. Then clear any configured domain scope so
     // stale shared cookies stop shadowing isolated app sessions.
-    deleteCookie(event, name, { path: "/" });
+    deleteCookie(event, name, { ...attributes, path: "/" });
     for (const domain of AUTH_COOKIE_NAMESPACE.frameworkCookieDomainsToClear) {
-        deleteCookie(event, name, { path: "/", domain });
+        deleteCookie(event, name, { ...attributes, path: "/", domain });
+    }
+}
+export function clearFrameworkSessionHintCookies(event) {
+    for (const name of frameworkSessionCookieNamesToClear()) {
+        deleteCookieFromEveryScope(event, frameworkSessionHintCookieName(name), crossSiteCookieAttrs(event));
     }
 }
 export function clearFrameworkSessionCookies(event) {
+    clearFrameworkSessionHintCookies(event);
     for (const name of frameworkSessionCookieNamesToClear()) {
         deleteCookieFromEveryScope(event, name);
     }
@@ -1199,10 +1208,16 @@ function getAuthOnboardingHtml(options, event, rawPath, authMode) {
     return getOnboardingHtml(getOnboardingHtmlOptions(options, event, rawPath, authMode));
 }
 function getOnboardingLoginHtmlConfig(options, authMode) {
-    if (options.loginHtml)
-        return { loginHtml: options.loginHtml, authMode };
+    if (options.loginHtml) {
+        return {
+            loginHtml: options.loginHtml,
+            authMode,
+            rootAuth: options.rootAuth ?? true,
+        };
+    }
     return {
         authMode,
+        rootAuth: options.rootAuth ?? Boolean(options.marketing),
         loginHtml: getAuthOnboardingHtml(options, undefined, undefined, authMode),
         getLoginHtml: (event, rawPath) => getAuthOnboardingHtml(options, event, rawPath, authMode),
     };
@@ -1696,6 +1711,7 @@ function applyCorsHeaders(event, publicCorsPaths = [], requestPath) {
             "X-Agent-Native-CSRF",
             "X-User-Timezone",
             "X-Agent-Native-Desktop-Verifier",
+            "X-Agent-Native-Test-Traffic",
             EMBED_TARGET_HEADER,
         ].join(","));
     return { hasOrigin: true, allowed: true };
@@ -1738,16 +1754,21 @@ function workspaceOAuthCallbackRelayResponse(event) {
     const { rawPath, search } = getRequestPathAndSearch(event);
     const normalizedPath = stripAppBasePath(rawPath);
     const basePath = getAppBasePath();
-    if (!basePath ||
-        !isWorkspaceOAuthCallbackRelayEnabled() ||
-        !isFrameworkOAuthCallbackPath(normalizedPath) ||
-        rawPath === `${basePath}/_agent-native` ||
-        rawPath.startsWith(`${basePath}/_agent-native/`)) {
+    if (!isFrameworkOAuthCallbackPath(normalizedPath) ||
+        (basePath && rawPath === `${basePath}/_agent-native`) ||
+        (basePath && rawPath.startsWith(`${basePath}/_agent-native/`))) {
         return undefined;
     }
     const state = new URLSearchParams(search.startsWith("?") ? search.slice(1) : search).get("state");
     const appId = extractOAuthStateAppId(state);
     const provider = extractOAuthStateProvider(state);
+    const isWorkspaceCallbackRelay = isWorkspaceOAuthCallbackRelayEnabled();
+    const isStandaloneGoogleProviderCallback = !isWorkspaceCallbackRelay &&
+        normalizedPath === "/_agent-native/google/callback" &&
+        isWorkspaceGoogleOAuthProvider(provider);
+    if (!isWorkspaceCallbackRelay && !isStandaloneGoogleProviderCallback) {
+        return undefined;
+    }
     const cookieAppId = !appId && !provider && normalizedPath === "/_agent-native/google/callback"
         ? extractMcpOAuthCookieAppId(event, state)
         : undefined;
@@ -1769,7 +1790,7 @@ function workspaceOAuthCallbackRelayResponse(event) {
     return new Response("", {
         status: 302,
         headers: {
-            Location: `/${effectiveAppId}${providerCallbackPath}${search}`,
+            Location: `${isWorkspaceCallbackRelay ? `/${effectiveAppId}` : basePath || ""}${providerCallbackPath}${search}`,
         },
     });
 }
@@ -2070,12 +2091,15 @@ function desktopMagicLinkLandingPage(actionUrl, fields) {
     });
 }
 function injectLoginSocialImageMeta(loginHtml, event) {
-    const headCloseIdx = loginHtml.indexOf("</head>");
-    if (headCloseIdx === -1)
+    const headCloseMatch = /<\/head\s*>/i.exec(loginHtml);
+    if (!headCloseMatch || headCloseMatch.index === undefined)
         return loginHtml;
+    const headCloseIdx = headCloseMatch.index;
     const hasAnySocialImage = LOGIN_OG_IMAGE_META_RE.test(loginHtml) ||
         LOGIN_TWITTER_IMAGE_META_RE.test(loginHtml);
-    const imageUrl = escapeHtmlAttr(withAgentNativeSocialImageCacheBuster(getAppUrl(event, AGENT_NATIVE_SOCIAL_IMAGE_PATH)));
+    const imageUrl = escapeHtmlAttr(withAgentNativeSocialImageCacheBuster(event
+        ? getAppUrl(event, AGENT_NATIVE_SOCIAL_IMAGE_PATH)
+        : `${getAppBasePath()}${AGENT_NATIVE_SOCIAL_IMAGE_PATH}`));
     const tags = [];
     if (!hasAnySocialImage) {
         tags.push(`<meta property="og:image" content="${imageUrl}">`);
@@ -2098,8 +2122,37 @@ function injectLoginSocialImageMeta(loginHtml, event) {
         tags.join("") +
         loginHtml.slice(headCloseIdx));
 }
-function loginHtmlResponse(loginHtml, event) {
-    return new Response(injectAnalyticsIntoHtml(injectLoginSocialImageMeta(injectBetaOptOutPersistence(loginHtml), event)), {
+function injectHeadScript(html, script) {
+    const headCloseMatch = /<\/head\s*>/i.exec(html);
+    if (headCloseMatch?.index !== undefined) {
+        return (html.slice(0, headCloseMatch.index) +
+            script +
+            html.slice(headCloseMatch.index));
+    }
+    const headOpenMatch = /<head\b[^>]*>/i.exec(html);
+    if (headOpenMatch?.index !== undefined) {
+        const headEnd = headOpenMatch.index + headOpenMatch[0].length;
+        return html.slice(0, headEnd) + script + html.slice(headEnd);
+    }
+    const bodyOpenMatch = /<body\b[^>]*>/i.exec(html);
+    if (bodyOpenMatch?.index !== undefined) {
+        return (html.slice(0, bodyOpenMatch.index) +
+            `<head>${script}</head>` +
+            html.slice(bodyOpenMatch.index));
+    }
+    const htmlOpenMatch = /<html\b[^>]*>/i.exec(html);
+    if (htmlOpenMatch?.index !== undefined) {
+        const htmlEnd = htmlOpenMatch.index + htmlOpenMatch[0].length;
+        return (html.slice(0, htmlEnd) + `<head>${script}</head>` + html.slice(htmlEnd));
+    }
+    return `<!doctype html><html><head>${script}</head><body>${html}</body></html>`;
+}
+function loginHtmlResponse(loginHtml, event, options = {}) {
+    let html = injectLoginSocialImageMeta(injectBetaOptOutPersistence(loginHtml), options.requestIndependent ? undefined : event);
+    if (options.includeRootAuthRedirect) {
+        html = injectHeadScript(html, getSsrAuthRedirectScript(SESSION_HINT_COOKIE));
+    }
+    return new Response(injectAnalyticsIntoHtml(html), {
         status: 200,
         headers: {
             "Content-Type": "text/html; charset=utf-8",
@@ -2137,7 +2190,6 @@ function createAuthGuardFn(app) {
         const url = event.node?.req?.url ?? event.path ?? "/";
         const queryStart = url.indexOf("?");
         const rawPath = queryStart >= 0 ? url.slice(0, queryStart) : url;
-        const loginHtml = config.getLoginHtml?.(event, rawPath) ?? config.loginHtml;
         const p = stripAppBasePath(rawPath);
         const normalizedUrl = queryStart >= 0 ? `${p}${url.slice(queryStart)}` : p;
         const callbackRelay = workspaceOAuthCallbackRelayResponse(event);
@@ -2349,6 +2401,17 @@ function createAuthGuardFn(app) {
         if (p === "/_agent-native/recap-image") {
             return;
         }
+        // The public home uses the same server-rendered auth surface as the
+        // framework sign-in entry. This is unconditional and does not inspect the
+        // request session, so the cached root document stays identical for every
+        // visitor; the head handoff handles existing sessions in the browser.
+        if (config.rootAuth && p === "/" && isHtmlDocumentRequest(event, p)) {
+            return loginHtmlResponse(config.loginHtml, event, {
+                includeRootAuthRedirect: true,
+                requestIndependent: true,
+            });
+        }
+        const loginHtml = config.getLoginHtml?.(event, rawPath) ?? config.loginHtml;
         // Force-sign-in entrypoint. Templates send viewers from public pages
         // (share links, embeds) here with a `?return=<path>` query. The clean
         // `/sign-in` path is canonical; keep the old framework path as a
@@ -2691,6 +2754,7 @@ function createLocalDevAuthHandler(config) {
                 return { error: "Local development sign-in is unavailable" };
             }
             setFrameworkSessionCookie(event, session.token);
+            setFirstRunOnboardingCookie(event);
             await addSession(session.token, session.email);
             return authLoginResponse(event, session.token, session.email);
         }
@@ -2782,6 +2846,7 @@ async function maybeAutoCreateDevSession(event, redirectTo) {
         if (!result?.token)
             return null;
         setFrameworkSessionCookie(event, result.token);
+        setFirstRunOnboardingCookie(event);
         await addSession(result.token, AUTO_DEV_ACCOUNT_EMAIL);
         // Emit the session cookie ON the 302 itself. Returning a bare
         // `new Response(...)` here drops the cookie staged on event.node.res
@@ -2991,7 +3056,7 @@ function isReadMethod(event) {
  * dev keeps the default `SameSite=Lax`; `None` requires Secure, and
  * `Partitioned` only takes effect alongside `Secure`.
  */
-function crossSiteCookieAttrs(event) {
+export function crossSiteCookieAttrs(event) {
     return isHttpsRequest(event)
         ? { sameSite: "none", secure: true, partitioned: true }
         : { sameSite: "lax", secure: false };
@@ -3011,6 +3076,7 @@ function desktopOAuthBrowserBindingCookieAttrs(event) {
 function setFirstRunOnboardingCookie(event) {
     setCookie(event, FIRST_RUN_ONBOARDING_COOKIE, "1", {
         ...crossSiteCookieAttrs(event),
+        ...cookieDomainAttrs(),
         httpOnly: false,
         path: "/",
         maxAge: FIRST_RUN_ONBOARDING_MAX_AGE,
@@ -3019,7 +3085,17 @@ function setFirstRunOnboardingCookie(event) {
 function clearFirstRunOnboardingCookie(event) {
     deleteCookie(event, FIRST_RUN_ONBOARDING_COOKIE, {
         ...crossSiteCookieAttrs(event),
+        ...cookieDomainAttrs(),
+        path: "/",
+    });
+}
+function setFrameworkSessionHintCookie(event) {
+    setCookie(event, SESSION_HINT_COOKIE, "1", {
+        ...crossSiteCookieAttrs(event),
+        ...cookieDomainAttrs(),
+        httpOnly: false,
         path: "/",
+        maxAge: sessionMaxAge,
     });
 }
 export function setFrameworkSessionCookie(event, token) {
@@ -3031,6 +3107,7 @@ export function setFrameworkSessionCookie(event, token) {
         path: "/",
         maxAge: sessionMaxAge,
     });
+    setFrameworkSessionHintCookie(event);
 }
 /**
  * Build a redirect `Response` that carries the security-sensitive headers just
@@ -4062,6 +4139,36 @@ async function mountBetterAuthRoutes(app, options) {
         const isResponse = response != null &&
             typeof response.status === "number" &&
             typeof response.headers?.get === "function";
+        if (isSignOut &&
+            isResponse &&
+            response.status >= 200 &&
+            response.status < 400) {
+            const stagedHeaders = event.res?.headers;
+            const stagedCookieCount = stagedHeaders
+                ? getSetCookieHeaders(stagedHeaders).length
+                : 0;
+            clearFrameworkSessionHintCookies(event);
+            if (stagedHeaders) {
+                for (const cookie of getSetCookieHeaders(stagedHeaders).slice(stagedCookieCount)) {
+                    response.headers.append("set-cookie", cookie);
+                }
+            }
+        }
+        if (isResponse &&
+            response.status >= 200 &&
+            response.status < 400 &&
+            extractSessionTokenFromSetCookies(response)) {
+            const stagedHeaders = event.res?.headers;
+            const stagedCookieCount = stagedHeaders
+                ? getSetCookieHeaders(stagedHeaders).length
+                : 0;
+            setFrameworkSessionHintCookie(event);
+            if (stagedHeaders) {
+                for (const cookie of getSetCookieHeaders(stagedHeaders).slice(stagedCookieCount)) {
+                    response.headers.append("set-cookie", cookie);
+                }
+            }
+        }
         if (isMagicLinkVerification && isResponse) {
             logMagicLinkVerificationResponse(event, "better-auth-catch-all", response, magicLinkPreConsume);
             if (response.status >= 200 &&
@@ -4073,6 +4180,24 @@ async function mountBetterAuthRoutes(app, options) {
                 await ensureEmailVerifiedForRedirect(authRequest, response);
             }
         }
+        // A rotated BETTER_AUTH_SECRET leaves the persisted JWKS key
+        // undecryptable, and Better Auth turns that into a 500 on any endpoint
+        // that signs a JWT (e.g. /token). The get-session hook heals itself via
+        // withJwksRotationRecovery; this backstop covers the endpoints that
+        // sign directly. healUndecryptableJwks verifies the key against the
+        // live secret before expiring anything, so a coincidental 500 is a
+        // no-op here. Magic-link verify is excluded: its one-time token is
+        // already consumed, so a replay can only produce a worse redirect.
+        if (isResponse &&
+            response.status >= 500 &&
+            !isMagicLinkVerification &&
+            getMethod(event) === "GET" &&
+            (await healUndecryptableJwks())) {
+            response = await auth.handler(new Request(requestForAuth.url, {
+                method: "GET",
+                headers: requestForAuth.headers,
+            }));
+        }
         if (isResponse && response.status >= 400) {
             // The direct Better Auth surface is also reachable from the browser,
             // so wrapper-route sanitization alone is not enough to keep adapter
@@ -4183,7 +4308,8 @@ async function mountBetterAuthRoutes(app, options) {
                 // Best-effort — don't block the response
             }
         }
-        if (reqPath.includes("/sign-up/email") &&
+        if ((reqPath.includes("/sign-up/email") ||
+            reqPath.includes("/sign-in/email")) &&
             isResponse &&
             response.status >= 200 &&
             response.status < 300) {
@@ -4220,6 +4346,7 @@ async function mountBetterAuthRoutes(app, options) {
             });
             if (result?.token) {
                 setFrameworkSessionCookie(event, result.token);
+                setFirstRunOnboardingCookie(event);
                 await addSession(result.token, email);
                 if (isElectronRequest(event)) {
                     await writeDesktopSso({
@@ -4511,6 +4638,10 @@ async function mountBetterAuthRoutes(app, options) {
             return { error: "Method not allowed" };
         }
         const session = await getSession(event);
+        if (session)
+            setFrameworkSessionHintCookie(event);
+        else
+            clearFrameworkSessionHintCookies(event);
         return session ?? { error: "Not authenticated" };
     }));
     // GET /_agent-native/auth/reset — HTML page shown when a user clicks the
@@ -4521,7 +4652,11 @@ async function mountBetterAuthRoutes(app, options) {
             setResponseStatus(event, 405);
             return { error: "Method not allowed" };
         }
-        return new Response(getResetPasswordHtml(), {
+        const requestPath = event.context?._mountedPathname ??
+            event.node?.req?.url ??
+            event.path ??
+            "/";
+        return new Response(getResetPasswordHtml(requestPath), {
             headers: { "Content-Type": "text/html; charset=utf-8" },
         });
     }));
@@ -4576,6 +4711,7 @@ function mountAuthFallbackRoutes(app) {
             });
             if (result?.token) {
                 setFrameworkSessionCookie(event, result.token);
+                setFirstRunOnboardingCookie(event);
                 await addSession(result.token, email);
                 if (isElectronRequest(event)) {
                     await writeDesktopSso({
@@ -4676,6 +4812,10 @@ function mountAuthFallbackRoutes(app) {
             return { error: "Method not allowed" };
         }
         const session = await getSession(event);
+        if (session)
+            setFrameworkSessionHintCookie(event);
+        else
+            clearFrameworkSessionHintCookies(event);
         return session ?? { error: "Not authenticated" };
     }));
 }
@@ -4725,6 +4865,12 @@ export async function autoMountAuth(app, options = {}) {
                 _authGuardConfig.loginHtml = loginHtmlConfig.loginHtml;
                 _authGuardConfig.getLoginHtml = loginHtmlConfig.getLoginHtml;
             }
+            if (options.rootAuth !== undefined) {
+                _authGuardConfig.rootAuth = options.rootAuth;
+            }
+            else if (options.loginHtml || options.marketing) {
+                _authGuardConfig.rootAuth = true;
+            }
             if (options.publicPaths) {
                 _authGuardConfig.publicPaths = [
                     ...(_authGuardConfig.publicPaths ?? []),
@@ -4813,6 +4959,7 @@ export async function autoMountAuth(app, options = {}) {
                 : {
                     getLoginHtml: () => getCustomAuthRequiredHtml(),
                 }),
+            rootAuth: options.rootAuth ?? Boolean(options.loginHtml),
             publicPaths,
             publicCorsPaths: options.publicCorsPaths ?? [],
             workspaceAppAudience,

package/dist/server/better-auth-instance.js

@@ -43,7 +43,9 @@ import { getWorkspaceA2ADerivedSecret } from "./derived-secret.js";
 import { renderMagicLinkEmail, renderResetPasswordEmail, renderVerifySignupEmail, } from "./email-templates.js";
 import { getDeploymentEmailReadiness, sendEmail, } from "./email.js";
 import { recordActiveGoogleSignInCredentials, resolveGoogleSignInCredentials, } from "./google-oauth-credentials.js";
+import { withJwksRotationRecovery } from "./jwks-secret-rotation.js";
 import { readMagicLinkSignupAttribution } from "./magic-link-attribution.js";
+import { getConfiguredOriginAllowlist } from "./origin-allowlist.js";
 import { getRequestContext, hasContinuationLocalRequestContext, } from "./request-context.js";
 export { getAuthLoginMode, resolveAuthLoginMode, resolveAuthLoginModeFromReadiness, } from "./auth-login-mode.js";
 async function flushSignupTracking() {
@@ -1225,13 +1227,21 @@ async function createBetterAuthInstance(config) {
                 email,
                 magicLinkUrl: deliveredMagicLinkUrl,
             });
-            await sendEmail({ to: email, subject, html, text, appSender });
+            await sendEmail({
+                to: email,
+                subject,
+                html,
+                text,
+                appSender,
+                disableClickTracking: true,
+            });
         },
     });
     const auth = betterAuth({
         basePath,
         baseURL: appUrl,
         database,
+        trustedOrigins: [...getConfiguredOriginAllowlist()],
         // Auth schema relations are intentionally not registered here. Keep the
         // experimental relational-query path off so a bundled Drizzle adapter
         // cannot recurse while resolving a session or account join.
@@ -1262,6 +1272,7 @@ async function createBetterAuthInstance(config) {
                     html,
                     text,
                     appSender,
+                    disableClickTracking: true,
                     templateId: CORE_RESET_PASSWORD_EMAIL_ID,
                 });
             },
@@ -1293,6 +1304,7 @@ async function createBetterAuthInstance(config) {
                     html,
                     text,
                     appSender,
+                    disableClickTracking: true,
                     templateId: CORE_VERIFY_SIGNUP_EMAIL_ID,
                 });
             },
@@ -1443,13 +1455,15 @@ async function createBetterAuthInstance(config) {
         },
         plugins: [
             magicLinkPlugin,
-            // JWT: issue tokens for A2A calls, JWKS endpoint for verification
-            jwt({
+            // JWT: issue tokens for A2A calls, JWKS endpoint for verification.
+            // Wrapped so a rotated BETTER_AUTH_SECRET (which orphans the encrypted
+            // jwks row) heals in place instead of 500ing every get-session.
+            withJwksRotationRecovery(jwt({
                 jwt: {
                     issuer: appUrl,
                     expirationTime: "15m",
                 },
-            }),
+            })),
             // Bearer: accept Bearer tokens on API requests
             bearer(),
             ...(config?.plugins ?? []),

package/dist/server/better-auth-migrations.d.ts

@@ -1,4 +1,18 @@
 import { type MigrationEntry } from "../db/migrations.js";
+/**
+ * Better Auth encrypts persisted JWT private keys with the current auth
+ * secret. If that secret is rotated, the old row remains the newest key and
+ * every token-producing request fails before it can mint a replacement. Mark
+ * active rows expired during the release so Better Auth rotates the signing
+ * key without touching users or sessions. The JWKS endpoint keeps expired
+ * keys during its grace period, so already-issued short-lived tokens remain
+ * verifiable while the new key propagates.
+ *
+ * Also invoked at runtime by `jwks-secret-rotation.ts` when a live request
+ * hits the decrypt failure — release migrations do not reach every deployed
+ * database, so the release-time pass alone cannot be relied on.
+ */
+export declare function expireJwksKeysAfterAuthSecretRotation(): Promise<void>;
 /**
  * Better Auth's framework-owned schema. This is deliberately a release
  * migration, not a fallback inside `getBetterAuth()`: request functions must

package/dist/server/better-auth-migrations.js

@@ -35,8 +35,12 @@ async function assertBetterAuthUserIdentityColumns() {
  * key without touching users or sessions. The JWKS endpoint keeps expired
  * keys during its grace period, so already-issued short-lived tokens remain
  * verifiable while the new key propagates.
+ *
+ * Also invoked at runtime by `jwks-secret-rotation.ts` when a live request
+ * hits the decrypt failure — release migrations do not reach every deployed
+ * database, so the release-time pass alone cannot be relied on.
  */
-async function expireJwksKeysAfterAuthSecretRotation() {
+export async function expireJwksKeysAfterAuthSecretRotation() {
     const { getDbExec, isPostgres } = await import("../db/client.js");
     const now = isPostgres() ? new Date().toISOString() : Date.now();
     const table = isPostgres() ? '"jwks"' : "jwks";

package/dist/server/builder-api-auth.js

@@ -41,9 +41,21 @@ export async function resolveBuilderApiAuthorization(requiredScope) {
     // the grant is org-scoped, and a recording that finalizes after the user
     // switched org must still authorize against the org it belongs to. The
     // legacy private-key path already resolves this way.
-    const orgId = getRequestOrgId();
+    const orgId = getRequestOrgId() ?? null;
     if (ownerEmail && (await readOAuthCustody(ownerEmail, orgId))) {
-        const session = await readCredentialStore(() => getBuilderOAuthSession(ownerEmail, orgId));
+        let session;
+        try {
+            session = await readCredentialStore(() => getBuilderOAuthSession(ownerEmail, orgId, requiredScope));
+        }
+        catch (err) {
+            if (requiredScope &&
+                err instanceof Error &&
+                err.message ===
+                    `Builder OAuth connection does not grant ${requiredScope}`) {
+                throw new Error(`Builder.io access needs re-authorizing to grant ${requiredScope}. Open Settings and authorize Builder.io again.`);
+            }
+            throw err;
+        }
         if (!session) {
             throw new Error("Builder.io access expired. Re-authorize Builder.io in Settings to continue.");
         }
@@ -69,7 +81,8 @@ export async function resolveBuilderApiAuthorization(requiredScope) {
  */
 export async function hasBuilderApiCredentialCustody() {
     const ownerEmail = getRequestUserEmail();
-    if (ownerEmail && (await readOAuthCustody(ownerEmail, getRequestOrgId()))) {
+    const orgId = getRequestOrgId() ?? null;
+    if (ownerEmail && (await readOAuthCustody(ownerEmail, orgId))) {
         return true;
     }
     return !!(await resolveBuilderPrivateKey());
@@ -80,10 +93,21 @@ export async function hasBuilderApiCredentialCustody() {
  */
 export async function canAuthorizeBuilderApiRequest(requiredScope) {
     const ownerEmail = getRequestUserEmail();
-    const orgId = getRequestOrgId();
+    const orgId = getRequestOrgId() ?? null;
     if (ownerEmail && (await hasBuilderOAuthSession(ownerEmail, orgId))) {
-        const session = await getBuilderOAuthSession(ownerEmail, orgId);
-        return (!!session && (!requiredScope || session.scopes.includes(requiredScope)));
+        try {
+            const session = await getBuilderOAuthSession(ownerEmail, orgId, requiredScope);
+            return (!!session && (!requiredScope || session.scopes.includes(requiredScope)));
+        }
+        catch (err) {
+            if (requiredScope &&
+                err instanceof Error &&
+                err.message ===
+                    `Builder OAuth connection does not grant ${requiredScope}`) {
+                return false;
+            }
+            throw err;
+        }
     }
     return !!(await resolveBuilderPrivateKey());
 }

package/dist/server/builder-browser.d.ts

@@ -36,6 +36,11 @@ export interface BuilderRelayRequestBody {
     relayState: string;
     credentials: BuilderRelayCredentials;
 }
+export declare class BuilderAccountProvisioningError extends Error {
+    readonly code: string | null;
+    constructor(message: string, code?: string);
+}
+export declare function isBuilderAccountAlreadyExistsError(error: unknown): boolean;
 export declare function createBuilderConnectState(): string;
 export declare function isSignedBuilderConnectState(value: string | null | undefined): boolean;
 /**
@@ -123,6 +128,7 @@ export declare const BUILDER_AGENT_NATIVE_TEMPLATE_PARAM = "agentNativeTemplate"
 export declare const BUILDER_CONNECT_MODE_PARAM = "_an_mode";
 export declare const BUILDER_AGENT_NATIVE_PROVISION_MODE = "agent-native";
 export declare const BUILDER_PROVISIONING_TOKEN_PARAM = "_an_provision";
+export declare const BUILDER_CONNECT_ATTEMPT_PARAM = "_an_connect_attempt";
 export declare function appendBuilderConnectStateCookie(value: string | null | undefined, state: string): string;
 export declare function removeBuilderConnectStateCookie(value: string | null | undefined, state: string): string;
 export declare function resolveBuilderConnectCallbackState(queryState: string | null, cookieState: string | null | undefined): string | null;
@@ -162,6 +168,7 @@ export interface BuilderBrowserStatus {
     connectError?: {
         message: string;
         at: number;
+        code?: string;
     };
     appHost: string;
     apiHost: string;
@@ -322,6 +329,7 @@ export declare function resolveBuilderCallbackReturnUrl(options: {
 }): string;
 export declare function createBuilderBrowserCallbackPage(previewUrl: string, opts?: {
     parentOrigin?: string;
+    attemptId?: string;
 }): string;
 /**
  * HTML page rendered inside the OAuth popup when the callback handler caught
@@ -342,6 +350,8 @@ export declare function createBuilderBrowserCallbackErrorPage(message: string, o
     body?: string;
     closeHint?: string;
     parentOrigin?: string;
+    code?: string;
+    attemptId?: string;
 }): string;
 export interface RunBuilderAgentArgs {
     prompt: string;