Class: Clickwrap::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/clickwrap/configuration.rb

Overview

The single configuration object the host populates in config/initializers/clickwrap.rb via Clickwrap.configure do |config| ... end.

Design rules:

- Runtime adapters and class names are read at the point of use. Policy
semantics — including merged request-evidence defaults — are copied into
the immutable compiled policy revision at boot, so changing this object
cannot mutate a form that was already rendered.
- Class names are stored as strings and constantized lazily, so the
initializer works no matter when the app loads (the User model may not
exist yet at boot).
- Validating setters normalize their input and raise a plain-English
ConfigurationError on a bad value — failing at the assignment line
rather than at 3am with a NoMethodError. `validate!` runs once more at
the end of `configure` for the cross-field checks.
- Every hook defaults to a no-op, so the gem works untouched and a host
wires hooks only as needed.
- Nothing here collects personal data by default. Every `record_*` flag
starts false, and turning one on without a purpose and a retention
decision is a configuration error, not a warning.

One setting deserves its own note: there is deliberately no gdpr_compliant_mode, maximum_evidence, full_evidence, or legal_proof. An option that silently enables a category of personal data is exactly the thing this gem exists not to do, and no runtime flag can make a legal determination on your behalf.

Constant Summary collapse

DOCUMENT_STORES = 
%i[database active_storage resolver].freeze
DIGEST_ALGORITHMS = 
%i[sha256 sha384 sha512].freeze
%i[external_browser same_screen].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Configuration

Returns a new instance of Configuration.



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
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
 
# File 'lib/clickwrap/configuration.rb', line 110

