openid4vp 0.1.0

data/lib/openid4vp/verifier/response_validator.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require_relative "../vp_token"
+require_relative "../response_mode"
+require_relative "../util"
+require_relative "../formats/context"
+require_relative "../dcql/evaluator"
+require_relative "../dcql/meta"
+require_relative "../dcql/matcher"
+require_relative "../transaction_data/sd_jwt_hashes"
+require_relative "verified_response"
+
+module OpenID4VP
+  class Verifier
+    # OpenID4VP §8.6/§14.1 (also §13.3 steps 8-10): verifies a Wallet's
+    # Authorization Response against its Verifier::Session -- parsing the
+    # vp_token, verifying every Presentation with its Credential Format
+    # handler (`Formats::Registry#for`), and checking the surviving
+    # Presentations satisfy the session's effective DCQL query
+    # (`DCQL::Evaluator.check_response!`). A Presentation that fails its own
+    # verification is DISCARDED rather than failing the whole response (a
+    # Credential id left with no surviving Presentation is then reported as
+    # missing by the DCQL check); an unexpected credential id, a malformed
+    # vp_token, or a mismatched `state` fails the whole response.
+    class ResponseValidator
+      def initialize(verifier)
+        @verifier = verifier
+      end
+
+      # `payload` is a decoded Authorization Response payload Hash (as
+      # produced by `AuthorizationResponse#to_payload`, i.e.
+      # `session.response_params`): a "vp_token" member (String or Hash) and,
+      # for non-DC-API response modes, an optional "state". Returns a
+      # `VerifiedResponse`. Raises `InvalidResponse` (or a subclass) on
+      # failure; never mutates `session`.
+      def validate(session, payload)
+        vp_token = OpenID4VP::VpToken.parse(payload["vp_token"])
+        verify_state!(session, payload)
+        query = session.request.effective_dcql_query
+        check_known_ids!(query, vp_token)
+
+        surviving, discarded = verify_all(session, query, vp_token)
+        check_query_satisfied!(query, surviving, discarded)
+        check_multi_credential_transaction_data!(session, surviving)
+
+        build_response(session, surviving)
+      end
+
+      # Validates `session`'s current response (`session.response_params`)
+      # and records the outcome on it: on success, `session.result` (a
+      # JSON-safe Hash) and status `:verified`; on failure, `session.error`
+      # and status `:failed` -- then re-raises. Used by both
+      # `ResponseEndpoint#verify_on_receipt!` and `Verifier#fetch_response`.
+      def verify(session)
+        verified = validate(session, session.response_params)
+        session.result = verified.to_h
+        session.transition!(:verified)
+        @verifier.session_store.update(session)
+        verified
+      rescue OpenID4VP::InvalidResponse => e
+        session.error = { "code" => e.code, "description" => e.description }
+        session.transition!(:failed)
+        @verifier.session_store.update(session)
+        raise
+      end
+
+      private
+
+      # OpenID4VP §14.3.2: for non-DC-API response modes, a `state` present
+      # in the response payload must match the session it was decoded for
+      # (an encrypted response's `state` is not itself used to locate the
+      # session, so it can only be checked here).
+      def verify_state!(session, payload)
+        return if OpenID4VP::ResponseMode.dc_api?(session.response_mode)
+
+        state = payload["state"]
+        return if state.nil? || state == session.state
+
+        raise OpenID4VP::InvalidResponse, "response state does not match session"
+      end
+
+      def check_known_ids!(query, vp_token)
+        vp_token.ids.each do |id|
+          next if query.ids.include?(id)
+
+          raise OpenID4VP::InvalidResponse, "unexpected credential id #{id.inspect}"
+        end
+      end
+
+      def verify_all(session, query, vp_token)
+        surviving = {}
+        discarded = []
+        vp_token.each do |id, presentations|
+          credential_query = query.credential(id)
+          verified_list = verify_presentations(session, credential_query, presentations, discarded)
+          surviving[id] = verified_list unless verified_list.empty?
+        end
+        [surviving, discarded]
+      end
+
+      def verify_presentations(session, credential_query, presentations, discarded)
+        context = build_context(session, credential_query)
+        presentations.filter_map do |presentation|
+          verify_one(credential_query, presentation, context)
+        rescue OpenID4VP::PresentationInvalid, OpenID4VP::HolderBindingInvalid, OpenID4VP::VerificationError => e
+          discarded << e
+          nil
+        end
+      end
+
+      def verify_one(credential_query, presentation, context)
+        handler = @verifier.formats.for(credential_query.format)
+        verified = handler.verify_presentation(presentation, context)
+        handler.check_vp_formats!(verified, context.vp_formats)
+        check_holder_binding!(credential_query, verified)
+        check_meta!(credential_query, verified)
+        check_trusted_authorities!(credential_query, verified)
+        verified
+      end
+
+      def check_holder_binding!(credential_query, verified)
+        return unless credential_query.require_cryptographic_holder_binding
+        return if verified.holder_bound
+
+        raise OpenID4VP::HolderBindingInvalid,
+              "credential id #{credential_query.id.inspect}: holder binding required but presentation is not bound"
+      end
+
+      def check_meta!(credential_query, verified)
+        credential = verified.to_credential
+        return if OpenID4VP::DCQL::Meta.matches?(credential_query.format, credential_query.meta, credential)
+
+        raise OpenID4VP::PresentationInvalid, "credential does not match meta"
+      end
+
+      # OpenID4VP §6.1.1: `config.trust[:authority_hooks]` is a Hash of
+      # `{trusted_authorities "type" String => callable(ta_query, credential)
+      # -> boolean}` for types `DCQL::Matcher.authority_matches?` does not
+      # already know how to check itself (only `"aki"` is built in).
+      def check_trusted_authorities!(credential_query, verified)
+        return unless credential_query.trusted_authorities
+
+        credential = verified.to_credential
+        hooks = @verifier.config.trust[:authority_hooks] || {}
+        matched = credential_query.trusted_authorities.any? do |ta|
+          OpenID4VP::DCQL::Matcher.authority_matches?(ta, credential, hooks: hooks)
+        end
+        return if matched
+
+        raise OpenID4VP::PresentationInvalid, "credential does not match any trusted_authorities"
+      end
+
+      # Appends the first discarded Presentation's error message to a raised
+      # QueryNotSatisfied so callers see the root cause, rather than just
+      # "credential id is missing".
+      def check_query_satisfied!(query, surviving, discarded)
+        OpenID4VP::DCQL::Evaluator.check_response!(query, surviving)
+      rescue OpenID4VP::QueryNotSatisfied => e
+        raise e if discarded.empty?
+
+        raise OpenID4VP::QueryNotSatisfied,
+              "#{e.message} (a presentation was discarded: #{discarded.first.message})"
+      end
+
+      def build_response(session, surviving)
+        claims = surviving.transform_values { |list| list.map(&:claims) }
+        OpenID4VP::Verifier::VerifiedResponse.new(
+          presentations: surviving, claims: claims, session_id: session.id, nonce: session.nonce
+        )
+      end
+
+      def build_context(session, credential_query)
+        OpenID4VP::Formats::Context.new(
+          nonce: session.nonce,
+          audience: session.request.audience(origin: session.origin),
+          client_id: session.request.client_id,
+          response_uri: OpenID4VP::ResponseMode.dc_api?(session.response_mode) ? nil : session.request.return_uri,
+          origin: session.origin,
+          encryption_jwk: encryption_jwk(session),
+          transaction_data: transaction_data_for(session, credential_query.id),
+          now: @verifier.now,
+          leeway: @verifier.config.leeway,
+          trust: @verifier.config.trust,
+          vp_formats: @verifier.config.vp_formats_supported,
+          require_holder_binding: credential_query.require_cryptographic_holder_binding,
+          dc_api: OpenID4VP::ResponseMode.dc_api?(session.response_mode)
+        )
+      end
+
+      # The PUBLIC form of the JWK that actually decrypted this response:
+      # the session's own ephemeral key when one was generated for it,
+      # otherwise the configured static key whose `kid` matches the JWE
+      # header's (nil when the response was not encrypted).
+      def encryption_jwk(session)
+        return nil unless session.response_encryption
+
+        return session.encryption_jwk.to_public if session.encryption_jwk
+
+        kid = session.response_encryption["kid"]
+        static_keys = @verifier.config.encryption && @verifier.config.encryption[:keys]
+        static_keys&.find { |jwk| jwk.kid == kid }&.to_public
+      end
+
+      # OpenID4VP §5.1: "the Wallet MUST use only one of the referenced
+      # Credentials" to satisfy an entry naming more than one credential id,
+      # so which of them actually carries it is not known in advance. Only
+      # single-id entries are enforced here, per presentation, at
+      # verification time (via `Formats::Context#transaction_data`); entries
+      # naming several ids are excluded and checked afterwards, across the
+      # surviving presentations of all their ids, by
+      # `check_multi_credential_transaction_data!`.
+      def transaction_data_for(session, credential_id)
+        entries = session.request.transaction_data
+        return nil if entries.nil?
+
+        entries.select { |entry| entry.credential_ids == [credential_id] }
+      end
+
+      # OpenID4VP §5.1/§8.5: for every transaction_data entry naming more
+      # than one credential id, at least one surviving presentation among
+      # those ids must carry the entry's hash in its Key Binding JWT's
+      # `transaction_data_hashes` (dc+sd-jwt only -- mso_mdoc's transaction
+      # data binding is format-specific and not checked here). Raises
+      # PresentationInvalid otherwise.
+      def check_multi_credential_transaction_data!(session, surviving)
+        entries = session.request.transaction_data
+        return if entries.nil?
+
+        entries.select { |entry| entry.credential_ids.size > 1 }.each do |entry|
+          next if multi_credential_entry_satisfied?(entry, surviving)
+
+          raise OpenID4VP::PresentationInvalid,
+                "transaction_data entry is not authorized by any presented credential: " \
+                "#{entry.credential_ids.inspect}"
+        end
+      end
+
+      def multi_credential_entry_satisfied?(entry, surviving)
+        entry.credential_ids.any? do |id|
+          (surviving[id] || []).any? { |verified| transaction_data_hash_present?(verified, entry) }
+        end
+      end
+
+      def transaction_data_hash_present?(verified, entry)
+        kb_payload = verified.details && verified.details[:kb_payload]
+        hashes = kb_payload && kb_payload["transaction_data_hashes"]
+        return false unless hashes.is_a?(::Array)
+
+        alg = kb_payload["transaction_data_hashes_alg"] || "sha-256"
+        expected = OpenID4VP::TransactionData::SdJwtHashes.compute([entry], alg: alg).first
+        hashes.any? { |actual| actual.is_a?(::String) && OpenID4VP::Util.secure_compare(expected, actual) }
+      rescue OpenID4VP::InvalidTransactionData
+        false
+      end
+    end
+  end
+end

