@lenne.tech/nuxt-extensions 1.5.1 → 1.5.3

package/CLAUDE.md

@@ -0,0 +1,115 @@
+# @lenne.tech/nuxt-extensions
+
+Reusable Nuxt 4 module providing composables, components, utilities, and Better Auth integration for lenne.tech projects.
+
+## Architecture
+
+```
+src/
+├── module.ts              # Nuxt module entry point (auto-imports, plugin registration)
+├── runtime/
+│   ├── composables/       # Auto-imported composables
+│   ├── components/        # Auto-imported components
+│   ├── lib/               # Library exports (auth-client, helpers)
+│   ├── middleware/         # Route middleware (auth)
+│   ├── plugins/           # Nuxt plugins (auth initialization)
+│   ├── server/            # Nitro server routes (auth proxy)
+│   ├── testing/           # Playwright test helpers
+│   ├── types/             # TypeScript type definitions
+│   └── utils/             # Auto-imported utility functions
+```
+
+## Key Composables
+
+| Composable | Purpose |
+|-----------|---------|
+| `useBetterAuth()` | Authentication state, login, logout, session management |
+| `useAuthClient()` | Raw Better Auth client access |
+| `useTusUpload()` | TUS resumable file uploads |
+
+## Module Configuration
+
+Configure in `nuxt.config.ts`:
+
+```typescript
+export default defineNuxtConfig({
+  modules: ['@lenne.tech/nuxt-extensions'],
+  lennetech: {
+    // API base URL for auth proxy
+    apiUrl: 'http://localhost:3000',
+    // Enable/disable features
+    betterAuth: true,
+    tusUpload: true,
+  }
+})
+```
+
+## Authentication (Better Auth)
+
+- SSR-safe session management via `useBetterAuth()`
+- Auth proxy server route at `/api/auth/**` (proxies to backend)
+- Middleware `auth` for protected routes
+- Passkey (WebAuthn) support via `@better-auth/passkey` peer dependency
+- 2FA (TOTP) support built-in
+
+### Auth Flow
+
+1. Frontend calls `useBetterAuth().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)
+
+## Testing Helpers
+
+Import from `@lenne.tech/nuxt-extensions/testing`:
+
+```typescript
+import { createTestUser, loginTestUser } from '@lenne.tech/nuxt-extensions/testing';
+```
+
+## Authentication Cookie Rules
+
+The `useLtAuth()` composable manages the `lt-auth-state` cookie for authentication state. Projects that implement custom auth middleware MUST follow these rules:
+
+### DO:
+- Use `useLtAuth()` for all auth state management (login, logout, session validation)
+- In custom auth middleware, read `lt-auth-state` via `document.cookie` (client) or `useCookie('lt-auth-state')` (server) — but ONLY for reading, never writing
+- Let `setUser()` and `clearUser()` handle all cookie mutations
+
+### DON'T:
+- Don't manually set `lt-auth-state` via `document.cookie` outside of `useLtAuth()`
+- Don't call `useCookie('lt-auth-state')` with different options than `useLtAuth()` uses (`maxAge: 604800, sameSite: 'lax'`)
+- Don't URL-decode or JSON-parse the cookie value manually on the server — `useCookie` handles this automatically
+- Don't write to `authState.value` from custom middleware — this generates a `Set-Cookie` header in the SSR response that may overwrite the browser's cookie
+
+### How Auth Cookies Work:
+1. `setUser()` writes the cookie via both `useCookie().value` (for SSR sync) and `document.cookie` (for immediate availability)
+2. On SSR, `useCookie` reads the cookie from the HTTP Cookie header, URL-decodes it, and parses the JSON
+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
+
+### Custom Auth Middleware Pattern:
+```typescript
+// CORRECT — read-only check, no cookie mutation
+export default defineNuxtRouteMiddleware((to) => {
+  if (import.meta.client) {
+    const cookie = document.cookie.split('; ').find(r => r.startsWith('lt-auth-state='));
+    if (cookie) {
+      const value = decodeURIComponent(cookie.split('=').slice(1).join('='));
+      const state = JSON.parse(value);
+      if (state?.user) return; // Authenticated
+    }
+  } else {
+    const authCookie = useCookie<{ user: unknown } | null>('lt-auth-state');
+    if (authCookie.value?.user) return; // Authenticated
+  }
+  return navigateTo('/auth/login');
+});
+```
+
+## Development Rules
+
+1. **ALWAYS read source code** in `dist/runtime/` to understand available composables and components
+2. **Use `useBetterAuth()`** for authentication — never implement auth manually
+3. **Check existing composables** before creating new ones — this module may already provide what you need
+4. **Peer dependencies** (`better-auth`, `@better-auth/passkey`, `tus-js-client`) must be installed in the consuming project

package/dist/module.d.mts

@@ -6,7 +6,7 @@ export { LtAuthModuleOptions, LtErrorTranslationModuleOptions, LtExtensionsModul
 export { LtErrorTranslationResponse, LtParsedError, UseLtErrorTranslationReturn } from '../dist/runtime/types/error.js';
 
 declare const name = "@lenne.tech/nuxt-extensions";
-declare const version = "1.4.0";
+declare const version = "1.5.2";
 declare const configKey = "ltExtensions";
 declare const _default: _nuxt_schema.NuxtModule<LtExtensionsModuleOptions, LtExtensionsModuleOptions, false>;
 

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "configKey": "ltExtensions",
   "name": "@lenne.tech/nuxt-extensions",
-  "version": "1.4.0",
+  "version": "1.5.2",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -1,7 +1,7 @@
 import { defineNuxtModule, createResolver, addImports, addComponent, addPlugin, addRouteMiddleware } from '@nuxt/kit';
 
 const name = "@lenne.tech/nuxt-extensions";
-const version = "1.4.0";
+const version = "1.5.2";
 const configKey = "ltExtensions";
 const defaultOptions = {
   auth: {

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

@@ -465,7 +465,7 @@ export declare function createLtAuthClient(config?: LtAuthClientConfig): {
          */
         passkey: any;
         social: <FetchOptions extends import("better-auth").ClientFetchOption<Partial<{
-            provider: (string & {}) | "linear" | "huggingface" | "github" | "apple" | "atlassian" | "cognito" | "discord" | "facebook" | "figma" | "microsoft" | "google" | "slack" | "spotify" | "twitch" | "twitter" | "dropbox" | "kick" | "linkedin" | "gitlab" | "tiktok" | "reddit" | "roblox" | "salesforce" | "vk" | "zoom" | "notion" | "kakao" | "naver" | "line" | "paybin" | "paypal" | "polar" | "railway" | "vercel";
+            provider: (string & {}) | "linear" | "huggingface" | "github" | "apple" | "atlassian" | "cognito" | "discord" | "facebook" | "figma" | "microsoft" | "google" | "slack" | "spotify" | "twitch" | "twitter" | "dropbox" | "kick" | "linkedin" | "gitlab" | "tiktok" | "reddit" | "roblox" | "salesforce" | "vk" | "zoom" | "notion" | "kakao" | "naver" | "line" | "paybin" | "paypal" | "polar" | "railway" | "vercel" | "wechat";
             callbackURL?: string | undefined;
             newUserCallbackURL?: string | undefined;
             errorCallbackURL?: string | undefined;
@@ -489,7 +489,7 @@ export declare function createLtAuthClient(config?: LtAuthClientConfig): {
             loginHint?: string | undefined;
             additionalData?: Record<string, any> | undefined;
         }> & Record<string, any>, Partial<Record<string, any>> & Record<string, any>, Record<string, any> | undefined>>(data_0: import("better-auth").Prettify<{
-            provider: (string & {}) | "linear" | "huggingface" | "github" | "apple" | "atlassian" | "cognito" | "discord" | "facebook" | "figma" | "microsoft" | "google" | "slack" | "spotify" | "twitch" | "twitter" | "dropbox" | "kick" | "linkedin" | "gitlab" | "tiktok" | "reddit" | "roblox" | "salesforce" | "vk" | "zoom" | "notion" | "kakao" | "naver" | "line" | "paybin" | "paypal" | "polar" | "railway" | "vercel";
+            provider: (string & {}) | "linear" | "huggingface" | "github" | "apple" | "atlassian" | "cognito" | "discord" | "facebook" | "figma" | "microsoft" | "google" | "slack" | "spotify" | "twitch" | "twitter" | "dropbox" | "kick" | "linkedin" | "gitlab" | "tiktok" | "reddit" | "roblox" | "salesforce" | "vk" | "zoom" | "notion" | "kakao" | "naver" | "line" | "paybin" | "paypal" | "polar" | "railway" | "vercel" | "wechat";
             callbackURL?: string | undefined;
             newUserCallbackURL?: string | undefined;
             errorCallbackURL?: string | undefined;

package/dist/runtime/middleware/setup.d.ts

@@ -8,5 +8,6 @@
  * - needsSetup === true AND route != setupPath -> redirect to setupPath
  * - needsSetup === false AND route === setupPath -> redirect to loginPath
  */
-declare const _default: import("nuxt/app").RouteMiddleware;
+import type { RouteMiddleware } from "#app";
+declare const _default: RouteMiddleware;
 export default _default;

package/dist/runtime/plugins/error-translation.client.d.ts

@@ -4,5 +4,6 @@
  * Automatically loads error translations on app start.
  * Provides global helper methods: $ltTranslateError, $ltShowErrorToast
  */
-declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
+import type { ObjectPlugin, Plugin } from "#app";
+declare const _default: Plugin & ObjectPlugin;
 export default _default;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nuxt-extensions",
-  "version": "1.5.1",
+  "version": "1.5.3",
   "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.32.1",
+  "packageManager": "pnpm@10.33.0",
   "type": "module",
   "exports": {
     ".": {
@@ -43,7 +43,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "CLAUDE.md"
   ],
   "scripts": {
     "prepare": "git config core.hooksPath .githooks",
@@ -93,22 +94,22 @@
     }
   },
   "devDependencies": {
-    "@better-auth/passkey": "1.5.5",
-    "@nuxt/devtools": "3.2.3",
+    "@better-auth/passkey": "1.5.6",
+    "@nuxt/devtools": "3.2.4",
     "@nuxt/module-builder": "1.0.2",
     "@nuxt/schema": "4.4.2",
-    "@playwright/test": "1.58.2",
-    "@types/node": "25.5.0",
-    "@vitest/coverage-v8": "4.1.0",
-    "better-auth": "1.5.5",
-    "happy-dom": "20.8.4",
+    "@playwright/test": "1.59.1",
+    "@types/node": "25.5.2",
+    "@vitest/coverage-v8": "4.1.2",
+    "better-auth": "1.5.6",
+    "happy-dom": "20.8.9",
     "nuxt": "4.4.2",
-    "oxfmt": "0.40.0",
-    "oxlint": "1.55.0",
+    "oxfmt": "0.43.0",
+    "oxlint": "1.58.0",
     "tus-js-client": "4.3.1",
     "typescript": "5.9.3",
-    "vitest": "4.1.0",
-    "vue-tsc": "3.2.5"
+    "vitest": "4.1.2",
+    "vue-tsc": "3.2.6"
   },
   "pnpm": {
     "onlyBuiltDependencies": [
@@ -116,13 +117,23 @@
       "esbuild"
     ],
     "overrides": {
-      "minimatch@>=5.0.0 <5.1.8": "5.1.8",
-      "minimatch@>=9.0.0 <9.0.7": "9.0.7",
-      "minimatch@>=10.0.0 <10.2.3": "10.2.3",
+      "brace-expansion@<2.0.3": ">=2.0.3",
+      "brace-expansion@>=4.0.0 <5.0.5": ">=5.0.5",
+      "defu@<=6.1.4": ">=6.1.5",
+      "h3@<1.15.9": ">=1.15.9",
+      "lodash@<=4.17.23": ">=4.18.0",
+      "minimatch@>=5.0.0 <5.1.9": "5.1.9",
+      "minimatch@>=9.0.0 <9.0.9": "9.0.9",
+      "minimatch@>=10.0.0 <10.2.5": "10.2.5",
+      "node-forge@<1.4.0": ">=1.4.0",
+      "picomatch@<2.3.2": ">=2.3.2",
+      "picomatch@>=4.0.0 <4.0.4": ">=4.0.4",
       "rollup@>=4.0.0 <4.59.0": ">=4.59.0",
-      "serialize-javascript@<=7.0.2": ">=7.0.3",
+      "serialize-javascript@<7.0.5": ">=7.0.5",
+      "srvx@<0.11.13": ">=0.11.13",
       "svgo@=4.0.0": ">=4.0.1",
-      "tar@<7.5.11": "7.5.11"
+      "tar@<7.5.11": "7.5.11",
+      "yaml@>=2.0.0 <2.8.3": ">=2.8.3"
     }
   },
   "keywords": [