@khni/auth-errors

A comprehensive authentication and OTP error handling system built on the @khni/error-handler foundation, designed for seamless integration with the @khni/auth package. This TypeScript/JavaScript library provides structured error classes, type-safe error codes, and consistent HTTP response mappings for robust authentication workflows.

Installation

npm install @khni/auth-errors
pnpm add  @khni/auth-errors
yarn add  @khni/auth-errors

Features

• 🏷️ Type-safe error codes with full TypeScript support
• 🎯 Separated concerns - Authentication and OTP errors in separate modules
• 📊 Domain vs Unexpected errors - Clear distinction between user-facing and system errors
• 🔧 Factory patterns - Consistent error creation with utilities
• 📝 Comprehensive documentation - Full JSDoc support for API Extractor
• 🚦 HTTP status mapping - Automatic status code and message mapping
• 🛡️ Type guards - Runtime error type checking

Quick Start

import {
  AuthDomainError,
  AuthUnexpectedError,
  OtpDomainError,
  AuthErrorCodes,
  OtpErrorCodes,
} from "@khni/auth-errors";

// Throw authentication domain errors
if (emailAlreadyExists) {
  throw new AuthDomainError(AuthErrorCodes.AUTH_USED_EMAIL);
}

// Throw OTP domain errors
if (otpIsInvalid) {
  throw new OtpDomainError(OtpErrorCodes.OTP_INVALID);
}

// Throw unexpected errors with original cause
try {
  await createUser(userData);
} catch (error) {
  throw new AuthUnexpectedError(
    AuthErrorCodes.AUTH_USER_CREATION_FAILED,
    error
  );
}

Error Categories

Authentication Errors

Domain Errors (User-facing, expected):

• AUTH_USED_EMAIL - Email already registered
• INCORRECT_CREDENTIALS - Invalid email/password
• INVALID_ACCESS_TOKEN - Malformed or invalid JWT
• REFRESH_TOKEN_INVALID - Expired or revoked refresh token
• And 15+ more...

Unexpected Errors (System-level):

• AUTH_USER_CREATION_FAILED - Database failure during user creation
• FINDING_USER_FAILED - User search operation failed
• ISSUE_TOKEN_FAILED - JWT generation failure
• And 7+ more...

OTP Errors

Domain Errors (User-facing, expected):

• OTP_INVALID - Incorrect OTP code
• OTP_EXPIRED - OTP code has expired
• OTP_TOKEN_INVALID - Invalid OTP session token

Unexpected Errors (System-level):

• OTP_CREATION_FAILED - OTP generation service failure
• OTP_VERIFICATION_FAILED - OTP validation service failure

Usage Examples

Basic Error Throwing

import {
  AuthDomainError,
  AuthUnexpectedError,
  OtpDomainError,
  AuthErrorCodes,
  OtpErrorCodes,
} from "@khni/auth-errors";

// Authentication domain errors
function registerUser(email: string) {
  if (await userExists(email)) {
    throw new AuthDomainError(
      AuthErrorCodes.AUTH_USED_EMAIL,
      `Email ${email} is already registered`,
      { email, source: "registration" }
    );
  }
}

// OTP domain errors
function verifyOtp(userId: string, otpCode: string) {
  const storedOtp = await getStoredOtp(userId);
  if (storedOtp.code !== otpCode) {
    throw new OtpDomainError(
      OtpErrorCodes.OTP_INVALID,
      "Invalid verification code",
      { userId, attempts: storedOtp.attempts }
    );
  }
}

// Unexpected errors with cause
async function resetPassword(userId: string, newPassword: string) {
  try {
    await updatePassword(userId, newPassword);
  } catch (error) {
    throw new AuthUnexpectedError(
      AuthErrorCodes.PASSWORD_RESET_FAILED,
      error,
      "Password reset operation failed",
      { userId, timestamp: new Date() }
    );
  }
}

Using Factory Methods

import { AuthErrorFactories, OtpErrorFactories } from "@khni/auth-errors";

