safire 0.1.0

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

@@ -0,0 +1,112 @@
+---
+layout: default
+title: Authorization
+parent: Public Client Workflow
+grand_parent: SMART on FHIR
+nav_order: 1
+---
+
+# Authorization
+
+{: .no_toc }
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Step 1: SMART Discovery
+
+Before generating an authorization URL, Safire fetches the server's SMART configuration from `/.well-known/smart-configuration`. This happens lazily on first use.
+
+```ruby
+def show_capabilities
+  metadata = @client.server_metadata
+
+  render json: {
+    authorization_endpoint:  metadata.authorization_endpoint,
+    token_endpoint:          metadata.token_endpoint,
+    capabilities:            metadata.capabilities,
+    supports_public_clients: metadata.supports_public_auth?,
+    supports_pkce:           metadata.code_challenge_methods_supported.include?('S256')
+  }
+end
+```
+
+Safire parses and validates the response and caches the metadata in the client instance. See [Metadata Fields and Validation]({% link smart-on-fhir/discovery/metadata.md %}) for the full field reference and validation rules.
+
+---
+
+## Step 2: Authorization Request
+
+Generate the authorization URL and redirect the user to the SMART authorization server.
+
+```ruby
+def launch
+  auth_data = @client.authorization_url
+
+  # Store state and code_verifier server-side (never expose to client)
+  session[:oauth_state]   = auth_data[:state]
+  session[:code_verifier] = auth_data[:code_verifier]
+
+  redirect_to auth_data[:auth_url], allow_other_host: true
+end
+```
+
+`authorization_url` returns:
+
+```ruby
+auth_data
+# => {
+#   auth_url:      "https://fhir.example.com/authorize?response_type=code&client_id=...",
+#   state:         "5b03ee70c3ff6b00e7fcd78227fb4bff",   # 32 hex chars (128 bits)
+#   code_verifier: "nioBARPNwPA8JvVQdZUPxTk6f..."        # 128 characters
+# }
+```
+
+{: .important }
+> Each call to `authorization_url` generates a fresh `state` and `code_verifier`. Never reuse values across authorization attempts.
+
+The generated URL includes these parameters:
+
+| Parameter | Value |
+|-----------|-------|
+| `response_type` | `code` |
+| `client_id` | Your registered client identifier |
+| `redirect_uri` | Your callback URL |
+| `scope` | Requested permissions (space-separated) |
+| `state` | CSRF protection token (32 hex chars) |
+| `aud` | FHIR server being accessed |
+| `code_challenge_method` | `S256` |
+| `code_challenge` | `Base64URL(SHA256(code_verifier))` |
+
+{: .note }
+> **POST-Based Authorization** — If the server advertises the `authorize-post` capability, pass `method: :post` to submit the request as a form POST instead of a GET redirect. See [POST-Based Authorization]({% link smart-on-fhir/post-based-authorization.md %}) for details.
+
+---
+
+## EHR-Initiated Launch
+
+When a launch is initiated from within an EHR (rather than standalone), the EHR provides a `launch` token as a query parameter. Pass it to `authorization_url`:
+
+```ruby
+def ehr_launch
+  launch_token = params[:launch]
+
+  auth_data = @client.authorization_url(launch: launch_token)
+
+  session[:oauth_state]   = auth_data[:state]
+  session[:code_verifier] = auth_data[:code_verifier]
+
+  redirect_to auth_data[:auth_url], allow_other_host: true
+end
+```
+
+The `launch` parameter is included in the authorization URL. The EHR uses it to convey context (patient, encounter) that the authorization server will include in the token response.
+
+---
+
+**Next:** [Token Exchange & Refresh]({% link smart-on-fhir/public-client/token-exchange.md %})

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

