clickwrap 0.0.0 → 0.1.1

data/lib/clickwrap/models/application_record.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  # The abstract base class every model the gem ships inherits from. It plays
+  # the exact role an engine's `app/models/<engine>/application_record.rb`
+  # normally plays.
+  #
+  # It inherits from the HOST's `::ActiveRecord::Base`, NOT from the host's
+  # `::ApplicationRecord`. That matters here more than in most engines: evidence
+  # tables must behave identically in every host, and a default scope, a
+  # multitenancy filter, or a `before_save` bolted onto the app's base class
+  # could quietly change what gets recorded — or hide rows from an export that
+  # is supposed to be complete.
+  #
+  # The reference to `::ActiveRecord::Base` is fully qualified so Ruby's
+  # constant lookup can never re-bind it to a `Clickwrap::ActiveRecord`.
+  class ApplicationRecord < ::ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/lib/clickwrap/models/chain_head.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  # The head of one tamper-evident event chain.
+  #
+  # Chaining is off unless configured. The scope is tenant-and-policy: a
+  # tenanted installation gets one chain per (tenant, policy). An UNTENANTED
+  # installation's scope is the literal "global/<policy_key>" — one chain per
+  # policy across all actors, which means every capture of that policy
+  # serializes behind every other. Enable chaining on hot policies knowing
+  # that queue exists; per-actor scoping is future work, not current behavior.
+  #
+  # What a chain detects: an event rewritten or removed after the fact, as long
+  # as the head remains trustworthy. What it does not do: stop a party with full
+  # control of the application and database from rewriting both the events and
+  # the head. That is what the optional independent anchor adapter is for, and
+  # even then the claim is only as strong as the anchor.
+  class ChainHead < ApplicationRecord
+    self.table_name = "clickwrap_chain_heads"
+
+    validates :chain_scope, presence: true, uniqueness: true
+
+    # Appending is two phases, and it has to be.
+    #
+    # An event's digest is computed from its own body, which the event does not
+    # have until it is built — but its `previous_event_digest` has to be set
+    # before it is saved. So `reserve!` hands out the predecessor's digest and
+    # the next sequence number, the event is written with those, and `record!`
+    # then stores the digest the event actually ended up with.
+    #
+    # Doing it in one call is how a chain quietly ends up with a head full of
+    # nils: every link would point at a digest that had not been computed yet.
+
+    # Takes the next position in the chain. The row lock is what stops two
+    # concurrent captures in the same scope from reading the same predecessor
+    # and forking the chain.
+    def self.reserve!(chain_scope:)
+      # The first probe must be an ordinary read. On MySQL/InnoDB, two
+      # `SELECT ... FOR UPDATE` calls for the same absent unique key both take
+      # gap locks; when both then INSERT, InnoDB has to deadlock one of them.
+      # Let the unique INSERT choose the first writer, absorb the loser's
+      # duplicate in a savepoint, and only then take the row lock.
+      head = find_by(chain_scope: chain_scope)
+
+      unless head
+        begin
+          transaction(requires_new: true) { create!(chain_scope: chain_scope, chain_sequence: 0) }
+        rescue ActiveRecord::RecordNotUnique
+          # The savepoint absorbs PostgreSQL's aborted-statement state before
+          # the winning row is read and locked in the caller's transaction.
+        end
+      end
+
+      # Always re-read under the lock. A plain read above is only an existence
+      # probe and may carry a stale sequence; this is the value from which the
+      # next link is actually reserved.
+      head = lock.find_by!(chain_scope: chain_scope)
+
+      next_sequence = head.chain_sequence + 1
+      previous_digest = head.last_event_digest
+
+      head.update!(chain_sequence: next_sequence)
+
+      [previous_digest, next_sequence]
+    end
+
+    # Records the digest the event was actually written with, so the next event
+    # in this scope links to something real.
+    def self.record!(chain_scope:, event_id:, event_digest:)
+      head = lock.find_by(chain_scope: chain_scope)
+      return nil unless head
+
+      head.update!(last_event_id: event_id, last_event_digest: event_digest)
+      head
+    end
+
+    def to_s = "chain #{chain_scope} at #{chain_sequence}"
+  end
+end

