safire 0.1.0

data/lib/safire/protocols/smart_metadata.rb

@@ -0,0 +1,231 @@
+module Safire
+  module Protocols
+    # SMART Metadata obtained from SMART on FHIR discovery endpoint. Attributes are defined
+    # as per [SMART on FHIR specification](https://build.fhir.org/ig/HL7/smart-app-launch/conformance.html#using-well-known)
+    #
+    # @!attribute [r] issuer
+    #   @return [String] conveying this system’s OpenID Connect Issuer URL. Required if the server’s
+    #     capabilities include sso-openid-connect.
+    # @!attribute [r] jwks_uri
+    #   @return [String] URL of the server’s JSON Web Key Set endpoint. Required if the server’s capabilities
+    #     include sso-openid-connect.
+    # @!attribute [r] authorization_endpoint
+    #   @return [String] URL of the server’s OAuth2 Authorization Endpoint. Required if the server’s capabilities
+    #     include launch-standalone or launch-ehr-launch.
+    # @!attribute [r] grant_types_supported
+    #   @return [Array<String>] list of OAuth2 grant types supported at the token endpoint.
+    # @!attribute [r] token_endpoint
+    #   @return [String] URL of the server’s OAuth2 Token Endpoint.
+    # @!attribute [r] token_endpoint_auth_methods_supported
+    #   @return [Array<String>] list of client authentication methods supported at the token endpoint.
+    #     Optionally provided.
+    # @!attribute [r] token_endpoint_auth_signing_alg_values_supported
+    #   @return [Array<String>] list of signing algorithms supported for JWT-based client authentication.
+    #     Optionally provided. Used for confidential asymmetric authentication.
+    # @!attribute [r] registration_endpoint
+    #   @return [String] URL of the server’s OAuth2 Dynamic Client Registration Endpoint. Optionally provided.
+    # @!attribute [r] associated_endpoints
+    #   @return [Array<Hash>] list of objects for endpoints that share the same authorization mechanism
+    #     as this FHIR endpoint, each with a “url” and “capabilities” array. Optionally provided.
+    # @!attribute [r] user_access_brand_bundle
+    #   @return [String] URL for a Brand Bundle for user-facing applications. Optionally provided.
+    # @!attribute [r] user_access_brand_identifier
+    #   @return [String] Identifier for the primary entry in a Brand Bundle. Optionally provided.
+    # @!attribute [r] scopes_supported
+    #   @return [Array<String>] list of scopes a client may request. Optionally provided.
+    # @!attribute [r] response_types_supported
+    #   @return [Array<String>] list of OAuth2 response types supported. Optionally provided.
+    # @!attribute [r] management_endpoint
+    #   @return [String] URL where an end-user can view which applications currently have access to data
+    #     and can make adjustments to these access rights. Optionally provided.
+    # @!attribute [r] introspection_endpoint
+    #   @return [String] URL to a server’s introspection endpoint that can be used to validate a token.
+    #     Optionally provided.
+    # @!attribute [r] revocation_endpoint
+    #   @return [String] URL to a server’s revocation endpoint that can be used to revoke a token.
+    #     Optionally provided.
+    # @!attribute [r] capabilities
+    #   @return [Array<String>] list of SMART capabilities supported by the server.
+    # @!attribute [r] code_challenge_methods_supported
+    #   @return [Array<String>] list of PKCE code challenge methods supported. Should include "S256".
+    #     Should not include "plain". See {#valid?} for compliance checks.
+    class SmartMetadata < Safire::Entity
+      REQUIRED_ATTRIBUTES = %i[
+        grant_types_supported token_endpoint capabilities
+        code_challenge_methods_supported
+      ].freeze
+
+      OPTIONAL_ATTRIBUTES = %i[
+        issuer
+        jwks_uri
+        authorization_endpoint
+        token_endpoint_auth_methods_supported
+        token_endpoint_auth_signing_alg_values_supported
+        registration_endpoint
+        associated_endpoints
+        user_access_brand_bundle
+        user_access_brand_identifier
+        scopes_supported
+        response_types_supported
+        management_endpoint
+        introspection_endpoint
+        revocation_endpoint
+      ].freeze
+
+      ATTRIBUTES = (REQUIRED_ATTRIBUTES | OPTIONAL_ATTRIBUTES).freeze
+
+      # Supported asymmetric signing algorithms (required by SMART spec)
+      SUPPORTED_ASYMMETRIC_ALGORITHMS = %w[RS384 ES384].freeze
+
+      attr_reader(*ATTRIBUTES)
+
+      def initialize(metadata)
+        super(metadata, ATTRIBUTES)
+      end
+
+      # Checks whether the server's SMART metadata is valid according to SMART App Launch 2.2.0.
+      #
+      # This is a user-callable helper. Safire performs discovery without automatically
+      # asserting server compliance — it is the caller's responsibility to invoke this
+      # method when they wish to verify conformance.
+      #
+      # Checks performed:
+      # - All required fields are present
+      #   (token_endpoint, grant_types_supported, capabilities, code_challenge_methods_supported)
+      # - Conditional fields present when their capability is advertised
+      #   (issuer + jwks_uri for sso-openid-connect; authorization_endpoint for launch types)
+      # - `code_challenge_methods_supported` includes 'S256'
+      #   (SMART App Launch 2.2.0, §Conformance — SHALL be included)
+      # - `code_challenge_methods_supported` does NOT include 'plain'
+      #   (SMART App Launch 2.2.0, §Conformance — SHALL NOT be included)
+      #
+      # A warning is logged for each SMART 2.2.0 violation detected.
+      #
+      # @return [Boolean] true if all checks pass, false if any violation is found
+      def valid?
+        required_attrs = [*REQUIRED_ATTRIBUTES]
+        required_attrs.push(:issuer, :jwks_uri) if issuer_and_jwks_uri_required?
+        required_attrs.push(:authorization_endpoint) if authorization_endpoint_required?
+
+        missing_attrs = required_attrs.reject { |attr| public_send(attr) }
+        missing_attrs.each do |attr|
+          Safire.logger.warn("SMART metadata non-compliance: required field '#{attr}' is missing")
+        end
+
+        pkce_valid = validate_pkce_methods!
+
+        missing_attrs.empty? && pkce_valid
+      end
+
+      # Launch type support checks - requires both capability and authorization_endpoint
+
+      def supports_ehr_launch?
+        ehr_launch_capability? && authorization_endpoint.present?
+      end
+
+      def supports_standalone_launch?
+        standalone_launch_capability? && authorization_endpoint.present?
+      end
+
+      # Authentication type support checks
+
+      # Checks if the server supports public client authentication.
+      # @return [Boolean] true if server has client-public capability
+      def supports_public_auth?
+        capability?('client-public')
+      end
+
+      # Checks if the server supports confidential symmetric authentication.
+      # @return [Boolean] true if server has capability and auth methods not advertised or includes client_secret_basic
+      def supports_symmetric_auth?
+        capability?('client-confidential-symmetric') &&
+          (token_endpoint_auth_methods_supported.blank? ||
+           token_endpoint_auth_methods_supported.include?('client_secret_basic'))
+      end
+
+      # Checks if the server supports confidential asymmetric authentication.
+      # @return [Boolean] true if server has capability, auth methods not advertised or includes private_key_jwt,
+      #   and has supported algorithms
+      def supports_asymmetric_auth?
+        capability?('client-confidential-asymmetric') &&
+          (token_endpoint_auth_methods_supported.blank? ||
+           token_endpoint_auth_methods_supported.include?('private_key_jwt')) &&
+          asymmetric_signing_algorithms_supported.any?
+      end
+
+      # Returns the asymmetric signing algorithms supported by both client and server.
+      # If the server doesn't advertise algorithms, assumes it supports the required ones (RS384, ES384).
+      # @return [Array<String>] list of supported algorithms
+      def asymmetric_signing_algorithms_supported
+        server_algs = token_endpoint_auth_signing_alg_values_supported.presence
+        (server_algs || SUPPORTED_ASYMMETRIC_ALGORITHMS) & SUPPORTED_ASYMMETRIC_ALGORITHMS
+      end
+
+      # Feature support checks
+
+      def supports_post_based_authorization?
+        capability?('authorize-post')
+      end
+
+      def supports_openid_connect?
+        openid_connect_capability? && issuer.present? && jwks_uri.present?
+      end
+
+      # Capability-only checks (does not verify required fields are present)
+
+      def ehr_launch_capability?
+        capability?('launch-ehr')
+      end
+
+      def standalone_launch_capability?
+        capability?('launch-standalone')
+      end
+
+      def openid_connect_capability?
+        capability?('sso-openid-connect')
+      end
+
+      private
+
+      def capability?(name)
+        capabilities&.include?(name)
+      end
+
+      def issuer_and_jwks_uri_required?
+        openid_connect_capability?
+      end
+
+      def authorization_endpoint_required?
+        ehr_launch_capability? || standalone_launch_capability?
+      end
+
+      # Validates PKCE code challenge methods per SMART App Launch 2.2.0:
+      # - 'S256' SHALL be included
+      # - 'plain' SHALL NOT be included
+      #
+      # @return [Boolean] true if both conditions are satisfied
+      def validate_pkce_methods!
+        methods = code_challenge_methods_supported
+        valid = true
+
+        unless methods&.include?('S256')
+          Safire.logger.warn(
+            "SMART metadata non-compliance: 'S256' is missing from code_challenge_methods_supported " \
+            '(SMART App Launch 2.2.0 requires S256)'
+          )
+          valid = false
+        end
+
+        if methods&.include?('plain')
+          Safire.logger.warn(
+            "SMART metadata non-compliance: 'plain' is present in code_challenge_methods_supported " \
+            '(SMART App Launch 2.2.0 prohibits plain)'
+          )
+          valid = false
+        end
+
+        valid
+      end
+    end
+  end
+end