def initialize
  # Identity. "User" is the overwhelmingly common case; the host overrides
  # it if their actor model is "Account", "Member", or something else.
  @actor_class_name = "User"
  @current_actor_method_name = :current_user
  @parent_controller_class_name = "ApplicationController"
  @find_current_tenant_with = ->(_controller) {}

  # How an actor is referenced in evidence. Prefer a host override, then a
  # GlobalID when available, then a stable class/id string in minimal Rails.
  # The resulting string survives row deletion instead of becoming a
  # cascading foreign-key loss.
  @identify_actor_with = ->(actor) { default_actor_reference(actor) }

  # Actor snapshots contain only what the host names. Clickwrap never
  # serializes a whole user into evidence: a receipt should carry the
  # fields someone reviewed and chose, not every column that happened to
  # exist on the day it was written.
  @snapshot_actor_with = ->(_actor) { {} }

  # An honest default: when the controller can name a current actor, the
  # request ran under an application-authenticated session; when it cannot
  # — a signup form, a public capture screen, a controller with no
  # authentication at all — nothing is claimed. The temptation this guards
  # against is describing every request as authenticated merely because it
  # passed through ApplicationController. Deliberately gentler than the
  # capture path's actor resolution: describing authentication is context,
  # not identity, so a missing actor method here means "nothing to
  # describe", never an error.
  configuration = self
  @describe_authentication_with = lambda do |controller|
    method_name = configuration.current_actor_method_name
    actor = controller.respond_to?(method_name, true) ? controller.send(method_name) : nil
    actor ? { method: :authenticated_session } : {}
  end

  # Documents and policies.
  @store_document_contents_in = :database
  @document_renderer = DocumentRenderer.new
  @document_resolver = nil
  @document_link_html_options_with = ->(_document) { { target: "_blank", rel: "noopener" } }
  @hotwire_native_document_links = nil
  @policy_paths = ["config/clickwrap.rb", "config/clickwrap/*.rb"]

  # Publishing rides `db:prepare`, so the deploy step everyone forgets
  # does not exist: by the time the server takes traffic, every declared
  # document version has an immutable snapshot. Idempotent — an
  # already-published version is left untouched — and a publish refusal
  # (a reused label over changed bytes) fails the deploy loudly, which is
  # strictly better than signups failing quietly later.
  @publish_documents_after_database_preparation = true

  # A required legal statement with no translation is not presentable. Fail
  # rather than show a raw I18n key, a blank, or an unexpected language.
  @raise_on_missing_translation = true

  # nil means "decide from the environment": on in development and test,
  # off everywhere else. `true` and `false` answer for a host that
  # disagrees with either half — a linter nobody can turn off is a warning
  # people learn to scroll past.
  @lint_presentations = nil

  # Presentation manifests are short-lived by design: they bind a render to
  # a submit, and a token that stayed valid for days would weaken exactly
  # the substitution check it exists to make.
  @presentation_valid_for = 2.hours
  @remediation_token_valid_for = 2.hours

  # Integrity. The baseline detects accidental or ordinary mutation of the
  # verified bytes. Chains, anchors, and third-party timestamps are separate,
  # explicitly enabled tiers, and each one claims only what it supplies.
  @digest_canonical_receipts_with = :sha256
  @chain_event_history_with = nil
  @anchor_event_history_with = nil
  @timestamp_receipts_with = nil
  @application_version = -> {}
  @template_version = -> {}

  # Authorization. Actors can read their own receipts; anything wider is
  # the host's decision, and unredacted request evidence needs a reason.
  @authorize_receipt_access_with = ->(_controller, _receipt) { false }
  @authorize_unredacted_request_evidence_access_with = ->(_controller, _receipt, _because) { false }
  @verify_actor_can_act_for_represented_party_with = lambda do |actor:, represented_party:, policy:,
                                                                authentication_context:, tenant:|
    AuthorityDecision.new(authorized: false)
  end
  @authorize_clickwrap_remediation_subject_with = lambda do |actor:, subject:, policy:, controller:|
    subject.nil?
  end
  @authorize_clickwrap_remediation_represented_party_with =
    lambda do |actor:, represented_party:, policy:, controller:|
      represented_party.nil?
    end
  @remediation_subject_authorization_configured = false
  @remediation_represented_party_authorization_configured = false
  @represented_party_authority_adapters = {
    "organizations_membership" => Integrations::OrganizationsAuthority.new
  }

  # Request evidence. Every one of these is false, and that is the whole
  # point. Recording an IP address is a decision with consequences; the
  # library will not make it silently on a host's behalf.
  @record_ip_address_by_default = false
  @record_browser_user_agent_by_default = false
  Vocabulary::IP_GEOLOCATION_DATA_FIELDS.each do |field|
    instance_variable_set(:"@record_ip_geolocation_#{field}_by_default", false)
  end

  @reason_for_recording_ip_addresses_by_default = nil
  @reason_for_recording_browser_user_agents_by_default = nil
  @reason_for_recording_ip_geolocation_by_default = nil
  @legal_basis_reference_for_recording_ip_addresses_by_default = nil
  @legal_basis_reference_for_recording_browser_user_agents_by_default = nil
  @legal_basis_reference_for_recording_ip_geolocation_by_default = nil
  @review_default_request_evidence_configuration_on = nil

  @encrypt_recorded_ip_addresses = true
  @encrypt_recorded_browser_user_agents = true
  @encrypt_recorded_ip_geolocation = true

  # nil means "every policy that enables the field must supply its own
  # rule". There is no keep-forever default anywhere in this gem.
  @delete_recorded_ip_addresses_after = nil
  @delete_recorded_browser_user_agents_after = nil
  @delete_recorded_ip_geolocation_after = nil

  # Rails' request.remote_ip is the conventional reader. The host remains
  # responsible for configuring and testing trusted proxies correctly:
  # https://api.rubyonrails.org/classes/ActionDispatch/RemoteIp.html
  @read_ip_address_from_http_request_with = ->(http_request) { http_request.remote_ip }
  @read_browser_user_agent_from_http_request_with = ->(http_request) { http_request.user_agent }
  @trusted_proxy_configuration_digest = nil

  @ip_geolocation_resolver = nil
  @ip_geolocation_resolvers = {}
  @fail_capture_when_ip_geolocation_is_unavailable = false

  # The keyed annex digest carries a key ID so a host can rotate keys
  # without making old annexes unverifiable. The default derives one key
  # from Rails' key generator and names it by a non-secret fingerprint.
  # Production hosts with explicit key rotation can replace both settings
  # with a credentials-backed keyring.
  @current_request_evidence_binding_key_id = nil
  @find_request_evidence_binding_key_with = lambda do |requested_key_id|
    key = default_request_evidence_binding_key
    expected_id = default_request_evidence_binding_key_id(key)
    key if key && Digest.secure_compare?(requested_key_id.to_s, expected_id.to_s)
  end

  # Hooks. These run only after required evidence and domain state have
  # committed, and a failure here is reported but can never undo the
  # committed action.
  @after_event_is_committed = ->(_event) {}
  @report_after_commit_failure_with = ->(_error, _event) {}

  # Host-registered retention calculations, keyed by the name a retention
  # class refers to.
  @retention_time_calculators = {}
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(name, *arguments, **options) ⇒ Object 



1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
 
# File 'lib/clickwrap/configuration.rb', line 1114

def method_missing(name, *arguments, **options, &)
  if name.to_s.end_with?("=")
    setting = name.to_s.delete_suffix("=")
    raise ConfigurationError,
          "Clickwrap has no initializer setting named `config.#{setting}`. Check the " \
          "spelling; unknown settings are refused so a typo can never look configured."
  end

  super
end

Instance Attribute Details

#actor_class_name ⇒ Object

The readers are grouped by section on purpose, and kept that way even though rubocop would happily collapse them into one line. The initializer this class backs is the main thing a host reads about Clickwrap, and the shape of these groups is the shape of that file.

--- Identity -------------------------------------------------------------



42
43
44
 
# File 'lib/clickwrap/configuration.rb', line 42

def actor_class_name
  @actor_class_name
end

#after_event_is_committed ⇒ Object

--- Hooks ----------------------------------------------------------------



108
109
110
 
# File 'lib/clickwrap/configuration.rb', line 108

def after_event_is_committed
  @after_event_is_committed
end

#anchor_event_history_with ⇒ Object

Returns the value of attribute anchor_event_history_with.



64
65
66
 
# File 'lib/clickwrap/configuration.rb', line 64