data/lib/clickwrap/models/concerns/has_clickwraps.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  # What `has_clickwraps` mixes into the actor model.
+  #
+  # It adds the evidence proxy and the associations, and nothing else. Notably
+  # absent: any `dependent: :destroy`. Deleting an account must not silently
+  # erase the record of what that person agreed to — that is a retention
+  # decision, and it belongs to the host and its counsel, not to a foreign key.
+  #
+  # So the associations nullify the actor link on destroy and leave the stable
+  # pseudonymous `actor_reference` behind. The evidence remains queryable and
+  # verifiable; what disappears is the pointer to a row that no longer exists.
+  # A host that genuinely wants the evidence gone runs disposition through
+  # `Clickwrap::Privacy`, which records that it did.
+  module HasClickwraps
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :clickwrap_events,
+               class_name: "Clickwrap::Event",
+               as: :actor,
+               inverse_of: :actor,
+               dependent: :nullify
+
+      has_many :clickwrap_statement_states,
+               class_name: "Clickwrap::StatementState",
+               as: :actor,
+               inverse_of: :actor,
+               dependent: :nullify
+
+      has_many :clickwrap_presentations,
+               class_name: "Clickwrap::Presentation",
+               as: :actor,
+               inverse_of: :actor,
+               dependent: :nullify
+    end
+
+    # The everyday API: `user.clickwraps.agreed_to?(:terms)`.
+    def clickwraps
+      @clickwraps ||= Clickwrap::ActorProxy.new(self)
+    end
+
+    # How this record is referenced in evidence.
+    #
+    # Uses GlobalID when the host loads it and a stable class/id string in a
+    # minimal Rails host. Either string remains in the evidence after the row is
+    # gone — which is the situation this reference exists for. Override this
+    # method when the host has its own stable pseudonymous identifier scheme;
+    # `identify_actor_with` asks for it first, so no initializer change is needed.
+    def clickwrap_actor_reference
+      Clickwrap::Reference.record(self)
+    end
+  end
+end

