safire 0.1.0

data/docs/configuration/client-setup.md

@@ -0,0 +1,158 @@
+---
+layout: default
+title: Client Setup
+parent: Configuration
+nav_order: 1
+---
+
+# Client Setup
+
+{: .no_toc }
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Creating a Client
+
+Pass configuration as a Hash — Safire wraps it in a `ClientConfig` automatically:
+
+```ruby
+client = Safire::Client.new(
+  base_url:     'https://fhir.example.com/r4',
+  client_id:    'my_client_id',
+  redirect_uri: 'https://myapp.com/callback',
+  scopes:       ['openid', 'profile', 'patient/*.read']
+)
+```
+
+If you need to reuse the same configuration across multiple clients or inspect it before use, create a `ClientConfig` explicitly:
+
+```ruby
+config = Safire::ClientConfig.new(
+  base_url:     'https://fhir.example.com/r4',
+  client_id:    'my_client_id',
+  redirect_uri: 'https://myapp.com/callback',
+  scopes:       ['openid', 'profile', 'patient/*.read']
+)
+
+client = Safire::Client.new(config)
+```
+
+---
+
+## Protocol and Client Type
+
+`protocol:` and `client_type:` are keyword arguments to `Safire::Client.new`. They are independent of each other.
+
+```ruby
+client = Safire::Client.new(config, protocol: :smart, client_type: :confidential_symmetric)
+```
+
+### Protocol
+
+Selects the authorization protocol. Defaults to `:smart`.
+
+| Value | Status | Description |
+|-------|--------|-------------|
+| `:smart` | Implemented | SMART App Launch 2.2.0 |
+| `:udap` | Planned | UDAP Security 1.0 — accepted by the validator, raises `NotImplementedError` until implemented |
+
+For UDAP, `client_type:` is ignored — UDAP clients always authenticate with a JWT signed by their private key.
+
+### Client Type
+
+Selects the SMART authentication method. Applies only when `protocol: :smart`. Defaults to `:public`.
+
+| Value | Extra config required | Authentication |
+|-------|-----------------------|----------------|
+| `:public` | None | PKCE; `client_id` in request body |
+| `:confidential_symmetric` | `client_secret` | HTTP Basic auth |
+| `:confidential_asymmetric` | `private_key`, `kid` | JWT assertion (RS384/ES384) |
+
+```ruby
+# Public (default)
+client = Safire::Client.new(config)
+
+# Confidential symmetric
+client = Safire::Client.new(
+  { **base_config, client_secret: ENV.fetch('SMART_CLIENT_SECRET') },
+  client_type: :confidential_symmetric
+)
+
+# Confidential asymmetric
+client = Safire::Client.new(
+  {
+    **base_config,
+    private_key: OpenSSL::PKey::RSA.new(File.read(ENV.fetch('SMART_PRIVATE_KEY_PATH'))),
+    kid:         ENV.fetch('SMART_KEY_ID'),
+    jwks_uri:    ENV.fetch('SMART_JWKS_URI')  # optional
+  },
+  client_type: :confidential_asymmetric
+)
+```
+
+You can also change `client_type` after initialization — useful when selecting a type based on server capabilities discovered at runtime:
+
+```ruby
+client = Safire::Client.new(config)
+metadata = client.server_metadata
+
+client.client_type = :confidential_asymmetric if metadata.supports_asymmetric_auth?
+```
+
+For a decision guide on which client type to use, see [SMART on FHIR — Choosing a Client Type]({{ site.baseurl }}/smart-on-fhir/).
+
+---
+
+## URI Validation
+
+All URI parameters are validated at initialization. Safire raises `Safire::Errors::ConfigurationError` for any violation:
+
+- URIs must be well-formed (scheme + host required)
+- URIs must use `https` — required by SMART App Launch 2.2.0
+- **Exception:** `http` is permitted for `localhost` and `127.0.0.1` (local development only)
+
+The following attributes are validated:
+
+| Attribute | Validated when |
+|-----------|----------------|
+| `base_url` | Always |
+| `redirect_uri` | Always |
+| `issuer` | When provided (defaults to `base_url`) |
+| `authorization_endpoint` | When provided |
+| `token_endpoint` | When provided |
+| `jwks_uri` | When provided |
+
+If you need to bypass discovery and provide endpoints directly, set `authorization_endpoint` and `token_endpoint` in your config. Safire will use them as-is instead of fetching `/.well-known/smart-configuration`.
+
+---
+
+## Credential Protection
+
+`ClientConfig` prevents `client_secret` and `private_key` from leaking in logs or REPL output.
+
+`#to_hash` replaces sensitive fields with `'[FILTERED]'`:
+
+```ruby
+config.to_hash[:client_secret]  # => "[FILTERED]"
+config.to_hash[:base_url]       # => "https://fhir.example.com"
+```
+
+`#inspect` is overridden to mask sensitive fields and omit `nil` attributes, so REPL sessions and error messages never expose credentials:
+
+```ruby
+config.inspect
+# => "#<Safire::ClientConfig base_url: \"https://fhir.example.com\", client_id: \"my_client_id\", client_secret: \"[FILTERED]\", ...>"
+```
+
+---
+
+## Next Steps
+
+- [Logging]({{ site.baseurl }}/configuration/logging/) — configure Safire's logger and HTTP request logging
+- [SMART on FHIR Workflows]({{ site.baseurl }}/smart-on-fhir/) — step-by-step authorization flow guides

