Class: Safire::ClientConfig

Inherits:
Entity
  • Object
show all
Includes:
URIValidation
Defined in:
lib/safire/client_config.rb

Overview

Client configuration entity providing attributes for SMART authorization flows, backend services, UDAP discovery, and UDAP client signing credentials. The ClientConfig instance is passed to Safire::Client upon initialization.

client = Safire::Client.new(config)

client = Safire::Client.new(config)

Examples:

Initializing a ClientConfig

config = Safire::ClientConfig.new(
  base_url: 'https://fhir.example.com',
  client_id: 'my_client_id',
  redirect_uri: 'https://myapp.example.com/callback',
  scopes: ['openid', 'profile', 'patient/*.read']
)

Initializing a ClientConfig using the Builder

config = Safire::ClientConfig.builder
  .base_url('https://fhir.example.com')
  .client_id('my_client_id')
  .redirect_uri('https://myapp.example.com/callback')
  .scopes(['openid', 'profile', 'patient/*.read'])
  .build

See Also:

Constant Summary collapse

ATTRIBUTES = 
%i[
  base_url issuer client_id client_secret redirect_uri
  scopes authorization_endpoint token_endpoint
  private_key certificate_chain kid jwt_algorithm jwks_uri
].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Entity

#to_hash

Constructor Details

#initialize(config) ⇒ ClientConfig

Returns a new instance of ClientConfig.



86
87
88
89
90
91
92
 
# File 'lib/safire/client_config.rb', line 86

def initialize(config)
  super(config, ATTRIBUTES)

  @certificate_chain = normalize_certificate_chain(@certificate_chain)
  @issuer ||= base_url
  validate!
end

Instance Attribute Details

#authorization_endpoint ⇒ String (readonly)

=> Optional, will be retrieved from the well-known smart-configuration if not provided

Returns:

  • (String) —

    URL of the server’s OAuth2 Authorization Endpoint.



66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
 
# File 'lib/safire/client_config.rb', line 66

class ClientConfig < Entity
  include URIValidation

  ATTRIBUTES = %i[
    base_url issuer client_id client_secret redirect_uri
    scopes authorization_endpoint token_endpoint
    private_key certificate_chain kid jwt_algorithm jwks_uri
  ].freeze

  CertificateSnapshot = Data.define(:der)
  private_constant :CertificateSnapshot

  attr_reader(*(ATTRIBUTES - [:certificate_chain]))

  def certificate_chain
    return if @certificate_chain.nil?

    @certificate_chain.map { |entry| materialize_certificate_entry(entry) }.freeze
  end

  def initialize(config)
    super(config, ATTRIBUTES)

    @certificate_chain = normalize_certificate_chain(@certificate_chain)
    @issuer ||= base_url
    validate!
  end

  class << self
    def builder
      ClientConfigBuilder.new
    end
  end

  CERTIFICATE_CHAIN_ENTRY_TYPES = [String, OpenSSL::X509::Certificate].freeze
  SENSITIVE_ATTRIBUTES = %i[client_secret private_key certificate_chain].freeze
  URI_ATTRS = %i[base_url redirect_uri issuer authorization_endpoint token_endpoint jwks_uri].freeze
  OPTIONAL_URI_ATTRS = %i[redirect_uri authorization_endpoint token_endpoint jwks_uri].freeze
  private_constant :CERTIFICATE_CHAIN_ENTRY_TYPES, :SENSITIVE_ATTRIBUTES, :URI_ATTRS, :OPTIONAL_URI_ATTRS

  # @api private
  def inspect
    attrs = ATTRIBUTES.map do |attr|
      # Read stored values directly so masked compound types are not materialized before being discarded.
      value = instance_variable_get(:"@#{attr}")
      next if value.nil?

      masked = SENSITIVE_ATTRIBUTES.include?(attr) ? '[FILTERED]' : value.inspect
      "#{attr}: #{masked}"
    end.compact.join(', ')
    "#<#{self.class} #{attrs}>"
  end

  protected

  # @return [Array<Symbol>] attributes masked as '[FILTERED]' in #to_hash
  def sensitive_attributes
    SENSITIVE_ATTRIBUTES
  end

  private

  def normalize_certificate_chain(chain)
    return if chain.nil?

    validate_certificate_chain_type!(chain)
    chain.map { |entry| snapshot_certificate_entry(entry) }.freeze
  end

  def validate_certificate_chain_type!(chain)
    raise_invalid_certificate_chain!(chain.class, [Array]) unless chain.is_a?(Array)
    raise_invalid_certificate_chain!(chain.class, ['non-empty Array']) if chain.empty?

    chain.each do |entry|
      next if CERTIFICATE_CHAIN_ENTRY_TYPES.any? { |type| entry.is_a?(type) }

      raise_invalid_certificate_chain!(entry.class, CERTIFICATE_CHAIN_ENTRY_TYPES)
    end
  end

  def snapshot_certificate_entry(entry)
    return entry.dup.freeze if entry.is_a?(String)

    CertificateSnapshot.new(der: entry.to_der.freeze)
  rescue OpenSSL::X509::CertificateError
    raise_invalid_certificate_chain!(entry.class, ['serializable OpenSSL::X509::Certificate'])
  end

  def materialize_certificate_entry(entry)
    return entry unless entry.is_a?(CertificateSnapshot)

    OpenSSL::X509::Certificate.new(entry.der)
  end

  def raise_invalid_certificate_chain!(invalid_value, valid_values)
    raise Errors::ConfigurationError.new(
      invalid_attribute: :certificate_chain,
      invalid_value:,
      valid_values:
    )
  end

  # Validates all URI attributes for structure and HTTPS requirement.
  #
  # Per SMART App Launch 2.2.0 (§App Protection, §Confidential Asymmetric),
  # all exchanges involving sensitive data SHALL use TLS. All endpoint URIs
  # must therefore use the `https` scheme.
  #
  # Exception: `http` is permitted when the host is `localhost` or `127.0.0.1`
  # to support local development without a TLS termination proxy.
  #
  # @raise [Errors::ConfigurationError] if any URI is malformed or uses HTTP on a non-localhost host
  def validate_uris!
    invalid_uris, non_https_uris = collect_uri_violations
    return if invalid_uris.empty? && non_https_uris.empty?

    raise Errors::ConfigurationError.new(
      invalid_uri_attributes: invalid_uris,
      non_https_uri_attributes: non_https_uris
    )
  end

  def collect_uri_violations
    invalid_uris = []
    non_https_uris = []

    URI_ATTRS.each do |attr|
      value = send(attr)
      next if value.nil? && OPTIONAL_URI_ATTRS.include?(attr)

      case classify_uri(value)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def validate!
    raise Errors::ConfigurationError.new(missing_attributes: [:base_url]) if base_url.nil?

    validate_uris!
  end
end

#base_url ⇒ String (readonly)

Returns the base URL of the FHIR service.

Returns:

  • (String) —

    the base URL of the FHIR service



66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
 
# File 'lib/safire/client_config.rb', line 66

