openid4vp 0.1.0

data/lib/openid4vp/mdoc/device_signed.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "cose"
+require_relative "../mdoc"
+require_relative "../errors"
+require_relative "cbor_values"
+require_relative "cose_key"
+require_relative "device_authentication"
+require_relative "sign1_decoder"
+
+module OpenID4VP
+  module Mdoc
+    # DeviceSigned = {"nameSpaces" => DeviceNameSpacesBytes, "deviceAuth" =>
+    # {"deviceSignature" => COSE_Sign1}} (ISO 18013-5 §9.1.3). DeviceMac
+    # authentication is not supported.
+    class DeviceSigned
+      attr_reader :name_spaces_bytes, :name_spaces, :device_auth
+
+      class << self
+        def parse(map)
+          raise OpenID4VP::InvalidResponse, "mdoc: invalid DeviceSigned" unless map.is_a?(::Hash)
+
+          tagged = map.fetch("nameSpaces") { raise OpenID4VP::InvalidResponse, "mdoc: missing DeviceSigned.nameSpaces" }
+          unless tagged.is_a?(CBOR::Tagged) && tagged.tag == 24
+            raise OpenID4VP::InvalidResponse, "mdoc: expected DeviceNameSpacesBytes (tag 24)"
+          end
+
+          device_name_spaces = decode(tagged.value)
+          raise OpenID4VP::InvalidResponse, "mdoc: invalid DeviceNameSpaces" unless device_name_spaces.is_a?(::Hash)
+
+          name_spaces = device_name_spaces.transform_values do |elements|
+            raise OpenID4VP::InvalidResponse, "mdoc: invalid DeviceNameSpaces" unless elements.is_a?(::Hash)
+
+            elements.transform_values { |v| CborValues.decode(v) }
+          end
+
+          new(name_spaces_bytes: tagged, name_spaces: name_spaces, device_auth: parse_device_auth(map))
+        end
+
+        # device_name_spaces: {ns => {element_identifier => value}}, values
+        # may be a Date/Time (encoded as tag 1004/0) or any other
+        # CBOR-encodable value. `device_key` is the device's private
+        # OpenID4VP::JOSE::JWK; the deviceSignature is a detached signature
+        # over DeviceAuthenticationBytes.
+        def build(device_name_spaces:, device_key:, session_transcript:, doc_type:, alg: -7, kid: nil)
+          CoseKey.check_alg_matches_key!(alg, device_key)
+
+          tagged = CBOR::Tagged.new(24, CBOR.encode(encode_name_spaces(device_name_spaces)))
+          device_authentication_bytes = DeviceAuthentication.bytes(
+            session_transcript: session_transcript, doc_type: doc_type, name_spaces_bytes: tagged
+          )
+          protected_headers = { 1 => alg }
+          protected_headers[4] = kid if kid
+          signing_sign1 = ::COSE::Sign1.new(
+            protected_headers: protected_headers, unprotected_headers: {}, payload: device_authentication_bytes
+          )
+          signing_sign1.sign(CoseKey.from_jwk(device_key))
+          signature = ::COSE::Sign1.new(
+            protected_headers: protected_headers, unprotected_headers: {},
+            payload: nil, signature: signing_sign1.signature
+          )
+
+          new(
+            name_spaces_bytes: tagged, name_spaces: device_name_spaces,
+            device_auth: { "deviceSignature" => signature }
+          )
+        end
+
+        private
+
+        def parse_device_auth(map)
+          device_auth = map.fetch("deviceAuth") { raise OpenID4VP::InvalidResponse, "mdoc: missing deviceAuth" }
+          raise OpenID4VP::InvalidResponse, "mdoc: invalid deviceAuth" unless device_auth.is_a?(::Hash)
+          raise OpenID4VP::PresentationInvalid, "DeviceMac not supported" if device_auth.key?("deviceMac")
+
+          raw_signature = device_auth.fetch("deviceSignature") do
+            raise OpenID4VP::InvalidResponse, "mdoc: missing deviceAuth.deviceSignature"
+          end
+          { "deviceSignature" => decode_sign1(raw_signature) }
+        end
+
+        def decode_sign1(raw)
+          Sign1Decoder.decode(raw, "deviceSignature")
+        end
+
+        def decode(bytes)
+          CBOR.decode(bytes)
+        rescue CBOR::MalformedFormatError, EOFError, TypeError
+          raise OpenID4VP::InvalidResponse, "mdoc: malformed DeviceNameSpaces"
+        end
+
+        def encode_name_spaces(name_spaces)
+          name_spaces.transform_values { |elements| elements.transform_values { |v| CborValues.encode(v) } }
+        end
+      end
+
+      def initialize(name_spaces_bytes:, name_spaces:, device_auth:)
+        @name_spaces_bytes = name_spaces_bytes
+        @name_spaces = name_spaces
+        @device_auth = device_auth
+      end
+
+      def to_map
+        {
+          "nameSpaces" => @name_spaces_bytes,
+          "deviceAuth" => { "deviceSignature" => @device_auth.fetch("deviceSignature").to_array }
+        }
+      end
+    end
+  end
+end

