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, which reduces the risk from compromised credentials.

Decision¶

Hop3's second authentication factor is TOTP (via pyotp or equivalent): it requires no hardware, integrates 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. No document should describe MFA as if it shipped. Operators who follow the intended deployment pattern already have an SSH-key factor in front of RPC (CLI → SSH tunnel → RPC); TOTP hardens the password-login path on top of that.

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 phishing-resistant authentication.

Biometrics are not a factor Hop3 can offer. A fingerprint or face check is verified on the user's own device. The server receives an assertion from that device, of the kind FIDO2 already carries, and the protocol is designed so a server can verify it. Anything else amounts to trusting a client's claim to have checked. Biometrics therefore enter, if at all, as the gesture that releases a FIDO2 authenticator's approval.

User Experience¶

User Enrollment:
MFA Enrollment Process: Let users 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 TOTP and hardware tokens to suit different user preferences and capabilities.
MFA Management: Allow users to manage their MFA methods from their account settings.

Consequences¶

Benefits¶

Enhanced Security: Protects user accounts from unauthorized access with a second verification factor.
User Confidence: Increases 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: Issues may arise during 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.