m2m_keygen 0.4.7 → 0.5.0

data/lib/m2m_keygen/nonce_store/disabled.rb

@@ -0,0 +1,19 @@
+# typed: strict
+
+module M2mKeygen
+  module NonceStore
+    # Explicit, greppable opt-out: `add` always succeeds, so replay protection
+    # falls back to expiry-only. See docs/ for when that risk is acceptable.
+    class Disabled
+      include NonceStore
+      extend T::Sig
+
+      # rubocop:disable Lint/UnusedMethodArgument -- interface method, args unused here
+      sig { override.params(nonce: String, ttl: Integer).returns(T::Boolean) }
+      def add(nonce, ttl:)
+        true
+      end
+      # rubocop:enable Lint/UnusedMethodArgument
+    end
+  end
+end

data/lib/m2m_keygen/nonce_store/memory.rb

@@ -0,0 +1,64 @@
+# typed: strict
+
+module M2mKeygen
+  module NonceStore
+    # In-process nonce store backed by a Mutex-guarded Hash.
+    #
+    # ⚠️ SINGLE-PROCESS ONLY. This store lives in this Ruby process' memory.
+    # As soon as your service runs more than one process — multiple Puma/Unicorn
+    # workers, multiple hosts, a restart between two requests — each process
+    # holds its own independent set of seen nonces, so replay protection becomes
+    # PARTIAL: a nonce recorded by worker A is invisible to worker B, which will
+    # happily accept it again. Use this only for single-process deployments or
+    # local development. For multi-worker/multi-host production, back
+    # `nonce_store:` with a store shared across processes (e.g. Redis or
+    # Postgres) — see the reference implementations under `examples/nonce_store/`.
+    class Memory
+      include NonceStore
+      extend T::Sig
+
+      DEFAULT_MAX_SIZE = 100_000
+
+      sig { params(max_size: Integer).void }
+      def initialize(max_size: DEFAULT_MAX_SIZE)
+        @max_size = T.let(max_size, Integer)
+        @mutex = T.let(Mutex.new, Mutex)
+        @expirations_by_nonce = T.let({}, T::Hash[String, Float])
+      end
+
+      sig { override.params(nonce: String, ttl: Integer).returns(T::Boolean) }
+      def add(nonce, ttl:)
+        @mutex.synchronize do
+          purge_expired
+          next false if @expirations_by_nonce.key?(nonce)
+
+          evict_soonest_to_expire if at_capacity?
+          @expirations_by_nonce[nonce] = Time.now.to_f + ttl
+          true
+        end
+      end
+
+      private
+
+      sig { void }
+      def purge_expired
+        now = Time.now.to_f
+        @expirations_by_nonce.delete_if do |_nonce, expires_at|
+          expires_at <= now
+        end
+      end
+
+      sig { returns(T::Boolean) }
+      def at_capacity?
+        @expirations_by_nonce.size >= @max_size
+      end
+
+      sig { void }
+      def evict_soonest_to_expire
+        soonest, =
+          @expirations_by_nonce.min_by { |_nonce, expires_at| expires_at }
+        @expirations_by_nonce.delete(soonest) if soonest
+      end
+    end
+  end
+end

data/lib/m2m_keygen/nonce_store.rb

@@ -0,0 +1,18 @@
+# typed: strict
+
+module M2mKeygen
+  # `add` MUST be atomic (check-and-set in one step): a separate seen?/record
+  # pair would be a TOCTOU race.
+  module NonceStore
+    extend T::Sig
+    extend T::Helpers
+    include Kernel
+
+    interface!
+
+    # Returns true if newly recorded, false if already seen (replay).
+    sig { abstract.params(nonce: String, ttl: Integer).returns(T::Boolean) }
+    def add(nonce, ttl:)
+    end
+  end
+end

data/lib/m2m_keygen/rack_validator.rb

@@ -6,40 +6,93 @@ module M2mKeygen
   class RackValidator
     extend T::Sig
 
+    DEFAULT_WINDOW_SECONDS = 120
+    NONCE_TTL_MARGIN_SECONDS = 5
+    MAX_NONCE_BYTES = 256
+
     sig { returns(Signature) }
     attr_reader :signature
 
     sig { returns(String) }
     attr_reader :header_name
 