data/lib/openid4vp/mdoc/document.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "../mdoc"
+require_relative "../errors"
+require_relative "issuer_signed"
+require_relative "device_signed"
+
+module OpenID4VP
+  module Mdoc
+    # Document = {"docType" => tstr, "issuerSigned" => IssuerSigned,
+    # "deviceSigned" => DeviceSigned, ? "errors" => ...} (ISO 18013-5 §8.3.2.1.2.2).
+    class Document
+      attr_reader :doc_type, :issuer_signed, :device_signed, :errors
+
+      def self.parse(map)
+        raise OpenID4VP::InvalidResponse, "mdoc: invalid Document" unless map.is_a?(::Hash)
+
+        doc_type = map.fetch("docType") { raise OpenID4VP::InvalidResponse, "mdoc: missing docType" }
+        issuer_signed_map = map.fetch("issuerSigned") { raise OpenID4VP::InvalidResponse, "mdoc: missing issuerSigned" }
+        device_signed_map = map.fetch("deviceSigned") { raise OpenID4VP::InvalidResponse, "mdoc: missing deviceSigned" }
+
+        new(
+          doc_type: doc_type,
+          issuer_signed: IssuerSigned.parse(issuer_signed_map),
+          device_signed: DeviceSigned.parse(device_signed_map),
+          errors: map["errors"]
+        )
+      end
+
+      def initialize(doc_type:, issuer_signed:, device_signed:, errors: nil)
+        @doc_type = doc_type
+        @issuer_signed = issuer_signed
+        @device_signed = device_signed
+        @errors = errors
+      end
+
+      def to_map
+        map = { "docType" => doc_type, "issuerSigned" => issuer_signed.to_map, "deviceSigned" => device_signed.to_map }
+        map["errors"] = errors if errors
+        map
+      end
+    end
+  end
+end

