openid4vp 0.1.0

data/lib/openid4vp/mdoc/verifier.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+require "cose"
+require_relative "../mdoc"
+require_relative "../errors"
+require_relative "../util"
+require_relative "../jose/jwk"
+require_relative "cose_key"
+require_relative "mso"
+require_relative "device_authentication"
+
+module OpenID4VP
+  module Mdoc
+    # Verifies a parsed OpenID4VP::Mdoc::Document (OpenID4VP §B.2, ISO
+    # 18013-5 §9.3.1): the IssuerAuth signature over the MSO, the MSO's
+    # validity window and per-element digests, and the DeviceSignature over
+    # the SessionTranscript-bound DeviceAuthentication structure.
+    module Verifier
+      Result = Struct.new(
+        :doc_type, :claims, :mso, :issuer_certs, :device_key, :issuer_alg, :device_alg, keyword_init: true
+      )
+
+      # COSE alg identifiers (protected header label 1 values) this module
+      # accepts for IssuerAuth/DeviceSignature: ES256/ES384/ES512, the
+      # ECDSA algs this gem itself issues and verifies (mirrors
+      # CoseKey::CURVE_FOR_ALG; EdDSA mdocs are not supported here). Any
+      # other alg is rejected before we ever
+      # call cose-ruby's verify: cose-ruby's ECDSA#valid_key? does not check
+      # that the key's curve matches the alg (only that the key carries no
+      # alg, or the same alg), so an IssuerAuth/DeviceSignature whose
+      # protected alg doesn't match the actual key's curve (e.g. alg -35
+      # ES384 with a P-256 leaf key) would otherwise reach
+      # OpenSSL::SignatureAlgorithm::Base#verify_key=, which raises
+      # OpenSSL::SignatureAlgorithm::VerifyKeyError -- a raw, undocumented
+      # error type -- instead of a clean OpenID4VP::Error.
+      ALLOWED_ALGS = [-7, -35, -36].freeze
+
+      module_function
+
+      # document: an OpenID4VP::Mdoc::Document. session_transcript: the
+      # SessionTranscript array (e.g. from SessionTranscript.for_request).
+      # issuer_cert_validator: a callable(chain_certs) -> leaf cert, e.g.
+      # ->(chain) { OpenID4VP::X509::ChainValidator.new(trust_anchors: [...]).validate!(chain) }.
+      #
+      # Every Credential-side failure (untrusted/invalid issuer chain, bad
+      # IssuerAuth signature, malformed/expired MSO, tampered disclosed
+      # element) raises OpenID4VP::PresentationInvalid. Only a failure to
+      # prove possession of the mdoc device key (a missing/invalid
+      # DeviceSignature) raises OpenID4VP::HolderBindingInvalid. Callers can
+      # rely on this distinction instead of inspecting error messages.
+      def verify(document, session_transcript:, issuer_cert_validator:, now: ::Time.now)
+        issuer_signed = document.issuer_signed
+        issuer_auth = issuer_signed.issuer_auth
+
+        chain = issuer_signed.x5chain
+        raise OpenID4VP::PresentationInvalid, "mdoc: IssuerAuth is missing an x5chain" if chain.empty?
+
+        leaf = validate_issuer_chain!(issuer_cert_validator, chain)
+        verify_issuer_signature!(issuer_auth, leaf)
+
+        mso = parse_mso!(issuer_auth.payload)
+        validate_doc_type!(mso, document.doc_type)
+        validate_validity!(mso, now)
+        claims = verify_disclosed_items!(issuer_signed, mso)
+        verify_device_signature!(document, mso, session_transcript)
+
+        Result.new(
+          doc_type: document.doc_type, claims: claims, mso: mso, issuer_certs: chain,
+          device_key: mso.device_key, issuer_alg: issuer_auth.headers.alg,
+          device_alg: document.device_signed.device_auth.fetch("deviceSignature").headers.alg
+        )
+      end
+
+      def validate_issuer_chain!(issuer_cert_validator, chain)
+        issuer_cert_validator.call(chain)
+      rescue OpenID4VP::VerificationError => e
+        raise OpenID4VP::PresentationInvalid, "mdoc: untrusted issuer certificate chain: #{e.message}"
+      end
+      private_class_method :validate_issuer_chain!
+
+      def verify_issuer_signature!(issuer_auth, leaf)
+        check_allowed_alg!(issuer_auth.headers.alg, OpenID4VP::PresentationInvalid, "IssuerAuth")
+        key = CoseKey.with_kid(::COSE::Key::EC2.from_pkey(leaf.public_key), issuer_auth.headers.kid)
+        issuer_auth.verify(key)
+      rescue ::COSE::Error, ::OpenSSL::SignatureAlgorithm::Error, ::OpenSSL::OpenSSLError => e
+        raise OpenID4VP::PresentationInvalid, "mdoc: issuer signature invalid: #{e.message}"
+      end
+      private_class_method :verify_issuer_signature!
+
+      # Raises `error_class` (OpenID4VP::PresentationInvalid for IssuerAuth,
+      # OpenID4VP::HolderBindingInvalid for DeviceSignature) unless `alg` is
+      # one of ALLOWED_ALGS. See ALLOWED_ALGS for why this check must run
+      # before we call cose-ruby's verify.
+      def check_allowed_alg!(alg, error_class, label)
+        return if ALLOWED_ALGS.include?(alg)
+
+        raise error_class, "mdoc: unsupported #{label} alg #{alg.inspect}"
+      end
+      private_class_method :check_allowed_alg!
+
+      def parse_mso!(issuer_auth_payload)
+        MSO.parse(issuer_auth_payload)
+      rescue OpenID4VP::InvalidResponse => e
+        raise OpenID4VP::PresentationInvalid, "mdoc: invalid MSO: #{e.message}"
+      end
+      private_class_method :parse_mso!
+
+      def validate_doc_type!(mso, doc_type)
+        return if mso.doc_type == doc_type
+
+        raise OpenID4VP::PresentationInvalid, "mdoc: MSO docType #{mso.doc_type.inspect} does not match " \
+                                              "Document docType #{doc_type.inspect}"
+      end
+      private_class_method :validate_doc_type!
+
+      def validate_validity!(mso, now)
+        valid_from = mso.validity_info.fetch("validFrom")
+        valid_until = mso.validity_info.fetch("validUntil")
+        raise OpenID4VP::PresentationInvalid, "mdoc: MSO is not yet valid" if now < valid_from
+        raise OpenID4VP::PresentationInvalid, "mdoc: MSO has expired" if now > valid_until
+      end
+      private_class_method :validate_validity!
+
+      def verify_disclosed_items!(issuer_signed, mso)
+        issuer_signed.name_spaces.to_h do |namespace, items|
+          namespace_digests = mso.value_digests[namespace] || {}
+          claims = items.to_h do |item|
+            [item.element_identifier, verified_element_value(item, namespace, namespace_digests, mso)]
+          end
+          [namespace, claims]
+        end
+      end
+      private_class_method :verify_disclosed_items!
+
+      def verified_element_value(item, namespace, namespace_digests, mso)
+        expected = namespace_digests[item.digest_id]
+        if expected.nil?
+          raise OpenID4VP::PresentationInvalid, "mdoc: unknown digest_id #{item.digest_id} in namespace #{namespace}"
+        end
+
+        actual = item.digest(mso.digest_algorithm)
+        unless OpenID4VP::Util.secure_compare(actual, expected.b)
+          raise OpenID4VP::PresentationInvalid,
+                "mdoc: digest mismatch for #{namespace}/#{item.element_identifier}"
+        end
+
+        item.element_value
+      end
+      private_class_method :verified_element_value
+
+      def verify_device_signature!(document, mso, session_transcript)
+        device_signed = document.device_signed
+        device_signature = device_signed.device_auth.fetch("deviceSignature") do
+          raise OpenID4VP::HolderBindingInvalid, "mdoc: device signature invalid: missing deviceSignature"
+        end
+        check_allowed_alg!(device_signature.headers.alg, OpenID4VP::HolderBindingInvalid, "DeviceSignature")
+        device_authentication_bytes = DeviceAuthentication.bytes(
+          session_transcript: session_transcript, doc_type: document.doc_type,
+          name_spaces_bytes: device_signed.name_spaces_bytes
+        )
+        key = CoseKey.with_kid(CoseKey.from_jwk(mso.device_key), device_signature.headers.kid)
+        device_signature.verify(key, nil, detached_payload: device_authentication_bytes)
+      rescue ::COSE::Error, ::OpenSSL::SignatureAlgorithm::Error, ::OpenSSL::OpenSSLError => e
+        raise OpenID4VP::HolderBindingInvalid, "mdoc: device signature invalid: #{e.message}"
+      end
+      private_class_method :verify_device_signature!
+    end
+  end
+end