class ClientConfig < Entity
  include URIValidation

  ATTRIBUTES = %i[
    base_url issuer client_id client_secret redirect_uri
    scopes authorization_endpoint token_endpoint
    private_key certificate_chain kid jwt_algorithm jwks_uri
  ].freeze

  CertificateSnapshot = Data.define(:der)
  private_constant :CertificateSnapshot

  attr_reader(*(ATTRIBUTES - [:certificate_chain]))

  def certificate_chain
    return if @certificate_chain.nil?

    @certificate_chain.map { |entry| materialize_certificate_entry(entry) }.freeze
  end

  def initialize(config)
    super(config, ATTRIBUTES)

    @certificate_chain = normalize_certificate_chain(@certificate_chain)
    @issuer ||= base_url
    validate!
  end

  class << self
    def builder
      ClientConfigBuilder.new
    end
  end

  CERTIFICATE_CHAIN_ENTRY_TYPES = [String, OpenSSL::X509::Certificate].freeze
  SENSITIVE_ATTRIBUTES = %i[client_secret private_key certificate_chain].freeze
  URI_ATTRS = %i[base_url redirect_uri issuer authorization_endpoint token_endpoint jwks_uri].freeze
  OPTIONAL_URI_ATTRS = %i[redirect_uri authorization_endpoint token_endpoint jwks_uri].freeze
  private_constant :CERTIFICATE_CHAIN_ENTRY_TYPES, :SENSITIVE_ATTRIBUTES, :URI_ATTRS, :OPTIONAL_URI_ATTRS

  # @api private
  def inspect
    attrs = ATTRIBUTES.map do |attr|
      # Read stored values directly so masked compound types are not materialized before being discarded.
      value = instance_variable_get(:"@#{attr}")
      next if value.nil?

      masked = SENSITIVE_ATTRIBUTES.include?(attr) ? '[FILTERED]' : value.inspect
      "#{attr}: #{masked}"
    end.compact.join(', ')
    "#<#{self.class} #{attrs}>"
  end

  protected

  # @return [Array<Symbol>] attributes masked as '[FILTERED]' in #to_hash
  def sensitive_attributes
    SENSITIVE_ATTRIBUTES
  end

  private

  def normalize_certificate_chain(chain)
    return if chain.nil?

    validate_certificate_chain_type!(chain)
    chain.map { |entry| snapshot_certificate_entry(entry) }.freeze
  end

  def validate_certificate_chain_type!(chain)
    raise_invalid_certificate_chain!(chain.class, [Array]) unless chain.is_a?(Array)
    raise_invalid_certificate_chain!(chain.class, ['non-empty Array']) if chain.empty?

    chain.each do |entry|
      next if CERTIFICATE_CHAIN_ENTRY_TYPES.any? { |type| entry.is_a?(type) }

      raise_invalid_certificate_chain!(entry.class, CERTIFICATE_CHAIN_ENTRY_TYPES)
    end
  end

  def snapshot_certificate_entry(entry)
    return entry.dup.freeze if entry.is_a?(String)

    CertificateSnapshot.new(der: entry.to_der.freeze)
  rescue OpenSSL::X509::CertificateError
    raise_invalid_certificate_chain!(entry.class, ['serializable OpenSSL::X509::Certificate'])
  end

  def materialize_certificate_entry(entry)
    return entry unless entry.is_a?(CertificateSnapshot)

    OpenSSL::X509::Certificate.new(entry.der)
  end

  def raise_invalid_certificate_chain!(invalid_value, valid_values)
    raise Errors::ConfigurationError.new(
      invalid_attribute: :certificate_chain,
      invalid_value:,
      valid_values:
    )
  end

  # Validates all URI attributes for structure and HTTPS requirement.
  #
  # Per SMART App Launch 2.2.0 (§App Protection, §Confidential Asymmetric),
  # all exchanges involving sensitive data SHALL use TLS. All endpoint URIs
  # must therefore use the `https` scheme.
  #
  # Exception: `http` is permitted when the host is `localhost` or `127.0.0.1`
  # to support local development without a TLS termination proxy.
  #
  # @raise [Errors::ConfigurationError] if any URI is malformed or uses HTTP on a non-localhost host
  def validate_uris!
    invalid_uris, non_https_uris = collect_uri_violations
    return if invalid_uris.empty? && non_https_uris.empty?

    raise Errors::ConfigurationError.new(
      invalid_uri_attributes: invalid_uris,
      non_https_uri_attributes: non_https_uris
    )
  end

  def collect_uri_violations
    invalid_uris = []
    non_https_uris = []

    URI_ATTRS.each do |attr|
      value = send(attr)
      next if value.nil? && OPTIONAL_URI_ATTRS.include?(attr)

      case classify_uri(value)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def validate!
    raise Errors::ConfigurationError.new(missing_attributes: [:base_url]) if base_url.nil?

    validate_uris!
  end
end

#certificate_chain ⇒ Array<String, OpenSSL::X509::Certificate>? (readonly)

Returns leaf-first X.509 certificate chain for planned UDAP software-statement signing. Entries may be PEM strings or certificate objects. Certificate objects are stored as DER snapshots and returned as fresh copies. Parsing PEM strings and identity validation occur when the software statement is built.

Returns:

  • (Array<String, OpenSSL::X509::Certificate>, nil) —

    leaf-first X.509 certificate chain for planned UDAP software-statement signing. Entries may be PEM strings or certificate objects. Certificate objects are stored as DER snapshots and returned as fresh copies. Parsing PEM strings and identity validation occur when the software statement is built.



66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
 
# File 'lib/safire/client_config.rb', line 66

class ClientConfig < Entity
  include URIValidation

  ATTRIBUTES = %i[
    base_url issuer client_id client_secret redirect_uri
    scopes authorization_endpoint token_endpoint
    private_key certificate_chain kid jwt_algorithm jwks_uri
  ].freeze

  CertificateSnapshot = Data.define(:der)
  private_constant :CertificateSnapshot

  attr_reader(*(ATTRIBUTES - [:certificate_chain]))

  def certificate_chain
    return if @certificate_chain.nil?

    @certificate_chain.map { |entry| materialize_certificate_entry(entry) }.freeze
  end

  def initialize(config)
    super(config, ATTRIBUTES)

    @certificate_chain = normalize_certificate_chain(@certificate_chain)
    @issuer ||= base_url
    validate!
  end

  class << self
    def builder
      ClientConfigBuilder.new
    end
  end

  CERTIFICATE_CHAIN_ENTRY_TYPES = [String, OpenSSL::X509::Certificate].freeze
  SENSITIVE_ATTRIBUTES = %i[client_secret private_key certificate_chain].freeze
  URI_ATTRS = %i[base_url redirect_uri issuer authorization_endpoint token_endpoint jwks_uri].freeze
  OPTIONAL_URI_ATTRS = %i[redirect_uri authorization_endpoint token_endpoint jwks_uri].freeze
  private_constant :CERTIFICATE_CHAIN_ENTRY_TYPES, :SENSITIVE_ATTRIBUTES, :URI_ATTRS, :OPTIONAL_URI_ATTRS

  # @api private
  def inspect
    attrs = ATTRIBUTES.map do |attr|
      # Read stored values directly so masked compound types are not materialized before being discarded.
      value = instance_variable_get(:"@#{attr}")
      next if value.nil?

      masked = SENSITIVE_ATTRIBUTES.include?(attr) ? '[FILTERED]' : value.inspect
      "#{attr}: #{masked}"
    end.compact.join(', ')
    "#<#{self.class} #{attrs}>"
  end

  protected

  # @return [Array<Symbol>] attributes masked as '[FILTERED]' in #to_hash
  def sensitive_attributes
    SENSITIVE_ATTRIBUTES
  end

  private

  def normalize_certificate_chain(chain)
    return if chain.nil?

    validate_certificate_chain_type!(chain)
    chain.map { |entry| snapshot_certificate_entry(entry) }.freeze
  end

  def validate_certificate_chain_type!(chain)
    raise_invalid_certificate_chain!(chain.class, [Array]) unless chain.is_a?(Array)
    raise_invalid_certificate_chain!(chain.class, ['non-empty Array']) if chain.empty?

    chain.each do |entry|
      next if CERTIFICATE_CHAIN_ENTRY_TYPES.any? { |type| entry.is_a?(type) }

      raise_invalid_certificate_chain!(entry.class, CERTIFICATE_CHAIN_ENTRY_TYPES)
    end
  end

  def snapshot_certificate_entry(entry)
    return entry.dup.freeze if entry.is_a?(String)

    CertificateSnapshot.new(der: entry.to_der.freeze)
  rescue OpenSSL::X509::CertificateError
    raise_invalid_certificate_chain!(entry.class, ['serializable OpenSSL::X509::Certificate'])
  end

  def materialize_certificate_entry(entry)
    return entry unless entry.is_a?(CertificateSnapshot)

    OpenSSL::X509::Certificate.new(entry.der)
  end

  def raise_invalid_certificate_chain!(invalid_value, valid_values)
    raise Errors::ConfigurationError.new(
      invalid_attribute: :certificate_chain,
      invalid_value:,
      valid_values:
    )
  end

  # Validates all URI attributes for structure and HTTPS requirement.
  #
  # Per SMART App Launch 2.2.0 (§App Protection, §Confidential Asymmetric),
  # all exchanges involving sensitive data SHALL use TLS. All endpoint URIs
  # must therefore use the `https` scheme.
  #
  # Exception: `http` is permitted when the host is `localhost` or `127.0.0.1`
  # to support local development without a TLS termination proxy.
  #
  # @raise [Errors::ConfigurationError] if any URI is malformed or uses HTTP on a non-localhost host
  def validate_uris!
    invalid_uris, non_https_uris = collect_uri_violations
    return if invalid_uris.empty? && non_https_uris.empty?

    raise Errors::ConfigurationError.new(
      invalid_uri_attributes: invalid_uris,
      non_https_uri_attributes: non_https_uris
    )
  end

  def collect_uri_violations
    invalid_uris = []
    non_https_uris = []

    URI_ATTRS.each do |attr|
      value = send(attr)
      next if value.nil? && OPTIONAL_URI_ATTRS.include?(attr)

      case classify_uri(value)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def validate!
    raise Errors::ConfigurationError.new(missing_attributes: [:base_url]) if base_url.nil?

    validate_uris!
  end
