openid4vp 0.1.0

data/lib/openid4vp/dc_api.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require_relative "request_object"
+require_relative "authorization_request"
+require_relative "client_id"
+require_relative "errors"
+require_relative "jose/jws"
+
+module OpenID4VP
+  # OpenID4VP Appendix A: OpenID4VP over the W3C Digital Credentials API
+  # (DC API). The DC API passes the request as a `{protocol, data}` object
+  # instead of a URL; this module wraps an AuthorizationRequest into that
+  # shape (Appendix A.1/A.3) and parses it back on the Wallet side,
+  # enforcing the `expected_origins` check of Appendix A.2. It does NOT
+  # verify any signature -- that happens once the caller has resolved the
+  # signer's key material.
+  module DcApi
+    PROTOCOLS = {
+      unsigned: "openid4vp-v1-unsigned",
+      signed: "openid4vp-v1-signed",
+      multisigned: "openid4vp-v1-multisigned"
+    }.freeze
+
+    # `requests` is nil for unsigned (there is no Request Object), the
+    # single-element `[RequestObject::Parsed]` for signed, or one
+    # `RequestObject::Parsed` per Client Identifier for multisigned.
+    # `request` is the effective AuthorizationRequest (unsigned: built
+    # straight from `data`; signed/multisigned: the first Parsed's).
+    ParsedDcApiRequest = Struct.new(:protocol, :requests, :request, :signed, keyword_init: true)
+
+    module_function
+
+    # Appendix A.3.1: an unsigned request. client_id and expected_origins
+    # are signed-request-only and MUST be omitted (the Wallet ignores them
+    # if present).
+    def unsigned_request(request)
+      { "protocol" => PROTOCOLS[:unsigned], "data" => request.to_h.except("client_id", "expected_origins") }
+    end
+
+    # Appendix A.3.2.1 (JWS Compact Serialization). `signer` is a callable
+    # receiving `request` and returning a compact JWS, e.g. Task 25's
+    # `->(r) { request_signer.sign(r) }`.
+    def signed_request(request, signer:)
+      { "protocol" => PROTOCOLS[:signed], "data" => { "request" => signer.call(request) } }
+    end
+
+    # Appendix A.3.2.2 (JWS JSON Serialization). `signers` is an Array of
+    # `{key:, alg:, header:}`, one per Client Identifier; each `header` MUST
+    # carry "client_id" and MAY carry "verifier_info", "trust_chain", "x5c"
+    # or "jwt". The shared payload omits the header-only params.
+    def multisigned_request(request, signers:)
+      payload = request.to_h.except(*OpenID4VP::RequestObject::HEADER_ONLY_PARAMS)
+      jws = OpenID4VP::JOSE::JWS.sign_json(payload, signers: signers.map { |signer| multisigned_signer(signer) })
+      { "protocol" => PROTOCOLS[:multisigned], "data" => jws }
+    end
+
+    # Parses a `{protocol, data}` DC API request. Raises InvalidRequest for
+    # an unsupported protocol, malformed `data`, or (signed/multisigned)
+    # when `origin` is not among the request's `expected_origins`.
+    def parse_request(protocol, data, origin:)
+      case protocol
+      when PROTOCOLS[:unsigned] then parse_unsigned(data)
+      when PROTOCOLS[:signed] then parse_signed(data, origin)
+      when PROTOCOLS[:multisigned] then parse_multisigned(data, origin)
+      else raise OpenID4VP::InvalidRequest, "unsupported DC API protocol #{protocol.inspect}"
+      end
+    end
+
+    # Appendix A.4: the audience for a DC API response is the Origin,
+    # prefixed with "origin:".
+    def audience(origin)
+      OpenID4VP::ClientId.origin(origin).to_s
+    end
+
+    def multisigned_signer(signer)
+      header = { "typ" => OpenID4VP::RequestObject::TYP }.merge(signer[:header] || {})
+      { key: signer.fetch(:key), alg: signer[:alg], header: header }
+    end
+    private_class_method :multisigned_signer
+
+    def parse_unsigned(data)
+      raise OpenID4VP::InvalidRequest, "DC API request data must be an object" unless data.is_a?(::Hash)
+
+      request = OpenID4VP::AuthorizationRequest.new(data.except("client_id", "expected_origins"))
+      ParsedDcApiRequest.new(protocol: PROTOCOLS[:unsigned], requests: nil, request: request, signed: false)
+    end
+    private_class_method :parse_unsigned
+
+    def parse_signed(data, origin)
+      unless data.is_a?(::Hash) && data["request"].is_a?(::String)
+        raise OpenID4VP::InvalidRequest, "DC API signed request data must be an object with a request string"
+      end
+
+      parsed = OpenID4VP::RequestObject.parse(data["request"])
+      check_expected_origins!(parsed.request, origin)
+      ParsedDcApiRequest.new(protocol: PROTOCOLS[:signed], requests: [parsed], request: parsed.request, signed: true)
+    end
+    private_class_method :parse_signed
+
+    def parse_multisigned(data, origin)
+      requests = OpenID4VP::RequestObject.parse_json(data)
+      request = requests.first.request
+      check_expected_origins!(request, origin)
+      ParsedDcApiRequest.new(protocol: PROTOCOLS[:multisigned], requests: requests, request: request, signed: true)
+    end
+    private_class_method :parse_multisigned
+
+    def check_expected_origins!(request, origin)
+      origins = request.expected_origins
+      return if origins.is_a?(::Array) && !origins.empty? && origins.include?(origin)
+
+      raise OpenID4VP::InvalidRequest, "origin not expected"
+    end
+    private_class_method :check_expected_origins!
+  end
+end

