@nauth-toolkit/core 0.1.0 → 0.1.3

package/src/services/auth-flow-rules.ts

@@ -1,202 +0,0 @@
-import { AuthFlowContext, Rule } from './auth-flow-state-machine.types';
-
-/**
- * Rule Builder
- *
- * Utility class for composing complex rules using combinators.
- * Supports logical operations: all, any, not.
- *
- * @example
- * ```typescript
- * const complexRule = RuleBuilder.all([
- *   Rules.mustChangePassword,
- *   RuleBuilder.not(Rules.isMFAExempt)
- * ]);
- * ```
- */
-export class RuleBuilder {
-  /**
-   * Combine multiple rules with AND logic
-   * All rules must evaluate to true
-   *
-   * @param rules - Array of rules to combine
-   * @returns Combined rule that returns true only if all rules are true
-   *
-   * @example
-   * ```typescript
-   * const rule = RuleBuilder.all([
-   *   Rules.emailVerificationPending,
-   *   Rules.isNotSocialLogin
-   * ]);
-   * ```
-   */
-  static all(rules: Rule[]): Rule {
-    return (context: AuthFlowContext): boolean => {
-      return rules.every((rule) => rule(context));
-    };
-  }
-
-  /**
-   * Combine multiple rules with OR logic
-   * At least one rule must evaluate to true
-   *
-   * @param rules - Array of rules to combine
-   * @returns Combined rule that returns true if any rule is true
-   *
-   * @example
-   * ```typescript
-   * const rule = RuleBuilder.any([
-   *   Rules.isDeviceTrusted,
-   *   Rules.isMFAExempt
-   * ]);
-   * ```
-   */
-  static any(rules: Rule[]): Rule {
-    return (context: AuthFlowContext): boolean => {
-      return rules.some((rule) => rule(context));
-    };
-  }
-
-  /**
-   * Negate a rule
-   * Returns true when the rule returns false
-   *
-   * @param rule - Rule to negate
-   * @returns Negated rule
-   *
-   * @example
-   * ```typescript
-   * const rule = RuleBuilder.not(Rules.isMFAExempt);
-   * ```
-   */
-  static not(rule: Rule): Rule {
-    return (context: AuthFlowContext): boolean => {
-      return !rule(context);
-    };
-  }
-}
-
-/**
- * Authentication Flow Rules
- *
- * Declarative rules for evaluating authentication flow states.
- * Each rule is a pure function that evaluates to true or false based on context.
- *
- * Rules are used in state definitions to determine which state applies.
- */
-export const Rules = {
-  /**
-   * User must change password
-   * Priority: 1 (highest)
-   *
-   * @param context - Authentication flow context
-   * @returns True if user must change password
-   */
-  mustChangePassword: (context: AuthFlowContext): boolean => {
-    return context.user.mustChangePassword === true;
-  },
-
-  /**
-   * Email verification is pending
-   * Priority: 2
-   *
-   * @param context - Authentication flow context
-   * @returns True if email verification is required and not completed
-   */
-  emailVerificationPending: (context: AuthFlowContext): boolean => {
-    return context.computed.isEmailVerificationRequired;
-  },
-
-  /**
-   * Phone collection is needed
-   * Priority: 3
-   *
-   * @param context - Authentication flow context
-   * @returns True if phone collection is needed (user has no phone)
-   */
-  phoneCollectionNeeded: (context: AuthFlowContext): boolean => {
-    return context.computed.isPhoneCollectionNeeded;
-  },
-
-  /**
-   * Phone verification is pending
-   * Priority: 4
-   *
-   * @param context - Authentication flow context
-   * @returns True if phone verification is required and not completed
-   */
-  phoneVerificationPending: (context: AuthFlowContext): boolean => {
-    return context.computed.isPhoneVerificationRequired;
-  },
-
-  /**
-   * MFA setup is required
-   * Priority: 5
-   *
-   * @param context - Authentication flow context
-   * @returns True if MFA setup is required
-   */
-  mfaSetupRequired: (context: AuthFlowContext): boolean => {
-    return context.computed.isMFASetupRequired;
-  },
-
-  /**
-   * MFA verification is required
-   * Priority: 6
-   *
-   * @param context - Authentication flow context
-   * @returns True if MFA verification is required
-   */
-  mfaVerificationRequired: (context: AuthFlowContext): boolean => {
-    return context.computed.isMFAVerificationRequired;
-  },
-
-  /**
-   * Grace period is active (ADAPTIVE mode with MFA not enabled)
-   * Priority: 7
-   *
-   * This rule applies when:
-   * - Enforcement is ADAPTIVE
-   * - Grace period is active
-   * - MFA is not enabled
-   * - User is not blocked
-   *
-   * @param context - Authentication flow context
-   * @returns True if grace period is active and MFA not enabled
-   */
-  gracePeriodActiveAdaptive: (context: AuthFlowContext): boolean => {
-    const enforcement = context.config.mfa?.enforcement || 'OPTIONAL';
-    return (
-      enforcement === 'ADAPTIVE' &&
-      context.computed.isGracePeriodActive &&
-      !context.user.mfaEnabled &&
-      !context.computed.isBlocked
-    );
-  },
-
-  /**
-   * User is blocked from signing in
-   * Priority: 8
-   *
-   * @param context - Authentication flow context
-   * @returns True if user is blocked
-   */
-  isBlocked: (context: AuthFlowContext): boolean => {
-    return context.computed.isBlocked;
-  },
-
-  /**
-   * User is authenticated (no challenges pending)
-   * Priority: 9 (lowest - default state)
-   *
-   * This rule applies when no other state rules match.
-   * It's the default state when all challenges are complete.
-   *
-   * @param _context - Authentication flow context (unused - always returns true)
-   * @returns True if user is authenticated (always true as fallback)
-   */
-  authenticated: (_context: AuthFlowContext): boolean => {
-    // Always true - this is the default state when no other rules match
-    return true;
-  },
-};

