safire 0.2.0 → 0.4.0

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?`)

data/docs/smart-on-fhir/dynamic-client-registration/index.md

@@ -0,0 +1,103 @@
+---
+layout: default
+title: Dynamic Client Registration
+parent: SMART
+nav_order: 2
+has_children: true
+permalink: /smart-on-fhir/dynamic-client-registration/
+description: "Register your Ruby application with a SMART authorization server at runtime using the OAuth 2.0 Dynamic Client Registration Protocol (RFC 7591). Safire handles endpoint discovery, metadata submission, and returns the assigned client_id and credentials."
+---
+
+# Dynamic Client Registration
+{: .no_toc }
+
+<div class="code-example" markdown="1">
+Obtain a `client_id` by registering your application with a SMART authorization server at runtime using the OAuth 2.0 Dynamic Client Registration Protocol (RFC 7591). Safire handles endpoint discovery and metadata submission through `Client#register_client`.
+</div>
+
+---
+
+## Overview
+
+Before your application can run any SMART authorization flow, it needs a `client_id`. This is a one-time, out-of-band setup step: the client presents its metadata to the authorization server, and the server issues credentials in return.
+
+The response always includes a `client_id`. For confidential symmetric clients, the server also issues a `client_secret`. For clients using asymmetric authentication (`private_key_jwt`), no secret is issued because the client authenticates with a signed JWT, but the client must include a `jwks_uri` or inline JWKS in its registration metadata so that the server can obtain the client's public keys for verifying those assertions.
+
+There are two ways to accomplish registration:
+
+- **Manual registration** — you register through the server's developer portal, email exchange, or administrative interface, and hard-code the assigned credentials into your configuration.
+- **Dynamic Client Registration (RFC 7591)** — your application POSTs its metadata to a registration endpoint at runtime and receives credentials in the response. No portal visit or manual coordination is required.
+
+SMART App Launch 2.2.0 does not mandate DCR. The specification states that "SMART does not specify a standards-based registration process, but we encourage EHR implementers to consider the OAuth 2.0 Dynamic Client Registration Protocol for an out-of-the-box solution." In practice, many servers support manual registration only, while others advertise a `registration_endpoint` in their SMART metadata and accept RFC 7591 requests. Safire implements DCR through [`Client#register_client`]({{ site.baseurl }}/api/Safire/Client.html).
+
+---
+
+## Where Registration Fits in the SMART Flow
+
+Client registration is always Step 1 in the SMART App Launch sequence. It is a one-time prerequisite that happens separately from the runtime authorization interaction.
+
+```
+1. Registration  — obtain credentials out-of-band (DCR or manual)
+2. Discovery     — fetch /.well-known/smart-configuration (lazy: on first auth call)
+3. Authorization — run the appropriate SMART App Launch or Backend Services flow
+```
+
+If you already hold a `client_id` from a prior registration, skip to the [Discovery]({% link smart-on-fhir/discovery/index.md %}) guide or directly to the authorization guide that matches your client type.
+
+---
+
+## When to Use DCR vs. Manual Registration
+
+| Situation | Recommended path |
+|-----------|-----------------|
+| Server advertises `registration_endpoint` in SMART metadata | DCR |
+| Automated deployment or multi-tenant provisioning | DCR |
+| Server requires administrator approval before issuing credentials | Manual |
+| No `registration_endpoint` in SMART metadata | Manual (or pass the endpoint explicitly to `register_client`) |
+| You already have a `client_id` | Skip registration entirely |
+
+---
+
+## How DCR Works
+
+```mermaid
+sequenceDiagram
+    participant App
+    participant Safire
+    participant AS as Authorization Server
+
+    Note over App,AS: One-time setup (out-of-band)
+
+    App->>Safire: Client.new(base_url:)
+
+    App->>Safire: register_client(metadata)
+    Safire->>AS: GET /.well-known/smart-configuration
+    AS-->>Safire: SmartMetadata (includes registration_endpoint)
+    Safire->>AS: POST /register<br/>Content-Type: application/json<br/>{ client_name, redirect_uris, grant_types,<br/>  token_endpoint_auth_method, jwks_uri, ... }
+    AS-->>Safire: { client_id: "dyn_abc123",<br/>  client_secret: "..." (symmetric only), ... }
+    Safire-->>App: registration response Hash
+
+    Note over App: Store credentials durably
+
+    Note over App,AS: Runtime (per user session or scheduled job)
+
+    App->>Safire: Client.new(base_url:, client_id: "dyn_abc123", ...)
+    Note over App: Proceed with the appropriate authorization flow
+```
+
+---
+
+## Prerequisites
+
+- **Registration endpoint** — The authorization server must expose a `registration_endpoint` in its SMART configuration, or you must know the URL and supply it explicitly through the `registration_endpoint:` keyword argument.
+- **Initial access token** — Some servers protect the registration endpoint with a bearer token (RFC 7591 §3.1). If required, obtain this out-of-band from the server operator and pass it through the `authorization:` keyword argument.
+- **JWKS or JWKS URI** — If your client will use `private_key_jwt` authentication, you must include either a `jwks_uri` pointing to your public key endpoint or an inline `jwks` object in the registration metadata. The server uses these keys to verify your JWT assertions during token requests.
+- **Accurate redirect URIs** — The `redirect_uris` field must contain the exact URIs the server will accept during authorization callbacks.
+
+---
+
+## What's Next
+
+[Calling register_client]({% link smart-on-fhir/dynamic-client-registration/registration.md %}) covers assembling client metadata, choosing grant types and authentication methods, endpoint discovery, and passing an initial access token.
+
+[Registration Response]({% link smart-on-fhir/dynamic-client-registration/response.md %}) covers what the server returns, how to persist credentials, how to build a runtime `Safire::Client` from the response, and error handling.