data/lib/openid4vp/mdoc.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module OpenID4VP
+  # ISO mdoc (ISO/IEC 18013-5) structures used to bind a DeviceResponse to an
+  # OpenID4VP request (OpenID4VP §B.2.6): OpenID4VP::Mdoc::Handover and
+  # OpenID4VP::Mdoc::SessionTranscript.
+  module Mdoc
+  end
+end

data/lib/openid4vp/metadata/verifier_metadata.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative "../metadata"
+require_relative "../errors"
+require_relative "../jose/jwk_set"
+require_relative "vp_formats"
+
+module OpenID4VP
+  module Metadata
+    # OpenID4VP §5.1/§11: the Verifier's client_metadata, e.g. the value of
+    # the client_metadata Authorization Request parameter or of a Verifier's
+    # RFC 7591 client registration. Wraps a Hash with String keys; unknown
+    # members are preserved as-is in #to_h.
+    class VerifierMetadata
+      DEFAULT_ENCRYPTED_RESPONSE_ENC_VALUES_SUPPORTED = %w[A128GCM].freeze
+
+      def initialize(hash)
+        raise OpenID4VP::InvalidRequest, "client_metadata must be an object" unless hash.is_a?(::Hash)
+
+        @hash = hash.dup.freeze
+        @memo = {}
+        freeze
+      end
+
+      def self.from_h(hash)
+        new(hash)
+      end
+
+      def to_h
+        @hash.dup
+      end
+
+      # OpenID4VP §5.1: the Verifier's jwks, or nil when absent. Raises
+      # InvalidRequest when it is not an object with a "keys" array, when a
+      # key is malformed, or when any key is missing its kid.
+      def jwks
+        memoize(:jwks) { build_jwks }
+      end
+
+      # OpenID4VP §5.1: defaults to ["A128GCM"] when absent.
+      def encrypted_response_enc_values_supported
+        memoize(:encrypted_response_enc_values_supported) { build_encrypted_response_enc_values_supported }
+      end
+
+      def vp_formats_supported
+        memoize(:vp_formats_supported) { build_vp_formats_supported }
+      end
+
+      # A new VerifierMetadata with the given members overridden (string or
+      # symbol keys are both accepted).
+      def with(**overrides)
+        self.class.new(@hash.merge(overrides.transform_keys(&:to_s)))
+      end
+
+      # Picks a key from #jwks usable for encrypting the Authorization
+      # Response, or nil when there is no jwks.
+      def encryption_key(supported_algs: nil)
+        jwks&.select_encryption_key(supported_algs: supported_algs)
+      end
+
+      private
+
+      def memoize(key)
+        return @memo[key] if @memo.key?(key)
+
+        @memo[key] = yield
+      end
+
+      def build_jwks
+        raw = @hash["jwks"]
+        return nil if raw.nil?
+
+        unless raw.is_a?(::Hash) && raw["keys"].is_a?(::Array)
+          raise OpenID4VP::InvalidRequest, "jwks must be an object with a keys array"
+        end
+
+        jwk_set = begin
+          OpenID4VP::JOSE::JWKSet.from_h(raw)
+        rescue OpenID4VP::Error
+          raise
+        rescue StandardError => e
+          raise OpenID4VP::InvalidRequest, "jwks: malformed key (#{e.message})"
+        end
+
+        jwk_set.require_kids!
+        jwk_set
+      end
+
+      def build_encrypted_response_enc_values_supported
+        value = @hash["encrypted_response_enc_values_supported"]
+        return DEFAULT_ENCRYPTED_RESPONSE_ENC_VALUES_SUPPORTED if value.nil?
+
+        unless value.is_a?(::Array) && !value.empty? && value.all?(::String)
+          raise OpenID4VP::InvalidRequest,
+                "encrypted_response_enc_values_supported must be a non-empty array of strings"
+        end
+
+        value
+      end
+
+      def build_vp_formats_supported
+        value = @hash["vp_formats_supported"]
+        return nil if value.nil?
+
+        VpFormats.from_h(value)
+      end
+    end
+  end
+end