data/lib/clickwrap/models/disposition_plan.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  # A reviewable plan to delete something.
+  #
+  # Deletion here is always two steps: plan, then apply. The plan is immutable,
+  # scoped, and expiring, and it is rechecked at apply time. A newly placed
+  # legal hold, a changed policy, a changed eligibility, or a stale plan stops
+  # the run rather than deleting a broader set than the person who reviewed it
+  # agreed to.
+  #
+  # The plan itself never decides whether an erasure request overrides a
+  # retention duty, a legal claim, or a hold. It shows what would happen.
+  class DispositionPlan < ApplicationRecord
+    self.table_name = "clickwrap_disposition_plans"
+    self.primary_key = "id"
+
+    KINDS = %w[retention actor_privacy].freeze
+    STATES = %w[open applying applied applied_with_errors superseded].freeze
+
+    DEFAULT_LIFETIME = 24.hours
+
+    validates :kind, inclusion: { in: KINDS }
+    validates :state, inclusion: { in: STATES }
+    validates :expires_at, presence: true
+    validates :plan_digest, presence: true
+
+    before_validation :assign_identifier, on: :create
+    before_validation :assign_plan_digest, on: :create
+    before_update :refuse_ordinary_update
+    before_destroy :refuse_destroy, prepend: true
+
+    scope :open_plans, -> { where(state: "open") }
+    scope :usable, ->(at = Clickwrap.now) { open_plans.where("expires_at > ?", at) }
+
+    def expired?(at = Clickwrap.now) = expires_at <= at
+    def applied? = state == "applied"
+
+    def usable?(at = Clickwrap.now)
+      state == "open" && !expired?(at)
+    end
+
+    # Raises with the specific reason this plan can no longer be applied, so an
+    # operator sees "the plan expired" or "this was already applied" rather than
+    # a generic refusal.
+    def ensure_usable!(at = Clickwrap.now)
+      raise DispositionPlanInvalid, "Disposition plan #{id} failed its immutable plan digest." unless digest_verified?
+      return true if usable?(at)
+
+      raise DispositionPlanInvalid,
+            case state
+            when "applied", "applied_with_errors" then "Disposition plan #{id} was already applied at #{applied_at}."
+            when "applying" then "Disposition plan #{id} is already being applied."
+            when "superseded" then "Disposition plan #{id} was superseded by a newer plan."
+            else "Disposition plan #{id} expired at #{expires_at}. Run the plan again and " \
+                 "review the current set before applying it."
+            end
+    end
+
+    def claim_for_application!(by_reference:, recover_if_stale_after: nil,
+                               because_recovery_is_needed: nil)
+      if by_reference.to_s.strip.empty?
+        raise DispositionPlanInvalid,
+              "Applying a disposition plan needs the stable reference of the operator doing it."
+      end
+
+      with_lock do
+        if state == "applying"
+          reclaim_stale_application!(
+            by_reference: by_reference,
+            stale_after: recover_if_stale_after,
+            because: because_recovery_is_needed
+          )
+        else
+          ensure_usable!
+          start_application_attempt!(by_reference)
+        end
+      end
+      self
+    end
+
+    def finish_application!(outcome_summary:, had_errors: false)
+      with_lock do
+        unless state == "applying"
+          raise DispositionPlanInvalid, "Disposition plan #{id} is not currently being applied."
+        end
+
+        update_columns(
+          state: had_errors ? "applied_with_errors" : "applied",
+          applied_at: Clickwrap.now,
+          application_outcome: outcome_summary
+        )
+      end
+      self
+    end
+
+    def supersede!(because:, by:)
+      raise DispositionPlanInvalid, "Superseding a plan needs a `because:`." if because.to_s.strip.empty?
+
+      with_lock do
+        ensure_usable!
+        update_columns(
+          state: "superseded",
+          superseded_at: Clickwrap.now,
+          superseded_by_reference: Reference.actor(by),
+          superseded_reason: because
+        )
+      end
+      self
+    end
+
+    def digest_verified?
+      Digest.secure_compare?(plan_digest.to_s, compute_plan_digest)
+    end
+
+    def to_s = "#{kind} disposition plan #{id} (#{item_count} items)"
+
+    private
+
+    def assign_identifier
+      self.id ||= Identifier.generate
+      self.expires_at ||= Clickwrap.now + DEFAULT_LIFETIME
+      self.created_at ||= Clickwrap.now
+      self.updated_at ||= created_at
+    end
+
+    def assign_plan_digest
+      self.plan_digest ||= compute_plan_digest
+    end
+
+    def compute_plan_digest
+      Digest.digest_canonical({
+                                "id" => id,
+                                "kind" => kind,
+                                "scope" => disposition_scope,
+                                "summary" => summary,
+                                "item_count" => item_count,
+                                "created_by_reference" => created_by_reference,
+                                "reason" => reason,
+                                "expires_at" => Receipt.format_time(expires_at),
+                                "created_at" => Receipt.format_time(created_at)
+                              })
+    end
+
+    def start_application_attempt!(by_reference)
+      started_at = Clickwrap.now
+      update_columns(
+        state: "applying",
+        application_started_at: started_at,
+        applied_by_reference: by_reference.to_s,
+        application_attempt_count: application_attempt_count.to_i + 1,
+        updated_at: started_at
+      )
+    end
+
+    def reclaim_stale_application!(by_reference:, stale_after:, because:)
+      raise DispositionPlanInvalid, "Disposition plan #{id} expired at #{expires_at}." if expired?
+
+      unless stale_after.respond_to?(:positive?) && stale_after.positive?
+        raise DispositionPlanInvalid,
+              "Disposition plan #{id} is already being applied. Recovering it requires " \
+              "recover_application_if_stale_for with a positive duration."
+      end
+
+      cutoff = Clickwrap.now - stale_after
+      if application_started_at.present? && application_started_at > cutoff
+        raise DispositionPlanInvalid,
+              "Disposition plan #{id} has only been applying since #{application_started_at}; " \
+              "it is not older than the #{stale_after.inspect} recovery threshold."
+      end
+
+      if because.to_s.strip.empty?
+        raise DispositionPlanInvalid,
+              "Recovering a stale disposition application needs " \
+              "because_recovery_is_needed in plain English."
+      end
+
+      recovered_at = Clickwrap.now
+      recoveries = Array(application_recoveries).dup
+      recoveries << {
+        "previous_application_started_at" => Receipt.format_time(application_started_at),
+        "previous_applied_by_reference" => applied_by_reference,
+        "recovered_at" => Receipt.format_time(recovered_at),
+        "recovered_by_reference" => by_reference.to_s,
+        "reason" => because.to_s.strip
+      }.compact
+
+      update_columns(
+        application_started_at: recovered_at,
+        applied_by_reference: by_reference.to_s,
+        application_attempt_count: application_attempt_count.to_i + 1,
+        application_recoveries: recoveries,
+        updated_at: recovered_at
+      )
+    end
+
+    def refuse_ordinary_update
+      raise ImmutableEvidenceError,
+            "Disposition plans refuse ordinary updates. Use claim_for_application!, " \
+            "finish_application!, or supersede!(because:, by:) for a named transition."
+    end
+
+    def refuse_destroy
+      raise ImmutableEvidenceError,
+            "Disposition plans cannot be destroyed; their reviewed scope and named transitions must remain."
+    end
+  end
+end

