safire 0.1.0

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

@@ -0,0 +1,142 @@
+---
+layout: default
+title: Capability Checks and Client Selection
+parent: SMART Discovery
+grand_parent: SMART on FHIR
+nav_order: 2
+---
+
+# Capability Checks and Client Selection
+
+{: .no_toc }
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Full Checks (`supports_*?`)
+
+These methods verify both the capability flag **and** any required associated fields. Use them to confirm the server is fully ready for a given mode.
+
+```ruby
+# Launch modes — requires capability flag AND authorization_endpoint present
+metadata.supports_ehr_launch?         # launch-ehr + authorization_endpoint
+metadata.supports_standalone_launch?  # launch-standalone + authorization_endpoint
+
+# Public clients
+metadata.supports_public_auth?
+# => true if capabilities include "client-public"
+
+# Confidential symmetric — checks capability AND auth method compatibility
+metadata.supports_symmetric_auth?
+# => true if:
+#    capabilities include "client-confidential-symmetric"
+#    AND (token_endpoint_auth_methods_supported is blank
+#         OR includes "client_secret_basic")
+
+# Confidential asymmetric — checks capability, auth method, AND algorithm support
+metadata.supports_asymmetric_auth?
+# => true if:
+#    capabilities include "client-confidential-asymmetric"
+#    AND (token_endpoint_auth_methods_supported is blank
+#         OR includes "private_key_jwt")
+#    AND asymmetric_signing_algorithms_supported.any?
+
+# OpenID Connect — requires capability flag, issuer, AND jwks_uri present
+metadata.supports_openid_connect?
+
+# POST-based authorization
+metadata.supports_post_based_authorization?
+# => true if capabilities include "authorize-post"
+```
+
+---
+
+## Flag-Only Checks (`*_capability?`)
+
+These check only the capability string — they do **not** verify that required fields are present. Use them for lightweight checks or when you plan to validate fields separately.
+
+```ruby
+metadata.ehr_launch_capability?        # capabilities include "launch-ehr"
+metadata.standalone_launch_capability? # capabilities include "launch-standalone"
+metadata.openid_connect_capability?    # capabilities include "sso-openid-connect"
+```
+
+{: .important }
+> **`supports_*?` vs `*_capability?`** — `supports_ehr_launch?` returns `false` if `authorization_endpoint` is missing even when the capability flag is set. `ehr_launch_capability?` returns `true` based on the flag alone. Prefer `supports_*?` unless you have a specific reason to check the flag independently.
+
+---
+
+## Asymmetric Signing Algorithms
+
+```ruby
+metadata.asymmetric_signing_algorithms_supported
+# Returns the intersection of server-advertised signing algorithms and
+# Safire's supported set [RS384, ES384].
+# If the server does not advertise algorithms, both RS384 and ES384 are assumed.
+# => ["RS384", "ES384"]
+```
+
+This method powers `supports_asymmetric_auth?` internally and is also useful when selecting a signing algorithm explicitly for a confidential asymmetric client.
+
+---
+
+## Client Selection Based on Discovery
+
+**Manual client type switch** — discover first, then update the client type. Already-fetched metadata is preserved; no re-discovery occurs.
+
+```ruby
+client = Safire::Client.new(config) # defaults to :public
+metadata = client.server_metadata
+
+if metadata.supports_symmetric_auth?
+  client.client_type = :confidential_symmetric
+end
+
+tokens = client.request_access_token(code: code, code_verifier: verifier)
+```
+
+**Automatic selection** based on server capabilities:
+
+```ruby
+def configure_client_type(client)
+  metadata = client.server_metadata
+
+  if metadata.supports_asymmetric_auth?
+    client.client_type = :confidential_asymmetric
+  elsif metadata.supports_symmetric_auth?
+    client.client_type = :confidential_symmetric
+  elsif metadata.supports_public_auth?
+    client.client_type = :public
+  else
+    raise 'Server does not support any known client types'
+  end
+end
+```
+
+---
+
+## SMART Capabilities Reference
+
+| Capability | Description |
+|------------|-------------|
+| `launch-ehr` | Supports EHR-initiated launch |
+| `launch-standalone` | Supports standalone launch |
+| `authorize-post` | Supports POST-based authorization |
+| `client-public` | Supports public clients |
+| `client-confidential-symmetric` | Supports `client_secret_basic` |
+| `client-confidential-asymmetric` | Supports `private_key_jwt` |
+| `sso-openid-connect` | Supports OpenID Connect |
+| `context-ehr-patient` | EHR launch provides patient context |
+| `context-ehr-encounter` | EHR launch provides encounter context |
+| `context-standalone-patient` | Standalone launch can request patient context |
+| `context-standalone-encounter` | Standalone launch can request encounter context |
+| `permission-offline` | Supports `offline_access` scope |
+| `permission-patient` | Supports patient-level scopes |
+| `permission-user` | Supports user-level scopes |
+| `permission-v1` | Supports SMART v1 scopes |
+| `permission-v2` | Supports SMART v2 scopes |

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

