openid4vp 0.1.0

data/lib/openid4vp/request_verification/x509_san_dns.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "verified_request"
+require_relative "../errors"
+require_relative "../x509"
+require_relative "../x509/chain_validator"
+require_relative "../jose/jwk"
+
+module OpenID4VP
+  module RequestVerification
+    # `x509_san_dns` Client Identifier Prefix (OpenID4VP §5.9.3): the
+    # original Client Identifier is a DNS name that MUST match a dNSName
+    # Subject Alternative Name entry in the leaf certificate carried in the
+    # request's `x5c` JOSE header.
+    class X509SanDns < Base
+      def verify!(client_id, request, parsed, dc_api: false)
+        raise OpenID4VP::InvalidRequest, "signed request required" if parsed.nil?
+
+        certs = parsed.x5c_certs
+        raise OpenID4VP::InvalidRequest, "x5c required" if certs.empty?
+
+        leaf = OpenID4VP::X509::ChainValidator.new(
+          trust_anchors: config.x509_trust_anchors, time: config.current_time
+        ).validate!(certs)
+
+        unless OpenID4VP::X509.dns_sans(leaf).include?(client_id.original)
+          raise OpenID4VP::VerificationError, "SAN mismatch"
+        end
+
+        signing_key = OpenID4VP::JOSE::JWK.from_openssl(leaf.public_key)
+        verify_signature!(parsed, signing_key)
+        check_return_uri_host!(client_id, request, dc_api)
+
+        VerifiedRequest.new(
+          request: request, client_id: client_id, verifier_metadata: request.client_metadata,
+          signed: true, signing_key: signing_key, parsed: parsed, attestation: nil
+        )
+      end
+
+      private
+
+      def check_return_uri_host!(client_id, request, dc_api)
+        return if dc_api || config.trusted_client_ids.include?(client_id.to_s)
+
+        return_uri = request.return_uri
+        return if return_uri.nil?
+
+        host = begin
+          ::URI.parse(return_uri).host
+        rescue ::URI::InvalidURIError
+          raise OpenID4VP::VerificationError, "malformed return URI"
+        end
+        return if host&.casecmp?(client_id.original)
+
+        raise OpenID4VP::VerificationError, "return URI host mismatch"
+      end
+    end
+  end
+end

data/lib/openid4vp/request_verification.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module OpenID4VP
+  # Wallet-side request verification (OpenID4VP §5.9): one strategy per
+  # Client Identifier Prefix (`OpenID4VP::RequestVerification::Base`
+  # subclasses), dispatched by `OpenID4VP::RequestVerification::Resolver`
+  # according to `OpenID4VP::RequestVerification::Config`.
+  module RequestVerification
+  end
+end

data/lib/openid4vp/response_encryption.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "jose/jwe"
+
+module OpenID4VP
+  # OpenID4VP §8.3: selects the Verifier's encryption key, `alg` and `enc`
+  # for an encrypted Authorization Response from the Verifier's
+  # `client_metadata` (a `Metadata::VerifierMetadata`), optionally narrowed
+  # by what the Wallet itself supports, and encrypts response payloads to it.
+  class ResponseEncryption
+    def initialize(verifier_metadata:, wallet_supported_algs: nil, wallet_supported_encs: nil)
+      @verifier_metadata = verifier_metadata
+      @wallet_supported_algs = wallet_supported_algs
+      @wallet_supported_encs = wallet_supported_encs
+    end
+
+    # The JWK to encrypt to. Raises OpenID4VP::InvalidRequest when the
+    # Verifier's metadata has no usable encryption key.
+    def key
+      return @key if @key
+
+      @key = @verifier_metadata.encryption_key(supported_algs: @wallet_supported_algs)
+      raise OpenID4VP::InvalidRequest, "no usable encryption key" if @key.nil?
+
+      @key
+    end
+
+    def alg
+      key.alg
+    end
+
+    # The JWE `enc` value: the first entry common to the Verifier's
+    # `encrypted_response_enc_values_supported` and the Wallet's supported
+    # `enc` values (all are considered supported when the latter is nil).
+    # Raises OpenID4VP::InvalidRequest when there is no common value.
+    def enc
+      return @enc if @enc
+
+      verifier_encs = @verifier_metadata.encrypted_response_enc_values_supported
+      common = @wallet_supported_encs ? (verifier_encs & @wallet_supported_encs) : verifier_encs
+      raise OpenID4VP::InvalidRequest, "no common content encryption algorithm" if common.empty?
+
+      @enc = common.first
+    end
+
+    def encrypt(payload_hash)
+      OpenID4VP::JOSE::JWE.encrypt(payload_hash, recipient: key, alg: alg, enc: enc)
+    end
+  end
+end

