@nauth-toolkit/core 0.1.0

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

@@ -0,0 +1,165 @@
+/**
+ * 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

@@ -0,0 +1,61 @@
+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

@@ -0,0 +1,38 @@
+/**
+ * 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

@@ -0,0 +1,219 @@
+/**
+ * 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

@@ -0,0 +1,37 @@
+{
+  "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

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