-    sig { params(secret: String, algorithm: String, header_name: String).void }
-    def initialize(secret, algorithm: 'sha512', header_name: 'X-Signature')
-      @header_name = T.let("HTTP_#{header_name.tr('-', '_').upcase}", String)
+    sig do
+      params(
+        secret: String,
+        nonce_store: NonceStore,
+        algorithm: String,
+        header_name: String,
+        window: Integer,
+        expiry_header: String,
+        nonce_header: String,
+      ).void
+    end
+    def initialize(
+      secret,
+      nonce_store:,
+      algorithm: 'sha512',
+      header_name: 'X-Signature',
+      window: DEFAULT_WINDOW_SECONDS,
+      expiry_header: 'X-M2M-Expiry',
+      nonce_header: 'X-M2M-Nonce'
+    )
       @signature = T.let(Signature.new(secret, algorithm: algorithm), Signature)
+      @nonce_store = T.let(nonce_store, NonceStore)
+      @window = T.let(window, Integer)
+      @header_name = T.let(env_key_for(header_name), String)
+      @expiry_header = T.let(env_key_for(expiry_header), String)
+      @nonce_header = T.let(env_key_for(nonce_header), String)
     end
 
     sig { params(req: T.untyped).returns(T::Boolean) }
     def validate(req)
-      # This will cover the case when Rails is used.
-      req = Rack::Request.new(req.env)
-      params = (req.params || {}).merge(parse_json_body(req))
-      !!@signature.validate(
-        params: params,
-        verb: req.request_method || 'get',
-        path: req.path || '/',
-        signature: req.env['HTTP_X_SIGNATURE'] || '',
-      ) && params['expiry'] && params['expiry'].to_i > Time.now.to_i &&
-        params['expiry'].to_i < Time.now.to_i + 120
+      request = Rack::Request.new(req.env)
+      nonce = request.env[@nonce_header].to_s
+      return false if nonce.empty? && nonce_required?
+      return false if nonce.bytesize > MAX_NONCE_BYTES
+
+      expiry = request.env[@expiry_header].to_i
+      body = request.body.read.to_s
+      request.body.rewind
+
+      valid_signature =
+        @signature.validate(
+          signature: request.env[@header_name].to_s,
+          verb: request.request_method || 'GET',
+          path: request.path || '/',
+          expiry: expiry,
+          nonce: nonce,
+          query: request.query_string || '',
+          body: body,
+        )
+
+      !!(
+        valid_signature && expiry_within_window?(expiry) &&
+          @nonce_store.add(nonce, ttl: nonce_ttl(expiry))
+      )
     end
 
     private
 
-    sig { params(req: T.untyped).returns(T::Hash[T.untyped, T.untyped]) }
-    def parse_json_body(req)
-      body = req.body.read
-      JSON.parse(body || '{}')
-    rescue JSON::ParserError
-      {}
+    sig { returns(T::Boolean) }
+    def nonce_required?
+      !@nonce_store.is_a?(NonceStore::Disabled)
+    end
+
+    sig { params(expiry: Integer).returns(T::Boolean) }
+    def expiry_within_window?(expiry)
+      now = Time.now.to_i
+      now < expiry && expiry < now + @window
+    end
+
+    sig { params(expiry: Integer).returns(Integer) }
+    def nonce_ttl(expiry)
+      expiry - Time.now.to_i + NONCE_TTL_MARGIN_SECONDS
+    end
+
+    sig { params(name: String).returns(String) }
+    def env_key_for(name)
+      "HTTP_#{name.tr('-', '_').upcase}"
     end
   end
 end

data/lib/m2m_keygen/request_signer/signed_request.rb

@@ -0,0 +1,10 @@
+# typed: strict
+
+module M2mKeygen
+  class RequestSigner
+    class SignedRequest < T::Struct
+      const :headers, T::Hash[String, String]
+      const :query, String
+    end
+  end
+end

data/lib/m2m_keygen/request_signer.rb