data/lib/openid4vp/verifier/session.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative "../authorization_request"
+require_relative "../jose/jwk"
+require_relative "../errors"
+
+module OpenID4VP
+  class Verifier
+    # A Verifier-side transaction (design doc §4.20, spec §13.3). Plain
+    # mutable value object so a `SessionStore` can freely update it in
+    # place; `#to_h`/`.from_h` round-trip it through a JSON-safe Hash for
+    # stores that serialize (e.g. a database or cache), storing `request`
+    # as `request.to_h` and `encryption_jwk` as its Hash form.
+    class Session
+      # created -> request_retrieved -> response_received -> (verified |
+      # failed), plus the created -> response_received shortcut used by
+      # response modes where the Wallet returns the response by value
+      # (fragment/query/DC API) without ever fetching a request_uri.
+      TRANSITIONS = {
+        created: %i[request_retrieved response_received],
+        request_retrieved: %i[response_received],
+        response_received: %i[verified failed]
+      }.freeze
+
+      attr_accessor :id, :request_id, :nonce, :state, :response_mode, :request, :request_object, :wallet_nonce,
+                    :wallet_metadata, :status, :response_params, :response_code, :encryption_jwk, :error, :result,
+                    :origin, :created_at, :expires_at, :response_encryption
+
+      def initialize(id:, request_id:, nonce:, response_mode:, request:, created_at:, expires_at:, state: nil,
+                     request_object: nil, wallet_nonce: nil, wallet_metadata: nil, status: :created,
+                     response_params: nil, response_code: nil, encryption_jwk: nil, error: nil, result: nil,
+                     origin: nil, response_encryption: nil)
+        @id = id
+        @request_id = request_id
+        @nonce = nonce
+        @state = state
+        @response_mode = response_mode
+        @request = request
+        @request_object = request_object
+        @wallet_nonce = wallet_nonce
+        @wallet_metadata = wallet_metadata
+        @status = status
+        @response_params = response_params
+        @response_code = response_code
+        @encryption_jwk = encryption_jwk
+        @error = error
+        @result = result
+        @origin = origin
+        @created_at = created_at
+        @expires_at = expires_at
+        @response_encryption = response_encryption
+      end
+
+      def expired?(now)
+        !expires_at.nil? && now >= expires_at
+      end
+
+      # Moves to `to`, raising ConfigurationError when that transition is
+      # not allowed from the current `status`.
+      def transition!(to)
+        allowed = TRANSITIONS[status] || []
+        unless allowed.include?(to)
+          raise OpenID4VP::ConfigurationError, "cannot transition session from #{status.inspect} to #{to.inspect}"
+        end
+
+        self.status = to
+      end
+
+      # WARNING: includes `encryption_jwk` in its PRIVATE form (with `d`) --
+      # a session's ephemeral response-decryption key -- so any
+      # `SessionStore` that persists this Hash (a database, a cache, ...) is
+      # persisting private key material and must protect it accordingly
+      # (encryption at rest, access control, etc).
+      def to_h
+        {
+          "id" => id, "request_id" => request_id, "nonce" => nonce, "state" => state,
+          "response_mode" => response_mode, "request" => request&.to_h, "request_object" => request_object,
+          "wallet_nonce" => wallet_nonce, "wallet_metadata" => wallet_metadata, "status" => status.to_s,
+          "response_params" => response_params, "response_code" => response_code,
+          "encryption_jwk" => encryption_jwk&.to_h, "error" => error, "result" => result, "origin" => origin,
+          "created_at" => created_at&.to_f, "expires_at" => expires_at&.to_f,
+          "response_encryption" => response_encryption
+        }
+      end
+
+      def self.from_h(hash)
+        h = hash.transform_keys(&:to_s)
+        new(**from_h_kwargs(h))
+      end
+
+      def self.from_h_kwargs(raw)
+        {
+          id: raw["id"], request_id: raw["request_id"], nonce: raw["nonce"], state: raw["state"],
+          response_mode: raw["response_mode"],
+          request: raw["request"] && OpenID4VP::AuthorizationRequest.new(raw["request"]),
+          request_object: raw["request_object"], wallet_nonce: raw["wallet_nonce"],
+          wallet_metadata: raw["wallet_metadata"], status: (raw["status"] || "created").to_sym,
+          response_params: raw["response_params"], response_code: raw["response_code"],
+          encryption_jwk: raw["encryption_jwk"] && OpenID4VP::JOSE::JWK.new(raw["encryption_jwk"]),
+          error: raw["error"], result: raw["result"], origin: raw["origin"],
+          created_at: raw["created_at"] && Time.at(raw["created_at"]),
+          expires_at: raw["expires_at"] && Time.at(raw["expires_at"]),
+          response_encryption: raw["response_encryption"]
+        }
+      end
+      private_class_method :from_h_kwargs
+    end
+  end
+end

