Security Patterns in Low-Level Design

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

// The core authentication strategy interface
interface AuthenticationStrategy {
    authenticate(credentials: Credentials): Promise<AuthenticationResult>;
    supports(credentialType: CredentialType): boolean;
    getName(): string;
}
 
// Base credentials type - extended by specific credential types
interface Credentials {
    readonly type: CredentialType;
    readonly timestamp: Date;
}
 
interface PasswordCredentials extends Credentials {
    readonly type: CredentialType.PASSWORD;
    readonly username: string;
    readonly password: string;
    readonly rememberMe?: boolean;
}
 
interface OAuthCredentials extends Credentials {
    readonly type: CredentialType.OAUTH;
    readonly provider: OAuthProvider;
    readonly authorizationCode: string;
    readonly redirectUri: string;
}
 
interface BiometricCredentials extends Credentials {
    readonly type: CredentialType.BIOMETRIC;
    readonly biometricType: BiometricType;
    readonly biometricData: Uint8Array;
    readonly deviceId: string;
}
 
// Authentication result encapsulates success or failure
class AuthenticationResult {
    private constructor(
        private readonly _success: boolean,
        private readonly _principal: Principal | null,
        private readonly _error: AuthenticationError | null,
        private readonly _requiresAdditionalFactor: boolean,
        private readonly _partialAuthToken: string | null
    ) {}
 
    static success(principal: Principal): AuthenticationResult {
        return new AuthenticationResult(true, principal, null, false, null);
    }
 
    static failure(error: AuthenticationError): AuthenticationResult {
        return new AuthenticationResult(false, null, error, false, null);
    }
 
    static requiresMfa(partialAuthToken: string): AuthenticationResult {
        return new AuthenticationResult(false, null, null, true, partialAuthToken);
    }
 
    get isSuccess(): boolean { return this._success; }
    get principal(): Principal | null { return this._principal; }
    get error(): AuthenticationError | null { return this._error; }
    get requiresAdditionalFactor(): boolean { return this._requiresAdditionalFactor; }
    get partialAuthToken(): string | null { return this._partialAuthToken; }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

// Authentication filter in the chain
abstract class AuthenticationFilter {
    protected next: AuthenticationFilter | null = null;
 
    setNext(filter: AuthenticationFilter): AuthenticationFilter {
        this.next = filter;
        return filter;
    }
 
    async process(context: AuthenticationContext): Promise<AuthenticationResult> {
        const result = await this.doFilter(context);
        
        // If this filter fails or completes authentication, return
        if (result.isSuccess || result.error || !this.next) {
            return result;
        }
        
        // Pass to next filter in chain
        return this.next.process(context);
    }
 
    protected abstract doFilter(context: AuthenticationContext): Promise<AuthenticationResult>;
}
 
// Concrete filter implementations
class RateLimitFilter extends AuthenticationFilter {
    constructor(private readonly rateLimiter: RateLimiter) {
        super();
    }
 
    protected async doFilter(context: AuthenticationContext): Promise<AuthenticationResult> {
        const key = `auth:${context.ipAddress}:${context.credentials.username}`;
        
        if (await this.rateLimiter.isExceeded(key)) {
            return AuthenticationResult.failure(
                new RateLimitExceededError("Too many authentication attempts. Please try again later.")
            );
        }
        
        // Allow chain to continue
        return AuthenticationResult.continueChain();
    }
}
 
class CredentialValidationFilter extends AuthenticationFilter {
    constructor(
        private readonly credentialValidator: CredentialValidator,
        private readonly passwordHasher: PasswordHasher
    ) {
        super();
    }
 
    protected async doFilter(context: AuthenticationContext): Promise<AuthenticationResult> {
        const user = await this.credentialValidator.findByUsername(context.credentials.username);
        
        if (!user) {
            // Important: Use constant-time comparison to prevent timing attacks
            await this.passwordHasher.verifyDummy();
            return AuthenticationResult.failure(new InvalidCredentialsError());
        }
        
        const isValid = await this.passwordHasher.verify(
            context.credentials.password,
            user.passwordHash
        );
        
        if (!isValid) {
            return AuthenticationResult.failure(new InvalidCredentialsError());
        }
        
        // Attach user to context for subsequent filters
        context.authenticatedUser = user;
        return AuthenticationResult.continueChain();
    }
}
 
class AccountStatusFilter extends AuthenticationFilter {
    protected async doFilter(context: AuthenticationContext): Promise<AuthenticationResult> {
        const user = context.authenticatedUser!;
        
        if (user.isLocked) {
            return AuthenticationResult.failure(
                new AccountLockedError(`Account locked until ${user.lockExpiresAt}`)
            );
        }
        
        if (!user.isEmailVerified && this.requiresEmailVerification) {
            return AuthenticationResult.failure(
                new EmailNotVerifiedError("Please verify your email before logging in.")
            );
        }
        
        if (user.isDisabled) {
            return AuthenticationResult.failure(
                new AccountDisabledError("This account has been disabled.")
            );
        }
        
        return AuthenticationResult.continueChain();
    }
}
 
class MfaCheckFilter extends AuthenticationFilter {
    constructor(private readonly mfaService: MfaService) {
        super();
    }
 
