safire 0.2.0 → 0.4.0

data/docs/adr/ADR-007-https-only-redirects-and-localhost-exception.md

@@ -1,11 +1,11 @@
 ---
 layout: default
-title: "ADR-007: HTTPS-only redirect enforcement and localhost exception"
+title: "ADR-007: HTTPS-only enforcement and explicit localhost opt-in"
 parent: Architecture Decision Records
 nav_order: 7
 ---
 
-# ADR-007: HTTPS-only redirect enforcement and localhost exception
+# ADR-007: HTTPS-only enforcement and explicit localhost opt-in
 
 **Status:** Accepted
 
@@ -17,17 +17,22 @@ SMART App Launch 2.2.0 requires TLS for all exchanges involving sensitive data.
 
 This is a known attack surface: a compromised or misconfigured server can use open redirects to redirect a client to an attacker-controlled HTTP endpoint.
 
-There is also a practical concern: developers running local FHIR servers (e.g. HAPI FHIR, Inferno test environments) use `http://localhost` or `http://127.0.0.1`. Blocking these in a development environment would make Safire unusable without a TLS termination proxy.
+There is also a practical concern: developers running local FHIR servers (e.g.
+HAPI FHIR, Inferno test environments) use `http://localhost` or
+`http://127.0.0.1`. Blocking these entirely would make Safire awkward to use
+without a TLS termination proxy, but accepting them implicitly weakens a
+security boundary and can hide production misconfiguration.
 
 ---
 
 ## Decision
 
-HTTPS is enforced at **two layers**, both with the same localhost exception:
+For client configuration and HTTP redirects, HTTPS is enforced at **two layers**.
+Both layers use the same explicit local-development opt-in:
 
-**Layer 1 — `ClientConfig` URI validation:** all URI attributes (`base_url`, `redirect_uri`, `issuer`, `authorization_endpoint`, `token_endpoint`, `jwks_uri`) must use `https://`, except when the host is `localhost` or `127.0.0.1`.
+**Layer 1 — `ClientConfig` URI validation:** all URI attributes (`base_url`, `redirect_uri`, `issuer`, `authorization_endpoint`, `token_endpoint`, `jwks_uri`) must use `https://`, except when `allow_insecure_localhost: true` is configured and the host is `localhost` or `127.0.0.1`.
 
-**Layer 2 — `HttpsOnlyRedirects` Faraday middleware:** intercepts every 3xx response before `faraday-follow_redirects` follows it. If the redirect target is not HTTPS (and not localhost), a `Safire::Errors::NetworkError` is raised immediately rather than following the redirect.
+**Layer 2 — `HttpsOnlyRedirects` Faraday middleware:** intercepts every 3xx response before `faraday-follow_redirects` follows it. If the redirect target is not HTTPS, and the local-development exception is not enabled for a loopback host, a `Safire::Errors::NetworkError` is raised immediately rather than following the redirect.
 
 ```ruby
 # middleware/https_only_redirects.rb
@@ -36,14 +41,32 @@ def on_complete(env)
 
   location = env.response_headers['location']
   uri = URI.parse(location)
-  return if uri.scheme == 'https' || localhost?(uri.host)
+  return if uri.scheme == 'https'
+  return if allow_insecure_localhost && localhost_host?(uri.host)
 
   raise Safire::Errors::NetworkError,
         "Blocked redirect to non-HTTPS URL: #{location}"
 end
 ```
 
