openid4vp 0.1.0

data/lib/openid4vp/sd_jwt/presentation.rb

@@ -0,0 +1,333 @@
+# frozen_string_literal: true
+
+require_relative "../sd_jwt"
+require_relative "parser"
+require_relative "digest"
+require_relative "reconstruct"
+require_relative "kb_jwt"
+require_relative "../errors"
+require_relative "../jose/jws"
+require_relative "../jose/jwk"
+require_relative "../jose/algorithms"
+require_relative "../x509"
+require_relative "../transaction_data/sd_jwt_hashes"
+
+module OpenID4VP
+  module SdJwt
+    # Verifies (verifier side) and builds (wallet side) SD-JWT VC
+    # presentations: `dc+sd-jwt` / `vc+sd-jwt` typed Issuer-signed JWTs, their
+    # selective disclosures, and the Key Binding JWT that binds a
+    # presentation to a specific Verifier request.
+    module Presentation
+      VALID_TYPES = %w[dc+sd-jwt vc+sd-jwt].freeze
+
+      Result = Struct.new(:payload, :claims, :kb_payload, :holder_jwk, :x5chain, :issuer, :vct, :alg, :kb_alg,
+                          keyword_init: true)
+
+      module_function
+
+      # `issuer_key_resolver` is a callable `(iss, header) -> JWK | [JWK] |
+      # nil`. Raises PresentationInvalid for an unknown issuer, an
+      # unexpected `typ`, an unverifiable signature, an expired/not-yet-valid
+      # credential, or a disclosure reconstruction failure (see
+      # Reconstruct). `require_kb` controls only whether a Key Binding JWT
+      # is MANDATORY: a Key Binding JWT that IS present is always verified
+      # (raising HolderBindingInvalid if `cnf.jwk` is missing or
+      # verification fails, see KbJwt.verify), regardless of `require_kb`;
+      # when one is absent, `require_kb` decides whether that is itself a
+      # HolderBindingInvalid or simply yields a nil `kb_payload`. When
+      # `transaction_data` is given and non-empty, verifies it against the
+      # Key Binding JWT (see OpenID4VP::TransactionData::SdJwtHashes.verify!).
+      def verify(str, issuer_key_resolver:, expected_nonce: nil, expected_aud: nil, require_kb: true, now: Time.now,
+                 leeway: 60, algorithms: %w[ES256 ES384 ES512], kb_algorithms: nil, transaction_data: nil)
+        parsed = coerce_parsed(str)
+        header, payload, sd_alg = verify_issuer_jwt(parsed, issuer_key_resolver, algorithms, now, leeway)
+
+        claims, = Reconstruct.claims(payload, parsed.disclosures, sd_alg)
+        cnf_jwk = extract_cnf_jwk(payload)
+
+        kb_payload, kb_alg = verify_kb(
+          parsed: parsed, cnf_jwk: cnf_jwk, expected_aud: expected_aud, expected_nonce: expected_nonce,
+          require_kb: require_kb, now: now, leeway: leeway, algorithms: kb_algorithms || algorithms, sd_alg: sd_alg
+        )
+        verify_transaction_data!(kb_payload, transaction_data)
+
+        Result.new(payload: payload, claims: claims, kb_payload: kb_payload, holder_jwk: cnf_jwk,
+                   x5chain: x5chain_from(header), issuer: payload["iss"], vct: payload["vct"],
+                   alg: header["alg"], kb_alg: kb_alg)
+      end
+
+      # Peeks, resolves the issuer key, verifies the signature and the
+      # exp/nbf time bounds. Returns `[header, payload, sd_alg]`.
+      def verify_issuer_jwt(parsed, issuer_key_resolver, algorithms, now, leeway)
+        peeked = OpenID4VP::JOSE::JWS.peek(parsed.issuer_jwt)
+        header = peeked.header
+        check_typ!(header)
+        raise OpenID4VP::PresentationInvalid, "sd-jwt: payload is not a JSON object" unless peeked.payload.is_a?(::Hash)
+
+        key = resolve_issuer_key(issuer_key_resolver, peeked.payload["iss"], header)
+        verified = verify_issuer_signature(parsed.issuer_jwt, header, key, algorithms)
+        payload = verified.payload
+        raise OpenID4VP::PresentationInvalid, "sd-jwt: payload is not a JSON object" unless payload.is_a?(::Hash)
+
+        check_time_bounds!(payload, now, leeway)
+
+        [header, payload, payload["_sd_alg"] || "sha-256"]
+      end
+      private_class_method :verify_issuer_jwt
+
+      # Returns `"<issuer-jwt>~<disclosure 1>~...~"` (no Key Binding JWT)
+      # containing only the disclosures needed to reveal `paths` (ancestors
+      # included). Raises PresentationInvalid when a path cannot be
+      # resolved.
+      def select(str_or_parsed, paths:)
+        parsed = coerce_parsed(str_or_parsed)
+        payload = OpenID4VP::JOSE::JWS.peek(parsed.issuer_jwt).payload
+        raise OpenID4VP::PresentationInvalid, "sd-jwt: payload is not a JSON object" unless payload.is_a?(::Hash)
+
+        sd_alg = payload["_sd_alg"] || "sha-256"
+        Reconstruct.reject_duplicate_disclosures!(parsed.disclosures)
+        by_digest = parsed.disclosures.to_h { |d| [d.digest(sd_alg), d] }
+
+        needed = {}
+        paths.each { |path| walk_path!(payload, path_components(path), by_digest, needed) }
+
+        selected = parsed.disclosures.select { |d| needed.key?(d.digest(sd_alg)) }
+        "#{parsed.issuer_jwt}~#{selected.map { |d| "#{d.raw}~" }.join}"
+      end
+
+      # `select` plus a Key Binding JWT signed by `holder_key`, whose
+      # `sd_hash` is computed over the selected (disclosure-minimized)
+      # presentation. Adds `SdJwtHashes.kb_claims(transaction_data)` when
+      # `transaction_data` is given and non-empty.
+      def present(str, paths:, holder_key:, aud:, nonce:, transaction_data: nil, kb_alg: nil, iat: nil)
+        selected = select(str, paths: paths)
+        payload = OpenID4VP::JOSE::JWS.peek(Parser.parse(selected).issuer_jwt).payload
+        sd_alg = (payload.is_a?(::Hash) && payload["_sd_alg"]) || "sha-256"
+        sd_hash = Digest.hash(sd_alg, selected)
+
+        extra =
+          if transaction_data && !transaction_data.empty?
+            OpenID4VP::TransactionData::SdJwtHashes.kb_claims(transaction_data)
+          else
+            {}
+          end
+
+        kb = KbJwt.build(aud: aud, nonce: nonce, sd_hash: sd_hash, key: holder_key, alg: kb_alg, iat: iat,
+                         extra: extra)
+        "#{selected}#{kb}"
+      end
+
+      def coerce_parsed(str_or_parsed)
+        str_or_parsed.is_a?(Parser::Parsed) ? str_or_parsed : Parser.parse(str_or_parsed)
+      end
+      private_class_method :coerce_parsed
+
+      def path_components(path)
+        path.respond_to?(:components) ? path.components : path
+      end
+      private_class_method :path_components
+
+      def check_typ!(header)
+        return if VALID_TYPES.include?(header["typ"])
+
+        raise OpenID4VP::PresentationInvalid, "sd-jwt: unexpected typ #{header['typ'].inspect}"
+      end
+      private_class_method :check_typ!
+
+      def resolve_issuer_key(resolver, iss, header)
+        resolved = resolver.call(iss, header)
+        raise OpenID4VP::PresentationInvalid, "sd-jwt: unknown issuer #{iss.inspect}" if resolved.nil?
+
+        resolved
+      end
+      private_class_method :resolve_issuer_key
+
+      def verify_issuer_signature(compact, header, key_or_keys, algorithms)
+        keys = key_or_keys.is_a?(::Array) ? key_or_keys : [key_or_keys]
+        raise OpenID4VP::PresentationInvalid, "sd-jwt: unknown issuer" if keys.empty?
+
+        try_keys(compact, order_by_kid(keys, header["kid"]), algorithms)
+      end
+      private_class_method :verify_issuer_signature
+
+      def order_by_kid(keys, kid)
+        return keys if kid.nil?
+
+        matching, rest = keys.partition { |k| k.kid == kid }
+        matching + rest
+      end
+      private_class_method :order_by_kid
+
+      def try_keys(compact, keys, algorithms)
+        last_error = nil
+        keys.each do |key|
+          return OpenID4VP::JOSE::JWS.verify(compact, key: key, algorithms: algorithms)
+        rescue OpenID4VP::VerificationError, OpenID4VP::InvalidRequest => e
+          last_error = e
+        end
+        raise OpenID4VP::PresentationInvalid, "sd-jwt: issuer signature verification failed: #{last_error&.message}"
+      end
+      private_class_method :try_keys
+
+      def check_time_bounds!(payload, now, leeway)
+        now_i = now.to_i
+        exp = payload["exp"]
+        if exp.is_a?(::Integer) && now_i > exp + leeway
+          raise OpenID4VP::PresentationInvalid,
+                "sd-jwt: credential expired"
+        end
+
+        nbf = payload["nbf"]
+        return unless nbf.is_a?(::Integer) && now_i < nbf - leeway
+
+        raise OpenID4VP::PresentationInvalid, "sd-jwt: credential not yet valid"
+      end
+      private_class_method :check_time_bounds!
+
+      def extract_cnf_jwk(payload)
+        jwk_hash = payload.is_a?(::Hash) ? payload.dig("cnf", "jwk") : nil
+        return nil unless jwk_hash.is_a?(::Hash)
+
+        OpenID4VP::JOSE::JWK.new(jwk_hash)
+      rescue OpenID4VP::InvalidRequest
+        nil
+      end
+      private_class_method :extract_cnf_jwk
+
+      # `require_kb` gates whether a Key Binding JWT is MANDATORY, not
+      # whether a present one gets checked: a KB-JWT that is present is
+      # always verified (and requires `cnf_jwk`), regardless of
+      # `require_kb`; only its absence is conditional on `require_kb`.
+      def verify_kb(parsed:, cnf_jwk:, expected_aud:, expected_nonce:, require_kb:, now:, leeway:, algorithms:,
+                    sd_alg:)
+        if parsed.kb_jwt.nil?
+          raise OpenID4VP::HolderBindingInvalid, "sd-jwt: key binding required but missing" if require_kb
+
+          return [nil, nil]
+        end
+
+        raise OpenID4VP::HolderBindingInvalid, "sd-jwt: cnf.jwk required for key binding" if cnf_jwk.nil?
+
+        kb_header = OpenID4VP::JOSE::JWS.peek(parsed.kb_jwt).header
+        kb_payload = KbJwt.verify(
+          parsed.kb_jwt, key: cnf_jwk, expected_aud: expected_aud, expected_nonce: expected_nonce,
+                         expected_sd_hash: parsed.sd_hash(sd_alg), now: now, leeway: leeway, algorithms: algorithms
+        )
+        [kb_payload, kb_header["alg"]]
+      end
+      private_class_method :verify_kb
+
+      def verify_transaction_data!(kb_payload, transaction_data)
+        return if transaction_data.nil? || transaction_data.empty?
+
+        if kb_payload.nil?
+          raise OpenID4VP::PresentationInvalid, "sd-jwt: transaction_data given but no key binding present"
+        end
+
+        OpenID4VP::TransactionData::SdJwtHashes.verify!(kb_payload, transaction_data)
+      end
+      private_class_method :verify_transaction_data!
+
+      def x5chain_from(header)
+        x5c = header["x5c"]
+        return nil unless x5c.is_a?(::Array)
+
+        OpenID4VP::X509.certs_from_x5c(x5c)
+      end
+      private_class_method :x5chain_from
+
+      def walk_path!(payload, components, by_digest, needed)
+        selected = [payload]
+
+        components.each do |component|
+          selected = case component
+                     when ::String then walk_key(selected, component, by_digest, needed)
+                     when nil then walk_all(selected, by_digest, needed)
+                     when ::Integer then walk_index(selected, component, by_digest, needed)
+                     else
+                       raise OpenID4VP::PresentationInvalid,
+                             "sd-jwt: unsupported claims path component #{component.inspect}"
+                     end
+
+          if selected.empty?
+            raise OpenID4VP::PresentationInvalid, "sd-jwt: cannot resolve claims path #{components.inspect}"
+          end
+        end
+      end
+      private_class_method :walk_path!
+
+      def walk_key(selected, key, by_digest, needed)
+        selected.each_with_object([]) do |node, result|
+          unless node.is_a?(::Hash)
+            raise OpenID4VP::PresentationInvalid, "sd-jwt: cannot select key #{key.inspect} on a non-object"
+          end
+
+          if node.key?(key)
+            result << node[key]
+            next
+          end
+
+          digest, disclosure = find_object_disclosure(node, key, by_digest)
+          next unless disclosure
+
+          needed[digest] = disclosure
+          result << disclosure.value
+        end
+      end
+      private_class_method :walk_key
+
+      def find_object_disclosure(node, key, by_digest)
+        sd = node["_sd"]
+        return [nil, nil] unless sd.is_a?(::Array)
+
+        sd.each do |digest|
+          disclosure = by_digest[digest]
+          return [digest, disclosure] if disclosure && !disclosure.array_element? && disclosure.name == key
+        end
+
+        [nil, nil]
+      end
+      private_class_method :find_object_disclosure
+
+      def walk_index(selected, index, by_digest, needed)
+        selected.each_with_object([]) do |node, result|
+          unless node.is_a?(::Array)
+            raise OpenID4VP::PresentationInvalid,
+                  "sd-jwt: cannot select an index on a non-array"
+          end
+          next if index >= node.size
+
+          resolve_array_element(node[index], by_digest, needed) { |value| result << value }
+        end
+      end
+      private_class_method :walk_index
+
+      def walk_all(selected, by_digest, needed)
+        selected.each_with_object([]) do |node, result|
+          unless node.is_a?(::Array)
+            raise OpenID4VP::PresentationInvalid, "sd-jwt: cannot select all elements of a non-array"
+          end
+
+          node.each { |element| resolve_array_element(element, by_digest, needed) { |value| result << value } }
+        end
+      end
+      private_class_method :walk_all
+
+      def resolve_array_element(element, by_digest, needed)
+        unless element.is_a?(::Hash) && element.size == 1 && element.key?("...")
+          yield element
+          return
+        end
+
+        digest = element["..."]
+        disclosure = by_digest[digest]
+        return unless disclosure # unknown digest: a decoy
+
+        needed[digest] = disclosure
+        yield disclosure.value
+      end
+      private_class_method :resolve_array_element
+    end
+  end
+end

