openid4vp 0.1.0

data/lib/openid4vp/verifier_attestation.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require_relative "jose/jws"
+require_relative "jose/jwk"
+require_relative "errors"
+
+module OpenID4VP
+  # Verifier Attestation JWT (OpenID4VP 1.0 Section 12): a JWT issued to a
+  # Verifier by a party the Wallet trusts, binding the Verifier's client_id
+  # (`sub`) to a public key (`cnf.jwk`) the Verifier must prove possession of.
+  module VerifierAttestation
+    TYP = "verifier-attestation+jwt"
+
+    Verified = Struct.new(:payload, :cnf_jwk, :sub, :iss, :redirect_uris, :header, keyword_init: true)
+
+    module_function
+
+    # Issues a Verifier Attestation JWT signed by `signing_key`.
+    def issue(iss:, sub:, cnf_jwk:, exp:, signing_key:, alg: nil, iat: nil, nbf: nil, redirect_uris: nil, extra: {})
+      header = { "typ" => TYP }
+      header["kid"] = signing_key.kid if signing_key.kid
+
+      payload = { "iss" => iss, "sub" => sub, "exp" => exp_to_i(exp), "cnf" => { "jwk" => cnf_jwk.to_public.to_h } }
+      payload["iat"] = iat unless iat.nil?
+      payload["nbf"] = nbf unless nbf.nil?
+      payload["redirect_uris"] = redirect_uris unless redirect_uris.nil?
+      payload.merge!(extra)
+
+      OpenID4VP::JOSE::JWS.sign(payload, key: signing_key, alg: alg, header: header)
+    end
+
+    # Verifies a Verifier Attestation JWT against `trusted_issuers` (a Hash of
+    # `iss => JWK | [JWK]`, or a callable `(iss, header) -> JWK | [JWK] | nil`).
+    def verify(jwt, trusted_issuers:, now: Time.now, leeway: 60, algorithms: OpenID4VP::JOSE::Algorithms::SIGNING)
+      peeked = OpenID4VP::JOSE::JWS.peek(jwt)
+      unless peeked.header["typ"] == TYP
+        raise OpenID4VP::VerificationError, "verifier attestation: unexpected typ #{peeked.header['typ'].inspect}"
+      end
+
+      verified = verify_signature(jwt, peeked, trusted_issuers, algorithms)
+      payload = verified.payload
+      check_exp!(payload, now, leeway)
+      check_nbf!(payload, now, leeway)
+      sub = check_sub!(payload)
+      cnf_jwk = check_cnf!(payload)
+
+      Verified.new(payload: payload, cnf_jwk: cnf_jwk, sub: sub, iss: payload["iss"],
+                   redirect_uris: payload["redirect_uris"], header: verified.header)
+    end
+
+    def exp_to_i(exp)
+      exp.is_a?(Time) ? exp.to_i : exp
+    end
+    private_class_method :exp_to_i
+
+    def verify_signature(jwt, peeked, trusted_issuers, algorithms)
+      iss = peeked.payload.is_a?(Hash) ? peeked.payload["iss"] : nil
+      keys = Array(resolve_keys(trusted_issuers, iss, peeked.header))
+      raise OpenID4VP::VerificationError, "verifier attestation: untrusted attestation issuer" if keys.empty?
+
+      try_keys(jwt, keys_matching_kid(keys, peeked.header["kid"]), algorithms)
+    end
+    private_class_method :verify_signature
+
+    def resolve_keys(trusted_issuers, iss, header)
+      if trusted_issuers.respond_to?(:call)
+        trusted_issuers.call(iss, header)
+      elsif trusted_issuers.is_a?(Hash)
+        trusted_issuers[iss]
+      end
+    end
+    private_class_method :resolve_keys
+
+    # Keys whose `kid` matches the header's are tried first (when both are
+    # present); the rest follow, so a kid mismatch still falls back to trying
+    # every trusted key for the issuer.
+    def keys_matching_kid(keys, kid)
+      return keys if kid.nil?
+
+      matching, rest = keys.partition { |k| k.kid == kid }
+      matching + rest
+    end
+    private_class_method :keys_matching_kid
+
+    def try_keys(jwt, keys, algorithms)
+      last_error = nil
+      keys.each do |key|
+        return OpenID4VP::JOSE::JWS.verify(jwt, key: key, algorithms: algorithms)
+      rescue OpenID4VP::VerificationError => e
+        last_error = e
+      end
+      raise last_error || OpenID4VP::VerificationError.new("verifier attestation: untrusted attestation issuer")
+    end
+    private_class_method :try_keys
+
+    def check_exp!(payload, now, leeway)
+      exp = payload["exp"]
+      raise OpenID4VP::VerificationError, "verifier attestation: missing exp" unless exp.is_a?(Integer)
+      raise OpenID4VP::VerificationError, "verifier attestation: exp has passed" unless exp > now.to_i - leeway
+    end
+    private_class_method :check_exp!
+
+    def check_nbf!(payload, now, leeway)
+      nbf = payload["nbf"]
+      return if nbf.nil?
+      raise OpenID4VP::VerificationError, "verifier attestation: nbf is not an Integer" unless nbf.is_a?(Integer)
+
+      raise OpenID4VP::VerificationError, "verifier attestation: nbf is in the future" unless nbf <= now.to_i + leeway
+    end
+    private_class_method :check_nbf!
+
+    def check_sub!(payload)
+      sub = payload["sub"]
+      raise OpenID4VP::VerificationError, "verifier attestation: missing sub" unless sub.is_a?(String) && !sub.empty?
+
+      sub
+    end
+    private_class_method :check_sub!
+
+    def check_cnf!(payload)
+      jwk_hash = payload.is_a?(Hash) ? payload.dig("cnf", "jwk") : nil
+      raise OpenID4VP::VerificationError, "verifier attestation: missing cnf.jwk" unless jwk_hash.is_a?(Hash)
+
+      OpenID4VP::JOSE::JWK.new(jwk_hash)
+    rescue OpenID4VP::InvalidRequest => e
+      raise OpenID4VP::VerificationError, "verifier attestation: malformed cnf.jwk: #{e.message}"
+    end
+    private_class_method :check_cnf!
+  end
+end