data/docs/configuration/index.md

@@ -0,0 +1,60 @@
+---
+layout: default
+title: Configuration
+nav_order: 3
+has_children: true
+permalink: /configuration/
+---
+
+# Configuration
+
+Safire is configured in two places:
+
+- **Client configuration** — the FHIR server URL, credentials, and OAuth parameters passed to `Safire::Client.new`
+- **Global configuration** — the logger, log level, and HTTP logging behaviour set once via `Safire.configure`
+
+## Architecture Overview
+
+`Safire::Client` is the public entry point. It owns a `ClientConfig` (validated at construction) and lazily builds a protocol implementation when first used. See [ADR-002]({% link adr/ADR-002-facade-and-forwardable.md %}) for the facade design rationale, [ADR-003]({% link adr/ADR-003-protocol-vs-client-type.md %}) for the `protocol:` / `client_type:` design, and [ADR-006]({% link adr/ADR-006-lazy-discovery.md %}) for the lazy discovery design.
+
+```mermaid
+flowchart TD
+    A["Safire::Client.new(config, protocol: :smart, client_type: :public)"]
+    B["Safire::ClientConfig\n— validates URIs\n— masks sensitive attrs"]
+    C{protocol:}
+    D["Protocols::Smart\n— reads attrs from ClientConfig\n— owns HTTPClient"]
+    E["SmartMetadata\n(lazy — fetched on first use)"]
+    F["GET /.well-known/\nsmart-configuration"]
+
+    A -->|"resolves config"| B
+    A -->|"validates protocol + client_type"| C
+    C -->|":smart (default)"| D
+    C -->|":udap (planned)"| G["Protocols::Udap\n(future)"]
+    D -->|"lazily fetches"| E
+    E -->|"HTTP"| F
+```
+
+## Quick Reference
+
+`protocol:` and `client_type:` are keyword arguments to `Safire::Client.new`. All other parameters are keys in the configuration hash (or `Safire::ClientConfig` attributes).
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| `base_url` | String | Yes | — | FHIR server base URL |
+| `client_id` | String | Yes | — | OAuth2 client identifier |
+| `redirect_uri` | String | Yes | — | Registered callback URL |
+| `protocol:` | Symbol | No | `:smart` | Authorization protocol — `:smart` or `:udap` |
+| `client_type:` | Symbol | No | `:public` | SMART client type — `:public`, `:confidential_symmetric`, or `:confidential_asymmetric` |
+| `client_secret` | String | No | — | Required for `:confidential_symmetric` |
+| `private_key` | OpenSSL::PKey / String | No | — | RSA/EC private key; required for `:confidential_asymmetric` |
+| `kid` | String | No | — | Key ID matching the public key registered with the server |
+| `jwt_algorithm` | String | No | auto | `RS384` or `ES384`; auto-detected from key type |
+| `jwks_uri` | String | No | — | URL to client's public JWKS, included as `jku` in JWT header |
+| `scopes` | Array | No | — | Default scopes for authorization requests |
+| `authorization_endpoint` | String | No | — | Override the discovered authorization endpoint |
+| `token_endpoint` | String | No | — | Override the discovered token endpoint |
+
+## In This Section
+
+- [Client Setup]({{ site.baseurl }}/configuration/client-setup/) — creating a client, protocol and client type selection, URI rules, and credential protection
+- [Logging]({{ site.baseurl }}/configuration/logging/) — global logger setup, HTTP request logging, log levels, and environment variables

