openid4vp 0.1.0

data/lib/openid4vp/dcql/evaluator.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+require_relative "../dcql"
+require_relative "../errors"
+require_relative "../credential"
+require_relative "meta"
+require_relative "matcher"
+require_relative "selection"
+
+module OpenID4VP
+  module DCQL
+    # OpenID4VP §6.4: evaluates a DCQL Query against a Wallet's available
+    # Credentials, selecting matching Credentials and claims (§6.4.1,
+    # §6.4.2). Also verifies, from the Verifier side, that a decoded
+    # response actually satisfies a Query (`.check_response!`).
+    class Evaluator
+      def initialize(query, credentials, hooks: {})
+        @query = query
+        @credentials = credentials
+        @hooks = hooks
+      end
+
+      def evaluate
+        matches_by_id = @query.credentials.to_h do |credential_query|
+          [credential_query.id, matches_for(credential_query)]
+        end
+
+        @query.credential_sets ? select_with_sets(matches_by_id) : select_without_sets(matches_by_id)
+      end
+
+      class << self
+        # presentations: {credential_query_id => [presentation]}, each
+        # presentation responding to #format and #claims. Raises
+        # OpenID4VP::QueryNotSatisfied naming the id/reason, or returns true.
+        # Named `!` (raises) rather than `?` per the DCQL evaluator interface.
+        # rubocop:disable-next Naming/PredicateMethod
+        def check_response!(query, presentations)
+          check_ids_known!(query, presentations)
+          check_multiple_and_claims!(query, presentations)
+          check_credential_sets!(query, presentations)
+          true
+        end
+
+        private
+
+        def check_ids_known!(query, presentations)
+          presentations.each_key do |id|
+            next if query.ids.include?(id)
+
+            raise OpenID4VP::QueryNotSatisfied, "response includes unknown credential id #{id.inspect}"
+          end
+        end
+
+        def check_multiple_and_claims!(query, presentations)
+          query.credentials.each do |credential_query|
+            creds = presentations[credential_query.id]
+            next if creds.nil? || creds.empty?
+
+            if !credential_query.multiple && creds.size != 1
+              raise OpenID4VP::QueryNotSatisfied,
+                    "credential id #{credential_query.id.inspect} expects exactly one presentation, got #{creds.size}"
+            end
+
+            creds.each { |presentation| check_claims!(credential_query, presentation) }
+          end
+        end
+
+        def check_claims!(credential_query, presentation)
+          credential = OpenID4VP::Credential.new(format: presentation.format, claims: presentation.claims)
+          return if credential_query.claims.nil?
+
+          if credential_query.claim_sets.nil?
+            check_all_claims_present!(credential_query, credential)
+          else
+            check_claim_sets_satisfied!(credential_query, credential)
+          end
+        end
+
+        def check_all_claims_present!(credential_query, credential)
+          missing = credential_query.claims.reject { |claims_query| Matcher.claim_present?(claims_query, credential) }
+          return if missing.empty?
+
+          raise OpenID4VP::QueryNotSatisfied,
+                "credential id #{credential_query.id.inspect} is missing claim(s) #{missing.map(&:id).inspect}"
+        end
+
+        def check_claim_sets_satisfied!(credential_query, credential)
+          satisfied = credential_query.claim_sets.any? do |ids|
+            ids.all? { |id| Matcher.claim_present?(credential_query.claim(id), credential) }
+          end
+          return if satisfied
+
+          raise OpenID4VP::QueryNotSatisfied,
+                "credential id #{credential_query.id.inspect} does not satisfy any claim_sets option"
+        end
+
+        def check_credential_sets!(query, presentations)
+          satisfied_ids = presentations.reject { |_id, creds| creds.nil? || creds.empty? }.keys
+
+          if query.credential_sets.nil?
+            missing = query.ids - satisfied_ids
+            return if missing.empty?
+
+            raise OpenID4VP::QueryNotSatisfied, "response is missing required credential(s) #{missing.inspect}"
+          end
+
+          query.credential_sets.each do |credential_set_query|
+            next unless credential_set_query.required
+            next if credential_set_query.options.any? { |ids| ids.all? { |id| satisfied_ids.include?(id) } }
+
+            raise OpenID4VP::QueryNotSatisfied,
+                  "response does not satisfy required credential_set options #{credential_set_query.options.inspect}"
+          end
+
+          check_unreferenced_ids!(query, satisfied_ids)
+        end
+
+        # Ids not referenced by any credential_sets option are always
+        # required, mirroring Evaluator#select_unreferenced_ids.
+        def check_unreferenced_ids!(query, satisfied_ids)
+          referenced = query.credential_sets.flat_map { |cs| cs.options.flatten(1) }.uniq
+          missing = query.ids - referenced - satisfied_ids
+          return if missing.empty?
+
+          raise OpenID4VP::QueryNotSatisfied,
+                "response is missing required credential(s) #{missing.inspect}"
+        end
+      end
+
+      private
+
+      def matches_for(credential_query)
+        candidates = @credentials.select { |credential| candidate?(credential_query, credential) }
+        matches = candidates.filter_map { |credential| build_match(credential_query, credential) }
+        credential_query.multiple ? matches : matches.first(1)
+      end
+
+      def candidate?(credential_query, credential)
+        return false unless credential.format == credential_query.format
+        return false unless Meta.matches?(credential_query.format, credential_query.meta, credential)
+        return false unless trusted_authorities_ok?(credential_query, credential)
+        return true if credential_query.require_cryptographic_holder_binding == false
+
+        credential.holder_bindable?
+      end
+
+      def trusted_authorities_ok?(credential_query, credential)
+        return true unless credential_query.trusted_authorities
+
+        credential_query.trusted_authorities.any? { |ta| Matcher.authority_matches?(ta, credential, hooks: @hooks) }
+      end
+
+      def build_match(credential_query, credential)
+        if credential_query.claims.nil?
+          Match.new(credential: credential, claims: [], credential_query: credential_query)
+        elsif credential_query.claim_sets.nil?
+          build_match_all_claims(credential_query, credential)
+        else
+          build_match_claim_sets(credential_query, credential)
+        end
+      end
+
+      def build_match_all_claims(credential_query, credential)
+        all_present = credential_query.claims.all? { |claims_query| Matcher.claim_present?(claims_query, credential) }
+        return nil unless all_present
+
+        Match.new(credential: credential, claims: credential_query.claims, credential_query: credential_query)
+      end
+
+      def build_match_claim_sets(credential_query, credential)
+        option = credential_query.claim_sets.find do |ids|
+          ids.all? { |id| Matcher.claim_present?(credential_query.claim(id), credential) }
+        end
+        return nil unless option
+
+        selected_claims = option.map { |id| credential_query.claim(id) }
+        Match.new(credential: credential, claims: selected_claims, credential_query: credential_query)
+      end
+
+      def select_without_sets(matches_by_id)
+        chosen = {}
+        missing = []
+        matches_by_id.each do |id, matches|
+          matches.empty? ? missing << id : chosen[id] = matches
+        end
+
+        Selection.new(matches: chosen, missing: missing)
+      end
+
+      def select_with_sets(matches_by_id)
+        chosen = {}
+        missing = []
+        satisfied_sets = []
+        unsatisfied_required_sets = []
+
+        @query.credential_sets.each do |credential_set_query|
+          option = credential_set_query.options.find do |ids|
+            ids.all? { |id| matches_by_id[id] && !matches_by_id[id].empty? }
+          end
+          if option
+            satisfied_sets << credential_set_query
+            option.each { |id| chosen[id] = matches_by_id[id] }
+          elsif credential_set_query.required
+            unsatisfied_required_sets << credential_set_query
+            missing.concat(credential_set_query.options.first)
+          end
+        end
+
+        select_unreferenced_ids(matches_by_id, chosen, missing)
+
+        Selection.new(
+          matches: chosen, missing: missing.uniq,
+          satisfied_sets: satisfied_sets, unsatisfied_required_sets: unsatisfied_required_sets
+        )
+      end
+
+      # Ids not referenced by any credential_sets option are always
+      # required, mirroring the no-credential_sets behavior for them.
+      def select_unreferenced_ids(matches_by_id, chosen, missing)
+        referenced = @query.credential_sets.flat_map { |cs| cs.options.flatten(1) }.uniq
+        (@query.ids - referenced).each do |id|
+          matches = matches_by_id[id]
+          matches && !matches.empty? ? chosen[id] = matches : missing << id
+        end
+      end
+    end
+  end
+end

