ADR 012: Multi-Factor Authentication (MFA)¶

Status: Deferred
Type: Feature
Created: 2024-07-17
Related-ADRs: 010, 011, 014

Context and Goals¶

Hop3's authentication model issues JWT tokens after password login (or magic link), protected by bcrypt password hashing and per-IP rate limiting on /auth/login and /auth/magic/{token}. Server-side RPC access is gated by the operator's SSH key on the host, which provides an SSH-backed second factor for operators following the intended deployment pattern (CLI → SSH tunnel → RPC).

Multi-Factor Authentication (MFA) further hardens user accounts against unauthorized access by requiring two or more verification factors, reducing the risk of compromised credentials.

Decision¶

Hop3's second authentication factor is TOTP (via pyotp or equivalent): it requires no hardware, integrates cleanly with the existing JWT flow (TOTP verification gates token issuance), and has a well-understood operator UX. Hardware tokens (U2F / FIDO2) are the layer above it once TOTP is in place.

This ADR is Deferred: the design below is settled, the implementation is not built. Nothing in Hop3 today enforces a second factor on the password-login path, and no document should describe MFA as if it shipped. What operators do have, when they follow the intended deployment pattern, is an SSH-key factor in front of RPC (CLI → SSH tunnel → server); TOTP hardens the password-login path on top of that rather than replacing it.

Design¶

MFA Implementation¶

One-Time Passwords (OTP):
Time-based OTP (TOTP): Integrate TOTP as a second factor, generated via authenticator apps. TOTP gates JWT issuance in the existing login flow.
Hardware Tokens:
U2F and FIDO2: Support Universal 2^nd Factor (U2F) and FIDO2 hardware tokens for strong, phishing-resistant authentication.

Biometrics are not a factor Hop3 can offer. A fingerprint or face check is verified on the user's own device, and what reaches the server is an assertion from that device, which is what FIDO2 already carries, through a protocol designed to make the assertion verifiable. Anything else amounts to trusting a client's claim to have checked. Biometrics therefore enter, if at all, as a FIDO2 authenticator's unlock gesture, not as a separate mechanism.

User Experience¶

User Enrollment:
MFA Enrollment Process: Implement an enrollment process for users to set up MFA on their accounts.
Backup Codes: Provide backup codes for users to access their accounts in case their primary MFA method is unavailable.
Flexibility:
Multiple MFA Options: Offer multiple MFA options to cater to different user preferences and capabilities.
MFA Management: Allow users to manage their MFA settings and preferences from their account settings.

Consequences¶

Benefits¶

Enhanced Security: Provides an additional layer of security to protect user accounts from unauthorized access.
User Confidence: Increases user confidence in the platform's security measures.
Compliance: Helps meet regulatory requirements for strong authentication mechanisms.

Drawbacks¶

User Convenience: May introduce inconvenience for users who prefer simpler login processes.
Implementation Complexity: Integrating and managing multiple MFA methods can be complex.

Risks¶

Adoption Resistance: Some users may resist adopting MFA due to perceived inconvenience. Mitigation involves providing clear instructions and support.
Technical Issues: Potential technical issues with MFA implementation. Mitigation includes thorough testing and support.

Alternatives Considered¶

SMS OTP: Delivering one-time passwords over SMS is an explicit non-goal. SIM-swapping and telecom-compromise risks make it unsuitable as a second factor for administrator accounts; it is rejected.