safire 0.1.0

data/docs/adr/ADR-005-per-client-http-ownership.md

@@ -0,0 +1,58 @@
+---
+layout: default
+title: "ADR-005: Per-client HTTPClient ownership — no shared connection pool"
+parent: Architecture Decision Records
+nav_order: 5
+---
+
+# ADR-005: Per-client `HTTPClient` ownership — no shared connection pool
+
+**Status:** Accepted
+
+---
+
+## Context
+
+Safire needs to make HTTP requests for SMART discovery and token operations. The question is: at what scope should the HTTP client live?
+
+**Option A — Module-level singleton:** one `HTTPClient` shared across all `Safire::Client` instances.
+
+**Option B — Per-`Client` ownership:** each `Safire::Client` constructs and owns its `Protocols::Smart` instance, which in turn owns its own `HTTPClient`.
+
+A shared HTTP client creates several problems:
+
+1. **Thread safety:** Faraday connection objects are not documented as thread-safe. A shared connection used concurrently by multiple clients in a web application could produce race conditions in connection state.
+
+2. **Configuration isolation:** if different clients need different SSL configurations, timeouts, or user-agent strings, a shared client cannot serve them all without complex multiplexing logic.
+
+3. **Discovery cache isolation:** SMART discovery metadata is cached inside `Protocols::Smart`. If two clients point at different FHIR servers, their metadata must not bleed across — and the HTTP client that fetched the metadata is tightly coupled to the `Smart` instance that owns the cache. Sharing the HTTP client would require separating it from the cache, which defeats the clean ownership model.
+
+---
+
+## Decision
+
+Each `Protocols::Smart` instance creates and owns its own `Safire::HTTPClient`:
+
+```ruby
+def initialize(config, client_type: :public)
+  # ...
+  @http_client = Safire::HTTPClient.new
+end
+```
+
+The `HTTPClient` is not shared, not exposed publicly, and not accessible from `Safire::Client`. Its lifetime is tied to the `Protocols::Smart` instance, which is itself tied to a single `Safire::Client`.
+
+For callers managing multiple FHIR servers, the recommended pattern is a per-server client registry (see [Advanced Examples]({{ site.baseurl }}/advanced/#multi-server-management)).
+
+---
+
+## Consequences
+
+**Benefits:**
+- Each client is fully isolated — different SSL configs, timeouts, or FHIR servers do not interact
+- Thread-safe by design — no shared mutable state in the HTTP layer across clients
+- Discovery cache and HTTP client have the same lifetime and owner — no partial invalidation
+
+**Trade-offs:**
+- No connection pooling across clients — applications with many client instances make independent TCP connections per client; for most healthcare FHIR use cases (one or a few servers) this is not a significant concern
+- Each `Safire::Client.new` allocates a new Faraday connection object, even before any network call; this is a minor allocation cost mitigated by lazy protocol client construction (see [ADR-006]({% link adr/ADR-006-lazy-discovery.md %}))

data/docs/adr/ADR-006-lazy-discovery.md

@@ -0,0 +1,83 @@
+---
+layout: default
+title: "ADR-006: Lazy SMART discovery — no HTTP in constructors"
+parent: Architecture Decision Records
+nav_order: 6
+---
+
+# ADR-006: Lazy SMART discovery — no HTTP in constructors
+
+**Status:** Accepted
+
+---
+
+## Context
+
+SMART on FHIR clients need the authorization server's endpoints (`authorization_endpoint`, `token_endpoint`) to build authorization URLs and request tokens. These are obtained by fetching `/.well-known/smart-configuration`. There are two approaches:
+
+**Option A — eager discovery:** fetch metadata in `Smart#initialize`.
+
+```ruby
+def initialize(config, client_type: :public)
+  # ...
+  @server_metadata = fetch_metadata  # HTTP call here
+end
+```
+
+**Option B — lazy discovery:** defer the fetch until a method actually needs an endpoint.
+
+```ruby
+def server_metadata
+  @server_metadata ||= fetch_metadata  # HTTP call deferred
+end
+
+def authorization_endpoint
+  @authorization_endpoint ||= server_metadata.authorization_endpoint
+end
+```
+
+Eager discovery has a significant problem: it makes `Safire::Client.new` a network operation. Construction can fail with a network error, configuration validation occurs after a potentially slow HTTP round-trip, and there is no way to instantiate a client to inspect its configuration without triggering discovery. It also makes testing harder — every `Client.new` call requires a stub.
+
+A second concern is `client_type=` mutation. After discovery, a caller may want to switch client type based on what the server supports:
+
+```ruby
+client   = Safire::Client.new(config)
+metadata = client.server_metadata
+
+client.client_type = :confidential_symmetric if metadata.supports_symmetric_auth?
+```
+
+With eager discovery, changing `client_type` must not trigger re-discovery — the metadata is already fetched. This means decoupling the discovery result from construction is necessary regardless.
+
+---
+
+## Decision
+
+Discovery is lazy and memoised at the `Protocols::Smart` instance level:
+
+```ruby
+def server_metadata
+  return @server_metadata if @server_metadata
+
+  response = @http_client.get(well_known_endpoint)
+  @server_metadata = SmartMetadata.new(parse_discovery_body(response.body))
+end
+```
+
+`authorization_endpoint` and `token_endpoint` are also lazy — they fall back to `server_metadata` only when not manually configured in `ClientConfig`, avoiding a discovery call for clients with pre-known endpoints.
+
+`Safire::Client` memoises the protocol client itself (`@protocol_client ||= ...`), so changing `client_type=` reuses the existing `Protocols::Smart` instance — and thus its already-fetched `@server_metadata` — rather than constructing a new one. This is the mechanism that prevents double-discovery on `client_type=` changes.
+
+---
+
+## Consequences
+
+**Benefits:**
+- `Safire::Client.new` is instantaneous — no network calls, no stubs required at construction time
+- Configuration errors are raised before any HTTP call
+- Callers control when discovery happens — supports application-level caching patterns (see [Advanced Examples]({{ site.baseurl }}/advanced/#metadata-caching))
+- `client_type=` mutation preserves cached metadata — no re-discovery
+
+**Trade-offs:**
+- Discovery errors surface at first use (e.g. `authorization_url`), not at construction — callers must handle `Errors::DiscoveryError` in their flow logic rather than at the `new` call site
+- In-process metadata caching is per-instance only — across requests in a web app, callers must implement application-level caching (e.g. `Rails.cache`) to avoid repeated discovery HTTP calls

data/docs/adr/ADR-007-https-only-redirects-and-localhost-exception.md

@@ -0,0 +1,59 @@
+---
+layout: default
+title: "ADR-007: HTTPS-only redirect enforcement and localhost exception"
+parent: Architecture Decision Records
+nav_order: 7
+---
+
+# ADR-007: HTTPS-only redirect enforcement and localhost exception
+
+**Status:** Accepted
+
+---
+
+## Context
+
+SMART App Launch 2.2.0 requires TLS for all exchanges involving sensitive data. However, enforcing HTTPS at the URI validation layer (`ClientConfig`) is not sufficient on its own — an authorization server could respond to a legitimate HTTPS request with a redirect to an HTTP endpoint. Without enforcement at the HTTP layer, Safire would silently follow that redirect, potentially exposing tokens or authorization codes over an unencrypted connection.
+
+This is a known attack surface: a compromised or misconfigured server can use open redirects to redirect a client to an attacker-controlled HTTP endpoint.
+
+There is also a practical concern: developers running local FHIR servers (e.g. HAPI FHIR, Inferno test environments) use `http://localhost` or `http://127.0.0.1`. Blocking these in a development environment would make Safire unusable without a TLS termination proxy.
+
+---
+
+## Decision
+
+HTTPS is enforced at **two layers**, both with the same localhost exception:
+
+**Layer 1 — `ClientConfig` URI validation:** all URI attributes (`base_url`, `redirect_uri`, `issuer`, `authorization_endpoint`, `token_endpoint`, `jwks_uri`) must use `https://`, except when the host is `localhost` or `127.0.0.1`.
+
+**Layer 2 — `HttpsOnlyRedirects` Faraday middleware:** intercepts every 3xx response before `faraday-follow_redirects` follows it. If the redirect target is not HTTPS (and not localhost), a `Safire::Errors::NetworkError` is raised immediately rather than following the redirect.
+
+```ruby
+# middleware/https_only_redirects.rb
+def on_complete(env)
+  return unless redirect?(env)
+
+  location = env.response_headers['location']
+  uri = URI.parse(location)
+  return if uri.scheme == 'https' || localhost?(uri.host)
+
+  raise Safire::Errors::NetworkError,
+        "Blocked redirect to non-HTTPS URL: #{location}"
+end
+```
+
+Both layers use the same localhost exception (`localhost` and `127.0.0.1`) and must stay consistent. The middleware raises `NetworkError` (transport layer) rather than `ConfigurationError` (construction time) because redirect enforcement is a runtime concern.
+
+---
+
+## Consequences
+
+**Benefits:**
+- Defence-in-depth: HTTPS is enforced at both config time and at every HTTP redirect, closing the redirect-based attack vector
+- Consistent localhost exception across both enforcement points — `http://localhost` works in both URI validation and redirect following
+- Clear error message when a non-HTTPS redirect is blocked, pointing directly at the offending URL
+
+**Trade-offs:**
+- The localhost exception must be maintained in two places — `ClientConfig#localhost_host?` and `HttpsOnlyRedirects` — any change to the exception policy must be applied to both; this duplication is intentional (the two layers are independent defences) but must be kept in sync
+- Blocking non-HTTPS redirects can cause unexpected failures if a FHIR server uses HTTP-to-HTTPS redirect chains (e.g. `http://fhir.example.com` → `https://fhir.example.com`); callers should configure `base_url` with the final HTTPS URL directly

data/docs/adr/ADR-008-warn-return-false-for-compliance-validation.md

@@ -0,0 +1,74 @@
+---
+layout: default
+title: "ADR-008: Warn and return false for compliance validation — raise only for configuration errors"
+parent: Architecture Decision Records
+nav_order: 8
+---
+
+# ADR-008: Warn and return false for compliance validation — raise only for configuration errors
+
+**Status:** Accepted
+
+---
+
+## Context
+
+Safire performs two different kinds of checks:
+
+1. **Configuration checks** — validating that the caller has provided a usable configuration (required attributes present, URIs well-formed and HTTPS). These run at construction time and represent programming errors if they fail.
+
+2. **Compliance checks** — validating that a remote server's response conforms to the SMART App Launch 2.2.0 specification. These run at runtime and represent server behaviour, not caller behaviour.
+
+The question is: what should compliance checks do when they find a violation?
+
+**Option A — Raise an exception:** `token_response_valid?` raises `TokenError`; `SmartMetadata#valid?` raises `DiscoveryError`. The caller must rescue.
+
+**Option B — Warn and return false:** log a warning via `Safire.logger` for each violation found, then return `false`. Never raise.
+
+Option A treats a non-compliant server as an unrecoverable error. In practice, some production FHIR servers have minor token response non-compliance (e.g. `token_type: "bearer"` in lowercase rather than `"Bearer"`) but are otherwise functional. Raising an exception would prevent Safire from working with those servers entirely, with no way for callers to override the decision.
+
+Option B lets the caller decide what to do: they can check the return value, observe the warnings in their logs, and choose to proceed or abort. This is consistent with how Ruby standard library methods (e.g. `URI.parse`, `JSON.parse` with `rescue nil`) handle validation — surface the issue, let the caller decide.
+
+There is also a clear boundary: **the caller controls the config** (configuration errors should raise — the caller can fix them); **the server controls the response** (compliance violations should warn — the caller cannot fix a remote server).
+
+---
+
+## Decision
+
+Compliance validation methods use the **warn + return false** pattern:
+
+```ruby
+def token_response_valid?(response)
+  # ...
+  Safire.logger.warn("SMART token response non-compliance: token_type is #{...}; expected 'Bearer'")
+  false
+end
+
+def valid?  # SmartMetadata
+  # ...
+  Safire.logger.warn("SMART metadata non-compliance: 'S256' not in code_challenge_methods_supported")
+  false
+end
+```
+
+These methods:
+- Never raise an exception
+- Log one warning per violation (not a single combined message) so each issue is individually observable
+- Return `true` only when fully compliant; `false` as soon as any violation is found
+- Are **user-callable** — they are not invoked automatically by `authorization_url` or `server_metadata`; callers opt in to compliance checking
+
+Configuration validation (`ClientConfig#validate!`, `Smart#validate!`) raises `ConfigurationError` — these are programming errors that must be fixed before the gem can function.
+
+---
+
+## Consequences
+
+**Benefits:**
+- Safire can interoperate with non-compliant but functional FHIR servers; callers choose whether to enforce strict compliance
+- Each violation produces a separate, actionable log line rather than a single combined error
+- Callers can implement their own compliance gate: `raise unless client.token_response_valid?(response)`
+- Consistent with the principle of least surprise — a compliance check method that raises on failure is not useful as a boolean check
+
+**Trade-offs:**
+- Callers who do not call `token_response_valid?` get no compliance signal at all — non-compliant responses are silently accepted; this is intentional (opt-in, not opt-out)
+- The distinction between "warn + return false" and "raise" must be maintained consistently — new validation methods should follow the same rule: server behaviour → warn; caller configuration → raise

data/docs/adr/index.md

@@ -0,0 +1,22 @@
+---
+layout: default
+title: Architecture Decision Records
+nav_order: 8
+has_children: true
+permalink: /adr/
+---
+
+# Architecture Decision Records
+
+Architecture Decision Records (ADRs) document significant design decisions made in Safire — what was decided, why, and what trade-offs were accepted.
+
+| ADR | Title | Status |
+|-----|-------|--------|
+| [ADR-001]({% link adr/ADR-001-activesupport-dependency.md %}) | `ActiveSupport` as a runtime dependency | Accepted |
+| [ADR-002]({% link adr/ADR-002-facade-and-forwardable.md %}) | Facade pattern — `Client` delegates to protocol implementations via `Forwardable` | Accepted |
+| [ADR-003]({% link adr/ADR-003-protocol-vs-client-type.md %}) | `protocol:` and `client_type:` as orthogonal dimensions | Accepted |
+| [ADR-004]({% link adr/ADR-004-clientconfig-immutability-and-entity-masking.md %}) | `ClientConfig` immutability and `Entity` sensitive attribute masking | Accepted |
+| [ADR-005]({% link adr/ADR-005-per-client-http-ownership.md %}) | Per-client `HTTPClient` ownership — no shared connection pool | Accepted |
+| [ADR-006]({% link adr/ADR-006-lazy-discovery.md %}) | Lazy SMART discovery — no HTTP in constructors | Accepted |
+| [ADR-007]({% link adr/ADR-007-https-only-redirects-and-localhost-exception.md %}) | HTTPS-only redirect enforcement and localhost exception | Accepted |
+| [ADR-008]({% link adr/ADR-008-warn-return-false-for-compliance-validation.md %}) | Warn and return false for compliance validation — raise only for configuration errors | Accepted |

data/docs/advanced.md

@@ -0,0 +1,284 @@
+---
+layout: default
+title: Advanced Examples
+nav_order: 7
+permalink: /advanced/
+---
+
+# Advanced Examples
+
+{: .no_toc }
+
+<div class="code-example" markdown="1">
+Patterns for caching, multi-server management, token lifecycle, and complete Rails integration.
+</div>
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Metadata Caching
+
+Safire caches SMART metadata within the client instance. In high-traffic applications you may want to share that cache across requests or processes using Rails.cache to avoid repeated HTTP calls to the FHIR server.
+
+```ruby
+# app/services/smart_metadata_service.rb
+class SmartMetadataService
+  CACHE_TTL = 1.hour
+
+  def self.fetch(base_url)
+    Rails.cache.fetch("smart_metadata:#{base_url}", expires_in: CACHE_TTL) do
+      config = Safire::ClientConfig.new(
+        base_url:     base_url,
+        client_id:    'discovery_only',
+        redirect_uri: 'https://example.com',
+        scopes:       []
+      )
+      client = Safire::Client.new(config)
+      client.server_metadata.to_hash
+    end
+  end
+
+  def self.invalidate(base_url)
+    Rails.cache.delete("smart_metadata:#{base_url}")
+  end
+end
+```
+
+```ruby
+# Usage
+metadata = SmartMetadataService.fetch('https://fhir.example.com/r4')
+auth_endpoint = metadata[:authorization_endpoint]
+```
+
+{: .note }
+> Cache the serialised hash (`to_hash`), not the `SmartMetadata` object itself — the object holds an HTTPClient reference that does not serialise cleanly.
+
+---
+
+## Multi-Server Management
+
+Applications that connect to multiple FHIR servers can use a registry to manage one client per server, keeping each client's metadata cache isolated.
+
+```ruby
+# app/services/fhir_server_registry.rb
+class FhirServerRegistry
+  def initialize
+    @clients = {}
+    @mutex   = Mutex.new
+  end
+
+  def client_for(server_key)
+    @mutex.synchronize do
+      @clients[server_key] ||= build_client(server_key)
+    end
+  end
+
+  def invalidate(server_key)
+    @mutex.synchronize { @clients.delete(server_key) }
+  end
+
+  private
+
+  SERVERS = {
+    epic:  { base_url: ENV['EPIC_BASE_URL'],  client_id: ENV['EPIC_CLIENT_ID']  },
+    cerner: { base_url: ENV['CERNER_BASE_URL'], client_id: ENV['CERNER_CLIENT_ID'] }
+  }.freeze
+
+  def build_client(server_key)
+    cfg = SERVERS.fetch(server_key) { raise ArgumentError, "Unknown server: #{server_key}" }
+    config = Safire::ClientConfig.new(
+      base_url:     cfg[:base_url],
+      client_id:    cfg[:client_id],
+      redirect_uri: ENV['REDIRECT_URI'],
+      scopes:       ['openid', 'profile', 'patient/*.read']
+    )
+    Safire::Client.new(config)
+  end
+end
+
+# Shared registry — initialise once at application boot
+FHIR_REGISTRY = FhirServerRegistry.new
+```
+
+```ruby
+# In a controller
+client   = FHIR_REGISTRY.client_for(:epic)
+metadata = client.server_metadata
+```
+
+---
+
+## Token Management
+
+### Proactive Refresh
+
+Check token expiry before making API calls rather than waiting for a 401:
+
+```ruby
+# app/services/token_manager.rb
+class TokenManager
+  EXPIRY_BUFFER = 5.minutes
+
+  def self.valid_token(session)
+    return refresh_token(session) if expiring_soon?(session)
+
+    session[:access_token]
+  end
+
+  def self.expiring_soon?(session)
+    expires_at = session[:token_expires_at]
+    return true if expires_at.nil?
+
+    Time.current >= (expires_at - EXPIRY_BUFFER)
+  end
+
+  def self.refresh_token(session)
+    client        = build_client(session)
+    token_params  = { refresh_token: session[:refresh_token] }
+    response      = client.refresh_token(token_params)
+
+    session[:access_token]     = response[:access_token]
+    session[:refresh_token]    = response[:refresh_token] || session[:refresh_token]
+    session[:token_expires_at] = Time.current + response[:expires_in].to_i.seconds
+
+    response[:access_token]
+  end
+end
+```
+
+### Retry with Exponential Backoff
+
+For transient failures during token exchange:
+
+```ruby
+def exchange_with_retry(client, params, max_attempts: 3)
+  attempts = 0
+
+  begin
+    attempts += 1
+    client.exchange_code_for_token(params)
+  rescue Safire::Errors::TokenError => e
+    raise if attempts >= max_attempts
+    raise unless e.message.match?(/timeout|503|429/i)
+
+    sleep(2**attempts)
+    retry
+  end
+end
+```
+
+### Custom Scopes Per Request
+
+Override the default scopes for specific actions without reconfiguring the client:
+
+```ruby
+def launch_with_scopes(client, extra_scopes: [])
+  base_scopes  = ['openid', 'profile', 'patient/*.read']
+  merged       = (base_scopes + extra_scopes).uniq
+  client.authorization_url(scope_override: merged)
+end
+
+# Requesting additional write access for a specific workflow
+url = launch_with_scopes(client, extra_scopes: ['patient/*.write', 'user/*.read'])
+```
+
+---
+
+## Complete Rails Example
+
+A single controller covers the full SMART authorization cycle. Only the client setup differs between client types — the controller logic is identical.
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  get  '/auth/launch',   to: 'smart_auth#launch'
+  get  '/auth/callback', to: 'smart_auth#callback'
+  post '/auth/logout',   to: 'smart_auth#logout'
+end
+
+# app/controllers/smart_auth_controller.rb
+class SmartAuthController < ApplicationController
+  before_action :initialize_client
+
+  # Step 1 — Redirect user to the authorization server
+  def launch
+    auth_url = @client.authorization_url
+    session[:pkce_verifier] = @client.code_verifier
+    session[:state]         = @client.state
+
+    redirect_to auth_url, allow_other_host: true
+  end
+
+  # Step 2 — Handle the authorization server callback
+  def callback
+    if params[:error]
+      redirect_to root_path, alert: "Authorization failed: #{params[:error_description]}"
+      return
+    end
+
+    token_response = @client.exchange_code_for_token(
+      code:          params[:code],
+      state:         params[:state],
+      pkce_verifier: session.delete(:pkce_verifier)
+    )
+
+    session[:access_token]     = token_response[:access_token]
+    session[:refresh_token]    = token_response[:refresh_token]
+    session[:token_expires_at] = Time.current + token_response[:expires_in].to_i.seconds
+
+    redirect_to dashboard_path
+  end
+
+  def logout
+    reset_session
+    redirect_to root_path
+  end
+
+  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', 'offline_access']
+    )
+
+    @client = Safire::Client.new(config) # :public is the default client_type
+  end
+end
+```
+
+### Switching Client Types
+
+Only `initialize_client` changes. The rest of the controller is untouched.
+
+```ruby
+# Confidential Symmetric — add client_secret
+config = Safire::ClientConfig.new(
+  base_url:      ENV['FHIR_BASE_URL'],
+  client_id:     ENV['SMART_CLIENT_ID'],
+  client_secret: ENV['SMART_CLIENT_SECRET'],   # from ENV, credentials, or secrets manager
+  redirect_uri:  callback_url,
+  scopes:        ['openid', 'profile', 'patient/*.read', 'offline_access']
+)
+@client = Safire::Client.new(config, client_type: :confidential_symmetric)
+
+# Confidential Asymmetric — add private_key and kid
+config = Safire::ClientConfig.new(
+  base_url:    ENV['FHIR_BASE_URL'],
+  client_id:   ENV['SMART_CLIENT_ID'],
+  private_key: OpenSSL::PKey::RSA.new(File.read(ENV['SMART_PRIVATE_KEY_PATH'])),
+  kid:         ENV['SMART_KEY_ID'],
+  redirect_uri: callback_url,
+  scopes:       ['openid', 'profile', 'patient/*.read', 'offline_access']
+)
+@client = Safire::Client.new(config, client_type: :confidential_asymmetric)
+```
+
+See the [Security Guide]({{ site.baseurl }}/security/) for credential loading patterns and key rotation.