data/lib/openid4vp/mdoc/handover.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "../mdoc"
+require_relative "../util"
+
+module OpenID4VP
+  module Mdoc
+    # OpenID4VPHandover and OpenID4VPDCAPIHandover (OpenID4VP §B.2.6): the
+    # CBOR structures that bind an ISO mdoc DeviceResponse to an OpenID4VP
+    # request, for redirect-based and Digital Credentials API invocation
+    # respectively.
+    module Handover
+      module_function
+
+      # The OpenID4VPHandoverInfo array, CBOR-encoded (OpenID4VP §B.2.6.1).
+      # `client_id` may be a String or an object responding to `#to_s` (e.g.
+      # OpenID4VP::ClientId). `jwk_thumbprint`, when present, must be the raw
+      # (binary-encoded) 32-byte SHA-256 JWK thumbprint; nil encodes as CBOR
+      # null.
+      def info_bytes_openid4vp(client_id:, nonce:, response_uri:, jwk_thumbprint: nil)
+        CBOR.encode([client_id.to_s, nonce, jwk_thumbprint&.b, response_uri])
+      end
+
+      # The OpenID4VPHandover array: ["OpenID4VPHandover", sha256(info_bytes)].
+      def openid4vp(client_id:, nonce:, response_uri:, jwk_thumbprint: nil)
+        info = info_bytes_openid4vp(
+          client_id: client_id, nonce: nonce, response_uri: response_uri, jwk_thumbprint: jwk_thumbprint
+        )
+        ["OpenID4VPHandover", Util.sha256(info)]
+      end
+
+      # The OpenID4VPDCAPIHandoverInfo array, CBOR-encoded (OpenID4VP
+      # §B.2.6.2). `origin` MUST NOT be prefixed with `origin:`.
+      def info_bytes_dc_api(origin:, nonce:, jwk_thumbprint: nil)
+        CBOR.encode([origin, nonce, jwk_thumbprint&.b])
+      end
+
+      # The OpenID4VPDCAPIHandover array: ["OpenID4VPDCAPIHandover", sha256(info_bytes)].
+      def dc_api(origin:, nonce:, jwk_thumbprint: nil)
+        info = info_bytes_dc_api(origin: origin, nonce: nonce, jwk_thumbprint: jwk_thumbprint)
+        ["OpenID4VPDCAPIHandover", Util.sha256(info)]
+      end
+
+      # CBOR encoding of a handover array (as returned by `.openid4vp` or
+      # `.dc_api`).
+      def encode(handover_array)
+        CBOR.encode(handover_array)
+      end
+    end
+  end
+end

