Engine: Auth - 2FA TOTP

[ollieread]

TOTP (Time-Based One-Time Password) is the primary 2FA method for launch. It is compatible with any RFC 6238 compliant authenticator app including Google Authenticator and Authy. It implements the TwoFactorProvider contract.

Setup Flow

Before TOTP can be used, the user must configure it. The setup flow:

1. A TOTP secret is generated for the user and stored against their account in a pending state
2. A QR code URI is returned to the client for the user to scan with their authenticator app
3. The user submits a code generated by their app to confirm setup
4. The code is verified against the pending secret — on success the secret is marked as active and TOTP is enabled for the user

TOTP is not considered enabled until the user has successfully confirmed setup. A pending secret that is never confirmed should be discarded.

Verification

TOTP verification uses the active secret stored against the user to verify a submitted code against the current time window. A small window of tolerance is applied to account for clock drift between the server and the user's device.

Disabling

A user can disable TOTP by submitting a valid code. Disabling TOTP removes the active secret from their account.

User Storage

The User entity gains a nullable totp_secret field representing the active TOTP secret, and a nullable totp_pending_secret field for the unconfirmed setup secret.

Tasks

• Implement TOTP secret generation
• Implement QR code URI generation for authenticator app setup
• Implement TotpProvider satisfying the TwoFactorProvider contract
• Implement TOTP setup confirmation flow including pending secret promotion
• Implement TOTP verification with clock drift tolerance
• Implement TOTP disable flow
• Add totp_secret and totp_pending_secret fields to User
• Write tests for setup flow including pending secret promotion on confirmation
• Write tests for verification including clock drift tolerance
• Write tests for unconfirmed pending secret being rejected for verification
• Write tests for disable flow