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
  allow_insecure_localhost
].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.



91
92
93
94
95
96
97
98
 
# File 'lib/safire/client_config.rb', line 91

def initialize(config)
  super(config, ATTRIBUTES)

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

Instance Attribute Details

#allow_insecure_localhost ⇒ Boolean (readonly)

Returns whether HTTP loopback URIs are accepted for local development. Defaults to false. Set to true only in development when a local FHIR server cannot terminate TLS.

Returns:

  • (Boolean) —

    whether HTTP loopback URIs are accepted for local development. Defaults to false. Set to true only in development when a local FHIR server cannot terminate TLS.



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
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
 
# File 'lib/safire/client_config.rb', line 70

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
    allow_insecure_localhost
  ].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)

    @allow_insecure_localhost = normalize_localhost_policy(config)
    @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

  def normalize_localhost_policy(config)
    value = if config.key?(:allow_insecure_localhost)
              config[:allow_insecure_localhost]
            elsif config.key?('allow_insecure_localhost')
              config['allow_insecure_localhost']
            else
              false
            end

    validate_localhost_policy(value)
  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 `allow_insecure_localhost` is true
  # and 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
    if invalid_uris.empty? && non_https_uris.empty?
      warn_if_insecure_localhost_used
      return
    end

    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, allow_insecure_localhost:)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def warn_if_insecure_localhost_used
    return unless allow_insecure_localhost

    local_http_attrs = URI_ATTRS.select do |attr|
      value = send(attr)
      value && localhost_http_uri?(value)
    end
    return if local_http_attrs.empty?

    Safire.logger.warn(
      '[Safire] allow_insecure_localhost permits development-only HTTP loopback URIs; ' \
      'SMART App Launch and UDAP require HTTPS in production'
    )
  end

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

    validate_uris!
  end
end

#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.



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
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
 
# File 'lib/safire/client_config.rb', line 70

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
    allow_insecure_localhost
  ].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)

    @allow_insecure_localhost = normalize_localhost_policy(config)
    @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

  def normalize_localhost_policy(config)
    value = if config.key?(:allow_insecure_localhost)
              config[:allow_insecure_localhost]
            elsif config.key?('allow_insecure_localhost')
              config['allow_insecure_localhost']
            else
              false
            end

    validate_localhost_policy(value)
  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 `allow_insecure_localhost` is true
  # and 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
    if invalid_uris.empty? && non_https_uris.empty?
      warn_if_insecure_localhost_used
      return
    end

    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, allow_insecure_localhost:)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def warn_if_insecure_localhost_used
    return unless allow_insecure_localhost

    local_http_attrs = URI_ATTRS.select do |attr|
      value = send(attr)
      value && localhost_http_uri?(value)
    end
    return if local_http_attrs.empty?

    Safire.logger.warn(
      '[Safire] allow_insecure_localhost permits development-only HTTP loopback URIs; ' \
      'SMART App Launch and UDAP require HTTPS in production'
    )
  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



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
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
 
# File 'lib/safire/client_config.rb', line 70

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
    allow_insecure_localhost
  ].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)

    @allow_insecure_localhost = normalize_localhost_policy(config)
    @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

  def normalize_localhost_policy(config)
    value = if config.key?(:allow_insecure_localhost)
              config[:allow_insecure_localhost]
            elsif config.key?('allow_insecure_localhost')
              config['allow_insecure_localhost']
            else
              false
            end

    validate_localhost_policy(value)
  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 `allow_insecure_localhost` is true
  # and 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
    if invalid_uris.empty? && non_https_uris.empty?
      warn_if_insecure_localhost_used
      return
    end

    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, allow_insecure_localhost:)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def warn_if_insecure_localhost_used
    return unless allow_insecure_localhost

    local_http_attrs = URI_ATTRS.select do |attr|
      value = send(attr)
      value && localhost_http_uri?(value)
    end
    return if local_http_attrs.empty?

    Safire.logger.warn(
      '[Safire] allow_insecure_localhost permits development-only HTTP loopback URIs; ' \
      'SMART App Launch and UDAP require HTTPS in production'
    )
  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, issuer-ordered X.509 certificate chain for 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, issuer-ordered X.509 certificate chain for 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.



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
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
 