data/lib/openid4vp/verifier_info.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module OpenID4VP
+  # OpenID4VP §5.1/§5.11: the verifier_info Authorization Request
+  # parameter, a non-empty array of attestations about the Verifier.
+  module VerifierInfo
+    module_function
+
+    # Parses each element of the verifier_info request parameter. Raises
+    # InvalidRequest unless `array` is a non-empty Array of valid entry
+    # objects.
+    def parse_all(array)
+      unless array.is_a?(::Array) && !array.empty?
+        raise OpenID4VP::InvalidRequest, "verifier_info must be a non-empty array"
+      end
+
+      array.map { |item| Entry.parse(item) }
+    end
+
+    # OpenID4VP §5.11: when present, every verifier_info credential_ids
+    # value MUST reference an id in the DCQL Credential Query. Raises
+    # InvalidRequest otherwise.
+    def validate_against_query!(entries, dcql_query)
+      ids = dcql_query.ids
+
+      entries.each do |entry|
+        next unless entry.credential_ids
+
+        entry.credential_ids.each do |credential_id|
+          next if ids.include?(credential_id)
+
+          raise OpenID4VP::InvalidRequest,
+                "verifier_info credential_ids references unknown credential id #{credential_id.inspect}"
+        end
+      end
+
+      entries
+    end
+
+    # A single verifier_info attestation object: `format`, `data` (a String
+    # or a Hash), and the optional `credential_ids` it is relevant to (nil
+    # meaning relevant to all requested Credentials).
+    class Entry
+      attr_reader :format, :data, :credential_ids
+
+      def initialize(format:, data:, credential_ids: nil)
+        @format = format
+        @data = data
+        @credential_ids = credential_ids
+        freeze
+      end
+
+      def to_h
+        h = { "format" => format, "data" => data }
+        h["credential_ids"] = credential_ids if credential_ids
+        h
+      end
+
+      def self.parse(hash)
+        raise OpenID4VP::InvalidRequest, "verifier_info entry must be an object" unless hash.is_a?(::Hash)
+
+        new(
+          format: validate_format(hash),
+          data: validate_data(hash),
+          credential_ids: validate_credential_ids(hash)
+        )
+      end
+
+      def self.validate_format(hash)
+        format = hash["format"]
+        return format if format.is_a?(::String) && !format.empty?
+
+        raise OpenID4VP::InvalidRequest, "verifier_info entry format must be a non-empty string"
+      end
+      private_class_method :validate_format
+
+      def self.validate_data(hash)
+        data = hash["data"]
+        return data if data.is_a?(::String) || data.is_a?(::Hash)
+
+        raise OpenID4VP::InvalidRequest, "verifier_info entry data must be a string or object"
+      end
+      private_class_method :validate_data
+
+      def self.validate_credential_ids(hash)
+        return nil unless hash.key?("credential_ids")
+
+        credential_ids = hash["credential_ids"]
+        unless credential_ids.is_a?(::Array) && !credential_ids.empty? &&
+               credential_ids.all?(::String)
+          raise OpenID4VP::InvalidRequest,
+                "verifier_info entry credential_ids must be a non-empty array of strings"
+        end
+
+        credential_ids
+      end
+      private_class_method :validate_credential_ids
+    end
+  end
+end

