openid4vp 0.1.0

data/lib/openid4vp/authorization_request.rb

@@ -0,0 +1,302 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "client_id"
+require_relative "response_mode"
+require_relative "response_type"
+require_relative "dcql/query"
+require_relative "metadata/verifier_metadata"
+require_relative "transaction_data"
+require_relative "verifier_info"
+require_relative "util"
+require_relative "util/uri"
+require_relative "authorization_request/validator"
+
+module OpenID4VP
+  # OpenID4VP §5-5.3: the Authorization Request parameters. Immutable value
+  # object over a Hash with String keys; typed accessors lazily parse the
+  # structured parameters, and #validate! performs the full set of §5
+  # request-level checks used by both Verifier (building) and Wallet
+  # (validating).
+  class AuthorizationRequest
+    # Parameters whose value is a JSON-serialized object/array when carried
+    # as an application/x-www-form-urlencoded value (OpenID4VP §5.1).
+    JSON_PARAMS = %w[
+      dcql_query client_metadata verifier_info expected_origins trust_chain transaction_data
+    ].freeze
+
+    KNOWN_KEYS = %w[
+      response_type response_mode client_id nonce state scope redirect_uri response_uri
+      dcql_query client_metadata request_uri request_uri_method request transaction_data
+      verifier_info expected_origins wallet_nonce trust_chain aud
+    ].freeze
+
+    include Validator
+
+    attr_reader :params
+
+    # `params` keys are normalized to Strings; values may already be decoded
+    # (Hash/Array/domain objects) or JSON-serialized Strings for the members
+    # listed in JSON_PARAMS (decoded lazily by the typed accessors).
+    def initialize(params)
+      raise OpenID4VP::InvalidRequest, "authorization request params must be an object" unless params.is_a?(::Hash)
+
+      @params = params.transform_keys(&:to_s).freeze
+      @memo = {}
+      freeze
+    end
+
+    # Decodes JSON-string values of the JSON_PARAMS members (transaction_data
+    # may arrive as a JSON-array string or already as an Array of base64url
+    # strings). Symbol keys are normalized to Strings.
+    def self.from_params(hash)
+      new(hash.each_with_object({}) { |(key, value), out| out[key.to_s] = decode_param(key.to_s, value) })
+    end
+
+    def self.from_url(url)
+      from_params(OpenID4VP::Util::URI.params_from(url))
+    end
+
+    def self.decode_param(key, value)
+      return value unless value.is_a?(::String) && JSON_PARAMS.include?(key)
+
+      begin
+        ::JSON.parse(value)
+      rescue ::JSON::ParserError
+        raise OpenID4VP::InvalidRequest, "#{key} is not valid JSON"
+      end
+    end
+    private_class_method :decode_param
+
+    def [](key)
+      @params[key.to_s]
+    end
+
+    # Unrecognized params, e.g. profile-specific extensions.
+    def extra
+      @params.except(*KNOWN_KEYS)
+    end
+
+    def response_type
+      self["response_type"]
+    end
+
+    def response_mode
+      self["response_mode"] || OpenID4VP::ResponseMode.default
+    end
+
+    def client_id
+      memoize(:client_id) do
+        raw = self["client_id"]
+        next nil if raw.nil?
+
+        raw.is_a?(OpenID4VP::ClientId) ? raw : OpenID4VP::ClientId.parse(raw)
+      end
+    end
+
+    def nonce
+      self["nonce"]
+    end
+
+    def state
+      self["state"]
+    end
+
+    def scope
+      self["scope"]
+    end
+
+    def redirect_uri
+      self["redirect_uri"]
+    end
+
+    def response_uri
+      self["response_uri"]
+    end
+
+    def request_uri
+      self["request_uri"]
+    end
+
+    def request_uri_method
+      self["request_uri_method"]
+    end
+
+    def request
+      self["request"]
+    end
+
+    def wallet_nonce
+      self["wallet_nonce"]
+    end
+
+    def aud
+      self["aud"]
+    end
+
+    def trust_chain
+      decoded("trust_chain")
+    end
+
+    def dcql_query
+      memoize(:dcql_query) do
+        raw = decoded("dcql_query")
+        next nil if raw.nil?
+
+        raw.is_a?(OpenID4VP::DCQL::Query) ? raw : OpenID4VP::DCQL::Query.from_h(raw)
+      end
+    end
+
+    def client_metadata
+      memoize(:client_metadata) do
+        raw = decoded("client_metadata")
+        next nil if raw.nil?
+
+        raw.is_a?(OpenID4VP::Metadata::VerifierMetadata) ? raw : OpenID4VP::Metadata::VerifierMetadata.new(raw)
+      end
+    end
+
+    def transaction_data
+      memoize(:transaction_data) do
+        raw = decoded("transaction_data")
+        next nil if raw.nil?
+
+        if raw.is_a?(::Array) && raw.all?(OpenID4VP::TransactionData::Entry)
+          raw
+        else
+          OpenID4VP::TransactionData.parse_all(raw)
+        end
+      end
+    end
+
+    def verifier_info
+      memoize(:verifier_info) do
+        raw = decoded("verifier_info")
+        next nil if raw.nil?
+
+        if raw.is_a?(::Array) && raw.all?(OpenID4VP::VerifierInfo::Entry)
+          raw
+        else
+          OpenID4VP::VerifierInfo.parse_all(raw)
+        end
+      end
+    end
+
+    def expected_origins
+      memoize(:expected_origins) do
+        raw = decoded("expected_origins")
+        next nil if raw.nil?
+
+        unless raw.is_a?(::Array) && !raw.empty? && raw.all?(::String)
+          raise OpenID4VP::InvalidRequest, "expected_origins must be a non-empty array of strings"
+        end
+
+        raw
+      end
+    end
+
+    # The dcql_query in effect: dcql_query itself, or (only meaningful after
+    # #validate! has resolved it) the scope-resolved query. Before #validate!,
+    # with only a scope present, this returns nil.
+    def effective_dcql_query
+      return @memo[:effective_dcql_query] if @memo.key?(:effective_dcql_query)
+
+      self["dcql_query"].nil? ? nil : dcql_query
+    end
+
+    # OpenID4VP §8.2: response_uri for direct_post response modes; otherwise
+    # redirect_uri, falling back to the `original` of a `redirect_uri:`
+    # prefixed client_id (§5.9) when redirect_uri is absent.
+    def return_uri
+      if OpenID4VP::ResponseMode.direct_post?(response_mode)
+        response_uri
+      else
+        redirect_uri || redirect_uri_from_client_id
+      end
+    end
+
+    # The audience to bind a signed request/response to: "origin:<origin>"
+    # for the DC API (origin required), otherwise the client_id.
+    def audience(origin: nil)
+      if OpenID4VP::ResponseMode.dc_api?(response_mode)
+        raise OpenID4VP::InvalidRequest, "origin required" if origin.nil?
+
+        OpenID4VP::ClientId.origin(origin).to_s
+      else
+        cid = client_id
+        raise OpenID4VP::InvalidRequest, "client_id is required" if cid.nil?
+
+        cid.to_s
+      end
+    end
+
+    # A new AuthorizationRequest with the given members overridden (string or
+    # symbol keys are both accepted).
+    def with(**overrides)
+      self.class.new(@params.merge(overrides.transform_keys(&:to_s)))
+    end
+
+    def to_h
+      @params.each_with_object({}) { |(key, _), out| out[key] = h_value(key) }
+    end
+
+    def to_form_params
+      @params.each_with_object({}) { |(key, _), out| out[key] = form_value(key) }
+    end
+
+    def to_url(authorization_endpoint)
+      OpenID4VP::Util::URI.with_query(authorization_endpoint, to_form_params)
+    end
+
+    private
+
+    def memoize(key)
+      return @memo[key] if @memo.key?(key)
+
+      @memo[key] = yield
+    end
+
+    def decoded(key)
+      self.class.send(:decode_param, key, self[key])
+    end
+
+    def redirect_uri_from_client_id
+      cid = client_id
+      return nil unless cid && cid.prefix == "redirect_uri"
+
+      cid.original
+    end
+
+    def h_value(key)
+      case key
+      when "dcql_query"
+        raw = decoded(key)
+        raw.is_a?(OpenID4VP::DCQL::Query) ? raw.to_h : raw
+      when "client_metadata"
+        raw = decoded(key)
+        raw.is_a?(OpenID4VP::Metadata::VerifierMetadata) ? raw.to_h : raw
+      when "transaction_data"
+        normalize_array(decoded(key)) { |item| item.is_a?(OpenID4VP::TransactionData::Entry) ? item.raw : item }
+      when "verifier_info"
+        normalize_array(decoded(key)) { |item| item.is_a?(OpenID4VP::VerifierInfo::Entry) ? item.to_h : item }
+      when *JSON_PARAMS
+        decoded(key)
+      else
+        self[key]
+      end
+    end
+
+    def form_value(key)
+      value = h_value(key)
+      return value if value.nil? || value.is_a?(::String)
+
+      JSON_PARAMS.include?(key) ? ::JSON.generate(value) : value.to_s
+    end
+
+    def normalize_array(value, &)
+      return value unless value.is_a?(::Array)
+
+      value.map(&)
+    end
+  end
+end

