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 40 potential issue(s).

Note

Medium Risk

Introduces breaking contract changes to Dynamic Client Registration (DCR) request and response payloads by replacing camelCase fields with RFC 7591 snake_case names, updates OAuth error responses to follow RFC 6749 instead of RFC 9457 problem details, and defines several new OAuth2 endpoints.

Overview

• RFC Alignment: Updates OAuth2 Dynamic Client Registration (/oauth2/register) request/response schemas to standard snake_case field names per RFC 7591 and RFC 6749.
• New Endpoints: Adds OpenAPI specs for token issuance (/oauth2/token), token revocation (/oauth2/revoke), client management (/oauth2/register/{clientId}), and discovery metadata (/.well-known/oauth-authorization-server).
• Error Formatting: Implements standard RFC 6749/7591 error responses (error, error_description) across all OAuth2 operations.
• Client Integration: Updates use-configure-replay.ts to register and parse client credentials using standard RFC 7591 properties.

[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.

[vadyvas]

do we need root "openapi" ?

[tatomyr]

Left a minor comment.