def anchor_event_history_with
  @anchor_event_history_with
end

#application_version ⇒ Object

Returns the value of attribute application_version.



65
66
67
 
# File 'lib/clickwrap/configuration.rb', line 65

def application_version
  @application_version
end

#authorize_clickwrap_remediation_represented_party_with ⇒ Object

Returns the value of attribute authorize_clickwrap_remediation_represented_party_with.



71
72
73
 
# File 'lib/clickwrap/configuration.rb', line 71

def authorize_clickwrap_remediation_represented_party_with
  @authorize_clickwrap_remediation_represented_party_with
end

#authorize_clickwrap_remediation_subject_with ⇒ Object

Returns the value of attribute authorize_clickwrap_remediation_subject_with.



70
71
72
 
# File 'lib/clickwrap/configuration.rb', line 70

def authorize_clickwrap_remediation_subject_with
  @authorize_clickwrap_remediation_subject_with
end

#authorize_receipt_access_with ⇒ Object

--- Authorization --------------------------------------------------------



68
69
70
 
# File 'lib/clickwrap/configuration.rb', line 68

def authorize_receipt_access_with
  @authorize_receipt_access_with
end

#authorize_unredacted_request_evidence_access_with ⇒ Object

--- Authorization --------------------------------------------------------



68
69
70
 
# File 'lib/clickwrap/configuration.rb', line 68

def authorize_unredacted_request_evidence_access_with
  @authorize_unredacted_request_evidence_access_with
end

#chain_event_history_with ⇒ Object

--- Integrity ------------------------------------------------------------



63
64
65
 
# File 'lib/clickwrap/configuration.rb', line 63

def chain_event_history_with
  @chain_event_history_with
end

#current_actor_method_name ⇒ Object

The readers are grouped by section on purpose, and kept that way even though rubocop would happily collapse them into one line. The initializer this class backs is the main thing a host reads about Clickwrap, and the shape of these groups is the shape of that file.

--- Identity -------------------------------------------------------------



42
43
44
 
# File 'lib/clickwrap/configuration.rb', line 42

def current_actor_method_name
  @current_actor_method_name
end

#delete_recorded_browser_user_agents_after ⇒ Object

Returns the value of attribute delete_recorded_browser_user_agents_after.



100
101
102
 
# File 'lib/clickwrap/configuration.rb', line 100

def delete_recorded_browser_user_agents_after
  @delete_recorded_browser_user_agents_after
end

#delete_recorded_ip_addresses_after ⇒ Object

Returns the value of attribute delete_recorded_ip_addresses_after.



100
101
102
 
# File 'lib/clickwrap/configuration.rb', line 100

def delete_recorded_ip_addresses_after
  @delete_recorded_ip_addresses_after
end

#delete_recorded_ip_geolocation_after ⇒ Object

Returns the value of attribute delete_recorded_ip_geolocation_after.



100
101
102
 
# File 'lib/clickwrap/configuration.rb', line 100

def delete_recorded_ip_geolocation_after
  @delete_recorded_ip_geolocation_after
end

#describe_authentication_with ⇒ Object

Returns the value of attribute describe_authentication_with.



44
45
46
 
# File 'lib/clickwrap/configuration.rb', line 44

def describe_authentication_with
  @describe_authentication_with
end

#digest_canonical_receipts_with ⇒ Object

--- Integrity ------------------------------------------------------------



63
64
65
 
# File 'lib/clickwrap/configuration.rb', line 63

def digest_canonical_receipts_with
  @digest_canonical_receipts_with
end

#document_link_html_options_with ⇒ Object

Returns the value of attribute document_link_html_options_with.



48
49
50
 
# File 'lib/clickwrap/configuration.rb', line 48

def document_link_html_options_with
  @document_link_html_options_with
end

#document_renderer ⇒ Object

--- Documents and policies -----------------------------------------------



47
48
49
 
# File 'lib/clickwrap/configuration.rb', line 47

def document_renderer
  @document_renderer
end

#document_resolver ⇒ Object

--- Documents and policies -----------------------------------------------



47
48
49
 
# File 'lib/clickwrap/configuration.rb', line 47

def document_resolver
  @document_resolver
end

#encrypt_recorded_browser_user_agents ⇒ Object

Returns the value of attribute encrypt_recorded_browser_user_agents.



98
99
100
 
# File 'lib/clickwrap/configuration.rb', line 98

def encrypt_recorded_browser_user_agents
  @encrypt_recorded_browser_user_agents
end

#encrypt_recorded_ip_addresses ⇒ Object

Returns the value of attribute encrypt_recorded_ip_addresses.



98
99
100
 
# File 'lib/clickwrap/configuration.rb', line 98

def encrypt_recorded_ip_addresses
  @encrypt_recorded_ip_addresses
end

#encrypt_recorded_ip_geolocation ⇒ Object

Returns the value of attribute encrypt_recorded_ip_geolocation.



98
99
100
 
# File 'lib/clickwrap/configuration.rb', line 98

def encrypt_recorded_ip_geolocation
  @encrypt_recorded_ip_geolocation
end

#fail_capture_when_ip_geolocation_is_unavailable ⇒ Object

