ap2_mandate_verifier 0.1.0.pre.3

data/lib/ap2_mandate_verifier/research_result.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module AP2MandateVerifier
+  # In-process immutable checked facts. No JSON/remote reconstruction API.
+  # Private constructors are API discipline, not a hostile Ruby-code sandbox.
+  class ResearchEvidence
+    CONTRACT_VERSION = "ap2.research-evidence.2"
+    IMPLEMENTATION_REVISION = "ap2.research-verifier.2"
+    SCOPE = %w[strict_inputs host_trust_profile_input_checks issuer_root_signature
+      original_root_graph_closure agent_key_confirmation agent_terminal_signature
+      closed_original_checkout_binding merchant_checkout_signature
+      fixed_subset_schema_constraints host_challenge_order_binding validity_intersection].freeze
+
+    def initialize(facts)
+      @data = self.class.__send__(:copy_frozen, facts.merge(
+        "contract_version" => CONTRACT_VERSION, "implementation_revision" => IMPLEMENTATION_REVISION,
+        "revision_kind" => "static_identifier_not_runtime_attestation", "verified_scope" => SCOPE))
+      freeze
+    end
+    def self.copy_frozen(value)
+      case value
+      when Hash
+        value.to_h { |key, child| [copy_frozen(key), copy_frozen(child)] }.freeze
+      when Array
+        value.map { |child| copy_frozen(child) }.freeze
+      when String
+        InputValidator.snapshot!(value)
+      when Integer, TrueClass, FalseClass, NilClass
+        value
+      else
+        raise ArgumentError, "unsupported checked fact"
+      end
+    end
+    private_class_method :new, :allocate, :copy_frozen
+    def [](field) = @data.fetch(field)
+    def to_h = @data
+    def dup = self
+    def clone(freeze: true) = self
+  end
+
+  # Only this factory runs the full supported pipeline and mints research output.
+  # Old Result never accepts Evidence, even for a successful research result.
+  class ResearchResult
+    def self.verify(**inputs)
+      facts = HostBinding.verified_binding!(**inputs)
+      new(ResearchEvidence.__send__(:new, facts))
+    rescue InputValidator::Unavailable, RootSignature::Unavailable => error
+      failure(:unavailable, error.code)
+    rescue InputValidator::Invalid, RootSignature::Rejected => error
+      failure(:rejected, error.code)
+    rescue LoadError
+      Result.new(status: :unavailable, code: :signature_dependency_unavailable)
+    rescue StandardError
+      Result.new(status: :unavailable, code: :research_verification_unavailable)
+    end
+    def self.failure(status, code)
+      unless Result::CODES.fetch(status).include?(code)
+        status, code = :unavailable, :research_verification_unavailable
+      end
+      Result.new(status: status, code: code)
+    end
+    private_class_method :failure
+    attr_reader :evidence
+    def initialize(evidence)
+      raise ArgumentError, "checked research evidence required" unless evidence.instance_of?(ResearchEvidence) && evidence.frozen?
+      @evidence = evidence
+      freeze
+    end
+    private_class_method :new, :allocate
+    def status = :verified_research
+    def code = :scoped_research_verified
+    def success? = true
+    def rejected? = false
+    def unverified? = false
+    def unavailable? = false
+    def dup = self
+    def clone(freeze: true) = self
+  end
+end

