openid4vp 0.1.0

data/lib/openid4vp/jose/jws.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+require "jwt"
+require "jwt/eddsa"
+
+require_relative "../jose"
+require_relative "../errors"
+require_relative "../util/base64url"
+require_relative "algorithms"
+
+module OpenID4VP
+  module JOSE
+    # JSON Web Signature (RFC 7515): compact and (flattened-free) general
+    # JSON serialization, signing and verification.
+    module JWS
+      # A verified (or peeked, unverified) JWS. `payload` is the parsed JSON
+      # Hash when `payload_bytes` parses as a JSON object, otherwise nil.
+      # `compact` is nil for signatures produced from JSON serialization.
+      # rubocop:disable-next Lint/StructNewOverride -- :compact is the interface name, not Array's method.
+      Verified = Struct.new(:header, :payload, :payload_bytes, :compact, keyword_init: true)
+
+      # A JWS in general JSON serialization, parsed but not verified.
+      ParsedJSON = Struct.new(:payload_bytes, :payload, :signatures, keyword_init: true)
+
+      # One entry of a ParsedJSON's `signatures` array.
+      SignatureEntry = Struct.new(:protected_header, :signature_b64, :protected_b64, keyword_init: true)
+
+      class << self
+        # Signs `payload` (a Hash, JSON-encoded; or a String, used as raw
+        # payload bytes) with `key`, returning the compact serialization.
+        def sign(payload, key:, alg: nil, header: {})
+          alg ||= Algorithms.for_key(key)
+          protected_header = { "alg" => alg }.merge(header)
+          protected_b64 = Util::Base64url.encode_json(protected_header)
+          payload_b64 = Util::Base64url.encode(payload_bytes_for(payload))
+          signature = sign_raw(alg, key, "#{protected_b64}.#{payload_b64}")
+          [protected_b64, payload_b64, Util::Base64url.encode(signature)].join(".")
+        end
+
+        # Verifies `compact` against `key`, rejecting `alg: none` and any
+        # alg not in `algorithms` or not matching `key`.
+        def verify(compact, key:, algorithms: Algorithms::SIGNING)
+          protected_b64, payload_b64, = split_compact(compact)
+          header = decode_header(protected_b64)
+          alg = header["alg"]
+          check_alg!(alg, algorithms, key)
+
+          payload_bytes = Util::Base64url.decode(payload_b64)
+          verify_compact_signature!(compact, alg, key)
+
+          Verified.new(header: header, payload: parse_payload(payload_bytes), payload_bytes: payload_bytes,
+                       compact: compact)
+        end
+
+        # Parses `compact` into header/payload WITHOUT verifying the
+        # signature. Raises InvalidRequest on malformed input.
+        def peek(compact)
+          protected_b64, payload_b64, = split_compact(compact)
+          header = decode_header(protected_b64)
+          payload_bytes = Util::Base64url.decode(payload_b64)
+          Verified.new(header: header, payload: parse_payload(payload_bytes), payload_bytes: payload_bytes,
+                       compact: compact)
+        end
+
+        # Produces a JWS in general JSON serialization, signed by every
+        # entry of `signers` (each a Hash with `key:`, optional `alg:` and
+        # `header:`).
+        def sign_json(payload, signers:)
+          payload_b64 = Util::Base64url.encode(payload_bytes_for(payload))
+          signatures = signers.map { |signer| sign_json_entry(signer, payload_b64) }
+          { "payload" => payload_b64, "signatures" => signatures }
+        end
+
+        # Parses a JWS in general JSON serialization (a Hash, or a JSON
+        # String) into a ParsedJSON, WITHOUT verifying any signature.
+        def parse_json(hash_or_string)
+          hash = coerce_json(hash_or_string)
+          payload_b64 = hash["payload"]
+          raw_signatures = hash["signatures"]
+          unless payload_b64.is_a?(String) && raw_signatures.is_a?(Array) && !raw_signatures.empty?
+            raise OpenID4VP::InvalidRequest, "jws: malformed JSON serialization"
+          end
+
+          payload_bytes = Util::Base64url.decode(payload_b64)
+          ParsedJSON.new(payload_bytes: payload_bytes, payload: parse_payload(payload_bytes),
+                         signatures: raw_signatures.map { |entry| build_signature_entry(entry) })
+        end
+
+        # Verifies the signature at `index` of a ParsedJSON against `key`.
+        def verify_json_signature(parsed, index, key:, algorithms: Algorithms::SIGNING)
+          entry = parsed.signatures[index]
+          raise OpenID4VP::InvalidRequest, "jws: no signature at index #{index}" unless entry
+
+          alg = entry.protected_header["alg"]
+          check_alg!(alg, algorithms, key)
+          payload_b64 = Util::Base64url.encode(parsed.payload_bytes)
+          signature = Util::Base64url.decode(entry.signature_b64)
+          signing_input = "#{entry.protected_b64}.#{payload_b64}"
+          unless verify_raw(alg, key, signing_input, signature)
+            raise OpenID4VP::VerificationError, "signature verification failed"
+          end
+
+          Verified.new(header: entry.protected_header, payload: parsed.payload, payload_bytes: parsed.payload_bytes,
+                       compact: nil)
+        end
+
+        private
+
+        def sign_json_entry(signer, payload_b64)
+          key = signer.fetch(:key)
+          alg = signer[:alg] || Algorithms.for_key(key)
+          protected_header = { "alg" => alg }.merge(signer[:header] || {})
+          protected_b64 = Util::Base64url.encode_json(protected_header)
+          signature = sign_raw(alg, key, "#{protected_b64}.#{payload_b64}")
+          { "protected" => protected_b64, "signature" => Util::Base64url.encode(signature) }
+        end
+
+        def build_signature_entry(entry)
+          raise OpenID4VP::InvalidRequest, "jws: malformed signature entry" unless entry.is_a?(Hash)
+
+          protected_b64 = entry["protected"]
+          signature_b64 = entry["signature"]
+          unless protected_b64.is_a?(String) && signature_b64.is_a?(String)
+            raise OpenID4VP::InvalidRequest, "jws: malformed signature entry"
+          end
+
+          SignatureEntry.new(protected_header: decode_header(protected_b64), signature_b64: signature_b64,
+                             protected_b64: protected_b64)
+        end
+
+        def coerce_json(hash_or_string)
+          hash = hash_or_string.is_a?(String) ? parse_json_string(hash_or_string) : hash_or_string
+          raise OpenID4VP::InvalidRequest, "jws: malformed JSON serialization" unless hash.is_a?(Hash)
+
+          hash
+        end
+
+        def parse_json_string(str)
+          ::JSON.parse(str)
+        rescue ::JSON::ParserError
+          raise OpenID4VP::InvalidRequest, "jws: invalid JSON"
+        end
+
+        def split_compact(compact)
+          parts = compact.to_s.split(".", -1)
+          raise OpenID4VP::InvalidRequest, "jws: malformed compact serialization" unless parts.size == 3
+
+          parts
+        end
+
+        def decode_header(protected_b64)
+          header = Util::Base64url.decode_json(protected_b64)
+          raise OpenID4VP::InvalidRequest, "jws: header is not a JSON object" unless header.is_a?(Hash)
+
+          header
+        end
+
+        def payload_bytes_for(payload)
+          payload.is_a?(String) ? payload.b : ::JSON.generate(payload).b
+        end
+
+        def parse_payload(bytes)
+          parsed = ::JSON.parse(bytes)
+          parsed.is_a?(Hash) ? parsed : nil
+        rescue ::JSON::ParserError, EncodingError
+          nil
+        end
+
+        def check_alg!(alg, algorithms, key)
+          raise OpenID4VP::VerificationError, "alg none rejected" if alg.nil? || alg == "none"
+          raise OpenID4VP::VerificationError, "algorithm not allowed" unless algorithms.include?(alg)
+          raise OpenID4VP::VerificationError, "algorithm does not match key" unless Algorithms.key_matches?(alg, key)
+        end
+
+        # Signs `signing_input` (the compact `protected_b64.payload_b64`)
+        # with `jwk`, via jwt's JWA registry (jwt-eddsa registers "EdDSA").
+        # jwt itself handles the ECDSA DER<->raw conversion and RSA-PSS.
+        def sign_raw(alg, jwk, signing_input)
+          jwa = ::JWT::JWA.resolve(alg)
+          jwa.sign(data: signing_input, signing_key: signing_key_for(alg, jwk))
+        rescue ::JWT::Error, ArgumentError, ::OpenSSL::PKey::PKeyError => e
+          raise OpenID4VP::InvalidRequest, "jws: #{e.message}"
+        end
+
+        def verify_raw(alg, jwk, signing_input, signature)
+          jwa = ::JWT::JWA.resolve(alg)
+          jwa.verify(data: signing_input, signature: signature, verification_key: verification_key_for(alg, jwk))
+        rescue ::JWT::Error, OpenSSL::PKey::PKeyError, ArgumentError
+          false
+        end
+
+        # Verifies `compact`'s signature via jwt's public JWT::EncodedToken
+        # API instead of the private JWT::JWA.resolve `verify_raw` uses
+        # (kept for `verify_json_signature`, whose per-signer signing input
+        # isn't a plain compact string EncodedToken can parse). `alg` has
+        # already been checked against our allow-list and against `key` by
+        # `check_alg!`, so only that single resolved alg is passed here.
+        # `EncodedToken#verify_signature!` only reads the header and the raw
+        # encoded payload bytes to build the signing input -- it never
+        # parses the payload as JSON (only claim verification/`#payload`
+        # would) -- so this is safe for both JSON-object and raw-string JWS
+        # payloads (e.g. SD-JWT's Issuer-signed JWT and KB-JWT bodies).
+        def verify_compact_signature!(compact, alg, key)
+          ::JWT::EncodedToken.new(compact).verify_signature!(algorithm: alg, key: verification_key_for(alg, key))
+        rescue ::JWT::VerificationError, ::JWT::DecodeError, ::ArgumentError, ::OpenSSL::OpenSSLError
+          raise OpenID4VP::VerificationError, "signature verification failed"
+        end
+
+        # jwt-eddsa's algorithm requires an Ed25519::SigningKey/VerifyKey
+        # (from the `ed25519` gem), not an OpenSSL::PKey.
+        def signing_key_for(alg, jwk)
+          return jwk.to_openssl unless alg == "EdDSA"
+
+          ::Ed25519::SigningKey.new(jwk.to_openssl.raw_private_key)
+        end
+
+        def verification_key_for(alg, jwk)
+          return jwk.to_openssl unless alg == "EdDSA"
+
+          ::Ed25519::VerifyKey.new(jwk.to_openssl.raw_public_key)
+        end
+      end
+    end
+  end
+end

