openid4vp 0.1.0

data/lib/openid4vp/transaction_data.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "util/base64url"
+
+module OpenID4VP
+  # OpenID4VP §5.1/§8.4: the transaction_data Authorization Request
+  # parameter, a non-empty array of base64url-encoded JSON objects binding
+  # user authorization to specific transaction details.
+  module TransactionData
+    module_function
+
+    # Parses each element of the transaction_data request parameter.
+    # Raises InvalidTransactionData unless `array` is a non-empty Array of
+    # Strings that each decode to a valid entry.
+    def parse_all(array)
+      unless array.is_a?(::Array) && !array.empty?
+        raise OpenID4VP::InvalidTransactionData, "transaction_data must be a non-empty array"
+      end
+
+      array.map do |item|
+        raise OpenID4VP::InvalidTransactionData, "transaction_data entries must be strings" unless item.is_a?(::String)
+
+        Entry.parse(item)
+      end
+    end
+
+    # OpenID4VP §5.1: every transaction_data credential_ids value MUST
+    # reference an id in the DCQL Credential Query. Raises
+    # InvalidTransactionData otherwise.
+    def validate_against_query!(entries, dcql_query)
+      ids = dcql_query.ids
+
+      entries.each do |entry|
+        entry.credential_ids.each do |credential_id|
+          next if ids.include?(credential_id)
+
+          raise OpenID4VP::InvalidTransactionData,
+                "transaction_data credential_ids references unknown credential id #{credential_id.inspect}"
+        end
+      end
+
+      entries
+    end
+
+    # A single parsed/built transaction_data entry: the base64url string as
+    # received or produced (`raw`, over which hashes are computed
+    # verbatim), the decoded JSON object (`data`), and its `type` and
+    # `credential_ids` parameters (§5.1) plus the optional
+    # `transaction_data_hashes_alg` parameter (§B.3.3.1).
+    class Entry
+      attr_reader :raw, :data, :type, :credential_ids, :transaction_data_hashes_alg
+
+      def initialize(raw:, data:, type:, credential_ids:, transaction_data_hashes_alg: nil)
+        @raw = raw
+        @data = data
+        @type = type
+        @credential_ids = credential_ids
+        @transaction_data_hashes_alg = transaction_data_hashes_alg
+        freeze
+      end
+
+      # Decodes and validates a single base64url-encoded transaction_data
+      # string. Raises InvalidTransactionData on bad base64/JSON, a
+      # non-object payload, or missing/invalid `type`, `credential_ids`, or
+      # `transaction_data_hashes_alg`.
+      def self.parse(raw)
+        raise OpenID4VP::InvalidTransactionData, "transaction_data entry must be a string" unless raw.is_a?(::String)
+
+        data =
+          begin
+            OpenID4VP::Util::Base64url.decode_json(raw)
+          rescue OpenID4VP::InvalidRequest
+            raise OpenID4VP::InvalidTransactionData, "transaction_data entry is not valid base64url-encoded JSON"
+          end
+
+        unless data.is_a?(::Hash)
+          raise OpenID4VP::InvalidTransactionData, "transaction_data entry must decode to a JSON object"
+        end
+
+        type = validate_type(data)
+        credential_ids = validate_credential_ids(data)
+        alg = validate_hashes_alg(data)
+
+        new(raw: raw, data: data, type: type, credential_ids: credential_ids, transaction_data_hashes_alg: alg)
+      end
+
+      # Builds a new entry from its parameters, re-encoding `raw` from
+      # `data` (`{"type"=>type, "credential_ids"=>credential_ids}` merged
+      # with the stringified `fields`).
+      def self.build(type:, credential_ids:, **fields)
+        data = { "type" => type, "credential_ids" => credential_ids }.merge(fields.transform_keys(&:to_s))
+        raw = OpenID4VP::Util::Base64url.encode_json(data)
+
+        new(
+          raw: raw,
+          data: data,
+          type: type,
+          credential_ids: credential_ids,
+          transaction_data_hashes_alg: data["transaction_data_hashes_alg"]
+        )
+      end
+
+      def self.validate_type(data)
+        type = data["type"]
+        return type if type.is_a?(::String)
+
+        raise OpenID4VP::InvalidTransactionData, "transaction_data entry is missing a valid type"
+      end
+      private_class_method :validate_type
+
+      def self.validate_credential_ids(data)
+        credential_ids = data["credential_ids"]
+        unless credential_ids.is_a?(::Array) && !credential_ids.empty? &&
+               credential_ids.all?(::String)
+          raise OpenID4VP::InvalidTransactionData,
+                "transaction_data entry credential_ids must be a non-empty array of strings"
+        end
+
+        credential_ids
+      end
+      private_class_method :validate_credential_ids
+
+      def self.validate_hashes_alg(data)
+        return nil unless data.key?("transaction_data_hashes_alg")
+
+        alg = data["transaction_data_hashes_alg"]
+        unless alg.is_a?(::Array) && !alg.empty? && alg.all?(::String)
+          raise OpenID4VP::InvalidTransactionData,
+                "transaction_data entry transaction_data_hashes_alg must be a non-empty array of strings"
+        end
+
+        alg
+      end
+      private_class_method :validate_hashes_alg
+    end
+  end
+end

