docs: note WebAuthn enrollment denial changed from 403 to 401+step-up-required in 5.3.4

[devondragon]

Summary

Adds a missing migration note for a consumer-facing behavior change introduced by #371.

#371 changed the stale/factorless-session denial on POST /webauthn/register from a bare HTTP 403 (the filter-chain authorization rule's default, no interpretable body) to HTTP 401 with a JSON body {"message": ..., "error": "step-up-required"}, via the new StepUpEnrollmentAccessDeniedHandler. This matches the passkey delete/rename endpoints so a client can recognize the denial and prompt for a fresh sign-in. The change shipped without a migration note.

This adds a 5.3.3 → 5.3.4 callout to the enrollment-gating section of MIGRATION.md telling clients that branched on the old 403 to also treat a 401 with error code step-up-required as the stale-session case.

How this was found

Surfaced by the pre-release demo-app release-integration test: the demo's chromium-step-up Playwright suite failed because webauthn-register.js branched on the old 403 and fell back to a generic message. The demo-side fix is in a companion PR on the demo repo; both now pass (step-up suite 8/8).

Docs-only change.

https://claude.ai/code/session_01KL5qvKVGQLLQDjHToy34vj

[claude]

Review

Small, well-scoped docs-only change — verified the technical claims against the actual code and they check out.

Verified correct:

• StepUpEnrollmentAccessDeniedHandler (src/main/java/.../security/StepUpEnrollmentAccessDeniedHandler.java) does return HTTP 401 with Content-Type: application/json and body {"message": ..., "error": "step-up-required"} — matches the note.
• WebAuthnStepUpRequiredException.ERROR_CODE is indeed "step-up-required".
• The prior behavior (bare 403 from the filter-chain authorization rule) is consistent with the handler's own Javadoc, which explicitly frames the change as "rather than receiving a bare 403 it cannot interpret."
• gradle.properties currently shows version=5.3.4-SNAPSHOT, so the 5.3.3 → 5.3.4 version callout is accurate for the release this will ship in.

Style/placement:

• Follows the existing convention used elsewhere in MIGRATION.md (e.g. the 5.0.0 → 5.0.1 blockquote note a few paragraphs above) — same format, placed immediately after the paragraph it clarifies, so readers get the update in context rather than in a separate changelog-only section. Good consistency.
• The closing sentence ("Re-running the passkey ceremony cannot satisfy enrollment...") is a nice touch — it heads off the natural but wrong assumption that retrying the WebAuthn ceremony would resolve a 401 here, same as it would for the credential-management endpoints.

Minor nitpick (non-blocking): the note says the old response had "no interpretable body," which is accurate for the default Spring Security 403 (empty body) — just flagging that if any consuming app previously added a custom AccessDeniedHandler for that specific rule, this note doesn't cover that edge case, but that's an extremely unlikely customization to have made on an internal filter-chain default and not worth mentioning in the doc.

No code, tests, or security surface changed — nothing further to flag. LGTM.

[Copilot]

🟡 Changes recommended

The new migration note’s JSON example uses ... (invalid JSON) and should be updated to a valid placeholder format to avoid clients copying an incorrect payload.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds a missing migration note documenting a consumer-facing behavior change in the WebAuthn enrollment endpoint denial response, so client apps can correctly detect the “stale session / step-up required” case when upgrading.

Changes:

• Document that POST /webauthn/register stale/factorless-session denial changed from bare HTTP 403 to HTTP 401 with a step-up-required JSON error contract in 5.3.4.
• Provide client guidance to branch on the new 401 + error=step-up-required condition.

File summaries

File	Description
MIGRATION.md	Adds a 5.3.3 → 5.3.4 callout describing the updated enrollment denial response contract for clients.

Review details

• Files reviewed: 1/1 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.