safire 0.1.0

data/docs/security.md

@@ -0,0 +1,256 @@
+---
+layout: default
+title: Security Guide
+nav_order: 6
+permalink: /security/
+---
+
+# Security Guide
+
+{: .no_toc }
+
+This guide covers security requirements and best practices for every Safire integration, regardless of client type. Apply these rules in all production deployments.
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## HTTPS and Redirect URI Rules
+
+All production FHIR integrations must use HTTPS. Safire enforces this at configuration time — HTTP redirect URIs are rejected in non-localhost environments.
+
+```ruby
+# config/environments/production.rb
+config.force_ssl = true
+```
+
+```ruby
+# ✅ Always use HTTPS in production
+config = Safire::ClientConfig.new(
+  redirect_uri: 'https://myapp.example.com/auth/callback',
+  # ...
+)
+
+# ❌ Raises Safire::Errors::ConfigurationError
+config = Safire::ClientConfig.new(
+  redirect_uri: 'http://myapp.example.com/auth/callback',
+  # ...
+)
+```
+
+Localhost is permitted during development:
+
+```ruby
+# ✅ Allowed for local development only
+redirect_uri: 'http://localhost:3000/auth/callback'
+```
+
+---
+
+## Credential Protection
+
+Never expose client secrets or private keys in logs, responses, or version control.
+
+### Client Secrets (Confidential Symmetric)
+
+```ruby
+# ❌ NEVER: log the secret
+Rails.logger.info("Using secret: #{client_secret}")
+
+# ❌ NEVER: render in a response
+render json: { client_secret: ENV['SMART_CLIENT_SECRET'] }
+
+# ❌ NEVER: commit .env to version control
+# Add to .gitignore: .env
+```
+
+Load secrets from a secure source:
+
+```ruby
+# Environment variable
+config = Safire::ClientConfig.new(
+  client_secret: ENV.fetch('SMART_CLIENT_SECRET'),
+  # ...
+)
+
+# Rails credentials
+config = Safire::ClientConfig.new(
+  client_secret: Rails.application.credentials.smart[:client_secret],
+  # ...
+)
+
+# AWS Secrets Manager
+require 'aws-sdk-secretsmanager'
+
+def fetch_client_secret
+  client = Aws::SecretsManager::Client.new
+  secret = client.get_secret_value(secret_id: 'smart/credentials')
+  JSON.parse(secret.secret_string)['client_secret']
+end
+```
+
+### Private Keys (Confidential Asymmetric)
+
+```ruby
+# ❌ NEVER: render or log the key
+render json: { private_key: @private_key.to_pem }
+
+# Add to .gitignore: *.pem, *.key
+```
+
+Load private keys securely:
+
+```ruby
+# From a file path
+private_key = OpenSSL::PKey::RSA.new(File.read(ENV['SMART_PRIVATE_KEY_PATH']))
+
+# From a PEM string in an env var
+private_key = OpenSSL::PKey::RSA.new(ENV['SMART_PRIVATE_KEY_PEM'])
+
+# From Rails credentials
+private_key = OpenSSL::PKey::RSA.new(
+  Rails.application.credentials.smart[:private_key_pem]
+)
+
+# From AWS Secrets Manager
+def fetch_private_key
+  client = Aws::SecretsManager::Client.new
+  secret = client.get_secret_value(secret_id: 'smart/private-key')
+  OpenSSL::PKey::RSA.new(secret.secret_string)
+end
+```
+
+Use strong keys:
+
+```ruby
+# RSA: minimum 2048-bit, 4096-bit recommended
+key = OpenSSL::PKey::RSA.generate(4096)
+
+# EC: must use P-384 curve (required by SMART spec for ES384)
+key = OpenSSL::PKey::EC.generate('secp384r1')
+```
+
+{: .note }
+> Safire automatically masks `client_secret` and `private_key` in `inspect` output and error messages, so they will not appear in Rails logs even if a `ClientConfig` object is accidentally logged.
+
+---
+
+## Token and Session Security
+
+### Token Storage
+
+Always store tokens server-side. Never expose them to client-side code.
+
+```ruby
+# ✅ DO: Server-side session
+session[:access_token] = tokens['access_token']
+
+# ✅ DO: Encrypted database column
+user.update(encrypted_access_token: cipher.encrypt(tokens['access_token']))
+
+# ❌ DON'T: Plain cookie
+cookies[:access_token] = tokens['access_token']
+
+# ❌ DON'T: JSON response to the browser
+render json: { access_token: tokens['access_token'] }
+```
+
+### CSRF State Parameter
+
+Safire generates a 32-character hex state value (128 bits of entropy) automatically. Always verify it on callback and delete it immediately after:
+
+```ruby
+def callback
+  unless params[:state] == session[:oauth_state]
+    render plain: 'Invalid state', status: :unauthorized
+    return
+  end
+
+  # ... exchange code for tokens ...
+
+  session.delete(:oauth_state)   # ✅ Delete after validation
+  session.delete(:code_verifier) # ✅ Delete after token exchange
+end
+```
+
+### PKCE Code Verifier
+
+Safire generates the code verifier automatically. Store it server-side only and discard it immediately after the token exchange — never send it to the client or include it in a URL.
+
+```ruby
+# Store on launch
+session[:code_verifier] = auth_data[:code_verifier]
+
+# Delete immediately after exchange
+session.delete(:code_verifier)
+```
+
+---
+
+## Key Rotation and Scope Minimization
+
+### Symmetric Secret Rotation
+
+Support two secrets during rotation to allow a zero-downtime rollover:
+
+```ruby
+module SmartSecretRotation
+  def build_smart_client
+    create_client(primary_secret)
+  rescue Safire::Errors::TokenError => e
+    raise unless e.error_code == 'invalid_client'
+    create_client(secondary_secret) # Fall back during rotation
+  end
+
+  def primary_secret   = ENV['SMART_CLIENT_SECRET']
+  def secondary_secret = ENV['SMART_CLIENT_SECRET_PREVIOUS']
+end
+```
+
+### Asymmetric Key Rotation
+
+Publish both old and new public keys simultaneously in your JWKS endpoint during rotation:
+
+```json
+{
+  "keys": [
+    { "kid": "key-v1", "kty": "RSA", "use": "sig", ... },
+    { "kid": "key-v2", "kty": "RSA", "use": "sig", ... }
+  ]
+}
+```
+
+Rotation steps:
+1. Generate a new key pair with a new `kid`
+2. Add the new public key to your JWKS endpoint
+3. Update your application to use the new private key
+4. Remove the old public key from JWKS after a grace period (allow in-flight tokens to expire)
+
+### Scope Minimization
+
+Request only the scopes your application needs. Broad wildcard scopes increase the impact of a compromised token.
+
+```ruby
+# ✅ Request specific resource types
+scopes: ['patient/Patient.read', 'patient/Observation.read']
+
+# ❌ Avoid unless truly necessary
+scopes: ['patient/*.*']
+```
+
+You can also reduce scopes at refresh time:
+
+```ruby
+client.refresh_token(
+  refresh_token: session[:refresh_token],
+  scopes: ['patient/Patient.read'] # Must be a subset of the original grant
+)
+```
+
+---
+
+*See also: [Configuration Guide]({{ site.baseurl }}/configuration/) for `ssl_options` and `log_http` settings that affect security behaviour.*

