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

Note

Low Risk

The blast radius is limited to API documentation and a theme script. Since there are no modifications to underlying backend services or core application logic, the operational risk is minimal.

Overview

Aligns the Cafe API OpenAPI documentation with standard OAuth2 (RFC 6749) and Dynamic Client Registration (RFC 7591) protocols:

• Migrates client registration schemas to use standard snake_case properties (e.g., client_id, grant_types).
• Updates OAuth2 error response definitions to use standard formats instead of RFC 9457 problem+json.
• Adds OpenAPI paths for token, revocation, well-known authorization metadata, and client configuration endpoints.
• Modifies @theme/ext/use-configure-replay.ts to consume the standard RFC 7591 registration fields.

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