safire 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9d2b84cc65eff523a4f1a8c86c5c2fe4f2089917062c115a12fb840e52369b4
-  data.tar.gz: 0f9cb348d913947546dff15f2d5d7a7904ca62dfdbce01dd8117598811ce5ec9
+  metadata.gz: e2907e363c56d115aedcc6b5bb0aa55a1780757a7a9fc8dfc3f8853262c4c926
+  data.tar.gz: 2cf29245a45cb4ad067418a1a23ad2c3bcddac91c3bb672a0b2b6901391af761
 SHA512:
-  metadata.gz: 955b05bf392bebc9202d4b4c623e7223a398a969e72a2ed399bf0d25b57436cf3b2bbc086c3cdc2902f22742c36139089ec59d0389f4708185920746575134b3
-  data.tar.gz: 146ef00d7041a656c401e580e24cd309901b28a9b0584b37074f7067a2c76fe2f6548369feaa7692940af3aafc6fd3c36d045623e835b0bfdb33c0b468350d07
+  metadata.gz: 814cf46717388979bd1a5e7a3666a30fcd1cdc19fd6eb4f71e30a0916d91993104bdf94566736390e3ec39f320eef1ec1bd1621afcacfc8c89b9de376522d038
+  data.tar.gz: 15dbfb7e5927ebbf91ae9aad6e2658f7f4cc9e42a6e0282267844c063e4693651a6c7348b6e71f24dfc5d75d525b5b0a3a0339e3888d9410c6c15babbbdf8944

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