data/lib/openid4vp/util/base64url.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require_relative "../util"
+
+module OpenID4VP
+  module Util
+    # Unpadded base64url (RFC 4648 §5), as used throughout OpenID4VP/JOSE/COSE.
+    module Base64url
+      VALID_CHARS = /\A[A-Za-z0-9\-_]*\z/
+
+      module_function
+
+      def encode(bytes)
+        [bytes].pack("m0").tr("+/", "-_").delete("=")
+      end
+
+      def decode(str)
+        raise OpenID4VP::InvalidRequest, "invalid base64url" unless str.is_a?(String) && VALID_CHARS.match?(str)
+
+        padded = str.tr("-_", "+/")
+        padded += "=" * ((4 - (padded.length % 4)) % 4)
+        begin
+          padded.unpack1("m0")
+        rescue ArgumentError
+          raise OpenID4VP::InvalidRequest, "invalid base64url"
+        end
+      end
+
+      def encode_json(obj)
+        encode(::JSON.generate(obj))
+      end
+
+      def decode_json(str)
+        parsed = ::JSON.parse(decode(str))
+        raise OpenID4VP::InvalidRequest, "invalid json" unless parsed.is_a?(Hash) || parsed.is_a?(Array)
+
+        parsed
+      rescue ::JSON::ParserError
+        raise OpenID4VP::InvalidRequest, "invalid json"
+      end
+    end
+  end
+end

data/lib/openid4vp/util/form.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require_relative "../util"
+
+module OpenID4VP
+  module Util
+    # application/x-www-form-urlencoded encode/decode for request/response
+    # bodies. Hash and Array values are JSON-encoded before being form-encoded.
+    module Form
+      module_function
+
+      def encode(hash)
+        ::URI.encode_www_form(
+          hash.transform_values { |v| v.is_a?(Hash) || v.is_a?(Array) ? ::JSON.generate(v) : v.to_s }
+        )
+      end
+
+      def decode(body)
+        ::URI.decode_www_form(body).to_h
+      end
+    end
+  end
+end

data/lib/openid4vp/util/random.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require_relative "../util"
+
+module OpenID4VP
+  module Util
+    # Cryptographically secure random value generators, base64url-encoded.
+    module Random
+      module_function
+
+      def nonce(bytes = 32)
+        Base64url.encode(SecureRandom.random_bytes(bytes))
+      end
+
+      def state
+        nonce
+      end
+
+      def response_code
+        nonce
+      end
+
+      def id
+        nonce
+      end
+    end
+  end
+end