@@ -0,0 +1,96 @@
+---
+layout: default
+title: SMART Discovery
+parent: SMART on FHIR
+nav_order: 1
+has_children: true
+permalink: /smart-on-fhir/discovery/
+---
+
+# SMART Discovery
+
+{: .no_toc }
+
+<div class="code-example" markdown="1">
+SMART on FHIR discovery allows clients to dynamically learn about a FHIR server's authorization capabilities before initiating the OAuth flow.
+</div>
+
+---
+
+## Overview
+
+Safire fetches server metadata from `/.well-known/smart-configuration`, appended to your `base_url`:
+
+```ruby
+base_url = 'https://fhir.example.com/r4'
+# Fetches: https://fhir.example.com/r4/.well-known/smart-configuration
+```
+
+Trailing slashes are handled automatically. The metadata is fetched lazily on first use and cached within the client instance.
+
+```ruby
+config = Safire::ClientConfig.new(
+  base_url:     'https://fhir.example.com',
+  client_id:    'my_client',
+  redirect_uri: 'https://myapp.com/callback',
+  scopes:       ['openid', 'profile']
+)
+
+# :public is the default client_type — appropriate for discovery
+client   = Safire::Client.new(config)
+metadata = client.server_metadata
+# => #<Safire::Protocols::SmartMetadata ...>
+```
+
+`server_metadata` returns a `Safire::Protocols::SmartMetadata` object with typed accessors for all fields. See [Metadata Fields and Validation]({% link smart-on-fhir/discovery/metadata.md %}) for the full field reference and validation rules.
+
+---
+
+## Error Handling
+
+```ruby
+begin
+  metadata = client.server_metadata
+rescue Safire::Errors::DiscoveryError => e
+  case e.message
+  when /404/
+    puts 'FHIR server does not support SMART on FHIR'
+  when /timeout/i
+    puts 'Discovery request timed out'
+  when /expected JSON object/
+    puts 'Server returned invalid SMART configuration'
+  else
+    puts "Discovery failed: #{e.message}"
+  end
+end
+```
+
+**Graceful fallback** — fall back to known endpoints when discovery is unavailable:
+
+```ruby
+def discover_with_fallback(client)
+  metadata = client.server_metadata
+  {
+    authorization_endpoint: metadata.authorization_endpoint,
+    token_endpoint:         metadata.token_endpoint,
+    source:                 :discovery
+  }
+rescue Safire::Errors::DiscoveryError => e
+  Rails.logger.warn("Discovery failed, using fallback: #{e.message}")
+  {
+    authorization_endpoint: ENV['FALLBACK_AUTH_ENDPOINT'],
+    token_endpoint:         ENV['FALLBACK_TOKEN_ENDPOINT'],
+    source:                 :fallback
+  }
+end
+```
+
+{: .note }
+> Application-level metadata caching (e.g. `Rails.cache`) and multi-server registry patterns are covered in the [Advanced Examples]({{ site.baseurl }}/advanced/) guide.
+
+---
+
+## What's Next
+
+- [Metadata Fields and Validation]({% link smart-on-fhir/discovery/metadata.md %}) — field reference, validation rules, PKCE checks
+- [Capability Checks and Client Selection]({% link smart-on-fhir/discovery/capability-checks.md %}) — all capability methods and dynamic client type selection

