clickwrap 0.0.0 → 0.1.0

data/lib/clickwrap/pending_receipt.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  # What `capture_and!` yields to the protected action, before anything has
+  # committed.
+  #
+  # It carries the one thing the domain row legitimately needs — a stable
+  # `event_id` to reference — and deliberately withholds everything else.
+  # Export and verification are unavailable because there is nothing yet to
+  # export or verify: the transaction may still roll back, and an object that
+  # happily serialized itself into a receipt at this point would be describing
+  # evidence that might never exist.
+  #
+  # If the transaction does roll back, this object becomes invalid rather than
+  # continuing to look like a committed record.
+  class PendingReceipt
+    attr_reader :event
+
+    def initialize(event, wait_for_outer_transaction: false)
+      @event = event
+      @wait_for_outer_transaction = wait_for_outer_transaction
+      @committed = false
+      @rolled_back = false
+    end
+
+    def event_id = event.id
+    def policy_key = event.policy_key
+    def recorded_at_by_server = event.recorded_at_by_server
+    def actor_reference = event.actor_reference
+    def subject_fingerprint = event.subject_fingerprint
+
+    def statements
+      event.statements.to_h { |statement| [statement.statement_key, statement.action] }
+    end
+
+    # Read the exact answer that this pending event accepted for one statement.
+    # Protected domain work often needs it before commit: for example, an
+    # optional consent can enable one preference while an unselected consent
+    # must leave that preference disabled. Reaching through
+    # `pending_receipt.event.statements` at every call site is both noisy and
+    # dangerously easy to get wrong (an offered-but-unselected option is not a
+    # grant).
+    #
+    # Unknown statement keys fail loudly so a typo cannot silently turn into a
+    # false boolean at a consequential boundary.
+    def answer_for(statement_key)
+      statement_for(statement_key)&.answer
+    end
+
+    def answered?(statement_key)
+      statement_for(statement_key)&.answered? || false
+    end
+
+    # Consent-oriented convenience predicates. They inspect BOTH the recorded
+    # action and whether the person actually answered, so these methods never
+    # reinterpret silence as a grant or decline.
+    def granted?(statement_key)
+      answered?(statement_key) && statement_for(statement_key).action == "granted"
+    end
+
+    def declined?(statement_key)
+      answered?(statement_key) && statement_for(statement_key).action == "declined"
+    end
+
+    def committed?
+      refresh_commit_state_if_possible!
+      @committed
+    end
+
+    def rolled_back? = @rolled_back
+
+    # Registers work that is only truthful after the real outer transaction
+    # commits. Clickwrap's controller adapters use this to clear a registration
+    # flow id without clearing it after a savepoint that later rolls back.
+    def when_durably_committed(&callback)
+      raise ArgumentError, "when_durably_committed needs a block" unless callback
+
+      if committed?
+        run_durable_commit_callback(callback)
+      elsif !rolled_back?
+        (@durable_commit_callbacks ||= []) << callback
+      end
+
+      self
+    end
+
+    # Once the real outermost transaction commits, this same object becomes a
+    # truthful handle to the finalized receipt. This matters when Clickwrap
+    # joins a host-owned transaction: the capture method has to return before
+    # that outer transaction does, so returning a Receipt there would claim a
+    # commit that has not happened yet.
+    def receipt
+      refuse(:receipt) unless committed?
+
+      Receipt.find(event_id)
+    end
+
+    def to_canonical_json = refuse(:to_canonical_json)
+    def to_html = refuse(:to_html)
+    def verify = refuse(:verify)
+    def export(*) = refuse(:export)
+
+    def inspect
+      state = if committed? then "committed"
+              elsif rolled_back? then "rolled back"
+              else "uncommitted"
+              end
+
+      "#<Clickwrap::PendingReceipt #{event_id} (#{state})>"
+    end
+
+    def to_s = event_id
+
+    # Internal transaction callbacks. Public only because the Event callback
+    # invokes them; downstream code gains no authority from calling them—the
+    # receipt lookup still requires the event to exist after commit.
+    def mark_committed!
+      # A non-joinable outer transaction (most visibly Rails' transactional
+      # test wrapper) can make a record-level after_commit fire at a savepoint.
+      # That is not durable finality. Leave the handle pending until no database
+      # transaction is open and the finalized row can be observed afresh.
+      return self if @wait_for_outer_transaction && ::ActiveRecord::Base.connection.transaction_open?
+
+      return self if @committed
+
+      @committed = true
+      @rolled_back = false
+      run_durable_commit_callbacks
+      self
+    end
+
+    def mark_rolled_back!
+      @committed = false
+      @rolled_back = true
+      @durable_commit_callbacks = []
+      self
+    end
+
+    private
+
+    def statement_for(statement_key)
+      # The policy lookup distinguishes an expected optional statement (which
+      # legitimately has no event row when left unselected) from a misspelled
+      # key. The former returns nil/false through the public helpers; the latter
+      # raises with the policy builder's precise error.
+      Clickwrap.policy!(policy_key).statement!(statement_key)
+      event.statement(statement_key)
+    end
+
+    def refresh_commit_state_if_possible!
+      return if @committed || @rolled_back || !@wait_for_outer_transaction
+      return if ::ActiveRecord::Base.connection.transaction_open?
+
+      mark_committed! if Event.where(id: event_id).where.not(event_digest: nil).exists?
+    end
+
+    def run_durable_commit_callbacks
+      callbacks = Array(@durable_commit_callbacks)
+      @durable_commit_callbacks = []
+      callbacks.each { |callback| run_durable_commit_callback(callback) }
+    end
+
+    def run_durable_commit_callback(callback)
+      callback.call
+    rescue StandardError => error
+      Clickwrap.report_after_commit_failure(error, event)
+    end
+
+    def refuse(method_name)
+      status = rolled_back? ? "rolled back" : "has not committed yet"
+
+      raise ReceiptNotCommitted,
+            "##{method_name} is not available because this pending receipt #{status}. There is " \
+            "no durable evidence to read until the real outermost database transaction commits."
+    end
+  end
+end

