@lenne.tech/nuxt-extensions 1.8.1 → 1.8.3

package/CLAUDE.md

@@ -12,7 +12,7 @@ src/
 │   ├── components/        # Auto-imported components
 │   ├── lib/               # Library exports (auth-client, auth-state, ai)
 │   ├── middleware/        # Route middleware (system setup)
-│   ├── plugins/           # Nuxt plugins (auth interceptor, error translation)
+│   ├── plugins/           # Nuxt plugins (auth interceptor, error translation, config check)
 │   ├── server/            # Nitro server routes (auth proxy)
 │   ├── testing/           # Playwright test helpers
 │   ├── types/             # TypeScript type definitions
@@ -133,6 +133,13 @@ The `useLtAuth()` composable manages the `lt-auth-state` cookie for authenticati
 3. If `useLtAuth()` can't find a valid user in the cookie on the server, it initializes with `{user: null}` — this is intentional and correct
 4. The `iam.session_token` httpOnly cookie (set by Better Auth) is the actual session identifier — `lt-auth-state` is a convenience cache for the client-side middleware
 
+### Session User Merge (nest-server-only fields):
+On session re-validation (`validateSession()` at app init / hard reload, and the passkey get-session fallback), `useLtAuth()` **merges** the Better-Auth session user onto the cached user of the SAME identity via the private `mergeSessionUser()`, instead of overwriting it. Consequences you must know:
+
+- **nest-server-only fields persist across reloads.** Better-Auth's get-session returns only Better-Auth-owned fields (id/email/name + registered additionalFields). Fields it does not own (e.g. custom preferences like `leadTableColumns`) previously vanished on every reload; they now survive. If you built a workaround that re-fetched such fields after each reload, you can retire it.
+- **Authorization fields are fail-closed.** `role`, `banned`, `banExpires`, `banReason`, `emailVerified`, `twoFactorEnabled` always reflect the session — any of these the session omits is dropped from the merge (never kept stale), so a backend downgrade is reflected client-side. If your project adds its OWN authorization-relevant user field, either register it as a Better-Auth additionalField (so get-session returns it) or add it to the `AUTHZ_KEYS` list in `use-lt-auth.ts` — otherwise it could persist stale in the client cache.
+- **Keep the cached user lean.** `lt-auth-state` is a non-httpOnly cookie sent on every same-site request and capped at ~4 KB by browsers. Because the merge keeps preference fields across reloads, large blobs on the user object can push the cookie over the limit — the browser then silently rejects the write and the next reload reads as a logout. `setUser` emits a dev-mode warning above ~3.5 KB; move large preference data off the user object and fetch it from an authenticated API.
+
 ### Custom Auth Middleware Pattern:
 ```typescript
 // CORRECT — read-only check, no cookie mutation

package/README.md

@@ -55,14 +55,16 @@ npm install tus-js-client
 All environment variables are resolved **at runtime** (not build time). This means you can build a Docker image once and deploy it to different environments by changing env vars — no rebuild needed.
 
 **SSR fallback chain:**
-`NUXT_API_URL` → `NUXT_PUBLIC_API_URL` → `auth.baseURL` (from nuxt.config.ts) → `http://localhost:3000`
+`NUXT_API_URL` → `NUXT_PUBLIC_API_URL` → `auth.baseURL` (from nuxt.config.ts) → *(unset)*
 
 **Client fallback chain (no proxy):**
-`NUXT_PUBLIC_API_URL` → `auth.baseURL` (from nuxt.config.ts) → `http://localhost:3000`
+`NUXT_PUBLIC_API_URL` → `auth.baseURL` (from nuxt.config.ts) → *(unset)*
 
 **Client with proxy (`NUXT_PUBLIC_API_PROXY=true`):**
 All requests go to `/api/{path}` — the Vite dev proxy forwards them to the backend.
 
+> **No implicit `localhost` default.** If none of the sources above is set, there is **no** built-in fallback URL: API paths stay relative (e.g. `/iam/token`) and resolve against the app origin, so auth and setup calls 404 unless the app is served behind a same-origin reverse proxy. The module logs a one-time warning (`[LtExtensions] No API URL configured…`) at app init and on the first API call. Always set `NUXT_PUBLIC_API_URL` (and optionally `NUXT_API_URL` for SSR).
+
 > **Security:** `NUXT_API_URL` is never exposed to the client bundle. It stays in `runtimeConfig.apiUrl` (server only). This is important when using internal network addresses like `http://api.svc.cluster.local`.
 
 ### Deployment Scenarios

package/dist/module.mjs

@@ -170,6 +170,7 @@ const module$1 = defineNuxtModule({
         filePath: resolve(`./runtime/components/transition/${componentName}.vue`)
       });
     }
