@habityzer/nuxt-symfony-kinde-layer 2.2.0 → 2.2.2

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## [2.2.2](https://github.com/Habityzer/nuxt-symfony-kinde-layer/compare/v2.2.1...v2.2.2) (2026-02-18)
+
+
+### Bug Fixes
+
+* Enhance Kinde authentication configuration and type safety ([ee59fc4](https://github.com/Habityzer/nuxt-symfony-kinde-layer/commit/ee59fc4d97832f9effcedb613c9c57773cee3d80))
+* Update pnpm lockfile to use published @habityzer/nuxt-kinde-auth package ([39e9f2c](https://github.com/Habityzer/nuxt-symfony-kinde-layer/commit/39e9f2c19ffa5f731cef610bd219dc3f4ba90bf5))
+
+## [2.2.1](https://github.com/Habityzer/nuxt-symfony-kinde-layer/compare/v2.2.0...v2.2.1) (2026-02-13)
+
 # [2.2.0](https://github.com/Habityzer/nuxt-symfony-kinde-layer/compare/v2.1.4...v2.2.0) (2026-02-13)
 
 

package/README.md

@@ -47,13 +47,13 @@ export default defineNuxtConfig({
     public: {
       apiBaseUrl: process.env.API_BASE_URL,
       
-      // IMPORTANT: Expose auth config for middleware (must match kindeAuth below)
+      // Optional: Override layer defaults for auth config
       kindeAuth: {
         cookie: {
-          prefix: 'myapp_' // Must match prefix in kindeAuth
+          prefix: 'myapp_' // Override default cookie prefix
         },
         middleware: {
-          publicRoutes: ['/', '/blog', '/help']
+          publicRoutes: ['/', '/blog', '/help'] // Override default public routes
         }
       }
     }
@@ -61,17 +61,17 @@ export default defineNuxtConfig({
 
   // Configure Kinde authentication module
   kindeAuth: {
-    authDomain: process.env.NUXT_KINDE_AUTH_DOMAIN,
-    clientId: process.env.NUXT_KINDE_CLIENT_ID,
-    clientSecret: process.env.NUXT_KINDE_CLIENT_SECRET,
-    redirectURL: process.env.NUXT_KINDE_REDIRECT_URL,
-    logoutRedirectURL: process.env.NUXT_KINDE_LOGOUT_REDIRECT_URL,
+    authDomain: process.env.KINDE_AUTH_DOMAIN,
+    clientId: process.env.KINDE_CLIENT_ID,
+    clientSecret: process.env.KINDE_CLIENT_SECRET,
+    redirectURL: process.env.KINDE_REDIRECT_URL,
+    logoutRedirectURL: process.env.KINDE_LOGOUT_REDIRECT_URL,
     postLoginRedirectURL: '/dashboard',
     cookie: {
-      prefix: 'myapp_' // IMPORTANT: Must be unique per project to avoid cookie conflicts
+      prefix: 'myapp_' // IMPORTANT: Must match runtimeConfig.public.kindeAuth.cookie.prefix
     },
     middleware: {
-      publicRoutes: ['/', '/blog', '/help'] // Must match publicRoutes in runtimeConfig.public
+      publicRoutes: ['/', '/blog', '/help'] // Must match runtimeConfig.public
     }
   }
 })
@@ -79,21 +79,32 @@ export default defineNuxtConfig({
 
 ### 2. Environment Variables
 
-Create a `.env` file:
+Create a `.env` file in your project:
 
 ```bash
 # Symfony Backend
 API_BASE_URL=http://localhost:8000
 
-# Kinde Authentication
-NUXT_KINDE_AUTH_DOMAIN=https://your-domain.kinde.com
-NUXT_KINDE_CLIENT_ID=your-client-id
-NUXT_KINDE_CLIENT_SECRET=your-client-secret
-NUXT_KINDE_REDIRECT_URL=http://localhost:3000/api/kinde/callback
-NUXT_KINDE_LOGOUT_REDIRECT_URL=http://localhost:3000
-NUXT_KINDE_POST_LOGIN_REDIRECT_URL=/dashboard
+# Kinde Authentication (required by @habityzer/nuxt-kinde-auth module)
+KINDE_AUTH_DOMAIN=https://your-domain.kinde.com
+KINDE_CLIENT_ID=your-client-id
+KINDE_CLIENT_SECRET=your-client-secret
+KINDE_REDIRECT_URL=http://localhost:3000/api/kinde/callback
+KINDE_LOGOUT_REDIRECT_URL=http://localhost:3000
+
+# Layer Configuration (optional - layer provides defaults)
+NUXT_PUBLIC_AUTH_COOKIE_PREFIX=myapp_
+NUXT_PUBLIC_AUTH_LOGIN_PATH=/api/kinde/login
+NUXT_PUBLIC_AUTH_CLOCK_SKEW_SECONDS=300
+NUXT_PUBLIC_AUTH_APP_TOKEN_PREFIX=Bearer
+NUXT_PUBLIC_AUTH_E2E_TOKEN_COOKIE_NAME=kinde_token
+NUXT_PUBLIC_AUTH_ID_TOKEN_NAME=id_token
+NUXT_PUBLIC_AUTH_ACCESS_TOKEN_NAME=access_token
+NUXT_PUBLIC_AUTH_REFRESH_TOKEN_NAME=refresh_token
 ```
 
+**Note:** The layer provides sensible defaults for all `NUXT_PUBLIC_AUTH_*` variables. You only need to override them if you want different values. The `KINDE_*` variables are required.
+
 ### 3. Use the Auth Composable
 
 ```vue
@@ -158,9 +169,12 @@ const response = await getUsersApi()
 ### Files
 
 - `server/api/symfony/[...].ts` - Symfony API proxy with auth
+- `server/middleware/auth-guard.ts` - Server-side authentication middleware
+- `server/utils/auth-constants.ts` - Re-exports shared auth constants for server
 - `app/composables/useAuth.ts` - Authentication composable
-- `app/constants/auth.ts` - Auth constants
-- `app/middleware/auth.global.ts` - Global route protection
+- `app/plugins/auth-guard.client.ts` - Client-side authentication guard
+- `app/constants/auth.ts` - Re-exports shared auth constants for app
+- `shared/auth-constants.ts` - Core authentication constants (source of truth)
 
 ## Configuration Options
 
@@ -266,16 +280,19 @@ Add these scripts to your project's `package.json`:
    pnpm install
    ```
 
-2. **The project uses Husky for git hooks:**
-   - Pre-commit: Automatically runs `pnpm lint` before each commit
-   - Commit-msg: Validates commit message format (conventional commits)
-
-3. **Run linter manually:**
+2. **Available scripts:**
    ```bash
-   pnpm lint        # Check for issues
-   pnpm lint:fix    # Auto-fix issues
+   pnpm dev          # Run dev server with example env
+   pnpm build        # Build the layer
+   pnpm lint         # Check for linting issues
+   pnpm lint:fix     # Auto-fix linting issues
+   pnpm release      # Create semantic release (CI only)
    ```
 
+3. **Git hooks (via Husky):**
+   - Pre-commit: Automatically runs `pnpm lint` before each commit
+   - Commit-msg: Validates commit message format (conventional commits)
+
 4. **First time setup:**
    The pre-commit hook will automatically run `nuxt prepare` if needed (with placeholder environment variables).
 
@@ -354,16 +371,34 @@ If you get type mismatches between expected Hydra collections and plain arrays,
 
 ## Architecture & Design Decisions
 
-### Why Constants Are Defined Inline in Server Code
+### Shared Constants Architecture
+
+The layer uses a centralized constants file at `shared/auth-constants.ts` as the single source of truth for authentication configuration values (cookie names, token prefixes, etc.).
+
+**Structure:**
+- `shared/auth-constants.ts` - Core constants definitions
+- `app/constants/auth.ts` - Re-exports for client-side code (supports `~/constants/auth` imports)
+- `server/utils/auth-constants.ts` - Re-exports for server-side code (supports `#imports` and relative imports)
+
+**Why this structure:**
+- Single source of truth prevents drift between client and server values
+- Re-export pattern works around Nuxt/Nitro bundling constraints
+- Maintains clean import paths for consuming projects
+
+### Runtime Configuration
 
-You'll notice that auth constants (`E2E_TOKEN_COOKIE_NAME`, `APP_TOKEN_PREFIX`, `KINDE_ID_TOKEN_COOKIE_NAME`) are defined directly in the server files (`server/api/symfony/[...].ts`) rather than imported from a shared constants file.
+The layer uses Nuxt's `runtimeConfig` to make authentication settings available to both server middleware and client code:
 
-**Reason**: Nitro's bundling process for server-side code doesn't support:
-- App aliases like `~` or `@` (these resolve to the consuming project's app directory, not the layer's)
-- Relative imports from external layers during the rollup bundling phase
-- The `#build` alias for accessing layer exports
+**Implementation:**
+1. Constants are imported in `nuxt.config.ts` from `shared/auth-constants.ts`
+2. Environment variables override defaults (e.g., `NUXT_PUBLIC_AUTH_COOKIE_PREFIX`)
+3. Values are merged into `runtimeConfig.public.kindeAuth` for runtime access
+4. Both server middleware and client plugins read from runtime config
 
-**Solution**: We define these constants inline in server files while maintaining the shared `app/constants/auth.ts` for client-side code. This is a deliberate architectural choice to ensure reliable builds across all consuming projects.
+This approach allows:
+- Projects to override defaults via environment variables
+- Type-safe access to configuration throughout the app
+- Consistent behavior between development and production
 
 ### Cookie Prefix Configuration
 

package/app/composables/useAuth.ts

@@ -1,4 +1,5 @@
 import { computed, ref, readonly } from 'vue'
+import type { KindeAuthRuntimeConfig } from '../../types/kinde-auth'
 import { E2E_TOKEN_COOKIE_NAME } from '../constants/auth'
 
 const LEGACY_E2E_STORAGE_KEY = 'e2e_app_token'
@@ -110,7 +111,7 @@ export const useAuth = () => {
     // Clear auth cookies first so route middleware blocks protected pages immediately.
     if (import.meta.client) {
       const config = useRuntimeConfig()
-      const kindeConfig = config.public.kindeAuth || {}
+      const kindeConfig = (config.public.kindeAuth || {}) as KindeAuthRuntimeConfig
       const cookieConfig = kindeConfig.cookie || {}
       const middlewareConfig = kindeConfig.middleware || {}
       const cookiePrefix = requireString(cookieConfig.prefix, 'kindeAuth.cookie.prefix')

package/app/plugins/auth-guard.client.ts

@@ -1,10 +1,11 @@
+import type { KindeAuthRuntimeConfig } from '../../types/kinde-auth'
+
 export default defineNuxtPlugin(() => {
   const router = useRouter()
   const config = useRuntimeConfig()
-  const kindeConfig = config.public.kindeAuth || {}
+  const kindeConfig = (config.public.kindeAuth || {}) as KindeAuthRuntimeConfig
   const middlewareConfig = kindeConfig.middleware || {}
   const cookieConfig = kindeConfig.cookie || {}
-  // @ts-expect-error - cookie property exists in runtime config but not in module types
   const cookiePrefix = requireString(cookieConfig.prefix, 'kindeAuth.cookie.prefix')
   const idTokenBaseName = requireString(cookieConfig.idTokenName, 'kindeAuth.cookie.idTokenName')
   const accessTokenBaseName = requireString(cookieConfig.accessTokenName, 'kindeAuth.cookie.accessTokenName')

package/nuxt.config.ts

@@ -25,7 +25,6 @@ export default defineNuxtConfig({
   modules: [
     '@nuxt/eslint',
     '@nuxt/ui',
-    '@nuxt/image',
     '@habityzer/nuxt-kinde-auth',
     '@pinia/nuxt'
   ],
@@ -136,15 +135,31 @@ export default defineNuxtConfig({
   pinia: {}
 })
 
+// Mapping of runtime config keys to their environment variable names
+const CONFIG_TO_ENV_MAP: Record<string, string> = {
+  'runtimeConfig.public.kindeAuth.cookie.prefix': 'NUXT_PUBLIC_AUTH_COOKIE_PREFIX',
+  'runtimeConfig.public.kindeAuth.middleware.clockSkewSeconds': 'NUXT_PUBLIC_AUTH_CLOCK_SKEW_SECONDS',
+  'kindeAuth.cookie.prefix': 'NUXT_PUBLIC_AUTH_COOKIE_PREFIX',
+  'kindeAuth.authDomain': 'KINDE_AUTH_DOMAIN',
+  'kindeAuth.clientId': 'KINDE_CLIENT_ID',
+  'kindeAuth.clientSecret': 'KINDE_CLIENT_SECRET',
+  'kindeAuth.redirectURL': 'KINDE_REDIRECT_URL',
+  'kindeAuth.logoutRedirectURL': 'KINDE_LOGOUT_REDIRECT_URL'
+}
+
 function assertRequiredString(value: unknown, key: string) {
   if (typeof value !== 'string' || value.trim().length === 0) {
-    throw new Error(`[nuxt-symfony-kinde-layer] Missing required config: ${key}`)
+    const envVar = CONFIG_TO_ENV_MAP[key]
+    const envVarHint = envVar ? `\n\n  \x1b[1m\x1b[33m→ Set the environment variable:\x1b[0m \x1b[1m\x1b[36m${envVar}\x1b[0m\n  \x1b[90mAdd it to your .env file (see .env.example for reference)\x1b[0m` : ''
+    throw new Error(`[nuxt-symfony-kinde-layer] \x1b[1m\x1b[31mMissing required config:\x1b[0m ${key}${envVarHint}`)
   }
 }
 
 function assertRequiredNumber(value: unknown, key: string) {
   if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
-    throw new Error(`[nuxt-symfony-kinde-layer] Missing or invalid required numeric config: ${key}`)
+    const envVar = CONFIG_TO_ENV_MAP[key]
+    const envVarHint = envVar ? `\n\n  \x1b[1m\x1b[33m→ Set the environment variable:\x1b[0m \x1b[1m\x1b[36m${envVar}\x1b[0m\n  \x1b[90mAdd it to your .env file (see .env.example for reference)\x1b[0m` : ''
+    throw new Error(`[nuxt-symfony-kinde-layer] \x1b[1m\x1b[31mMissing or invalid required numeric config:\x1b[0m ${key}${envVarHint}`)
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@habityzer/nuxt-symfony-kinde-layer",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "description": "Shared Nuxt layer for Symfony + Kinde authentication integration",
   "type": "module",
   "main": "./nuxt.config.ts",
@@ -23,11 +23,11 @@
   "author": "Habityzer",
   "license": "MIT",
   "dependencies": {
-    "@habityzer/nuxt-kinde-auth": "^1.2.0",
-    "@pinia/nuxt": "^0.11.2",
-    "@nuxt/ui": "^4.0.1",
-    "@nuxt/image": "^1.11.0",
+    "@habityzer/nuxt-kinde-auth": "^1.2.2",
     "@nuxt/eslint": "^1.9.0",
+    "@nuxt/image": "^1.11.0",
+    "@nuxt/ui": "^4.0.1",
+    "@pinia/nuxt": "^0.11.2",
     "@vueuse/core": "^13.9.0",
     "nuxt": "^4.1.3",
     "vue": "^3.5.22",
@@ -35,20 +35,20 @@
   },
   "devDependencies": {
     "@commitlint/config-conventional": "^19.8.1",
-    "commitlint": "^19.8.1",
-    "conventional-changelog-conventionalcommits": "^9.1.0",
+    "@habityzer/nuxt-openapi-composables": "^1.1.0",
+    "@iconify-json/heroicons": "^1.2.3",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/commit-analyzer": "^13.0.1",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/npm": "^12.0.1",
     "@semantic-release/release-notes-generator": "^14.1.0",
-    "@habityzer/nuxt-openapi-composables": "^1.1.0",
-    "@iconify-json/heroicons": "^1.2.3",
-    "openapi-typescript": "^7.10.0",
-    "typescript": "^5.9.3",
+    "commitlint": "^19.8.1",
+    "conventional-changelog-conventionalcommits": "^9.1.0",
     "eslint": "^9.37.0",
+    "husky": "^9.0.0",
+    "openapi-typescript": "^7.10.0",
     "semantic-release": "^24.2.9",
-    "husky": "^9.0.0"
+    "typescript": "^5.9.3"
   },
   "peerDependencies": {
     "nuxt": "^3.0.0 || ^4.0.0"

package/server/api/symfony/[...].ts

@@ -12,9 +12,11 @@
  * @see .cursorrules for proxy best practices
  */
 
+import type { KindeAuthRuntimeConfig } from '../../../types/kinde-auth'
+
 export default defineEventHandler(async (event) => {
   const config = useRuntimeConfig()
-  const kindeConfig = config.public.kindeAuth || {}
+  const kindeConfig = (config.public.kindeAuth || {}) as KindeAuthRuntimeConfig
   const middlewareConfig = kindeConfig.middleware || {}
   const cookieConfig = kindeConfig.cookie || {}
   const appTokenPrefix = requireString(middlewareConfig.appTokenPrefix, 'kindeAuth.middleware.appTokenPrefix')
@@ -32,7 +34,7 @@ export default defineEventHandler(async (event) => {
 
   // Check if this is a public API route (no auth required)
   const publicApiRoutes
-    = config.public.kindeAuth?.middleware?.publicApiRoutes || []
+    = (config.public.kindeAuth as KindeAuthRuntimeConfig | undefined)?.middleware?.publicApiRoutes || []
   const isPublicRoute = publicApiRoutes.some((route: string) => {
     if (route.endsWith('/**')) {
       const prefix = route.slice(0, -3)
@@ -124,13 +126,13 @@ export default defineEventHandler(async (event) => {
     // Get Content-Type to determine how to handle body
     const contentType = getHeader(event, 'content-type') || ''
 
-    let body: string | undefined
+    let body: string | Buffer | undefined
 
     // Handle multipart/form-data specially (preserve binary data and MIME types)
     if (contentType.includes('multipart/form-data')) {
       // For multipart/form-data, read the raw body without parsing
       // This preserves the boundary and binary data including MIME types
-      body = await readRawBody(event, false)
+      body = await readRawBody(event, false) as string | Buffer | undefined
     } else if (method !== 'GET' && method !== 'HEAD') {
       // For other content types (JSON, etc.), read and parse the body
       body = await readBody(event)

package/types/kinde-auth.d.ts

@@ -6,11 +6,19 @@ declare module '@habityzer/nuxt-kinde-auth' {
   interface ModuleOptions {
     cookie?: {
       prefix?: string
+      idTokenName?: string
+      accessTokenName?: string
+      refreshTokenName?: string
     }
     middleware?: {
       enabled?: boolean
       global?: boolean
       publicRoutes?: string[]
+      publicApiRoutes?: string[]
+      e2eTokenCookieName?: string
+      appTokenPrefix?: string
+      clockSkewSeconds?: number
+      loginPath?: string
     }
     debug?: {
       enabled?: boolean
@@ -18,4 +26,25 @@ declare module '@habityzer/nuxt-kinde-auth' {
   }
 }
 
-export {}
+/** Runtime config shape for kindeAuth (used for type-safe access in layer code) */
+export interface KindeAuthRuntimeConfig {
+  cookie?: {
+    prefix?: string
+    idTokenName?: string
+    accessTokenName?: string
+    refreshTokenName?: string
+  }
+  middleware?: {
+    enabled?: boolean
+    global?: boolean
+    publicRoutes?: string[]
+    publicApiRoutes?: string[]
+    e2eTokenCookieName?: string
+    appTokenPrefix?: string
+    clockSkewSeconds?: number
+    loginPath?: string
+  }
+  debug?: {
+    enabled?: boolean
+  }
+}