safire 0.1.0

data/docs/Gemfile.lock

@@ -0,0 +1,195 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.8)
+      public_suffix (>= 2.0.2, < 8.0)
+    base64 (0.3.0)
+    bigdecimal (4.0.1)
+    colorator (1.1.0)
+    concurrent-ruby (1.3.6)
+    csv (3.3.5)
+    em-websocket (0.5.3)
+      eventmachine (>= 0.12.9)
+      http_parser.rb (~> 0)
+    eventmachine (1.2.7)
+    ffi (1.17.3)
+    ffi (1.17.3-arm-linux-gnu)
+    ffi (1.17.3-arm-linux-musl)
+    ffi (1.17.3-x86_64-linux-gnu)
+    forwardable-extended (2.6.0)
+    google-protobuf (4.33.4)
+      bigdecimal
+      rake (>= 13)
+    http_parser.rb (0.8.1)
+    i18n (1.14.8)
+      concurrent-ruby (~> 1.0)
+    jekyll (4.4.1)
+      addressable (~> 2.4)
+      base64 (~> 0.2)
+      colorator (~> 1.0)
+      csv (~> 3.0)
+      em-websocket (~> 0.5)
+      i18n (~> 1.0)
+      jekyll-sass-converter (>= 2.0, < 4.0)
+      jekyll-watch (~> 2.0)
+      json (~> 2.6)
+      kramdown (~> 2.3, >= 2.3.1)
+      kramdown-parser-gfm (~> 1.0)
+      liquid (~> 4.0)
+      mercenary (~> 0.3, >= 0.3.6)
+      pathutil (~> 0.9)
+      rouge (>= 3.0, < 5.0)
+      safe_yaml (~> 1.0)
+      terminal-table (>= 1.8, < 4.0)
+      webrick (~> 1.7)
+    jekyll-feed (0.17.0)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-include-cache (0.2.1)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-sass-converter (3.1.0)
+      sass-embedded (~> 1.75)
+    jekyll-seo-tag (2.8.0)
+      jekyll (>= 3.8, < 5.0)
+    jekyll-sitemap (1.4.0)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-watch (2.2.1)
+      listen (~> 3.0)
+    json (2.18.0)
+    just-the-docs (0.12.0)
+      jekyll (>= 3.8.5)
+      jekyll-include-cache
+      jekyll-seo-tag (>= 2.0)
+      rake (>= 12.3.1)
+    kramdown (2.5.2)
+      rexml (>= 3.4.4)
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
+    liquid (4.0.4)
+    listen (3.10.0)
+      logger
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    logger (1.7.0)
+    mercenary (0.4.0)
+    pathutil (0.16.2)
+      forwardable-extended (~> 2.6)
+    public_suffix (7.0.2)
+    rake (13.3.1)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.11.1)
+      ffi (~> 1.0)
+    rexml (3.4.4)
+    rouge (4.7.0)
+    safe_yaml (1.0.5)
+    sass-embedded (1.97.3)
+      google-protobuf (~> 4.31)
+      rake (>= 13)
+    sass-embedded (1.97.3-aarch64-linux-android)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.97.3-arm-linux-androideabi)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.97.3-arm-linux-gnueabihf)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.97.3-arm-linux-musleabihf)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.97.3-riscv64-linux-android)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.97.3-riscv64-linux-gnu)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.97.3-riscv64-linux-musl)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.97.3-x86_64-linux-android)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.97.3-x86_64-linux-gnu)
+      google-protobuf (~> 4.31)
+    terminal-table (3.0.2)
+      unicode-display_width (>= 1.1.1, < 3)
+    unicode-display_width (2.6.0)
+    webrick (1.9.2)
+
+PLATFORMS
+  aarch64-linux-android
+  arm-linux-androideabi
+  arm-linux-gnu
+  arm-linux-gnueabihf
+  arm-linux-musl
+  arm-linux-musleabihf
+  riscv64-linux-android
+  riscv64-linux-gnu
+  riscv64-linux-musl
+  ruby
+  x86_64-linux
+  x86_64-linux-android
+
+DEPENDENCIES
+  base64
+  bigdecimal
+  csv
+  http_parser.rb (~> 0.8.0)
+  jekyll (~> 4.4)
+  jekyll-feed (~> 0.17)
+  jekyll-seo-tag
+  jekyll-sitemap
+  just-the-docs
+  logger
+  tzinfo (>= 1, < 3)
+  tzinfo-data
+  wdm (~> 0.1)
+  webrick
+
+CHECKSUMS
+  addressable (2.8.8) sha256=7c13b8f9536cf6364c03b9d417c19986019e28f7c00ac8132da4eb0fe393b057
+  base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
+  bigdecimal (4.0.1) sha256=8b07d3d065a9f921c80ceaea7c9d4ae596697295b584c296fe599dd0ad01c4a7
+  colorator (1.1.0) sha256=e2f85daf57af47d740db2a32191d1bdfb0f6503a0dfbc8327d0c9154d5ddfc38
+  concurrent-ruby (1.3.6) sha256=6b56837e1e7e5292f9864f34b69c5a2cbc75c0cf5338f1ce9903d10fa762d5ab
+  csv (3.3.5) sha256=6e5134ac3383ef728b7f02725d9872934f523cb40b961479f69cf3afa6c8e73f
+  em-websocket (0.5.3) sha256=f56a92bde4e6cb879256d58ee31f124181f68f8887bd14d53d5d9a292758c6a8
+  eventmachine (1.2.7) sha256=994016e42aa041477ba9cff45cbe50de2047f25dd418eba003e84f0d16560972
+  ffi (1.17.3) sha256=0e9f39f7bb3934f77ad6feab49662be77e87eedcdeb2a3f5c0234c2938563d4c
+  ffi (1.17.3-arm-linux-gnu) sha256=5bd4cea83b68b5ec0037f99c57d5ce2dd5aa438f35decc5ef68a7d085c785668
+  ffi (1.17.3-arm-linux-musl) sha256=0d7626bb96265f9af78afa33e267d71cfef9d9a8eb8f5525344f8da6c7d76053
+  ffi (1.17.3-x86_64-linux-gnu) sha256=3746b01f677aae7b16dc1acb7cb3cc17b3e35bdae7676a3f568153fb0e2c887f
+  forwardable-extended (2.6.0) sha256=1bec948c469bbddfadeb3bd90eb8c85f6e627a412a3e852acfd7eaedbac3ec97
+  google-protobuf (4.33.4) sha256=86921935b023ed0d872d6e84382e79016c91689be0520d614c74426778f13c16
+  http_parser.rb (0.8.1) sha256=9ae8df145b39aa5398b2f90090d651c67bd8e2ebfe4507c966579f641e11097a
+  i18n (1.14.8) sha256=285778639134865c5e0f6269e0b818256017e8cde89993fdfcbfb64d088824a5
+  jekyll (4.4.1) sha256=4c1144d857a5b2b80d45b8cf5138289579a9f8136aadfa6dd684b31fe2bc18c1
+  jekyll-feed (0.17.0) sha256=689aab16c877949bb9e7a5c436de6278318a51ecb974792232fd94d8b3acfcc3
+  jekyll-include-cache (0.2.1) sha256=c7d4b9e551732a27442cb2ce853ba36a2f69c66603694b8c1184c99ab1a1a205
+  jekyll-sass-converter (3.1.0) sha256=83925d84f1d134410c11d0c6643b0093e82e3a3cf127e90757a85294a3862443
+  jekyll-seo-tag (2.8.0) sha256=3f2ed1916d56f14ebfa38e24acde9b7c946df70cb183af2cb5f0598f21ae6818
+  jekyll-sitemap (1.4.0) sha256=0de08c5debc185ea5a8f980e1025c7cd3f8e0c35c8b6ef592f15c46235cf4218
+  jekyll-watch (2.2.1) sha256=bc44ed43f5e0a552836245a54dbff3ea7421ecc2856707e8a1ee203a8387a7e1
+  json (2.18.0) sha256=b10506aee4183f5cf49e0efc48073d7b75843ce3782c68dbeb763351c08fd505
+  just-the-docs (0.12.0) sha256=15f2839ac9082898d60f33b978aa6f8e46fc50ba8fac20ae7a7f0e1fb295523e
+  kramdown (2.5.2) sha256=1ba542204c66b6f9111ff00dcc26075b95b220b07f2905d8261740c82f7f02fa
+  kramdown-parser-gfm (1.1.0) sha256=fb39745516427d2988543bf01fc4cf0ab1149476382393e0e9c48592f6581729
+  liquid (4.0.4) sha256=4fcfebb1a045e47918388dbb7a0925e7c3893e58d2bd6c3b3c73ec17a2d8fdb3
+  listen (3.10.0) sha256=c6e182db62143aeccc2e1960033bebe7445309c7272061979bb098d03760c9d2
+  logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
+  mercenary (0.4.0) sha256=b25a1e4a59adca88665e08e24acf0af30da5b5d859f7d8f38fba52c28f405138
+  pathutil (0.16.2) sha256=e43b74365631cab4f6d5e4228f812927efc9cb2c71e62976edcb252ee948d589
+  public_suffix (7.0.2) sha256=9114090c8e4e7135c1fd0e7acfea33afaab38101884320c65aaa0ffb8e26a857
+  rake (13.3.1) sha256=8c9e89d09f66a26a01264e7e3480ec0607f0c497a861ef16063604b1b08eb19c
+  rb-fsevent (0.11.2) sha256=43900b972e7301d6570f64b850a5aa67833ee7d87b458ee92805d56b7318aefe
+  rb-inotify (0.11.1) sha256=a0a700441239b0ff18eb65e3866236cd78613d6b9f78fea1f9ac47a85e47be6e
+  rexml (3.4.4) sha256=19e0a2c3425dfbf2d4fc1189747bdb2f849b6c5e74180401b15734bc97b5d142
+  rouge (4.7.0) sha256=dba5896715c0325c362e895460a6d350803dbf6427454f49a47500f3193ea739
+  safe_yaml (1.0.5) sha256=a6ac2d64b7eb027bdeeca1851fe7e7af0d668e133e8a88066a0c6f7087d9f848
+  sass-embedded (1.97.3) sha256=c4136da69ae3acfa7b0809f4ec10891125edf57df214a2d1ab570f721f96f7a6
+  sass-embedded (1.97.3-aarch64-linux-android) sha256=623b2f52fed6e3696c6445406e4efaef57b54442cc35604bfffbb82aef7d5c45
+  sass-embedded (1.97.3-arm-linux-androideabi) sha256=e2ef33b187066e09374023e58e72cf3b5baabe6b77ecd74356fe9b4892a1c6e1
+  sass-embedded (1.97.3-arm-linux-gnueabihf) sha256=ce443b57f3d7f03740267cf0f2cdff13e8055dd5938488967746f29f230222da
+  sass-embedded (1.97.3-arm-linux-musleabihf) sha256=be3972424616f916ce1f4f41228266d57339e490dfd7ca0cea5588579564d4c0
+  sass-embedded (1.97.3-riscv64-linux-android) sha256=201426b3e58611aa8cf34a7574df51905ec42fefb5a69982cc8497ac7fb26a6b
+  sass-embedded (1.97.3-riscv64-linux-gnu) sha256=d7bac32f4de55c589a036da13ac4482bf5b7dfac980b4c0203d31a1bd9f07622
+  sass-embedded (1.97.3-riscv64-linux-musl) sha256=621d981d700e2b8d0459b5ea696fff746dfa07d6b6bbc70cd982905214b07888
+  sass-embedded (1.97.3-x86_64-linux-android) sha256=8f5e179bee8610be432499f228ea4e53ab362b1db0da1ae3cd3e76b114712372
+  sass-embedded (1.97.3-x86_64-linux-gnu) sha256=173a4d0dbe2fffdf7482bd3e82fb597dfc658c18d1e8fd746aa7d5077ed4e850
+  terminal-table (3.0.2) sha256=f951b6af5f3e00203fb290a669e0a85c5dd5b051b3b023392ccfd67ba5abae91
+  unicode-display_width (2.6.0) sha256=12279874bba6d5e4d2728cef814b19197dbb10d7a7837a869bab65da943b7f5a
+  webrick (1.9.2) sha256=beb4a15fc474defed24a3bda4ffd88a490d517c9e4e6118c3edce59e45864131
+
+BUNDLED WITH
+  4.0.3