data/lib/openid4vp/sd_jwt/reconstruct.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require_relative "../sd_jwt"
+require_relative "../errors"
+
+module OpenID4VP
+  module SdJwt
+    # Reconstructs the full claims of an SD-JWT from its (verified) payload
+    # and disclosures (draft-ietf-oauth-selective-disclosure-jwt-22 §5.3):
+    # object `_sd` digests and array `{"..." => digest}` items are replaced
+    # by the matching disclosure's name/value (recursively); digests that
+    # match no disclosure are decoys and are dropped; `_sd`/`_sd_alg` are
+    # removed.
+    module Reconstruct
+      module_function
+
+      # Returns `[claims, used]`, `used` being the Array of Disclosure
+      # objects that were actually referenced. Raises PresentationInvalid if
+      # the same disclosure is listed more than once, if a digest is
+      # referenced more than once, or if any of `disclosures` is never
+      # referenced.
+      def claims(payload, disclosures, alg)
+        reject_duplicate_disclosures!(disclosures)
+        by_digest = disclosures.to_h { |d| [d.digest(alg), d] }
+        used = {}
+
+        result = process(payload, by_digest, used, alg)
+
+        unused = disclosures.reject { |d| used.key?(d.digest(alg)) }
+        unless unused.empty?
+          raise OpenID4VP::PresentationInvalid,
+                "sd-jwt: disclosure(s) not referenced by any digest: #{unused.map(&:raw).join(', ')}"
+        end
+
+        [result, used.values]
+      end
+
+      # Raises PresentationInvalid when the same disclosure (identical raw
+      # string) is listed more than once in `disclosures` -- shared by
+      # `.claims` and `Presentation.select`.
+      def reject_duplicate_disclosures!(disclosures)
+        duplicates = disclosures.map(&:raw).tally.select { |_, count| count > 1 }.keys
+        return if duplicates.empty?
+
+        raise OpenID4VP::PresentationInvalid, "sd-jwt: disclosure listed more than once: #{duplicates.join(', ')}"
+      end
+
+      def process(node, by_digest, used, alg)
+        case node
+        when ::Hash then process_hash(node, by_digest, used, alg)
+        when ::Array then process_array(node, by_digest, used, alg)
+        else node
+        end
+      end
+      private_class_method :process
+
+      def process_hash(hash, by_digest, used, alg)
+        result = {}
+        hash.each do |key, value|
+          next if %w[_sd _sd_alg].include?(key)
+
+          result[key] = process(value, by_digest, used, alg)
+        end
+
+        merge_sd!(result, hash["_sd"], by_digest, used, alg)
+        result
+      end
+      private_class_method :process_hash
+
+      def merge_sd!(result, sd_digests, by_digest, used, alg)
+        return if sd_digests.nil?
+
+        raise OpenID4VP::PresentationInvalid, "sd-jwt: _sd must be an array" unless sd_digests.is_a?(::Array)
+
+        sd_digests.each do |digest|
+          disclosure = by_digest[digest]
+          next unless disclosure # unknown digest: a decoy
+
+          mark_used!(used, digest, disclosure)
+          if disclosure.array_element?
+            raise OpenID4VP::PresentationInvalid,
+                  "sd-jwt: array-element disclosure referenced from an object's _sd: #{disclosure.raw}"
+          end
+
+          if result.key?(disclosure.name)
+            raise OpenID4VP::PresentationInvalid,
+                  "sd-jwt: claim name collision: #{disclosure.name.inspect} is already present"
+          end
+
+          result[disclosure.name] = process(disclosure.value, by_digest, used, alg)
+        end
+      end
+      private_class_method :merge_sd!
+
+      def process_array(array, by_digest, used, alg)
+        array.each_with_object([]) do |element, result|
+          digest = array_element_digest(element)
+          if digest.nil?
+            result << process(element, by_digest, used, alg)
+            next
+          end
+
+          disclosure = by_digest[digest]
+          next unless disclosure # unknown digest: a decoy, dropped
+
+          mark_used!(used, digest, disclosure)
+          unless disclosure.array_element?
+            raise OpenID4VP::PresentationInvalid,
+                  "sd-jwt: object-property disclosure referenced from an array: #{disclosure.raw}"
+          end
+
+          result << process(disclosure.value, by_digest, used, alg)
+        end
+      end
+      private_class_method :process_array
+
+      def array_element_digest(element)
+        return nil unless element.is_a?(::Hash) && element.size == 1 && element.key?("...")
+
+        element["..."]
+      end
+      private_class_method :array_element_digest
+
+      def mark_used!(used, digest, disclosure)
+        raise OpenID4VP::PresentationInvalid, "sd-jwt: digest used more than once: #{digest}" if used.key?(digest)
+
+        used[digest] = disclosure
+      end
+      private_class_method :mark_used!
+    end
+  end
+end

