@devcoffee/nuxt-core 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## v1.6.0
+
+[compare changes](https://github.com/coolkg1412/devcoffee-nuxt-core/compare/v1.5.1...v1.6.0)
+
+### 🚀 Enhancements
+
+- Add toFormattedSize function and update PluginProviders interface ([7e8d420](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/7e8d420))
+
+### 🩹 Fixes
+
+- Implement server bypass rules and enhance session handling in auth module ([c86c70a](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/c86c70a))
+- Update release script to include type checks before publishing ([2895197](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/2895197))
+- Enhance documentation and type definitions for server bypass rules and logging utilities ([429d4d7](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/429d4d7))
+
+### ❤️ Contributors
+
+- Hieu Nguyen <hieu.nguyen@devcoffee.tech>
+
+## v1.5.1
+
+[compare changes](https://github.com/coolkg1412/devcoffee-nuxt-core/compare/v1.5.0...v1.5.1)
+
+### 🩹 Fixes
+
+- Implement auth request bypass logic for improved session handling ([8b4299c](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/8b4299c))
+- Add ignore rule for .gitnexus/run.cjs in ESLint configuration ([5c563ff](https://github.com/coolkg1412/devcoffee-nuxt-core/commit/5c563ff))
+
+### ❤️ Contributors
+
+- Hieu Nguyen <hieu.nguyen@devcoffee.tech>
+
 ## v1.5.0
 
 [compare changes](https://github.com/coolkg1412/devcoffee-nuxt-core/compare/v1.4.2...v1.5.0)

package/README.md

@@ -144,8 +144,14 @@ All options are nested under `nuxtCore` in `nuxt.config.ts`.
 | `loginUri` | `string` | `'/login'` | Path middleware redirects unauthenticated users to |
 | `defaultLoginRedirectUri` | `string` | `'/'` | Default post-login redirect when no intended destination is recorded |
 | `defaultLogoutRedirectUri` | `string` | `'/login'` | Post-logout redirect |
-| `ignoreRegexPatterns` | `RegExp[]` | `[]` | Routes matching these patterns are excluded from middleware in all environments |
-| `ignoreRegexPatternsDev` | `RegExp[]` | `[]` | Routes excluded from middleware in development only |
+| `ignoreRegexPatterns` | `RegExp[]` | `[]` | Routes matching these patterns are excluded from middleware in all environments |
+| `ignoreRegexPatternsDev` | `RegExp[]` | `[]` | Routes excluded from middleware in development only |
+| `appendIgnoreRegexPatterns` | `RegExp[]` | `[]` | Additional routes appended to `ignoreRegexPatterns`, useful for downstream modules |
+| `appendIgnoreRegexPatternsDev` | `RegExp[]` | `[]` | Additional routes appended to `ignoreRegexPatternsDev`, useful for downstream modules |
+| `serverBypassRules` | `{ pattern: string \| RegExp, mode: 'hard' \| 'soft' \| 'none' }[]` | built-ins | Server auth plugin bypass rules; last matching rule wins. Patterns are normalized to serializable regex source strings |
+| `serverBypassRulesDev` | `{ pattern: string \| RegExp, mode: 'hard' \| 'soft' \| 'none' }[]` | `[]` | Development-only server auth plugin bypass rules |
+| `appendServerBypassRules` | `{ pattern: string \| RegExp, mode: 'hard' \| 'soft' \| 'none' }[]` | `[]` | Additional server bypass rules appended after `serverBypassRules` |
+| `appendServerBypassRulesDev` | `{ pattern: string \| RegExp, mode: 'hard' \| 'soft' \| 'none' }[]` | `[]` | Additional development-only server bypass rules |
 
 ### `logging` options
 

package/dist/module.d.mts

@@ -16,6 +16,13 @@ interface AuthorizedUser {
 
 type AuthStatus = 'unauthenticated' | 'authenticated'
 
+type AuthRequestBypassMode = 'hard' | 'soft' | 'none'
+
+type AuthRequestBypassRule = {
+  pattern: string | RegExp
+  mode: AuthRequestBypassMode
+}
+
 type AuthData = {
   status: AuthStatus
   tokenSet?: {
@@ -226,6 +233,42 @@ type AuthOptions = {
   ignoreRegexPatterns: RegExp[]
 
   ignoreRegexPatternsDev: RegExp[]
+
+  /**
+   * Server-side auth plugin bypass rules.
+   *
+   * - `hard`: skips session validation, refresh, userInfo, and cookie writes.
+   * - `soft`: validates session and writes cookies, but skips refresh and userInfo side effects.
+   * - `none`: applies full auth processing; useful to override an earlier broad rule.
+   *
+   * Rules are evaluated in order and the last matching rule wins.
+   */
+  serverBypassRules: AuthRequestBypassRule[]
+
+  /** Development-only server-side auth plugin bypass rules. */
+  serverBypassRulesDev: AuthRequestBypassRule[]
+
+  /**
+   * Additional ignore patterns appended after the normalized `ignoreRegexPatterns` list.
+   * Intended for downstream modules that need to contribute ignored routes without
+   * replacing the app-owned base list.
+   */
+  appendIgnoreRegexPatterns: RegExp[]
+
+  /**
+   * Additional development-only ignore patterns appended after the normalized
+   * `ignoreRegexPatternsDev` list.
+   */
+  appendIgnoreRegexPatternsDev: RegExp[]
+
+  /**
+   * Additional server-side bypass rules appended after `serverBypassRules`.
+   * Intended for downstream modules that need to contribute system routes.
+   */
+  appendServerBypassRules: AuthRequestBypassRule[]
+
+  /** Additional development-only server-side bypass rules appended after `serverBypassRulesDev`. */
+  appendServerBypassRulesDev: AuthRequestBypassRule[]
 }
 
 /**
@@ -304,7 +347,19 @@ type ModulePublicRuntimeConfig = Pick<ModuleOptions, 'defaultLocale' | 'defaultT
 
 type InputModuleOptions = DeepPartial<ModuleOptions>
 
+/**
+ * The main entry point for the `@devcoffee/nuxt-core` module.
+ *
+ * This Nuxt module sets up the core infrastructure for applications, including:
+ * - Authentication and session management (authts)
+ * - Server and client logging functionality
+ * - Global utilities and formatters
+ * - Nitro plugins for request handling
+ * - Custom Nuxt DevTools integration for inspecting sessions
+ *
+ * @type {NuxtModule<InputModuleOptions>}
+ */
 declare const _module: NuxtModule<InputModuleOptions>;
 
 export { _module as default };
-export type { AuthData, AuthorizedUser, AuthtsMiddlewareMeta, AuthtsModuleOptions, CoreLogInstance, CoreLogLevel, InputModuleOptions, LoggingModuleOptions, LoggingOptions, ModuleOptions, ModulePublicRuntimeConfig, NuxtAuthOptions, NuxtCoreLogging, NuxtSessionContext, NuxtSessionUpdateContext, SessionContext };
+export type { AuthData, AuthRequestBypassMode, AuthRequestBypassRule, AuthorizedUser, AuthtsMiddlewareMeta, AuthtsModuleOptions, CoreLogInstance, CoreLogLevel, InputModuleOptions, LoggingModuleOptions, LoggingOptions, ModuleOptions, ModulePublicRuntimeConfig, NuxtAuthOptions, NuxtCoreLogging, NuxtSessionContext, NuxtSessionUpdateContext, SessionContext };

package/dist/module.d.ts

@@ -16,6 +16,13 @@ interface AuthorizedUser {
 
 type AuthStatus = 'unauthenticated' | 'authenticated'
 
+type AuthRequestBypassMode = 'hard' | 'soft' | 'none'
+
+type AuthRequestBypassRule = {
+  pattern: string | RegExp
+  mode: AuthRequestBypassMode
+}
+
 type AuthData = {
   status: AuthStatus
   tokenSet?: {
@@ -226,6 +233,42 @@ type AuthOptions = {
   ignoreRegexPatterns: RegExp[]
 
   ignoreRegexPatternsDev: RegExp[]
+
+  /**
+   * Server-side auth plugin bypass rules.
+   *
+   * - `hard`: skips session validation, refresh, userInfo, and cookie writes.
+   * - `soft`: validates session and writes cookies, but skips refresh and userInfo side effects.
+   * - `none`: applies full auth processing; useful to override an earlier broad rule.
+   *
+   * Rules are evaluated in order and the last matching rule wins.
+   */
+  serverBypassRules: AuthRequestBypassRule[]
+
+  /** Development-only server-side auth plugin bypass rules. */
+  serverBypassRulesDev: AuthRequestBypassRule[]
+
+  /**
+   * Additional ignore patterns appended after the normalized `ignoreRegexPatterns` list.
+   * Intended for downstream modules that need to contribute ignored routes without
+   * replacing the app-owned base list.
+   */
+  appendIgnoreRegexPatterns: RegExp[]
+
+  /**
+   * Additional development-only ignore patterns appended after the normalized
+   * `ignoreRegexPatternsDev` list.
+   */
+  appendIgnoreRegexPatternsDev: RegExp[]
+
+  /**
+   * Additional server-side bypass rules appended after `serverBypassRules`.
+   * Intended for downstream modules that need to contribute system routes.
+   */
+  appendServerBypassRules: AuthRequestBypassRule[]
+
+  /** Additional development-only server-side bypass rules appended after `serverBypassRulesDev`. */
+  appendServerBypassRulesDev: AuthRequestBypassRule[]
 }
 
 /**
@@ -304,7 +347,19 @@ type ModulePublicRuntimeConfig = Pick<ModuleOptions, 'defaultLocale' | 'defaultT
 
 type InputModuleOptions = DeepPartial<ModuleOptions>
 
+/**
+ * The main entry point for the `@devcoffee/nuxt-core` module.
+ *
+ * This Nuxt module sets up the core infrastructure for applications, including:
+ * - Authentication and session management (authts)
+ * - Server and client logging functionality
+ * - Global utilities and formatters
+ * - Nitro plugins for request handling
+ * - Custom Nuxt DevTools integration for inspecting sessions
+ *
+ * @type {NuxtModule<InputModuleOptions>}
+ */
 declare const _module: NuxtModule<InputModuleOptions>;
 
 export { _module as default };
-export type { AuthData, AuthorizedUser, AuthtsMiddlewareMeta, AuthtsModuleOptions, CoreLogInstance, CoreLogLevel, InputModuleOptions, LoggingModuleOptions, LoggingOptions, ModuleOptions, ModulePublicRuntimeConfig, NuxtAuthOptions, NuxtCoreLogging, NuxtSessionContext, NuxtSessionUpdateContext, SessionContext };
+export type { AuthData, AuthRequestBypassMode, AuthRequestBypassRule, 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.5.0",
+  "version": "1.6.0",
   "configKey": "nuxtCore",
   "compatibility": {
     "nuxt": "^4.0.0"

package/dist/module.mjs

@@ -2,11 +2,17 @@ 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.5.0";
+const version = "1.6.0";
 
 const defaultLocale = "vi-VN";
 const defaultLanguage = "vi";
 const defaultTimeZone = "Asia/Ho_Chi_Minh";
+const builtInServerBypassRules = [
+  { pattern: "^/__devcoffee_core_session_devtools__$", mode: "hard" },
+  { pattern: "^/_i18n/", mode: "hard" },
+  { pattern: "^/_nuxt/", mode: "hard" },
+  { pattern: "^/__nuxt", mode: "soft" }
+];
 const loggingDefaults = {
   server: {
     tag: "server",
@@ -19,7 +25,8 @@ const loggingDefaults = {
   client: {
     tag: "app-client",
     level: 2
-  }
+  },
+  loggers: {}
 };
 const authtsDefaults = {
   enabled: true,
@@ -74,11 +81,37 @@ const authtsDefaults = {
       timezone: defaultTimeZone
     },
     ignoreRegexPatterns: [],
-    ignoreRegexPatternsDev: []
+    ignoreRegexPatternsDev: [],
+    serverBypassRules: [],
+    serverBypassRulesDev: [],
+    appendIgnoreRegexPatterns: [],
+    appendIgnoreRegexPatternsDev: [],
+    appendServerBypassRules: [],
+    appendServerBypassRulesDev: []
   }
 };
+function collectAuthIgnorePatterns(inputOpts, key) {
+  return inputOpts.flatMap((opts) => (opts.authts?.auth?.[key] || []).filter(isRegExp));
+}
+function collectAuthServerBypassRules(inputOpts, key) {
+  return inputOpts.flatMap((opts) => (opts.authts?.auth?.[key] || []).filter(isAuthRequestBypassRule));
+}
+function isRegExp(value) {
+  return value instanceof RegExp;
+}
+function isAuthRequestBypassRule(value) {
+  if (!value || typeof value !== "object") return false;
+  const rule = value;
+  return (isRegExp(rule.pattern) || typeof rule.pattern === "string") && ["hard", "soft", "none"].includes(String(rule.mode));
+}
+function normalizeAuthRequestBypassRule(rule) {
+  return {
+    pattern: typeof rule.pattern === "string" ? rule.pattern : rule.pattern.source,
+    mode: rule.mode
+  };
+}
 function normalizedModuleOptions(...inputOpts) {
-  return deepMerge(
+  const mergedOptions = deepMerge(
     {
       defaultLocale,
       defaultLanguage,
@@ -88,6 +121,32 @@ function normalizedModuleOptions(...inputOpts) {
     },
     ...inputOpts
   );
+  const appendIgnoreRegexPatterns = collectAuthIgnorePatterns(inputOpts, "appendIgnoreRegexPatterns");
+  const appendIgnoreRegexPatternsDev = collectAuthIgnorePatterns(inputOpts, "appendIgnoreRegexPatternsDev");
+  const appendServerBypassRules = collectAuthServerBypassRules(inputOpts, "appendServerBypassRules");
+  const appendServerBypassRulesDev = collectAuthServerBypassRules(inputOpts, "appendServerBypassRulesDev");
+  mergedOptions.authts.auth.appendIgnoreRegexPatterns = appendIgnoreRegexPatterns;
+  mergedOptions.authts.auth.appendIgnoreRegexPatternsDev = appendIgnoreRegexPatternsDev;
+  mergedOptions.authts.auth.appendServerBypassRules = appendServerBypassRules.map(normalizeAuthRequestBypassRule);
+  mergedOptions.authts.auth.appendServerBypassRulesDev = appendServerBypassRulesDev.map(normalizeAuthRequestBypassRule);
+  mergedOptions.authts.auth.ignoreRegexPatterns = [
+    ...mergedOptions.authts.auth.ignoreRegexPatterns || [],
+    ...appendIgnoreRegexPatterns
+  ];
+  mergedOptions.authts.auth.ignoreRegexPatternsDev = [
+    ...mergedOptions.authts.auth.ignoreRegexPatternsDev || [],
+    ...appendIgnoreRegexPatternsDev
+  ];
+  mergedOptions.authts.auth.serverBypassRules = [
+    ...builtInServerBypassRules,
+    ...mergedOptions.authts.auth.serverBypassRules || [],
+    ...appendServerBypassRules
+  ].map(normalizeAuthRequestBypassRule);
+  mergedOptions.authts.auth.serverBypassRulesDev = [
+    ...mergedOptions.authts.auth.serverBypassRulesDev || [],
+    ...appendServerBypassRulesDev
+  ].map(normalizeAuthRequestBypassRule);
+  return mergedOptions;
 }
 function normalizePublicRuntimeConfig(inputOpts) {
   const { enabled } = inputOpts.authts;

package/dist/runtime/app/composables/useLogger.d.ts

@@ -1,4 +1,16 @@
 import type { CoreLogInstance, CoreLogLevel } from '#app';
+/**
+ * 📝 Provides access to the core logging instance.
+ *
+ * Retrieves a Nuxt logger configured with the given options, falling back to
+ * default NuxtCore logging settings.
+ *
+ * @param {Object} [opts] - Optional logger configuration.
+ * @param {string} [opts.tag] - A specific tag to apply to the logger.
+ * @param {CoreLogLevel} [opts.level] - Override the default log level.
+ * @returns {CoreLogInstance} A configured logger instance.
+ * @since 1.0.0
+ */
 export default function useLogger(opts?: {
     tag?: string;
     level?: CoreLogLevel;

package/dist/runtime/app/plugins/formatters.d.ts

@@ -1,20 +1,37 @@
+/**
+ * Options for padding a number or string.
+ */
 type PadOptions = {
+    /** A prefix to apply before the padded string. */
     prefix: string & {
         __uppercaseBrand?: never;
     };
+    /** The separator to insert between the prefix and the padded string. */
     separator: string;
+    /** The total target length to pad to. */
     length: number;
+    /** The character to use for padding. */
     padChar: string;
 };
+/** Formats a number with specific padding and prefix options. */
 type ToPad = (num: number, opts?: Partial<PadOptions>) => string;
+/** Formats a raw number string into a US phone number format `(XXX) XXX-XXXX`. */
 type AsPhoneText = (numStr: string) => string;
+/** Converts a byte value into a formatted human-readable file size. */
+type ToFormattedSize = (numStr?: Nullable<string> | Nullable<number>) => string;
+/** Formats a Date object into a localized date string. */
 type AsDateString = (date: Date) => string;
+/** Formats a Date object into a localized time string. */
 type AsTimeString = (date: Date, seconds?: boolean) => string;
+/** Formats a Date object into a localized date and time string. */
 type AsDateTimeString = (date: Date, seconds?: boolean) => string;
+/** Formats a Date object into a relative time string (e.g. "2 days ago"). */
 type AsRelativeTimeString = (date: Date) => string;
+/** Defines the formatter functions provided to the Nuxt application context. */
 type PluginProviders = {
     toPad: ToPad;
     asPhoneText: AsPhoneText;
+    toFormattedSize: ToFormattedSize;
     asDateString: AsDateString;
     asTimeString: AsTimeString;
     asDateTimeString: AsDateTimeString;
@@ -25,5 +42,13 @@ declare module 'vue' {
         $formatters: PluginProviders;
     }
 }
+/**
+ * 🧩 Nuxt plugin for global data formatting utilities.
+ *
+ * Provides helpers for formatting numbers, dates, times, filesizes, and phone numbers
+ * across the application, actively aware of the user's current locale and timezone.
+ *
+ * @since 1.0.0
+ */
 declare const _default: any;
 export default _default;

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

@@ -42,6 +42,15 @@ export default defineNuxtPlugin((_nuxtApp) => {
     const digits = numStr.replace(/\D/g, "");
     return digits.replace(/(\d{3})(\d{3})(\d{4})/, "($1) $2-$3");
   }
+  function toFormattedSize(numStr) {
+    if (!numStr) return "0B";
+    const bytes = typeof numStr == "number" ? numStr : parseInt(numStr);
+    const units = ["B", "KB", "MB", "GB", "TB"];
+    const index = Math.min(units.length - 1, Math.floor(Math.log(bytes) / Math.log(1024)));
+    const value = bytes / 1024 ** index;
+    const rounded = value >= 10 || index === 0 ? Math.round(value) : Number(value.toFixed(1));
+    return `${rounded}${units[index]}`;
+  }
   function asDateString(date) {
     logger.debug(`Format date with  locale ='${currentLocale.value}'`);
     return new Intl.DateTimeFormat(currentLocale.value).format(date);
@@ -101,6 +110,7 @@ export default defineNuxtPlugin((_nuxtApp) => {
   }
   _nuxtApp.provide("formatters", {
     toPad,
+    toFormattedSize,
     asPhoneText,
     asDateString,
     asTimeString,

package/dist/runtime/app/plugins/locale.d.ts

@@ -1,8 +1,14 @@
+/**
+ * Represents the current active locale configuration.
+ */
 type LocaleState = {
     locale: string;
     language: string;
     timeZone: string;
 };
+/**
+ * The provider shape for locale settings exposed to the application context.
+ */
 type LocaleProvider = LocaleState;
 /**
  * 🧩 Nuxt plugin for locale utilities.

package/dist/runtime/app/utils/hashing.d.ts

@@ -1 +1,8 @@
+/**
+ * Generates a random short hash without hyphens.
+ *
+ * @param {number} [length=8] - The desired length of the resulting hash.
+ * @returns {string} A random string of the specified length.
+ * @since 1.0.0
+ */
 export declare function randomShortHash(length?: number): string;

package/dist/runtime/server/composables/useServerLogger.d.ts

@@ -1,5 +1,17 @@
 import { type ConsolaInstance, type LogLevel } from 'consola';
 import type { H3Event } from 'h3';
+/**
+ * Retrieves or initializes the server-side logger instance.
+ *
+ * Uses the Nuxt runtime configuration to set up a `consola` logger with the appropriate
+ * tags and log levels. If an H3 event is provided, it will be used to fetch the current event's runtime config.
+ *
+ * @param {Object} [options] - Optional logger configuration.
+ * @param {H3Event} [options.event] - The current H3 event, used to fetch runtime config context.
+ * @param {string} [options.tag] - A specific tag to apply to the logger.
+ * @param {LogLevel} [options.level] - Override the default log level.
+ * @returns {ConsolaInstance} A configured Consola logger instance.
+ */
 export default function useServerLogger(options?: Partial<{
     event?: H3Event;
     tag?: string;

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

@@ -77,6 +77,15 @@ export declare function validateSession(sessionCookieId: string | undefined, opt
  * @since 1.0.0
  */
 export declare function updateSession(sessionId: string, input: DeepPartial<Omit<SessionContext, 'id' | 'expiresAt' | 'issuedAt'>>, opts: SessionCreateOptions): Promise<SessionContext>;
+/**
+ * Renews an existing session by destroying it and creating a fresh unauthenticated session
+ * with a new session ID and updated expiration time.
+ *
+ * @param sessionId - The ID of the session to renew.
+ * @param opts - Session creation options including storage name, prefix, and expiration time.
+ * @returns A promise that resolves to the newly created {@link SessionContext}.
+ * @since 1.0.0
+ */
 export declare function renewSession(sessionId: string, opts: SessionCreateOptions): Promise<SessionContext>;
 /**
  * Delete a session from storage by ID.
@@ -180,6 +189,14 @@ export declare function authorizationCodeGrant(authorizeParams: {
     redirectUri: string;
     usePkce: boolean;
 }): Promise<any>;
+/**
+ * Constructs a normalized token set from an OpenID Connect token endpoint response.
+ * Ensures the token type is properly capitalized.
+ *
+ * @param input - The raw token endpoint response.
+ * @returns A normalized token set containing access, id, and refresh tokens along with expiry.
+ * @since 1.0.0
+ */
 export declare function constructTokenSet(input: TokenEndpointResponse): {
     tokenType: string;
     idToken: any;
@@ -188,6 +205,15 @@ export declare function constructTokenSet(input: TokenEndpointResponse): {
     scopes: any;
     expiresAt: number;
 };
+/**
+ * Checks if the session's access token is expired or expiring soon, and refreshes it if necessary.
+ * Implements a distributed lock to prevent concurrent refresh attempts for the same session.
+ *
+ * @param session - The current session context.
+ * @param opts - Configuration options for the refresh token grant, caching, and locking.
+ * @returns A partial session update containing the new authentication status and user, or empty object if no refresh occurred.
+ * @since 1.0.0
+ */
 export declare function refreshTokenIfNeeded(session: SessionContext, opts: {
     wellKnownUrl: string;
     cache: {
@@ -208,7 +234,7 @@ export declare function refreshTokenIfNeeded(session: SessionContext, opts: {
 /**
  * Fetch user profile information from the OpenID Provider using the access token.
  *
- * @param tokenSet - The token response returned from the token endpoint.
+ * @param accessToken - The access token used to authenticate the request to the userinfo endpoint.
  * @param sub - The subject identifier of the authenticated user.
  * @param opts - OpenID discovery and client configuration options.
  * @returns Simplified user information (id, sub, email, first/last name).
@@ -217,6 +243,15 @@ export declare function refreshTokenIfNeeded(session: SessionContext, opts: {
 export declare function fetchUserInfo(accessToken: string, sub: string, opts: OpenIdDiscoveryOptions & {
     wellKnownUrl: string;
 }): Promise<any>;
+/**
+ * Revoke an array of tokens (e.g., access and refresh tokens) at the OpenID Provider.
+ * Skips empty or undefined tokens.
+ *
+ * @param tokens - An array of token strings to revoke.
+ * @param opts - OpenID discovery and client configuration options.
+ * @returns A promise resolving to an array of settlement results for each revocation request.
+ * @since 1.0.0
+ */
 export declare function revokeTokens(tokens: string[], opts: OpenIdDiscoveryOptions & {
     wellKnownUrl: string;
 }): Promise<PromiseSettledResult<any>[]>;

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

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

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

@@ -1,4 +1,281 @@
-import { defineEventHandler } from "h3";
-export default defineEventHandler((event) => {
-  return event.context.session;
+import { eventHandler, getCookie, getQuery, useRuntimeConfig } from "#devcoffee-core/server/adapters/http";
+import { getSessionData } from "#devcoffee-core/server/adapters/storage";
+import { isValidSessionId, verifySessionId } from "#devcoffee-core/server/core/crypto";
+function getSessionStorageKey(storagePrefix, sessionId) {
+  return storagePrefix ? `${storagePrefix}:${sessionId}` : sessionId;
+}
+function isEncryptedTokenSet(tokenSet) {
+  return Boolean(tokenSet && "encrypted" in tokenSet && tokenSet.encrypted === true);
+}
+function sanitizeSession(session) {
+  const tokenSet = session.auth?.tokenSet;
+  const tokenSetEncrypted = isEncryptedTokenSet(tokenSet);
+  const tokenSetPresent = Boolean(tokenSet);
+  const tokenExpiresAt = tokenSet && !tokenSetEncrypted && "expiresAt" in tokenSet ? tokenSet.expiresAt : void 0;
+  return {
+    ...session,
+    auth: {
+      status: session.auth?.status || "unauthenticated",
+      tokenSet: {
+        encrypted: tokenSetEncrypted,
+        present: tokenSetPresent,
+        tokenType: tokenSet && !tokenSetEncrypted && "tokenType" in tokenSet ? tokenSet.tokenType : void 0,
+        scopes: tokenSet && !tokenSetEncrypted && "scopes" in tokenSet ? tokenSet.scopes : void 0,
+        expiresAt: tokenExpiresAt,
+        expiresInMs: typeof tokenExpiresAt === "number" ? tokenExpiresAt - Date.now() : void 0
+      }
+    }
+  };
+}
+async function readSessionSnapshot(event) {
+  const {
+    sessions: {
+      secret = "",
+      storage: { name: storageName, prefix: storagePrefix },
+      names: { sessionId: cookieName }
+    }
+  } = useRuntimeConfig(event).nuxtCore.authts;
+  const cookieValue = getCookie(event, cookieName);
+  const sessionId = verifySessionId(cookieValue, secret);
+  if (!cookieValue) {
+    return createSnapshot("missing-cookie", null, null, null);
+  }
+  if (!sessionId || !isValidSessionId(sessionId)) {
+    return createSnapshot("invalid-cookie", null, null, null);
+  }
+  const storageKey = getSessionStorageKey(storagePrefix, sessionId);
+  const session = await getSessionData(storageName, storageKey);
+  if (!session) {
+    return createSnapshot("missing-session", sessionId, storageKey, null);
+  }
+  const status = session.expiresAt <= Date.now() ? "expired" : "active";
+  return createSnapshot(status, sessionId, storageKey, sanitizeSession(session));
+}
+function createSnapshot(status, sessionId, storageKey, session) {
+  return {
+    meta: {
+      readOnly: true,
+      loadedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      status,
+      sessionId,
+      storageKey
+    },
+    session
+  };
+}
+function renderSessionInspector() {
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Devcoffee Session</title>
+  <style>
+    :root {
+      color-scheme: light dark;
+      --bg: #f7f8fb;
+      --panel: #ffffff;
+      --text: #17202a;
+      --muted: #637083;
+      --border: #d9dee8;
+      --accent: #0f766e;
+      --accent-strong: #0d5f59;
+      --code: #101828;
+      --code-bg: #eef2f7;
+      font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+    }
+
+    @media (prefers-color-scheme: dark) {
+      :root {
+        --bg: #111827;
+        --panel: #182233;
+        --text: #ecf1f8;
+        --muted: #aab6c7;
+        --border: #314057;
+        --accent: #2dd4bf;
+        --accent-strong: #5eead4;
+        --code: #e8eef8;
+        --code-bg: #0f172a;
+      }
+    }
+
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      min-height: 100vh;
+      background: var(--bg);
+      color: var(--text);
+      font-size: 14px;
+    }
+    main {
+      width: min(980px, calc(100vw - 32px));
+      margin: 0 auto;
+      padding: 24px 0;
+    }
+    header {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: 16px;
+      margin-bottom: 16px;
+    }
+    h1 {
+      margin: 0;
+      font-size: 20px;
+      font-weight: 700;
+      letter-spacing: 0;
+    }
+    button {
+      border: 1px solid var(--accent);
+      border-radius: 6px;
+      background: var(--accent);
+      color: #ffffff;
+      cursor: pointer;
+      font: inherit;
+      font-weight: 700;
+      min-height: 36px;
+      padding: 0 14px;
+    }
+    button:hover { background: var(--accent-strong); }
+    button:disabled {
+      cursor: wait;
+      opacity: .7;
+    }
+    .panel {
+      background: var(--panel);
+      border: 1px solid var(--border);
+      border-radius: 8px;
+      overflow: hidden;
+    }
+    .summary {
+      display: grid;
+      grid-template-columns: repeat(4, minmax(0, 1fr));
+      gap: 0;
+      border-bottom: 1px solid var(--border);
+    }
+    .item {
+      min-width: 0;
+      padding: 14px 16px;
+      border-right: 1px solid var(--border);
+    }
+    .item:last-child { border-right: 0; }
+    .label {
+      color: var(--muted);
+      font-size: 12px;
+      font-weight: 700;
+      margin-bottom: 6px;
+      text-transform: uppercase;
+    }
+    .value {
+      overflow-wrap: anywhere;
+      font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+      font-size: 13px;
+    }
+    pre {
+      margin: 0;
+      min-height: 320px;
+      overflow: auto;
+      padding: 16px;
+      background: var(--code-bg);
+      color: var(--code);
+      font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+      font-size: 12px;
+      line-height: 1.55;
+      white-space: pre-wrap;
+      word-break: break-word;
+    }
+    .error {
+      color: #b42318;
+      padding: 16px;
+    }
+
+    @media (max-width: 720px) {
+      header { align-items: flex-start; flex-direction: column; }
+      button { width: 100%; }
+      .summary { grid-template-columns: 1fr; }
+      .item { border-bottom: 1px solid var(--border); border-right: 0; }
+      .item:last-child { border-bottom: 0; }
+    }
+  </style>
+</head>
+<body>
+  <main>
+    <header>
+      <h1>Devcoffee Session</h1>
+      <button id="refresh" type="button">Refresh</button>
+    </header>
+    <section class="panel">
+      <div class="summary">
+        <div class="item">
+          <div class="label">Status</div>
+          <div class="value" id="status">loading</div>
+        </div>
+        <div class="item">
+          <div class="label">Authenticated</div>
+          <div class="value" id="authenticated">unknown</div>
+        </div>
+        <div class="item">
+          <div class="label">User</div>
+          <div class="value" id="user">unknown</div>
+        </div>
+        <div class="item">
+          <div class="label">Loaded</div>
+          <div class="value" id="loaded">pending</div>
+        </div>
+      </div>
+      <pre id="payload">{}</pre>
+      <div class="error" id="error" hidden></div>
+    </section>
+  </main>
+  <script>
+    const refreshButton = document.getElementById('refresh')
+    const statusNode = document.getElementById('status')
+    const authenticatedNode = document.getElementById('authenticated')
+    const userNode = document.getElementById('user')
+    const loadedNode = document.getElementById('loaded')
+    const payloadNode = document.getElementById('payload')
+    const errorNode = document.getElementById('error')
+
+    async function loadSession() {
+      refreshButton.disabled = true
+      errorNode.hidden = true
+      statusNode.textContent = 'loading'
+
+      try {
+        const response = await fetch('?format=json&ts=' + Date.now(), {
+          credentials: 'same-origin',
+          headers: { Accept: 'application/json' },
+        })
+        if (!response.ok) throw new Error('Request failed: ' + response.status)
+
+        const snapshot = await response.json()
+        const session = snapshot.session
+        statusNode.textContent = snapshot.meta.status
+        authenticatedNode.textContent = String(session?.auth?.status === 'authenticated')
+        userNode.textContent = session?.user?.email || session?.user?.id || 'none'
+        loadedNode.textContent = new Date(snapshot.meta.loadedAt).toLocaleTimeString()
+        payloadNode.textContent = JSON.stringify(snapshot, null, 2)
+      } catch (error) {
+        errorNode.hidden = false
+        errorNode.textContent = error instanceof Error ? error.message : String(error)
+        statusNode.textContent = 'error'
+      } finally {
+        refreshButton.disabled = false
+      }
+    }
+
+    refreshButton.addEventListener('click', loadSession)
+    loadSession()
+  <\/script>
+</body>
+</html>`;
+}
+export default eventHandler(async (event) => {
+  const query = getQuery(event);
+  if (query.format === "json") {
+    event.node.res.setHeader("Content-Type", "application/json; charset=utf-8");
+    return await readSessionSnapshot(event);
+  }
+  event.node.res.setHeader("Content-Type", "text/html; charset=utf-8");
+  return renderSessionInspector();
 });

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

@@ -1,4 +1,4 @@
-import { defineNitroPlugin, getCookie, useRuntimeConfig } from "#devcoffee-core/server/adapters/http";
+import { defineNitroPlugin, getCookie, getRequestHeaders, useRuntimeConfig } from "#devcoffee-core/server/adapters/http";
 import useServerLogger from "#devcoffee-core/server/composables/useServerLogger";
 import {
   refreshTokenIfNeeded,
@@ -7,10 +7,42 @@ import {
   writeSessionCookie
 } from "#devcoffee-core/server/core/helpers";
 import { useNitroApp, useStorage } from "nitropack/runtime";
+const fallbackServerBypassRules = [
+  { pattern: "^/__devcoffee_core_session_devtools__$", mode: "hard" },
+  { pattern: "^/_i18n/", mode: "hard" },
+  { pattern: "^/_nuxt/", mode: "hard" },
+  { pattern: "^/__nuxt", mode: "soft" }
+];
+function testBypassRule(rule, pathname) {
+  const pattern = typeof rule.pattern === "string" ? new RegExp(rule.pattern) : rule.pattern;
+  pattern.lastIndex = 0;
+  return pattern.test(pathname);
+}
+function getAuthRequestBypass(event, opts = {}) {
+  const path = event.path || "";
+  const pathname = path.split("?")[0] || "";
+  const i18nHeader = getRequestHeaders(event)["x-nuxt-i18n"];
+  if (i18nHeader?.toLowerCase() === "internal") {
+    return "hard";
+  }
+  const serverBypassRules = opts.serverBypassRules?.length ? opts.serverBypassRules : fallbackServerBypassRules;
+  const serverBypassRulesDev = opts.serverBypassRulesDev || [];
+  let mode = "none";
+  for (const rule of serverBypassRules) {
+    if (testBypassRule(rule, pathname)) mode = rule.mode;
+  }
+  if (import.meta.dev) {
+    for (const rule of serverBypassRulesDev) {
+      if (testBypassRule(rule, pathname)) mode = rule.mode;
+    }
+  }
+  return mode;
+}
 export default defineNitroPlugin((nitroApp) => {
   nitroApp.hooks.hook("request", async (event) => {
     const {
       enabled: authtsEnabled,
+      auth: { serverBypassRules, serverBypassRulesDev } = {},
       openid: {
         wellKnownUrl,
         cache,
@@ -28,6 +60,8 @@ export default defineNitroPlugin((nitroApp) => {
         names: { sessionId: cookieName }
       }
     } = useRuntimeConfig(event).nuxtCore.authts;
+    const authRequestBypass = getAuthRequestBypass(event, { serverBypassRules, serverBypassRulesDev });
+    if (authRequestBypass === "hard") return;
     const sessionCookieId = getCookie(event, cookieName);
     const logger = useServerLogger({ event, tag: "plugin.auth" });
     let session = await validateSession(sessionCookieId, {
@@ -37,7 +71,8 @@ export default defineNitroPlugin((nitroApp) => {
       secret
     });
     const { status = "unauthenticated", tokenSet } = session.auth || {};
-    if (authtsEnabled && status === "authenticated" && tokenSet) {
+    const shouldRunAuthSideEffects = authRequestBypass === "none";
+    if (shouldRunAuthSideEffects && authtsEnabled && status === "authenticated" && tokenSet) {
       const sessionUpdate = await refreshTokenIfNeeded(session, {
         wellKnownUrl,
         cache,
@@ -79,10 +114,12 @@ export default defineNitroPlugin((nitroApp) => {
     event.context.session = session;
   });
   nitroApp.hooks.hook("beforeResponse", async (event) => {
+    const { auth: { serverBypassRules, serverBypassRulesDev } = {}, sessions } = useRuntimeConfig(event).nuxtCore.authts;
+    if (getAuthRequestBypass(event, { serverBypassRules, serverBypassRulesDev }) === "hard") return;
     if (event.node.res.headersSent) return;
     const session = event.context.session;
     if (session) {
-      writeSessionCookie(event, session, useRuntimeConfig(event).nuxtCore.authts.sessions);
+      writeSessionCookie(event, session, sessions);
     }
   });
 });

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

@@ -1,2 +1,11 @@
+/**
+ * 📝 Nitro plugin for server-side logging integration.
+ *
+ * This plugin initializes the server logger and attaches it to the H3 event context (`event.context.logger`)
+ * for every incoming request. It also sets up a global error hook to automatically log uncaught
+ * Nitro server errors alongside their relevant request context (method and path).
+ *
+ * @since 1.0.0
+ */
 declare const _default: import("nitropack").NitroAppPlugin;
 export default _default;

package/dist/types.d.mts

@@ -6,4 +6,4 @@ declare module '@nuxt/schema' {
 
 export { default } from './module.mjs'
 
-export { type AuthData, type AuthorizedUser, type AuthtsMiddlewareMeta, type AuthtsModuleOptions, type CoreLogInstance, type CoreLogLevel, type InputModuleOptions, type LoggingModuleOptions, type LoggingOptions, type ModuleOptions, type ModulePublicRuntimeConfig, type NuxtAuthOptions, type NuxtCoreLogging, type NuxtSessionContext, type NuxtSessionUpdateContext, type SessionContext } from './module.mjs'
+export { type AuthData, type AuthRequestBypassMode, type AuthRequestBypassRule, type AuthorizedUser, type AuthtsMiddlewareMeta, type AuthtsModuleOptions, type CoreLogInstance, type CoreLogLevel, type InputModuleOptions, type LoggingModuleOptions, type LoggingOptions, type ModuleOptions, type ModulePublicRuntimeConfig, type NuxtAuthOptions, type NuxtCoreLogging, type NuxtSessionContext, type NuxtSessionUpdateContext, type SessionContext } from './module.mjs'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devcoffee/nuxt-core",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "publishConfig": {
     "access": "public"
   },
@@ -52,7 +52,7 @@
     "cleanup": "nuxi cleanup && nuxi cleanup playground",
     "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",
+    "release": "npm run lint && npm run test:types && npm run test:all && npm run prepack && changelogen --release && npm publish && git push --follow-tags",
     "lint": "eslint",
     "lint:fix": "eslint --fix",
     "test": "cross-env NODE_OPTIONS=--no-deprecation vitest run test/unit",
@@ -60,7 +60,7 @@
     "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",
+    "test:types": "vue-tsc --noEmit -p .nuxt/tsconfig.app.json",
     "typecheck": "vue-tsc --noEmit -p .nuxt/tsconfig.app.json"
   },
   "dependencies": {