package/src/services/auth-flow-state-definitions.ts

@@ -1,190 +0,0 @@
-import { AuthFlowState, StateDefinition, AuthFlowContext, ResponseMetadata } from './auth-flow-state-machine.types';
-import { AuthChallenge } from '../dto/auth-challenge.dto';
-import { Rules } from './auth-flow-rules';
-import { MFAMethod } from '../enums/mfa-method.enum';
-
-/**
- * Authentication Flow State Definitions
- *
- * Defines all possible states in the authentication flow with their:
- * - Priority (evaluation order, 1-9)
- * - Condition rules (when state applies)
- * - Challenge mappings (which AuthChallenge this state maps to)
- * - Metadata builders (optional additional response data)
- * - OnEnter hooks (optional actions when state is entered)
- *
- * States are evaluated in priority order. The first state whose condition
- * evaluates to true is selected.
- *
- * @example
- * ```typescript
- * const state = STATE_DEFINITIONS.find(def => def.condition(context));
- * ```
- */
-export const STATE_DEFINITIONS: StateDefinition[] = [
-  /**
-   * Priority 1: Force Password Change
-   * Highest priority - must be completed before any other challenges
-   */
-  {
-    state: AuthFlowState.PENDING_PASSWORD_CHANGE,
-    priority: 1,
-    condition: Rules.mustChangePassword,
-    challenge: AuthChallenge.FORCE_CHANGE_PASSWORD,
-  },
-
-  /**
-   * Priority 2: Email Verification
-   * Required before phone verification (sequential flow)
-   */
-  {
-    state: AuthFlowState.PENDING_EMAIL_VERIFICATION,
-    priority: 2,
-    condition: Rules.emailVerificationPending,
-    challenge: AuthChallenge.VERIFY_EMAIL,
-  },
-
-  /**
-   * Priority 3: Phone Collection
-   * User must provide phone number before verification
-   */
-  {
-    state: AuthFlowState.PENDING_PHONE_COLLECTION,
-    priority: 3,
-    condition: Rules.phoneCollectionNeeded,
-    challenge: AuthChallenge.VERIFY_PHONE,
-  },
-
-  /**
-   * Priority 4: Phone Verification
-   * Required after email verification (sequential flow)
-   */
-  {
-    state: AuthFlowState.PENDING_PHONE_VERIFICATION,
-    priority: 4,
-    condition: Rules.phoneVerificationPending,
-    challenge: AuthChallenge.VERIFY_PHONE,
-  },
-
-  /**
-   * Priority 5: MFA Setup Required
-   * Required when enforcement is REQUIRED/ADAPTIVE and grace period expired
-   */
-  {
-    state: AuthFlowState.PENDING_MFA_SETUP,
-    priority: 5,
-    condition: Rules.mfaSetupRequired,
-    challenge: AuthChallenge.MFA_SETUP_REQUIRED,
-    /**
-     * OnEnter hook: Auto-complete SMS MFA setup if phone is already verified
-     *
-     * Special case: If user's phone is already verified and they choose SMS MFA,
-     * we can skip the SMS verification step during setup (improves UX).
-     * The phone was already verified, so we trust it for MFA setup.
-     *
-     * This sets skipMFAVerification flag which will be checked during MFA setup completion.
-     */
-    onEnter: async (context: AuthFlowContext): Promise<void> => {
-      // Check if phone is verified and preferred method is SMS
-      if (context.user.isPhoneVerified && context.user.phone && context.user.preferredMfaMethod === MFAMethod.SMS) {
-        // Auto-complete: Set skipMFAVerification flag
-        // This will be used during MFA setup completion to skip SMS verification
-        context.skipMFAVerification = true;
-      }
-    },
-  },
-
-  /**
-   * Priority 6: MFA Verification Required
-   * Required when MFA is enabled and verification is needed
-   */
-  {
-    state: AuthFlowState.PENDING_MFA_VERIFICATION,
-    priority: 6,
-    condition: Rules.mfaVerificationRequired,
-    challenge: AuthChallenge.MFA_REQUIRED,
-  },
-
-  /**
-   * Priority 7: Grace Period Active
-   * ADAPTIVE mode with grace period active and MFA not enabled
-   * This is a special state that allows login but includes metadata about grace period
-   */
-  {
-    state: AuthFlowState.GRACE_PERIOD_ACTIVE,
-    priority: 7,
-    condition: Rules.gracePeriodActiveAdaptive,
-    /**
-     * Build metadata for grace period state
-     * Includes grace period end timestamp and risk information
-     */
-    buildMetadata: (context: AuthFlowContext): ResponseMetadata | undefined => {
-      return {
-        gracePeriodEndsAt: context.computed.gracePeriodEndsAt,
-        riskScore: context.computed.riskScore,
-        riskLevel: context.computed.riskLevel,
-      };
-    },
-  },
-
-  /**
-   * Priority 8: Blocked
-   * User is blocked from signing in due to high risk
-   */
-  {
-    state: AuthFlowState.BLOCKED,
-    priority: 8,
-    condition: Rules.isBlocked,
-    /**
-     * Build metadata for blocked state
-     * Includes block expiration and reason
-     */
-    buildMetadata: (context: AuthFlowContext): ResponseMetadata | undefined => {
-      return {
-        blockedUntil: context.computed.blockedUntil,
-        reason: context.computed.blockReason,
-      };
-    },
-  },
-
-  /**
-   * Priority 9: Authenticated
-   * Default state when all challenges are complete
-   * This rule always evaluates to true, so it's the fallback state
-   */
-  {
-    state: AuthFlowState.AUTHENTICATED,
-    priority: 9,
-    condition: Rules.authenticated,
-  },
-];
-
-/**
- * Get state definition by state
- *
- * @param state - State to get definition for
- * @returns State definition or undefined if not found
- *
- * @example
- * ```typescript
- * const def = getStateDefinition(AuthFlowState.PENDING_EMAIL_VERIFICATION);
- * ```
- */
-export function getStateDefinition(state: AuthFlowState): StateDefinition | undefined {
-  return STATE_DEFINITIONS.find((def) => def.state === state);
-}
-
-/**
- * Get state definitions sorted by priority
- *
- * @returns State definitions sorted by priority (1-9)
- *
- * @example
- * ```typescript
- * const sorted = getStateDefinitionsByPriority();
- * // Evaluates states in order: PENDING_PASSWORD_CHANGE, PENDING_EMAIL_VERIFICATION, ...
- * ```
- */
-export function getStateDefinitionsByPriority(): StateDefinition[] {
-  return [...STATE_DEFINITIONS].sort((a, b) => a.priority - b.priority);
-}