data/lib/openid4vp/response_endpoint_result.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module OpenID4VP
+  # OpenID4VP §8.2: the JSON body a Response Endpoint returns to the Wallet
+  # (HTTP 200, application/json, Cache-Control: no-store) after processing a
+  # direct_post[.jwt] Authorization Response.
+  class ResponseEndpointResult
+    HEADERS = { "content-type" => "application/json", "cache-control" => "no-store" }.freeze
+
+    attr_reader :redirect_uri
+
+    def initialize(redirect_uri: nil)
+      @redirect_uri = redirect_uri
+      freeze
+    end
+
+    def status
+      200
+    end
+
+    def headers
+      HEADERS
+    end
+
+    def to_h
+      @redirect_uri.nil? ? {} : { "redirect_uri" => @redirect_uri }
+    end
+
+    def to_json(*)
+      ::JSON.generate(to_h, *)
+    end
+  end
+end

data/lib/openid4vp/response_mode.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module OpenID4VP
+  module ResponseMode
+    FRAGMENT = "fragment"
+    QUERY = "query"
+    DIRECT_POST = "direct_post"
+    DIRECT_POST_JWT = "direct_post.jwt"
+    DC_API = "dc_api"
+    DC_API_JWT = "dc_api.jwt"
+
+    ALL = [FRAGMENT, QUERY, DIRECT_POST, DIRECT_POST_JWT, DC_API, DC_API_JWT].freeze
+
+    module_function
+
+    def direct_post?(mode)
+      return false if mode.nil?
+
+      [DIRECT_POST, DIRECT_POST_JWT].include?(mode)
+    end
+
+    def dc_api?(mode)
+      return false if mode.nil?
+
+      [DC_API, DC_API_JWT].include?(mode)
+    end
+
+    def encrypted?(mode)
+      return false if mode.nil?
+
+      mode.end_with?(".jwt")
+    end
+
+    def redirect?(mode)
+      return false if mode.nil?
+
+      [FRAGMENT, QUERY].include?(mode)
+    end
+
+    def default
+      FRAGMENT
+    end
+  end
+end

data/lib/openid4vp/response_type.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module OpenID4VP
+  module ResponseType
+    VP_TOKEN = "vp_token"
+  end
+end

data/lib/openid4vp/sd_jwt/digest.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "../sd_jwt"
+require_relative "../errors"
+require_relative "../util/base64url"
+
+module OpenID4VP
+  module SdJwt
+    # SD-JWT `_sd_alg` digest algorithms (draft-ietf-oauth-selective-disclosure-jwt-22
+    # §5.1.1.2): sha-256 (the default), sha-384, sha-512.
+    module Digest
+      ALGS = {
+        "sha-256" => "SHA256",
+        "sha-384" => "SHA384",
+        "sha-512" => "SHA512"
+      }.freeze
+
+      module_function
+
+      # base64url(hash(str)), hashing the ASCII bytes of `str` verbatim (no
+      # base64url decoding first) with the OpenSSL digest named by `alg`.
+      def hash(alg, str)
+        digest_name = ALGS.fetch(alg) do
+          raise OpenID4VP::PresentationInvalid, "sd-jwt: unsupported _sd_alg #{alg.inspect}"
+        end
+        Util::Base64url.encode(::OpenSSL::Digest.digest(digest_name, str))
+      end
+    end
+  end
+end