data/lib/safire/version.rb

@@ -0,0 +1,4 @@
+# lib/safire/version.rb
+module Safire
+  VERSION = '0.1.0'.freeze
+end

data/lib/safire.rb

@@ -0,0 +1,54 @@
+require 'logger'
+require 'active_support/all'
+require 'addressable/uri'
+require 'base64'
+
+require_relative 'safire/version'
+require_relative 'safire/errors'
+require_relative 'safire/middleware/https_only_redirects'
+require_relative 'safire/http_client'
+require_relative 'safire/entity'
+require_relative 'safire/pkce'
+require_relative 'safire/jwt_assertion'
+
+root = File.expand_path '.', File.dirname(File.absolute_path(__FILE__))
+Dir.glob(File.join(root, 'safire', 'protocols', '**', '*.rb')).each do |file|
+  require file
+end
+
+require_relative 'safire/client_config_builder'
+require_relative 'safire/client_config'
+require_relative 'safire/client'
+
+# Main module for Safire gem
+module Safire
+  class << self
+    attr_reader :configuration
+
+    def configure
+      @configuration ||= Configuration.new
+      yield(configuration)
+    end
+
+    def logger
+      log = configuration&.logger || default_logger
+      log.level = configuration.log_level if configuration&.log_level && log.respond_to?(:level=)
+      log
+    end
+
+    def default_logger
+      @default_logger ||= Logger.new(ENV['SAFIRE_LOGGER'] || $stdout).tap do |l|
+        l.level = Logger::INFO
+      end
+    end
+  end
+
+  class Configuration
+    attr_accessor :logger, :log_level, :user_agent, :log_http
+
+    def initialize
+      @user_agent = "Safire v#{Safire::VERSION}"
+      @log_http   = true
+    end
+  end
+end