# File 'lib/safire/client_config.rb', line 70

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
    allow_insecure_localhost
  ].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)

    @allow_insecure_localhost = normalize_localhost_policy(config)
    @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

  def normalize_localhost_policy(config)
    value = if config.key?(:allow_insecure_localhost)
              config[:allow_insecure_localhost]
            elsif config.key?('allow_insecure_localhost')
              config['allow_insecure_localhost']
            else
              false
            end

    validate_localhost_policy(value)
  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 `allow_insecure_localhost` is true
  # and 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
    if invalid_uris.empty? && non_https_uris.empty?
      warn_if_insecure_localhost_used
      return
    end

    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, allow_insecure_localhost:)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def warn_if_insecure_localhost_used
    return unless allow_insecure_localhost

    local_http_attrs = URI_ATTRS.select do |attr|
      value = send(attr)
      value && localhost_http_uri?(value)
    end
    return if local_http_attrs.empty?

    Safire.logger.warn(
      '[Safire] allow_insecure_localhost permits development-only HTTP loopback URIs; ' \
      'SMART App Launch and UDAP require HTTPS in production'
    )
  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.



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
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
 
# File 'lib/safire/client_config.rb', line 70

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
    allow_insecure_localhost
  ].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)

    @allow_insecure_localhost = normalize_localhost_policy(config)
    @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

  def normalize_localhost_policy(config)
    value = if config.key?(:allow_insecure_localhost)
              config[:allow_insecure_localhost]
            elsif config.key?('allow_insecure_localhost')
              config['allow_insecure_localhost']
            else
              false
            end

    validate_localhost_policy(value)
  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 `allow_insecure_localhost` is true
  # and 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
    if invalid_uris.empty? && non_https_uris.empty?
      warn_if_insecure_localhost_used
      return
    end

    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, allow_insecure_localhost:)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def warn_if_insecure_localhost_used
    return unless allow_insecure_localhost

    local_http_attrs = URI_ATTRS.select do |attr|
      value = send(attr)
      value && localhost_http_uri?(value)
    end
    return if local_http_attrs.empty?

    Safire.logger.warn(
      '[Safire] allow_insecure_localhost permits development-only HTTP loopback URIs; ' \
      'SMART App Launch and UDAP require HTTPS in production'
    )
  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.



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
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
 
# File 'lib/safire/client_config.rb', line 70

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
    allow_insecure_localhost
  ].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)

    @allow_insecure_localhost = normalize_localhost_policy(config)
    @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

  def normalize_localhost_policy(config)
    value = if config.key?(:allow_insecure_localhost)
              config[:allow_insecure_localhost]
            elsif config.key?('allow_insecure_localhost')
              config['allow_insecure_localhost']
            else
              false
            end

    validate_localhost_policy(value)
  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 `allow_insecure_localhost` is true
  # and 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
    if invalid_uris.empty? && non_https_uris.empty?
      warn_if_insecure_localhost_used
      return
    end

    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, allow_insecure_localhost:)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def warn_if_insecure_localhost_used
    return unless allow_insecure_localhost

    local_http_attrs = URI_ATTRS.select do |attr|
      value = send(attr)
      value && localhost_http_uri?(value)
    end
    return if local_http_attrs.empty?

    Safire.logger.warn(
      '[Safire] allow_insecure_localhost permits development-only HTTP loopback URIs; ' \
      'SMART App Launch and UDAP require HTTPS in production'
    )
  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.



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
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
 