data/lib/openid4vp/sd_jwt/disclosure.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require_relative "../sd_jwt"
+require_relative "digest"
+require_relative "../errors"
+require_relative "../util/base64url"
+
+module OpenID4VP
+  module SdJwt
+    # A single SD-JWT disclosure (draft-ietf-oauth-selective-disclosure-jwt-22
+    # §5.2): base64url(JSON array). `[salt, name, value]` discloses an object
+    # property (`name` is a String); `[salt, value]` discloses an array
+    # element (`name` is nil).
+    class Disclosure
+      attr_reader :salt, :name, :value, :raw
+
+      def initialize(salt:, value:, name: nil, raw: nil)
+        @salt = salt
+        @name = name
+        @value = value
+        @raw = raw || self.class.encode(salt: salt, name: name, value: value)
+        freeze
+      end
+
+      class << self
+        # Parses a base64url-encoded disclosure, preserving `raw` verbatim.
+        # Raises PresentationInvalid on malformed input: invalid
+        # base64url/JSON, not a 2- or 3-element array, or a non-String
+        # salt/name.
+        def parse(raw)
+          array = decode_array(raw)
+
+          case array.size
+          when 3
+            salt, name, value = array
+            unless salt.is_a?(::String) && name.is_a?(::String)
+              raise OpenID4VP::PresentationInvalid, "sd-jwt: disclosure salt and name must be strings"
+            end
+
+            new(salt: salt, name: name, value: value, raw: raw)
+          when 2
+            salt, value = array
+            raise OpenID4VP::PresentationInvalid, "sd-jwt: disclosure salt must be a string" unless salt.is_a?(::String)
+
+            new(salt: salt, value: value, raw: raw)
+          else
+            raise OpenID4VP::PresentationInvalid, "sd-jwt: disclosure must be a 2- or 3-element array"
+          end
+        end
+
+        # Builds a disclosure for an object property (`name` given) or an
+        # array element (`name` nil), generating a fresh 128-bit salt unless
+        # one is given.
+        def build(value:, name: nil, salt: nil)
+          new(salt: salt || random_salt, name: name, value: value)
+        end
+
+        def encode(salt:, name:, value:)
+          array = name.nil? ? [salt, value] : [salt, name, value]
+          Util::Base64url.encode(::JSON.generate(array))
+        end
+
+        def random_salt
+          Util::Base64url.encode(::SecureRandom.random_bytes(16))
+        end
+
+        private
+
+        def decode_array(raw)
+          array =
+            begin
+              Util::Base64url.decode_json(raw)
+            rescue OpenID4VP::InvalidRequest
+              raise OpenID4VP::PresentationInvalid, "sd-jwt: invalid disclosure encoding"
+            end
+          raise OpenID4VP::PresentationInvalid, "sd-jwt: disclosure must be a JSON array" unless array.is_a?(::Array)
+
+          array
+        end
+      end
+
+      # Whether this disclosure discloses an array element (as opposed to an
+      # object property).
+      def array_element?
+        name.nil?
+      end
+
+      # base64url(hash(raw)) -- the digest referenced by `_sd` arrays or by
+      # `{"..." => digest}` array items.
+      def digest(alg = "sha-256")
+        Digest.hash(alg, raw)
+      end
+
+      def ==(other)
+        other.is_a?(Disclosure) && raw == other.raw
+      end
+      alias eql? ==
+
+      def hash
+        raw.hash
+      end
+    end
+  end
+end