data/lib/openid4vp/dcql/claims_path_pointer.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative "../dcql"
+require_relative "../errors"
+
+module OpenID4VP
+  module DCQL
+    # OpenID4VP §7: a Claims Path Pointer is a non-empty array of strings,
+    # nulls and non-negative integers that addresses one or more claims
+    # within a Credential.
+    class ClaimsPathPointer
+      # Raised when processing a pointer against a Credential fails (§7.1.1,
+      # §7.2.1). Not a wire-level protocol error on its own (code is nil).
+      class Error < OpenID4VP::Error; end
+
+      attr_reader :components
+
+      def initialize(components)
+        unless components.is_a?(::Array) && !components.empty?
+          raise OpenID4VP::InvalidRequest, "claims path pointer must be a non-empty array"
+        end
+
+        components.each { |component| validate_component(component) }
+
+        @components = components.dup.freeze
+      end
+
+      # OpenID4VP §7.1.1: process the pointer against a JSON-based Credential
+      # (a Hash/Array/scalar tree, e.g. from JSON.parse). Returns the array
+      # of selected elements, or raises Error.
+      def select(json)
+        selected = [json]
+
+        components.each do |component|
+          selected = case component
+                     when ::String then select_key(selected, component)
+                     when nil then select_all(selected)
+                     when ::Integer then select_index(selected, component)
+                     end
+
+          raise Error, "claims path pointer selection is empty" if selected.empty?
+        end
+
+        selected
+      end
+
+      # OpenID4VP §7.2.1: extract the [namespace, element_identifier] pair
+      # for an ISO mdoc-based Credential.
+      def mdoc_components
+        unless components.size == 2 && components.all?(::String)
+          raise Error, "mdoc claims path pointer must contain exactly two string components"
+        end
+
+        components
+      end
+
+      def to_a
+        components.dup
+      end
+
+      def to_s
+        ::JSON.generate(components)
+      end
+
+      def ==(other)
+        other.is_a?(self.class) && components == other.components
+      end
+      alias eql? ==
+
+      def hash
+        components.hash
+      end
+
+      private
+
+      def validate_component(component)
+        return if component.nil? || component.is_a?(::String)
+        return if component.is_a?(::Integer) && component >= 0
+
+        raise OpenID4VP::InvalidRequest,
+              "claims path pointer component must be a string, null, or non-negative integer, got: #{component.inspect}"
+      end
+
+      def select_key(selected, key)
+        selected.each_with_object([]) do |element, result|
+          raise Error, "cannot select key #{key.inspect} on a non-object element" unless element.is_a?(::Hash)
+
+          result << element[key] if element.key?(key)
+        end
+      end
+
+      def select_all(selected)
+        selected.each do |element|
+          raise Error, "cannot select all elements of a non-array element" unless element.is_a?(::Array)
+        end
+
+        selected.flat_map { |element| element }
+      end
+
+      def select_index(selected, index)
+        selected.each_with_object([]) do |element, result|
+          raise Error, "cannot select index #{index} of a non-array element" unless element.is_a?(::Array)
+
+          result << element[index] if index < element.size
+        end
+      end
+    end
+  end
+end