end

#client_id ⇒ String? (readonly)

Returns the client identifier issued to the app by the authorization server. Optional at initialization — required by all authorization flows. Omit only when performing Dynamic Client Registration (RFC 7591) to obtain a client_id before any flow begins.

Returns:

  • (String, nil) —

    the client identifier issued to the app by the authorization server. Optional at initialization — required by all authorization flows. Omit only when performing Dynamic Client Registration (RFC 7591) to obtain a client_id before any flow begins.



66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
 
# File 'lib/safire/client_config.rb', line 66

class ClientConfig < Entity
  include URIValidation

  ATTRIBUTES = %i[
    base_url issuer client_id client_secret redirect_uri
    scopes authorization_endpoint token_endpoint
    private_key certificate_chain kid jwt_algorithm jwks_uri
  ].freeze

  CertificateSnapshot = Data.define(:der)
  private_constant :CertificateSnapshot

  attr_reader(*(ATTRIBUTES - [:certificate_chain]))

  def certificate_chain
    return if @certificate_chain.nil?

    @certificate_chain.map { |entry| materialize_certificate_entry(entry) }.freeze
  end

  def initialize(config)
    super(config, ATTRIBUTES)

    @certificate_chain = normalize_certificate_chain(@certificate_chain)
    @issuer ||= base_url
    validate!
  end

  class << self
    def builder
      ClientConfigBuilder.new
    end
  end

  CERTIFICATE_CHAIN_ENTRY_TYPES = [String, OpenSSL::X509::Certificate].freeze
  SENSITIVE_ATTRIBUTES = %i[client_secret private_key certificate_chain].freeze
  URI_ATTRS = %i[base_url redirect_uri issuer authorization_endpoint token_endpoint jwks_uri].freeze
  OPTIONAL_URI_ATTRS = %i[redirect_uri authorization_endpoint token_endpoint jwks_uri].freeze
  private_constant :CERTIFICATE_CHAIN_ENTRY_TYPES, :SENSITIVE_ATTRIBUTES, :URI_ATTRS, :OPTIONAL_URI_ATTRS

  # @api private
  def inspect
    attrs = ATTRIBUTES.map do |attr|
      # Read stored values directly so masked compound types are not materialized before being discarded.
      value = instance_variable_get(:"@#{attr}")
      next if value.nil?

      masked = SENSITIVE_ATTRIBUTES.include?(attr) ? '[FILTERED]' : value.inspect
      "#{attr}: #{masked}"
    end.compact.join(', ')
    "#<#{self.class} #{attrs}>"
  end

  protected

  # @return [Array<Symbol>] attributes masked as '[FILTERED]' in #to_hash
  def sensitive_attributes
    SENSITIVE_ATTRIBUTES
  end

  private

  def normalize_certificate_chain(chain)
    return if chain.nil?

    validate_certificate_chain_type!(chain)
    chain.map { |entry| snapshot_certificate_entry(entry) }.freeze
  end

  def validate_certificate_chain_type!(chain)
    raise_invalid_certificate_chain!(chain.class, [Array]) unless chain.is_a?(Array)
    raise_invalid_certificate_chain!(chain.class, ['non-empty Array']) if chain.empty?

    chain.each do |entry|
      next if CERTIFICATE_CHAIN_ENTRY_TYPES.any? { |type| entry.is_a?(type) }

      raise_invalid_certificate_chain!(entry.class, CERTIFICATE_CHAIN_ENTRY_TYPES)
    end
  end

  def snapshot_certificate_entry(entry)
    return entry.dup.freeze if entry.is_a?(String)

    CertificateSnapshot.new(der: entry.to_der.freeze)
  rescue OpenSSL::X509::CertificateError
    raise_invalid_certificate_chain!(entry.class, ['serializable OpenSSL::X509::Certificate'])
  end

  def materialize_certificate_entry(entry)
    return entry unless entry.is_a?(CertificateSnapshot)

    OpenSSL::X509::Certificate.new(entry.der)
  end

  def raise_invalid_certificate_chain!(invalid_value, valid_values)
    raise Errors::ConfigurationError.new(
      invalid_attribute: :certificate_chain,
      invalid_value:,
      valid_values:
    )
  end

  # Validates all URI attributes for structure and HTTPS requirement.
  #
  # Per SMART App Launch 2.2.0 (§App Protection, §Confidential Asymmetric),
  # all exchanges involving sensitive data SHALL use TLS. All endpoint URIs
  # must therefore use the `https` scheme.
  #
  # Exception: `http` is permitted when the host is `localhost` or `127.0.0.1`
  # to support local development without a TLS termination proxy.
  #
  # @raise [Errors::ConfigurationError] if any URI is malformed or uses HTTP on a non-localhost host
  def validate_uris!
    invalid_uris, non_https_uris = collect_uri_violations
    return if invalid_uris.empty? && non_https_uris.empty?

    raise Errors::ConfigurationError.new(
      invalid_uri_attributes: invalid_uris,
      non_https_uri_attributes: non_https_uris
    )
  end

  def collect_uri_violations
    invalid_uris = []
    non_https_uris = []

    URI_ATTRS.each do |attr|
      value = send(attr)
      next if value.nil? && OPTIONAL_URI_ATTRS.include?(attr)

      case classify_uri(value)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def validate!
    raise Errors::ConfigurationError.new(missing_attributes: [:base_url]) if base_url.nil?

    validate_uris!
  end
end

#issuer ⇒ String (readonly)

Returns the URL of the FHIR service from which the app wishes to retrieve FHIR data. Optionally provided. Will default to base_url if not provided.

Returns:

  • (String) —

    the URL of the FHIR service from which the app wishes to retrieve FHIR data. Optionally provided. Will default to base_url if not provided.



66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
 
# File 'lib/safire/client_config.rb', line 66

