safire 0.1.0

data/lib/safire/client_config_builder.rb

@@ -0,0 +1,72 @@
+module Safire
+  # ClientConfigBuilder helps to build a Safire::ClientConfig instance
+  class ClientConfigBuilder
+    def initialize
+      @config = {}
+    end
+
+    def base_url(url)
+      @config[:base_url] = url
+      self
+    end
+
+    def issuer(issuer)
+      @config[:issuer] = issuer
+      self
+    end
+
+    def client_id(client_id)
+      @config[:client_id] = client_id
+      self
+    end
+
+    def client_secret(client_secret)
+      @config[:client_secret] = client_secret
+      self
+    end
+
+    def redirect_uri(uri)
+      @config[:redirect_uri] = uri
+      self
+    end
+
+    def scopes(scopes)
+      @config[:scopes] = scopes
+      self
+    end
+
+    def authorization_endpoint(authorization_endpoint)
+      @config[:authorization_endpoint] = authorization_endpoint
+      self
+    end
+
+    def token_endpoint(token_endpoint)
+      @config[:token_endpoint] = token_endpoint
+      self
+    end
+
+    def private_key(private_key)
+      @config[:private_key] = private_key
+      self
+    end
+
+    def kid(kid)
+      @config[:kid] = kid
+      self
+    end
+
+    def jwt_algorithm(jwt_algorithm)
+      @config[:jwt_algorithm] = jwt_algorithm
+      self
+    end
+
+    def jwks_uri(jwks_uri)
+      @config[:jwks_uri] = jwks_uri
+      self
+    end
+
+    def build
+      Safire::ClientConfig.new(@config)
+    end
+  end
+end

data/lib/safire/entity.rb

@@ -0,0 +1,26 @@
+module Safire
+  class Entity
+    def initialize(params, attributes)
+      attributes.each { |name| instance_variable_set("@#{name}", params[name] || params[name.to_s]) }
+    end
+
+    def to_hash
+      hash = {}
+      instance_variables.each do |var|
+        key = var.to_s.delete_prefix('@').to_sym
+        value = instance_variable_get(var)
+        hash[key] = sensitive_attributes.include?(key) && !value.nil? ? '[FILTERED]' : value
+      end
+      hash.deep_symbolize_keys
+    end
+
+    protected
+
+    # Returns attribute names whose values are masked as '[FILTERED]' in #to_hash.
+    #
+    # @return [Array<Symbol>]
+    def sensitive_attributes
+      []
+    end
+  end
+end

data/lib/safire/errors.rb

