authproto 0.3.0.beta1

data/lib/authproto/dpop/client.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+require_relative '../errors'
+require_relative 'key_manager'
+require_relative 'nonce_manager'
+require_relative 'proof_generator'
+
+module AuthProto
+
+  #
+  # Key management, per-request proofs and server-origin nonces for DPoP authentication.
+  #
+
+  module DPoP
+
+    # High-level client for managing DPoP operations. Integrates key management,
+    # proof generation, and nonce tracking to provide a complete DPoP client
+    # implementation according to RFC 9449.
+    #
+    # This client handles:
+    # - Key management for signing proofs
+    # - Proof generation for HTTP requests
+    # - Nonce tracking across servers
+    # - Header construction for requests
+    # - Response processing for nonce updates
+    #
+
+    class Client
+
+      # Error raised for DPoP client operations
+      class Error < AuthProto::Error; end
+
+      # Key manager used to sign proofs.
+      # @return [KeyManager]
+      attr_reader :key_manager
+
+      # Generator for per-request DPoP JWTs.
+      # @return [ProofGenerator]
+      attr_reader :proof_generator
+
+      # Persistent nonce store, indexed by server origin.
+      # @return [NonceManager]
+      attr_reader :nonce_manager
+
+      # Creates DPoP signing, proof and nonce managers.
+      #
+      # @param key_manager [KeyManager, nil] existing key manager, or `nil` to generate a keypair
+      # @param nonce_ttl [Integer, nil] stored nonce lifetime in seconds, or the nonce manager's default
+      # @raise [KeyManager::KeyError] if key generation fails
+      # @raise [ProofGenerator::ProofError] if the key manager is invalid
+      # @raise [ArgumentError] if the encryption master key is not valid Base64
+      #
+      def initialize(key_manager: nil, nonce_ttl: nil)
+        @key_manager = key_manager || KeyManager.new
+        @nonce_manager = NonceManager.new(ttl: nonce_ttl)
+        @proof_generator = ProofGenerator.new(@key_manager)
+      end
+
+      # Generates a fresh DPoP proof using a supplied or stored nonce for the origin.
+      #
+      # @param http_method [String] HTTP method, converted to uppercase
+      # @param http_uri [String] absolute HTTP(S) URL; callers should omit the query and fragment
+      # @param access_token [String, nil] token to bind with an `ath` claim
+      # @param nonce [String, nil] explicit nonce; `nil` looks up the origin's stored nonce
+      # @return [JOSE::SignedBinary] compact signed DPoP JWT
+      # @raise [Error] if URI parsing, nonce lookup or signing fails
+      #
+      def generate_proof(http_method:, http_uri:, access_token: nil, nonce: nil)
+        uri = URI(http_uri)
+        server_url = "#{uri.scheme}://#{uri.host}#{":#{uri.port}" if uri.port != uri.default_port}"
+
+        # Use provided nonce or get one from the manager
+        nonce ||= @nonce_manager.get(server_url)
+
+        @proof_generator.generate(
+          http_method: http_method,
+          http_uri: http_uri,
+          nonce: nonce,
+          access_token: access_token
+        )
+      rescue StandardError => e
+        raise Error, "Failed to generate proof: #{e.message}"
+      end
+
+      # Stores a `DPoP-Nonce` response header for future requests to the same origin.
+      # Header names are compared case-insensitively. Missing headers/nonces are ignored.
+      #
+      # @param response_headers [Hash{String => String}, nil] response headers, or `nil`
+      # @param server_url [String] request URL whose origin owns the nonce
+      # @return [void]
+      # @raise [Error] if nonce validation or persistence fails
+      #
+      def process_response(response_headers, server_url)
+        return unless response_headers
+
+        # Look for DPoP-Nonce header (case insensitive)
+        nonce = response_headers.find { |k, _| k.downcase == "dpop-nonce" }&.last
+        return unless nonce
+
+        # Store new nonce for future requests
+        @nonce_manager.update(nonce: nonce, server_url: server_url)
+      rescue StandardError => e
+        raise Error, "Failed to process response: #{e.message}"
+      end
+
+      # Wraps a proof in an HTTP header hash.
+      #
+      # @param proof [String] signed DPoP JWT
+      # @return [Hash{String => String}] a single `DPoP` header
+      #
+      def request_headers(proof)
+        {
+          "DPoP" => proof
+        }
+      end
+
+      # Exports the current public signing key.
+      #
+      # @return [Hash{String => Object}] public JWK
+      # @raise [KeyManager::KeyError] if public-key export fails
+      #
+      def public_key
+        @key_manager.public_jwk
+      end
+
+      # Exports the current DPoP key for persistence or inspection.
+      #
+      # @param include_private [Boolean] include the private key needed to restore the same identity
+      # @return [JOSE::Map] JWK fields; call `to_h` for a Ruby hash
+      # @raise [KeyManager::KeyError] if key export fails
+      #
+      def export_key(include_private: false)
+        @key_manager.to_jwk(include_private: include_private)
+      end
+
+
+      private
+
+      def extract_nonce(headers)
+        # Headers can be hash with string or symbol keys, or http headers object
+        headers = headers.to_h if headers.respond_to?(:to_h)
+
+        # Try different common header key formats
+        nonce = headers["DPoP-Nonce"] || headers["dpop-nonce"] || headers[:dpop_nonce]
+
+        nonce&.strip
+      end
+
+      def origin_for_uri(uri)
+        port = uri.port
+        port = nil if (uri.scheme == "https" && port == 443) || (uri.scheme == "http" && port == 80)
+
+        origin = "#{uri.scheme}://#{uri.host}"
+        origin = "#{origin}:#{port}" if port
+        origin
+      end
+    end
+  end
+end

