@nauth-toolkit/core 0.1.0 → 0.1.3

package/src/utils/setup/register-mfa.ts

@@ -1,165 +0,0 @@
-/**
- * MFA Provider Registration
- *
- * Dynamically loads and registers MFA providers with the MFAService.
- */
-
-import { Repository } from 'typeorm';
-// Public API imports
-import {
-  NAuthConfig,
-  NAuthLogger,
-  MFAService,
-  BaseMFADevice,
-  BaseUser,
-  PhoneVerificationService,
-  EmailVerificationService,
-  AuthAuditService,
-  ClientInfoService,
-  IMFAProviderService,
-} from '../../index';
-// Internal API imports (for framework adapter use only)
-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 async 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> {
-  if (!config.mfa?.enabled) {
-    return;
-  }
-
-  // ============================================================================
-  // TOTP MFA Provider
-  // ============================================================================
-  try {
-    // @ts-ignore - Optional peer dependency, may not be installed
-    const { TOTPMFAProviderService, TOTPService } = await import('@nauth-toolkit/mfa-totp');
-
-    const totpService = new TOTPService(config, logger);
-
-    const totpProvider = new TOTPMFAProviderService(
-      mfaDeviceRepository,
-      userRepository,
-      config,
-      logger,
-      passwordService,
-      totpService,
-      challengeService,
-      auditService,
-      clientInfoService,
-    );
-
-    mfaService.registerProvider(totpProvider as unknown as IMFAProviderService);
-    logger?.debug?.('TOTP MFA provider registered');
-  } catch (error) {
-    logger?.warn?.('TOTP MFA package not found. Install @nauth-toolkit/mfa-totp to enable TOTP MFA.');
-  }
-
-  // ============================================================================
-  // SMS MFA Provider
-  // ============================================================================
-  if (phoneVerificationService) {
-    try {
-      // @ts-ignore - Optional peer dependency, may not be installed
-      const { SMSMFAProviderService } = await import('@nauth-toolkit/mfa-sms');
-
-      const smsProvider = new SMSMFAProviderService(
-        mfaDeviceRepository,
-        userRepository,
-        config,
-        logger,
-        passwordService,
-        phoneVerificationService,
-        challengeService,
-        auditService,
-        clientInfoService,
-      );
-
-      mfaService.registerProvider(smsProvider as unknown as IMFAProviderService);
-      logger?.debug?.('SMS MFA provider registered');
-    } catch (error) {
-      logger?.warn?.('SMS MFA package not found. Install @nauth-toolkit/mfa-sms to enable SMS MFA.');
-    }
-  } else {
-    logger?.debug?.('Phone verification service not configured. Skipping SMS MFA registration.');
-  }
-
-  // ============================================================================
-  // Email MFA Provider
-  // ============================================================================
-  try {
-    // @ts-ignore - Optional peer dependency, may not be installed
-    const { EmailMFAProviderService } = await import('@nauth-toolkit/mfa-email');
-
-    const emailProvider = new EmailMFAProviderService(
-      mfaDeviceRepository,
-      userRepository,
-      config,
-      logger,
-      passwordService,
-      emailVerificationService,
-      challengeService,
-      auditService,
-      clientInfoService,
-    );
-
-    mfaService.registerProvider(emailProvider as unknown as IMFAProviderService);
-    logger?.debug?.('Email MFA provider registered');
-  } catch (error) {
-    logger?.warn?.('Email MFA package not found. Install @nauth-toolkit/mfa-email to enable Email MFA.');
-  }
-
-  // ============================================================================
-  // Passkey MFA Provider
-  // ============================================================================
-  try {
-    // @ts-ignore - Optional peer dependency, may not be installed
-    const { PasskeyMFAProviderService, PasskeyService } = await import('@nauth-toolkit/mfa-passkey');
-
-    const passkeyService = new PasskeyService(config, logger);
-
-    const passkeyProvider = new PasskeyMFAProviderService(
-      mfaDeviceRepository,
-      userRepository,
-      config,
-      logger,
-      passwordService,
-      passkeyService,
-      challengeService,
-      auditService,
-      clientInfoService,
-    );
-
-    mfaService.registerProvider(passkeyProvider as unknown as IMFAProviderService);
-    logger?.debug?.('Passkey MFA provider registered');
-  } catch (error) {
-    logger?.warn?.('Passkey MFA package not found. Install @nauth-toolkit/mfa-passkey to enable Passkey MFA.');
-  }
-}