class ClientConfig < Entity
  include URIValidation

  ATTRIBUTES = %i[
    base_url issuer client_id client_secret redirect_uri
    scopes authorization_endpoint token_endpoint
    private_key certificate_chain kid jwt_algorithm jwks_uri
  ].freeze

  CertificateSnapshot = Data.define(:der)
  private_constant :CertificateSnapshot

  attr_reader(*(ATTRIBUTES - [:certificate_chain]))

  def certificate_chain
    return if @certificate_chain.nil?

    @certificate_chain.map { |entry| materialize_certificate_entry(entry) }.freeze
  end

  def initialize(config)
    super(config, ATTRIBUTES)

    @certificate_chain = normalize_certificate_chain(@certificate_chain)
    @issuer ||= base_url
    validate!
  end

  class << self
    def builder
      ClientConfigBuilder.new
    end
  end

  CERTIFICATE_CHAIN_ENTRY_TYPES = [String, OpenSSL::X509::Certificate].freeze
  SENSITIVE_ATTRIBUTES = %i[client_secret private_key certificate_chain].freeze
  URI_ATTRS = %i[base_url redirect_uri issuer authorization_endpoint token_endpoint jwks_uri].freeze
  OPTIONAL_URI_ATTRS = %i[redirect_uri authorization_endpoint token_endpoint jwks_uri].freeze
  private_constant :CERTIFICATE_CHAIN_ENTRY_TYPES, :SENSITIVE_ATTRIBUTES, :URI_ATTRS, :OPTIONAL_URI_ATTRS

  # @api private
  def inspect
    attrs = ATTRIBUTES.map do |attr|
      # Read stored values directly so masked compound types are not materialized before being discarded.
      value = instance_variable_get(:"@#{attr}")
      next if value.nil?

      masked = SENSITIVE_ATTRIBUTES.include?(attr) ? '[FILTERED]' : value.inspect
      "#{attr}: #{masked}"
    end.compact.join(', ')
    "#<#{self.class} #{attrs}>"
  end

  protected

  # @return [Array<Symbol>] attributes masked as '[FILTERED]' in #to_hash
  def sensitive_attributes
    SENSITIVE_ATTRIBUTES
  end

  private

  def normalize_certificate_chain(chain)
    return if chain.nil?

    validate_certificate_chain_type!(chain)
    chain.map { |entry| snapshot_certificate_entry(entry) }.freeze
  end

  def validate_certificate_chain_type!(chain)
    raise_invalid_certificate_chain!(chain.class, [Array]) unless chain.is_a?(Array)
    raise_invalid_certificate_chain!(chain.class, ['non-empty Array']) if chain.empty?

    chain.each do |entry|
      next if CERTIFICATE_CHAIN_ENTRY_TYPES.any? { |type| entry.is_a?(type) }

      raise_invalid_certificate_chain!(entry.class, CERTIFICATE_CHAIN_ENTRY_TYPES)
    end
  end

  def snapshot_certificate_entry(entry)
    return entry.dup.freeze if entry.is_a?(String)

    CertificateSnapshot.new(der: entry.to_der.freeze)
  rescue OpenSSL::X509::CertificateError
    raise_invalid_certificate_chain!(entry.class, ['serializable OpenSSL::X509::Certificate'])
  end

  def materialize_certificate_entry(entry)
    return entry unless entry.is_a?(CertificateSnapshot)

    OpenSSL::X509::Certificate.new(entry.der)
  end

  def raise_invalid_certificate_chain!(invalid_value, valid_values)
    raise Errors::ConfigurationError.new(
      invalid_attribute: :certificate_chain,
      invalid_value:,
      valid_values:
    )
  end

  # Validates all URI attributes for structure and HTTPS requirement.
  #
  # Per SMART App Launch 2.2.0 (§App Protection, §Confidential Asymmetric),
  # all exchanges involving sensitive data SHALL use TLS. All endpoint URIs
  # must therefore use the `https` scheme.
  #
  # Exception: `http` is permitted when the host is `localhost` or `127.0.0.1`
  # to support local development without a TLS termination proxy.
  #
  # @raise [Errors::ConfigurationError] if any URI is malformed or uses HTTP on a non-localhost host
  def validate_uris!
    invalid_uris, non_https_uris = collect_uri_violations
    return if invalid_uris.empty? && non_https_uris.empty?

    raise Errors::ConfigurationError.new(
      invalid_uri_attributes: invalid_uris,
      non_https_uri_attributes: non_https_uris
    )
  end

  def collect_uri_violations
    invalid_uris = []
    non_https_uris = []

    URI_ATTRS.each do |attr|
      value = send(attr)
      next if value.nil? && OPTIONAL_URI_ATTRS.include?(attr)

      case classify_uri(value)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def validate!
    raise Errors::ConfigurationError.new(missing_attributes: [:base_url]) if base_url.nil?

    validate_uris!
  end
end

#jwks_uri ⇒ String? (readonly)

Returns URL to the client's JWKS containing the public key. Optional, included as jku header in JWT assertions when provided.

Returns:

  • (String, nil) —

    URL to the client's JWKS containing the public key. Optional, included as jku header in JWT assertions when provided.



66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
 
# File 'lib/safire/client_config.rb', line 66

class ClientConfig < Entity
  include URIValidation

  ATTRIBUTES = %i[
    base_url issuer client_id client_secret redirect_uri
    scopes authorization_endpoint token_endpoint
    private_key certificate_chain kid jwt_algorithm jwks_uri
  ].freeze

  CertificateSnapshot = Data.define(:der)
  private_constant :CertificateSnapshot

  attr_reader(*(ATTRIBUTES - [:certificate_chain]))

  def certificate_chain
    return if @certificate_chain.nil?

    @certificate_chain.map { |entry| materialize_certificate_entry(entry) }.freeze
  end

  def initialize(config)
    super(config, ATTRIBUTES)

    @certificate_chain = normalize_certificate_chain(@certificate_chain)
    @issuer ||= base_url
    validate!
  end

  class << self
    def builder
      ClientConfigBuilder.new
    end
  end

  CERTIFICATE_CHAIN_ENTRY_TYPES = [String, OpenSSL::X509::Certificate].freeze
  SENSITIVE_ATTRIBUTES = %i[client_secret private_key certificate_chain].freeze
  URI_ATTRS = %i[base_url redirect_uri issuer authorization_endpoint token_endpoint jwks_uri].freeze
  OPTIONAL_URI_ATTRS = %i[redirect_uri authorization_endpoint token_endpoint jwks_uri].freeze
  private_constant :CERTIFICATE_CHAIN_ENTRY_TYPES, :SENSITIVE_ATTRIBUTES, :URI_ATTRS, :OPTIONAL_URI_ATTRS

  # @api private
  def inspect
    attrs = ATTRIBUTES.map do |attr|
      # Read stored values directly so masked compound types are not materialized before being discarded.
      value = instance_variable_get(:"@#{attr}")
      next if value.nil?

      masked = SENSITIVE_ATTRIBUTES.include?(attr) ? '[FILTERED]' : value.inspect
      "#{attr}: #{masked}"
    end.compact.join(', ')
    "#<#{self.class} #{attrs}>"
  end

  protected

  # @return [Array<Symbol>] attributes masked as '[FILTERED]' in #to_hash
  def sensitive_attributes
    SENSITIVE_ATTRIBUTES
  end

  private

  def normalize_certificate_chain(chain)
    return if chain.nil?

    validate_certificate_chain_type!(chain)
    chain.map { |entry| snapshot_certificate_entry(entry) }.freeze
  end

  def validate_certificate_chain_type!(chain)
    raise_invalid_certificate_chain!(chain.class, [Array]) unless chain.is_a?(Array)
    raise_invalid_certificate_chain!(chain.class, ['non-empty Array']) if chain.empty?

    chain.each do |entry|
      next if CERTIFICATE_CHAIN_ENTRY_TYPES.any? { |type| entry.is_a?(type) }

      raise_invalid_certificate_chain!(entry.class, CERTIFICATE_CHAIN_ENTRY_TYPES)
    end
  end

  def snapshot_certificate_entry(entry)
    return entry.dup.freeze if entry.is_a?(String)

    CertificateSnapshot.new(der: entry.to_der.freeze)
  rescue OpenSSL::X509::CertificateError
    raise_invalid_certificate_chain!(entry.class, ['serializable OpenSSL::X509::Certificate'])
  end

  def materialize_certificate_entry(entry)
    return entry unless entry.is_a?(CertificateSnapshot)

    OpenSSL::X509::Certificate.new(entry.der)
  end

  def raise_invalid_certificate_chain!(invalid_value, valid_values)
    raise Errors::ConfigurationError.new(
      invalid_attribute: :certificate_chain,
      invalid_value:,
      valid_values:
    )
  end

  # Validates all URI attributes for structure and HTTPS requirement.
  #
  # Per SMART App Launch 2.2.0 (§App Protection, §Confidential Asymmetric),
  # all exchanges involving sensitive data SHALL use TLS. All endpoint URIs
  # must therefore use the `https` scheme.
  #
  # Exception: `http` is permitted when the host is `localhost` or `127.0.0.1`
  # to support local development without a TLS termination proxy.
  #
  # @raise [Errors::ConfigurationError] if any URI is malformed or uses HTTP on a non-localhost host
  def validate_uris!
    invalid_uris, non_https_uris = collect_uri_violations
    return if invalid_uris.empty? && non_https_uris.empty?

    raise Errors::ConfigurationError.new(
      invalid_uri_attributes: invalid_uris,
      non_https_uri_attributes: non_https_uris
    )
  end

  def collect_uri_violations
    invalid_uris = []
    non_https_uris = []

    URI_ATTRS.each do |attr|
      value = send(attr)
      next if value.nil? && OPTIONAL_URI_ATTRS.include?(attr)

      case classify_uri(value)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def validate!
    raise Errors::ConfigurationError.new(missing_attributes: [:base_url]) if base_url.nil?

    validate_uris!
  end