@@ -0,0 +1,118 @@
+# typed: strict
+
+require 'rack'
+require 'securerandom'
+
+module M2mKeygen
+  class RequestSigner
+    extend T::Sig
+
+    DEFAULT_EXPIRY_TTL_SECONDS = 90
+    NONCE_BYTES = 16
+
+    sig do
+      params(
+        secret: String,
+        algorithm: String,
+        header_name: String,
+        expiry_header: String,
+        nonce_header: String,
+      ).void
+    end
+    def initialize(
+      secret,
+      algorithm: 'sha512',
+      header_name: 'X-Signature',
+      expiry_header: 'X-M2M-Expiry',
+      nonce_header: 'X-M2M-Nonce'
+    )
+      @signature = T.let(Signature.new(secret, algorithm: algorithm), Signature)
+      @header_name = T.let(header_name, String)
+      @expiry_header = T.let(expiry_header, String)
+      @nonce_header = T.let(nonce_header, String)
+    end
+
+    sig do
+      params(
+        verb: String,
+        path: String,
+        params: Types::ParamsType,
+        body: String,
+        expiry: T.nilable(Integer),
+        nonce: T.nilable(String),
+      ).returns(SignedRequest)
+    end
+    def sign_request(
+      verb:,
+      path:,
+      params: {},
+      body: '',
+      expiry: nil,
+      nonce: nil
+    )
+      resolved_nonce = nonce || SecureRandom.hex(NONCE_BYTES)
+      resolved_expiry = expiry || (Time.now.to_i + DEFAULT_EXPIRY_TTL_SECONDS)
+      query = build_query(params)
+
+      signature =
+        @signature.sign(
+          verb: verb,
+          path: path,
+          expiry: resolved_expiry,
+          nonce: resolved_nonce,
+          query: query,
+          body: body,
+        )
+
+      SignedRequest.new(
+        headers: {
+          @header_name => signature,
+          @expiry_header => resolved_expiry.to_s,
+          @nonce_header => resolved_nonce,
+        },
+        query: query,
+      )
+    end
+
+    private
+
+    sig { params(params: Types::ParamsType).returns(String) }
+    def build_query(params)
+      return '' if params.empty?
+
+      Rack::Utils.build_query(stringify_values(params))
+    end
+
+    sig do
+      params(params: Types::ParamsType).returns(T::Hash[String, T.untyped])
+    end
+    def stringify_values(params)
+      params
+        .transform_keys(&:to_s)
+        .transform_values { |value| stringify(value) }
+    end
+
+    sig do
+      params(value: Types::ParamsValueType).returns(
+        T.any(String, T::Array[String]),
+      )
+    end
+    def stringify(value)
+      if value.is_a?(Array)
+        return value.map { |element| stringify_scalar(element) }
+      end
+
+      stringify_scalar(value)
+    end
+
+    sig { params(value: Types::ParamsScalarType).returns(String) }
+    def stringify_scalar(value)
+      if value.is_a?(Float) && !value.finite?
+        raise CanonicalizationError,
+              "Non-finite float values cannot be signed (NaN/Infinity): #{value.inspect}"
+      end
+
+      value.to_s
+    end
+  end
+end

data/lib/m2m_keygen/signature.rb

@@ -1,15 +1,11 @@
 # typed: strict
 
 require 'openssl'
-require 'json'
 
 module M2mKeygen
   class Signature
     extend T::Sig
 
-    sig { returns(String) }
-    attr_reader :secret
-
     sig { returns(String) }
     attr_reader :algorithm
 
@@ -17,62 +13,68 @@ module M2mKeygen
     def initialize(secret, algorithm: 'sha512')
       @secret = T.let(secret, String)
       @algorithm = T.let(algorithm, String)
+      # Fail fast on an unsupported algorithm (OpenSSL's error class varies).
       OpenSSL::HMAC.hexdigest(@algorithm, @secret, '')
+    rescue StandardError => e
+      raise Error,
+            "Unsupported HMAC algorithm #{algorithm.inspect}: #{e.message}"
+    end
+
+    sig { returns(String) }
+    def inspect
+      "#<#{self.class.name} algorithm=#{@algorithm.inspect}>"
     end
 
     sig do
       params(
-        params: Types::ParamsType,
-        verb: T.any(String, Symbol),
+        verb: String,
         path: String,
+        expiry: Integer,
+        nonce: String,
+        query: String,
+        body: String,
       ).returns(String)
     end
-    def sign(params:, verb:, path:)
+    def sign(verb:, path:, expiry:, nonce:, query: '', body: '')
       OpenSSL::HMAC.hexdigest(
         @algorithm,
         @secret,
-        "#{verb.to_s.upcase}#{path}#{ParamsEncoder.new(params).encode}",
+        Canonicalizer.canonical(
+          verb: verb,
+          path: path,
+          expiry: expiry,
+          nonce: nonce,
+          query: query,
+          body: body,
+        ),
       )
     end
 
     sig do
       params(
-        params: Types::ParamsType,
-        verb: T.any(String, Symbol),
-        path: String,
         signature: String,
+        verb: String,
+        path: String,
+        expiry: Integer,
+        nonce: String,
+        query: String,
+        body: String,
       ).returns(T::Boolean)
     end
-    def validate(params:, verb:, path:, signature:)
-      if OpenSSL.methods.include?(:fixed_length_secure_compare)
-        OpenSSL.fixed_length_secure_compare(
-          sign(params: params, verb: verb, path: path),
-          signature,
-        )
-      else
-        fallback_fixed_length_secure_compare(
-          sign(params: params, verb: verb, path: path),
-          signature,
-        )
-      end
+    def validate(signature:, verb:, path:, expiry:, nonce:, query: '', body: '')
+      OpenSSL.fixed_length_secure_compare(
+        sign(
+          verb: verb,
+          path: path,
+          expiry: expiry,
+          nonce: nonce,
+          query: query,
+          body: body,
+        ),
+        signature,
+      )
     rescue StandardError
       false
     end
