FortressAuth Class

The main orchestrator class for all authentication operations.

Constructor

Creates a new FortressAuth instance with the provided configuration.

import { FortressAuth } from '@fortressauth/core';

const fortress = new FortressAuth(
  repository: AuthRepository,
  rateLimiter: RateLimiterPort,
  emailProvider: EmailProviderPort,
  config?: FortressConfigInput
);

Parameters

Methods

signUp(input)

Creates a new user account with email and password.

interface SignUpInput {
  email: string;
  password: string;
  ipAddress?: string;
  userAgent?: string;
}

const result = await fortress.signUp({
  email: 'user@example.com',
  password: 'securePassword123',
  ipAddress: '127.0.0.1',
  userAgent: 'Mozilla/5.0...',
});

// Returns: Result<AuthResult, AuthErrorCode>
// Success: { success: true, data: { user: User, token: string } }
// Error: { success: false, error: AuthErrorCode }

Possible Errors

• EMAIL_EXISTS - Email already registered
• PASSWORD_TOO_WEAK - Password doesn't meet requirements
• RATE_LIMIT_EXCEEDED - Too many signup attempts
• INVALID_INPUT - Invalid email format or input

signIn(input)

Authenticates a user and creates a new session.

interface SignInInput {
  email: string;
  password: string;
  ipAddress?: string;
  userAgent?: string;
}

const result = await fortress.signIn({
  email: 'user@example.com',
  password: 'securePassword123',
  ipAddress: '127.0.0.1',
});

// Returns: Result<AuthResult, AuthErrorCode>

Possible Errors

• INVALID_CREDENTIALS - Wrong email or password
• ACCOUNT_LOCKED - Account locked due to failed attempts
• EMAIL_NOT_VERIFIED - Email not yet verified
• RATE_LIMIT_EXCEEDED - Too many login attempts

validateSession(rawToken)

Validates a session token and returns the user.

const result = await fortress.validateSession(token);

// Returns: Result<{ user: User, session: Session }, AuthErrorCode>

if (result.success) {
  const { user, session } = result.data;
  console.log('User:', user.email);
  console.log('Session expires:', session.expiresAt);
}

Possible Errors

• SESSION_INVALID - Token is malformed or doesn't exist
• SESSION_EXPIRED - Session has expired

signOut(rawToken)

Invalidates a session token.

const result = await fortress.signOut(token);

// Returns: Result<void, AuthErrorCode>

Possible Errors

• SESSION_INVALID - Token is invalid

verifyEmail(token, context?)

Verifies a user's email address using a verification token.

const result = await fortress.verifyEmail(token, {
  ipAddress: '127.0.0.1',
  userAgent: 'Mozilla/5.0...',
});

// Returns: Result<void, AuthErrorCode>

Possible Errors

• EMAIL_VERIFICATION_INVALID - Token is invalid
• EMAIL_VERIFICATION_EXPIRED - Token has expired
• RATE_LIMIT_EXCEEDED - Too many verification attempts

requestPasswordReset(email)

Initiates a password reset flow by sending a reset email.

const result = await fortress.requestPasswordReset('user@example.com');

// Returns: Result<void, AuthErrorCode>
// Always returns success to prevent email enumeration

resetPassword(input)

Resets a user's password using a reset token.

interface ResetPasswordInput {
  token: string;
  newPassword: string;
  ipAddress?: string;
  userAgent?: string;
}

const result = await fortress.resetPassword({
  token: 'reset-token-from-email',
  newPassword: 'newSecurePassword123',
  ipAddress: '127.0.0.1',
});

// Returns: Result<void, AuthErrorCode>

Possible Errors

• PASSWORD_RESET_INVALID - Token is invalid
• PASSWORD_RESET_EXPIRED - Token has expired
• PASSWORD_TOO_WEAK - New password doesn't meet requirements
• RATE_LIMIT_EXCEEDED - Too many reset attempts

getConfig()

Returns the current configuration (read-only).

const config = fortress.getConfig();

// Returns: Readonly<FortressConfig>
console.log(config.session.ttlMs);
console.log(config.password.minLength);

Type Definitions

AuthResult

interface AuthResult {
  user: User;
  token: string;
}

User

interface User {
  readonly id: string;
  readonly email: string;
  readonly emailVerified: boolean;
  readonly createdAt: Date;
  readonly updatedAt: Date;
  readonly lockedUntil: Date | null;
  
  isLocked(): boolean;
}

Session

interface Session {
  readonly id: string;
  readonly userId: string;
  readonly selector: string;
  readonly verifierHash: string;
  readonly expiresAt: Date;
  readonly ipAddress?: string;
  readonly userAgent?: string;
  readonly createdAt: Date;
  
  isExpired(): boolean;
}

Result Type

type Result<T, E> = 
  | { success: true; data: T }
  | { success: false; error: E };

// Usage:
if (result.success) {
  // TypeScript knows result.data exists
  console.log(result.data);
} else {
  // TypeScript knows result.error exists
  console.error(result.error);
}