data/lib/openid4vp/metadata/vp_formats.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require_relative "../metadata"
+require_relative "../errors"
+
+module OpenID4VP
+  module Metadata
+    # OpenID4VP §11.1/§10.1: a vp_formats_supported object, mapping
+    # Credential Format Identifiers to format-specific parameters (Appendix
+    # B). Wraps a Hash with String keys; unknown formats and unknown
+    # per-format parameters are preserved as-is.
+    class VpFormats
+      KNOWN_PARAMS = {
+        "jwt_vc_json" => %w[alg_values],
+        "ldp_vc" => %w[proof_type_values cryptosuite_values],
+        "mso_mdoc" => %w[issuerauth_alg_values deviceauth_alg_values],
+        "dc+sd-jwt" => %w[sd-jwt_alg_values kb-jwt_alg_values]
+      }.freeze
+
+      def initialize(hash)
+        raise OpenID4VP::InvalidRequest, "vp_formats_supported must be an object" unless hash.is_a?(::Hash)
+
+        @hash = hash.dup.freeze
+        freeze
+      end
+
+      def self.from_h(hash)
+        new(hash)
+      end
+
+      def to_h
+        @hash.dup
+      end
+
+      def formats
+        @hash.keys
+      end
+
+      def supports?(format)
+        @hash.key?(format)
+      end
+
+      def params_for(format)
+        @hash[format]
+      end
+
+      def empty?
+        @hash.empty?
+      end
+
+      # Raises InvalidRequest unless every value is an object (a Hash), and
+      # every known parameter (per KNOWN_PARAMS) present in it is a
+      # non-empty array.
+      def validate!
+        @hash.each do |format, params|
+          unless params.is_a?(::Hash)
+            raise OpenID4VP::InvalidRequest, "vp_formats_supported[#{format.inspect}] must be an object"
+          end
+
+          (KNOWN_PARAMS[format] || []).each do |param|
+            next unless params.key?(param)
+
+            value = params[param]
+            next if value.is_a?(::Array) && !value.empty?
+
+            raise OpenID4VP::InvalidRequest,
+                  "vp_formats_supported[#{format.inspect}][#{param.inspect}] must be a non-empty array"
+          end
+        end
+        self
+      end
+
+      # Common formats between self and other; for each known parameter
+      # present on both sides, keeps the array intersection (dropping the
+      # format entirely if any common known parameter intersects to empty).
+      # A known parameter present on only one side is kept as-is. Formats
+      # not listed in KNOWN_PARAMS are intersected by name only.
+      def intersect(other)
+        result = (formats & other.formats).each_with_object({}) do |format, acc|
+          merged = intersect_format(format, params_for(format) || {}, other.params_for(format) || {})
+          acc[format] = merged unless merged.nil?
+        end
+        self.class.new(result)
+      end
+
+      private
+
+      def intersect_format(format, self_params, other_params)
+        known = KNOWN_PARAMS[format]
+        return {} unless known
+
+        merged = {}
+        known.each do |param|
+          in_self = self_params.key?(param)
+          in_other = other_params.key?(param)
+
+          if in_self && in_other
+            common = self_params[param] & other_params[param]
+            return nil if common.empty?
+
+            merged[param] = common
+          elsif in_self
+            merged[param] = self_params[param]
+          elsif in_other
+            merged[param] = other_params[param]
+          end
+        end
+        merged
+      end
+    end
+  end
+end

