Skip to content

error-model.adoc

Latest commit

 

History

History
92 lines (71 loc) · 3.93 KB

error-model.adoc

File metadata and controls

92 lines (71 loc) · 3.93 KB
Raw

Commons Specification — Error Model

Table of Contents

1. Overview

Realizes COMMONS-9–COMMONS-12. See T-LEAK.

The error model splits cleanly by layer: libraries throw typed exceptions; HTTP edges render RFC 9457 problem documents. Commons owns the typed hierarchy (commons.error) and the inbound normalization of IdP error responses; each edge owns its RFC 9457 mapping.

2. The layer split

Layer Behaviour

Libraries — commons + validation packages, the client engine (pure Java)

Throw a typed exception hierarchy defined in commons.error. They MUST NOT produce HTTP problem documents — that is not their layer (COMMONS-9).

HTTP edges — token-sheriff-validation-quarkus, token-sheriff-client-quarkus, and any future non-Quarkus / RESTEasy edge (e.g. a portal adapter)

MUST map those exceptions to application/problem+json per RFC 9457, without leaking internal detail (COMMONS-10, COMMONS-12). Existing validation rejection responses retrofit to this.

3. Typed exception hierarchy (commons.error)

A small, stable hierarchy that library code throws and edges map:

  • TokenSheriffException is the common base, carrying a category (from commons.events, structure / signature / semantic) and a safe, caller-facing message — never internal detail.

  • Transport failures (TLS rejected, SSRF blocked, timeout, oversized response, unreachable endpoint) are the TransportException branch; inbound IdP protocol errors normalize to ClientProtocolException (via InboundErrorNormalizer).

  • Token-validation failures (TokenValidationException, keyed by SecurityEventCounter.EventType) are another branch on the shared base so the edges have one mapping surface.

4. RFC 9457 mapping at the edge

Each edge maps the typed exception to a problem document:

Category HTTP status type / title

Transport (SSRF blocked, TLS rejected, unreachable, timeout)

502 / 503 as appropriate

Stable type URI + generic title

Structure / signature / semantic (token rejection)

401

Stable type URI + generic title

Bad request (malformed input)

400

Stable type URI + generic title

A problem document carries type, title, status, and a safe detail. It MUST NOT carry stack traces, internal identifiers, upstream URLs, or credential material (COMMONS-12, mitigating T-LEAK).

Because every rendered member is a fixed, per-category constant (no request or exception data is interpolated), the validation-quarkus edge builds the document from constant strings — guaranteeing the exact application/problem+json bytes with no escaping surface. If a future edge needs a dynamic detail (interpolating request-derived text), it MUST switch to a serialized DTO with proper JSON escaping rather than string concatenation.

Example problem document
{
  "type": "https://cuioss.github.io/TokenSheriff/problems/token-invalid",
  "title": "Token validation failed",
  "status": 401,
  "detail": "The presented token could not be validated."
}

5. Inbound IdP error normalization (COMMONS-11)

Commons normalizes inbound OAuth error responses (error / error_description, RFC 6749 §5.2) into the same typed model the edges render — one contract, both directions. The raw upstream error is never passed through to the caller verbatim.

6. See also