data/lib/openid4vp/util/uri.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require_relative "../util"
+
+module OpenID4VP
+  module Util
+    # URI helpers for building and parsing authorization request/response
+    # URLs, including custom-scheme (e.g. `openid4vp://`, `openid4vp:`) URLs
+    # that the stdlib ::URI parser does not always handle uniformly.
+    module URI
+      module_function
+
+      def with_query(base, params)
+        return base if params.nil? || params.empty?
+
+        separator = base.include?("?") ? "&" : "?"
+        "#{base}#{separator}#{::URI.encode_www_form(params)}"
+      end
+
+      def with_fragment(base, params)
+        return base if params.nil? || params.empty?
+
+        "#{base}##{::URI.encode_www_form(params)}"
+      end
+
+      def params_from(url)
+        query = parsed_query(url) || manual_query(url)
+        return {} if query.nil? || query.empty?
+
+        ::URI.decode_www_form(query).to_h
+      end
+
+      def parsed_query(url)
+        ::URI.parse(url).query
+      rescue ::URI::InvalidURIError
+        nil
+      end
+
+      def manual_query(url)
+        idx = url.index("?")
+        return nil unless idx
+
+        url[(idx + 1)..]
+      end
+    end
+  end
+end

data/lib/openid4vp/util.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module OpenID4VP
+  # Low-level helpers shared across the gem. See also the nested
+  # `OpenID4VP::Util::Base64url`, `Random`, `Form` and `URI` modules.
+  module Util
+    module_function
+
+    # Constant-time string comparison, safe for comparing secrets.
+    def secure_compare(lhs, rhs)
+      OpenSSL.secure_compare(lhs, rhs)
+    end
+
+    # OID4VP §5.2: nonce/state values are restricted to this charset.
+    def url_safe?(str)
+      str.is_a?(String) && str.match?(/\A[A-Za-z0-9\-._~]+\z/)
+    end
+
+    def sha256(bytes)
+      OpenSSL::Digest::SHA256.digest(bytes)
+    end
+  end
+end