data/lib/openid4vp/dcql/claims_query.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative "../dcql"
+require_relative "../errors"
+require_relative "claims_path_pointer"
+
+module OpenID4VP
+  module DCQL
+    # OpenID4VP §6.3: specifies a claim within a requested Credential.
+    class ClaimsQuery
+      ID_PATTERN = /\A[A-Za-z0-9_-]+\z/
+
+      KNOWN_KEYS = %w[id path values intent_to_retain].freeze
+
+      attr_reader :id, :path, :values, :intent_to_retain, :extra
+
+      def initialize(path:, id: nil, values: nil, intent_to_retain: nil, extra: {})
+        validate_id(id)
+        validate_values(values)
+        validate_intent_to_retain(intent_to_retain)
+
+        @id = id
+        @path = path.is_a?(ClaimsPathPointer) ? path : ClaimsPathPointer.new(path)
+        @values = values&.dup&.freeze
+        @intent_to_retain = intent_to_retain
+        @extra = extra.dup.freeze
+      end
+
+      def self.from_h(hash)
+        raise OpenID4VP::InvalidRequest, "claims[] entry must be an object" unless hash.is_a?(::Hash)
+
+        new(
+          id: hash["id"],
+          path: hash["path"],
+          values: hash["values"],
+          intent_to_retain: hash["intent_to_retain"],
+          extra: hash.except(*KNOWN_KEYS)
+        )
+      end
+
+      def to_h
+        h = { "path" => path.to_a }
+        h["id"] = id if id
+        h["values"] = values.dup if values
+        h["intent_to_retain"] = intent_to_retain unless intent_to_retain.nil?
+        h.merge(extra)
+      end
+
+      private
+
+      def validate_id(id)
+        return if id.nil?
+        return if id.is_a?(::String) && id.match?(ID_PATTERN)
+
+        raise OpenID4VP::InvalidRequest, "claims[].id must be a non-empty string matching #{ID_PATTERN.inspect}"
+      end
+
+      def validate_values(values)
+        return if values.nil?
+
+        valid = values.is_a?(::Array) && !values.empty? &&
+                values.all? { |value| value.is_a?(::String) || value.is_a?(::Integer) || [true, false].include?(value) }
+        return if valid
+
+        raise OpenID4VP::InvalidRequest,
+              "claims[].values must be a non-empty array of strings, integers or booleans"
+      end
+
+      def validate_intent_to_retain(intent_to_retain)
+        return if intent_to_retain.nil? || [true, false].include?(intent_to_retain)
+
+        raise OpenID4VP::InvalidRequest, "claims[].intent_to_retain must be a boolean"
+      end
+    end
+  end
+end