-Both layers use the same localhost exception (`localhost` and `127.0.0.1`) and must stay consistent. The middleware raises `NetworkError` (transport layer) rather than `ConfigurationError` (construction time) because redirect enforcement is a runtime concern.
+Both layers use the shared loopback host set in `URIValidation` (`localhost`
+and `127.0.0.1`). The middleware raises `NetworkError` (transport layer) rather
+than `ConfigurationError` (construction time) because redirect enforcement is a
+runtime concern.
+
+UDAP registration metadata applies the same secure default to its registration
+URI fields. The UDAP Security STU2 registration profile requires
+`redirect_uris` and `logo_uri` to use HTTPS.
+`URIValidation#strict_https_uri?` provides that default predicate, while
+`URIValidation#localhost_http_uri?` identifies the only local HTTP shape that
+can be accepted when a caller explicitly opts into development mode.
+
+`UdapRegistrationMetadata` uses the same explicit option name for non-TLS local
+redirect and logo URIs. It accepts only HTTP on `localhost` or `127.0.0.1`,
+logs a development-only warning when used, and never permits remote HTTP.
+Safire does not infer Rails, Rack, or another framework's environment; the host
+application must opt in deliberately. Metadata produced through this exception
+is non-conformant and must not be used in production.
 
 ---
 
@@ -51,9 +74,16 @@ Both layers use the same localhost exception (`localhost` and `127.0.0.1`) and m
 
 **Benefits:**
 - Defence-in-depth: HTTPS is enforced at both config time and at every HTTP redirect, closing the redirect-based attack vector
-- Consistent localhost exception across both enforcement points — `http://localhost` works in both URI validation and redirect following
+- Consistent explicit localhost opt-in across config validation, redirect following,
+  and UDAP registration metadata
+- UDAP registration fields remain strict by default while non-TLS local testing
+  requires an explicit, narrowly scoped opt-in
 - Clear error message when a non-HTTPS redirect is blocked, pointing directly at the offending URL
 
 **Trade-offs:**
-- The localhost exception must be maintained in two places — `ClientConfig#localhost_host?` and `HttpsOnlyRedirects` — any change to the exception policy must be applied to both; this duplication is intentional (the two layers are independent defences) but must be kept in sync
+- The config and redirect layers are independent defences, but they share the
+  loopback host policy through `URIValidation`; changes to that helper affect
+  both layers and must be reviewed as a security policy change
+- Callers enabling the local-development exception are responsible for tying it
+  to their application's environment and preventing production use
 - Blocking non-HTTPS redirects can cause unexpected failures if a FHIR server uses HTTP-to-HTTPS redirect chains (e.g. `http://fhir.example.com` → `https://fhir.example.com`); callers should configure `base_url` with the final HTTPS URL directly

data/docs/adr/ADR-009-oauth-error-hierarchy.md