data/lib/clickwrap/models/document.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  # A logical document — `:terms`, `:privacy_notice` — separate from the
+  # immutable versions that carry its actual bytes.
+  class Document < ApplicationRecord
+    self.table_name = "clickwrap_documents"
+
+    has_many :versions,
+             class_name: "Clickwrap::DocumentVersion",
+             foreign_key: :document_id,
+             inverse_of: :document,
+             dependent: :restrict_with_error
+
+    validates :document_key, presence: true, uniqueness: { scope: :tenant_key }
+
+    scope :for_tenant, ->(tenant_key) { where(tenant_key: tenant_key.presence) }
+
+    # The version a policy should present right now for a locale: published,
+    # already effective, and not retired. A version scheduled for the future is
+    # deliberately not presentable yet — that is what `effective_at` is for.
+    # The version to present right now: published, already effective, and not
+    # retired. A version scheduled for the future is deliberately not
+    # presentable yet — that is what `effective_at` is for.
+    #
+    # The ordering is by effective time, then by publication time as a
+    # tie-breaker for two versions scheduled for the same instant. Publishing
+    # always writes an `effective_at`, so no NULL reaches this comparison and
+    # PostgreSQL and SQLite agree about which document the server offered.
+    def current_version(locale: I18n.locale, at: Clickwrap.now)
+      versions
+        .published
+        .effective_at_or_before(at)
+        .not_retired_at(at)
+        .for_locale(locale)
+        .order(effective_at: :desc, published_at: :desc, created_at: :desc)
+        .first
+    end
+
+    def version(label, locale: I18n.locale)
+      versions.for_locale(locale).find_by(version_label: label)
+    end
+
+    def to_s = document_key
+  end
+end