data/docs/configuration/logging.md

@@ -0,0 +1,86 @@
+---
+layout: default
+title: Logging
+parent: Configuration
+nav_order: 2
+---
+
+# Logging
+
+{: .no_toc }
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Global Logger Setup
+
+Configure Safire's logger once at application startup via `Safire.configure`:
+
+```ruby
+# config/initializers/safire.rb
+Safire.configure do |config|
+  config.logger    = Rails.logger
+  config.log_level = Rails.env.development? ? Logger::DEBUG : Logger::INFO
+  config.log_http  = true  # default
+end
+```
+
+By default, Safire logs to `$stdout` at `Logger::INFO`.
+
+---
+
+## Log Levels
+
+| Level | Behaviour |
+|-------|-----------|
+| `Logger::DEBUG` | Verbose — all Safire internal operations |
+| `Logger::INFO` | Standard — normal operation events (default) |
+| `Logger::WARN` | Compliance warnings and non-critical issues only |
+| `Logger::ERROR` | Errors only |
+
+---
+
+## HTTP Request Logging
+
+When `log_http` is `true` (the default), Safire logs each outbound HTTP request and response. Sensitive data is automatically filtered:
+
+- The `Authorization` header is replaced with `[FILTERED]`
+- Request and response **bodies are never logged** — tokens and credentials are never captured
+
+```ruby
+Safire.configure do |config|
+  config.log_http = false  # disable if not needed in production
+end
+```
+
+---
+
+## Environment Variables
+
+### `SAFIRE_LOGGER`
+
+By default Safire logs to `$stdout`. Set `SAFIRE_LOGGER` to a file path to redirect output:
+
+```bash
+SAFIRE_LOGGER=/var/log/safire.log
+```
+
+This only affects the **default logger**. If you set `config.logger` in `Safire.configure`, `SAFIRE_LOGGER` is ignored entirely.
+
+| `SAFIRE_LOGGER` set? | `config.logger` set? | Log destination |
+|----------------------|----------------------|-----------------|
+| No | No | `$stdout` |
+| Yes | No | File at that path |
+| Either | Yes | Your custom logger |
+
+---
+
+## Next Steps
+
+- [Client Setup]({{ site.baseurl }}/configuration/client-setup/) — client parameters, protocol, and credential protection
+- [Troubleshooting]({{ site.baseurl }}/troubleshooting/) — common issues and solutions

data/docs/index.md

