safire 0.2.0 → 0.4.0

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

@@ -0,0 +1,122 @@
+---
+layout: default
+title: "ADR-014: UDAP software-statement signing"
+parent: Architecture Decision Records
+nav_order: 14
+---
+
+# ADR-014: UDAP software-statement signing
+
+**Status:** Accepted
+
+---
+
+## Context
+
+UDAP Dynamic Client Registration submits caller-controlled registration
+metadata inside a signed software statement. HL7 UDAP Security STU2 requires
+that statement to be a compact JWS with an `alg` header, an inline leaf-first
+`x5c` certificate chain, issuer and subject set to the client URI, audience set
+to the authorization server's registration endpoint, a short validity window,
+and a fresh `jti`.
+
+Safire already has `JWTAssertion` for SMART private-key JWT authentication, but
+that class has SMART-specific audiences, claims, headers, algorithms, and key
+distribution assumptions. Reusing it for UDAP would require protocol branches
+in the signing path and make both flows harder to reason about.
+
+---
+
+## Decision
+
+### Use a dedicated builder
+
+`UdapSoftwareStatement` builds only UDAP registration software statements. It
+accepts a validated `UdapRegistrationMetadata` object, a client URI, the
+discovered registration endpoint, a private key, a leaf-first certificate
+chain, and the server-advertised registration signing algorithms.
+
+The builder has no HTTP behavior and does not perform discovery. UDAP protocol
+orchestration is responsible for fetching metadata, checking DCR capability,
+POSTing the request envelope, and parsing the response.
+
+### Keep URI comparison exact
+
+The client URI is used exactly as `iss` and `sub` and must exactly match a
+`uniformResourceIdentifier` Subject Alternative Name entry in the leaf
+certificate. Safire does not derive it from `ClientConfig#issuer` and does not
+canonicalize case, ports, or trailing slashes.
+
+STU2 does not constrain the URI scheme used for client identifiers, so Safire
+does not require `client_uri` to use HTTPS. HTTP and HTTPS client URIs must have
+a host, while trust-community schemes such as `did:` can be valid when they are
+absolute and exactly match the certificate URI SAN.
+
+The registration endpoint is different: it is a server endpoint used as `aud`
+and must be an absolute HTTPS URI by default. `allow_insecure_localhost: true`
+permits HTTP only on `localhost` or `127.0.0.1` for local development. The value
+is still signed exactly as supplied.
+
+### Generate a minimal JOSE header
+
+Safire includes only the required `alg` and `x5c` header fields. It does not
+emit `typ`, `kid`, `jku`, or `x5u`. STU2's experimental `jku` alternative does
+not apply to registration requests.
+
+`x5c` is generated from the supplied certificate chain in leaf-first issuer
+order. Each entry is Base64 DER with no PEM wrapper.
+
+### Constrain algorithm selection
+
+Safire supports the STU2 algorithm set it can sign safely:
+
+| Key | Algorithms |
+|-----|------------|
+| RSA | `RS256`, `RS384` |
+| EC P-256 | `ES256` |
+| EC P-384 | `ES384` |
+
+An explicit algorithm must be supported by Safire, compatible with the private
+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.
+
+### Validate local signing identity, not server trust
+
+Before signing, Safire parses and snapshots the certificate chain, checks that
+the supplied chain is leaf-first and issuer-ordered, verifies that the private
+key matches the leaf certificate, and checks that the client URI appears in the
+leaf certificate URI SAN. Certificate validity dates are checked when the
+builder is constructed and rechecked each time a software statement is emitted.
+
+Safire does not decide whether the authorization server will trust the client
+certificate chain. Chain-building to trust anchors, revocation policy, and
+community trust for the client certificate remain authorization-server
+decisions during registration processing.
+
+### Keep test seams explicit
+
+The builder accepts a clock and a JTI generator. Production defaults are
+`Time.now` and `SecureRandom.uuid`; specs inject deterministic values without
+stubbing global randomness.
+
+---
+
+## Consequences
+
+- SMART JWT assertions and UDAP software statements remain separate, readable
+  signing paths.
+- Invalid local signing configuration fails before a malformed JWT can be
+  produced.
+- The generated JWT is short-lived: `exp` is always `iat + 300`.
+- Private keys, compact JWTs, and certificate contents are not included in
+  validation error messages.
+- End-to-end UDAP registration lifecycle operations use this builder through
+  `Protocols::Udap#register_client` and `Protocols::Udap#cancel_registration`;
+  applications should prefer the facade methods over direct software-statement
+  construction.