data/lib/openid4vp/verifier/config.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require_relative "../client_id"
+require_relative "../x509"
+require_relative "../response_mode"
+require_relative "../jose/jws"
+require_relative "../jose/jwk"
+require_relative "../jose/algorithms"
+require_relative "../formats/registry"
+require_relative "../transaction_data/registry"
+require_relative "memory_session_store"
+
+module OpenID4VP
+  class Verifier
+    # Normalizes and validates the keyword arguments of `Verifier.new`
+    # exactly once, at construction time (design doc §4.20), so later
+    # per-request code (`RequestBuilder`, `RequestSigner`) can trust it
+    # without re-checking. Immutable once built.
+    class Config
+      DEFAULT_AUTHORIZATION_ENDPOINT = "openid4vp://"
+      DEFAULT_SESSION_TTL = 600
+      DEFAULT_LEEWAY = 60
+      DEFAULT_ENC_VALUES = %w[A128GCM].freeze
+      DEFAULT_ENCRYPTION_ALG = "ECDH-ES"
+      DEFAULT_ENCRYPTION_CRV = "P-256"
+
+      # trust: see `Formats::Context`'s doc comment for its per-format hook
+      # keys; also consulted directly (not via `Context#trust_hook`) by
+      # `Verifier::ResponseValidator` for `trust[:authority_hooks]` --
+      # OpenID4VP §6.1.1 trusted_authorities matching for authority types
+      # `DCQL::Matcher.authority_matches?` has no built-in check for.
+      attr_reader :client_id, :response_uri, :redirect_uri, :request_uri_base, :redirect_uri_base,
+                  :authorization_endpoint, :signing, :attestation_jwt, :encryption, :vp_formats_supported,
+                  :client_metadata, :session_store, :trust, :formats, :transaction_data_types, :scope_resolver,
+                  :session_ttl, :clock, :verify_on_receipt, :leeway
+
+      def initialize(client_id:, response_uri: nil, redirect_uri: nil, request_uri_base: nil,
+                     redirect_uri_base: nil, authorization_endpoint: DEFAULT_AUTHORIZATION_ENDPOINT, signing: nil,
+                     attestation_jwt: nil, encryption: nil, vp_formats_supported: nil, client_metadata: {},
+                     session_store: nil, trust: {},
+                     formats: OpenID4VP::Formats::Registry.default,
+                     transaction_data_types: OpenID4VP::TransactionData::Registry.new, scope_resolver: nil,
+                     session_ttl: DEFAULT_SESSION_TTL, clock: -> { Time.now }, verify_on_receipt: false,
+                     leeway: DEFAULT_LEEWAY)
+        @client_id = client_id.is_a?(OpenID4VP::ClientId) ? client_id : OpenID4VP::ClientId.parse(client_id)
+        @response_uri = response_uri
+        @redirect_uri = redirect_uri
+        @request_uri_base = request_uri_base
+        @redirect_uri_base = redirect_uri_base
+        @authorization_endpoint = authorization_endpoint
+        @signing = normalize_signing(signing)
+        @attestation_jwt = attestation_jwt
+        @encryption = normalize_encryption(encryption)
+        @vp_formats_supported = vp_formats_supported
+        @client_metadata = client_metadata || {}
+        @clock = clock
+        @session_store = session_store || OpenID4VP::Verifier::MemorySessionStore.new(clock: clock)
+        @trust = trust
+        @formats = formats
+        @transaction_data_types = transaction_data_types
+        @scope_resolver = scope_resolver
+        @session_ttl = session_ttl
+        @verify_on_receipt = verify_on_receipt
+        @leeway = leeway
+
+        validate_client_id_prefix!
+        freeze
+      end
+
+      def now
+        clock.call
+      end
+
+      def signing_key
+        signing && signing[:key]
+      end
+
+      # Encryption additions for a `create_request` call: the
+      # client_metadata members to add for a response sent under
+      # `response_mode`, and the per-session ephemeral private JWK to store
+      # on the session (nil for static keys, or when no encryption is
+      # configured / the mode is not encrypted).
+      def encryption_metadata(response_mode, request_id)
+        return [{}, nil] unless OpenID4VP::ResponseMode.encrypted?(response_mode) && encryption
+
+        if encryption[:mode] == :ephemeral
+          private_jwk = OpenID4VP::JOSE::JWK.generate(
+            :ec, crv: encryption[:crv], kid: request_id, use: "enc", alg: encryption[:alg]
+          )
+          [jwks_metadata([private_jwk.to_public]), private_jwk]
+        else
+          [jwks_metadata(encryption[:keys].map(&:to_public)), nil]
+        end
+      end
+
+      private
+
+      def jwks_metadata(public_keys)
+        metadata = { "jwks" => { "keys" => public_keys.map(&:to_h) } }
+        enc_values = encryption[:enc_values]
+        metadata["encrypted_response_enc_values_supported"] = enc_values unless enc_values == DEFAULT_ENC_VALUES
+        metadata
+      end
+
+      def normalize_signing(signing)
+        return nil if signing.nil?
+
+        { key: signing.fetch(:key), alg: signing[:alg], x5c: signing[:x5c] }
+      end
+
+      # A Hash with `:keys` is static encryption; any other Hash (including
+      # `{}`) is ephemeral -- `:ephemeral` is never actually read, so
+      # `encryption: { ephemeral: true }` (README quick start) is accepted
+      # purely as documentation sugar for the reader, not as a flag this
+      # method branches on.
+      def normalize_encryption(encryption)
+        return nil if encryption.nil?
+
+        encryption[:keys] ? normalize_static_encryption(encryption) : normalize_ephemeral_encryption(encryption)
+      end
+
+      def normalize_static_encryption(encryption)
+        keys = encryption[:keys]
+        keys.each do |jwk|
+          next if jwk.kid && jwk.use && jwk.alg
+
+          raise OpenID4VP::ConfigurationError, "encryption keys must each have a kid, use and alg"
+        end
+        { mode: :static, keys: keys, enc_values: encryption[:enc_values] || DEFAULT_ENC_VALUES }
+      end
+
+      def normalize_ephemeral_encryption(encryption)
+        {
+          mode: :ephemeral,
+          crv: encryption[:crv] || DEFAULT_ENCRYPTION_CRV,
+          alg: encryption[:alg] || DEFAULT_ENCRYPTION_ALG,
+          enc_values: encryption[:enc_values] || DEFAULT_ENC_VALUES
+        }
+      end
+
+      def validate_client_id_prefix!
+        case client_id.prefix
+        when "x509_san_dns" then validate_x509!(:san_dns)
+        when "x509_hash" then validate_x509!(:hash)
+        when "verifier_attestation" then validate_verifier_attestation!
+        when "decentralized_identifier" then validate_decentralized_identifier!
+        when "redirect_uri" then validate_redirect_uri!
+        end
+      end
+
+      def validate_x509!(kind)
+        unless signing && signing[:key] && signing[:x5c] && !Array(signing[:x5c]).empty?
+          raise OpenID4VP::ConfigurationError, "#{client_id.prefix} requires a signing key and x5c"
+        end
+
+        leaf = OpenID4VP::X509.parse(Array(signing[:x5c]).first)
+        kind == :san_dns ? validate_x509_san_dns!(leaf) : validate_x509_hash!(leaf)
+      end
+
+      def validate_x509_san_dns!(leaf)
+        return if OpenID4VP::X509.dns_sans(leaf).include?(client_id.original)
+
+        raise OpenID4VP::ConfigurationError,
+              "x509_san_dns: leaf certificate SAN does not include #{client_id.original.inspect}"
+      end
+
+      def validate_x509_hash!(leaf)
+        return if OpenID4VP::X509.leaf_hash_b64(leaf) == client_id.original
+
+        raise OpenID4VP::ConfigurationError, "x509_hash: leaf certificate hash does not match client_id"
+      end
+
+      def validate_verifier_attestation!
+        raise OpenID4VP::ConfigurationError, "verifier_attestation requires attestation_jwt" if attestation_jwt.nil?
+        raise OpenID4VP::ConfigurationError, "verifier_attestation requires a signing key" unless signing_key
+
+        payload = OpenID4VP::JOSE::JWS.peek(attestation_jwt).payload || {}
+        validate_attestation_sub!(payload)
+        validate_attestation_cnf!(payload)
+      end
+
+      def validate_attestation_sub!(payload)
+        return if payload["sub"] == client_id.original
+
+        raise OpenID4VP::ConfigurationError, "verifier_attestation: attestation_jwt sub does not match client_id"
+      end
+
+      def validate_attestation_cnf!(payload)
+        cnf_jwk_hash = payload.dig("cnf", "jwk")
+        unless cnf_jwk_hash.is_a?(::Hash)
+          raise OpenID4VP::ConfigurationError, "verifier_attestation: attestation_jwt missing cnf.jwk"
+        end
+
+        cnf_jwk = OpenID4VP::JOSE::JWK.new(cnf_jwk_hash)
+        return if cnf_jwk.thumbprint == signing_key.thumbprint
+
+        raise OpenID4VP::ConfigurationError, "verifier_attestation: attestation_jwt cnf.jwk does not match signing key"
+      end
+
+      def validate_decentralized_identifier!
+        prefix = "#{client_id.original}#"
+        return if signing_key&.kid&.start_with?(prefix)
+
+        raise OpenID4VP::ConfigurationError,
+              "decentralized_identifier requires a signing key kid starting with #{prefix.inspect}"
+      end
+
+      def validate_redirect_uri!
+        return if signing.nil?
+
+        raise OpenID4VP::ConfigurationError, "redirect_uri client_id must not have a signing key"
+      end
+    end
+  end
+end

