fix(mfa): return the spec's auth-factor enrollment envelope

[gjtorikian]

Summary

Fixes #110. Verified against production (userland-user-authentication-factors.controller.ts), the published OpenAPI spec, and all 11 backend SDKs.

• Enrollment envelope. POST /user_management/users/:id/auth_factors returned a bare factor where the spec's UserlandUserAuthenticationFactorEnrollResponse wraps it as { authentication_factor, authentication_challenge }. The Node SDK threw a TypeError; Python, Kotlin, Android, Rust, Swift and PHP refused to deserialize; Go, Ruby, .NET and Elixir silently returned nil for both halves. No SDK could drive TOTP enrollment through the emulator.
• TOTP secrets. The wrapper alone was not enough: the spec's enrolled factor requires totp.secret, totp.qr_code and totp.uri, and the same SDKs fail one level down without them. Enrollment now mints a 32-character Base32 secret (honoring a caller-supplied totp_secret, validated as production does, 422 invalid_totp_secret otherwise) and is the only response that shows it — GET and LIST return the spec's secretless AuthenticationFactor, as production does. Also fixes totp_user being ignored.
• Challenge field name. Every authentication_challenge on the wire (challenge routes, the password grant's mfa_challenge step, legacy MFA) carried the store's factor_id/user_id where the spec has authentication_factor_id and no user. Seven SDKs hard-fail on this. Changed at the single formatter every route already goes through; the store keeps its columns.
• text/plain on 204. Not the handler's doing — @hono/node-server 1.x stamped a text/plain default on every response without one, empty body included, so all 27 no-content routes were affected. 2.x skips the default for a null body; bumping fixes them all with no adapter workaround. (Only serve is used; the only 2.x breaking change is dropping Node 18, and engines already requires ≥22.)

Notes

• qr_code is a valid 1×1 PNG rather than a scannable code: the field is required and typed as a string, the emulator never verifies a real TOTP code, and uri already carries everything the code would. Marked with a ponytail: comment naming the upgrade path.
• Why the spec conformance loops didn't catch this. response-envelopes.spec.ts already hits each cataloged route live and diffs the body against the OpenAPI spec, but no MFA operation or resource was in the curated catalogs — a coverage gap, not a design one. The last commit adds the six MFA operations with a JSON body and the two resources to the catalogs, regenerates them, and adds the live cases. Run against main without the fix, those cases fail six times, each naming one of the drifts above. The loops diff top-level keys only, so the nested totp.secret/qr_code/uri requirement is pinned by the new auth-factors.spec.ts instead.

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge; the previously reported secret-type contract issue is fixed and no new actionable failures remain.

Summary

This PR aligns MFA enrollment and challenge responses with the published API contract.

• Returns the authentication-factor enrollment envelope with an enrolled factor and challenge.
• Generates and validates Base32 TOTP secrets while limiting secret disclosure to enrollment responses.
• Maps stored challenge fields to their public schema names.
• Expands MFA response-shape and route coverage.
• Upgrades @hono/node-server to correct headers on empty responses.

Diagram

sequenceDiagram
    participant SDK
    participant Emulator
    participant Store

    SDK->>Emulator: "POST /users/{id}/auth_factors"
    Emulator->>Emulator: Validate or generate Base32 secret
    Emulator->>Store: Insert authentication factor
    Emulator->>Store: Insert enrollment challenge
    Emulator-->>SDK: "201 {authentication_factor, authentication_challenge}"

    SDK->>Emulator: GET/LIST authentication factors
    Emulator->>Store: Read stored factor
    Emulator-->>SDK: Secretless AuthenticationFactor

Loading

_{Reviews (3) · Last reviewed commit: "fix(mfa): reject a non-string totp_secre..."}