clickwrap 0.0.0 → 0.1.0

data/lib/generators/clickwrap/link_generator.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Clickwrap
+  module Generators
+    # Links a domain table to the clickwrap evidence that authorized its rows:
+    #
+    #   bin/rails generate clickwrap:link payouts_withdrawals
+    #
+    # writes the migration for a `clickwrap_event_id` column (ULID string,
+    # indexed, nullable, no foreign key — see the migration's own comment for
+    # why each of those is deliberate). Pair it with `has_clickwrap_evidence`
+    # on the model and assign `pending_receipt.event_id` inside
+    # `capture_clickwrap_and!`.
+    class LinkGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      argument :table_name, type: :string,
+                            desc: "The domain table whose rows are authorized by a clickwrap capture"
+
+      def create_link_migration
+        migration_template "link_clickwrap_event_migration.rb.erb",
+                           "db/migrate/add_clickwrap_event_to_#{table_name}.rb"
+      end
+
+      def explain
+        say ""
+        say "Next, on the model:"
+        say ""
+        say "  has_clickwrap_evidence policy: :your_policy,"
+        say "                         statement: :your_statement,"
+        say "                         actor: :user,"
+        say "                         subject: :self"
+        say ""
+        say "and assign the event inside the capture that authorizes the row:"
+        say ""
+        say "  capture_clickwrap_and!(:your_policy) do |pending_receipt|"
+        say "    record.clickwrap_event_id = pending_receipt.event_id"
+        say "    record.save!"
+        say "    record # returned to the protected-outcome recorder"
+        say "  end"
+        say ""
+      end
+
+      private
+
+      def migration_class_name
+        "AddClickwrapEventTo#{table_name.camelize}"
+      end
+    end
+  end
+end

data/lib/generators/clickwrap/policy_generator.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Clickwrap
+  module Generators
+    # `rails generate clickwrap:policy contractor_declaration declare
+    # --statement-text="I declare ..."` — one compiling policy and its test.
+    #
+    # The verb and exact first-person statement are required because choosing or
+    # inventing either would silently make product/legal meaning on the host's
+    # behalf. Once they are supplied, the generated file compiles immediately;
+    # it never writes an empty policy or an executable TODO placeholder.
+    #
+    # The test comes with it for the same reason tests come with a model: a
+    # policy is executable meaning, and "does this still say what we think it
+    # says" is a question worth asking on every commit.
+    class PolicyGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+      desc "Create one compiling clickwrap policy and its test"
+
+      VERBS = %w[agree_to acknowledge consent_to declare attest authorize].freeze
+
+      argument :name, type: :string, banner: "POLICY_NAME"
+      argument :verb, type: :string, banner: VERBS.join("|")
+
+      class_option :statement_text, type: :string, required: true,
+                                    desc: "Exact first-person assertion for the generated control"
+      class_option :statement_key, type: :string,
+                                   desc: "Stable statement key (defaults to the policy name)"
+      class_option :document, type: :string,
+                              desc: "Declared Clickwrap document key to link (optional)"
+      class_option :retention_class, type: :string, default: "ordinary_agreement_evidence",
+                                     desc: "Existing Clickwrap retention class"
+      class_option :withdrawal_path, type: :string,
+                                     desc: "Required remediation path for consent_to"
+
+      def validate_arguments!
+        return if VERBS.include?(policy_verb) && (!consent? || withdrawal_path.present?)
+
+        unless VERBS.include?(policy_verb)
+          raise Thor::Error,
+                "#{verb.inspect} is not a Clickwrap policy verb. Choose one of: #{VERBS.join(", ")}."
+        end
+
+        raise Thor::Error,
+              "A consent_to policy needs --withdrawal-path=/your/settings/page so the " \
+              "person has a concrete way to withdraw it."
+      end
+
+      def create_policy_file
+        template "policy.rb.erb", "config/clickwrap/#{policy_key}.rb"
+      end
+
+      def create_policy_test
+        template "policy_test.rb.erb", "test/clickwrap/#{policy_key}_policy_test.rb"
+      end
+
+      def display_next_steps
+        say "\n☑️  Compiling policy created.", :green
+        say "\nTo finish it:"
+        say "  1. Review the verb and exact statement in config/clickwrap/#{policy_key}.rb."
+        say "  2. If it references a document, declare and publish that document."
+        say "  3. Replace the generated test skips with your real actor and submission flow."
+        say "\nThe policy compiles at boot: a missing document, a duplicate statement key, a"
+        say "consent without a withdrawal path, or an indefinite one-time authorization is a"
+        say "startup failure with a sentence explaining it.\n"
+      end
+
+      private
+
+      def policy_key
+        name.to_s.underscore.tr("-", "_").tr("/", "_")
+      end
+
+      def policy_verb = verb.to_s
+
+      def statement_key
+        (options[:statement_key].presence || policy_key).underscore.tr("-", "_").tr("/", "_")
+      end
+
+      def statement_text = options.fetch(:statement_text).to_s
+
+      def document_key
+        key = options[:document].presence&.underscore
+        key&.tr("-", "_")&.tr("/", "_")
+      end
+
+      def retention_class_key = options.fetch(:retention_class).to_s.underscore.tr("-", "_").tr("/", "_")
+      def withdrawal_path = options[:withdrawal_path].to_s.strip
+      def consent? = policy_verb == "consent_to"
+
+      def evidence_kind
+        {
+          "agree_to" => "agreement",
+          "acknowledge" => "acknowledgment",
+          "consent_to" => "consent",
+          "declare" => "declaration",
+          "attest" => "attestation",
+          "authorize" => "authorization"
+        }.fetch(policy_verb)
+      end
+
+      def statement_options
+        options = ["statement: #{statement_text.inspect}"]
+        options.unshift("document: :#{document_key}") if document_key
+        options.unshift("document: nil") unless document_key
+        options << "optional: true" if consent?
+        options << "withdrawal_path: #{withdrawal_path.inspect}" if consent?
+        options
+      end
+
+      def test_class_name
+        "#{policy_key.camelize}PolicyTest"
+      end
+    end
+  end
+end