data/lib/openid4vp/verifier/session_store.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module OpenID4VP
+  class Verifier
+    # Abstract Verifier session store interface (design doc §4.20). A
+    # concrete implementation persists `Verifier::Session` instances (or
+    # anything responding to the same shape) keyed by their `id`, with
+    # secondary lookups by `request_id` and `response_code`.
+    #
+    # WARNING: a Session's `encryption_jwk` (see `Session#to_h`) is a
+    # PRIVATE key -- the session's ephemeral response-decryption key -- so
+    # any implementation that persists Sessions outside this process (a
+    # database, a cache, ...) is persisting private key material and must
+    # protect it accordingly.
+    #
+    # See `OpenID4VP::Verifier::MemorySessionStore` for the in-process
+    # reference implementation.
+    class SessionStore
+      def create(_session)
+        raise NotImplementedError
+      end
+
+      def find(_id)
+        raise NotImplementedError
+      end
+
+      def find_by_request_id(_request_id)
+        raise NotImplementedError
+      end
+
+      def find_by_response_code(_response_code)
+        raise NotImplementedError
+      end
+
+      def update(_session)
+        raise NotImplementedError
+      end
+
+      def delete(_id)
+        raise NotImplementedError
+      end
+
+      def cleanup(_now)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/openid4vp/verifier/verified_response.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "../formats/verified_presentation"
+
+module OpenID4VP
+  class Verifier
+    # The result of `ResponseValidator#validate` / `Verifier#fetch_response`
+    # (OpenID4VP §8.6, §14.1): the verified Presentations -- and, redundantly,
+    # just their claims -- for each Credential Query id the response
+    # satisfied. `#to_h`/`.from_h` round-trip it through a JSON-safe Hash
+    # (e.g. `Session#result`); a Presentation restored via `.from_h` carries
+    # `raw: nil` (the original wire-format Presentation is not preserved).
+    VerifiedResponse = Struct.new(:presentations, :claims, :session_id, :nonce, keyword_init: true) do
+      def to_h
+        {
+          "session_id" => session_id,
+          "nonce" => nonce,
+          "presentations" => presentations.transform_values { |list| list.map { |vp| presentation_to_h(vp) } }
+        }
+      end
+
+      def self.from_h(hash)
+        h = hash.transform_keys(&:to_s)
+        presentations = (h["presentations"] || {}).transform_values do |list|
+          list.map { |presentation_hash| presentation_from_h(presentation_hash) }
+        end
+
+        new(
+          presentations: presentations, claims: presentations.transform_values { |list| list.map(&:claims) },
+          session_id: h["session_id"], nonce: h["nonce"]
+        )
+      end
+
+      def self.presentation_from_h(hash)
+        OpenID4VP::Formats::VerifiedPresentation.new(
+          format: hash["format"], claims: hash["claims"], holder_bound: hash["holder_bound"],
+          issuer: hash["issuer"], raw: nil, metadata: hash["metadata"] || {}
+        )
+      end
+      private_class_method :presentation_from_h
+
+      private
+
+      def presentation_to_h(verified_presentation)
+        {
+          "format" => verified_presentation.format, "claims" => verified_presentation.claims,
+          "holder_bound" => verified_presentation.holder_bound, "issuer" => verified_presentation.issuer,
+          "metadata" => verified_presentation.metadata
+        }
+      end
+    end
+  end
+end