data/lib/ap2_mandate_verifier/result.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module AP2MandateVerifier
+  # Legacy non-success type. The opt-in research entry uses a separate type.
+  class Result
+    CODES = {
+      rejected: %i[invalid_input_type input_too_large invalid_encoding
+                   invalid_json duplicate_key input_too_deep invalid_root_jws
+                   unsupported_root_header unsupported_root_algorithm
+                   unsupported_root_type invalid_root_payload invalid_root_signature
+                   invalid_root_presentation unsupported_disclosure_profile invalid_disclosure
+                   missing_disclosure duplicate_disclosure duplicate_commitment extra_disclosure
+                   disclosure_limit_exceeded unsupported_purchase_profile agent_key_mismatch
+                   root_binding_mismatch audience_mismatch nonce_mismatch invalid_purchase_time
+                   delegation_claim_mismatch checkout_binding_mismatch checkout_identity_mismatch
+                   invalid_scoped_schema unsupported_scoped_profile unsupported_constraint
+                   constraint_mismatch amount_mismatch currency_mismatch constraint_limit_exceeded
+                   invalid_trust_context trust_context_mismatch unsupported_trust_profile inactive_trust_snapshot
+                   trust_snapshot_time_mismatch invalid_trust_key trust_key_not_found ambiguous_trust_key
+                   inactive_trust_key trust_key_time_mismatch
+                   invalid_host_context host_binding_mismatch challenge_state_mismatch
+                   challenge_reference_mismatch challenge_time_mismatch invalid_host_validity].freeze,
+      unverified: %i[verification_not_implemented root_signature_verified_only root_disclosures_verified_only
+                     purchase_binding_verified_only scoped_constraints_verified_only host_binding_verified_only].freeze,
+      unavailable: %i[json_dependency_unavailable input_check_unavailable
+                      signature_dependency_unavailable issuer_key_unavailable
+                      issuer_key_unsupported root_signature_check_unavailable
+                      disclosure_dependency_unavailable root_disclosure_check_unavailable
+                      purchase_context_unavailable purchase_dependency_unavailable purchase_check_unavailable
+                      constraint_context_unavailable constraint_dependency_unavailable constraint_check_unavailable trust_check_unavailable host_binding_check_unavailable research_verification_unavailable].freeze
+    }.freeze
+
+    attr_reader :status, :code
+
+    def initialize(status:, code:)
+      unless CODES.fetch(status, []).include?(code)
+        raise ArgumentError, "unsupported non-success result"
+      end
+      @status = status
+      @code = code
+      freeze
+    end
+
+    def success? = false
+    def evidence = nil
+    def rejected? = status == :rejected
+    def unverified? = status == :unverified
+    def unavailable? = status == :unavailable
+  end
+end

