safire 0.4.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc7c5bf60b5d43365009f5073aae66d535f8e5345825f8ca08b638fb26587417
-  data.tar.gz: f47a4a2c4a84eefa8427e05a59d9e5e2cfca4adbce2a989f43cd53ead47e42bf
+  metadata.gz: d9019d0d248f2e4e723a7be2051feea39d3be739d6b7118b31c1d67be16aad1a
+  data.tar.gz: ed3c092bc91718d766e779b361e10275014b0d750d3f59f22fa60504b9cee5a9
 SHA512:
-  metadata.gz: 625c96ea6424f41590d5396fb9d455ec0d89477474f484cbda236ec55ef13aed76d756ce88e014f76c1556ee8fa8e6e9d92a5a37743af2279e30c59456d74a58
-  data.tar.gz: 8c572a8974dfabdad87fd9d672013ca9bf64276a604db1492d11d6ad19e0351b30ecc2485b9262a366e3fce21af8eff656e2d0060077295c1b1127d6315c5ae2
+  metadata.gz: cd779a03d653c1108aee4085d90a14f806b1cf0e337892a3a9ca08bbe41dd2f266211e5173b265b5ca597b82b60cf4a0d4509705181369deb9b7affb79eb8888
+  data.tar.gz: 69939d1190e064f56a38481d069f27d313fdfacb2efd096316add8c2db4e5baa6c7b572420f949fe952edfa844f2bb35d63ecbdf18833208fb5f95896c2d7b72

data/CHANGELOG.md

@@ -7,6 +7,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-08-29
+
+### Changed
+
+- SMART and UDAP discovery now accept usable raw JSON-object response bodies
+  when incorrect or missing response content types leave them undecoded by the
+  HTTP adapter. Shared discovery, registration, and OAuth error handling treats
+  malformed or non-object JSON plus ambiguous, recursive, or non-JSON-compatible
+  adapter-provided Hashes as unusable instead of risking silent normalization
+  or unexpected type errors.
+- SMART metadata diagnostics now validate array-valued field shapes. Capability
+  and signing-algorithm helpers treat malformed list advertisements as
+  unsupported instead of applying scalar substring semantics or raising an
+  unexpected type error. Authorization and token operations now also apply the
+  configured HTTPS/localhost policy to endpoints obtained through SMART
+  discovery before using them. OAuth authorization, token, registration, and
+  redirect endpoint URIs are rejected when they contain fragment components.
+- UDAP Dynamic Client Registration now validates and snapshots caller input
+  before discovery, then gates only on trusted DCR profile, endpoint, algorithm,
+  certification, and scope values needed by the request. Missing RS256
+  advertisement and unconfirmed scope support produce value-free warnings when
+  an otherwise usable request can proceed; unrelated metadata conformance
+  defects remain available through `UdapMetadata#valid?`. In v0.4.1,
+  unadvertised wildcards still proceed after warning; registration and
+  modification require exact advertisement in v0.5.0, while wildcard scope
+  compatibility remains warning-only during cancellation.
+- UDAP authorization-code registration now rejects only locally provable
+  `logo_uri` defects. Usable HTTPS URLs whose PNG, JPG/JPEG, or GIF format
+  cannot be inferred from the path are accepted with a value-free warning;
+  Safire does not dereference caller-supplied logo URLs during validation.
+- UDAP registration returns metadata only for completed `200`/`201` outcomes;
+  `202 Accepted` is reported as pending rather than treated as completed.
+  Cancellation error messages now more clearly distinguish an unconfirmed
+  outcome from server rejection. Safire never retries registration lifecycle
+  requests automatically when the authorization server may already have
+  committed them.
+
+### Deprecated
+
+- SMART Backend Services requests without usable configured or per-call scopes
+  still use `system/*.rs` for v0.4.x compatibility, but now emit a deprecation warning.
+  Configure or pass scopes explicitly before v0.6.0, when missing scopes will
+  raise `ConfigurationError`.
+
 ## [0.4.0] - 2026-08-07
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    safire (0.4.0)
+    safire (0.4.1)
       activesupport (>= 7.1, < 9)
       addressable (~> 2.8)
       faraday (~> 2.14)