data/lib/openid4vp/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module OpenID4VP
+  VERSION = "0.1.0"
+end

data/lib/openid4vp/vp_token.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module OpenID4VP
+  # OpenID4VP §8.1: the vp_token Authorization Response parameter — a JSON
+  # object mapping DCQL Credential Query ids to a non-empty array of
+  # Presentations (each a String or an object). Instances are immutable.
+  class VpToken
+    class << self
+      # `json_or_hash` is either a JSON String or an already-parsed Hash.
+      # Raises OpenID4VP::InvalidResponse unless the result is a Hash with
+      # String keys and non-empty Array values whose items are all String
+      # or Hash.
+      def parse(json_or_hash)
+        hash = json_or_hash.is_a?(::String) ? parse_json(json_or_hash) : json_or_hash
+        validate!(hash)
+        new(hash)
+      end
+
+      private
+
+      def parse_json(str)
+        ::JSON.parse(str)
+      rescue ::JSON::ParserError
+        raise OpenID4VP::InvalidResponse, "vp_token is not valid JSON"
+      end
+
+      def validate!(hash)
+        raise OpenID4VP::InvalidResponse, "vp_token must be a JSON object" unless hash.is_a?(::Hash)
+
+        hash.each do |id, presentations|
+          raise OpenID4VP::InvalidResponse, "vp_token keys must be strings" unless id.is_a?(::String)
+
+          validate_presentations!(id, presentations)
+        end
+      end
+
+      def validate_presentations!(id, presentations)
+        unless presentations.is_a?(::Array) && !presentations.empty?
+          raise OpenID4VP::InvalidResponse, "vp_token[#{id}] must be a non-empty array"
+        end
+
+        return if presentations.all? { |p| p.is_a?(::String) || p.is_a?(::Hash) }
+
+        raise OpenID4VP::InvalidResponse, "vp_token[#{id}] items must be strings or objects"
+      end
+    end
+
+    def initialize(hash)
+      @hash = hash.each_with_object({}) { |(k, v), h| h[k] = v.dup.freeze }.freeze
+      freeze
+    end
+
+    def ids
+      @hash.keys
+    end
+
+    def [](id)
+      @hash[id]
+    end
+
+    def presentations_for(id)
+      @hash[id]
+    end
+
+    def each(&)
+      @hash.each(&)
+    end
+
+    # A shallow-mutable copy: the top-level Hash and each Presentation Array
+    # are duplicated, so callers cannot mutate this VpToken's state.
+    def to_h
+      @hash.transform_values(&:dup)
+    end
+
+    def to_json(*)
+      ::JSON.generate(@hash, *)
+    end
+  end
+end