data/lib/authproto/dpop/key_manager.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'jose'
+require 'json'
+require 'openssl'
+
+require_relative '../errors'
+
+module AuthProto
+  module DPoP
+
+    #
+    # Manages ES256 keypair generation and storage for DPoP proofs.
+    # Provides functionality to generate new keys and store them securely.
+    # Uses JOSE for cryptographic operations and key format handling.
+    #
+
+    class KeyManager
+
+      # Error raised when key operations fail
+      class KeyError < AuthProto::Error; end
+
+      # Elliptic curve used for DPoP signing keys.
+      # @return [String]
+      CURVE = "P-256"
+
+      # JWS signing algorithm used for DPoP proofs.
+      # @return [String]
+      ALGORITHM = "ES256"
+
+      # Private EC P-256 keypair used for signing.
+      # @return [JOSE::JWK]
+      attr_reader :keypair
+
+      # Creates a new KeyManager instance with an optional existing keypair
+      #
+      # @param keypair [JOSE::JWK, nil] Optional existing keypair to use
+      # @raise [KeyError] if the provided keypair is invalid
+      #
+      def initialize(keypair = nil)
+        @keypair = keypair || generate_keypair
+        validate_keypair
+      end
+
+      # Generates a new ES256 keypair for DPoP usage
+      #
+      # @return [JOSE::JWK] The newly generated keypair
+      # @raise [KeyError] if key generation fails
+      #
+      def generate_keypair
+        # Generate base keypair
+        base_key = JOSE::JWK.generate_key([:ec, CURVE])
+        base_map = base_key.to_map
+
+        # Create new map with all required properties
+        key_map = {
+          "kty" => base_map["kty"],
+          "crv" => base_map["crv"],
+          "x" => base_map["x"],
+          "y" => base_map["y"],
+          "d" => base_map["d"],
+          "use" => "sig",
+          "kid" => generate_kid(base_map)
+        }
+
+        # Create new JWK with all properties
+        JOSE::JWK.from_map(key_map)
+      rescue StandardError => e
+        raise KeyError, "Failed to generate keypair: #{e.message}"
+      end
+
+      # Exports the public key with `use: sig` and a key ID.
+      #
+      # @return [Hash{String => Object}] public JWK without private key material
+      # @raise [KeyError] if public-key export fails
+      #
+      def public_jwk
+        jwk = @keypair.to_public.to_map.to_h
+        # If somehow the properties aren't set, add them
+        jwk["use"] ||= "sig"
+        jwk["kid"] ||= generate_kid(jwk)
+        jwk
+      rescue StandardError => e
+        raise KeyError, "Failed to export public key: #{e.message}"
+      end
+
+      # Signs bytes with this keypair and returns a compact JWS.
+      #
+      # @param data [String] payload bytes to sign
+      # @return [JOSE::SignedBinary] compact JWS (a string subclass)
+      # @raise [KeyError] if signing fails
+      #
+      def sign(data)
+        @keypair.sign(data).compact
+      rescue StandardError => e
+        raise KeyError, "Failed to sign data: #{e.message}"
+      end
+
+      # Signs a JSON payload with the supplied protected JWS header and ES256.
+      # Hash keys are recursively converted to strings. The algorithm is forced to `ES256`.
+      #
+      # @param header [Hash{String, Symbol => Object}] protected JOSE header fields
+      # @param payload [Hash{String, Symbol => Object}] JWT claims to JSON-encode
+      # @return [JOSE::SignedBinary] compact JWS (a string subclass)
+      # @raise [KeyError] if encoding or signing fails
+      #
+      def sign_segments(header, payload)
+        # Deep transform all keys to strings to avoid symbol comparison issues
+        header = deep_stringify_keys(header)
+        payload = deep_stringify_keys(payload)
+
+        # Configure JOSE to use ES256 for signing
+        signing_config = { "alg" => "ES256" }
+
+        # Merge our header with JOSE's required fields
+        full_header = header.merge(signing_config)
+
+        # Convert payload to JSON string before signing
+        payload_json = JSON.generate(payload)
+
+        # Create the JWS with our header and payload
+        jws = @keypair.sign(payload_json, full_header)
+
+        # Get the compact serialization
+        jws.compact
+      rescue StandardError => e
+        raise KeyError, "Failed to sign segments: #{e.message}"
+      end
+
+      # Copies hashes and arrays recursively, converting hash keys to strings.
+      #
+      # @param obj [Object] input structure or scalar value
+      # @return [Object] transformed hash/array, or the original scalar
+      #
+      def deep_stringify_keys(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) do |(k, v), hash|
+            hash[k.to_s] = deep_stringify_keys(v)
+          end
+        when Array
+          obj.map { |v| deep_stringify_keys(v) }
+        else
+          obj
+        end
+      end
+
+      # Verifies a compact JWS using this keypair.
+      #
+      # @param signed_jws [String, JOSE::SignedBinary] complete signed JWS
+      # @return [Boolean] whether the signature is valid
+      # @raise [KeyError] if decoding or verification raises an error
+      #
+      def verify(signed_jws)
+        verified, payload, = @keypair.verify(signed_jws)
+        verified
+      rescue StandardError => e
+        raise KeyError, "Failed to verify signature: #{e.message}"
+      end
+
+      # Exports this keypair as a JOSE map.
+      #
+      # @param include_private [Boolean] include secret `d` key material when `true`
+      # @return [JOSE::Map] JWK fields; call `to_h` for a Ruby hash
+      # @raise [KeyError] if export fails
+      #
+      def to_jwk(include_private: false)
+        key = include_private ? @keypair : @keypair.to_public
+        key.to_map
+      rescue StandardError => e
+        raise KeyError, "Failed to export key: #{e.message}"
+      end
+
+      # Imports an EC P-256 JWK and validates that it can sign and verify.
+      #
+      # @param jwk [Hash{String => Object}, JOSE::Map] JWK including private key material
+      # @return [KeyManager] imported key manager
+      # @raise [KeyError] if import or key validation fails
+      #
+      def self.from_jwk(jwk)
+        keypair = JOSE::JWK.from_map(jwk)
+        new(keypair)
+      rescue StandardError => e
+        raise KeyError, "Failed to import key: #{e.message}"
+      end
+
+      private
+
+      def generate_kid(jwk)
+        # Generate a key ID based on the key's components
+        components = [
+          jwk["kty"],
+          jwk["crv"],
+          jwk["x"],
+          jwk["y"]
+        ].join(":")
+
+        # Create a SHA-256 hash and take first 8 bytes
+        digest = OpenSSL::Digest::SHA256.digest(components)
+        Base64.urlsafe_encode64(digest[0..7], padding: false)
+      end
+
+      # Validates that the keypair meets DPoP requirements
+      # @raise [KeyError] if validation fails
+      def validate_keypair
+        # Check that we have a valid EC key
+        raise KeyError, "Invalid key type: #{@keypair.kty}, must be :ec" unless @keypair.kty.is_a?(JOSE::JWK::KTY_EC)
+
+        # Verify the curve
+        curve = @keypair.to_map["crv"]
+        raise KeyError, "Invalid curve: #{curve}, must be #{CURVE}" unless curve == CURVE
+
+        # Verify we can perform basic operations
+        test_data = "test"
+        signed = sign(test_data)
+        raise KeyError, "Key validation failed: signature verification error" unless verify(signed)
+      rescue StandardError => e
+        raise KeyError, "Key validation failed: #{e.message}"
+      end
+    end
+  end
+end