data/lib/openid4vp/verifier.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "verifier/config"
+require_relative "verifier/session"
+require_relative "verifier/session_store"
+require_relative "verifier/memory_session_store"
+require_relative "verifier/request_signer"
+require_relative "verifier/request_builder"
+require_relative "verifier/created_request"
+require_relative "verifier/http_result"
+require_relative "verifier/request_uri_endpoint"
+require_relative "verifier/response_endpoint"
+require_relative "verifier/response_validator"
+require_relative "verifier/verified_response"
+require_relative "util"
+
+module OpenID4VP
+  # OpenID4VP Verifier orchestration (design doc §4.20, spec §13.3): builds
+  # and signs Authorization Requests, receives and validates the Wallet's
+  # Authorization Response, and manages the Verifier-side session for a
+  # transaction.
+  class Verifier
+    # `session.error["code"]` -> the Error subclass `fetch_response` raises
+    # for a `:failed` session, when one is registered here; unregistered
+    # codes (including `nil`, from a ResponseValidator failure) raise
+    # `InvalidResponse`.
+    FAILURE_CLASSES = {
+      "access_denied" => OpenID4VP::AccessDenied,
+      "invalid_request" => OpenID4VP::InvalidRequest
+    }.freeze
+
+    def initialize(**)
+      @config = Config.new(**)
+      @request_signer = RequestSigner.new(@config)
+      @request_builder = RequestBuilder.new(self)
+    end
+
+    attr_reader :config, :request_signer
+
+    def session_store
+      config.session_store
+    end
+
+    def formats
+      config.formats
+    end
+
+    def clock
+      config.clock
+    end
+
+    def now
+      config.now
+    end
+
+    def client_id
+      config.client_id
+    end
+
+    # OpenID4VP §5, §13.3 steps 2-4: builds an Authorization Request (or DC
+    # API request), creates its session and returns a CreatedRequest.
+    def create_request(**)
+      @request_builder.build(**)
+    end
+
+    # Internal accessor used by `handle_request_uri`, `handle_response`,
+    # `fetch_response` and `result` to look up a session directly.
+    def session(session_id)
+      session_store.find(session_id)
+    end
+
+    def status(session_id)
+      found = session(session_id)
+      raise OpenID4VP::SessionNotFound, "unknown session #{session_id.inspect}" if found.nil?
+
+      found.status
+    end
+
+    # OpenID4VP §5.10-5.10.2: the Request URI endpoint (memoized instance).
+    def request_uri_endpoint
+      @request_uri_endpoint ||= RequestUriEndpoint.new(self)
+    end
+
+    # OpenID4VP §8.2/§8.3.1: the Response endpoint (memoized instance).
+    def response_endpoint
+      @response_endpoint ||= ResponseEndpoint.new(self)
+    end
+
+    # OpenID4VP §8.6/§14.1: the Response validator (memoized instance).
+    def response_validator
+      @response_validator ||= ResponseValidator.new(self)
+    end
+
+    # Serves a Request URI GET/POST for `request_id` (OpenID4VP §5.10-5.10.2).
+    def handle_request_uri(request_id, method:, params: {}, headers: {})
+      request_uri_endpoint.call(request_id, method: method, params: params, headers: headers)
+    end
+
+    # Receives an Authorization Response/Error Response (OpenID4VP §8.2,
+    # §8.3.1). `session_id` is required for DC API sessions, which carry no
+    # request/state parameter of their own to locate the session by.
+    def handle_response(params, headers: {}, session_id: nil)
+      response_endpoint.call(params, headers: headers, session_id: session_id)
+    end
+
+    # OpenID4VP §8.6/§14.1: fetches (validating on first call) the
+    # `VerifiedResponse` for `session_id`. `response_code` is REQUIRED and
+    # checked (constant-time) whenever the session has one (OpenID4VP §8.5:
+    # the redirect_uri-carried `response_code` used by the RP's frontend to
+    # retrieve the response from its backend). Returns nil while the
+    # response is still pending; raises the session's stored error (mapped
+    # through `FAILURE_CLASSES`) once it has failed; validates (storing the
+    # result or the error) the first time it is called on a session that has
+    # merely received a response.
+    def fetch_response(session_id, response_code: nil)
+      found = session(session_id)
+      raise OpenID4VP::SessionNotFound, "unknown session #{session_id.inspect}" if found.nil?
+
+      check_response_code!(found, response_code)
+
+      case found.status
+      when :verified then OpenID4VP::Verifier::VerifiedResponse.from_h(found.result)
+      when :failed then raise_stored_error!(found)
+      when :response_received then response_validator.verify(found)
+      when :created, :request_retrieved then nil
+      end
+    end
+
+    # Like `fetch_response`, but never validates or raises: returns the
+    # cached `VerifiedResponse` for an already-`:verified` session, or nil
+    # otherwise (pending, failed, or unknown). For internal/trusted use,
+    # where a `response_code` has already been (or need not be) checked.
+    def result(session_id)
+      found = session(session_id)
+      return nil unless found && found.status == :verified
+
+      OpenID4VP::Verifier::VerifiedResponse.from_h(found.result)
+    end
+
+    private
+
+    def check_response_code!(session, response_code)
+      return unless session.response_code
+      return if response_code && OpenID4VP::Util.secure_compare(response_code, session.response_code)
+
+      raise OpenID4VP::InvalidResponse, "invalid response_code"
+    end
+
+    def raise_stored_error!(session)
+      error = session.error || {}
+      raise(FAILURE_CLASSES[error["code"]] || OpenID4VP::InvalidResponse, error["description"])
+    end
+  end
+end