openid4vp 0.1.0

data/lib/openid4vp/error_response.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative "response_mode"
+require_relative "errors"
+require_relative "util/uri"
+require_relative "util/form"
+require_relative "encoded_response"
+
+module OpenID4VP
+  # OpenID4VP §8.5: the Authorization Error Response. Per §8.3.1, error
+  # responses are always sent unencrypted, even for `.jwt` Response Modes.
+  class ErrorResponse
+    Encoded = EncodedResponse
+
+    attr_reader :error, :error_description, :state
+
+    def initialize(error:, error_description: nil, state: nil)
+      @error = error
+      @error_description = error_description
+      @state = state
+      freeze
+    end
+
+    # Builds an ErrorResponse from a raised OpenID4VP::Error (or any
+    # exception): `error` is `exception.code` when present, else
+    # "invalid_request"; `error_description` is `exception.description` when
+    # the exception responds to it, else `exception.message`.
+    def self.from_exception(exception, state: nil)
+      code = exception.respond_to?(:code) && exception.code ? exception.code : "invalid_request"
+      description = exception.respond_to?(:description) ? exception.description : exception.message
+      new(error: code, error_description: description, state: state)
+    end
+
+    def to_params
+      params = { "error" => @error }
+      params["error_description"] = @error_description unless @error_description.nil?
+      params.merge(state_param)
+    end
+    alias to_payload to_params
+
+    # Encodes this error response for `response_mode`. Never encrypts, even
+    # for `.jwt` Response Modes (OpenID4VP §8.3.1): those are treated the
+    # same as their unencrypted counterpart. `encryption` is accepted for
+    # signature parity with AuthorizationResponse#encode and ignored.
+    def encode(response_mode, redirect_uri: nil, encryption: nil) # rubocop:disable Lint/UnusedMethodArgument
+      validate_response_mode!(response_mode)
+      return encode_redirect(response_mode, redirect_uri) if ResponseMode.redirect?(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
+
+    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
+  end
+end

data/lib/openid4vp/errors.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module OpenID4VP
+  # Base class for all errors raised by this gem. Subclasses that represent
+  # OAuth 2.0 / OpenID4VP protocol errors declare an `oauth_code`; a subclass
+  # without its own code inherits its superclass's code.
+  class Error < StandardError
+    class << self
+      def oauth_code(code)
+        @code = code
+      end
+
+      def code
+        @code || (superclass.respond_to?(:code) ? superclass.code : nil)
+      end
+    end
+
+    def code
+      self.class.code
+    end
+
+    def description
+      message
+    end
+  end
+
+  class InvalidRequest < Error
+    oauth_code "invalid_request"
+  end
+
+  class InvalidClient < Error
+    oauth_code "invalid_client"
+  end
+
+  class InvalidScope < Error
+    oauth_code "invalid_scope"
+  end
+
+  class AccessDenied < Error
+    oauth_code "access_denied"
+  end
+
+  class VpFormatsNotSupported < Error
+    oauth_code "vp_formats_not_supported"
+  end
+
+  class InvalidRequestUriMethod < Error
+    oauth_code "invalid_request_uri_method"
+  end
+
+  class InvalidTransactionData < Error
+    oauth_code "invalid_transaction_data"
+  end
+
+  class WalletUnavailable < Error
+    oauth_code "wallet_unavailable"
+  end
+
+  # Raised for verifier-side response/presentation verification failures that
+  # are reported to the wallet as an OAuth "invalid_request" error.
+  class VerificationError < InvalidRequest; end
+
+  # Raised for wallet-side response validation problems. Has no OAuth error
+  # code of its own since it is not sent back over the wire as such.
+  class InvalidResponse < Error; end
+
+  class PresentationInvalid < InvalidResponse; end
+  class HolderBindingInvalid < InvalidResponse; end
+  class QueryNotSatisfied < InvalidResponse; end
+
+  class SessionNotFound < Error; end
+  class ConfigurationError < Error; end
+end

data/lib/openid4vp/formats/base.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "../formats"
+require_relative "../errors"
+require_relative "../dcql/meta"
+
+module OpenID4VP
+  module Formats
+    # Abstract base for a Credential Format handler. A concrete subclass
+    # implements `.format_id`, `#verify_presentation`, `#build_presentation`
+    # and `.credential_from`; `#check_vp_formats!` is overridden by formats
+    # that define `vp_formats_supported` algorithm-restriction parameters
+    # (OpenID4VP Appendix B).
+    class Base
+      def self.format_id
+        raise NotImplementedError, "#{self} must implement .format_id"
+      end
+
+      def self.credential_from(*, **)
+        raise NotImplementedError, "#{self} must implement .credential_from"
+      end
+
+      def format_id
+        self.class.format_id
+      end
+
+      # Verifies a single raw Presentation (a String, or a format-specific
+      # structure) against `context` (a `Context`), returning a
+      # `VerifiedPresentation`. Raises `PresentationInvalid` /
+      # `HolderBindingInvalid` on failure.
+      def verify_presentation(_presentation, _context)
+        raise NotImplementedError, "#{self.class} must implement #verify_presentation"
+      end
+
+      # Builds a raw Presentation (a String, or a format-specific Hash) for
+      # `credential` (an `OpenID4VP::Credential`), disclosing the claims
+      # addressed by `claims_queries` (an Array of `DCQL::ClaimsQuery`),
+      # against `context` (a `Context`).
+      def build_presentation(_credential, _claims_queries, _context)
+        raise NotImplementedError, "#{self.class} must implement #build_presentation"
+      end
+
+      # OpenID4VP Appendix B: validates the REQUIRED shape of this format's
+      # `meta` parameter in a DCQL Credential Query.
+      def validate_meta!(meta)
+        OpenID4VP::DCQL::Meta.validate!(format_id, meta)
+      end
+
+      # Whether `credential` (an `OpenID4VP::Credential`) matches `meta`.
+      def meta_matches?(meta, credential)
+        OpenID4VP::DCQL::Meta.matches?(format_id, meta, credential)
+      end
+
+      # Enforces this format's `vp_formats_supported` algorithm
+      # restrictions (OpenID4VP Appendix B) against a `VerifiedPresentation`.
+      # No-op by default: `vp_formats` is nil, or carries no parameters for
+      # this format. Formats with restrictable algorithms override this,
+      # using `alg_allowed!` below.
+      def check_vp_formats!(_verified, _vp_formats); end
+
+      protected
+
+      # Raises PresentationInvalid unless `alg` is allowed by `values` (an
+      # Array from `vp_formats.params_for(format_id)`, or nil when the
+      # parameter is absent). A nil `alg` (the restriction does not apply to
+      # this Presentation) is always allowed.
+      def alg_allowed!(values, alg, param_name)
+        return if values.nil? || alg.nil? || values.include?(alg)
+
+        raise OpenID4VP::PresentationInvalid, "#{param_name} does not allow #{alg}"
+      end
+    end
+  end
+end

data/lib/openid4vp/formats/context.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "../formats"
+
+module OpenID4VP
+  module Formats
+    # Everything a `Base` handler needs to verify or build a Presentation,
+    # threaded through by the (not-yet-implemented) protocol layer.
+    # Immutable.
+    class Context
+      attr_reader :nonce, :audience, :client_id, :response_uri, :origin, :encryption_jwk, :transaction_data, :now,
+                  :leeway, :trust, :vp_formats, :require_holder_binding, :dc_api
+
+      # nonce/audience: the Authorization Request's `nonce`, and the
+      #   expected `aud` of a holder-bound Presentation (the Client
+      #   Identifier, or `origin:<origin>` for DC API requests -- see
+      #   OpenID4VP Appendix B.3.6 / A.4).
+      # trust: a Hash with Symbol keys, e.g. `:sd_jwt_issuer_keys` (callable
+      #   `(iss, header) -> JWK | [JWK]`), `:jwt_vc_issuer_keys`,
+      #   `:jwt_vc_holder_keys`, `:mdoc_trust_anchors` (Array of
+      #   certificates), `:ldp_proof_verifier` (callable
+      #   `(vp_hash, context) -> bool`). Consulted via `#trust_hook`.
+      #   `:authority_hooks` (OpenID4VP §6.1.1, consulted by
+      #   `Verifier::ResponseValidator`, not via `#trust_hook`) is instead a
+      #   Hash of `{trusted_authorities "type" String => callable(ta_query,
+      #   credential) -> bool}`, for authority types `DCQL::Matcher
+      #   .authority_matches?` has no built-in check for (only `"aki"` is
+      #   built in).
+      # vp_formats: an `OpenID4VP::Metadata::VpFormats`, or nil to skip
+      #   `Base#check_vp_formats!` algorithm restriction checks.
+      def initialize(nonce:, audience:, client_id: nil, response_uri: nil, origin: nil, encryption_jwk: nil,
+                     transaction_data: nil, now: Time.now, leeway: 60, trust: {}, vp_formats: nil,
+                     require_holder_binding: true, dc_api: false)
+        @nonce = nonce
+        @audience = audience
+        @client_id = client_id
+        @response_uri = response_uri
+        @origin = origin
+        @encryption_jwk = encryption_jwk
+        @transaction_data = transaction_data
+        @now = now
+        @leeway = leeway
+        @trust = trust.dup.freeze
+        @vp_formats = vp_formats
+        @require_holder_binding = require_holder_binding
+        @dc_api = dc_api
+        freeze
+      end
+
+      # The configured trust hook for `name` (a Symbol), or nil.
+      def trust_hook(name)
+        trust[name]
+      end
+    end
+  end
+end

data/lib/openid4vp/formats/jwt_vc_json.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+require_relative "../formats"
+require_relative "base"
+require_relative "verified_presentation"
+require_relative "registry"
+require_relative "../errors"
+require_relative "../credential"
+require_relative "../x509"
+require_relative "../jose/jws"
+require_relative "../jose/jwk"
+
+module OpenID4VP
+  module Formats
+    # OpenID4VP Appendix B.1.3.1: the `jwt_vc_json` (W3C Verifiable
+    # Credential secured as a JWT, no JSON-LD) Credential Format handler.
+    class JwtVcJson < Base
+      FORMAT_ID = "jwt_vc_json"
+      VP_CONTEXT = ["https://www.w3.org/2018/credentials/v1"].freeze
+
+      def self.format_id
+        FORMAT_ID
+      end
+
+      # Issues a `jwt_vc_json` Verifiable Credential JWT with payload
+      # `{iss, sub, nbf, exp, jti, vc: {"@context", "type", "credentialSubject"}}`.
+      def self.issue_vc(claims:, issuer:, subject:, types:, key:, alg: nil, exp: nil, nbf: nil, jti: nil)
+        payload = {
+          "iss" => issuer,
+          "sub" => subject,
+          "nbf" => nbf || Time.now.to_i,
+          "jti" => jti || "urn:uuid:#{::SecureRandom.uuid}",
+          "vc" => {
+            "@context" => VP_CONTEXT,
+            "type" => types,
+            "credentialSubject" => claims
+          }
+        }
+        payload["exp"] = exp unless exp.nil?
+        OpenID4VP::JOSE::JWS.sign(payload, key: key, alg: alg, header: { "typ" => "JWT" })
+      end
+
+      # Parses (WITHOUT verifying the signature) an issued VC JWT into a
+      # wallet-side `OpenID4VP::Credential`, e.g. right after issuance.
+      def self.credential_from(vc_jwt, holder_key: nil)
+        peeked = OpenID4VP::JOSE::JWS.peek(vc_jwt)
+        claims, metadata = claims_and_metadata(peeked.payload)
+
+        OpenID4VP::Credential.new(
+          format: FORMAT_ID,
+          claims: claims,
+          raw: vc_jwt,
+          holder_key: holder_key,
+          x5chain: x5chain_from_header(peeked.header),
+          metadata: metadata
+        )
+      end
+
+      # Merges the VC's own claims (`vc`) with the enclosing JWT's top-level
+      # `iss`/`sub`/`nbf`/`exp`/`jti`, so both `["credentialSubject", "x"]`
+      # and `["iss"]` claims paths resolve. Returns `[claims, metadata]`.
+      def self.claims_and_metadata(payload)
+        raise OpenID4VP::PresentationInvalid, "jwt_vc_json: payload is not a JSON object" unless payload.is_a?(::Hash)
+
+        vc = payload["vc"]
+        raise OpenID4VP::PresentationInvalid, "jwt_vc_json: payload missing vc" unless vc.is_a?(::Hash)
+
+        claims = vc.merge(
+          "iss" => payload["iss"], "sub" => payload["sub"], "nbf" => payload["nbf"],
+          "exp" => payload["exp"], "jti" => payload["jti"]
+        ).compact
+        metadata = { "type" => vc["type"], "issuer" => payload["iss"], "holder" => payload["sub"] }
+        [claims, metadata]
+      end
+
+      def self.x5chain_from_header(header)
+        x5c = header["x5c"]
+        return [] unless x5c.is_a?(::Array)
+
+        OpenID4VP::X509.certs_from_x5c(x5c)
+      end
+      private_class_method :x5chain_from_header
+
+      # Verifies `presentation` (a compact JWT String) against `context`.
+      # Accepts either a Verifiable Presentation JWT (payload has `vp`) or,
+      # when `!context.require_holder_binding`, a bare Verifiable Credential
+      # JWT (payload has `vc` but no `vp`) -- OpenID4VP Appendix B.1.
+      def verify_presentation(presentation, context)
+        unless presentation.is_a?(::String)
+          raise OpenID4VP::PresentationInvalid, "jwt_vc_json: presentation must be a string"
+        end
+
+        peeked = OpenID4VP::JOSE::JWS.peek(presentation)
+        payload = peeked.payload
+        raise OpenID4VP::PresentationInvalid, "jwt_vc_json: payload is not a JSON object" unless payload.is_a?(::Hash)
+
+        if payload.key?("vp")
+          verify_vp(presentation, peeked.header, payload, context)
+        elsif payload.key?("vc")
+          verify_bare_vc(presentation, context)
+        else
+          raise OpenID4VP::PresentationInvalid, "jwt_vc_json: payload has neither vp nor vc"
+        end
+      end
+
+      # OpenID4VP Appendix B.1.3.1.3: `alg_values` restricts the `alg` of
+      # both the Verifiable Presentation JWT and the Verifiable Credential
+      # JWT it carries.
+      def check_vp_formats!(verified, vp_formats)
+        return if vp_formats.nil?
+
+        params = vp_formats.params_for(FORMAT_ID)
+        return if params.nil?
+
+        alg_allowed!(params["alg_values"], verified.details[:vp_alg], "alg_values")
+        alg_allowed!(params["alg_values"], verified.details[:vc_alg], "alg_values")
+      end
+
+      # Builds a Verifiable Presentation JWT for `credential`. When the
+      # credential has no holder key: returns `credential.raw` unchanged if
+      # `!context.require_holder_binding` (a Credential without Holder
+      # Binding, Appendix B.1), else raises HolderBindingInvalid.
+      def build_presentation(credential, _claims_queries, context)
+        holder_key = credential.holder_key
+        if holder_key.nil?
+          raise OpenID4VP::HolderBindingInvalid, "credential has no holder key" if context.require_holder_binding
+
+          return credential.raw
+        end
+
+        iat = context.now.to_i
+        holder_id = credential.metadata["holder"] || "did:jwk:#{holder_key.thumbprint_b64}"
+        payload = {
+          "iss" => holder_id,
+          "jti" => "urn:uuid:#{::SecureRandom.uuid}",
+          "aud" => context.audience,
+          "nonce" => context.nonce,
+          "iat" => iat,
+          "nbf" => iat,
+          "exp" => iat + 300,
+          "vp" => {
+            "@context" => VP_CONTEXT,
+            "type" => ["VerifiablePresentation"],
+            "verifiableCredential" => [credential.raw]
+          }
+        }
+        OpenID4VP::JOSE::JWS.sign(payload, key: holder_key, header: { "typ" => "JWT" })
+      end
+
+      private
+
+      def verify_vp(presentation, header, unverified_payload, context)
+        resolver = context.trust_hook(:jwt_vc_holder_keys)
+        holder_key = resolver&.call(unverified_payload["iss"], header)
+        raise OpenID4VP::HolderBindingInvalid, "jwt_vc_json: cannot resolve holder key" if holder_key.nil?
+
+        verified = OpenID4VP::JOSE::JWS.verify(presentation, key: holder_key)
+        payload = verified.payload
+
+        raise OpenID4VP::HolderBindingInvalid, "jwt_vc_json: nonce mismatch" unless payload["nonce"] == context.nonce
+        raise OpenID4VP::HolderBindingInvalid, "jwt_vc_json: aud mismatch" unless payload["aud"] == context.audience
+
+        check_time_bounds!(payload, context, "presentation")
+
+        vc_jwt = single_verifiable_credential(payload["vp"])
+        vc_result = verify_vc_jwt(vc_jwt, context)
+        check_subject_binding!(payload["iss"], holder_key, vc_result[:payload])
+
+        VerifiedPresentation.new(
+          format: FORMAT_ID,
+          claims: vc_result[:claims],
+          holder_bound: true,
+          issuer: vc_result[:issuer],
+          raw: presentation,
+          metadata: vc_result[:metadata],
+          details: { vp_alg: verified.header["alg"], vc_alg: vc_result[:alg] }
+        )
+      end
+
+      def verify_bare_vc(presentation, context)
+        raise OpenID4VP::HolderBindingInvalid, "jwt_vc_json: holder binding required" if context.require_holder_binding
+
+        vc_result = verify_vc_jwt(presentation, context)
+
+        VerifiedPresentation.new(
+          format: FORMAT_ID,
+          claims: vc_result[:claims],
+          holder_bound: false,
+          issuer: vc_result[:issuer],
+          raw: presentation,
+          metadata: vc_result[:metadata],
+          details: { vp_alg: nil, vc_alg: vc_result[:alg] }
+        )
+      end
+
+      def single_verifiable_credential(vp_object)
+        vcs = vp_object.is_a?(::Hash) ? vp_object["verifiableCredential"] : nil
+        unless vcs.is_a?(::Array) && vcs.size == 1
+          raise OpenID4VP::PresentationInvalid, "jwt_vc_json: multiple credentials in one presentation not supported"
+        end
+
+        vcs.first
+      end
+
+      def verify_vc_jwt(vc_jwt, context)
+        unless vc_jwt.is_a?(::String)
+          raise OpenID4VP::PresentationInvalid, "jwt_vc_json: verifiableCredential entry must be a string"
+        end
+
+        peeked = OpenID4VP::JOSE::JWS.peek(vc_jwt)
+        vc_payload = peeked.payload
+        unless vc_payload.is_a?(::Hash)
+          raise OpenID4VP::PresentationInvalid, "jwt_vc_json: vc payload is not a JSON object"
+        end
+
+        resolver = context.trust_hook(:jwt_vc_issuer_keys)
+        raise OpenID4VP::ConfigurationError, "jwt_vc_issuer_keys trust hook required" if resolver.nil?
+
+        issuer_key = resolver.call(vc_payload["iss"], peeked.header)
+        raise OpenID4VP::PresentationInvalid, "jwt_vc_json: unknown issuer" if issuer_key.nil?
+
+        verified_vc = OpenID4VP::JOSE::JWS.verify(vc_jwt, key: issuer_key)
+        check_time_bounds!(verified_vc.payload, context, "credential")
+
+        claims, metadata = self.class.claims_and_metadata(verified_vc.payload)
+        { claims: claims, metadata: metadata, issuer: verified_vc.payload["iss"], alg: verified_vc.header["alg"],
+          payload: verified_vc.payload }
+      end
+
+      # OpenID4VP Appendix B.1.3.1.5: the VP JWT's `iss` (the holder id the
+      # presentation was signed under) must be the enclosed VC's own
+      # subject -- `iss == vc_payload["sub"]` or `iss ==
+      # vc["credentialSubject"]["id"]` -- so a party holding someone else's
+      # VC cannot present it as their own. Only when the VC declares
+      # neither does a `cnf.jwk` in the VC payload matching the VP signing
+      # key's thumbprint satisfy the binding instead.
+      def check_subject_binding!(vp_iss, vp_signing_key, vc_payload)
+        sub = vc_payload["sub"]
+        vc = vc_payload["vc"]
+        subject_id = vc.is_a?(::Hash) ? vc.dig("credentialSubject", "id") : nil
+
+        if sub || subject_id
+          return if vp_iss == sub || vp_iss == subject_id
+        elsif cnf_jwk_matches?(vc_payload, vp_signing_key)
+          return
+        end
+
+        raise OpenID4VP::HolderBindingInvalid, "jwt_vc_json: VP issuer does not match credential subject"
+      end
+
+      def cnf_jwk_matches?(vc_payload, vp_signing_key)
+        cnf_jwk_hash = vc_payload.dig("cnf", "jwk")
+        return false unless cnf_jwk_hash.is_a?(::Hash)
+
+        OpenID4VP::JOSE::JWK.new(cnf_jwk_hash).thumbprint == vp_signing_key.thumbprint
+      rescue OpenID4VP::InvalidRequest
+        false
+      end
+
+      def check_time_bounds!(payload, context, kind)
+        now = context.now.to_i
+        exp = payload["exp"]
+        raise OpenID4VP::PresentationInvalid, "jwt_vc_json: #{kind} expired" if exp && now > exp + context.leeway
+
+        nbf = payload["nbf"]
+        return unless nbf && now < nbf - context.leeway
+
+        raise OpenID4VP::PresentationInvalid, "jwt_vc_json: #{kind} not yet valid"
+      end
+    end
+
+    Registry.default_handlers << JwtVcJson unless Registry.default_handlers.include?(JwtVcJson)
+  end
+end