data/lib/openid4vp/mdoc/issuer_signed.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "cose"
+require_relative "../mdoc"
+require_relative "../errors"
+require_relative "../x509"
+require_relative "cbor_values"
+require_relative "sign1_decoder"
+
+module OpenID4VP
+  module Mdoc
+    # A single ISO 18013-5 §9.1.2.4 IssuerSignedItem: one disclosed data
+    # element from an mdoc namespace. The original IssuerSignedItemBytes
+    # (`#6.24(bstr .cbor IssuerSignedItem)`) are preserved verbatim in
+    # `#bytes` so that `#digest` recomputes exactly the bytes the issuer
+    # digested into the MSO's valueDigests, regardless of Ruby Hash
+    # re-encoding order.
+    class IssuerSignedItem
+      attr_reader :digest_id, :random, :element_identifier, :element_value, :bytes
+
+      class << self
+        # tagged: a CBOR::Tagged(24, bstr), as decoded from an IssuerSigned
+        # nameSpaces entry.
+        def from_tagged(tagged)
+          bytes = unwrap_tag24(tagged)
+          map = decode_item(bytes)
+
+          new(
+            digest_id: fetch!(map, "digestID"),
+            random: fetch!(map, "random"),
+            element_identifier: fetch!(map, "elementIdentifier"),
+            element_value: CborValues.decode(fetch!(map, "elementValue")),
+            bytes: bytes
+          )
+        end
+
+        # Builds a fresh item (used by Builder), encoding `element_value`
+        # immediately so `#bytes`/`#digest` are available. `element_value`
+        # may be a Date (encoded as full-date, tag 1004), a Time (encoded as
+        # tdate, tag 0), or any other CBOR-encodable value (kept as-is).
+        def build(digest_id:, random:, element_identifier:, element_value:)
+          map = {
+            "digestID" => digest_id, "random" => random,
+            "elementIdentifier" => element_identifier, "elementValue" => CborValues.encode(element_value)
+          }
+          new(
+            digest_id: digest_id, random: random, element_identifier: element_identifier,
+            element_value: element_value, bytes: CBOR.encode(map)
+          )
+        end
+
+        private
+
+        def unwrap_tag24(tagged)
+          unless tagged.is_a?(CBOR::Tagged) && tagged.tag == 24
+            raise OpenID4VP::InvalidResponse, "mdoc: expected IssuerSignedItemBytes (tag 24)"
+          end
+
+          tagged.value
+        end
+
+        def decode_item(bytes)
+          map = CBOR.decode(bytes)
+          raise OpenID4VP::InvalidResponse, "mdoc: invalid IssuerSignedItem" unless map.is_a?(::Hash)
+
+          map
+        rescue CBOR::MalformedFormatError, EOFError, TypeError
+          raise OpenID4VP::InvalidResponse, "mdoc: malformed IssuerSignedItem"
+        end
+
+        def fetch!(map, key)
+          map.fetch(key) { raise OpenID4VP::InvalidResponse, "mdoc: missing IssuerSignedItem.#{key}" }
+        end
+      end
+
+      def initialize(digest_id:, random:, element_identifier:, element_value:, bytes:)
+        @digest_id = digest_id
+        @random = random
+        @element_identifier = element_identifier
+        @element_value = element_value
+        @bytes = bytes.b
+      end
+
+      # SHA-256/384/512 digest of the tag-24 IssuerSignedItemBytes, INCLUDING
+      # the tag, over the exact original bytes.
+      def digest(alg)
+        OpenSSL::Digest.digest(alg, CBOR.encode(CBOR::Tagged.new(24, @bytes)))
+      end
+
+      def to_tagged
+        CBOR::Tagged.new(24, @bytes)
+      end
+    end
+
+    # IssuerSigned = {"nameSpaces" => {ns => [IssuerSignedItemBytes]}, "issuerAuth" => COSE_Sign1}
+    # (ISO 18013-5 §9.1.2.4).
+    class IssuerSigned
+      # COSE header label for the x5chain header (RFC 9360 §2).
+      LABEL_X5CHAIN = 33
+
+      attr_reader :name_spaces, :issuer_auth
+
+      class << self
+        def parse(map)
+          raise OpenID4VP::InvalidResponse, "mdoc: invalid IssuerSigned" unless map.is_a?(::Hash)
+
+          raw_name_spaces = map.fetch("nameSpaces") { raise OpenID4VP::InvalidResponse, "mdoc: missing nameSpaces" }
+          raise OpenID4VP::InvalidResponse, "mdoc: invalid nameSpaces" unless raw_name_spaces.is_a?(::Hash)
+
+          name_spaces = raw_name_spaces.transform_values do |items|
+            Array(items).map { |t| IssuerSignedItem.from_tagged(t) }
+          end
+          raw_issuer_auth = map.fetch("issuerAuth") { raise OpenID4VP::InvalidResponse, "mdoc: missing issuerAuth" }
+          issuer_auth = decode_sign1(raw_issuer_auth)
+
+          new(name_spaces: name_spaces, issuer_auth: issuer_auth)
+        end
+
+        private
+
+        # `raw` is the already-decoded issuerAuth value: either a plain
+        # 4-element Array (untagged COSE_Sign1, the common mdoc encoding) or
+        # a CBOR::Tagged(18, array).
+        def decode_sign1(raw)
+          Sign1Decoder.decode(raw, "issuerAuth")
+        end
+      end
+
+      def initialize(name_spaces:, issuer_auth:)
+        @name_spaces = name_spaces
+        @issuer_auth = issuer_auth
+      end
+
+      def mso
+        @mso ||= MSO.parse(@issuer_auth.payload)
+      end
+
+      # The certificate chain from header label 33 (protected header takes
+      # precedence over unprotected), as OpenSSL::X509::Certificate objects.
+      # A single byte string is one certificate; an array of byte strings is
+      # several, leaf first. Returns [] when there is no x5chain header.
+      def x5chain
+        raw = @issuer_auth.protected_headers[LABEL_X5CHAIN] || @issuer_auth.unprotected_headers[LABEL_X5CHAIN]
+        return [] if raw.nil?
+
+        (raw.is_a?(::Array) ? raw : [raw]).map { |der| OpenID4VP::X509.parse(der) }
+      end
+
+      def to_map
+        {
+          "nameSpaces" => @name_spaces.transform_values { |items| items.map(&:to_tagged) },
+          "issuerAuth" => @issuer_auth.to_array
+        }
+      end
+    end
+  end
+end