end

#jwt_algorithm ⇒ String? (readonly)

Returns the JWT signing algorithm. SMART supports RS384 or ES384; planned UDAP registration supports RS256, RS384, ES256, or ES384 subject to key compatibility and server discovery. Optional; selected from the key and protocol requirements when omitted.

Returns:

  • (String, nil) —

    the JWT signing algorithm. SMART supports RS384 or ES384; planned UDAP registration supports RS256, RS384, ES256, or ES384 subject to key compatibility and server discovery. Optional; selected from the key and protocol requirements when omitted.



66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
 
# File 'lib/safire/client_config.rb', line 66

class ClientConfig < Entity
  include URIValidation

  ATTRIBUTES = %i[
    base_url issuer client_id client_secret redirect_uri
    scopes authorization_endpoint token_endpoint
    private_key certificate_chain kid jwt_algorithm jwks_uri
  ].freeze

  CertificateSnapshot = Data.define(:der)
  private_constant :CertificateSnapshot

  attr_reader(*(ATTRIBUTES - [:certificate_chain]))

  def certificate_chain
    return if @certificate_chain.nil?

    @certificate_chain.map { |entry| materialize_certificate_entry(entry) }.freeze
  end

  def initialize(config)
    super(config, ATTRIBUTES)

    @certificate_chain = normalize_certificate_chain(@certificate_chain)
    @issuer ||= base_url
    validate!
  end

  class << self
    def builder
      ClientConfigBuilder.new
    end
  end

  CERTIFICATE_CHAIN_ENTRY_TYPES = [String, OpenSSL::X509::Certificate].freeze
  SENSITIVE_ATTRIBUTES = %i[client_secret private_key certificate_chain].freeze
  URI_ATTRS = %i[base_url redirect_uri issuer authorization_endpoint token_endpoint jwks_uri].freeze
  OPTIONAL_URI_ATTRS = %i[redirect_uri authorization_endpoint token_endpoint jwks_uri].freeze
  private_constant :CERTIFICATE_CHAIN_ENTRY_TYPES, :SENSITIVE_ATTRIBUTES, :URI_ATTRS, :OPTIONAL_URI_ATTRS

  # @api private
  def inspect
    attrs = ATTRIBUTES.map do |attr|
      # Read stored values directly so masked compound types are not materialized before being discarded.
      value = instance_variable_get(:"@#{attr}")
      next if value.nil?

      masked = SENSITIVE_ATTRIBUTES.include?(attr) ? '[FILTERED]' : value.inspect
      "#{attr}: #{masked}"
    end.compact.join(', ')
    "#<#{self.class} #{attrs}>"
  end

  protected

  # @return [Array<Symbol>] attributes masked as '[FILTERED]' in #to_hash
  def sensitive_attributes
    SENSITIVE_ATTRIBUTES
  end

  private

  def normalize_certificate_chain(chain)
    return if chain.nil?

    validate_certificate_chain_type!(chain)
    chain.map { |entry| snapshot_certificate_entry(entry) }.freeze
  end

  def validate_certificate_chain_type!(chain)
    raise_invalid_certificate_chain!(chain.class, [Array]) unless chain.is_a?(Array)
    raise_invalid_certificate_chain!(chain.class, ['non-empty Array']) if chain.empty?

    chain.each do |entry|
      next if CERTIFICATE_CHAIN_ENTRY_TYPES.any? { |type| entry.is_a?(type) }

      raise_invalid_certificate_chain!(entry.class, CERTIFICATE_CHAIN_ENTRY_TYPES)
    end
  end

  def snapshot_certificate_entry(entry)
    return entry.dup.freeze if entry.is_a?(String)

    CertificateSnapshot.new(der: entry.to_der.freeze)
  rescue OpenSSL::X509::CertificateError
    raise_invalid_certificate_chain!(entry.class, ['serializable OpenSSL::X509::Certificate'])
  end

  def materialize_certificate_entry(entry)
    return entry unless entry.is_a?(CertificateSnapshot)

    OpenSSL::X509::Certificate.new(entry.der)
  end

  def raise_invalid_certificate_chain!(invalid_value, valid_values)
    raise Errors::ConfigurationError.new(
      invalid_attribute: :certificate_chain,
      invalid_value:,
      valid_values:
    )
  end

  # Validates all URI attributes for structure and HTTPS requirement.
  #
  # Per SMART App Launch 2.2.0 (§App Protection, §Confidential Asymmetric),
  # all exchanges involving sensitive data SHALL use TLS. All endpoint URIs
  # must therefore use the `https` scheme.
  #
  # Exception: `http` is permitted when the host is `localhost` or `127.0.0.1`
  # to support local development without a TLS termination proxy.
  #
  # @raise [Errors::ConfigurationError] if any URI is malformed or uses HTTP on a non-localhost host
  def validate_uris!
    invalid_uris, non_https_uris = collect_uri_violations
    return if invalid_uris.empty? && non_https_uris.empty?

    raise Errors::ConfigurationError.new(
      invalid_uri_attributes: invalid_uris,
      non_https_uri_attributes: non_https_uris
    )
  end

  def collect_uri_violations
    invalid_uris = []
    non_https_uris = []

    URI_ATTRS.each do |attr|
      value = send(attr)
      next if value.nil? && OPTIONAL_URI_ATTRS.include?(attr)

      case classify_uri(value)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def validate!
    raise Errors::ConfigurationError.new(missing_attributes: [:base_url]) if base_url.nil?

    validate_uris!
  end
end

#kid ⇒ String? (readonly)

Returns the key ID matching the public key registered with the authorization server. Required for confidential asymmetric authentication.

Returns:

  • (String, nil) —

    the key ID matching the public key registered with the authorization server. Required for confidential asymmetric authentication.



66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
 
# File 'lib/safire/client_config.rb', line 66