@@ -0,0 +1,80 @@
+---
+layout: default
+title: Public Client Workflow
+parent: SMART on FHIR
+nav_order: 2
+has_children: true
+permalink: /smart-on-fhir/public-client/
+---
+
+# Public Client Workflow
+
+{: .no_toc }
+
+<div class="code-example" markdown="1">
+This guide demonstrates SMART on FHIR public client integration in a **Rails application**. The patterns shown here can be adapted for Sinatra or other Ruby web frameworks.
+</div>
+
+---
+
+## Overview
+
+Public clients are applications that cannot securely store a client secret, such as:
+- Browser-based single-page applications (SPAs)
+- Native mobile applications
+- Desktop applications distributed to end users
+
+Because there is no shared secret, public clients use **PKCE (Proof Key for Code Exchange)** to prove that the party exchanging an authorization code is the same party that initiated the request. This protects against authorization code interception attacks.
+
+---
+
+## PKCE at a Glance
+
+PKCE is built into Safire — you do not implement it yourself. Here is how it works:
+
+1. **Code Verifier** — Safire generates a cryptographically random 128-character string on each launch
+2. **Code Challenge** — Safire computes `Base64URL(SHA256(verifier))` and sends it with the authorization request
+3. **Verification** — When you exchange the authorization code for tokens, you send the original verifier; the server re-computes the hash and confirms it matches
+
+Store the code verifier server-side only and delete it immediately after the token exchange. See the [Security Guide]({{ site.baseurl }}/security/#pkce-code-verifier) for handling rules.
+
+---
+
+## Client Setup
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  get '/auth/launch',    to: 'smart_auth#launch'
+  get '/auth/callback',  to: 'smart_auth#callback'
+end
+
+# app/controllers/smart_auth_controller.rb
+class SmartAuthController < ApplicationController
+  before_action :initialize_client
+
+  private
+
+  def initialize_client
+    config = Safire::ClientConfig.new(
+      base_url:      ENV['FHIR_BASE_URL'],
+      client_id:     ENV['SMART_CLIENT_ID'],
+      redirect_uri:  callback_url,
+      scopes:        ['openid', 'profile', 'patient/*.read']
+    )
+
+    @client = Safire::Client.new(config, client_type: :public) # :public is the default client_type, so can omit to pass this.
+  end
+end
+```
+
+No `client_secret` is configured — public clients authenticate using PKCE only.
+
+---
+
+## What's Next
+
+- [Authorization]({% link smart-on-fhir/public-client/authorization.md %}) — Discovery and generating the authorization URL
+- [Token Exchange & Refresh]({% link smart-on-fhir/public-client/token-exchange.md %}) — Exchanging the code, refreshing tokens, and error handling
+- [Security Guide]({{ site.baseurl }}/security/) — Token storage, CSRF protection, scope minimization
+- [Advanced Examples]({{ site.baseurl }}/advanced/) — Complete Rails controller, caching, multi-server, and retry patterns

data/docs/smart-on-fhir/public-client/token-exchange.md

@@ -0,0 +1,249 @@
+---
+layout: default
+title: Token Exchange & Refresh
+parent: Public Client Workflow
+grand_parent: SMART on FHIR
+nav_order: 2
+---
+
+# Token Exchange & Refresh
+
+{: .no_toc }
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Step 3: Token Exchange
+
+After the user authorizes, the server redirects to your callback with an authorization code. Exchange it for tokens.
+
+```ruby
+def callback
+  # Verify state parameter (CSRF protection)
+  unless params[:state] == session[:oauth_state]
+    Rails.logger.error("State mismatch: expected #{session[:oauth_state]}, got #{params[:state]}")
+    render plain: 'Invalid state parameter', status: :unauthorized
+    return
+  end
+
+  tokens = @client.request_access_token(
+    code:          params[:code],
+    code_verifier: session[:code_verifier]
+  )
+
+  # Store tokens server-side only
+  session[:access_token]     = tokens['access_token']
+  session[:refresh_token]    = tokens['refresh_token']
+  session[:token_expires_at] = Time.current + tokens['expires_in'].seconds
+
+  # SMART context parameters
+  session[:patient_id]   = tokens['patient']   if tokens['patient']
+  session[:encounter_id] = tokens['encounter'] if tokens['encounter']
+
+  # Clean up authorization state immediately
+  session.delete(:oauth_state)
+  session.delete(:code_verifier)
+
+  redirect_to patient_path(session[:patient_id])
+rescue Safire::Errors::TokenError => e
+  Rails.logger.error("Token exchange failed: #{e.message}")
+  render plain: 'Authorization failed', status: :unauthorized
+end
+```
+
+Safire sends:
+
+```http
+POST /token HTTP/1.1
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=authorization_code&
+code=AUTH_CODE_FROM_CALLBACK&
+redirect_uri=https://myapp.example.com/callback&
+code_verifier=nioBARPNwPA8JvVQdZUPxTk6f...&
+client_id=my_public_client
+```
+
+{: .note }
+> Public clients include `client_id` in the request body. No `Authorization` header or `client_secret` is sent.
+
+The token response includes:
+
+```ruby
+tokens
+# => {
+#   "access_token"  => "eyJhbGci...",
+#   "token_type"    => "Bearer",
+#   "expires_in"    => 3600,
+#   "scope"         => "openid profile patient/*.read",
+#   "refresh_token" => "eyJhbGci...",
+#   "patient"       => "123",    # SMART context (if present)
+#   "encounter"     => "456",    # SMART context (if present)
+#   "id_token"      => "eyJ..."  # OpenID Connect (if requested)
+# }
+```
+
+See the [Security Guide]({{ site.baseurl }}/security/#token-and-session-security) for token storage rules.
+
+---
+
+## Step 4: Token Refresh
+
+Use a controller concern to automatically refresh tokens before they expire.
+
+```ruby
+# app/controllers/concerns/smart_authentication.rb
+module SmartAuthentication
+  extend ActiveSupport::Concern
+
+  included do
+    before_action :ensure_authenticated
+    before_action :ensure_valid_token
+  end
+
+  private
+
+  def ensure_authenticated
+    unless session[:access_token]
+      redirect_to launch_path, alert: 'Please sign in to continue.'
+    end
+  end
+
+  def ensure_valid_token
+    return unless session[:access_token] && session[:token_expires_at]
+    refresh_access_token if session[:token_expires_at] < 5.minutes.from_now
+  end
+
+  def refresh_access_token
+    return unless session[:refresh_token]
+
+    new_tokens = build_smart_client.refresh_token(
+      refresh_token: session[:refresh_token]
+    )
+
+    session[:access_token]     = new_tokens['access_token']
+    session[:token_expires_at] = Time.current + new_tokens['expires_in'].seconds
+    session[:refresh_token]    = new_tokens['refresh_token'] if new_tokens['refresh_token']
+  rescue Safire::Errors::TokenError => e
+    Rails.logger.error("Token refresh failed: #{e.message}")
+    clear_auth_session
+    redirect_to launch_path, alert: 'Your session has expired. Please sign in again.'
+  end
+
+  def clear_auth_session
+    session.delete(:access_token)
+    session.delete(:refresh_token)
+    session.delete(:token_expires_at)
+    session.delete(:patient_id)
+    session.delete(:encounter_id)
+  end
+
+  def build_smart_client
+    config = Safire::ClientConfig.new(
+      base_url:     ENV['FHIR_BASE_URL'],
+      client_id:    ENV['SMART_CLIENT_ID'],
+      redirect_uri: callback_url,
+      scopes:       ['openid', 'profile', 'patient/*.read']
+    )
+    Safire::Client.new(config, client_type: :public)
+  end
+end
+```
+
+**Reduced scopes on refresh** — request a subset of the original grant:
+
+```ruby
+client.refresh_token(
+  refresh_token: session[:refresh_token],
+  scopes: ['patient/Patient.read'] # Must be a subset of the original
+)
+```
+
+---
+
+## Error Handling
+
+| Error code | Meaning | Suggested action |
+|------------|---------|-----------------|
+| `invalid_grant` | Code expired or already used | Redirect to launch |
+| `invalid_client` | Client ID not recognised | Log and return 500 — configuration issue |
+
+```ruby
+rescue Safire::Errors::TokenError => e
+  case e.error_code
+  when 'invalid_grant'
+    redirect_to launch_path, alert: 'Authorization code expired. Please try again.'
+  when 'invalid_client'
+    Rails.logger.error("Invalid client configuration: #{e.message}")
+    render plain: 'Configuration error', status: :internal_server_error
+  else
+    Rails.logger.error("Token exchange failed: #{e.message}")
+    render plain: 'Authorization failed', status: :unauthorized
+  end
+```
+
+**Discovery errors** — catch early to surface server availability issues:
+
+```ruby
+def initialize_client
+  # ...
+  @client.server_metadata # Trigger discovery eagerly if desired
+rescue Safire::Errors::DiscoveryError => e
+  Rails.logger.error("SMART discovery failed: #{e.message}")
+  render plain: 'FHIR server not available', status: :service_unavailable
+end
+```
+
+---
+
+## Testing Your Integration
+
+Set up against the [SMART Health IT reference server](https://launch.smarthealthit.org):
+
+```bash
+# .env.development
+FHIR_BASE_URL=https://launch.smarthealthit.org/v/r4/sim/eyJoIjoiMSJ9/fhir
+SMART_CLIENT_ID=your_test_client_id
+```
+
+Steps:
+1. Register your client with redirect URI `http://localhost:3000/auth/callback`
+2. Start your Rails server: `rails s`
+3. Visit `http://localhost:3000/auth/launch`
+4. Complete the flow on the reference server
+5. Verify the callback receives tokens with SMART context
+
+```ruby
+# spec/requests/smart_auth_spec.rb
+RSpec.describe 'SMART Public Client Flow', type: :request do
+  before do
+    stub_request(:get, "#{ENV['FHIR_BASE_URL']}/.well-known/smart-configuration")
+      .to_return(status: 200, body: {
+        authorization_endpoint:          "#{ENV['FHIR_BASE_URL']}/authorize",
+        token_endpoint:                  "#{ENV['FHIR_BASE_URL']}/token",
+        capabilities:                    ['launch-standalone', 'client-public'],
+        code_challenge_methods_supported: ['S256']
+      }.to_json)
+  end
+
+  it 'generates authorization URL and stores state' do
+    get '/auth/launch'
+
+    expect(response).to redirect_to(/authorize/)
+    expect(session[:oauth_state].length).to eq(32)
+    expect(session[:code_verifier].length).to eq(128)
+  end
+end
+```
+
+{: .note }
+> A complete Rails controller implementation is available in the [Advanced Examples]({{ site.baseurl }}/advanced/) guide.
+
+---
+
+**See also:** [Security Guide]({{ site.baseurl }}/security/) · [Troubleshooting]({% link troubleshooting/index.md %}) · [SMART Discovery]({% link smart-on-fhir/discovery/index.md %})

data/docs/troubleshooting/auth-errors.md

@@ -0,0 +1,124 @@
+---
+layout: default
+title: Discovery and Authorization Errors
+parent: Troubleshooting
+nav_order: 1
+---
+
+# Discovery and Authorization Errors
+
+{: .no_toc }
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Discovery Errors
+
+### `DiscoveryError`: Failed to discover SMART configuration
+
+```
+Safire::Errors::DiscoveryError: Failed to discover SMART configuration from
+https://fhir.example.com/.well-known/smart-configuration (HTTP 404)
+```
+
+**Causes:** the server does not support SMART on FHIR, `base_url` includes an extra path segment, or the server uses a non-standard discovery path.
+
+Verify the endpoint manually:
+
+```bash
+curl -I https://fhir.example.com/.well-known/smart-configuration
+```
+
+Ensure `base_url` points to the FHIR root, not a resource path:
+
+```ruby
+# ✅ Correct
+base_url: 'https://fhir.example.com/r4'
+
+# ❌ Too specific — strip the resource type
+base_url: 'https://fhir.example.com/r4/Patient'
+```
+
+If the server does not support discovery, provide endpoints manually in `ClientConfig`:
+
+```ruby
+config = Safire::ClientConfig.new(
+  base_url:               'https://fhir.example.com',
+  client_id:              'my_client',
+  redirect_uri:           'https://myapp.com/callback',
+  scopes:                 ['openid', 'profile'],
+  authorization_endpoint: 'https://fhir.example.com/authorize',
+  token_endpoint:         'https://fhir.example.com/token'
+)
+```
+
+### `DiscoveryError`: Invalid SMART configuration format
+
+```
+Safire::Errors::DiscoveryError: ... response is not a JSON object
+```
+
+The server returned an HTML error page, a JSON array, or malformed JSON. Inspect the raw response:
+
+```bash
+curl https://fhir.example.com/.well-known/smart-configuration
+```
+
+The response must be a JSON object (`{...}`) with at least `authorization_endpoint` and `token_endpoint`.
+
+---
+
+## Authorization Errors
+
+### `ConfigurationError`: Missing scopes
+
+```
+Safire::Errors::ConfigurationError: Configuration missing: scopes
+```
+
+Scopes must be provided either in `ClientConfig` or when calling `authorization_url`:
+
+```ruby
+# Option 1 — in config
+config = Safire::ClientConfig.new(
+  scopes: ['openid', 'profile', 'patient/*.read'],
+  # ...
+)
+
+# Option 2 — per request
+auth_data = client.authorization_url(
+  custom_scopes: ['openid', 'profile', 'patient/Patient.read']
+)
+```
+
+### State mismatch on callback
+
+**Symptom:** authorization callback fails or state validation raises an error.
+
+**Causes:** state not stored in session before redirect, session expired, or multiple tabs in flight.
+
+Always store both `state` and `code_verifier` before redirecting, and validate `state` immediately on callback:
+
+```ruby
+# On launch
+auth_data = client.authorization_url
+session[:oauth_state]   = auth_data[:state]
+session[:code_verifier] = auth_data[:code_verifier]
+redirect_to auth_data[:auth_url], allow_other_host: true
+
+# On callback
+unless params[:state] == session[:oauth_state]
+  render plain: 'Invalid state', status: :unauthorized
+  return
+end
+
+# Delete immediately after use
+session.delete(:oauth_state)
+```
+
+If the session has expired by the time the user returns, redirect them back to the launch endpoint with a user-friendly message rather than showing a raw error.

data/docs/troubleshooting/client-errors.md

@@ -0,0 +1,130 @@
+---
+layout: default
+title: Confidential Client and Network Errors
+parent: Troubleshooting
+nav_order: 3
+---
+
+# Confidential Client and Network Errors
+
+{: .no_toc }
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Confidential Symmetric Client Errors
+
+### `ConfigurationError`: Missing `client_secret`
+
+```
+Safire::Errors::ConfigurationError: Configuration missing: client_secret
+```
+
+`client_secret` must be present when using `:confidential_symmetric`:
+
+```ruby
+config = Safire::ClientConfig.new(
+  client_secret: ENV.fetch('SMART_CLIENT_SECRET'),
+  # ...
+)
+client = Safire::Client.new(config, client_type: :confidential_symmetric)
+```
+
+You can also pass it as an override directly to the token call — useful when rotating secrets:
+
+```ruby
+tokens = client.request_access_token(
+  code: code, code_verifier: verifier,
+  client_secret: ENV.fetch('SMART_CLIENT_SECRET')
+)
+```
+
+### `401 Unauthorized` with Basic Auth
+
+**Causes:** incorrect credentials, or the server does not support `client_secret_basic`.
+
+Verify the server supports Basic Auth before debugging credentials:
+
+```ruby
+metadata = client.server_metadata
+unless metadata.token_endpoint_auth_methods_supported.include?('client_secret_basic')
+  raise 'Server does not support client_secret_basic'
+end
+```
+
+Safire encodes credentials with `Base64.strict_encode64` — special characters in secrets are handled automatically.
+
+---
+
+## Confidential Asymmetric Client Errors
+
+### `ConfigurationError`: Missing `private_key` or `kid`
+
+```
+Safire::Errors::ConfigurationError: Configuration missing: private_key, kid
+```
+
+Both are required for `:confidential_asymmetric`:
+
+```ruby
+config = Safire::ClientConfig.new(
+  private_key: OpenSSL::PKey::RSA.new(File.read(ENV['SMART_PRIVATE_KEY_PATH'])),
+  kid:         ENV.fetch('SMART_KEY_ID'),
+  # ...
+)
+client = Safire::Client.new(config, client_type: :confidential_asymmetric)
+```
+
+### `401 Unauthorized` with JWT assertion
+
+**Causes:** key mismatch, wrong `kid`, clock skew, or server does not support `private_key_jwt`.
+
+Verify `private_key_jwt` is supported:
+
+```ruby
+metadata = client.server_metadata
+unless metadata.token_endpoint_auth_methods_supported.include?('private_key_jwt')
+  raise 'Server does not support private_key_jwt'
+end
+```
+
+Verify the public key registered with the server matches the private key you are using, and that the `kid` value matches the key ID the server expects. Safire sets JWT `exp` to 5 minutes from `iat` — if your system clock is significantly skewed from the server, assertions will be rejected.
+
+---
+
+## Network Errors
+
+### `NetworkError`: Connection refused or timeout
+
+```
+Safire::Errors::NetworkError: HTTP request failed: Connection refused
+```
+
+Verify server connectivity before debugging Safire configuration:
+
+```bash
+curl -v https://fhir.example.com/.well-known/smart-configuration
+```
+
+For transient network failures, implement retry with exponential backoff in your application — see [Advanced Examples]({{ site.baseurl }}/advanced/#token-management) for a reusable pattern.
+
+### `NetworkError`: Blocked redirect to non-HTTPS URL
+
+```
+Safire::Errors::NetworkError: Blocked redirect to non-HTTPS URL: http://fhir.example.com/...
+```
+
+Safire blocks redirects to non-HTTPS URLs (except `localhost`). Configure `base_url` with the final HTTPS URL directly, bypassing any HTTP-to-HTTPS redirect the server may use:
+
+```ruby
+# ✅ Use the final HTTPS URL directly
+base_url: 'https://fhir.example.com/r4'
+
+# ❌ Will fail if the server redirects HTTP → HTTPS
+base_url: 'http://fhir.example.com/r4'
+```