clickwrap 0.0.0 → 0.1.0

data/lib/clickwrap/authority.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  AUTHORITY_DECISION_ATTRIBUTES = %i[authorized source role verified_at details].freeze
+
+  # Namespace marker for authority adapters and future helpers. The public
+  # immutable value objects remain Clickwrap::AuthorityRule and
+  # Clickwrap::AuthorityDecision for the shortest host-facing API.
+  module Authority
+  end
+
+  # The server-owned rule that says which represented parties a policy allows
+  # and which adapter has to establish the actor's authority. It is compiled
+  # into the policy revision and repeated in the signed presentation, so a
+  # browser cannot choose a weaker role or a different authority source.
+  AuthorityRule = Data.define(
+    :represented_party_types,
+    :adapter_name,
+    :minimum_role,
+    :required_permission,
+    :allow_represented_party_creation
+  ) do
+    def initialize(represented_party_types: [], adapter_name: :host,
+                   minimum_role: nil, required_permission: nil,
+                   allow_represented_party_creation: false)
+      normalized_types = Array(represented_party_types).filter_map do |type|
+        name = type.is_a?(Class) ? type.name : type.to_s
+        name unless name.strip.empty?
+      end.uniq.freeze
+
+      if normalized_types.empty?
+        raise DefinitionError,
+              "A represented-party authority rule must name at least one represented-party " \
+              "class. An empty list would let the rule authorize every kind of record."
+      end
+
+      super(
+        represented_party_types: normalized_types,
+        adapter_name: adapter_name.to_s,
+        minimum_role: minimum_role&.to_s,
+        required_permission: required_permission&.to_s,
+        allow_represented_party_creation: allow_represented_party_creation == true
+      )
+    end
+
+    def allows_represented_party_creation? = allow_represented_party_creation == true
+
+    def permits?(represented_party)
+      return false if represented_party.nil?
+
+      represented_party.class.ancestors.any? do |ancestor|
+        ancestor.respond_to?(:name) && represented_party_types.include?(ancestor.name)
+      end
+    end
+
+    def to_snapshot
+      {
+        "represented_party_types" => represented_party_types,
+        "authority_adapter" => adapter_name,
+        "when_actor_is_at_least" => minimum_role,
+        "when_actor_has_permission" => required_permission,
+        "including_when_this_action_creates_the_represented_party" =>
+          allows_represented_party_creation?
+      }.compact
+    end
+  end
+
+  # The host's answer to "may this actor act for that represented party?".
+  # Clickwrap records the answer and its provenance; it does not decide whether
+  # the authority is legally sufficient.
+  AuthorityDecision = Data.define(:authorized, :source, :role, :verified_at, :details) do
+    def initialize(authorized: false, source: nil, role: nil, verified_at: nil, details: {})
+      super(
+        authorized: authorized == true,
+        source: source&.to_s,
+        role: role&.to_s,
+        verified_at: verified_at,
+        details: (details || {}).to_h.deep_stringify_keys.freeze
+      )
+    end
+
+    def authorized? = authorized == true
+
+    def to_snapshot
+      {
+        "state" => authorized? ? "verified" : "not_verified",
+        "source" => source,
+        "role" => role,
+        "verified_at" => verified_at&.iso8601(6),
+        "details" => details.presence
+      }.compact
+    end
+
+    def self.from(value)
+      return value if value.is_a?(self)
+
+      if value == true
+        raise ConfigurationError,
+              "The represented-party authority callback returned bare true. Return a " \
+              "Clickwrap::AuthorityDecision (or a hash) with `authorized:`, `source:`, " \
+              "`role:`, and `verified_at:` so the evidence records why the actor was authorized."
+      end
+
+      return new(authorized: false) if value.nil? || value == false
+
+      unless value.respond_to?(:to_h)
+        raise ConfigurationError,
+              "The represented-party authority callback must return false, nil, a " \
+              "Clickwrap::AuthorityDecision, or a hash with `authorized:`, `source:`, " \
+              "`role:`, and `verified_at:`. It returned #{value.class.name}."
+      end
+
+      attributes = value.to_h.symbolize_keys
+      unknown = attributes.keys - AUTHORITY_DECISION_ATTRIBUTES
+      if unknown.any?
+        label = unknown.one? ? "attribute" : "attributes"
+        raise ConfigurationError,
+              "The represented-party authority callback returned unknown #{label} " \
+              "#{unknown.map { |key| "`#{key}:`" }.join(", ")}. Supported attributes are " \
+              "#{AUTHORITY_DECISION_ATTRIBUTES.map { |key| "`#{key}:`" }.join(", ")}."
+      end
+
+      new(**attributes)
+    end
+  end
+
+  # One fail-closed path for presentation-time and capture-time authority
+  # checks. The represented-party adapter owns the authorization fact;
+  # Clickwrap only validates that an affirmative decision carries enough
+  # provenance to become meaningful evidence.
+  class AuthorityVerifier
+    def self.verify!(policy:, actor:, represented_party:, tenant:, authentication_context:)
+      unless policy.permits_acting_for_party?(represented_party)
+        raise AuthorityNotVerified,
+              "Policy #{policy.key} does not permit an actor to act for " \
+              "#{represented_party.class.name}. Declare the represented-party type and a " \
+              "reviewed server-side authority rule."
+      end
+
+      rule = policy.authority_rule
+      adapter = Clickwrap.config.represented_party_authority_adapter(rule.adapter_name)
+      raw = if adapter
+              adapter.verify(
+                actor: actor,
+                represented_party: represented_party,
+                authority_rule: rule,
+                tenant: tenant,
+                authentication_context: authentication_context
+              )
+            else
+              Clickwrap.config.verify_actor_can_act_for_represented_party_with.call(
+                actor: actor,
+                represented_party: represented_party,
+                policy: policy,
+                tenant: tenant,
+                authentication_context: authentication_context
+              )
+            end
+      decision = AuthorityDecision.from(raw)
+
+      unless decision.authorized?
+        raise AuthorityNotVerified,
+              "The host authority check did not authorize this actor to act for the represented party."
+      end
+
+      missing = %i[source role verified_at].select { |attribute| decision.public_send(attribute).blank? }
+      return decision if missing.empty?
+
+      raise AuthorityNotVerified,
+            "An authorized represented-party action must record #{missing.join(", ")}. Return " \
+            "those facts from `verify_actor_can_act_for_represented_party_with`."
+    end
+  end
+end