data/lib/openid4vp/authorization_response.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require_relative "vp_token"
+require_relative "response_mode"
+require_relative "errors"
+require_relative "util/uri"
+require_relative "util/form"
+require_relative "jose/jwe"
+require_relative "encoded_response"
+
+module OpenID4VP
+  # OpenID4VP §8: the Authorization Response carrying the VP Token, encoded
+  # for and decoded from any Response Mode (fragment, query,
+  # direct_post[.jwt], dc_api[.jwt]).
+  class AuthorizationResponse
+    Encoded = EncodedResponse
+    Decoded = Struct.new(:response, :encrypted, :encryption_header, :encryption_key, keyword_init: true)
+
+    EXTRA_EXCLUDED_KEYS = %w[vp_token state error error_description].freeze
+
+    attr_reader :vp_token, :state, :extra
+
+    def initialize(vp_token:, state: nil, extra: {})
+      @vp_token = vp_token.is_a?(VpToken) ? vp_token : VpToken.parse(vp_token)
+      @state = state
+      @extra = extra.each_with_object({}) { |(k, v), h| h[k.to_s] = v }.freeze
+      freeze
+    end
+
+    def to_params
+      { "vp_token" => @vp_token.to_json }.merge(state_param).merge(@extra)
+    end
+
+    def to_payload
+      { "vp_token" => @vp_token.to_h }.merge(state_param).merge(@extra)
+    end
+
+    # Encodes this response for `response_mode`. `redirect_uri` is required
+    # for the `fragment`/`query` Response Modes; `encryption` (a
+    # ResponseEncryption) is required for the `.jwt` Response Modes. Raises
+    # OpenID4VP::ConfigurationError when a required argument is missing.
+    def encode(response_mode, redirect_uri: nil, encryption: nil)
+      validate_response_mode!(response_mode)
+      return encode_redirect(response_mode, redirect_uri) if ResponseMode.redirect?(response_mode)
+      return encode_encrypted(response_mode, encryption) if ResponseMode.encrypted?(response_mode)
+
+      encode_plain(response_mode)
+    end
+
+    class << self
+      # Reverses #encode. `params` is a String-keyed Hash: form params for
+      # direct_post[.jwt], fragment/query params, or the dc_api[.jwt] data
+      # object. Raises OpenID4VP::InvalidResponse on any shape problem.
+      def decode(response_mode, params, decryption_keys: [])
+        effective_params, encrypted, header, key = resolve_params(response_mode, params, decryption_keys)
+        Decoded.new(
+          response: build_response(effective_params),
+          encrypted: encrypted, encryption_header: header, encryption_key: key
+        )
+      end
+
+      private
+
+      def resolve_params(response_mode, params, decryption_keys)
+        return [params, false, nil, nil] unless ResponseMode.encrypted?(response_mode)
+
+        if params["response"]
+          decrypted = decrypt_response(params["response"], decryption_keys)
+          [decrypted.payload, true, decrypted.header, decrypted.key]
+        elsif params["error"]
+          [params, false, nil, nil]
+        else
+          raise OpenID4VP::InvalidResponse, "missing response parameter"
+        end
+      end
+
+      def decrypt_response(compact, decryption_keys)
+        decrypted = OpenID4VP::JOSE::JWE.decrypt(compact, keys: decryption_keys)
+        unless decrypted.payload.is_a?(::Hash)
+          raise OpenID4VP::InvalidResponse, "encrypted response payload is not a JSON object"
+        end
+
+        decrypted
+      rescue OpenID4VP::VerificationError => e
+        raise OpenID4VP::InvalidResponse, "response decryption failed: #{e.message}"
+      end
+
+      def build_response(params)
+        if params["error"]
+          return OpenID4VP::ErrorResponse.new(
+            error: params["error"], error_description: params["error_description"], state: params["state"]
+          )
+        end
+
+        vp_token = params["vp_token"]
+        raise OpenID4VP::InvalidResponse, "missing vp_token" unless vp_token.is_a?(::String) || vp_token.is_a?(::Hash)
+
+        extra = params.except(*EXTRA_EXCLUDED_KEYS)
+        new(vp_token: VpToken.parse(vp_token), state: params["state"], extra: extra)
+      end
+    end
+
+    private
+
+    def state_param
+      @state.nil? ? {} : { "state" => @state }
+    end
+
+    def validate_response_mode!(response_mode)
+      return if ResponseMode::ALL.include?(response_mode)
+
+      raise OpenID4VP::ConfigurationError, "unsupported response_mode #{response_mode.inspect}"
+    end
+
+    def encode_redirect(response_mode, redirect_uri)
+      if redirect_uri.nil?
+        raise OpenID4VP::ConfigurationError, "redirect_uri is required for response_mode #{response_mode}"
+      end
+
+      url =
+        if response_mode == ResponseMode::FRAGMENT
+          Util::URI.with_fragment(redirect_uri, to_params)
+        else
+          Util::URI.with_query(redirect_uri, to_params)
+        end
+      Encoded.new(mode: response_mode, url: url)
+    end
+
+    def encode_encrypted(response_mode, encryption)
+      if encryption.nil?
+        raise OpenID4VP::ConfigurationError, "encryption is required for response_mode #{response_mode}"
+      end
+
+      jwe = encryption.encrypt(to_payload)
+      if ResponseMode.direct_post?(response_mode)
+        Encoded.new(mode: response_mode, form_params: { "response" => jwe },
+                    form_body: Util::Form.encode("response" => jwe), jwe: jwe)
+      else
+        Encoded.new(mode: response_mode, data: { "response" => jwe }, jwe: jwe)
+      end
+    end
+
+    def encode_plain(response_mode)
+      if ResponseMode.direct_post?(response_mode)
+        Encoded.new(mode: response_mode, form_params: to_params, form_body: Util::Form.encode(to_params))
+      else
+        Encoded.new(mode: response_mode, data: to_payload)
+      end
+    end
+  end
+end