Returns the value of attribute fail_capture_when_ip_geolocation_is_unavailable.



103
104
105
 
# File 'lib/clickwrap/configuration.rb', line 103

def fail_capture_when_ip_geolocation_is_unavailable
  @fail_capture_when_ip_geolocation_is_unavailable
end

#find_current_tenant_with ⇒ Object

Returns the value of attribute find_current_tenant_with.



43
44
45
 
# File 'lib/clickwrap/configuration.rb', line 43

def find_current_tenant_with
  @find_current_tenant_with
end

#find_request_evidence_binding_key_with ⇒ Object

Returns the value of attribute find_request_evidence_binding_key_with.



105
106
107
 
# File 'lib/clickwrap/configuration.rb', line 105

def find_request_evidence_binding_key_with
  @find_request_evidence_binding_key_with
end

#hotwire_native_document_links ⇒ Object

Returns the value of attribute hotwire_native_document_links.



49
50
51
 
# File 'lib/clickwrap/configuration.rb', line 49

def hotwire_native_document_links
  @hotwire_native_document_links
end

#identify_actor_with ⇒ Object

Returns the value of attribute identify_actor_with.



43
44
45
 
# File 'lib/clickwrap/configuration.rb', line 43

def identify_actor_with
  @identify_actor_with
end

#ip_geolocation_resolver ⇒ Object

Returns the value of attribute ip_geolocation_resolver.



103
104
105
 
# File 'lib/clickwrap/configuration.rb', line 103

def ip_geolocation_resolver
  @ip_geolocation_resolver
end

#legal_basis_reference_for_recording_browser_user_agents_by_default ⇒ Object

--- Request evidence: why, how long, and how it is protected -------------



90
91
92
 
# File 'lib/clickwrap/configuration.rb', line 90

def legal_basis_reference_for_recording_browser_user_agents_by_default
  @legal_basis_reference_for_recording_browser_user_agents_by_default
end

#legal_basis_reference_for_recording_ip_addresses_by_default ⇒ Object

--- Request evidence: why, how long, and how it is protected -------------



90
91
92
 
# File 'lib/clickwrap/configuration.rb', line 90

def legal_basis_reference_for_recording_ip_addresses_by_default
  @legal_basis_reference_for_recording_ip_addresses_by_default
end

#legal_basis_reference_for_recording_ip_geolocation_by_default ⇒ Object

--- Request evidence: why, how long, and how it is protected -------------



90
91
92
 
# File 'lib/clickwrap/configuration.rb', line 90

def legal_basis_reference_for_recording_ip_geolocation_by_default
  @legal_basis_reference_for_recording_ip_geolocation_by_default
end

#lint_presentations ⇒ Object

--- Development aids -----------------------------------------------------



56
57
58
 
# File 'lib/clickwrap/configuration.rb', line 56

def lint_presentations
  @lint_presentations
end

#parent_controller_class_name ⇒ Object

The readers are grouped by section on purpose, and kept that way even though rubocop would happily collapse them into one line. The initializer this class backs is the main thing a host reads about Clickwrap, and the shape of these groups is the shape of that file.

--- Identity -------------------------------------------------------------



42
43
44
 
# File 'lib/clickwrap/configuration.rb', line 42

def parent_controller_class_name
  @parent_controller_class_name
end

#policy_paths ⇒ Object

Returns the value of attribute policy_paths.



51
52
53
 
# File 'lib/clickwrap/configuration.rb', line 51

def policy_paths
  @policy_paths
end

#presentation_valid_for ⇒ Object

--- Presentation ---------------------------------------------------------



59
60
61
 
# File 'lib/clickwrap/configuration.rb', line 59

def presentation_valid_for
  @presentation_valid_for
end

#publish_documents_after_database_preparation ⇒ Object

Returns the value of attribute publish_documents_after_database_preparation.



50
51
52
 
# File 'lib/clickwrap/configuration.rb', line 50

def publish_documents_after_database_preparation
  @publish_documents_after_database_preparation
end

#raise_on_missing_translation ⇒ Object

Returns the value of attribute raise_on_missing_translation.



53
54
55
 
# File 'lib/clickwrap/configuration.rb', line 53

def raise_on_missing_translation
  @raise_on_missing_translation
end

#read_browser_user_agent_from_http_request_with ⇒ Object

Returns the value of attribute read_browser_user_agent_from_http_request_with.



102
103
104
 
# File 'lib/clickwrap/configuration.rb', line 102

def read_browser_user_agent_from_http_request_with
  @read_browser_user_agent_from_http_request_with
end

#read_ip_address_from_http_request_with ⇒ Object

Returns the value of attribute read_ip_address_from_http_request_with.



102
103
104
 
# File 'lib/clickwrap/configuration.rb', line 102

def read_ip_address_from_http_request_with
  @read_ip_address_from_http_request_with
end

#reason_for_recording_browser_user_agents_by_default ⇒ Object

--- Request evidence: why, how long, and how it is protected -------------



90
91
92
 
# File 'lib/clickwrap/configuration.rb', line 90