@@ -0,0 +1,247 @@
+module Safire
+  # Namespace for all Safire error classes.
+  #
+  # Every Safire error inherits from {Error} so consumers can rescue
+  # all Safire errors with a single +rescue Safire::Errors::Error+.
+  # Each subclass exposes typed, domain-specific attributes and builds
+  # its own human-readable message.
+  #
+  # @example Rescuing a specific error
+  #   begin
+  #     tokens = client.request_access_token(code: code, code_verifier: verifier)
+  #   rescue Safire::Errors::TokenError => e
+  #     puts e.message        # "Token request failed — HTTP 401 — invalid_grant — Code expired"
+  #     puts e.status         # 401
+  #     puts e.error_code     # "invalid_grant"
+  #   rescue Safire::Errors::Error => e
+  #     puts e.message        # catch-all for any other Safire error
+  #   end
+  module Errors
+    # Base class — rescue anchor only. All Safire errors inherit from this.
+    class Error < StandardError; end
+
+    # Raised when client configuration is missing or invalid.
+    #
+    # @!attribute [r] missing_attributes
+    #   @return [Array<Symbol>] required attributes that are absent
+    # @!attribute [r] invalid_attribute
+    #   @return [Symbol, nil] attribute whose value is not acceptable
+    # @!attribute [r] invalid_value
+    #   @return [Object, nil] the offending value
+    # @!attribute [r] valid_values
+    #   @return [Array, nil] acceptable values for the attribute
+    # @!attribute [r] invalid_uri_attributes
+    #   @return [Array<Symbol>] attributes whose URIs are malformed
+    # @!attribute [r] non_https_uri_attributes
+    #   @return [Array<Symbol>] attributes whose URIs use HTTP on a non-localhost host
+    class ConfigurationError < Error
+      attr_reader :missing_attributes, :invalid_attribute, :invalid_value, :valid_values,
+                  :invalid_uri_attributes, :non_https_uri_attributes
+
+      def initialize(missing_attributes: [], invalid_attribute: nil, invalid_value: nil,
+                     valid_values: nil, invalid_uri_attributes: [], non_https_uri_attributes: [])
+        @missing_attributes     = Array(missing_attributes)
+        @invalid_attribute      = invalid_attribute
+        @invalid_value          = invalid_value
+        @valid_values           = valid_values
+        @invalid_uri_attributes = Array(invalid_uri_attributes)
+        @non_https_uri_attributes = Array(non_https_uri_attributes)
+        super(build_message)
+      end
+
+      private
+
+      def build_message
+        if @missing_attributes.any?
+          "Configuration missing: #{@missing_attributes.join(', ')}"
+        elsif @invalid_attribute
+          "Invalid #{@invalid_attribute}: #{@invalid_value.inspect}; valid: #{@valid_values&.join(', ')}"
+        else
+          build_uri_message
+        end
+      end
+
+      def build_uri_message
+        parts = []
+        parts << "Configuration has invalid URIs: #{@invalid_uri_attributes.join(', ')}" if @invalid_uri_attributes.any?
+        if @non_https_uri_attributes.any?
+          parts << "Configuration requires HTTPS for: #{@non_https_uri_attributes.join(', ')} " \
+                   '(SMART App Launch 2.2.0 requires TLS; HTTP is only allowed for localhost)'
+        end
+        parts.any? ? parts.join('. ') : 'Configuration error'
+      end
+    end
+
+    # Raised when SMART configuration discovery fails.
+    #
+    # @!attribute [r] endpoint
+    #   @return [String] the discovery endpoint URL that was requested
+    # @!attribute [r] status
+    #   @return [Integer, nil] HTTP status code returned by the server
+    # @!attribute [r] error_description
+    #   @return [String, nil] description of why discovery failed (e.g. unexpected response format)
+    class DiscoveryError < Error
+      attr_reader :endpoint, :status, :error_description
+
+      def initialize(endpoint:, status: nil, error_description: nil)
+        @endpoint          = endpoint
+        @status            = status
+        @error_description = error_description
+        super(build_message)
+      end
+
+      private
+
+      def build_message
+        msg = "Failed to discover SMART configuration from #{@endpoint}"
+        msg += " (HTTP #{@status})" if @status
+        msg += ": #{@error_description}" if @error_description
+        msg
+      end
+    end
+
+    # Raised for token exchange or refresh failures.
+    #
+    # Two usage paths:
+    # - HTTP failure: provide +status+, +error_code+, and/or +error_description+
+    # - Structural failure (missing +access_token+): provide +received_fields+
+    #
+    # @!attribute [r] status
+    #   @return [Integer, nil] HTTP status code
+    # @!attribute [r] error_code
+    #   @return [String, nil] OAuth2 +error+ field (e.g. +"invalid_grant"+)
+    # @!attribute [r] error_description
+    #   @return [String, nil] OAuth2 +error_description+ field
+    # @!attribute [r] received_fields
+    #   @return [Array<String>, nil] field names present in an invalid token response (no values)
+    class TokenError < Error
+      attr_reader :status, :error_code, :error_description, :received_fields
+
+      def initialize(status: nil, error_code: nil, error_description: nil, received_fields: nil)
+        @status            = status
+        @error_code        = error_code
+        @error_description = error_description
+        @received_fields   = received_fields
+        super(build_message)
+      end
+
+      private
+
+      def build_message
+        if @received_fields
+          "Missing access token in response; received fields: #{@received_fields.join(', ')}"
+        else
+          parts = ['Token request failed']
+          parts << "HTTP #{@status}" if @status
+          parts << @error_code if @error_code
+          parts << @error_description if @error_description
+          parts.join(' — ')
+        end
+      end
+    end
+
+    # Raised when an authorization request fails.
+    #
+    # @!attribute [r] status
+    #   @return [Integer, nil] HTTP status code
+    # @!attribute [r] error_code
+    #   @return [String, nil] OAuth2 +error+ field
+    # @!attribute [r] error_description
+    #   @return [String, nil] OAuth2 +error_description+ field
+    class AuthError < Error
+      attr_reader :status, :error_code, :error_description
+
+      def initialize(status: nil, error_code: nil, error_description: nil)
+        @status            = status
+        @error_code        = error_code
+        @error_description = error_description
+        super(build_message)
+      end
+
+      private
+
+      def build_message
+        parts = ['Authorization request failed']
+        parts << "HTTP #{@status}" if @status
+        parts << @error_code if @error_code
+        parts << @error_description if @error_description
+        parts.join(' — ')
+      end
+    end
+
+    # Raised for X.509 certificate errors (e.g., in UDAP flows).
+    #
+    # @!attribute [r] reason
+    #   @return [String, nil] why the certificate is invalid (e.g. +"expired"+, +"untrusted"+)
+    # @!attribute [r] subject
+    #   @return [String, nil] certificate subject string (safe to log)
+    class CertificateError < Error
+      attr_reader :reason, :subject
+
+      def initialize(reason: nil, subject: nil)
+        @reason  = reason
+        @subject = subject
+        super(build_message)
+      end
+
+      private
+
+      def build_message
+        parts = ['Certificate error']
+        parts << @reason if @reason
+        parts << "(subject: #{@subject})" if @subject
+        parts.join(' — ')
+      end
+    end
+
+    # Raised when an HTTP request fails at the network or transport level
+    # (connection refused, timeout, SSL handshake failure, etc.).
+    #
+    # @!attribute [r] error_description
+    #   @return [String, nil] the underlying transport error message
+    class NetworkError < Error
+      attr_reader :error_description
+
+      def initialize(error_description: nil)
+        @error_description = error_description
+        super(build_message)
+      end
+
+      private
+
+      def build_message
+        return 'HTTP request failed' unless @error_description
+
+        "HTTP request failed: #{@error_description}"
+      end
+    end
+
+    # Raised for input validation errors.
+    #
+    # @!attribute [r] attribute
+    #   @return [Symbol, nil] the attribute that failed validation
+    # @!attribute [r] reason
+    #   @return [String, nil] why validation failed
+    class ValidationError < Error
+      attr_reader :attribute, :reason
+
+      def initialize(attribute: nil, reason: nil)
+        @attribute = attribute
+        @reason    = reason
+        super(build_message)
+      end
+
+      private
+
+      def build_message
+        if @attribute && @reason
+          "Validation failed for #{@attribute}: #{@reason}"
+        elsif @attribute
+          "Validation failed for #{@attribute}"
+        else
+          'Validation error'
+        end
+      end
+    end
+  end
+end