data/lib/openid4vp/client_id.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module OpenID4VP
+  class ClientId
+    PREFIXES = %w[
+      redirect_uri openid_federation decentralized_identifier
+      verifier_attestation x509_san_dns x509_hash origin
+    ].freeze
+    PRE_REGISTERED = "pre-registered"
+
+    SIGNED_REQUEST_REQUIRED = %w[
+      openid_federation decentralized_identifier verifier_attestation
+      x509_san_dns x509_hash
+    ].freeze
+    SIGNED_REQUEST_NOT_ALLOWED = %w[redirect_uri].freeze
+
+    def self.parse(input)
+      raise InvalidRequest, "client_id must be a non-empty string" unless input.is_a?(String) && !input.empty?
+
+      colon_index = input.index(":")
+
+      if colon_index.nil?
+        # No colon: pre-registered id
+        new(prefix: PRE_REGISTERED, original: input, candidate_prefix: nil)
+      else
+        potential_prefix = input[0...colon_index]
+        remainder = input[(colon_index + 1)..]
+
+        if PREFIXES.include?(potential_prefix)
+          # Known prefix
+          new(prefix: potential_prefix, original: remainder, candidate_prefix: potential_prefix)
+        else
+          # Unknown prefix
+          new(prefix: PRE_REGISTERED, original: input, candidate_prefix: potential_prefix)
+        end
+      end
+    end
+
+    def self.origin(origin_str)
+      new(prefix: "origin", original: origin_str, candidate_prefix: "origin")
+    end
+
+    def initialize(prefix:, original:, candidate_prefix: nil)
+      @prefix = prefix.freeze
+      @original = original.freeze
+      @candidate_prefix = candidate_prefix.freeze
+      freeze
+    end
+
+    attr_reader :prefix, :original, :candidate_prefix
+
+    def to_s
+      if prefix == PRE_REGISTERED
+        original
+      else
+        "#{prefix}:#{original}"
+      end
+    end
+
+    def pre_registered?
+      prefix == PRE_REGISTERED
+    end
+
+    def unknown_prefix?
+      pre_registered? && !candidate_prefix.nil?
+    end
+
+    def signed_request_required?
+      SIGNED_REQUEST_REQUIRED.include?(prefix)
+    end
+
+    def signed_request_allowed?
+      !SIGNED_REQUEST_NOT_ALLOWED.include?(prefix)
+    end
+
+    def ==(other)
+      other.is_a?(ClientId) && to_s == other.to_s
+    end
+
+    def eql?(other)
+      self == other
+    end
+
+    def hash
+      to_s.hash
+    end
+  end
+end