data/safire.gemspec

@@ -0,0 +1,36 @@
+# safire.gemspec
+require_relative 'lib/safire/version'
+
+Gem::Specification.new do |spec|
+  spec.name                  = 'safire'
+  spec.version               = Safire::VERSION
+  spec.authors               = ['Vanessa Fotso']
+  spec.email                 = ['vanessuniq@gmail.com']
+  spec.summary               = 'SMART on FHIR and UDAP implementation for Ruby'
+  spec.description           = 'A Ruby gem implementing SMART on FHIR and UDAP protocols for clients.'
+  spec.homepage              = 'https://github.com/vanessuniq/safire'
+  spec.license               = 'Apache-2.0'
+  spec.required_ruby_version = Gem::Requirement.new('>= 4.0.2')
+
+  spec.metadata['source_code_uri']   = spec.homepage
+  spec.metadata['changelog_uri']     = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['documentation_uri'] = 'https://vanessuniq.github.io/safire'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ examples/ .git .github appveyor])
+    end
+  end
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  # Runtime deps
+  spec.add_dependency 'activesupport', '~> 8.0.0'
+  spec.add_dependency 'addressable', '~> 2.8'
+  spec.add_dependency 'faraday', '~> 2.14'
+  spec.add_dependency 'faraday-follow_redirects', '~> 0.4'
+  spec.add_dependency 'jwt', '~> 2.8'
+end