@@ -0,0 +1,64 @@
+---
+layout: default
+title: Home
+nav_order: 1
+permalink: /
+---
+
+# Safire Documentation
+
+[![Gem Version](https://badge.fury.io/rb/safire.svg)](https://badge.fury.io/rb/safire)
+[![CI](https://github.com/vanessuniq/safire/workflows/CI/badge.svg)](https://github.com/vanessuniq/safire/actions)
+
+A lean Ruby gem implementing **[SMART on FHIR](https://hl7.org/fhir/smart-app-launch/)** and **[UDAP](https://hl7.org/fhir/us/udap-security/)** protocols for clients.
+
+## Quick Navigation
+
+| Section | Description |
+|---------|-------------|
+| [Getting Started]({{ site.baseurl }}/installation/) | Install Safire and quick start guide |
+| [Configuration]({{ site.baseurl }}/configuration/) | All configuration options and parameters |
+| [SMART on FHIR]({{ site.baseurl }}/smart-on-fhir/) | Discovery, Public clients, Confidential clients |
+| [UDAP]({{ site.baseurl }}/udap/) | UDAP protocol overview and planned support |
+| [Security Guide]({{ site.baseurl }}/security/) | HTTPS, credential protection, token storage, key rotation |
+| [Advanced Examples]({{ site.baseurl }}/advanced/) | Caching, multi-server, token management, complete Rails integration |
+| [Troubleshooting]({{ site.baseurl }}/troubleshooting/) | Common issues and solutions |
+| [Safire API Docs]({{ site.baseurl }}/api/){:target="_blank"} | Complete YARD documentation |
+
+## Features
+
+### SMART on FHIR App Launch
+
+- Discovery (`/.well-known/smart-configuration`)
+- Public Client (PKCE)
+- Confidential Symmetric Client (client_secret + Basic Auth)
+- Confidential Asymmetric Client (private_key_jwt with RS384/ES384)
+- POST-Based Authorization
+
+### UDAP
+
+> Planned. See [ROADMAP.md](https://github.com/vanessuniq/safire/blob/main/ROADMAP.md) for details (coming soon).
+
+## Demo Application
+
+A Sinatra-based demo app is included to help you explore Safire's features:
+
+```bash
+bin/demo
+```
+
+Visit http://localhost:4567 to test SMART discovery, authorization flows, and token management.
+
+See [`examples/sinatra_app/README.md`](https://github.com/vanessuniq/safire/tree/main/examples/sinatra_app) for details.
+
+## Community
+
+- [GitHub Repository](https://github.com/vanessuniq/safire)
+- [Issue Tracker](https://github.com/vanessuniq/safire/issues)
+- [Architecture Decision Records]({{ site.baseurl }}/adr/) — design decisions and rationale
+
+---
+
+*Last updated: {{ site.time | date: '%B %d, %Y' }}*
+
+*Parts of this project were developed with AI assistance (Claude Code) and reviewed by maintainers.*

data/docs/installation.md

@@ -0,0 +1,96 @@
+---
+layout: default
+title: Installation
+nav_order: 2
+---
+
+# Installation
+
+{: .no_toc }
+
+## Table of contents
+{: .no_toc .text-delta }
+
+1. TOC
+{:toc}
+
+---
+
+## Install
+
+**Requirements:** Ruby ≥ 4.0.2. OpenSSL is bundled with Ruby — no separate install needed.
+
+Add to your Gemfile:
+
+```ruby
+gem 'safire'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install safire
+```
+
+---
+
+## Development Setup
+
+Clone the repo and set up the development environment:
+
+```bash
+git clone https://github.com/vanessuniq/safire.git
+cd safire
+bin/setup          # Install dependencies
+bundle exec rspec  # Run tests to verify
+bin/console        # Interactive prompt
+```
+
+To serve the docs site locally:
+
+```bash
+bin/docs                                           # Generate YARD API docs
+cd docs && bundle install && bundle exec jekyll serve
+```
+
+Then visit `http://localhost:4000/safire/`.
+
+---
+
+## Verify
+
+A quick smoke test to confirm the gem is installed and SMART discovery is working:
+
+```ruby
+require 'safire'
+
+client = Safire::Client.new(
+  base_url:     'https://launch.smarthealthit.org/v/r4/sim/eyJoIjoiMSJ9/fhir',
+  client_id:    'test',
+  redirect_uri: 'https://example.com/callback',
+  scopes:       ['openid', 'profile', 'patient/*.read']
+)
+
+metadata = client.server_metadata
+puts metadata.authorization_endpoint
+# => https://launch.smarthealthit.org/.../auth/authorize
+```
+
+If you see an authorization endpoint URL, the gem is working. For troubleshooting, see the [Troubleshooting Guide]({{ site.baseurl }}/troubleshooting/).
+
+---
+
+## Next Steps
+
+| | |
+|-|-|
+| [Configuration]({{ site.baseurl }}/configuration/) | Client credentials, logging, and protocol selection |
+| [SMART on FHIR]({{ site.baseurl }}/smart-on-fhir/) | Authorization flows for public and confidential clients |
+| [Security Guide]({{ site.baseurl }}/security/) | HTTPS requirements, credential protection, token storage |
+| [API Reference]({{ site.baseurl }}/api/){:target="_blank"} | Complete YARD documentation |