def reason_for_recording_browser_user_agents_by_default
  @reason_for_recording_browser_user_agents_by_default
end

#reason_for_recording_ip_addresses_by_default ⇒ Object

--- Request evidence: why, how long, and how it is protected -------------



90
91
92
 
# File 'lib/clickwrap/configuration.rb', line 90

def reason_for_recording_ip_addresses_by_default
  @reason_for_recording_ip_addresses_by_default
end

#reason_for_recording_ip_geolocation_by_default ⇒ Object

--- Request evidence: why, how long, and how it is protected -------------



90
91
92
 
# File 'lib/clickwrap/configuration.rb', line 90

def reason_for_recording_ip_geolocation_by_default
  @reason_for_recording_ip_geolocation_by_default
end

#reason_for_storing_request_evidence_unencrypted ⇒ Object (readonly)

Returns the value of attribute reason_for_storing_request_evidence_unencrypted.



104
105
106
 
# File 'lib/clickwrap/configuration.rb', line 104

def reason_for_storing_request_evidence_unencrypted
  @reason_for_storing_request_evidence_unencrypted
end

#record_browser_user_agent_by_default ⇒ Object

--- Request evidence: what is recorded by default ------------------------

One reader per IP-geolocation field, spelled out rather than generated, because each is a separate decision about what to keep about someone's network context and each should be greppable by its own name.



78
79
80
 
# File 'lib/clickwrap/configuration.rb', line 78

def record_browser_user_agent_by_default
  @record_browser_user_agent_by_default
end

#record_ip_address_by_default ⇒ Object

--- Request evidence: what is recorded by default ------------------------

One reader per IP-geolocation field, spelled out rather than generated, because each is a separate decision about what to keep about someone's network context and each should be greppable by its own name.



78
79
80
 
# File 'lib/clickwrap/configuration.rb', line 78

def record_ip_address_by_default
  @record_ip_address_by_default
end

#record_ip_geolocation_accuracy_radius_in_kilometers_by_default ⇒ Object (readonly)

Returns the value of attribute record_ip_geolocation_accuracy_radius_in_kilometers_by_default.



79
80
81
 
# File 'lib/clickwrap/configuration.rb', line 79

def record_ip_geolocation_accuracy_radius_in_kilometers_by_default
  @record_ip_geolocation_accuracy_radius_in_kilometers_by_default
end

#record_ip_geolocation_city_by_default ⇒ Object (readonly)

Returns the value of attribute record_ip_geolocation_city_by_default.



79
80
81
 
# File 'lib/clickwrap/configuration.rb', line 79

def record_ip_geolocation_city_by_default
  @record_ip_geolocation_city_by_default
end

#record_ip_geolocation_continent_by_default ⇒ Object (readonly)

Returns the value of attribute record_ip_geolocation_continent_by_default.



79
80
81
 
# File 'lib/clickwrap/configuration.rb', line 79

def record_ip_geolocation_continent_by_default
  @record_ip_geolocation_continent_by_default
end

#record_ip_geolocation_country_by_default ⇒ Object (readonly)

Returns the value of attribute record_ip_geolocation_country_by_default.



79
80
81
 
# File 'lib/clickwrap/configuration.rb', line 79

def record_ip_geolocation_country_by_default
  @record_ip_geolocation_country_by_default
end

#record_ip_geolocation_latitude_and_longitude_by_default ⇒ Object (readonly)

Returns the value of attribute record_ip_geolocation_latitude_and_longitude_by_default.



79
80
81
 
# File 'lib/clickwrap/configuration.rb', line 79

def record_ip_geolocation_latitude_and_longitude_by_default
  @record_ip_geolocation_latitude_and_longitude_by_default
end

#record_ip_geolocation_metro_code_by_default ⇒ Object (readonly)

Returns the value of attribute record_ip_geolocation_metro_code_by_default.



79
80
81
 
# File 'lib/clickwrap/configuration.rb', line 79

def record_ip_geolocation_metro_code_by_default
  @record_ip_geolocation_metro_code_by_default
end

#record_ip_geolocation_postal_code_by_default ⇒ Object (readonly)

Returns the value of attribute record_ip_geolocation_postal_code_by_default.



79
80
81
 
# File 'lib/clickwrap/configuration.rb', line 79

def record_ip_geolocation_postal_code_by_default
  @record_ip_geolocation_postal_code_by_default
end

#record_ip_geolocation_region_by_default ⇒ Object (readonly)

Returns the value of attribute record_ip_geolocation_region_by_default.



79
80
81
 
# File 'lib/clickwrap/configuration.rb', line 79

def record_ip_geolocation_region_by_default
  @record_ip_geolocation_region_by_default
end

#record_ip_geolocation_timezone_by_default ⇒ Object (readonly)

Returns the value of attribute record_ip_geolocation_timezone_by_default.



79
80
81
 
# File 'lib/clickwrap/configuration.rb', line 79

def record_ip_geolocation_timezone_by_default
  @record_ip_geolocation_timezone_by_default
end

#remediation_token_valid_for ⇒ Object

Returns the value of attribute remediation_token_valid_for.



