docs(rp): document step-up authentication for relying parties

[StaberindeZA]

Description

RP-facing documentation for the step-up authentication work in FXA-12763 — acr_values, max_age, and the acr / auth_time / amr claims. None of this was documented anywhere: a grep of docs/ before this PR found zero occurrences of acr_values, AAL2, max_age, auth_time, or "step-up". AMO cannot integrate from what exists today.

New page — relying-parties/how-tos/step-up-authentication.md:

• When to use it, and how it differs from prompt=login (which prompts for a password; step-up deliberately does not)
• Requesting elevation, including that AAL2 is the only recognised acr_values token and others are silently ignored
• Choosing a max_age — the most consequential integration decision, including the five-second leeway and the fact that freshness is a property of the shared browser session, so another RP's challenge can satisfy yours
• Reading the claims, split by token type, with the seconds-vs-milliseconds introspection gotcha and the reason RPs must verify auth_time themselves
• Elevation does not survive a token refresh — and a refreshed token still introspects as active: true
• Inline enrolment for users with no second factor
• prompt=none failing with unmet_authentication_requirements
• The resource-server WWW-Authenticate challenge (RFC 9470 §3), which is the RP's half to implement and was previously unowned by any ticket
• Current limitations, each linked to its tracking ticket

Existing pages:

• query-parameters — acr_values and max_age entries
• using-apis — a new section distinguishing an insufficient_user_authentication 401 from an expired-token 401. The existing advice ("on a 401, refresh") is actively wrong for the former, because elevation is deliberately not carried by refresh tokens, so the retry loops.
• using-apis — a callout for the auth_time / auth_at semantics change from FXA-14308, which affects every RP, not only step-up integrators
• glossary — AAL, ACR, AMR, step-up authentication
• tokens — acr / auth_time on JWT access tokens, and the ID token claims
• integrating-with-fxa — parameters in the Step 2 authorization table

Drive-by: corrects the notices list to mozilla-accounts-notices. integration-requirements and using-apis both named firefox-accounts-notices and linked to a matching URL; integrating-with-fxa also had an undefined link reference.

Testing

yarn build passes with no errors. The only anchor warning on the new page is /api#tag/..., the pre-existing class that affects every page linking into the redocusaurus route (tokens, using-apis, apple-iap, google-iap, integration-requirements).

Every normative claim was verified against mozilla/fxa@main rather than the ticket text, which had drifted — MAX_AGE_LEEWAY_SECONDS = 5, lastAuthAt() = max(authAt, verifiedAt), the claim distribution across ID token / JWT access token / introspection, the empty jwtAccessTokens.enabledClientIds default, the passkey-to-TOTP divert, and the discovery document omitting acr_values_supported. packages/functional-tests/tests/oauth/stepUpAuth.spec.ts was used as the executable spec.

Issue(s)

Closes FXA-12864.

Notes for reviewers

• The OpenAPI half of FXA-12864 is a separate PR against mozilla/fxa; api-swagger.json here is a build artifact pulled daily from production by pull-api-definitions.yml, so it is deliberately untouched.
• The prompt=none section documents behaviour from fix(oauth): fail prompt=none step-up instead of challenging fxa#21103, which is still in review. It carries a note saying so. This PR should land after that one, or that note needs to stay until it does.
• Three known gaps are documented rather than papered over, since AMO will hit them: no RP-visible error when a user abandons an interactive challenge (FXA-12860), the discovery document advertising nothing (unticketed), and passkey users being routed into TOTP enrolment they do not need (FXA-14312).

🤖 Generated with Claude Code