data/docs/adr/index.md

@@ -17,6 +17,12 @@ Architecture Decision Records (ADRs) document significant design decisions made
 | [ADR-003]({% link adr/ADR-003-protocol-vs-client-type.md %}) | `protocol:` and `client_type:` as orthogonal dimensions | Accepted |
 | [ADR-004]({% link adr/ADR-004-clientconfig-immutability-and-entity-masking.md %}) | `ClientConfig` immutability and `Entity` sensitive attribute masking | Accepted |
 | [ADR-005]({% link adr/ADR-005-per-client-http-ownership.md %}) | Per-client `HTTPClient` ownership — no shared connection pool | Accepted |
-| [ADR-006]({% link adr/ADR-006-lazy-discovery.md %}) | Lazy SMART discovery — no HTTP in constructors | Accepted |
-| [ADR-007]({% link adr/ADR-007-https-only-redirects-and-localhost-exception.md %}) | HTTPS-only redirect enforcement and localhost exception | Accepted |
-| [ADR-008]({% link adr/ADR-008-warn-return-false-for-compliance-validation.md %}) | Warn and return false for compliance validation — raise only for configuration errors | Accepted |
+| [ADR-006]({% link adr/ADR-006-lazy-discovery.md %}) | Lazy discovery — no HTTP in constructors | Accepted |
+| [ADR-007]({% link adr/ADR-007-https-only-redirects-and-localhost-exception.md %}) | HTTPS-only enforcement and explicit localhost opt-in | Accepted |
+| [ADR-008]({% link adr/ADR-008-warn-return-false-for-compliance-validation.md %}) | Warn and return false for compliance validation — raise only for configuration errors | Accepted |
+| [ADR-009]({% link adr/ADR-009-oauth-error-hierarchy.md %}) | `OAuthError` base class and `ReceivesFields` mixin for protocol error hierarchy | Accepted |
+| [ADR-010]({% link adr/ADR-010-optional-client-id-dcr-temp-client.md %}) | `client_id` optional at initialization — deferred validation for the DCR temp-client pattern | Accepted |
+| [ADR-011]({% link adr/ADR-011-udap-stu2-discovery-conformance.md %}) | `UdapMetadata` entity — structural validation separate from cryptographic validation | Accepted |
+| [ADR-012]({% link adr/ADR-012-udap-signed-metadata-validation.md %}) | `signed_metadata` JWT validation — design and chain verification defaults | Accepted |
+| [ADR-013]({% link adr/ADR-013-udap-registration-request-model.md %}) | UDAP registration metadata as an immutable value object | Accepted |
+| [ADR-014]({% link adr/ADR-014-udap-software-statement-signing.md %}) | UDAP software-statement signing | Accepted |

data/docs/advanced.md

@@ -32,14 +32,7 @@ class SmartMetadataService
 
   def self.fetch(base_url)
     Rails.cache.fetch("smart_metadata:#{base_url}", expires_in: CACHE_TTL) do
-      config = Safire::ClientConfig.new(
-        base_url:     base_url,
-        client_id:    'discovery_only',
-        redirect_uri: 'https://example.com',
-        scopes:       []
-      )
-      client = Safire::Client.new(config)
-      client.server_metadata.to_hash
+      Safire::Client.new({ base_url: base_url }).server_metadata.to_hash
     end
   end
 
@@ -142,11 +135,11 @@ class TokenManager
     token_params  = { refresh_token: session[:refresh_token] }
     response      = client.refresh_token(token_params)
 
-    session[:access_token]     = response[:access_token]
-    session[:refresh_token]    = response[:refresh_token] || session[:refresh_token]
-    session[:token_expires_at] = Time.current + response[:expires_in].to_i.seconds
+    session[:access_token]     = response['access_token']
+    session[:refresh_token]    = response['refresh_token'] || session[:refresh_token]
+    session[:token_expires_at] = Time.current + response['expires_in'].to_i.seconds
 