data/lib/authproto/dpop/nonce_manager.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+require_relative '../configuration'
+require_relative '../errors'
+require_relative '../serialization/stored_nonce'
+require_relative '../storage/key_builder'
+require_relative 'stored_nonce'
+
+module AuthProto
+  module DPoP
+
+    #
+    # Manages DPoP nonces provided by servers during the OAuth flow.
+    # Tracks separate nonces for each server using persistent storage.
+    # Thread-safe to handle concurrent requests.
+    #
+
+    class NonceManager
+
+      # Error for nonce-related issues
+      class NonceError < AuthProto::Error; end
+
+      # Default stored nonce lifetime in seconds.
+      # @return [Integer]
+      DEFAULT_TTL = 300 # 5 minutes
+
+      # Creates a nonce manager using the global storage backend.
+      #
+      # @param ttl [Integer, nil] nonce lifetime in seconds; `nil` uses {DEFAULT_TTL}
+      # @raise [ArgumentError] if the master encryption key is not valid Base64
+      #
+      def initialize(ttl: nil)
+        @ttl = ttl || DEFAULT_TTL
+        @serializer = Serialization::StoredNonce.new
+      end
+
+      # Stores a nonce for the URL's origin, replacing any previous value.
+      #
+      # @param nonce [String] nonempty server-provided nonce
+      # @param server_url [String] HTTPS URL, or HTTP URL with host `localhost`
+      # @return [void]
+      # @raise [NonceError] if inputs are invalid or storage reports failure
+      # @raise [Storage::StorageError] if backend validation or storage fails
+      #
+      def update(nonce:, server_url:)
+        validate_inputs(nonce, server_url)
+        origin = normalize_server_url(server_url)
+
+        stored_nonce = StoredNonce.new(nonce, origin)
+        serialized = @serializer.serialize(stored_nonce)
+
+        key = Storage::KeyBuilder.nonce_key(origin)
+        return if AuthProto.storage.set(key, serialized, ttl: @ttl)
+
+        raise NonceError, "Failed to store nonce"
+      end
+
+      # Retrieves the current nonce for a URL's origin.
+      #
+      # @param server_url [String] HTTPS URL, or HTTP URL with host `localhost`
+      # @return [String, nil] stored nonce, or `nil` when missing/expired according to storage TTL
+      # @raise [NonceError] if the URL is invalid or serialized data cannot be read
+      # @raise [Storage::StorageError] if storage retrieval fails
+      #
+      def get(server_url)
+        validate_server_url(server_url)
+        origin = normalize_server_url(server_url)
+        key = Storage::KeyBuilder.nonce_key(origin)
+
+        stored = AuthProto.storage.get(key)
+        return nil unless stored
+
+        begin
+          stored_nonce = @serializer.deserialize(stored)
+          stored_nonce.value
+        rescue Serialization::Error => e
+          raise NonceError, "Failed to deserialize nonce: #{e.message}"
+        end
+      end
+
+      # Removes the stored nonce for a URL's origin.
+      #
+      # @param server_url [String] HTTPS URL, or HTTP URL with host `localhost`
+      # @return [Boolean] backend deletion status
+      # @raise [NonceError] if the URL is invalid
+      # @raise [Storage::StorageError] if deletion fails
+      #
+      def clear(server_url)
+        validate_server_url(server_url)
+        origin = normalize_server_url(server_url)
+        key = Storage::KeyBuilder.nonce_key(origin)
+        AuthProto.storage.delete(key)
+      end
+
+      # Checks for an unexpired nonce record in storage for a URL's origin.
+      #
+      # @param server_url [String] HTTPS URL, or HTTP URL with host `localhost`
+      # @return [Boolean] whether the backend reports a nonce record present
+      # @raise [NonceError] if the URL is invalid
+      # @raise [Storage::StorageError] if the existence check fails
+      #
+      def valid_nonce?(server_url)
+        validate_server_url(server_url)
+        origin = normalize_server_url(server_url)
+        key = Storage::KeyBuilder.nonce_key(origin)
+        AuthProto.storage.exists?(key)
+      end
+
+      private
+
+      def normalize_server_url(url)
+        uri = URI(url)
+        port = uri.port
+        port = nil if (uri.scheme == "https" && port == 443) ||
+                      (uri.scheme == "http" && port == 80)
+
+        origin = "#{uri.scheme}://#{uri.host}"
+        origin = "#{origin}:#{port}" if port
+        origin
+      end
+
+      def validate_inputs(nonce, server_url)
+        raise NonceError, "nonce is required" if nonce.nil? || nonce.empty?
+
+        validate_server_url(server_url)
+      end
+
+      def validate_server_url(server_url)
+        raise NonceError, "server_url is required" if server_url.nil? || server_url.empty?
+
+        uri = URI(server_url)
+        raise NonceError, "server_url must be HTTP(S)" unless uri.is_a?(URI::HTTP)
+
+        # Allow HTTP for localhost only
+        if uri.host != "localhost" && uri.scheme != "https"
+          raise NonceError, "server_url must be HTTPS (except for localhost)"
+        end
+      rescue URI::InvalidURIError => e
+        raise NonceError, "invalid server_url: #{e.message}"
+      end
+    end
+  end
+end