data/lib/openid4vp/credential.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module OpenID4VP
+  # Framework-agnostic view of a Credential held by a Wallet (or decoded from
+  # a Verifier's Presentation), used by `OpenID4VP::DCQL::Evaluator` on both
+  # sides. Immutable.
+  class Credential
+    attr_reader :format, :claims, :raw, :holder_key, :x5chain, :metadata
+
+    # format: e.g. "dc+sd-jwt", "mso_mdoc", "jwt_vc_json", "ldp_vc".
+    # claims: JSON-like Hash used by DCQL::ClaimsPathPointer; for mso_mdoc,
+    #   {namespace => {element => value}}.
+    # raw: the issued/presented artifact (SD-JWT string, VC JWT, mdoc
+    #   IssuerSigned CBOR, ...), or nil.
+    # holder_key: the credential's holder binding key material, or nil.
+    # x5chain: Array of OpenSSL::X509::Certificate, leaf first.
+    # metadata: format-specific descriptors, e.g. {"vct"=>, "doctype"=>,
+    #   "type"=>[...], "issuer"=>}.
+    def initialize(format:, claims:, raw: nil, holder_key: nil, x5chain: [], metadata: {})
+      @format = format
+      @claims = deep_freeze(Marshal.load(Marshal.dump(claims)))
+      @raw = raw
+      @holder_key = holder_key
+      @x5chain = x5chain.dup.freeze
+      @metadata = metadata.dup.freeze
+    end
+
+    def holder_bindable?
+      !holder_key.nil?
+    end
+
+    private
+
+    # Deep-copies (via Marshal) and freezes `claims` so the Credential is
+    # actually immutable, without mutating/freezing the caller's own
+    # objects. Suitable for JSON-like data (Hash/Array/String/Integer/
+    # Float/true/false/nil) and mdoc byte strings.
+    def deep_freeze(obj)
+      case obj
+      when ::Hash
+        obj.each_pair do |key, value|
+          deep_freeze(key)
+          deep_freeze(value)
+        end
+      when ::Array
+        obj.each { |value| deep_freeze(value) }
+      end
+      obj.freeze
+    end
+  end
+end