clickwrap 0.0.0 → 0.1.1

data/lib/clickwrap.rb

@@ -1,15 +1,505 @@
 # frozen_string_literal: true
 
+require "active_support"
+require "active_support/core_ext/string/inflections"
+require "active_support/core_ext/numeric/time"
+require "active_support/core_ext/object/blank"
+
 require_relative "clickwrap/version"
+require_relative "clickwrap/errors"
+require_relative "clickwrap/vocabulary"
+require_relative "clickwrap/canonical_json"
+require_relative "clickwrap/digest"
+require_relative "clickwrap/identifier"
+require_relative "clickwrap/reference"
+require_relative "clickwrap/protected_outcome"
+require_relative "clickwrap/trusted_proxy_configuration"
+require_relative "clickwrap/reviewed_text"
+require_relative "clickwrap/ip_geolocation"
+require_relative "clickwrap/authority"
+require_relative "clickwrap/integrations/organizations_authority"
+require_relative "clickwrap/subject_fingerprint"
+require_relative "clickwrap/remediation_token"
+require_relative "clickwrap/durable_commit_callback"
+require_relative "clickwrap/front_matter"
+require_relative "clickwrap/document_renderer"
+require_relative "clickwrap/document_renderers/markdown"
+require_relative "clickwrap/document_renderers/markdown_rails"
+require_relative "clickwrap/configuration"
+require_relative "clickwrap/macros"
+
+require_relative "clickwrap/engine" if defined?(Rails::Engine)
 
-# clickwrap is not implemented yet.
+# == Clickwrap
+#
+# The evidence-and-assent layer for Rails: versioned agreements,
+# acknowledgments, consent, declarations, attestations, and authorizations,
+# captured with the exact content and presentation they were offered under, and
+# committed in the same transaction as the action they authorize.
+#
+# The public surface is intentionally small:
+#
+#   Clickwrap.configure { |config| ... }   # one block, in an initializer
+#   Clickwrap.document :terms, ...         # immutable versioned content
+#   Clickwrap.policy :signup do ... end    # what the server offers and accepts
+#   Clickwrap.retention :ordinary do ...   # how long each part is kept
 #
-# This release exists only to hold the gem name while the product is being
-# defined. It ships no engine, no models, no migrations, and no public API,
-# and it deliberately declares no runtime dependencies. Requiring it does
-# nothing beyond defining this module and VERSION.
+#   has_clickwraps                         # on the model that can act
+#   form.clickwrap :signup, submit: "..."  # render the controls and the action
 #
-# See https://github.com/rameerez/clickwrap for the README-first contract
-# describing the gem we intend to build.
+#   Clickwrap.capture!(:signup, actor:, http_request:, submission:)
+#   Clickwrap.capture_and!(:withdrawal, ...) { withdrawal.submit! }
+#   user.clickwraps.agreed_to?(:terms)
+#   Clickwrap.verify(:withdrawal, actor:, subject:)
+#
+# What this gem does is evidence mechanics. What it does not do is decide
+# whether your agreement is enforceable, whether consent is the right lawful
+# basis, whether a document change is material, who someone really is, or how
+# long you must keep anything. Those belong to the application and its counsel,
+# and no configuration flag here can stand in for them.
 module Clickwrap
