@nuxtjs/better-auth 0.3.7 → 0.3.9

package/dist/module.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxtjs/better-auth",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "configKey": "auth",
   "compatibility": {
     "nuxt": ">=4.0.0"

package/dist/module.mjs

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { mkdir, writeFile } from 'node:fs/promises';
-import { getLayerDirectories, updateTemplates, addServerImports, addServerHandler, addImports, addPlugin, addComponentsDir, addRouteMiddleware, extendPages, addTemplate, hasNuxtModule, addTypeTemplate, defineNuxtModule, createResolver } from '@nuxt/kit';
+import { getLayerDirectories, resolveServerVariant, hasNuxtCompatibility, updateTemplates, addServerImports, addServerHandler, addNitroPlugin, addImports, addPlugin, addComponentsDir, addRouteMiddleware, extendPages, addTemplate, hasNuxtModule, addTypeTemplate, defineNuxtModule, createResolver, getNitroVersion } from '@nuxt/kit';
 import { consola as consola$1 } from 'consola';
 import { defineDiagnostics, Diagnostic, formatDiagnostic } from 'nostics';
 import { isAbsolute, join, resolve, relative, dirname } from 'pathe';
@@ -13,7 +13,7 @@ import { isCI, isTest } from 'std-env';
 import { isInternalAssetPath } from '../dist/runtime/internal/auth-route-rules.js';
 export { defineClientAuth, defineServerAuth } from '../dist/runtime/config.js';
 
-const version = "0.3.7";
+const version = "0.3.9";
 
 const CONFIG_EXTENSIONS = [".ts", ".js", ".mts", ".cts", ".mjs", ".cjs"];
 const CONFIG_EXTENSION_RE = /\.[cm]?[jt]s$/;
@@ -198,13 +198,26 @@ function resolveNitro3RouteRulesTarget(nuxtRootDir) {
     return fallback;
   }
 }