data/lib/openid4vp/mdoc/mso.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "../mdoc"
+require_relative "../errors"
+require_relative "cose_key"
+
+module OpenID4VP
+  module Mdoc
+    # The ISO 18013-5 §9.1.2.4 MobileSecurityObject (MSO): the IssuerAuth
+    # payload, binding each namespace's disclosed-element digests and the
+    # mdoc's device public key to a docType and validity window.
+    class MSO
+      DIGEST_ALGORITHMS = %w[SHA-256 SHA-384 SHA-512].freeze
+
+      attr_reader :version, :digest_algorithm, :value_digests, :device_key, :doc_type, :validity_info
+
+      class << self
+        # bytes_or_tagged: MobileSecurityObjectBytes (`#6.24(bstr .cbor MSO)`),
+        # either raw CBOR bytes (typically `IssuerAuth#payload`) or an
+        # already-decoded CBOR::Tagged(24, bstr).
+        def parse(bytes_or_tagged)
+          tagged = bytes_or_tagged.is_a?(CBOR::Tagged) ? bytes_or_tagged : decode(bytes_or_tagged)
+          unless tagged.is_a?(CBOR::Tagged) && tagged.tag == 24
+            raise OpenID4VP::InvalidResponse, "mdoc: expected MobileSecurityObjectBytes (tag 24)"
+          end
+
+          map = decode(tagged.value)
+          raise OpenID4VP::InvalidResponse, "mdoc: invalid MobileSecurityObject" unless map.is_a?(::Hash)
+
+          from_map(map)
+        end
+
+        # Builds MobileSecurityObjectBytes (tag-24 CBOR bytes), suitable as
+        # an IssuerAuth payload. `device_key` is a public
+        # OpenID4VP::JOSE::JWK.
+        def build(
+          doc_type:, digest_algorithm:, value_digests:, device_key:, valid_from:, valid_until:, signed: ::Time.now
+        )
+          unless DIGEST_ALGORITHMS.include?(digest_algorithm)
+            raise OpenID4VP::InvalidRequest, "mdoc: unsupported digestAlgorithm #{digest_algorithm.inspect}"
+          end
+
+          map = {
+            "version" => "1.0",
+            "digestAlgorithm" => digest_algorithm,
+            "valueDigests" => value_digests,
+            "deviceKeyInfo" => { "deviceKey" => CoseKey.from_jwk(device_key.to_public).map },
+            "docType" => doc_type,
+            "validityInfo" => {
+              "signed" => tdate(signed), "validFrom" => tdate(valid_from), "validUntil" => tdate(valid_until)
+            }
+          }
+          CBOR.encode(CBOR::Tagged.new(24, CBOR.encode(map)))
+        end
+
+        private
+
+        def from_map(map)
+          validity = fetch!(map, "validityInfo")
+          raise OpenID4VP::InvalidResponse, "mdoc: invalid validityInfo" unless validity.is_a?(::Hash)
+
+          device_key_info = fetch!(map, "deviceKeyInfo")
+          raise OpenID4VP::InvalidResponse, "mdoc: invalid deviceKeyInfo" unless device_key_info.is_a?(::Hash)
+
+          new(
+            version: fetch!(map, "version"),
+            digest_algorithm: validate_digest_algorithm!(fetch!(map, "digestAlgorithm")),
+            value_digests: fetch!(map, "valueDigests"),
+            device_key: parse_device_key(fetch!(device_key_info, "deviceKey")),
+            doc_type: fetch!(map, "docType"),
+            validity_info: {
+              "signed" => parse_tdate(fetch!(validity, "signed")),
+              "validFrom" => parse_tdate(fetch!(validity, "validFrom")),
+              "validUntil" => parse_tdate(fetch!(validity, "validUntil"))
+            }
+          )
+        end
+
+        def fetch!(map, key)
+          map.fetch(key) { raise OpenID4VP::InvalidResponse, "mdoc: missing MobileSecurityObject.#{key}" }
+        end
+
+        # map: a deviceKeyInfo.deviceKey COSE_Key map (Integer label =>
+        # value), as decoded from CBOR. Raises OpenID4VP::InvalidResponse for
+        # anything COSE::Key::EC2/OpenSSL rejects, rather than leaking a bare
+        # COSE::Error/RuntimeError/ArgumentError/OpenSSL error.
+        def parse_device_key(map)
+          CoseKey.to_jwk(::COSE::Key::EC2.from_map(map))
+        rescue ::COSE::Error, ::RuntimeError, ::ArgumentError, ::TypeError, ::OpenSSL::OpenSSLError => e
+          raise OpenID4VP::InvalidResponse, "mdoc: invalid deviceKey: #{e.message}"
+        end
+
+        # ISO 18013-5 §9.1.2.4: `digestAlgorithm` must be one of
+        # DIGEST_ALGORITHMS -- an unsupported value would otherwise only
+        # surface later, as a bare RuntimeError out of OpenSSL::Digest, the
+        # first time a digest is computed with it (`IssuerSignedItem#digest`).
+        def validate_digest_algorithm!(digest_algorithm)
+          return digest_algorithm if DIGEST_ALGORITHMS.include?(digest_algorithm)
+
+          raise OpenID4VP::PresentationInvalid, "mdoc: unsupported digestAlgorithm #{digest_algorithm.inspect}"
+        end
+
+        def decode(bytes)
+          CBOR.decode(bytes)
+        rescue CBOR::MalformedFormatError, EOFError, TypeError
+          raise OpenID4VP::InvalidResponse, "mdoc: malformed MobileSecurityObject"
+        end
+
+        def tdate(time)
+          CBOR::Tagged.new(0, time.utc.strftime("%Y-%m-%dT%H:%M:%SZ"))
+        end
+
+        def parse_tdate(tagged)
+          unless tagged.is_a?(CBOR::Tagged) && tagged.tag.zero?
+            raise OpenID4VP::InvalidResponse, "mdoc: expected tdate (tag 0)"
+          end
+
+          ::Time.parse(tagged.value).utc
+        end
+      end
+
+      def initialize(version:, digest_algorithm:, value_digests:, device_key:, doc_type:, validity_info:)
+        @version = version
+        @digest_algorithm = digest_algorithm
+        @value_digests = value_digests
+        @device_key = device_key
+        @doc_type = doc_type
+        @validity_info = validity_info
+      end
+    end
+  end
+end