+  DOCUMENT_OPTIONS = %i[
+    version locale media_type effective_at tenant from content resolver renderer link
+  ].freeze
+
+  # The Minitest helpers hosts include in their own suite. Autoloaded rather
+  # than required at boot: a test helper has no business being resident in a
+  # production process, and a host that never writes a Clickwrap test never
+  # loads the file.
+  #
+  #   class ActiveSupport::TestCase
+  #     include Clickwrap::TestHelpers
+  #   end
+  autoload :TestHelpers, "clickwrap/test_helpers"
+
+  class << self
+    # --- Configuration --------------------------------------------------------
+
+    def config
+      @config ||= Configuration.new
+    end
+
+    alias configuration config
+
+    def configure
+      yield config if block_given?
+      config.validate!
+      config
+    end
+
+    # Reset all global state. Used by the test suite to keep examples isolated;
+    # also handy in a console when experimenting with configuration.
+    def reset!
+      @config = Configuration.new
+      @documents = nil
+      @policies = nil
+      @retention_classes = nil
+      # Every memoized verifier goes with the configuration it was built from.
+      # A verifier that outlived a reset keeps signing and accepting tokens
+      # under the previous secret, which is the kind of thing a test suite
+      # papers over (by resetting it itself) and a console session discovers
+      # the hard way.
+      RemediationToken.reset_verifier! if defined?(RemediationToken)
+      PresentationManifest.reset_verifier! if defined?(PresentationManifest)
+      SchemaRequirements.reset! if defined?(SchemaRequirements)
+      self
+    end
+
+    # --- Registries -----------------------------------------------------------
+
+    def documents = @documents ||= Registry.new(:document)
+    def policies = @policies ||= Registry.new(:policy)
+    def retention_classes = @retention_classes ||= Registry.new(:retention_class)
+
+    # Declares one immutable document version. Declaring it does not publish it:
+    # `bin/rails clickwrap:publish` reads the bytes once, digests them, and
+    # freezes a database snapshot. Until then the declaration is a promise about
+    # what will be published, and a policy that references an unpublished
+    # document fails loudly rather than presenting nothing.
+    def document(key, **options)
+      unknown = options.keys.map(&:to_sym) - DOCUMENT_OPTIONS
+      unless unknown.empty?
+        raise DefinitionError,
+              "Document #{key.inspect} has unknown option#{"s" if unknown.many?} " \
+              "#{unknown.map { |option| "`#{option}:`" }.join(", ")}. Supported options are: " \
+              "#{DOCUMENT_OPTIONS.map { |option| "`#{option}:`" }.join(", ")}. Clickwrap never " \
+              "ignores document options."
+      end
+
+      definition = DocumentDefinition.new(key: key, **options)
+      documents.register(definition.identity, definition)
+      definition
+    end
+
+    # Declares a server-owned policy. Compiles immediately so a mistake is a
+    # boot failure with a sentence explaining it, not a surprise at 3am.
+    def policy(key, &block)
+      raise DefinitionError, "Clickwrap.policy needs a block" unless block
+
+      builder = DSL::PolicyBuilder.new(key)
+      builder.instance_eval(&block)
+      compiled = builder.compile
+
+      policies.register(compiled.key, compiled)
+      compiled
+    end
+
+    # Declares a retention class. Clickwrap does not choose retention periods
+    # and cannot tell you whether yours are right; it makes a reviewed decision
+    # executable, auditable, and separable — the core event's schedule is
+    # independent of the optional personal request evidence attached to it.
+    def retention(key, &block)
+      raise DefinitionError, "Clickwrap.retention needs a block" unless block
+
+      builder = DSL::RetentionBuilder.new(key)
+      builder.instance_eval(&block)
+      compiled = builder.compile
+
+      retention_classes.register(compiled.key, compiled)
+      compiled
+    end
+
+    def policy!(key)
+      policies.fetch(key.to_s) do
+        raise UnknownPolicyError,
+              "No policy named #{key.inspect}. Defined policies: " \
+              "#{policies.keys.sort.join(", ").presence || "(none)"}. Policies are declared with " \
+              "`Clickwrap.policy #{key.inspect} do ... end`, conventionally in config/clickwrap.rb."
+      end
+    end
+
+    def retention_class!(key)
+      retention_classes.fetch(key.to_s) do
+        raise UnknownRetentionClassError,
+              "No retention class named #{key.inspect}. Defined classes: " \
+              "#{retention_classes.keys.sort.join(", ").presence || "(none)"}."
+      end
+    end
+
+    def document_definitions_for(key, tenant: nil)
+      documents.values.select do |definition|
+        definition.key == key.to_s && definition.tenant_key == tenant&.to_s
+      end
+    end
+
+    # --- Presentation and capture --------------------------------------------
+
+    def present(policy_key, **)
+      Presenter.new(policy: policy!(policy_key), **).present
+    end
+
+    def capture!(policy_key, actor:, subject: nil, tenant: nil, http_request: nil,
+                 submission: nil, answers: nil, locale: nil, capture_channel: nil,
+                 acting_for: nil, authentication_context: nil, attribution_method: nil,
+                 idempotency_key: nil)
+      Capture.new(
+        policy: policy!(policy_key), actor: actor, subject: subject, tenant: tenant,
+        http_request: http_request, submission: submission, answers: answers, locale: locale,
+        capture_channel: capture_channel, acting_for: acting_for,
+        authentication_context: authentication_context, attribution_method: attribution_method,
+        idempotency_key: idempotency_key
+      ).capture!
+    end
+
+    def capture_and!(policy_key, actor:, subject: nil, tenant: nil, http_request: nil,
+                     submission: nil, answers: nil, locale: nil, capture_channel: nil,
+                     acting_for: nil, authentication_context: nil, attribution_method: nil,
+                     idempotency_key: nil, &)
+      Capture.new(
+        policy: policy!(policy_key), actor: actor, subject: subject, tenant: tenant,
+        http_request: http_request, submission: submission, answers: answers, locale: locale,
+        capture_channel: capture_channel, acting_for: acting_for,
+        authentication_context: authentication_context, attribution_method: attribution_method,
+        idempotency_key: idempotency_key
+      ).capture_and!(&)
+    end
+
+    # A prospective represented-party flow for records such as a new customer
+    # organization. The form binds the record type and a server-owned browser
+    # flow before the record exists. This block must return a persisted record
+    # of that presented type after creating its host authority relationship;
+    # Clickwrap then verifies authority,
+    # rebinds the final stable reference, and commits all of it together.
+    def create_represented_party!(policy_key, actor:, represented_party:,
+                                  represented_party_creation_flow_id:,
+                                  subject: nil, tenant: nil, http_request: nil,
+                                  submission: nil, answers: nil, locale: nil,
+                                  capture_channel: nil, authentication_context: nil,
+                                  attribution_method: nil, idempotency_key: nil, &)
+      Capture.new(
+        policy: policy!(policy_key), actor: actor, subject: subject, tenant: tenant,
+        http_request: http_request, submission: submission, answers: answers, locale: locale,
+        capture_channel: capture_channel, acting_for: represented_party,
+        authentication_context: authentication_context, attribution_method: attribution_method,
+        idempotency_key: idempotency_key,
+        represented_party_creation_flow_id: represented_party_creation_flow_id
+      ).create_represented_party!(&)
+    end
+
+    # Signup, modeled honestly: at first render there is no persisted actor, so
+    # the presentation binds to a short-lived registration flow, and the account
+    # and its evidence commit together. The receipt records account-registration
+    # attribution rather than pretending someone was already authenticated.
+    #
+    # A prospective actor must be new. A public form's typed email address is
+    # not proof that its visitor controls an existing account or lead row. Use
+    # a distinct pending-request record, confirm the email address, and only
+    # then capture for the verified actor through the ordinary authenticated
+    # path.
+    def register!(policy_key, prospective_actor:, subject: nil, tenant: nil, http_request: nil,
+                  submission: nil, answers: nil, locale: nil, capture_channel: nil,
+                  acting_for: nil, authentication_context: nil, idempotency_key: nil,
+                  registration_flow_id: nil, &)
+      Capture.new(
+        policy: policy!(policy_key), actor: nil, prospective_actor: prospective_actor,
+        subject: subject, tenant: tenant, http_request: http_request, submission: submission,
+        answers: answers, locale: locale, capture_channel: capture_channel,
+        acting_for: acting_for, authentication_context: authentication_context,
+        idempotency_key: idempotency_key, registration_flow_id: registration_flow_id
+      ).register!(&)
+    end
+
+    # Produces the strict, canonical result snapshot consumed by
+    # `record_protected_outcome_with`. Keeping this construction in the gem
+    # prevents every host from inventing a subtly different hash contract.
+    def protected_outcome(...) = ProtectedOutcome.build(...)
+
+    # Digest the effective proxy rules rather than a prose description of
+    # them. The Rails-specific helper includes Rails' actual defaults when the
+    # application has not overridden `action_dispatch.trusted_proxies`.
+    def trusted_proxy_configuration_digest_for(trusted_proxies)
+      TrustedProxyConfiguration.digest_for(trusted_proxies)
+    end
+
+    def trusted_proxy_configuration_digest_for_rails_application(application = Rails.application)
+      TrustedProxyConfiguration.digest_for_rails_application(application)
+    end
+
+    def submission_from(params, ...) = Submission.from_params(params, ...)
+
+    # --- Lifecycle ------------------------------------------------------------
+    #
+    # Each of these spells out the keywords its target accepts rather than
+    # forwarding `**`. A bare forward compiles fine and reads fine, and then an
+    # editor shows `**` where the argument list should be, a typo'd keyword
+    # travels one method further before failing, and the public API of the gem
+    # is documented only in the private method behind it.
+
+    def withdraw!(purpose_key, actor:, because:, tenant: nil, subject: nil,
+                  acting_for: nil, http_request: nil)
+      Lifecycle.withdraw!(purpose_key, actor: actor, because: because, tenant: tenant,
+                                       subject: subject, acting_for: acting_for,
+                                       http_request: http_request)
+    end
+
+    # Correcting, renewing, and rescoping are new statements by the same
+    # person, so each takes the same `submission:` a first capture does: they
+    # are captured through a real presentation, not flipped administratively.
+    def correct_declaration!(statement_key, actor:, because:, subject: nil, tenant: nil,
+                             replaces: nil, acting_for: nil, http_request: nil,
+                             submission: nil, answers: nil)
+      Lifecycle.correct!(statement_key, actor: actor, because: because, subject: subject,
+                                        tenant: tenant, replaces: replaces, acting_for: acting_for,
+                                        http_request: http_request, submission: submission,
+                                        answers: answers)
+    end
+
+    def renew!(statement_key, actor:, because:, subject: nil, tenant: nil,
+               acting_for: nil, http_request: nil, submission: nil, answers: nil)
+      Lifecycle.renew!(statement_key, actor: actor, because: because, subject: subject,
+                                      tenant: tenant, acting_for: acting_for,
+                                      http_request: http_request, submission: submission,
+                                      answers: answers)
+    end
+
+    def change_consent_scope!(statement_key, actor:, because:, subject: nil, tenant: nil,
+                              acting_for: nil, http_request: nil, submission: nil, answers: nil)
+      Lifecycle.change_consent_scope!(statement_key, actor: actor, because: because,
+                                                     subject: subject, tenant: tenant,
+                                                     acting_for: acting_for,
+                                                     http_request: http_request,
+                                                     submission: submission, answers: answers)
+    end
+
+    def revoke!(statement_key, actor:, because:, subject: nil, tenant: nil,
+                acting_for: nil, http_request: nil)
+      Lifecycle.revoke!(statement_key, actor: actor, because: because, subject: subject,
+                                       tenant: tenant, acting_for: acting_for,
+                                       http_request: http_request)
+    end
+
+    def supersede!(statement_key, actor:, because: nil, subject: nil, tenant: nil,
+                   acting_for: nil, http_request: nil)
+      Lifecycle.supersede!(statement_key, actor: actor, because: because, subject: subject,
+                                          tenant: tenant, acting_for: acting_for,
+                                          http_request: http_request)
+    end
+
+    # An explicitly recorded system exemption. Seeds, imports, invitations, and
+    # service accounts must never "accept" by omitting a browser parameter or by
+    # fabricating a human click. An exemption says plainly that no human action
+    # occurred, records who created it and why, and never satisfies
+    # `agreed_to?` — it answers the separate `exempted_from?` question.
+    def exempt!(policy_key, actor:, because:, subject: nil, tenant: nil)
+      Lifecycle.exempt!(policy_key, actor: actor, because: because, subject: subject,
+                                    tenant: tenant)
+    end
+
+    # Captures evidence and commits a pending outbox row in one local
+    # transaction, for an action that has to cross a system boundary. This is a
+    # distributed reliability protocol, not a cross-system ACID transaction —
+    # see Clickwrap::Services::AuthorizeExternalAction for exactly what it does
+    # and does not promise.
+    def authorize_external_action!(policy_key,
+                                   after_pending_action_is_saved_inside_transaction: nil,
+                                   **,
+                                   &local_transaction_block)
+      if after_pending_action_is_saved_inside_transaction && local_transaction_block
+        raise ArgumentError,
+              "Pass either after_pending_action_is_saved_inside_transaction: or a block, not both."
+      end
+
+      local_transaction_hook =
+        after_pending_action_is_saved_inside_transaction || local_transaction_block
+
+      Services::AuthorizeExternalAction.new(
+        policy: policy!(policy_key),
+        after_pending_action_is_saved_inside_transaction: local_transaction_hook,
+        **
+      ).call
+    end
+
+    def import_external_receipt!(policy_key, actor:, provider_name:, provider_event_id:,
+                                 provider_receipt: nil, verified_with: nil, verified_at: nil,
+                                 occurred_at: nil, subject: nil, tenant: nil, because: nil,
+                                 statements: nil)
+      Import::ExternalReceipt.new(
+        policy: policy!(policy_key), actor: actor, provider_name: provider_name,
+        provider_event_id: provider_event_id, provider_receipt: provider_receipt,
+        verified_with: verified_with, verified_at: verified_at, occurred_at: occurred_at,
+        subject: subject, tenant: tenant, because: because, statements: statements
+      ).import!
+    end
+
+    def import_legacy!(policy_key, actor:, occurred_at:, because:, known: {}, unknown: [],
+                       dry_run: false, subject: nil, tenant: nil, statements: nil,
+                       capture_channel: "imported_provider", source: nil, counts_as_current: true)
+      Import::Legacy.new(
+        policy: policy!(policy_key), actor: actor, occurred_at: occurred_at, because: because,
+        known: known, unknown: unknown, dry_run: dry_run, subject: subject, tenant: tenant,
+        statements: statements, capture_channel: capture_channel, source: source,
+        counts_as_current: counts_as_current
+      ).import!
+    end
+
+    # --- Verification and gating ---------------------------------------------
+
+    def verify(policy_or_event, **) = Verification.verify(policy_or_event, **)
+
+    def require!(policy_key, **)
+      result = verify(policy_key, **)
+      raise VerificationFailed, result unless result.success?
+
+      result
+    end
+
+    def current?(policy_key, **) = verify(policy_key, **).success?
+
+    # True when the actor needs to complete this policy: either they have no
+    # current evidence, or a newer required document version has published since
+    # they last acted. The application decides which change is material;
+    # Clickwrap enforces the rule it is given.
+    def required?(policy_key, **) = !current?(policy_key, **)
+
+    def receipt(event_id) = Receipt.find(event_id)
+
+    def export_receipt(receipt, **) = Receipt.export(receipt, **)
+
+    # Retry optional timestamp/anchor work that left no immutable result after a
+    # committed event. This is intentionally explicit: it can call external
+    # providers, so applications normally run it from a scheduled job or the
+    # matching rake task rather than hiding it in a read path.
+    def reconcile_missing_integrity_attestations!(scope: Event.all, retry_failed_attestations: false)
+      Integrity::AttestationReconciler.new(
+        scope: scope,
+        retry_failed_attestations: retry_failed_attestations
+      ).call
+    end
+
+    # --- Disposition ----------------------------------------------------------
+
+    def delete_recorded_ip_address!(receipt, because:)
+      Retention::Disposition.delete_field!(receipt, :ip_address, because:)
+    end
+
+    def delete_recorded_browser_user_agent!(receipt, because:)
+      Retention::Disposition.delete_field!(receipt, :browser_user_agent, because:)
+    end
+
+    def delete_recorded_ip_geolocation!(receipt, because:)
+      Retention::Disposition.delete_field!(receipt, :ip_geolocation, because:)
+    end
+
+    # --- Actors ---------------------------------------------------------------
+
+    # A stable opaque identifier for someone who is not a persisted record. The
+    # host owns the identifier and any later account linking. An IP address is
+    # not an actor identifier and Clickwrap will not accept one here.
+    def anonymous_actor(identifier) = AnonymousActor.new(identifier)
+
+    # A named non-human actor, for seeds, imports, and background processes.
+    def system_actor(name) = SystemActor.new(name)
+
+    # --- Publishing -----------------------------------------------------------
+
+    def publish!(dry_run: false) = Services::PublishDocuments.new(dry_run:).call
+
+    def doctor = Doctor.new.report
+
+    # --- Internals ------------------------------------------------------------
+
+    def gem_version = VERSION
+    def canonical_schema_version = CANONICAL_SCHEMA_VERSION
+
+    # The server's own clock, used for every recorded time. It is described in
+    # receipts as exactly that — time recorded by the application server — and
+    # never as trusted time, which is a different thing supplied by a different
+    # kind of provider.
+    def now = Time.now.utc
+
+    def logger
+      defined?(::Rails) && ::Rails.respond_to?(:logger) ? ::Rails.logger : nil
+    end
+
+    # Post-commit hooks are observers, never authorization. A failure here is
+    # reported and swallowed, because the evidence and the action it protected
+    # have already committed and nothing an analytics call does may undo them.
+    def report_after_commit_failure(error, event)
+      config.report_after_commit_failure_with.call(error, event)
+    rescue StandardError => error
+      logger&.error("[clickwrap] after-commit failure reporter itself raised: #{error.class}")
+      nil
+    end
+  end
 end