data/docs/_config.yml

@@ -0,0 +1,103 @@
+# Welcome to Jekyll!
+#
+# This config file is meant for settings that affect your whole blog, values
+# which you are expected to set up once and rarely edit after that. If you find
+# yourself editing this file very often, consider using Jekyll's data files
+# feature for the data you need to update frequently.
+#
+# For technical reasons, this file is *NOT* reloaded automatically when you use
+# 'bundle exec jekyll serve'. If you change this file, please restart the server process.
+#
+# If you need help with YAML syntax, here are some quick references for you:
+# https://learn-the-web.algonquindesign.ca/topics/markdown-yaml-cheat-sheet/#yaml
+# https://learnxinyminutes.com/docs/yaml/
+#
+# Site settings
+# These are used to personalize your new site. If you look in the HTML files,
+# you will see them accessed via {{ site.title }}, {{ site.email }}, and so on.
+# You can create any custom variable you would like, and they will be accessible
+# in the templates via {{ site.myvariable }}.
+
+title: Safire Documentation
+description: SMART on FHIR and UDAP implementation library for Ruby
+baseurl: /safire
+url: https://vanessuniq.github.io
+
+# Build settings
+markdown: kramdown
+highlighter: rouge
+theme: just-the-docs
+plugins:
+  - jekyll-feed
+  - jekyll-seo-tag
+  - jekyll-sitemap
+
+# Just the Docs theme configuration
+color_scheme: light
+search_enabled: true
+search:
+  previews: 2
+  preview_words_before: 3
+  preview_words_after: 5
+  tokenizer_separator: /[\s\-/]+/
+nav_sort: case_insensitive
+footer_content: ""
+
+# Markdown Processors
+sass:
+  quiet_deps: true
+  silence_deprecations:
+    - import
+
+kramdown:
+  syntax_highlighter: rouge
+  syntax_highlighter_opts:
+    css_class: highlight
+    span:
+      line_numbers: false
+    block:
+      line_numbers: false
+      start_line: 1
+
+
+defaults:
+  - scope:
+      path: ""
+      type: pages
+    values:
+      layout: default
+      toc: true
+
+aux_links:
+  Safire API Docs:
+    - /safire/api
+  GitHub:
+    - https://github.com/vanessuniq/safire
+
+aux_links_new_tab: true
+
+back_to_top: true
+back_to_top_text: Back to Top ↑
+
+# Mermaid diagrams
+mermaid:
+  version: "10.9.0"
+# Exclude from processing.
+# The following items will not be processed, by default.
+# Any item listed under the `exclude:` key here will be automatically added to
+# the internal "default list".
+#
+# Excluded items can be processed by explicitly listing the directories or
+# their entries' file path in the `include:` list.
+#
+# exclude:
+#   - .sass-cache/
+#   - .jekyll-cache/
+#   - gemfiles/
+#   - Gemfile
+#   - Gemfile.lock
+#   - node_modules/
+#   - vendor/bundle/
+#   - vendor/cache/
+#   - vendor/gems/
+#   - vendor/ruby/