data/lib/openid4vp/dcql/matcher.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "../dcql"
+require_relative "../errors"
+require_relative "claims_path_pointer"
+require_relative "../x509"
+require_relative "../util/base64url"
+
+module OpenID4VP
+  module DCQL
+    # OpenID4VP §6.3-6.4 claim presence/value matching and §6.1.1 trusted
+    # authorities matching used by `DCQL::Evaluator`.
+    module Matcher
+      module_function
+
+      # §6.3: "the Wallet SHOULD return the claim only if the type and value
+      # of the claim both match exactly for at least one of the elements".
+      # Plain Ruby `==` is not enough (1 == 1.0), so types must match too.
+      def values_match?(values, actual)
+        return false if values.nil? || actual.nil?
+
+        values.any? { |value| value.instance_of?(actual.class) && value == actual }
+      end
+
+      # Returns the selected elements (an Array) for `claims_query` against
+      # `credential`, or nil when the claim is absent, its path cannot be
+      # resolved, or its `values` restriction does not match. Named per the
+      # DCQL evaluator interface, not a boolean predicate.
+      # rubocop:disable-next Naming/PredicateMethod, Style/ReturnNilInPredicateMethodDefinition
+      def claim_present?(claims_query, credential)
+        selected = select_claim(claims_query, credential)
+        return nil if selected.nil?
+        return nil if claims_query.values && selected.none? { |element| values_match?(claims_query.values, element) }
+
+        selected
+      end
+
+      # §6.1.1: a Credential matches a single Trusted Authorities Query when
+      # it matches one of its `values` under its `type`.
+      def authority_matches?(ta_query, credential, hooks: {})
+        case ta_query.type
+        when "aki" then aki_match?(ta_query, credential)
+        else
+          hook = hooks[ta_query.type]
+          hook ? !!hook.call(ta_query, credential) : false
+        end
+      end
+
+      def select_claim(claims_query, credential)
+        path = claims_query.path
+        if credential.format == "mso_mdoc"
+          mdoc_claim(path, credential)
+        else
+          path.select(credential.claims)
+        end
+      rescue ClaimsPathPointer::Error
+        nil
+      end
+      private_class_method :select_claim
+
+      def mdoc_claim(path, credential)
+        namespace, element = path.mdoc_components
+        value = credential.claims.dig(namespace, element)
+        value.nil? ? nil : [value]
+      end
+      private_class_method :mdoc_claim
+
+      def aki_match?(ta_query, credential)
+        credential.x5chain.any? do |cert|
+          aki = OpenID4VP::X509.authority_key_identifier(cert)
+          next false unless aki
+
+          ta_query.values.include?(OpenID4VP::Util::Base64url.encode(aki))
+        end
+      end
+      private_class_method :aki_match?
+    end
+  end
+end