data/lib/openid4vp/dcql/credential_query.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require_relative "../dcql"
+require_relative "../errors"
+require_relative "claims_query"
+require_relative "trusted_authorities_query"
+
+module OpenID4VP
+  module DCQL
+    # OpenID4VP §6.1: a request for a presentation of one or more matching
+    # Credentials.
+    class CredentialQuery
+      ID_PATTERN = /\A[A-Za-z0-9_-]+\z/
+
+      KNOWN_KEYS = %w[
+        id format multiple meta trusted_authorities
+        require_cryptographic_holder_binding claims claim_sets
+      ].freeze
+
+      attr_reader :id, :format, :multiple, :meta, :trusted_authorities,
+                  :require_cryptographic_holder_binding, :claims, :claim_sets, :extra
+
+      def initialize(
+        id:, format:, meta:, multiple: false, trusted_authorities: nil,
+        require_cryptographic_holder_binding: true, claims: nil, claim_sets: nil, extra: {}
+      )
+        validate_id(id)
+        validate_format(format)
+        validate_meta(meta)
+        validate_boolean(multiple, "multiple")
+        validate_boolean(require_cryptographic_holder_binding, "require_cryptographic_holder_binding")
+
+        @id = id
+        @format = format
+        @meta = meta.dup.freeze
+        @multiple = multiple
+        @require_cryptographic_holder_binding = require_cryptographic_holder_binding
+        @trusted_authorities = build_trusted_authorities(trusted_authorities)
+        @claims = build_claims(claims)
+        @claim_sets = build_claim_sets(claim_sets, @claims)
+        @extra = extra.dup.freeze
+      end
+
+      def self.from_h(hash)
+        raise OpenID4VP::InvalidRequest, "credentials[] entry must be an object" unless hash.is_a?(::Hash)
+
+        new(
+          id: hash["id"],
+          format: hash["format"],
+          meta: hash["meta"],
+          multiple: hash.key?("multiple") ? hash["multiple"] : false,
+          trusted_authorities: hash["trusted_authorities"],
+          require_cryptographic_holder_binding:
+            hash.key?("require_cryptographic_holder_binding") ? hash["require_cryptographic_holder_binding"] : true,
+          claims: hash["claims"],
+          claim_sets: hash["claim_sets"],
+          extra: hash.except(*KNOWN_KEYS)
+        )
+      end
+
+      def claim(id)
+        claims&.find { |claims_query| claims_query.id == id }
+      end
+
+      def to_h
+        h = {
+          "id" => id,
+          "format" => format,
+          "multiple" => multiple,
+          "meta" => meta.dup,
+          "require_cryptographic_holder_binding" => require_cryptographic_holder_binding
+        }
+        h["trusted_authorities"] = trusted_authorities.map(&:to_h) if trusted_authorities
+        h["claims"] = claims.map(&:to_h) if claims
+        h["claim_sets"] = claim_sets.map(&:dup) if claim_sets
+        h.merge(extra)
+      end
+
+      private
+
+      def validate_id(id)
+        return if id.is_a?(::String) && id.match?(ID_PATTERN)
+
+        raise OpenID4VP::InvalidRequest, "credentials[].id must be a non-empty string matching #{ID_PATTERN.inspect}"
+      end
+
+      def validate_format(format)
+        return if format.is_a?(::String) && !format.empty?
+
+        raise OpenID4VP::InvalidRequest, "credentials[].format must be a non-empty string"
+      end
+
+      def validate_meta(meta)
+        return if meta.is_a?(::Hash)
+
+        raise OpenID4VP::InvalidRequest, "credentials[].meta must be an object"
+      end
+
+      def validate_boolean(value, field)
+        return if [true, false].include?(value)
+
+        raise OpenID4VP::InvalidRequest, "credentials[].#{field} must be a boolean"
+      end
+
+      def build_trusted_authorities(trusted_authorities)
+        return nil if trusted_authorities.nil?
+
+        unless trusted_authorities.is_a?(::Array) && !trusted_authorities.empty?
+          raise OpenID4VP::InvalidRequest, "credentials[].trusted_authorities must be a non-empty array"
+        end
+
+        trusted_authorities.map do |entry|
+          entry.is_a?(TrustedAuthoritiesQuery) ? entry : TrustedAuthoritiesQuery.from_h(entry)
+        end.freeze
+      end
+
+      def build_claims(claims)
+        return nil if claims.nil?
+
+        unless claims.is_a?(::Array) && !claims.empty?
+          raise OpenID4VP::InvalidRequest, "credentials[].claims must be a non-empty array"
+        end
+
+        built = claims.map { |claim| claim.is_a?(ClaimsQuery) ? claim : ClaimsQuery.from_h(claim) }
+        deduped = dedupe_by_path(built)
+
+        ids = deduped.filter_map(&:id)
+        raise OpenID4VP::InvalidRequest, "credentials[].claims ids must be unique" if ids.uniq.size != ids.size
+
+        deduped.freeze
+      end
+
+      # OID4VP §6.1: "Verifiers MUST NOT point to the same claim more than
+      # once... Wallets SHOULD ignore such duplicate claim queries." Keep the
+      # first occurrence for each distinct path, silently.
+      def dedupe_by_path(claims_queries)
+        seen_paths = []
+        claims_queries.each_with_object([]) do |claims_query, kept|
+          next if seen_paths.any? { |path| path == claims_query.path }
+
+          seen_paths << claims_query.path
+          kept << claims_query
+        end
+      end
+
+      def build_claim_sets(claim_sets, claims)
+        return nil if claim_sets.nil?
+
+        raise OpenID4VP::InvalidRequest, "credentials[].claim_sets requires claims to be present" if claims.nil?
+
+        unless claim_sets.is_a?(::Array) && !claim_sets.empty?
+          raise OpenID4VP::InvalidRequest, "credentials[].claim_sets must be a non-empty array"
+        end
+
+        unless claims.all?(&:id)
+          raise OpenID4VP::InvalidRequest, "credentials[].claims must all have an id when claim_sets is present"
+        end
+
+        claim_ids = claims.map(&:id)
+        claim_sets.each { |option| validate_claim_set_option(option, claim_ids) }
+
+        claim_sets.map(&:dup).freeze
+      end
+
+      def validate_claim_set_option(option, claim_ids)
+        unless option.is_a?(::Array) && !option.empty? && option.all?(::String)
+          raise OpenID4VP::InvalidRequest, "credentials[].claim_sets options must be non-empty arrays of strings"
+        end
+
+        option.each do |id|
+          next if claim_ids.include?(id)
+
+          raise OpenID4VP::InvalidRequest, "credentials[].claim_sets references unknown claim id #{id.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/openid4vp/dcql/credential_set_query.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "../dcql"
+require_relative "../errors"
+
+module OpenID4VP
+  module DCQL
+    # OpenID4VP §6.2: a request for one or more Credentials to satisfy a
+    # particular use case, expressed as alternative sets of credential ids.
+    class CredentialSetQuery
+      KNOWN_KEYS = %w[options required].freeze
+
+      attr_reader :options, :required, :extra
+
+      def initialize(options:, required: true, extra: {})
+        valid_options = options.is_a?(::Array) && !options.empty? && options.all? do |option|
+          option.is_a?(::Array) && !option.empty? && option.all?(::String)
+        end
+        unless valid_options
+          raise OpenID4VP::InvalidRequest,
+                "credential_sets[].options must be a non-empty array of non-empty arrays of strings"
+        end
+
+        unless [true, false].include?(required)
+          raise OpenID4VP::InvalidRequest, "credential_sets[].required must be a boolean"
+        end
+
+        @options = options.map(&:dup).freeze
+        @required = required
+        @extra = extra.dup.freeze
+      end
+
+      def self.from_h(hash)
+        raise OpenID4VP::InvalidRequest, "credential_sets[] entry must be an object" unless hash.is_a?(::Hash)
+
+        required = hash.key?("required") ? hash["required"] : true
+        new(
+          options: hash["options"],
+          required: required,
+          extra: hash.except(*KNOWN_KEYS)
+        )
+      end
+
+      def to_h
+        { "options" => options.map(&:dup), "required" => required }.merge(extra)
+      end
+    end
+  end
+end