class ClientConfig < Entity
  include URIValidation

  ATTRIBUTES = %i[
    base_url issuer client_id client_secret redirect_uri
    scopes authorization_endpoint token_endpoint
    private_key certificate_chain kid jwt_algorithm jwks_uri
  ].freeze

  CertificateSnapshot = Data.define(:der)
  private_constant :CertificateSnapshot

  attr_reader(*(ATTRIBUTES - [:certificate_chain]))

  def certificate_chain
    return if @certificate_chain.nil?

    @certificate_chain.map { |entry| materialize_certificate_entry(entry) }.freeze
  end

  def initialize(config)
    super(config, ATTRIBUTES)

    @certificate_chain = normalize_certificate_chain(@certificate_chain)
    @issuer ||= base_url
    validate!
  end

  class << self
    def builder
      ClientConfigBuilder.new
    end
  end

  CERTIFICATE_CHAIN_ENTRY_TYPES = [String, OpenSSL::X509::Certificate].freeze
  SENSITIVE_ATTRIBUTES = %i[client_secret private_key certificate_chain].freeze
  URI_ATTRS = %i[base_url redirect_uri issuer authorization_endpoint token_endpoint jwks_uri].freeze
  OPTIONAL_URI_ATTRS = %i[redirect_uri authorization_endpoint token_endpoint jwks_uri].freeze
  private_constant :CERTIFICATE_CHAIN_ENTRY_TYPES, :SENSITIVE_ATTRIBUTES, :URI_ATTRS, :OPTIONAL_URI_ATTRS

  # @api private
  def inspect
    attrs = ATTRIBUTES.map do |attr|
      # Read stored values directly so masked compound types are not materialized before being discarded.
      value = instance_variable_get(:"@#{attr}")
      next if value.nil?

      masked = SENSITIVE_ATTRIBUTES.include?(attr) ? '[FILTERED]' : value.inspect
      "#{attr}: #{masked}"
    end.compact.join(', ')
    "#<#{self.class} #{attrs}>"
  end

  protected

  # @return [Array<Symbol>] attributes masked as '[FILTERED]' in #to_hash
  def sensitive_attributes
    SENSITIVE_ATTRIBUTES
  end

  private

  def normalize_certificate_chain(chain)
    return if chain.nil?

    validate_certificate_chain_type!(chain)
    chain.map { |entry| snapshot_certificate_entry(entry) }.freeze
  end

  def validate_certificate_chain_type!(chain)
    raise_invalid_certificate_chain!(chain.class, [Array]) unless chain.is_a?(Array)
    raise_invalid_certificate_chain!(chain.class, ['non-empty Array']) if chain.empty?

    chain.each do |entry|
      next if CERTIFICATE_CHAIN_ENTRY_TYPES.any? { |type| entry.is_a?(type) }

      raise_invalid_certificate_chain!(entry.class, CERTIFICATE_CHAIN_ENTRY_TYPES)
    end
  end

  def snapshot_certificate_entry(entry)
    return entry.dup.freeze if entry.is_a?(String)

    CertificateSnapshot.new(der: entry.to_der.freeze)
  rescue OpenSSL::X509::CertificateError
    raise_invalid_certificate_chain!(entry.class, ['serializable OpenSSL::X509::Certificate'])
  end

  def materialize_certificate_entry(entry)
    return entry unless entry.is_a?(CertificateSnapshot)

    OpenSSL::X509::Certificate.new(entry.der)
  end

  def raise_invalid_certificate_chain!(invalid_value, valid_values)
    raise Errors::ConfigurationError.new(
      invalid_attribute: :certificate_chain,
      invalid_value:,
      valid_values:
    )
  end

  # Validates all URI attributes for structure and HTTPS requirement.
  #
  # Per SMART App Launch 2.2.0 (§App Protection, §Confidential Asymmetric),
  # all exchanges involving sensitive data SHALL use TLS. All endpoint URIs
  # must therefore use the `https` scheme.
  #
  # Exception: `http` is permitted when the host is `localhost` or `127.0.0.1`
  # to support local development without a TLS termination proxy.
  #
  # @raise [Errors::ConfigurationError] if any URI is malformed or uses HTTP on a non-localhost host
  def validate_uris!
    invalid_uris, non_https_uris = collect_uri_violations
    return if invalid_uris.empty? && non_https_uris.empty?

    raise Errors::ConfigurationError.new(
      invalid_uri_attributes: invalid_uris,
      non_https_uri_attributes: non_https_uris
    )
  end

  def collect_uri_violations
    invalid_uris = []
    non_https_uris = []

    URI_ATTRS.each do |attr|
      value = send(attr)
      next if value.nil? && OPTIONAL_URI_ATTRS.include?(attr)

      case classify_uri(value)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def validate!
    raise Errors::ConfigurationError.new(missing_attributes: [:base_url]) if base_url.nil?

    validate_uris!
  end
end

#private_key ⇒ OpenSSL::PKey::RSA, ... (readonly)

Returns the private key for signing SMART JWT assertions or planned UDAP software statements. Can be an OpenSSL key object or PEM string.

Returns:

  • (OpenSSL::PKey::RSA, OpenSSL::PKey::EC, String, nil) —

    the private key for signing SMART JWT assertions or planned UDAP software statements. Can be an OpenSSL key object or PEM string.



66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
 
# File 'lib/safire/client_config.rb', line 66

class ClientConfig < Entity
  include URIValidation

  ATTRIBUTES = %i[
    base_url issuer client_id client_secret redirect_uri
    scopes authorization_endpoint token_endpoint
    private_key certificate_chain kid jwt_algorithm jwks_uri
  ].freeze

  CertificateSnapshot = Data.define(:der)
  private_constant :CertificateSnapshot

  attr_reader(*(ATTRIBUTES - [:certificate_chain]))

  def certificate_chain
    return if @certificate_chain.nil?

    @certificate_chain.map { |entry| materialize_certificate_entry(entry) }.freeze
  end

  def initialize(config)
    super(config, ATTRIBUTES)

    @certificate_chain = normalize_certificate_chain(@certificate_chain)
    @issuer ||= base_url
    validate!
  end

  class << self
    def builder
      ClientConfigBuilder.new
    end
  end

  CERTIFICATE_CHAIN_ENTRY_TYPES = [String, OpenSSL::X509::Certificate].freeze
  SENSITIVE_ATTRIBUTES = %i[client_secret private_key certificate_chain].freeze
  URI_ATTRS = %i[base_url redirect_uri issuer authorization_endpoint token_endpoint jwks_uri].freeze
  OPTIONAL_URI_ATTRS = %i[redirect_uri authorization_endpoint token_endpoint jwks_uri].freeze
  private_constant :CERTIFICATE_CHAIN_ENTRY_TYPES, :SENSITIVE_ATTRIBUTES, :URI_ATTRS, :OPTIONAL_URI_ATTRS

  # @api private
  def inspect
    attrs = ATTRIBUTES.map do |attr|
      # Read stored values directly so masked compound types are not materialized before being discarded.
      value = instance_variable_get(:"@#{attr}")
      next if value.nil?

      masked = SENSITIVE_ATTRIBUTES.include?(attr) ? '[FILTERED]' : value.inspect
      "#{attr}: #{masked}"
    end.compact.join(', ')
    "#<#{self.class} #{attrs}>"
  end

  protected

  # @return [Array<Symbol>] attributes masked as '[FILTERED]' in #to_hash
  def sensitive_attributes
    SENSITIVE_ATTRIBUTES
  end

  private

  def normalize_certificate_chain(chain)
    return if chain.nil?

    validate_certificate_chain_type!(chain)
    chain.map { |entry| snapshot_certificate_entry(entry) }.freeze
  end

  def validate_certificate_chain_type!(chain)
    raise_invalid_certificate_chain!(chain.class, [Array]) unless chain.is_a?(Array)
    raise_invalid_certificate_chain!(chain.class, ['non-empty Array']) if chain.empty?

    chain.each do |entry|
      next if CERTIFICATE_CHAIN_ENTRY_TYPES.any? { |type| entry.is_a?(type) }

      raise_invalid_certificate_chain!(entry.class, CERTIFICATE_CHAIN_ENTRY_TYPES)
    end
  end

  def snapshot_certificate_entry(entry)
    return entry.dup.freeze if entry.is_a?(String)

    CertificateSnapshot.new(der: entry.to_der.freeze)
  rescue OpenSSL::X509::CertificateError
    raise_invalid_certificate_chain!(entry.class, ['serializable OpenSSL::X509::Certificate'])
  end

  def materialize_certificate_entry(entry)
    return entry unless entry.is_a?(CertificateSnapshot)

    OpenSSL::X509::Certificate.new(entry.der)
  end

  def raise_invalid_certificate_chain!(invalid_value, valid_values)
    raise Errors::ConfigurationError.new(
      invalid_attribute: :certificate_chain,
      invalid_value:,
      valid_values:
    )
  end

  # Validates all URI attributes for structure and HTTPS requirement.
  #
  # Per SMART App Launch 2.2.0 (§App Protection, §Confidential Asymmetric),
  # all exchanges involving sensitive data SHALL use TLS. All endpoint URIs
  # must therefore use the `https` scheme.
  #
  # Exception: `http` is permitted when the host is `localhost` or `127.0.0.1`
  # to support local development without a TLS termination proxy.
  #
  # @raise [Errors::ConfigurationError] if any URI is malformed or uses HTTP on a non-localhost host
  def validate_uris!
    invalid_uris, non_https_uris = collect_uri_violations
    return if invalid_uris.empty? && non_https_uris.empty?

    raise Errors::ConfigurationError.new(
      invalid_uri_attributes: invalid_uris,
      non_https_uri_attributes: non_https_uris
    )
  end

  def collect_uri_violations
    invalid_uris = []
    non_https_uris = []

    URI_ATTRS.each do |attr|
      value = send(attr)
      next if value.nil? && OPTIONAL_URI_ATTRS.include?(attr)

      case classify_uri(value)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def validate!
    raise Errors::ConfigurationError.new(missing_attributes: [:base_url]) if base_url.nil?

    validate_uris!
  end
