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

package/dist/server/email.js

@@ -35,11 +35,14 @@ function resolveAttachments(args) {
     }
     return [...(args.attachments ?? []), getAgentNativeLogoAttachment()];
 }
-async function resolveEmailTransport() {
+async function resolveEmailTransport(useDeploymentCredentials = false) {
+    const resolve = useDeploymentCredentials
+        ? (key) => readDeployCredentialEnv(key) ?? null
+        : resolveSecret;
     const [resendApiKey, sendgridApiKey, from] = await Promise.all([
-        resolveSecret("RESEND_API_KEY"),
-        resolveSecret("SENDGRID_API_KEY"),
-        resolveSecret("EMAIL_FROM"),
+        resolve("RESEND_API_KEY"),
+        resolve("SENDGRID_API_KEY"),
+        resolve("EMAIL_FROM"),
     ]);
     const resolvedFrom = from ?? undefined;
     if (resendApiKey) {
@@ -177,7 +180,7 @@ function resolveAppSender(configuredFrom, appSender) {
     };
 }
 async function deliverEmail(args, signal) {
-    const config = await resolveEmailTransport();
+    const config = await resolveEmailTransport(args.useDeploymentCredentials);
     signal?.throwIfAborted();
     const provider = config.provider;
     const branded = resolveAppSender(config.from, args.appSender);
@@ -262,6 +265,11 @@ async function deliverEmail(args, signal) {
         ].filter((value) => Boolean(value));
         if (categories.length)
             sgPayload.categories = categories;
+        if (args.disableClickTracking) {
+            sgPayload.tracking_settings = {
+                click_tracking: { enable: false },
+            };
+        }
         const sgHeaders = {};
         if (args.inReplyTo)
             sgHeaders["In-Reply-To"] = args.inReplyTo;

package/dist/server/framework-request-handler.js

@@ -1,8 +1,9 @@
-import { setResponseHeader, setResponseStatus } from "h3";
+import { getHeader, setResponseHeader, setResponseStatus } from "h3";
 import { AppConfigurationError } from "../app-config/index.js";
 import { getMissingDefaultPlugins } from "../deploy/route-discovery.js";
 import { MCP_PUBLIC_ROUTE_PREFIX } from "../mcp/route-paths.js";
 import { SIGN_IN_ENTRY_PATH, SIGN_IN_LEGACY_ENTRY_PATH, } from "../shared/sign-in-journey.js";
+import { SYNTHETIC_TRAFFIC_HEADER, isSyntheticTrafficValue, } from "../shared/test-traffic.js";
 import { getConfiguredAppBasePath } from "./app-base-path.js";
 import { captureError } from "./capture-error.js";
 import { createCsrfMiddleware } from "./csrf.js";
@@ -244,10 +245,12 @@ function registerRequestContextBoundary(nitroApp) {
         return;
     if (h3[REQUEST_CONTEXT_BOUNDARY_KEY])
         return;
-    const middleware = (_event, next) => {
+    const middleware = (event, next) => {
         if (hasRequestContext())
             return next();
-        return runWithRequestContext({}, () => next());
+        return runWithRequestContext({
+            isSyntheticTraffic: isSyntheticTrafficValue(getHeader(event, SYNTHETIC_TRAFFIC_HEADER)),
+        }, () => next());
     };
     h3[REQUEST_CONTEXT_BOUNDARY_KEY] = middleware;
     h3["~middleware"].unshift(middleware);

package/dist/server/google-credential-check.d.ts

@@ -3,7 +3,7 @@ export type GoogleCredentialStatus =
 "valid"
 /** Google rejected the client id or secret — sign-in is broken. */
  | "invalid"
-/** No sign-in credentials are configured on this deploy. */
+/** No credentials are configured for the requested Google client. */
  | "unconfigured"
 /** Google could not be reached, or answered something unrecognised. */
  | "unknown";
@@ -15,9 +15,12 @@ export interface GoogleCredentialCheck {
     /**
      * Where the probed pair came from. `active` is the pair Better Auth wired to
      * the provider; `preferred` means auth had not initialised yet and this fell
-     * back to the preferred pair, which a scoped template may not use.
+     * back to the preferred pair; `managed` is the deployment-level pair used by
+     * the unauthenticated workspace OAuth health contract; `user` means the app
+     * intentionally resolves a user-scoped pair after sign-in; `none` means the
+     * app declared that it does not expose deployment-level Google OAuth.
      */
-    credentialSource: "active" | "preferred";
+    credentialSource: "active" | "preferred" | "managed" | "user" | "none";
     /** Google's `error` field, or the transport failure, when there was one. */
     reason: string | null;
     checkedAt: number;
@@ -36,3 +39,4 @@ export declare function checkGoogleSignInCredential(options?: {
     ttlMs?: number;
     now?: () => number;
 }): Promise<GoogleCredentialCheck>;
+export declare function checkGoogleManagedCredential(): Promise<GoogleCredentialCheck>;

package/dist/server/google-credential-check.js

@@ -1,3 +1,4 @@
+import { resolveSecretPair } from "./credential-provider.js";
 import { describeGoogleSignInCredentialPairs, getActiveGoogleSignInCredentials, resolveGoogleSignInCredentials, } from "./google-oauth-credentials.js";
 const GOOGLE_TOKEN_ENDPOINT = "https://oauth2.googleapis.com/token";
 /**
@@ -11,9 +12,13 @@ const PROBE_REDIRECT_URI = "https://example.com/agent-native-credential-probe";
 const DEFAULT_TTL_MS = 5 * 60 * 1000;
 const REQUEST_TIMEOUT_MS = 10_000;
 let cached = null;
+let managedCached = null;
+let managedInFlight = null;
 /** Test seam: drop the memoised result. */
 export function resetGoogleCredentialCheckCache() {
     cached = null;
+    managedCached = null;
+    managedInFlight = null;
 }
 async function probeGoogle(clientId, clientSecret) {
     let response;
@@ -113,3 +118,69 @@ export async function checkGoogleSignInCredential(options) {
     }
     return value;
 }
+/**
+ * Ask Google about the deployment-level client used by managed workspace OAuth.
+ * This is separate from Better Auth sign-in because a deploy may intentionally
+ * use GOOGLE_SIGN_IN_* and GOOGLE_* as different clients.
+ */
+async function checkGoogleManagedCredentialOnce() {
+    const checkedAt = Date.now();
+    let credentials;
+    try {
+        credentials = await resolveSecretPair([
+            "GOOGLE_CLIENT_ID",
+            "GOOGLE_CLIENT_SECRET",
+        ]);
+    }
+    catch {
+        return {
+            status: "unknown",
+            clientId: null,
+            mismatchedPairs: false,
+            credentialSource: "managed",
+            reason: "credential lookup failed",
+            checkedAt,
+        };
+    }
+    if (!credentials) {
+        return {
+            status: "unconfigured",
+            clientId: null,
+            mismatchedPairs: false,
+            credentialSource: "managed",
+            reason: null,
+            checkedAt,
+        };
+    }
+    const [clientId, clientSecret] = credentials;
+    return {
+        ...(await probeGoogle(clientId, clientSecret)),
+        clientId,
+        mismatchedPairs: false,
+        credentialSource: "managed",
+        checkedAt,
+    };
+}
+export async function checkGoogleManagedCredential() {
+    const at = Date.now();
+    if (managedCached && managedCached.expiresAt > at) {
+        return managedCached.value;
+    }
+    if (managedInFlight)
+        return managedInFlight;
+    const inFlight = checkGoogleManagedCredentialOnce();
+    managedInFlight = inFlight;
+    try {
+        const value = await inFlight;
+        // Keep transient Google or credential-store failures retryable while
+        // protecting the public health route from repeated definitive probes.
+        if (value.status !== "unknown") {
+            managedCached = { value, expiresAt: at + DEFAULT_TTL_MS };
+        }
+        return value;
+    }
+    finally {
+        if (managedInFlight === inFlight)
+            managedInFlight = null;
+    }
+}

package/dist/server/google-oauth-credentials.d.ts

@@ -63,9 +63,10 @@ export declare function getActiveGoogleSignInCredentials(): {
 /**
  * Which sign-in credential pairs are configured, and whether they disagree.
  *
- * `mismatched` is the state that hid the 2026-08-20 outage: two pairs naming
- * different Google clients, where only the winner is ever read. Callers report
- * it; the resolver only warns.
+ * `mismatched` is diagnostic only. Two pairs may name different clients when
+ * identity sign-in and provider APIs intentionally have separate OAuth apps.
+ * Callers must compare the pair used by their specific flow, not delete one
+ * based on this flag alone.
  */
 export declare function describeGoogleSignInCredentialPairs(): {
     signInClientId: string | null;

package/dist/server/google-oauth-credentials.js

@@ -59,11 +59,9 @@ export async function resolveGoogleProviderCredentialCandidatesWithReader(option
 export function resolveGoogleSignInCredentials() {
     const signIn = readCredentialPair("GOOGLE_SIGN_IN_CLIENT_ID", "GOOGLE_SIGN_IN_CLIENT_SECRET");
     const provider = readCredentialPair("GOOGLE_CLIENT_ID", "GOOGLE_CLIENT_SECRET");
-    // Both pairs configured for different clients means one of them is dead
-    // config that nothing will ever read. Silence here cost a fleet-wide beta
-    // sign-in outage: GOOGLE_CLIENT_SECRET was repaired and verified while the
-    // callback kept using a stale GOOGLE_SIGN_IN_CLIENT_SECRET, so the repaired
-    // variable looked correct and changed nothing. Name the loser explicitly.
+    // Different clients can be intentional: sign-in uses GOOGLE_SIGN_IN_* while
+    // provider API flows use GOOGLE_CLIENT_*. Keep the warning because editing
+    // the provider pair cannot repair a sign-in pair that is actually active.
     if (signIn && provider && signIn.clientId !== provider.clientId) {
         console.warn("[agent-native][google-oauth] GOOGLE_SIGN_IN_CLIENT_ID and GOOGLE_CLIENT_ID " +
             "are set to different Google clients. Sign-in uses GOOGLE_SIGN_IN_CLIENT_ID; " +
@@ -107,9 +105,10 @@ export function getActiveGoogleSignInCredentials() {
 /**
  * Which sign-in credential pairs are configured, and whether they disagree.
  *
- * `mismatched` is the state that hid the 2026-08-20 outage: two pairs naming
- * different Google clients, where only the winner is ever read. Callers report
- * it; the resolver only warns.
+ * `mismatched` is diagnostic only. Two pairs may name different clients when
+ * identity sign-in and provider APIs intentionally have separate OAuth apps.
+ * Callers must compare the pair used by their specific flow, not delete one
+ * based on this flag alone.
  */
 export function describeGoogleSignInCredentialPairs() {
     const signIn = readCredentialPair("GOOGLE_SIGN_IN_CLIENT_ID", "GOOGLE_SIGN_IN_CLIENT_SECRET");

package/dist/server/google-oauth.d.ts

@@ -45,6 +45,10 @@ export declare function getOrigin(event: H3Event, options?: {
 export declare function getAppBasePath(): string;
 /** Build an absolute same-origin URL that preserves APP_BASE_PATH. */
 export declare function getAppUrl(event: H3Event, path?: string): string;
+export type OAuthRedirectUriOptions = {
+    /** Allow a known framework callback to bypass an app mount prefix. */
+    allowRootCallback?: boolean;
+};
 /**
  * Validate a user-supplied `redirect_uri` for OAuth flows.
  *
@@ -70,7 +74,7 @@ export declare function getAppUrl(event: H3Event, path?: string): string;
  * loopback URIs, callers should validate those at the template level
  * with a dedicated allowlist — this helper rejects them by design.
  */
-export declare function isAllowedOAuthRedirectUri(candidate: string, event: H3Event, expectedOrigin?: string): boolean;
+export declare function isAllowedOAuthRedirectUri(candidate: string, event: H3Event, expectedOrigin?: string, options?: OAuthRedirectUriOptions): boolean;
 /**
  * Resolve the `redirect_uri` for an outbound OAuth `auth-url` request.
  *
@@ -85,7 +89,7 @@ export declare function isAllowedOAuthRedirectUri(candidate: string, event: H3Ev
  * `defaultPath` (e.g. `"/_agent-native/google/desktop-callback"` for
  * desktop flows).
  */
-export declare function resolveOAuthRedirectUri(event: H3Event, defaultPath?: string): string | null;
+export declare function resolveOAuthRedirectUri(event: H3Event, defaultPath?: string, options?: OAuthRedirectUriOptions): string | null;
 export interface OAuthStatePayload {
     redirectUri: string;
     owner?: string;
@@ -183,8 +187,9 @@ export declare function encodeOAuthState(opts: EncodeOAuthStateOptions): string;
 export declare function encodeOAuthState(redirectUri: string, owner?: string, desktop?: boolean, addAccount?: boolean, app?: string, returnUrl?: string, flowId?: string): string;
 /**
  * Decode and verify OAuth state from the callback's state query parameter.
- * Rejects forged or tampered state by checking the HMAC signature.
- * Falls back to the provided URI if decoding or verification fails.
+ * A fallback-shaped payload is returned when state is missing, malformed, or
+ * fails HMAC verification. That payload is untrusted; callers must validate
+ * the fields their flow requires before exchanging a code or redirecting.
  */
 export declare function decodeOAuthState(stateParam: string | undefined, fallbackUri: string): OAuthStatePayload;
 export interface OAuthOwnerResult {

package/dist/server/google-oauth.js

@@ -17,6 +17,7 @@ import { hasBetterAuthUserEmail, trackSignupEvent, } from "./better-auth-instanc
 import { getWorkspaceA2ADerivedSecret } from "./derived-secret.js";
 import { writeDesktopSso } from "./desktop-sso.js";
 import { appendSessionToOAuthReturnUrl } from "./oauth-return-url.js";
+import { EXPLICIT_PUBLIC_ORIGIN_ENV_KEYS, firstOriginFromEnv, getConfiguredOriginAllowlist, isLoopbackHost, normalizeOrigin, WORKSPACE_GATEWAY_ORIGIN_ENV_KEYS, } from "./origin-allowlist.js";
 import { isWorkspaceOAuthCallbackRelayEnabled } from "./workspace-oauth.js";
 // ─── Platform Detection ─────────────────────────────────────────────────────
 /** Return an HTML response with the correct Content-Type.
@@ -75,66 +76,6 @@ export function isElectron(event) {
 export function isMobile(event) {
     return /iPhone|iPad|iPod|Android/i.test(getHeader(event, "user-agent") || "");
 }
-/**
- * Build the static allowlist of origins we trust for `getOrigin`. Reads
- * deployment-known public URLs. Each entry is normalised to
- * `${proto}://${host}` (no path). Duplicates collapse, invalid entries are
- * dropped silently.
- */
-const EXPLICIT_PUBLIC_ORIGIN_ENV_KEYS = [
-    "WORKSPACE_OAUTH_ORIGIN",
-    "VITE_WORKSPACE_OAUTH_ORIGIN",
-    "APP_URL",
-    "VITE_APP_URL",
-    "BETTER_AUTH_URL",
-    "VITE_BETTER_AUTH_URL",
-    "URL",
-    "DEPLOY_URL",
-];
-const WORKSPACE_GATEWAY_ORIGIN_ENV_KEYS = [
-    "WORKSPACE_GATEWAY_URL",
-    "VITE_WORKSPACE_GATEWAY_URL",
-];
-function normalizeOrigin(raw) {
-    if (!raw)
-        return undefined;
-    try {
-        const u = new URL(raw);
-        return `${u.protocol}//${u.host}`;
-    }
-    catch {
-        return undefined;
-    }
-}
-function addNormalizedOrigin(out, raw, options) {
-    const origin = normalizeOrigin(raw);
-    if (!origin)
-        return;
-    if (!options.allowLoopback && isLoopbackOrigin(origin))
-        return;
-    out.add(origin);
-}
-function firstOriginFromEnv(keys, options) {
-    for (const key of keys) {
-        const origin = normalizeOrigin(process.env[key]);
-        if (!origin)
-            continue;
-        if (!options.allowLoopback && isLoopbackOrigin(origin))
-            continue;
-        return origin;
-    }
-    return undefined;
-}
-function getConfiguredOriginAllowlist() {
-    const out = new Set();
-    for (const key of EXPLICIT_PUBLIC_ORIGIN_ENV_KEYS) {
-        addNormalizedOrigin(out, process.env[key], { allowLoopback: true });
-    }
-    for (const key of WORKSPACE_GATEWAY_ORIGIN_ENV_KEYS) {
-        addNormalizedOrigin(out, process.env[key], { allowLoopback: false });
-    }
-    return out;
-}
 /** Return whether a candidate is one of this deployment's configured origins. */
 export function isConfiguredAppOrigin(value) {
     const origin = normalizeOrigin(value);
@@ -150,30 +91,6 @@ function getWorkspaceCallbackOrigin() {
         allowLoopback: false,
     });
 }
-function isLoopbackHost(host) {
-    if (!host)
-        return false;
-    try {
-        const parsed = new URL(`http://${host}`);
-        return (parsed.hostname === "localhost" ||
-            parsed.hostname === "127.0.0.1" ||
-            parsed.hostname === "::1" ||
-            parsed.hostname === "[::1]");
-    }
-    catch {
-        return false;
-    }
-}
-function isLoopbackOrigin(origin) {
-    if (!origin)
-        return false;
-    try {
-        return isLoopbackHost(new URL(origin).host);
-    }
-    catch {
-        return false;
-    }
-}
 function isBuilderPreviewHost(host) {
     if (!host)
         return false;
@@ -281,9 +198,9 @@ function isRequestUnderAppBasePath(event) {
     return (requestPath === `${basePath}/_agent-native` ||
         requestPath.startsWith(`${basePath}/_agent-native/`));
 }
-function getDefaultOAuthRedirectUrl(event, path) {
+function getDefaultOAuthRedirectUrl(event, path, options = {}) {
     const cleanPath = path.startsWith("/") ? path : `/${path}`;
-    if (isWorkspaceOAuthCallbackRelayEnabled() &&
+    if ((isWorkspaceOAuthCallbackRelayEnabled() || options.allowRootCallback) &&
         isFrameworkOAuthCallbackPath(cleanPath)) {
         return `${getOrigin(event)}${cleanPath}`;
     }
@@ -316,7 +233,7 @@ function getDefaultOAuthRedirectUrl(event, path) {
  * loopback URIs, callers should validate those at the template level
  * with a dedicated allowlist — this helper rejects them by design.
  */
-export function isAllowedOAuthRedirectUri(candidate, event, expectedOrigin = getOrigin(event)) {
+export function isAllowedOAuthRedirectUri(candidate, event, expectedOrigin = getOrigin(event), options = {}) {
     if (typeof candidate !== "string" || candidate.length === 0)
         return false;
     let url;
@@ -346,7 +263,8 @@ export function isAllowedOAuthRedirectUri(candidate, event, expectedOrigin = get
     const allowedPrefixes = basePath && isRequestUnderAppBasePath(event)
         ? [
             `${basePath}/_agent-native/`,
-            ...(isWorkspaceOAuthCallbackRelayEnabled() &&
+            ...((isWorkspaceOAuthCallbackRelayEnabled() ||
+                options.allowRootCallback) &&
                 isFrameworkOAuthCallbackPath(url.pathname)
                 ? ["/_agent-native/"]
                 : []),
@@ -371,12 +289,14 @@ export function isAllowedOAuthRedirectUri(candidate, event, expectedOrigin = get
  * `defaultPath` (e.g. `"/_agent-native/google/desktop-callback"` for
  * desktop flows).
  */
-export function resolveOAuthRedirectUri(event, defaultPath = "/_agent-native/google/callback") {
+export function resolveOAuthRedirectUri(event, defaultPath = "/_agent-native/google/callback", options = {}) {
     const supplied = getQuery(event).redirect_uri;
     if (typeof supplied === "string" && supplied.length > 0) {
-        return isAllowedOAuthRedirectUri(supplied, event) ? supplied : null;
+        return isAllowedOAuthRedirectUri(supplied, event, getOrigin(event), options)
+            ? supplied
+            : null;
     }
-    return getDefaultOAuthRedirectUrl(event, defaultPath);
+    return getDefaultOAuthRedirectUrl(event, defaultPath, options);
 }
 /**
  * Ephemeral in-memory state-signing key for development. Generated lazily
@@ -489,8 +409,9 @@ export function encodeOAuthState(redirectUriOrOpts, owner, desktop, addAccount,
 }
 /**
  * Decode and verify OAuth state from the callback's state query parameter.
- * Rejects forged or tampered state by checking the HMAC signature.
- * Falls back to the provided URI if decoding or verification fails.
+ * A fallback-shaped payload is returned when state is missing, malformed, or
+ * fails HMAC verification. That payload is untrusted; callers must validate
+ * the fields their flow requires before exchanging a code or redirecting.
  */
 export function decodeOAuthState(stateParam, fallbackUri) {
     if (stateParam) {

package/dist/server/index.d.ts

@@ -74,7 +74,7 @@ export { buildWorkspaceProviderAuthorizationUrl, createWorkspaceProviderOAuthHan
 export { CredentialStoreUnavailableError, FeatureNotConfiguredError, hasBuilderPrivateKey, isBuilderEnvManaged, getBuilderProxyOrigin, getBuilderImageGenerationBaseUrl, getBuilderWebSearchBaseUrl, getBuilderAuthHeader, resolveBuilderPrivateKey, resolveBuilderAuthHeader, resolveHasBuilderPrivateKey, resolveHasCompleteBuilderConnection, resolveBuilderCredentials, resolveBuilderCredentialsDetailed, resolveBuilderGatewayCredentials, resolveBuilderGatewayCredentialsDetailed, resolveHasBuilderGatewayCredential, resolveBuilderCredentialSource, resolveBuilderCredential, readDeployCredentialEnv, writeBuilderCredentials, deleteBuilderCredentials, resolveSecret, type BuilderCredentialsDetailed, } from "./credential-provider.js";
 export { canAuthorizeBuilderApiRequest, hasBuilderApiCredentialCustody, resolveBuilderApiAuthorization, } from "./builder-api-auth.js";
 export { BUILDER_ASSETS_WRITE_SCOPE } from "./builder-oauth.js";
-export { builderDesignSystemUrl, builderProjectBranchUrl, buildBuilderDesignSystemIndexFiles, collectBuilderDesignSystemGitHubFiles, createBuilderDesignSystemProxyFields, fetchBuilderDesignSystemDecodeJobStatus, fetchBuilderDesignSystemDocs, getBuilderDesignSystemsBaseUrl, hydrateBuilderDesignSystemReference, indexBuilderDesignSystem, localBuilderDesignSystemId, mimeTypeForBuilderDesignSystemFilename, parseBuilderDesignSystemProxyReference, startBuilderDesignSystemIndex, startBuilderDesignSystemUpload, type BuildBuilderDesignSystemIndexFilesOptions, type BuilderDesignSystemCodeFileInput, type BuilderDesignSystemDecodeJobStatus, type BuilderDesignSystemDocsOptions, type BuilderDesignSystemDocument, type BuilderDesignSystemHydratedReference, type BuilderDesignSystemIndexFile, type BuilderDesignSystemIndexFromSourcesOptions, type BuilderDesignSystemIndexOptions, type BuilderDesignSystemIndexResult, type BuilderDesignSystemStatus, type BuilderDesignSystemGitHubFile, type BuilderDesignSystemGitHubFileCollection, type BuilderDesignSystemGitHubSource, type BuilderDesignSystemUploadAttachment, type BuilderDesignSystemUploadSlot, type BuilderDesignSystemProxyFields, type BuilderDesignSystemProxyFieldsOptions, type BuilderDesignSystemProxyReference, type BuilderDesignSystemSourceKind, } from "./builder-design-systems.js";
+export { builderDesignSystemUrl, builderProjectBranchUrl, buildBuilderDesignSystemIndexFiles, collectBuilderDesignSystemGitHubFiles, createBuilderDesignSystemProxyFields, fetchBuilderDesignSystemDecodeJobStatus, fetchBuilderDesignSystemDocs, fetchBuilderDesignSystemRecord, getBuilderDesignSystemsBaseUrl, hydrateBuilderDesignSystemReference, indexBuilderDesignSystem, localBuilderDesignSystemId, mimeTypeForBuilderDesignSystemFilename, parseBuilderDesignSystemProxyReference, startBuilderDesignSystemIndex, startBuilderDesignSystemUpload, type BuildBuilderDesignSystemIndexFilesOptions, type BuilderDesignSystemCodeFileInput, type BuilderDesignSystemDecodeJobStatus, type BuilderDesignSystemDocsOptions, type BuilderDesignSystemDocument, type BuilderDesignSystemHydratedReference, type BuilderDesignSystemIndexFile, type BuilderDesignSystemIndexFromSourcesOptions, type BuilderDesignSystemIndexOptions, type BuilderDesignSystemIndexResult, type BuilderDesignSystemRecord, type BuilderDesignSystemStatus, type BuilderDesignSystemGitHubFile, type BuilderDesignSystemGitHubFileCollection, type BuilderDesignSystemGitHubSource, type BuilderDesignSystemUploadAttachment, type BuilderDesignSystemUploadSlot, type BuilderDesignSystemProxyFields, type BuilderDesignSystemProxyFieldsOptions, type BuilderDesignSystemProxyReference, type BuilderDesignSystemSourceKind, } from "./builder-design-systems.js";
 export { createBuilderProject, ensureBuilderProject, findBuilderProjectForRepo, getBuilderBranchProjectId, isBuilderBranchingEnabled, requestBuilderBrowserConnection, resolveBuilderBranchProjectId, resolveIsBuilderBranchingEnabled, runBuilderAgent, type BuilderProjectResult, type RunBuilderAgentResult, } from "./builder-browser.js";
 export { ensureFusionContainer, sendFusionBranchMessage, pushFusionBranch, reserveFusionHostingSlug, deployFusionProject, getFusionDeploys, getFusionBranchEditorUrl, getFusionHostingUrl, type FusionBranchRef, type EnsureFusionContainerResult, type SendFusionMessageResult, } from "./fusion-app.js";
 export { sendEmail, isEmailConfigured, getEmailReadiness, getEmailProvider, type EmailAttachment, type EmailReadiness, type EmailProvider, type SendEmailArgs, } from "./email.js";

package/dist/server/index.js

@@ -83,7 +83,7 @@ export { CredentialStoreUnavailableError, FeatureNotConfiguredError, hasBuilderP
 resolveBuilderGatewayCredentials, resolveBuilderGatewayCredentialsDetailed, resolveHasBuilderGatewayCredential, resolveBuilderCredentialSource, resolveBuilderCredential, readDeployCredentialEnv, writeBuilderCredentials, deleteBuilderCredentials, resolveSecret, } from "./credential-provider.js";
 export { canAuthorizeBuilderApiRequest, hasBuilderApiCredentialCustody, resolveBuilderApiAuthorization, } from "./builder-api-auth.js";
 export { BUILDER_ASSETS_WRITE_SCOPE } from "./builder-oauth.js";
-export { builderDesignSystemUrl, builderProjectBranchUrl, buildBuilderDesignSystemIndexFiles, collectBuilderDesignSystemGitHubFiles, createBuilderDesignSystemProxyFields, fetchBuilderDesignSystemDecodeJobStatus, fetchBuilderDesignSystemDocs, getBuilderDesignSystemsBaseUrl, hydrateBuilderDesignSystemReference, indexBuilderDesignSystem, localBuilderDesignSystemId, mimeTypeForBuilderDesignSystemFilename, parseBuilderDesignSystemProxyReference, startBuilderDesignSystemIndex, startBuilderDesignSystemUpload, } from "./builder-design-systems.js";
+export { builderDesignSystemUrl, builderProjectBranchUrl, buildBuilderDesignSystemIndexFiles, collectBuilderDesignSystemGitHubFiles, createBuilderDesignSystemProxyFields, fetchBuilderDesignSystemDecodeJobStatus, fetchBuilderDesignSystemDocs, fetchBuilderDesignSystemRecord, getBuilderDesignSystemsBaseUrl, hydrateBuilderDesignSystemReference, indexBuilderDesignSystem, localBuilderDesignSystemId, mimeTypeForBuilderDesignSystemFilename, parseBuilderDesignSystemProxyReference, startBuilderDesignSystemIndex, startBuilderDesignSystemUpload, } from "./builder-design-systems.js";
 export { createBuilderProject, ensureBuilderProject, findBuilderProjectForRepo, getBuilderBranchProjectId, isBuilderBranchingEnabled, requestBuilderBrowserConnection, resolveBuilderBranchProjectId, resolveIsBuilderBranchingEnabled, runBuilderAgent, } from "./builder-browser.js";
 export { ensureFusionContainer, sendFusionBranchMessage, pushFusionBranch, reserveFusionHostingSlug, deployFusionProject, getFusionDeploys, getFusionBranchEditorUrl, getFusionHostingUrl, } from "./fusion-app.js";
 export { sendEmail, isEmailConfigured, getEmailReadiness, getEmailProvider, } from "./email.js";

package/dist/server/jwks-secret-rotation.d.ts

@@ -0,0 +1,29 @@
+export declare function isJwksDecryptError(error: unknown): boolean;
+export declare function resetJwksSecretRotationStateForTests(): void;
+/**
+ * Verify the newest active JWKS key against the current secret and, only when
+ * it genuinely cannot be decrypted, expire the stale rows so Better Auth
+ * mints a fresh key on the next JWT it signs. Returns true when rows were
+ * expired (callers may retry the failed request once), false otherwise.
+ */
+export declare function healUndecryptableJwks(): Promise<boolean>;
+type AuthHookLike = {
+    matcher: (context: any) => boolean;
+    handler: (context: any) => Promise<unknown>;
+};
+type AuthPluginLike = {
+    hooks?: {
+        before?: AuthHookLike[];
+        after?: AuthHookLike[];
+    };
+};
+/**
+ * Wrap a Better Auth plugin's after-hooks so a JWKS decrypt failure heals and
+ * retries instead of failing the request. Built for the JWT plugin, whose
+ * `/get-session` hook only decorates the response with `set-auth-jwt`: when
+ * the retry still cannot sign, the header is skipped — loudly — because
+ * failing every session check over an optional header is exactly the outage
+ * this module exists to prevent.
+ */
+export declare function withJwksRotationRecovery<P extends AuthPluginLike>(plugin: P): P;
+export {};

package/dist/server/jwks-secret-rotation.js

@@ -0,0 +1,150 @@
+/**
+ * Runtime recovery for Better Auth JWKS keys orphaned by an auth-secret
+ * rotation.
+ *
+ * Better Auth encrypts the persisted JWT signing key with the current
+ * `BETTER_AUTH_SECRET`. Rotating that secret leaves the newest `jwks` row
+ * undecryptable, and the JWT plugin decrypts it on every `/get-session`
+ * response (to emit `set-auth-jwt`) — so a rotation turns every session check
+ * into a 500 and signs the whole deployment out (2026-08-28 outage on the
+ * hosted design/clips apps). The release migration
+ * `better-auth-jwks-key-rotation-recovery` already expires stale rows, but
+ * release migrations do not reach every deployed database, so the same
+ * recovery must also run where the failure is actually observed.
+ */
+import { parseEnvelope, symmetricDecrypt } from "better-auth/crypto";
+/** Better Auth's stable copy for this failure (plugins/jwt sign path). */
+const JWKS_DECRYPT_ERROR_SNIPPET = "Failed to decrypt private key";
+export function isJwksDecryptError(error) {
+    return (error instanceof Error && error.message.includes(JWKS_DECRYPT_ERROR_SNIPPET));
+}
+/**
+ * A failed heal must not be re-attempted on every request — under an outage
+ * every session check funnels here at once. One attempt per process per
+ * cooldown window; concurrent callers share the in-flight attempt.
+ */
+const HEAL_COOLDOWN_MS = 60_000;
+let lastHealAttemptAt = 0;
+let inFlightHeal;
+export function resetJwksSecretRotationStateForTests() {
+    lastHealAttemptAt = 0;
+    inFlightHeal = undefined;
+}
+/**
+ * Verify the newest active JWKS key against the current secret and, only when
+ * it genuinely cannot be decrypted, expire the stale rows so Better Auth
+ * mints a fresh key on the next JWT it signs. Returns true when rows were
+ * expired (callers may retry the failed request once), false otherwise.
+ */
+export async function healUndecryptableJwks() {
+    if (inFlightHeal)
+        return inFlightHeal;
+    const now = Date.now();
+    if (now - lastHealAttemptAt < HEAL_COOLDOWN_MS)
+        return false;
+    lastHealAttemptAt = now;
+    inFlightHeal = attemptHeal().finally(() => {
+        inFlightHeal = undefined;
+    });
+    return inFlightHeal;
+}
+async function attemptHeal() {
+    // Lazy imports keep this module cycle-free: better-auth-instance wraps the
+    // JWT plugin with `withJwksRotationRecovery` from this file.
+    const [{ getDbExec, isPostgres }, { getAuthSecret }] = await Promise.all([
+        import("../db/client.js"),
+        import("./better-auth-instance.js"),
+    ]);
+    const table = isPostgres() ? '"jwks"' : "jwks";
+    const nowValue = isPostgres() ? new Date().toISOString() : Date.now();
+    const { rows } = await getDbExec().execute({
+        sql: `SELECT private_key FROM ${table} WHERE expires_at IS NULL OR expires_at > ? ORDER BY created_at DESC LIMIT 1`,
+        args: [nowValue],
+    });
+    const storedPrivateKey = rows[0]?.private_key;
+    // No active key: Better Auth mints one itself, nothing to heal.
+    if (typeof storedPrivateKey !== "string")
+        return false;
+    // Better Auth stores the ciphertext JSON-encoded; a non-string payload means
+    // private-key encryption is disabled and the decrypt failure came from
+    // somewhere else — expiring healthy keys would be worse than the 500.
+    // An unparseable stored key is "not the shape this heal owns", and false
+    // ("did not heal") is the typed answer callers distinguish from success.
+    let ciphertext;
+    try {
+        ciphertext = JSON.parse(storedPrivateKey);
+        // coercion-ok: false is the typed "did not heal" answer, documented above.
+    }
+    catch {
+        return false;
+    }
+    if (typeof ciphertext !== "string")
+        return false;
+    // Multi-version secrets (`BETTER_AUTH_SECRETS`, honored by Better Auth
+    // itself) wrap ciphertexts in a versioned envelope this single-secret heal
+    // cannot validate; leave those deployments to Better Auth's own rotation
+    // machinery instead of expiring keys we cannot assess.
+    if (parseEnvelope(ciphertext))
+        return false;
+    try {
+        await symmetricDecrypt({ key: getAuthSecret(), data: ciphertext });
+        // The key decrypts with the current secret — the observed failure was not
+        // a secret rotation. Leave the healthy key alone.
+        return false;
+        // coercion-ok: this decrypt is a probe; the throw is the positive signal.
+    }
+    catch {
+        // Confirmed: the newest active key does not decrypt with the current
+        // secret. Fall through to the loud expiry below.
+    }
+    console.error("[auth] The newest JWKS signing key cannot be decrypted with the current " +
+        "BETTER_AUTH_SECRET — the secret was rotated after the key was stored. " +
+        "Expiring stale JWKS keys so Better Auth mints a fresh one; users, " +
+        "sessions, and cookies are unaffected.");
+    const { expireJwksKeysAfterAuthSecretRotation } = await import("./better-auth-migrations.js");
+    await expireJwksKeysAfterAuthSecretRotation();
+    return true;
+}
+/**
+ * Wrap a Better Auth plugin's after-hooks so a JWKS decrypt failure heals and
+ * retries instead of failing the request. Built for the JWT plugin, whose
+ * `/get-session` hook only decorates the response with `set-auth-jwt`: when
+ * the retry still cannot sign, the header is skipped — loudly — because
+ * failing every session check over an optional header is exactly the outage
+ * this module exists to prevent.
+ */
+export function withJwksRotationRecovery(plugin) {
+    const after = plugin.hooks?.after;
+    if (!after)
+        return plugin;
+    return {
+        ...plugin,
+        hooks: {
+            ...plugin.hooks,
+            after: after.map((hook) => ({
+                ...hook,
+                handler: async (context) => {
+                    try {
+                        return await hook.handler(context);
+                    }
+                    catch (error) {
+                        if (!isJwksDecryptError(error))
+                            throw error;
+                        if (await healUndecryptableJwks()) {
+                            try {
+                                return await hook.handler(context);
+                            }
+                            catch (retryError) {
+                                if (!isJwksDecryptError(retryError))
+                                    throw retryError;
+                            }
+                        }
+                        console.error("[auth] Skipping the set-auth-jwt response header: the JWKS " +
+                            "signing key is still undecryptable after rotation recovery.", error);
+                        return undefined;
+                    }
+                },
+            })),
+        },
+    };
+}