Skip to content

requirements.adoc

Latest commit

 

History

History
213 lines (149 loc) · 9.95 KB

requirements.adoc

File metadata and controls

213 lines (149 loc) · 9.95 KB
Raw

Commons Requirements

Table of Contents

1. Overview

Functional and non-functional requirements for the commons base layer — the de.cuioss.sheriff.token.commons. packages inside token-sheriff-validation. Commons gathers the four cross-cutting concerns every capability sits on: *IdP transport, the error model, security events and metrics. It moves bytes, raises typed errors, counts events and exposes metrics; it never interprets a token’s trust — that is the validation layer’s job.

Requirement IDs use the COMMONS-N scheme, grouped by concern. IDs are stable identifiers referenced across documentation and the threat model; they are not sequential across groups.

1.1. Document Navigation

The capability README is the entry point — it carries the full document map and the recommended reading order for this set.

1.2. Referenced Standards

New standards are catalogued in References. Standards reused from the validation bibliography (RFC 7517, RFC 6749, RFC 9700) are cited inline below and not restated here.

2. Transport requirements

All outbound IdP HTTP. See Transport specification and Threat Model.

2.1. COMMONS-1: Outbound IdP HTTP transport

Commons owns the validation-side outbound HTTP to an OpenID Provider — discovery and JWKS — and provides the hardened transport primitives (built on cui-http) it is performed with. The client capability builds its own back-channel HTTP (token, userinfo, revocation, PAR) on those primitives and applies its own in-module egress control (owned back-channel HTTP); it does not route those fetches through a commons transport service.

2.2. COMMONS-2: TLS enforcement

All outbound IdP requests MUST use TLS 1.2 or higher with certificate validation. Plain HTTP endpoints MUST be rejected. TLS configuration is centralized (via cui-http’s `SecureSSLContextProvider), not per-caller.

Carve-out — hostname matching. Certificate validation decomposes into chain trust, expiry, algorithm constraints, and hostname matching. The first three are unconditional and admit no opt-out. Hostname matching alone is a per-configuration, default-ON knob that a deployment MAY relax by explicit opt-in; when it is relaxed, the remaining checks stay fully enforced, so an untrusted or expired certificate is still rejected. The knob exists for development and test topologies serving SAN-mismatched certificates and MUST NOT be used in production — a deployment that opts out accepts a narrowed mitigation. It is reachable from two configuration surfaces: sheriff.token.issuers.<name>.jwks.http.verify-hostname (per-issuer, validation) and sheriff.client.verify-hostname (client-wide, client engine). See ADR-0008.

2.3. COMMONS-3: SSRF defence for advertised URLs

Any URL taken from an IdP-controlled source (jwks_uri, discovery endpoints, userinfo, or any endpoint advertised via discovery) MUST be constrained before it is fetched: scheme restricted to HTTPS, host subject to an allow-list / egress policy (EgressPolicy), and internal / link-local / loopback address ranges blocked. The wellknown and jwks fetch paths were audited to this requirement during their relocation into commons.

2.4. COMMONS-4: Response resilience and DoS bounds

Every outbound fetch MUST apply a connect/read timeout, a response-size limit, and bounded retry/backoff. Large or slow metadata, JWKS or userinfo responses MUST NOT be able to exhaust memory or block a caller indefinitely.

2.5. COMMONS-5: Discovery (.well-known)

Commons fetches and parses OpenID Provider metadata from .well-known/openid-configuration (OIDC Discovery) and OAuth authorization-server metadata (RFC 8414). The advertised issuer MUST be validated against the configured issuer; advertised endpoint URLs are subject to COMMONS-3: SSRF defence for advertised URLs.

2.6. COMMONS-6: JWKS retrieval

Commons retrieves JWKS documents (RFC 7517) over the hardened transport, subject to COMMONS-2: TLS enforcement, COMMONS-3: SSRF defence for advertised URLs and COMMONS-4: Response resilience and DoS bounds, and caches them (COMMONS-8: Caching of discovery and JWKS). Key material parsing is a transport-format concern; trust decisions about the resulting keys remain in validation.

  • Source: RFC 7517 (reused from validation bibliography).

2.7. COMMONS-7: Extended IdP endpoints (client-facing)

Commons defines the transport contract for the endpoints the OIDC client capability drives: token (RFC 6749), userinfo (OIDC Core), revocation (RFC 7009), introspection (RFC 7662), end-session / RP-initiated logout, and PAR (RFC 9126). Each is exercised by a dedicated MockWebServer dispatcher in the generators test artifact (default + adversarial modes), so the contract is testable independently of the client engine.

2.8. COMMONS-8: Caching of discovery and JWKS

Discovery documents and JWKS are cached with a bounded lifetime to avoid re-fetching on every validation. Cache refresh MUST re-apply COMMONS-2: TLS enforcement–COMMONS-4: Response resilience and DoS bounds.

3. Error-model requirements

3.1. COMMONS-9: Typed exception hierarchy

Library code (the commons and validation packages, and the client engine — pure Java) MUST signal failure through a typed exception hierarchy defined in commons.error. Library code MUST NOT produce HTTP problem documents — that is not its layer.

  • Source: RFC 9457 §3 (problem details are an HTTP-edge concern).

3.2. COMMONS-10: RFC 9457 rendering at every HTTP edge

Every HTTP edge — token-sheriff-validation-quarkus, token-sheriff-client-quarkus, and any future non-Quarkus/RESTEasy edge (e.g. a portal adapter) — MUST map the typed exceptions to application/problem+json per RFC 9457. Existing validation rejection responses are retrofitted to this contract.

3.3. COMMONS-11: Inbound IdP error normalization

Commons MUST normalize inbound IdP error responses (OAuth error / error_description per RFC 6749 §5.2) into the typed model the edges render — one contract, both directions.

3.4. COMMONS-12: No internal-detail leakage

Rendered problem documents MUST carry only a safe type / title / detail, and MUST NOT leak stack traces, internal identifiers, upstream URLs, or credential material.

4. Security-event requirements

4.1. COMMONS-13: Shared security-event surface

SecurityEventCounter and the security-event types live in commons.events so validation and the client share one event surface. The counter MUST remain thread-safe and free of any Micrometer dependency; Quarkus extensions expose it as before.

4.2. COMMONS-14: Event categorization

Each security event MUST carry a category (structure / signature / semantic) usable by an edge to select a response. Event categories MUST NOT depend on any validation-layer type (the ArchUnit boundary — see Architecture).

5. Metrics requirements

5.1. COMMONS-15: Metric identifiers defined once

Metric identifiers / contracts (sheriff.token.*) are defined once in commons.metrics. Each Quarkus extension wires them to Micrometer; the identifiers themselves carry no Micrometer dependency.

  • Source: RFC 9700 §4 (observability), project metric-naming convention (sheriff.token.*).

6. Traceability

Each requirement is covered by the threat model and realized in the transport, error-model and observability specifications.

Requirement Threats Specification

COMMONS-1..8

T-SSRF, T-TLS, T-DOS, T-DISCOVERY

transport.adoc

COMMONS-9..12

T-LEAK

error-model.adoc

COMMONS-13..14

T-LEAK (categorization)

observability.adoc

COMMONS-15

—

observability.adoc