-
-    private
-
-    # Ruby 2.7 openssl lib doesn't have fixed_length_secure_compare method
-    # File activesupport/lib/active_support/security_utils.rb, line 11
-    # With sorbet fix
-    sig { params(str_a: String, str_b: String).returns(T::Boolean) }
-    def fallback_fixed_length_secure_compare(str_a, str_b)
-      return false unless str_a.bytesize == str_b.bytesize
-
-      l = str_a.unpack "C#{str_a.bytesize}"
-
-      res = 0
-      str_b.each_byte { |byte| res |= byte ^ l.shift.to_i }
-      res == 0
-    end
   end
 end

data/lib/m2m_keygen/types/params_type.rb

@@ -3,23 +3,13 @@ module M2mKeygen
   module Types
     extend T::Sig
 
-    ParamsType =
-      T.type_alias do
-        T.nilable(T::Hash[T.any(String, Symbol), T.nilable(ParamsValueType)])
-      end
-
-    ParamsHashNotNilType =
-      T.type_alias { T::Hash[T.any(String, Symbol), ParamsValueType] }
+    ParamsScalarType =
+      T.type_alias { T.any(String, Symbol, Integer, Float, T::Boolean) }
 
     ParamsValueType =
-      T.type_alias do
-        T.any(
-          Integer,
-          String,
-          Symbol,
-          T::Array[T.untyped],
-          T::Hash[T.untyped, T.untyped],
-        )
-      end
+      T.type_alias { T.any(ParamsScalarType, T::Array[ParamsScalarType]) }
+
+    ParamsType =
+      T.type_alias { T::Hash[T.any(String, Symbol), ParamsValueType] }
   end
 end

data/lib/m2m_keygen/version.rb

@@ -3,5 +3,5 @@
 
 module M2mKeygen
   # Gem version
-  VERSION = '0.4.7'
+  VERSION = '0.5.0'
 end

data/lib/m2m_keygen.rb

@@ -11,4 +11,10 @@ module M2mKeygen
   # Standard error for the gem
   class Error < StandardError
   end
+
+  # Raised when an input cannot be turned into the canonical signing string
+  # (e.g. an unsupported value type). Surfaces loudly on the signer side; the
+  # verifier turns it into a `false` result.
+  class CanonicalizationError < Error
+  end
 end

data/m2m_keygen.gemspec

@@ -11,19 +11,17 @@ Gem::Specification.new do |spec|
   spec.summary = 'Secure M2M key generator'
   spec.description =
     'Secure M2M key generator for Ruby. Generates secure keys for M2M communication in REST APIs.'
-  spec.homepage = 'https://github.com/Billcorporate/m2m_keygen_ruby'
+  spec.homepage = 'https://github.com/zaratan/m2m_keygen_ruby'
   spec.license = 'MIT'
-  spec.required_ruby_version = '>= 2.7.0'
+  spec.required_ruby_version = '>= 3.3.0'
 
-  spec.metadata['homepage_uri'] = spec.homepage
-  spec.metadata['source_code_uri'] = spec.homepage
-  spec.metadata[
-    'changelog_uri'
-  ] = 'https://github.com/Billcorporate/m2m_keygen_ruby/blob/main/CHANGELOG.md'
-  spec.metadata[
-    'documentation_uri'
-  ] = 'https://billcorporate.github.io/m2m_keygen_ruby'
-  spec.metadata = { 'rubygems_mfa_required' => 'true' }
+  spec.metadata = {
+    'homepage_uri' => spec.homepage,
+    'source_code_uri' => spec.homepage,
+    'changelog_uri' => "#{spec.homepage}/blob/main/CHANGELOG.md",
+    'bug_tracker_uri' => "#{spec.homepage}/issues",
+    'rubygems_mfa_required' => 'true',
+  }
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
@@ -41,7 +39,7 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'rack'
-  spec.add_dependency 'sorbet-runtime'
-  spec.add_dependency 'zeitwerk', '>= 2.6'
+  spec.add_dependency 'rack', '>= 2.2', '< 4.0'
+  spec.add_dependency 'sorbet-runtime', '>= 0.5'
+  spec.add_dependency 'zeitwerk', '>= 2.6', '< 3.0'
 end

data/sorbet/config

@@ -3,3 +3,4 @@
 --ignore=node_modules
 --ignore=tmp
 --ignore=vendor
+--ignore=examples

data/sorbet/rbi/gems/.gitattributes

@@ -0,0 +1 @@
+**/*.rbi linguist-generated=true