@@ -0,0 +1,131 @@
+---
+layout: default
+title: "ADR-009: OAuthError base class and ReceivesFields mixin for protocol error hierarchy"
+parent: Architecture Decision Records
+nav_order: 9
+---
+
+# ADR-009: OAuthError base class and ReceivesFields mixin for protocol error hierarchy
+
+**Status:** Accepted
+
+---
+
+## Context
+
+Three protocol operations can return OAuth2-style error responses: token exchange (`TokenError`), authorization failure (`AuthError`), and dynamic client registration (`RegistrationError`). All three carry the same RFC-defined fields — HTTP `status`, an OAuth2 `error` code, and an `error_description` string — and all three produce structured error messages from those fields.
+
+`TokenError` and `RegistrationError` have a second failure path: the server returns a 2xx response but omits the field the caller requires (`access_token` or `client_id`). In that case the error must report which fields were present in the response, without logging their values, to assist debugging without leaking data.
+
+Without a shared foundation, each error class would duplicate the constructor, the attribute readers, and the message-building logic.
+
+**Option A — Duplicate per class:** each error class independently defines `attr_reader :status, :error_code, :error_description`, its own constructor, and its own `build_message` method.
+
+**Option B — Extract a shared base:** introduce `OAuthError < Error` with a template-method design; each subclass overrides `operation_label` to supply the lead phrase of the error message. Extract a `ReceivesFields` mixin for the structural failure path (`received_fields` attribute + constructor forwarding), included only by the two classes that need it.
+
+---
+
+## Decision
+
+Option B — `OAuthError` as a shared base class with `ReceivesFields` as a private mixin.
+
+```ruby
+class OAuthError < Error
+  attr_reader :status, :error_code, :error_description
+
+  def initialize(status: nil, error_code: nil, error_description: nil)
+    @status = status; @error_code = error_code; @error_description = error_description
+    super(build_message)
+  end
+
+  private
+
+  def operation_label
+    raise NotImplementedError, "#{self.class} must define #operation_label"
+  end
+
+  def build_message
+    parts = [operation_label]
+    parts << "HTTP #{@status}" if @status
+    parts << @error_code       if @error_code
+    parts << @error_description if @error_description
+    parts.join(' — ')
+  end
+end
+
+module ReceivesFields
+  def self.included(base) = base.attr_reader :received_fields
+  def initialize(received_fields: nil, **) = (@received_fields = received_fields; super(**))
+end
+
+class TokenError        < OAuthError; include ReceivesFields; ... end
+class AuthError         < OAuthError; ...                          end
+class RegistrationError < OAuthError; include ReceivesFields; ... end
+```
+
+Each subclass defines only `operation_label` and, when needed, overrides `build_message` for the structural path.
+
+---
+
+## Consequences
+
+**Benefits:**
+- DRY: each concrete error class is a handful of lines; the shared attributes and message format are defined once
+- Consistent error messages across all three operations; callers and log parsers see the same structure
+- `ReceivesFields` is `@api private` — callers interact only with `TokenError` and `RegistrationError`; the mixin is an implementation detail
+- Adding a new OAuth-style error (e.g. for a future introspection endpoint) requires only a new subclass with `operation_label`
+
+**Trade-offs:**
+- The `operation_label` template method raises `NotImplementedError` at runtime if a subclass forgets to define it; a compile-time check is not possible in Ruby
+- `ReceivesFields` modifies the constructor via `super(**)` forwarding, which requires care when the inheritance chain has multiple `initialize` overrides
+
+---
+
+## Amendment: Shared protocol response handling
+
+UDAP Dynamic Client Registration uses the same RFC 7591 success and OAuth-style
+error response shapes as SMART registration. Keeping response translation as
+private methods on `Protocols::Smart` would either couple UDAP to SMART or
+duplicate parsing at the protocol trust boundary.
+
+`Protocols::OAuthResponseHandling` now owns two private transformations shared
+by protocol implementations:
+
+- converting a Faraday error response into a typed `OAuthError` subclass
+- validating and normalizing an RFC 7591 registration success response
+
+The module accepts already-received response bodies. It does not send HTTP
+requests, select endpoints, log response values, or apply protocol-specific
+policy.
+
+Registration success responses are normalized to string-keyed hashes and must
+contain a non-blank string `client_id`, as required by RFC 7591. Missing
+`client_id` responses continue to report only the received field names. A
+present but blank or non-string `client_id` raises `RegistrationError` with a
+structural error description. This intentionally hardens SMART registration:
+valid RFC 7591 responses are unchanged, while malformed identifiers that were
+previously accepted through `present?` now fail closed.
+
+Malformed or non-object OAuth error bodies produce an error containing the HTTP
+status only. Parsed JSON objects preserve their protocol error codes, including
+UDAP-specific values such as `invalid_software_statement`.
+
+### Amendment consequences
+
+**Benefits:**
+
+- SMART and UDAP share one auditable response boundary without sharing request
+  construction or endpoint policy
+- response key normalization makes direct and middleware-parsed hashes behave
+  consistently
+- malformed successful registrations fail before an invalid identifier reaches
+  application state
+
+**Trade-offs:**
+
+- the private module contains generic OAuth error translation and
+  registration-specific success validation; splitting two small transformations
+  into separate objects would add indirection without creating an independent
+  responsibility
+- SMART servers returning a non-string `client_id` are now rejected even if an
+  earlier Safire version accepted the malformed value