data/lib/openid4vp/verifier/created_request.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module OpenID4VP
+  class Verifier
+    # The result of `Verifier#create_request` (design doc §4.20): the
+    # stored `session`, and exactly one of `url` (by-value or by-reference
+    # Authorization Request URL) or `dc_api_request` (the DC API
+    # `{protocol, data}` object), plus the signed Request Object compact
+    # JWS when one was produced eagerly.
+    CreatedRequest = Struct.new(:session, :url, :request_object, :dc_api_request, :authorization_request,
+                                keyword_init: true) do
+      def session_id
+        session.id
+      end
+
+      def request_id
+        session.request_id
+      end
+
+      def nonce
+        session.nonce
+      end
+    end
+  end
+end

data/lib/openid4vp/verifier/http_result.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module OpenID4VP
+  class Verifier
+    # A framework-agnostic HTTP response from a Verifier endpoint (design doc
+    # §4.20): the status code, header Hash (lowercase keys) and body String
+    # a thin controller adapter can hand straight to its web framework.
+    HttpResult = Struct.new(:status, :headers, :body, keyword_init: true)
+
+    class HttpResult
+      NO_STORE = { "cache-control" => "no-store" }.freeze
+      JSON_HEADERS = { "content-type" => "application/json", "cache-control" => "no-store" }.freeze
+      JWT_HEADERS = { "content-type" => "application/oauth-authz-req+jwt", "cache-control" => "no-store" }.freeze
+
+      class << self
+        # OpenID4VP §8.2: a JSON response (200 with a ResponseEndpointResult,
+        # or any error/status code with a `{error, error_description}` body).
+        def json(status, hash)
+          new(status: status, headers: JSON_HEADERS, body: ::JSON.generate(hash))
+        end
+
+        # OpenID4VP §5.10.1: a Request URI endpoint response carrying the
+        # signed (optionally encrypted) Request Object.
+        def jwt(jws)
+          new(status: 200, headers: JWT_HEADERS, body: jws)
+        end
+
+        def error(status, code, description)
+          json(status, { "error" => code, "error_description" => description })
+        end
+      end
+    end
+  end
+end

