@devcoffee/nuxt-core 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,115 @@
+# Changelog
+
+## v1.2.0
+
+[compare changes](https://github.com/coolkg1412/devcoffee-nuxt-core/compare/v1.1.1...v1.2.0)
+
+### 🚀 Enhancements
+
+- **quick-260328-uf7:** Create admin-board test fixture ([45dae18](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/45dae18))
+- **quick-260328-uf7:** Add admin-board OIDC e2e test ([20bf504](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/20bf504))
+
+### 🩹 Fixes
+
+- **types:** Explicitly type module export as NuxtModule for better type inference ([33e140e](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/33e140e))
+- **types:** Resolve TypeScript errors in middleware and plugins ([df23475](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/df23475))
+- Resolve #devcoffee-core subpath import warnings in build ([#19](https://github.com/coolkg1412/devcoffee-nuxt-core/pull/19))
+- Eliminate duplicate Redis sessions on SSR first load and refactor event.context.session ([#20](https://github.com/coolkg1412/devcoffee-nuxt-core/pull/20))
+- Rotate session on logout and remove console.log debug statement ([fbe129f](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/fbe129f))
+- Resolve autoFetchUser SSR divergence on first render ([1f15ac7](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/1f15ac7))
+- **lint:** Remove unused destructure aliases in SSR session mapping ([cfe7884](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/cfe7884))
+
+### 📖 Documentation
+
+- **quick:** Create plan for admin-board OIDC e2e test ([ce8c611](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/ce8c611))
+- **quick-260328-uf7:** Complete admin-board OIDC e2e plan ([23c0945](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/23c0945))
+
+### ✅ Tests
+
+- Update deleteSession tests to reflect renewSession LOGOUT behavior ([b444baa](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/b444baa))
+
+### ❤️ Contributors
+
+- Hieu Nguyen <hieu.nguyen@devcoffee.tech>
+- Hiếu Nguyễn ([@coolkg1412](https://github.com/coolkg1412))
+
+## v1.1.1
+
+[compare changes](https://github.com/coolkg1412/devcoffee-nuxt-core/compare/v1.0...v1.1.1)
+
+### 💅 Refactors
+
+- Sort storage adapter imports in helpers.ts; remove unused moduleText in forward handler test ([20f3496](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/20f3496))
+
+### 🏡 Chore
+
+- Complete v1.0 milestone — archive roadmap, requirements, retrospective ([2cb5067](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/2cb5067))
+- Delete REQUIREMENTS.md — archived to milestones/v1.0-REQUIREMENTS.md ([48ce751](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/48ce751))
+- Archive phase directories from v1.0 milestone ([1f3ced8](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/1f3ced8))
+
+### ❤️ Contributors
+
+- Hieu Nguyen <hieu.nguyen@devcoffee.tech>
+
+## v1.1.0
+
+[compare changes](https://github.com/coolkg1412/devcoffee-nuxt-core/compare/v1.0.2...v1.1.0)
+
+### 🚀 Enhancements
+
+- Add support for ignored authentication path regex patterns ([#5](https://github.com/coolkg1412/devcoffee-nuxt-core/pull/5))
+- **04:** Adapter foundation — http/utils/storage/oidc barrel adapters (ADPT-01–04) ([3c44a78](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/3c44a78))
+- **09:** Add E2E test coverage using Playwright ([#14](https://github.com/coolkg1412/devcoffee-nuxt-core/pull/14))
+- **docs:** Phase 10 — README.md and GUIDELINE.md for consumers and contributors ([#15](https://github.com/coolkg1412/devcoffee-nuxt-core/pull/15))
+- **11:** Distributed token refresh mutex — atomic Redis NX lock for multi-instance deployments ([f7e2d72](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/f7e2d72))
+
+### 🩹 Fixes
+
+- TypeScript ([#4](https://github.com/coolkg1412/devcoffee-nuxt-core/pull/4))
+- Update index page test to check for non-null response ([aba39bf](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/aba39bf))
+- **lint:** Auto-fix prettier formatting and replace dynamic delete in omit() ([89d987a](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/89d987a))
+- **test:** Update SEC-03 source-text assertion to match prettier-formatted multiline call ([55f92d7](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/55f92d7))
+- **types:** Resolve TypeScript strict-mode errors across app layer and server core ([b089812](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/b089812))
+- **types:** Cast cookieOpts input before omit to resolve TS key narrowing error ([93dbb50](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/93dbb50))
+- **types:** Include global.d.ts in Nitro server tsconfig to resolve DeepPartial on server layer ([24700e2](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/24700e2))
+
+### 💅 Refactors
+
+- Flatten utils paths (utils/utils.ts → utils.ts) ([45d8997](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/45d8997))
+- **test:** Migrate test imports to @/ alias and fix tsconfig/vitest paths ([1f73e73](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/1f73e73))
+- **utils:** Consolidate utility exports and fix module import paths ([d9e2fdc](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/d9e2fdc))
+- **module:** Remove redundant typescript tsConfig includes covered by prepare:types hook ([9ced2c5](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/9ced2c5))
+
+### 📖 Documentation
+
+- **10:** Research phase for README.md and GUIDELINE.md documentation ([31d5ab0](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/31d5ab0))
+- Resolve debug eslint-ts-type-errors ([0653761](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/0653761))
+- Update debug knowledge base with eslint-ts-type-errors ([2dc0cc1](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/2dc0cc1))
+
+### 🏡 Chore
+
+- Authorize for devecoffee ([#2](https://github.com/coolkg1412/devcoffee-nuxt-core/pull/2))
+- The base UI and common Components ([#3](https://github.com/coolkg1412/devcoffee-nuxt-core/pull/3))
+- Update docs ([b708e93](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/b708e93))
+- Suppress DEP0155 deprecation warning in test scripts ([6fdb696](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/6fdb696))
+- **test:** Split test scripts and enable headed E2E mode ([207c3d5](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/207c3d5))
+- Bump `compatibilityDate` ([2654eb2](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/2654eb2))
+
+### ✅ Tests
+
+- **api:** Mark BUG-03 deprecation tests as todo until implemented ([69cd623](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/69cd623))
+- Update import aliases and trim stale todo tests for BUG-03 ([f7c5cff](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/f7c5cff))
+
+### ❤️ Contributors
+
+- Hieu Nguyen <hieu.nguyen@devcoffee.tech>
+- Hiếu Nguyễn ([@coolkg1412](https://github.com/coolkg1412))
+
+## v1.0.2
+
+[compare changes](https://github.com/coolkg1412/devcoffee-nuxt-core/compare/v1.0.1...v1.0.2)
+
+## v1.0.1
+
+[compare changes](https://github.com/coolkg1412/devcoffee-nuxt-core/compare/v1.0.0...v1.0.1)
+

package/GUIDELINE.md

@@ -0,0 +1,351 @@
+# @devcoffee/nuxt-core — Contributor Guide
+
+This guide is for developers working on the module itself. If you are integrating the module into your app, see [README.md](./README.md).
+
+## Quick Reference
+
+| Topic | Section |
+|---|---|
+| Module layers and responsibilities | [Architecture](#architecture) |
+| Annotated file tree | [Directory Reference](#directory-reference) |
+| First-time setup | [Development Setup](#development-setup) |
+| Test commands | [Test Infrastructure](#test-infrastructure) |
+| Adding external dependencies | [Adapter Pattern](#adapter-pattern) |
+| Per-request auth flow | [Request Lifecycle](#request-lifecycle) |
+| Guarded design choices | [Key Architectural Decisions](#key-architectural-decisions) |
+| Publishing a new version | [Release Pipeline](#release-pipeline) |
+| Planning workflow | [GSD Workflow](#gsd-workflow) |
+| Style and naming rules | [Coding Conventions](#coding-conventions) |
+
+## Architecture
+
+The module is organized into five layers. Each layer has a single responsibility and strict import rules.
+
+### Layer 1: Module Definition (`src/module.ts`)
+
+Entry point. Configures and registers all runtime components into Nuxt and Nitro during build:
+
+- Registers server plugins, server composables, and server handler imports via `@nuxt/kit`
+- Registers app plugins, app composables, and route middleware
+- Injects runtime configuration from `nuxtCore` options
+- Sets up Nitro storage and DevTools routes
+
+### Layer 2: Server / Nitro (`src/runtime/server/`)
+
+All server-side auth logic. Runs in the Nitro runtime (not the browser):
+
+- `plugins/authts.ts` — global Nitro plugin; validates and refreshes sessions on every HTTP request
+- `core/helpers.ts` — PKCE, state, token exchange, session CRUD, token refresh mutex
+- `core/nuxtAuthtsHandler.ts` — `NuxtAuthtsHandler` export; handles GET_SESSION, TOKEN, LOGOUT, AUTHORIZE_URL actions
+- `core/nuxtForwardHandler.ts` — `NuxtForwardRequestHandler` export; authenticated API proxy
+- `adapters/` — external dependency wrappers (see [Adapter Pattern](#adapter-pattern))
+- `composables/useServerLogger.ts` — server-side logging composable
+
+### Layer 3: Client / App (`src/runtime/app/`)
+
+Client-side auth state, UI interactions, and route protection. Runs in Vue/Nuxt:
+
+- `plugins/authts.ts` — app plugin; initializes session state, provides `$sessionContext`, `$sessionReady`, fires hooks
+- `middleware/authts.ts` — global route middleware; enforces `definePageMeta` auth requirements
+- `composables/useAuthContext.ts` — reactive auth state and actions
+- `composables/useSessionContext.ts` — low-level session accessor
+- `composables/useLogger.ts` — client-side logging composable
+- `pages/authorize.vue` — OIDC callback page (auto-registered at `openid.redirectUri`)
+
+### Layer 4: Types (`src/types/`)
+
+All TypeScript interfaces and augmentations:
+
+- `types/authts.d.ts` — auth types (`SessionContext`, `AuthorizedUser`, `ModuleOptions`, etc.)
+- `types/logging.d.ts` — logging types
+- `types/index.d.ts` — central re-export point; consumers import from `@devcoffee/nuxt-core`
+
+### Layer 5: Module Helpers (`src/helpers.ts`)
+
+Option normalization and public config sanitization:
+
+- `normalizedModuleOptions()` — merges user config with defaults
+- `normalizePublicRuntimeConfig()` — strips private fields before injecting into runtime config
+
+## Directory Reference
+
+```
+src/
+├── module.ts              # Layer 1: Module Definition
+├── helpers.ts             # Layer 5: Option normalization + defaults
+├── utils.ts               # Utility relay (re-exports from runtime/utils)
+├── types/
+│   ├── index.d.ts         # Central type re-export for consumers
+│   ├── authts.d.ts        # Auth types (SessionContext, AuthorizedUser, etc.)
+│   └── logging.d.ts       # Logging types
+└── runtime/
+    ├── server/            # Layer 2: Server / Nitro
+    │   ├── adapters/      # External dependency wrappers
+    │   │   ├── http.ts    # h3 cookie, request, response, error functions
+    │   │   ├── oidc.ts    # openid-client wrappers with module-owned types
+    │   │   ├── storage.ts # Nitro useStorage session CRUD
+    │   │   └── utils.ts   # deepMerge, omit, pick (native, no lodash)
+    │   ├── core/          # Business logic — imports ONLY from adapters/
+    │   │   ├── helpers.ts
+    │   │   ├── nuxtAuthtsHandler.ts
+    │   │   └── nuxtForwardHandler.ts
+    │   ├── composables/
+    │   │   └── useServerLogger.ts
+    │   ├── plugins/
+    │   │   └── authts.ts  # Per-request session validation entry point
+    │   └── dev/           # DevTools route handler
+    └── app/               # Layer 3: Client / App
+        ├── composables/
+        │   ├── useAuthContext.ts
+        │   ├── useSessionContext.ts
+        │   └── useLogger.ts
+        ├── middleware/
+        │   └── authts.ts  # Global route protection middleware
+        ├── pages/
+        │   └── authorize.vue  # OIDC callback page (auto-registered)
+        ├── plugins/
+        │   ├── authts.ts      # Session init, hooks, $sessionReady
+        │   ├── logging.ts
+        │   ├── formatters.ts
+        │   └── locale.ts
+        └── utils/
+            └── utils.ts       # Utility relay
+
+test/
+├── unit/          # Vitest unit tests
+└── e2e/           # Playwright + Vitest E2E tests
+    ├── fixture/   # Nuxt test app with mock OIDC server
+    └── *.test.ts
+```
+
+## Development Setup
+
+### Prerequisites
+
+- Node.js LTS (18+)
+- npm 10+
+- A `.certs/devcoffee.ca.pem` file — required for TLS in development (internal CA). Place the DevCoffee CA certificate at this path.
+
+### First-time setup
+
+```bash
+# 1. Clone and install
+git clone <repo-url>
+cd devcoffee-nuxt-core
+npm install
+
+# 2. Generate type stubs (required before dev or test)
+npm run dev:prepare
+
+# 3. Start the playground dev server
+npm run dev
+```
+
+The playground runs at `http://localhost:3000`. The custom CA certificate is injected via `NODE_EXTRA_CA_CERTS` in the `dev` script.
+
+### Clean rebuild
+
+```bash
+npm run cleanup    # Remove .nuxt and playground build artifacts
+npm run dev:prepare
+npm run dev
+```
+
+## Test Infrastructure
+
+| Command | What it runs | When to use |
+|---|---|---|
+| `npm run test` | Vitest unit suite (once) | Before committing |
+| `npm run test:watch` | Vitest unit suite (watch mode) | During development |
+| `npm run test:types` | `vue-tsc --noEmit` type check | Before committing |
+| `npm run test:e2e` | Playwright + Vitest E2E tests (headless) | After changing auth flow, middleware, or session handling |
+| `npm run test:e2e:ui` | E2E tests in headed Chromium (via `PLAYWRIGHT_HEADLESS=false`) | Debugging browser-mode E2E failures |
+| `npm run test:all` | All unit + E2E tests combined | Before opening a PR or releasing |
+
+### Unit tests (`test/unit/`)
+
+Written with Vitest. Use `@nuxt/test-utils` for composable and middleware tests. Mock Nitro virtual modules where needed (e.g., `vi.mock('nitropack/runtime')`).
+
+Tests follow source-text assertions for structural code presence and behavior assertions for logic. TDD was used for SEC-*, PERF-*, MDLW-*, and SSR-* requirements — new security or behavior requirements should follow the same pattern.
+
+### E2E tests (`test/e2e/`)
+
+Run in Vitest but use `@playwright/test` for browser automation and `createNuxtDevServer` from `@nuxt/test-utils` to spin up the fixture Nuxt app. A mock OIDC server is embedded as a Nitro route handler in the fixture.
+
+Key files:
+
+- `test/e2e/fixture/` — test Nuxt app (standalone, not the playground)
+- `test/e2e/fixture/server/routes/` — mock OIDC discovery, token, and userinfo endpoints
+- `test/e2e/middleware.test.ts` — E2E-01 (required redirect) and E2E-02 (unauthenticatedOnly)
+- `test/e2e/session.test.ts` — E2E-03 (session creation) and E2E-07 (token refresh)
+- `test/e2e/auth-flow.test.ts` — E2E-04 (valid TOKEN flow), E2E-05 (invalid state), E2E-06 (LOGOUT)
+- `test/e2e/auth-flow-browser.test.ts` — E2E-08 (browser-mode Chromium tests)
+
+**Important:** Browser tests (`auth-flow-browser.test.ts`) are isolated in their own file to prevent `EADDRINUSE` port conflicts when two Nuxt dev servers start in the same process.
+
+## Adapter Pattern
+
+### Why adapters exist
+
+Business logic in `src/runtime/server/core/` must not import directly from `h3`, `openid-client`, or any external npm package. Instead, all external calls go through adapter barrel files in `src/runtime/server/adapters/`.
+
+**Rationale:** Adapters create a stable internal boundary. If `h3` or `openid-client` upgrades break their API, only the adapter needs to change — not every call site in the business logic. Adapters also own the type bridge between external library types and module-owned types (e.g., `OidcUserInfo`).
+
+This rule is enforced by grep assertions in the test suite:
+
+```bash
+# These must return zero matches:
+grep -r "from 'h3'" src/runtime/server/core/
+grep -r "from 'openid-client'" src/runtime/server/core/
+```
+
+### How to add a new external dependency
+
+1. Install the package as a dependency
+2. Create (or update) the appropriate adapter file in `src/runtime/server/adapters/`
+3. Write module-owned types for any types the adapter exposes
+4. Export only what business logic needs — keep the adapter surface minimal
+5. Import from the adapter in `core/` files, never directly from the package
+
+Example: adding a hypothetical `jose` utility to the http adapter:
+
+```typescript
+// src/runtime/server/adapters/http.ts
+import { decodeJwt as _decodeJwt } from 'jose'
+import type { JWTPayload } from './types' // module-owned type, not jose's type
+
+export function decodeJwt(token: string): JWTPayload {
+  return _decodeJwt(token) as JWTPayload
+}
+```
+
+## Request Lifecycle
+
+Every HTTP request to the Nuxt app passes through this sequence:
+
+```
+HTTP request
+    │
+    ▼
+Nitro server plugin (src/runtime/server/plugins/authts.ts)
+    │  Reads session cookie → validateSession()
+    │  If authenticated + near-expiry → refreshTokenIfNeeded() [mutex-protected per session]
+    │  Sets event.context.sessionId
+    │
+    ▼
+Route handler (src/runtime/server/core/nuxtAuthtsHandler.ts)
+    │  Reads action from URL path: GET_SESSION | TOKEN | LOGOUT | AUTHORIZE_URL
+    │  Calls getSession(event.context.sessionId) → reads + decrypts session from storage
+    │  Dispatches to action handler
+    │
+    ▼
+Client (src/runtime/app/plugins/authts.ts)
+    │  useAsyncData('authts:session') fetches /api/_auth/session on SSR
+    │  Sets $sessionReady promise — resolved before route middleware runs
+    │
+    ▼
+Route middleware (src/runtime/app/middleware/authts.ts)
+    │  Awaits $sessionReady
+    │  Reads definePageMeta({ authts: { required, unauthenticatedOnly } })
+    │  Redirects or aborts navigation based on auth state
+```
+
+### Authorization code flow (login)
+
+```
+User clicks login
+    │
+    ▼
+useAuthContext.login(redirectTo)
+    │  GET /api/_auth/authorize-url → returns OIDC authorization URL
+    │  Stores redirectTo in session cookie (auths.redirect)
+    │
+    ▼
+Browser redirects to OIDC provider
+    │
+    ▼
+Provider redirects to /authorize?code=...&state=...
+    │
+    ▼
+authorize.vue (auto-registered OIDC callback page)
+    │  useAuthContext.authorize(code, state)
+    │  POST /api/_auth/token → validates state, exchanges code for tokens
+    │  If autoFetchUser: fetches userinfo from provider
+    │  Stores session in Nitro storage (tokenSet encrypted if secret is set)
+    │  Fires user:loggedIn hook
+    │
+    ▼
+Browser redirects to intended destination
+```
+
+## Key Architectural Decisions
+
+These decisions are enforced by tests or type constraints. Changing them requires updating the tests that guard them.
+
+| Decision | What it means |
+|---|---|
+| `sessions.secret` empty = no signing | Backward compatible — existing deployments without a secret continue working. Insecure for new deployments. |
+| HKDF-SHA256 derives AES key from `sessions.secret` | Domain-separated with `'devcoffee-authts-tokenset-v1'` info string |
+| Cookie names are `auths.ssid`, `auths.state`, `auths.pkce`, `auths.redirect` | Configured in `sessions.names` defaults in `src/helpers.ts` |
+| `deleteSession()` is separate from `renewSession()` | Logout deletes the session and does not create a replacement. Prevents zombie sessions. |
+| Token refresh mutex per session | Lock is placed inside `accessExpired && refreshToken` branch only — no storage overhead for non-expiring tokens |
+| Adapter import enforcement | Verified by grep in test suite. Zero direct `h3` or `openid-client` imports allowed in `core/`. |
+| `usePkce: false` in E2E fixture | PKCE threading through test requires additional cookie management. PKCE is fully covered at the unit layer. |
+
+Full decision log: see `## Decisions` in `.planning/STATE.md`.
+
+## Release Pipeline
+
+```bash
+npm run release
+```
+
+This runs in sequence: `lint` → `test:all` → `prepack` → `changelogen` → `npm publish` → `git push --follow-tags`.
+
+Individual steps:
+
+```bash
+npm run lint          # ESLint check (with --fix)
+npm run test          # Vitest unit suite
+npm run test:types    # vue-tsc type check
+npm run test:all      # All unit + E2E tests combined
+npm run prepack       # Build module dist (ES module + .d.ts types via @nuxt/module-builder)
+npm run release       # Full pipeline (lint + test:all + prepack + changelogen + publish + push)
+```
+
+The published package is `@devcoffee/nuxt-core`. The `dist/` directory is generated by `@nuxt/module-builder` and is what consumers install.
+
+## GSD Workflow
+
+This project uses a phase-based planning system. All code changes must go through a GSD command to keep planning artifacts in sync.
+
+| Task type | Entry point |
+|---|---|
+| Small fix or ad-hoc change | `/gsd:quick` |
+| Bug investigation | `/gsd:debug` |
+| Planned phase work | `/gsd:execute-phase` |
+
+Planning artifacts live in `.planning/`:
+
+- `ROADMAP.md` — all phases and their requirements
+- `STATE.md` — current position, accumulated decisions, blockers
+- `phases/NN-slug/` — per-phase RESEARCH.md, PLAN.md files, SUMMARY.md files
+
+Do not make direct file edits outside a GSD workflow unless explicitly bypassing it.
+
+## Coding Conventions
+
+Key rules (full reference: `CLAUDE.md`):
+
+- **No semicolons** — Prettier enforces this
+- **Single quotes** for strings
+- **2-space indent**, 120-char line length
+- **Trailing commas:** es5 style (objects and arrays, not function parameters)
+- **TypeScript strict** — no `any` in public API surface
+- **Composables:** `use[Name].ts` file and function name
+- **Server handlers:** `Nuxt[Name]Handler` (PascalCase with `Nuxt` prefix)
+- **Getters:** `get[Name]`, **Setters:** `set[Name]`, **Validators:** `validate[Name]`
+- **Logging:** Use `useLogger` on client, `useServerLogger` on server. Always include `tag` and `level`.
+- **Error handling:** `createError()` from h3 for server errors, `abortNavigation(createError())` for middleware
+- **Imports:** Prefer named imports. Use `#imports` for Nuxt auto-imports.
+- **JSDoc:** All public functions and composables must have JSDoc with `@param`, `@returns`, `@example`, `@since 1.0.0`

package/README.md

@@ -252,8 +252,6 @@ export default NuxtForwardRequestHandler({
 })
 ```
 
-> **Note:** `NuxtForwardRequestHandller` (double-l) is a deprecated alias kept for backward compatibility. Use `NuxtForwardRequestHandler` in new code.
-
 ## Route Protection
 
 The module registers a global Nuxt middleware that runs on every navigation. Control access per page with `definePageMeta`.

package/dist/module.d.mts

@@ -1,6 +1,7 @@
-import { CookieSerializeOptions } from '#devcoffee-core/runtime/server/adapters/http';
-import { OidcUserInfo } from '#devcoffee-core/runtime/server/adapters/oidc';
-import { ConsolaInstance, LogLevel as LogLevel$1, ConsolaOptions } from 'consola';
+import { NuxtModule } from '@nuxt/schema';
+import { CookieSerializeOptions } from '../dist/runtime/server/adapters/http.js';
+import { OidcUserInfo } from '../dist/runtime/server/adapters/oidc.js';
+import { LogLevel as LogLevel$1, ConsolaOptions, ConsolaInstance } from 'consola';
 
 interface AuthorizedUser {
   id: string
@@ -294,7 +295,7 @@ type ModulePublicRuntimeConfig = Pick<ModuleOptions, 'defaultLocale' | 'defaultT
 
 type InputModuleOptions = DeepPartial<ModuleOptions>
 
-declare const _default: any;
+declare const _module: NuxtModule<InputModuleOptions>;
 
-export { _default as default };
+export { _module as default };
 export type { AuthData, AuthorizedUser, AuthtsMiddlewareMeta, AuthtsModuleOptions, CoreLogInstance, CoreLogLevel, InputModuleOptions, LoggingModuleOptions, LoggingOptions, ModuleOptions, ModulePublicRuntimeConfig, NuxtAuthOptions, NuxtCoreLogging, NuxtSessionContext, NuxtSessionUpdateContext, SessionContext };

package/dist/module.d.ts

@@ -1,6 +1,7 @@
-import { CookieSerializeOptions } from '#devcoffee-core/runtime/server/adapters/http';
-import { OidcUserInfo } from '#devcoffee-core/runtime/server/adapters/oidc';
-import { ConsolaInstance, LogLevel as LogLevel$1, ConsolaOptions } from 'consola';
+import { NuxtModule } from '@nuxt/schema';
+import { CookieSerializeOptions } from '../dist/runtime/server/adapters/http.js';
+import { OidcUserInfo } from '../dist/runtime/server/adapters/oidc.js';
+import { LogLevel as LogLevel$1, ConsolaOptions, ConsolaInstance } from 'consola';
 
 interface AuthorizedUser {
   id: string
@@ -294,7 +295,7 @@ type ModulePublicRuntimeConfig = Pick<ModuleOptions, 'defaultLocale' | 'defaultT
 
 type InputModuleOptions = DeepPartial<ModuleOptions>
 
-declare const _default: any;
+declare const _module: NuxtModule<InputModuleOptions>;
 
-export { _default as default };
+export { _module as default };
 export type { AuthData, AuthorizedUser, AuthtsMiddlewareMeta, AuthtsModuleOptions, CoreLogInstance, CoreLogLevel, InputModuleOptions, LoggingModuleOptions, LoggingOptions, ModuleOptions, ModulePublicRuntimeConfig, NuxtAuthOptions, NuxtCoreLogging, NuxtSessionContext, NuxtSessionUpdateContext, SessionContext };

package/dist/module.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-core",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "configKey": "nuxtCore",
   "compatibility": {
     "nuxt": "^4.0.0"

package/dist/module.mjs

@@ -2,7 +2,7 @@ import { addCustomTab } from '@nuxt/devtools-kit';
 import { defineNuxtModule, useLogger, createResolver, addServerImports, addServerImportsDir, addServerPlugin, addImportsDir, addPlugin, addRouteMiddleware, addTemplate, addServerHandler } from '@nuxt/kit';
 import { deepMerge, pick } from '../dist/runtime/utils.js';
 
-const version = "1.1.0";
+const version = "1.2.0";
 
 const defaultLocale = "vi-VN";
 const defaultLanguage = "vi";
@@ -113,7 +113,7 @@ function normalizePublicRuntimeConfig(inputOpts) {
 
 const moduleName = "nuxt-core";
 const configKey = "nuxtCore";
-const module = defineNuxtModule({
+const _module = defineNuxtModule({
   meta: {
     name: moduleName,
     version,
@@ -228,4 +228,4 @@ const module = defineNuxtModule({
   }
 });
 
-export { module as default };
+export { _module as default };

package/dist/runtime/app/composables/useAuthContext.js

@@ -1,4 +1,4 @@
-import { useRequestURL } from "#app";
+import { useRequestEvent, useRequestURL, useRuntimeConfig } from "#app";
 import {
   computed,
   createError,
@@ -9,6 +9,7 @@ import {
   useRequestFetch,
   useSessionContext
 } from "#imports";
+import { deleteCookie, setCookie } from "h3";
 export function useAuthContext(initiator) {
   const { callHook, runWithContext } = useNuxtApp();
   const { getValue } = useSessionContext();
@@ -58,7 +59,15 @@ export function useAuthContext(initiator) {
         processing.value = true;
       }
     }).then(
-      async ({ redirectUrl }) => runWithContext(async () => await navigateTo(redirectUrl, { external: true, replace: true }))
+      async ({ redirectUrl, cookies }) => runWithContext(async () => {
+        if (import.meta.server) {
+          const event = useRequestEvent();
+          if (event) {
+            cookies.forEach(([n, v, o]) => setCookie(event, n, v, o));
+          }
+        }
+        return await navigateTo(redirectUrl, { external: true, replace: true });
+      })
     ).catch((ex) => {
       logger.log(`[login] failed error:${ex}`, ex);
       throw sanitizeError(ex);
@@ -76,7 +85,18 @@ export function useAuthContext(initiator) {
       await runWithContext(async () => await callHook("user:loggedIn"));
       return response;
     }).then(
-      async ({ redirectUrl }) => runWithContext(async () => await navigateTo(redirectUrl))
+      async ({ redirectUrl }) => runWithContext(async () => {
+        if (import.meta.server) {
+          const event = useRequestEvent();
+          if (event) {
+            const { cookieOpts, names: cookienames } = useRuntimeConfig(event).nuxtCore.authts.sessions;
+            Array.of(cookienames.state, cookienames.pkce, cookienames.redirectUrl).forEach(
+              (cookie) => deleteCookie(event, cookie, cookieOpts)
+            );
+          }
+        }
+        return await navigateTo(redirectUrl);
+      })
     ).catch((ex) => {
       logger.log(`[authorize] failed error:${ex}`, ex);
       throw sanitizeError(ex);
@@ -90,7 +110,16 @@ export function useAuthContext(initiator) {
         processing.value = true;
       }
     }).then(async (response) => {
-      await runWithContext(async () => await callHook("user:loggedOut"));
+      await runWithContext(async () => {
+        if (import.meta.server) {
+          const event = useRequestEvent();
+          if (event) {
+            const { cookieOpts, names: cookienames } = useRuntimeConfig(event).nuxtCore.authts.sessions;
+            deleteCookie(event, cookienames.sessionId, cookieOpts);
+          }
+        }
+        return await callHook("user:loggedOut");
+      });
       return response;
     }).then(
       async ({ redirectUrl }) => runWithContext(async () => await navigateTo(redirectUrl))

package/dist/runtime/app/middleware/authts.js

@@ -3,7 +3,6 @@ import {
   createError,
   defineNuxtRouteMiddleware,
   navigateTo,
-  refreshNuxtData,
   useCookie,
   useNuxtApp,
   useRequestEvent,
@@ -68,7 +67,7 @@ export default defineNuxtRouteMiddleware(async (to) => {
     logger.debug(`Bypassing auth checks for ignored path: ${normalizedPath}`);
     return;
   }
-  if (import.meta.env.DEV && ignoreRegexPatternsDev.length && ignoreRegexPatternsDev.some((pattern) => pattern.test(normalizedPath))) {
+  if (import.meta.dev && ignoreRegexPatternsDev.length && ignoreRegexPatternsDev.some((pattern) => pattern.test(normalizedPath))) {
     logger.debug(`Bypassing auth checks for ignored path (dev): ${normalizedPath}`);
     return;
   }
@@ -83,7 +82,7 @@ export default defineNuxtRouteMiddleware(async (to) => {
     );
   }
   if (import.meta.client) {
-    await refreshNuxtData("authts:session");
+    await nuxtApp.$sessionContext.refetch();
   }
   const { isAuthenticated } = useAuthContext("core.app.authts.middleware");
   const loginPath = loginUri.toLowerCase();

package/dist/runtime/app/plugins/authts.js

@@ -2,10 +2,10 @@ import { watch } from "vue";
 import {
   createError,
   defineNuxtPlugin,
-  refreshNuxtData,
   useAsyncData,
   useCookie,
   useNuxtApp,
+  useRequestEvent,
   useRequestFetch,
   useRuntimeConfig,
   useState
@@ -21,8 +21,25 @@ export default defineNuxtPlugin(async (_nuxtApp) => {
     }
   );
   async function __getServerSession(initiator) {
+    logger.debug(`[__getServerSession] Called with initiator: '${initiator}'`);
+    if (import.meta.server) {
+      const event = useRequestEvent();
+      const session = event?.context?.session ?? null;
+      if (!session) {
+        throw createError({
+          status: 500,
+          fatal: true,
+          statusMessage: "Failed to fetch session",
+          message: "Server session not found on event context"
+        });
+      }
+      const { auth, ...rest } = session;
+      return {
+        ...rest,
+        isAuthenticated: auth?.status === "authenticated" && Boolean(auth?.tokenSet && session.user?.id)
+      };
+    }
     try {
-      logger.debug(`[__getServerSession] Called with initiator: '${initiator}'`);
       return await fetchRequest("/api/_auth/session");
     } catch (ex) {
       throw createError({
@@ -41,36 +58,17 @@ export default defineNuxtPlugin(async (_nuxtApp) => {
   _nuxtApp.provide("sessionReady", sessionReady);
   const sessionId = useCookie(useRuntimeConfig().public.nuxtCore.authts.sessionCookie);
   logger.debug(`Initial session fetch on plugin init with sessionId: ${sessionId.value}`);
-  if (sessionId.value) {
-    const { data } = await useAsyncData("authts:session", () => __getServerSession("plugin initialization"));
-    if (data.value) {
-      context.value = data.value;
-    }
-    watch(data, (newData) => {
+  const { data, refresh } = await useAsyncData("authts:session", () => __getServerSession("plugin initialization"));
+  watch(
+    data,
+    (newData) => {
       if (newData) context.value = newData;
-    });
-  } else {
-    context.value = {
-      id: "",
-      isAuthenticated: false,
-      user: {
-        id: "",
-        sub: "",
-        email: "",
-        firstName: "Anonymous",
-        lastName: "User",
-        locale: "",
-        language: "",
-        timezone: ""
-      },
-      data: {}
-    };
-  }
-  resolveReady();
+    },
+    { immediate: true }
+  );
   _nuxtApp.hooks.addHooks({
-    // session:fetch calls refreshNuxtData to stay coherent with useAsyncData cache (D-04)
     "session:fetch": async (_initiator) => {
-      await refreshNuxtData("authts:session");
+      await refresh({ dedupe: "cancel" });
     },
     "user:loggedIn": async () => {
       await _nuxtApp.callHook("session:fetch", "user:loggedIn");
@@ -88,4 +86,5 @@ export default defineNuxtPlugin(async (_nuxtApp) => {
     await _nuxtApp.callHook("session:fetch");
   }
   _nuxtApp.provide("sessionContext", { getValue, refetch });
+  resolveReady();
 });

package/dist/runtime/server/adapters/http.d.ts

@@ -1,5 +1,5 @@
 export { createError, deleteCookie, eventHandler, getCookie, getQuery, getRequestHeaders, getRequestURL, proxyRequest, readBody, readFormData, sendNoContent, setCookie, } from 'h3';
 export type { EventHandlerRequest, H3Error, H3Event, ProxyOptions, RequestHeaders } from 'h3';
 export { defineNitroPlugin, useRuntimeConfig } from 'nitropack/runtime';
-export type { CoreLogLevel, NuxtAuthOptions } from 'nitropack/runtime';
+export type { CoreLogLevel, NuxtAuthOptions } from '@devcoffee/nuxt-core';
 export type { CookieSerializeOptions } from 'cookie-es';

package/dist/runtime/server/core/helpers.d.ts

@@ -10,8 +10,8 @@ type SessionCreateOptions = {
 /**
  * Check whether a candidate redirect URL is same-origin with the request URL.
  *
- * Uses the WHATWG URL constructor — malformed URLs and relative paths return false
- * instead of throwing, guarding against attacker-controlled input.
+ * Uses the WHATWG URL constructor — relative paths are considered same-origin.
+ * Malformed URLs return false, guarding against attacker-controlled input.
  *
  * @param redirectUrl - The candidate redirect URL string (from query param or cookie).
  * @param requestUrl - The trusted request URL from the h3 event.

package/dist/runtime/server/core/helpers.js

@@ -12,10 +12,16 @@ import {
   refreshTokenGrant as refreshTokenGrantFromOidc,
   revokeToken
 } from "#devcoffee-core/server/adapters/oidc";
+import {
+  getSessionData,
+  hasSessionData,
+  removeSessionData,
+  setSessionData
+} from "#devcoffee-core/server/adapters/storage";
 import { deepMerge, omit } from "#devcoffee-core/server/adapters/utils";
 import useServerLogger from "#devcoffee-core/server/composables/useServerLogger";
 import { useRuntimeConfig } from "#imports";
-import { useStorage } from "nitropack/runtime/internal/storage";
+import { useStorage } from "nitropack/runtime";
 import { decryptTokenSet, encryptTokenSet, generateSessionId, isValidSessionId, verifySessionId } from "./crypto.js";
 import { tryAcquireLock } from "./mutex.js";
 function getAnonymousUser(extras) {
@@ -41,17 +47,19 @@ function getSessionStorageKey(storagePrefix, sessionId) {
   return storagePrefix ? `${storagePrefix}:${sessionId}` : sessionId;
 }
 export function isSameOrigin(redirectUrl, requestUrl) {
+  if (redirectUrl.includes(" ")) {
+    return false;
+  }
   try {
-    return new URL(redirectUrl).origin === requestUrl.origin;
+    return new URL(redirectUrl, requestUrl.href).origin === requestUrl.origin;
   } catch {
     return false;
   }
 }
 export async function getSession(sessionId, opts) {
-  const storage = useStorage(opts.storageName);
   const sessingKey = getSessionStorageKey(opts.storagePrefix, sessionId);
-  if (!await storage.hasItem(sessingKey)) return null;
-  const session = await storage.getItem(sessingKey);
+  if (!await hasSessionData(opts.storageName, sessingKey)) return null;
+  const session = await getSessionData(opts.storageName, sessingKey);
   if (!session) return null;
   if (session.auth?.tokenSet && session.auth.tokenSet.encrypted === true) {
     if (opts.secret) {
@@ -78,7 +86,6 @@ function newSession(sessionId, expiresAt) {
   };
 }
 export async function validateSession(sessionCookieId, opts) {
-  const storage = useStorage(opts.storageName);
   const now = Date.now();
   const expiresAt = now + opts.expiresIn;
   let sessionId = void 0;
@@ -91,8 +98,8 @@ export async function validateSession(sessionCookieId, opts) {
   }
   if (sessionId) {
     sessionKey = getSessionStorageKey(opts.storagePrefix, sessionId);
-    if (await storage.hasItem(sessionKey)) {
-      session = await storage.getItem(sessionKey);
+    if (await hasSessionData(opts.storageName, sessionKey)) {
+      session = await getSessionData(opts.storageName, sessionKey);
     }
     if (!session || session.expiresAt <= now) {
       deleteSessionKey = session ? sessionKey : void 0;
@@ -105,22 +112,19 @@ export async function validateSession(sessionCookieId, opts) {
   session = session || newSession(generateSessionId(), expiresAt);
   sessionKey = sessionKey || getSessionStorageKey(opts.storagePrefix, session.id);
   if (deleteSessionKey && deleteSessionKey !== sessionKey) {
-    await storage.removeItem(deleteSessionKey);
+    await removeSessionData(opts.storageName, deleteSessionKey);
   }
-  await storage.setItem(sessionKey, session, {
-    ttl: opts.expiresIn / 1e3 | 0
-  });
+  await setSessionData(opts.storageName, sessionKey, session, opts.expiresIn / 1e3 | 0);
   return session;
 }
 export async function updateSession(sessionId, input, opts) {
   const now = Date.now();
-  const storage = useStorage(opts.storageName);
   const serverKey = `${opts.storagePrefix}:${sessionId}`;
   const normalizedInput = omit(
     input,
     ["id", "issuedAt", "expiresAt"]
   );
-  let session = await storage.getItem(serverKey);
+  let session = await getSessionData(opts.storageName, serverKey);
   if (!session) {
     throw createError({
       status: 500,
@@ -140,29 +144,23 @@ export async function updateSession(sessionId, input, opts) {
       )
     };
   }
-  await storage.setItem(serverKey, sessionToStore, {
-    ttl: opts.expiresIn / 1e3 | 0
-  });
+  await setSessionData(opts.storageName, serverKey, sessionToStore, opts.expiresIn / 1e3 | 0);
   return session;
 }
 export async function renewSession(sessionId, opts) {
-  const storage = useStorage(opts.storageName);
   let sessionKey = getSessionStorageKey(opts.storagePrefix, sessionId);
-  if (await storage.hasItem(sessionKey)) {
-    await storage.removeItem(sessionKey);
+  if (await hasSessionData(opts.storageName, sessionKey)) {
+    await removeSessionData(opts.storageName, sessionKey);
   }
   const session = newSession(generateSessionId(), Date.now() + opts.expiresIn);
   sessionKey = getSessionStorageKey(opts.storagePrefix, session.id);
-  await storage.setItem(sessionKey, session, {
-    ttl: opts.expiresIn / 1e3 | 0
-  });
+  await setSessionData(opts.storageName, sessionKey, session, opts.expiresIn / 1e3 | 0);
   return session;
 }
 export async function deleteSession(sessionId, opts) {
-  const storage = useStorage(opts.storageName);
   const sessionKey = getSessionStorageKey(opts.storagePrefix, sessionId);
-  if (await storage.hasItem(sessionKey)) {
-    await storage.removeItem(sessionKey);
+  if (await hasSessionData(opts.storageName, sessionKey)) {
+    await removeSessionData(opts.storageName, sessionKey);
   }
 }
 export async function discoveryOpendId(wellKnownUrl, opts) {

package/dist/runtime/server/core/mutex.js

@@ -1,5 +1,5 @@
 import useServerLogger from "#devcoffee-core/server/composables/useServerLogger";
-import { useStorage } from "nitropack/runtime/internal/storage";
+import { useStorage } from "nitropack/runtime";
 const logger = useServerLogger({ tag: "authts-mutex", level: 3 });
 export async function tryAcquireLock(storage, lockKey, ttlSeconds, useAtomic) {
   if (useAtomic) {

package/dist/runtime/server/core/nuxtAuthtsHandler.d.ts

@@ -1,4 +1,10 @@
 import type { NuxtAuthOptions } from '#devcoffee-core/server/adapters/http';
+declare module 'nitropack' {
+    interface NitroApp {
+        /** Registered userInfo callback from NuxtAuthtsHandler — used by server plugin for SSR autoFetchUser enrichment. */
+        _sessionUserInfo?: NuxtAuthOptions['userInfo'];
+    }
+}
 /**
  * Creates a universal authentication handler for Nuxt, integrating with OpenID Connect.
  *

package/dist/runtime/server/core/nuxtAuthtsHandler.js

@@ -10,15 +10,14 @@ import {
   useRuntimeConfig
 } from "#devcoffee-core/server/adapters/http";
 import { deepMerge, omit } from "#devcoffee-core/server/adapters/utils";
-import { useStorage } from "nitropack/runtime/internal/storage";
+import { useNitroApp, useStorage } from "nitropack/runtime";
 import {
   authorizationCodeGrant,
   buildAuthorizationUrl,
   constructTokenSet,
-  deleteSession,
   fetchUserInfo,
-  getSession,
   isSameOrigin,
+  renewSession,
   revokeTokens,
   updateSession
 } from "./helpers.js";
@@ -67,20 +66,17 @@ const defaultNuxtAuthOptions = {
 export default function NuxtAuthtsHandler(options) {
   const { enabled: authEnabled, sessions: sessionConfig, openid, auth } = useRuntimeConfig().nuxtCore.authts;
   const nuxtAuthOptions = deepMerge({ ...defaultNuxtAuthOptions }, options || {});
+  useNitroApp()._sessionUserInfo = nuxtAuthOptions.userInfo;
   return eventHandler(async (event) => {
     const requestUrl = getRequestURL(event);
     const queryParams = getQuery(event);
     const authAction = getAuthAction(requestUrl);
-    let session = await getSession(event.context.sessionId, {
-      storageName: sessionConfig.storage.name,
-      storagePrefix: sessionConfig.storage.prefix,
-      secret: sessionConfig.secret || ""
-    });
+    let session = event.context.session;
     if (!session) {
       throw createError({
         status: 500,
         fatal: true,
-        message: `session '${event.context.sessionId}' was not found!`
+        message: `session was not found on event context!`
       });
     }
     if (!authEnabled && !["session" /* GET_SESSION */].includes(authAction)) {
@@ -114,7 +110,7 @@ export default function NuxtAuthtsHandler(options) {
             secret: sessionConfig.secret || ""
           });
         }
-        event.context.sessionId = session.id;
+        event.context.session = session;
         return nuxtAuthOptions.session(omit(session, ["auth"]), session.auth);
       case "authorize-url" /* AUTHORIZE_URL */:
         const { authorizeUrl, state, pkceCodeVerifier } = await buildAuthorizationUrl(session, {
@@ -131,8 +127,10 @@ export default function NuxtAuthtsHandler(options) {
           sessionStorageName: sessionConfig.storage.name,
           sessionStoragePrefix: sessionConfig.storage.prefix
         });
+        const result = { redirectUrl: authorizeUrl, cookies: [] };
         if (pkceCodeVerifier) {
           setCookie(event, sessionConfig.names.pkce, pkceCodeVerifier, authCookieOpts);
+          result.cookies.push([sessionConfig.names.pkce, pkceCodeVerifier, authCookieOpts]);
         }
         if (queryParams.redirectUrl) {
           const candidateUrl = String(queryParams.redirectUrl);
@@ -144,10 +142,12 @@ export default function NuxtAuthtsHandler(options) {
             });
           }
           setCookie(event, sessionConfig.names.redirectUrl, candidateUrl, authCookieOpts);
+          result.cookies.push([sessionConfig.names.redirectUrl, candidateUrl, authCookieOpts]);
         }
         setCookie(event, sessionConfig.names.state, state, authCookieOpts);
-        event.context.sessionId = session.id;
-        return { redirectUrl: authorizeUrl };
+        result.cookies.push([sessionConfig.names.state, state, authCookieOpts]);
+        event.context.session = session;
+        return result;
       case "token" /* TOKEN */:
         const formData = await readFormData(event);
         const openIdTokenSet = await authorizationCodeGrant(
@@ -198,13 +198,13 @@ export default function NuxtAuthtsHandler(options) {
           });
           sessionData.user = await nuxtAuthOptions.userInfo(session.user, { openidUser, tokenSet });
         }
-        await updateSession(session.id, sessionData, {
+        session = await updateSession(session.id, sessionData, {
           storageName: sessionConfig.storage.name,
           storagePrefix: sessionConfig.storage.prefix,
           expiresIn: sessionConfig.expiresIn,
           secret: sessionConfig.secret || ""
         });
-        event.context.sessionId = session.id;
+        event.context.session = session;
         return { redirectUrl };
       case "logout" /* LOGOUT */:
         redirectUrl = auth.defaultLogoutRedirectUri;
@@ -217,14 +217,15 @@ export default function NuxtAuthtsHandler(options) {
             wellKnownUrl: openid.wellKnownUrl
           });
         }
-        await deleteSession(session.id, {
+        const newSession = await renewSession(session.id, {
           storageName: sessionConfig.storage.name,
-          storagePrefix: sessionConfig.storage.prefix
+          storagePrefix: sessionConfig.storage.prefix,
+          expiresIn: sessionConfig.expiresIn,
+          secret: sessionConfig.secret || ""
         });
         const cacheStorage = useStorage("cache");
         await cacheStorage.removeItem(`${openid.cache.prefix}:userinfo:${session.id}`);
-        deleteCookie(event, sessionConfig.names.sessionId, authCookieOpts);
-        event.context.sessionId = "";
+        event.context.session = newSession;
         return { redirectUrl };
       default:
         break;

package/dist/runtime/server/core/nuxtForwardHandler.js

@@ -7,7 +7,7 @@ import {
 } from "#devcoffee-core/server/adapters/http";
 import { deepMerge } from "#devcoffee-core/server/adapters/utils";
 import useServerLogger from "#devcoffee-core/server/composables/useServerLogger";
-import { getOpenIdConfiguration, getSession } from "./helpers.js";
+import { getOpenIdConfiguration } from "./helpers.js";
 const defaultOpts = {
   logLevel: 2,
   proxyPrefix: ""
@@ -34,15 +34,11 @@ export default function NuxtForwardRequestHandler(opts) {
     });
   }
   const {
-    openid: { wellKnownUrl, cache, clientId, clientSecret },
-    sessions: {
-      secret = "",
-      storage: { name: storageName, prefix: storagePrefix }
-    }
+    openid: { wellKnownUrl, cache, clientId, clientSecret }
   } = useRuntimeConfig().nuxtCore.authts;
   return eventHandler(async (event) => {
     const oidConfig = await getOpenIdConfiguration(wellKnownUrl, { cache, clientId, clientSecret });
-    const session = await getSession(event.context.sessionId, { storageName, storagePrefix, secret });
+    const session = event.context.session;
     const headers = getRequestHeaders(event);
     if (session?.auth?.status === "authenticated" && session.auth.tokenSet?.accessToken) {
       headers.Authorization = `${session.auth.tokenSet.tokenType} ${session.auth.tokenSet?.accessToken}`;

package/dist/runtime/server/dev/route/session.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<any>>;
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, any>;
 export default _default;

package/dist/runtime/server/dev/route/session.js

@@ -1,8 +1,4 @@
 import { defineEventHandler } from "h3";
-import { useRuntimeConfig } from "nitropack/runtime";
-import { getSession } from "../../core/helpers.js";
-export default defineEventHandler(async (event) => {
-  const { name: storageName, prefix: storagePrefix } = useRuntimeConfig(event).nuxtCore.authts.sessions.storage;
-  const { secret = "" } = useRuntimeConfig(event).nuxtCore.authts.sessions;
-  return await getSession(event.context.sessionId, { storageName, storagePrefix, secret });
+export default defineEventHandler((event) => {
+  return event.context.session;
 });

package/dist/runtime/server/plugins/authts.d.ts

@@ -2,10 +2,10 @@
  * 🔐 Nitro plugin for session validation and cookie management.
  *
  * This plugin automatically validates the session ID from the incoming request cookie.
- * If the session is invalid or expired, it will create or refresh the session ID and
- * reassign it back to the request context and cookie.
+ * If the session is invalid or expired, it will create or refresh the session and
+ * store the full session object on event.context.session for downstream handlers.
  *
  * @since 1.0.0
  */
-declare const _default: import("nitropack").NitroAppPlugin;
+declare const _default: any;
 export default _default;

package/dist/runtime/server/plugins/authts.js

@@ -1,12 +1,21 @@
+import { defineNitroPlugin, getCookie, setCookie, useRuntimeConfig } from "#devcoffee-core/server/adapters/http";
 import { signSessionId } from "#devcoffee-core/server/core/crypto";
-import { getSession, refreshTokenIfNeeded, updateSession, validateSession } from "#devcoffee-core/server/core/helpers";
-import { getCookie, setCookie } from "h3";
-import { defineNitroPlugin, useRuntimeConfig } from "nitropack/runtime";
+import { refreshTokenIfNeeded, updateSession, validateSession } from "#devcoffee-core/server/core/helpers";
+import { useNitroApp, useStorage } from "nitropack/runtime";
 export default defineNitroPlugin((nitroApp) => {
   nitroApp.hooks.hook("request", async (event) => {
     const {
       enabled: authtsEnabled,
-      openid: { wellKnownUrl, cache, clientId, clientSecret, tokenRefreshBufferMs },
+      openid: {
+        wellKnownUrl,
+        cache,
+        clientId,
+        clientSecret,
+        tokenRefreshBufferMs,
+        distributedLock,
+        autoFetchUser,
+        autoFetchUserTtl
+      },
       sessions: {
         expiresIn,
         secret = "",
@@ -14,7 +23,7 @@ export default defineNitroPlugin((nitroApp) => {
         names: { sessionId: cookieName }
       }
     } = useRuntimeConfig(event).nuxtCore.authts;
-    const session = await validateSession(getCookie(event, cookieName), {
+    let session = await validateSession(getCookie(event, cookieName), {
       storageName,
       storagePrefix,
       expiresIn,
@@ -27,25 +36,39 @@ export default defineNitroPlugin((nitroApp) => {
         cache,
         clientId,
         clientSecret,
-        tokenRefreshBufferMs
+        tokenRefreshBufferMs,
+        distributedLock
       });
       if (Object.keys(sessionUpdate).length > 0) {
-        await updateSession(session.id, sessionUpdate, { storageName, storagePrefix, expiresIn, secret });
+        session = await updateSession(session.id, sessionUpdate, { storageName, storagePrefix, expiresIn, secret });
+      }
+      if (autoFetchUser) {
+        const cacheStorage = useStorage("cache");
+        const userInfoCacheKey = `${cache.prefix}:userinfo:${session.id}`;
+        let cachedUser = await cacheStorage.getItem(userInfoCacheKey);
+        if (!cachedUser) {
+          const userInfoFn = useNitroApp()._sessionUserInfo;
+          if (userInfoFn && session.auth.tokenSet) {
+            cachedUser = await userInfoFn(session.user, { tokenSet: session.auth.tokenSet });
+            await cacheStorage.setItem(userInfoCacheKey, cachedUser, { ttl: autoFetchUserTtl });
+          }
+        }
+        if (cachedUser) {
+          session = { ...session, user: cachedUser };
+        }
       }
     }
-    event.context.sessionId = session.id;
+    event.context.session = session;
   });
   nitroApp.hooks.hook("beforeResponse", async (event) => {
     const {
       cookieOpts,
       secret = "",
-      storage: { name: storageName, prefix: storagePrefix },
       names: { sessionId: cookieName }
     } = useRuntimeConfig(event).nuxtCore.authts.sessions;
-    const session = await getSession(event.context.sessionId, { storageName, storagePrefix, secret });
+    const session = event.context.session;
     if (session) {
       const cookieValue = secret ? signSessionId(session.id, secret) : session.id;
-      event.context.sessionId = session.id;
       setCookie(event, cookieName, cookieValue, {
         ...cookieOpts,
         expires: new Date(session.expiresAt)

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

@@ -1,9 +1,9 @@
-import type { CoreLogInstance, CoreLogLevel, NuxtAuthOptions } from '@devcoffee/nuxt-core'
+import type { CoreLogInstance, CoreLogLevel, NuxtAuthOptions, SessionContext } from '@devcoffee/nuxt-core'
 
 declare module 'h3' {
   interface H3EventContext {
     logger: CoreLogInstance
-    sessionId: string
+    session: SessionContext | null
   }
 }
 

package/package.json

@@ -1,8 +1,25 @@
 {
   "name": "@devcoffee/nuxt-core",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "author": "Hieu Nguyen <hieunguyen@devcoffee.tech>",
-  "description": "devcoffee core module for Nuxt",
+  "description": "Nuxt 4 module providing OpenID Connect / OAuth 2.0 authorization code grant with PKCE, server-side session management via Nitro, client-side auth state composables, and universal route protection middleware.",
+  "keywords": [
+    "nuxt",
+    "nuxt-module",
+    "nuxt4",
+    "oidc",
+    "oauth2",
+    "pkce",
+    "openid-connect",
+    "authentication",
+    "session",
+    "jwt",
+    "nitro",
+    "vue3",
+    "auth",
+    "middleware",
+    "composables"
+  ],
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -20,7 +37,9 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "CHANGELOG.md",
+    "GUIDELINE.md"
   ],
   "nuxt": {
     "module": "src/module.ts"
@@ -32,13 +51,14 @@
     "dev:build": "nuxi build playground",
     "prepack": "nuxt-module-build build",
     "release": "npm run lint && npm run test:all && npm run prepack && changelogen --release && npm publish && git push --follow-tags",
-    "lint": "eslint --fix src test",
+    "lint": "eslint",
+    "lint:fix": "eslint --fix",
     "test": "cross-env NODE_OPTIONS=--no-deprecation vitest run test/unit",
     "test:e2e": "cross-env NODE_OPTIONS=--no-deprecation vitest run test/e2e",
     "test:e2e:ui": "cross-env NODE_OPTIONS=--no-deprecation PLAYWRIGHT_HEADLESS=false vitest run test/e2e",
     "test:all": "cross-env NODE_OPTIONS=--no-deprecation vitest run",
     "test:watch": "cross-env NODE_OPTIONS=--no-deprecation vitest watch test/unit",
-    "test:types": "vue-tsc --noEmit src --skipLibCheck --strict"
+    "test:types": "vue-tsc --noEmit"
   },
   "dependencies": {
     "@nuxt/kit": "^4.1.3",
@@ -71,4 +91,4 @@
     "vitest": "^3.2.4",
     "vue-tsc": "^3.1.0"
   }
-}
+}

package/dist/runtime/app/pages/authorize.d.vue.ts

@@ -1,3 +0,0 @@
-declare const __VLS_export: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
-declare const _default: typeof __VLS_export;
-export default _default;

package/dist/runtime/app/pages/authorize.vue

@@ -1,32 +0,0 @@
-<script setup>
-import { computed, onMounted } from "vue";
-import { createError, useRoute } from "#app";
-import { useAuthContext } from "#imports";
-const { query } = useRoute();
-const { authorize } = useAuthContext("core.app.pages.authorize");
-const searchParms = computed(() => {
-  const params = new URLSearchParams();
-  if (query.code) {
-    params.set("code", query.code);
-  }
-  if (query.state) {
-    params.set("state", query.state);
-  }
-  return params;
-});
-if (!searchParms.value.has("code")) {
-  throw createError({
-    status: 400,
-    message: "Invalid code params"
-  });
-}
-onMounted(async () => {
-  if (searchParms.value.has("code")) {
-    await authorize(searchParms.value);
-  }
-});
-</script>
-
-<template>
-  <div>Nuxt module auth callback!</div>
-</template>

package/dist/runtime/app/pages/authorize.vue.d.ts

@@ -1,3 +0,0 @@
-declare const __VLS_export: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
-declare const _default: typeof __VLS_export;
-export default _default;