data/lib/openid4vp/wallet/config.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "../metadata/wallet_metadata"
+require_relative "../request_verification/config"
+require_relative "../formats/registry"
+require_relative "../transaction_data/registry"
+require_relative "http_client"
+
+module OpenID4VP
+  class Wallet
+    # Normalizes and validates the keyword arguments of `Wallet.new` exactly
+    # once, at construction time, mirroring `Verifier::Config` (design doc
+    # §4.21). Immutable once built.
+    class Config
+      attr_reader :metadata, :http, :verification, :formats, :transaction_data_types, :scope_resolver, :clock,
+                  :holder_keys, :authority_hooks
+
+      def initialize(metadata:, http: OpenID4VP::Wallet::HttpClient.new, verification: {},
+                     formats: OpenID4VP::Formats::Registry.default,
+                     transaction_data_types: OpenID4VP::TransactionData::Registry.new, scope_resolver: nil,
+                     clock: -> { ::Time.now }, holder_keys: nil, authority_hooks: {})
+        @metadata = normalize_metadata(metadata)
+        @http = http
+        @verification = normalize_verification(verification)
+        @formats = formats
+        @transaction_data_types = transaction_data_types
+        @scope_resolver = scope_resolver
+        @clock = clock
+        @holder_keys = holder_keys
+        @authority_hooks = authority_hooks
+        freeze
+      end
+
+      def now
+        clock.call
+      end
+
+      private
+
+      def normalize_metadata(metadata)
+        metadata.is_a?(::Hash) ? OpenID4VP::Metadata::WalletMetadata.new(metadata) : metadata
+      end
+
+      def normalize_verification(verification)
+        verification.is_a?(::Hash) ? OpenID4VP::RequestVerification::Config.new(**verification) : verification
+      end
+    end
+  end
+end

data/lib/openid4vp/wallet/http_client.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "net/http"
+
+require_relative "../errors"
+
+module OpenID4VP
+  class Wallet
+    # Raised by `HttpClient` for URL scheme violations and connection/HTTP
+    # failures while fetching a request_uri or posting a response.
+    class HttpError < OpenID4VP::Error; end
+
+    # Default Net::HTTP-based `Wallet` HTTP adapter. `#get`/`#post` return a
+    # `Response` Struct; connection failures raise `HttpError`. Requires
+    # `https` URLs unless constructed with `allow_http: true` (tests only).
+    class HttpClient
+      Response = Struct.new(:status, :headers, :body, keyword_init: true)
+
+      def initialize(allow_http: false, open_timeout: 10, read_timeout: 10)
+        @allow_http = allow_http
+        @open_timeout = open_timeout
+        @read_timeout = read_timeout
+      end
+
+      def get(url, headers: {})
+        perform(:get, url, headers: headers)
+      end
+
+      def post(url, body:, headers: {})
+        perform(:post, url, headers: headers, body: body)
+      end
+
+      private
+
+      def perform(method, url, headers:, body: nil)
+        uri = parse_uri!(url)
+        request = build_request(method, uri, headers, body)
+        response = execute(uri, request)
+        Response.new(status: response.code.to_i, headers: header_hash(response), body: response.body.to_s)
+      rescue HttpError
+        raise
+      rescue StandardError => e
+        raise HttpError, "#{method.to_s.upcase} #{url} failed: #{e.message}"
+      end
+
+      def parse_uri!(url)
+        uri = ::URI.parse(url)
+        allowed = uri.scheme == "https" || (uri.scheme == "http" && @allow_http)
+        raise HttpError, "refusing to use non-https URL: #{url.inspect}" unless allowed
+
+        uri
+      end
+
+      def build_request(method, uri, headers, body)
+        request = method == :get ? ::Net::HTTP::Get.new(uri) : ::Net::HTTP::Post.new(uri)
+        headers.each { |name, value| request[name.to_s] = value.to_s }
+        request.body = body if body
+        request
+      end
+
+      def execute(uri, request)
+        ::Net::HTTP.start(
+          uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: @open_timeout,
+                              read_timeout: @read_timeout
+        ) { |http| http.request(request) }
+      end
+
+      def header_hash(response)
+        response.each_header.with_object({}) { |(name, value), acc| acc[name] = value }
+      end
+    end
+  end
+end