data/lib/safire/http_client.rb

@@ -0,0 +1,87 @@
+require 'active_support/all'
+require 'faraday'
+require 'faraday/follow_redirects'
+
+module Safire
+  # HTTP client wrapper for Safire
+  class HTTPClient
+    def initialize(base_url: nil, adapter: nil, request_format: :url_encoded, ssl_options: {})
+      @options = {
+        url: normalize_base_url(base_url),
+        ssl: ssl_options,
+        headers: {
+          'User-Agent' => Safire.configuration&.user_agent || "Safire v#{Safire::VERSION}",
+          'Accept' => 'application/json'
+        }
+      }
+      @adapter = adapter || Faraday.default_adapter
+      @request_format = request_format.to_sym
+      warn_if_ssl_verification_disabled(ssl_options)
+      @connection = build_connection
+    end
+
+    def get(path = '', params: {}, headers: {})
+      request(:get, path, params:, headers:)
+    end
+
+    def post(path = '', body: nil, params: {}, headers: {})
+      request(:post, path, body:, params:, headers:)
+    end
+
+    def put(path = '', body: nil, params: {}, headers: {})
+      request(:put, path, body:, params:, headers:)
+    end
+
+    def delete(path = '', params: {}, headers: {})
+      request(:delete, path, params:, headers:)
+    end
+
+    private
+
+    def build_connection
+      Faraday.new(@options) do |builder|
+        builder.request @request_format
+        builder.response :follow_redirects
+        builder.use Safire::Middleware::HttpsOnlyRedirects
+        builder.response :json
+        builder.response :raise_error
+        configure_logger(builder)
+        builder.adapter @adapter
+      end
+    end
+
+    def configure_logger(builder)
+      return if Safire.configuration&.log_http == false
+
+      builder.response :logger, Safire.logger, { headers: { request: true, response: true }, bodies: false } do |logger|
+        logger.filter(/(Authorization: )(.+)/, '\1[FILTERED]')
+      end
+    end
+
+    def request(method, path, body: nil, params: {}, headers: {})
+      @connection.send(method) do |req|
+        req.url path.sub(%r{^/}, '') # Remove leading slash if present since base_url ends with slash
+        req.params.update(params) if params.present?
+        req.headers.update(headers) if headers.present?
+        req.body = body if body
+      end
+    rescue Faraday::ConnectionFailed, Faraday::TimeoutError, Faraday::SSLError => e
+      raise Safire::Errors::NetworkError.new(error_description: e.message)
+    end
+
+    def warn_if_ssl_verification_disabled(ssl_options)
+      return unless ssl_options.is_a?(Hash) && ssl_options[:verify] == false
+
+      Safire.logger.warn(
+        '[Safire] ssl_options: { verify: false } disables TLS certificate verification — ' \
+        'do not use in production'
+      )
+    end
+
+    def normalize_base_url(url)
+      return '' unless url
+
+      url.ends_with?('/') ? url : "#{url}/"
+    end
+  end
+end

