Enhance HMAC authentication plugin to support customizable structured header parsing

Author: GrantBirki

docs/auth_plugins.md

@@ -90,6 +90,7 @@ The format of the signature header content. Use "structured" for headers contain
 
 **Default:** `simple`  
 **Valid values:**
+
 - `simple` - Standard single-value headers like "sha256=abc123..." or "abc123..."
 - `structured` - Comma-separated key-value pairs like "t=1663781880,v1=abc123..."
 

lib/hooks/core/config_validator.rb

@@ -45,6 +45,11 @@ class ValidationError < StandardError; end
           optional(:format).filled(:string)
           optional(:version_prefix).filled(:string)
           optional(:payload_template).filled(:string)
+          optional(:header_format).filled(:string)
+          optional(:signature_key).filled(:string)
+          optional(:timestamp_key).filled(:string)
+          optional(:structured_header_separator).filled(:string)
+          optional(:key_value_separator).filled(:string)
         end
 
         optional(:opts).hash

lib/hooks/plugins/auth/hmac.rb

@@ -92,6 +92,8 @@ class HMAC < Base
         # @option config [String] :header_format ('simple') Header format: 'simple' or 'structured'
         # @option config [String] :signature_key ('v1') Key for signature in structured headers
         # @option config [String] :timestamp_key ('t') Key for timestamp in structured headers
+        # @option config [String] :structured_header_separator (',') Separator for structured headers
+        # @option config [String] :key_value_separator ('=') Separator for key-value pairs in structured headers
         # @return [Boolean] true if signature is valid, false otherwise
         # @raise [StandardError] Rescued internally, returns false on any error
         # @note This method is designed to be safe and will never raise exceptions
@@ -219,7 +221,9 @@ def self.build_config(config)
             payload_template: validator_config[:payload_template],
             header_format: validator_config[:header_format] || DEFAULT_CONFIG[:header_format],
             signature_key: validator_config[:signature_key] || "v1",
-            timestamp_key: validator_config[:timestamp_key] || "t"
+            timestamp_key: validator_config[:timestamp_key] || "t",
+            structured_header_separator: validator_config[:structured_header_separator] || ",",
+            key_value_separator: validator_config[:key_value_separator] || "="
           })
         end
 
@@ -378,11 +382,13 @@ def self.format_signature(hash, config)
         def self.parse_structured_header(header_value, config)
           signature_key = config[:signature_key]
           timestamp_key = config[:timestamp_key]
+          separator = config[:structured_header_separator]
+          key_value_separator = config[:key_value_separator]
 
           # Parse comma-separated key-value pairs
           pairs = {}
-          header_value.split(",").each do |pair|
-            key, value = pair.split("=", 2)
+          header_value.split(separator).each do |pair|
+            key, value = pair.split(key_value_separator, 2)
             return nil if key.nil? || value.nil?
 
             pairs[key.strip] = value.strip

spec/unit/lib/hooks/plugins/auth/hmac_spec.rb

@@ -699,7 +699,7 @@ def test_iso_timestamp(iso_timestamp, should_be_valid)
 
   describe ".parse_structured_header" do
     it "parses valid structured header with timestamp and signature" do
-      config = { signature_key: "v1", timestamp_key: "t" }
+      config = { signature_key: "v1", timestamp_key: "t", key_value_separator: "=", structured_header_separator: "," }
       header_value = "t=1663781880,v1=0123456789abcdef"
 
       result = described_class.send(:parse_structured_header, header_value, config)
@@ -710,8 +710,20 @@ def test_iso_timestamp(iso_timestamp, should_be_valid)
       })
     end
 
+    it "parses valid structured header with timestamp and signature using different separators" do
+      config = { signature_key: "v1", timestamp_key: "t", key_value_separator: ":", structured_header_separator: "." }
+      header_value = "t:1663781880.v1:0123456789abcdef"
+
+      result = described_class.send(:parse_structured_header, header_value, config)
+
+      expect(result).to eq({
+        signature: "0123456789abcdef",
+        timestamp: "1663781880"
+      })
+    end
+
     it "parses structured header with only signature" do
-      config = { signature_key: "v1", timestamp_key: "t" }
+      config = { signature_key: "v1", timestamp_key: "t", key_value_separator: "=", structured_header_separator: "," }
       header_value = "v1=abcdef123456"
 
       result = described_class.send(:parse_structured_header, header_value, config)
@@ -722,7 +734,7 @@ def test_iso_timestamp(iso_timestamp, should_be_valid)
     end
 
     it "handles extra whitespace in key-value pairs" do
-      config = { signature_key: "v1", timestamp_key: "t" }
+      config = { signature_key: "v1", timestamp_key: "t", key_value_separator: "=", structured_header_separator: "," }
       header_value = "t = 1663781880 , v1 = 0123456789abcdef "
 
       result = described_class.send(:parse_structured_header, header_value, config)
@@ -734,7 +746,7 @@ def test_iso_timestamp(iso_timestamp, should_be_valid)
     end
 
     it "returns nil for malformed header (missing equals)" do
-      config = { signature_key: "v1", timestamp_key: "t" }
+      config = { signature_key: "v1", timestamp_key: "t", key_value_separator: "=", structured_header_separator: "," }
       header_value = "t,v1=abcdef"
 
       result = described_class.send(:parse_structured_header, header_value, config)
@@ -743,7 +755,7 @@ def test_iso_timestamp(iso_timestamp, should_be_valid)
     end
 
     it "returns nil when signature key is missing" do
-      config = { signature_key: "v1", timestamp_key: "t" }
+      config = { signature_key: "v1", timestamp_key: "t", key_value_separator: "=", structured_header_separator: "," }
       header_value = "t=1663781880,other=value"
 
       result = described_class.send(:parse_structured_header, header_value, config)
@@ -752,7 +764,7 @@ def test_iso_timestamp(iso_timestamp, should_be_valid)
     end
 
     it "returns nil when signature value is empty" do
-      config = { signature_key: "v1", timestamp_key: "t" }
+      config = { signature_key: "v1", timestamp_key: "t", key_value_separator: "=", structured_header_separator: "," }
       header_value = "t=1663781880,v1="
 
       result = described_class.send(:parse_structured_header, header_value, config)
@@ -761,7 +773,7 @@ def test_iso_timestamp(iso_timestamp, should_be_valid)
     end
 
     it "ignores extra key-value pairs not in config" do
-      config = { signature_key: "v1", timestamp_key: "t" }
+      config = { signature_key: "v1", timestamp_key: "t", key_value_separator: "=", structured_header_separator: "," }
       header_value = "t=1663781880,v1=abcdef,extra=ignored,another=also_ignored"
 
       result = described_class.send(:parse_structured_header, header_value, config)