@nauth-toolkit/core 0.1.14 → 0.1.18

package/dist/utils/setup/init-social.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Social Authentication Provider Initialization
+ *
+ * Dynamically loads and initializes social auth providers based on configuration.
+ */
 import { NAuthConfig, NAuthLogger, SocialAuthService, AuthService, ClientInfoService, AuthAuditService, PhoneVerificationService, BaseUser } from '../../index';
 import { JwtService, SessionService, AuthChallengeHelperService, SocialProviderRegistry, TrustedDeviceService } from '../../internal';
 import { Repository } from 'typeorm';
@@ -7,6 +12,28 @@ export interface NAuthSocialProviders {
     appleAuth?: ISocialAuthProviderService;
     facebookAuth?: ISocialAuthProviderService;
 }
+/**
+ * Initialize and register social authentication providers
+ *
+ * Dynamically imports social provider packages based on configuration.
+ * Each provider is initialized with all required services and registered
+ * with the SocialAuthService registry.
+ *
+ * @param config - NAuth configuration
+ * @param providerRegistry - Social provider registry (internal)
+ * @param authService - Core authentication service
+ * @param socialAuthService - Social authentication service
+ * @param jwtService - JWT token service
+ * @param sessionService - Session management service
+ * @param challengeHelper - Auth challenge helper service
+ * @param clientInfoService - Client information service
+ * @param logger - Logger instance
+ * @param socialAuthStateStore - Shared state store for OAuth CSRF protection
+ * @param phoneVerificationService - Phone verification service (optional)
+ * @param auditService - Audit logging service (optional)
+ * @param trustedDeviceService - Trusted device service (optional)
+ * @returns Object containing initialized social providers
+ */
 export declare function initSocialAuth(config: NAuthConfig, providerRegistry: SocialProviderRegistry, authService: AuthService, socialAuthService: SocialAuthService, jwtService: JwtService, sessionService: SessionService, challengeHelper: AuthChallengeHelperService, clientInfoService: ClientInfoService, logger: NAuthLogger, socialAuthStateStore: Map<string, {
     timestamp: number;
     provider: string;

package/dist/utils/setup/init-social.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init-social.d.ts","sourceRoot":"","sources":["../../../src/utils/setup/init-social.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,WAAW,EACX,WAAW,EACX,iBAAiB,EACjB,WAAW,EACX,iBAAiB,EACjB,gBAAgB,EAChB,wBAAwB,EACxB,QAAQ,EACT,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,UAAU,EACV,cAAc,EACd,0BAA0B,EAC1B,sBAAsB,EACtB,oBAAoB,EACrB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,0BAA0B,EAAE,MAAM,iDAAiD,CAAC;AAG7F,MAAM,WAAW,oBAAoB;IACnC,UAAU,CAAC,EAAE,0BAA0B,CAAC;IACxC,SAAS,CAAC,EAAE,0BAA0B,CAAC;IACvC,YAAY,CAAC,EAAE,0BAA0B,CAAC;CAC3C;AAuCD,wBAAsB,cAAc,CAClC,MAAM,EAAE,WAAW,EACnB,gBAAgB,EAAE,sBAAsB,EACxC,WAAW,EAAE,WAAW,EACxB,iBAAiB,EAAE,iBAAiB,EACpC,UAAU,EAAE,UAAU,EACtB,cAAc,EAAE,cAAc,EAC9B,eAAe,EAAE,0BAA0B,EAC3C,iBAAiB,EAAE,iBAAiB,EACpC,MAAM,EAAE,WAAW,EACnB,oBAAoB,EAAE,GAAG,CAAC,MAAM,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,EAC1E,cAAc,EAAE,UAAU,CAAC,QAAQ,CAAC,EACpC,wBAAwB,CAAC,EAAE,wBAAwB,EACnD,YAAY,CAAC,EAAE,gBAAgB,EAC/B,oBAAoB,CAAC,EAAE,oBAAoB,GAC1C,OAAO,CAAC,oBAAoB,CAAC,CA0J/B"}
+{"version":3,"file":"init-social.d.ts","sourceRoot":"","sources":["../../../src/utils/setup/init-social.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EACL,WAAW,EACX,WAAW,EACX,iBAAiB,EACjB,WAAW,EACX,iBAAiB,EACjB,gBAAgB,EAChB,wBAAwB,EACxB,QAAQ,EACT,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,UAAU,EACV,cAAc,EACd,0BAA0B,EAC1B,sBAAsB,EACtB,oBAAoB,EACrB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,0BAA0B,EAAE,MAAM,iDAAiD,CAAC;AAG7F,MAAM,WAAW,oBAAoB;IACnC,UAAU,CAAC,EAAE,0BAA0B,CAAC;IACxC,SAAS,CAAC,EAAE,0BAA0B,CAAC;IACvC,YAAY,CAAC,EAAE,0BAA0B,CAAC;CAC3C;AAiBD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,WAAW,EACnB,gBAAgB,EAAE,sBAAsB,EACxC,WAAW,EAAE,WAAW,EACxB,iBAAiB,EAAE,iBAAiB,EACpC,UAAU,EAAE,UAAU,EACtB,cAAc,EAAE,cAAc,EAC9B,eAAe,EAAE,0BAA0B,EAC3C,iBAAiB,EAAE,iBAAiB,EACpC,MAAM,EAAE,WAAW,EACnB,oBAAoB,EAAE,GAAG,CAAC,MAAM,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,EAC1E,cAAc,EAAE,UAAU,CAAC,QAAQ,CAAC,EACpC,wBAAwB,CAAC,EAAE,wBAAwB,EACnD,YAAY,CAAC,EAAE,gBAAgB,EAC/B,oBAAoB,CAAC,EAAE,oBAAoB,GAC1C,OAAO,CAAC,oBAAoB,CAAC,CA0J/B"}

package/dist/utils/setup/init-social.js

@@ -1,4 +1,9 @@
 "use strict";
+/**
+ * Social Authentication Provider Initialization
+ *
+ * Dynamically loads and initializes social auth providers based on configuration.
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -34,6 +39,13 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.initSocialAuth = initSocialAuth;
+/**
+ * Import an optional peer dependency at runtime without creating a compile-time
+ * dependency for TypeScript consumers of `@nauth-toolkit/core`.
+ *
+ * IMPORTANT: the module specifier is intentionally typed as `string` (not a literal)
+ * to prevent TypeScript from erroring when the peer dependency isn't installed.
+ */
 async function importOptional(moduleName) {
     try {
         return (await Promise.resolve(`${moduleName}`).then(s => __importStar(require(s))));
@@ -42,8 +54,33 @@ async function importOptional(moduleName) {
         return null;
     }
 }
+/**
+ * Initialize and register social authentication providers
+ *
+ * Dynamically imports social provider packages based on configuration.
+ * Each provider is initialized with all required services and registered
+ * with the SocialAuthService registry.
+ *
+ * @param config - NAuth configuration
+ * @param providerRegistry - Social provider registry (internal)
+ * @param authService - Core authentication service
+ * @param socialAuthService - Social authentication service
+ * @param jwtService - JWT token service
+ * @param sessionService - Session management service
+ * @param challengeHelper - Auth challenge helper service
+ * @param clientInfoService - Client information service
+ * @param logger - Logger instance
+ * @param socialAuthStateStore - Shared state store for OAuth CSRF protection
+ * @param phoneVerificationService - Phone verification service (optional)
+ * @param auditService - Audit logging service (optional)
+ * @param trustedDeviceService - Trusted device service (optional)
+ * @returns Object containing initialized social providers
+ */
 async function initSocialAuth(config, providerRegistry, authService, socialAuthService, jwtService, sessionService, challengeHelper, clientInfoService, logger, socialAuthStateStore, userRepository, phoneVerificationService, auditService, trustedDeviceService) {
     const providers = {};
+    // ============================================================================
+    // Google OAuth Provider
+    // ============================================================================
     if (config.social?.google?.enabled) {
         try {
             const googleModule = await importOptional('@nauth-toolkit/social-google');
@@ -51,9 +88,11 @@ async function initSocialAuth(config, providerRegistry, authService, socialAuthS
                 logger?.warn?.('Google OAuth provider not available. Install @nauth-toolkit/social-google to enable Google authentication.');
                 return providers;
             }
+            // Create token verifier for native mobile token validation
             const tokenVerifier = new googleModule.TokenVerifierService(config);
             const googleAuth = new googleModule.GoogleSocialAuthService(config, logger, authService, socialAuthService, jwtService, sessionService, challengeHelper, clientInfoService, socialAuthStateStore, userRepository, phoneVerificationService, auditService, trustedDeviceService, tokenVerifier);
             providers.googleAuth = googleAuth;
+            // Register with registry
             providerRegistry.registerProvider(googleAuth);
             logger?.debug?.('Google OAuth provider initialized');
         }
@@ -61,6 +100,9 @@ async function initSocialAuth(config, providerRegistry, authService, socialAuthS
             logger?.warn?.('Google OAuth provider not available. Install @nauth-toolkit/social-google to enable Google authentication.');
         }
     }
+    // ============================================================================
+    // Apple Sign-In Provider
+    // ============================================================================
     if (config.social?.apple?.enabled) {
         try {
             const appleModule = await importOptional('@nauth-toolkit/social-apple');
@@ -68,9 +110,11 @@ async function initSocialAuth(config, providerRegistry, authService, socialAuthS
                 logger?.warn?.('Apple Sign-In provider not available. Install @nauth-toolkit/social-apple to enable Apple authentication.');
                 return providers;
             }
+            // Create token verifier for native mobile token validation
             const tokenVerifier = new appleModule.TokenVerifierService(config);
             const appleAuth = new appleModule.AppleSocialAuthService(config, logger, authService, socialAuthService, jwtService, sessionService, challengeHelper, clientInfoService, socialAuthStateStore, userRepository, phoneVerificationService, auditService, trustedDeviceService, tokenVerifier);
             providers.appleAuth = appleAuth;
+            // Register with registry
             providerRegistry.registerProvider(appleAuth);
             logger?.debug?.('Apple Sign-In provider initialized');
         }
@@ -78,6 +122,9 @@ async function initSocialAuth(config, providerRegistry, authService, socialAuthS
             logger?.warn?.('Apple Sign-In provider not available. Install @nauth-toolkit/social-apple to enable Apple authentication.');
         }
     }
+    // ============================================================================
+    // Facebook OAuth Provider
+    // ============================================================================
     if (config.social?.facebook?.enabled) {
         try {
             const facebookModule = await importOptional('@nauth-toolkit/social-facebook');
@@ -85,9 +132,11 @@ async function initSocialAuth(config, providerRegistry, authService, socialAuthS
                 logger?.warn?.('Facebook OAuth provider not available. Install @nauth-toolkit/social-facebook to enable Facebook authentication.');
                 return providers;
             }
+            // Create token verifier for native mobile token validation
             const tokenVerifier = new facebookModule.TokenVerifierService(config);
             const facebookAuth = new facebookModule.FacebookSocialAuthService(config, logger, authService, socialAuthService, jwtService, sessionService, challengeHelper, clientInfoService, socialAuthStateStore, userRepository, phoneVerificationService, auditService, trustedDeviceService, tokenVerifier);
             providers.facebookAuth = facebookAuth;
+            // Register with registry
             providerRegistry.registerProvider(facebookAuth);
             logger?.debug?.('Facebook OAuth provider initialized');
         }

package/dist/utils/setup/init-social.js.map

@@ -1 +1 @@
-{"version":3,"file":"init-social.js","sourceRoot":"","sources":["../../../src/utils/setup/init-social.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"init-social.js","sourceRoot":"","sources":["../../../src/utils/setup/init-social.ts"],"names":[],"mappings":"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"}

package/dist/utils/setup/init-storage.d.ts

@@ -1,4 +1,26 @@
+/**
+ * Storage Adapter Initialization Helper
+ *
+ * Initializes storage adapter with repository injection and proper error handling.
+ */
 import { Repository, type ObjectLiteral } from 'typeorm';
 import { StorageAdapter, LoggerService, NAuthConfig } from '../../index';
+/**
+ * Initialize storage adapter
+ *
+ * Handles:
+ * - Logger injection (if adapter supports it)
+ * - Repository injection (for DatabaseStorageAdapter)
+ * - Adapter initialization
+ * - Fallback to DatabaseStorageAdapter if no adapter provided and repositories available
+ * - Error if no adapter and no repositories (prevents unsafe defaults)
+ *
+ * @param config - NAuth configuration
+ * @param rateLimitRepo - RateLimit repository (nullable)
+ * @param storageLockRepo - StorageLock repository (nullable)
+ * @param logger - Logger instance
+ * @returns Initialized StorageAdapter
+ * @throws {NAuthException} If no adapter provided and DatabaseStorageAdapter cannot be created
+ */
 export declare function initStorage(config: NAuthConfig, rateLimitRepo: Repository<ObjectLiteral> | null, storageLockRepo: Repository<ObjectLiteral> | null, logger: LoggerService): Promise<StorageAdapter>;
 //# sourceMappingURL=init-storage.d.ts.map

package/dist/utils/setup/init-storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init-storage.d.ts","sourceRoot":"","sources":["../../../src/utils/setup/init-storage.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,WAAW,EAAiC,MAAM,aAAa,CAAC;AAkCxG,wBAAsB,WAAW,CAC/B,MAAM,EAAE,WAAW,EACnB,aAAa,EAAE,UAAU,CAAC,aAAa,CAAC,GAAG,IAAI,EAC/C,eAAe,EAAE,UAAU,CAAC,aAAa,CAAC,GAAG,IAAI,EACjD,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,cAAc,CAAC,CAqFzB"}
+{"version":3,"file":"init-storage.d.ts","sourceRoot":"","sources":["../../../src/utils/setup/init-storage.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,WAAW,EAAiC,MAAM,aAAa,CAAC;AAiBxG;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,WAAW,EACnB,aAAa,EAAE,UAAU,CAAC,aAAa,CAAC,GAAG,IAAI,EAC/C,eAAe,EAAE,UAAU,CAAC,aAAa,CAAC,GAAG,IAAI,EACjD,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,cAAc,CAAC,CAqFzB"}

package/dist/utils/setup/init-storage.js

@@ -1,4 +1,9 @@
 "use strict";
+/**
+ * Storage Adapter Initialization Helper
+ *
+ * Initializes storage adapter with repository injection and proper error handling.
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -35,6 +40,13 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.initStorage = initStorage;
 const index_1 = require("../../index");
+/**
+ * Import an optional peer dependency at runtime without creating a compile-time
+ * dependency for TypeScript consumers of `@nauth-toolkit/core`.
+ *
+ * IMPORTANT: the module specifier is intentionally typed as `string` (not a literal)
+ * to prevent TypeScript from erroring when the peer dependency isn't installed.
+ */
 async function importOptional(moduleName) {
     try {
         return (await Promise.resolve(`${moduleName}`).then(s => __importStar(require(s))));
@@ -43,15 +55,35 @@ async function importOptional(moduleName) {
         return null;
     }
 }
+/**
+ * Initialize storage adapter
+ *
+ * Handles:
+ * - Logger injection (if adapter supports it)
+ * - Repository injection (for DatabaseStorageAdapter)
+ * - Adapter initialization
+ * - Fallback to DatabaseStorageAdapter if no adapter provided and repositories available
+ * - Error if no adapter and no repositories (prevents unsafe defaults)
+ *
+ * @param config - NAuth configuration
+ * @param rateLimitRepo - RateLimit repository (nullable)
+ * @param storageLockRepo - StorageLock repository (nullable)
+ * @param logger - Logger instance
+ * @returns Initialized StorageAdapter
+ * @throws {NAuthException} If no adapter provided and DatabaseStorageAdapter cannot be created
+ */
 async function initStorage(config, rateLimitRepo, storageLockRepo, logger) {
+    // If storage adapter explicitly provided, use it
     if (config.storageAdapter) {
         const adapter = config.storageAdapter;
+        // Inject logger if adapter supports it
         {
             const maybeLoggerAware = adapter;
             if (typeof maybeLoggerAware.setLogger === 'function') {
                 maybeLoggerAware.setLogger(logger);
             }
         }
+        // Inject repositories into DatabaseStorageAdapter if it supports it
         {
             const maybeRepoAware = adapter;
             if (typeof maybeRepoAware.setRepositories === 'function' && rateLimitRepo && storageLockRepo) {
@@ -61,8 +93,10 @@ async function initStorage(config, rateLimitRepo, storageLockRepo, logger) {
         await adapter.initialize();
         return adapter;
     }
+    // No storage adapter provided - try to use DatabaseStorageAdapter if repositories available
     if (rateLimitRepo && storageLockRepo) {
         try {
+            // Lazy import to avoid bundling if not used
             const mod = await importOptional('@nauth-toolkit/storage-database');
             if (!mod) {
                 throw new Error('storage-database package not installed');
@@ -77,9 +111,11 @@ async function initStorage(config, rateLimitRepo, storageLockRepo, logger) {
             return adapter;
         }
         catch (error) {
+            // If DatabaseStorageAdapter import fails, fall through to error
             logger?.error?.('Failed to create DatabaseStorageAdapter. Please explicitly configure storageAdapter in your config.', { error: error });
         }
     }
+    // No storage adapter provided and no repositories available - REQUIRE explicit configuration
     throw new index_1.NAuthException(index_1.AuthErrorCode.VALIDATION_FAILED, 'Storage adapter is REQUIRED for production deployments. ' +
         'MemoryStorageAdapter is NOT safe for production (data lost on restart, not shared across instances). ' +
         'Please configure storageAdapter in your NAuthConfig:\n\n' +

package/dist/utils/setup/init-storage.js.map

@@ -1 +1 @@
-{"version":3,"file":"init-storage.js","sourceRoot":"","sources":["../../../src/utils/setup/init-storage.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,kCA0FC;AA5HD,uCAAwG;AASxG,KAAK,UAAU,cAAc,CAAU,UAAkB;IACvD,IAAI,CAAC;QACH,OAAO,CAAC,yBAAa,UAAU,uCAAC,CAAuB,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAmBM,KAAK,UAAU,WAAW,CAC/B,MAAmB,EACnB,aAA+C,EAC/C,eAAiD,EACjD,MAAqB;IAGrB,IAAI,MAAM,CAAC,cAAc,EAAE,CAAC;QAC1B,MAAM,OAAO,GAAG,MAAM,CAAC,cAAc,CAAC;QAGtC,CAAC;YACC,MAAM,gBAAgB,GAAG,OAA0D,CAAC;YACpF,IAAI,OAAO,gBAAgB,CAAC,SAAS,KAAK,UAAU,EAAE,CAAC;gBACrD,gBAAgB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;YACrC,CAAC;QACH,CAAC;QAGD,CAAC;YACC,MAAM,cAAc,GAAG,OAKtB,CAAC;YACF,IAAI,OAAO,cAAc,CAAC,eAAe,KAAK,UAAU,IAAI,aAAa,IAAI,eAAe,EAAE,CAAC;gBAC7F,cAAc,CAAC,eAAe,CAAC,aAAa,EAAE,eAAe,CAAC,CAAC;YACjE,CAAC;QACH,CAAC;QAED,MAAM,OAAO,CAAC,UAAU,EAAE,CAAC;QAC3B,OAAO,OAAO,CAAC;IACjB,CAAC;IAGD,IAAI,aAAa,IAAI,eAAe,EAAE,CAAC;QACrC,IAAI,CAAC;YAWH,MAAM,GAAG,GAAG,MAAM,cAAc,CAA+B,iCAA2C,CAAC,CAAC;YAC5G,IAAI,CAAC,GAAG,EAAE,CAAC;gBACT,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;YAC5D,CAAC;YAED,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,sBAAsB,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;YACnE,IAAI,OAAO,OAAO,CAAC,eAAe,KAAK,UAAU,EAAE,CAAC;gBAClD,OAAO,CAAC,eAAe,CAAC,aAAa,EAAE,eAAe,CAAC,CAAC;YAC1D,CAAC;YACD,MAAM,OAAO,CAAC,UAAU,EAAE,CAAC;YAE3B,MAAM,EAAE,IAAI,EAAE,CACZ,kFAAkF;gBAChF,qEAAqE,CACxE,CAAC;YAEF,OAAO,OAAO,CAAC;QACjB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAEf,MAAM,EAAE,KAAK,EAAE,CACb,qGAAqG,EACrG,EAAE,KAAK,EAAE,KAAc,EAAE,CAC1B,CAAC;QACJ,CAAC;IACH,CAAC;IAGD,MAAM,IAAI,sBAAc,CACtB,qBAAa,CAAC,iBAAiB,EAC/B,0DAA0D;QACxD,uGAAuG;QACvG,0DAA0D;QAC1D,yEAAyE;QACzE,4EAA4E;QAC5E,sDAAsD;QACtD,iFAAiF;QACjF,yEAAyE;QACzE,wEAAwE;QACxE,2EAA2E;QAC3E,kGAAkG;QAClG,4EAA4E,CAC/E,CAAC;AACJ,CAAC"}
+{"version":3,"file":"init-storage.js","sourceRoot":"","sources":["../../../src/utils/setup/init-storage.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCH,kCA0FC;AA5HD,uCAAwG;AAExG;;;;;;GAMG;AACH,KAAK,UAAU,cAAc,CAAU,UAAkB;IACvD,IAAI,CAAC;QACH,OAAO,CAAC,yBAAa,UAAU,uCAAC,CAAuB,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACI,KAAK,UAAU,WAAW,CAC/B,MAAmB,EACnB,aAA+C,EAC/C,eAAiD,EACjD,MAAqB;IAErB,iDAAiD;IACjD,IAAI,MAAM,CAAC,cAAc,EAAE,CAAC;QAC1B,MAAM,OAAO,GAAG,MAAM,CAAC,cAAc,CAAC;QAEtC,uCAAuC;QACvC,CAAC;YACC,MAAM,gBAAgB,GAAG,OAA0D,CAAC;YACpF,IAAI,OAAO,gBAAgB,CAAC,SAAS,KAAK,UAAU,EAAE,CAAC;gBACrD,gBAAgB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;YACrC,CAAC;QACH,CAAC;QAED,oEAAoE;QACpE,CAAC;YACC,MAAM,cAAc,GAAG,OAKtB,CAAC;YACF,IAAI,OAAO,cAAc,CAAC,eAAe,KAAK,UAAU,IAAI,aAAa,IAAI,eAAe,EAAE,CAAC;gBAC7F,cAAc,CAAC,eAAe,CAAC,aAAa,EAAE,eAAe,CAAC,CAAC;YACjE,CAAC;QACH,CAAC;QAED,MAAM,OAAO,CAAC,UAAU,EAAE,CAAC;QAC3B,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,4FAA4F;IAC5F,IAAI,aAAa,IAAI,eAAe,EAAE,CAAC;QACrC,IAAI,CAAC;YAUH,4CAA4C;YAC5C,MAAM,GAAG,GAAG,MAAM,cAAc,CAA+B,iCAA2C,CAAC,CAAC;YAC5G,IAAI,CAAC,GAAG,EAAE,CAAC;gBACT,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;YAC5D,CAAC;YAED,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,sBAAsB,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;YACnE,IAAI,OAAO,OAAO,CAAC,eAAe,KAAK,UAAU,EAAE,CAAC;gBAClD,OAAO,CAAC,eAAe,CAAC,aAAa,EAAE,eAAe,CAAC,CAAC;YAC1D,CAAC;YACD,MAAM,OAAO,CAAC,UAAU,EAAE,CAAC;YAE3B,MAAM,EAAE,IAAI,EAAE,CACZ,kFAAkF;gBAChF,qEAAqE,CACxE,CAAC;YAEF,OAAO,OAAO,CAAC;QACjB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,gEAAgE;YAChE,MAAM,EAAE,KAAK,EAAE,CACb,qGAAqG,EACrG,EAAE,KAAK,EAAE,KAAc,EAAE,CAC1B,CAAC;QACJ,CAAC;IACH,CAAC;IAED,6FAA6F;IAC7F,MAAM,IAAI,sBAAc,CACtB,qBAAa,CAAC,iBAAiB,EAC/B,0DAA0D;QACxD,uGAAuG;QACvG,0DAA0D;QAC1D,yEAAyE;QACzE,4EAA4E;QAC5E,sDAAsD;QACtD,iFAAiF;QACjF,yEAAyE;QACzE,wEAAwE;QACxE,2EAA2E;QAC3E,kGAAkG;QAClG,4EAA4E,CAC/E,CAAC;AACJ,CAAC"}

package/dist/utils/setup/register-mfa.d.ts

@@ -1,5 +1,27 @@
+/**
+ * MFA Provider Registration
+ *
+ * Dynamically loads and registers MFA providers with the MFAService.
+ */
 import { Repository } from 'typeorm';
 import { NAuthConfig, NAuthLogger, MFAService, BaseMFADevice, BaseUser, PhoneVerificationService, EmailVerificationService, AuthAuditService, ClientInfoService } from '../../index';
 import { PasswordService, ChallengeService } from '../../internal';
+/**
+ * Register MFA providers with the MFA service
+ *
+ * Dynamically imports MFA provider packages based on configuration.
+ * Each provider is initialized with required services and registered.
+ *
+ * @param config - NAuth configuration
+ * @param mfaService - MFA management service
+ * @param mfaDeviceRepository - MFA device repository
+ * @param userRepository - User repository
+ * @param logger - Logger instance
+ * @param passwordService - Password service (required by base provider)
+ * @param phoneVerificationService - Phone verification service (optional, for SMS MFA)
+ * @param challengeService - Challenge service (optional)
+ * @param auditService - Audit service (optional)
+ * @param clientInfoService - Client info service (optional)
+ */
 export declare function registerMFAProviders(config: NAuthConfig, mfaService: MFAService, mfaDeviceRepository: Repository<BaseMFADevice>, userRepository: Repository<BaseUser>, logger: NAuthLogger, passwordService: PasswordService, emailVerificationService: EmailVerificationService, phoneVerificationService?: PhoneVerificationService, challengeService?: ChallengeService, auditService?: AuthAuditService, clientInfoService?: ClientInfoService): Promise<void>;
 //# sourceMappingURL=register-mfa.d.ts.map

package/dist/utils/setup/register-mfa.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"register-mfa.d.ts","sourceRoot":"","sources":["../../../src/utils/setup/register-mfa.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErC,OAAO,EACL,WAAW,EACX,WAAW,EACX,UAAU,EACV,aAAa,EACb,QAAQ,EACR,wBAAwB,EACxB,wBAAwB,EACxB,gBAAgB,EAChB,iBAAiB,EAElB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAkCnE,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,WAAW,EACnB,UAAU,EAAE,UAAU,EACtB,mBAAmB,EAAE,UAAU,CAAC,aAAa,CAAC,EAC9C,cAAc,EAAE,UAAU,CAAC,QAAQ,CAAC,EACpC,MAAM,EAAE,WAAW,EACnB,eAAe,EAAE,eAAe,EAChC,wBAAwB,EAAE,wBAAwB,EAClD,wBAAwB,CAAC,EAAE,wBAAwB,EACnD,gBAAgB,CAAC,EAAE,gBAAgB,EACnC,YAAY,CAAC,EAAE,gBAAgB,EAC/B,iBAAiB,CAAC,EAAE,iBAAiB,GACpC,OAAO,CAAC,IAAI,CAAC,CA0If"}
+{"version":3,"file":"register-mfa.d.ts","sourceRoot":"","sources":["../../../src/utils/setup/register-mfa.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAErC,OAAO,EACL,WAAW,EACX,WAAW,EACX,UAAU,EACV,aAAa,EACb,QAAQ,EACR,wBAAwB,EACxB,wBAAwB,EACxB,gBAAgB,EAChB,iBAAiB,EAElB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAiBnE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,WAAW,EACnB,UAAU,EAAE,UAAU,EACtB,mBAAmB,EAAE,UAAU,CAAC,aAAa,CAAC,EAC9C,cAAc,EAAE,UAAU,CAAC,QAAQ,CAAC,EACpC,MAAM,EAAE,WAAW,EACnB,eAAe,EAAE,eAAe,EAChC,wBAAwB,EAAE,wBAAwB,EAClD,wBAAwB,CAAC,EAAE,wBAAwB,EACnD,gBAAgB,CAAC,EAAE,gBAAgB,EACnC,YAAY,CAAC,EAAE,gBAAgB,EAC/B,iBAAiB,CAAC,EAAE,iBAAiB,GACpC,OAAO,CAAC,IAAI,CAAC,CA0If"}

package/dist/utils/setup/register-mfa.js

@@ -1,4 +1,9 @@
 "use strict";
+/**
+ * MFA Provider Registration
+ *
+ * Dynamically loads and registers MFA providers with the MFAService.
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -34,6 +39,13 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerMFAProviders = registerMFAProviders;
+/**
+ * Import an optional peer dependency at runtime without creating a compile-time
+ * dependency for TypeScript consumers of `@nauth-toolkit/core`.
+ *
+ * IMPORTANT: the module specifier is intentionally typed as `string` (not a literal)
+ * to prevent TypeScript from erroring when the peer dependency isn't installed.
+ */
 async function importOptional(moduleName) {
     try {
         return (await Promise.resolve(`${moduleName}`).then(s => __importStar(require(s))));
@@ -42,10 +54,30 @@ async function importOptional(moduleName) {
         return null;
     }
 }
+/**
+ * Register MFA providers with the MFA service
+ *
+ * Dynamically imports MFA provider packages based on configuration.
+ * Each provider is initialized with required services and registered.
+ *
+ * @param config - NAuth configuration
+ * @param mfaService - MFA management service
+ * @param mfaDeviceRepository - MFA device repository
+ * @param userRepository - User repository
+ * @param logger - Logger instance
+ * @param passwordService - Password service (required by base provider)
+ * @param phoneVerificationService - Phone verification service (optional, for SMS MFA)
+ * @param challengeService - Challenge service (optional)
+ * @param auditService - Audit service (optional)
+ * @param clientInfoService - Client info service (optional)
+ */
 async function registerMFAProviders(config, mfaService, mfaDeviceRepository, userRepository, logger, passwordService, emailVerificationService, phoneVerificationService, challengeService, auditService, clientInfoService) {
     if (!config.mfa?.enabled) {
         return;
     }
+    // ============================================================================
+    // TOTP MFA Provider
+    // ============================================================================
     try {
         const mod = await importOptional('@nauth-toolkit/mfa-totp');
         if (!mod) {
@@ -61,6 +93,9 @@ async function registerMFAProviders(config, mfaService, mfaDeviceRepository, use
     catch {
         logger?.warn?.('TOTP MFA package not found. Install @nauth-toolkit/mfa-totp to enable TOTP MFA.');
     }
+    // ============================================================================
+    // SMS MFA Provider
+    // ============================================================================
     if (phoneVerificationService) {
         try {
             const mod = await importOptional('@nauth-toolkit/mfa-sms');
@@ -80,6 +115,9 @@ async function registerMFAProviders(config, mfaService, mfaDeviceRepository, use
     else {
         logger?.debug?.('Phone verification service not configured. Skipping SMS MFA registration.');
     }
+    // ============================================================================
+    // Email MFA Provider
+    // ============================================================================
     try {
         const mod = await importOptional('@nauth-toolkit/mfa-email');
         if (!mod) {
@@ -94,6 +132,9 @@ async function registerMFAProviders(config, mfaService, mfaDeviceRepository, use
     catch {
         logger?.warn?.('Email MFA package not found. Install @nauth-toolkit/mfa-email to enable Email MFA.');
     }
+    // ============================================================================
+    // Passkey MFA Provider
+    // ============================================================================
     try {
         const mod = await importOptional('@nauth-toolkit/mfa-passkey');
         if (!mod) {

package/dist/utils/setup/register-mfa.js.map

@@ -1 +1 @@
-{"version":3,"file":"register-mfa.js","sourceRoot":"","sources":["../../../src/utils/setup/register-mfa.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"register-mfa.js","sourceRoot":"","sources":["../../../src/utils/setup/register-mfa.ts"],"names":[],"mappings":"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"}

package/dist/utils/setup/run-nauth-migrations.d.ts

@@ -1,5 +1,12 @@
 import type { DataSource } from 'typeorm';
 import type { NAuthConfig } from '../../interfaces/config.interface';
 import type { NAuthLogger } from '../nauth-logger';
+/**
+ * Runs nauth-toolkit migrations automatically on startup (zero consumer burden).
+ *
+ * @remarks
+ * This dynamically loads the database-specific adapter package and asks it to run its
+ * own adapter-owned migrations into the provided `DataSource`.
+ */
 export declare function runNAuthMigrationsOnStartup(config: NAuthConfig, dataSource: DataSource, logger: NAuthLogger): Promise<void>;
 //# sourceMappingURL=run-nauth-migrations.d.ts.map

package/dist/utils/setup/run-nauth-migrations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-nauth-migrations.d.ts","sourceRoot":"","sources":["../../../src/utils/setup/run-nauth-migrations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AACrE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAqBnD,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,WAAW,EACnB,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,IAAI,CAAC,CAiCf"}
+{"version":3,"file":"run-nauth-migrations.d.ts","sourceRoot":"","sources":["../../../src/utils/setup/run-nauth-migrations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AACrE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAcnD;;;;;;GAMG;AACH,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,WAAW,EACnB,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,IAAI,CAAC,CAiCf"}

package/dist/utils/setup/run-nauth-migrations.js

@@ -40,6 +40,13 @@ function getDbType(dataSource) {
         return type;
     return null;
 }
+/**
+ * Runs nauth-toolkit migrations automatically on startup (zero consumer burden).
+ *
+ * @remarks
+ * This dynamically loads the database-specific adapter package and asks it to run its
+ * own adapter-owned migrations into the provided `DataSource`.
+ */
 async function runNAuthMigrationsOnStartup(config, dataSource, logger) {
     if (!dataSource.isInitialized) {
         logger.warn('[nauth-toolkit] DataSource not initialized; skipping migrations');
@@ -53,6 +60,7 @@ async function runNAuthMigrationsOnStartup(config, dataSource, logger) {
     const adapterPackageName = dbType === 'postgres' ? '@nauth-toolkit/database-typeorm-postgres' : '@nauth-toolkit/database-typeorm-mysql';
     let imported;
     try {
+        // NOTE: use a variable import (not a string literal) to avoid hard dependency from core -> adapter packages
         imported = (await Promise.resolve(`${adapterPackageName}`).then(s => __importStar(require(s))));
     }
     catch (err) {

package/dist/utils/setup/run-nauth-migrations.js.map

@@ -1 +1 @@
-{"version":3,"file":"run-nauth-migrations.js","sourceRoot":"","sources":["../../../src/utils/setup/run-nauth-migrations.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuBA,kEAqCC;AAtDD,SAAS,SAAS,CAAC,UAAsB;IACvC,MAAM,IAAI,GAAI,UAAU,CAAC,OAA0C,EAAE,IAAI,CAAC;IAC1E,IAAI,IAAI,KAAK,UAAU,IAAI,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAC/E,OAAO,IAAI,CAAC;AACd,CAAC;AAaM,KAAK,UAAU,2BAA2B,CAC/C,MAAmB,EACnB,UAAsB,EACtB,MAAmB;IAEnB,IAAI,CAAC,UAAU,CAAC,aAAa,EAAE,CAAC;QAC9B,MAAM,CAAC,IAAI,CAAC,iEAAiE,CAAC,CAAC;QAC/E,OAAO;IACT,CAAC;IAED,MAAM,MAAM,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC;IACrC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,CAAC,KAAK,CACV,6EAA6E,MAAM,CAChF,UAAU,CAAC,OAA0C,EAAE,IAAI,CAC7D,EAAE,CACJ,CAAC;QACF,OAAO;IACT,CAAC;IAED,MAAM,kBAAkB,GACtB,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,0CAA0C,CAAC,CAAC,CAAC,uCAAuC,CAAC;IAE/G,IAAI,QAA+B,CAAC;IACpC,IAAI,CAAC;QAEH,QAAQ,GAAG,CAAC,yBAAa,kBAAkB,uCAAC,CAAqC,CAAC;IACpF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,MAAM,IAAI,KAAK,CAAC,oDAAoD,kBAAkB,KAAK,OAAO,EAAE,CAAC,CAAC;IACxG,CAAC;IAED,IAAI,OAAO,QAAQ,CAAC,kBAAkB,KAAK,UAAU,EAAE,CAAC;QACtD,MAAM,IAAI,KAAK,CAAC,qCAAqC,kBAAkB,uCAAuC,CAAC,CAAC;IAClH,CAAC;IAED,MAAM,QAAQ,CAAC,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAChE,CAAC"}
+{"version":3,"file":"run-nauth-migrations.js","sourceRoot":"","sources":["../../../src/utils/setup/run-nauth-migrations.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuBA,kEAqCC;AAtDD,SAAS,SAAS,CAAC,UAAsB;IACvC,MAAM,IAAI,GAAI,UAAU,CAAC,OAA0C,EAAE,IAAI,CAAC;IAC1E,IAAI,IAAI,KAAK,UAAU,IAAI,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAC/E,OAAO,IAAI,CAAC;AACd,CAAC;AAMD;;;;;;GAMG;AACI,KAAK,UAAU,2BAA2B,CAC/C,MAAmB,EACnB,UAAsB,EACtB,MAAmB;IAEnB,IAAI,CAAC,UAAU,CAAC,aAAa,EAAE,CAAC;QAC9B,MAAM,CAAC,IAAI,CAAC,iEAAiE,CAAC,CAAC;QAC/E,OAAO;IACT,CAAC;IAED,MAAM,MAAM,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC;IACrC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,CAAC,KAAK,CACV,6EAA6E,MAAM,CAChF,UAAU,CAAC,OAA0C,EAAE,IAAI,CAC7D,EAAE,CACJ,CAAC;QACF,OAAO;IACT,CAAC;IAED,MAAM,kBAAkB,GACtB,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,0CAA0C,CAAC,CAAC,CAAC,uCAAuC,CAAC;IAE/G,IAAI,QAA+B,CAAC;IACpC,IAAI,CAAC;QACH,4GAA4G;QAC5G,QAAQ,GAAG,CAAC,yBAAa,kBAAkB,uCAAC,CAAqC,CAAC;IACpF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,MAAM,IAAI,KAAK,CAAC,oDAAoD,kBAAkB,KAAK,OAAO,EAAE,CAAC,CAAC;IACxG,CAAC;IAED,IAAI,OAAO,QAAQ,CAAC,kBAAkB,KAAK,UAAU,EAAE,CAAC;QACtD,MAAM,IAAI,KAAK,CAAC,qCAAqC,kBAAkB,uCAAuC,CAAC,CAAC;IAClH,CAAC;IAED,MAAM,QAAQ,CAAC,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAChE,CAAC"}

package/dist/utils/token-delivery-policy.d.ts

@@ -1,6 +1,23 @@
+/**
+ * Token Delivery Policy Resolution
+ *
+ * Framework-agnostic utility to determine per-request token delivery:
+ * - 'cookies' for web browser origins
+ * - 'json' for native/mobile or non-web clients
+ *
+ * Uses only generic request shape (headers.origin) to avoid express/fastify types.
+ */
 export interface HybridPolicy {
+    /** Allowed web SPA origins (cookies) */
     webOrigins?: string[];
+    /** Allowed native or non-web origins (json tokens) */
     nativeOrigins?: string[];
 }
+/**
+ * Resolve effective delivery for a request in hybrid mode.
+ *
+ * Safe default: return 'cookies' when origin is unknown or not matched.
+ * This avoids leaking tokens to browsers by default.
+ */
 export declare function resolveDeliveryForRequest(req: unknown, policy?: HybridPolicy): 'cookies' | 'json';
 //# sourceMappingURL=token-delivery-policy.d.ts.map

package/dist/utils/token-delivery-policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"token-delivery-policy.d.ts","sourceRoot":"","sources":["../../src/utils/token-delivery-policy.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,YAAY;IAE3B,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IAEtB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAQD,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,SAAS,GAAG,MAAM,CAcjG"}
+{"version":3,"file":"token-delivery-policy.d.ts","sourceRoot":"","sources":["../../src/utils/token-delivery-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,YAAY;IAC3B,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,sDAAsD;IACtD,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,SAAS,GAAG,MAAM,CAcjG"}

package/dist/utils/token-delivery-policy.js

@@ -1,15 +1,32 @@
 "use strict";
+/**
+ * Token Delivery Policy Resolution
+ *
+ * Framework-agnostic utility to determine per-request token delivery:
+ * - 'cookies' for web browser origins
+ * - 'json' for native/mobile or non-web clients
+ *
+ * Uses only generic request shape (headers.origin) to avoid express/fastify types.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveDeliveryForRequest = resolveDeliveryForRequest;
+/**
+ * Resolve effective delivery for a request in hybrid mode.
+ *
+ * Safe default: return 'cookies' when origin is unknown or not matched.
+ * This avoids leaking tokens to browsers by default.
+ */
 function resolveDeliveryForRequest(req, policy) {
     const r = req;
     const origin = r?.headers?.origin || '';
+    // Prefer explicit origin classification
     if (policy?.nativeOrigins && policy.nativeOrigins.includes(origin)) {
         return 'json';
     }
     if (policy?.webOrigins && policy.webOrigins.includes(origin)) {
         return 'cookies';
     }
+    // Default safe posture: treat as web (cookies only)
     return 'cookies';
 }
 //# sourceMappingURL=token-delivery-policy.js.map

package/dist/utils/token-delivery-policy.js.map

@@ -1 +1 @@
-{"version":3,"file":"token-delivery-policy.js","sourceRoot":"","sources":["../../src/utils/token-delivery-policy.ts"],"names":[],"mappings":";;AAuBA,8DAcC;AAdD,SAAgB,yBAAyB,CAAC,GAAY,EAAE,MAAqB;IAC3E,MAAM,CAAC,GAAG,GAAwD,CAAC;IACnE,MAAM,MAAM,GAAI,CAAC,EAAE,OAAO,EAAE,MAAiB,IAAI,EAAE,CAAC;IAGpD,IAAI,MAAM,EAAE,aAAa,IAAI,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QACnE,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,IAAI,MAAM,EAAE,UAAU,IAAI,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7D,OAAO,SAAS,CAAC;IACnB,CAAC;IAGD,OAAO,SAAS,CAAC;AACnB,CAAC"}
+{"version":3,"file":"token-delivery-policy.js","sourceRoot":"","sources":["../../src/utils/token-delivery-policy.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;AAeH,8DAcC;AApBD;;;;;GAKG;AACH,SAAgB,yBAAyB,CAAC,GAAY,EAAE,MAAqB;IAC3E,MAAM,CAAC,GAAG,GAAwD,CAAC;IACnE,MAAM,MAAM,GAAI,CAAC,EAAE,OAAO,EAAE,MAAiB,IAAI,EAAE,CAAC;IAEpD,wCAAwC;IACxC,IAAI,MAAM,EAAE,aAAa,IAAI,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QACnE,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,IAAI,MAAM,EAAE,UAAU,IAAI,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7D,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,oDAAoD;IACpD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/utils.d.ts

@@ -1,2 +1,10 @@
+/**
+ * Utilities barrel export (shim)
+ *
+ * This file exists to ensure TypeScript's emitted declaration paths (e.g. `./utils.js`)
+ * resolve correctly for consumers.
+ *
+ * See `packages/core/src/dto.ts` for background.
+ */
 export * from './utils/index';
 //# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAQA,cAAc,eAAe,CAAC"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,cAAc,eAAe,CAAC"}

package/dist/utils.js

@@ -14,5 +14,13 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Utilities barrel export (shim)
+ *
+ * This file exists to ensure TypeScript's emitted declaration paths (e.g. `./utils.js`)
+ * resolve correctly for consumers.
+ *
+ * See `packages/core/src/dto.ts` for background.
+ */
 __exportStar(require("./utils/index"), exports);
 //# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAQA,gDAA8B"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;;;;GAOG;AACH,gDAA8B"}