@@ -0,0 +1,151 @@
+---
+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 and Update Gemfile.lock (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`.
+
+Ask the user to approve this commit:
+```
+git add lib/safire/version.rb Gemfile.lock
+git commit -s -m "Bump version to X.Y.Z"
+```
+
+Stage `lib/safire/version.rb` and `Gemfile.lock` 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)
+- 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/CHANGELOG.md

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    safire (0.2.0)
+    safire (0.3.0)
       activesupport (~> 8.0.0)
       addressable (~> 2.8)
       faraday (~> 2.14)
@@ -66,7 +66,7 @@ GEM
       pp (>= 0.6.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.19.2)
+    json (2.19.3)
     jwt (2.10.2)
       base64
     language_server-protocol (3.17.0.5)
@@ -78,7 +78,7 @@ GEM
     net-http (0.9.1)
       uri (>= 0.11.1)
     parallel (1.27.0)
-    parser (3.3.10.2)
+    parser (3.3.11.1)
       ast (~> 2.4.1)
       racc
     pp (0.6.3)
@@ -118,11 +118,11 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.6)
-    rubocop (1.86.0)
+    rubocop (1.86.1)
       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)
@@ -148,7 +148,7 @@ GEM
     simplecov_json_formatter (0.1.4)
     stringio (3.1.9)
     thor (1.4.0)
-    timecop (0.9.10)
+    timecop (0.9.11)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
     unicode-display_width (3.2.0)
@@ -159,7 +159,7 @@ GEM
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
-    yard (0.9.38)
+    yard (0.9.41)
 
 PLATFORMS
   ruby

data/README.md

@@ -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)
@@ -154,7 +155,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 Dynamic Client Registration, 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.
 
 ---
 

data/ROADMAP.md

@@ -1,6 +1,6 @@
 # Safire Roadmap
 
-## Current Release — v0.1.0
+## Current Release — v0.2.0
 
 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).
 
@@ -20,15 +20,12 @@ Feedback, bug reports, and pull requests are welcome via the [issue tracker](htt
 - **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
+- **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
 
 ---
 
 ## Planned Features
 
-### SMART App Launch
-
-- **Dynamic Client Registration** — programmatic client registration per [RFC 7591](https://www.rfc-editor.org/rfc/rfc7591)
-
 ### UDAP Security
 
 - **UDAP Discovery** — `/.well-known/udap` metadata fetch and validation

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

@@ -0,0 +1,80 @@
+---
+layout: default
+title: "ADR-009: OAuthError base class and ReceivesFields mixin for protocol error hierarchy"
+parent: Architecture Decision Records
+nav_order: 9
+---
+
+# ADR-009: OAuthError base class and ReceivesFields mixin for protocol error hierarchy
+
+**Status:** Accepted
+
+---
+
+## Context
+
+Three protocol operations can return OAuth2-style error responses: token exchange (`TokenError`), authorization failure (`AuthError`), and dynamic client registration (`RegistrationError`). All three carry the same RFC-defined fields — HTTP `status`, an OAuth2 `error` code, and an `error_description` string — and all three produce structured error messages from those fields.
+
+`TokenError` and `RegistrationError` have a second failure path: the server returns a 2xx response but omits the field the caller requires (`access_token` or `client_id`). In that case the error must report which fields were present in the response, without logging their values, to assist debugging without leaking data.
+
+Without a shared foundation, each error class would duplicate the constructor, the attribute readers, and the message-building logic.
+
+**Option A — Duplicate per class:** each error class independently defines `attr_reader :status, :error_code, :error_description`, its own constructor, and its own `build_message` method.
+
+**Option B — Extract a shared base:** introduce `OAuthError < Error` with a template-method design; each subclass overrides `operation_label` to supply the lead phrase of the error message. Extract a `ReceivesFields` mixin for the structural failure path (`received_fields` attribute + constructor forwarding), included only by the two classes that need it.
+
+---
+
+## Decision
+
+Option B — `OAuthError` as a shared base class with `ReceivesFields` as a private mixin.
+
+```ruby
+class OAuthError < Error
+  attr_reader :status, :error_code, :error_description
+
+  def initialize(status: nil, error_code: nil, error_description: nil)
+    @status = status; @error_code = error_code; @error_description = error_description
+    super(build_message)
+  end
+
+  private
+
+  def operation_label
+    raise NotImplementedError, "#{self.class} must define #operation_label"
+  end
+
+  def build_message
+    parts = [operation_label]
+    parts << "HTTP #{@status}" if @status
+    parts << @error_code       if @error_code
+    parts << @error_description if @error_description
+    parts.join(' — ')
+  end
+end
+
+module ReceivesFields
+  def self.included(base) = base.attr_reader :received_fields
+  def initialize(received_fields: nil, **) = (@received_fields = received_fields; super(**))
+end
+
+class TokenError        < OAuthError; include ReceivesFields; ... end
+class AuthError         < OAuthError; ...                          end
+class RegistrationError < OAuthError; include ReceivesFields; ... end
+```
+
+Each subclass defines only `operation_label` and, when needed, overrides `build_message` for the structural path.
+
+---
+
+## Consequences
+
+**Benefits:**
+- DRY: each concrete error class is a handful of lines; the shared attributes and message format are defined once
+- Consistent error messages across all three operations; callers and log parsers see the same structure
+- `ReceivesFields` is `@api private` — callers interact only with `TokenError` and `RegistrationError`; the mixin is an implementation detail
+- Adding a new OAuth-style error (e.g. for a future introspection endpoint) requires only a new subclass with `operation_label`
+
+**Trade-offs:**
+- The `operation_label` template method raises `NotImplementedError` at runtime if a subclass forgets to define it; a compile-time check is not possible in Ruby
+- `ReceivesFields` modifies the constructor via `super(**)` forwarding, which requires care when the inheritance chain has multiple `initialize` overrides

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

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

data/docs/adr/index.md

@@ -19,4 +19,6 @@ Architecture Decision Records (ADRs) document significant design decisions made
 | [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-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 |

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,6 +45,9 @@ config = Safire::ClientConfig.new(
 client = Safire::Client.new(config)
 ```
 
+{: .note }
+> `client_id` is the only authorization parameter validated at call time rather than at construction. `authorization_url`, `request_access_token`, `refresh_token`, and `request_backend_token` each raise `Safire::Errors::ConfigurationError` if `client_id` is absent when called. This means you can build a client without a `client_id` and call `register_client` to obtain one at runtime. See [Dynamic Client Registration]({{ site.baseurl }}/smart-on-fhir/dynamic-client-registration/) for details.
+
 ---
 
 ## Protocol and Client Type
@@ -157,4 +160,5 @@ config.inspect
 ## Next Steps
 
 - [Logging]({{ site.baseurl }}/configuration/logging/) — configure Safire's logger and HTTP request logging
+- [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

@@ -41,12 +41,12 @@ 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_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; required for `:confidential_asymmetric` and Backend Services |
 | `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 |

data/docs/installation.md

@@ -2,6 +2,7 @@
 layout: default
 title: Installation
 nav_order: 2
+permalink: /installation/
 description: "How to install the Safire Ruby gem and get started with SMART App Launch and UDAP authorization in your healthcare application."
 ---
 

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
 

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

@@ -2,7 +2,7 @@
 layout: default
 title: Confidential Symmetric Client Workflow
 parent: SMART
-nav_order: 3
+nav_order: 4
 has_children: true
 permalink: /smart-on-fhir/confidential-symmetric/
 ---

data/docs/smart-on-fhir/discovery/capability-checks.md

@@ -53,6 +53,10 @@ metadata.supports_openid_connect?
 metadata.supports_post_based_authorization?
 # => true if capabilities include "authorize-post"
 
+# Dynamic Client Registration (RFC 7591)
+metadata.supports_dynamic_registration?
+# => true if registration_endpoint is present in the server's SMART metadata
+
 # Backend Services (client_credentials grant, no user interaction)
 metadata.supports_backend_services?
 # => true if:
@@ -63,6 +67,9 @@ metadata.supports_backend_services?
 {: .note }
 > `supports_backend_services?` checks `grant_types_supported` rather than a capability flag — it combines a grant type check with `supports_asymmetric_auth?` because the SMART Backend Services flow always authenticates via JWT assertion (`private_key_jwt`).
 
+{: .note }
+> `supports_dynamic_registration?` checks only for the presence of `registration_endpoint` in the server's SMART metadata. SMART App Launch 2.2.0 defines no dedicated capability string for DCR, so the endpoint field is the sole signal.
+
 ---
 
 ## Flag-Only Checks (`*_capability?`)