data/lib/ap2_mandate_verifier/root_disclosures.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module AP2MandateVerifier
+  # Pinned AP2 b4587ac1 / DC04 exact-three-array-commitments profile only.
+  # Whole original Root graph, including all disclosed subtrees, is inspected.
+  module RootDisclosures
+    MAX_DISCLOSURES = 16
+    MAX_SEGMENT_BYTES = 8_192
+    PATHS = [
+      ["delegate_payload", 0],
+      ["delegate_payload", 0, "disclosed", "constraints", 1, "allowed", 0],
+      ["delegate_payload", 0, "disclosed", "constraints", 0, "items", 0, "acceptable_items", 0]
+    ].map { |path| path.map { |part| part.freeze }.freeze }.freeze
+
+    class Rejected < RootSignature::Rejected; end
+
+    def self.check!(source, issuer_pem)
+      verified_root!(source, issuer_pem)
+      nil
+    end
+
+    # Internal handoff only: signature and entire closure are verified first.
+    # AP2 semantics, constraints and Host authorization remain unvalidated.
+    def self.verified_root!(source, issuer_pem)
+      wire = InputValidator.snapshot!(source)
+      raise Rejected, :invalid_root_presentation unless wire.ascii_only? && wire.end_with?("~")
+      parts = wire.split("~", -1)
+      raise Rejected, :invalid_root_presentation unless parts.size.between?(3, MAX_DISCLOSURES + 2) &&
+        parts.last == "" && !parts.first.empty? && parts[1...-1].none?(&:empty?)
+      # No disclosure decode, digest graph or trusted claims before signature.
+      payload = RootSignature.verified_payload!(parts.first, issuer_pem)
+      raise Rejected, :unsupported_disclosure_profile unless
+        (payload.keys - %w[delegate_payload _sd_alg]).empty? &&
+        (!payload.key?("_sd_alg") || payload["_sd_alg"] == "sha-256") &&
+        payload["delegate_payload"].instance_of?(Array) && payload["delegate_payload"].size == 1
+      require "digest"
+      mapping = {}
+      parts[1...-1].each do |part|
+        raise Rejected, :disclosure_limit_exceeded if part.bytesize > MAX_SEGMENT_BYTES
+        decoded = InputValidator.parse!(decode!(part))
+        raise Rejected, :unsupported_disclosure_profile unless decoded.instance_of?(Array) &&
+          decoded.size == 2 && decoded[0].instance_of?(String) &&
+          decoded[0].bytesize.between?(8, 128) && decoded[1].instance_of?(Hash)
+        digest = Base64.urlsafe_encode64(Digest::SHA256.digest(part), padding: false)
+        raise Rejected, :duplicate_disclosure if mapping.key?(digest)
+        mapping[digest] = decoded[1]
+      end
+      used = {}
+      observed = []
+      budget = [0]
+      resolved = walk!(payload, [], mapping, used, observed, budget, 1)
+      raise Rejected, :unsupported_disclosure_profile unless observed.sort_by(&:to_s) == PATHS.sort_by(&:to_s)
+      raise Rejected, :extra_disclosure unless used.size == mapping.size
+      resolved
+    end
+
+    def self.walk!(value, path, mapping, used, observed, budget, depth)
+      budget[0] += 1
+      raise Rejected, :disclosure_limit_exceeded if budget[0] > 2_048 ||
+        (depth > 24 && (value.instance_of?(Hash) || value.instance_of?(Array)))
+      case value
+      when Hash
+        raise Rejected, :unsupported_disclosure_profile if value.key?("_sd") || value.key?("...") ||
+          (path != [] && value.key?("_sd_alg"))
+        raise Rejected, :disclosure_limit_exceeded if value.size > 32
+        value.to_h { |key, child| [key, walk!(child, path + [key], mapping, used, observed, budget, depth + 1)] }
+      when Array
+        raise Rejected, :disclosure_limit_exceeded if value.size > 16
+        value.each_with_index.map do |item, index|
+          here = path + [index]
+          if item.instance_of?(Hash) && item.key?("...")
+            raise Rejected, :unsupported_disclosure_profile unless item.keys == ["..."] && PATHS.include?(here)
+            digest = item["..."]
+            raise Rejected, :invalid_disclosure unless digest.instance_of?(String) &&
+              digest.bytesize == 43 && decode!(digest).bytesize == 32
+            raise Rejected, :duplicate_commitment if used.key?(digest)
+            raise Rejected, :missing_disclosure unless mapping.key?(digest)
+            used[digest] = true
+            observed << here
+            walk!(mapping.fetch(digest), here + ["disclosed"], mapping, used, observed, budget, depth + 1)
+          else
+            walk!(item, here, mapping, used, observed, budget, depth + 1)
+          end
+        end
+      else
+        value
+      end
+    end
+
+    def self.decode!(part)
+      raise Rejected, :invalid_disclosure unless part.match?(/\A[A-Za-z0-9_-]+\z/)
+      raw = Base64.urlsafe_decode64(part + "=" * (-part.bytesize % 4))
+      raise Rejected, :invalid_disclosure unless Base64.urlsafe_encode64(raw, padding: false) == part
+      raw
+    rescue ArgumentError
+      raise Rejected, :invalid_disclosure
+    end
+    private_class_method :walk!, :decode!
+  end
+end