60
61
62
 
# File 'lib/clickwrap/configuration.rb', line 60

def remediation_token_valid_for
  @remediation_token_valid_for
end

#report_after_commit_failure_with ⇒ Object

--- Hooks ----------------------------------------------------------------



108
109
110
 
# File 'lib/clickwrap/configuration.rb', line 108

def report_after_commit_failure_with
  @report_after_commit_failure_with
end

#review_default_request_evidence_configuration_on ⇒ Object

--- Request evidence: why, how long, and how it is protected -------------



90
91
92
 
# File 'lib/clickwrap/configuration.rb', line 90

def review_default_request_evidence_configuration_on
  @review_default_request_evidence_configuration_on
end

#snapshot_actor_with ⇒ Object

Returns the value of attribute snapshot_actor_with.



43
44
45
 
# File 'lib/clickwrap/configuration.rb', line 43

def snapshot_actor_with
  @snapshot_actor_with
end

#store_document_contents_in ⇒ Object

--- Documents and policies -----------------------------------------------



47
48
49
 
# File 'lib/clickwrap/configuration.rb', line 47

def store_document_contents_in
  @store_document_contents_in
end

#template_version ⇒ Object

Returns the value of attribute template_version.



65
66
67
 
# File 'lib/clickwrap/configuration.rb', line 65

def template_version
  @template_version
end

#timestamp_receipts_with ⇒ Object

Returns the value of attribute timestamp_receipts_with.



64
65
66
 
# File 'lib/clickwrap/configuration.rb', line 64

def timestamp_receipts_with
  @timestamp_receipts_with
end

#trusted_proxy_configuration_digest ⇒ Object

Returns the value of attribute trusted_proxy_configuration_digest.



104
105
106
 
# File 'lib/clickwrap/configuration.rb', line 104

def trusted_proxy_configuration_digest
  @trusted_proxy_configuration_digest
end

#verify_actor_can_act_for_represented_party_with ⇒ Object

Returns the value of attribute verify_actor_can_act_for_represented_party_with.



69
70
71
 
# File 'lib/clickwrap/configuration.rb', line 69

def verify_actor_can_act_for_represented_party_with
  @verify_actor_can_act_for_represented_party_with
end

Instance Method Details

#actor_class ⇒ Object

The constantized actor class, resolved lazily on first use. Lazy on purpose: the initializer that sets config.actor_class_name = "User" runs before the User model is necessarily loaded.



303
304
305
306
307
308
309
310
 
# File 'lib/clickwrap/configuration.rb', line 303

def actor_class
  name = actor_class_name
  if @actor_class.nil? || @actor_class_name_at_resolution != name
    @actor_class = name.constantize
    @actor_class_name_at_resolution = name
  end
  @actor_class
end

#calculate_retention_time_for(name, &block) ⇒ Object

Registers a host calculation for an event-based retention rule.

config.calculate_retention_time_for :regulated_evidence_retention_ends do |event|
[event.recorded_at_by_server + 5.years,
 event.subject_liquidated_at&.+(3.years)].compact.max
end

Returning nil is a legitimate answer: it means the triggering host event has not happened yet, so the record is not due for disposition and Clickwrap reports it as unresolved rather than inventing a date.

Raises:



783
784
785
786
787
788
789
790
791
792
793
794
795
 
# File 'lib/clickwrap/configuration.rb', line 783

def calculate_retention_time_for(name, &block)
  raise ConfigurationError, "calculate_retention_time_for needs a block" unless block

  key = ensure_present_symbol(name, "retention calculation name")
  if @retention_time_calculators.key?(key)
    raise ConfigurationError,
          "A retention calculation named #{key.inspect} is already registered. Use one " \
          "stable name per calculation; Clickwrap will not silently replace a deletion " \
          "deadline because initializer order changed."
  end

  @retention_time_calculators[key] = block
end

#current_request_evidence_binding_key_id ⇒ Object 



732
733
734
735
 
# File 'lib/clickwrap/configuration.rb', line 732

def current_request_evidence_binding_key_id
  @current_request_evidence_binding_key_id ||
    default_request_evidence_binding_key_id(default_request_evidence_binding_key)
end

#current_request_evidence_binding_key_id=(value) ⇒ Object

Plain-English key-rotation API. The ID is evidence and must stay stable; the callback returns key bytes for current OR historical IDs.

config.current_request_evidence_binding_key_id = "request-evidence-2026-01"
config.find_request_evidence_binding_key_with = ->(key_id) { keyring[key_id] }


726
727
728
729
730
 
# File 'lib/clickwrap/configuration.rb', line 726

def current_request_evidence_binding_key_id=(value)
  @current_request_evidence_binding_key_id = ensure_present_string(
    value, "current_request_evidence_binding_key_id"
  )
end

#deliberately_store_request_evidence_unencrypted!(because:) ⇒ Object

The deliberate, named escape hatch referenced by ensure_encryption_choice. It exists so that turning encryption off is a sentence a reviewer can find in a diff, with the host's own reason attached, rather than a false.



1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
 
# File 'lib/clickwrap/configuration.rb', line 1101

