Multi-Factor Authentication

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

import speakeasy from 'speakeasy';
import qrcode from 'qrcode';
 
interface TOTPSetup {
  secret: string;           // Base32-encoded secret
  otpauthUrl: string;       // URL for QR code
  qrCodeDataUrl: string;    // Base64 QR code image
}
 
// Generate new TOTP secret for user enrollment
async function generateTOTPSecret(
  userEmail: string,
  issuer: string = 'MyApp'
): Promise<TOTPSetup> {
  // Generate cryptographically random secret
  const secret = speakeasy.generateSecret({
    length: 20,          // 160 bits
    name: userEmail,
    issuer: issuer,
  });
  
  // Generate QR code for authenticator apps
  const qrCodeDataUrl = await qrcode.toDataURL(secret.otpauth_url!);
  
  return {
    secret: secret.base32,           // Store this securely
    otpauthUrl: secret.otpauth_url!, // For manual entry
    qrCodeDataUrl,                   // Display to user
  };
}
 
// Verify TOTP code during authentication
function verifyTOTPCode(
  userSecret: string, 
  submittedCode: string
): boolean {
  return speakeasy.totp.verify({
    secret: userSecret,
    encoding: 'base32',
    token: submittedCode,
    window: 1,    // Accept codes from T-1, T, T+1 (90-second window)
  });
}
 
// Example enrollment flow
async function enrollUserMFA(userId: string): Promise<TOTPSetup> {
  const user = await db.users.findById(userId);
  const setup = await generateTOTPSecret(user.email);
  
  // IMPORTANT: Store encrypted secret, not plaintext
  await db.users.updateOne(
    { id: userId },
    { 
      totpSecretEncrypted: encrypt(setup.secret),
      mfaEnabled: false,  // Not enabled until verified
      mfaPending: true,
    }
  );
  
  return setup;
}
 
// Confirm enrollment with verification code
async function confirmMFAEnrollment(
  userId: string, 
  code: string
): Promise<boolean> {
  const user = await db.users.findById(userId);
  const secret = decrypt(user.totpSecretEncrypted);
  
  if (verifyTOTPCode(secret, code)) {
    await db.users.updateOne(
      { id: userId },
      { mfaEnabled: true, mfaPending: false }
    );
    
    // Generate backup codes
    const backupCodes = await generateBackupCodes(userId);
    return backupCodes;
  }
  
  return false;
}

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

import {
  generateRegistrationOptions,
  verifyRegistrationResponse,
  generateAuthenticationOptions,
  verifyAuthenticationResponse,
} from '@simplewebauthn/server';
 
const rpName = 'My Application';
const rpID = 'example.com';
const origin = 'https://example.com';
 
// Step 1: Generate registration options
async function startRegistration(user: User) {
  const options = await generateRegistrationOptions({
    rpName,
    rpID,
    userID: user.id,
    userName: user.email,
    attestationType: 'none',  // Or 'direct' for attestation verification
    authenticatorSelection: {
      residentKey: 'preferred',
      userVerification: 'preferred',
      authenticatorAttachment: 'cross-platform',  // Hardware keys
    },
  });
  
  // Store challenge for verification
  await redis.set(`webauthn:reg:${user.id}`, options.challenge, 'EX', 300);
  
  return options;
}
 
// Step 2: Verify registration response
async function finishRegistration(user: User, response: RegistrationResponse) {
  const expectedChallenge = await redis.get(`webauthn:reg:${user.id}`);
  
  const verification = await verifyRegistrationResponse({
    response,
    expectedChallenge,
    expectedOrigin: origin,
    expectedRPID: rpID,
  });
  
  if (verification.verified && verification.registrationInfo) {
    const { credentialID, credentialPublicKey, counter } = verification.registrationInfo;
    
    // Store credential for this user
    await db.credentials.create({
      userId: user.id,
      credentialId: Buffer.from(credentialID).toString('base64url'),
      publicKey: Buffer.from(credentialPublicKey).toString('base64'),
      counter,
      createdAt: new Date(),
    });
    
    return { success: true };
  }
  
  return { success: false };
}
 
// Step 3: Generate authentication options
async function startAuthentication(user: User) {
  const userCredentials = await db.credentials.findByUserId(user.id);
  
  const options = await generateAuthenticationOptions({
    rpID,
    allowCredentials: userCredentials.map(cred => ({
      id: Buffer.from(cred.credentialId, 'base64url'),
      type: 'public-key',
    })),
    userVerification: 'preferred',
  });
  
  await redis.set(`webauthn:auth:${user.id}`, options.challenge, 'EX', 300);
  
  return options;
}
 
