safire 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9d2b84cc65eff523a4f1a8c86c5c2fe4f2089917062c115a12fb840e52369b4
-  data.tar.gz: 0f9cb348d913947546dff15f2d5d7a7904ca62dfdbce01dd8117598811ce5ec9
+  metadata.gz: dc7c5bf60b5d43365009f5073aae66d535f8e5345825f8ca08b638fb26587417
+  data.tar.gz: f47a4a2c4a84eefa8427e05a59d9e5e2cfca4adbce2a989f43cd53ead47e42bf
 SHA512:
-  metadata.gz: 955b05bf392bebc9202d4b4c623e7223a398a969e72a2ed399bf0d25b57436cf3b2bbc086c3cdc2902f22742c36139089ec59d0389f4708185920746575134b3
-  data.tar.gz: 146ef00d7041a656c401e580e24cd309901b28a9b0584b37074f7067a2c76fe2f6548369feaa7692940af3aafc6fd3c36d045623e835b0bfdb33c0b468350d07
+  metadata.gz: 625c96ea6424f41590d5396fb9d455ec0d89477474f484cbda236ec55ef13aed76d756ce88e014f76c1556ee8fa8e6e9d92a5a37743af2279e30c59456d74a58
+  data.tar.gz: 8c572a8974dfabdad87fd9d672013ca9bf64276a604db1492d11d6ad19e0351b30ecc2485b9262a366e3fce21af8eff656e2d0060077295c1b1127d6315c5ae2