def deliberately_store_request_evidence_unencrypted!(because:)
  if because.to_s.strip.empty?
    raise ConfigurationError,
          "deliberately_store_request_evidence_unencrypted! needs a `because:` explaining " \
          "the reviewed decision."
  end

  @deliberately_storing_request_evidence_unencrypted = true
  @reason_for_storing_request_evidence_unencrypted = because
end

#enabled_default_ip_geolocation_fields ⇒ Object 



853
854
855
856
857
 
# File 'lib/clickwrap/configuration.rb', line 853

def enabled_default_ip_geolocation_fields
  Vocabulary::IP_GEOLOCATION_DATA_FIELDS.select do |field|
    public_send(:"record_ip_geolocation_#{field}_by_default")
  end
end

#hotwire_native_canonical_host ⇒ Object

The canonical host, resolved and validated at use time so a host that is only knowable after boot (application config, credentials) can be a callable. Trailing slashes are trimmed because the engine path this prefixes always begins with one.



479
480
481
482
483
484
485
486
 
# File 'lib/clickwrap/configuration.rb', line 479

def hotwire_native_canonical_host
  configured = hotwire_native_document_links&.fetch(:canonical_host, nil)
  return nil if configured.nil?

  resolved = configured.respond_to?(:call) ? configured.call.to_s : configured.to_s
  validate_hotwire_native_canonical_host!(resolved)
  resolved.chomp("/")
end

#hotwire_native_document_link_mode(context = nil) ⇒ Object

The mode this render should use, resolved at use time so a callable can answer per request or per screen. context is the controller handling the request; both the href and the link attributes are resolved from the same one, so the two halves of a document link cannot disagree.



459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
 
# File 'lib/clickwrap/configuration.rb', line 459

def hotwire_native_document_link_mode(context = nil)
  configured = hotwire_native_document_links&.fetch(:open_in, nil)
  return configured unless configured.respond_to?(:call)

  resolved = (configured.arity.zero? ? configured.call : configured.call(context))&.to_sym

  unless HOTWIRE_NATIVE_DOCUMENT_LINK_MODES.include?(resolved)
    raise ConfigurationError,
          "hotwire_native_document_links `open_in:` answered #{resolved.inspect}. A callable " \
          "there must answer #{HOTWIRE_NATIVE_DOCUMENT_LINK_MODES.map(&:inspect).join(" or ")} " \
          "on every request — there is no third way for a document link to open."
  end

  resolved
end

#ip_geolocation_resolver_for(name = nil) ⇒ Object 



713
714
715
716
717
 
# File 'lib/clickwrap/configuration.rb', line 713

def ip_geolocation_resolver_for(name = nil)
  return ip_geolocation_resolver if name.blank? || name.to_s == "application_default"

  @ip_geolocation_resolvers[name.to_s]
end

#ip_geolocation_resolver_names ⇒ Object 



719
 
# File 'lib/clickwrap/configuration.rb', line 719

def ip_geolocation_resolver_names = @ip_geolocation_resolvers.keys.sort.freeze

#parent_controller_class ⇒ Object 



312
 
# File 'lib/clickwrap/configuration.rb', line 312

def parent_controller_class = parent_controller_class_name.constantize

#records_any_request_evidence_by_default? ⇒ Boolean

A convenience the initializer template and clickwrap:doctor both use.

Returns:

  • (Boolean) 


847
848
849
850
851
 
# File 'lib/clickwrap/configuration.rb', line 847

def records_any_request_evidence_by_default?
  record_ip_address_by_default ||
    record_browser_user_agent_by_default ||
    enabled_default_ip_geolocation_fields.any?
end

#register_ip_geolocation_resolver(name, resolver) ⇒ Object

Register more than one resolver and let each server-owned policy select one by name with record_ip_geolocation ..., using: :maxmind.



698
699
700
701
702
703
704
705
706
707
708
709
710
711
 
# File 'lib/clickwrap/configuration.rb', line 698

def register_ip_geolocation_resolver(name, resolver)
  key = ensure_present_symbol(name, "IP-geolocation resolver name").to_s
  if key == "application_default" || @ip_geolocation_resolvers.key?(key)
    raise ConfigurationError,
          "An IP-geolocation resolver named #{key.inspect} is already reserved or registered. " \
          "Choose one stable, unique name; Clickwrap will not silently replace a resolver " \
          "because initializer order changed."
  end

  @ip_geolocation_resolvers[key] = ensure_ip_geolocation_resolver(
    resolver,
    "IP-geolocation resolver #{key}"
  )
end

#register_represented_party_authority(name, adapter) ⇒ Object

Register a named, server-side authority adapter. Policies refer to the name from their compiled revision; the browser never submits it.

config.register_represented_party_authority :company_directory, MyAdapter.new

The adapter receives actor:, represented_party:, authority_rule:, tenant:, and authentication_context:, and returns Clickwrap::AuthorityDecision.



588
589
590
591
592
593
594
595
596
597
598
599
 
# File 'lib/clickwrap/configuration.rb', line 588