// Simplified error creation
function authenticateUser(email: string, password: string) {
  const user = await findUserByEmail(email);

  if (!user) {
    throw AuthErrorFactories.domain("USER_IS_NOT_EXIST", { email });
  }

  if (!user.verified) {
    throw AuthErrorFactories.domain("AUTH_UNVERIFIED_EMAIL", {
      userId: user.id,
    });
  }

  if (otpAttempts > 3) {
    throw OtpErrorFactories.domain("OTP_INVALID", {
      userId: user.id,
      attempts: otpAttempts,
    });
  }
}

Error Handling in Express

import {
  AuthError,
  OtpError,
  isAuthDomainError,
  isOtpDomainError,
  getAuthErrorResponse,
  getOtpErrorResponse,
} from "@khni/auth-errors";

app.use((error: Error, req: Request, res: Response, next: NextFunction) => {
  // Handle authentication errors
  if (error instanceof AuthError) {
    const config = getAuthErrorResponse(error.code);

    if (isAuthDomainError(error)) {
      // Log domain errors as warnings
      logger.warn("Auth domain error", { code: error.code, meta: error.meta });
    } else {
      // Log unexpected errors with full details
      logger.error("Auth unexpected error", {
        code: error.code,
        cause: error.cause,
        meta: error.meta,
      });
    }

    return res.status(config.statusCode).json({
      error: config.responseMessage,
      code: error.code,
    });
  }

  // Handle OTP errors
  if (error instanceof OtpError) {
    const config = getOtpErrorResponse(error.code);

    if (isOtpDomainError(error)) {
      logger.warn("OTP domain error", { code: error.code, meta: error.meta });
    } else {
      logger.error("OTP unexpected error", {
        code: error.code,
        cause: error.cause,
        meta: error.meta,
      });
    }

    return res.status(config.statusCode).json({
      error: config.responseMessage,
      code: error.code,
    });
  }

  // Handle other errors
  next(error);
});

API Reference

Core Classes

AuthError

Base class for all authentication errors.

AuthDomainError

Expected business logic errors during authentication.

AuthUnexpectedError

System-level failures during authentication.

OtpError

Base class for all OTP errors.

OtpDomainError

Expected business logic errors during OTP operations.

OtpUnexpectedError

System-level failures during OTP operations.

Utility Functions

getAuthErrorResponse(code: AuthErrorCodesType)

Returns HTTP status code and message for authentication errors.

getOtpErrorResponse(code: OtpErrorCodesType)

Returns HTTP status code and message for OTP errors.

Type Guards

• isAuthDomainError(error: unknown)
• isAuthUnexpectedError(error: unknown)
• isOtpDomainError(error: unknown)
• isOtpUnexpectedError(error: unknown)

Factory Classes

AuthErrorFactories

• .domain(code, meta?) - Create domain errors
• .unexpected(code, cause, meta?) - Create unexpected errors

OtpErrorFactories

• .domain(code, meta?) - Create domain errors
• .unexpected(code, cause, meta?) - Create unexpected errors

Error Codes Reference

Authentication Error Codes

Domain Errors

Code	HTTP Status	Message	Description
AUTH_USED_EMAIL	409	Email already registered	Email exists during registration
AUTH_USED_IDENTIFIER	409	Identifier already registered	Username/identifier taken
AUTH_UNVERIFIED_EMAIL	403	Email verification required	User needs to verify email
INCORRECT_CREDENTIALS	401	Invalid credentials	Wrong email/password
USER_NOT_LOCAL	400	External authentication required	OAuth user tried local auth
REFRESH_TOKEN_INVALID	401	Refresh token is invalid or expired	Refresh token validation failed
INVALID_ACCESS_TOKEN	401	Access token is invalid or expired	Malformed JWT token
EXPIRED_ACCESS_TOKEN	401	Access token is expired	JWT token expired
MISSING_ACCESS_TOKEN	401	Access token is missing	No Authorization header
MISSING_REFRESH_TOKEN	400	You are already logged out	No refresh token during logout
USER_IS_NOT_EXIST	400	Email does not exist	User not found

