@devcoffee/nuxt-core 1.0.2 → 1.1.1

package/README.md

@@ -1,84 +1,405 @@
-<!--
-Get your module up and running quickly.
-
-Find and replace all on all files (CMD+SHIFT+F):
-- Name: My Module
-- Package name: my-module
-- Description: My new Nuxt module
--->
-
-# My Module
-
-[![npm version][npm-version-src]][npm-version-href]
-[![npm downloads][npm-downloads-src]][npm-downloads-href]
-[![License][license-src]][license-href]
-[![Nuxt][nuxt-src]][nuxt-href]
-
-My new Nuxt module for doing amazing things.
-
-- [✨ &nbsp;Release Notes](/CHANGELOG.md)
-<!-- - [🏀 Online playground](https://stackblitz.com/github/your-org/my-module?file=playground%2Fapp.vue) -->
-<!-- - [📖 &nbsp;Documentation](https://example.com) -->
-
-## Features
-
-<!-- Highlight some of the features your module provide here -->
-- ⛰ &nbsp;Foo
-- 🚠 &nbsp;Bar
-- 🌲 &nbsp;Baz
-
-## Quick Setup
-
-Install the module to your Nuxt application with one command:
-
-```bash
-npx nuxi module add my-module
-```
-
-That's it! You can now use My Module in your Nuxt app ✨
-
-
-## Contribution
-
-<details>
-  <summary>Local development</summary>
-  
-  ```bash
-  # Install dependencies
-  npm install
-  
-  # Generate type stubs
-  npm run dev:prepare
-  
-  # Develop with the playground
-  npm run dev
-  
-  # Build the playground
-  npm run dev:build
-  
-  # Run ESLint
-  npm run lint
-  
-  # Run Vitest
-  npm run test
-  npm run test:watch
-  
-  # Release new version
-  npm run release
-  ```
-
-</details>
-
-
-<!-- Badges -->
-[npm-version-src]: https://img.shields.io/npm/v/my-module/latest.svg?style=flat&colorA=020420&colorB=00DC82
-[npm-version-href]: https://npmjs.com/package/my-module
-
-[npm-downloads-src]: https://img.shields.io/npm/dm/my-module.svg?style=flat&colorA=020420&colorB=00DC82
-[npm-downloads-href]: https://npm.chart.dev/my-module
-
-[license-src]: https://img.shields.io/npm/l/my-module.svg?style=flat&colorA=020420&colorB=00DC82
-[license-href]: https://npmjs.com/package/my-module
-
-[nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt.js
-[nuxt-href]: https://nuxt.com
+# @devcoffee/nuxt-core
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![License][license-src]][license-href]
+[![Nuxt][nuxt-src]][nuxt-href]
+
+Full OpenID Connect / OAuth 2.0 authorization code grant with PKCE for DevCoffee internal Nuxt 4 applications.
+Provides server-side session management via Nitro, client-side auth state via Vue composables, and universal route protection middleware.
+
+- [Release Notes](/CHANGELOG.md)
+- [Contributor Guide](/GUIDELINE.md)
+
+## Features
+
+- PKCE-enforced authorization code flow (S256, enabled by default)
+- HMAC-SHA256 signed session cookies when `sessions.secret` is configured
+- AES-256-GCM encrypted tokenSet storage with HKDF-derived key
+- 256-bit session ID entropy via `crypto.randomBytes(32)`
+- Open redirect protection on all post-auth redirects
+- Per-route protection via `definePageMeta` — no page-level boilerplate
+- Auto-imported composables: `useAuthContext`, `useSessionContext`, `useLogger`
+- Server-side session validation on every Nitro request
+- Token refresh mutex — no concurrent refresh races
+- User info caching with configurable TTL
+- Nuxt DevTools integration (session inspector)
+
+## Requirements
+
+- **Nuxt:** `^4.0.0` — Nuxt 3 is not supported
+- **Node.js:** LTS (18+)
+- **OIDC provider:** Any provider with a `.well-known/openid-configuration` endpoint
+
+## Installation
+
+```bash
+npm install @devcoffee/nuxt-core
+```
+
+Register the module in `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  modules: ['@devcoffee/nuxt-core'],
+})
+```
+
+## Quick Setup
+
+**1. Install and register the module** (see [Installation](#installation) above).
+
+**2. Add the minimum config to `nuxt.config.ts`:**
+
+```ts
+export default defineNuxtConfig({
+  modules: ['@devcoffee/nuxt-core'],
+  nuxtCore: {
+    authts: {
+      openid: {
+        wellKnownUrl: process.env.OIDC_WELL_KNOWN_URL!,
+        clientId: process.env.OIDC_CLIENT_ID!,
+        clientSecret: process.env.OIDC_CLIENT_SECRET!,
+        redirectUri: '/authorize',
+        scopes: ['openid', 'profile', 'email'],
+      },
+      sessions: {
+        secret: process.env.SESSION_SECRET!,
+      },
+    },
+  },
+})
+```
+
+**3. Create the server handler** — **required**. Auth endpoints return 404 without this file.
+
+Create `server/api/_auth/[...].ts`:
+
+```ts
+export default NuxtAuthtsHandler({
+  userInfo: async (user, { openidUser }) => ({
+    ...user,
+    id: openidUser?.sub ?? user.id,
+    email: openidUser?.email ?? user.email,
+    firstName: openidUser?.given_name ?? user.firstName,
+    lastName: openidUser?.family_name ?? user.lastName,
+  }),
+})
+```
+
+> The OIDC callback page at `openid.redirectUri` (default `/authorize`) is auto-registered by the module. Do NOT create it manually.
+
+**4. Set environment variables:**
+
+```bash
+OIDC_WELL_KNOWN_URL=https://your-provider/.well-known/openid-configuration
+OIDC_CLIENT_ID=your-client-id
+OIDC_CLIENT_SECRET=your-client-secret
+SESSION_SECRET=your-32-char-minimum-random-secret
+```
+
+## Configuration Reference
+
+All options are nested under `nuxtCore` in `nuxt.config.ts`.
+
+### `authts.openid` options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `wellKnownUrl` | `string` | `''` (required) | OIDC provider discovery URL (`/.well-known/openid-configuration` endpoint) |
+| `clientId` | `string` | `''` (required) | OAuth 2.0 client ID registered with the OIDC provider |
+| `clientSecret` | `string` | `''` (required) | OAuth 2.0 client secret |
+| `redirectUri` | `string` | `'/authorize'` | OIDC callback path. Must match the redirect URI registered with your provider. The module auto-registers this page. |
+| `scopes` | `string[]` | `[]` | OAuth scopes to request. Include `'openid'` at minimum. |
+| `usePkce` | `boolean` | `true` | Enable PKCE (S256). Strongly recommended — disabling reduces security. |
+| `codeChallengeMethod` | `string` | `'S256'` | PKCE code challenge method |
+| `autoFetchUser` | `boolean` | `true` | Fetch user info from the OIDC userinfo endpoint on GET_SESSION |
+| `autoFetchUserTtl` | `number` | `300` | Userinfo cache TTL in seconds. Prevents redundant OIDC provider calls. |
+| `fetchUserOnLogin` | `boolean` | `true` | Fetch user info immediately after the token exchange |
+| `tokenRefreshBufferMs` | `number` | `60000` | Refresh tokens this many ms before expiry |
+| `cache.prefix` | `string` | `'oidc-server-meta'` | Nitro cache key prefix for OIDC server metadata |
+| `cache.expires` | `number` | `86400` | OIDC metadata cache TTL in seconds (24 hours) |
+
+### `authts.sessions` options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `secret` | `string` | `''` | Secret for HMAC-SHA256 cookie signing and AES-256-GCM tokenSet encryption. **Must be set in production** (see [Security](#security)). Empty string disables signing and encryption. |
+| `expiresIn` | `number` | `518400` | Session lifetime in seconds (default 6 days) |
+| `names.sessionId` | `string` | `'auths.ssid'` | Session ID cookie name |
+| `names.state` | `string` | `'auths.state'` | OAuth state cookie name |
+| `names.redirectUrl` | `string` | `'auths.redirect'` | Redirect URL cookie name |
+| `names.pkce` | `string` | `'auths.pkce'` | PKCE verifier cookie name |
+| `storage.name` | `string` | `'sessions'` | Nitro storage mount name |
+| `storage.prefix` | `string` | `'session'` | Nitro storage key prefix |
+| `cookieOpts.path` | `string` | `'/'` | Cookie path |
+| `cookieOpts.sameSite` | `string` | `'lax'` | Cookie SameSite attribute |
+| `cookieOpts.httpOnly` | `boolean` | `true` | Cookie HttpOnly flag |
+| `cookieOpts.secure` | `boolean` | `true` in production | Cookie Secure flag |
+
+### `authts.auth` options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `loginUri` | `string` | `'/login'` | Path middleware redirects unauthenticated users to |
+| `defaultLoginRedirectUri` | `string` | `'/'` | Default post-login redirect when no intended destination is recorded |
+| `defaultLogoutRedirectUri` | `string` | `'/login'` | Post-logout redirect |
+| `ignoreRegexPatterns` | `RegExp[]` | `[]` | Routes matching these patterns are excluded from middleware in all environments |
+| `ignoreRegexPatternsDev` | `RegExp[]` | `[]` | Routes excluded from middleware in development only |
+
+### `logging` options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `logging.server.level` | `number` | `2` | Server log level (0=silent, 1=fatal, 2=error, 3=warn, 4=info/debug) |
+| `logging.server.tag` | `string` | `'server'` | Server log tag |
+| `logging.ssr.tag` | `string` | `'app-ssr'` | SSR log tag |
+| `logging.client.tag` | `string` | `'app-client'` | Client log tag |
+
+## Composables
+
+All composables are auto-imported. No import statement needed.
+
+### `useAuthContext(initiator?)`
+
+Reactive authentication state and actions.
+
+```ts
+const { login, logout, authorize, isAuthenticated, user, session, processing, sanitizeError } = useAuthContext()
+
+// login — redirects to the OIDC provider's authorization endpoint
+await login('/dashboard')
+
+// logout — revokes tokens and redirects to defaultLogoutRedirectUri
+await logout()
+
+// authorize — exchanges the authorization code for tokens (called on the callback page)
+await authorize(new URLSearchParams(window.location.search))
+
+// isAuthenticated — ComputedRef<boolean>, true when the user has a valid session
+console.log(isAuthenticated.value) // true | false
+
+// user — ComputedRef<AuthorizedUser>, the current authenticated user
+console.log(user.value.email)
+
+// processing — Ref<boolean>, true while an auth request is in flight
+console.log(processing.value) // true during login/logout/authorize
+
+// sanitizeError — normalizes any error to H3Error
+const h3err = sanitizeError(unknownError)
+```
+
+### `useSessionContext()`
+
+Low-level session accessor. Prefer `useAuthContext` for most use cases.
+
+```ts
+const { getValue, refetch } = useSessionContext()
+
+// getValue — returns the current NuxtSessionContext
+const session = getValue()
+
+// refetch — triggers a session re-fetch from the server
+await refetch()
+```
+
+### `useLogger(opts?)`
+
+Create a tagged logger instance.
+
+```ts
+const logger = useLogger({ tag: 'my-feature', level: 4 })
+
+logger.debug('Debug message')
+logger.warn('Warning message')
+logger.error('Error message', error)
+```
+
+Log levels: 0 silent, 1 fatal, 2 error (default), 3 warn, 4 info/debug
+
+## Server Handlers
+
+Server handlers are auto-imported into Nitro routes. No import needed.
+
+### `NuxtAuthtsHandler(options?)`
+
+Main auth handler. **Required** — create this file or auth endpoints return 404.
+
+```ts
+// server/api/_auth/[...].ts
+export default NuxtAuthtsHandler({
+  userInfo: async (user, { openidUser }) => ({
+    ...user,
+    id: openidUser?.sub ?? user.id,
+    email: openidUser?.email ?? user.email,
+    firstName: openidUser?.given_name ?? user.firstName,
+    lastName: openidUser?.family_name ?? user.lastName,
+  }),
+})
+```
+
+The `userInfo` callback maps OIDC claims to `AuthorizedUser`. It is called after the token exchange (when `fetchUserOnLogin` is true) and on every `GET_SESSION` request when `autoFetchUser` is true (results are cached for `autoFetchUserTtl` seconds).
+
+### `NuxtForwardRequestHandler(opts)`
+
+Authenticated reverse proxy — forwards requests to a backend service with the session access token attached.
+
+```ts
+// server/api/backend/[...].ts
+export default NuxtForwardRequestHandler({
+  targetBaseUrl: process.env.BACKEND_API_URL,
+  proxyPrefix: '/api/backend',
+})
+```
+
+## Route Protection
+
+The module registers a global Nuxt middleware that runs on every navigation. Control access per page with `definePageMeta`.
+
+### Require authentication
+
+```vue
+<!-- pages/dashboard.vue -->
+<script setup lang="ts">
+definePageMeta({
+  authts: { required: true },
+})
+
+const { user, isAuthenticated, logout } = useAuthContext()
+</script>
+
+<template>
+  <div>
+    <p>Welcome, {{ user.firstName }}</p>
+    <button @click="logout()">Sign out</button>
+  </div>
+</template>
+```
+
+Unauthenticated users are redirected to `auth.loginUri` (default `/login`). The intended URL is preserved as the post-login redirect.
+
+### Restrict to unauthenticated users (login page)
+
+```vue
+<!-- pages/login.vue -->
+<script setup lang="ts">
+definePageMeta({
+  authts: { unauthenticatedOnly: true },
+})
+
+const { login } = useAuthContext()
+</script>
+
+<template>
+  <button @click="login('/dashboard')">Sign in</button>
+</template>
+```
+
+Authenticated users navigating to this page receive a 404 from middleware.
+
+> **Warning:** Do not set both `required: true` and `unauthenticatedOnly: true` on the same page. This combination causes a middleware error.
+
+> **Note:** `roles` is a reserved field in `AuthtsMiddlewareMeta` and is not currently enforced.
+
+## Nuxt Hooks
+
+```ts
+// plugins/my-app.ts
+export default defineNuxtPlugin((_nuxtApp) => {
+  // Fires after every successful authorization code exchange
+  _nuxtApp.hook('user:loggedIn', async () => {
+    console.log('User logged in — session is now populated')
+  })
+
+  // Fires after successful logout
+  _nuxtApp.hook('user:loggedOut', async () => {
+    console.log('User logged out — session has been cleared')
+  })
+
+  // Trigger a session re-fetch manually (e.g. after a server-side state change)
+  // _nuxtApp.callHook('session:fetch', 'my-initiator')
+
+  // Fires after every session fetch — receives the latest session data
+  _nuxtApp.hook('session:changed', async (session) => {
+    console.log('Session updated:', session.isAuthenticated)
+  })
+})
+```
+
+## TypeScript
+
+```ts
+import type {
+  AuthorizedUser,
+  AuthtsMiddlewareMeta,
+  NuxtSessionContext,
+  SessionContext,
+} from '@devcoffee/nuxt-core'
+```
+
+### Custom session data
+
+`SessionContext` and `NuxtSessionContext` accept a generic `TData` parameter for type-safe custom session data.
+
+```ts
+import type { SessionContext } from '@devcoffee/nuxt-core'
+
+type MyAppData = {
+  preferences: { theme: string }
+  roles: string[]
+}
+
+// In a server handler or Nitro plugin:
+const session: SessionContext<MyAppData> = await getSession(sessionId, opts)
+
+// Fully typed — no casting required
+console.log(session.data.preferences.theme) // string
+console.log(session.data.roles)             // string[]
+```
+
+## Security
+
+### Production checklist
+
+**1. Set `sessions.secret` — most important step.**
+
+Without it, session ID cookies are unsigned and tokenSet storage is unencrypted. An attacker who gains read access to Nitro storage can extract access tokens.
+
+Set a 32+ character random string:
+
+```bash
+SESSION_SECRET=your-32-char-minimum-random-secret
+```
+
+When `sessions.secret` is configured:
+- **HMAC-SHA256** signs the session ID cookie — tampering is detected with constant-time comparison
+- **AES-256-GCM** encrypts the tokenSet in Nitro storage — keys are derived via HKDF-SHA256 with domain separation
+
+**2. PKCE is enabled by default** — `usePkce: true` with `S256`. Do not disable it.
+
+**3. Open redirect protection** — `isSameOrigin()` validates all post-auth redirects. External URLs are rejected with HTTP 400.
+
+**4. Session ID entropy** — `crypto.randomBytes(32)`, 256-bit. UUID v4 is not used.
+
+**5. HttpOnly cookies** — `httpOnly: true` and `secure: true` in production by default.
+
+## Changelog
+
+See [CHANGELOG.md](/CHANGELOG.md) for the full release history.
+
+## Contributing
+
+See [GUIDELINE.md](/GUIDELINE.md) for contribution guidelines, local development setup, and release instructions.
+
+<!-- Badges -->
+[npm-version-src]: https://img.shields.io/npm/v/@devcoffee/nuxt-core/latest.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-version-href]: https://npmjs.com/package/@devcoffee/nuxt-core
+
+[npm-downloads-src]: https://img.shields.io/npm/dm/@devcoffee/nuxt-core.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-downloads-href]: https://npm.chart.dev/@devcoffee/nuxt-core
+
+[license-src]: https://img.shields.io/npm/l/@devcoffee/nuxt-core.svg?style=flat&colorA=020420&colorB=00DC82
+[license-href]: https://npmjs.com/package/@devcoffee/nuxt-core
+
+[nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt.js
+[nuxt-href]: https://nuxt.com