package/src/utils/setup/run-nauth-migrations.ts

@@ -1,61 +0,0 @@
-import type { DataSource } from 'typeorm';
-import type { NAuthConfig } from '../../interfaces/config.interface';
-import type { NAuthLogger } from '../nauth-logger';
-
-type SupportedTypeOrmDbType = 'postgres' | 'mysql' | 'mariadb';
-
-function getDbType(dataSource: DataSource): SupportedTypeOrmDbType | null {
-  const type = (dataSource.options as { type?: unknown } | undefined)?.type;
-  if (type === 'postgres' || type === 'mysql' || type === 'mariadb') return type;
-  return null;
-}
-
-type MigrationRunnerModule = {
-  runNAuthMigrations?: (dataSource: DataSource, logger: NAuthLogger, config: NAuthConfig) => Promise<void>;
-};
-
-/**
- * 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 async function runNAuthMigrationsOnStartup(
-  config: NAuthConfig,
-  dataSource: DataSource,
-  logger: NAuthLogger,
-): Promise<void> {
-  if (!dataSource.isInitialized) {
-    logger.warn('[nauth-toolkit] DataSource not initialized; skipping migrations');
-    return;
-  }
-
-  const dbType = getDbType(dataSource);
-  if (!dbType) {
-    logger.debug(
-      `[nauth-toolkit] Skipping migrations: unsupported TypeORM DataSource type: ${String(
-        (dataSource.options as { type?: unknown } | undefined)?.type,
-      )}`,
-    );
-    return;
-  }
-
-  const adapterPackageName =
-    dbType === 'postgres' ? '@nauth-toolkit/database-typeorm-postgres' : '@nauth-toolkit/database-typeorm-mysql';
-
-  let imported: MigrationRunnerModule;
-  try {
-    // NOTE: use a variable import (not a string literal) to avoid hard dependency from core -> adapter packages
-    imported = (await import(adapterPackageName)) as unknown as MigrationRunnerModule;
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    throw new Error(`[nauth-toolkit] Failed to load migration adapter ${adapterPackageName}: ${message}`);
-  }
-
-  if (typeof imported.runNAuthMigrations !== 'function') {
-    throw new Error(`[nauth-toolkit] Migration adapter ${adapterPackageName} does not export runNAuthMigrations()`);
-  }
-
-  await imported.runNAuthMigrations(dataSource, logger, config);
-}

package/src/utils/token-delivery-policy.ts

@@ -1,38 +0,0 @@
-/**
- * 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 function resolveDeliveryForRequest(req: unknown, policy?: HybridPolicy): 'cookies' | 'json' {
-  const r = req as { headers?: Record<string, unknown> } | undefined;
-  const origin = (r?.headers?.origin as string) || '';
-
-  // 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';
-}

package/src/validators/template.validator.ts

@@ -1,219 +0,0 @@
-/**
- * Template Validation Utility
- *
- * Validates custom templates to ensure they include all required parameters.
- * Provides clear error messages for missing parameters.
- */
-
-import { TemplateType, CustomTemplateDefinition } from '../interfaces/template.interface';
-import { NAuthException } from '../exceptions/nauth.exception';
-import { AuthErrorCode } from '../enums/error-codes.enum';
-
-/**
- * Required parameters for each template type
- *
- * Maps template types to their required Handlebars variables.
- */
-export const TEMPLATE_REQUIRED_PARAMS: Record<TemplateType, string[]> = {
-  [TemplateType.VERIFICATION]: ['code', 'link', 'expiryMinutes'],
-  [TemplateType.PASSWORD_RESET]: ['link', 'expiryMinutes'],
-  [TemplateType.WELCOME]: [],
-  [TemplateType.ACCOUNT_LOCKOUT]: ['reason', 'durationMinutes'],
-  [TemplateType.NEW_DEVICE]: ['deviceName', 'timestamp'],
-  [TemplateType.PASSWORD_CHANGED]: [],
-  [TemplateType.EMAIL_CHANGED]: ['userEmail'],
-  [TemplateType.MFA_ENABLED]: [],
-};
-
-/**
- * Optional parameters available to all templates
- *
- * These can be used but are not required.
- * Injected by the template engine at runtime if available.
- */
-export const TEMPLATE_OPTIONAL_PARAMS = [
-  // User information
-  'firstName',
-  'lastName',
-  'userName',
-  'userEmail',
-  'greetingName',
-
-  // Global branding
-  'appName',
-  'companyName',
-  'companyAddress',
-  'brandColor',
-  'logoUrl',
-  'dashboardUrl',
-  'supportEmail',
-
-  // Social media
-  'facebookUrl',
-  'twitterUrl',
-  'linkedinUrl',
-
-  // Timestamps
-  'currentYear',
-
-  // Security alerts (device-specific)
-  'deviceType',
-  'ipAddress',
-  'location',
-];
-
-/**
- * Validate template content for required parameters
- *
- * Scans template HTML/text for required Handlebars variables.
- * Throws error if any required parameters are missing.
- *
- * @param templateType - Type of template being validated
- * @param templateContent - HTML or text content to validate
- * @throws {NAuthException} If required parameters are missing
- *
- * @example
- * ```typescript
- * validateTemplateParams(
- *   TemplateType.VERIFICATION,
- *   '<html>{{code}} {{link}} {{expiryMinutes}}</html>'
- * ); // OK
- *
- * validateTemplateParams(
- *   TemplateType.VERIFICATION,
- *   '<html>{{code}}</html>'
- * ); // Throws: Missing required parameters: link, expiryMinutes
- * ```
- */
-export function validateTemplateParams(templateType: TemplateType | string, templateContent: string): void {
-  // Get required params for this template type
-  const requiredParams = TEMPLATE_REQUIRED_PARAMS[templateType as TemplateType] || [];
-
-  if (requiredParams.length === 0) {
-    // No validation needed for templates with no required params
-    return;
-  }
-
-  // Extract all Handlebars variables from template
-  // Matches: {{variable}}, {{#if variable}}, {{#each variable}}, etc.
-  const variablePattern = /\{\{[#/]?(\w+)(?:\s|}})/g;
-  const foundVariables = new Set<string>();
-
-  let match;
-  while ((match = variablePattern.exec(templateContent)) !== null) {
-    foundVariables.add(match[1]);
-  }
-
-  // Check for missing required parameters
-  const missingParams = requiredParams.filter((param) => !foundVariables.has(param));
-
-  if (missingParams.length > 0) {
-    throw new NAuthException(
-      AuthErrorCode.INTERNAL_ERROR,
-      `Invalid template configuration for "${templateType}": ` +
-        `Missing required parameters: ${missingParams.join(', ')}. ` +
-        `Template must include: ${requiredParams.map((p) => `{{${p}}}`).join(', ')}`,
-    );
-  }
-}
-
-/**
- * Validate custom template definition
- *
- * Ensures template definition is valid:
- * - Has either htmlPath OR html content
- * - Contains all required parameters for template type
- *
- * @param templateType - Type of template being validated
- * @param definition - Template definition to validate
- * @param templateContent - Already loaded template content (if available)
- * @throws {NAuthException} If template definition is invalid
- *
- * @example
- * ```typescript
- * validateCustomTemplate(TemplateType.VERIFICATION, {
- *   htmlPath: './verification.html.hbs'
- * });
- * ```
- */
-export function validateCustomTemplate(
-  templateType: TemplateType | string,
-  definition: CustomTemplateDefinition,
-  templateContent?: string,
-): void {
-  // Validate that either htmlPath or html is provided
-  if (!definition.htmlPath && !definition.html) {
-    throw new NAuthException(
-      AuthErrorCode.INTERNAL_ERROR,
-      `Invalid template configuration for "${templateType}": ` + `Must provide either "htmlPath" or "html" content.`,
-    );
-  }
-
-  // Validate that both htmlPath and html are not provided
-  if (definition.htmlPath && definition.html) {
-    throw new NAuthException(
-      AuthErrorCode.INTERNAL_ERROR,
-      `Invalid template configuration for "${templateType}": ` +
-        `Cannot provide both "htmlPath" and "html". Use one or the other.`,
-    );
-  }
-
-  // Validate that both textPath and text are not provided
-  if (definition.textPath && definition.text) {
-    throw new NAuthException(
-      AuthErrorCode.INTERNAL_ERROR,
-      `Invalid template configuration for "${templateType}": ` +
-        `Cannot provide both "textPath" and "text". Use one or the other.`,
-    );
-  }
-
-  // If template content is provided, validate parameters
-  if (templateContent) {
-    validateTemplateParams(templateType, templateContent);
-  }
-}
-
-/**
- * Get help text for template parameters
- *
- * Returns human-readable list of required and optional parameters
- * for a specific template type.
- *
- * @param templateType - Template type
- * @returns Help text with parameter information
- *
- * @example
- * ```typescript
- * console.log(getTemplateParamsHelp(TemplateType.VERIFICATION));
- * // Output:
- * // Required parameters:
- * //   - {{code}}: Verification code
- * //   - {{link}}: Verification link
- * //   - {{expiryMinutes}}: Code expiry time
- * // Optional parameters:
- * //   - {{firstName}}, {{lastName}}, {{userName}}, {{appName}}, etc.
- * ```
- */
-export function getTemplateParamsHelp(templateType: TemplateType): string {
-  const required = TEMPLATE_REQUIRED_PARAMS[templateType];
-
-  let help = `Template: ${templateType}\n\n`;
-
-  if (required.length > 0) {
-    help += `Required parameters (must be in template):\n`;
-    required.forEach((param) => {
-      help += `  - {{${param}}}\n`;
-    });
-  } else {
-    help += `No required parameters.\n`;
-  }
-
-  help += `\nOptional parameters (available at runtime):\n`;
-  help += `  - User: {{firstName}}, {{lastName}}, {{userName}}, {{greetingName}}\n`;
-  help += `  - Branding: {{appName}}, {{companyName}}, {{brandColor}}, {{logoUrl}}\n`;
-  help += `  - Support: {{supportEmail}}, {{dashboardUrl}}\n`;
-  help += `  - Social: {{facebookUrl}}, {{twitterUrl}}, {{linkedinUrl}}\n`;
-  help += `  - Other: {{currentYear}}\n`;
-
-  return help;
-}

package/tsconfig.json

@@ -1,37 +0,0 @@
-{
-  "compilerOptions": {
-    "composite": true,
-    "target": "ES2022",
-    "module": "commonjs",
-    "lib": ["ES2022"],
-    "declaration": true,
-    "declarationMap": true,
-    "sourceMap": true,
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "removeComments": true,
-    "strict": true,
-    "noImplicitAny": true,
-    "strictNullChecks": true,
-    "strictFunctionTypes": true,
-    "strictBindCallApply": true,
-    "strictPropertyInitialization": true,
-    "noImplicitThis": true,
-    "alwaysStrict": true,
-    "noUnusedLocals": false,
-    "noUnusedParameters": false,
-    "noImplicitReturns": true,
-    "noFallthroughCasesInSwitch": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "resolveJsonModule": true,
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true,
-    "moduleResolution": "node",
-    "allowSyntheticDefaultImports": true
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "**/*.spec.ts", "../social/**/*", "*.tsbuildinfo"]
-}
-

package/tsconfig.lint.json

@@ -1,6 +0,0 @@
-{
-  "extends": "./tsconfig.json",
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
-}
-