@@ -127,8 +127,8 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.6)
-    rubocop (1.89.0)
-      json (~> 2.3)
+    rubocop (1.90.0)
+      json (>= 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
       parallel (>= 1.10)
@@ -146,7 +146,7 @@ GEM
       rubocop (~> 1.81)
     ruby-progressbar (1.13.0)
     securerandom (0.4.1)
-    simplecov (1.0.3)
+    simplecov (1.1.1)
     simplecov-cobertura (4.0.0)
       rexml
       simplecov (~> 1.0)
@@ -167,7 +167,7 @@ GEM
       unicode-emoji (~> 4.1)
     unicode-emoji (4.2.0)
     uri (1.1.1)
-    webmock (3.26.2)
+    webmock (3.26.4)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)

data/README.md

@@ -19,7 +19,7 @@ Safire is a Ruby gem for healthcare client applications that implements [SMART A
 - Confidential Symmetric Client (`client_secret` + HTTP Basic Auth)
 - Confidential Asymmetric Client (`private_key_jwt` with RS384/ES384)
 - POST-Based Authorization
-- Backend Services (`client_credentials` grant, JWT assertion, no user interaction or PKCE; scope defaults to `system/*.rs`)
+- Backend Services (`client_credentials` grant, JWT assertion, no user interaction or PKCE; client-selected scopes)
 
 ### UDAP Security (STU2)
 
@@ -77,6 +77,13 @@ cancellation = udap_client.cancel_registration(
 )
 ```
 
+UDAP registration uses the trusted fields needed for that workflow rather than
+turning the full `UdapMetadata#valid?` conformance diagnostic into an automatic
+gate. In v0.4.1, an unadvertised requested wildcard produces a warning and is
+still submitted; v0.5.0 will require exact wildcard advertisement for
+registration and modification while keeping wildcard scope drift warning-only
+during cancellation.
+
 UDAP JWT client authentication and Tiered OAuth are planned. See [ROADMAP.md](https://github.com/vanessuniq/safire/blob/main/ROADMAP.md) for details.
 
 ---
@@ -185,6 +192,12 @@ token_data = client.request_backend_token(
 client.token_response_valid?(token_data, flow: :backend_services)
 ```
 
+Configure scopes on the client or pass `scopes:` to each Backend Services
+request. The legacy `system/*.rs` fallback is deprecated in v0.4.x and will be
+removed in v0.6.0. Backend Services normally uses `system/` scopes. Safire
+preserves explicit non-system scopes because SMART permits them when context is
+established out of band.
+
 ---
 
 ## Configuration

data/ROADMAP.md

@@ -1,6 +1,6 @@
 # Safire Roadmap
 
-## Latest Published Release — v0.4.0
+## Latest Published Release — v0.4.1
 
 Safire is in early development (pre-release). The API is functional but not yet stable — breaking changes may occur before v1.0.0. Published to [RubyGems](https://rubygems.org/gems/safire).
 
@@ -22,7 +22,7 @@ Feedback, bug reports, and pull requests are welcome via the [issue tracker](htt
 - **POST-Based Authorization** — form-encoded authorization requests
 - **JWT Assertion Builder** — signed JWT assertions with configurable `kid` and expiry
 - **PKCE** — automatic code verifier and challenge generation
-- **Backend Services** — `client_credentials` grant for system-to-system flows; JWT assertion (RS384/ES384); no user interaction, redirect, or PKCE required; scope defaults to `system/*.rs` when not configured
+- **Backend Services** — `client_credentials` grant for system-to-system flows; JWT assertion (RS384/ES384); no user interaction, redirect, or PKCE required; client-selected scopes with a deprecated v0.4.x compatibility fallback
 - **Dynamic Client Registration** — runtime client registration per [RFC 7591](https://www.rfc-editor.org/rfc/rfc7591); endpoint discovered from SMART metadata or supplied explicitly; supports initial access token
 
 ### UDAP Security (STU2 / v2.0.0)
@@ -53,9 +53,30 @@ Feedback, bug reports, and pull requests are welcome via the [issue tracker](htt
 
 ## Planned Features
 
-### UDAP Security
+### v0.5.0 — UDAP JWT Client Authentication and B2B Authorization
+
+- **UDAP Registration Wildcard Enforcement** — require exact
+  `scopes_supported` advertisement for requested wildcard scopes during new
+  registration and modification after the v0.4.1 warning period; cancellation
+  remains warning-only so metadata drift cannot strand an existing registration
+- **UDAP Authentication Tokens** — certificate-backed JWT client authentication
+  for token endpoint requests, using authoritative signed discovery metadata
+- **B2B Client Credentials** — headless system-to-system authorization with the
+  STU2 `hl7-b2b` authorization extension and discovery-constrained scopes,
+  signing algorithms, and extension support
+
+### v0.6.0 — UDAP Authorization Code Flows
+
+- **Explicit SMART Backend Scopes** — remove the deprecated `system/*.rs`
+  fallback; Backend Services requests without configured or per-call scopes
+  raise `ConfigurationError`
+- **Consumer-Facing Authorization** — UDAP authorization code flow with state,
+  PKCE, Authentication Tokens, code exchange, and refresh support
+- **Interactive B2B Authorization** — authorization code flow for B2B clients,
+  including local-user authorization and UDAP client authentication
+
+### v0.7.0 — UDAP Tiered OAuth
 
-- **UDAP JWT Client Auth** — B2B and consumer-facing authorization flows
 - **Tiered OAuth** — identity chaining for multi-system access
 
 ### Quality and Compliance
@@ -99,5 +120,5 @@ Feedback, bug reports, and pull requests are welcome via the [issue tracker](htt
 | ActiveSupport | ≥ 7.1, < 9 |
 | Rails (optional) | ≥ 7.1 |
 | SMART App Launch | 2.2.0 (STU2) |
-| UDAP Security | 2.0.0 (STU2 discovery and Dynamic Client Registration lifecycle implemented; auth flows planned) |
+| UDAP Security | 2.0.0 (STU2 discovery and Dynamic Client Registration lifecycle implemented; JWT client authentication and authorization flows planned) |
 | FHIR | R4, R4B |

data/docs/adr/ADR-006-lazy-discovery.md

@@ -125,6 +125,15 @@ end
 
 A 204 response means the server has no UDAP workflows for that community. `Protocols::Udap` raises `DiscoveryError` before the body is parsed, with a descriptive message that identifies the community when one was requested.
 
+SMART and UDAP discovery both require a JSON object but do not depend on the
+HTTP adapter having already decoded it. A shared protocol-neutral parser accepts
+an already parsed Hash or a raw JSON-object string, then deeply normalizes keys
+without mutating adapter-owned data. This allows Safire to interoperate when a
+server sends valid JSON with an incorrect or missing content type; the response
+is still non-conformant at the HTTP layer. Malformed JSON, non-object JSON, and
+ambiguous or non-JSON-compatible adapter Hashes raise the protocol's existing
+`DiscoveryError`.
+
 ---
 
 ## Consequences
@@ -136,6 +145,8 @@ A 204 response means the server has no UDAP workflows for that community. `Proto
 - Callers control when discovery happens — supports application-level caching patterns (see [Advanced Examples]({{ site.baseurl }}/advanced/#metadata-caching))
 - `client_type=` mutation preserves cached SMART metadata — no re-discovery
 - UDAP community-and-trust-policy cache allows a single client instance to serve multiple communities without serving stale signed metadata
+- Discovery parsing is independent of response content-type middleware while
+  still failing closed on unusable object data
 
 **Trade-offs:**
 - Discovery errors surface at first use (e.g. `authorization_url`), not at construction — callers must handle `Errors::DiscoveryError` in their flow logic rather than at the `new` call site

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

@@ -30,7 +30,7 @@ security boundary and can hide production misconfiguration.
 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 `allow_insecure_localhost: true` is configured and 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`. OAuth redirect, authorization, and token endpoint URIs must not contain a fragment component, as required by RFC 6749 Sections 3.1 and 3.2.
 
 **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.
 
@@ -57,9 +57,9 @@ 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.
+`URIValidation#classify_uri` provides the shared HTTPS and fragment policy.
+UDAP redirect URIs reject fragment components; the rule is not applied to the
+presentation-oriented `logo_uri` field.
 
 `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`,

data/docs/adr/ADR-008-warn-return-false-for-compliance-validation.md

@@ -15,7 +15,10 @@ nav_order: 8
 
 Safire performs two different kinds of checks:
 
-1. **Configuration checks** — validating that the caller has provided a usable configuration (required attributes present, URIs well-formed and HTTPS). These run at construction time and represent programming errors if they fail.
+1. **Configuration checks** — validating that the caller has provided usable
+   configuration (required attributes present, URIs well-formed and HTTPS).
+   General checks run at construction time; flow-specific requirements run at
+   the operation boundary. They represent caller-correctable errors if they fail.
 
 2. **Compliance checks** — validating that a remote server's response conforms to the SMART App Launch 2.2.0 specification. These run at runtime and represent server behaviour, not caller behaviour.
 
@@ -31,6 +34,12 @@ Option B lets the caller decide what to do: they can check the return value, obs
 
 There is also a clear boundary: **the caller controls the config** (configuration errors should raise — the caller can fix them); **the server controls the response** (compliance violations should warn — the caller cannot fix a remote server).
 
+This caller/server distinction is a useful default, but it is not sufficient
+for security-sensitive runtime decisions. ADR-015 refines the boundary: remote
+data raises when its defect makes the requested client operation unsafe,
+impossible, or unconfirmed. Complete structural conformance remains an explicit
+warn-and-return-false diagnostic when the operation does not depend on it.
+
 ---
 
 ## Decision
@@ -52,12 +61,16 @@ end
 ```
 
 These methods:
+
 - Never raise an exception
 - Log one warning per violation (not a single combined message) so each issue is individually observable
-- Return `true` only when fully compliant; `false` as soon as any violation is found
+- Return `true` only when fully compliant and `false` when any violation is found
 - Are **user-callable** — they are not invoked automatically by `authorization_url` or `server_metadata`; callers opt in to compliance checking
 
-Configuration validation (`ClientConfig#validate!`, `Smart#validate!`) raises `ConfigurationError` — these are programming errors that must be fixed before the gem can function.
+Configuration validation in `ClientConfig` and protocol workflow-readiness
+checks raise typed Safire errors. These are caller-correctable failures or
+conditions that make the requested operation unsafe, impossible, or
+unconfirmed; ADR-015 owns the detailed boundary.
 
 ---
 
@@ -71,5 +84,5 @@ Configuration validation (`ClientConfig#validate!`, `Smart#validate!`) raises `C
 
 **Trade-offs:**
 - Callers who do not call `token_response_valid?` get no compliance signal at all — non-compliant responses are silently accepted; this is intentional (opt-in, not opt-out)
-- The distinction between "warn + return false" and "raise" must be maintained consistently — new validation methods should follow the same rule: server behaviour → warn; caller configuration → raise
+- The distinction between "warn + return false" and "raise" must be maintained consistently. New validation methods follow ADR-015: explicit conformance diagnostics warn, while client obligations and security or operation-readiness failures raise.
 - `token_response_valid?` accepts a `flow:` keyword argument (`:app_launch` default, `:backend_services`) that adjusts which fields are required and what the warning messages say. For example, `token_type` must be `"Bearer"` (App Launch spec) or `"bearer"` (Backend Services spec), and `expires_in` is RECOMMENDED for App Launch but REQUIRED for Backend Services. Callers opt in to the stricter backend-services validation by passing `flow: :backend_services`

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

@@ -98,7 +98,9 @@ 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
+Registration success responses delegate JSON-object parsing to the private,
+protocol-neutral `JSONResponseParsing` collaborator. Raw JSON strings and
+already parsed Hashes are normalized to new, deeply 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
@@ -106,9 +108,14 @@ 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`.
+Malformed, non-object, ambiguous, or non-JSON-compatible 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`. Symbol/string key collisions and the other Ruby
+structure guards apply only to adapter-supplied or directly passed Hashes;
+`JSON.parse` and Faraday's JSON middleware produce string-keyed Hashes. The
+guards prevent local normalization from silently overwriting ambiguous values,
+not collisions in JSON received on the wire.
 
 ### Amendment consequences
 
@@ -118,6 +125,8 @@ UDAP-specific values such as `invalid_software_statement`.
   construction or endpoint policy
 - response key normalization makes direct and middleware-parsed hashes behave
   consistently
+- strict adapter-Hash validation makes response translation total for cyclic or
+  non-JSON-compatible Ruby values
 - malformed successful registrations fail before an invalid identifier reaches
   application state
 

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

@@ -66,10 +66,11 @@ semantics.
   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`) must be absolute HTTPS URLs without fragment components; 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 and does not relax
+  the fragment prohibition
 - `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`
@@ -108,6 +109,7 @@ semantics.
 
 **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
+- A directly constructed `UdapMetadata` object is not automatically
+  cryptographically validated. `Safire::Client#server_metadata` validates
+  `signed_metadata` before returning the entity; callers that construct an
+  entity themselves must establish that trust separately.

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

@@ -41,6 +41,11 @@ 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.
 
+Registration orchestration constructs this value object once, before discovery
+or other network activity. Scope diagnostics and software-statement signing
+consume the same immutable instance; Safire does not independently normalize
+the caller's raw Hash at multiple stages.
+
 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,
@@ -55,7 +60,20 @@ Registration accepts exactly one primary grant:
 
 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.
+registration. Redirect and logo URIs require absolute HTTPS by default, and
+redirect URIs must not contain fragment components.
+
+The STU2 logo requirement has two different validation boundaries. Safire can
+prove locally that `logo_uri` is an absolute HTTPS URI, so malformed, relative,
+and insecure public values fail before signing. Safire cannot prove that the
+remote representation is PNG, JPG/JPEG, or GIF from a URI path alone. Familiar
+image suffixes remain a quiet heuristic; other usable URI paths produce a
+value-free warning and remain the caller's responsibility.
+
+Safire does not dereference `logo_uri` during validation. Fetching an untrusted
+caller-supplied URI would introduce SSRF, latency, redirect, and remote
+availability concerns into construction of an otherwise local value object,
+without reliably proving what the authorization server will later retrieve.
 
 For local development without TLS, callers may explicitly pass
 `allow_insecure_localhost: true`. This permits HTTP only on `localhost` and
@@ -94,10 +112,13 @@ regular expression.
 ## Consequences
 
 - Signing code can consume one canonical, already validated metadata hash.
+- Invalid caller metadata fails before discovery, signing, or POSTing.
 - 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.
+- Logo media type remains a caller obligation when it cannot be established
+  from the URI path; Safire reports that uncertainty without fetching the URI.
 - Extension metadata remains forward-compatible without permitting arbitrary
   Ruby objects into a JWT payload.
 - Metadata validation remains independent of software-statement signing and the

data/docs/adr/ADR-014-udap-software-statement-signing.md

@@ -81,10 +81,14 @@ key, and advertised by the server. Without an explicit algorithm, Safire chooses
 the first key-compatible advertised algorithm, preferring `RS256` over `RS384`
 for RSA keys because `RS256` is the STU2 baseline.
 
-Protocol orchestration separately requires every DCR-capable server to advertise
-mandatory `RS256` support before Safire signs with any compatible advertised
-algorithm. This enforces the server baseline independently from the configured
-client key type.
+Protocol orchestration requires the advertised value to be a non-empty array of
+algorithm names. A malformed or empty value makes safe algorithm selection
+impossible and raises `DiscoveryError`. Because STU2 requires every FHIR server
+to support `RS256`, Safire warns when it is absent. The warning diagnoses the
+server baseline without blocking an otherwise interoperable request: the
+builder may still select another advertised, Safire-supported,
+key-compatible algorithm. A valid advertisement with no usable intersection
+raises `ConfigurationError`.
 
 ### Validate local signing identity, not server trust
 

data/docs/adr/ADR-015-client-role-and-runtime-readiness.md

@@ -0,0 +1,207 @@
+---
+layout: default
+title: "ADR-015: Client role and runtime readiness"
+parent: Architecture Decision Records
+nav_order: 15
+---
+
+# ADR-015: Client role and runtime readiness
+
+**Status:** Accepted
+
+---
+
+## Context
+
+Safire consumes metadata and protocol responses from remote SMART App Launch
+and UDAP servers. Some defects make a client request unsafe or impossible;
+others are server conformance defects that an interoperable client can report
+without blocking an otherwise valid operation.
+
+A blanket rule such as "caller input raises, server input warns" is not
+sufficient at a protocol trust boundary. A server controls discovery and token
+responses, but Safire must still reject an untrusted value when it is needed to
+select a secure endpoint, validate a signed assertion, protect credentials, or
+establish that a lifecycle operation completed. Conversely, complete server
+certification is outside a client library's runtime role.
+
+Safire therefore needs a consistent way to distinguish operational readiness
+from optional conformance diagnostics. Comprehensive server certification
+belongs in a conformance harness such as Inferno.
+
+## Decision
+
+Safire classifies protocol checks by their effect on the requested client
+operation:
+
+1. **Runtime hard failure:** reject a condition that would violate a client
+   obligation, make the operation unsafe or impossible, expose credentials, or
+   leave a security-sensitive result unconfirmed. This includes malformed wire
+   shapes required by the operation and failed UDAP signed-metadata trust
+   validation.
+2. **Warning or negotiation:** report a server defect or uncertain capability
+   when Safire can still send a safe, conformant request and the server remains
+   authoritative for acceptance.
+3. **Explicit diagnostic:** methods such as `SmartMetadata#valid?`,
+   `UdapMetadata#valid?`, and `Smart#token_response_valid?` warn and return a
+   Boolean when called. Discovery does not automatically promote every failed
+   diagnostic into a workflow failure.
+4. **Server-owned decision:** authorization grants, requested scope approval,
+   client registration policy, certifications, and issued credentials are
+   decided by the authorization server. Safire validates its request and the
+   response shape it must consume, but does not predict the policy result.
+
+This decision refines ADR-008. Server-controlled data is warning-only when the
+defect does not cross a security or operation-readiness boundary; its remote
+origin alone does not determine the error behavior.
+
+Protocol response bodies that must be JSON objects use the private,
+protocol-neutral `JSONResponseParsing` collaborator. It accepts an already
+parsed `Hash` or a raw JSON string, produces a new deeply string-keyed Hash, and
+rejects malformed or non-object JSON. Adapter-supplied Hashes also fail closed
+when they contain recursive structures, unsupported JSON key or value types,
+non-finite numbers, invalid string encodings, excessive nesting, or keys that
+collide after symbol-to-string normalization. The collaborator returns a parse
+failure and leaves each consumer to choose its protocol-specific error class.
+
+Parsing a valid raw JSON object allows interoperability when an HTTP adapter did
+not decode the body because the server sent an incorrect or missing content
+type. Safire's tolerance does not make that server response conformant.
+
+Metadata capability helpers type-check list-shaped advertisements before using
+membership semantics. A malformed list cannot assert a SMART capability or
+raise an unexpected type error. The complete structural assessment remains the
+caller's explicit `SmartMetadata#valid?` diagnostic rather than an automatic
+discovery failure.
+
+SMART discovery preserves metadata for inspection, but an operation validates
+its discovered authorization or token endpoint against Safire's HTTPS policy
+and rejects fragment components before use. This focused runtime stop protects
+authorization data and client credentials while enforcing the OAuth endpoint
+shape the operation consumes, without promoting unrelated metadata defects into
+discovery failures.
+
+UDAP DCR uses focused readiness rather than calling `UdapMetadata#valid?` as an
+operational gate. Safire requires trusted discovery, an advertised `udap_dcr`
+profile, a usable authoritative registration endpoint, usable registration
+algorithm metadata, and type-safe certification requirements. Other structural
+conformance checks remain available through the explicit `valid?` diagnostic.
+
+In v0.4.1, requested UDAP registration scopes are diagnostic only. Requested
+tokens containing a literal `*` are classified first and compared by exact
+membership in `scopes_supported`; narrower recognized SMART FHIR scopes may be
+covered by broader advertised scopes. Unrecognized syntax uses exact membership.
+Missing, malformed, or insufficient advertisements produce separate aggregated
+warnings while the server remains authoritative for negotiation. Registration
+and modification move to exact wildcard enforcement in v0.5.0; cancellation
+remains warning-only so an existing registration can still be removed.
+
+For warning suppression only, compatible advertised FHIR permission fragments
+may collectively cover a requested permission set. STU2 does not guarantee that
+the server accepts the combined token, so this permissive inference must not be
+reused as a hard-failure decision without a separate normative rule.
+
+SMART Backend Services scope intent remains client-owned. In v0.4.x, Safire
+preserves the historical `system/*.rs` fallback only for compatibility and
+logs a deprecation warning whenever it is used. Callers should configure or
+pass scopes explicitly; absent scopes become a runtime `ConfigurationError` in
+v0.6.0. SMART discovery `scopes_supported` is non-exhaustive and is not used as
+an exact allow-list for token requests.
+
+`system/` scopes are the normal Backend Services context. The
+[SMART STU2.2 Backend Services scope requirements](https://hl7.org/fhir/smart-app-launch/STU2.2/backend-services.html#scopes)
+also state that `user/` and `patient/` scopes are not prohibited when context
+is established through out-of-band coordination. Safire therefore preserves
+and submits explicit non-system scopes without warning or rejection. The
+library cannot determine whether the caller completed that external
+coordination, and must not make a permitted healthy path noisy based on missing
+local evidence.
+
+Scope diagnostics log only the requested scope category and count, never the
+raw token values. SMART v2 scopes may carry FHIR search constraints, and opaque
+custom scopes may encode equally sensitive application context in forms Safire
+cannot safely redact. Count-and-category logging preserves the operational and
+migration signal without copying caller-controlled authorization details into
+application logs.
+
+The classifications below were checked against the published
+[SMART App Launch STU2.2 conformance and discovery rules](https://hl7.org/fhir/smart-app-launch/STU2.2/conformance.html),
+[SMART App Launch workflow](https://hl7.org/fhir/smart-app-launch/STU2.2/app-launch.html),
+[SMART Backend Services profile](https://hl7.org/fhir/smart-app-launch/STU2.2/backend-services.html),
+[RFC 7591 Dynamic Client Registration](https://www.rfc-editor.org/rfc/rfc7591),
+[UDAP Security STU2 discovery](https://hl7.org/fhir/us/udap-security/STU2/discovery.html),
+and [UDAP Security STU2 registration](https://hl7.org/fhir/us/udap-security/STU2/registration.html).
+
+## Operation Matrix
+
+This matrix covers the public protocol operations currently implemented by the
+`Safire::Client` facade.
+
+| Operation | Client obligation | Required capability or input | Runtime hard failure | Runtime warning or negotiation | Explicit diagnostic | Server-owned decision |
+|-----------|-------------------|------------------------------|----------------------|--------------------------------|---------------------|-----------------------|
+| SMART `server_metadata` | Request and consume the well-known JSON object over a protected connection | FHIR base URL | Transport or HTTP failure; unusable JSON-object body | None | Caller may invoke `SmartMetadata#valid?` | Advertised endpoints and capabilities |
+| SMART `authorization_url` | Supply client ID, redirect URI, scopes, and launch context as applicable; Safire adds state and S256 PKCE | Usable authorization endpoint; caller selects GET or POST | Invalid request method; missing client ID, scopes, or redirect URI; missing, malformed, or insecure endpoint | None | Metadata capability helpers and `SmartMetadata#valid?` remain caller-invoked | User authorization, launch context, accepted request method, and granted scopes |
+| SMART `request_access_token` | Supply the authorization code, matching PKCE verifier, redirect URI, and client credentials required by the configured client type | Usable token endpoint | Missing credentials; invalid JWT assertion configuration; missing, malformed, or insecure endpoint; transport, OAuth, unusable response, or missing access-token failure | None | Caller may invoke `token_response_valid?` | Code acceptance and issued token contents |
+| SMART `refresh_token` | Supply the refresh token and authenticate the client; any requested scopes must not exceed the original grant | Usable token endpoint | Missing credentials; invalid JWT assertion configuration; missing, malformed, or insecure endpoint; transport, OAuth, unusable response, or missing access-token failure | None | Caller may invoke `token_response_valid?` | Refresh-token acceptance and issued scope |
+| SMART `request_backend_token` | Supply client ID, a registered signing identity, and explicit scope intent | Usable token endpoint and pre-authorized asymmetric client registration | Missing identity or signing credentials; invalid JWT assertion configuration; missing, malformed, or insecure endpoint; transport, OAuth, unusable response, or missing access-token failure | The v0.4.x legacy scope fallback warns; explicit scopes remain subject to server negotiation | Caller may invoke `token_response_valid?(flow: :backend_services)` | Out-of-band context, client authentication, requested scope, and token issuance |
+| SMART `register_client` | Supply RFC 7591 client metadata and any required initial access token | Explicit or discovered HTTPS registration endpoint | Missing or unsafe endpoint; transport or OAuth failure; unusable response or missing/invalid client ID | None | Discovery capability helpers and `SmartMetadata#valid?` remain caller-invoked | Registration policy, accepted metadata, and issued credentials |
+| SMART `token_response_valid?` | Choose whether to require the optional conformance diagnostic | Token-response Hash and selected flow | None; this method is not an operational gate | Logs each diagnosed response defect and returns `false` | This method is the explicit diagnostic | Caller decides how to handle a failed diagnostic |
+| UDAP `server_metadata` | Supply the intended community and production trust/revocation policy; validate signed metadata before any later workflow | UDAP well-known endpoint and a trusted signed-metadata chain | Transport, HTTP, or 204 outcome; unusable JSON object; failed signature, chain, revocation, issuer, time, or endpoint validation | None | Caller may invoke `UdapMetadata#valid?` or explicitly re-run `signed_metadata_valid?` | Community-specific profiles and capabilities |
+| UDAP `register_client` | Supply conformant metadata, client URI, certifications when required, and a matching private key/certificate chain | Trusted discovery; `udap_dcr`; authoritative registration endpoint; usable algorithm and certification-requirement metadata | Unsafe or unusable readiness data; invalid caller metadata or signing identity; transport or server rejection; pending or malformed completion response | Missing RS256 advertisement and unconfirmed scope support warn in v0.4.1 | Caller may invoke `UdapMetadata#valid?`; it is not a blanket gate | Registration policy, scope and certification acceptance, effective metadata, and issued client ID |
+| UDAP `cancel_registration` | Supply the same stable client URI and trust-community identity; preserve local state until cancellation is confirmed | Registration readiness above and an existing registration to remove | Registration hard failures above; any response that does not provide final 2xx body confirmation with the client ID and empty grants | Scope compatibility and malformed scope advertisements remain warning-only so cleanup can proceed | Caller may invoke `UdapMetadata#valid?`; it is not a blanket gate | Cancellation policy and the confirmation response |
+
+SMART cancellation and UDAP authorization, token, refresh, backend-token, and
+token-response operations are not implemented. They raise
+`NotImplementedError` through the shared protocol contract rather than implying
+runtime support.
+
+### Rules for Future Operations
+
+Every new public protocol operation must update the matrix and apply these
+questions in order:
+
+1. Which normative actor owns the requirement: client, authorization server,
+   resource server, or trust community?
+2. Does a failure prevent Safire from constructing a conformant request,
+   selecting a trusted endpoint, protecting credentials, or confirming the
+   operation's result? If so, fail before signing or network activity whenever
+   the condition is locally knowable.
+3. Can Safire still send a safe, conformant request while the server remains
+   authoritative for policy or negotiation? If so, preserve the request and use
+   a warning only when it gives the caller actionable information.
+4. Is the check broad server conformance rather than operation readiness? Keep
+   it in an explicit diagnostic and do not call it automatically.
+5. Is untrusted response data consumed by the operation? Validate its type and
+   shape before use, and translate failure into the protocol-specific Safire
+   error rather than leaking a Ruby implementation exception.
+6. Does an error prove rejection, or only an unavailable, malformed, pending,
+   or otherwise unconfirmed outcome? Use only the strongest description the
+   evidence supports.
+7. Does the implementation invent client intent, retry a possibly committed
+   operation, or log caller credentials or authorization details? If so, stop
+   and require an explicit, documented policy instead.
+
+Shared helpers may encode mechanism, such as JSON-object parsing or
+warning-only UDAP scope coverage, but must not silently promote a diagnostic
+inference into a hard-failure rule for another workflow.
+
+## Consequences
+
+**Benefits:**
+
+- Runtime failures now have an operation or security rationale rather than
+  serving as blanket server certification.
+- Callers retain explicit tools for enforcing stricter server conformance.
+- Shared JSON-object parsing is total for untrusted adapter output and preserves
+  protocol-specific error ownership.
+- Valid raw JSON objects remain usable even when response content-type handling
+  is imperfect.
+
+**Trade-offs:**
+
+- The same metadata defect can be diagnostic in one flow and fatal in another
+  when the latter needs the affected field to proceed safely.
+- Tolerating a raw JSON object can hide an HTTP content-type defect unless the
+  caller separately audits server conformance.
+- The operation matrix must be updated whenever a public protocol operation or
+  runtime gate is added or materially changed.