# File 'lib/safire/client_config.rb', line 70

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
    allow_insecure_localhost
  ].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)

    @allow_insecure_localhost = normalize_localhost_policy(config)
    @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

  def normalize_localhost_policy(config)
    value = if config.key?(:allow_insecure_localhost)
              config[:allow_insecure_localhost]
            elsif config.key?('allow_insecure_localhost')
              config['allow_insecure_localhost']
            else
              false
            end

    validate_localhost_policy(value)
  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 `allow_insecure_localhost` is true
  # and 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
    if invalid_uris.empty? && non_https_uris.empty?
      warn_if_insecure_localhost_used
      return
    end

    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, allow_insecure_localhost:)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def warn_if_insecure_localhost_used
    return unless allow_insecure_localhost

    local_http_attrs = URI_ATTRS.select do |attr|
      value = send(attr)
      value && localhost_http_uri?(value)
    end
    return if local_http_attrs.empty?

    Safire.logger.warn(
      '[Safire] allow_insecure_localhost permits development-only HTTP loopback URIs; ' \
      'SMART App Launch and UDAP require HTTPS in production'
    )
  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; UDAP software-statement signing 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; UDAP software-statement signing supports RS256, RS384, ES256, or ES384 subject to key compatibility and server discovery. Optional; selected from the key and protocol requirements when omitted.



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
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
 
# File 'lib/safire/client_config.rb', line 70

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
    allow_insecure_localhost
  ].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)

    @allow_insecure_localhost = normalize_localhost_policy(config)
    @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

  def normalize_localhost_policy(config)
    value = if config.key?(:allow_insecure_localhost)
              config[:allow_insecure_localhost]
            elsif config.key?('allow_insecure_localhost')
              config['allow_insecure_localhost']
            else
              false
            end

    validate_localhost_policy(value)
  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 `allow_insecure_localhost` is true
  # and 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
    if invalid_uris.empty? && non_https_uris.empty?
      warn_if_insecure_localhost_used
      return
    end

    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, allow_insecure_localhost:)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def warn_if_insecure_localhost_used
    return unless allow_insecure_localhost

    local_http_attrs = URI_ATTRS.select do |attr|
      value = send(attr)
      value && localhost_http_uri?(value)
    end
    return if local_http_attrs.empty?

    Safire.logger.warn(
      '[Safire] allow_insecure_localhost permits development-only HTTP loopback URIs; ' \
      'SMART App Launch and UDAP require HTTPS in production'
    )
  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.



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
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
 
# File 'lib/safire/client_config.rb', line 70

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
    allow_insecure_localhost
  ].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)

    @allow_insecure_localhost = normalize_localhost_policy(config)
    @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

  def normalize_localhost_policy(config)
    value = if config.key?(:allow_insecure_localhost)
              config[:allow_insecure_localhost]
            elsif config.key?('allow_insecure_localhost')
              config['allow_insecure_localhost']
            else
              false
            end

    validate_localhost_policy(value)
  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 `allow_insecure_localhost` is true
  # and 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
    if invalid_uris.empty? && non_https_uris.empty?
      warn_if_insecure_localhost_used
      return
    end

    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, allow_insecure_localhost:)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def warn_if_insecure_localhost_used
    return unless allow_insecure_localhost

    local_http_attrs = URI_ATTRS.select do |attr|
      value = send(attr)
      value && localhost_http_uri?(value)
    end
    return if local_http_attrs.empty?

    Safire.logger.warn(
      '[Safire] allow_insecure_localhost permits development-only HTTP loopback URIs; ' \
      'SMART App Launch and UDAP require HTTPS in production'
    )
  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 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 UDAP software statements. Can be an OpenSSL key object or PEM string.



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
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
 
# File 'lib/safire/client_config.rb', line 70

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
    allow_insecure_localhost
  ].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)

    @allow_insecure_localhost = normalize_localhost_policy(config)
    @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

  def normalize_localhost_policy(config)
    value = if config.key?(:allow_insecure_localhost)
              config[:allow_insecure_localhost]
            elsif config.key?('allow_insecure_localhost')
              config['allow_insecure_localhost']
            else
              false
            end

    validate_localhost_policy(value)
  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 `allow_insecure_localhost` is true
  # and 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
    if invalid_uris.empty? && non_https_uris.empty?
      warn_if_insecure_localhost_used
      return
    end

    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, allow_insecure_localhost:)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def warn_if_insecure_localhost_used
    return unless allow_insecure_localhost

    local_http_attrs = URI_ATTRS.select do |attr|
      value = send(attr)
      value && localhost_http_uri?(value)
    end
    return if local_http_attrs.empty?

    Safire.logger.warn(
      '[Safire] allow_insecure_localhost permits development-only HTTP loopback URIs; ' \
      'SMART App Launch and UDAP require HTTPS in production'
    )
  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



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
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
 