data/lib/openid4vp/mdoc/session_transcript.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "../mdoc"
+require_relative "handover"
+
+module OpenID4VP
+  module Mdoc
+    # The ISO/IEC 18013-5 §9.1.5.1 SessionTranscript CBOR structure, as
+    # adapted by OpenID4VP §B.2.6 for OpenID4VP-invoked mdoc presentations:
+    # DeviceEngagementBytes and EReaderKeyBytes are always null, and Handover
+    # is an OpenID4VPHandover or OpenID4VPDCAPIHandover array (see
+    # OpenID4VP::Mdoc::Handover).
+    module SessionTranscript
+      module_function
+
+      # [nil, nil, handover], where `handover` is a Handover array as
+      # returned by `Handover.openid4vp` or `Handover.dc_api`.
+      def build(handover)
+        [nil, nil, handover]
+      end
+
+      # CBOR encoding of `build(handover)`.
+      def encode(handover)
+        CBOR.encode(build(handover))
+      end
+
+      # The SessionTranscript array for a redirect-based (OpenID4VPHandover)
+      # presentation. `encryption_jwk`, when the response is encrypted (e.g.
+      # response_mode `direct_post.jwt`), is the Verifier's public
+      # OpenID4VP::JOSE::JWK used to encrypt the response.
+      def for_request(client_id:, nonce:, response_uri:, encryption_jwk: nil)
+        handover = Handover.openid4vp(
+          client_id: client_id, nonce: nonce, response_uri: response_uri,
+          jwk_thumbprint: encryption_jwk&.thumbprint
+        )
+        build(handover)
+      end
+
+      # The SessionTranscript array for a Digital Credentials API
+      # (OpenID4VPDCAPIHandover) presentation. `encryption_jwk`, when the
+      # response is encrypted (response_mode `dc_api.jwt`), is the
+      # Verifier's public OpenID4VP::JOSE::JWK used to encrypt the response.
+      def for_dc_api(origin:, nonce:, encryption_jwk: nil)
+        handover = Handover.dc_api(origin: origin, nonce: nonce, jwk_thumbprint: encryption_jwk&.thumbprint)
+        build(handover)
+      end
+    end
+  end
+end