data/lib/clickwrap/policy.rb

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  # A compiled, frozen policy: what the server will present and what it will
+  # accept back.
+  #
+  # The browser may answer a policy. It may never choose one. Policy key,
+  # revision, document versions, validity, subject binding, retention, and
+  # request-evidence fields are all resolved server-side and rechecked at
+  # submit, because every one of them is a security decision and a form field
+  # is not a safe place to keep one.
+  #
+  # A policy's `revision` is the digest of its compiled snapshot. Publishing
+  # freezes that snapshot in the database the first time the policy is
+  # presented or captured, so a receipt written today still explains itself
+  # after the Ruby source has moved on. The digest covers declared structure and
+  # copy; host lambdas (subject fingerprints, protected-outcome recorders) are
+  # recorded as present rather than serialized, since their bodies cannot be
+  # canonicalized. That boundary is stated in the receipt rather than papered
+  # over.
+  class Policy
+    attr_reader :key, :statements, :retention_class_key, :request_evidence, :persist_presentations_for,
+                :persist_presentations_because, :capture_channels, :locales, :authority_rule,
+                :tenant_scope, :options, :snapshot, :revision
+
+    def initialize(key:, statements:, retention_class_key: nil, request_evidence: nil,
+                   persist_presentations_for: nil, persist_presentations_because: nil,
+                   capture_channels: nil, locales: nil, tenant_scope: "optional",
+                   authority_rule: nil, options: {})
+      @key = key.to_s
+      @statements = statements.freeze
+      @retention_class_key = retention_class_key&.to_s
+      @request_evidence = request_evidence || RequestEvidencePolicy.new(policy_key: @key)
+      @persist_presentations_for = persist_presentations_for
+      @persist_presentations_because = persist_presentations_because
+      @capture_channels = (capture_channels || Vocabulary::CAPTURE_CHANNELS).map(&:to_s).freeze
+      @locales = locales&.map(&:to_s)&.freeze
+      @tenant_scope = tenant_scope.to_s
+      @authority_rule = authority_rule
+      @options = options.freeze
+
+      validate!
+      @snapshot = build_snapshot.freeze
+      @revision = Digest.digest_canonical(@snapshot).freeze
+      freeze
+    end
+
+    def statement(statement_key)
+      statements.find { |statement| statement.key == statement_key.to_s }
+    end
+
+    def statement!(statement_key)
+      statement(statement_key) || raise(
+        UnknownStatementError,
+        "Policy #{key} has no statement #{statement_key.inspect}. It declares: " \
+        "#{statements.map(&:key).join(", ")}."
+      )
+    end
+
+    def required_statements = statements.select(&:required?)
+    def optional_statements = statements.select(&:optional?)
+    def document_keys = statements.flat_map(&:document_keys).uniq
+    def kinds = statements.map(&:kind).uniq
+
+    def one_time_statements = statements.select(&:one_time?)
+    def subject_bound? = statements.any?(&:subject_bound?)
+    def consent_statements = statements.select { |statement| statement.kind == "consent" }
+    def authorization_statements = statements.select { |statement| statement.kind == "authorization" }
+    def protected_outcome_statements = statements.select(&:record_protected_outcome_with)
+    def protected_outcome_statement = protected_outcome_statements.first
+    def records_protected_outcome? = protected_outcome_statement.present?
+
+    def persist_presentations? = !persist_presentations_for.nil?
+
+    # Whether a system exemption may stand in for a human action under this
+    # policy. It is off unless the policy says otherwise, and an exemption never
+    # satisfies `agreed_to?` or any other human-action predicate even when it
+    # is permitted — it answers `exempted_from?` instead.
+    def permits_exemptions? = options.fetch(:permit_exemptions, false) == true
+
+    def permits_capture_channel?(channel) = capture_channels.include?(channel.to_s)
+
+    def permits_locale?(locale)
+      locales.nil? || locales.include?(locale.to_s)
+    end
+
+    def tenant_not_applicable? = tenant_scope == "not_applicable"
+    def tenant_required? = tenant_scope == "required"
+    def tenant_optional? = tenant_scope == "optional"
+
+    # Resolves ambient controller context according to this policy. Personal
+    # evidence deliberately discards a current organization; tenant-required
+    # evidence fails before rendering if the host cannot supply one.
+    def tenant_from_controller(candidate)
+      return nil if tenant_not_applicable?
+
+      validate_tenant!(candidate)
+      candidate
+    end
+
+    # Direct service callers own their arguments, so an incompatible explicit
+    # value is rejected instead of silently rewritten.
+    def validate_tenant!(tenant)
+      if tenant_not_applicable? && tenant.present?
+        raise DefinitionError,
+              "Policy #{key} says `tenant_is :not_applicable`, but this call supplied a tenant. " \
+              "Remove `tenant:`; personal evidence must not change identity when the actor joins " \
+              "or switches organizations."
+      end
+
+      if tenant_required? && tenant.nil?
+        raise DefinitionError,
+              "Policy #{key} says `tenant_is :required`, but this call supplied no tenant. Pass " \
+              "the server-resolved tenant to presentation, capture, and verification."
+      end
+
+      true
+    end
+
+    # Delegation, guardianship, service-account action, and impersonation are
+    # rejected unless the policy opts in and the host authority adapter agrees.
+    # When permitted, the receipt keeps the authenticated principal, asserted
+    # actor, and represented party as separate facts; Clickwrap does not decide
+    # whether that authority is sufficient.
+    def permits_acting_for? = options.fetch(:permit_acting_for, false) == true
+
+    def permits_acting_for_party?(represented_party)
+      permits_acting_for? && authority_rule&.permits?(represented_party)
+    end
+
+    def to_s = "Clickwrap policy #{key} (#{revision})"
+
+    private
+
+    def build_snapshot
+      {
+        "schema" => Clickwrap::CANONICAL_SCHEMA_VERSION,
+        "policy" => key,
+        "statements" => statements.map(&:to_snapshot),
+        "retention_class" => retention_class_key,
+        "request_evidence" => request_evidence.to_snapshot,
+        "persist_presentations_for_seconds" => persist_presentations_for&.to_i,
+        "persist_presentations_because" => persist_presentations_because,
+        "capture_channels" => capture_channels,
+        "locales" => locales,
+        "tenant_scope" => tenant_scope,
+        "permit_exemptions" => permits_exemptions?,
+        "permit_acting_for" => permits_acting_for?,
+        "represented_party_authority" => authority_rule&.to_snapshot
+      }.compact
+    end
+
+    def validate!
+      validate_statements_present!
+      validate_unique_statement_keys!
+      validate_one_protected_outcome_recorder!
+      validate_prerequisites!
+      validate_retention!
+      validate_persisted_presentations!
+      validate_capture_channels!
+      validate_tenant_scope!
+      validate_authority_rule!
+    end
+
+    def validate_authority_rule!
+      if permits_acting_for? && authority_rule.nil?
+        raise DefinitionError,
+              "Policy #{key} permits represented-party action without a compiled authority rule."
+      end
+
+      return unless authority_rule
+
+      unless permits_acting_for?
+        raise DefinitionError,
+              "Policy #{key} has a represented-party authority rule but does not permit acting for another party."
+      end
+
+      return if authority_rule.adapter_name == "host"
+      return if Clickwrap.config.represented_party_authority_adapter(authority_rule.adapter_name)
+
+      raise DefinitionError,
+            "Policy #{key} uses represented-party authority adapter " \
+            "#{authority_rule.adapter_name.inspect}, but it is not registered. Register it with " \
+            "`config.register_represented_party_authority`. Registered adapters: " \
+            "#{Clickwrap.config.represented_party_authority_adapter_names.join(", ").presence || "(none)"}."
+    end
+
+    def validate_statements_present!
+      return unless statements.empty?
+
+      raise DefinitionError,
+            "Policy #{key} declares no statements. A policy that asks for nothing records " \
+            "nothing; add at least one `agree_to`, `acknowledge`, `consent_to`, `declare`, " \
+            "`attest`, or `authorize`."
+    end
+
+    def validate_unique_statement_keys!
+      duplicates = statements.map(&:key).tally.select { |_, count| count > 1 }.keys
+      return if duplicates.empty?
+
+      raise DefinitionError,
+            "Policy #{key} declares #{duplicates.join(", ")} more than once. Two statements " \
+            "with the same key would produce evidence nobody can tell apart."
+    end
+
+    def validate_one_protected_outcome_recorder!
+      return if protected_outcome_statements.length <= 1
+
+      raise DefinitionError,
+            "Policy #{key} configures protected-outcome recorders on " \
+            "#{protected_outcome_statements.map(&:key).join(", ")}. One protected action has one " \
+            "result snapshot; put `record_protected_outcome_with:` on exactly one statement."
+    end
+
+    # `requires:` says an authorization is only good when named statements were
+    # made in the same submission, and in order. A prerequisite that does not
+    # exist, or that comes later on the page, is a policy bug rather than a
+    # runtime surprise.
+    def validate_prerequisites!
+      statements.each do |statement|
+        statement.requires.each do |prerequisite_key|
+          prerequisite = statement(prerequisite_key)
+
+          unless prerequisite
+            raise DefinitionError,
+                  "Statement #{statement.key} in policy #{key} requires #{prerequisite_key}, " \
+                  "which this policy does not declare."
+          end
+
+          next if prerequisite.ordinal < statement.ordinal
+
+          raise DefinitionError,
+                "Statement #{statement.key} in policy #{key} requires #{prerequisite_key}, " \
+                "but that statement is declared after it. Prerequisites must come first, " \
+                "because that is the order the person will be asked."
+        end
+      end
+    end
+
+    def validate_retention!
+      return if retention_class_key
+
+      raise DefinitionError,
+            "Policy #{key} has no retention class. Add `retain_with :some_class` and define " \
+            "that class with `Clickwrap.retention`. Clickwrap will not default your evidence " \
+            "to forever, and it will not pick a period for you."
+    end
+
+    def validate_persisted_presentations!
+      return unless persist_presentations?
+
+      if persist_presentations_because.to_s.strip.empty?
+        raise DefinitionError,
+              "Policy #{key} persists presentations before submission but gives no `because:`. " \
+              "Storing every render is more personal data than the default path; say why."
+      end
+
+      return if persist_presentations_for.to_i.positive?
+
+      raise DefinitionError,
+            "Policy #{key} persists presentations for #{persist_presentations_for.inspect}, " \
+            "which is not a retention period."
+    end
+
+    def validate_capture_channels!
+      unknown = capture_channels - Vocabulary::CAPTURE_CHANNELS
+      return if unknown.empty?
+
+      raise DefinitionError,
+            "Policy #{key} allows unknown capture channels #{unknown.join(", ")}. " \
+            "Choose from: #{Vocabulary::CAPTURE_CHANNELS.join(", ")}."
+    end
+
+    def validate_tenant_scope!
+      return if %w[not_applicable optional required].include?(tenant_scope)
+
+      raise DefinitionError,
+            "Policy #{key} says `tenant_is #{tenant_scope.inspect}`. Choose `:not_applicable`, " \
+            "`:optional`, or `:required`; Clickwrap will not guess whether ambient tenant context " \
+            "belongs in an evidence identity."
+    end
+  end
+end