data/lib/openid4vp/sd_jwt.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module OpenID4VP
+  # IETF SD-JWT VC (OpenID4VP Appendix B.3): parsing, digest computation,
+  # claims reconstruction, selective disclosure, issuance and Key Binding
+  # JWT handling for the `dc+sd-jwt` Credential Format, per
+  # draft-ietf-oauth-selective-disclosure-jwt-22.
+  module SdJwt
+  end
+end

data/lib/openid4vp/transaction_data/registry.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "../transaction_data"
+
+module OpenID4VP
+  module TransactionData
+    # A wallet- or verifier-side registry of supported transaction_data
+    # types (OpenID4VP §8.4). Each type may be registered with an optional
+    # validator that checks the type-specific fields of the decoded entry.
+    class Registry
+      def initialize
+        @validators = {}
+      end
+
+      # Registers `type` as supported. `validator` (or `block`) is an
+      # optional callable invoked with the entry's decoded `data` Hash; it
+      # should raise InvalidTransactionData for bad type-specific fields.
+      # Registering with neither means "type supported, no extra checks".
+      def register(type, validator = nil, &block)
+        @validators[type] = validator || block
+        self
+      end
+
+      def supports?(type)
+        @validators.key?(type)
+      end
+
+      # Raises InvalidTransactionData when `entry.type` is not registered,
+      # or when its registered validator rejects `entry.data`. Returns
+      # `entry` on success.
+      def validate!(entry)
+        unless supports?(entry.type)
+          raise OpenID4VP::InvalidTransactionData, "unsupported transaction data type: #{entry.type}"
+        end
+
+        @validators[entry.type]&.call(entry.data)
+
+        entry
+      end
+    end
+  end
+end