data/lib/ap2_mandate_verifier/root_signature.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module AP2MandateVerifier
+  # Crypto-only extraction of isolated_root_closure.rb's original JWS decode.
+  # No legacy research parser, test autorun, SD resolver or Host code is loaded.
+  module RootSignature
+    MAX_WIRE_BYTES = 32_768
+    MAX_KEY_BYTES = 1_024
+    JWT_VERSION = "3.3.0"
+
+    class Rejected < StandardError
+      attr_reader :code
+      def initialize(code)
+        @code = code
+        super(code.to_s)
+      end
+    end
+    class Unavailable < Rejected; end
+
+    def self.check!(source, issuer_pem)
+      verified_payload!(source, issuer_pem)
+      nil
+    end
+
+    # Internal stage handoff: always authenticates this original wire first.
+    # Returned claims remain unvalidated for AP2 authority/schema/constraints.
+    def self.verified_payload!(source, issuer_pem, expected_typ: "example+sd-jwt", max_bytes: MAX_WIRE_BYTES)
+      wire = InputValidator.snapshot!(source, max_bytes: max_bytes)
+      raise Rejected, :invalid_root_jws unless wire.ascii_only?
+      parts = wire.split(".", -1)
+      raise Rejected, :invalid_root_jws unless parts.length == 3
+      dependencies!
+      header = InputValidator.parse!(decode!(parts[0], 2_048))
+      payload = InputValidator.parse!(decode!(parts[1], 24_576))
+      signature = decode!(parts[2], 64)
+      raise Rejected, :invalid_root_jws unless signature.bytesize == 64
+      raise Rejected, :unsupported_root_header unless header.instance_of?(Hash) &&
+        (header.keys - %w[alg typ kid]).empty? &&
+        (!header.key?("kid") || (header["kid"].instance_of?(String) &&
+          header["kid"].bytesize.between?(1, 128)))
+      raise Rejected, :unsupported_root_algorithm unless header["alg"] == "ES256"
+      raise Rejected, :unsupported_root_type unless header["typ"] == expected_typ
+      raise Rejected, :invalid_root_payload unless payload.instance_of?(Hash)
+      key = public_key!(issuer_pem)
+
+      begin
+        # Preserve original signed bytes. Nested mandate claims/time, SD
+        # completeness and Host constraints belong to later checks, not this
+        # crypto-only primitive. Disabling top-level JWT claims grants nothing.
+        verified, protected_header = JWT.decode(wire, key, true,
+          algorithms: ["ES256"], verify_expiration: false,
+          verify_not_before: false, verify_iat: false, verify_iss: false,
+          verify_aud: false, verify_jti: false, verify_sub: false,
+          required_claims: [], jwks: nil, x5c: nil)
+      rescue JWT::DecodeError
+        raise Rejected, :invalid_root_signature
+      end
+      raise Unavailable, :root_signature_check_unavailable unless verified == payload && protected_header == header
+      payload
+    end
+
+    # Canonical coordinates from independently supplied public PEM, never JWK import.
+    def self.public_jwk!(pem)
+      dependencies!
+      point = public_key!(pem).public_key.to_octet_string(:uncompressed)
+      {"kty" => "EC", "crv" => "P-256",
+       "x" => Base64.urlsafe_encode64(point.byteslice(1, 32), padding: false),
+       "y" => Base64.urlsafe_encode64(point.byteslice(33, 32), padding: false)}
+    end
+
+    def self.dependencies!
+      raise Unavailable, :signature_dependency_unavailable unless defined?(Gem)
+      gem "jwt", "= #{JWT_VERSION}"
+      require "jwt"
+      require "base64"
+      require "openssl"
+      raise Unavailable, :signature_dependency_unavailable unless
+        Gem.loaded_specs["jwt"]&.version&.to_s == JWT_VERSION
+    rescue LoadError
+      raise Unavailable, :signature_dependency_unavailable
+    end
+
+    def self.decode!(part, limit)
+      raise Rejected, :invalid_root_jws unless part.match?(/\A[A-Za-z0-9_-]+\z/)
+      raw = Base64.urlsafe_decode64(part + "=" * (-part.bytesize % 4))
+      raise Rejected, :invalid_root_jws unless raw.bytesize <= limit &&
+        Base64.urlsafe_encode64(raw, padding: false) == part
+      raw.freeze
+    rescue ArgumentError
+      raise Rejected, :invalid_root_jws
+    end
+
+    def self.public_key!(source)
+      begin
+        pem = InputValidator.snapshot!(source, max_bytes: MAX_KEY_BYTES)
+      rescue InputValidator::Invalid
+        raise Unavailable, :issuer_key_unavailable
+      end
+      # Accept canonical SPKI public PEM only: no encrypted/private key
+      # parsing, filesystem paths, URLs, JWK fetches or token-selected keys.
+      raise Unavailable, :issuer_key_unsupported unless pem.ascii_only? &&
+        pem.start_with?("-----BEGIN PUBLIC KEY-----\n")
+      begin
+        key = OpenSSL::PKey.read(pem)
+        raise Unavailable, :issuer_key_unsupported unless
+          key.instance_of?(OpenSSL::PKey::EC) && !key.private? &&
+          key.group.curve_name == "prime256v1" && key.public_to_pem == pem
+      rescue OpenSSL::PKey::PKeyError, ArgumentError
+        raise Unavailable, :issuer_key_unsupported
+      end
+      key
+    end
+    private_class_method :dependencies!, :decode!, :public_key!
+  end
+end