data/lib/openid4vp/verifier/memory_session_store.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative "session_store"
+require_relative "../errors"
+
+module OpenID4VP
+  class Verifier
+    # In-process `SessionStore` (design doc §4.20): Mutex-protected Hash
+    # storage with secondary indexes by `request_id` and `response_code`.
+    # Expired sessions are dropped lazily on lookup (and in bulk via
+    # `#cleanup`); not shared across processes, so production deployments
+    # will typically supply their own `SessionStore`.
+    class MemorySessionStore < SessionStore
+      # `clock`: a callable returning the current Time, consulted by
+      # `#lookup` instead of `Time.now` directly -- lets a `Verifier`
+      # configured with its own `clock:` (design doc §4.20) keep this
+      # store's notion of "now" consistent with the rest of its request
+      # handling, and lets tests control expiry deterministically.
+      def initialize(clock: -> { Time.now })
+        super()
+        @clock = clock
+        @mutex = Mutex.new
+        @sessions = {}
+        @by_request_id = {}
+        @by_response_code = {}
+      end
+
+      def create(session)
+        @mutex.synchronize { index(session) }
+        session
+      end
+
+      def find(id)
+        @mutex.synchronize { lookup(id) }
+      end
+
+      def find_by_request_id(request_id)
+        @mutex.synchronize do
+          id = @by_request_id[request_id]
+          id && lookup(id)
+        end
+      end
+
+      def find_by_response_code(response_code)
+        @mutex.synchronize do
+          id = @by_response_code[response_code]
+          id && lookup(id)
+        end
+      end
+
+      def update(session)
+        @mutex.synchronize do
+          raise OpenID4VP::SessionNotFound, session.id unless @sessions.key?(session.id)
+
+          index(session)
+        end
+        session
+      end
+
+      def delete(id)
+        @mutex.synchronize { unindex(id) }
+        nil
+      end
+
+      # Drops every session expired as of `now`; returns how many were removed.
+      def cleanup(now)
+        @mutex.synchronize do
+          expired_ids = @sessions.each_value.select { |s| s.expired?(now) }.map(&:id)
+          expired_ids.each { |id| unindex(id) }
+          expired_ids.size
+        end
+      end
+
+      private
+
+      def index(session)
+        @sessions[session.id] = session
+        @by_request_id[session.request_id] = session.id if session.request_id
+        @by_response_code[session.response_code] = session.id if session.response_code
+      end
+
+      # Not synchronized itself: only called from within an already-held
+      # @mutex.synchronize block.
+      def lookup(id)
+        session = @sessions[id]
+        return nil if session.nil?
+        return session unless session.expired?(@clock.call)
+
+        unindex(id)
+        nil
+      end
+
+      def unindex(id)
+        session = @sessions.delete(id)
+        return unless session
+
+        @by_request_id.delete(session.request_id)
+        @by_response_code.delete(session.response_code) if session.response_code
+      end
+    end
+  end
+end