+
+require_relative "clickwrap/registry"
+require_relative "clickwrap/localized_text"
+require_relative "clickwrap/document_definition"
+require_relative "clickwrap/statement"
+require_relative "clickwrap/request_evidence_policy"
+require_relative "clickwrap/policy"
+require_relative "clickwrap/retention_class"
+require_relative "clickwrap/dsl/policy_builder"
+require_relative "clickwrap/dsl/retention_builder"
+
+# The framework-integration modules are spine files, not autoloaded code: the
+# engine's `on_load(:action_view)` / `on_load(:action_controller)` hooks run
+# IMMEDIATELY when a host's other gems have already loaded that framework by
+# the time Clickwrap's initializers register — which can be before the host's
+# autoloader can serve these constants. They must exist the moment the engine
+# file does.
+require_relative "clickwrap/form_builder_extensions"
+require_relative "clickwrap/view_helpers"
+require_relative "clickwrap/controller_helpers"
+require_relative "clickwrap/registration"

data/lib/generators/clickwrap/document_generator.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Clickwrap
+  module Generators
+    # `rails generate clickwrap:document terms` — declares one document and
+    # creates the file its bytes will come from, with the file's own front
+    # matter naming its version.
+    #
+    # Declaring is not publishing. This generator adds a declaration and a
+    # placeholder file; `bin/rails clickwrap:publish` is what reads the bytes,
+    # digests them, and freezes the snapshot that receipts point at from then
+    # on (deploys do this automatically after `db:prepare`).
+    #
+    # Changing a document later is NOT another run of this generator: the file
+    # that holds the words also names its version, so a new version is one
+    # edit in one file — change the text, bump `last_updated:` (or add
+    # `clickwrap_version:` for a same-day correction), publish. The
+    # declaration never changes, published bytes are never edited in place,
+    # and every receipt goes on pointing at the exact version its accepted
+    # server offer bound.
+    class DocumentGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+      desc "Declare a clickwrap document and create its content file"
+
+      argument :name, type: :string, banner: "DOCUMENT_NAME"
+
+      class_option :document_version, type: :string,
+                                      desc: "An explicit version label, written into the file's " \
+                                            "front matter (defaults to today's date as last_updated)"
+      class_option :locale, type: :string,
+                            desc: "Declare this version for one locale (en, es…)"
+
+      def create_content_file
+        if host_file?(content_path)
+          say_status :skip, "#{content_path} (you already have a file there)", :yellow
+          return
+        end
+
+        create_file content_path, placeholder_content
+      end
+
+      def declare_document
+        create_policy_file_if_missing
+
+        if declaration_present?
+          say_status :skip, "#{policy_file} (:#{document_key} is already declared — a new " \
+                            "version is a front-matter bump in #{content_path}, not a new " \
+                            "declaration)", :yellow
+          return
+        end
+
+        append_to_file policy_file, declaration
+      end
+
+      def display_next_steps
+        say "\n☑️  Document :#{document_key} declared.", :green
+        say "\nTo finish:"
+        say "  1. Put the real text in #{content_path}, keeping the front matter at the top."
+        say "     Clickwrap never writes legal text — the words are yours."
+        say "  2. Run 'bin/rails clickwrap:publish' to freeze an immutable snapshot."
+        say "     Deploys do this for you — publishing rides `db:prepare`."
+        say "  3. Reference it from a policy in #{policy_file}."
+        say "\nThe file names its own version: its `last_updated:` front matter is the label,"
+        say "so changing the text later is one edit in one file — new words, bumped label,"
+        say "publish. Reusing a label for different bytes is refused rather than accepted,"
+        say "and old receipts go on pointing at the bytes their accepted server offers bound.\n"
+      end
+
+      private
+
+      def document_key
+        name.to_s.underscore.tr("-", "_").tr("/", "_")
+      end
+
+      def explicit_version_label
+        options[:document_version].presence
+      end
+
+      def locale
+        options[:locale].presence
+      end
+
+      def policy_file
+        "config/clickwrap.rb"
+      end
+
+      def content_path
+        return "app/content/legal/#{document_key}.#{locale}.md" if locale
+
+        "app/content/legal/#{document_key}.md"
+      end
+
+      def declaration
+        lines = ["\nClickwrap.document :#{document_key},"]
+        lines << "  locale: :#{locale}," if locale
+        lines << "  from: Rails.root.join(#{content_path.inspect})\n"
+        lines.join("\n")
+      end
+
+      # One declaration per document key (and per locale): the version lives in
+      # the file, so a "new version" never adds a declaration — and a second
+      # version-less declaration of the same key would be refused at boot as a
+      # duplicate anyway.
+      def declaration_present?
+        File.read(File.expand_path(policy_file, destination_root))
+            .include?("Clickwrap.document :#{document_key},#{"\n  locale: :#{locale}," if locale}")
+      rescue StandardError
+        false
+      end
+
+      def create_policy_file_if_missing
+        return if host_file?(policy_file)
+
+        create_file policy_file, <<~RUBY
+          # frozen_string_literal: true
+
+          # Clickwrap documents, policies, and retention classes. Ordinary Ruby, so it is
+          # reviewable in a pull request and deploys with the code that depends on it.
+        RUBY
+      end
+
+      def host_file?(path)
+        File.exist?(File.expand_path(path, destination_root))
+      end
+
+      # The front matter is the version label. `last_updated:` is the usual
+      # key; an explicit --document-version lands as `clickwrap_version:`,
+      # which outranks it, so a hand-chosen label and a human-facing date can
+      # coexist without fighting.
+      def placeholder_front_matter
+        lines = ["---", "title: #{document_key.humanize}"]
+        lines << "clickwrap_version: #{explicit_version_label}" if explicit_version_label
+        lines << "last_updated: #{Date.today.iso8601}"
+        lines << "---"
+        "#{lines.join("\n")}\n\n"
+      end
+
+      def placeholder_content
+        <<~MARKDOWN
+          #{placeholder_front_matter.rstrip}
+
+          # PLACEHOLDER — replace this with your own reviewed text
+
+          **This is not a #{document_key.humanize.downcase}.** The `clickwrap` gem created this
+          file so the declaration in `config/clickwrap.rb` has bytes to point at, and it
+          deliberately contains no legal text of any kind: the gem does not know who you
+          are, where you operate, or which rules apply, and text that merely looked
+          plausible would be worse than this, because someone would ship it.
+
+          Replace this file, then run `bin/rails clickwrap:publish` to freeze an immutable
+          snapshot. Publishing records the exact bytes, media type, locale, and digest, so
+          a receipt written today can reproduce the document version its accepted server
+          offer bound years from now.
+
+          The front matter above is the version label: when the text changes, bump
+          `last_updated:` (or add `clickwrap_version:` for a same-day correction) and
+          publish again, rather than editing a published version in place.
+        MARKDOWN
+      end
+    end
+  end
+end