@lenne.tech/nuxt-extensions 1.5.2 → 1.5.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CLAUDE.md +40 -0
- package/package.json +1 -1
package/CLAUDE.md
CHANGED
|
@@ -67,6 +67,46 @@ Import from `@lenne.tech/nuxt-extensions/testing`:
|
|
|
67
67
|
import { createTestUser, loginTestUser } from '@lenne.tech/nuxt-extensions/testing';
|
|
68
68
|
```
|
|
69
69
|
|
|
70
|
+
## Authentication Cookie Rules
|
|
71
|
+
|
|
72
|
+
The `useLtAuth()` composable manages the `lt-auth-state` cookie for authentication state. Projects that implement custom auth middleware MUST follow these rules:
|
|
73
|
+
|
|
74
|
+
### DO:
|
|
75
|
+
- Use `useLtAuth()` for all auth state management (login, logout, session validation)
|
|
76
|
+
- In custom auth middleware, read `lt-auth-state` via `document.cookie` (client) or `useCookie('lt-auth-state')` (server) — but ONLY for reading, never writing
|
|
77
|
+
- Let `setUser()` and `clearUser()` handle all cookie mutations
|
|
78
|
+
|
|
79
|
+
### DON'T:
|
|
80
|
+
- Don't manually set `lt-auth-state` via `document.cookie` outside of `useLtAuth()`
|
|
81
|
+
- Don't call `useCookie('lt-auth-state')` with different options than `useLtAuth()` uses (`maxAge: 604800, sameSite: 'lax'`)
|
|
82
|
+
- Don't URL-decode or JSON-parse the cookie value manually on the server — `useCookie` handles this automatically
|
|
83
|
+
- 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
|
|
84
|
+
|
|
85
|
+
### How Auth Cookies Work:
|
|
86
|
+
1. `setUser()` writes the cookie via both `useCookie().value` (for SSR sync) and `document.cookie` (for immediate availability)
|
|
87
|
+
2. On SSR, `useCookie` reads the cookie from the HTTP Cookie header, URL-decodes it, and parses the JSON
|
|
88
|
+
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
|
|
89
|
+
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
|
|
90
|
+
|
|
91
|
+
### Custom Auth Middleware Pattern:
|
|
92
|
+
```typescript
|
|
93
|
+
// CORRECT — read-only check, no cookie mutation
|
|
94
|
+
export default defineNuxtRouteMiddleware((to) => {
|
|
95
|
+
if (import.meta.client) {
|
|
96
|
+
const cookie = document.cookie.split('; ').find(r => r.startsWith('lt-auth-state='));
|
|
97
|
+
if (cookie) {
|
|
98
|
+
const value = decodeURIComponent(cookie.split('=').slice(1).join('='));
|
|
99
|
+
const state = JSON.parse(value);
|
|
100
|
+
if (state?.user) return; // Authenticated
|
|
101
|
+
}
|
|
102
|
+
} else {
|
|
103
|
+
const authCookie = useCookie<{ user: unknown } | null>('lt-auth-state');
|
|
104
|
+
if (authCookie.value?.user) return; // Authenticated
|
|
105
|
+
}
|
|
106
|
+
return navigateTo('/auth/login');
|
|
107
|
+
});
|
|
108
|
+
```
|
|
109
|
+
|
|
70
110
|
## Development Rules
|
|
71
111
|
|
|
72
112
|
1. **ALWAYS read source code** in `dist/runtime/` to understand available composables and components
|