data/docs/adr/ADR-010-optional-client-id-dcr-temp-client.md

@@ -0,0 +1,90 @@
+---
+layout: default
+title: "ADR-010: client_id optional at initialization — deferred validation for the DCR temp-client pattern"
+parent: Architecture Decision Records
+nav_order: 10
+---
+
+# ADR-010: client_id optional at initialization — deferred validation for the DCR temp-client pattern
+
+**Status:** Accepted
+
+---
+
+## Context
+
+RFC 7591 Dynamic Client Registration requires calling the authorization server's registration endpoint before a `client_id` exists. The natural usage pattern is:
+
+1. Create a temporary `Safire::Client` with only `base_url` (no `client_id` yet)
+2. Call `register_client` to POST metadata and receive `client_id` from the server
+3. Build a properly configured client with the returned `client_id` for subsequent authorization flows
+
+Previously, `ClientConfig#validate!` required `client_id` to be present at construction time. A caller following the temp-client pattern could not even construct the initial client, so DCR was impossible without out-of-band `client_id` knowledge.
+
+**Option A — Keep client_id required; provide a separate class:** introduce a `Safire::RegistrationClient` (or similar) that omits the `client_id` requirement, performs DCR, and returns a configured `Safire::Client`.
+
+**Option B — Make client_id optional at initialization; validate at call time:** remove the construction-time presence check for `client_id`; each flow method that requires it validates and raises `ConfigurationError` at the point of the call.
+
+---
+
+## Decision
+
+Option B — `client_id` is optional at `ClientConfig` and `Client` initialization.
+
+Construction succeeds with only `base_url`:
+
+```ruby
+temp_client = Safire::Client.new({ base_url: 'https://fhir.example.com' })
+registration = temp_client.register_client({ client_name: 'My App', ... })
+
+client = Safire::Client.new({
+  base_url:  'https://fhir.example.com',
+  client_id: registration['client_id'],
+  ...
+})
+```
+
+Flow methods that require `client_id` (`authorization_url`,
+`request_access_token`, `refresh_token`, and `request_backend_token`) validate
+its presence at call time and raise `ConfigurationError` if absent.
+
+### 2026-07-04 amendment: UDAP certificate-backed temp clients
+
+UDAP Dynamic Client Registration uses the same temp-client pattern, but the
+temporary client is identified by a private key and X.509 certificate chain
+rather than by SMART client type credentials:
+
+```ruby
+temp_client = Safire::Client.new(
+  {
+    base_url: 'https://fhir.example.com',
+    private_key: File.read('client-key.pem'),
+    certificate_chain: [File.read('client-cert.pem')]
+  },
+  protocol: :udap
+)
+
+registration = temp_client.register_client(
+  metadata,
+  client_uri: 'https://client.example.com',
+  trusted_anchors: [udap_ca],
+  crls: [udap_crl]
+)
+```
+
+`client_id` remains optional at construction. UDAP `register_client` discovers
+the registration endpoint, signs a software statement using the configured or
+per-call signing identity, and returns the server-assigned `client_id`.
+
+---
+
+## Consequences
+
+**Benefits:**
+- The temp-client pattern works with the existing `Safire::Client` class; no new class is needed
+- No proliferation of client variants; the public API surface stays small
+- Consistent with how `token_endpoint` and `authorization_endpoint` are handled: both are optional at construction and resolved via lazy discovery when needed
+
+**Trade-offs:**
+- A misconfigured client (missing `client_id`) fails at call time rather than construction time; callers may see the error later than expected
+- This is an intentional trade-off: `client_id` is now in the same category as other lazily-resolved attributes, so the surprise of deferred validation is mitigated by the established pattern

data/docs/adr/ADR-011-udap-stu2-discovery-conformance.md