data/docs/smart-on-fhir/confidential-asymmetric/authorization.md

@@ -0,0 +1,72 @@
+---
+layout: default
+title: Authorization
+parent: Confidential Asymmetric 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. Check that the server supports `private_key_jwt` and your preferred signing algorithm.
+
+```ruby
+def check_server_capabilities
+  metadata = @client.server_metadata
+
+  unless metadata.supports_asymmetric_auth?
+    raise 'Server does not support confidential asymmetric clients'
+  end
+
+  auth_methods = metadata.token_endpoint_auth_methods_supported
+  algorithms   = metadata.asymmetric_signing_algorithms_supported
+
+  render json: {
+    supports_asymmetric:     true,
+    auth_methods:            auth_methods,
+    signing_algorithms:      algorithms,
+    supports_private_key_jwt: auth_methods&.include?('private_key_jwt'),
+    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, including `asymmetric_signing_algorithms_supported`.
+
+---
+
+## Step 2: Authorization Request
+
+Authorization URL generation is identical to other client types — 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 other client types. The difference surfaces at token exchange, where Safire replaces the authorization header with a signed JWT assertion in the request body.
+
+{: .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-asymmetric/token-exchange.md %})

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

@@ -0,0 +1,162 @@
+---
+layout: default
+title: Confidential Asymmetric Client Workflow
+parent: SMART on FHIR
+nav_order: 4
+has_children: true
+permalink: /smart-on-fhir/confidential-asymmetric/
+---
+
+# Confidential Asymmetric Client Workflow
+
+{: .no_toc }
+
+<div class="code-example" markdown="1">
+This guide demonstrates SMART on FHIR confidential asymmetric client integration in a **Rails application**. The patterns shown here can be adapted for Sinatra or other Ruby web frameworks.
+</div>
+
+---
+
+## Overview
+
+Confidential asymmetric clients authenticate using **`private_key_jwt`** — a signed JWT assertion built from your RSA or EC private key — instead of a shared client secret. This is the most secure SMART client authentication method and is recommended for many production healthcare deployments.
+
+Safire implements `private_key_jwt` per [SMART App Launch STU 2.2.0](https://hl7.org/fhir/smart-app-launch/client-confidential-asymmetric.html).
+
+Suitable for:
+- Backend services where sharing a secret out-of-band is impractical
+- Multi-tenant platforms where independent key rotation per tenant is valuable
+- Deployments requiring the highest level of client authentication assurance
+
+---
+
+## Key Differences from Other Client Types
+
+| Aspect | Public | Confidential Symmetric | Confidential Asymmetric |
+|--------|--------|------------------------|-------------------------|
+| **Credential** | None | Shared `client_secret` | RSA or EC private key |
+| **Token Request Auth** | `client_id` in body | `Authorization: Basic` header | JWT assertion in body |
+| **Key Rotation** | N/A | Coordinated secret change | Publish new public key, rotate independently |
+| **Algorithms** | N/A | N/A | RS384 or ES384 |
+| **PKCE** | Required | Required | Required |
+
+{: .important }
+> **PKCE is still required.** The JWT assertion authenticates the *client*; PKCE protects the *authorization code exchange*. They serve different purposes.
+
+---
+
+## Prerequisites: Keys, JWKS, and Algorithm
+
+Before writing any flow code, you need a key pair, a key ID, and a way for the authorization server to verify your public key.
+
+### Generating a Key Pair
+
+```bash
+# RSA key (2048-bit minimum, 4096-bit recommended)
+openssl genrsa -out private_key.pem 4096
+openssl rsa -in private_key.pem -pubout -out public_key.pem
+
+# --- OR ---
+
+# EC key (P-384 curve, required for ES384)
+openssl ecparam -name secp384r1 -genkey -noout -out private_key_ec.pem
+openssl ec -in private_key_ec.pem -pubout -out public_key_ec.pem
+```
+
+Add `*.pem` and `*.key` to `.gitignore`. See the [Security Guide]({{ site.baseurl }}/security/#private-keys-confidential-asymmetric) for loading keys securely in production.
+
+### Publishing Your Public Key (JWKS)
+
+The authorization server must know your public key. Host a JWKS endpoint:
+
+```json
+{
+  "keys": [
+    {
+      "kty": "RSA",
+      "kid": "my-key-id-123",
+      "use": "sig",
+      "alg": "RS384",
+      "n":   "<base64url-encoded modulus>",
+      "e":   "AQAB"
+    }
+  ]
+}
+```
+
+If you provide a `jwks_uri` in your Safire config, it is included as the `jku` header in JWT assertions so the server can locate your public key automatically.
+
+### JWT Assertion Structure
+
+Safire builds the following JWT assertion (sent as `client_assertion` in every token request):
+
+```mermaid
+flowchart LR
+    subgraph Header["JOSE Header"]
+        H1["alg: RS384 or ES384"]
+        H2["kid: key ID"]
+        H3["jku: JWKS URI (optional)"]
+    end
+
+    subgraph Claims["JWT Claims"]
+        C1["iss: client_id"]
+        C2["sub: client_id"]
+        C3["aud: token_endpoint"]
+        C4["jti: unique random ID"]
+        C5["iat: issued at"]
+        C6["exp: iat + 5 minutes"]
+    end
+
+    PK["Private Key\n(RSA or EC)"]
+
+    Header --> JWT
+    Claims --> JWT
+    PK -->|signs| JWT["Signed JWT Assertion\n(client_assertion)"]
+```
+
+### Algorithm Selection
+
+Safire supports the two algorithms required by the SMART specification:
+
+| Algorithm | Key Type | Use Case |
+|-----------|----------|----------|
+| **RS384** | RSA | Most common, widest server support |
+| **ES384** | EC, P-384 curve | Smaller keys, faster signing |
+
+Safire auto-detects the algorithm from the key type — no explicit configuration needed:
+
+```ruby
+# RSA key → RS384 automatically
+config = Safire::ClientConfig.new(private_key: OpenSSL::PKey::RSA.new(...), kid: 'my-rsa-key', ...)
+
+# EC key → ES384 automatically
+config = Safire::ClientConfig.new(private_key: OpenSSL::PKey::EC.generate('secp384r1'), kid: 'my-ec-key', ...)
+
+# Override explicitly if needed
+config = Safire::ClientConfig.new(private_key: rsa_key, kid: 'my-key', jwt_algorithm: 'RS384', ...)
+```
+
+### Client Setup
+
+```ruby
+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'] # Optional
+)
+
+@client = Safire::Client.new(config, client_type: :confidential_asymmetric)
+```
+
+---
+
+## What's Next
+
+- [Authorization]({% link smart-on-fhir/confidential-asymmetric/authorization.md %}) — Discovery and generating the authorization URL
+- [Token Exchange & Refresh]({% link smart-on-fhir/confidential-asymmetric/token-exchange.md %}) — JWT assertion token requests, refresh, and error handling
+- [Security Guide]({{ site.baseurl }}/security/) — Private key management and rotation
+- [Advanced Examples]({{ site.baseurl }}/advanced/) — Complete Rails controller, caching, multi-server, and retry patterns