data/lib/openid4vp/sd_jwt/issuer.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require_relative "../sd_jwt"
+require_relative "disclosure"
+require_relative "../errors"
+require_relative "../util/base64url"
+require_relative "../jose/jws"
+
+module OpenID4VP
+  module SdJwt
+    # Issues an IETF SD-JWT VC (`dc+sd-jwt`): builds selectively disclosable
+    # claims (draft-ietf-oauth-selective-disclosure-jwt-22 §5.1) and signs
+    # the resulting Issuer-signed JWT.
+    module Issuer
+      module_function
+
+      # `disclosable` is an Array of claims-path-like Arrays (of String
+      # property names / Integer array indices, or ClaimsPathPointer),
+      # each addressing a single object property or array element to make
+      # selectively disclosable -- only the path's final component becomes a
+      # disclosure; intermediate objects/arrays are navigated as plain
+      # structure. Returns `"<issuer-jwt>~<disclosure 1>~...~"`.
+      def issue(claims:, key:, vct:, iss:, iat:, exp:, disclosable: [], holder_jwk: nil, alg: nil, x5c: nil,
+                decoy: 0, typ: "dc+sd-jwt")
+        payload = deep_dup(claims)
+        payload["vct"] = vct
+        payload["iss"] = iss
+        payload["iat"] = iat
+        payload["exp"] = exp
+        payload["_sd_alg"] = "sha-256"
+        payload["cnf"] = { "jwk" => holder_jwk.to_public.to_h } if holder_jwk
+
+        # Deepest paths first, so a disclosure that itself contains a nested
+        # selectively-disclosable property (e.g. both ["address"] and
+        # ["address", "street_address"] listed) sees the still-plain parent
+        # object before it is turned into its own disclosure.
+        ordered = disclosable.sort_by { |path| -path_components(path).size }
+        disclosures = ordered.flat_map { |path| apply_disclosure!(payload, path_components(path)) }
+
+        add_decoys!(payload, decoy) if decoy.positive?
+        sort_sd_arrays!(payload)
+
+        header = { "typ" => typ }
+        header["x5c"] = x5c if x5c
+
+        issuer_jwt = OpenID4VP::JOSE::JWS.sign(payload, key: key, alg: alg, header: header)
+        "#{issuer_jwt}~#{disclosures.map { |d| "#{d.raw}~" }.join}"
+      end
+
+      def path_components(path)
+        path.respond_to?(:components) ? path.components : path
+      end
+      private_class_method :path_components
+
+      def deep_dup(claims)
+        ::JSON.parse(::JSON.generate(claims))
+      end
+      private_class_method :deep_dup
+
+      def apply_disclosure!(payload, components)
+        if !components.is_a?(::Array) || components.empty?
+          raise OpenID4VP::InvalidRequest, "sd-jwt: disclosable path must be a non-empty array"
+        end
+
+        parent = components[0..-2].reduce(payload) { |node, component| navigate(node, component) }
+        build_disclosure!(parent, components.last)
+      end
+      private_class_method :apply_disclosure!
+
+      def navigate(node, component)
+        case component
+        when ::String
+          unless node.is_a?(::Hash) && node.key?(component)
+            raise OpenID4VP::InvalidRequest, "sd-jwt: no such claim #{component.inspect} to navigate"
+          end
+
+          node[component]
+        when ::Integer
+          unless node.is_a?(::Array) && component < node.size
+            raise OpenID4VP::InvalidRequest, "sd-jwt: no such index #{component} to navigate"
+          end
+
+          node[component]
+        else
+          raise OpenID4VP::InvalidRequest, "sd-jwt: unsupported claims path component #{component.inspect}"
+        end
+      end
+      private_class_method :navigate
+
+      def build_disclosure!(parent, final)
+        case final
+        when ::String
+          unless parent.is_a?(::Hash) && parent.key?(final)
+            raise OpenID4VP::InvalidRequest, "sd-jwt: no such claim #{final.inspect} to disclose"
+          end
+
+          disclosure = Disclosure.build(name: final, value: parent.delete(final))
+          (parent["_sd"] ||= []) << disclosure.digest
+          disclosure
+        when ::Integer
+          unless parent.is_a?(::Array) && final < parent.size
+            raise OpenID4VP::InvalidRequest, "sd-jwt: no such index #{final} to disclose"
+          end
+
+          disclosure = Disclosure.build(value: parent[final])
+          parent[final] = { "..." => disclosure.digest }
+          disclosure
+        else
+          raise OpenID4VP::InvalidRequest, "sd-jwt: unsupported claims path component #{final.inspect}"
+        end
+      end
+      private_class_method :build_disclosure!
+
+      def add_decoys!(payload, count)
+        payload["_sd"] ||= []
+        count.times { payload["_sd"] << Util::Base64url.encode(::SecureRandom.random_bytes(32)) }
+      end
+      private_class_method :add_decoys!
+
+      def sort_sd_arrays!(node)
+        case node
+        when ::Hash
+          node["_sd"] = node["_sd"].sort if node["_sd"].is_a?(::Array)
+          node.each_value { |value| sort_sd_arrays!(value) }
+        when ::Array
+          node.each { |value| sort_sd_arrays!(value) }
+        end
+      end
+      private_class_method :sort_sd_arrays!
+    end
+  end
+end