data/lib/openid4vp/mdoc/sign1_decoder.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "cose"
+require_relative "../mdoc"
+require_relative "../errors"
+
+module OpenID4VP
+  module Mdoc
+    # Decodes an already CBOR-decoded COSE_Sign1 value -- either a bare
+    # 4-element Array or a CBOR::Tagged(18, array), as found inside a parsed
+    # IssuerSigned.issuerAuth / DeviceSigned.deviceAuth.deviceSignature --
+    # into a ::COSE::Sign1. Validates the array's shape first (element
+    # count/types) so a malformed or adversarial structure (wrong element
+    # count, a non-map unprotected header, a non-string signature, a
+    # protected header bstr whose content decodes to deeply nested CBOR)
+    # raises OpenID4VP::InvalidResponse instead of a bare
+    # NoMethodError/CBOR::StackError/... out of cose-ruby, which only
+    # validates COSE_Sign1 shape loosely (it never checks that the
+    # unprotected header is actually a Hash, for example).
+    module Sign1Decoder
+      module_function
+
+      # raw: the already-decoded issuerAuth/deviceSignature value. label: a
+      # short description used in the error message (e.g. "issuerAuth",
+      # "deviceSignature").
+      def decode(raw, label)
+        array = validate!(unwrap(raw), label)
+        sign1 = ::COSE::Sign1.from_array(array)
+        raise OpenID4VP::InvalidResponse, "mdoc: malformed #{label}" unless sign1.protected_headers.is_a?(::Hash)
+
+        sign1
+      rescue CBOR::UnpackError, CBOR::TypeError, EOFError, ::TypeError, ::ArgumentError, ::NoMethodError,
+             ::COSE::Error => e
+        raise OpenID4VP::InvalidResponse, "mdoc: malformed #{label}: #{e.message}"
+      end
+
+      def unwrap(raw)
+        raw.is_a?(CBOR::Tagged) ? raw.value : raw
+      end
+
+      # array: the (possibly tag-18-unwrapped) COSE_Sign1 candidate. Requires
+      # exactly 4 elements: protected (a binary String, possibly empty),
+      # unprotected (a Hash), payload (a binary String or nil, for a
+      # detached-content COSE_Sign1 like mdoc DeviceSignature) and signature
+      # (a binary String). Returns `array` unchanged once validated.
+      def validate!(array, label)
+        raise OpenID4VP::InvalidResponse, "mdoc: malformed #{label}" unless array.is_a?(::Array) && array.size == 4
+
+        protected_bstr, unprotected, payload, signature = array
+        valid_shape =
+          protected_bstr.is_a?(::String) && unprotected.is_a?(::Hash) &&
+          (payload.nil? || payload.is_a?(::String)) && signature.is_a?(::String)
+
+        raise OpenID4VP::InvalidResponse, "mdoc: malformed #{label}" unless valid_shape
+
+        array
+      end
+    end
+  end
+end