data/.claude/skills/release-safire/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: release-safire
+description: Run the full Safire gem release workflow
+argument-hint: Optional target version (e.g. 0.3.0); omit to auto-determine from CHANGELOG
+---
+
+# Safire Release Workflow
+
+You are guiding the user through a complete Safire gem release. Follow each phase in order. **Never modify files or run commands without explicit user approval.** All commits must use `-s` (Signed-off-by) and one-line subjects.
+
+## Context
+
+Before proceeding, gather context by reading these files directly (do not shell out):
+- Read `lib/safire/version.rb` to determine the current version
+- Read `CHANGELOG.md` to find the `## [Unreleased]` section and its entries
+- Run `git branch --show-current` to confirm the current branch
+- Run `git status --short` to check for any uncommitted changes
+
+---
+
+## Phase 1: Determine Target Version
+
+Target version argument: $ARGUMENTS
+
+If `$ARGUMENTS` is blank, analyze the [Unreleased] CHANGELOG section and recommend a version bump:
+- **PATCH** (X.Y.Z+1): bug fixes only
+- **MINOR** (X.Y+1.0): new backward-compatible features
+- **MAJOR** (X+1.0.0): breaking changes
+
+Present your recommendation with reasoning. Ask the user to confirm or provide a different version before proceeding.
+
+---
+
+## Phase 2: Pre-Release Checks
+
+Present this checklist and ask the user to approve running all checks before proceeding:
+
+1. `bundle exec rspec` — all tests must pass
+2. `bundle exec rubocop` — zero offenses
+3. `bundle exec bundler-audit check --update` — no known vulnerabilities
+4. `cd docs && bundle exec jekyll build` — docs must build clean
+
+Run each check sequentially and report results. If any check fails, stop and clearly describe what needs to be fixed. Do not proceed to Phase 3 until all checks pass.
+
+---
+
+## Phase 3: Create Release Branch
+
+Ask the user to approve creating the release branch, then run:
+
+```
+git checkout main
+git pull origin main
+git checkout -b release-X.Y.Z
+```
+
+Replace `X.Y.Z` with the confirmed target version.
+
+---
+
+## Phase 4: Update CHANGELOG.md (docs commit)
+
+Show the user the exact diff you will make:
+- Rename `## [Unreleased]` → `## [X.Y.Z] - YYYY-MM-DD` (use today's date)
+- Add a fresh empty `## [Unreleased]` section above the new versioned entry
+
+Wait for approval, then edit `CHANGELOG.md`.
+
+After editing, ask the user to approve this commit:
+```
+git add CHANGELOG.md
+git commit -s -m "Update CHANGELOG for vX.Y.Z"
+```
+
+Stage `CHANGELOG.md` only — no other files.
+
+---
+
+## Phase 5: Bump Version, Update Gemfile.lock and ROADMAP (release commit)
+
+Show the user the exact change to `lib/safire/version.rb`:
+```ruby
+VERSION = 'X.Y.Z'.freeze
+```
+
+Wait for approval, then edit the file and run `bundle install` to regenerate `Gemfile.lock`.
+
+Update the `Latest Published Release` in the Roadmap.md file
+
+Ask the user to approve this commit:
+```
+git add lib/safire/version.rb Gemfile.lock ROADMAP.md
+git commit -s -m "Bump version to X.Y.Z"
+```
+
+Stage `lib/safire/version.rb`, `Gemfile.lock`, and `ROADMAP.md` only — no other files.
+
+---
+
+## Phase 6: Local Gem Verification
+
+Ask the user to approve running local verification (no files will be committed):
+
+```bash
+gem build safire.gemspec
+gem install ./safire-X.Y.Z.gem
+ruby -e "require 'safire'; puts Safire::VERSION"
+rm safire-X.Y.Z.gem
+```
+
+The `ruby -e` line must print `X.Y.Z`. If it does not, stop and report the issue. Never commit the `.gem` file.
+
+---
+
+## Phase 7: Push Release Branch
+
+Ask the user to approve:
+```
+git push -u origin release-X.Y.Z
+```
+
+---
+
+## Phase 8: Open Release PR
+
+Show the proposed PR and ask for approval before running `gh pr create`:
+
+- **Title:** `Release vX.Y.Z`
+- **Body:** the full CHANGELOG entry for this version (the `## [X.Y.Z] - YYYY-MM-DD` block)
+
+---
+
+## Phase 9: Post-Merge Instructions
+
+After the PR is created, tell the user the remaining manual steps:
+
+1. **Merge the PR** once CI passes and it is approved.
+2. **Create a GitHub Release** after merge:
+   - Tag: `vX.Y.Z` on `main`
+   - Title: `Safire vX.Y.Z`
+   - Notes: the CHANGELOG entry for this version
+3. **Publishing is automated** — `.github/workflows/publish-gem.yml` triggers on release creation.
+4. **Verify** once published: `gem info safire -r`
+
+---
+
+## Rules (never violate)
+
+- All commits use `-s`; subjects are one-line only
+- Two-commit structure on the release branch: docs commit (CHANGELOG) then release commit (version.rb + Gemfile.lock + ROADMAP.md)
+- Never commit a `.gem` file
+- Separate doc changes from code changes into distinct commits
+- Always get explicit user approval before modifying files or running commands

data/.rubocop.yml

@@ -2,7 +2,7 @@ plugins:
   - rubocop-rspec
 
 AllCops:
-  TargetRubyVersion: 4.0
+  TargetRubyVersion: 3.2
   NewCops: enable
   Exclude:
     - 'vendor/**/*'
@@ -32,6 +32,10 @@ Metrics/BlockLength:
     - 'spec/**/*'
     - '*.gemspec'
 
+Metrics/AbcSize:
+  Exclude:
+    - 'spec/**/*'
+
 Metrics/ParameterLists:
   CountKeywordArgs: false
 
@@ -51,6 +55,12 @@ RSpec/MultipleMemoizedHelpers:
 RSpec/NestedGroups:
   Enabled: false
 
+RSpec/SpecFilePathFormat:
+  CustomTransform:
+    OAuthResponseHandling: oauth_response_handling
+    RuboCop: rubocop
+    RSpec: rspec
+
 # Integration tests describe workflows, not classes
 RSpec/DescribeClass:
   Exclude:

data/.tool-versions

@@ -1 +1 @@
-ruby 4.0.2
+ruby 4.0.6

data/CHANGELOG.md

@@ -1,12 +1,118 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
+All notable changes to the packaged Safire gem will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-08-07
+
+### Added
+
+- `Safire::Client#register_client` and `Safire::Client#cancel_registration` now
+  support the UDAP Security STU2 Dynamic Client Registration lifecycle when
+  initialized with `protocol: :udap`. Safire performs discovery-bound
+  registration against authoritative signed endpoints, checks structural DCR
+  capability, posts the fixed UDAP envelope with optional certification or
+  endorsement JWTs, accepts new-registration `201` and update-style `200`
+  responses with a valid `client_id`, and confirms cancellation through a
+  successful response containing a valid `client_id` and an empty `grant_types`
+  array. OAuth-style failures preserve UDAP error codes such as
+  `invalid_software_statement` and `unapproved_software_statement`.
+- `Safire::Protocols::UdapRegistrationMetadata` validates and normalizes
+  caller-controlled UDAP Security STU2 registration and cancellation metadata
+  before software-statement signing. It enforces exact grant shapes, HTTPS
+  redirect and logo URIs, required `mailto:` contact data, protocol-owned
+  fields, JSON-compatible extensions, and immutable canonical output. An
+  explicit `allow_insecure_localhost: true` option permits development-only
+  HTTP loopback URIs without allowing remote HTTP. Registration software
+  statements use minimal `alg`/`x5c` headers, exact `iss`/`sub`/`aud` claims, a
+  five-minute lifetime, fresh `jti`, key-compatible algorithm negotiation, and
+  local certificate/key/SAN checks. `ClientConfig` accepts and masks the
+  non-empty, leaf-first `certificate_chain` of PEM strings or
+  `OpenSSL::X509::Certificate` instances required for UDAP registration.
+- UDAP Security STU2 discovery is now available with
+  `Safire::Client.new(..., protocol: :udap).server_metadata`. Safire fetches
+  `/.well-known/udap`, supports community-scoped discovery via `community:`, accepts
+  `trusted_anchors:`, `crls:`, `revocation_checker:`, and `verify_chain:` for
+  signed metadata trust validation (`verify_chain: false` is for development/test
+  only), parses metadata into `Safire::Protocols::UdapMetadata`, and raises
+  `DiscoveryError` for HTTP errors, 204 responses, a response body that is not a
+  JSON object, or failed signed metadata validation.
+- `Safire::Protocols::UdapMetadata` provides STU2 structural validation and helper
+  predicates for advertised UDAP profiles and capabilities.
+- `Safire::Protocols::UdapSignedMetadataValidator` validates the `signed_metadata`
+  JWT per UDAP Security STU2, including RS256, `x5c`, JWT signature, certificate
+  chain and revocation checks, issuer/subject/time claims, `jti`, and signed
+  endpoint claims.
+- UDAP signed endpoint claims are merged over unsigned discovery metadata after
+  successful validation. Cached UDAP metadata is revalidated before reuse and
+  refetched if the signed JWT, certificate chain, or revocation policy no longer
+  validates.
+- `UdapMetadata#signed_metadata_valid?` allows explicit cryptographic re-validation
+  against caller-provided trust anchors and revocation material.
+- `Safire::Errors::DiscoveryError` accepts a `label:` keyword argument (default:
+  `'SMART configuration'`) and exposes it as a readable attribute so callers can
+  identify which protocol's discovery failed.
+
+### Breaking Changes
+
+- SMART and shared HTTP URI handling now require an explicit
+  `allow_insecure_localhost: true` opt-in before accepting HTTP loopback URIs
+  or redirects. This aligns SMART local-development behavior with UDAP DCR
+  metadata validation while keeping production defaults HTTPS-only.
+
+### Changed
+
+- SMART Dynamic Client Registration now requires successful RFC 7591 responses
+  to contain a non-blank string `client_id`. Malformed identifiers that were
+  previously accepted now raise `Safire::Errors::RegistrationError`; valid
+  registration responses are unchanged.
+- Ruby requirement relaxed from `>= 4.0.4` to `>= 3.2` to support Rails 7.1+ apps still
+  running on Ruby 3.x. The minimum is 3.2 because the gem uses anonymous keyword splat
+  forwarding (`**` without a name), which was introduced in Ruby 3.2.
+- ActiveSupport requirement relaxed from `~> 8.0.0` to `>= 7.1, < 9`, resolving the
+  bundler conflict that prevented the gem from being used in Rails 8.1 apps or any app
+  pinning ActiveSupport 8.1.x.
+- `Safire::Client` now raises `ConfigurationError` when `client_type:` is passed explicitly for
+  `protocol: :udap`, both at construction and via `client_type=`; previously the value was
+  ignored silently.
+
+## [0.3.0] - 2026-04-15
+
+### Added
+
+- `Safire::Client#register_client` implements the OAuth 2.0 Dynamic Client Registration
+  Protocol (RFC 7591): POSTs client metadata to the server's registration endpoint and
+  returns the response as a Hash containing at minimum a `client_id`
+  - Endpoint is resolved from SMART discovery (`registration_endpoint` field) when not
+    supplied explicitly via the `registration_endpoint:` keyword argument; HTTPS is
+    enforced on the endpoint regardless of source
+  - Supports an optional initial access token via the `authorization:` keyword argument
+    (full `Authorization` header value including token type prefix)
+  - Raises `Safire::Errors::DiscoveryError` when no registration endpoint is available,
+    `Safire::Errors::RegistrationError` on server error or a 2xx response missing
+    `client_id`, and `Safire::Errors::NetworkError` on transport failure
+- `Safire::Errors::RegistrationError` — new error class for Dynamic Client Registration
+  failures; inherits from `Safire::Errors::OAuthError` with `status`, `error_code`,
+  `error_description`, and `received_fields` attributes
+- `Safire::Errors::OAuthError` — new shared base class for `RegistrationError`,
+  `TokenError`, and `AuthError`; provides `status`, `error_code`, and
+  `error_description` attributes and can be used as a single rescue point for any
+  server-side OAuth protocol error
+
+### Changed
+
+- `client_id` is now optional at `ClientConfig` and `Protocols::Smart` initialization;
+  all authorization flows (`authorization_url`, `request_access_token`, `refresh_token`,
+  `request_backend_token`) validate its presence at call time and raise
+  `Safire::Errors::ConfigurationError` if it is absent
+- `Protocols::Smart#token_endpoint` now raises `Safire::Errors::DiscoveryError` when
+  the discovery response does not include a `token_endpoint` field, rather than silently
+  passing `nil` to the HTTP client
+
 ## [0.2.0] - 2026-04-04
 
 ### Added

data/CONTRIBUTION.md

@@ -20,6 +20,9 @@ This project adheres to a [Code of Conduct](CODE_OF_CONDUCT.md). By participatin
 ## Getting Started
 
 1. Fork the repository on GitHub
+
+   Note: Codex automated review currently runs only for same-repository branches because it requires repository secrets and reviews untrusted PR content. Fork-based PRs are still welcome, but maintainers will review them manually.
+
 2. Clone your fork locally:
    ```bash
    git clone https://github.com/YOUR_USERNAME/safire.git
@@ -34,7 +37,7 @@ This project adheres to a [Code of Conduct](CODE_OF_CONDUCT.md). By participatin
 
 ### Requirements
 
-- Ruby 4.0.2 or later
+- Ruby 3.2 or later
 - Bundler
 
 ### Setup
@@ -231,6 +234,8 @@ end
 
 2. Open a Pull Request against `main`
 
+   Codex automated review only runs for same-repository branches. Pull requests from forks will receive maintainer review instead.
+
 3. Fill out the PR template with:
    - Summary of changes
    - Related issues

data/Gemfile

@@ -1,7 +1,5 @@
 source 'https://rubygems.org'
 
-ruby '4.0.2'
-
 gemspec
 
 group :development, :test do
@@ -23,5 +21,6 @@ group :test do
   gem 'dotenv', '~> 3.0'
   gem 'simplecov', require: false
   gem 'simplecov-cobertura', require: false
+  gem 'sinatra', '~> 4.0'
   gem 'webmock', '~> 3.18'
 end

data/Gemfile.lock

@@ -1,8 +1,8 @@
 PATH
   remote: .
   specs:
-    safire (0.2.0)
-      activesupport (~> 8.0.0)
+    safire (0.4.0)
+      activesupport (>= 7.1, < 9)
       addressable (~> 2.8)
       faraday (~> 2.14)
       faraday-follow_redirects (~> 0.4)
@@ -11,7 +11,7 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (8.0.2.1)
+    activesupport (8.0.5)
       base64
       benchmark (>= 0.3)
       bigdecimal
@@ -24,20 +24,20 @@ GEM
       securerandom (>= 0.3)
       tzinfo (~> 2.0, >= 2.0.5)
       uri (>= 0.13.1)
-    addressable (2.8.9)
+    addressable (2.9.0)
       public_suffix (>= 2.0.2, < 8.0)
     ast (2.4.3)
     base64 (0.3.0)
-    benchmark (0.4.1)
-    bigdecimal (3.3.1)
+    benchmark (0.5.0)
+    bigdecimal (4.1.2)
     bundler-audit (0.9.3)
       bundler (>= 1.2.0)
       thor (~> 1.0)
     byebug (13.0.0)
       reline (>= 0.6.0)
     coderay (1.1.3)
-    concurrent-ruby (1.3.5)
-    connection_pool (2.5.4)
+    concurrent-ruby (1.3.7)
+    connection_pool (3.0.2)
     crack (1.0.1)
       bigdecimal
       rexml
@@ -46,39 +46,40 @@ GEM
       irb (~> 1.10)
       reline (>= 0.3.8)
     diff-lcs (1.6.2)
-    docile (1.4.1)
     dotenv (3.2.0)
     drb (2.2.3)
-    erb (5.0.3)
-    faraday (2.14.1)
+    erb (6.0.4)
+    faraday (2.14.3)
       faraday-net_http (>= 2.0, < 3.5)
       json
       logger
     faraday-follow_redirects (0.5.0)
       faraday (>= 1, < 3)
-    faraday-net_http (3.4.2)
+    faraday-net_http (3.4.4)
       net-http (~> 0.5)
     hashdiff (1.2.1)
-    i18n (1.14.7)
+    i18n (1.14.8)
       concurrent-ruby (~> 1.0)
     io-console (0.8.2)
     irb (1.15.3)
       pp (>= 0.6.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.19.2)
-    jwt (2.10.2)
+    json (2.21.2)
+    jwt (2.10.3)
       base64
-    language_server-protocol (3.17.0.5)
+    language_server-protocol (3.17.0.6)
     lint_roller (1.1.0)
     logger (1.7.0)
     method_source (1.1.0)
-    minitest (6.0.1)
+    minitest (6.0.6)
+      drb (~> 2.0)
       prism (~> 1.5)
+    mustermann (3.1.1)
     net-http (0.9.1)
       uri (>= 0.11.1)
-    parallel (1.27.0)
-    parser (3.3.10.2)
+    parallel (1.28.0)
+    parser (3.3.12.0)
       ast (~> 2.4.1)
       racc
     pp (0.6.3)
@@ -95,13 +96,21 @@ GEM
     psych (5.2.6)
       date
       stringio
-    public_suffix (6.0.2)
+    public_suffix (7.0.5)
     racc (1.8.1)
+    rack (3.2.6)
+    rack-protection (4.2.1)
+      base64 (>= 0.1.0)
+      logger (>= 1.6.0)
+      rack (>= 3.0.0, < 4)
+    rack-session (2.1.2)
+      base64 (>= 0.1.0)
+      rack (>= 3.0.0)
     rainbow (3.1.1)
     rdoc (6.14.2)
       erb
       psych (>= 4.0.0)
-    regexp_parser (2.11.3)
+    regexp_parser (2.12.0)
     reline (0.6.3)
       io-console (~> 0.5)
     rexml (3.4.4)
@@ -118,18 +127,18 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.6)
-    rubocop (1.86.0)
+    rubocop (1.89.0)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
-      parallel (~> 1.10)
+      parallel (>= 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
       rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.49.1)
+    rubocop-ast (1.50.0)
       parser (>= 3.3.7.2)
       prism (~> 1.7)
     rubocop-rspec (3.9.0)
@@ -137,18 +146,21 @@ GEM
       rubocop (~> 1.81)
     ruby-progressbar (1.13.0)
     securerandom (0.4.1)
-    simplecov (0.22.0)
-      docile (~> 1.1)
-      simplecov-html (~> 0.11)
-      simplecov_json_formatter (~> 0.1)
-    simplecov-cobertura (3.1.0)
+    simplecov (1.0.3)
+    simplecov-cobertura (4.0.0)
       rexml
-      simplecov (~> 0.19)
-    simplecov-html (0.13.2)
-    simplecov_json_formatter (0.1.4)
+      simplecov (~> 1.0)
+    sinatra (4.2.1)
+      logger (>= 1.6.0)
+      mustermann (~> 3.0)
+      rack (>= 3.0.0, < 4)
+      rack-protection (= 4.2.1)
+      rack-session (>= 2.0.0, < 3)
+      tilt (~> 2.0)
     stringio (3.1.9)
     thor (1.4.0)
-    timecop (0.9.10)
+    tilt (2.7.0)
+    timecop (0.9.11)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
     unicode-display_width (3.2.0)
@@ -159,7 +171,7 @@ GEM
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
-    yard (0.9.38)
+    yard (0.9.45)
 
 PLATFORMS
   ruby
@@ -177,12 +189,10 @@ DEPENDENCIES
   safire!
   simplecov
   simplecov-cobertura
+  sinatra (~> 4.0)
   timecop (~> 0.9)
   webmock (~> 3.18)
   yard (~> 0.9)
 
-RUBY VERSION
-   ruby 4.0.2p0
-
 BUNDLED WITH
    2.7.1

data/README.md

@@ -5,7 +5,7 @@
 [![Coverage](https://codecov.io/gh/vanessuniq/safire/branch/main/graph/badge.svg)](https://codecov.io/gh/vanessuniq/safire)
 [![Documentation](https://img.shields.io/badge/docs-yard-blue.svg)](https://vanessuniq.github.io/safire)
 
-Safire is a Ruby gem implementing the [SMART App Launch 2.2.0](https://hl7.org/fhir/smart-app-launch/) specification and the [UDAP Security](https://hl7.org/fhir/us/udap-security/) protocol for healthcare client applications. It handles OAuth 2.0 authorization against HL7 FHIR servers, covering PKCE, private key JWT assertions, and the Backend Services system-to-system flow, so you can focus on your application rather than protocol plumbing.
+Safire is a Ruby gem for healthcare client applications that implements [SMART App Launch 2.2.0](https://hl7.org/fhir/smart-app-launch/) and [UDAP Security STU2 / v2.0.0](https://hl7.org/fhir/us/udap-security/STU2/index.html) discovery plus certificate-backed Dynamic Client Registration. It handles SMART OAuth 2.0 authorization against HL7 FHIR servers, covering PKCE, private key JWT assertions, and the Backend Services system-to-system flow, so you can focus on your application rather than protocol plumbing.
 
 ---
 
@@ -13,6 +13,7 @@ Safire is a Ruby gem implementing the [SMART App Launch 2.2.0](https://hl7.org/f
 
 ### SMART App Launch (v2.2.0)
 
+- Dynamic Client Registration (RFC 7591): obtain a `client_id` at runtime by POSTing client metadata to the server's registration endpoint
 - Discovery (`/.well-known/smart-configuration`)
 - Public Client (PKCE)
 - Confidential Symmetric Client (`client_secret` + HTTP Basic Auth)
@@ -20,15 +21,69 @@ Safire is a Ruby gem implementing the [SMART App Launch 2.2.0](https://hl7.org/f
 - POST-Based Authorization
 - Backend Services (`client_credentials` grant, JWT assertion, no user interaction or PKCE; scope defaults to `system/*.rs`)
 
-### UDAP
+### UDAP Security (STU2)
 
-> Planned. See [ROADMAP.md](https://github.com/vanessuniq/safire/blob/main/ROADMAP.md) for details.
+Server metadata discovery is implemented. Pass `protocol: :udap` to fetch `/.well-known/udap`:
+
+```ruby
+client = Safire::Client.new(
+  { base_url: 'https://fhir.example.com' },
+  protocol: :udap
+)
+
+metadata = client.server_metadata(verify_chain: false) # development/test only
+# => #<Safire::Protocols::UdapMetadata ...>
+
+# Community-scoped discovery
+metadata = client.server_metadata(community: 'https://udap.example.org/community1', verify_chain: false)
+```
+
+Production UDAP discovery requires trust anchors plus an explicit certificate revocation policy
+(`crls:` or `revocation_checker:`). Use `verify_chain: false` only for development or tests.
+
+Dynamic Client Registration is implemented for certificate-backed UDAP clients:
+
+```ruby
+udap_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 = udap_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: [ca_cert],
+  crls:            [ca_crl]
+)
+
+cancellation = udap_client.cancel_registration(
+  {
+    client_name: 'Example Backend Service',
+    contacts: ['mailto:security@example.com'],
+    scope: 'system/Patient.rs'
+  },
+  client_uri:      'https://client.example.com',
+  trusted_anchors: [ca_cert],
+  crls:            [ca_crl]
+)
+```
+
+UDAP JWT client authentication and Tiered OAuth are planned. See [ROADMAP.md](https://github.com/vanessuniq/safire/blob/main/ROADMAP.md) for details.
 
 ---
 
 ## Installation
 
-Requires Ruby ≥ 4.0.2.
+Requires Ruby ≥ 3.2.
 
 ```ruby
 gem 'safire'
@@ -154,7 +209,7 @@ bin/demo
 # Visit http://localhost:4567
 ```
 
-Demonstrates SMART discovery, all authorization flows, token refresh, and backend services token requests. See [`examples/sinatra_app/README.md`](examples/sinatra_app/README.md) for details.
+Demonstrates SMART Dynamic Client Registration, SMART discovery, UDAP discovery with `signed_metadata` trust validation, UDAP Dynamic Client Registration and cancellation, all authorization flows, token refresh, and backend services token requests. See [`examples/sinatra_app/README.md`](examples/sinatra_app/README.md) for details.
 
 ---