data/lib/generators/clickwrap/templates/clickwrap_hardening.rb.erb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+# ==============================================================================
+# Clickwrap database hardening — OPT-IN, PostgreSQL only
+# ==============================================================================
+#
+# Clickwrap's models make unsupported mutation loud. This migration adds a
+# narrower database control for writes that bypass models: direct SQL, `delete`,
+# `delete_all`, `update_column`, and `update_all`.
+#
+# WHAT THIS CLAIMS, IN FULL
+#
+# It rejects unsupported UPDATE and DELETE paths while these triggers are
+# installed and the writer is not able to disable or replace them.
+#
+# WHAT IT DOES NOT CLAIM
+#
+# It does not make evidence impossible to alter. A database owner, superuser,
+# migration role, or anyone able to drop triggers can remove this control. It
+# does not authenticate a person, establish when an event happened, or make a
+# local digest independent of the database that stores it.
+#
+# WHAT REMAINS POSSIBLE
+#
+# * A new event may be finalized once while its INSERT transaction is open.
+# * Host records may be deleted, nulling only optional polymorphic pointers; the
+#   stable actor/subject/represented-party references remain unchanged.
+# * A request-evidence annex may be linked once.
+# * A legal-hold flag may change through Clickwrap's recorded hold lifecycle.
+# * Core payload may be removed only when a finalized linked disposition event
+#   already identifies the event and its original digest. Child statement and
+#   document rows may be deleted only after that marker exists.
+#
+# Optional personal request-evidence annex values remain separately disposable
+# in `clickwrap_request_evidence` on their reviewed schedules, so this migration
+# does not protect that table from its own named disposition operations.
+#
+# Reversible: `rails db:rollback` drops only the functions and triggers created
+# below. It changes no evidence rows.
+# ==============================================================================
+class ClickwrapDatabaseHardening < ActiveRecord::Migration<%= migration_version %>
+  # This is a generation-time snapshot of the runtime's named write sets. It is
+  # intentionally self-contained: a host must be able to rebuild a database
+  # from this migration after upgrading Clickwrap without asking a newer gem to
+  # reinterpret an older database contract.
+  EVENT_WRITE_SETS = {
+<%= event_write_sets_for_migration %>
+  }.transform_values { |columns| columns.map(&:to_s).sort.freeze }.freeze
+
+  EVIDENCE_CHILD_TABLES = %w[
+    clickwrap_event_statements clickwrap_event_documents
+  ].freeze
+
+  def up
+    return say_unsupported_adapter unless postgresql?
+
+    execute <<~SQL
+      CREATE OR REPLACE FUNCTION clickwrap_reject_evidence_write() RETURNS trigger AS $function$
+      BEGIN
+        RAISE EXCEPTION
+          'clickwrap: % rejects this %. Use a named Clickwrap lifecycle or disposition operation.',
+          TG_TABLE_NAME,
+          TG_OP
+          USING ERRCODE = 'restrict_violation';
+      END;
+      $function$ LANGUAGE plpgsql;
+    SQL
+
+    execute <<~SQL
+      CREATE OR REPLACE FUNCTION clickwrap_guard_event_update() RETURNS trigger AS $function$
+      BEGIN
+        -- An unfinalized row is visible only inside its INSERT transaction. The
+        -- application builds children/outcome and then changes event_digest from
+        -- NULL to a value exactly once before COMMIT.
+        IF OLD.event_digest IS NULL THEN
+          RETURN NEW;
+        END IF;
+
+        -- A hold is a mutable projection backed by immutable hold lifecycle
+        -- rows. No other event field may ride along with this update.
+        IF (#{jsonb_without("NEW", EVENT_WRITE_SETS.fetch("legal_hold"))})
+           IS NOT DISTINCT FROM
+           (#{jsonb_without("OLD", EVENT_WRITE_SETS.fetch("legal_hold"))}) THEN
+          RETURN NEW;
+        END IF;
+
+        -- The annex pointer is attached once; its keyed category digests were
+        -- already covered by the finalized event digest.
+        IF OLD.request_evidence_id IS NULL
+           AND NEW.request_evidence_id IS NOT NULL
+           AND (#{jsonb_without("NEW", EVENT_WRITE_SETS.fetch("request_evidence_link"))})
+               IS NOT DISTINCT FROM
+               (#{jsonb_without("OLD", EVENT_WRITE_SETS.fetch("request_evidence_link"))}) THEN
+          RETURN NEW;
+        END IF;
+
+        -- Deleting a host actor/subject/represented party may only null its
+        -- convenience pointer. Stable references and every covered fact stay.
+        IF (#{jsonb_without("NEW", EVENT_WRITE_SETS.fetch("pointer_nullification"))})
+           IS NOT DISTINCT FROM
+           (#{jsonb_without("OLD", EVENT_WRITE_SETS.fetch("pointer_nullification"))})
+           AND ((NEW.actor_type IS NULL AND NEW.actor_id IS NULL)
+                OR (NEW.actor_type IS NOT DISTINCT FROM OLD.actor_type
+                    AND NEW.actor_id IS NOT DISTINCT FROM OLD.actor_id))
+           AND ((NEW.represented_party_type IS NULL AND NEW.represented_party_id IS NULL)
+                OR (NEW.represented_party_type IS NOT DISTINCT FROM OLD.represented_party_type
+                    AND NEW.represented_party_id IS NOT DISTINCT FROM OLD.represented_party_id))
+           AND ((NEW.subject_type IS NULL AND NEW.subject_id IS NULL)
+                OR (NEW.subject_type IS NOT DISTINCT FROM OLD.subject_type
+                    AND NEW.subject_id IS NOT DISTINCT FROM OLD.subject_id)) THEN
+          RETURN NEW;
+        END IF;
+
+        -- Core disposition is a one-way transition whose linked, finalized
+        -- disposition event names both this event and its original digest.
+        IF OLD.core_event_disposed_at IS NULL
+           AND NEW.core_event_disposed_at IS NOT NULL
+           AND NEW.core_event_disposition_event_id IS NOT NULL
+           AND (#{jsonb_without("NEW", EVENT_WRITE_SETS.fetch("disposition"))})
+               IS NOT DISTINCT FROM
+               (#{jsonb_without("OLD", EVENT_WRITE_SETS.fetch("disposition"))})
+           AND NEW.actor_type IS NULL AND NEW.actor_id IS NULL
+           AND NEW.actor_reference = '' AND NEW.actor_snapshot = '{}'::jsonb
+           AND NEW.represented_party_type IS NULL AND NEW.represented_party_id IS NULL
+           AND NEW.represented_party_reference = ''
+           AND NEW.authority_source IS NULL AND NEW.authority_role IS NULL
+           AND NEW.authority_verified_at IS NULL AND NEW.authority_details = '{}'::jsonb
+           AND NEW.tenant_key = ''
+           AND NEW.subject_type IS NULL AND NEW.subject_id IS NULL
+           AND NEW.subject_key = '' AND NEW.subject_fingerprint IS NULL
+           AND NEW.authentication_method IS NULL AND NEW.authentication_context = '{}'::jsonb
+           AND NEW.idempotency_key IS NULL
+           AND NEW.http_request_id IS NULL AND NEW.http_route_name IS NULL
+           AND NEW.presentation_id IS NULL AND NEW.presentation_manifest IS NULL
+           AND NEW.presentation_manifest_digest IS NULL
+           AND NEW.protected_outcome IS NULL
+           AND NEW.provider_receipt IS NULL AND NEW.provider_verification IS NULL
+           AND NEW.reason IS NULL
+           AND EXISTS (
+             SELECT 1
+               FROM clickwrap_events disposition
+              WHERE disposition.id = NEW.core_event_disposition_event_id
+                AND disposition.event_type = 'disposition'
+                AND disposition.event_digest IS NOT NULL
+                AND disposition.protected_outcome
+                      -> 'core_event_disposition' ->> 'event_id' = OLD.id
+                AND disposition.protected_outcome
+                      -> 'core_event_disposition' ->> 'original_event_digest' = OLD.event_digest
+           ) THEN
+          RETURN NEW;
+        END IF;
+
+        RAISE EXCEPTION
+          'clickwrap: clickwrap_events rejects this UPDATE. Use a named Clickwrap lifecycle or disposition operation.'
+          USING ERRCODE = 'restrict_violation';
+      END;
+      $function$ LANGUAGE plpgsql;
+    SQL
+
+    execute <<~SQL
+      CREATE OR REPLACE FUNCTION clickwrap_guard_evidence_child_write() RETURNS trigger AS $function$
+      BEGIN
+        IF TG_OP = 'DELETE' AND EXISTS (
+          SELECT 1
+            FROM clickwrap_events source_event
+            JOIN clickwrap_events disposition
+              ON disposition.id = source_event.core_event_disposition_event_id
+           WHERE source_event.id = OLD.event_id
+             AND source_event.core_event_disposed_at IS NOT NULL
+             AND disposition.event_type = 'disposition'
+             AND disposition.event_digest IS NOT NULL
+             AND disposition.protected_outcome
+                   -> 'core_event_disposition' ->> 'event_id' = source_event.id
+             AND disposition.protected_outcome
+                   -> 'core_event_disposition' ->> 'original_event_digest' = source_event.event_digest
+        ) THEN
+          RETURN OLD;
+        END IF;
+
+        RAISE EXCEPTION
+          'clickwrap: % rejects this %. Evidence children may be deleted only by a documented core disposition.',
+          TG_TABLE_NAME,
+          TG_OP
+          USING ERRCODE = 'restrict_violation';
+      END;
+      $function$ LANGUAGE plpgsql;
+    SQL
+
+    install_event_triggers
+    install_child_triggers
+
+    say "clickwrap: PostgreSQL update/delete protection installed on finalized events and their evidence children."
+  end
+
+  def down
+    return unless postgresql?
+
+    execute "DROP TRIGGER IF EXISTS clickwrap_events_guard_update ON clickwrap_events;"
+    execute "DROP TRIGGER IF EXISTS clickwrap_events_reject_delete ON clickwrap_events;"
+
+    EVIDENCE_CHILD_TABLES.each do |table|
+      execute "DROP TRIGGER IF EXISTS #{table}_guard_write ON #{table};"
+    end
+
+    execute "DROP FUNCTION IF EXISTS clickwrap_guard_event_update();"
+    execute "DROP FUNCTION IF EXISTS clickwrap_guard_evidence_child_write();"
+    execute "DROP FUNCTION IF EXISTS clickwrap_reject_evidence_write();"
+
+    say "clickwrap: PostgreSQL update/delete protection removed. No evidence rows were changed."
+  end
+
+  private
+
+  def install_event_triggers
+    execute "DROP TRIGGER IF EXISTS clickwrap_events_guard_update ON clickwrap_events;"
+    execute <<~SQL
+      CREATE TRIGGER clickwrap_events_guard_update
+        BEFORE UPDATE ON clickwrap_events
+        FOR EACH ROW EXECUTE FUNCTION clickwrap_guard_event_update();
+    SQL
+
+    execute "DROP TRIGGER IF EXISTS clickwrap_events_reject_delete ON clickwrap_events;"
+    execute <<~SQL
+      CREATE TRIGGER clickwrap_events_reject_delete
+        BEFORE DELETE ON clickwrap_events
+        FOR EACH ROW EXECUTE FUNCTION clickwrap_reject_evidence_write();
+    SQL
+  end
+
+  def install_child_triggers
+    EVIDENCE_CHILD_TABLES.each do |table|
+      execute "DROP TRIGGER IF EXISTS #{table}_guard_write ON #{table};"
+      execute <<~SQL
+        CREATE TRIGGER #{table}_guard_write
+          BEFORE UPDATE OR DELETE ON #{table}
+          FOR EACH ROW EXECUTE FUNCTION clickwrap_guard_evidence_child_write();
+      SQL
+    end
+  end
+
+  def jsonb_without(row_name, columns)
+    (["to_jsonb(#{row_name})"] + columns.map { |column| "- #{connection.quote(column)}" }).join(" ")
+  end
+
+  def postgresql?
+    connection.adapter_name.to_s.downcase.match?(/postgres|postgis/)
+  end
+
+  def say_unsupported_adapter
+    say "clickwrap: no database-level update/delete protection was installed."
+    say "  This opt-in migration is implemented and tested only for PostgreSQL.", true
+    say "  SQLite has no separate runtime role; any writer can drop its own trigger.", true
+    say "  On MySQL, use a runtime role whose grants match your reviewed write paths.", true
+    say "  Model refusals and digest verification continue to work on every supported adapter.", true
+  end
+end

data/lib/generators/clickwrap/templates/clickwrap_policies.rb.erb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+# ==============================================================================
+# Clickwrap documents, policies, and retention classes
+# ==============================================================================
+#
+# This file is ordinary Ruby so it is reviewable in a pull request and deploys
+# with the code that depends on it. It is re-read on every boot and every
+# development reload, and a mistake is a boot failure with a sentence explaining
+# it — not a surprise the first time someone tries to sign up.
+#
+# Three kinds of declaration live here:
+#
+#   Clickwrap.document   versioned source and rendered bytes used in offers
+#   Clickwrap.policy     what the server offers and will accept
+#   Clickwrap.retention  how long each part of the evidence lives
+#
+# The browser never chooses any of it. Policy key, revision, document versions,
+# validity, subject binding, retention, and request-evidence fields are resolved
+# on the server and rechecked when the form comes back.
+# ==============================================================================
+
+# --- Documents ----------------------------------------------------------------
+#
+# A logical document (:terms) is separate from its immutable versions. Declaring
+# a version here does not publish it: `bin/rails clickwrap:publish` reads the
+# bytes once, digests them, and freezes a database snapshot. From then on the
+# snapshot is the evidence and the file is only where it came from.
+#
+# Every version has a LABEL YOU OWN, and the file that holds the words is where
+# that label belongs. A page with leading YAML front matter names its own
+# version, so there is no `version:` line here and no second copy of the label
+# to drift:
+#
+#   ---
+#   title: Terms of Service
+#   last_updated: <%= Date.today.iso8601 %>
+#   ---
+#
+# `last_updated:` is the usual key, because a page that tells readers when it
+# last changed already has one. `clickwrap_version:` wins when both are present,
+# which is how a same-day correction gets a fresh label while the date readers
+# see stays put. So changing a legal text is one edit in one file, then
+# `bin/rails clickwrap:publish` — and reusing a label over changed bytes is
+# refused rather than quietly accepted, which is what keeps the label and the
+# bytes describing the same document. A file with neither key and no explicit
+# `version:` fails the boot with a sentence; Clickwrap never invents a label.
+#
+# `version:` here stays the way to label a source that cannot carry front matter
+# — a PDF, an HTML fragment, or a `resolver:` whose bytes are only read at
+# publish time:
+#
+#   Clickwrap.document :handbook,
+#     version: "<%= Date.today.iso8601 %>",
+#     from: Rails.root.join("app/content/legal/handbook.pdf")
+#
+# Whether a change is material enough to require re-acceptance is your decision.
+# Clickwrap enforces the rule it is given; it does not decide materiality.
+
+<%- unless terms_document_names_its_own_version? -%>
+# <%= File.basename(terms_document_path) %> carries no version key yet. Move this label into the page's own
+# `last_updated:` front matter and delete the line, so the text names its version.
+<%- end -%>
+Clickwrap.document :terms,
+<%- unless terms_document_names_its_own_version? -%>
+  version: "<%= Date.today.iso8601 %>",
+<%- end -%>
+  from: Rails.root.join("<%= terms_document_path %>")
+
+<%- unless privacy_document_names_its_own_version? -%>
+# <%= File.basename(privacy_document_path) %> carries no version key yet. Move this label into the page's own
+# `last_updated:` front matter and delete the line, so the text names its version.
+<%- end -%>
+Clickwrap.document :privacy_notice,
+<%- unless privacy_document_names_its_own_version? -%>
+  version: "<%= Date.today.iso8601 %>",
+<%- end -%>
+  from: Rails.root.join("<%= privacy_document_path %>")
+
+# Several locales are several versions of the same logical document. Each is
+# published and digested separately, each names its own version in its own front
+# matter, and the receipt records which one the accepted server offer bound:
+#
+# Clickwrap.document :terms,
+#   locale: :es,
+#   effective_at: Time.utc(<%= Date.today.year %>, <%= Date.today.month %>, <%= Date.today.day %>),
+#   from: Rails.root.join("app/content/legal/terms.es.md")
+
+# --- Retention ----------------------------------------------------------------
+#
+# Clickwrap does not know how long your evidence should live and will not
+# pretend to. What it does is make a reviewed decision executable and auditable,
+# and keep two clocks apart:
+#
+#   the CORE EVENT   — what was agreed, by whom, to which version
+#   the ANNEX        — optional personal request evidence attached to it
+#
+# They are separate because they answer to different rules. Deleting the annex
+# removes the encrypted value and appends a disposition event; the agreement it
+# accompanied stays intact and still verifies. Nothing cascades: deleting an
+# actor account never silently destroys the record of what they agreed to.
+#
+# THE PERIODS BELOW ARE PLACEHOLDERS, NOT RECOMMENDATIONS. Replace them with
+# periods you have reviewed for your jurisdiction, your obligations, and your
+# disputes. `bin/rails clickwrap:retention:plan` shows what any of this would
+# delete before anything is deleted.
+
+Clickwrap.retention :ordinary_agreement_evidence do
+  retain_core_event_for 6.years
+
+  # These only matter if a policy or the initializer enables the field at all.
+  # A rule for something you never collect costs nothing and stops a future
+  # "we turned it on and forgot the clock".
+  delete_recorded_ip_address_after 90.days
+  delete_recorded_browser_user_agent_after 90.days
+  delete_recorded_ip_geolocation_after 90.days
+end
+
+# A regulated schedule that a duration cannot express — "the later of five years
+# after capture and three years after the subject closed" — names a host event
+# instead, and registers the calculation in config/initializers/clickwrap.rb:
+#
+# Clickwrap.retention :regulated_evidence do
+#   retain_core_event_until :regulated_evidence_retention_ends
+#   retain_recorded_ip_address_until :security_evidence_retention_ends
+#   retain_recorded_browser_user_agent_until :security_evidence_retention_ends
+#   retain_recorded_ip_geolocation_until :security_evidence_retention_ends
+# end
+
+# --- Policies -----------------------------------------------------------------
+#
+# A policy is a server-owned offer: exactly what the server will generate, and
+# exactly what it will accept back. One submitted policy produces one event and one
+# receipt, but each act inside it keeps its own kind, documents, wording,
+# answer, and lifecycle — "agreed to the Terms" and "acknowledged the Privacy
+# Notice" never flatten into one meaning.
+
+Clickwrap.policy :signup do
+  # `agree_to` means assent to contractual terms. The lifecycle it gets is the
+  # one assent needs: it stands until a new version supersedes it.
+  agree_to :terms
+
+  # `acknowledge`, NOT `agree_to`, and NOT `consent_to`.
+  #
+  # A privacy notice is information a person is entitled to receive. It is not a
+  # contract term they assent to, and it is not permission they grant: consent
+  # is one possible lawful basis among several, and most of what a notice
+  # describes usually rests on a different one. Presenting a notice as something
+  # to "agree" to misdescribes it, and treating the acknowledgment as blanket
+  # consent would let a checkbox stand in for permissions nobody asked for.
+  #
+  # So the receipt says what the application recorded: the server offered this
+  # exact notice version, and the person submitted an affirmative acknowledgment
+  # of receiving it. Anything you genuinely need consent for gets its own
+  # `consent_to`, its own purpose, its own unselected control, and its own
+  # withdrawal path — see the marketing example below.
+  acknowledge :privacy_notice
+
+  retain_with :ordinary_agreement_evidence
+end
+
+# --- An optional, separate marketing consent ----------------------------------
+#
+# Never bundled into signup, never preselected, and never required to create an
+# account. Leaving an optional control unselected creates no grant at all: the
+# receipt can show the option was offered and not taken, but silence is not
+# recorded as a refusal.
+#
+# Consent that cannot be withdrawn is not consent, so Clickwrap structurally
+# requires a withdrawal path. It still does not decide whether consent is the
+# right basis for what you are doing — that one is yours.
+#
+# Clickwrap.document :marketing_notice,
+#   from: Rails.root.join("app/content/legal/marketing.md")
+#
+# Clickwrap.policy :marketing_preferences do
+#   consent_to :product_updates,
+#     document: :marketing_notice,
+#     optional: true,
+#     withdrawal_path: "/settings/privacy"
+#
+#   retain_with :ordinary_agreement_evidence
+# end
+#
+# Withdrawal appends an event; it never edits or deletes the historical grant:
+#
+# Clickwrap.withdraw!(
+#   :product_updates,
+#   actor: current_user,
+#   http_request: request,
+#   because: "The user withdrew this purpose in privacy settings"
+# )