package/src/services/auth-flow-state-machine.service.ts

@@ -1,207 +0,0 @@
-import { AuthFlowState, AuthFlowContext, StateDefinition, ResponseMetadata } from './auth-flow-state-machine.types';
-import { AuthFlowContextBuilder } from './auth-flow-context-builder.service';
-import { NAuthLogger } from '../utils/nauth-logger';
-import { getStateDefinitionsByPriority, getStateDefinition } from './auth-flow-state-definitions';
-
-/**
- * Authentication Flow State Machine Service
- *
- * Core engine for evaluating authentication flow states using declarative rules.
- * Replaces imperative if/else logic with a rule-based state machine.
- *
- * **How it works:**
- * 1. Build context with pre-computed values
- * 2. Evaluate states in priority order (1-9)
- * 3. Select first state whose condition rule evaluates to true
- * 4. Execute onEnter hook if defined
- * 5. Return state with metadata
- *
- * **Benefits:**
- * - Declarative and maintainable
- * - Easy to test (pure functions)
- * - Extensible (add new states/rules easily)
- * - Clear priority ordering
- *
- * @example
- * ```typescript
- * const state = await stateMachine.evaluateState(context);
- * const definition = stateMachine.getStateDefinition(state);
- * ```
- */
-export class AuthFlowStateMachineService {
-  constructor(
-    private readonly contextBuilder: AuthFlowContextBuilder,
-    private readonly logger?: NAuthLogger,
-  ) {}
-
-  /**
-   * Evaluate authentication flow state
-   *
-   * Evaluates states in priority order and returns the first matching state.
-   * Executes onEnter hook if defined for the selected state.
-   *
-   * @param context - Authentication flow context
-   * @returns Evaluated state
-   *
-   * @example
-   * ```typescript
-   * const context = await contextBuilder.build({ user, config, authMethod: 'password' });
-   * const state = await stateMachine.evaluateState(context);
-   * // Returns: AuthFlowState.PENDING_EMAIL_VERIFICATION
-   * ```
-   */
-  async evaluateState(context: AuthFlowContext): Promise<AuthFlowState> {
-    // Get state definitions sorted by priority
-    const stateDefinitions = getStateDefinitionsByPriority();
-
-    this.logger?.debug?.(
-      `[StateMachine] Evaluating states for user ${context.user.sub} (priority 1-9, first match wins)`,
-    );
-
-    // Evaluate states in priority order
-    for (const definition of stateDefinitions) {
-      // Evaluate condition rule
-      const ruleResult = definition.condition(context);
-      this.logger?.debug?.(
-        `[StateMachine] Priority ${definition.priority}: ${definition.state} → ${ruleResult ? 'MATCH' : 'skip'}`,
-      );
-
-      if (ruleResult) {
-        // State matches - execute onEnter hook if defined
-        if (definition.onEnter) {
-          this.logger?.debug?.(`[StateMachine] Executing onEnter hook for ${definition.state}`);
-          try {
-            await definition.onEnter(context);
-          } catch (error) {
-            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-            this.logger?.warn?.(`onEnter hook failed for state ${definition.state}: ${errorMessage}`, {
-              error,
-              state: definition.state,
-              userId: context.user.id,
-            });
-            // Continue with state selection even if hook fails
-          }
-        }
-
-        this.logger?.debug?.(`[StateMachine] ✓ Selected state: ${definition.state} for user ${context.user.sub}`);
-        return definition.state;
-      }
-    }
-
-    // Fallback: Should never reach here (AUTHENTICATED always matches)
-    // But return AUTHENTICATED as safe default
-    this.logger?.warn?.(`No state matched for user ${context.user.sub} - falling back to AUTHENTICATED`, {
-      userId: context.user.id,
-    });
-    return AuthFlowState.AUTHENTICATED;
-  }
-
-  /**
-   * Get state definition by state
-   *
-   * @param state - State to get definition for
-   * @returns State definition or undefined if not found
-   *
-   * @example
-   * ```typescript
-   * const def = stateMachine.getStateDefinition(AuthFlowState.PENDING_EMAIL_VERIFICATION);
-   * ```
-   */
-  getStateDefinition(state: AuthFlowState): StateDefinition | undefined {
-    return getStateDefinition(state);
-  }
-
-  /**
-   * Build metadata for state response
-   *
-   * Calls buildMetadata function if defined for the state.
-   *
-   * @param state - State to build metadata for
-   * @param context - Authentication flow context
-   * @returns Metadata object or undefined
-   *
-   * @example
-   * ```typescript
-   * const metadata = await stateMachine.buildMetadata(state, context);
-   * // Returns: { gracePeriodEndsAt: Date, riskScore: 45, riskLevel: 'medium' }
-   * ```
-   */
-  buildMetadata(state: AuthFlowState, context: AuthFlowContext): ResponseMetadata | undefined {
-    const definition = this.getStateDefinition(state);
-    if (!definition || !definition.buildMetadata) {
-      return undefined;
-    }
-
-    try {
-      return definition.buildMetadata(context);
-    } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-      this.logger?.warn?.(`buildMetadata failed for state ${state}: ${errorMessage}`, {
-        error,
-        state,
-        userId: context.user.id,
-      });
-      return undefined;
-    }
-  }
-
-  /**
-   * Transition after challenge completion
-   *
-   * Re-evaluates state after a challenge is completed.
-   * This is used in the challenge completion flow to determine the next state.
-   *
-   * @param params - Transition parameters
-   * @param params.completedChallenge - Challenge that was just completed
-   * @param params.context - Current authentication flow context
-   * @param params.updateFn - Function to update user data (e.g., mark email as verified)
-   * @returns New state after transition
-   *
-   * @example
-   * ```typescript
-   * const newState = await stateMachine.transitionAfterChallenge({
-   *   completedChallenge: AuthChallenge.VERIFY_EMAIL,
-   *   context,
-   *   updateFn: async (user) => {
-   *     user.isEmailVerified = true;
-   *     await userRepository.save(user);
-   *   }
-   * });
-   * ```
-   */
-  async transitionAfterChallenge(params: {
-    completedChallenge: string;
-    context: AuthFlowContext;
-    updateFn?: (user: AuthFlowContext['user']) => Promise<void>;
-  }): Promise<AuthFlowState> {
-    const { completedChallenge, context, updateFn } = params;
-
-    // Update user data if update function provided
-    if (updateFn) {
-      try {
-        await updateFn(context.user);
-      } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-        this.logger?.error?.(`Failed to update user after challenge completion: ${errorMessage}`, {
-          error,
-          challenge: completedChallenge,
-          userId: context.user.id,
-        });
-        // Continue with re-evaluation even if update fails
-      }
-    }
-
-    // Re-build context with updated user data
-    const newContext = await this.contextBuilder.build({
-      user: context.user,
-      config: context.config,
-      authMethod: context.authMethod,
-      authProvider: context.authProvider,
-      deviceToken: context.deviceToken,
-      skipMFAVerification: context.skipMFAVerification,
-    });
-
-    // Re-evaluate state
-    return this.evaluateState(newContext);
-  }
-}