data/lib/clickwrap/models/document_version.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  # An immutable published version of a document.
+  #
+  # Once `published_at` is set, the bytes and their digest are frozen. There is
+  # no supported way to edit them: a change is a new version, and the old row
+  # stays exactly as it was because a receipt from last year points at it.
+  #
+  # `content_digest` covers the original source bytes. `rendered_content_digest`
+  # covers the representation actually offered when a source format was
+  # transformed for display. Keeping both is what lets a receipt distinguish
+  # "this Markdown file existed" from "the server offered this rendered HTML"
+  # instead of letting one claim borrow the other's credibility.
+  class DocumentVersion < ApplicationRecord
+    self.table_name = "clickwrap_document_versions"
+
+    STORAGE_BACKENDS = %w[database active_storage resolver].freeze
+
+    belongs_to :document, class_name: "Clickwrap::Document", inverse_of: :versions
+
+    has_many :event_documents,
+             class_name: "Clickwrap::EventDocument",
+             foreign_key: :document_version_id,
+             inverse_of: :document_version,
+             dependent: :restrict_with_error
+
+    validates :version_label, :locale, :media_type, :content_digest, presence: true
+    validates :version_label, uniqueness: { scope: %i[document_id locale] }
+    validates :storage_backend, inclusion: { in: STORAGE_BACKENDS }
+
+    scope :published, -> { where.not(published_at: nil) }
+    scope :for_locale, ->(locale) { where(locale: locale.to_s) }
+    scope :effective_at_or_before, ->(moment) { where(effective_at: ..moment).or(where(effective_at: nil)) }
+    scope :not_retired_at, ->(moment) { where(retired_at: nil).or(where(retired_at: moment...)) }
+
+    # Publishing freezes content. Editing a published version is refused here
+    # rather than in a code review, because the whole promise of this table is
+    # that its rows do not change.
+    before_update :refuse_to_change_published_version
+    before_destroy :refuse_to_destroy_published_version, prepend: true
+
+    def published? = published_at.present?
+    def retired? = retired_at.present?
+
+    def presentable_at?(moment = Clickwrap.now)
+      published? &&
+        (effective_at.nil? || effective_at <= moment) &&
+        (retired_at.nil? || retired_at > moment)
+    end
+
+    # Reads the bytes for this version, from wherever the storage adapter put
+    # them, and verifies them against the recorded digest before returning.
+    # Verification is not optional: silently returning bytes that no longer
+    # match would turn this method into a way to launder edited content into an
+    # export.
+    def content_bytes
+      bytes = read_bytes
+
+      unless Digest.matches?(bytes, "#{content_digest_algorithm}:#{bare_digest(content_digest)}")
+        raise DocumentDigestMismatchError,
+              "The stored bytes for document version #{self} no longer match the digest " \
+              "recorded when it was published. The evidence that references this version " \
+              "cannot be reproduced until that is explained. Recorded: #{content_digest}."
+      end
+
+      bytes
+    end
+
+    def verify_content_digest
+      content_bytes
+      true
+    rescue DocumentDigestMismatchError, DocumentNotPublishedError
+      false
+    end
+
+    def rendered_bytes
+      return content_bytes if rendered_content.nil?
+
+      unless rendered_content_digest.present? && Digest.matches?(rendered_content, rendered_content_digest)
+        raise DocumentDigestMismatchError,
+              "The rendered bytes for document version #{self} no longer match the digest " \
+              "recorded when they were published."
+      end
+
+      rendered_content
+    end
+
+    def verify_rendered_content_digest
+      rendered_bytes
+      true
+    rescue DocumentDigestMismatchError, DocumentNotPublishedError
+      false
+    end
+
+    def retire!(because:, at: Clickwrap.now)
+      raise DocumentVersionConflictError, "Retiring a document version needs a `because:`." if because.to_s.strip.empty?
+      raise DocumentVersionConflictError, "Document version #{self} is already retired." if retired?
+
+      update_columns(retired_at: at, retired_reason: because)
+      self
+    end
+
+    def prefixed_content_digest = content_digest
+
+    def to_s = "#{document&.document_key} #{version_label} (#{locale})"
+
+    private
+
+    def read_bytes
+      case storage_backend
+      when "database" then content.to_s
+      when "resolver" then read_from_resolver
+      when "active_storage" then read_from_active_storage
+      end
+    end
+
+    def read_from_resolver
+      resolver = Clickwrap.config.document_resolver
+
+      unless resolver
+        raise ConfigurationError,
+              "Document version #{self} is stored through a resolver, but no " \
+              "`document_resolver` is configured."
+      end
+
+      resolver.call(self).to_s
+    end
+
+    def read_from_active_storage
+      unless defined?(::ActiveStorage)
+        raise ConfigurationError,
+              "Document version #{self} is stored in Active Storage, but Active Storage is " \
+              "not loaded in this application."
+      end
+
+      ::ActiveStorage::Blob.find_signed!(storage_locator).download
+    end
+
+    def bare_digest(value)
+      value.to_s.split(":").last
+    end
+
+    def refuse_to_change_published_version
+      return unless published_at_was.present?
+
+      changed_frozen = changed - %w[retired_at retired_reason]
+      return if changed_frozen.empty? && !will_save_change_to_retired_at? && !will_save_change_to_retired_reason?
+
+      raise DocumentVersionConflictError,
+            "Document version #{self} has frozen published content. Use `retire!(because:)` to " \
+            "record the named retirement metadata and stop future presentation, or publish a new " \
+            "version; ordinary updates are refused."
+    end
+
+    def refuse_to_destroy_published_version
+      return unless published?
+
+      raise DocumentVersionConflictError,
+            "Published document version #{self} cannot be destroyed because receipts may cite it."
+    end
+  end
+end