fix(web): MFA status detection false positive + auth architecture docs

[FSM1]

Summary

• Fix MFA status detection: Changed details.totalFactors >= 2 to details.totalFactors > 2 in useMfa.ts. Every Web3Auth MPC Core Kit account starts with 2 default factors (JWT verifier share + hashedShare cloud custodial key), so the old check was always true — falsely showing MFA as [ENABLED] for every user. After enableMFA() deletes the hashedShare and creates device + recovery factors, totalFactors becomes 3+.
• Add authentication architecture doc: New docs/AUTHENTICATION_ARCHITECTURE.md covering the MPC Core Kit key hierarchy, custom verifier flow, factor lifecycle (pre/post MFA), security analysis of semi-custodial vs non-custodial trust models, cross-device approval protocol, and MFA status detection logic.
• Capture todo: Alternative MFA factor types research (passkey via WebAuthn PRF, password-derived key, secondary OAuth) noted for future phases.

Test plan

• Verify fresh account (no MFA enrolled) shows [DISABLED] status badge on Security tab
• Verify account after enableMFA() shows [ENABLED] status badge
• TypeScript compiles: pnpm --filter web exec tsc --noEmit
• Review docs/AUTHENTICATION_ARCHITECTURE.md for accuracy

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Fixed false positive MFA status detection that incorrectly marked newly created accounts as having MFA enabled.

• Documentation

  • Added comprehensive authentication architecture documentation covering end-to-end authentication flows, key derivation, MFA state transitions, and cross-device approval processes.

[coderabbitai]

Walkthrough

This PR fixes an MFA status detection false positive by adjusting the enabled threshold from ≥2 to >2 factors in useMfa.ts, eliminating incorrect MFA enabled status on fresh accounts. It includes planning documents for the fix and a new proposal for alternative MFA factor types, plus comprehensive authentication architecture documentation.

Changes

Cohort / File(s)	Summary
Planning and State Updates .planning/STATE.md, .planning/quick/022-fix-mfa-status-detection-false-positive/022-PLAN.md, .planning/quick/022-fix-mfa-status-detection-false-positive/022-SUMMARY.md, .planning/todos/pending/2026-02-26-alternative-mfa-factor-types.md	Updated progress tracking, session continuity, and task logs reflecting completion of task 022. New planning document for alternative MFA factor types proposal (Passkey/WebAuthn PRF, password-derived keys, secondary OAuth).
MFA Status Detection Logic apps/web/src/hooks/useMfa.ts	Changed MFA enabled threshold from totalFactors >= 2 to totalFactors > 2 with updated JSDoc comment explaining that default accounts have two initial factors (JWT verifier share and hashedShare) and MFA requires 3+ factors.
Authentication Documentation docs/AUTHENTICATION_ARCHITECTURE.md	New comprehensive documentation describing CipherBox Web3Auth MPC Core Kit key architecture, end-to-end authentication flows, factor partitioning across pre/post-MFA states, security analyses, and cross-device approval flows.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• feat(12.4): MFA + Cross-Device Approval #128: Directly relates to useMfa.ts modifications; the referenced PR implements/overhauls the useMfa hook and related MFA flow, while this PR adjusts the MFA-enabled threshold logic within the same file.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the two main changes: fixing an MFA status detection false positive and adding authentication architecture documentation.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/mfa-status-false-positive

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}