chore(other): align cafe api description with dcr rfc7591 and oauth2 rfc6749

[DmitryAnansky]

Aligned Cafe API description with dcr rfc7591 and oauth2 rfc6749.

Preview LINK

[redocly]

cafe AI Review: 🟢 Completed

Redocly Agent has reviewed your changes and found 29 potential issue(s).

Note

Medium Risk

Introduces breaking changes to the OAuth2 and Dynamic Client Registration (DCR) endpoint responses. While DCR requests now accept both legacy camelCase and standard snake_case fields, responses strictly enforce standard snake_case names (e.g., client_id instead of clientId). Furthermore, OAuth2 endpoints have transitioned to returning standard RFC 6749/7591 errors rather than RFC 9457 problem+json. Clients heavily relying on the previous non-standard structures will need to be updated.

Overview of changes

Updates the Cafe API OpenAPI specification to fully comply with standard OAuth2 (RFC 6749) and DCR (RFC 7591/7592) protocols.

• Enforces snake_case response fields in DCR (e.g., client_id, client_secret) while supporting camelCase requests.
• Documents new endpoints for token exchange (/oauth2/token), revocation (/oauth2/revoke), client management (/oauth2/register/{clientId}), and server metadata (/.well-known/oauth-authorization-server).
• Standardizes OAuth2 endpoint error structures, replacing the legacy problem+json format.
• Modifies the internal use-configure-replay client hook to leverage the standardized request and response fields.
• Expands operation ID validation rules to permit Revoke prefixes.

[redocly]

OAuth2Client.yaml requires client_secret and registration_access_token. Returning these in GET/PUT responses for /oauth2/register/{clientId} violates RFC 7592 Section 2.1 and exposes sensitive credentials unnecessarily. Use a separate schema for management responses.

[DmitryAnansky]

Not valid

What RFC 7592 actually specifies:

Section 2.1 (Read) and Section 2.2 (Update) both say, verbatim: "Some values in the response, including the client_secret and registration_access_token, MAY be different from those in the initial registration response." The RFC doesn't merely permit these fields in GET/PUT responses — it builds a feature on top of them: the server may rotate the secret or registration token during a read/update, and the response is how the client learns the new values. Omitting them would break that mechanism.
Section 3 (Client Information Response) — the response format both operations reference — says the server "MUST return all registered metadata about this client", extends RFC 7591's client information response ("the response contains the client identifier as well as the client secret, if the client is a confidential client"), and its example response literally contains both client_secret and registration_access_token.

So our GET/PUT responses (and OAuth2Client.yaml requiring those fields) are not a violation of §2.1 — they're an implementation of it. The contract tests validate exactly this shape.

Where the reviewer likely went wrong: §2.2 does contain a MUST NOT, but it applies to the request: the update request must not include registration_access_token, registration_client_uri, client_id_issued_at, or client_secret_expires_at (and any included client_secret must match). We enforce that direction correctly. It's an easy sentence to misattribute to the response.

[redocly]

The token_endpoint_auth_method enum lacks none, forcing a client_secret even for public clients (e.g., SPAs, mobile apps). This often leads to developers hardcoding secrets in insecure environments.