data/lib/ap2_mandate_verifier/scoped_constraints.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module AP2MandateVerifier
+  # Hand-checked closed subset of pinned b4587ac1 AP2/UCP schemas, not a
+  # general JSON Schema evaluator. One Merchant/SKU, no tax/discount/links.
+  module ScopedConstraints
+    MAX_AMOUNT = 9_007_199_254_740_991
+    MAX_QUANTITY = 1_000_000
+    CURRENCIES = %w[USD EUR JPY].freeze
+    CORE_INSTANCE_OF = Object.instance_method(:instance_of?)
+    class Rejected < RootSignature::Rejected; end
+
+    def self.check!(**inputs)
+      verified_constraints!(**inputs)
+      nil
+    end
+
+    # Internal claims handoff after the complete existing limited profile.
+    def self.verified_constraints!(expected_currency:, expected_total_minor:, **binding_inputs)
+      begin
+        currency = InputValidator.snapshot!(expected_currency, max_bytes: 3)
+      rescue InputValidator::Invalid
+        raise RootSignature::Unavailable, :constraint_context_unavailable
+      end
+      raise RootSignature::Unavailable, :constraint_context_unavailable unless
+        CURRENCIES.include?(currency) && CORE_INSTANCE_OF.bind_call(expected_total_minor, Integer) &&
+        expected_total_minor.between?(0, MAX_AMOUNT)
+      details = PurchaseBinding.verified_details!(**binding_inputs)
+      open, checkout = details.values_at(:open, :checkout)
+      constraints = open["constraints"]
+      raise Rejected, :unsupported_constraint unless constraints.instance_of?(Array) && constraints.size == 2
+      required, allowed = constraints
+      raise Rejected, :invalid_scoped_schema unless required.instance_of?(Hash) && allowed.instance_of?(Hash)
+      raise Rejected, :unsupported_constraint unless required["type"] == "checkout.line_items" &&
+        allowed["type"] == "checkout.allowed_merchants"
+      exact!(required, %w[items type])
+      exact!(allowed, %w[allowed type])
+      requirement = one!(required["items"])
+      exact!(requirement, %w[acceptable_items id quantity])
+      text!(requirement["id"]) # S01: signature VALID does not make id=123 valid.
+      quantity!(requirement["quantity"])
+      sku = one!(requirement["acceptable_items"])
+      exact!(sku, %w[id title])
+      text!(sku["id"])
+      text!(sku["title"], 512)
+      merchant = one!(allowed["allowed"])
+      exact!(merchant, %w[id name])
+      text!(merchant["id"])
+      text!(merchant["name"], 512)
+
+      text!(checkout["id"])
+      text!(checkout["merchant"]["id"])
+      text!(checkout["merchant"]["name"], 512)
+      raise Rejected, :constraint_mismatch unless checkout["merchant"] == merchant
+      text!(checkout["currency"], 3)
+      raise Rejected, :unsupported_scoped_profile unless CURRENCIES.include?(checkout["currency"])
+      raise Rejected, :currency_mismatch unless checkout["currency"] == currency
+      raise Rejected, :invalid_scoped_schema unless checkout["links"].instance_of?(Array)
+      raise Rejected, :unsupported_scoped_profile unless checkout["links"].empty?
+      line = one!(checkout["line_items"])
+      exact!(line, %w[id item quantity totals])
+      text!(line["id"])
+      quantity!(line["quantity"])
+      product = line["item"]
+      exact!(product, %w[id price title])
+      text!(product["id"])
+      text!(product["title"], 512)
+      amount!(product["price"])
+      raise Rejected, :constraint_mismatch unless product["id"] == sku["id"] &&
+        product["title"] == sku["title"] && line["quantity"] == requirement["quantity"]
+      amount = product["price"] * line["quantity"]
+      raise Rejected, :constraint_limit_exceeded if amount > MAX_AMOUNT
+      raise Rejected, :amount_mismatch unless amount == expected_total_minor
+      totals!(line["totals"], amount)
+      totals!(checkout["totals"], amount)
+      details
+    end
+
+    def self.exact!(value, fields)
+      raise Rejected, :invalid_scoped_schema unless value.instance_of?(Hash) && (fields - value.keys).empty?
+      raise Rejected, :unsupported_scoped_profile unless (value.keys - fields).empty?
+    end
+    def self.one!(value)
+      raise Rejected, :invalid_scoped_schema unless value.instance_of?(Array)
+      raise Rejected, :unsupported_scoped_profile unless value.size == 1
+      value.first
+    end
+    def self.text!(value, limit = 256)
+      raise Rejected, :invalid_scoped_schema unless value.instance_of?(String) && !value.empty?
+      raise Rejected, :constraint_limit_exceeded if value.bytesize > limit
+    end
+    def self.quantity!(value)
+      raise Rejected, :invalid_scoped_schema unless value.instance_of?(Integer) && value > 0
+      raise Rejected, :constraint_limit_exceeded if value > MAX_QUANTITY
+    end
+    def self.amount!(value)
+      raise Rejected, :invalid_scoped_schema unless value.instance_of?(Integer) && value >= 0
+      raise Rejected, :constraint_limit_exceeded if value > MAX_AMOUNT
+    end
+    def self.totals!(values, expected)
+      raise Rejected, :invalid_scoped_schema unless values.instance_of?(Array)
+      raise Rejected, :unsupported_scoped_profile unless values.size == 2
+      values.each do |entry|
+        exact!(entry, %w[amount type])
+        text!(entry["type"])
+        amount!(entry["amount"])
+      end
+      raise Rejected, :unsupported_scoped_profile unless values.map { |entry| entry["type"] }.sort == %w[subtotal total]
+      raise Rejected, :amount_mismatch unless values.all? { |entry| entry["amount"] == expected }
+    end
+    private_class_method :exact!, :one!, :text!, :quantity!, :amount!, :totals!
+    private_constant :CORE_INSTANCE_OF
+  end
+end