data/lib/safire/jwt_assertion.rb

@@ -0,0 +1,237 @@
+require 'jwt'
+require 'openssl'
+require 'securerandom'
+
+module Safire
+  # Generates JWT client assertions for SMART on FHIR confidential asymmetric authentication.
+  #
+  # This class creates signed JWTs according to the SMART App Launch STU 2.2.0 specification
+  # for private_key_jwt client authentication.
+  #
+  # @see https://hl7.org/fhir/smart-app-launch/client-confidential-asymmetric.html
+  #
+  # @example Creating a JWT assertion with RSA key
+  #   assertion = Safire::JWTAssertion.new(
+  #     client_id: 'my_app',
+  #     token_endpoint: 'https://auth.example.com/token',
+  #     private_key: OpenSSL::PKey::RSA.new(File.read('private.pem')),
+  #     kid: 'key-id-123'
+  #   )
+  #   jwt = assertion.to_jwt  # => signed JWT string
+  #
+  # @example With explicit algorithm and jku header
+  #   assertion = Safire::JWTAssertion.new(
+  #     client_id: 'my_app',
+  #     token_endpoint: 'https://auth.example.com/token',
+  #     private_key: private_key,
+  #     kid: 'key-id-123',
+  #     algorithm: 'RS384',
+  #     jku: 'https://app.example.com/.well-known/jwks.json'
+  #   )
+  #
+  class JWTAssertion
+    # Maximum expiration time allowed per SMART specification (5 minutes)
+    MAX_EXPIRATION_SECONDS = 300
+
+    # Default expiration time (5 minutes)
+    DEFAULT_EXPIRATION_SECONDS = 300
+
+    # Supported signing algorithms (required by SMART specification)
+    SUPPORTED_ALGORITHMS = %w[RS384 ES384].freeze
+
+    # Required parameters for JWT assertion
+    REQUIRED_PARAMS = %i[client_id token_endpoint kid].freeze
+
+    # EC curve names that support ES384 algorithm
+    SUPPORTED_EC_CURVES = %w[secp384r1 P-384].freeze
+
+    # Default algorithm for RSA keys (required by SMART spec)
+    DEFAULT_RSA_ALGORITHM = 'RS384'.freeze
+
+    # Default algorithm for EC keys (required by SMART spec)
+    DEFAULT_EC_ALGORITHM = 'ES384'.freeze
+
+    # @!attribute [r] client_id
+    #   @return [String] the client_id used as iss and sub claims in the JWT
+    # @!attribute [r] token_endpoint
+    #   @return [String] the token endpoint URL used as aud claim in the JWT
+    # @!attribute [r] private_key
+    #   @return [OpenSSL::PKey::RSA, OpenSSL::PKey::EC] the private key for signing the JWT
+    # @!attribute [r] kid
+    #   @return [String] the key ID matching the public key registered with the authorization server
+    # @!attribute [r] algorithm
+    #   @return [String] the signing algorithm (RS384 or ES384)
+    # @!attribute [r] jku
+    #   @return [String, nil] the optional JWKS URL included in the JWT header
+    # @!attribute [r] expiration_seconds
+    #   @return [Integer] the JWT expiration time in seconds (max 300 per SMART spec)
+    attr_reader :client_id, :token_endpoint, :private_key, :kid, :algorithm, :jku, :expiration_seconds
+
+    # Creates a new JWT assertion generator.
+    #
+    # @param client_id [String] the client_id to use as iss and sub claims
+    # @param token_endpoint [String] the token endpoint URL to use as aud claim
+    # @param private_key [OpenSSL::PKey::RSA, OpenSSL::PKey::EC, String] the private key for signing
+    #   (can be a PEM-encoded string)
+    # @param kid [String] the key ID matching the registered public key
+    # @param algorithm [String, nil] the signing algorithm (auto-detected from key type if nil)
+    # @param jku [String, nil] optional JWKS URL for jku header (must be HTTPS)
+    # @param expiration_seconds [Integer] expiration time in seconds (default: 300, max: 300)
+    #
+    # @raise [ArgumentError] if required parameters are missing or invalid
+    def initialize(client_id:, token_endpoint:, private_key:, kid:, algorithm: nil, jku: nil,
+                   expiration_seconds: DEFAULT_EXPIRATION_SECONDS)
+      @client_id = client_id
+      @token_endpoint = token_endpoint
+      @private_key = parse_private_key(private_key)
+      @kid = kid
+      @algorithm = algorithm || detect_algorithm(@private_key)
+      @jku = jku
+      @expiration_seconds = [expiration_seconds, MAX_EXPIRATION_SECONDS].min
+
+      validate!
+    end
+
+    # Generates a signed JWT assertion.
+    #
+    # @return [String] the signed JWT string
+    def to_jwt
+      JWT.encode(payload, private_key, algorithm, header)
+    end
+
+    # Returns the JWT header.
+    #
+    # @return [Hash] the JWT header with typ, kid, alg, and optional jku
+    def header
+      h = { typ: 'JWT', kid: kid, alg: algorithm }
+      h[:jku] = jku if jku.present?
+      h
+    end
+
+    # Returns the JWT payload.
+    #
+    # @return [Hash] the JWT payload with iss, sub, aud, exp, and jti claims
+    def payload
+      now = Time.now.to_i
+      { iss: client_id, sub: client_id, aud: token_endpoint, exp: now + expiration_seconds, jti: generate_jti }
+    end
+
+    private
+
+    # Parses the private key from various formats.
+    #
+    # @param key [OpenSSL::PKey::RSA, OpenSSL::PKey::EC, String, nil] the private key
+    # @return [OpenSSL::PKey::RSA, OpenSSL::PKey::EC] the parsed private key
+    # @raise [ArgumentError] if the key is invalid or unsupported
+    def parse_private_key(key)
+      case key
+      when OpenSSL::PKey::RSA, OpenSSL::PKey::EC
+        key
+      when String
+        parse_pem_key(key)
+      else
+        raise ArgumentError, 'private_key must be an OpenSSL::PKey::RSA, OpenSSL::PKey::EC, or PEM string'
+      end
+    end
+
+    # Parses a PEM-encoded private key string.
+    #
+    # @param pem [String] the PEM-encoded private key
+    # @return [OpenSSL::PKey::RSA, OpenSSL::PKey::EC] the parsed private key
+    # @raise [ArgumentError] if the PEM string is invalid
+    def parse_pem_key(pem)
+      OpenSSL::PKey.read(pem)
+    rescue OpenSSL::PKey::PKeyError => e
+      raise ArgumentError, "Invalid private key: #{e.message}"
+    end
+
+    # Detects the appropriate signing algorithm based on the key type.
+    # For RSA keys, uses RS384 (required by SMART spec).
+    # For EC keys, uses ES384 (required by SMART spec) - requires P-384 curve.
+    #
+    # @param key [OpenSSL::PKey::RSA, OpenSSL::PKey::EC] the private key
+    # @return [String] the detected algorithm
+    # @raise [ArgumentError] if the key type or EC curve is unsupported
+    def detect_algorithm(key)
+      case key
+      when OpenSSL::PKey::RSA
+        DEFAULT_RSA_ALGORITHM
+      when OpenSSL::PKey::EC
+        validate_ec_curve!(key)
+        DEFAULT_EC_ALGORITHM
+      else
+        raise ArgumentError, "Unsupported key type: #{key.class}"
+      end
+    end
+
+    # Validates that the EC key uses a supported curve (P-384 for ES384).
+    #
+    # @param key [OpenSSL::PKey::EC] the EC private key
+    # @raise [ArgumentError] if the curve is not supported
+    def validate_ec_curve!(key)
+      curve = key.group.curve_name
+      return if SUPPORTED_EC_CURVES.include?(curve)
+
+      raise ArgumentError, "Unsupported EC curve: #{curve}. ES384 requires P-384 (secp384r1) curve"
+    end
+
+    # Generates a unique JWT ID (jti) for replay protection.
+    #
+    # @return [String] a unique UUID identifier
+    def generate_jti
+      SecureRandom.uuid
+    end
+
+    # Validates the assertion configuration.
+    #
+    # @raise [ArgumentError] if validation fails
+    def validate!
+      validate_required_params!
+      validate_algorithm!
+      validate_key_algorithm_match!
+      validate_jku! if jku.present?
+    end
+
+    # Validates that required parameters are present.
+    #
+    # @raise [ArgumentError] if required parameters are missing
+    def validate_required_params!
+      missing = REQUIRED_PARAMS.select { |param| send(param).blank? }
+      return if missing.empty?
+
+      raise ArgumentError, "Missing required parameters: #{missing.to_sentence}"
+    end
+
+    # Validates the algorithm is supported.
+    #
+    # @raise [ArgumentError] if the algorithm is not supported
+    def validate_algorithm!
+      return if SUPPORTED_ALGORITHMS.include?(algorithm)
+
+      raise ArgumentError, "Unsupported algorithm: #{algorithm}. Supported: #{SUPPORTED_ALGORITHMS.to_sentence}"
+    end
+
+    # Validates the key type matches the algorithm.
+    #
+    # @raise [ArgumentError] if there is a mismatch
+    def validate_key_algorithm_match!
+      rsa_algorithm = algorithm.start_with?('RS')
+      expected_key_class = rsa_algorithm ? OpenSSL::PKey::RSA : OpenSSL::PKey::EC
+      return if private_key.is_a?(expected_key_class)
+
+      raise ArgumentError, "Algorithm #{algorithm} requires an #{rsa_algorithm ? 'RSA' : 'EC'} key"
+    end
+
+    # Validates the jku URL format.
+    #
+    # @raise [ArgumentError] if the jku is not a valid HTTPS URL
+    def validate_jku!
+      uri = URI.parse(jku)
+      return if uri.scheme == 'https'
+
+      raise ArgumentError, 'jku must be an HTTPS URL'
+    rescue URI::InvalidURIError
+      raise ArgumentError, 'jku must be a valid URL'
+    end
+  end
+end