safire 0.1.0

data/docs/smart-on-fhir/confidential-asymmetric/token-exchange.md

@@ -0,0 +1,250 @@
+---
+layout: default
+title: Token Exchange & Refresh
+parent: Confidential Asymmetric 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
+
+Instead of a shared secret, Safire generates a signed JWT assertion and includes it in the request body. Your application code looks identical to other client types.
+
+```ruby
+def callback
+  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
+
+  # Safire generates and signs a JWT assertion automatically
+  tokens = @client.request_access_token(
+    code:          params[:code],
+    code_verifier: session[:code_verifier]
+  )
+
+  session[:access_token]     = tokens['access_token']
+  session[:refresh_token]    = tokens['refresh_token']
+  session[:token_expires_at] = Time.current + tokens['expires_in'].seconds
+  session[:patient_id]       = tokens['patient']   if tokens['patient']
+  session[:encounter_id]     = tokens['encounter'] if tokens['encounter']
+
+  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_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&
+client_assertion=eyJhbGciOiJSUzM4NCIsInR5cCI6IkpXVCIsImtpZCI6Im15LWtleS1pZCJ9...
+```
+
+{: .important }
+> No `Authorization` header is sent. The `client_id` is inside the JWT assertion, not in the request body.
+
+**What Safire does automatically** when `client_type: :confidential_asymmetric`:
+
+1. Builds a JWT assertion with the required claims
+2. Signs the JWT using your private key and the detected or configured algorithm
+3. Adds `client_assertion_type` and `client_assertion` to the request body
+4. Generates a fresh assertion per request (unique `jti`, updated `exp`)
+
+**JWT assertion structure:**
+
+| Field | Value |
+|-------|-------|
+| Header `alg` | `RS384` or `ES384` |
+| Header `kid` | Your registered key ID |
+| Header `jku` | Your JWKS URI (if configured) |
+| Claim `iss` | `client_id` |
+| Claim `sub` | `client_id` |
+| Claim `aud` | Token endpoint URL |
+| Claim `exp` | `now + 300s` (5 minutes max per spec) |
+| Claim `jti` | UUID (replay protection) |
+
+---
+
+## Step 4: Token Refresh
+
+Each refresh request generates a fresh JWT assertion automatically.
+
+```ruby
+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]
+
+    # Fresh JWT assertion generated automatically per request
+    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
+    %i[access_token refresh_token token_expires_at patient_id encounter_id].each do |key|
+      session.delete(key)
+    end
+  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', 'offline_access'],
+      private_key:  OpenSSL::PKey::RSA.new(File.read(ENV['SMART_PRIVATE_KEY_PATH'])),
+      kid:          ENV['SMART_KEY_ID'],
+      jwks_uri:     ENV['SMART_JWKS_URI']
+    )
+    Safire::Client.new(config, client_type: :confidential_asymmetric)
+  end
+end
+```
+
+The refresh request includes a fresh JWT assertion:
+
+```http
+POST /token HTTP/1.1
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=refresh_token&
+refresh_token=eyJhbGciOiJub25lIn0...&
+client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&
+client_assertion=eyJhbGciOiJSUzM4NCJ9...
+```
+
+---
+
+## Error Handling
+
+| Error code | Meaning | Suggested action |
+|------------|---------|-----------------|
+| `invalid_client` | JWT assertion rejected (wrong key, bad signature, expired) | Log, check key config, return 500 |
+| `invalid_grant` | Code or refresh token expired | Redirect to launch |
+
+```ruby
+rescue Safire::Errors::TokenError => e
+  case e.error_code
+  when 'invalid_client'
+    Rails.logger.error("JWT assertion rejected: #{e.message}")
+    render plain: 'Client authentication failed', status: :unauthorized
+  when 'invalid_grant'
+    redirect_to launch_path, alert: 'Authorization expired. Please try again.'
+  else
+    Rails.logger.error("Token exchange failed: #{e.message}")
+    render plain: 'Authorization failed', status: :unauthorized
+  end
+```
+
+**Missing credentials** — if `private_key` or `kid` is absent, Safire raises before the HTTP call:
+
+```ruby
+rescue Safire::Errors::TokenError => e
+  if e.message.include?('Missing required asymmetric credentials')
+    Rails.logger.error("Asymmetric auth misconfigured: #{e.message}")
+    render plain: 'Server configuration error', status: :internal_server_error
+  else
+    raise
+  end
+```
+
+---
+
+## Testing Your Integration
+
+```bash
+# .env.development
+FHIR_BASE_URL=https://launch.smarthealthit.org/v/r4/sim/eyJoIjoiMSJ9/fhir
+SMART_CLIENT_ID=your_test_client_id
+SMART_PRIVATE_KEY_PATH=test/fixtures/private_key.pem
+SMART_KEY_ID=test-key-id
+```
+
+{: .note }
+> Register your public key at [https://launch.smarthealthit.org](https://launch.smarthealthit.org). The reference server supports `private_key_jwt`.
+
+```ruby
+RSpec.describe 'SMART Confidential Asymmetric Flow', type: :request do
+  it 'uses JWT assertion in body and sends no Authorization header' do
+    get '/auth/launch'
+    state = session[:oauth_state]
+
+    stub_request(:post, "#{ENV['FHIR_BASE_URL']}/token")
+      .to_return(status: 200, body: {
+        access_token: 'token_123', token_type: 'Bearer', expires_in: 3600
+      }.to_json)
+
+    get '/auth/callback', params: { code: 'auth_code', state: state }
+
+    expect(WebMock).to have_requested(:post, "#{ENV['FHIR_BASE_URL']}/token")
+      .with { |req|
+        body = URI.decode_www_form(req.body).to_h
+        body['client_assertion_type'] == 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer' &&
+          body['client_assertion'].present? &&
+          !body.key?('client_id') &&
+          !req.headers.key?('Authorization')
+      }
+  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/smart-on-fhir/confidential-symmetric/authorization.md

@@ -0,0 +1,75 @@
+---
+layout: default
+title: Authorization
+parent: Confidential Symmetric 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`. You can check server capabilities to confirm confidential symmetric support before proceeding.
+
+```ruby
+def check_server_capabilities
+  metadata = @client.server_metadata
+
+  unless metadata.supports_symmetric_auth?
+    raise 'Server does not support confidential symmetric clients'
+  end
+
+  auth_methods = metadata.token_endpoint_auth_methods_supported
+  unless auth_methods.include?('client_secret_basic')
+    raise 'Server does not support client_secret_basic'
+  end
+
+  render json: {
+    supports_confidential_symmetric: true,
+    auth_methods:                    auth_methods,
+    supports_offline_access:         metadata.scopes_supported&.include?('offline_access')
+  }
+end
+```
+
+See [SMART Discovery]({% link smart-on-fhir/discovery/metadata.md %}) for the full field reference and validation rules.
+
+---
+
+## Step 2: Authorization Request
+
+Authorization URL generation is identical to the public client flow — Safire handles PKCE automatically.
+
+```ruby
+def 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
+end
+```
+
+The generated URL parameters are identical to the public client. The only difference surfaces at token exchange, where Safire adds the `Authorization: Basic` header.
+
+{: .note }
+> **Offline Access** — Include `offline_access` in your scopes to obtain a refresh token for long-lived sessions.
+
+{: .note }
+> **POST-Based Authorization** — If the server advertises `authorize-post`, pass `method: :post` to `authorization_url`. See [POST-Based Authorization]({% link smart-on-fhir/post-based-authorization.md %}) for details.
+
+---
+
+**Next:** [Token Exchange & Refresh]({% link smart-on-fhir/confidential-symmetric/token-exchange.md %})

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

@@ -0,0 +1,69 @@
+---
+layout: default
+title: Confidential Symmetric Client Workflow
+parent: SMART on FHIR
+nav_order: 3
+has_children: true
+permalink: /smart-on-fhir/confidential-symmetric/
+---
+
+# Confidential Symmetric Client Workflow
+
+{: .no_toc }
+
+<div class="code-example" markdown="1">
+This guide demonstrates SMART on FHIR confidential symmetric client integration in a **Rails application**. The patterns shown here can be adapted for Sinatra or other Ruby web frameworks.
+</div>
+
+---
+
+## Overview
+
+Confidential symmetric clients are server-side applications that can securely store a shared `client_secret`. The secret is sent with every token request using **HTTP Basic Authentication**, providing an additional authentication layer on top of PKCE.
+
+Suitable for:
+- Traditional server-side web applications
+- Backend services with secure credential storage
+- Enterprise applications behind firewalls
+
+---
+
+## Key Differences from Public Clients
+
+| Aspect | Public Client | Confidential Symmetric |
+|--------|---------------|------------------------|
+| **Credential** | None | Shared `client_secret` |
+| **Token Request Auth** | `client_id` in body | `Authorization: Basic` header |
+| **Security Layer** | PKCE only | PKCE + client secret |
+| **Typical Use Case** | SPAs, mobile apps | Server-side apps |
+| **Offline Access** | Limited | Full support |
+
+{: .important }
+> **PKCE is still required.** The client secret provides an additional authentication layer, not a replacement for PKCE.
+
+---
+
+## Client Setup
+
+```ruby
+config = Safire::ClientConfig.new(
+  base_url:      ENV.fetch('FHIR_BASE_URL'),
+  client_id:     ENV.fetch('SMART_CLIENT_ID'),
+  client_secret: ENV.fetch('SMART_CLIENT_SECRET'),
+  redirect_uri:  callback_url,
+  scopes:        ['openid', 'profile', 'patient/*.read', 'offline_access']
+)
+
+@client = Safire::Client.new(config, client_type: :confidential_symmetric)
+```
+
+Load `client_secret` from an environment variable, Rails credentials, or a secrets manager — never hard-code it. See the [Security Guide]({{ site.baseurl }}/security/#credential-protection) for loading patterns and rotation.
+
+---
+
+## What's Next
+
+- [Authorization]({% link smart-on-fhir/confidential-symmetric/authorization.md %}) — Discovery and generating the authorization URL
+- [Token Exchange & Refresh]({% link smart-on-fhir/confidential-symmetric/token-exchange.md %}) — Basic auth token requests, refresh, and error handling
+- [Security Guide]({{ site.baseurl }}/security/) — Secret management and rotation
+- [Advanced Examples]({{ site.baseurl }}/advanced/) — Complete Rails controller, caching, multi-server, and retry patterns

data/docs/smart-on-fhir/confidential-symmetric/token-exchange.md

@@ -0,0 +1,215 @@
+---
+layout: default
+title: Token Exchange & Refresh
+parent: Confidential Symmetric 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
+
+This is where confidential symmetric clients differ from public clients. Safire automatically adds an `Authorization: Basic` header — your application code looks identical.
+
+```ruby
+def callback
+  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
+
+  # Safire uses Basic auth automatically for :confidential_symmetric
+  tokens = @client.request_access_token(
+    code:          params[:code],
+    code_verifier: session[:code_verifier]
+  )
+
+  session[:access_token]     = tokens['access_token']
+  session[:refresh_token]    = tokens['refresh_token']
+  session[:token_expires_at] = Time.current + tokens['expires_in'].seconds
+  session[:patient_id]       = tokens['patient']   if tokens['patient']
+  session[:encounter_id]     = tokens['encounter'] if tokens['encounter']
+
+  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
+Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=
+
+grant_type=authorization_code&
+code=AUTH_CODE_FROM_CALLBACK&
+redirect_uri=https://myapp.example.com/callback&
+code_verifier=nioBARPNwPA8JvVQdZUPxTk6f...
+```
+
+{: .important }
+> The Basic auth value is `Base64(client_id:client_secret)`. Safire constructs this automatically — `client_id` is **not** included in the request body for confidential symmetric clients.
+
+Safire does this automatically when `client_type: :confidential_symmetric`:
+1. Constructs the `Authorization: Basic` header from `client_id` and `client_secret`
+2. Excludes `client_id` from the request body
+3. Applies Basic auth to both token exchange and token refresh
+
+---
+
+## Step 4: Token Refresh
+
+```ruby
+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]
+
+    # Basic auth is applied automatically
+    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
+    %i[access_token refresh_token token_expires_at patient_id encounter_id].each do |key|
+      session.delete(key)
+    end
+  end
+
+  def build_smart_client
+    config = Safire::ClientConfig.new(
+      base_url:      ENV.fetch('FHIR_BASE_URL'),
+      client_id:     ENV.fetch('SMART_CLIENT_ID'),
+      client_secret: ENV.fetch('SMART_CLIENT_SECRET'),
+      redirect_uri:  callback_url,
+      scopes:        ['openid', 'profile', 'patient/*.read', 'offline_access']
+    )
+    Safire::Client.new(config, client_type: :confidential_symmetric)
+  end
+end
+```
+
+The refresh request uses Basic auth in the same way as the exchange:
+
+```http
+POST /token HTTP/1.1
+Content-Type: application/x-www-form-urlencoded
+Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=
+
+grant_type=refresh_token&
+refresh_token=eyJhbGciOiJub25lIn0...
+```
+
+---
+
+## Error Handling
+
+| Error code | Meaning | Suggested action |
+|------------|---------|-----------------|
+| `invalid_client` | Wrong `client_id` or `client_secret` | Log, alert ops team, return 500 |
+| `invalid_grant` | Code or refresh token expired | Redirect to launch |
+
+```ruby
+rescue Safire::Errors::TokenError => e
+  case e.error_code
+  when 'invalid_client'
+    Rails.logger.error('Invalid client credentials — check client_id and client_secret')
+    notify_operations_team('SMART client credentials invalid')
+    render plain: 'Configuration error', status: :internal_server_error
+  when 'invalid_grant'
+    redirect_to launch_path, alert: 'Authorization expired. Please try again.'
+  else
+    Rails.logger.error("Token exchange failed: #{e.message}")
+    render plain: 'Authorization failed', status: :unauthorized
+  end
+```
+
+---
+
+## Testing Your Integration
+
+```bash
+# .env.development
+FHIR_BASE_URL=https://launch.smarthealthit.org/v/r4/sim/eyJoIjoiMSJ9/fhir
+SMART_CLIENT_ID=your_test_client_id
+SMART_CLIENT_SECRET=your_test_secret
+```
+
+{: .note }
+> Register your client at [https://launch.smarthealthit.org](https://launch.smarthealthit.org). The reference server supports `client_secret_basic`.
+
+```ruby
+RSpec.describe 'SMART Confidential Symmetric Flow', type: :request do
+  it 'uses Basic auth header and excludes client_id from body' do
+    get '/auth/launch'
+    state = session[:oauth_state]
+
+    stub_request(:post, "#{ENV['FHIR_BASE_URL']}/token")
+      .to_return(status: 200, body: {
+        access_token: 'token_123', token_type: 'Bearer', expires_in: 3600
+      }.to_json)
+
+    get '/auth/callback', params: { code: 'auth_code', state: state }
+
+    expected_basic = Base64.strict_encode64("#{ENV['SMART_CLIENT_ID']}:#{ENV['SMART_CLIENT_SECRET']}")
+    expect(WebMock).to have_requested(:post, "#{ENV['FHIR_BASE_URL']}/token")
+      .with { |req|
+        req.headers['Authorization'] == "Basic #{expected_basic}" &&
+          !req.body.include?('client_id')
+      }
+  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 %})