# File 'lib/safire/client_config.rb', line 70

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
    allow_insecure_localhost
  ].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)

    @allow_insecure_localhost = normalize_localhost_policy(config)
    @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

  def normalize_localhost_policy(config)
    value = if config.key?(:allow_insecure_localhost)
              config[:allow_insecure_localhost]
            elsif config.key?('allow_insecure_localhost')
              config['allow_insecure_localhost']
            else
              false
            end

    validate_localhost_policy(value)
  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 `allow_insecure_localhost` is true
  # and 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
    if invalid_uris.empty? && non_https_uris.empty?
      warn_if_insecure_localhost_used
      return
    end

    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, allow_insecure_localhost:)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def warn_if_insecure_localhost_used
    return unless allow_insecure_localhost

    local_http_attrs = URI_ATTRS.select do |attr|
      value = send(attr)
      value && localhost_http_uri?(value)
    end
    return if local_http_attrs.empty?

    Safire.logger.warn(
      '[Safire] allow_insecure_localhost permits development-only HTTP loopback URIs; ' \
      'SMART App Launch and UDAP require HTTPS in production'
    )
  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.



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
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
 
# File 'lib/safire/client_config.rb', line 70

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
    allow_insecure_localhost
  ].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)

    @allow_insecure_localhost = normalize_localhost_policy(config)
    @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

  def normalize_localhost_policy(config)
    value = if config.key?(:allow_insecure_localhost)
              config[:allow_insecure_localhost]
            elsif config.key?('allow_insecure_localhost')
              config['allow_insecure_localhost']
            else
              false
            end

    validate_localhost_policy(value)
  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 `allow_insecure_localhost` is true
  # and 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
    if invalid_uris.empty? && non_https_uris.empty?
      warn_if_insecure_localhost_used
      return
    end

    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, allow_insecure_localhost:)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def warn_if_insecure_localhost_used
    return unless allow_insecure_localhost

    local_http_attrs = URI_ATTRS.select do |attr|
      value = send(attr)
      value && localhost_http_uri?(value)
    end
    return if local_http_attrs.empty?

    Safire.logger.warn(
      '[Safire] allow_insecure_localhost permits development-only HTTP loopback URIs; ' \
      'SMART App Launch and UDAP require HTTPS in production'
    )
  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.



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
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
 
# File 'lib/safire/client_config.rb', line 70

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
    allow_insecure_localhost
  ].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)

    @allow_insecure_localhost = normalize_localhost_policy(config)
    @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

  def normalize_localhost_policy(config)
    value = if config.key?(:allow_insecure_localhost)
              config[:allow_insecure_localhost]
            elsif config.key?('allow_insecure_localhost')
              config['allow_insecure_localhost']
            else
              false
            end

    validate_localhost_policy(value)
  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 `allow_insecure_localhost` is true
  # and 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
    if invalid_uris.empty? && non_https_uris.empty?
      warn_if_insecure_localhost_used
      return
    end

    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, allow_insecure_localhost:)
      when :invalid   then invalid_uris << attr
      when :non_https then non_https_uris << attr
      end
    end

    [invalid_uris, non_https_uris]
  end

  def warn_if_insecure_localhost_used
    return unless allow_insecure_localhost

    local_http_attrs = URI_ATTRS.select do |attr|
      value = send(attr)
      value && localhost_http_uri?(value)
    end
    return if local_http_attrs.empty?

    Safire.logger.warn(
      '[Safire] allow_insecure_localhost permits development-only HTTP loopback URIs; ' \
      'SMART App Launch and UDAP require HTTPS in production'
    )
  end

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

    validate_uris!
  end
end

Class Method Details

.builder ⇒ Object 



101
102
103
 
# File 'lib/safire/client_config.rb', line 101

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. 



113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/safire/client_config.rb', line 113

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