-    response[:access_token]
+    response['access_token']
   end
 end
 ```
@@ -178,9 +171,9 @@ Override the default scopes for specific actions without reconfiguring the clien
 
 ```ruby
 def launch_with_scopes(client, extra_scopes: [])
-  base_scopes  = ['openid', 'profile', 'patient/*.read']
-  merged       = (base_scopes + extra_scopes).uniq
-  client.authorization_url(scope_override: merged)
+  base_scopes = ['openid', 'profile', 'patient/*.read']
+  merged      = (base_scopes + extra_scopes).uniq
+  client.authorization_url(custom_scopes: merged)
 end
 
 # Requesting additional write access for a specific workflow
@@ -207,11 +200,11 @@ class SmartAuthController < ApplicationController
 
   # Step 1 — Redirect user to the authorization server
   def launch
-    auth_url = @client.authorization_url
-    session[:pkce_verifier] = @client.code_verifier
-    session[:state]         = @client.state
+    auth_data = @client.authorization_url
+    session[:code_verifier] = auth_data[:code_verifier]
+    session[:state]         = auth_data[:state]
 
-    redirect_to auth_url, allow_other_host: true
+    redirect_to auth_data[:auth_url], allow_other_host: true
   end
 
   # Step 2 — Handle the authorization server callback
@@ -221,15 +214,19 @@ class SmartAuthController < ApplicationController
       return
     end
 
