docs(spec): make grant_type binding at POST /token

[antstanley]

Note

Stacked PR 6 of 16 — part of stack #35, which targets main.
Base: #19 (spec/validate-revoke-token-claims) · Followed by: #20

This PR's diff shows only its own change. Merge the stack bottom-up; do not merge this before its base.

Why it sits at position 6: Replaces ExchangeRequest's optional fields with an ExchangeCredential enum, which invalidates #20's field-presence rationale and relocates provider_access_token. Also carries the RFC 6749 §5.1 no-store headers.

Scope of this PR

This PR currently carries the change spec. It will also carry the implementation plan and the build work for that spec — plan and code land as later commits on this same branch, so the spec, its plan, and its implementation review and merge as one unit.

Review order within the PR: spec first, then plan, then implementation.

---

Change spec proposing that grant_type select the flow at POST /token.

Problem. crates/core/src/service/exchange.rs selects the flow by which optional fields are present, not by the declared grant_type. Supplying an id_token field while declaring grant_type=authorization_code runs the direct ID-token path and skips code redemption entirely, along with the redirect_uri requirement the authorization-code flow depends on.

Proposed delta. The declared grant_type becomes the sole selector, with a closed per-grant parameter set — authorization_code requires provider/code/redirect_uri, id_token requires provider/id_token, refresh_token requires refresh_token — and any parameter belonging to a different grant is rejected 400 invalid_request rather than ignored.

Enforcement is structural rather than a boundary check: ExchangeRequest loses its Option<String> fields and its #[derive(Default)] in favour of an ExchangeCredential enum whose variants own their own fields, so an invalid combination cannot be constructed.

Notes.

• A gap the finding did not name: because TokenForm.grant_type is a bare String, a body omitting it currently fails axum's form deserialization and returns 422 plain text, escaping the RFC 6749 error envelope entirely. The spec pins it to 400 invalid_request and gives two implementation routes.
• No compatibility mode. A dedicated Compatibility and migration section names the three request shapes that break, the callers verified not to break, and a release-note-plus-staging migration path.
• Deferred to Open questions rather than scope-crept: gating/advertising the id_token grant (discovery advertises two grant types while three are accepted), and whether a mismatch should emit a ValidationFailed audit event.

Drafted with the spec-creator plugin from a deep security scan of the repository at 53cbdec9. Spec only — no source changes.