data/lib/openid4vp/sd_jwt/kb_jwt.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative "../sd_jwt"
+require_relative "../errors"
+require_relative "../util"
+require_relative "../jose/jws"
+require_relative "../jose/algorithms"
+
+module OpenID4VP
+  module SdJwt
+    # The SD-JWT Key Binding JWT (draft-ietf-oauth-selective-disclosure-jwt-22
+    # §4.3): proves possession of the key in the Issuer-signed JWT's
+    # `cnf.jwk`, binding the presentation to a `nonce`/`aud` and to the exact
+    # disclosures presented (`sd_hash`).
+    module KbJwt
+      TYP = "kb+jwt"
+
+      module_function
+
+      # Signs a Key Binding JWT with `key` (the holder's private key). `iat`
+      # defaults to `Time.now.to_i`; `extra` claims (e.g.
+      # `transaction_data_hashes`) are merged in.
+      def build(aud:, nonce:, sd_hash:, key:, alg: nil, iat: nil, extra: {})
+        payload = { "iat" => iat || Time.now.to_i, "aud" => aud, "nonce" => nonce, "sd_hash" => sd_hash }.merge(extra)
+        OpenID4VP::JOSE::JWS.sign(payload, key: key, alg: alg, header: { "typ" => TYP })
+      end
+
+      # Verifies a Key Binding JWT against `key` (the holder's public key
+      # from the Issuer-signed JWT's `cnf.jwk`): `typ`, signature, `aud`,
+      # `nonce`, `sd_hash` and `iat` (within `leeway` seconds of `now`).
+      # Raises HolderBindingInvalid on any failure. Returns the payload Hash.
+      def verify(compact, key:, expected_aud:, expected_nonce:, expected_sd_hash:, now: Time.now, leeway: 60,
+                 algorithms: OpenID4VP::JOSE::Algorithms::SIGNING)
+        raise OpenID4VP::HolderBindingInvalid, "kb-jwt: missing" if compact.nil? || compact.empty?
+
+        verified = verify_signature(compact, key, algorithms)
+        check_typ!(verified.header)
+        payload = verified.payload
+        raise OpenID4VP::HolderBindingInvalid, "kb-jwt: payload is not a JSON object" unless payload.is_a?(::Hash)
+
+        check_claims!(payload, expected_aud, expected_nonce, expected_sd_hash)
+        check_iat!(payload["iat"], now, leeway)
+
+        payload
+      end
+
+      def verify_signature(compact, key, algorithms)
+        OpenID4VP::JOSE::JWS.verify(compact, key: key, algorithms: algorithms)
+      rescue OpenID4VP::InvalidRequest, OpenID4VP::VerificationError => e
+        raise OpenID4VP::HolderBindingInvalid, "kb-jwt: #{e.message}"
+      end
+      private_class_method :verify_signature
+
+      def check_typ!(header)
+        return if header["typ"] == TYP
+
+        raise OpenID4VP::HolderBindingInvalid, "kb-jwt: unexpected typ #{header['typ'].inspect}"
+      end
+      private_class_method :check_typ!
+
+      def check_claims!(payload, expected_aud, expected_nonce, expected_sd_hash)
+        raise OpenID4VP::HolderBindingInvalid, "kb-jwt: aud mismatch" unless payload["aud"] == expected_aud
+        raise OpenID4VP::HolderBindingInvalid, "kb-jwt: nonce mismatch" unless payload["nonce"] == expected_nonce
+
+        sd_hash = payload["sd_hash"]
+        return if sd_hash.is_a?(::String) && OpenID4VP::Util.secure_compare(sd_hash, expected_sd_hash)
+
+        raise OpenID4VP::HolderBindingInvalid, "kb-jwt: sd_hash mismatch"
+      end
+      private_class_method :check_claims!
+
+      def check_iat!(iat, now, leeway)
+        raise OpenID4VP::HolderBindingInvalid, "kb-jwt: missing iat" unless iat.is_a?(::Integer)
+
+        return if (iat - now.to_i).abs <= leeway
+
+        raise OpenID4VP::HolderBindingInvalid, "kb-jwt: iat outside of allowed leeway"
+      end
+      private_class_method :check_iat!
+    end
+  end
+end

data/lib/openid4vp/sd_jwt/parser.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "../sd_jwt"
+require_relative "disclosure"
+require_relative "digest"
+require_relative "../errors"
+
+module OpenID4VP
+  module SdJwt
+    # Splits an SD-JWT(+KB) compact serialization
+    # (`<Issuer-signed JWT>~<Disclosure 1>~...~<Disclosure N>~<KB-JWT>`, the
+    # KB-JWT being optional) into its parts, per
+    # draft-ietf-oauth-selective-disclosure-jwt-22 §4.
+    module Parser
+      # `raw` is the exact string parsed. `kb_jwt` is nil when the input has
+      # no Key Binding JWT (the segment after the last "~" is empty).
+      Parsed = Struct.new(:issuer_jwt, :disclosures, :kb_jwt, :raw, keyword_init: true) do
+        # The presented string up to and including the last disclosure's
+        # trailing "~", omitting any Key Binding JWT -- the exact string a
+        # Key Binding JWT's `sd_hash` is computed over.
+        def without_kb
+          "#{issuer_jwt}~#{disclosures.map { |d| "#{d.raw}~" }.join}"
+        end
+
+        def sd_hash(alg = "sha-256")
+          Digest.hash(alg, without_kb)
+        end
+      end
+
+      module_function
+
+      # Raises PresentationInvalid unless `str` is a String containing at
+      # least one "~".
+      def parse(str)
+        unless str.is_a?(::String) && str.include?("~")
+          raise OpenID4VP::PresentationInvalid, "sd-jwt: malformed presentation (missing '~')"
+        end
+
+        parts = str.split("~", -1)
+        issuer_jwt = parts.first
+        kb_jwt = parts.last.empty? ? nil : parts.last
+        disclosures = parts[1..-2].map { |part| Disclosure.parse(part) }
+
+        Parsed.new(issuer_jwt: issuer_jwt, disclosures: disclosures, kb_jwt: kb_jwt, raw: str)
+      end
+    end
+  end
+end