// Step 4: Verify authentication response
async function finishAuthentication(user: User, response: AuthenticationResponse) {
  const expectedChallenge = await redis.get(`webauthn:auth:${user.id}`);
  const credential = await db.credentials.findByCredentialId(
    Buffer.from(response.id, 'base64url').toString('base64url')
  );
  
  const verification = await verifyAuthenticationResponse({
    response,
    expectedChallenge,
    expectedOrigin: origin,
    expectedRPID: rpID,
    authenticator: {
      credentialID: Buffer.from(credential.credentialId, 'base64url'),
      credentialPublicKey: Buffer.from(credential.publicKey, 'base64'),
      counter: credential.counter,
    },
  });
  
  if (verification.verified) {
    // Update counter to prevent replay attacks
    await db.credentials.updateCounter(credential.id, verification.authenticationInfo.newCounter);
    return { success: true };
  }
  
  return { success: false };
}

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

import crypto from 'crypto';
import argon2 from 'argon2';
 
interface BackupCode {
  hash: string;      // Argon2 hash of the code
  used: boolean;
  usedAt?: Date;
}
 
// Generate backup codes during MFA enrollment
async function generateBackupCodes(userId: string): Promise<string[]> {
  const codes: string[] = [];
  const codeRecords: BackupCode[] = [];
  
  for (let i = 0; i < 10; i++) {
    // Generate 8-character alphanumeric code
    const code = crypto.randomBytes(6).toString('base64url').slice(0, 8).toUpperCase();
    codes.push(code);
    
    // Store hash of the code (not the code itself)
    const hash = await argon2.hash(code, {
      type: argon2.argon2id,
      memoryCost: 16384,    // Lower than login (speed vs security for recovery)
      timeCost: 2,
      parallelism: 1,
    });
    
    codeRecords.push({ hash, used: false });
  }
  
  // Store hashed codes
  await db.users.updateOne(
    { id: userId },
    { 
      backupCodes: codeRecords,
      backupCodesGeneratedAt: new Date(),
      backupCodesRemaining: 10,
    }
  );
  
  // Return plaintext codes to display to user ONCE
  return codes;
}
 
// Use backup code for recovery
async function useBackupCode(userId: string, submittedCode: string): Promise<boolean> {
  const user = await db.users.findById(userId);
  
  for (const codeRecord of user.backupCodes) {
    if (codeRecord.used) continue;
    
    // Check if this code matches
    if (await argon2.verify(codeRecord.hash, submittedCode.toUpperCase())) {
      // Mark code as used
      await db.users.updateOne(
        { id: userId, 'backupCodes.hash': codeRecord.hash },
        { 
          $set: { 
            'backupCodes.$.used': true,
            'backupCodes.$.usedAt': new Date(),
          },
          $inc: { backupCodesRemaining: -1 },
        }
      );
      
      // Alert user that a backup code was used
      await sendEmail(user.email, 'Backup code used', 
        'A backup recovery code was just used on your account...');
      
      return true;
    }
  }
  
  return false;
}

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

import { Request, Response, NextFunction } from 'express';
 
// Authentication levels
enum AuthLevel {
  NONE = 0,
  BASIC = 1,           // Password, possibly old
  RECENT = 2,          // Password within last 10 minutes
  MFA_RECENT = 3,      // Password + MFA within last 10 minutes
}
 
interface AuthSession {
  userId: string;
  level: AuthLevel;
  passwordAuthAt: Date;
  mfaAuthAt?: Date;
}
 
// Middleware factory for requiring specific auth level
function requireAuthLevel(requiredLevel: AuthLevel) {
  return async (req: Request, res: Response, next: NextFunction) => {
    const session = req.session as AuthSession;
    
    if (!session.userId) {
      return res.status(401).json({ 
        error: 'authentication_required',
        message: 'Please log in to continue',
        redirectTo: '/login',
      });
    }
    
    const currentLevel = calculateCurrentAuthLevel(session);
    
    if (currentLevel >= requiredLevel) {
      return next();  // Sufficient authentication
    }
    
    // Determine what additional auth is needed
    const stepUpRequired = determineStepUp(currentLevel, requiredLevel);
    
    return res.status(403).json({
      error: 'step_up_required',
      message: 'Additional verification required for this action',
      currentLevel,
      requiredLevel,
      stepUp: stepUpRequired,  // 'password' | 'mfa' | 'both'
      redirectTo: '/verify',
    });
  };
}
 
function calculateCurrentAuthLevel(session: AuthSession): AuthLevel {
  const TEN_MINUTES = 10 * 60 * 1000;
  const now = Date.now();
  
  const passwordRecent = session.passwordAuthAt && 
    (now - session.passwordAuthAt.getTime()) < TEN_MINUTES;
    
  const mfaRecent = session.mfaAuthAt && 
    (now - session.mfaAuthAt.getTime()) < TEN_MINUTES;
  
  if (passwordRecent && mfaRecent) return AuthLevel.MFA_RECENT;
  if (passwordRecent) return AuthLevel.RECENT;
  if (session.userId) return AuthLevel.BASIC;
  return AuthLevel.NONE;
}
 
// Usage in routes
app.post('/account/change-password', 
  requireAuthLevel(AuthLevel.MFA_RECENT),
  changePasswordHandler
);
 
app.get('/account/security-settings',
  requireAuthLevel(AuthLevel.RECENT),
  securitySettingsHandler
);
 
app.get('/dashboard',
  requireAuthLevel(AuthLevel.BASIC),
  dashboardHandler
);