data/lib/openid4vp/transaction_data/sd_jwt_hashes.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require_relative "../transaction_data"
+require_relative "../util"
+require_relative "../util/base64url"
+
+module OpenID4VP
+  module TransactionData
+    # OpenID4VP §B.3.3.1: the `transaction_data_hashes` / `transaction_data_hashes_alg`
+    # profile of transaction data in SD-JWT VC Key Binding JWTs.
+    module SdJwtHashes
+      # IANA "Named Information Hash Algorithm" identifiers this gem
+      # supports, mapped to their OpenSSL::Digest name.
+      ALGS = {
+        "sha-256" => "SHA256",
+        "sha-384" => "SHA384",
+        "sha-512" => "SHA512"
+      }.freeze
+
+      module_function
+
+      # base64url(hash(entry.raw)) for each entry, in order, using `alg`
+      # (default sha-256; base64url decoding of `raw` is NOT performed
+      # before hashing, per §B.3.3.1).
+      def compute(entries, alg: "sha-256")
+        digest_name = digest_name_for(alg)
+
+        entries.map { |entry| OpenID4VP::Util::Base64url.encode(::OpenSSL::Digest.digest(digest_name, entry.raw)) }
+      end
+
+      # Builds the Key Binding JWT top-level claims for `entries`:
+      # `transaction_data_hashes` (via #compute) and, only when at least one
+      # entry declared `transaction_data_hashes_alg`, `transaction_data_hashes_alg`
+      # itself. `alg`, when given, is used as-is; otherwise the first
+      # algorithm (in ALGS order) supported by this gem and permitted by
+      # every declaring entry is chosen, defaulting to sha-256.
+      def kb_claims(entries, alg: nil)
+        chosen = alg || pick_alg(entries)
+        claims = { "transaction_data_hashes" => compute(entries, alg: chosen) }
+        claims["transaction_data_hashes_alg"] = chosen if entries.any?(&:transaction_data_hashes_alg)
+        claims
+      end
+
+      # Verifies a Key Binding JWT payload's transaction data hashes against
+      # `entries` (same length and order required). Raises
+      # PresentationInvalid on any mismatch, missing hashes, or a
+      # disallowed/missing `transaction_data_hashes_alg`. Returns true on
+      # success (the task interface mandates a boolean, not the payload).
+      # rubocop:disable-next Naming/PredicateMethod
+      def verify!(kb_payload, entries)
+        hashes = kb_payload["transaction_data_hashes"]
+        unless hashes.is_a?(::Array) && hashes.length == entries.length
+          raise OpenID4VP::PresentationInvalid,
+                "transaction_data_hashes missing or does not match the requested transaction_data entries"
+        end
+
+        alg = resolve_verify_alg(kb_payload, entries)
+        expected = compute(entries, alg: alg)
+
+        expected.each_with_index do |expected_hash, index|
+          actual = hashes[index]
+          next if actual.is_a?(::String) && OpenID4VP::Util.secure_compare(expected_hash, actual)
+
+          raise OpenID4VP::PresentationInvalid, "transaction_data_hashes[#{index}] does not match"
+        end
+
+        true
+      end
+
+      def digest_name_for(alg)
+        ALGS.fetch(alg) { raise OpenID4VP::InvalidTransactionData, "unsupported hash algorithm: #{alg.inspect}" }
+      end
+      private_class_method :digest_name_for
+
+      def pick_alg(entries)
+        declaring = entries.select(&:transaction_data_hashes_alg)
+        return "sha-256" if declaring.empty?
+
+        common = ALGS.each_key.find do |candidate|
+          declaring.all? { |entry| entry.transaction_data_hashes_alg.include?(candidate) }
+        end
+        common || "sha-256"
+      end
+      private_class_method :pick_alg
+
+      # OpenID4VP §B.3.3.1: "If transaction_data_hashes_alg was not
+      # specified in the request, the hash function MUST be sha-256." /
+      # "If transaction_data_hashes_alg was specified in the request, the
+      # hash function MUST be one of its values." Also rejects any alg this
+      # gem does not support (i.e. not in ALGS) before it ever reaches
+      # #compute.
+      def resolve_verify_alg(kb_payload, entries)
+        declaring = entries.select(&:transaction_data_hashes_alg)
+        alg = kb_payload["transaction_data_hashes_alg"]
+
+        alg = declaring.empty? ? resolve_unrequested_alg(alg) : resolve_requested_alg(alg, declaring)
+
+        unless ALGS.key?(alg)
+          raise OpenID4VP::PresentationInvalid, "unsupported transaction_data_hashes_alg: #{alg.inspect}"
+        end
+
+        alg
+      end
+      private_class_method :resolve_verify_alg
+
+      def resolve_unrequested_alg(alg)
+        return "sha-256" if alg.nil? || alg == "sha-256"
+
+        raise OpenID4VP::PresentationInvalid, "transaction_data_hashes_alg not requested"
+      end
+      private_class_method :resolve_unrequested_alg
+
+      def resolve_requested_alg(alg, declaring)
+        if alg.nil? || !declaring.all? { |entry| entry.transaction_data_hashes_alg.include?(alg) }
+          raise OpenID4VP::PresentationInvalid,
+                "transaction_data_hashes_alg #{alg.inspect} is not permitted by the requested transaction_data"
+        end
+
+        alg
+      end
+      private_class_method :resolve_requested_alg
+    end
+  end
+end