data/docs/_includes/footer_custom.html

@@ -0,0 +1,6 @@
+{% assign current_year = site.time | date: '%Y' %}
+{% if current_year == '2025' %}
+  <p class="footer-copyright">Copyright &copy; 2025 Safire Contributors. Licensed under Apache 2.0.</p>
+{% else %}
+  <p class="footer-copyright">Copyright &copy; 2025-{{ current_year }} Safire Contributors. Licensed under Apache 2.0.</p>
+{% endif %}

data/docs/_includes/head_custom.html

@@ -0,0 +1,14 @@
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Raleway:ital,wght@0,300;0,400;1,300&display=swap" rel="stylesheet">
+<style>
+  .footer-copyright {
+    font-family: 'Raleway', sans-serif;
+    font-size: 0.72rem;
+    font-weight: 700;
+    letter-spacing: 0.06em;
+    text-align: center;
+    opacity: 0.75;
+    margin-top: 0.5rem;
+  }
+</style>

data/docs/_sass/custom/custom.scss

@@ -0,0 +1,108 @@
+// Custom styles for Safire documentation
+
+// Sticky footer - ensure footer stays at bottom of viewport
+html {
+  height: 100%;
+}
+
+body {
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+
+.side-bar {
+  display: flex;
+  flex-direction: column;
+}
+
+.main {
+  flex: 1 0 auto;
+  display: flex;
+  flex-direction: column;
+}
+
+.main-content-wrap {
+  flex: 1 0 auto;
+}
+
+// Footer styling
+.site-footer {
+  flex-shrink: 0;
+  padding: 1rem;
+  margin-top: auto;
+  border-top: 1px solid #e1e4e8;
+  background: #f6f8fa;
+}
+
+// Grid layout for cards
+.grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
+  gap: 1rem;
+  margin: 2rem 0;
+}
+
+.grid-item {
+  padding: 1.5rem;
+  border: 1px solid #e1e4e8;
+  border-radius: 6px;
+  background: #f6f8fa;
+
+  h3 {
+    margin-top: 0;
+
+    a {
+      color: #0366d6;
+      text-decoration: none;
+
+      &:hover {
+        color: #93116c;
+      }
+    }
+  }
+}
+
+// Status badges
+.status-complete {
+  color: #28a745;
+}
+
+.status-planned {
+  color: #6f42c1;
+}
+
+.status-progress {
+  color: #fd7e14;
+}
+
+// Code highlighting improvements
+.highlight {
+  margin: 1rem 0;
+
+  pre {
+    padding: 1rem;
+    overflow-x: auto;
+    font-size: 0.875rem;
+    line-height: 1.45;
+  }
+}
+
+// Warning and info boxes
+.warning {
+  padding: 1rem;
+  margin: 1rem 0;
+  background-color: #fff3cd;
+  border: 1px solid #ffeaa7;
+  border-radius: 6px;
+  color: #856404;
+}
+
+.info {
+  padding: 1rem;
+  margin: 1rem 0;
+  background-color: #d1ecf1;
+  border: 1px solid #bee5eb;
+  border-radius: 6px;
+  color: #0c5460;
+}