    protected async doFilter(context: AuthenticationContext): Promise<AuthenticationResult> {
        const user = context.authenticatedUser!;
        
        if (!user.mfaEnabled) {
            // MFA not required, continue chain
            return AuthenticationResult.continueChain();
        }
        
        // MFA required but not yet provided
        if (!context.mfaToken) {
            const partialToken = await this.mfaService.createPartialAuthToken(user);
            return AuthenticationResult.requiresMfa(partialToken);
        }
        
        // Validate MFA token
        const mfaValid = await this.mfaService.validateToken(user.id, context.mfaToken);
        if (!mfaValid) {
            return AuthenticationResult.failure(new InvalidMfaTokenError());
        }
        
        return AuthenticationResult.continueChain();
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

// Token configuration - externalized for flexibility
interface TokenConfig {
    readonly accessTokenTtlSeconds: number;
    readonly refreshTokenTtlSeconds: number;
    readonly issuer: string;
    readonly audience: string[];
    readonly algorithm: 'RS256' | 'ES256';  // Asymmetric only for security
}
 
// Claims that will be embedded in the token
interface TokenClaims {
    readonly sub: string;           // Subject (user ID)
    readonly email: string;
    readonly roles: string[];
    readonly permissions: string[];
    readonly sessionId: string;     // Links to server-side session for revocation
    readonly iat: number;           // Issued at
    readonly exp: number;           // Expiration
    readonly iss: string;           // Issuer
    readonly aud: string[];         // Audience
}
 
// Token pair returned after successful authentication
interface TokenPair {
    readonly accessToken: string;
    readonly refreshToken: string;
    readonly accessTokenExpiresAt: Date;
    readonly refreshTokenExpiresAt: Date;
    readonly tokenType: 'Bearer';
}
 
class JwtTokenService implements TokenService {
    constructor(
        private readonly config: TokenConfig,
        private readonly keyProvider: AsymmetricKeyProvider,
        private readonly sessionRepository: SessionRepository,
        private readonly clock: Clock
    ) {}
 
    async generateTokenPair(principal: Principal): Promise<TokenPair> {
        // Create server-side session for revocation capability
        const session = await this.sessionRepository.create({
            userId: principal.id,
            createdAt: this.clock.now(),
            expiresAt: this.clock.nowPlusSeconds(this.config.refreshTokenTtlSeconds),
            userAgent: principal.userAgent,
            ipAddress: principal.ipAddress,
        });
 
        const now = this.clock.nowUnix();
        
        // Access token - short-lived, contains permissions
        const accessTokenClaims: TokenClaims = {
            sub: principal.id,
            email: principal.email,
            roles: principal.roles,
            permissions: principal.permissions,
            sessionId: session.id,
            iat: now,
            exp: now + this.config.accessTokenTtlSeconds,
            iss: this.config.issuer,
            aud: this.config.audience,
        };
 
        // Refresh token - long-lived, minimal claims
        const refreshTokenClaims = {
            sub: principal.id,
            sessionId: session.id,
            type: 'refresh',
            iat: now,
            exp: now + this.config.refreshTokenTtlSeconds,
            iss: this.config.issuer,
        };
 
        const privateKey = await this.keyProvider.getPrivateKey();
        
        const accessToken = await this.signToken(accessTokenClaims, privateKey);
        const refreshToken = await this.signToken(refreshTokenClaims, privateKey);
 
        return {
            accessToken,
            refreshToken,
            accessTokenExpiresAt: new Date((now + this.config.accessTokenTtlSeconds) * 1000),
            refreshTokenExpiresAt: new Date((now + this.config.refreshTokenTtlSeconds) * 1000),
            tokenType: 'Bearer',
        };
    }
 
    async validateAccessToken(token: string): Promise<TokenValidationResult> {
        try {
            const publicKey = await this.keyProvider.getPublicKey();
            const claims = await this.verifyToken(token, publicKey);
            
            // Check if session has been revoked
            const session = await this.sessionRepository.findById(claims.sessionId);
            if (!session || session.revokedAt) {
                return TokenValidationResult.invalid(TokenInvalidReason.SESSION_REVOKED);
            }
            
            return TokenValidationResult.valid(claims);
        } catch (error) {
            if (error instanceof TokenExpiredError) {
                return TokenValidationResult.expired();
            }
            return TokenValidationResult.invalid(TokenInvalidReason.MALFORMED);
        }
    }
 
    async refreshTokens(refreshToken: string): Promise<TokenPair> {
        const publicKey = await this.keyProvider.getPublicKey();
        const claims = await this.verifyToken(refreshToken, publicKey);
        
        if (claims.type !== 'refresh') {
            throw new InvalidTokenTypeError("Expected refresh token");
        }
        
        const session = await this.sessionRepository.findById(claims.sessionId);
        if (!session || session.revokedAt) {
            throw new SessionRevokedError();
        }
        
        // Rotate refresh token for security
        await this.sessionRepository.updateLastRefreshed(session.id, this.clock.now());
        
        const principal = await this.loadPrincipal(claims.sub);
        return this.generateTokenPair(principal);
    }
 
    async revokeSession(sessionId: string): Promise<void> {
        await this.sessionRepository.revoke(sessionId, this.clock.now());
    }
 
    async revokeAllUserSessions(userId: string, exceptSessionId?: string): Promise<number> {
        return this.sessionRepository.revokeAllForUser(userId, this.clock.now(), exceptSessionId);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133

// Rich session entity with security metadata
interface Session {
    readonly id: string;
    readonly userId: string;
    readonly createdAt: Date;
    readonly expiresAt: Date;
    readonly lastActiveAt: Date;
    readonly ipAddress: string;
    readonly userAgent: string;
    readonly deviceFingerprint?: string;
    readonly location?: GeoLocation;
    readonly revokedAt?: Date;
    readonly revocationReason?: SessionRevocationReason;
}
 
enum SessionRevocationReason {
    USER_LOGOUT = 'USER_LOGOUT',
    PASSWORD_CHANGE = 'PASSWORD_CHANGE',
    SECURITY_CONCERN = 'SECURITY_CONCERN',
    ADMIN_ACTION = 'ADMIN_ACTION',
    CONCURRENT_LIMIT = 'CONCURRENT_LIMIT',
    EXPIRED = 'EXPIRED',
}
 
interface SessionRepository {
    create(session: CreateSessionDto): Promise<Session>;
    findById(id: string): Promise<Session | null>;
    findActiveByUserId(userId: string): Promise<Session[]>;
    updateLastActive(id: string, timestamp: Date, ipAddress?: string): Promise<void>;
    revoke(id: string, timestamp: Date, reason: SessionRevocationReason): Promise<void>;
    revokeAllForUser(userId: string, timestamp: Date, exceptId?: string): Promise<number>;
    deleteExpired(): Promise<number>;
}
 
class SessionManager {
    constructor(
        private readonly sessionRepository: SessionRepository,
        private readonly config: SessionConfig,
        private readonly eventPublisher: EventPublisher,
        private readonly clock: Clock
    ) {}
 
    async createSession(
        userId: string,
        context: AuthenticationContext
    ): Promise<Session> {
        // Enforce concurrent session limit
        const activeSessions = await this.sessionRepository.findActiveByUserId(userId);
        
        if (activeSessions.length >= this.config.maxConcurrentSessions) {
            // Revoke oldest session
            const oldest = activeSessions.reduce((a, b) => 
                a.createdAt < b.createdAt ? a : b
            );
            await this.revokeSession(oldest.id, SessionRevocationReason.CONCURRENT_LIMIT);
        }
 
        const session = await this.sessionRepository.create({
            userId,
            createdAt: this.clock.now(),
            expiresAt: this.clock.nowPlusSeconds(this.config.sessionTtlSeconds),
            lastActiveAt: this.clock.now(),
            ipAddress: context.ipAddress,
            userAgent: context.userAgent,
            deviceFingerprint: context.deviceFingerprint,
            location: context.geoLocation,
        });
 
        await this.eventPublisher.publish(new SessionCreatedEvent(session));
        
        return session;
    }
 
    async validateSession(sessionId: string): Promise<SessionValidationResult> {
        const session = await this.sessionRepository.findById(sessionId);
        
        if (!session) {
            return SessionValidationResult.invalid(SessionInvalidReason.NOT_FOUND);
        }
        
        if (session.revokedAt) {
            return SessionValidationResult.invalid(SessionInvalidReason.REVOKED);
        }
        
        if (session.expiresAt < this.clock.now()) {
            return SessionValidationResult.invalid(SessionInvalidReason.EXPIRED);
        }
        
        // Update last active time for sliding expiration
        await this.sessionRepository.updateLastActive(sessionId, this.clock.now());
        
        return SessionValidationResult.valid(session);
    }
 
    async revokeSession(
        sessionId: string,
        reason: SessionRevocationReason
    ): Promise<void> {
        await this.sessionRepository.revoke(sessionId, this.clock.now(), reason);
        await this.eventPublisher.publish(new SessionRevokedEvent(sessionId, reason));
    }
 
    async revokeAllUserSessions(
        userId: string,
        reason: SessionRevocationReason,
        currentSessionId?: string
    ): Promise<number> {
        const count = await this.sessionRepository.revokeAllForUser(
            userId,
            this.clock.now(),
            currentSessionId  // Optionally keep current session active
        );
        
        await this.eventPublisher.publish(
            new AllUserSessionsRevokedEvent(userId, count, reason)
        );
        
        return count;
    }
 
    async getActiveSessions(userId: string): Promise<SessionInfo[]> {
        const sessions = await this.sessionRepository.findActiveByUserId(userId);
        
        return sessions.map(session => ({
            id: session.id,
            createdAt: session.createdAt,
            lastActiveAt: session.lastActiveAt,
            location: session.location,
            deviceInfo: this.parseUserAgent(session.userAgent),
            isCurrent: false,  // Set by caller based on current session ID
        }));
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188

// MFA factor interface - Strategy pattern for different factor types
interface MfaFactor {
    readonly type: MfaFactorType;
    validate(userId: string, input: MfaInput): Promise<MfaValidationResult>;
    generateChallenge(userId: string): Promise<MfaChallenge>;
    isAvailable(userId: string): Promise<boolean>;
}
 
// TOTP implementation
class TotpFactor implements MfaFactor {
    readonly type = MfaFactorType.TOTP;
    
    constructor(
        private readonly userMfaRepository: UserMfaRepository,
        private readonly totpGenerator: TotpGenerator,
        private readonly clock: Clock
    ) {}
 
    async validate(userId: string, input: TotpInput): Promise<MfaValidationResult> {
        const mfaConfig = await this.userMfaRepository.findByUserIdAndType(
            userId,
            MfaFactorType.TOTP
        );
        
        if (!mfaConfig || !mfaConfig.secret) {
            return MfaValidationResult.factorNotConfigured();
        }
        
        // Validate with time window for clock drift
        const isValid = this.totpGenerator.validate(
            input.code,
            mfaConfig.secret,
            {
                window: 1,  // Allow ±30 seconds
                time: this.clock.nowUnix(),
            }
        );
        
        if (!isValid) {
            await this.recordFailedAttempt(userId);
            return MfaValidationResult.invalid();
        }
        
        // Prevent code reuse
        if (await this.isCodeRecentlyUsed(userId, input.code)) {
            return MfaValidationResult.codeAlreadyUsed();
        }
        
        await this.recordUsedCode(userId, input.code);
        return MfaValidationResult.valid();
    }
 
    async generateChallenge(userId: string): Promise<TotpChallenge> {
        // TOTP doesn't require server-side challenge generation
        return {
            type: MfaFactorType.TOTP,
            message: "Enter the 6-digit code from your authenticator app",
        };
    }
}
 
// WebAuthn/FIDO2 implementation for hardware keys
class WebAuthnFactor implements MfaFactor {
    readonly type = MfaFactorType.WEBAUTHN;
    
    constructor(
        private readonly webAuthnRepository: WebAuthnCredentialRepository,
        private readonly challengeStore: ChallengeStore,
        private readonly relyingParty: RelyingParty
    ) {}
 
    async generateChallenge(userId: string): Promise<WebAuthnChallenge> {
        const credentials = await this.webAuthnRepository.findByUserId(userId);
        
        const challenge = crypto.getRandomValues(new Uint8Array(32));
        await this.challengeStore.store(userId, challenge, 300);  // 5 minute TTL
        
        return {
            type: MfaFactorType.WEBAUTHN,
            challenge: base64url.encode(challenge),
            rpId: this.relyingParty.id,
            allowCredentials: credentials.map(c => ({
                type: 'public-key',
                id: c.credentialId,
            })),
            timeout: 60000,
            userVerification: 'preferred',
        };
    }
 
    async validate(userId: string, input: WebAuthnInput): Promise<MfaValidationResult> {
        const expectedChallenge = await this.challengeStore.retrieve(userId);
        if (!expectedChallenge) {
            return MfaValidationResult.challengeExpired();
        }
        
        const credential = await this.webAuthnRepository.findByCredentialId(
            input.credentialId
        );
        
        if (!credential || credential.userId !== userId) {
            return MfaValidationResult.invalid();
        }
        
        // Verify the assertion
        const isValid = await this.verifyAssertion(
            input,
            expectedChallenge,
            credential.publicKey
        );
        
        if (!isValid) {
            return MfaValidationResult.invalid();
        }
        
        // Update signature counter for clone detection
        await this.webAuthnRepository.updateSignatureCounter(
            credential.id,
            input.signatureCounter
        );
        
        return MfaValidationResult.valid();
    }
}
 
// MFA orchestration service
class MfaService {
    constructor(
        private readonly factors: Map<MfaFactorType, MfaFactor>,
        private readonly userMfaRepository: UserMfaRepository,
        private readonly partialAuthStore: PartialAuthStore,
        private readonly eventPublisher: EventPublisher
    ) {}
 
    async createPartialAuthToken(user: User): Promise<string> {
        const token = crypto.randomUUID();
        
        await this.partialAuthStore.store(token, {
            userId: user.id,
            completedFactor: 'password',
            requiredFactors: await this.getRequiredFactors(user.id),
            createdAt: new Date(),
            expiresAt: new Date(Date.now() + 300000),  // 5 minutes
        });
        
        return token;
    }
 
    async validateFactor(
        partialToken: string,
        factorType: MfaFactorType,
        input: MfaInput
    ): Promise<MfaAuthResult> {
        const partialAuth = await this.partialAuthStore.retrieve(partialToken);
        
        if (!partialAuth || partialAuth.expiresAt < new Date()) {
            return MfaAuthResult.sessionExpired();
        }
        
        const factor = this.factors.get(factorType);
        if (!factor) {
            return MfaAuthResult.unsupportedFactor();
        }
        
        const result = await factor.validate(partialAuth.userId, input);
        
        if (!result.isValid) {
            return MfaAuthResult.factorFailed(result.reason);
        }
        
        // Check if all required factors are now complete
        const remainingFactors = partialAuth.requiredFactors.filter(
            f => f !== factorType && !partialAuth.completedFactors?.includes(f)
        );
        
        if (remainingFactors.length === 0) {
            await this.partialAuthStore.delete(partialToken);
            return MfaAuthResult.complete(partialAuth.userId);
        }
        
        // More factors required
        await this.partialAuthStore.update(partialToken, {
            completedFactors: [...(partialAuth.completedFactors || []), factorType],
        });
        
        return MfaAuthResult.requiresAdditionalFactor(remainingFactors);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178

// The main authentication service - facade over authentication subsystems
class AuthenticationService {
    private readonly authenticationChain: AuthenticationFilter;
 
    constructor(
        private readonly strategyRegistry: AuthenticationStrategyRegistry,
        private readonly tokenService: TokenService,
        private readonly sessionManager: SessionManager,
        private readonly mfaService: MfaService,
        private readonly auditLogger: SecurityAuditLogger,
        private readonly eventPublisher: EventPublisher,
        rateLimiter: RateLimiter,
        credentialValidator: CredentialValidator,
        passwordHasher: PasswordHasher
    ) {
        // Build the authentication filter chain
        this.authenticationChain = this.buildAuthenticationChain(
            rateLimiter,
            credentialValidator,
            passwordHasher
        );
    }
 
    private buildAuthenticationChain(
        rateLimiter: RateLimiter,
        credentialValidator: CredentialValidator,
        passwordHasher: PasswordHasher
    ): AuthenticationFilter {
        const rateLimit = new RateLimitFilter(rateLimiter);
        const credentialValidation = new CredentialValidationFilter(
            credentialValidator,
            passwordHasher
        );
        const accountStatus = new AccountStatusFilter();
        const mfaCheck = new MfaCheckFilter(this.mfaService);
 
        // Chain filters together
        rateLimit
            .setNext(credentialValidation)
            .setNext(accountStatus)
            .setNext(mfaCheck);
 
        return rateLimit;
    }
 
    async authenticate(request: AuthenticationRequest): Promise<AuthenticationResponse> {
        const context = this.createContext(request);
        
        try {
            // Run through authentication chain
            const result = await this.authenticationChain.process(context);
            
            if (result.requiresAdditionalFactor) {
                await this.auditLogger.logMfaRequired(context);
                return AuthenticationResponse.mfaRequired(
                    result.partialAuthToken,
                    await this.mfaService.getAvailableFactors(context.authenticatedUser!.id)
                );
            }
            
            if (!result.isSuccess) {
                await this.recordFailedAttempt(context, result.error!);
                return AuthenticationResponse.failure(result.error!);
            }
            
            // Authentication successful - issue tokens
            return await this.completeAuthentication(context);
            
        } catch (error) {
            await this.auditLogger.logAuthenticationError(context, error);
            throw error;
        }
    }
 
    async completeMfaAuthentication(
        partialToken: string,
        factorType: MfaFactorType,
        input: MfaInput,
        context: RequestContext
    ): Promise<AuthenticationResponse> {
        const result = await this.mfaService.validateFactor(
            partialToken,
            factorType,
            input
        );
        
        if (!result.isComplete) {
            if (result.isExpired) {
                return AuthenticationResponse.failure(
                    new MfaSessionExpiredError()
                );
            }
            if (result.requiresAdditionalFactor) {
                return AuthenticationResponse.mfaRequired(
                    partialToken,
                    result.remainingFactors
                );
            }
            return AuthenticationResponse.failure(new InvalidMfaTokenError());
        }
        
        // MFA complete - load user and issue tokens
        const user = await this.loadUser(result.userId);
        const authContext = this.createContextForUser(user, context);
        
        return await this.completeAuthentication(authContext);
    }
 
    private async completeAuthentication(
        context: AuthenticationContext
    ): Promise<AuthenticationResponse> {
        const user = context.authenticatedUser!;
        
        // Create session
        const session = await this.sessionManager.createSession(user.id, context);
        
        // Generate tokens
        const principal = this.buildPrincipal(user, session.id);
        const tokens = await this.tokenService.generateTokenPair(principal);
        
        // Log successful authentication
        await this.auditLogger.logSuccessfulAuthentication(context, session);
        
        // Publish event for other systems
        await this.eventPublisher.publish(
            new UserAuthenticatedEvent(user.id, session.id, context.ipAddress)
        );
        
        // Check for suspicious patterns
        await this.checkForAnomalies(context, session);
        
        return AuthenticationResponse.success(tokens, this.sanitizeUser(user));
    }
 
    async logout(sessionId: string, userId: string): Promise<void> {
        await this.sessionManager.revokeSession(
            sessionId,
            SessionRevocationReason.USER_LOGOUT
        );
        
        await this.eventPublisher.publish(new UserLoggedOutEvent(userId, sessionId));
        await this.auditLogger.logLogout(userId, sessionId);
    }
 
    async logoutAllDevices(userId: string, currentSessionId?: string): Promise<void> {
        const revokedCount = await this.sessionManager.revokeAllUserSessions(
            userId,
            SessionRevocationReason.USER_LOGOUT,
            currentSessionId
        );
        
        await this.auditLogger.logLogoutAllDevices(userId, revokedCount);
    }
 
    private async checkForAnomalies(
        context: AuthenticationContext,
        session: Session
    ): Promise<void> {
        // Check for impossible travel
        const recentSessions = await this.sessionManager.getRecentSessions(
            context.authenticatedUser!.id,
            10
        );
        
        if (this.detectImpossibleTravel(session, recentSessions)) {
            await this.eventPublisher.publish(
                new SuspiciousLoginEvent(session, 'IMPOSSIBLE_TRAVEL')
            );
        }
        
        // Check for new device
        if (!recentSessions.some(s => s.deviceFingerprint === session.deviceFingerprint)) {
            await this.eventPublisher.publish(
                new NewDeviceLoginEvent(session)
            );
        }
    }
}