data/lib/openid4vp/jose.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module OpenID4VP
+  # JSON Object Signing and Encryption (JOSE) primitives: JWK and JWKSet
+  # (this task), plus JWS/JWE in later tasks. Built on stdlib OpenSSL 3.
+  module JOSE
+  end
+end

data/lib/openid4vp/mdoc/builder.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "cose"
+require_relative "../mdoc"
+require_relative "../errors"
+require_relative "../x509"
+require_relative "cose_key"
+require_relative "issuer_signed"
+require_relative "mso"
+require_relative "device_signed"
+require_relative "document"
+require_relative "device_response"
+
+module OpenID4VP
+  module Mdoc
+    # Test/wallet-side mdoc issuance and presentation builder: issues an
+    # IssuerSigned credential (Builder.issue) and, given a set of disclosed
+    # elements, builds a signed DeviceResponse (Builder.device_response).
+    module Builder
+      RANDOM_SALT_BYTES = 16
+
+      module_function
+
+      # name_spaces: {namespace => {element_identifier => value}}, where
+      # value may be a Date (encoded as full-date), a Time (encoded as
+      # tdate) or any other CBOR-encodable value. issuer_key: the issuer's
+      # private OpenID4VP::JOSE::JWK. issuer_chain: [OpenSSL::X509::Certificate,
+      # ...] (leaf first) embedded as IssuerAuth's x5chain. device_key: the
+      # mdoc holder's OpenID4VP::JOSE::JWK (its public part is bound into the
+      # MSO's deviceKeyInfo).
+      def issue(
+        doc_type:, name_spaces:, issuer_key:, issuer_chain:, device_key:,
+        valid_from:, valid_until:, digest_alg: "SHA-256", alg: -7, signed: ::Time.now, kid: nil
+      )
+        items_by_namespace = build_items(name_spaces)
+        value_digests = digests_for(items_by_namespace, digest_alg)
+
+        CoseKey.check_alg_matches_key!(alg, issuer_key)
+
+        mso_bytes = MSO.build(
+          doc_type: doc_type, digest_algorithm: digest_alg, value_digests: value_digests,
+          device_key: device_key, valid_from: valid_from, valid_until: valid_until, signed: signed
+        )
+        protected_headers = { 1 => alg }
+        protected_headers[4] = kid if kid
+        issuer_auth = ::COSE::Sign1.new(
+          protected_headers: protected_headers,
+          unprotected_headers: { IssuerSigned::LABEL_X5CHAIN => x5chain_header(issuer_chain) },
+          payload: mso_bytes
+        )
+        issuer_auth.sign(CoseKey.from_jwk(issuer_key))
+
+        IssuerSigned.new(name_spaces: items_by_namespace, issuer_auth: issuer_auth)
+      end
+
+      # issuer_signed: an IssuerSigned as returned by `.issue`. disclose:
+      # {namespace => [element_identifier, ...]}, the elements the holder
+      # chooses to reveal. device_key: the mdoc holder's private
+      # OpenID4VP::JOSE::JWK (must match the public key bound in the MSO).
+      # session_transcript: the SessionTranscript array (e.g. from
+      # SessionTranscript.for_request). device_name_spaces: elements
+      # authenticated by, but not part of, the issuer-signed credential
+      # (rarely used; defaults to none).
+      def device_response(
+        issuer_signed:, doc_type:, disclose:, device_key:, session_transcript:, device_name_spaces: {}, alg: -7,
+        device_kid: nil
+      )
+        disclosed_issuer_signed = IssuerSigned.new(
+          name_spaces: filter_disclosed(issuer_signed.name_spaces, disclose), issuer_auth: issuer_signed.issuer_auth
+        )
+        device_signed = DeviceSigned.build(
+          device_name_spaces: device_name_spaces, device_key: device_key,
+          session_transcript: session_transcript, doc_type: doc_type, alg: alg, kid: device_kid
+        )
+        document = Document.new(
+          doc_type: doc_type, issuer_signed: disclosed_issuer_signed, device_signed: device_signed
+        )
+
+        DeviceResponse.new(version: "1.0", documents: [document], status: 0)
+      end
+
+      def build_items(name_spaces)
+        name_spaces.to_h do |namespace, elements|
+          used_ids = {}
+          items = elements.map do |element_identifier, element_value|
+            IssuerSignedItem.build(
+              digest_id: unique_digest_id(used_ids), random: ::SecureRandom.random_bytes(RANDOM_SALT_BYTES),
+              element_identifier: element_identifier.to_s, element_value: element_value
+            )
+          end
+          [namespace, items]
+        end
+      end
+      private_class_method :build_items
+
+      def unique_digest_id(used_ids)
+        loop do
+          candidate = ::SecureRandom.random_number(1_000_000)
+          next if used_ids.key?(candidate)
+
+          used_ids[candidate] = true
+          return candidate
+        end
+      end
+      private_class_method :unique_digest_id
+
+      def digests_for(items_by_namespace, digest_alg)
+        items_by_namespace.transform_values do |items|
+          items.to_h { |item| [item.digest_id, item.digest(digest_alg)] }
+        end
+      end
+      private_class_method :digests_for
+
+      def x5chain_header(chain)
+        ders = Array(chain).map { |cert| OpenID4VP::X509.parse(cert).to_der.b }
+        ders.length == 1 ? ders.first : ders
+      end
+      private_class_method :x5chain_header
+
+      def filter_disclosed(name_spaces, disclose)
+        disclose.to_h do |namespace, element_identifiers|
+          items = name_spaces.fetch(namespace) do
+            raise OpenID4VP::InvalidRequest, "mdoc: unknown namespace #{namespace.inspect}"
+          end
+          [namespace, items.select { |item| element_identifiers.include?(item.element_identifier) }]
+        end
+      end
+      private_class_method :filter_disclosed
+    end
+  end
+end