-function resolveNitroCompatibilityImports(nuxtVersion) {
-  const major = Number.parseInt(nuxtVersion, 10);
-  const nitroV3 = Number.isFinite(major) && major >= 5;
-  return {
-    h3: nitroV3 ? "nitro/h3" : "h3",
-    runtime: nitroV3 ? "nitro3" : "nitro2"
-  };
+function resolveServerRuntimeShim(resolve) {
+  const nitro2 = resolve("./runtime/server/internal/nitro2");
+  return resolveServerVariant({
+    nuxt: resolve("./runtime/server/internal/portable"),
+    nitro2
+  }) ?? nitro2;
+}
+function resolveH3TypesPath(nitroMajor) {
+  return nitroMajor === 3 ? "nitro/h3" : "h3";
+}
+async function resolveAppSecretShim(resolve) {
+  const canDeriveAppSecret = await hasNuxtCompatibility({ nuxt: ">=4.6.0-0" });
+  return resolve(`./runtime/server/internal/${canDeriveAppSecret ? "app-secret" : "app-secret-unavailable"}`);
+}
+async function resolveAuthSecretPlugin(resolve) {
+  if (!await hasNuxtCompatibility({ nuxt: ">=4.6.0-0" }))
+    return;
+  if (!resolveServerVariant({ nitro2: true, nitro3: true, nuxt: false }))
+    return;
+  return resolve("./runtime/server/plugins/auth-secret");
 }
 
 function configFilename(file) {
@@ -286,15 +299,18 @@ function registerTemplateHmrHook(nuxt) {
   });
 }
 function registerServerRuntime(input) {
-  const { clientOnly, resolve } = input;
+  const { authSecretPlugin, clientOnly, resolve } = input;
   if (!clientOnly) {
     addServerImports([
       { name: "defineServerAuth", from: resolve("./runtime/config") },
       { name: "serverAuth", from: resolve("./runtime/server/utils/auth") },
+      { name: "ensureServerAuth", from: resolve("./runtime/server/utils/auth") },
       ...["getRequestSession", "getUserSession", "setRequestSession", "refreshSessionCookieCache", "setSessionCookie", "createSession", "requireUserSession"].map((name) => ({ name, from: resolve("./runtime/server/utils/session") }))
     ]);
     addServerHandler({ middleware: true, handler: resolve("./runtime/server/middleware/route-access") });
     addServerHandler({ route: "/api/auth/**", handler: resolve("./runtime/server/api/auth/[...all]") });
+    if (authSecretPlugin)
+      addNitroPlugin({ nitro2: authSecretPlugin, nitro3: authSecretPlugin });
   }
   addImports([
     "runWithSessionRefresh",
@@ -643,45 +659,62 @@ async function setupBetterAuthSchema(nuxt, serverConfigPath, options, consola, h
 const DEFAULT_SECRET_ENV = "NUXT_BETTER_AUTH_SECRET";
 const FALLBACK_SECRET_ENV = "BETTER_AUTH_SECRET";
 const VERSIONED_SECRET_ENV = "BETTER_AUTH_SECRETS";
+const APP_SECRET_ENV = "NUXT_APP_SECRET";
 const generateSecret = () => randomBytes(32).toString("hex");
 function readEnvFile(rootDir) {
   const envPath = join(rootDir, ".env");
   return existsSync(envPath) ? readFileSync(envPath, "utf-8") : "";
 }
-function hasEnvSecret(rootDir) {
+function hasEnvSecret(rootDir, names) {
   const envFile = readEnvFile(rootDir);
-  return [DEFAULT_SECRET_ENV, FALLBACK_SECRET_ENV, VERSIONED_SECRET_ENV].some((name) => {
+  return names.some((name) => {
     const match = envFile.match(new RegExp(`^${name}=(.+)$`, "m"));
     return !!match && !!match[1] && match[1].trim().length > 0;
   });
 }
-function appendSecretToEnv(rootDir, secret) {
+function appendSecretToEnv(rootDir, name, secret) {
   const envPath = join(rootDir, ".env");
   let content = readEnvFile(rootDir);
   if (content.length > 0 && !content.endsWith("\n"))
     content += "\n";
-  content += `${DEFAULT_SECRET_ENV}=${secret}
+  content += `${name}=${secret}
 `;
   writeFileSync(envPath, content, "utf-8");
 }
+function getSecretEnvName(appSecret) {
+  return appSecret ? APP_SECRET_ENV : DEFAULT_SECRET_ENV;
+}
+function applyPromptedAppSecret(secret) {
+  process.env[APP_SECRET_ENV] = secret;
+  delete process.env.NUXT_APP_SECRET_GENERATED;
+}
 async function promptForSecret(rootDir, consola, options = {}) {
   const configuredSecret = options.configuredSecret?.trim();
   if (configuredSecret)
     return void 0;
-  if (process.env.NUXT_BETTER_AUTH_SECRET || process.env.BETTER_AUTH_SECRET || process.env.BETTER_AUTH_SECRETS || hasEnvSecret(rootDir))
+  if (process.env.NUXT_BETTER_AUTH_SECRET || process.env.BETTER_AUTH_SECRET || process.env.BETTER_AUTH_SECRETS)
+    return void 0;
+  const secretEnvNames = [DEFAULT_SECRET_ENV, FALLBACK_SECRET_ENV, VERSIONED_SECRET_ENV];
+  if (options.appSecret)
+    secretEnvNames.push(APP_SECRET_ENV);
+  if (hasEnvSecret(rootDir, secretEnvNames))
+    return void 0;
+  const generatedAppSecret = process.env.NUXT_APP_SECRET_GENERATED === "1";
+  if (options.appSecret && !generatedAppSecret && (process.env.NUXT_APP_SECRET || options.configuredAppSecret?.trim()))
     return void 0;
   const hasTty = Boolean(process.stdin.isTTY && process.stdout.isTTY);
   if (options.prepare || !hasTty) {
-    consola.warn("[nuxt-better-auth] Skipping auth secret prompt (non-interactive). Set NUXT_BETTER_AUTH_SECRET, BETTER_AUTH_SECRET, or BETTER_AUTH_SECRETS.");
+    consola.warn(options.appSecret ? "[nuxt-better-auth] Skipping auth secret prompt (non-interactive). Set NUXT_APP_SECRET, or NUXT_BETTER_AUTH_SECRET, BETTER_AUTH_SECRET, or BETTER_AUTH_SECRETS." : "[nuxt-better-auth] Skipping auth secret prompt (non-interactive). Set NUXT_BETTER_AUTH_SECRET, BETTER_AUTH_SECRET, or BETTER_AUTH_SECRETS.");
     return void 0;
   }
+  const envName = getSecretEnvName(options.appSecret);
   if (isCI || isTest) {
     const secret2 = generateSecret();
-    appendSecretToEnv(rootDir, secret2);
-    consola.info("Generated NUXT_BETTER_AUTH_SECRET and added to .env (CI/test mode)");
+    appendSecretToEnv(rootDir, envName, secret2);
+    consola.info(`Generated ${envName} and added to .env (CI/test mode)`);
     return secret2;
   }
-  consola.box("An auth secret is required for authentication.\nThis will add NUXT_BETTER_AUTH_SECRET to your .env file.\nBETTER_AUTH_SECRET and BETTER_AUTH_SECRETS are also supported.");
+  consola.box(options.appSecret ? "An auth secret is required for authentication.\nThis will add NUXT_APP_SECRET to your .env file. The auth secret is derived from it.\nNUXT_BETTER_AUTH_SECRET, BETTER_AUTH_SECRET and BETTER_AUTH_SECRETS are also supported." : "An auth secret is required for authentication.\nThis will add NUXT_BETTER_AUTH_SECRET to your .env file.\nBETTER_AUTH_SECRET and BETTER_AUTH_SECRETS are also supported.");
   const choice = await consola.prompt("How do you want to set it?", {
     type: "select",
     options: [
@@ -708,14 +741,14 @@ async function promptForSecret(rootDir, consola, options = {}) {
   }
   const preview = `${secret.slice(0, 8)}...${secret.slice(-4)}`;
   const confirm = await consola.prompt(`Add to .env:
-${DEFAULT_SECRET_ENV}=${preview}
+${envName}=${preview}
 Proceed?`, { type: "confirm", initial: true, cancel: "null" });
   if (typeof confirm === "symbol" || !confirm) {
     consola.info("Cancelled. Secret not written.");
     return void 0;
   }
-  appendSecretToEnv(rootDir, secret);
-  consola.success("Added NUXT_BETTER_AUTH_SECRET to .env");
+  appendSecretToEnv(rootDir, envName, secret);
+  consola.success(`Added ${envName} to .env`);
   return secret;
 }
 
@@ -1645,16 +1678,25 @@ const module$1 = defineNuxtModule({
   },
   async onInstall(nuxt) {
     const configuredSecret = nuxt.options.runtimeConfig?.betterAuthSecret;
-    const generatedSecret = await promptForSecret(nuxt.options.rootDir, consola, { configuredSecret, prepare: Boolean(nuxt.options._prepare) });
-    if (generatedSecret)
+    const appSecret = await hasNuxtCompatibility({ nuxt: ">=4.6.0-0" }, nuxt);
+    const generatedSecret = await promptForSecret(nuxt.options.rootDir, consola, {
+      configuredSecret,
+      prepare: Boolean(nuxt.options._prepare),
+      appSecret,
+      configuredAppSecret: nuxt.options.runtimeConfig?.appSecret
+    });
+    if (generatedSecret && appSecret)
+      applyPromptedAppSecret(generatedSecret);
+    else if (generatedSecret)
       process.env.NUXT_BETTER_AUTH_SECRET = generatedSecret;
     await createDefaultAuthConfigFiles(nuxt);
   },
   setup(options, nuxt) {
     const finishSetup = async () => {
       const resolver = createResolver(import.meta.url);
-      const nitroImports = resolveNitroCompatibilityImports(nuxt._version);
-      nuxt.options.alias["#better-auth/nitro-compat"] = resolver.resolve(`./runtime/server/internal/${nitroImports.runtime}`);
+      const h3TypesPath = resolveH3TypesPath(getNitroVersion(nuxt));
+      nuxt.options.alias["#better-auth/nitro-compat"] = resolveServerRuntimeShim(resolver.resolve);
+      nuxt.options.alias["#better-auth/app-secret"] = await resolveAppSecretShim(resolver.resolve);
       const registeredPluginSources = {};
       await nuxt.callHook("better-auth:plugins:extend", registeredPluginSources);
       for (const source of [...registeredPluginSources.server || [], ...registeredPluginSources.client || []]) {
@@ -1740,8 +1782,8 @@ const module$1 = defineNuxtModule({
           hasHubDb: setup.serverTypes.hasHubDb,
           runtimeTypesPath: resolver.resolve("./runtime/types"),
           sharedServerConfigSafe: [setup.configs.server.path, ...setup.pluginSources.server].every(isServerConfigSharedTypeSafe),
-          h3TypesPath: nitroImports.h3,
-          nitro3RouteRulesTarget: nitroImports.runtime === "nitro3" ? resolveNitro3RouteRulesTarget(nuxt.options.rootDir) : void 0
+          h3TypesPath,
+          nitro3RouteRulesTarget: h3TypesPath === "nitro/h3" ? resolveNitro3RouteRulesTarget(nuxt.options.rootDir) : void 0
         });
       }
       if (setup.schemaGeneration) {
@@ -1759,11 +1801,15 @@ const module$1 = defineNuxtModule({
         runtimeTypesAugmentPath: setup.sharedTypes.runtimeTypesAugmentPath,
         runtimeTypesPath: resolver.resolve("./runtime/types"),
         clientConfigPath,
-        h3TypesPath: nitroImports.h3,
+        h3TypesPath,
         clientOnly: setup.clientOnly
       });
       registerTemplateHmrHook(nuxt);
-      registerServerRuntime({ clientOnly: setup.clientOnly, resolve: resolver.resolve });
+      registerServerRuntime({
+        clientOnly: setup.clientOnly,
+        resolve: resolver.resolve,
+        authSecretPlugin: setup.clientOnly ? void 0 : await resolveAuthSecretPlugin(resolver.resolve)
+      });
       registerAuthMiddleware(resolver.resolve);
       await registerDevtools({ nuxt, clientOnly: setup.clientOnly, hasHubDb: setup.database.hasHubDb, resolve: resolver.resolve });
       registerRouteRulesMetaHook(nuxt);

package/dist/runtime/app/middleware/auth.global.js

@@ -31,6 +31,8 @@ export default defineNuxtRouteMiddleware(async (to) => {
   if (auth === void 0 || auth === false)
     return;
   const config = useRuntimeConfig().public.auth;
+  if (import.meta.server && config?.clientOnly)
+    return;
   const { fetchSession, user, loggedIn } = useUserSession();
   const mode = typeof auth === "string" ? auth : auth?.only ?? "user";
   const redirectTo = typeof auth === "object" ? auth.redirectTo : void 0;

package/dist/runtime/server/api/auth/[...all].js

@@ -1,6 +1,8 @@
+import { prepareAuthSecret } from "../../internal/auth-secret.js";
 import { defineEventHandler, toWebRequest } from "../../internal/nitro-compat.js";
 import { serverAuth } from "../../utils/auth.js";
 export default defineEventHandler(async (event) => {
+  await prepareAuthSecret();
   const auth = serverAuth(event);
   return auth.handler(toWebRequest(event));
 });

package/dist/runtime/server/internal/app-secret-compat.d.ts

@@ -0,0 +1 @@
+export * from '#better-auth/app-secret';

package/dist/runtime/server/internal/app-secret-compat.js

@@ -0,0 +1 @@
+export * from "#better-auth/app-secret";

package/dist/runtime/server/internal/app-secret-unavailable.d.ts

@@ -0,0 +1,2 @@
+/** Nuxt < 4.6 has no `appSecret` to derive the Better Auth secret from. */
+export declare const deriveAuthSecret: (() => Promise<string>) | undefined;

package/dist/runtime/server/internal/app-secret-unavailable.js

@@ -0,0 +1 @@
+export const deriveAuthSecret = void 0;

package/dist/runtime/server/internal/app-secret.d.ts

@@ -0,0 +1,4 @@
+/** The `deriveSecret()` purpose for the Better Auth secret. Changing it rotates every derived secret. */
+export declare const AUTH_SECRET_PURPOSE = "better-auth:secret";
+/** Derives the Better Auth secret from Nuxt's `appSecret` (`NUXT_APP_SECRET`), on Nuxt 4.6+. */
+export declare const deriveAuthSecret: (() => Promise<string>) | undefined;

package/dist/runtime/server/internal/app-secret.js

@@ -0,0 +1,3 @@
+import { deriveSecret } from "nuxt/server";
+export const AUTH_SECRET_PURPOSE = "better-auth:secret";
+export const deriveAuthSecret = () => deriveSecret(AUTH_SECRET_PURPOSE);

package/dist/runtime/server/internal/auth-secret.d.ts

@@ -0,0 +1,25 @@
+/** The singular secret configured for the module: runtime config (`NUXT_BETTER_AUTH_SECRET`) or `BETTER_AUTH_SECRET`. */
+export declare function getConfiguredAuthSecret(runtimeConfig: object): string;
+/** Whether a secret source that predates `appSecret` derivation is configured. These always win. */
+export declare function hasExplicitAuthSecret(runtimeConfig: object): boolean;
+/**
+ * Whether the auth secret is derived from `appSecret`: Nuxt provides `deriveSecret()` (4.6+) and
+ * the `appSecret` is the user's. In development Nuxt generates an `appSecret` when none is set
+ * (`NUXT_APP_SECRET_GENERATED`); deriving from that would replace Better Auth's development
+ * default secret and sign out existing development sessions, so the default is kept.
+ */
+export declare function canDeriveAuthSecret(): boolean;
+/**
+ * Derives the Better Auth secret from Nuxt's `appSecret` once per server process, when no auth
+ * secret is configured and the `appSecret` is the user's (see `canDeriveAuthSecret`).
+ * `serverAuth()` is synchronous, so request entry points and the startup plugin start this, and
+ * the request entry points await it before they create the auth instance.
+ */
+export declare function prepareAuthSecret(): Promise<void> | undefined;
+export interface DerivedAuthSecretState {
+    /** The secret is derived from the user's `appSecret` (Nuxt 4.6+). */
+    available: boolean;
+    secret?: string;
+    error?: unknown;
+}
+export declare function getDerivedAuthSecret(): DerivedAuthSecretState;

package/dist/runtime/server/internal/auth-secret.js

@@ -0,0 +1,40 @@
+import { env } from "better-auth";
+import { deriveAuthSecret } from "./app-secret-compat.js";
+import { useRuntimeConfig } from "./nitro-compat.js";
+let derivedSecret;
+let derivedSecretPromise;
+let derivedSecretError;
+export function getConfiguredAuthSecret(runtimeConfig) {
+  const secret = runtimeConfig.betterAuthSecret;
+  return typeof secret === "string" && secret || env.BETTER_AUTH_SECRET || "";
+}
+export function hasExplicitAuthSecret(runtimeConfig) {
+  return Boolean(getConfiguredAuthSecret(runtimeConfig) || env.BETTER_AUTH_SECRETS || env.AUTH_SECRET);
+}
+export function canDeriveAuthSecret() {
+  if (!deriveAuthSecret)
+    return false;
+  return !(import.meta.dev && globalThis.process?.env?.NUXT_APP_SECRET_GENERATED === "1");
+}
+export function prepareAuthSecret() {
+  if (derivedSecret !== void 0 || derivedSecretError !== void 0 || !canDeriveAuthSecret())
+    return;
+  if (hasExplicitAuthSecret(useRuntimeConfig()))
+    return;
+  derivedSecretPromise ||= deriveAuthSecret().then(
+    (secret) => {
+      derivedSecret = secret;
+    },
+    (error) => {
+      derivedSecretError = error ?? new Error("deriveSecret failed");
+    }
+  );
+  return derivedSecretPromise;
+}
+export function getDerivedAuthSecret() {
+  return {
+    available: canDeriveAuthSecret(),
+    secret: derivedSecret,
+    error: derivedSecretError
+  };
+}

package/dist/runtime/server/internal/{nitro3.d.ts → portable.d.ts}

@@ -1,10 +1,9 @@
-import type { H3Event } from 'nitro/h3';
+import type { RequestEvent } from 'nuxt/server';
 import type { AuthRouteRules } from '../../types.js';
 import { splitSetCookieString } from 'cookie-es';
-import { defineEventHandler, getQuery, getRequestHost, getRequestProtocol, getRequestURL, readBody } from 'nitro/h3';
-import { useRuntimeConfig } from 'nitro/runtime-config';
+import { defineEventHandler, getQuery, getRequestHost, getRequestProtocol, getRequestURL, readBody, useRuntimeConfig } from 'nuxt/server';
 export { defineEventHandler, getQuery, getRequestHost, getRequestProtocol, getRequestURL, readBody, useRuntimeConfig, };
-export type ServerEvent = H3Event;
+export type ServerEvent = RequestEvent;
 export { splitSetCookieString as splitCookiesString };
 export declare function getAuthRouteRules(event: ServerEvent): AuthRouteRules;
 export declare function createAuthError(status: number, statusText: string): Error;

package/dist/runtime/server/internal/{nitro3.js → portable.js}

@@ -1,15 +1,15 @@
 import { splitSetCookieString } from "cookie-es";
-import { getRouteRules } from "nitro/app";
 import {
+  createError,
   defineEventHandler,
   getQuery,
   getRequestHost,
   getRequestProtocol,
   getRequestURL,
-  HTTPError,
-  readBody
-} from "nitro/h3";
-import { useRuntimeConfig } from "nitro/runtime-config";
+  getRouteRules,
+  readBody,
+  useRuntimeConfig
+} from "nuxt/server";
 import { normalizeAuthRouteRule } from "../../internal/auth-route-rules.js";
 export {
   defineEventHandler,
@@ -22,11 +22,11 @@ export {
 };
 export { splitSetCookieString as splitCookiesString };
 export function getAuthRouteRules(event) {
-  const auth = getRouteRules(event.req.method, getRequestURL(event).pathname).routeRules?.auth;
-  return { auth: normalizeAuthRouteRule(auth) };
+  const rules = getRouteRules(event);
+  return { auth: normalizeAuthRouteRule(rules.auth) };
 }
 export function createAuthError(status, statusText) {
-  return HTTPError.status(status, statusText);
+  return createError({ status, statusText });
 }
 export function toWebRequest(event) {
   return event.req;

package/dist/runtime/server/middleware/route-access.js

@@ -1,8 +1,10 @@
 import { normalizeAuthRoutePath, shouldSkipAuthRouteRules } from "../../internal/auth-route-rules.js";
 import { matchesUser } from "../../utils/match-user.js";
+import { prepareAuthSecret } from "../internal/auth-secret.js";
 import { createAuthError, defineEventHandler, getAuthRouteRules, getRequestURL, useRuntimeConfig } from "../internal/nitro-compat.js";
 import { getUserSession, requireUserSession } from "../utils/session.js";
 export default defineEventHandler(async (event) => {
+  await prepareAuthSecret();
   const path = normalizeAuthRoutePath(
     getRequestURL(event).pathname,
     useRuntimeConfig().app?.baseURL

package/dist/runtime/server/plugins/auth-secret.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Starts deriving the auth secret from Nuxt's `appSecret` when the server starts, so a
+ * `serverAuth()` call made before the first request, such as from a task, can use it.
+ * Nitro does not await plugins: startup code that needs the secret right away awaits
+ * `ensureServerAuth()` instead.
+ */
+export default function authSecretPlugin(): void;

package/dist/runtime/server/plugins/auth-secret.js

@@ -0,0 +1,4 @@
+import { prepareAuthSecret } from "../internal/auth-secret.js";
+export default function authSecretPlugin() {
+  void prepareAuthSecret();
+}

package/dist/runtime/server/tsconfig.json

@@ -4,6 +4,7 @@
     "module": "ESNext",
     "moduleResolution": "bundler",
     "paths": {
+      "#better-auth/app-secret": ["./internal/app-secret"],
       "#better-auth/nitro-compat": ["./internal/nitro2"],
       "#nuxt-better-auth": ["../types/augment"]
     },

package/dist/runtime/server/utils/auth.d.ts

@@ -16,6 +16,12 @@ type ResolvedAuthOptions = Omit<UserAuthConfig, 'secret' | 'baseURL' | 'trustedO
     database?: BetterAuthOptions['database'];
 };
 type AuthInstance = ReturnType<typeof betterAuth<ResolvedAuthOptions>>;
+/**
+ * Returns the Better Auth instance like `serverAuth()`, after waiting for the auth secret that
+ * Nuxt 4.6+ derives from `appSecret` (`NUXT_APP_SECRET`). Use it in code that can run before the
+ * first request, such as a Nitro plugin or task at server startup.
+ */
+export declare function ensureServerAuth(event?: ServerEvent): Promise<AuthInstance>;
 /** Returns Better Auth instance. Caches per resolved host (or single instance when siteUrl is explicit). */
 export declare function serverAuth(event?: ServerEvent): AuthInstance;
 export {};

package/dist/runtime/server/utils/auth.js

@@ -1,6 +1,7 @@
 import { betterAuth, env } from "better-auth";
 import { createDatabase, db } from "#auth/database";
 import createServerAuth from "#auth/server";
+import { getConfiguredAuthSecret, getDerivedAuthSecret, hasExplicitAuthSecret, prepareAuthSecret } from "../internal/auth-secret.js";
 import { getRequestHost, getRequestProtocol, useRuntimeConfig } from "../internal/nitro-compat.js";
 import { resolveAuthBaseURL } from "../../internal/auth-base-url.js";
 import { resolveCustomSecondaryStorageRequirement } from "./custom-secondary-storage.js";
@@ -10,6 +11,7 @@ let _baseURLInferenceLogged = false;
 let _customSecondaryStorageMisconfigWarned = false;
 let _unsupportedHubSecondaryStorageWarned = false;
 let _secondaryStorageRateLimitFallbackWarned = false;
+let _derivedSecretFallbackWarned = false;
 const fallbackRequestAuthContext = /* @__PURE__ */ new WeakMap();
 function getRequestAuthContext(event) {
   const eventWithContext = event;
@@ -193,17 +195,39 @@ function withDevTrustedOrigins(trustedOrigins) {
     return mergeOrigins([], request);
   };
 }
+function missingAuthSecretMessage(derived) {
+  const message = "[nuxt-better-auth] An auth secret is required in production. Set NUXT_BETTER_AUTH_SECRET, BETTER_AUTH_SECRET, BETTER_AUTH_SECRETS, or defineServerAuth({ secrets })";
+  if (!derived.available)
+    return `${message}.`;
+  if (derived.error !== void 0)
+    return `${message}, or set NUXT_APP_SECRET (at least 32 characters) to derive one from Nuxt's appSecret.`;
+  return `${message}. The secret derived from NUXT_APP_SECRET is resolved asynchronously, and serverAuth() was called before it was ready, outside a request. Use \`await ensureServerAuth()\` in code that runs at server startup.`;
+}
+function warnDerivedSecretFallback(derived) {
+  if (_derivedSecretFallbackWarned)
+    return;
+  _derivedSecretFallbackWarned = true;
+  const reason = derived.error !== void 0 ? "could not be derived from NUXT_APP_SECRET. Set NUXT_APP_SECRET (at least 32 characters) or NUXT_BETTER_AUTH_SECRET." : "derived from NUXT_APP_SECRET was not ready yet. Use `await ensureServerAuth()` in code that runs at server startup.";
+  console.warn(`[nuxt-better-auth] Better Auth's development default secret is used for this call: the auth secret ${reason}`);
+}
+export async function ensureServerAuth(event) {
+  await prepareAuthSecret();
+  return serverAuth(event);
+}
 export function serverAuth(event) {
   const runtimeConfig = useRuntimeConfig();
-  const betterAuthSecret = runtimeConfig.betterAuthSecret || env.BETTER_AUTH_SECRET || "";
-  if (betterAuthSecret && betterAuthSecret.length < 32)
+  const configuredSecret = getConfiguredAuthSecret(runtimeConfig);
+  if (configuredSecret && configuredSecret.length < 32)
     throw new Error("[nuxt-better-auth] Singular auth secret must be at least 32 characters for security");
+  const derived = getDerivedAuthSecret();
   const requestOrigin = resolveEventOrigin(event);
   let userConfig;
-  if (!import.meta.dev && !betterAuthSecret && !env.BETTER_AUTH_SECRETS) {
+  if (!import.meta.dev && !configuredSecret && !env.BETTER_AUTH_SECRETS && !derived.secret) {
     userConfig = createServerAuth({ runtimeConfig, db, requestOrigin });
-    if (userConfig.secrets === void 0)
-      throw new Error("[nuxt-better-auth] An auth secret is required in production. Set NUXT_BETTER_AUTH_SECRET, BETTER_AUTH_SECRET, BETTER_AUTH_SECRETS, or defineServerAuth({ secrets }).");
+    if (userConfig.secrets === void 0) {
+      void prepareAuthSecret();
+      throw new Error(missingAuthSecretMessage(derived));
+    }
   }
   const siteUrl = getBaseURL(event);
   const hasExplicitSiteUrl = runtimeConfig.public.siteUrl && typeof runtimeConfig.public.siteUrl === "string";
@@ -212,6 +236,13 @@ export function serverAuth(event) {
   if (requestContext?.[requestAuthKey])
     return requestContext[requestAuthKey];
   userConfig ??= createServerAuth({ runtimeConfig, db, requestOrigin });
+  const usesDerivedSecret = derived.available && userConfig.secrets === void 0 && !hasExplicitAuthSecret(runtimeConfig);
+  const derivedSecretMissing = usesDerivedSecret && !derived.secret;
+  if (derivedSecretMissing) {
+    void prepareAuthSecret();
+    warnDerivedSecretFallback(derived);
+  }
+  const betterAuthSecret = configuredSecret || (usesDerivedSecret ? derived.secret ?? "" : "");
   const database = createDatabase(event);
   const trustedOrigins = withDevTrustedOrigins(userConfig.trustedOrigins);
   const hubSecondaryStorage = runtimeConfig.auth?.hubSecondaryStorage;
@@ -232,7 +263,8 @@ export function serverAuth(event) {
     console.warn('[nuxt-better-auth] rateLimit.storage: "secondary-storage" requires secondaryStorage. Falling back to process-local memory. Set rateLimit.storage to "database" or provide rateLimit.customStorage for shared limits.');
   }
   const rateLimit = useMemoryRateLimit ? { ...userConfig.rateLimit, storage: "memory" } : userConfig.rateLimit;
-  if (!database) {
+  const cacheable = !database && !derivedSecretMissing;
+  if (cacheable) {
     const cached = _authCache.get(cacheKey);
     if (cached) {
       if (requestContext)
@@ -251,7 +283,7 @@ export function serverAuth(event) {
   const auth = betterAuth(authOptions);
   if (requestContext)
     requestContext[requestAuthKey] = auth;
-  if (!database)
+  if (cacheable)
     _authCache.set(cacheKey, auth);
   return auth;
 }

package/dist/runtime/server/utils/session.js

@@ -1,5 +1,6 @@
 import { matchesUser } from "../../utils/match-user.js";
 import { createAuthError } from "../internal/nitro-compat.js";
+import { prepareAuthSecret } from "../internal/auth-secret.js";
 import { appendCookieHeader, appendSetCookieHeaders, getSetCookieHeaders } from "../internal/cookie-headers.js";
 import { serverAuth } from "./auth.js";
 const requestSessionLoadKey = Symbol.for("nuxt-better-auth.requestSessionLoad");
@@ -26,6 +27,9 @@ function getRequestHeaders(event) {
   return getRequestSessionContext(event).requestHeaders ?? getIncomingRequestHeaders(event);
 }
 async function loadSession(event) {
+  const pendingSecret = prepareAuthSecret();
+  if (pendingSecret)
+    await pendingSecret;
   const auth = serverAuth(event);
   const result = await auth.api.getSession({
     headers: getRequestHeaders(event),
@@ -36,6 +40,9 @@ async function loadSession(event) {
   return { headers: new Headers(), response: result };
 }
 function loadFreshSession(event) {
+  const pendingSecret = prepareAuthSecret();
+  if (pendingSecret)
+    return pendingSecret.then(() => loadFreshSession(event));
   const auth = serverAuth(event);
   return auth.api.getSession({
     headers: getRequestHeaders(event),
@@ -44,6 +51,9 @@ function loadFreshSession(event) {
   });
 }
 function getServerAuthContext(event) {
+  const pendingSecret = prepareAuthSecret();
+  if (pendingSecret)
+    return pendingSecret.then(() => getServerAuthContext(event));
   const auth = serverAuth(event);
   return auth.$context;
 }

package/dist/runtime/test-utils/server/handler.js

@@ -9,7 +9,7 @@ const requestSchema = z.discriminatedUnion("action", [
 ]);
 const ownedUsers = /* @__PURE__ */ new Set();
 export default defineEventHandler(async (event) => {
-  const token = useRuntimeConfig(event).betterAuthTestToken;
+  const token = useRuntimeConfig().betterAuthTestToken;
   if (!token || toWebRequest(event).headers.get("x-nuxt-auth-test") !== token)
     throw createAuthError(404, "Not found");
   const body = requestSchema.parse(parseJSON(await toWebRequest(event).text()));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nuxtjs/better-auth",
   "type": "module",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "description": "Nuxt module for Better Auth integration with NuxtHub, route protection, session management, and role-based access",
   "author": "onmax",
   "license": "MIT",
@@ -73,7 +73,7 @@
   },
   "dependencies": {
     "@nuxt/devtools-kit": "^3.4.1",
-    "@nuxt/kit": "^4.5.2",
+    "@nuxt/kit": "^4.6.0",
     "@types/node": "^24.13.3",
     "auth": "1.7.7",
     "consola": "^3.4.2",
@@ -91,36 +91,36 @@
   },
   "devDependencies": {
     "@antfu/eslint-config": "^9.3.0",
-    "@libsql/client": "^0.17.4",
+    "@libsql/client": "^0.18.0",
     "@libsql/linux-x64-gnu": "0.5.29",
     "@nuxt/devtools": "^3.4.1",
     "@nuxt/fonts": "0.14.0",
     "@nuxt/module-builder": "^1.0.3",
-    "@nuxt/schema": "^4.5.2",
-    "@nuxt/test-utils": "^4.1.0",
+    "@nuxt/schema": "^4.6.0",
+    "@nuxt/test-utils": "^4.3.3",
     "@nuxthub/core": "^0.10.8",
     "@pinia/nuxt": "^1.0.2",
     "@types/better-sqlite3": "^9.6.0",
     "@vue/test-utils": "^2.4.6",
     "better-auth": "1.7.7",
     "better-call": "1.4.0",
-    "better-sqlite3": "^12.11.1",
+    "better-sqlite3": "^13.0.0",
     "drizzle-kit": "^0.31.10",
     "drizzle-orm": "^0.45.2",
     "eslint": "^10.8.1",
     "happy-dom": "^20.8.9",
     "nitropack": "2.13.4",
-    "nuxt": "^4.5.2",
+    "nuxt": "^4.6.0",
     "pinia": "^4.0.3",
     "pkg-pr-new": "0.0.88",
-    "playwright-core": "1.58.2",
+    "playwright-core": "1.63.0",
     "postgres": "^3.4.9",
     "typescript": "~5.9.3",
     "unstorage": "^1.17.5",
-    "vitest": "^4.1.11",
-    "vue": "3.5.41",
+    "vitest": "^5.0.0",
+    "vue": "3.5.43",
     "vue-tsc": "^3.3.10",
-    "wrangler": "4.124.0",
+    "wrangler": "4.147.0",
     "yaml": "^2.9.0"
   },
   "scripts": {