data/docs/smart-on-fhir/discovery/metadata.md

@@ -0,0 +1,147 @@
+---
+layout: default
+title: Metadata Fields and Validation
+parent: SMART Discovery
+grand_parent: SMART on FHIR
+nav_order: 1
+---
+
+# Metadata Fields and Validation
+
+{: .no_toc }
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Field Reference
+
+`server_metadata` returns a `Safire::Protocols::SmartMetadata` object. All fields are accessible as typed readers.
+
+### Always Required
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `token_endpoint` | String | OAuth2 token endpoint URL |
+| `grant_types_supported` | Array | Supported OAuth2 grant types |
+| `capabilities` | Array | SMART capabilities list |
+| `code_challenge_methods_supported` | Array | Must include `"S256"`, must not include `"plain"` |
+
+### Conditionally Required
+
+| Field | Type | Required when |
+|-------|------|--------------|
+| `authorization_endpoint` | String | capabilities include `launch-ehr` or `launch-standalone` |
+| `issuer` | String | capabilities include `sso-openid-connect` |
+| `jwks_uri` | String | capabilities include `sso-openid-connect` |
+
+### Optional
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `registration_endpoint` | String | Dynamic client registration URL |
+| `scopes_supported` | Array | Available OAuth2 scopes |
+| `response_types_supported` | Array | Supported response types |
+| `token_endpoint_auth_methods_supported` | Array | Token endpoint auth methods (e.g. `client_secret_basic`, `private_key_jwt`) |
+| `token_endpoint_auth_signing_alg_values_supported` | Array | JWT signing algorithms (e.g. `RS384`, `ES384`) — used by `asymmetric_signing_algorithms_supported` |
+| `introspection_endpoint` | String | Token introspection URL |
+| `revocation_endpoint` | String | Token revocation URL |
+| `management_endpoint` | String | User access management URL |
+| `associated_endpoints` | Array | Endpoints sharing this auth server |
+| `user_access_brand_bundle` | String | Brand bundle URL for user-facing apps |
+| `user_access_brand_identifier` | String | Primary brand identifier |
+
+### Example Usage
+
+```ruby
+metadata.token_endpoint                    # => "https://fhir.example.com/token"
+metadata.grant_types_supported             # => ["authorization_code", "refresh_token"]
+metadata.capabilities                      # => ["launch-ehr", "client-public", ...]
+metadata.code_challenge_methods_supported  # => ["S256"]
+
+# Conditionally present
+metadata.authorization_endpoint            # => "https://fhir.example.com/authorize"
+metadata.issuer                            # => "https://fhir.example.com"
+metadata.jwks_uri                          # => "https://fhir.example.com/.well-known/jwks.json"
+
+# Optional
+metadata.registration_endpoint             # => "https://fhir.example.com/register"
+metadata.scopes_supported                  # => ["openid", "profile", "patient/*.read", ...]
+metadata.token_endpoint_auth_methods_supported         # => ["client_secret_basic", "private_key_jwt"]
+metadata.token_endpoint_auth_signing_alg_values_supported # => ["RS384", "ES384"]
+metadata.introspection_endpoint            # => "https://fhir.example.com/introspect"
+metadata.revocation_endpoint               # => "https://fhir.example.com/revoke"
+metadata.management_endpoint              # => "https://fhir.example.com/manage"
+metadata.associated_endpoints              # => [{"url" => "...", "capabilities" => [...]}]
+metadata.user_access_brand_bundle          # => "https://fhir.example.com/brands"
+metadata.user_access_brand_identifier      # => "example-brand"
+```
+
+---
+
+## Validation
+
+`valid?` checks conformance with SMART App Launch 2.2.0 and logs a warning for each violation. It never raises — deciding whether to block on non-compliant metadata is the caller's responsibility.
+
+```ruby
+if metadata.valid?
+  # All required fields present, PKCE compliant
+else
+  # Safire has already logged warnings for each violation
+  raise 'Server metadata does not meet SMART App Launch 2.2.0 requirements'
+end
+```
+
+**What `valid?` checks:**
+- All always-required fields are present
+- Conditional fields present when their capability is advertised
+- `code_challenge_methods_supported` includes `'S256'` (SHALL per SMART 2.2.0)
+- `code_challenge_methods_supported` does not include `'plain'` (SHALL NOT per SMART 2.2.0)
+
+Example warning output:
+
+```
+WARN: SMART metadata non-compliance: required field 'authorization_endpoint' is missing
+WARN: SMART metadata non-compliance: 'S256' is missing from code_challenge_methods_supported (SMART App Launch 2.2.0 requires S256)
+WARN: SMART metadata non-compliance: 'plain' is present in code_challenge_methods_supported (SMART App Launch 2.2.0 prohibits plain)
+```
+
+---
+
+## Example Server Response (SMART App Launch 2.2.0)
+
+```json
+{
+  "issuer": "https://fhir.example.com",
+  "authorization_endpoint": "https://fhir.example.com/authorize",
+  "token_endpoint": "https://fhir.example.com/token",
+  "jwks_uri": "https://fhir.example.com/.well-known/jwks.json",
+  "grant_types_supported": ["authorization_code", "refresh_token"],
+  "scopes_supported": ["openid", "profile", "launch", "patient/*.read", "offline_access"],
+  "response_types_supported": ["code"],
+  "token_endpoint_auth_methods_supported": [
+    "client_secret_basic",
+    "private_key_jwt"
+  ],
+  "token_endpoint_auth_signing_alg_values_supported": ["RS384", "ES384"],
+  "code_challenge_methods_supported": ["S256"],
+  "capabilities": [
+    "launch-ehr",
+    "launch-standalone",
+    "client-public",
+    "client-confidential-symmetric",
+    "client-confidential-asymmetric",
+    "sso-openid-connect",
+    "context-ehr-patient",
+    "context-ehr-encounter",
+    "context-standalone-patient",
+    "permission-offline",
+    "permission-patient",
+    "permission-user"
+  ]
+}
+```

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