data/docs/adr/ADR-001-activesupport-dependency.md

@@ -0,0 +1,50 @@
+---
+layout: default
+title: "ADR-001: ActiveSupport as a runtime dependency"
+parent: Architecture Decision Records
+nav_order: 1
+---
+
+# ADR-001: ActiveSupport as a runtime dependency
+
+**Status:** Accepted
+
+---
+
+## Context
+
+Safire needs several utility methods throughout its codebase: presence checks (`present?`, `blank?`), string/array utilities, and safe object handling. There are three options:
+
+**Option A — Implement utilities inline:** write custom `present?`, `blank?`, and other helpers inside the `Safire` module.
+
+**Option B — Require individual ActiveSupport components:** use `require 'active_support/core_ext/object/blank'` and similar targeted requires to pull in only what is needed.
+
+**Option C — `require 'active_support/all'`:** load the entire ActiveSupport library at once.
+
+Option A introduces maintenance burden and drift from well-tested, community-maintained implementations. Option B requires tracking which AS components are used and updating requires when new utilities are adopted — a form of accidental complexity with no real benefit.
+
+The key fact about ActiveSupport is that it uses Ruby's `autoload` mechanism internally. Even though `require 'active_support/all'` loads the autoload registry for all AS modules, the actual code for each module is only loaded when that module is first referenced. The memory overhead of `require 'active_support/all'` is therefore close to the overhead of targeted requires — the difference is measured in milliseconds at startup, not in runtime memory.
+
+Safire is also commonly used alongside Rails applications, where ActiveSupport is already loaded. In that context, `require 'active_support/all'` is effectively a no-op.
+
+---
+
+## Decision
+
+Use `require 'active_support/all'` and treat ActiveSupport as a first-class runtime dependency (`spec.add_dependency 'activesupport', '~> 8.0.0'`).
+
+ActiveSupport utilities (`present?`, `blank?`, `fetch`, safe navigation, etc.) may be used freely throughout the codebase without needing to track individual requires.
+
+---
+
+## Consequences
+
+**Benefits:**
+- No custom utility reimplementations to maintain
+- Any ActiveSupport method is available anywhere in the codebase without an explicit require
+- No startup overhead in Rails applications (AS already loaded)
+- Minimal overhead in non-Rails applications due to AS autoloading
+
+**Trade-offs:**
+- `activesupport` is pinned to `~> 8.0.0` — non-Rails Ruby applications must accept this dependency; a future major AS version bump requires a Safire dependency update
+- Developers unfamiliar with AS may not recognise AS methods as external — mitigated by the fact that AS conventions (`present?`, `blank?`) are widely known in the Ruby ecosystem