data/lib/openid4vp/mdoc/cbor_values.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "date"
+require_relative "../mdoc"
+
+module OpenID4VP
+  module Mdoc
+    # Shared CBOR elementValue encode/decode helpers for mdoc namespace
+    # elements (ISO 18013-5 §7.2.1 date/time types), used by both
+    # IssuerSignedItem (issuerSigned nameSpaces) and DeviceSigned
+    # (deviceSigned nameSpaces): a Ruby Date encodes as full-date (tag 1004),
+    # a Time encodes as tdate (tag 0); any other value is CBOR-encodable
+    # as-is. Both tag forms decode back to their raw String (never a
+    # Date/Time instance), matching how ISO 18013-5 element values are
+    # exposed in `claims`.
+    module CborValues
+      module_function
+
+      def encode(value)
+        case value
+        when ::Date then CBOR::Tagged.new(1004, value.strftime("%Y-%m-%d"))
+        when ::Time then CBOR::Tagged.new(0, value.utc.strftime("%Y-%m-%dT%H:%M:%SZ"))
+        else value
+        end
+      end
+
+      def decode(value)
+        value.is_a?(CBOR::Tagged) ? value.value : value
+      end
+    end
+  end
+end

data/lib/openid4vp/mdoc/cose_key.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "cose"
+require_relative "../mdoc"
+require_relative "../errors"
+require_relative "../jose/jwk"
+
+module OpenID4VP
+  module Mdoc
+    # OpenID4VP::JOSE::JWK <-> COSE::Key::EC2 (the `cose` gem) conversions,
+    # used internally by MSO (deviceKeyInfo.deviceKey), Builder and Verifier
+    # to bridge this gem's JWK-based key representation with cose-ruby's
+    # COSE_Sign1/COSE_Key API. EC keys only (the only kty used by ISO mdoc
+    # COSE_Sign1 structures).
+    module CoseKey
+      # COSE alg identifier (protected header label 1 value) -> expected JOSE
+      # EC curve name, for the ECDSA algs ISO mdoc COSE_Sign1 structures use.
+      CURVE_FOR_ALG = { -7 => "P-256", -35 => "P-384", -36 => "P-521" }.freeze
+
+      module_function
+
+      # jwk: an OpenID4VP::JOSE::JWK with kty "EC" (private or public).
+      # Raises OpenID4VP::InvalidRequest (not a bare NoMethodError/
+      # RuntimeError out of COSE::Key::EC2.from_pkey) for a non-EC key.
+      def from_jwk(jwk)
+        ::COSE::Key::EC2.from_pkey(jwk.to_openssl)
+      rescue ::NoMethodError, ::RuntimeError
+        raise OpenID4VP::InvalidRequest, "mdoc requires an EC key"
+      end
+
+      # cose_key: a ::COSE::Key::EC2 (public or private).
+      def to_jwk(cose_key)
+        OpenID4VP::JOSE::JWK.from_openssl(cose_key.to_pkey)
+      end
+
+      # Rebuilds `cose_key` (a ::COSE::Key::EC2) carrying `kid` (may be nil),
+      # preserving its key material and other COSE::Key::Base attributes
+      # (alg, key_ops, base_iv). Used at verification time so the
+      # verification key's kid always matches the signed message's own kid
+      # header (label 4): cose-ruby's COSE::Sign1#verify requires
+      # `key.kid == headers.kid`, but our verification keys are derived
+      # independently of any header value -- from a chain-validated X.509
+      # leaf certificate (IssuerAuth) or an already-verified MSO
+      # deviceKeyInfo (DeviceSignature) -- so leaving kid unset would
+      # incorrectly reject a spec-valid IssuerAuth/DeviceSignature that
+      # happens to carry a kid header.
+      def with_kid(cose_key, kid)
+        return cose_key if cose_key.kid == kid
+
+        ::COSE::Key::EC2.new(
+          crv: cose_key.crv, x: cose_key.x, y: cose_key.y, d: cose_key.d, kid: kid,
+          alg: cose_key.alg, key_ops: cose_key.key_ops, base_iv: cose_key.base_iv
+        )
+      end
+
+      # Raises OpenID4VP::InvalidRequest unless `jwk` is an EC key on the
+      # curve COSE alg `alg` expects (e.g. alg -7/ES256 requires a P-256
+      # key), so a mismatched alg/key pairing is rejected before signing
+      # rather than either silently producing a spec-violating signature or
+      # failing later, more confusingly, on verification.
+      def check_alg_matches_key!(alg, jwk)
+        expected_curve = CURVE_FOR_ALG.fetch(alg) { raise OpenID4VP::InvalidRequest, "mdoc: unsupported alg #{alg.inspect}" }
+        return if jwk.kty == "EC" && jwk.crv == expected_curve
+
+        raise OpenID4VP::InvalidRequest,
+              "mdoc: alg #{alg.inspect} requires an EC key on curve #{expected_curve.inspect}, " \
+              "got kty #{jwk.kty.inspect} crv #{jwk.crv.inspect}"
+      end
+    end
+  end
+end