end

#redirect_uri ⇒ String (readonly)

Returns the redirect URI registered by the app with the authorization server.

Returns:

  • (String) —

    the redirect URI registered by the app with the authorization server



66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
 
# File 'lib/safire/client_config.rb', line 66

class ClientConfig < Entity
  include URIValidation

  ATTRIBUTES = %i[
    base_url issuer client_id client_secret redirect_uri
    scopes authorization_endpoint token_endpoint
    private_key certificate_chain kid jwt_algorithm jwks_uri
  ].freeze

  CertificateSnapshot = Data.define(:der)
  private_constant :CertificateSnapshot

  attr_reader(*(ATTRIBUTES - [:certificate_chain]))

  def certificate_chain
    return if @certificate_chain.nil?

    @certificate_chain.map { |entry| materialize_certificate_entry(entry) }.freeze
  end

  def initialize(config)
    super(config, ATTRIBUTES)

    @certificate_chain = normalize_certificate_chain(@certificate_chain)
    @issuer ||= base_url
    validate!
  end

  class << self
    def builder
      ClientConfigBuilder.new
    end
  end

  CERTIFICATE_CHAIN_ENTRY_TYPES = [String, OpenSSL::X509::Certificate].freeze
  SENSITIVE_ATTRIBUTES = %i[client_secret private_key certificate_chain].freeze
  URI_ATTRS = %i[base_url redirect_uri issuer authorization_endpoint token_endpoint jwks_uri].freeze
  OPTIONAL_URI_ATTRS = %i[redirect_uri authorization_endpoint token_endpoint jwks_uri].freeze
  private_constant :CERTIFICATE_CHAIN_ENTRY_TYPES, :SENSITIVE_ATTRIBUTES, :URI_ATTRS, :OPTIONAL_URI_ATTRS

  # @api private
  def inspect
    attrs = ATTRIBUTES.map do |attr|
      # Read stored values directly so masked compound types are not materialized before being discarded.
      value = instance_variable_get(:"@#{attr}")
      next if value.nil?

      masked = SENSITIVE_ATTRIBUTES.include?(attr) ? '[FILTERED]' : value.inspect
      "#{attr}: #{masked}"
    end.compact.join(', ')
    "#<#{self.class} #{attrs}>"
  end

  protected

  # @return [Array<Symbol>] attributes masked as '[FILTERED]' in #to_hash
  def sensitive_attributes
    SENSITIVE_ATTRIBUTES
  end

  private

  def normalize_certificate_chain(chain)
    return if chain.nil?

    validate_certificate_chain_type!(chain)
    chain.map { |entry| snapshot_certificate_entry(entry) }.freeze
  end

  def validate_certificate_chain_type!(chain)
    raise_invalid_certificate_chain!(chain.class, [Array]) unless chain.is_a?(Array)
    raise_invalid_certificate_chain!(chain.class, ['non-empty Array']) if chain.empty?

    chain.each do |entry|
      next if CERTIFICATE_CHAIN_ENTRY_TYPES.any? { |type| entry.is_a?(type) }

      raise_invalid_certificate_chain!(entry.class, CERTIFICATE_CHAIN_ENTRY_TYPES)
    end
  end

  def snapshot_certificate_entry(entry)
    return entry.dup.freeze if entry.is_a?(String)

    CertificateSnapshot.new(der: entry.to_der.freeze)
  rescue OpenSSL::X509::CertificateError
    raise_invalid_certificate_chain!(entry.class, ['serializable OpenSSL::X509::Certificate'])
  end

  def materialize_certificate_entry(entry)
    return entry unless entry.is_a?(CertificateSnapshot)

    OpenSSL::X509::Certificate.new(entry.der)
  end

  def raise_invalid_certificate_chain!(invalid_value, valid_values)
    raise Errors::ConfigurationError.new(
      invalid_attribute: :certificate_chain,
      invalid_value:,
      valid_values:
    )
  end

  # Validates all URI attributes for structure and HTTPS requirement.
  #
  # Per SMART App Launch 2.2.0 (§App Protection, §Confidential Asymmetric),
  # all exchanges involving sensitive data SHALL use TLS. All endpoint URIs
  # must therefore use the `https` scheme.
  #
  # Exception: `http` is permitted when the host is `localhost` or `127.0.0.1`
  # to support local development without a TLS termination proxy.
  #
  # @raise [Errors::ConfigurationError] if any URI is malformed or uses HTTP on a non-localhost host
  def validate_uris!
    invalid_uris, non_https_uris = collect_uri_violations
    return if invalid_uris.empty? && non_https_uris.empty?

    raise Errors::ConfigurationError.new(
      invalid_uri_attributes: invalid_uris,
      non_https_uri_attributes: non_https_uris
    )
  end

  def collect_uri_violations
    invalid_uris = []
    non_https_uris = []

    URI_ATTRS.each do |attr|
      value = send(attr)
      next if value.nil? && OPTIONAL_URI_ATTRS.include?(attr)

      case classify_uri(value)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def validate!
    raise Errors::ConfigurationError.new(missing_attributes: [:base_url]) if base_url.nil?

    validate_uris!
  end
end

#scopes ⇒ Array<String> (readonly)

Returns list of OAuth2 scopes describing the app's desired access. Optionally provided.

Returns:

  • (Array<String>) —

    list of OAuth2 scopes describing the app's desired access. Optionally provided.



66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
 
# File 'lib/safire/client_config.rb', line 66

class ClientConfig < Entity
  include URIValidation

  ATTRIBUTES = %i[
    base_url issuer client_id client_secret redirect_uri
    scopes authorization_endpoint token_endpoint
    private_key certificate_chain kid jwt_algorithm jwks_uri
  ].freeze

  CertificateSnapshot = Data.define(:der)
  private_constant :CertificateSnapshot

  attr_reader(*(ATTRIBUTES - [:certificate_chain]))

  def certificate_chain
    return if @certificate_chain.nil?

    @certificate_chain.map { |entry| materialize_certificate_entry(entry) }.freeze
  end

  def initialize(config)
    super(config, ATTRIBUTES)

    @certificate_chain = normalize_certificate_chain(@certificate_chain)
    @issuer ||= base_url
    validate!
  end

  class << self
    def builder
      ClientConfigBuilder.new
    end
  end

  CERTIFICATE_CHAIN_ENTRY_TYPES = [String, OpenSSL::X509::Certificate].freeze
  SENSITIVE_ATTRIBUTES = %i[client_secret private_key certificate_chain].freeze
  URI_ATTRS = %i[base_url redirect_uri issuer authorization_endpoint token_endpoint jwks_uri].freeze
  OPTIONAL_URI_ATTRS = %i[redirect_uri authorization_endpoint token_endpoint jwks_uri].freeze
  private_constant :CERTIFICATE_CHAIN_ENTRY_TYPES, :SENSITIVE_ATTRIBUTES, :URI_ATTRS, :OPTIONAL_URI_ATTRS

  # @api private
  def inspect
    attrs = ATTRIBUTES.map do |attr|
      # Read stored values directly so masked compound types are not materialized before being discarded.
      value = instance_variable_get(:"@#{attr}")
      next if value.nil?

      masked = SENSITIVE_ATTRIBUTES.include?(attr) ? '[FILTERED]' : value.inspect
      "#{attr}: #{masked}"
    end.compact.join(', ')
    "#<#{self.class} #{attrs}>"
  end

  protected

  # @return [Array<Symbol>] attributes masked as '[FILTERED]' in #to_hash
  def sensitive_attributes
    SENSITIVE_ATTRIBUTES
  end

  private

  def normalize_certificate_chain(chain)
    return if chain.nil?

    validate_certificate_chain_type!(chain)
    chain.map { |entry| snapshot_certificate_entry(entry) }.freeze
  end

  def validate_certificate_chain_type!(chain)
    raise_invalid_certificate_chain!(chain.class, [Array]) unless chain.is_a?(Array)
    raise_invalid_certificate_chain!(chain.class, ['non-empty Array']) if chain.empty?

    chain.each do |entry|
      next if CERTIFICATE_CHAIN_ENTRY_TYPES.any? { |type| entry.is_a?(type) }

      raise_invalid_certificate_chain!(entry.class, CERTIFICATE_CHAIN_ENTRY_TYPES)
    end
  end

  def snapshot_certificate_entry(entry)
    return entry.dup.freeze if entry.is_a?(String)

    CertificateSnapshot.new(der: entry.to_der.freeze)
  rescue OpenSSL::X509::CertificateError
    raise_invalid_certificate_chain!(entry.class, ['serializable OpenSSL::X509::Certificate'])
  end

  def materialize_certificate_entry(entry)
    return entry unless entry.is_a?(CertificateSnapshot)

    OpenSSL::X509::Certificate.new(entry.der)
  end

  def raise_invalid_certificate_chain!(invalid_value, valid_values)
    raise Errors::ConfigurationError.new(
      invalid_attribute: :certificate_chain,
      invalid_value:,
      valid_values:
    )
  end

  # Validates all URI attributes for structure and HTTPS requirement.
  #
  # Per SMART App Launch 2.2.0 (§App Protection, §Confidential Asymmetric),
  # all exchanges involving sensitive data SHALL use TLS. All endpoint URIs
  # must therefore use the `https` scheme.
  #
  # Exception: `http` is permitted when the host is `localhost` or `127.0.0.1`
  # to support local development without a TLS termination proxy.
  #
  # @raise [Errors::ConfigurationError] if any URI is malformed or uses HTTP on a non-localhost host
  def validate_uris!
    invalid_uris, non_https_uris = collect_uri_violations
    return if invalid_uris.empty? && non_https_uris.empty?

    raise Errors::ConfigurationError.new(
      invalid_uri_attributes: invalid_uris,
      non_https_uri_attributes: non_https_uris
    )
  end

  def collect_uri_violations
    invalid_uris = []
    non_https_uris = []

    URI_ATTRS.each do |attr|
      value = send(attr)
      next if value.nil? && OPTIONAL_URI_ATTRS.include?(attr)

      case classify_uri(value)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def validate!
    raise Errors::ConfigurationError.new(missing_attributes: [:base_url]) if base_url.nil?

    validate_uris!
  end