+    addPlugin(resolve("./runtime/plugins/lt-config-check"));
     if (resolvedOptions.auth?.enabled && resolvedOptions.auth?.interceptor?.enabled) {
       addPlugin(resolve("./runtime/plugins/auth-interceptor.client"));
     }

package/dist/runtime/composables/auth/use-lt-auth.js

@@ -58,7 +58,13 @@ export function useLtAuth() {
     if (import.meta.client) {
       const maxAge = 60 * 60 * 24 * 7;
       const secure = globalThis.location?.protocol === "https:" ? "; secure" : "";
-      document.cookie = `${stateCookieName}=${encodeURIComponent(JSON.stringify(newState))}; path=/; max-age=${maxAge}; samesite=lax${secure}`;
+      const encoded = encodeURIComponent(JSON.stringify(newState));
+      if (import.meta.dev && encoded.length > 3500) {
+        console.warn(
+          `[lt-auth] lt-auth-state cookie is ${encoded.length} bytes (encoded), approaching the ~4KB browser limit \u2014 an oversized cookie is dropped on write and reads as a logout on reload. Keep the cached user lean: move large preference data off the user object.`
+        );
+      }
+      document.cookie = `${stateCookieName}=${encoded}; path=/; max-age=${maxAge}; samesite=lax${secure}`;
     }
   }
   function clearUser() {
@@ -123,6 +129,20 @@ export function useLtAuth() {
     }
     return response;
   }