data/docs/adr/ADR-002-facade-and-forwardable.md

@@ -0,0 +1,79 @@
+---
+layout: default
+title: "ADR-002: Facade pattern — Client delegates to protocol implementations via Forwardable"
+parent: Architecture Decision Records
+nav_order: 2
+---
+
+# ADR-002: Facade pattern — `Client` delegates to protocol implementations via `Forwardable`
+
+**Status:** Accepted
+
+---
+
+## Context
+
+Safire must support multiple authorization protocols (SMART on FHIR, UDAP) from a single public entry point. There are several ways to structure this:
+
+**Option A — Monolithic `Client`:** implement all protocol logic directly inside `Safire::Client`. Simple at first, but grows unbounded as each protocol adds methods, and makes it impossible to test protocol logic in isolation.
+
+**Option B — Inheritance:** `Safire::Client` is an abstract base class; `SmartClient` and `UdapClient` subclass it. Callers would instantiate the concrete subclass. This leaks implementation details to callers (they must know which subclass to pick) and makes the `protocol:` keyword redundant.
+
+**Option C — Strategy pattern via instance variable:** `Client` holds a `@protocol_client` strategy object and calls it manually in every method. Works, but every delegated method requires a boilerplate wrapper with the same `def method_name(...); @protocol_client.method_name(...); end` pattern.
+
+**Option D — Facade with `Forwardable`:** `Client` is a thin facade. It resolves configuration, validates `protocol:` and `client_type:`, constructs the appropriate protocol implementation lazily, and then delegates all public methods to it using Ruby's `Forwardable` module.
+
+The core requirement that drives the choice is: **callers must use a single, stable class (`Safire::Client`) regardless of which protocol they need.** Adding a new protocol must not change the public API or require callers to change their code.
+
+---
+
+## Decision
+
+`Safire::Client` is a facade. It owns:
+- Configuration resolution (hash → `ClientConfig`)
+- Protocol and client type validation
+- Lazy construction of the protocol implementation (`@protocol_client`)
+- Delegation of all public protocol methods via `Forwardable`
+
+```ruby
+class Client
+  extend Forwardable
+
+  def_delegators :protocol_client,
+                 :server_metadata, :authorization_url,
+                 :request_access_token, :refresh_token,
+                 :token_response_valid?, :register_client
+
+  private
+
+  def protocol_client
+    @protocol_client ||= PROTOCOL_CLASSES.fetch(@protocol).new(config, client_type:)
+  end
+end
+```
+
+Protocol implementations (`Protocols::Smart`, future `Protocols::Udap`) include `Protocols::Behaviours` to declare the required interface. Adding a new protocol requires:
+1. Implementing the `Behaviours` interface in a new class
+2. Adding the class to `PROTOCOL_CLASSES`
+3. Adding its valid client types to `PROTOCOL_CLIENT_TYPES`
+
+No changes to `Client` itself.
+
+**Why `Forwardable` over `method_missing`:** `Forwardable` is explicit — the delegated method list is visible in the class body, easy to grep, and YARD-documented. `method_missing` is implicit, difficult to introspect, and catches typos silently.
+
+**Why `Forwardable` over manual wrappers:** manual wrappers require writing the same boilerplate for every method and must be updated whenever a method signature changes. `def_delegators` is a single declaration.
+
+---
+
+## Consequences
+
+**Benefits:**
+- Public API (`Safire::Client`) is stable — callers never need to change when a new protocol is added
+- Protocol implementations are independently testable
+- `Forwardable` delegation is explicit and greppable
+- The `protocol:` keyword cleanly selects the implementation class without leaking subclass names to callers
+- `client_type=` mutation works naturally — the facade updates `@protocol_client` in place (see [ADR-006]({% link adr/ADR-006-lazy-discovery.md %}) for why this preserves cached discovery)
+
+**Trade-offs:**
+- `Client` itself has no runtime behaviour — all logic lives in protocol classes; contributors must know to look in `Protocols::Smart` for SMART logic, not in `Client`
+- `def_delegators` does not forward keyword arguments transparently in all Ruby versions — method signatures in `Behaviours` must be compatible with delegation