data/lib/openid4vp/mdoc/device_authentication.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "../mdoc"
+
+module OpenID4VP
+  module Mdoc
+    # DeviceAuthenticationBytes (ISO 18013-5 §9.1.3.4): the payload covered
+    # by a DeviceSignature/DeviceMac, binding the SessionTranscript, docType
+    # and disclosed DeviceSigned nameSpaces together.
+    #
+    #   DeviceAuthentication = [
+    #     "DeviceAuthentication", SessionTranscript, DocType, DeviceNameSpacesBytes
+    #   ]
+    #   DeviceAuthenticationBytes = #6.24(bstr .cbor DeviceAuthentication)
+    #
+    # Used identically by both DeviceSigned.build (to compute the bytes to
+    # sign) and OpenID4VP::Mdoc::Verifier (to recompute the same bytes as the
+    # detached payload to verify against).
+    module DeviceAuthentication
+      module_function
+
+      # session_transcript: the SessionTranscript array (e.g. from
+      # SessionTranscript.for_request). name_spaces_bytes: the
+      # DeviceNameSpacesBytes value itself (a CBOR::Tagged(24, ...)), as
+      # exposed by DeviceSigned#name_spaces_bytes.
+      def bytes(session_transcript:, doc_type:, name_spaces_bytes:)
+        array = ["DeviceAuthentication", session_transcript, doc_type, name_spaces_bytes]
+        CBOR.encode(CBOR::Tagged.new(24, CBOR.encode(array)))
+      end
+    end
+  end
+end