+  const AUTHZ_KEYS = ["banExpires", "banReason", "banned", "emailVerified", "role", "twoFactorEnabled"];
+  function mergeSessionUser(sessionUser) {
+    const cached = resolvedAuthState.value?.user;
+    if (!cached?.id || !sessionUser?.id || cached.id !== sessionUser.id) {
+      return sessionUser;
+    }
+    const merged = { ...cached, ...sessionUser };
+    for (const key of AUTHZ_KEYS) {
+      if (!(key in sessionUser)) {
+        delete merged[key];
+      }
+    }
+    return merged;
+  }
   async function validateSession() {
     try {
       const session = authClient.useSession();
@@ -141,7 +161,7 @@ export function useLtAuth() {
         });
       }
       if (session.value.data?.user) {
-        setUser(session.value.data.user, "cookie");
+        setUser(mergeSessionUser(session.value.data.user), "cookie");
         switchToJwtMode().catch(() => {
         });
         return true;
@@ -297,8 +317,9 @@ export function useLtAuth() {
           if (sessionResponse.ok) {
             const sessionData = await sessionResponse.json();
             if (sessionData?.user) {
-              result.user = sessionData.user;
-              setUser(sessionData.user, "cookie");
+              const mergedUser = mergeSessionUser(sessionData.user);
+              result.user = mergedUser;
+              setUser(mergedUser, "cookie");
               switchToJwtMode().catch(() => {
               });
             }

package/dist/runtime/lib/auth-state.d.ts

@@ -90,6 +90,14 @@ export declare function getLtAuthCookieNames(): {
  * unchanged by the duplicate-tolerant read; it only decides which twin wins.
  */
 export declare function resolveLtAuthState(cookieString: string, stateCookieName?: string): LtAuthState | null;
+/**
+ * Clear the one-shot warning state.
+ *
+ * INTERNAL — test-only. Module-scope state survives every test in a file that
+ * does not call `vi.resetModules()`, which would make assertions on these
+ * warnings depend on test order. Production code must never call this.
+ */
+export declare function resetLtWarnOnceState(): void;
 /**
  * Determines if HTTP requests should use the Nuxt Vite dev proxy.
  *
@@ -124,6 +132,46 @@ export declare function resolveLtAuthState(cookieString: string, stateCookieName
  * @see https://github.com/lenneTech/nuxt-base-starter — Vite proxy configuration
  */
 export declare function isLocalDevApiProxy(): boolean;
+/**
+ * Outcome of resolving the API base URL for the current render scope.
+ *
+ * INTERNAL — plumbing for {@link buildLtApiUrl} and the `lt-config-check` plugin.
+ * Not part of the public API (absent from the package barrels and auto-imports);
+ * reachable only via a deep path import. Shape may change without a major bump.
+ */
+export interface LtApiUrlResolution {
+    /** Base URL to prefix onto API paths. `'/api'` in proxy mode, `''` when unresolved. */
+    baseUrl: string;
+    /** `true` when no API URL is configured for {@link scope}. */
+    missing: boolean;
+    /** `true` when the Vite dev proxy prefix is in use (see {@link isLocalDevApiProxy}). */
+    proxy: boolean;
+    /** The render scope the resolution was performed for. */
+    scope: 'client' | 'server';
+}
+/**
+ * Resolve the API base URL for the current render scope.
+ *
+ * INTERNAL — plumbing shared by {@link buildLtApiUrl} and the `lt-config-check`
+ * plugin; not part of the public API (absent from the barrels and auto-imports).
+ *
+ * Pure: it reads `runtimeConfig` and reports what it found, but never logs and
+ * never mutates. The `missing` flag lets callers decide how to surface the
+ * misconfiguration — {@link buildLtApiUrl} warns lazily, the `lt-config-check`
+ * plugin warns eagerly at app init. Both funnel through the same one-shot key,
+ * so the user sees exactly one warning either way.
+ *
+ * Throws when called outside a Nuxt runtime-config context; callers catch.
+ */
+export declare function resolveLtApiBaseUrl(): LtApiUrlResolution;
+/**
+ * Warn — at most once per module instance — that no API URL is configured.
+ *
+ * INTERNAL — shared by {@link buildLtApiUrl} and the `lt-config-check` plugin so
+ * an eager boot-time check and a lazy first-URL check never double-report. Not
+ * part of the public API (absent from the barrels and auto-imports).
+ */
+export declare function warnMissingLtApiUrl(scope: 'client' | 'server'): void;
 /**
  * Build a full API URL for a given path, handling SSR, proxy, and direct modes.
  *
@@ -157,6 +205,9 @@ export declare function isLocalDevApiProxy(): boolean;
  *
  * Trailing slashes on the base URL are automatically stripped.
  *
+ * A missing API URL is reported at most once per module instance — the condition
+ * is constant for the process, so repeating it per call only drowns other output.
+ *
  * @param path - The API path (e.g., `/system-setup/status`, `/i18n/errors/de`)
  */
 export declare function buildLtApiUrl(path: string): string;

package/dist/runtime/lib/auth-state.js

@@ -42,7 +42,17 @@ export function resolveLtAuthState(cookieString, stateCookieName) {
   }
   return fallback;
 }
-let _proxyFallbackWarned = false;
+const warnedKeys = /* @__PURE__ */ new Set();
+function warnOnce(key, message) {
+  if (warnedKeys.has(key)) {
+    return;
+  }
+  warnedKeys.add(key);
+  console.warn(message);
+}
+export function resetLtWarnOnceState() {
+  warnedKeys.clear();
+}
 export function isLocalDevApiProxy() {
   if (import.meta.server) {
     return false;
@@ -55,12 +65,10 @@ export function isLocalDevApiProxy() {
     }
     const buildId = runtimeConfig?.app && runtimeConfig.app?.buildId;
     if (buildId === "dev") {
-      if (!_proxyFallbackWarned) {
-        _proxyFallbackWarned = true;
-        console.warn(
-          "\n\u26A0\uFE0F  [LtExtensions] API proxy activated implicitly because nuxt dev was detected.\n    To make this explicit, add NUXT_PUBLIC_API_PROXY=true to your .env file.\n    If you do NOT want the proxy, set NUXT_PUBLIC_API_PROXY=false.\n"
-        );
-      }
+      warnOnce(
+        "api-proxy-fallback",
+        "\n\u26A0\uFE0F  [LtExtensions] API proxy activated implicitly because nuxt dev was detected.\n    To make this explicit, add NUXT_PUBLIC_API_PROXY=true to your .env file.\n    If you do NOT want the proxy, set NUXT_PUBLIC_API_PROXY=false.\n"
+      );
       return true;
     }
     return false;
@@ -68,26 +76,37 @@ export function isLocalDevApiProxy() {
     return false;
   }
 }
+const MISSING_API_URL_WARNING = {
+  client: "[LtExtensions] No API URL configured. Set NUXT_PUBLIC_API_URL. API paths stay relative and resolve against the app origin, so auth and setup calls 404 unless the app is served behind a same-origin reverse proxy.",
+  server: "[LtExtensions] No API URL configured for SSR. Set NUXT_API_URL or NUXT_PUBLIC_API_URL. API paths stay relative, so server-side requests never reach the backend: $fetch resolves them against Nitro (404) and global fetch rejects them as an invalid URL."
+};
+function stripTrailingSlashes(url) {
+  return url.replace(/\/+$/, "");
+}
+export function resolveLtApiBaseUrl() {
+  const runtimeConfig = useRuntimeConfig();
+  const publicUrl = runtimeConfig.public.apiUrl || "";
+  const authBaseURL = runtimeConfig.public?.ltExtensions?.auth?.baseURL || "";
+  if (import.meta.server) {
+    const apiUrl2 = runtimeConfig.apiUrl || publicUrl || authBaseURL;
+    return { baseUrl: stripTrailingSlashes(apiUrl2), missing: !apiUrl2, proxy: false, scope: "server" };
+  }
+  if (isLocalDevApiProxy()) {
+    return { baseUrl: "/api", missing: false, proxy: true, scope: "client" };
+  }
+  const apiUrl = publicUrl || authBaseURL;
+  return { baseUrl: stripTrailingSlashes(apiUrl), missing: !apiUrl, proxy: false, scope: "client" };
+}
+export function warnMissingLtApiUrl(scope) {
+  warnOnce(`missing-api-url:${scope}`, MISSING_API_URL_WARNING[scope]);
+}
 export function buildLtApiUrl(path) {
   try {
-    const runtimeConfig = useRuntimeConfig();
-    const publicUrl = runtimeConfig.public.apiUrl || "";
-    const authBaseURL = runtimeConfig.public?.ltExtensions?.auth?.baseURL || "";
-    if (import.meta.server) {
-      const apiUrl2 = runtimeConfig.apiUrl || publicUrl || authBaseURL;
-      if (!apiUrl2) {
-        console.warn("[LtExtensions] No API URL configured. Set NUXT_API_URL or NUXT_PUBLIC_API_URL.");
-      }
-      return `${(apiUrl2 || "").replace(/\/+$/, "")}${path}`;
-    }
-    if (isLocalDevApiProxy()) {
-      return `/api${path}`;
-    }
-    const apiUrl = publicUrl || authBaseURL;
-    if (!apiUrl) {
-      console.warn("[LtExtensions] No API URL configured. Set NUXT_PUBLIC_API_URL.");
+    const { baseUrl, missing, scope } = resolveLtApiBaseUrl();
+    if (missing) {
+      warnMissingLtApiUrl(scope);
     }
-    return `${(apiUrl || "").replace(/\/+$/, "")}${path}`;
+    return `${baseUrl}${path}`;
   } catch {
     return path;
   }

package/dist/runtime/plugins/lt-config-check.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Config Check Plugin
+ *
+ * Reports a missing API URL once at app init instead of waiting for whichever
+ * code path happens to build the first URL. The condition is read from
+ * `runtimeConfig` and is fixed for the module instance, so it belongs in a
+ * single boot-time check rather than in the hot `buildLtApiUrl()` path.
+ *
+ * Universal on purpose: SSR and the browser resolve the base URL from different
+ * keys (`NUXT_API_URL` vs `NUXT_PUBLIC_API_URL`) and can be misconfigured
+ * independently. On the server the plugin runs per request, but
+ * `warnMissingLtApiUrl()` is one-shot, so the warning still appears exactly once
+ * per process — and `buildLtApiUrl()` shares the same key, so it never repeats.
+ */
+import type { ObjectPlugin, Plugin } from '#app';
+declare const _default: ObjectPlugin & Plugin;
+export default _default;

package/dist/runtime/plugins/lt-config-check.js

@@ -0,0 +1,11 @@
+import { defineNuxtPlugin } from "#imports";
+import { resolveLtApiBaseUrl, warnMissingLtApiUrl } from "../lib/auth-state.js";
+export default defineNuxtPlugin(() => {
+  try {
+    const { missing, scope } = resolveLtApiBaseUrl();
+    if (missing) {
+      warnMissingLtApiUrl(scope);
+    }
+  } catch {
+  }
+});

package/dist/runtime/types/auth.d.ts

@@ -33,7 +33,7 @@ export interface LtAuthState {
  * All options have sensible defaults for nest-server compatibility
  */
 export interface LtAuthClientConfig {
-    /** API base URL (default: from env or http://localhost:3000) */
+    /** API base URL (default: `''` — empty means requests use the current app origin; production passes an explicit URL from `NUXT_PUBLIC_API_URL`. No implicit `localhost` fallback) */
     baseURL?: string;
     /** Auth API base path (default: '/iam' - must match nest-server betterAuth.basePath) */
     basePath?: string;

package/dist/runtime/types/module.d.ts

@@ -56,7 +56,7 @@ export interface LtAuthCookieNamesOptions {
 export interface LtAuthModuleOptions {
     /** Auth API base path (default: '/iam' - must match nest-server betterAuth.basePath) */
     basePath?: string;
-    /** API base URL (default: from env or http://localhost:3000) */
+    /** API base URL (default: `''` — resolved at runtime from `NUXT_PUBLIC_API_URL` / `NUXT_API_URL`; no implicit `localhost` fallback, so an unset URL keeps API paths relative to the app origin) */
     baseURL?: string;
     /** Override the cookie names used for auth state and JWT storage */
     cookieNames?: LtAuthCookieNamesOptions;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nuxt-extensions",
-  "version": "1.8.1",
+  "version": "1.8.3",
   "description": "Reusable Nuxt 4 composables, components, and Better-Auth integration for lenne.tech projects",
   "repository": {
     "type": "git",