@@ -0,0 +1,72 @@
+---
+layout: default
+title: SMART on FHIR
+nav_order: 4
+has_children: true
+permalink: /smart-on-fhir/
+---
+
+# SMART on FHIR
+
+This section provides step-by-step guides for implementing SMART on FHIR authorization flows with Safire.
+
+## Available Workflows
+
+| Workflow | Description |
+|----------|-------------|
+| [SMART Discovery]({% link smart-on-fhir/discovery/index.md %}) | Fetching and using SMART configuration metadata |
+| [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) |
+| [POST-Based Authorization]({% link smart-on-fhir/post-based-authorization.md %}) | Sending the authorization request as a form POST (`authorize-post` capability) |
+
+## Choosing a Client Type
+
+```
+Is your application a server-side web application
+that can securely store credentials?
+        │
+        ├── YES → Can you use asymmetric key pairs (RSA/EC)?
+        │         │
+        │         ├── YES → Confidential Asymmetric Client
+        │         │         (Uses private_key_jwt with signed JWT assertions)
+        │         │
+        │         └── NO  → Confidential Symmetric Client
+        │                   (Uses client_secret with HTTP Basic auth)
+        │
+        └── NO  → Public Client
+                  (Uses PKCE only, no client secret)
+```
+
+## Common Flow
+
+All SMART authorization flows follow this general pattern. The key differences between client types are in how they authenticate during token exchange and refresh.
+
+```mermaid
+sequenceDiagram
+    participant App
+    participant Safire
+    participant FHIR as FHIR Server
+
+    App->>Safire: Client.new(config)
+    Note over Safire: No network call yet
+
+    App->>Safire: authorization_url()
+    Safire->>FHIR: GET /.well-known/smart-configuration
+    FHIR-->>Safire: SmartMetadata (endpoints, capabilities)
+    Safire-->>App: { auth_url, state, code_verifier }
+
+    App->>FHIR: Redirect user to auth_url
+    FHIR-->>App: Callback with ?code=...&state=...
+
+    App->>Safire: request_access_token(code:, code_verifier:)
+    Note over Safire: Auth method varies by client_type:<br/>public → client_id in body<br/>confidential_symmetric → Basic auth header<br/>confidential_asymmetric → JWT assertion in body
+    Safire->>FHIR: POST /token
+    FHIR-->>Safire: { access_token, refresh_token, expires_in, ... }
+    Safire-->>App: token response Hash
+
+    App->>Safire: refresh_token(refresh_token:)
+    Safire->>FHIR: POST /token (grant_type=refresh_token)
+    FHIR-->>Safire: { access_token, ... }
+    Safire-->>App: new token response Hash
+```

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