data/lib/ap2_mandate_verifier/trust_context.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+require "digest"
+
+module AP2MandateVerifier
+  # Authenticated Host assertions, never token-selected registration. No I/O.
+  module TrustContext
+    PROFILE_BODY = '{"profile_ref":"ap2.checkout.single_merchant_sku","version":"1","ap2_source":"b4587ac1d055888a73b4b21750973cffba961793","subset_source":"027ed4734af47c8289dbcb837373bb6086463ec4","algorithm":"ES256","key_format":"canonical-public-SPKI-P256-SHA256","root_type":"example+sd-jwt","terminal_type":"kb+sd-jwt","checkout_type":"JWT","disclosure_path_semantics":"root-walker-with-synthetic-disclosed-edges","disclosure_positions":["delegate_payload[0]","delegate_payload[0].disclosed.constraints[0].items[0].acceptable_items[0]","delegate_payload[0].disclosed.constraints[1].allowed[0]"],"constraints":["checkout.line_items","checkout.allowed_merchants"]}'.freeze
+    PROFILE_REF = "ap2.checkout.single_merchant_sku"
+    PROFILE_VERSION = "1"
+    PROFILE_HASH = Digest::SHA256.hexdigest(PROFILE_BODY).freeze
+    ROLES = {"Issuer" => :trusted_issuer_public_key_pem,
+             "Agent" => :expected_agent_public_key_pem,
+             "Merchant" => :trusted_merchant_public_key_pem}.freeze
+    RECORD_FIELDS = %w[role identity tenant_id purpose key_ref profile_ref profile_version public_key_pem key_fingerprint algorithm active not_before not_after].freeze
+    SELECTION_FIELDS = %w[trust_snapshot_id policy_version trust_content_hash profile_ref profile_version profile_definition_hash tenant_id Issuer Agent Merchant].freeze
+    INPUTS = %i[root_presentation terminal_jws host_checkout_jws expected_aud expected_nonce verified_at expected_checkout_id expected_merchant_id expected_currency expected_total_minor].freeze
+
+    def self.reject!(code = :invalid_trust_context) = raise(RootSignature::Rejected, code)
+    def self.shape!(value, fields)
+      reject! unless value.instance_of?(Hash) && value.keys.sort == fields.sort
+    end
+    def self.id!(value)
+      reject! unless value.instance_of?(String) && value.bytesize.between?(1, 256)
+    end
+    def self.digest!(value)
+      reject! unless value.instance_of?(String) && /\A[0-9a-f]{64}\z/.match?(value)
+    end
+    def self.time!(value)
+      reject! unless value.instance_of?(Integer) && value.between?(0, 4_102_444_800)
+    end
+    def self.window!(value)
+      reject! unless value["active"] == true || value["active"] == false
+      time!(value["not_before"])
+      time!(value["not_after"])
+      reject! unless value["not_before"] < value["not_after"]
+    end
+    def self.live!(value, now, inactive, expired)
+      reject!(inactive) unless value["active"]
+      reject!(expired) unless value["not_before"] <= now && now < value["not_after"]
+    end
+    def self.body!(envelope, fields, hash_name, limit)
+      shape!(envelope, fields + [hash_name, "body"])
+      digest!(envelope[hash_name])
+      wire = InputValidator.snapshot!(envelope["body"], max_bytes: limit)
+      reject!(:trust_context_mismatch) unless Digest::SHA256.hexdigest(wire) == envelope[hash_name]
+      body = InputValidator.parse!(wire)
+      fields.each do |field|
+        id!(envelope[field])
+        reject!(:trust_context_mismatch) unless body.instance_of?(Hash) && body[field] == envelope[field]
+      end
+      [body, wire]
+    end
+    def self.keys!(**inputs) = verified_context!(**inputs).fetch(:keys)
+
+    # Internal handoff of validated Host references and selected-key windows.
+    def self.verified_context!(trust_json:, selection_json:, verified_at:, expected_merchant_id:)
+      time!(verified_at)
+      trust = InputValidator.parse!(trust_json)
+      selection = InputValidator.parse!(InputValidator.snapshot!(selection_json, max_bytes: 16_384))
+      shape!(trust, %w[snapshot profile])
+      shape!(selection, SELECTION_FIELDS)
+      %w[trust_snapshot_id policy_version profile_ref profile_version tenant_id].each { |f| id!(selection[f]) }
+      %w[trust_content_hash profile_definition_hash].each { |f| digest!(selection[f]) }
+      ROLES.each_key do |role|
+        shape!(selection[role], %w[identity purpose key_ref])
+        selection[role].each_value { |value| id!(value) }
+      end
+      reject!(:trust_context_mismatch) unless selection["Merchant"]["identity"] == expected_merchant_id
+      snapshot, = body!(trust["snapshot"], %w[id policy_version], "content_hash", 65_536)
+      shape!(snapshot, %w[id policy_version active not_before not_after records])
+      window!(snapshot)
+      reject!(:trust_context_mismatch) unless trust["snapshot"].values_at("id", "policy_version", "content_hash") ==
+        selection.values_at("trust_snapshot_id", "policy_version", "trust_content_hash")
+      live!(snapshot, verified_at, :inactive_trust_snapshot, :trust_snapshot_time_mismatch)
+      _profile, wire = body!(trust["profile"], %w[profile_ref version], "definition_hash", 8_192)
+      reject!(:unsupported_trust_profile) unless wire == PROFILE_BODY &&
+        trust["profile"].values_at("profile_ref", "version", "definition_hash") == [PROFILE_REF, PROFILE_VERSION, PROFILE_HASH] &&
+        selection.values_at("profile_ref", "profile_version", "profile_definition_hash") == [PROFILE_REF, PROFILE_VERSION, PROFILE_HASH]
+      records = snapshot["records"]
+      reject! unless records.instance_of?(Array) && records.length.between?(1, 16)
+      records.each do |record|
+        shape!(record, RECORD_FIELDS)
+        %w[identity tenant_id purpose key_ref profile_ref profile_version].each { |f| id!(record[f]) }
+        reject! unless ROLES.key?(record["role"])
+        window!(record)
+        reject!(:unsupported_trust_profile) unless record.values_at("profile_ref", "profile_version", "algorithm") == [PROFILE_REF, PROFILE_VERSION, "ES256"]
+        digest!(record["key_fingerprint"])
+        begin
+          RootSignature.public_jwk!(record["public_key_pem"])
+        rescue RootSignature::Unavailable => error
+          raise if error.code == :signature_dependency_unavailable
+          reject!(:invalid_trust_key)
+        end
+        reject!(:invalid_trust_key) unless Digest::SHA256.hexdigest(record["public_key_pem"]) == record["key_fingerprint"]
+      end
+      selected = {}
+      keys = ROLES.to_h do |role, keyword|
+        wanted = selection[role]
+        matches = records.select do |record|
+          record["role"] == role && record["tenant_id"] == selection["tenant_id"] &&
+            wanted.all? { |field, value| record[field] == value }
+        end
+        reject!(:trust_key_not_found) if matches.empty?
+        reject!(:ambiguous_trust_key) unless matches.length == 1
+        record = matches.first
+        live!(record, verified_at, :inactive_trust_key, :trust_key_time_mismatch)
+        selected[role] = record
+        [keyword, record["public_key_pem"].freeze]
+      end.freeze
+      windows = [snapshot] + selected.values
+      references = selection.slice("trust_snapshot_id", "policy_version", "trust_content_hash",
+        "profile_definition_hash", "profile_ref", "profile_version", "tenant_id").transform_values(&:freeze).freeze
+      selected_keys = selected.values.map do |record|
+        record.reject { |field, _| field == "public_key_pem" }.freeze
+      end.freeze
+      {keys: keys, references: references, selected_keys: selected_keys,
+       agent_fingerprint: selected.fetch("Agent").fetch("key_fingerprint").freeze,
+       valid_from: windows.map { |value| value["not_before"] }.max,
+       valid_until: windows.map { |value| value["not_after"] }.min}.freeze
+    end
+    private_class_method :reject!, :shape!, :id!, :digest!, :time!, :window!, :live!, :body!
+  end
+end