data/lib/clickwrap/presentation_manifest.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  # The canonical description of one offer: which policy revision, which
+  # document versions and digests, the exact sentences and link labels, the
+  # choice structure, the call to action, who it was issued to, and when it
+  # stops being valid.
+  #
+  # This exists because "the database says version 3" is a weak claim. It says
+  # what the row contains now, not what the server offered then. A manifest is
+  # generated by the server at render, signed, and verified again at submit
+  # against the current immutable rows — so a deploy between GET and POST can
+  # never cause the server to record a version the person was not offered.
+  #
+  # What it proves is bounded, and the receipt says so: the server generated and
+  # accepted this particular offer. It does not prove the person read the
+  # document, understood it, saw particular pixels, or received an interface
+  # that any given jurisdiction would consider adequate.
+  class PresentationManifest
+    SIGNING_PURPOSE = "clickwrap/presentation"
+
+    attr_reader :attributes
+
+    def initialize(attributes)
+      @attributes = deep_stringify(attributes).freeze
+      # Computed here rather than memoized on first use: the object is frozen
+      # below, and a manifest that could still change after construction is not
+      # a manifest anything should be bound to.
+      @digest = Digest.digest_canonical(
+        @attributes, algorithm: Clickwrap.config.digest_canonical_receipts_with.to_s
+      ).freeze
+      freeze
+    end
+
+    class << self
+      def build(policy:, revision_digest:, statements:, submit_button_text:, locale:,
+                actor_reference: nil, actor_type: nil, tenant_key: nil, subject_key: nil,
+                subject_fingerprint: nil, registration_flow_id: nil,
+                prospective_actor_type: nil, represented_party_reference: nil,
+                represented_party_type: nil, authority_rule: nil,
+                represented_party_creation_flow_id: nil,
+                represented_party_will_be_created_by_protected_action: false,
+                authority_at_presentation: nil, combined_control: nil,
+                capture_channel: "web_browser", issued_at: nil, expires_at: nil, nonce: nil)
+        issued_at ||= Clickwrap.now
+        expires_at ||= issued_at + Clickwrap.config.presentation_valid_for
+
+        attributes = {
+          "schema" => Clickwrap::CANONICAL_SCHEMA_VERSION,
+          "policy" => { "key" => policy.key, "revision" => revision_digest },
+          "statements" => statements,
+          "submit_button_text" => submit_button_text,
+          "locale" => locale.to_s,
+          "actor" => { "reference" => actor_reference, "type" => actor_type }.compact.presence,
+          "registration_flow_id" => registration_flow_id,
+          "prospective_actor_type" => prospective_actor_type,
+          "represented_party" => {
+            "reference" => represented_party_reference,
+            "type" => represented_party_type,
+            "authority_rule" => authority_rule,
+            "creation_flow_id" => represented_party_creation_flow_id,
+            "will_be_created_by_protected_action" =>
+              represented_party_will_be_created_by_protected_action == true,
+            "authority_at_presentation" => authority_at_presentation
+          }.compact.presence,
+          "tenant_key" => tenant_key,
+          "subject" => { "reference" => subject_key, "fingerprint" => subject_fingerprint }.compact.presence,
+          "capture_channel" => capture_channel.to_s,
+          "issued_at" => Receipt.format_time(issued_at),
+          "expires_at" => Receipt.format_time(expires_at),
+          "nonce" => nonce || SecureRandom.uuid,
+          "gem_version" => Clickwrap::VERSION,
+          "application_version" => Clickwrap.config.resolved_application_version,
+          "template_version" => Clickwrap.config.resolved_template_version
+        }
+
+        # Only present when the offer really was one control, so a manifest
+        # from an itemized presentation is byte-identical to the ones this gem
+        # has always written.
+        attributes["combined_control"] = combined_control if combined_control
+
+        new(attributes)
+      end
+
+      # Reads a token back into a manifest. Every failure here is the same kind
+      # of failure — the browser handed us something we did not sign, or signed
+      # too long ago — so they all raise PresentationInvalid rather than leaking
+      # which specific check tripped.
+      def from_token(token)
+        raise PresentationInvalid, "No presentation token was submitted" if token.blank?
+
+        payload = verifier.verified(token, purpose: SIGNING_PURPOSE)
+
+        raise PresentationInvalid, "The presentation token could not be verified" if payload.nil?
+
+        new(payload)
+      rescue ActiveSupport::MessageVerifier::InvalidSignature
+        raise PresentationInvalid, "The presentation token could not be verified"
+      end
+
+      def verifier
+        @verifier ||= build_verifier
+      end
+
+      def reset_verifier!
+        @verifier = nil
+      end
+
+      private
+
+      def build_verifier
+        secret =
+          if defined?(::Rails) && ::Rails.application
+            ::Rails.application.key_generator.generate_key("clickwrap/presentation-manifest", 32)
+          else
+            ENV.fetch("CLICKWRAP_PRESENTATION_SECRET") do
+              raise ConfigurationError,
+                    "Clickwrap needs a signing secret for presentation tokens. Inside Rails it " \
+                    "derives one from secret_key_base; outside Rails, set " \
+                    "CLICKWRAP_PRESENTATION_SECRET."
+            end
+          end
+
+        ActiveSupport::MessageVerifier.new(secret, digest: "SHA256", serializer: JSON)
+      end
+    end
+
+    def [](key) = attributes[key.to_s]
+
+    def policy_key = attributes.dig("policy", "key")
+    def revision_digest = attributes.dig("policy", "revision")
+    def statements = attributes["statements"] || []
+    def submit_button_text = attributes["submit_button_text"]
+    def locale = attributes["locale"]
+    def nonce = attributes["nonce"]
+    def actor_reference = attributes.dig("actor", "reference")
+    def registration_flow_id = attributes["registration_flow_id"]
+    def prospective_actor_type = attributes["prospective_actor_type"]
+    def represented_party_reference = attributes.dig("represented_party", "reference")
+    def represented_party_type = attributes.dig("represented_party", "type")
+    def authority_rule = attributes.dig("represented_party", "authority_rule")
+    def represented_party_creation_flow_id = attributes.dig("represented_party", "creation_flow_id")
+
+    def represented_party_will_be_created_by_protected_action?
+      attributes.dig("represented_party", "will_be_created_by_protected_action") == true
+    end
+
+    def authority_at_presentation = attributes.dig("represented_party", "authority_at_presentation")
+    def tenant_key = attributes["tenant_key"]
+    def subject_key = attributes.dig("subject", "reference")
+    def subject_fingerprint = attributes.dig("subject", "fingerprint")
+    def capture_channel = attributes["capture_channel"]
+    def issued_at = parse_time(attributes["issued_at"])
+    def expires_at = parse_time(attributes["expires_at"])
+
+    def statement(key)
+      statements.find { |statement| statement["key"] == key.to_s }
+    end
+
+    # The one control this offer rendered, and the statements it answered.
+    #
+    # This is where the substitution defense lives for a composed presentation.
+    # The per-statement assertions below say what each act was; this says what
+    # the person actually READ — one sentence, composed from those acts, with
+    # the document links inside it — and which keys the single answer covers.
+    # Nil whenever the offer was itemized.
+    def combined_control = attributes["combined_control"]
+    def combined_sentence = combined_control&.fetch("sentence", nil)
+    def combined_statement_keys = Array(combined_control&.fetch("covers", nil))
+
+    # The statement key the single control is submitted under. Every covered
+    # key takes its answer from this one, server-side.
+    def combined_answered_as = combined_control&.fetch("answered_as", nil)
+
+    def expired?(at = Clickwrap.now) = expires_at.nil? || expires_at <= at
+
+    # Computed in the constructor, before the object freezes. Lazy memoization
+    # would raise on a frozen manifest, and recomputing on every call would
+    # canonicalize the whole body each time it is read — which happens on every
+    # render and every capture.
+    attr_reader :digest
+
+    def to_token
+      self.class.verifier.generate(attributes, purpose: SIGNING_PURPOSE, expires_at: expires_at)
+    end
+
+    def to_h = attributes
+
+    def to_s = "presentation of #{policy_key} (#{nonce})"
+
+    private
+
+    def parse_time(value)
+      return nil if value.blank?
+
+      Time.parse(value).utc
+    rescue ArgumentError
+      nil
+    end
+
+    def deep_stringify(value)
+      case value
+      when Hash then value.to_h { |key, nested| [key.to_s, deep_stringify(nested)] }
+      when Array then value.map { |element| deep_stringify(element) }
+      when Symbol then value.to_s
+      else value
+      end
+    end
+  end
+end