data/lib/openid4vp/dcql/meta.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative "../dcql"
+require_relative "../errors"
+
+module OpenID4VP
+  module DCQL
+    # OpenID4VP Appendix B: format-specific `meta` matching (used by
+    # `DCQL::Evaluator`) and validation for DCQL Credential Queries.
+    module Meta
+      module_function
+
+      def matches?(format, meta, credential)
+        return true if meta.nil? || meta.empty?
+
+        case format
+        when "dc+sd-jwt" then vct_values_match?(meta, credential)
+        when "mso_mdoc" then meta["doctype_value"] == credential.metadata["doctype"]
+        when "jwt_vc_json", "ldp_vc" then type_values_match?(meta, credential)
+        else generic_match?(meta, credential)
+        end
+      end
+
+      # Appendix B: validates the REQUIRED shape of format-specific meta
+      # parameters. Unknown formats: meta must be a Hash, nothing else
+      # checked.
+      def validate!(format, meta)
+        raise OpenID4VP::InvalidRequest, "meta must be an object" unless meta.is_a?(::Hash)
+
+        case format
+        when "dc+sd-jwt" then validate_vct_values!(meta)
+        when "mso_mdoc" then validate_doctype_value!(meta)
+        when "jwt_vc_json", "ldp_vc" then validate_type_values!(meta)
+        end
+      end
+
+      def vct_values_match?(meta, credential)
+        values = meta["vct_values"]
+        return true unless values
+
+        vct = credential.metadata["vct"] || credential.claims["vct"]
+        values.include?(vct)
+      end
+      private_class_method :vct_values_match?
+
+      def type_values_match?(meta, credential)
+        values = meta["type_values"]
+        return true unless values
+
+        types = credential_types(credential)
+        return false if types.nil?
+
+        values.any? { |option| (option - types).empty? }
+      end
+      private_class_method :type_values_match?
+
+      def credential_types(credential)
+        types = credential.metadata["type"] || credential.claims.dig("vc", "type") || credential.claims["type"]
+        return nil if types.nil?
+
+        types.is_a?(::String) ? [types] : types
+      end
+      private_class_method :credential_types
+
+      def generic_match?(meta, credential)
+        meta.all? do |key, value|
+          actual = credential.metadata[key]
+          actual == value || (actual.is_a?(::Array) && actual.include?(value))
+        end
+      end
+      private_class_method :generic_match?
+
+      def validate_vct_values!(meta)
+        values = meta["vct_values"]
+        valid = values.is_a?(::Array) && !values.empty? && values.all?(::String)
+        raise OpenID4VP::InvalidRequest, "meta.vct_values must be a non-empty array of strings" unless valid
+      end
+      private_class_method :validate_vct_values!
+
+      def validate_doctype_value!(meta)
+        return if meta["doctype_value"].is_a?(::String) && !meta["doctype_value"].empty?
+
+        raise OpenID4VP::InvalidRequest, "meta.doctype_value must be a non-empty string"
+      end
+      private_class_method :validate_doctype_value!
+
+      def validate_type_values!(meta)
+        values = meta["type_values"]
+        valid = values.is_a?(::Array) && !values.empty? && values.all? do |inner|
+          inner.is_a?(::Array) && !inner.empty? && inner.all?(::String)
+        end
+        return if valid
+
+        raise OpenID4VP::InvalidRequest, "meta.type_values must be a non-empty array of non-empty string arrays"
+      end
+      private_class_method :validate_type_values!
+    end
+  end
+end

