@nauth-toolkit/core 0.1.14 → 0.1.17

package/dist/utils/context-storage.js

@@ -2,12 +2,66 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ContextStorage = void 0;
 const async_hooks_1 = require("async_hooks");
+/**
+ * Context Storage - Platform-Agnostic Async Local Storage
+ *
+ * Provides request-scoped storage using Node.js AsyncLocalStorage.
+ * Replaces nestjs-cls for platform-agnostic context management.
+ *
+ * **Features:**
+ * - Request-scoped data storage
+ * - Works across async boundaries
+ * - No framework dependencies
+ * - Type-safe storage and retrieval
+ *
+ * @example
+ * ```typescript
+ * // Store data in context
+ * ContextStorage.run(() => {
+ *   ContextStorage.set('userId', '123');
+ *   ContextStorage.set('clientInfo', { ip: '1.2.3.4' });
+ *
+ *   // Access from any nested function
+ *   const userId = ContextStorage.get<string>('userId');
+ * });
+ * ```
+ */
 class ContextStorage {
     static als = new async_hooks_1.AsyncLocalStorage();
+    /**
+     * Run a callback within a new context
+     *
+     * Creates a new async local storage context for the callback.
+     * All ContextStorage operations within the callback will use this context.
+     *
+     * @param callback - Function to execute with context
+     * @returns Result of the callback
+     *
+     * @example
+     * ```typescript
+     * const result = ContextStorage.run(() => {
+     *   ContextStorage.set('key', 'value');
+     *   return processRequest();
+     * });
+     * ```
+     */
     static run(callback) {
         const store = new Map();
         return this.als.run(store, callback);
     }
+    /**
+     * Store a value in the current context
+     *
+     * @param key - Storage key
+     * @param value - Value to store
+     * @throws Error if called outside of a context (ContextStorage.run not called)
+     *
+     * @example
+     * ```typescript
+     * ContextStorage.set('userId', '123');
+     * ContextStorage.set('clientInfo', { ip: '1.2.3.4', userAgent: 'Mozilla...' });
+     * ```
+     */
     static set(key, value) {
         const store = this.als.getStore();
         if (!store) {
@@ -15,14 +69,50 @@ class ContextStorage {
         }
         store.set(key, value);
     }
+    /**
+     * Retrieve a value from the current context
+     *
+     * @param key - Storage key
+     * @returns Stored value or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const userId = ContextStorage.get<string>('userId');
+     * const clientInfo = ContextStorage.get<ClientInfo>('CLIENT_INFO');
+     * ```
+     */
     static get(key) {
         const store = this.als.getStore();
         return store?.get(key);
     }
+    /**
+     * Check if a key exists in the current context
+     *
+     * @param key - Storage key
+     * @returns True if key exists, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (ContextStorage.has('userId')) {
+     *   const userId = ContextStorage.get<string>('userId');
+     * }
+     * ```
+     */
     static has(key) {
         const store = this.als.getStore();
         return store?.has(key) || false;
     }
+    /**
+     * Delete a value from the current context
+     *
+     * @param key - Storage key
+     * @returns True if key was deleted, false if it didn't exist
+     *
+     * @example
+     * ```typescript
+     * ContextStorage.delete('temporaryData');
+     * ```
+     */
     static delete(key) {
         const store = this.als.getStore();
         if (!store) {
@@ -30,12 +120,31 @@ class ContextStorage {
         }
         return store.delete(key);
     }
+    /**
+     * Clear all values from the current context
+     *
+     * @example
+     * ```typescript
+     * ContextStorage.clear();
+     * ```
+     */
     static clear() {
         const store = this.als.getStore();
         if (store) {
             store.clear();
         }
     }
+    /**
+     * Get all keys in the current context
+     *
+     * @returns Array of storage keys
+     *
+     * @example
+     * ```typescript
+     * const keys = ContextStorage.keys();
+     * console.log('Stored keys:', keys);
+     * ```
+     */
     static keys() {
         const store = this.als.getStore();
         if (!store) {
@@ -43,9 +152,29 @@ class ContextStorage {
         }
         return Array.from(store.keys());
     }
+    /**
+     * Get the current store instance
+     *
+     * This is useful for frameworks like Fastify where hooks run independently
+     * and you need to preserve the store across hook boundaries.
+     *
+     * @returns The current Map store or undefined
+     * @internal
+     */
     static getStore() {
         return this.als.getStore();
     }
+    /**
+     * Enter an existing context store
+     *
+     * This allows re-entering a context that was created elsewhere,
+     * useful for frameworks where handlers run in separate scopes.
+     *
+     * @param store - The store to enter
+     * @param callback - Function to execute with the store
+     * @returns Result of the callback
+     * @internal
+     */
     static enterStore(store, callback) {
         return this.als.run(store, callback);
     }

package/dist/utils/context-storage.js.map

@@ -1 +1 @@
-{"version":3,"file":"context-storage.js","sourceRoot":"","sources":["../../src/utils/context-storage.ts"],"names":[],"mappings":";;;AAAA,6CAAgD;AA0BhD,MAAa,cAAc;IACjB,MAAM,CAAC,GAAG,GAAG,IAAI,+BAAiB,EAAwB,CAAC;IAmBnE,MAAM,CAAC,GAAG,CAAI,QAAiB;QAC7B,MAAM,KAAK,GAAG,IAAI,GAAG,EAAmB,CAAC;QACzC,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACvC,CAAC;IAeD,MAAM,CAAC,GAAG,CAAI,GAAW,EAAE,KAAQ;QACjC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;QAClC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,2DAA2D,CAAC,CAAC;QAC/E,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACxB,CAAC;IAcD,MAAM,CAAC,GAAG,CAAI,GAAW;QACvB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;QAClC,OAAO,KAAK,EAAE,GAAG,CAAC,GAAG,CAAkB,CAAC;IAC1C,CAAC;IAeD,MAAM,CAAC,GAAG,CAAC,GAAW;QACpB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;QAClC,OAAO,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC;IAClC,CAAC;IAaD,MAAM,CAAC,MAAM,CAAC,GAAW;QACvB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;QAClC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAUD,MAAM,CAAC,KAAK;QACV,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;QAClC,IAAI,KAAK,EAAE,CAAC;YACV,KAAK,CAAC,KAAK,EAAE,CAAC;QAChB,CAAC;IACH,CAAC;IAaD,MAAM,CAAC,IAAI;QACT,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;QAClC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IAClC,CAAC;IAWD,MAAM,CAAC,QAAQ;QACb,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;IAC7B,CAAC;IAaD,MAAM,CAAC,UAAU,CAAI,KAA2B,EAAE,QAAiB;QACjE,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACvC,CAAC;;AAhKH,wCAiKC"}
+{"version":3,"file":"context-storage.js","sourceRoot":"","sources":["../../src/utils/context-storage.ts"],"names":[],"mappings":";;;AAAA,6CAAgD;AAEhD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAa,cAAc;IACjB,MAAM,CAAC,GAAG,GAAG,IAAI,+BAAiB,EAAwB,CAAC;IAEnE;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,GAAG,CAAI,QAAiB;QAC7B,MAAM,KAAK,GAAG,IAAI,GAAG,EAAmB,CAAC;QACzC,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACvC,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,GAAG,CAAI,GAAW,EAAE,KAAQ;QACjC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;QAClC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CAAC,2DAA2D,CAAC,CAAC;QAC/E,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACxB,CAAC;IAED;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,GAAG,CAAI,GAAW;QACvB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;QAClC,OAAO,KAAK,EAAE,GAAG,CAAC,GAAG,CAAkB,CAAC;IAC1C,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,GAAG,CAAC,GAAW;QACpB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;QAClC,OAAO,KAAK,EAAE,GAAG,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC;IAClC,CAAC;IAED;;;;;;;;;;OAUG;IACH,MAAM,CAAC,MAAM,CAAC,GAAW;QACvB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;QAClC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,KAAK;QACV,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;QAClC,IAAI,KAAK,EAAE,CAAC;YACV,KAAK,CAAC,KAAK,EAAE,CAAC;QAChB,CAAC;IACH,CAAC;IAED;;;;;;;;;;OAUG;IACH,MAAM,CAAC,IAAI;QACT,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;QAClC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IAClC,CAAC;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,QAAQ;QACb,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;IAC7B,CAAC;IAED;;;;;;;;;;OAUG;IACH,MAAM,CAAC,UAAU,CAAI,KAA2B,EAAE,QAAiB;QACjE,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACvC,CAAC;;AAhKH,wCAiKC"}

package/dist/utils/cookie-names.util.d.ts

@@ -1,7 +1,42 @@
+/**
+ * Cookie Name Utilities
+ *
+ * Provides consistent cookie name generation using the configured prefix.
+ * All cookie names are prefixed to avoid conflicts with other cookies.
+ */
 import { NAuthConfig } from '../interfaces/config.interface';
+/**
+ * Get the cookie name prefix from config
+ * @param config - NAuth configuration
+ * @returns Cookie name prefix (default: 'nauth_')
+ */
 export declare function getCookieNamePrefix(config?: NAuthConfig): string;
+/**
+ * Get the access token cookie name
+ * @param config - NAuth configuration
+ * @returns Access token cookie name (default: 'nauth_access_token')
+ */
 export declare function getAccessTokenCookieName(config?: NAuthConfig): string;
+/**
+ * Get the refresh token cookie name
+ * @param config - NAuth configuration
+ * @returns Refresh token cookie name (default: 'nauth_refresh_token')
+ */
 export declare function getRefreshTokenCookieName(config?: NAuthConfig): string;
+/**
+ * Get the device token cookie name
+ * @param config - NAuth configuration
+ * @returns Device token cookie name (default: 'nauth_device_token')
+ */
 export declare function getDeviceTokenCookieName(config?: NAuthConfig): string;
+/**
+ * Get the CSRF token cookie name
+ *
+ * If explicitly configured via security.csrf.cookieName, uses that value.
+ * Otherwise, uses the prefix: `${prefix}csrf_token`
+ *
+ * @param config - NAuth configuration
+ * @returns CSRF token cookie name (default: 'nauth_csrf_token')
+ */
 export declare function getCsrfTokenCookieName(config?: NAuthConfig): string;
 //# sourceMappingURL=cookie-names.util.d.ts.map

package/dist/utils/cookie-names.util.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cookie-names.util.d.ts","sourceRoot":"","sources":["../../src/utils/cookie-names.util.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAO7D,wBAAgB,mBAAmB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,MAAM,CAEhE;AAOD,wBAAgB,wBAAwB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,MAAM,CAGrE;AAOD,wBAAgB,yBAAyB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,MAAM,CAGtE;AAOD,wBAAgB,wBAAwB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,MAAM,CAGrE;AAWD,wBAAgB,sBAAsB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,MAAM,CASnE"}
+{"version":3,"file":"cookie-names.util.d.ts","sourceRoot":"","sources":["../../src/utils/cookie-names.util.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAE7D;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,MAAM,CAEhE;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,MAAM,CAGrE;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,MAAM,CAGtE;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,MAAM,CAGrE;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,MAAM,CASnE"}

package/dist/utils/cookie-names.util.js

@@ -1,29 +1,66 @@
 "use strict";
+/**
+ * Cookie Name Utilities
+ *
+ * Provides consistent cookie name generation using the configured prefix.
+ * All cookie names are prefixed to avoid conflicts with other cookies.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getCookieNamePrefix = getCookieNamePrefix;
 exports.getAccessTokenCookieName = getAccessTokenCookieName;
 exports.getRefreshTokenCookieName = getRefreshTokenCookieName;
 exports.getDeviceTokenCookieName = getDeviceTokenCookieName;
 exports.getCsrfTokenCookieName = getCsrfTokenCookieName;
+/**
+ * Get the cookie name prefix from config
+ * @param config - NAuth configuration
+ * @returns Cookie name prefix (default: 'nauth_')
+ */
 function getCookieNamePrefix(config) {
     return config?.tokenDelivery?.cookieNamePrefix || 'nauth_';
 }
+/**
+ * Get the access token cookie name
+ * @param config - NAuth configuration
+ * @returns Access token cookie name (default: 'nauth_access_token')
+ */
 function getAccessTokenCookieName(config) {
     const prefix = getCookieNamePrefix(config);
     return `${prefix}access_token`;
 }
+/**
+ * Get the refresh token cookie name
+ * @param config - NAuth configuration
+ * @returns Refresh token cookie name (default: 'nauth_refresh_token')
+ */
 function getRefreshTokenCookieName(config) {
     const prefix = getCookieNamePrefix(config);
     return `${prefix}refresh_token`;
 }
+/**
+ * Get the device token cookie name
+ * @param config - NAuth configuration
+ * @returns Device token cookie name (default: 'nauth_device_token')
+ */
 function getDeviceTokenCookieName(config) {
     const prefix = getCookieNamePrefix(config);
     return `${prefix}device_token`;
 }
+/**
+ * Get the CSRF token cookie name
+ *
+ * If explicitly configured via security.csrf.cookieName, uses that value.
+ * Otherwise, uses the prefix: `${prefix}csrf_token`
+ *
+ * @param config - NAuth configuration
+ * @returns CSRF token cookie name (default: 'nauth_csrf_token')
+ */
 function getCsrfTokenCookieName(config) {
+    // If explicitly configured, use it
     if (config?.security?.csrf?.cookieName) {
         return config.security.csrf.cookieName;
     }
+    // Otherwise, use prefix
     const prefix = getCookieNamePrefix(config);
     return `${prefix}csrf_token`;
 }

package/dist/utils/cookie-names.util.js.map

@@ -1 +1 @@
-{"version":3,"file":"cookie-names.util.js","sourceRoot":"","sources":["../../src/utils/cookie-names.util.ts"],"names":[],"mappings":";;AAcA,kDAEC;AAOD,4DAGC;AAOD,8DAGC;AAOD,4DAGC;AAWD,wDASC;AApDD,SAAgB,mBAAmB,CAAC,MAAoB;IACtD,OAAO,MAAM,EAAE,aAAa,EAAE,gBAAgB,IAAI,QAAQ,CAAC;AAC7D,CAAC;AAOD,SAAgB,wBAAwB,CAAC,MAAoB;IAC3D,MAAM,MAAM,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC3C,OAAO,GAAG,MAAM,cAAc,CAAC;AACjC,CAAC;AAOD,SAAgB,yBAAyB,CAAC,MAAoB;IAC5D,MAAM,MAAM,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC3C,OAAO,GAAG,MAAM,eAAe,CAAC;AAClC,CAAC;AAOD,SAAgB,wBAAwB,CAAC,MAAoB;IAC3D,MAAM,MAAM,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC3C,OAAO,GAAG,MAAM,cAAc,CAAC;AACjC,CAAC;AAWD,SAAgB,sBAAsB,CAAC,MAAoB;IAEzD,IAAI,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;QACvC,OAAO,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC;IACzC,CAAC;IAGD,MAAM,MAAM,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC3C,OAAO,GAAG,MAAM,YAAY,CAAC;AAC/B,CAAC"}
+{"version":3,"file":"cookie-names.util.js","sourceRoot":"","sources":["../../src/utils/cookie-names.util.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;AASH,kDAEC;AAOD,4DAGC;AAOD,8DAGC;AAOD,4DAGC;AAWD,wDASC;AAzDD;;;;GAIG;AACH,SAAgB,mBAAmB,CAAC,MAAoB;IACtD,OAAO,MAAM,EAAE,aAAa,EAAE,gBAAgB,IAAI,QAAQ,CAAC;AAC7D,CAAC;AAED;;;;GAIG;AACH,SAAgB,wBAAwB,CAAC,MAAoB;IAC3D,MAAM,MAAM,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC3C,OAAO,GAAG,MAAM,cAAc,CAAC;AACjC,CAAC;AAED;;;;GAIG;AACH,SAAgB,yBAAyB,CAAC,MAAoB;IAC5D,MAAM,MAAM,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC3C,OAAO,GAAG,MAAM,eAAe,CAAC;AAClC,CAAC;AAED;;;;GAIG;AACH,SAAgB,wBAAwB,CAAC,MAAoB;IAC3D,MAAM,MAAM,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC3C,OAAO,GAAG,MAAM,cAAc,CAAC;AACjC,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,sBAAsB,CAAC,MAAoB;IACzD,mCAAmC;IACnC,IAAI,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;QACvC,OAAO,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC;IACzC,CAAC;IAED,wBAAwB;IACxB,MAAM,MAAM,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC3C,OAAO,GAAG,MAAM,YAAY,CAAC;AAC/B,CAAC"}

package/dist/utils/cookies.util.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Cookie Utilities
+ *
+ * Helpers for clearing nauth auth cookies in HTTP responses.
+ */
 import { NAuthConfig } from '../interfaces/config.interface';
 export interface CookieOptions {
     domain?: string;
@@ -5,6 +10,20 @@ export interface CookieOptions {
     secure?: boolean;
     sameSite?: 'strict' | 'lax' | 'none';
 }
+/**
+ * Clear nauth auth cookies on the response.
+ *
+ * - Clears access token, refresh token, CSRF token cookies
+ * - Optionally clears device token cookie (only when forgetDevice=true)
+ * - Device token cookies persist across logout by default (remember device feature)
+ * - Applies security attributes consistent with how cookies were set
+ * - Uses configured cookie name prefix (default: 'nauth_')
+ *
+ * @param res - HTTP response object (Express or Fastify compatible)
+ * @param config - NAuth configuration (optional, for cookie name resolution)
+ * @param opt - Optional cookie options to match configured attributes
+ * @param forgetDevice - If true, also clears device token cookie (for "forget me" logout). Default: false
+ */
 export declare function clearAuthCookies(res: {
     cookie?: Function;
     setCookie?: Function;

package/dist/utils/cookies.util.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cookies.util.d.ts","sourceRoot":"","sources":["../../src/utils/cookies.util.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAQ7D,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;CACtC;AAgBD,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE;IAAE,MAAM,CAAC,EAAE,QAAQ,CAAC;IAAC,SAAS,CAAC,EAAE,QAAQ,CAAA;CAAE,EAChD,MAAM,CAAC,EAAE,WAAW,GAAG,aAAa,EACpC,GAAG,CAAC,EAAE,aAAa,EACnB,YAAY,GAAE,OAAe,GAC5B,IAAI,CAqDN"}
+{"version":3,"file":"cookies.util.d.ts","sourceRoot":"","sources":["../../src/utils/cookies.util.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAQ7D,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;CACtC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE;IAAE,MAAM,CAAC,EAAE,QAAQ,CAAC;IAAC,SAAS,CAAC,EAAE,QAAQ,CAAA;CAAE,EAChD,MAAM,CAAC,EAAE,WAAW,GAAG,aAAa,EACpC,GAAG,CAAC,EAAE,aAAa,EACnB,YAAY,GAAE,OAAe,GAC5B,IAAI,CAqDN"}

package/dist/utils/cookies.util.js

@@ -1,15 +1,37 @@
 "use strict";
+/**
+ * Cookie Utilities
+ *
+ * Helpers for clearing nauth auth cookies in HTTP responses.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.clearAuthCookies = clearAuthCookies;
 const cookie_names_util_1 = require("./cookie-names.util");
+/**
+ * Clear nauth auth cookies on the response.
+ *
+ * - Clears access token, refresh token, CSRF token cookies
+ * - Optionally clears device token cookie (only when forgetDevice=true)
+ * - Device token cookies persist across logout by default (remember device feature)
+ * - Applies security attributes consistent with how cookies were set
+ * - Uses configured cookie name prefix (default: 'nauth_')
+ *
+ * @param res - HTTP response object (Express or Fastify compatible)
+ * @param config - NAuth configuration (optional, for cookie name resolution)
+ * @param opt - Optional cookie options to match configured attributes
+ * @param forgetDevice - If true, also clears device token cookie (for "forget me" logout). Default: false
+ */
 function clearAuthCookies(res, config, opt, forgetDevice = false) {
+    // Handle old signature: clearAuthCookies(res, opt) where opt might be config or CookieOptions
     let cookieOptions;
     let nauthConfig;
     if (config && 'tokenDelivery' in config) {
+        // Second param is NAuthConfig
         nauthConfig = config;
         cookieOptions = opt;
     }
     else {
+        // Second param is CookieOptions (backward compatibility)
         cookieOptions = config;
     }
     const base = {
@@ -24,24 +46,29 @@ function clearAuthCookies(res, config, opt, forgetDevice = false) {
     const refreshTokenName = (0, cookie_names_util_1.getRefreshTokenCookieName)(nauthConfig);
     const csrfTokenName = (0, cookie_names_util_1.getCsrfTokenCookieName)(nauthConfig);
     const deviceTokenName = (0, cookie_names_util_1.getDeviceTokenCookieName)(nauthConfig);
+    // CSRF cookie options (httpOnly: false, matches how it was set)
     const csrfBase = {
         ...base,
-        httpOnly: false,
+        httpOnly: false, // CSRF token must be readable by JavaScript
     };
     if (typeof res.cookie === 'function') {
         res.cookie(accessTokenName, '', base);
         res.cookie(refreshTokenName, '', base);
         res.cookie(csrfTokenName, '', csrfBase);
+        // Only clear device token cookie if forgetDevice=true (for "forget me" logout)
+        // Device tokens persist across normal logout (remember device feature)
         if (forgetDevice) {
-            res.cookie(deviceTokenName, '', base);
+            res.cookie(deviceTokenName, '', base); // Device token cookie (httpOnly: true)
         }
     }
     else if (typeof res.setCookie === 'function') {
         res.setCookie(accessTokenName, '', base);
         res.setCookie(refreshTokenName, '', base);
         res.setCookie(csrfTokenName, '', csrfBase);
+        // Only clear device token cookie if forgetDevice=true (for "forget me" logout)
+        // Device tokens persist across normal logout (remember device feature)
         if (forgetDevice) {
-            res.setCookie(deviceTokenName, '', base);
+            res.setCookie(deviceTokenName, '', base); // Device token cookie (httpOnly: true)
         }
     }
 }

package/dist/utils/cookies.util.js.map

@@ -1 +1 @@
-{"version":3,"file":"cookies.util.js","sourceRoot":"","sources":["../../src/utils/cookies.util.ts"],"names":[],"mappings":";;AAmCA,4CA0DC;AAtFD,2DAK6B;AAuB7B,SAAgB,gBAAgB,CAC9B,GAAgD,EAChD,MAAoC,EACpC,GAAmB,EACnB,eAAwB,KAAK;IAG7B,IAAI,aAAwC,CAAC;IAC7C,IAAI,WAAoC,CAAC;IAEzC,IAAI,MAAM,IAAI,eAAe,IAAI,MAAM,EAAE,CAAC;QAExC,WAAW,GAAG,MAAqB,CAAC;QACpC,aAAa,GAAG,GAAG,CAAC;IACtB,CAAC;SAAM,CAAC;QAEN,aAAa,GAAG,MAAmC,CAAC;IACtD,CAAC;IAED,MAAM,IAAI,GAAG;QACX,QAAQ,EAAE,IAAa;QACvB,MAAM,EAAE,aAAa,EAAE,MAAM,KAAK,KAAK;QACvC,QAAQ,EAAE,CAAC,aAAa,EAAE,QAAQ,IAAI,QAAQ,CAA8B;QAC5E,IAAI,EAAE,aAAa,EAAE,IAAI,IAAI,GAAG;QAChC,MAAM,EAAE,aAAa,EAAE,MAAM;QAC7B,MAAM,EAAE,CAAC;KACV,CAAC;IAEF,MAAM,eAAe,GAAG,IAAA,4CAAwB,EAAC,WAAW,CAAC,CAAC;IAC9D,MAAM,gBAAgB,GAAG,IAAA,6CAAyB,EAAC,WAAW,CAAC,CAAC;IAChE,MAAM,aAAa,GAAG,IAAA,0CAAsB,EAAC,WAAW,CAAC,CAAC;IAC1D,MAAM,eAAe,GAAG,IAAA,4CAAwB,EAAC,WAAW,CAAC,CAAC;IAG9D,MAAM,QAAQ,GAAG;QACf,GAAG,IAAI;QACP,QAAQ,EAAE,KAAc;KACzB,CAAC;IAEF,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;QACrC,GAAG,CAAC,MAAM,CAAC,eAAe,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;QACtC,GAAG,CAAC,MAAM,CAAC,gBAAgB,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;QACvC,GAAG,CAAC,MAAM,CAAC,aAAa,EAAE,EAAE,EAAE,QAAQ,CAAC,CAAC;QAGxC,IAAI,YAAY,EAAE,CAAC;YACjB,GAAG,CAAC,MAAM,CAAC,eAAe,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;SAAM,IAAI,OAAO,GAAG,CAAC,SAAS,KAAK,UAAU,EAAE,CAAC;QAC/C,GAAG,CAAC,SAAS,CAAC,eAAe,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;QACzC,GAAG,CAAC,SAAS,CAAC,gBAAgB,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;QAC1C,GAAG,CAAC,SAAS,CAAC,aAAa,EAAE,EAAE,EAAE,QAAQ,CAAC,CAAC;QAG3C,IAAI,YAAY,EAAE,CAAC;YACjB,GAAG,CAAC,SAAS,CAAC,eAAe,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC;AACH,CAAC"}
+{"version":3,"file":"cookies.util.js","sourceRoot":"","sources":["../../src/utils/cookies.util.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AA+BH,4CA0DC;AAtFD,2DAK6B;AAS7B;;;;;;;;;;;;;GAaG;AACH,SAAgB,gBAAgB,CAC9B,GAAgD,EAChD,MAAoC,EACpC,GAAmB,EACnB,eAAwB,KAAK;IAE7B,8FAA8F;IAC9F,IAAI,aAAwC,CAAC;IAC7C,IAAI,WAAoC,CAAC;IAEzC,IAAI,MAAM,IAAI,eAAe,IAAI,MAAM,EAAE,CAAC;QACxC,8BAA8B;QAC9B,WAAW,GAAG,MAAqB,CAAC;QACpC,aAAa,GAAG,GAAG,CAAC;IACtB,CAAC;SAAM,CAAC;QACN,yDAAyD;QACzD,aAAa,GAAG,MAAmC,CAAC;IACtD,CAAC;IAED,MAAM,IAAI,GAAG;QACX,QAAQ,EAAE,IAAa;QACvB,MAAM,EAAE,aAAa,EAAE,MAAM,KAAK,KAAK;QACvC,QAAQ,EAAE,CAAC,aAAa,EAAE,QAAQ,IAAI,QAAQ,CAA8B;QAC5E,IAAI,EAAE,aAAa,EAAE,IAAI,IAAI,GAAG;QAChC,MAAM,EAAE,aAAa,EAAE,MAAM;QAC7B,MAAM,EAAE,CAAC;KACV,CAAC;IAEF,MAAM,eAAe,GAAG,IAAA,4CAAwB,EAAC,WAAW,CAAC,CAAC;IAC9D,MAAM,gBAAgB,GAAG,IAAA,6CAAyB,EAAC,WAAW,CAAC,CAAC;IAChE,MAAM,aAAa,GAAG,IAAA,0CAAsB,EAAC,WAAW,CAAC,CAAC;IAC1D,MAAM,eAAe,GAAG,IAAA,4CAAwB,EAAC,WAAW,CAAC,CAAC;IAE9D,gEAAgE;IAChE,MAAM,QAAQ,GAAG;QACf,GAAG,IAAI;QACP,QAAQ,EAAE,KAAc,EAAE,4CAA4C;KACvE,CAAC;IAEF,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;QACrC,GAAG,CAAC,MAAM,CAAC,eAAe,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;QACtC,GAAG,CAAC,MAAM,CAAC,gBAAgB,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;QACvC,GAAG,CAAC,MAAM,CAAC,aAAa,EAAE,EAAE,EAAE,QAAQ,CAAC,CAAC;QACxC,+EAA+E;QAC/E,uEAAuE;QACvE,IAAI,YAAY,EAAE,CAAC;YACjB,GAAG,CAAC,MAAM,CAAC,eAAe,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,uCAAuC;QAChF,CAAC;IACH,CAAC;SAAM,IAAI,OAAO,GAAG,CAAC,SAAS,KAAK,UAAU,EAAE,CAAC;QAC/C,GAAG,CAAC,SAAS,CAAC,eAAe,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;QACzC,GAAG,CAAC,SAAS,CAAC,gBAAgB,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;QAC1C,GAAG,CAAC,SAAS,CAAC,aAAa,EAAE,EAAE,EAAE,QAAQ,CAAC,CAAC;QAC3C,+EAA+E;QAC/E,uEAAuE;QACvE,IAAI,YAAY,EAAE,CAAC;YACjB,GAAG,CAAC,SAAS,CAAC,eAAe,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,uCAAuC;QACnF,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/utils/index.d.ts

@@ -1,3 +1,6 @@
+/**
+ * Utility Functions and Classes
+ */
 export * from './pii-redactor';
 export * from './ip-extractor';
 export * from './nauth-logger';

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAIA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC"}

package/dist/utils/index.js

@@ -1,4 +1,7 @@
 "use strict";
+/**
+ * Utility Functions and Classes
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -21,4 +24,5 @@ __exportStar(require("./cookies.util"), exports);
 __exportStar(require("./cookie-names.util"), exports);
 __exportStar(require("./context-storage"), exports);
 __exportStar(require("./token-delivery-policy"), exports);
+// user-agent-parser removed - functionality moved to ClientInfoService.parseUserAgent()
 //# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAIA,iDAA+B;AAC/B,iDAA+B;AAC/B,iDAA+B;AAC/B,iDAA+B;AAC/B,sDAAoC;AACpC,oDAAkC;AAClC,0DAAwC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;;;;;;;;;;;;;;AAEH,iDAA+B;AAC/B,iDAA+B;AAC/B,iDAA+B;AAC/B,iDAA+B;AAC/B,sDAAoC;AACpC,oDAAkC;AAClC,0DAAwC;AACxC,wFAAwF"}

package/dist/utils/ip-extractor.d.ts

@@ -1,8 +1,66 @@
+/**
+ * IP Address Extractor
+ *
+ * Extracts the real client IP address from requests, handling:
+ * - Direct connections
+ * - Reverse proxies (Nginx, Apache)
+ * - Load balancers (AWS ALB/NLB, GCP, Azure)
+ * - CDNs (Cloudflare, Fastly, Akamai)
+ *
+ * **Priority Order:**
+ * 1. X-Forwarded-For (standard proxy header)
+ * 2. CF-Connecting-IP (Cloudflare)
+ * 3. X-Real-IP (Nginx proxy)
+ * 4. X-Client-IP (Apache, other proxies)
+ * 5. Fastly-Client-IP (Fastly CDN)
+ * 6. Akamai-Origin-Hop (Akamai CDN)
+ * 7. req.ip (NestJS/Express default)
+ * 8. req.socket.remoteAddress (fallback)
+ *
+ * **Security:**
+ * - Handles multiple proxies (takes leftmost IP)
+ * - Validates IP format
+ * - Filters private/internal IPs (optional)
+ * - Prevents IP spoofing
+ *
+ * @example
+ * ```typescript
+ * import { extractClientIp } from '@nauth-toolkit/core/utils';
+ *
+ * @Post('login')
+ * async login(@Req() req: Request) {
+ *   const ipAddress = extractClientIp(req);
+ *   logger.debug('Client IP:', ipAddress); // Real client IP
+ * }
+ * ```
+ */
+/**
+ * Options for IP extraction
+ */
 export interface IpExtractorOptions {
+    /**
+     * Whether to filter out private/internal IP addresses
+     * Defaults to false
+     */
     filterPrivateIps?: boolean;
+    /**
+     * List of trusted proxy IP addresses or CIDR ranges
+     * If specified, only accepts X-Forwarded-For from these proxies
+     */
     trustedProxies?: string[];
+    /**
+     * Whether to use the leftmost IP in X-Forwarded-For
+     * (true = original client, false = rightmost/last proxy)
+     * Defaults to true
+     */
     useLeftmostIp?: boolean;
 }
+/**
+ * Minimal request shape required for IP extraction.
+ *
+ * We keep this intentionally framework-agnostic (no Express/Fastify types) to avoid
+ * adding hard dependencies from core.
+ */
 interface IpRequestLike extends Record<string, unknown> {
     headers?: Record<string, unknown>;
     ip?: string;
@@ -13,8 +71,38 @@ interface IpRequestLike extends Record<string, unknown> {
         remoteAddress?: string;
     };
 }
+/**
+ * Extracts the real client IP address from an HTTP request
+ *
+ * @param req - Express Request object
+ * @param options - Optional configuration
+ * @returns The client's IP address, or '0.0.0.0' if unable to determine
+ */
 export declare function extractClientIp(req: IpRequestLike, options?: IpExtractorOptions): string;
+/**
+ * Checks if an IP address is private/internal
+ *
+ * Detects:
+ * - Localhost (127.0.0.0/8, ::1)
+ * - Private IPv4 ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
+ * - Link-local addresses (169.254.0.0/16)
+ *
+ * @param ip - IP address to check
+ * @returns True if private, false otherwise
+ *
+ * @example
+ * ```typescript
+ * isPrivateIp('192.168.1.1'); // true
+ * isPrivateIp('8.8.8.8'); // false
+ * ```
+ */
 export declare function isPrivateIp(ip: string): boolean;
+/**
+ * Gets geolocation information for an IP address (placeholder)
+ *
+ * @param ip - IP address
+ * @returns Geolocation info (to be implemented with MaxMind/IP-API)
+ */
 export declare function getIpGeolocation(_ip: string): {
     country?: string;
     city?: string;

package/dist/utils/ip-extractor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ip-extractor.d.ts","sourceRoot":"","sources":["../../src/utils/ip-extractor.ts"],"names":[],"mappings":"AA0CA,MAAM,WAAW,kBAAkB;IAKjC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAM3B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAO1B,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAQD,UAAU,aAAc,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC,UAAU,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACzC;AASD,wBAAgB,eAAe,CAAC,GAAG,EAAE,aAAa,EAAE,OAAO,GAAE,kBAAuB,GAAG,MAAM,CA8D5F;AA8DD,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAe/C;AAQD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAGjF"}
+{"version":3,"file":"ip-extractor.d.ts","sourceRoot":"","sources":["../../src/utils/ip-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAIH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAE1B;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;GAKG;AACH,UAAU,aAAc,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACpC,UAAU,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACzC;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,aAAa,EAAE,OAAO,GAAE,kBAAuB,GAAG,MAAM,CA8D5F;AA6CD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAe/C;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAGjF"}