data/lib/openid4vp/metadata/wallet_metadata.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require_relative "../metadata"
+require_relative "../errors"
+require_relative "../jose/jwk_set"
+require_relative "../client_id"
+require_relative "vp_formats"
+
+module OpenID4VP
+  module Metadata
+    # OpenID4VP §10: the Wallet's (Authorization Server) metadata, e.g. as
+    # obtained via RFC 8414 or pre-agreed out of band (§13.1.2). Wraps a Hash
+    # with String keys; unknown members are preserved as-is in #to_h.
+    class WalletMetadata
+      DEFAULT_CLIENT_ID_PREFIXES_SUPPORTED = [OpenID4VP::ClientId::PRE_REGISTERED].freeze
+
+      def initialize(hash)
+        raise OpenID4VP::InvalidRequest, "wallet metadata must be an object" unless hash.is_a?(::Hash)
+
+        @hash = hash.dup.freeze
+        @memo = {}
+        freeze
+      end
+
+      def self.from_h(hash)
+        new(hash)
+      end
+
+      # OpenID4VP §13.1.2: the non-normative set of static configuration
+      # values bound to the openid4vp: custom URL scheme.
+      def self.static_openid4vp
+        new(
+          "authorization_endpoint" => "openid4vp:",
+          "response_types_supported" => %w[vp_token],
+          "vp_formats_supported" => {
+            "dc+sd-jwt" => {
+              "sd-jwt_alg_values" => %w[ES256],
+              "kb-jwt_alg_values" => %w[ES256]
+            },
+            "mso_mdoc" => {}
+          },
+          "request_object_signing_alg_values_supported" => %w[ES256]
+        )
+      end
+
+      def to_h
+        @hash.dup
+      end
+
+      # OpenID4VP §10.1: required. Raises InvalidRequest when absent.
+      def vp_formats_supported
+        memoize(:vp_formats_supported) { build_vp_formats_supported }
+      end
+
+      # OpenID4VP §10.1: defaults to ["pre-registered"] when absent.
+      def client_id_prefixes_supported
+        memoize(:client_id_prefixes_supported) { build_client_id_prefixes_supported }
+      end
+
+      def authorization_endpoint
+        @hash["authorization_endpoint"]
+      end
+
+      def response_types_supported
+        @hash["response_types_supported"]
+      end
+
+      def response_modes_supported
+        @hash["response_modes_supported"]
+      end
+
+      def request_object_signing_alg_values_supported
+        @hash["request_object_signing_alg_values_supported"]
+      end
+
+      def authorization_encryption_alg_values_supported
+        @hash["authorization_encryption_alg_values_supported"]
+      end
+
+      def authorization_encryption_enc_values_supported
+        @hash["authorization_encryption_enc_values_supported"]
+      end
+
+      def jwks
+        memoize(:jwks) { build_jwks }
+      end
+
+      # Whether this Wallet supports the Client Identifier Prefix of
+      # client_id (or "pre-registered" when client_id has none).
+      def supports_prefix?(client_id)
+        prefix = client_id.pre_registered? ? OpenID4VP::ClientId::PRE_REGISTERED : client_id.prefix
+        client_id_prefixes_supported.include?(prefix)
+      end
+
+      private
+
+      def memoize(key)
+        return @memo[key] if @memo.key?(key)
+
+        @memo[key] = yield
+      end
+
+      def build_vp_formats_supported
+        value = @hash["vp_formats_supported"]
+        raise OpenID4VP::InvalidRequest, "vp_formats_supported is required" if value.nil?
+
+        VpFormats.from_h(value)
+      end
+
+      def build_client_id_prefixes_supported
+        value = @hash["client_id_prefixes_supported"]
+        return DEFAULT_CLIENT_ID_PREFIXES_SUPPORTED if value.nil?
+
+        unless value.is_a?(::Array) && !value.empty? && value.all?(::String)
+          raise OpenID4VP::InvalidRequest, "client_id_prefixes_supported must be a non-empty array of strings"
+        end
+
+        value
+      end
+
+      def build_jwks
+        raw = @hash["jwks"]
+        return nil if raw.nil?
+
+        unless raw.is_a?(::Hash) && raw["keys"].is_a?(::Array)
+          raise OpenID4VP::InvalidRequest, "jwks must be an object with a keys array"
+        end
+
+        begin
+          OpenID4VP::JOSE::JWKSet.from_h(raw)
+        rescue OpenID4VP::Error
+          raise
+        rescue StandardError => e
+          raise OpenID4VP::InvalidRequest, "jwks: malformed key (#{e.message})"
+        end
+      end
+    end
+  end
+end

data/lib/openid4vp/metadata.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module OpenID4VP
+  # Verifier and Wallet metadata (OpenID4VP §5.1, §10, §11): the
+  # vp_formats_supported object (VpFormats), the Verifier's client_metadata
+  # (VerifierMetadata) and the Wallet's authorization server metadata
+  # (WalletMetadata).
+  module Metadata
+  end
+end