data/lib/openid4vp/dcql/query.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative "../dcql"
+require_relative "../errors"
+require_relative "credential_query"
+require_relative "credential_set_query"
+
+module OpenID4VP
+  module DCQL
+    # OpenID4VP §6: the top-level DCQL query object, e.g. the value of the
+    # dcql_query Authorization Request parameter.
+    class Query
+      KNOWN_KEYS = %w[credentials credential_sets].freeze
+
+      attr_reader :credentials, :credential_sets, :extra
+
+      def initialize(credentials:, credential_sets: nil, extra: {})
+        @credentials = build_credentials(credentials)
+        @credential_sets = build_credential_sets(credential_sets, @credentials)
+        @extra = extra.dup.freeze
+      end
+
+      def self.from_h(hash)
+        raise OpenID4VP::InvalidRequest, "dcql query must be an object" unless hash.is_a?(::Hash)
+
+        new(
+          credentials: hash["credentials"],
+          credential_sets: hash["credential_sets"],
+          extra: hash.except(*KNOWN_KEYS)
+        )
+      end
+
+      def self.from_json(str)
+        from_h(::JSON.parse(str))
+      end
+
+      def credential(id)
+        credentials.find { |credential_query| credential_query.id == id }
+      end
+
+      def ids
+        credentials.map(&:id)
+      end
+
+      def to_h
+        h = { "credentials" => credentials.map(&:to_h) }
+        h["credential_sets"] = credential_sets.map(&:to_h) if credential_sets
+        h.merge(extra)
+      end
+
+      private
+
+      def build_credentials(credentials)
+        unless credentials.is_a?(::Array) && !credentials.empty?
+          raise OpenID4VP::InvalidRequest, "credentials must be a non-empty array"
+        end
+
+        built = credentials.map { |entry| entry.is_a?(CredentialQuery) ? entry : CredentialQuery.from_h(entry) }
+
+        ids = built.map(&:id)
+        raise OpenID4VP::InvalidRequest, "credentials ids must be unique" if ids.uniq.size != ids.size
+
+        built.freeze
+      end
+
+      def build_credential_sets(credential_sets, credentials)
+        return nil if credential_sets.nil?
+
+        unless credential_sets.is_a?(::Array) && !credential_sets.empty?
+          raise OpenID4VP::InvalidRequest, "credential_sets must be a non-empty array"
+        end
+
+        credential_ids = credentials.map(&:id)
+        built = credential_sets.map do |entry|
+          entry.is_a?(CredentialSetQuery) ? entry : CredentialSetQuery.from_h(entry)
+        end
+        built.each { |credential_set_query| validate_credential_set_references(credential_set_query, credential_ids) }
+
+        built.freeze
+      end
+
+      def validate_credential_set_references(credential_set_query, credential_ids)
+        credential_set_query.options.each do |option|
+          option.each do |id|
+            next if credential_ids.include?(id)
+
+            raise OpenID4VP::InvalidRequest, "credential_sets references unknown credential id #{id.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/openid4vp/dcql/selection.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "../dcql"
+
+module OpenID4VP
+  module DCQL
+    # A single Credential chosen for a `CredentialQuery`, together with the
+    # `ClaimsQuery` entries (from `claims` or the winning `claim_sets`
+    # option) that were selected for it. Carries no claim values: callers
+    # resolve those from `credential` via `Matcher.claim_present?`.
+    Match = Struct.new(:credential, :claims, :credential_query, keyword_init: true)
+
+    # OpenID4VP §6.4.2: the result of evaluating a DCQL Query against a set
+    # of available Credentials.
+    class Selection
+      # {credential_query_id => [Match]}, only for ids that are part of the
+      # chosen result (with credential_sets, ids only referenced by
+      # unsatisfiable optional sets are excluded).
+      attr_reader :matches
+
+      # [credential_query_id], the required ids/options that could not be
+      # satisfied.
+      attr_reader :missing
+
+      # [CredentialSetQuery] the credential_sets entries (required or
+      # optional) for which a satisfying option was found.
+      attr_reader :satisfied_sets
+
+      # [CredentialSetQuery] the required credential_sets entries for which
+      # no option could be satisfied.
+      attr_reader :unsatisfied_required_sets
+
+      def initialize(matches:, missing:, satisfied_sets: [], unsatisfied_required_sets: [])
+        @matches = matches
+        @missing = missing
+        @satisfied_sets = satisfied_sets
+        @unsatisfied_required_sets = unsatisfied_required_sets
+      end
+
+      def satisfiable?
+        missing.empty? && unsatisfied_required_sets.empty?
+      end
+    end
+  end
+end