data/lib/openid4vp/wallet/presenter.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require_relative "../formats/context"
+require_relative "../response_mode"
+
+module OpenID4VP
+  class Wallet
+    # OpenID4VP §8.1: builds the vp_token Hash (`{credential_query_id =>
+    # [presentation, ...]}`) for a wallet-side `DCQL::Selection`
+    # (`DCQL::Evaluator#evaluate`), delegating each Presentation to its
+    # Credential Format handler (`Formats::Registry#for`).
+    class Presenter
+      def initialize(wallet)
+        @wallet = wallet
+      end
+
+      # `selection` is a `DCQL::Selection` (its `#matches` need not be
+      # `#satisfiable?` -- callers check that separately, e.g.
+      # `ResponseBuilder`). Returns a Hash suitable for `VpToken.parse`.
+      def present(processed, selection)
+        assignment = assign_transaction_data(processed.transaction_data, selection)
+
+        selection.matches.each_with_object({}) do |(id, matches), vp_token|
+          vp_token[id] = matches.map { |match| build_one(processed, match, assignment[id]) }
+        end
+      end
+
+      private
+
+      def build_one(processed, match, transaction_data)
+        handler = @wallet.formats.for(match.credential_query.format)
+        context = build_context(processed, match, transaction_data)
+        handler.build_presentation(match.credential, match.claims, context)
+      end
+
+      def build_context(processed, match, transaction_data)
+        OpenID4VP::Formats::Context.new(
+          nonce: processed.request.nonce,
+          audience: processed.audience,
+          client_id: processed.client_id,
+          response_uri: return_uri_for(processed),
+          origin: processed.origin,
+          encryption_jwk: processed.encryption&.key,
+          transaction_data: transaction_data,
+          now: @wallet.now,
+          require_holder_binding: match.credential_query.require_cryptographic_holder_binding,
+          dc_api: processed.dc_api
+        )
+      end
+
+      # OpenID4VP Appendix B.2.6/B.3.6: `response_uri` (bound into a
+      # holder-bound Presentation's audience/transcript, e.g. mso_mdoc's
+      # OpenID4VPHandover) is meaningful for every non-DC-API Response Mode --
+      # direct_post[.jwt] via `response_uri`, fragment/query (redirect) via
+      # `redirect_uri` -- `AuthorizationRequest#return_uri` already resolves
+      # either. Only DC API Presentations bind against `client_id`/`origin`
+      # instead of a response_uri at all.
+      def return_uri_for(processed)
+        processed.dc_api ? nil : processed.return_uri
+      end
+
+      # OpenID4VP §5.1: each transaction_data entry is authorized by
+      # EXACTLY ONE credential -- the first id (in the entry's
+      # `credential_ids` order) that is actually part of `selection.matches`
+      # -- so it is passed only to that id's Formats::Context, never to any
+      # other credential_ids entry it also names. Returns
+      # `{credential_query_id => [entry, ...]}`, defaulting to `[]` for ids
+      # with no assigned entries. OpenID4VP §8.5: raises
+      # InvalidTransactionData when NONE of an entry's `credential_ids` is
+      # being presented ("the referenced Credential(s) are not available in
+      # the Wallet").
+      def assign_transaction_data(entries, selection)
+        assignment = selection.matches.each_key.to_h { |id| [id, []] }
+
+        (entries || []).each do |entry|
+          owner = entry.credential_ids.find { |id| assignment.key?(id) }
+          if owner.nil?
+            raise OpenID4VP::InvalidTransactionData,
+                  "transaction_data references credential(s) not being presented: #{entry.credential_ids.inspect}"
+          end
+
+          assignment[owner] << entry
+        end
+
+        assignment
+      end
+    end
+  end
+end

data/lib/openid4vp/wallet/processed_request.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module OpenID4VP
+  class Wallet
+    # The result of `Wallet#process_request`/`#process_dc_api_request`
+    # (design doc §4.21): the effective, verified AuthorizationRequest
+    # together with everything a caller needs to build a response
+    # (`Presenter`/`ResponseBuilder`/`#submit`, Task 29).
+    ProcessedRequest = Struct.new(
+      :request, :client_id, :verified, :verifier_metadata, :audience, :response_mode, :return_uri, :dc_api,
+      :origin, :vp_formats, :dcql_query, :transaction_data, :encryption, :wallet_nonce, keyword_init: true
+    )
+  end
+end