Unexpected Errors

Code	HTTP Status	Message	Description
FINDING_USER_FAILED	500	Something went wrong while finding the user	Database search failure
AUTH_USER_CREATION_FAILED	500	Account creation failed	User creation database failure
ISSUE_TOKEN_FAILED	400	Unexpected error while issuing tokens	JWT generation failure
PASSWORD_RESET_FAILED	500	Password Reset Failed	Password update operation failed
REFRESHTOKEN_REVOKE_FAILED	500	Failed to Logout	Refresh token revocation failed
REFRESHTOKEN_CREATE_FAILED	500	Failed to create refresh token	Refresh token creation failed
REFRESHTOKEN_VERIFY_FAILED	500	Failed to verify refresh token	Refresh token verification failed
LOGIN_FAILED	500	Something went wrong while login	General login process failure

OTP Error Codes

Domain Errors

Code	HTTP Status	Message	Description
OTP_INVALID	401	The OTP you entered is incorrect	Wrong OTP code provided
OTP_EXPIRED	401	The OTP is expired	OTP code has expired
TOKEN_EXPIRED	401	Token is expired	OTP session token expired
OTP_TOKEN_INVALID	401	Please request new OTP	Invalid or expired OTP token

Unexpected Errors

Code	HTTP Status	Message	Description
OTP_CREATION_FAILED	500	Something went wrong while creating OTP	OTP generation service failure
OTP_VERIFICATION_FAILED	500	Something went wrong while verifying OTP	OTP validation service failure

Best Practices

1. Error Handling Strategy

// Use domain errors for business logic
if (!user.exists) {
  throw new AuthDomainError("USER_IS_NOT_EXIST");
}

// Use unexpected errors for system failures
try {
  await databaseOperation();
} catch (error) {
  throw new AuthUnexpectedError("FINDING_USER_FAILED", error);
}

2. Metadata for Debugging

// Include relevant context in meta
throw new AuthDomainError("INCORRECT_CREDENTIALS", "Multiple failed attempts", {
  userId: user.id,
  attempts: loginAttempts,
  ip: request.ip,
});

3. Error Recovery

import { isOtpDomainError } from "@khni/auth-errors";

try {
  await verifyOtp(userId, otpCode);
} catch (error) {
  if (isOtpDomainError(error)) {
    // User can retry with new OTP
    return res.status(401).json({
      error: error.message,
      canRetry: true,
    });
  }
  throw error; // Re-throw unexpected errors
}

Integration with Logging

import {
  AuthError,
  isAuthDomainError,
  isAuthUnexpectedError,
} from "@khni/auth-errors";

function logAuthError(error: AuthError) {
  if (isAuthDomainError(error)) {
    logger.warn("Authentication domain error", {
      code: error.code,
      message: error.message,
      meta: error.meta,
    });
  } else if (isAuthUnexpectedError(error)) {
    logger.error("Authentication system error", {
      code: error.code,
      message: error.message,
      cause: error.cause,
      meta: error.meta,
      stack: error.stack,
    });

    // Send to error monitoring service
    sentry.captureException(error);
  }
}

Migration Guide

From v1 to v2

If you're migrating from a previous version:

1. Import paths changed:

   // Before
   import { AuthError } from "@khni/auth-errors";
   
   // After
   import { AuthError } from "@khni/auth-errors";
   // Paths remain the same but internal structure changed

2. Error code constants are now enums:

   // Before
   throw new Error("USER_NOT_FOUND");
   
   // After
   throw new AuthDomainError(AuthErrorCodes.USER_IS_NOT_EXIST);

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-error-codes
3. Commit your changes: git commit -am 'Add new error codes'
4. Push to the branch: git push origin feature/new-error-codes
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• 📚 Full API Documentation
• 🐛 Issue Tracker
• 💬 Discussions