@devcoffee/nuxt-core 1.4.3 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## v1.5.0
+
+[compare changes](https://github.com/coolkg1412/devcoffee-nuxt-core/compare/v1.4.2...v1.5.0)
+
+### 🚀 Enhancements
+
+- Add .gitnexusrc configuration file for project settings ([b3f8d23](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/b3f8d23))
+- Restructure documentation by adding AGENTS.md and moving GUIDELINE.md to docs folder ([ff6ca21](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/ff6ca21))
+- Enhance session management by validating HMAC format, clearing tokenSet on auth reset, and updating related tests ([ae2b6fb](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/ae2b6fb))
+- Enhance session management by adding lock release functionality and improving token refresh logic ([506f3c5](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/506f3c5))
+
+### 🩹 Fixes
+
+- Enhance refreshTokenIfNeeded to support sessionCreateOptions for improved session handling ([609a4a4](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/609a4a4))
+- Update release script to include changelogen for better version management ([853cfbb](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/853cfbb))
+
+### 🏡 Chore
+
+- **release:** V1.4.3 ([0b430bd](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/0b430bd))
+
+### ❤️ Contributors
+
+- Hieu Nguyen <hieu.nguyen@devcoffee.tech>
+
 ## v1.4.3
 
 [compare changes](https://github.com/coolkg1412/devcoffee-nuxt-core/compare/v1.4.2...v1.4.3)

package/README.md

@@ -9,7 +9,7 @@ Full OpenID Connect / OAuth 2.0 authorization code grant with PKCE for DevCoffee
 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)
+- [Contributor Guide](/docs/GUIDELINE.md)
 
 ## Features
 
@@ -389,7 +389,7 @@ 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.
+See [GUIDELINE.md](/docs/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

package/dist/module.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-core",
-  "version": "1.4.3",
+  "version": "1.5.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, addTemplate, addServerImports, addServerImportsDir, addServerPlugin, addImportsDir, addPlugin, addRouteMiddleware, addServerHandler } from '@nuxt/kit';
 import { deepMerge, pick } from '../dist/runtime/utils.js';
 
-const version = "1.4.3";
+const version = "1.5.0";
 
 const defaultLocale = "vi-VN";
 const defaultLanguage = "vi";

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

@@ -21,6 +21,9 @@ export function verifySessionId(cookieValue, secret) {
   }
   const sessionId = cookieValue.slice(0, 64);
   const providedSig = cookieValue.slice(65);
+  if (!/^[0-9a-f]{64}$/i.test(providedSig)) {
+    return null;
+  }
   const expected = createHmac("sha256", secret).update(sessionId).digest("hex");
   const valid = timingSafeEqual(Buffer.from(providedSig, "hex"), Buffer.from(expected, "hex"));
   return valid ? sessionId : null;

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

@@ -201,6 +201,7 @@ export declare function refreshTokenIfNeeded(session: SessionContext, opts: {
     sessionCreateOptions?: {
         storageName: string;
         storagePrefix: string;
+        expiresIn?: number;
         secret: string;
     };
 }): Promise<any>;

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

@@ -30,7 +30,7 @@ import {
   signSessionId,
   verifySessionId
 } from "./crypto.js";
-import { tryAcquireLock } from "./mutex.js";
+import { releaseLock, tryAcquireLock } from "./mutex.js";
 function getAnonymousUser(extras) {
   const anonymous = useRuntimeConfig().nuxtCore.authts.auth.anonymousUser;
   const { defaultLocale, defaultTimeZone, defaultLanguage } = useRuntimeConfig().nuxtCore;
@@ -160,6 +160,9 @@ export async function updateSession(sessionId, input, opts) {
     });
   }
   session = deepMerge({}, session, normalizedInput);
+  if (normalizedInput.auth && Object.prototype.hasOwnProperty.call(normalizedInput.auth, "tokenSet") && normalizedInput.auth.tokenSet === void 0) {
+    delete session.auth.tokenSet;
+  }
   session.expiresAt = now + opts.expiresIn * 1e3;
   const sessionToStore = { ...session };
   if (opts.secret && sessionToStore.auth?.tokenSet) {
@@ -216,7 +219,7 @@ export async function discoveryOpendId(wellKnownUrl, opts) {
       server: config.serverMetadata(),
       client: config.clientMetadata()
     };
-    await storage.setItem(cacheKey, meta, { ttl: expires / 1e3 | 0 });
+    await storage.setItem(cacheKey, meta, { ttl: expires });
     logger.info('Fetching OpenID Connect metadata from "%s"', wellKnownUrl);
   }
   return meta;
@@ -267,7 +270,7 @@ export async function buildAuthorizationUrl(session, opt) {
   }
   await updateSession(
     session.id,
-    { auth: { status: "unauthenticated" } },
+    { auth: { status: "unauthenticated", tokenSet: void 0 } },
     {
       storageName: sessionStorageName,
       storagePrefix: sessionStoragePrefix,
@@ -324,7 +327,7 @@ export function constructTokenSet(input) {
 }
 export async function refreshTokenIfNeeded(session, opts) {
   const logger = useServerLogger({ tag: "authts-helper" });
-  let updateSession2 = {
+  let sessionUpdate = {
     auth: { status: "unauthenticated", tokenSet: void 0 },
     user: getAnonymousUser()
   };
@@ -332,7 +335,7 @@ export async function refreshTokenIfNeeded(session, opts) {
     const { accessToken, refreshToken, expiresAt } = session.auth.tokenSet;
     const accessExpired = Boolean(accessToken && expiresAt - opts.tokenRefreshBufferMs < Date.now());
     if (!accessExpired) {
-      updateSession2 = {
+      sessionUpdate = {
         auth: {
           status: session.auth.status,
           tokenSet: session.auth.tokenSet
@@ -342,56 +345,88 @@ export async function refreshTokenIfNeeded(session, opts) {
     } else if (accessExpired && refreshToken) {
       const lockStorage = useStorage("cache");
       const lockKey = `${opts.cache.prefix}:refresh-lock:${session.id}`;
-      const acquired = await tryAcquireLock(lockStorage, lockKey, 10, opts.distributedLock ?? false);
-      if (!acquired) {
-        logger.debug('[refreshTokenIfNeeded] refresh lock held for session "%s" \u2014 waiting...', session.id);
-        if (opts.sessionCreateOptions) {
-          const { storageName, storagePrefix, secret } = opts.sessionCreateOptions;
-          let attempts = 0;
-          const maxAttempts = 50;
-          while (attempts < maxAttempts) {
-            await new Promise((resolve) => setTimeout(resolve, 100));
-            const lockExists = await lockStorage.hasItem(lockKey);
-            if (!lockExists) {
-              const updatedSession = await getSession(session.id, { storageName, storagePrefix, secret });
-              if (updatedSession?.auth?.tokenSet) {
-                const newExpiresAt = updatedSession.auth.tokenSet.expiresAt;
-                const isStillExpired = Boolean(newExpiresAt - opts.tokenRefreshBufferMs < Date.now());
-                if (!isStillExpired) {
-                  logger.debug("[refreshTokenIfNeeded] session refreshed by another request, proceeding.");
-                  return {
-                    auth: { status: updatedSession.auth.status, tokenSet: updatedSession.auth.tokenSet },
-                    user: updatedSession.user
-                  };
-                }
+      const waitDeadline = Date.now() + 5e3;
+      let lease = await tryAcquireLock(lockStorage, lockKey, 10, opts.distributedLock ?? false);
+      const sessionCreateOptions = opts.sessionCreateOptions;
+      if (!lease) {
+        if (!sessionCreateOptions) {
+          logger.warn("[refreshTokenIfNeeded] sessionCreateOptions not provided, cannot wait for concurrent refresh");
+          return {};
+        }
+        while (!lease && Date.now() < waitDeadline) {
+          logger.debug('[refreshTokenIfNeeded] refresh lock held for session "%s" \u2014 waiting...', session.id);
+          const { storageName, storagePrefix, secret } = sessionCreateOptions;
+          const updatedSession = await getSession(session.id, { storageName, storagePrefix, secret });
+          if (updatedSession?.auth?.tokenSet) {
+            const newExpiresAt = updatedSession.auth.tokenSet.expiresAt;
+            const isStillExpired = Boolean(newExpiresAt - opts.tokenRefreshBufferMs < Date.now());
+            if (!isStillExpired) {
+              logger.debug("[refreshTokenIfNeeded] session refreshed by another request, proceeding.");
+              return {
+                auth: { status: updatedSession.auth.status, tokenSet: updatedSession.auth.tokenSet },
+                user: updatedSession.user
+              };
+            }
+          }
+          await new Promise((resolve) => setTimeout(resolve, 100));
+          if (!await lockStorage.hasItem(lockKey)) {
+            const updatedSessionAfterRelease = await getSession(session.id, { storageName, storagePrefix, secret });
+            if (updatedSessionAfterRelease?.auth?.tokenSet) {
+              const newExpiresAt = updatedSessionAfterRelease.auth.tokenSet.expiresAt;
+              const isStillExpired = Boolean(newExpiresAt - opts.tokenRefreshBufferMs < Date.now());
+              if (!isStillExpired) {
+                logger.debug("[refreshTokenIfNeeded] session refreshed by another request after lock release.");
+                return {
+                  auth: {
+                    status: updatedSessionAfterRelease.auth.status,
+                    tokenSet: updatedSessionAfterRelease.auth.tokenSet
+                  },
+                  user: updatedSessionAfterRelease.user
+                };
               }
             }
-            attempts++;
+            lease = await tryAcquireLock(lockStorage, lockKey, 10, opts.distributedLock ?? false);
           }
-          logger.warn('[refreshTokenIfNeeded] Timeout waiting for refresh lock for session "%s"', session.id);
-        } else {
-          logger.warn("[refreshTokenIfNeeded] sessionCreateOptions not provided, cannot wait for concurrent refresh");
         }
-        return { auth: { status: session.auth.status, tokenSet: session.auth.tokenSet }, user: session.user };
       }
-      logger.info('Refreshing access token for session "%s"', session.id);
-      const tokenSet = await refreshTokenGrant(refreshToken, {
-        wellKnownUrl: opts.wellKnownUrl,
-        cache: opts.cache,
-        clientId: opts.clientId,
-        clientSecret: opts.clientSecret
-      });
-      await lockStorage.removeItem(`${opts.cache.prefix}:userinfo:${session.id}`);
-      updateSession2 = {
-        auth: {
-          status: session.auth.status,
-          tokenSet: constructTokenSet(tokenSet)
-        },
-        user: session.user
-      };
+      if (!lease) {
+        logger.warn('[refreshTokenIfNeeded] Timeout waiting for refresh lock for session "%s"', session.id);
+        return {};
+      }
+      try {
+        logger.info('Refreshing access token for session "%s"', session.id);
+        const tokenSet = await refreshTokenGrant(refreshToken, {
+          wellKnownUrl: opts.wellKnownUrl,
+          cache: opts.cache,
+          clientId: opts.clientId,
+          clientSecret: opts.clientSecret
+        });
+        await lockStorage.removeItem(`${opts.cache.prefix}:userinfo:${session.id}`);
+        sessionUpdate = {
+          auth: {
+            status: session.auth.status,
+            tokenSet: constructTokenSet(tokenSet)
+          },
+          user: session.user
+        };
+        if (opts.sessionCreateOptions?.expiresIn) {
+          const { storageName, storagePrefix, expiresIn, secret } = opts.sessionCreateOptions;
+          await updateSession(session.id, sessionUpdate, { storageName, storagePrefix, expiresIn, secret });
+        }
+      } finally {
+        try {
+          await releaseLock(lockStorage, lease);
+        } catch (err) {
+          logger.warn(
+            '[refreshTokenIfNeeded] failed to release refresh lock for session "%s": %s',
+            session.id,
+            String(err)
+          );
+        }
+      }
     }
   }
-  return updateSession2;
+  return sessionUpdate;
 }
 export async function fetchUserInfo(accessToken, sub, opts) {
   const { wellKnownUrl, cache, clientId, clientSecret } = opts;

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

@@ -1,4 +1,15 @@
 import type { Storage } from 'unstorage';
+type RedisLockClient = {
+    set: (...args: unknown[]) => Promise<string | null>;
+    eval?: (...args: unknown[]) => Promise<unknown>;
+};
+export type LockLease = {
+    key: string;
+    owner: string;
+    atomic: boolean;
+    prefixedKey?: string;
+    client?: RedisLockClient;
+};
 /**
  * Attempts to acquire a distributed or optimistic mutex lock in Nitro cache storage.
  *
@@ -11,9 +22,11 @@ import type { Storage } from 'unstorage';
  *
  * @param storage - Prefixed cache storage (`useStorage('cache')`). Used for the optimistic path.
  * @param lockKey - The lock key (without the cache prefix). Must be unique per session.
- * @param ttlSeconds - Lock TTL in seconds. Lock expires automatically; no explicit release needed.
+ * @param ttlSeconds - Lock TTL in seconds. Lock expires automatically if release is skipped.
  * @param useAtomic - When `true`, attempt atomic NX acquisition via Redis native client.
- * @returns `true` if the lock was acquired by this caller, `false` if the lock was already held.
+ * @returns A lock lease if acquired by this caller, otherwise `null` if the lock was already held.
  * @since 1.0.0
  */
-export declare function tryAcquireLock(storage: Storage, lockKey: string, ttlSeconds: number, useAtomic: boolean): Promise<boolean>;
+export declare function tryAcquireLock(storage: Storage, lockKey: string, ttlSeconds: number, useAtomic: boolean, owner?: string): Promise<LockLease | null>;
+export declare function releaseLock(storage: Storage, lease: LockLease): Promise<void>;
+export {};

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

@@ -1,6 +1,7 @@
+import { randomUUID } from "node:crypto";
 import useServerLogger from "#devcoffee-core/server/composables/useServerLogger";
 import { useStorage } from "nitropack/runtime";
-export async function tryAcquireLock(storage, lockKey, ttlSeconds, useAtomic) {
+export async function tryAcquireLock(storage, lockKey, ttlSeconds, useAtomic, owner = randomUUID()) {
   const logger = useServerLogger({ tag: "authts-mutex" });
   if (useAtomic) {
     try {
@@ -9,19 +10,14 @@ export async function tryAcquireLock(storage, lockKey, ttlSeconds, useAtomic) {
       const client = driver.getInstance?.();
       if (client) {
         const prefixedKey = base + lockKey;
-        const result = await client.set(
-          prefixedKey,
-          "1",
-          "NX",
-          "EX",
-          ttlSeconds
-        );
+        const redisClient = client;
+        const result = await redisClient.set(prefixedKey, owner, "NX", "EX", ttlSeconds);
         if (result === "OK") {
           logger.debug('[mutex] atomic lock acquired for key "%s"', lockKey);
-          return true;
+          return { key: lockKey, owner, atomic: true, prefixedKey, client: redisClient };
         }
         logger.debug('[mutex] atomic lock held for key "%s" \u2014 skipping', lockKey);
-        return false;
+        return null;
       }
       logger.warn("[mutex] atomic lock unavailable (getInstance not present on driver) \u2014 falling back to optimistic");
     } catch (err) {
@@ -32,8 +28,26 @@ export async function tryAcquireLock(storage, lockKey, ttlSeconds, useAtomic) {
   const lockExists = await storage.hasItem(lockKey);
   if (lockExists) {
     logger.debug('[mutex] optimistic lock held for key "%s" \u2014 skipping', lockKey);
-    return false;
+    return null;
   }
-  await storage.setItem(lockKey, true, { ttl: ttlSeconds });
-  return true;
+  await storage.setItem(lockKey, owner, { ttl: ttlSeconds });
+  return { key: lockKey, owner, atomic: false };
+}
+export async function releaseLock(storage, lease) {
+  const logger = useServerLogger({ tag: "authts-mutex" });
+  if (lease.atomic && lease.client?.eval && lease.prefixedKey) {
+    await lease.client.eval(
+      "if redis.call('get', KEYS[1]) == ARGV[1] then return redis.call('del', KEYS[1]) else return 0 end",
+      1,
+      lease.prefixedKey,
+      lease.owner
+    );
+    return;
+  }
+  const currentOwner = await storage.getItem(lease.key);
+  if (currentOwner === lease.owner) {
+    await storage.removeItem(lease.key);
+    return;
+  }
+  logger.debug('[mutex] skip releasing lock "%s" because owner changed', lease.key);
 }

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

@@ -133,6 +133,7 @@ export default function NuxtAuthtsHandler(options) {
           clientSecret: openid.clientSecret,
           redirectUri: openid.redirectUri,
           scopes: openid.scopes,
+          sessionSecret: sessionConfig.secret || "",
           sessionStorageName: sessionConfig.storage.name,
           sessionStoragePrefix: sessionConfig.storage.prefix
         });

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

@@ -48,6 +48,7 @@ export default defineNitroPlugin((nitroApp) => {
         sessionCreateOptions: {
           storageName,
           storagePrefix,
+          expiresIn,
           secret
         }
       });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devcoffee/nuxt-core",
-  "version": "1.4.3",
+  "version": "1.5.0",
   "publishConfig": {
     "access": "public"
   },
@@ -41,8 +41,7 @@
   },
   "files": [
     "dist",
-    "CHANGELOG.md",
-    "GUIDELINE.md"
+    "CHANGELOG.md"
   ],
   "nuxt": {
     "module": "src/module.ts"

package/GUIDELINE.md

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