docs(diagnosis): mobile auth method failure root-cause report (2026-05-30)

[ahmetabdullahgultekin]

Summary

• Comprehensive 12-section diagnosis of "no MFA method passes" symptom from ahabgu@gmail.com on FIVUCSAS Mobile v5.2.2 against prod identity-core-api today.
• Backend is healthy — same user completed TOTP/EMAIL_OTP/FINGERPRINT successfully 7+ times in last 72h (audit_logs success=t). What's new is network conditions + active flow shape.
• Primary cause: 4 server-side Malformed request body: I/O error while reading input message events at 16:16-16:31 UTC — request bodies aborting mid-stream on the user's ~1 Mbps cellular uplink. Methods with small JSON bodies (PASSWORD ~80 B, SMS_OTP ~110 B) succeed; methods with large bodies (FACE 20-200 KB, VOICE 100-500 KB, WebAuthn 2-5 KB) fail to upload.
• Secondary cause: Tenant Fivucsas active flow is "Default 3-Step Flow" (PASSWORD + EMAIL_OTP + FACE) — step 3 binds FACE only; mobile picker shows all 9 enrolled methods, server returns METHOD_NOT_PERMITTED for non-FACE picks, app maps to generic error → user reads as "this method gives error".
• Latent v5.2.2 bug (fixed in v5.2.3): cacheLoginData throw-inside-verify-try flips a 200 AUTHENTICATED into "Verification failed". Present on user's device but NOT today's blocker (only triggers on final-step success path).

Evidence (all verified live)

• Server log timeline 16:03 → 16:31 UTC with request IDs.
• audit_logs snapshot for ahabgu (3 events today: 2× USER_LOGIN, 1× MFA_STEP_COMPLETED SMS_OTP; zero MFA_STEP_FAILED — failures never reached the handler).
• auth_flows + auth_flow_steps DB query confirming 3-step PASSWORD/EMAIL_OTP/FACE config.
• Independent e2e-sweep@fivucsas.local login → HTTP 200, mfaRequired=false (pipeline healthy).
• Mobile dispatch map from MfaFlowScreen.kt:439-531 (method → body-field → size estimate).

Recommendations (12 items, ranked)

• P0 mobile: aggressive face-image compression (≤30 KB), retry-on-IOException with backoff.
• P1 mobile: longer Ktor write timeout, HTTP/1.1 fallback on cellular, upload progress + low-signal banner, install v5.2.3.
• P1 backend: log Content-Length + path in handleHttpMessageNotReadable, emit MFA_REQUEST_TRUNCATED audit row.
• Operator: confirm 3-step flow is intentional; if yes, add TOTP/FINGERPRINT as alternatives at step 3 so users with broken camera/network can still finish.

Test plan

• Review the verified vs. unverified separation in §7 — flag anything that needs deeper confirmation.
• Confirm whether the "Default 3-Step Flow" superseding the prior 2-step CHOICE flow was intentional.
• (Optional) Cross-check the FINGERPRINT dispatch field name (fingerprintData vs assertion) against FingerprintVerifyMfaStepHandler.java.
• Adopt P0 fixes for v5.2.4 milestone.

🤖 Generated with Claude Code

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.