data/lib/openid4vp/dcql/trusted_authorities_query.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "../dcql"
+require_relative "../errors"
+
+module OpenID4VP
+  module DCQL
+    # OpenID4VP §6.1.1: identifies an authority or trust framework that
+    # certifies Issuers a Credential must match.
+    class TrustedAuthoritiesQuery
+      # Type Identifiers defined by the specification (§6.1.1.1-3). Other
+      # string values are accepted and preserved for future extensions.
+      TYPES = %w[aki etsi_tl openid_federation].freeze
+
+      KNOWN_KEYS = %w[type values].freeze
+
+      attr_reader :type, :values, :extra
+
+      def initialize(type:, values:, extra: {})
+        unless type.is_a?(::String) && !type.empty?
+          raise OpenID4VP::InvalidRequest, "trusted_authorities[].type must be a non-empty string"
+        end
+
+        unless values.is_a?(::Array) && !values.empty? && values.all?(::String)
+          raise OpenID4VP::InvalidRequest, "trusted_authorities[].values must be a non-empty array of strings"
+        end
+
+        @type = type
+        @values = values.dup.freeze
+        @extra = extra.dup.freeze
+      end
+
+      def self.from_h(hash)
+        raise OpenID4VP::InvalidRequest, "trusted_authorities[] entry must be an object" unless hash.is_a?(::Hash)
+
+        new(
+          type: hash["type"],
+          values: hash["values"],
+          extra: hash.except(*KNOWN_KEYS)
+        )
+      end
+
+      def to_h
+        { "type" => type, "values" => values.dup }.merge(extra)
+      end
+    end
+  end
+end

data/lib/openid4vp/dcql.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module OpenID4VP
+  # Digital Credentials Query Language (OpenID4VP §6-7): the JSON-encoded
+  # query language a Verifier uses to request Credentials and claims from a
+  # Wallet, plus the Claims Path Pointer used to address claims within a
+  # Credential.
+  module DCQL
+  end
+end

data/lib/openid4vp/encoded_response.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module OpenID4VP
+  # The shape returned by AuthorizationResponse#encode and
+  # ErrorResponse#encode: which members are set depends on the Response
+  # Mode encoded for (`url` for fragment/query, `form_body`/`form_params`
+  # for direct_post[.jwt], `data` for dc_api[.jwt], `jwe` in addition to
+  # `form_params`/`data` for the encrypted `.jwt` modes).
+  EncodedResponse = Struct.new(:mode, :url, :form_body, :form_params, :data, :jwe, keyword_init: true)
+end