data/docs/adr/ADR-003-protocol-vs-client-type.md

@@ -0,0 +1,67 @@
+---
+layout: default
+title: "ADR-003: protocol: and client_type: as orthogonal dimensions"
+parent: Architecture Decision Records
+nav_order: 3
+---
+
+# ADR-003: `protocol:` and `client_type:` as orthogonal dimensions
+
+**Status:** Accepted
+
+---
+
+## Context
+
+`Safire::Client` needs to support multiple healthcare authorization protocols (SMART on FHIR, UDAP) and, within SMART, multiple client authentication methods (public, confidential symmetric, confidential asymmetric). There are two ways to model this:
+
+**Option A — flat enum:** a single parameter enumerating every combination.
+
+```ruby
+Safire::Client.new(config, auth: :smart_public)
+Safire::Client.new(config, auth: :smart_confidential_symmetric)
+Safire::Client.new(config, auth: :udap_b2b)
+```
+
+**Option B — two orthogonal keyword arguments:** one for the protocol, one for the client type within that protocol.
+
+```ruby
+Safire::Client.new(config, protocol: :smart, client_type: :public)
+Safire::Client.new(config, protocol: :smart, client_type: :confidential_symmetric)
+Safire::Client.new(config, protocol: :udap)  # client_type not applicable
+```
+
+The key structural difference: SMART has three client authentication methods; UDAP has none — UDAP always authenticates via signed JWT assertions (AnT) with an X.509 certificate chain, and this is not user-configurable. Mixing them into one flat enum would create invalid combinations (`:udap_public`, `:udap_confidential_symmetric`) and make `client_type=` mutation impossible to express cleanly.
+
+---
+
+## Decision
+
+Two orthogonal keyword arguments: `protocol:` selects the protocol implementation class; `client_type:` is a SMART-specific parameter that controls the token endpoint authentication method.
+
+```ruby
+VALID_PROTOCOLS = %i[smart udap].freeze
+
+PROTOCOL_CLIENT_TYPES = {
+  smart: %i[public confidential_symmetric confidential_asymmetric],
+  udap:  nil   # not user-configurable; AnT with x5c always used
+}.freeze
+```
+
+- `protocol:` is validated against `VALID_PROTOCOLS`; an unknown protocol raises `ConfigurationError`
+- `client_type:` is validated against `PROTOCOL_CLIENT_TYPES[@protocol]`; if `nil` (UDAP), validation is skipped and the setter logs a warning and no-ops rather than raising
+- Changing `client_type=` on a SMART client updates the underlying protocol client in place — already-fetched server metadata is preserved and no re-discovery occurs
+
+---
+
+## Consequences
+
+**Benefits:**
+- No invalid combinations — UDAP has no client type choices at all; this is enforced at the type level, not with runtime checks
+- `client_type=` mutation is clean and natural for the "discover first, then select client type" pattern
+- Adding a new SMART client type requires only adding a symbol to `PROTOCOL_CLIENT_TYPES[:smart]`
+- Adding a new protocol requires adding a class to `PROTOCOL_CLASSES` and an entry to `PROTOCOL_CLIENT_TYPES`
+
+**Trade-offs:**
+- Two keyword args instead of one — a caller needs to know which dimension belongs to which kwarg; mitigated by clear documentation and validation errors that name the invalid parameter
+- `client_type:` defaults to `:public` even when `protocol: :udap` — the value is ignored for UDAP, but setting it is technically a no-op with a warning rather than an error; this is intentional for resilience in generic caller code