data/lib/clickwrap/canonical_json.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "errors"
+
+module Clickwrap
+  # Canonical JSON serialization, implementing the JSON Canonicalization Scheme
+  # (RFC 8785, https://www.rfc-editor.org/rfc/rfc8785).
+  #
+  # Receipts are digested and verified by code that may be years newer than the
+  # code that wrote them, and by verifiers written in other languages. So the
+  # bytes have to be reproducible from the data alone: no Ruby object
+  # serialization, no YAML, no hash insertion order, no database column order,
+  # no locale-dependent number formatting.
+  #
+  # The Clickwrap profile adds a few rules on top of RFC 8785, applied by the
+  # callers in ReceiptSchema rather than here:
+  #
+  #   * timestamps are UTC strings with exactly six fractional digits;
+  #   * digests are "<algorithm>:<lowercase hex>" strings;
+  #   * identifiers are strings, never numbers;
+  #   * a value that was never collected is an explicit state object, never
+  #     `null` and never a missing key that could mean either; and
+  #   * host extensions use keys prefixed `x_`.
+  module CanonicalJson
+    # Integers above this magnitude cannot survive a round trip through the
+    # IEEE 754 double that RFC 8785 assumes, so serializing one would produce
+    # bytes another verifier could not reproduce.
+    MAX_EXACT_INTEGER = (2**53) - 1
+
+    ESCAPES = {
+      "\b" => "\\b",
+      "\t" => "\\t",
+      "\n" => "\\n",
+      "\f" => "\\f",
+      "\r" => "\\r",
+      '"' => '\\"',
+      "\\" => "\\\\"
+    }.freeze
+
+    class SerializationError < Clickwrap::Error; end
+
+    class << self
+      # Returns the canonical UTF-8 JSON bytes for `value`.
+      def generate(value)
+        buffer = +""
+        write(value, buffer)
+        buffer.force_encoding(Encoding::UTF_8)
+      end
+
+      alias dump generate
+
+      # Parses JSON text and returns the canonical bytes for it. Useful for
+      # verifying a receipt that arrived as arbitrarily formatted JSON.
+      def canonicalize(json_text)
+        generate(JSON.parse(json_text))
+      end
+
+      # True when `json_text` is already in canonical form.
+      def canonical?(json_text)
+        canonicalize(json_text) == json_text
+      rescue JSON::ParserError, SerializationError
+        false
+      end
+
+      private
+
+      def write(value, buffer)
+        case value
+        when nil then buffer << "null"
+        when true then buffer << "true"
+        when false then buffer << "false"
+        when String then write_string(value, buffer)
+        when Symbol then write_string(value.to_s, buffer)
+        when Integer then write_integer(value, buffer)
+        when Float then buffer << format_number(value)
+        when Array then write_array(value, buffer)
+        when Hash then write_object(value, buffer)
+        else
+          raise SerializationError,
+                "#{value.class} cannot appear in canonical JSON. Convert it to a string, " \
+                "number, boolean, array, or hash before it reaches a receipt."
+        end
+      end
+
+      def write_array(array, buffer)
+        buffer << "["
+        array.each_with_index do |element, index|
+          buffer << "," unless index.zero?
+          write(element, buffer)
+        end
+        buffer << "]"
+      end
+
+      def write_object(hash, buffer)
+        entries = hash.map { |key, value| [canonical_key(key), value] }
+        detect_duplicate_keys(entries)
+
+        buffer << "{"
+        entries.sort_by { |key, _| utf16_sort_key(key) }.each_with_index do |(key, value), index|
+          buffer << "," unless index.zero?
+          write_string(key, buffer)
+          buffer << ":"
+          write(value, buffer)
+        end
+        buffer << "}"
+      end
+
+      def canonical_key(key)
+        case key
+        when String then key
+        when Symbol then key.to_s
+        else
+          raise SerializationError,
+                "Canonical JSON object keys must be strings or symbols, got #{key.class}"
+        end
+      end
+
+      def detect_duplicate_keys(entries)
+        keys = entries.map(&:first)
+        return if keys.uniq.length == keys.length
+
+        duplicate = keys.tally.find { |_, count| count > 1 }&.first
+        raise SerializationError, "Duplicate object key #{duplicate.inspect} in canonical JSON"
+      end
+
+      # RFC 8785 sorts object keys by their UTF-16 code units. Ruby compares
+      # strings by UTF-8 bytes, which orders characters outside the Basic
+      # Multilingual Plane differently, so encode before comparing.
+      def utf16_sort_key(key)
+        key.encode(Encoding::UTF_16BE, invalid: :replace, undef: :replace).b
+      end
+
+      def write_string(string, buffer)
+        raise SerializationError, "Canonical JSON strings must be valid UTF-8" unless string.valid_encoding?
+
+        buffer << '"'
+        string.each_char do |char|
+          escape = ESCAPES[char]
+          buffer << if escape
+                      escape
+                    elsif char.ord < 0x20
+                      format('\\u%04x', char.ord)
+                    else
+                      char
+                    end
+        end
+        buffer << '"'
+      end
+
+      def write_integer(value, buffer)
+        if value.abs > MAX_EXACT_INTEGER
+          raise SerializationError,
+                "#{value} is too large to serialize exactly in canonical JSON. " \
+                "Record large identifiers as strings."
+        end
+
+        buffer << value.to_s
+      end
+
+      # RFC 8785 defers to the ECMAScript Number::toString algorithm, which is
+      # not what Ruby's Float#to_s produces: Ruby writes 1.0 where ECMAScript
+      # writes 1, and 1.0e-05 where ECMAScript writes 0.00001. This rebuilds
+      # the ECMAScript form from Ruby's shortest round-trip digits.
+      def format_number(value)
+        raise SerializationError, "Canonical JSON cannot represent #{value}" if value.nan? || value.infinite?
+        return "0" if value.zero?
+
+        sign = value.negative? ? "-" : ""
+        digits, exponent = shortest_digits(value.abs)
+        sign + place_decimal_point(digits, exponent)
+      end
+
+      # Returns [digits, n] such that the value equals 0.<digits> * 10**n with
+      # no leading or trailing zero in `digits`.
+      def shortest_digits(magnitude)
+        text = magnitude.to_s
+        match = /\A(\d+)(?:\.(\d+))?(?:e([+-]?\d+))?\z/.match(text)
+        raise SerializationError, "Cannot canonicalize the number #{text}" unless match
+
+        integer_part = match[1]
+        fraction_part = match[2] || ""
+        exponent = (match[3] || "0").to_i
+
+        digits = integer_part + fraction_part
+        position = integer_part.length + exponent
+
+        leading_zeros = digits.length - digits.sub(/\A0+/, "").length
+        digits = digits[leading_zeros..] || ""
+        position -= leading_zeros
+
+        digits = digits.sub(/0+\z/, "")
+        digits = "0" if digits.empty?
+
+        [digits, position]
+      end
+
+      def place_decimal_point(digits, position)
+        length = digits.length
+
+        if position.between?(length, 21)
+          digits + ("0" * (position - length))
+        elsif position.positive? && position <= 21
+          "#{digits[0, position]}.#{digits[position..]}"
+        elsif position > -6 && position <= 0
+          "0.#{"0" * -position}#{digits}"
+        else
+          exponent = position - 1
+          exponent_sign = exponent.negative? ? "-" : "+"
+          mantissa = length == 1 ? digits : "#{digits[0]}.#{digits[1..]}"
+          "#{mantissa}e#{exponent_sign}#{exponent.abs}"
+        end
+      end
+    end
+  end
+end