data/lib/authproto/dpop/proof_generator.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'openssl'
+require 'securerandom'
+require 'uri'
+
+require_relative '../errors'
+require_relative 'key_manager'
+
+module AuthProto
+  module DPoP
+
+    #
+    # Creates and manages DPoP proof JWTs according to RFC 9449.
+    # DPoP proofs are used to prove possession of a key when making
+    # HTTP requests. Each proof is a JWT that includes details about
+    # the request and is signed by the DPoP key.
+    #
+
+    class ProofGenerator
+
+      # Error raised for proof generation/validation issues
+      class ProofError < AuthProto::Error; end
+
+      # Key manager used to sign proofs.
+      # @return [KeyManager]
+      attr_reader :key_manager
+
+      # Creates a new ProofGenerator instance
+      #
+      # @param key_manager [KeyManager] Key manager to use for signing proofs
+      # @raise [ProofError] if key_manager is invalid
+      #
+      def initialize(key_manager)
+        raise ProofError, "key_manager is required" unless key_manager
+        raise ProofError, "invalid key_manager type" unless key_manager.is_a?(KeyManager)
+
+        @key_manager = key_manager
+      end
+
+      # Builds and signs a fresh DPoP JWT with `jti`, `htm`, `htu` and `iat` claims.
+      #
+      # A nonce and access-token hash are added when requested. The URI normalizer removes
+      # fragments and default ports; callers must remove query strings before calling.
+      #
+      # @param http_method [String] nonempty HTTP method, converted to uppercase
+      # @param http_uri [String] absolute HTTP(S) request URL without a query string
+      # @param nonce [String, nil] server-provided nonce to include
+      # @param access_token [String, nil] access token to bind to the proof
+      # @param ath [Boolean, nil] include an access-token hash; `nil` enables it when a token is supplied
+      # @return [JOSE::SignedBinary] compact signed DPoP JWT
+      # @raise [ProofError] if input validation or proof generation fails
+      #
+      def generate(http_method:, http_uri:, nonce: nil, access_token: nil, ath: nil)
+        validate_inputs(http_method, http_uri)
+        ath = !access_token.nil? if ath.nil?
+
+        header = build_header
+        payload = build_payload(
+          http_method: http_method,
+          http_uri: http_uri,
+          nonce: nonce,
+          access_token: access_token,
+          include_ath: ath
+        )
+
+        key_manager.sign_segments(header, payload)
+      rescue StandardError => e
+        raise ProofError, "Failed to generate proof: #{e.message}"
+      end
+
+      private
+
+      def validate_inputs(http_method, http_uri)
+        raise ProofError, "http_method is required" if http_method.nil? || http_method.empty?
+        raise ProofError, "http_uri is required" if http_uri.nil? || http_uri.empty?
+
+        uri = URI(http_uri)
+        raise ProofError, "invalid http_uri" unless uri.is_a?(URI::HTTP)
+      rescue URI::InvalidURIError => e
+        raise ProofError, "invalid http_uri: #{e.message}"
+      end
+
+      def build_header
+        {
+          typ: "dpop+jwt",
+          alg: "ES256",
+          jwk: key_manager.public_jwk.to_h
+        }
+      end
+
+      def build_payload(http_method:, http_uri:, nonce: nil, access_token: nil, include_ath: nil)
+        payload = {
+          "jti" => SecureRandom.uuid,
+          "htm" => http_method.upcase,
+          "htu" => normalize_uri(http_uri),
+          "iat" => Time.now.to_i
+        }
+
+        # Add the nonce if provided
+        payload["nonce"] = nonce if nonce
+
+        # Add access token hash if needed
+        payload["ath"] = generate_access_token_hash(access_token) if access_token && include_ath
+
+        payload
+      end
+
+      def normalize_uri(uri)
+        uri = URI(uri)
+        # Remove default ports
+        uri.port = nil if (uri.scheme == "https" && uri.port == 443) || (uri.scheme == "http" && uri.port == 80)
+        uri.fragment = nil
+        uri.to_s
+      end
+
+      def generate_access_token_hash(access_token)
+        digest = OpenSSL::Digest::SHA256.digest(access_token)
+        Base64.urlsafe_encode64(digest, padding: false)
+      end
+    end
+  end
+end

data/lib/authproto/dpop/stored_nonce.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module AuthProto
+  module DPoP
+
+    #
+    # Represents a stored nonce with its server URL
+    #
+
+    class StoredNonce
+
+      # Nonce value received from the server.
+      # @return [String]
+      attr_reader :value
+
+      # Server origin associated with the nonce.
+      # @return [String]
+      attr_reader :server_url
+
+      # Creation timestamp; defaults to integer Unix seconds.
+      # @return [Integer, Time]
+      attr_reader :timestamp
+
+      # Creates a nonce record without validation.
+      #
+      # @param value [String] server-provided nonce
+      # @param server_url [String] server origin URL
+      # @param timestamp [Integer, Time, nil] timestamp to retain, or `nil` for current Unix seconds
+      #
+      def initialize(value, server_url, timestamp: nil)
+        @value = value
+        @server_url = server_url
+        @timestamp = timestamp || Time.now.to_i
+      end
+    end
+  end
+end