-    token_response = @client.exchange_code_for_token(
+    unless params[:state] == session.delete(:state)
+      redirect_to root_path, alert: 'Invalid state parameter'
+      return
+    end
+
+    token_response = @client.request_access_token(
       code:          params[:code],
-      state:         params[:state],
-      pkce_verifier: session.delete(:pkce_verifier)
+      code_verifier: session.delete(:code_verifier)
     )
 
-    session[:access_token]     = token_response[:access_token]
-    session[:refresh_token]    = token_response[:refresh_token]
-    session[:token_expires_at] = Time.current + token_response[:expires_in].to_i.seconds
+    session[:access_token]     = token_response['access_token']
+    session[:refresh_token]    = token_response['refresh_token']
+    session[:token_expires_at] = Time.current + token_response['expires_in'].to_i.seconds
 
     redirect_to dashboard_path
   end

data/docs/configuration/client-setup.md

@@ -45,11 +45,20 @@ config = Safire::ClientConfig.new(
 client = Safire::Client.new(config)
 ```
 
+{: .note }
+> `client_id` is intentionally optional at construction. `authorization_url`,
+> `request_access_token`, `refresh_token`, and `request_backend_token` validate
+> it when called. This permits a temporary client to call `register_client` and
+> obtain an identifier first. Other flow-specific credentials and signing
+> requirements may also be validated when the operation that needs them runs.
+> See [SMART Dynamic Client Registration]({{ site.baseurl }}/smart-on-fhir/dynamic-client-registration/)
+> or [UDAP Dynamic Client Registration]({{ site.baseurl }}/udap/dynamic-client-registration/).
+
 ---
 
 ## Protocol and Client Type
 
-`protocol:` and `client_type:` are keyword arguments to `Safire::Client.new`. They are independent of each other.
+`protocol:` and `client_type:` are keyword arguments to `Safire::Client.new`. `protocol:` selects the protocol implementation; `client_type:` selects the SMART authentication style and is not used for UDAP.
 
 ```ruby
 client = Safire::Client.new(config, protocol: :smart, client_type: :confidential_symmetric)
@@ -62,9 +71,91 @@ Selects the authorization protocol. Defaults to `:smart`.
 | Value | Status | Description |
 |-------|--------|-------------|
 | `:smart` | Implemented | SMART App Launch 2.2.0 |
-| `:udap` | Planned | UDAP Security 1.0 — accepted by the validator, raises `NotImplementedError` until implemented |
+| `:udap` | Partial | UDAP Security STU2 discovery and Dynamic Client Registration — `server_metadata` validates `signed_metadata`, supports optional `community:`, and accepts trust policy keywords (`trusted_anchors:`, `crls:`, `revocation_checker:`, `verify_chain:`); `register_client` and `cancel_registration` submit certificate-backed UDAP registration lifecycle requests; auth/token flows raise `NotImplementedError` |
+
+For UDAP, `client_type:` is not applicable. Passing any explicit value, either at initialization or through `client.client_type=`, raises `Safire::Errors::ConfigurationError`. Future UDAP authentication flows will use signed JWT assertions rather than SMART client types.
+
+```ruby
+client = Safire::Client.new(
+  { base_url: 'https://fhir.example.com' },
+  protocol: :udap
+)
+
+metadata = client.server_metadata(verify_chain: false) # development/test only
+```
+
+Production UDAP discovery must validate `signed_metadata` with trust anchors and an explicit revocation policy:
+
+```ruby
+ca_cert = OpenSSL::X509::Certificate.new(File.read('udap_ca.pem'))
+ca_crl  = OpenSSL::X509::CRL.new(File.read('udap_ca.crl'))
+
+metadata = client.server_metadata(
+  trusted_anchors: [ca_cert],
+  crls:            [ca_crl]
+)
+```
+
+Pass `community:` when the server participates in a specific UDAP trust community:
+
+```ruby
+metadata = client.server_metadata(
+  community:       'https://udap.example.org/community1',
+  trusted_anchors: [ca_cert],
+  crls:            [ca_crl]
+)
+```
+
+See [UDAP]({{ site.baseurl }}/udap/) for validation helpers, 404/204 discovery behavior, and the `verify_chain: false` development caveat.
+
+#### UDAP client signing credentials
 
-For UDAP, `client_type:` is ignored — UDAP clients always authenticate with a JWT signed by their private key.
+UDAP software statements use a client private key and a leaf-first,
+issuer-ordered X.509 certificate chain. Configure these reusable credentials on
+the client:
+
+```ruby
+config = Safire::ClientConfig.new(
+  base_url:   'https://fhir.example.com',
+  private_key: File.read(ENV.fetch('UDAP_CLIENT_PRIVATE_KEY_PATH')),
+  certificate_chain: [
+    File.read(ENV.fetch('UDAP_CLIENT_CERTIFICATE_PATH')),
+    File.read(ENV.fetch('UDAP_CLIENT_ISSUING_CA_PATH'))
+  ],
+  jwt_algorithm: 'RS256'
+)
+
+client = Safire::Client.new(config, protocol: :udap)
+```
+
+`certificate_chain` accepts PEM strings or
+`OpenSSL::X509::Certificate` instances. The leaf certificate must be first, as
+required by the
+[UDAP Security STU2 JWT header profile](https://hl7.org/fhir/us/udap-security/STU2/general.html#jwt-headers).
+`ClientConfig` requires a non-empty collection, copies and freezes PEM strings,
+and snapshots certificate objects as DER. Accessing the chain returns fresh
+certificate objects, so subsequent caller mutations cannot alter the configured
+identity. Safire performs PEM parsing, private-key matching, validity checks,
+and URI SAN checks when a software statement is built.
+
+Configured credentials are intended to serve as defaults for UDAP Dynamic
+Client Registration, with per-call overrides for applications that select
+signing identities dynamically. UDAP discovery does not access these signing
+credentials.
+
+```ruby
+registration = client.register_client(
+  {
+    client_name: 'Example Backend Service',
+    contacts: ['mailto:security@example.com'],
+    grant_types: ['client_credentials'],
+    scope: 'system/Patient.rs'
+  },
+  client_uri:      'https://client.example.com',
+  trusted_anchors: [udap_ca],
+  crls:            [udap_crl]
+)
+```
 
 ### Client Type
 
@@ -113,11 +204,15 @@ For a decision guide on which workflow to use, see [SMART App Launch — Choosin
 
 ## URI Validation
 
-All URI parameters are validated at initialization. Safire raises `Safire::Errors::ConfigurationError` for any violation:
+All URI attributes supplied through `ClientConfig` are validated at
+initialization. Per-call values, such as UDAP registration metadata, are
+validated by the operation-specific value object or protocol flow. Safire
+raises `Safire::Errors::ConfigurationError` for invalid configuration URIs:
 
 - URIs must be well-formed (scheme + host required)
-- URIs must use `https` — required by SMART App Launch 2.2.0
-- **Exception:** `http` is permitted for `localhost` and `127.0.0.1` (local development only)
+- URIs must use `https` — required for SMART App Launch and UDAP discovery
+- **Development exception:** `http` loopback URIs (`localhost` and `127.0.0.1`)
+  are permitted only when `allow_insecure_localhost: true` is configured
 
 The following attributes are validated:
 
@@ -132,17 +227,36 @@ The following attributes are validated:
 
 If you need to bypass discovery and provide endpoints directly, set `authorization_endpoint` and `token_endpoint` in your config. Safire will use them as-is instead of fetching `/.well-known/smart-configuration`.
 
+For a local development server without TLS, opt in deliberately:
+
+```ruby
+config = Safire::ClientConfig.new(
+  base_url: 'http://localhost:3000/fhir',
+  redirect_uri: 'http://localhost:3000/callback',
+  allow_insecure_localhost: ENV['APP_ENV'] == 'development'
+)
+```
+
+Safire does not infer your framework environment. Leave the default `false` in
+production.
+
+UDAP discovery always uses the FHIR `base_url` and the `/.well-known/udap` endpoint. UDAP endpoint values are taken from discovered, signed metadata rather than from SMART endpoint overrides.
+
 ---
 
 ## Credential Protection
 
-`ClientConfig` prevents `client_secret` and `private_key` from leaking in logs or REPL output.
+`ClientConfig` prevents `client_secret`, `private_key`, and
+`certificate_chain` from leaking in logs or REPL output. The certificate chain
+is masked even though certificates are public because the full chain can be
+large and identifies the client's operational signing identity.
 
 `#to_hash` replaces sensitive fields with `'[FILTERED]'`:
 
 ```ruby
-config.to_hash[:client_secret]  # => "[FILTERED]"
-config.to_hash[:base_url]       # => "https://fhir.example.com"
+config.to_hash[:client_secret]      # => "[FILTERED]"
+config.to_hash[:certificate_chain]  # => "[FILTERED]"
+config.to_hash[:base_url]           # => "https://fhir.example.com"
 ```
 
 `#inspect` is overridden to mask sensitive fields and omit `nil` attributes, so REPL sessions and error messages never expose credentials:
@@ -157,4 +271,6 @@ config.inspect
 ## Next Steps
 
 - [Logging]({{ site.baseurl }}/configuration/logging/) — configure Safire's logger and HTTP request logging
-- [SMART App Launch Workflows]({{ site.baseurl }}/smart-on-fhir/) — step-by-step authorization flow guides
+- [UDAP]({{ site.baseurl }}/udap/) — discover UDAP metadata and register certificate-backed clients
+- [SMART Dynamic Client Registration]({{ site.baseurl }}/smart-on-fhir/dynamic-client-registration/) — obtain a `client_id` at runtime using RFC 7591
+- [SMART App Launch Workflows]({{ site.baseurl }}/smart-on-fhir/) — step-by-step authorization flow guides

data/docs/configuration/index.md

@@ -29,7 +29,7 @@ flowchart TD
     A -->|"resolves config"| B
     A -->|"validates protocol + client_type"| C
     C -->|":smart (default)"| D
-    C -->|":udap (planned)"| G["Protocols::Udap\n(future)"]
+    C -->|":udap"| G["Protocols::Udap\n— discovery implemented\n— DCR implemented\n— auth flows planned"]
     D -->|"lazily fetches"| E
     E -->|"HTTP"| F
 ```
@@ -41,19 +41,23 @@ flowchart TD
 | Parameter | Type | Required | Default | Description |
 |-----------|------|----------|---------|-------------|
 | `base_url` | String | Yes | — | FHIR server base URL |
-| `client_id` | String | Yes | — | OAuth2 client identifier |
-| `redirect_uri` | String | Yes | — | Registered callback URL |
+| `client_id` | String | No | — | OAuth2 client identifier — required by all authorization flows; validated at call time, not at construction |
+| `redirect_uri` | String | No | — | Registered callback URL — required for App Launch flows; not used in Backend Services |
 | `protocol:` | Symbol | No | `:smart` | Authorization protocol — `:smart` or `:udap` |
-| `client_type:` | Symbol | No | `:public` | SMART client type — `:public`, `:confidential_symmetric`, or `:confidential_asymmetric` |
+| `client_type:` | Symbol | No | `nil` (→ `:public` for SMART) | SMART client type — `:public`, `:confidential_symmetric`, or `:confidential_asymmetric`; not applicable for `:udap` (any explicit value raises `ConfigurationError`) |
 | `client_secret` | String | No | — | Required for `:confidential_symmetric` |
-| `private_key` | OpenSSL::PKey / String | No | — | RSA/EC private key; required for `:confidential_asymmetric` |
+| `private_key` | OpenSSL::PKey / String | No | — | RSA/EC private key; used by SMART asymmetric clients and as the UDAP client signing key |
+| `certificate_chain` | Array of PEM strings / OpenSSL::X509::Certificate | No | — | Non-empty, leaf-first, issuer-ordered client certificate chain for UDAP software-statement signing |
 | `kid` | String | No | — | Key ID matching the public key registered with the server |
-| `jwt_algorithm` | String | No | auto | `RS384` or `ES384`; auto-detected from key type |
-| `jwks_uri` | String | No | — | URL to client's public JWKS, included as `jku` in JWT header |
+| `jwt_algorithm` | String | No | auto | SMART: `RS384` or `ES384`; UDAP registration: `RS256`, `RS384`, `ES256`, or `ES384`, constrained by the key and server metadata |
+| `jwks_uri` | String | No | — | SMART-only URL to the client's public JWKS, included as `jku` in SMART JWT assertions |
 | `scopes` | Array | No | — | Default scopes for authorization requests |
 | `authorization_endpoint` | String | No | — | Override the discovered authorization endpoint |
 | `token_endpoint` | String | No | — | Override the discovered token endpoint |
 
+`certificate_chain` and the UDAP algorithm values are used by
+`Safire::Client#register_client` when `protocol: :udap`.
+
 ## In This Section
 
 - [Client Setup]({{ site.baseurl }}/configuration/client-setup/) — creating a client, protocol and client type selection, URI rules, and credential protection

data/docs/index.md

@@ -3,7 +3,7 @@ layout: default
 title: Home
 nav_order: 1
 permalink: /
-description: "Safire is a Ruby gem implementing SMART App Launch 2.2.0 and UDAP Security protocols for healthcare client applications, with full support for OAuth 2.0 authorization against HL7 FHIR servers."
+description: "Safire implements SMART App Launch 2.2.0 plus UDAP Security STU2 discovery and Dynamic Client Registration for Ruby clients."
 ---
 
 # Safire Documentation
@@ -11,7 +11,7 @@ description: "Safire is a Ruby gem implementing SMART App Launch 2.2.0 and UDAP
 [![Gem Version](https://badge.fury.io/rb/safire.svg)](https://badge.fury.io/rb/safire)
 [![CI](https://github.com/vanessuniq/safire/workflows/CI/badge.svg)](https://github.com/vanessuniq/safire/actions)
 
-A lean Ruby gem implementing **[SMART App Launch](https://hl7.org/fhir/smart-app-launch/)** and **[UDAP](https://hl7.org/fhir/us/udap-security/)** protocols for clients.
+A lean Ruby gem implementing **[SMART App Launch](https://hl7.org/fhir/smart-app-launch/)** flows and **[UDAP Security STU2 / v2.0.0](https://hl7.org/fhir/us/udap-security/STU2/index.html)** discovery and Dynamic Client Registration for clients.
 
 ## Quick Navigation
 
@@ -20,7 +20,7 @@ A lean Ruby gem implementing **[SMART App Launch](https://hl7.org/fhir/smart-app
 | [Getting Started]({{ site.baseurl }}/installation/) | Install Safire and quick start guide |
 | [Configuration]({{ site.baseurl }}/configuration/) | All configuration options and parameters |
 | [SMART]({{ site.baseurl }}/smart-on-fhir/) | App Launch (Public, Confidential Symmetric, Confidential Asymmetric) and Backend Services |
-| [UDAP]({{ site.baseurl }}/udap/) | UDAP protocol overview and planned support |
+| [UDAP]({{ site.baseurl }}/udap/) | UDAP Security discovery plus certificate-backed Dynamic Client Registration |
 | [Security Guide]({{ site.baseurl }}/security/) | HTTPS, credential protection, token storage, key rotation |
 | [Advanced Examples]({{ site.baseurl }}/advanced/) | Caching, multi-server, token management, complete Rails integration |
 | [Troubleshooting]({{ site.baseurl }}/troubleshooting/) | Common issues and solutions |
@@ -37,9 +37,15 @@ A lean Ruby gem implementing **[SMART App Launch](https://hl7.org/fhir/smart-app
 - POST-Based Authorization
 - Backend Services (client_credentials grant, JWT assertion, no user interaction or PKCE)
 
-### UDAP
+### UDAP Security (STU2)
 
-> Planned. See [ROADMAP.md](https://github.com/vanessuniq/safire/blob/main/ROADMAP.md) for details (coming soon).
+- Discovery (`/.well-known/udap`) with optional community scoping
+- Dynamic Client Registration metadata validation and normalization
+- X.509-backed software-statement signing for registration, modification, and cancellation
+
+JWT assertion authentication and Tiered OAuth remain planned. See
+[ROADMAP.md](https://github.com/vanessuniq/safire/blob/main/ROADMAP.md) for
+details.
 
 ## Demo Application
 
@@ -49,7 +55,8 @@ A Sinatra-based demo app is included to help you explore Safire's features:
 bin/demo
 ```
 
-Visit http://localhost:4567 to test SMART discovery, authorization flows, token management, and backend services token requests.
+Visit http://localhost:4567 to test SMART registration and authorization flows,
+UDAP signed metadata discovery, and the UDAP registration lifecycle.
 
 See [`examples/sinatra_app/README.md`](https://github.com/vanessuniq/safire/tree/main/examples/sinatra_app) for details.
 

data/docs/installation.md

@@ -2,7 +2,8 @@
 layout: default
 title: Installation
 nav_order: 2
-description: "How to install the Safire Ruby gem and get started with SMART App Launch and UDAP authorization in your healthcare application."
+permalink: /installation/
+description: "How to install the Safire Ruby gem and get started with SMART App Launch and UDAP in your healthcare application."
 ---
 
 # Installation
@@ -19,7 +20,7 @@ description: "How to install the Safire Ruby gem and get started with SMART App
 
 ## Install
 
-**Requirements:** Ruby ≥ 4.0.2. OpenSSL is bundled with Ruby — no separate install needed.
+**Requirements:** Ruby ≥ 3.2. OpenSSL is bundled with Ruby — no separate install needed.
 
 Add to your Gemfile:
 

data/docs/security.md

@@ -21,7 +21,9 @@ This guide covers security requirements and best practices for every Safire inte
 
 ## HTTPS and Redirect URI Rules
 
-All production FHIR integrations must use HTTPS. Safire enforces this at configuration time — HTTP redirect URIs are rejected in non-localhost environments.
+All production FHIR integrations must use HTTPS. Safire enforces this at
+configuration time — HTTP URIs are rejected unless the caller explicitly opts
+into the local-development loopback exception.
 
 ```ruby
 # config/environments/production.rb
@@ -42,11 +44,15 @@ config = Safire::ClientConfig.new(
 )
 ```
 
-Localhost is permitted during development:
+Localhost HTTP is permitted only when the application enables it deliberately:
 
 ```ruby
 # ✅ Allowed for local development only
-redirect_uri: 'http://localhost:3000/auth/callback'
+config = Safire::ClientConfig.new(
+  base_url: 'http://localhost:3000/fhir',
+  redirect_uri: 'http://localhost:3000/auth/callback',
+  allow_insecure_localhost: ENV['APP_ENV'] == 'development'
+)
 ```
 
 ---
@@ -93,7 +99,7 @@ def fetch_client_secret
 end
 ```
 
-### Private Keys (Confidential Asymmetric)
+### Private Keys and Client Certificates
 
 ```ruby
 # ❌ NEVER: render or log the key
@@ -124,7 +130,8 @@ def fetch_private_key
 end
 ```
 
-Use strong keys:
+For SMART confidential-asymmetric flows, use strong keys compatible with the
+SMART signing algorithms:
 
 ```ruby
 # RSA: minimum 2048-bit, 4096-bit recommended
@@ -137,6 +144,38 @@ key = OpenSSL::PKey::EC.generate('secp384r1')
 {: .note }
 > Safire automatically masks `client_secret` and `private_key` in `inspect` output and error messages, so they will not appear in Rails logs even if a `ClientConfig` object is accidentally logged.
 
+UDAP Dynamic Client Registration additionally requires a leaf-first client
+certificate chain. The certificates contain public material, but they identify
+the client's operational signing identity and can be large, so Safire masks
+`certificate_chain` in `ClientConfig#inspect` and `#to_hash` as well.
+
+```ruby
+udap_client = Safire::Client.new(
+  {
+    base_url: 'https://fhir.example.com',
+    private_key: Rails.application.credentials.udap[:private_key_pem],
+    certificate_chain: [
+      File.read(ENV.fetch('UDAP_CLIENT_CERTIFICATE_PATH')),
+      File.read(ENV.fetch('UDAP_CLIENT_ISSUING_CA_PATH'))
+    ]
+  },
+  protocol: :udap
+)
+```
+
+Keep the two UDAP trust directions separate:
+
+- `private_key` and `certificate_chain` identify the client and sign
+  registration software statements.
+- `trusted_anchors`, `crls`, and `revocation_checker` validate the server's
+  discovery `signed_metadata`.
+
+Never use `verify_chain: false` or `allow_insecure_localhost: true` in
+production. The generated credentials and self-declaration JWTs in the
+unbundled Sinatra demo are development fixtures, not production trust material.
+See [UDAP Dynamic Client Registration]({% link udap/dynamic-client-registration/index.md %})
+for the complete trust model.
+
 ---
 
 ## Token and Session Security

data/docs/smart-on-fhir/backend-services/index.md

@@ -2,7 +2,7 @@
 layout: default
 title: Backend Services Workflow
 parent: SMART
-nav_order: 6
+nav_order: 7
 has_children: true
 permalink: /smart-on-fhir/backend-services/
 ---
@@ -56,7 +56,7 @@ Suitable for:
 
 ### Client Registration
 
-Before making any token requests, the client **SHALL** register with the authorization server following the [confidential asymmetric client registration](https://hl7.org/fhir/smart-app-launch/client-confidential-asymmetric.html#registering-a-client-communicating-public-keys) steps defined in the SMART App Launch specification. Registration communicates the client's public key(s) to the server, either via a JWKS URI or by uploading the JWKS directly.
+Before making any token requests, the client **SHALL** register with the authorization server following the [confidential asymmetric client registration](https://hl7.org/fhir/smart-app-launch/client-confidential-asymmetric.html#registering-a-client-communicating-public-keys) steps defined in the SMART App Launch specification. Registration communicates the client's public key(s) to the server, either via a JWKS URI or by uploading the JWKS directly. If the server supports RFC 7591, you can automate this step with Safire's `register_client` — see the [Dynamic Client Registration]({% link smart-on-fhir/dynamic-client-registration/index.md %}) guide.
 
 ### Key Pair and JWKS
 

data/docs/smart-on-fhir/backend-services/token-request.md

@@ -117,7 +117,7 @@ end
 begin
   token_data = client.request_backend_token
 rescue Safire::Errors::ConfigurationError => e
-  # private_key or kid missing from config and not passed at call time
+  # client_id, private_key, or kid missing — only private_key and kid can be overridden at call time
   Rails.logger.error("Backend services misconfigured: #{e.message}")
   raise
 rescue Safire::Errors::TokenError => e

data/docs/smart-on-fhir/confidential-asymmetric/index.md

@@ -2,7 +2,7 @@
 layout: default
 title: Confidential Asymmetric Client Workflow
 parent: SMART
-nav_order: 4
+nav_order: 5
 has_children: true
 permalink: /smart-on-fhir/confidential-asymmetric/
 ---
@@ -50,7 +50,7 @@ Suitable for:
 
 ## Prerequisites: Keys, JWKS, and Algorithm
 
-Before writing any flow code, you need a key pair, a key ID, and a way for the authorization server to verify your public key.
+Before writing any flow code, you need a key pair, a key ID, and a way for the authorization server to verify your public key. If the server supports RFC 7591, you can register dynamically using Safire's `register_client` — see the [Dynamic Client Registration]({% link smart-on-fhir/dynamic-client-registration/index.md %}) guide.
 
 ### Generating a Key Pair