@@ -0,0 +1,190 @@
+---
+layout: default
+title: POST-Based Authorization
+parent: SMART on FHIR
+nav_order: 5
+has_toc: true
+---
+
+# POST-Based Authorization
+
+{: .no_toc }
+
+<div class="code-example" markdown="1">
+SMART App Launch 2.2.0 introduces the `authorize-post` capability, allowing servers to accept the authorization request as an HTTP form POST instead of a GET redirect. This page explains when and how to use it with Safire.
+</div>
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Overview
+
+By default, SMART authorization uses a GET redirect — the user's browser is sent to the authorization server with all parameters in the query string. Servers that advertise the `authorize-post` capability also accept the authorization request as an HTTP POST with parameters in the request body.
+
+POST-based authorization can be useful when:
+- Authorization parameters are too large for a URL (e.g. rich `state` or `launch` values)
+- The client prefers to avoid sensitive parameters appearing in browser history or server logs
+
+---
+
+## Detecting Server Support
+
+Check whether the authorization server advertises the `authorize-post` capability before using POST mode:
+
+```ruby
+client = Safire::Client.new(config, client_type: :public)
+metadata = client.server_metadata
+
+if metadata.supports_post_based_authorization?
+  puts "Server supports POST-based authorization"
+end
+```
+
+---
+
+## Generating a POST Authorization Request
+
+Pass `method: :post` (or `method: 'post'`) to `authorization_url`:
+
+```ruby
+auth_data = client.authorization_url(method: :post)
+
+auth_data[:auth_url]      # The bare authorization endpoint URL
+auth_data[:params]        # Hash of parameters to POST as the request body
+auth_data[:state]         # Store in session for CSRF verification
+auth_data[:code_verifier] # Store in session for token exchange
+```
+
+The `:get` method returns `auth_url` as a fully-formed URL with query parameters. The `:post` method returns the endpoint separately from the parameters so your application can submit a form POST.
+
+---
+
+## Rails Example
+
+```ruby
+# app/controllers/smart_auth_controller.rb
+def launch
+  # Check server support (optional but recommended)
+  metadata = @client.server_metadata
+  use_post = metadata.supports_post_based_authorization?
+
+  auth_data = @client.authorization_url(method: use_post ? :post : :get)
+
+  session[:oauth_state] = auth_data[:state]
+  session[:code_verifier] = auth_data[:code_verifier]
+
+  if use_post
+    # Render a form that auto-submits to the authorization endpoint
+    @auth_url = auth_data[:auth_url]
+    @auth_params = auth_data[:params]
+    render :authorize_post
+  else
+    redirect_to auth_data[:auth_url], allow_other_host: true
+  end
+end
+```
+
+```erb
+<%# app/views/smart_auth/authorize_post.html.erb %>
+<form id="auth-form" method="POST" action="<%= @auth_url %>">
+  <% @auth_params.each do |key, value| %>
+    <input type="hidden" name="<%= key %>" value="<%= value %>">
+  <% end %>
+</form>
+
+<script>
+  // Auto-submit after the page loads
+  document.getElementById('auth-form').submit();
+</script>
+```
+
+### Response Hash Comparison
+
+| Key           | GET (`method: :get`)                          | POST (`method: :post`)         |
+|---------------|-----------------------------------------------|--------------------------------|
+| `:auth_url`   | Full URL with query string parameters         | Bare authorization endpoint URL |
+| `:state`      | State value (also embedded in query string)   | State value                    |
+| `:code_verifier` | PKCE code verifier                         | PKCE code verifier             |
+| `:params`     | Not present                                   | Hash of all authorization parameters |
+
+The callback handling (token exchange) is identical for both methods — the authorization server always redirects back to your `redirect_uri` with an authorization code.
+
+---
+
+## Sinatra Example
+
+```ruby
+get '/launch' do
+  auth_data = @client.authorization_url(method: :post)
+
+  session[:state] = auth_data[:state]
+  session[:code_verifier] = auth_data[:code_verifier]
+
+  @auth_url = auth_data[:auth_url]
+  @auth_params = auth_data[:params]
+  erb :authorize_post
+end
+```
+
+```erb
+<%# views/authorize_post.erb %>
+<form id="auth-form" method="POST" action="<%= @auth_url %>">
+  <% @auth_params.each do |key, value| %>
+    <input type="hidden" name="<%= key %>" value="<%= value %>">
+  <% end %>
+</form>
+<script>document.getElementById('auth-form').submit();</script>
+```
+
+---
+
+## String and Symbol Forms
+
+Both string and symbol values are accepted:
+
+```ruby
+client.authorization_url(method: :post)   # symbol
+client.authorization_url(method: 'post')  # string — also accepted
+client.authorization_url(method: :get)    # default
+client.authorization_url(method: 'get')   # also accepted
+```
+
+Passing any other value raises a `Safire::Errors::ConfigurationError`:
+
+```ruby
+client.authorization_url(method: :put)
+# => Safire::Errors::ConfigurationError:
+#      Invalid authorization method: :put. Supported methods are :get and :post
+```
+
+---
+
+## Authorization Parameters
+
+The parameters included in `:params` (POST) are identical to those embedded in the query string for GET:
+
+| Parameter | Description |
+|---|---|
+| `response_type` | `"code"` — OAuth 2.0 authorization code flow |
+| `client_id` | Your registered client identifier |
+| `redirect_uri` | Callback URL for your application |
+| `scope` | Requested permissions (space-separated) |
+| `state` | CSRF protection token (32 hex chars, randomly generated) |
+| `aud` | FHIR server being accessed |
+| `code_challenge_method` | `"S256"` — PKCE using SHA-256 |
+| `code_challenge` | SHA-256 hash of the code verifier |
+| `launch` | EHR launch token (if provided via `launch:` argument) |
+
+---
+
+## Next Steps
+
+- [Public Client Workflow]({% link smart-on-fhir/public-client/index.md %})
+- [Confidential Symmetric Client Workflow]({% link smart-on-fhir/confidential-symmetric/index.md %})
+- [Confidential Asymmetric Client Workflow]({% link smart-on-fhir/confidential-asymmetric/index.md %})
+- [SMART Discovery Details]({% link smart-on-fhir/discovery/index.md %})