@lenne.tech/nuxt-extensions 1.8.3 → 1.9.0

package/CLAUDE.md

@@ -13,7 +13,7 @@ src/
 │   ├── lib/               # Library exports (auth-client, auth-state, ai)
 │   ├── middleware/        # Route middleware (system setup)
 │   ├── plugins/           # Nuxt plugins (auth interceptor, error translation, config check)
-│   ├── server/            # Nitro server routes (auth proxy)
+│   ├── server/            # server-side tsconfig scope (no runtime routes; auth talks to the backend directly)
 │   ├── testing/           # Playwright test helpers
 │   ├── types/             # TypeScript type definitions
 │   └── utils/             # Auto-imported utility functions
@@ -85,17 +85,17 @@ The API base URL is resolved at runtime from `NUXT_PUBLIC_API_URL` (client + SSR
 ## Authentication (Better Auth)
 
 - SSR-safe session management via `useLtAuth()`
-- Auth proxy server route at `/api/auth/**` (proxies to backend)
-- Middleware `auth` for protected routes
+- Auth requests go **directly** to the backend Better-Auth endpoints (`basePath: '/iam'`) via `ltAuthFetch` (Cookie/JWT dual-mode) — the module ships **no** local Nitro `/api/auth/**` proxy
+- Protected-route gating is the consumer's own middleware (see "Custom Auth Middleware Pattern" below); the module only registers the optional `lt-system-setup` middleware
 - Passkey (WebAuthn) support via `@better-auth/passkey` peer dependency
 - 2FA (TOTP) support built-in
 
 ### Auth Flow
 
 1. Frontend calls `useLtAuth().signIn()` / `.signUp()`
-2. Request goes through Nitro proxy at `/api/auth/**`
-3. Proxy forwards to backend Better Auth endpoints
-4. Session cookie set via `httpOnly` cookie (SSR-safe)
+2. The Better-Auth client sends the request straight to the backend Better-Auth endpoints (`basePath: '/iam'`), with the base URL resolved by `buildLtApiUrl` (`NUXT_PUBLIC_API_URL` / SSR `NUXT_API_URL`)
+3. The backend sets the session as an `httpOnly` cookie (`iam.session_token`); `lt-auth-state` is the non-httpOnly client-side cache used by middleware
+4. Subsequent authenticated requests use `ltAuthFetch` (Cookie mode by default, JWT fallback)
 
 ## AI Assistant Flow
 
@@ -137,9 +137,21 @@ The `useLtAuth()` composable manages the `lt-auth-state` cookie for authenticati
 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.
+- **Authorization fields are fail-closed.** `role`, `roles`, `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.
 
+### Admin Detection (`role` vs `roles`):
+`useLtAuth().isAdmin` accepts BOTH user shapes, so one frontend works against either backend:
+
+- **`@lenne.tech/nest-server`** registers `roles` as a *core* Better-Auth additionalField (`type: 'string[]'`, `defaultValue: []`). Its users carry `roles: ['admin']` and no singular `role`.
+- **Better-Auth's admin plugin** uses the singular `role: 'admin'`.
+
+`isAdmin` is `true` when `role === 'admin'` **or** `roles` contains `'admin'` (a union — either shape granting admin is sufficient). A malformed non-array `roles` (the `lt-auth-state` cookie is client-writable) degrades to `false` — it never throws and never fail-opens via `String.prototype.includes` substring matching. Matching is case-sensitive (`'admin'`, not `'Admin'`), identical to nest-server's own `hasRole(RoleEnum.ADMIN)`.
+
+- `roles` is in `AUTHZ_KEYS`, so a backend-side admin revocation closes the admin UI on the next session re-validation instead of being masked by a stale cached array.
+- The `auth.enableAdmin` module option toggles the Better-Auth **admin client plugin** (user-management calls like `admin.listUsers()`). It does NOT control `isAdmin` — role detection works regardless of that flag.
+- **`isAdmin` is a UX gate, not an authorization boundary.** It reads the non-httpOnly `lt-auth-state` cache, which a user can edit. Render admin UI behind it; enforce admin rights server-side (`@Restricted(RoleEnum.ADMIN)`).
+
 ### Custom Auth Middleware Pattern:
 ```typescript
 // CORRECT — read-only check, no cookie mutation

package/README.md

@@ -166,6 +166,7 @@ export default defineNuxtConfig({
 const {
   user,
   isAuthenticated,
+  isAdmin,
   isLoading,
   signIn,
   signOut,
@@ -199,6 +200,42 @@ async function handlePasskeyLogin() {
 </template>
 ```
 
+#### Admin detection (`role` vs `roles`)
+
+`isAdmin` accepts **both** user shapes, so the same frontend works against either backend:
+
+| Backend | User shape | `isAdmin` is `true` when |
+|---------|------------|-------------------------|
+| `@lenne.tech/nest-server` | `roles: ['admin']` — core Better-Auth additionalField (`type: 'string[]'`), no singular `role` | `roles` contains `'admin'` |
+| Better-Auth admin plugin | `role: 'admin'` — single role | `role === 'admin'` |
+
+```vue
+<script setup>
+const { isAdmin } = useLtAuth();
+</script>
+
+<template>
+  <NuxtLink v-if="isAdmin" to="/admin">Admin</NuxtLink>
+</template>
+```
+
+> **`isAdmin` is a UX gate, not an authorization boundary.** It reads the client-side `lt-auth-state` cookie cache, which is not httpOnly and therefore user-writable. Use it to decide what to *render*; always enforce admin rights server-side (`@Restricted(RoleEnum.ADMIN)` in nest-server).
+>
+> The `auth.enableAdmin` option toggles the Better-Auth **admin client plugin** (user-management calls such as `admin.listUsers()`). It does **not** control `isAdmin` — role detection works regardless of that flag.
+
+For roles other than admin, use `hasRole(role)` / `hasAnyRole(...roles)`. They apply the exact same both-shapes union and `Array.isArray` guard as `isAdmin` (which is itself just `hasRole('admin')`), so you never need the unguarded `user.value?.roles?.includes(...)`:
+
+```vue
+<script setup>
+const { hasRole, hasAnyRole } = useLtAuth();
+</script>
+
+<template>
+  <button v-if="hasRole('editor')">Edit</button>
+  <NuxtLink v-if="hasAnyRole('admin', 'editor')" to="/manage">Manage</NuxtLink>
+</template>
+```
+
 ### Custom Better Auth Plugins
 
 You can extend the auth client with additional [Better Auth plugins](https://www.better-auth.com/docs/plugins):

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

@@ -46,7 +46,17 @@ export function useLtAuth() {
   const isJwtMode = computed(() => authMode.value === "jwt");
   const user = computed(() => resolvedAuthState.value?.user ?? null);
   const isAuthenticated = computed(() => !!user.value);
-  const isAdmin = computed(() => user.value?.role === "admin");
+  function hasRole(role) {
+    const current = user.value;
+    if (!current) {
+      return false;
+    }
+    return current.role === role || Array.isArray(current.roles) && current.roles.includes(role);
+  }
+  function hasAnyRole(...roles) {
+    return roles.some((role) => hasRole(role));
+  }
+  const isAdmin = computed(() => hasRole("admin"));
   const is2FAEnabled = computed(() => user.value?.twoFactorEnabled ?? false);
   const features = useState("lt-auth-features", () => ({}));
   const featuresFetched = useState("lt-auth-features-fetched", () => false);
@@ -129,7 +139,7 @@ export function useLtAuth() {
     }
     return response;
   }
-  const AUTHZ_KEYS = ["banExpires", "banReason", "banned", "emailVerified", "role", "twoFactorEnabled"];
+  const AUTHZ_KEYS = ["banExpires", "banReason", "banned", "emailVerified", "role", "roles", "twoFactorEnabled"];
   function mergeSessionUser(sessionUser) {
     const cached = resolvedAuthState.value?.user;
     if (!cached?.id || !sessionUser?.id || cached.id !== sessionUser.id) {
@@ -457,6 +467,8 @@ export function useLtAuth() {
     isLoading: computed(() => isLoading.value),
     user,
     // User properties
+    hasAnyRole,
+    hasRole,
     is2FAEnabled,
     isAdmin,
     // Feature detection

package/dist/runtime/plugins/auth-interceptor.client.d.ts

@@ -2,10 +2,17 @@
  * Auth Interceptor Plugin
  *
  * This plugin intercepts all API responses and handles session expiration.
- * When a 401 (Unauthorized) response is received, it automatically:
+ * When a 401 (Unauthorized) response is received, it verifies against the
+ * session endpoint that the session is genuinely dead and then automatically:
  * 1. Clears the user session state
  * 2. Redirects to the login page
  *
+ * The verification step exists because a 401 from a domain endpoint is not
+ * proof of an expired session: backends may mislabel permission errors
+ * (authenticated user, missing rights — semantically 403) as 401. Logging out
+ * on those would kick a logged-in user out of the app for a mere missing
+ * right. Only a dead session may clear state.
+ *
  * Note: This is a client-only plugin (.client.ts) since auth state
  * management only makes sense in the browser context.
  */

package/dist/runtime/plugins/auth-interceptor.client.js

@@ -1,4 +1,5 @@
 import { useLtAuth } from "../composables/auth/use-lt-auth.js";
+import { getLtApiBase } from "../lib/auth-state.js";
 export default (nuxtApp) => {
   if (import.meta.server) return;
   let _authInstance = null;
@@ -42,6 +43,19 @@ export default (nuxtApp) => {
     ];
     return authEndpoints.some((endpoint) => url.includes(endpoint));
   }
+  async function isSessionStillAlive() {
+    try {
+      const { fetchWithAuth } = getAuth();
+      const response = await fetchWithAuth(`${getLtApiBase()}/get-session`, { method: "GET" });
+      if (!response.ok) {
+        return false;
+      }
+      const data = await response.json().catch(() => null);
+      return Boolean(data && (data.user || data.session));
+    } catch {
+      return null;
+    }
+  }
   async function handleUnauthorized(requestUrl) {
     if (isHandling401) {
       return;
@@ -56,6 +70,13 @@ export default (nuxtApp) => {
     try {
       const { clearUser, isAuthenticated } = getAuth();
       if (isAuthenticated.value) {
+        const sessionAlive = await isSessionStillAlive();
+        if (sessionAlive !== false) {
+          console.debug(
+            sessionAlive ? `[LtAuth Interceptor] 401 from ${requestUrl ?? "unknown URL"} but session is still valid \u2014 treating it as a permission error, not logging out` : "[LtAuth Interceptor] 401 received but session state could not be verified \u2014 not logging out"
+          );
+          return;
+        }
         console.debug("[LtAuth Interceptor] Session expired, logging out...");
         clearUser();
         const router = nuxtApp.$router;

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

@@ -12,7 +12,22 @@ export interface LtUser {
     id: string;
     image?: string;
     name?: string;
+    /** Single-role shape (Better-Auth admin plugin). See also {@link LtUser.roles}. */
     role?: string;
+    /**
+     * Multi-role shape, and the canonical home for this fact: `@lenne.tech/nest-server`
+     * registers `roles` as a core Better-Auth additionalField (`type: 'string[]'`,
+     * `defaultValue: []`), so its users carry `roles: ['admin']` and usually NO
+     * singular `role`.
+     *
+     * NOT a source of authorization truth: this lives in the non-httpOnly
+     * `lt-auth-state` cookie and is therefore client-writable. It is kept
+     * fail-closed on session merge (see `AUTHZ_KEYS` in `use-lt-auth.ts`) so a
+     * backend downgrade is never masked by a stale value — that is a *staleness*
+     * guarantee, not a security guarantee. `isAdmin` reads it for UI gating;
+     * authorization is enforced server-side (`@Restricted(RoleEnum.ADMIN)`).
+     */
+    roles?: string[];
     twoFactorEnabled?: boolean;
 }
 /**
@@ -94,7 +109,50 @@ export interface UseLtAuthReturn {
     isLoading: ComputedRef<boolean>;
     jwtToken: Ref<string | null>;
     user: ComputedRef<LtUser | null>;
+    /**
+     * Returns `true` when the current user has ANY of the given roles (union).
+     * Same shape-tolerance and UX-gate-only caveats as {@link UseLtAuthReturn.hasRole}.
+     *
+     * @example
+     * // <NuxtLink v-if="hasAnyRole('admin', 'editor')" to="/manage">Manage</NuxtLink>
+     */
+    hasAnyRole: (...roles: string[]) => boolean;
+    /**
+     * Returns `true` when the current user has `role` in EITHER supported shape:
+     * `role === role` (Better-Auth admin plugin) or `roles` containing it
+     * (`@lenne.tech/nest-server`; see {@link LtUser.roles}). A malformed non-array
+     * `roles` degrades to `false` — never throws, never fail-opens via
+     * `String.prototype.includes` substring matching. Reads `user` live, so call it
+     * from a template or `computed` for reactivity.
+     *
+     * Prefer this over the raw `user.value?.roles?.includes(x)`, which is unguarded
+     * against the string-`roles` substring-confusion this method closes.
+     *
+     * UX gate only — the `lt-auth-state` cache is client-writable; enforce rights
+     * server-side.
+     *
+     * @example
+     * // <button v-if="hasRole('editor')">Edit</button>
+     * @see {@link LtUser.role}
+     * @see {@link LtUser.roles}
+     */
+    hasRole: (role: string) => boolean;
     is2FAEnabled: ComputedRef<boolean>;
+    /**
+     * `true` when the current user is an admin in EITHER supported shape:
+     * `role === 'admin'` (Better-Auth admin plugin) or `roles` containing `'admin'`
+     * (`@lenne.tech/nest-server`; see {@link LtUser.roles}). Equivalent to
+     * `hasRole('admin')`. A malformed non-array `roles` degrades to `false` (never
+     * throws, never fail-opens). Independent of the `enableAdmin` module option,
+     * which only toggles the Better-Auth admin *client plugin*.
+     *
+     * UX gate only: the `lt-auth-state` cache it reads is client-writable, so treat
+     * this as "what to render", never as the gate itself. Enforce admin rights
+     * server-side.
+     *
+     * @see {@link UseLtAuthReturn.hasRole}
+     * @see {@link LtUser.roles}
+     */
     isAdmin: ComputedRef<boolean>;
     features: ComputedRef<Record<string, boolean | number | string[]>>;
     fetchFeatures: () => Promise<Record<string, boolean | number | string[]>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nuxt-extensions",
-  "version": "1.8.3",
+  "version": "1.9.0",
   "description": "Reusable Nuxt 4 composables, components, and Better-Auth integration for lenne.tech projects",
   "repository": {
     "type": "git",
@@ -12,7 +12,7 @@
   },
   "author": "lenne.Tech <info@lenne.tech> (https://lenne.tech)",
   "license": "MIT",
-  "packageManager": "pnpm@10.33.0",
+  "packageManager": "pnpm@11.13.0",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -113,25 +113,6 @@
     "vitest": "4.1.7",
     "vue-tsc": "3.3.3"
   },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "@parcel/watcher",
-      "esbuild"
-    ],
-    "overrides": {
-      "brace-expansion@>=5.0.0 <5.0.6": "5.0.6",
-      "devalue@>=5.6.3 <=5.8.0": "5.8.1",
-      "kysely@>=0.26.0 <0.28.17": "0.28.17",
-      "ws@>=8.0.0 <8.20.1": "8.21.0",
-      "shell-quote@<1.8.4": "1.8.4",
-      "nuxt@<4.4.7": "4.4.7",
-      "vite@>=7.0.0 <7.3.5": "7.3.5",
-      "tar@<7.5.16": "7.5.16",
-      "launch-editor@<2.14.1": "2.14.1",
-      "esbuild@<0.28.1": "0.28.1",
-      "@babel/core@<7.29.6": "7.29.6"
-    }
-  },
   "keywords": [
     "nuxt",
     "nuxt-module",
@@ -144,5 +125,8 @@
     "tus-upload",
     "file-upload",
     "lenne-tech"
-  ]
+  ],
+  "engines": {
+    "node": ">= 22"
+  }
 }