@devcoffee/nuxt-core 1.0.2 → 1.1.1

package/CHANGELOG.md

@@ -0,0 +1,82 @@
+# Changelog
+
+## 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`