data/lib/clickwrap/capture/event_builder.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  class Capture
+    # Builds one complete, unsaved event graph from already verified input.
+    # Persistence/idempotency stay in Capture because they decide whether the
+    # protected block may run; this collaborator only constructs evidence.
+    class EventBuilder
+      Result = Data.define(:event, :request_evidence_annex)
+
+      def initialize(policy:, manifest:, revision:, statement_snapshots:, answers:,
+                     document_versions_by_id:, request_evidence:, event_type:,
+                     root_event_id:, predecessor_event_id:, actor:, actor_reference:,
+                     actor_snapshot:, represented_party:, authority_decision:, tenant_key:,
+                     subject:, subject_key:, subject_fingerprint:, capture_channel:,
+                     authentication_context:, attribution_method:, idempotency_key:,
+                     http_request_id:, http_route_name:, reason:, statement_action_overrides:)
+        @policy = policy
+        @manifest = manifest
+        @revision = revision
+        @statement_snapshots = statement_snapshots
+        @answers = answers
+        @document_versions_by_id = document_versions_by_id
+        @request_evidence = request_evidence
+        @event_type = event_type
+        @root_event_id = root_event_id
+        @predecessor_event_id = predecessor_event_id
+        @actor = actor
+        @actor_reference = actor_reference
+        @actor_snapshot = actor_snapshot
+        @represented_party = represented_party
+        @authority_decision = authority_decision
+        @tenant_key = tenant_key
+        @subject = subject
+        @subject_key = subject_key
+        @subject_fingerprint = subject_fingerprint
+        @capture_channel = capture_channel
+        @authentication_context = authentication_context
+        @attribution_method = attribution_method
+        @idempotency_key = idempotency_key
+        @http_request_id = http_request_id
+        @http_route_name = http_route_name
+        @reason = reason
+        @statement_action_overrides = statement_action_overrides
+      end
+
+      def build
+        now = Clickwrap.now
+        event_id = Identifier.generate(now)
+        annex = build_request_evidence_annex(event_id)
+        event = build_event(event_id, annex, now)
+
+        build_statements(event, now)
+        build_documents(event)
+
+        Result.new(event: event, request_evidence_annex: annex)
+      end
+
+      private
+
+      attr_reader :policy, :manifest
+
+      def build_event(event_id, annex, now)
+        Event.new(
+          id: event_id,
+          request_evidence_category_binding_digests: annex&.category_binding_digests || {},
+          request_evidence_digest_algorithm: annex&.binding_digest_algorithm,
+          request_evidence_key_id: annex&.binding_key_id,
+          event_type: @event_type,
+          policy_key: policy.key,
+          policy_revision: @revision,
+          root_event_id: @root_event_id,
+          predecessor_event_id: @predecessor_event_id,
+          actor: persisted_record(@actor),
+          actor_reference: @actor_reference,
+          actor_snapshot: @actor_snapshot,
+          represented_party: persisted_record(@represented_party),
+          represented_party_reference: represented_party_reference,
+          authority_source: @authority_decision&.source,
+          authority_role: @authority_decision&.role,
+          authority_verified_at: @authority_decision&.verified_at,
+          authority_details: @authority_decision&.details || {},
+          tenant_key: @tenant_key.presence,
+          subject: persisted_record(@subject),
+          subject_key: @subject_key,
+          subject_fingerprint: @subject_fingerprint,
+          capture_channel: @capture_channel,
+          authentication_method: @authentication_context[:method]&.to_s,
+          authentication_context: @authentication_context,
+          attribution_method: @attribution_method,
+          recorded_at_by_server: now,
+          idempotency_key: @idempotency_key,
+          http_request_id: @http_request_id,
+          http_route_name: @http_route_name,
+          presentation: persisted_presentation,
+          presentation_manifest: manifest.to_h,
+          presentation_manifest_digest: manifest.digest,
+          retention_class_key: policy.retention_class_key,
+          reason: @reason,
+          canonical_schema_version: Clickwrap::CANONICAL_SCHEMA_VERSION,
+          gem_version: Clickwrap::VERSION,
+          application_version: Clickwrap.config.resolved_application_version,
+          template_version: Clickwrap.config.resolved_template_version,
+          created_at: now
+        )
+      end
+
+      def build_statements(event, now)
+        @statement_snapshots.each_value.with_index do |statement, index|
+          key = statement.fetch("key")
+          fragment = manifest.statement(key) || {}
+          answer = @answers[key]
+          answered = statement["choices"] ? answer.present? : Submission.affirmative?(answer)
+
+          # Silence on an optional control is an offer not taken, not an
+          # affirmative refusal. It creates no grant statement.
+          next if statement["optional"] && !answered
+
+          event.statements.build(
+            ordinal: index,
+            statement_key: key,
+            kind: statement["kind"],
+            action: action_for(statement, answer, answered),
+            assertion_text: fragment["assertion"],
+            assertion_locale: manifest.locale,
+            label_text: fragment["label"],
+            link_labels: Array(fragment["documents"]).to_h { |document| [document["key"], document["label"]] },
+            choices: statement["choices"],
+            required: statement["required"],
+            optional: statement["optional"],
+            answer: answer,
+            answered: answered,
+            purpose_key: statement["purpose_key"],
+            withdrawal_path: statement["withdrawal_path"],
+            valid_from: now,
+            expires_at: policy.statement!(key).expires_after(now),
+            one_time: statement["one_time"],
+            requires: statement["requires"],
+            subject_fingerprint: fragment["subject_fingerprint"],
+            created_at: now
+          )
+        end
+      end
+
+      def action_for(statement, answer, answered)
+        override = @statement_action_overrides[statement.fetch("key")]
+        return override if override
+
+        initial = Vocabulary.initial_action_for(statement.fetch("kind"))
+        return initial unless statement["choices"] && answered
+
+        case statement["choices"][answer.to_s]
+        when "grant" then initial
+        when "decline" then "declined"
+        else statement["choices"][answer.to_s]
+        end
+      end
+
+      def build_documents(event)
+        ordinal = 0
+
+        manifest.statements.each do |statement|
+          Array(statement["documents"]).each do |document|
+            version = @document_versions_by_id.fetch(document["version_id"].to_s)
+
+            event.documents.build(
+              statement_key: statement["key"],
+              document_key: document["key"],
+              document_version_id: version.id,
+              version_label: document["version"],
+              locale: document["locale"],
+              source_media_type: document["source_media_type"],
+              source_content_digest: document["source_digest"],
+              rendered_media_type: document["rendered_media_type"],
+              rendered_content_digest: document["rendered_digest"],
+              renderer_name: document.dig("renderer", "name"),
+              renderer_version: document.dig("renderer", "version"),
+              sanitizer_name: document.dig("renderer", "sanitizer_name"),
+              sanitizer_version: document.dig("renderer", "sanitizer_version"),
+              ordinal: ordinal,
+              created_at: event.recorded_at_by_server
+            )
+
+            ordinal += 1
+          end
+        end
+      end
+
+      def build_request_evidence_annex(event_id)
+        return nil if @request_evidence.nil? || !@request_evidence.records_anything?
+
+        # Idempotent, and applied here as well as at boot: declaring an
+        # encrypted attribute reads the column, so an application whose
+        # database was not reachable during initialization would otherwise
+        # write this annex in plain text without anyone noticing.
+        RequestEvidence.apply_configured_encryption!
+
+        RequestEvidence.new(
+          @request_evidence.attributes.merge(event_id: event_id, created_at: Clickwrap.now)
+        )
+      end
+
+      def represented_party_reference
+        return "" if @represented_party.nil?
+
+        Reference.represented_party(@represented_party)
+      end
+
+      def persisted_record(value)
+        value if value.is_a?(::ActiveRecord::Base)
+      end
+
+      def persisted_presentation
+        return nil unless policy.persist_presentations?
+
+        Presentation.find_by(nonce: manifest.nonce)
+      end
+    end
+  end
+end