data/docs/adr/ADR-004-clientconfig-immutability-and-entity-masking.md

@@ -0,0 +1,59 @@
+---
+layout: default
+title: "ADR-004: ClientConfig immutability and Entity sensitive attribute masking"
+parent: Architecture Decision Records
+nav_order: 4
+---
+
+# ADR-004: `ClientConfig` immutability and `Entity` sensitive attribute masking
+
+**Status:** Accepted
+
+---
+
+## Context
+
+`ClientConfig` holds all credentials and endpoints for a Safire client — including `client_secret` and `private_key`. Two separate concerns need to be addressed:
+
+**Concern 1 — Mutability:** should `ClientConfig` allow attributes to be changed after construction?
+
+Mutable configuration creates subtle bugs in concurrent environments: a `ClientConfig` instance shared across threads could have its `client_secret` changed mid-request. It also makes it impossible to reason about the state of a client at any point after construction, because any attribute may have been changed.
+
+**Concern 2 — Sensitive data leakage:** Ruby's default `inspect` and `to_s` output every instance variable. In a Rails application, an unhandled exception containing a `ClientConfig` would dump `client_secret` and `private_key` into error logs, exception trackers (Sentry, Datadog), and any other logging middleware.
+
+These two concerns are related: if `ClientConfig` is mutable, masking is harder to guarantee (a new value could be assigned via a setter without going through the masking layer).
+
+---
+
+## Decision
+
+**`ClientConfig` is immutable after construction.** All attributes are `attr_reader` only — no setters. Validation runs once at construction. After `initialize` returns, the object's state cannot change.
+
+**Sensitive attributes are masked at two layers** via the `Entity` base class:
+
+**Layer 1 — `#to_hash`:** the `sensitive_attributes` hook (overridden in `ClientConfig` to return `[:client_secret, :private_key]`) causes those values to appear as `'[FILTERED]'` in any hash serialisation.
+
+```ruby
+def to_hash
+  ATTRIBUTES.each_with_object({}) do |attr, hash|
+    value = send(attr)
+    hash[attr] = sensitive_attributes.include?(attr) ? '[FILTERED]' : value
+  end
+end
+```
+
+**Layer 2 — `#inspect`:** `ClientConfig` overrides `inspect` directly, emitting `[FILTERED]` for sensitive attributes. This prevents credential leakage in exception backtraces, IRB/pry sessions, and logging middleware that calls `inspect` on objects.
+
+---
+
+## Consequences
+
+**Benefits:**
+- Thread-safe by default — a `ClientConfig` shared across threads has no mutable state
+- Credentials cannot leak through `inspect`, `to_s`, exception trackers, or log output
+- Validation at construction means invalid configs are caught early, before any network calls
+- The `sensitive_attributes` hook is extensible — subclasses can add fields without modifying `Entity`
+
+**Trade-offs:**
+- Callers cannot modify a `ClientConfig` in place — they must construct a new one; this is intentional and makes state changes explicit
+- `private_key` masking means the key object itself is not serialisable via `to_hash` — callers needing to inspect or store the key must access it directly via `config.private_key`