metadata

@@ -0,0 +1,184 @@
+--- !ruby/object:Gem::Specification
+name: safire
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Vanessa Fotso
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 8.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 8.0.0
+- !ruby/object:Gem::Dependency
+  name: addressable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.14'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.14'
+- !ruby/object:Gem::Dependency
+  name: faraday-follow_redirects
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+description: A Ruby gem implementing SMART on FHIR and UDAP protocols for clients.
+email:
+- vanessuniq@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- ".tool-versions"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- CONTRIBUTION.md
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- ROADMAP.md
+- Rakefile
+- docs/.gitignore
+- docs/404.html
+- docs/Gemfile
+- docs/Gemfile.lock
+- docs/_config.yml
+- docs/_includes/footer_custom.html
+- docs/_includes/head_custom.html
+- docs/_sass/custom/custom.scss
+- docs/adr/ADR-001-activesupport-dependency.md
+- docs/adr/ADR-002-facade-and-forwardable.md
+- docs/adr/ADR-003-protocol-vs-client-type.md
+- docs/adr/ADR-004-clientconfig-immutability-and-entity-masking.md
+- docs/adr/ADR-005-per-client-http-ownership.md
+- docs/adr/ADR-006-lazy-discovery.md
+- docs/adr/ADR-007-https-only-redirects-and-localhost-exception.md
+- docs/adr/ADR-008-warn-return-false-for-compliance-validation.md
+- docs/adr/index.md
+- docs/advanced.md
+- docs/configuration/client-setup.md
+- docs/configuration/index.md
+- docs/configuration/logging.md
+- docs/index.md
+- docs/installation.md
+- docs/security.md
+- docs/smart-on-fhir/confidential-asymmetric/authorization.md
+- docs/smart-on-fhir/confidential-asymmetric/index.md
+- docs/smart-on-fhir/confidential-asymmetric/token-exchange.md
+- docs/smart-on-fhir/confidential-symmetric/authorization.md
+- docs/smart-on-fhir/confidential-symmetric/index.md
+- docs/smart-on-fhir/confidential-symmetric/token-exchange.md
+- docs/smart-on-fhir/discovery/capability-checks.md
+- docs/smart-on-fhir/discovery/index.md
+- docs/smart-on-fhir/discovery/metadata.md
+- docs/smart-on-fhir/index.md
+- docs/smart-on-fhir/post-based-authorization.md
+- docs/smart-on-fhir/public-client/authorization.md
+- docs/smart-on-fhir/public-client/index.md
+- docs/smart-on-fhir/public-client/token-exchange.md
+- docs/troubleshooting/auth-errors.md
+- docs/troubleshooting/client-errors.md
+- docs/troubleshooting/index.md
+- docs/troubleshooting/token-errors.md
+- docs/udap.md
+- lib/safire.rb
+- lib/safire/client.rb
+- lib/safire/client_config.rb
+- lib/safire/client_config_builder.rb
+- lib/safire/entity.rb
+- lib/safire/errors.rb
+- lib/safire/http_client.rb
+- lib/safire/jwt_assertion.rb
+- lib/safire/middleware/https_only_redirects.rb
+- lib/safire/pkce.rb
+- lib/safire/protocols/behaviours.rb
+- lib/safire/protocols/smart.rb
+- lib/safire/protocols/smart_metadata.rb
+- lib/safire/version.rb
+- safire.gemspec
+homepage: https://github.com/vanessuniq/safire
+licenses:
+- Apache-2.0
+metadata:
+  source_code_uri: https://github.com/vanessuniq/safire
+  changelog_uri: https://github.com/vanessuniq/safire/blob/main/CHANGELOG.md
+  documentation_uri: https://vanessuniq.github.io/safire
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: SMART on FHIR and UDAP implementation for Ruby
+test_files: []