data/docs/smart-on-fhir/dynamic-client-registration/registration.md

@@ -0,0 +1,160 @@
+---
+layout: default
+title: Calling register_client
+parent: Dynamic Client Registration
+grand_parent: SMART
+nav_order: 1
+permalink: /smart-on-fhir/dynamic-client-registration/registration/
+description: "How to call Client#register_client: assembling client metadata, choosing grant types and authentication methods, endpoint discovery, and passing an initial access token."
+---
+
+# Calling register_client
+{: .no_toc }
+
+<div class="code-example" markdown="1">
+Call `Client#register_client` to POST your application's metadata to the authorization server's registration endpoint and receive a `client_id` in response.
+</div>
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Quick Start
+
+Create a `Safire::Client` without a `client_id`, call `register_client` with your application's metadata, and then build a fully configured client using the credentials the server returns.
+
+```ruby
+# Step 1 — temporary client for registration only (no client_id needed)
+temp_client = Safire::Client.new({ base_url: 'https://fhir.example.com' })
+
+# Step 2 — register and receive credentials
+registration = temp_client.register_client(
+  {
+    client_name:                'My FHIR App',
+    redirect_uris:              ['https://myapp.example.com/callback'],
+    grant_types:                ['authorization_code'],
+    token_endpoint_auth_method: 'none',
+    scope:                      'openid profile patient/*.read'
+  }
+)
+# => { "client_id" => "dyn_abc123", "client_name" => "My FHIR App", ... }
+
+# Step 3 — persist credentials durably (database, secrets manager, etc.)
+client_id = registration['client_id']     # always present
+secret    = registration['client_secret'] # present for confidential_symmetric only
+
+# Step 4 — build a properly configured client for authorization flows
+client = Safire::Client.new(
+  {
+    base_url:     'https://fhir.example.com',
+    client_id:    client_id,
+    redirect_uri: 'https://myapp.example.com/callback',
+    scopes:       ['openid', 'profile', 'patient/*.read']
+  }
+)
+```
+
+---
+
+## Client Metadata
+
+The `metadata` argument is a Hash of RFC 7591 §2 client metadata fields. Keys may be symbols or strings. Any field the server does not recognize is silently ignored; any field the server requires but you omit will produce a `RegistrationError`.
+
+### Common fields
+
+| Field | Type | When required | Notes |
+|-------|------|--------------|-------|
+| `client_name` | String | Recommended | Human-readable application name displayed in authorization prompts |
+| `redirect_uris` | Array\<String\> | Required for `authorization_code` | Exact URIs the server will redirect to after authorization |
+| `grant_types` | Array\<String\> | Recommended | See [Grant types](#grant-types) below |
+| `token_endpoint_auth_method` | String | Recommended | See [Authentication methods](#authentication-methods) below |
+| `scope` | String | Optional | Space-separated default scopes; may be narrowed per-request at runtime |
+| `jwks_uri` | String | Required for `private_key_jwt` | URL of the client's JWKS endpoint; the server fetches public keys for JWT verification |
+| `jwks` | Hash | Alternative to `jwks_uri` | Inline JWKS containing the client's public key(s) |
+| `client_uri` | String | Optional | URL of the client's home page |
+
+### Grant types
+
+Pass an array containing each grant type the client intends to use.
+
+| Value | Use |
+|-------|-----|
+| `authorization_code` | SMART App Launch — user-facing authorization with redirect and PKCE |
+| `client_credentials` | Backend Services — system-to-system access with no user interaction |
+| `refresh_token` | Token refresh; include alongside `authorization_code` when the server should issue refresh tokens |
+
+### Authentication methods
+
+The `token_endpoint_auth_method` value tells the server how the client will authenticate at the token endpoint. Safire supports the following methods.
+
+| Value | Safire `client_type` | How it works |
+|-------|----------------------|-------------|
+| `none` | `:public` | No client authentication; `client_id` sent in the POST body |
+| `client_secret_basic` | `:confidential_symmetric` | HTTP Basic auth using the `client_secret` the server issues |
+| `private_key_jwt` | `:confidential_asymmetric` | Signed JWT assertion; requires `jwks_uri` or inline `jwks` in metadata |
+
+{: .note }
+If your client will use `private_key_jwt`, you must include `jwks_uri` or `jwks` in the registration metadata so the server can obtain your public key for JWT verification.
+
+---
+
+## Registration Endpoint
+
+### Discovery (default)
+
+When you do not supply `registration_endpoint:`, Safire fetches the server's SMART configuration from `/.well-known/smart-configuration` and reads the `registration_endpoint` field. Discovery is cached after the first call, so repeated calls on the same `Safire::Client` instance do not issue another network request.
+
+```ruby
+# Safire discovers the registration endpoint automatically
+registration = client.register_client({ client_name: 'My App', ... })
+```
+
+If the server does not advertise a `registration_endpoint`, Safire raises `Safire::Errors::DiscoveryError`. The error message explains that you must supply the endpoint explicitly or that the server may not support DCR.
+
+To check before calling `register_client`, use `supports_dynamic_registration?` on the server metadata. This is only relevant when you are relying on discovery — if you already hold the endpoint URL, pass it via `registration_endpoint:` and skip this check.
+
+```ruby
+metadata = client.server_metadata
+
+unless metadata.supports_dynamic_registration?
+  raise 'Server does not advertise a registration_endpoint — pass registration_endpoint: explicitly or use manual registration'
+end
+
+registration = client.register_client({ client_name: 'My App', ... })
+```
+
+### Explicit endpoint
+
+Pass `registration_endpoint:` to bypass discovery entirely. This is useful when the server advertises the endpoint out-of-band, when you want to skip the discovery request, or when the server does not expose `/.well-known/smart-configuration`.
+
+```ruby
+registration = client.register_client(
+  { client_name: 'My App', ... },
+  registration_endpoint: 'https://auth.example.com/register'
+)
+```
+
+---
+
+## Initial Access Token
+
+Some authorization servers protect their registration endpoint with a bearer token to prevent unauthorized registrations (RFC 7591 §3.1). If the server requires one, obtain it out-of-band from the server operator and pass the full `Authorization` header value to `authorization:`.
+
+```ruby
+registration = client.register_client(
+  { client_name: 'My App', ... },
+  authorization: 'Bearer eyJhbGciOiJSUzI1NiJ9...'
+)
+```
+
+The `authorization:` parameter accepts any valid header value. Safire passes it verbatim as the `Authorization` header, so the token type prefix (`Bearer`, `MAC`, etc.) must be included.
+
+---
+
+## What's Next
+
+[Registration Response]({% link smart-on-fhir/dynamic-client-registration/response.md %}) covers what the server returns, how to persist credentials, how to build a runtime client from the response, and error handling.

data/docs/smart-on-fhir/dynamic-client-registration/response.md

@@ -0,0 +1,161 @@
+---
+layout: default
+title: Registration Response
+parent: Dynamic Client Registration
+grand_parent: SMART
+nav_order: 2
+permalink: /smart-on-fhir/dynamic-client-registration/response/
+description: "What register_client returns: client_id, client_secret, echoed fields, building a runtime Safire::Client from the response, and handling DiscoveryError, RegistrationError, and NetworkError."
+---
+
+# Registration Response
+{: .no_toc }
+
+<div class="code-example" markdown="1">
+On success, `register_client` returns the server's response as a Hash. On failure, it raises `DiscoveryError`, `RegistrationError`, or `NetworkError`.
+</div>
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Response Fields
+
+### `client_id`
+
+The `client_id` is always present. It is the permanent identifier the server assigned to this client and is required for every subsequent authorization flow.
+
+```ruby
+client_id = registration['client_id']  # => "dyn_abc123"
+```
+
+### `client_secret`
+
+For clients registered with `token_endpoint_auth_method: 'client_secret_basic'`, the server also issues a `client_secret`. Store it durably in a secrets manager or encrypted storage. The server will not return it again in routine operation; if it is lost, you will need to obtain a replacement through the server's administrative process.
+
+```ruby
+client_secret = registration['client_secret']  # => "s3cr3t..." or nil
+```
+
+### Additional fields
+
+The server typically echoes back some or all of the metadata you submitted, along with server-assigned values such as `client_id_issued_at` or `client_secret_expires_at`. Servers that also implement the OAuth 2.0 Dynamic Client Registration Management Protocol (RFC 7592) may include a `registration_client_uri` and `registration_access_token` for subsequent read, update, and delete operations. Safire does not implement RFC 7592 management operations, but you can store those fields if you need to interact with the management endpoint using another tool.
+
+---
+
+## Building Your Runtime Client
+
+After persisting credentials, build a new `Safire::Client` configured for the authorization flows you intend to use. The client type determines how authentication works at the token endpoint.
+
+```ruby
+# Public client — authorization_code grant with PKCE
+client = Safire::Client.new(
+  {
+    base_url:     'https://fhir.example.com',
+    client_id:    registration['client_id'],
+    redirect_uri: 'https://myapp.example.com/callback',
+    scopes:       ['openid', 'profile', 'patient/*.read']
+  }
+)
+
+# Confidential symmetric — client_secret_basic
+client = Safire::Client.new(
+  {
+    base_url:      'https://fhir.example.com',
+    client_id:     registration['client_id'],
+    client_secret: registration['client_secret'],
+    redirect_uri:  'https://myapp.example.com/callback',
+    scopes:        ['openid', 'profile', 'patient/*.read']
+  },
+  client_type: :confidential_symmetric
+)
+
+# Confidential asymmetric — private_key_jwt
+client = Safire::Client.new(
+  {
+    base_url:    'https://fhir.example.com',
+    client_id:   registration['client_id'],
+    redirect_uri: 'https://myapp.example.com/callback',
+    scopes:      ['openid', 'profile', 'patient/*.read'],
+    private_key: OpenSSL::PKey::RSA.new(File.read('private.pem')),
+    kid:         'my-key-id'
+  },
+  client_type: :confidential_asymmetric
+)
+```
+
+---
+
+## Error Handling
+
+`register_client` raises one of three error classes. All inherit from `Safire::Errors::Error`, so you can rescue any Safire error with a single clause when needed.
+
+### `Safire::Errors::DiscoveryError`
+
+Raised when no `registration_endpoint:` was passed and the server either does not publish `/.well-known/smart-configuration`, returns a non-JSON response, or does not include a `registration_endpoint` field in its SMART metadata.
+
+```ruby
+rescue Safire::Errors::DiscoveryError => e
+  puts e.message   # "Failed to discover SMART configuration from https://...: server does not advertise a 'registration_endpoint'..."
+  puts e.endpoint  # "https://fhir.example.com/.well-known/smart-configuration"
+  puts e.status    # HTTP status code, or nil if the server was unreachable
+```
+
+### `Safire::Errors::RegistrationError`
+
+Raised when the server returns an HTTP error response (4xx or 5xx), or when a
+2xx response does not contain a non-blank string `client_id`.
+
+```ruby
+rescue Safire::Errors::RegistrationError => e
+  # HTTP error path — server returned an RFC 7591 error response
+  puts e.status            # 400
+  puts e.error_code        # "invalid_redirect_uri"
+  puts e.error_description # "Redirect URI must use HTTPS"
+
+  # Structural failure path — client_id key is missing
+  puts e.received_fields   # ["error", "error_description"]
+  puts e.message           # "Registration response missing client_id; received fields: ..."
+
+  # Structural failure path — client_id is nil, blank, or not a string
+  puts e.error_description # "response client_id must be a non-blank string"
+```
+
+For a missing `client_id` key, `received_fields` contains the field names from
+the response. When the key is present but its value is invalid,
+`error_description` describes the validation failure and `received_fields` is
+`nil`.
+
+To rescue any OAuth protocol error in one clause, use `Safire::Errors::OAuthError`, the shared base class for `RegistrationError`, `TokenError`, and `AuthError`.
+
+### `Safire::Errors::NetworkError`
+
+Raised when the HTTP request fails at the transport level: connection refused, timeout, or SSL handshake error.
+
+```ruby
+rescue Safire::Errors::NetworkError => e
+  puts e.message           # "HTTP request failed: ..."
+  puts e.error_description # underlying transport error message
+```
+
+### Full rescue example
+
+```ruby
+begin
+  registration = client.register_client(
+    { client_name: 'My App', ... },
+    registration_endpoint: explicit_endpoint,
+    authorization:         initial_access_token
+  )
+rescue Safire::Errors::DiscoveryError => e
+  logger.error("Registration endpoint not found: #{e.message}")
+rescue Safire::Errors::RegistrationError => e
+  logger.error("Server rejected registration: #{e.message}")
+rescue Safire::Errors::NetworkError => e
+  logger.error("Network failure during registration: #{e.message}")
+end
+```

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

@@ -4,7 +4,7 @@ title: SMART
 nav_order: 4
 has_children: true
 permalink: /smart-on-fhir/
-description: "Step-by-step guides for SMART App Launch OAuth 2.0 flows in Ruby, covering public client (PKCE), confidential symmetric, confidential asymmetric (private_key_jwt), and Backend Services (system-to-system)."
+description: "Step-by-step guides for SMART App Launch OAuth 2.0 flows in Ruby, covering Dynamic Client Registration (RFC 7591), public client (PKCE), confidential symmetric, confidential asymmetric (private_key_jwt), and Backend Services (system-to-system)."
 ---
 
 # SMART App Launch
@@ -16,6 +16,7 @@ This section provides step-by-step guides for implementing SMART authorization f
 | Workflow | Description |
 |----------|-------------|
 | [SMART Discovery]({% link smart-on-fhir/discovery/index.md %}) | Fetching and using SMART configuration metadata |
+| [Dynamic Client Registration]({% link smart-on-fhir/dynamic-client-registration/index.md %}) | Register a client at runtime using RFC 7591 to obtain a `client_id` |
 | [Public Client]({% link smart-on-fhir/public-client/index.md %}) | Authorization flow for browser-based and mobile applications |
 | [Confidential Symmetric Client]({% link smart-on-fhir/confidential-symmetric/index.md %}) | Authorization flow for server-side applications with client secrets |
 | [Confidential Asymmetric Client]({% link smart-on-fhir/confidential-asymmetric/index.md %}) | Authorization flow using private_key_jwt (RSA/EC key pair) |

data/docs/smart-on-fhir/post-based-authorization.md

@@ -2,7 +2,7 @@
 layout: default
 title: POST-Based Authorization
 parent: SMART
-nav_order: 5
+nav_order: 6
 has_toc: true
 ---
 

data/docs/smart-on-fhir/public-client/index.md

@@ -2,7 +2,7 @@
 layout: default
 title: Public Client Workflow
 parent: SMART
-nav_order: 2
+nav_order: 3
 has_children: true
 permalink: /smart-on-fhir/public-client/
 ---

data/docs/troubleshooting/auth-errors.md

@@ -75,6 +75,26 @@ The response must be a JSON object (`{...}`) with at least `authorization_endpoi
 
 ## Authorization Errors
 
+### `ConfigurationError`: Missing `client_id`
+
+```
+Safire::Errors::ConfigurationError: Configuration missing: client_id
+```
+
+`client_id` is optional at construction but required by every authorization method. It is validated at call time, not when the client is created. Ensure `client_id` is set in `ClientConfig` before calling any flow method:
+
+```ruby
+config = Safire::ClientConfig.new(
+  base_url:  'https://fhir.example.com',
+  client_id: ENV.fetch('SMART_CLIENT_ID'),
+  # ...
+)
+```
+
+This error is raised by `authorization_url`, `request_access_token`, `refresh_token`, and `request_backend_token`.
+
+---
+
 ### `ConfigurationError`: Missing scopes
 
 ```

data/docs/troubleshooting/client-errors.md

@@ -17,6 +17,149 @@ nav_order: 3
 
 ---
 
+## Dynamic Client Registration Errors
+
+### `DiscoveryError`: Server does not advertise a registration endpoint
+
+```
+Safire::Errors::DiscoveryError: Failed to discover SMART configuration from https://...: server does not advertise a 'registration_endpoint'
+```
+
+The server either does not support Dynamic Client Registration or its registration endpoint is not published in `/.well-known/smart-configuration`. Pass the endpoint explicitly or register manually through the server's developer portal:
+
+```ruby
+registration = client.register_client(
+  metadata,
+  registration_endpoint: 'https://auth.example.com/register'
+)
+```
+
+For UDAP, the registration endpoint is always discovery-bound. Safire raises
+`DiscoveryError` before POSTing when discovery fails, `signed_metadata` cannot
+be validated, `UdapMetadata#valid?` reports structural non-conformance, the
+server does not advertise `udap_dcr`, or the server does not publish
+mandatory `RS256` registration signing support:
+
+```ruby
+registration = udap_client.register_client(
+  metadata,
+  client_uri:      'https://client.example.com',
+  trusted_anchors: [ca_cert],
+  crls:            [ca_crl]
+)
+```
+
+### `ValidationError`: UDAP registration metadata or certifications are invalid
+
+```
+Safire::Errors::ValidationError: Validation failed for certifications: must be nil or an array of compact JWS strings
+```
+
+UDAP registration signs caller-controlled metadata before sending it. Safire
+therefore validates the metadata and certification collection locally and raises
+`ValidationError` before building a software statement when input is malformed.
+
+Common causes:
+
+- missing required metadata such as `client_name`, `contacts`, `grant_types`, or `scope`
+- unsupported grant combinations
+- non-HTTPS redirect or logo URIs, except HTTP localhost when explicitly enabled for development
+- reserved claims such as `iss`, `sub`, `aud`, `exp`, `jti`, `software_statement`, `certifications`, or `udap`
+- `certifications:` is not `nil` or an array of compact JWS strings
+- discovery declares required certification policy URIs, but `certifications:`
+  is omitted or empty; the server still decides whether supplied JWTs satisfy
+  those policies
+
+### `CertificateError`: UDAP client signing identity cannot support registration
+
+```
+Safire::Errors::CertificateError: Certificate error — client_uri does not match any URI SAN in the leaf certificate
+```
+
+UDAP registration requires a private key and leaf-first certificate chain. The
+private key must match the leaf certificate, every certificate must be currently
+valid, and the `client_uri:` must exactly match a URI Subject Alternative Name
+in the leaf certificate. Case, port, and trailing slash differences are
+significant.
+
+### `RegistrationError`: Server rejected the registration request
+
+```
+Safire::Errors::RegistrationError: Client registration failed — HTTP 400 — invalid_redirect_uri — Redirect URI must use HTTPS
+```
+
+The server returned an OAuth 2.0 error response. Check `e.error_code` and `e.error_description` for the specific reason, correct the metadata, and retry:
+
+```ruby
+rescue Safire::Errors::RegistrationError => e
+  puts e.status            # 400
+  puts e.error_code        # "invalid_redirect_uri"
+  puts e.error_description # "Redirect URI must use HTTPS"
+```
+
+UDAP servers may return UDAP-specific error codes such as
+`invalid_software_statement` or `unapproved_software_statement`; Safire
+preserves them in `e.error_code`.
+
+### `RegistrationError`: 2xx response has a missing or invalid `client_id`
+
+```
+Safire::Errors::RegistrationError: Registration response missing client_id; received fields: error, error_description
+```
+
+The server returned a successful HTTP status without a valid `client_id`. A
+successful registration response must contain a non-blank string `client_id`.
+
+If the response omitted the key, check `e.received_fields` to see what the
+server returned:
+
+```ruby
+rescue Safire::Errors::RegistrationError => e
+  puts e.received_fields # ["error", "error_description"]
+end
+```
+
+If the key was present but its value was `nil`, blank, or not a string,
+`e.error_description` reports the validation failure and `e.received_fields`
+is `nil`:
+
+```ruby
+rescue Safire::Errors::RegistrationError => e
+  puts e.error_description # "response client_id must be a non-blank string"
+end
+```
+
+Either response is a server-side protocol error and should not be treated as a
+successful registration.
+
+### `RegistrationError`: UDAP cancellation response does not confirm cancellation
+
+```
+Safire::Errors::RegistrationError: Client registration failed — HTTP 202 — cancellation response must include an empty grant_types array
+```
+
+UDAP registration cancellation is confirmed by the response body, not by a
+specific success status such as `200` or `201`. Safire accepts a cancellation
+response only when the final status is `2xx` and the body contains a non-blank
+string `client_id` plus an empty `grant_types` array:
+
+```ruby
+cancellation = udap_client.cancel_registration(
+  metadata,
+  client_uri:      'https://client.example.com',
+  trusted_anchors: [ca_cert],
+  crls:            [ca_crl]
+)
+
+cancellation['grant_types'] # => []
+```
+
+If the response status is not `2xx`, or if the body omits `grant_types`, returns
+a non-array value, or returns a non-empty array, treat it as a failed
+cancellation and investigate the authorization server response.
+
+---
+
 ## Confidential Symmetric Client Errors
 
 ### `ConfigurationError`: Missing `client_secret`