@@ -0,0 +1,113 @@
+---
+layout: default
+title: "ADR-011: UdapMetadata entity — structural validation separate from cryptographic validation"
+parent: Architecture Decision Records
+nav_order: 11
+---
+
+# ADR-011: `UdapMetadata` entity — structural validation separate from cryptographic validation
+
+**Status:** Accepted
+
+---
+
+## Context
+
+UDAP Security STU2 discovery returns a JSON object from `/.well-known/udap`. That object must be
+parsed into a typed entity and validated before any downstream flow (Dynamic Client Registration,
+JWT client authentication, etc.) can proceed. Two distinct validation concerns arise:
+
+1. **Structural validation** — are all required fields present? Do they satisfy the fixed-value
+   and conditional constraints specified in STU2?
+2. **Cryptographic validation** — is the `signed_metadata` JWT signature valid, and does the
+   embedded X.509 chain chain to a trusted anchor?
+
+These concerns operate at different layers: structural checks need only the parsed JSON object,
+while cryptographic checks require a trusted certificate store and key material. Mixing them
+inside the same class would make the entity difficult to test (crypto requires real certs) and
+would couple two unrelated failure modes.
+
+---
+
+## Decision
+
+`UdapMetadata` handles structural parsing and validation only. It inherits from `Safire::Entity`
+(the same base used by `SmartMetadata`) and follows the same warn-and-return-false convention
+for `valid?`.
+
+**Conformance target:** HL7 UDAP Security STU2 / v2.0.0
+([discovery section](https://hl7.org/fhir/us/udap-security/STU2/discovery.html)).
+
+**Signed metadata:** STU2 uses `signed_metadata` (not the deprecated `signed_endpoints` from
+earlier drafts). `signed_metadata` is treated as a required field by `UdapMetadata#valid?` and
+as an opaque string. Cryptographic validation of the JWT is intentionally deferred to a
+dedicated cryptographic validator; see
+[ADR-012]({% link adr/ADR-012-udap-signed-metadata-validation.md %}).
+
+**Presence check uses `nil?`, not `blank?`:** Several required array fields — for example,
+`udap_authorization_extensions_supported` — may legitimately be empty arrays in a conformant
+response. Using `blank?` would flag `[]` as absent; using `nil?` preserves the distinction
+between "field not present in the JSON response" and "field present but empty".
+
+**Array type and element validation is explicit:** Discovery metadata is untrusted JSON.
+`UdapMetadata#valid?` verifies every array-valued field is an `Array` whose elements are all
+`String`s before performing profile, grant, non-empty, or subset checks. Public helper methods
+also treat malformed scalar metadata as unsupported instead of using Ruby string `include?`
+semantics.
+
+**Value-level constraints in `valid?`:**
+
+- `udap_versions_supported` must equal `["1"]` exactly (STU2 fixed value)
+- `udap_profiles_supported` must include `"udap_dcr"` and `"udap_authn"` (both required by STU2)
+- `token_endpoint_auth_methods_supported` must equal `["private_key_jwt"]` exactly (STU2 fixed value)
+- `scopes_supported`, `grant_types_supported`, and both JWT signing algorithm arrays must each have at least one element
+- `signed_metadata` must be a compact-JWS string: exactly three dot-separated segments where
+  every segment contains only base64url characters (`[A-Za-z0-9\-_]`, no padding); JWT header
+  algorithm (`alg`), required claim presence, and signature are not validated here — these are
+  deferred to the cryptographic validator
+- endpoint URL fields (`token_endpoint`, `registration_endpoint`, conditionally
+  `authorization_endpoint`) must be absolute HTTPS URLs; plain HTTP is accepted only when
+  `allow_insecure_localhost: true` is configured and the host is `localhost` or `127.0.0.1`
+  to support development without TLS — any other scheme on those hosts (e.g. `ftp://localhost`)
+  is rejected; this exception does not apply in production
+- `authorization_endpoint` is conditionally required when `grant_types_supported` includes
+  `"authorization_code"`
+- `"udap_authz"` is conditionally required in `udap_profiles_supported` when `grant_types_supported`
+  includes `"client_credentials"`
+- `"authorization_code"` is conditionally required in `grant_types_supported` when `"refresh_token"`
+  is also present
+- `udap_authorization_extensions_required` is conditionally required when
+  `udap_authorization_extensions_supported` is non-empty; its values must be a subset of
+  `udap_authorization_extensions_supported`
+- `udap_certifications_required` is conditionally required when `udap_certifications_supported`
+  is non-empty; its values must be a subset of `udap_certifications_supported`
+
+**Public helpers follow a two-tier naming convention:**
+
+- *Profile checks* (`dynamic_registration_profile?`, `jwt_client_auth_profile?`, etc.) test
+  only whether the server advertises the profile string in `udap_profiles_supported`; they do
+  not check whether all required supporting fields are present.
+- *Capability checks* (`supports_dynamic_registration?`, `supports_jwt_client_auth?`, etc.)
+  combine profile advertisement with the minimum preconditions needed to start that flow:
+  - `supports_dynamic_registration?` requires `udap_dcr` profile and a valid `registration_endpoint`
+  - `supports_jwt_client_auth?` requires `udap_authn` profile and a valid `token_endpoint`
+  - `supports_client_authorization?` requires `udap_authz` profile, `client_credentials` in
+    `grant_types_supported`, and a valid `token_endpoint`
+
+---
+
+## Consequences
+
+**Benefits:**
+
+- Structural conformance is independently testable without any certificate infrastructure
+- `valid?` follows the same warn-and-return-false contract as `SmartMetadata#valid?`, giving
+  callers a consistent API across protocols
+- `signed_metadata` cryptographic validation stays separate from the entity; see
+  [ADR-012]({% link adr/ADR-012-udap-signed-metadata-validation.md %})
+
+**Trade-offs:**
+
+- A structurally valid `UdapMetadata` object is not automatically cryptographically validated;
+  callers that require full STU2 conformance must also perform cryptographic validation of the
+  `signed_metadata` JWT after structural validation passes

data/docs/adr/ADR-012-udap-signed-metadata-validation.md

@@ -0,0 +1,104 @@
+---
+layout: default
+title: "ADR-012: signed_metadata JWT validation — design and chain verification defaults"
+parent: Architecture Decision Records
+nav_order: 12
+---
+
+# ADR-012: `signed_metadata` JWT validation — design and chain verification defaults
+
+**Status:** Accepted
+
+---
+
+## Context
+
+UDAP Security STU2 requires that servers include a `signed_metadata` JWT in their discovery
+response. Per the spec, clients MUST validate this JWT before using any of the discovered endpoint
+URLs. Signed endpoint claims (`token_endpoint`, `registration_endpoint`, and optionally
+`authorization_endpoint`) take precedence over the unsigned values in the JSON body.
+
+Validation involves:
+
+1. Decoding the JOSE header and verifying `alg == RS256` and `x5c` is present.
+2. Verifying the JWT signature against the leaf certificate in `x5c[0]`.
+3. Validating the X.509 chain using `x5c[1..]`, caller-supplied trust anchors, and explicit
+   revocation policy/material.
+4. Checking required claims: `iss`, `sub`, `exp`, `iat`, `jti`, `token_endpoint`,
+   `registration_endpoint`, and conditionally `authorization_endpoint`.
+
+---
+
+## Decisions
+
+### Separate validator class (`UdapSignedMetadataValidator`)
+
+Cryptographic validation is isolated in `UdapSignedMetadataValidator`, keeping it out of
+`UdapMetadata` (the structural entity) and `Udap` (the HTTP discovery orchestrator). This follows
+the single-responsibility principle and keeps the entity layer free of crypto dependencies.
+
+### Warn-and-return-nil per failure; raise only on unrecoverable parse errors
+
+Validation failures log a warning through `Safire.logger.warn` and return `nil`
+rather than raising. Decode, header, signature, and chain failures stop checks
+that depend on them; once a payload is trusted enough to inspect, claim checks
+run together so one call surfaces every applicable claim warning. The only
+exception is malformed certificate DER in `x5c`, which raises
+`Safire::Errors::CertificateError` because the certificate cannot be parsed.
+
+### Chain and revocation verification on by default; `verify_chain: false` for dev/test only
+
+`verify_chain: true` is the secure production default. Skipping chain and revocation verification
+is an explicit opt-in intended for development and testing against servers whose certificates are
+not rooted in a trusted CA. The parameter threads from `Udap#server_metadata` through to
+`UdapSignedMetadataValidator`.
+
+When `verify_chain: true`, validation fails closed unless the caller supplies either `crls:` or a
+custom `revocation_checker:`. CRLs are applied to the OpenSSL certificate store with CRL checking
+enabled. A custom checker must return literal `true`; any other value or exception is treated as a
+revocation validation failure.
+
+### Signed endpoint claims merged before constructing `UdapMetadata`
+
+`Udap#fetch_metadata` validates `signed_metadata` and merges the authoritative signed endpoint
+claims over the unsigned JSON values before constructing the `UdapMetadata` instance. Callers
+never receive a `UdapMetadata` object with unverified endpoint URLs. If validation fails,
+`Safire::Errors::DiscoveryError` is raised.
+
+### Cached metadata is revalidated before reuse
+
+`Protocols::Udap` caches parsed metadata per community and trust policy, but cache hits are not
+blind returns. Before returning cached metadata, Safire revalidates the original `signed_metadata`
+JWT against the current trust policy. If the JWT has expired, the certificate chain no longer
+validates, or the configured revocation policy rejects it, the cache entry is discarded and
+discovery is fetched again.
+
+### `UdapMetadata#signed_metadata_valid?` for re-validation
+
+`UdapMetadata` exposes `signed_metadata_valid?(base_url:, ...)` as a convenience for callers who
+hold a metadata object and want to explicitly re-validate (for example, with a different trust
+anchor set). Instances returned by `Udap#server_metadata` are already pre-validated.
+
+### DCR consumes authoritative signed endpoint claims
+
+UDAP Dynamic Client Registration is the first Safire flow that acts on
+discovered UDAP endpoints after discovery. `Protocols::Udap#register_client`
+and `Protocols::Udap#cancel_registration` use the `registration_endpoint` from
+the `UdapMetadata` instance returned by `server_metadata`. Because
+`server_metadata` merges signed endpoint claims over unsigned JSON before
+constructing the entity, registration lifecycle requests post to the
+authoritative signed endpoint when signed and unsigned values differ.
+
+---
+
+## Consequences
+
+- Production use requires providing `trusted_anchors:` plus an explicit revocation policy
+  (`crls:` or `revocation_checker:`) to `server_metadata`. With `verify_chain: true`, Safire
+  validates against caller-supplied material; it does not fall back to the operating system trust
+  store or perform implicit online revocation checks.
+- `CertificateError` is reserved for unrecoverable DER parse failures. All other validation
+  decisions use the warn-and-return-nil pattern.
+- `UdapMetadata#valid?` remains a structural check only; it does not invoke the JWT validator.
+- Downstream UDAP flows must consume endpoints from `UdapMetadata` returned by
+  `server_metadata`; they must not read unsigned discovery JSON directly.

data/docs/adr/ADR-013-udap-registration-request-model.md

@@ -0,0 +1,106 @@
+---
+layout: default
+title: "ADR-013: UDAP registration metadata as an immutable value object"
+parent: Architecture Decision Records
+nav_order: 13
+---
+
+# ADR-013: UDAP registration metadata as an immutable value object
+
+**Status:** Accepted
+
+---
+
+## Context
+
+UDAP Dynamic Client Registration signs caller-controlled client metadata into a
+software statement. Once signed, that statement is authoritative: the
+registration server uses it instead of an unsigned request-body field when the
+same metadata appears in both places.
+
+This creates a trust boundary before cryptographic construction. Safire must
+reject malformed or ambiguous registration metadata before signing, while still
+preserving valid extension fields allowed by RFC 7591. Discovery entities are
+not an appropriate model for this boundary: they represent remote input and use
+warn-and-return-false compliance checks, whereas registration metadata is local
+input that must either produce one canonical payload or raise.
+
+The conformance target is
+[HL7 UDAP Security STU2 / v2.0.0](https://hl7.org/fhir/us/udap-security/STU2/registration.html),
+which builds on the
+[UDAP Dynamic Client Registration profile](https://www.udap.org/udap-dynamic-client-registration-stu1.html).
+
+---
+
+## Decision
+
+### Use a dedicated strict value object
+
+`UdapRegistrationMetadata` validates and normalizes the caller's metadata at
+construction. Invalid input raises `Safire::Errors::ValidationError` with the
+failing attribute and a value-free reason. The class does not inherit from
+`Entity` and does not use the discovery layer's warn-and-return-false contract.
+
+Top-level string and symbol keys are normalized to strings. Supplying both forms
+of one key is rejected rather than allowing insertion order to decide which
+value is signed. The value object and its canonical internal hash are frozen,
+and `to_h` returns a defensive copy.
+
+### Enforce exact STU2 grant shapes
+
+Registration accepts exactly one primary grant:
+
+- `authorization_code`, optionally with `refresh_token`
+- `client_credentials`
+
+Unknown and duplicate grant values are rejected. `redirect_uris`, `logo_uri`,
+and generated `response_types: ["code"]` apply only to authorization-code
+registration. Redirect and logo URIs require absolute HTTPS by default.
+
+For local development without TLS, callers may explicitly pass
+`allow_insecure_localhost: true`. This permits HTTP only on `localhost` and
+`127.0.0.1`; remote HTTP remains invalid. Safire warns only when the exception
+is actually used. The library does not infer a framework environment because
+an implicit environment default could silently weaken production validation.
+Metadata created through the exception is intentionally documented as
+non-conformant.
+
+Cancellation is a separate `operation: :cancel` mode. Callers omit
+`grant_types`; Safire injects an empty array and removes authorization-only
+metadata from the canonical result.
+
+### Reserve protocol-owned fields
+
+Safire generates `token_endpoint_auth_method: "private_key_jwt"` and, when
+applicable, `response_types`. Callers cannot supply those fields, registered JWT
+claims, or request-envelope fields such as `software_statement`,
+`certifications`, and `udap`.
+
+Unknown RFC 7591 extension fields are retained only when their values are exact
+JSON data: strings, finite JSON numbers, booleans, null, arrays, or objects with
+string keys and recursively valid values. Ruby-specific values and recursive
+collections are rejected.
+
+### Use the standard-library mail boundary
+
+`contacts` must be a non-empty array of absolute URI strings with at least one
+valid `mailto:` address. Safire parses mail contacts as `URI::MailTo`, obtains
+addresses from `URI::MailTo#to`, and applies
+`URI::MailTo::EMAIL_REGEXP`. It does not maintain a project-specific email
+regular expression.
+
+---
+
+## Consequences
+
+- Signing code can consume one canonical, already validated metadata hash.
+- Caller mutations cannot change metadata between validation and signing.
+- Protocol-owned claims cannot be shadowed through caller input.
+- Plain HTTP remains impossible for remote hosts; local HTTP requires a literal
+  boolean opt-in and produces a warning.
+- Extension metadata remains forward-compatible without permitting arbitrary
+  Ruby objects into a JWT payload.
+- Metadata validation remains independent of software-statement signing and the
+  network registration lifecycle. `Protocols::Udap#register_client` and
+  `Protocols::Udap#cancel_registration` consume this value object when
+  performing end-to-end UDAP registration operations.