end

#token_endpoint ⇒ String (readonly)

=> Optional, will be retrieved from the well-known smart-configuration if not provided

Returns:

  • (String) —

    URL of the server's OAuth2 Token Endpoint.



66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
 
# File 'lib/safire/client_config.rb', line 66

class ClientConfig < Entity
  include URIValidation

  ATTRIBUTES = %i[
    base_url issuer client_id client_secret redirect_uri
    scopes authorization_endpoint token_endpoint
    private_key certificate_chain kid jwt_algorithm jwks_uri
  ].freeze

  CertificateSnapshot = Data.define(:der)
  private_constant :CertificateSnapshot

  attr_reader(*(ATTRIBUTES - [:certificate_chain]))

  def certificate_chain
    return if @certificate_chain.nil?

    @certificate_chain.map { |entry| materialize_certificate_entry(entry) }.freeze
  end

  def initialize(config)
    super(config, ATTRIBUTES)

    @certificate_chain = normalize_certificate_chain(@certificate_chain)
    @issuer ||= base_url
    validate!
  end

  class << self
    def builder
      ClientConfigBuilder.new
    end
  end

  CERTIFICATE_CHAIN_ENTRY_TYPES = [String, OpenSSL::X509::Certificate].freeze
  SENSITIVE_ATTRIBUTES = %i[client_secret private_key certificate_chain].freeze
  URI_ATTRS = %i[base_url redirect_uri issuer authorization_endpoint token_endpoint jwks_uri].freeze
  OPTIONAL_URI_ATTRS = %i[redirect_uri authorization_endpoint token_endpoint jwks_uri].freeze
  private_constant :CERTIFICATE_CHAIN_ENTRY_TYPES, :SENSITIVE_ATTRIBUTES, :URI_ATTRS, :OPTIONAL_URI_ATTRS

  # @api private
  def inspect
    attrs = ATTRIBUTES.map do |attr|
      # Read stored values directly so masked compound types are not materialized before being discarded.
      value = instance_variable_get(:"@#{attr}")
      next if value.nil?

      masked = SENSITIVE_ATTRIBUTES.include?(attr) ? '[FILTERED]' : value.inspect
      "#{attr}: #{masked}"
    end.compact.join(', ')
    "#<#{self.class} #{attrs}>"
  end

  protected

  # @return [Array<Symbol>] attributes masked as '[FILTERED]' in #to_hash
  def sensitive_attributes
    SENSITIVE_ATTRIBUTES
  end

  private

  def normalize_certificate_chain(chain)
    return if chain.nil?

    validate_certificate_chain_type!(chain)
    chain.map { |entry| snapshot_certificate_entry(entry) }.freeze
  end

  def validate_certificate_chain_type!(chain)
    raise_invalid_certificate_chain!(chain.class, [Array]) unless chain.is_a?(Array)
    raise_invalid_certificate_chain!(chain.class, ['non-empty Array']) if chain.empty?

    chain.each do |entry|
      next if CERTIFICATE_CHAIN_ENTRY_TYPES.any? { |type| entry.is_a?(type) }

      raise_invalid_certificate_chain!(entry.class, CERTIFICATE_CHAIN_ENTRY_TYPES)
    end
  end

  def snapshot_certificate_entry(entry)
    return entry.dup.freeze if entry.is_a?(String)

    CertificateSnapshot.new(der: entry.to_der.freeze)
  rescue OpenSSL::X509::CertificateError
    raise_invalid_certificate_chain!(entry.class, ['serializable OpenSSL::X509::Certificate'])
  end

  def materialize_certificate_entry(entry)
    return entry unless entry.is_a?(CertificateSnapshot)

    OpenSSL::X509::Certificate.new(entry.der)
  end

  def raise_invalid_certificate_chain!(invalid_value, valid_values)
    raise Errors::ConfigurationError.new(
      invalid_attribute: :certificate_chain,
      invalid_value:,
      valid_values:
    )
  end

  # Validates all URI attributes for structure and HTTPS requirement.
  #
  # Per SMART App Launch 2.2.0 (§App Protection, §Confidential Asymmetric),
  # all exchanges involving sensitive data SHALL use TLS. All endpoint URIs
  # must therefore use the `https` scheme.
  #
  # Exception: `http` is permitted when the host is `localhost` or `127.0.0.1`
  # to support local development without a TLS termination proxy.
  #
  # @raise [Errors::ConfigurationError] if any URI is malformed or uses HTTP on a non-localhost host
  def validate_uris!
    invalid_uris, non_https_uris = collect_uri_violations
    return if invalid_uris.empty? && non_https_uris.empty?

    raise Errors::ConfigurationError.new(
      invalid_uri_attributes: invalid_uris,
      non_https_uri_attributes: non_https_uris
    )
  end

  def collect_uri_violations
    invalid_uris = []
    non_https_uris = []

    URI_ATTRS.each do |attr|
      value = send(attr)
      next if value.nil? && OPTIONAL_URI_ATTRS.include?(attr)

      case classify_uri(value)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def validate!
    raise Errors::ConfigurationError.new(missing_attributes: [:base_url]) if base_url.nil?

    validate_uris!
  end
end

Class Method Details

.builder ⇒ Object 



95
96
97
 
# File 'lib/safire/client_config.rb', line 95

def builder
  ClientConfigBuilder.new
end

Instance Method Details

#inspect ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/safire/client_config.rb', line 107

def inspect
  attrs = ATTRIBUTES.map do |attr|
    # Read stored values directly so masked compound types are not materialized before being discarded.
    value = instance_variable_get(:"@#{attr}")
    next if value.nil?

    masked = SENSITIVE_ATTRIBUTES.include?(attr) ? '[FILTERED]' : value.inspect
    "#{attr}: #{masked}"
  end.compact.join(', ')
  "#<#{self.class} #{attrs}>"
end