data/lib/openid4vp/mdoc/device_response.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative "../mdoc"
+require_relative "../errors"
+require_relative "../util/base64url"
+require_relative "document"
+
+module OpenID4VP
+  module Mdoc
+    # DeviceResponse = {"version" => "1.0", "documents" => [Document],
+    # "status" => 0} (ISO 18013-5 §8.3.2.1.2.2), the CBOR structure carried
+    # base64url-encoded in a `mso_mdoc` `vp_token` entry (OpenID4VP §B.2.5).
+    class DeviceResponse
+      DEFAULT_VERSION = "1.0"
+
+      attr_reader :version, :documents, :status
+
+      # A base64url string only ever contains these characters; raw CBOR
+      # bytes for any non-trivial DeviceResponse (digests, signatures, ...)
+      # are effectively guaranteed to contain a byte outside this set.
+      B64URL_CONTENT = /\A[A-Za-z0-9_-]+\z/
+
+      class << self
+        # bytes: raw CBOR bytes (a binary String). Tolerant: a String whose
+        # content matches base64url's charset is treated as base64url (e.g.
+        # a vp_token entry passed here directly), so this also accepts what
+        # `parse_b64url` accepts. Prefer `parse_b64url` when the input is
+        # known to be base64url-encoded.
+        def parse(bytes)
+          build(decode(looks_like_b64url?(bytes) ? Util::Base64url.decode(bytes) : bytes))
+        end
+
+        # str: a base64url-encoded String (as received in a vp_token entry).
+        def parse_b64url(str)
+          build(decode(Util::Base64url.decode(str)))
+        end
+
+        def encode(documents, version: DEFAULT_VERSION, status: 0)
+          CBOR.encode({ "version" => version, "documents" => documents.map(&:to_map), "status" => status })
+        end
+
+        private
+
+        def looks_like_b64url?(input)
+          input.is_a?(::String) && B64URL_CONTENT.match?(input)
+        end
+
+        def build(map)
+          raise OpenID4VP::InvalidResponse, "mdoc: invalid DeviceResponse" unless map.is_a?(::Hash)
+
+          documents = Array(map["documents"]).map { |d| Document.parse(d) }
+          new(
+            version: map.fetch("version") { raise OpenID4VP::InvalidResponse, "mdoc: missing version" },
+            documents: documents,
+            status: map.fetch("status") { raise OpenID4VP::InvalidResponse, "mdoc: missing status" }
+          )
+        end
+
+        def decode(bytes)
+          CBOR.decode(bytes)
+        rescue CBOR::MalformedFormatError, EOFError, TypeError
+          raise OpenID4VP::InvalidResponse, "mdoc: malformed DeviceResponse"
+        end
+      end
+
+      def initialize(version:, documents:, status:)
+        @version = version
+        @documents = documents
+        @status = status
+      end
+
+      def to_b64url
+        Util::Base64url.encode(self.class.encode(documents, version: version, status: status))
+      end
+    end
+  end
+end