def register_represented_party_authority(name, adapter)
  key = ensure_present_symbol(name, "represented-party authority name").to_s
  if @represented_party_authority_adapters.key?(key)
    raise ConfigurationError,
          "A represented-party authority adapter named #{key.inspect} is already registered. " \
          "Use one stable name per adapter; Clickwrap will not silently replace an " \
          "authorization decision because initializer order changed."
  end

  @represented_party_authority_adapters[key] =
    ensure_adapter(adapter, "represented-party authority #{key}", :verify)
end

#remediation_represented_party_authorization_configured? ⇒ Boolean

Returns:

  • (Boolean) 


577
578
579
 
# File 'lib/clickwrap/configuration.rb', line 577

def remediation_represented_party_authorization_configured?
  @remediation_represented_party_authorization_configured
end

#remediation_subject_authorization_configured? ⇒ Boolean

Returns:

  • (Boolean) 


575
 
# File 'lib/clickwrap/configuration.rb', line 575

def remediation_subject_authorization_configured? = @remediation_subject_authorization_configured

#replace_retention_time_calculation_for(name, because:, &block) ⇒ Object

Deliberate replacement for tests, staged migrations, or a host that is intentionally changing an existing calculation. The separate verb and required reason keep this from becoming last-initializer-wins behavior.



800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
 
# File 'lib/clickwrap/configuration.rb', line 800

def replace_retention_time_calculation_for(name, because:, &block)
  key = ensure_present_symbol(name, "retention calculation name")
  unless @retention_time_calculators.key?(key)
    raise ConfigurationError,
          "No retention calculation named #{key.inspect} exists to replace. Register it " \
          "first with `calculate_retention_time_for`."
  end
  unless block
    raise ConfigurationError,
          "replace_retention_time_calculation_for needs a block with the new calculation."
  end
  if because.to_s.strip.empty?
    raise ConfigurationError,
          "Replacing retention calculation #{key.inspect} needs a `because:` explaining " \
          "the reviewed change."
  end

  @retention_time_calculators[key] = block
end

#represented_party_authority_adapter(name) ⇒ Object 



601
602
603
 
# File 'lib/clickwrap/configuration.rb', line 601

def represented_party_authority_adapter(name)
  @represented_party_authority_adapters[name.to_s]
end

#represented_party_authority_adapter_names ⇒ Object 



605
606
607
 
# File 'lib/clickwrap/configuration.rb', line 605

def represented_party_authority_adapter_names
  @represented_party_authority_adapters.keys.sort.freeze
end

#request_evidence_binding_key_for(key_id) ⇒ Object 



742
743
744
745
746
747
748
749
750
751
752
753
754
 
# File 'lib/clickwrap/configuration.rb', line 742

def request_evidence_binding_key_for(key_id)
  key = find_request_evidence_binding_key_with.call(key_id)
  return nil if key.nil?

  bytes = key.to_s.b
  if bytes.bytesize < 32
    raise ConfigurationError,
          "find_request_evidence_binding_key_with returned only #{bytes.bytesize} bytes for " \
          "#{key_id.inspect}. Request-evidence binding keys must be at least 32 bytes."
  end

  bytes
end

#resolve_retention_time(name, event) ⇒ Object 



822
823
824
825
826
827
828
829
830
831
832
833
 
# File 'lib/clickwrap/configuration.rb', line 822

def resolve_retention_time(name, event)
  calculator = @retention_time_calculators[name.to_sym]

  unless calculator
    raise ConfigurationError,
          "No retention calculation is registered for #{name.inspect}. A retention class " \
          "asked for it with `retain_..._until #{name.inspect}`. Register it with " \
          "`config.calculate_retention_time_for #{name.inspect} do |event| ... end`."
  end

  calculator.call(event)
end

#resolved_application_version ⇒ Object 



544
 
# File 'lib/clickwrap/configuration.rb', line 544

def resolved_application_version = application_version.call

#resolved_template_version ⇒ Object 



545
 
# File 'lib/clickwrap/configuration.rb', line 545

def resolved_template_version = template_version.call

#respond_to_missing?(name, include_private = false) ⇒ Boolean

Returns:

  • (Boolean) 


1125
1126
1127
 
# File 'lib/clickwrap/configuration.rb', line 1125

def respond_to_missing?(name, include_private = false)
  super
end

#retention_time_calculator_names ⇒ Object 



820
 
# File 'lib/clickwrap/configuration.rb', line 820

def retention_time_calculator_names = @retention_time_calculators.keys

#storing_request_evidence_unencrypted? ⇒ Boolean

Returns:

  • (Boolean) 


1112
 
# File 'lib/clickwrap/configuration.rb', line 1112

def storing_request_evidence_unencrypted? = @deliberately_storing_request_evidence_unencrypted == true

#validate! ⇒ Object

Run at the end of Clickwrap.configure. The per-setter checks already caught the typos; these are the things that need the whole block resolved.



839
840
841
842
843
844
 
# File 'lib/clickwrap/configuration.rb', line 839

def validate!
  validate_request_evidence_defaults!
  validate_trusted_proxy_configuration!
  validate_ip_geolocation_resolver!
  true
end