Add support for structured signature headers (Tailscale-style)

Co-authored-by: GrantBirki <[email protected]>

Author: Copilot

lib/hooks/plugins/auth/hmac.rb

@@ -42,7 +42,8 @@ class HMAC < Base
           format: "algorithm=signature",  # Format: algorithm=hash
           header: "X-Signature",         # Default header containing the signature
           timestamp_tolerance: 300,       # 5 minutes tolerance for timestamp validation
-          version_prefix: "v0"           # Default version prefix for versioned signatures
+          version_prefix: "v0",          # Default version prefix for versioned signatures
+          header_format: "simple"        # Header format: "simple" or "structured"
         }.freeze
 
         # Mapping of signature format strings to internal format symbols
@@ -75,6 +76,9 @@ class HMAC < Base
         # @option config [String] :format ('algorithm=signature') Signature format
         # @option config [String] :version_prefix ('v0') Version prefix for versioned signatures
         # @option config [String] :payload_template Template for payload construction
+        # @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
         # @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
@@ -121,7 +125,28 @@ def self.valid?(payload:, headers:, config:)
 
           # Now we can safely normalize headers for the rest of the validation
           normalized_headers = normalize_headers(headers)
-          provided_signature = normalized_headers[signature_header.downcase]
+
+          # Handle structured headers (e.g., Tailscale format: "t=123,v1=abc")
+          if validator_config[:header_format] == "structured"
+            parsed_signature_data = parse_structured_header(raw_signature, validator_config)
+            if parsed_signature_data.nil?
+              log.warn("Auth::HMAC validation failed: Could not parse structured signature header")
+              return false
+            end
+
+            provided_signature = parsed_signature_data[:signature]
+
+            # For structured headers, timestamp comes from the signature header itself
+            if parsed_signature_data[:timestamp]
+              normalized_headers = normalized_headers.merge(
+                "extracted_timestamp" => parsed_signature_data[:timestamp]
+              )
+              # Override timestamp_header to use our extracted timestamp
+              validator_config = validator_config.merge(timestamp_header: "extracted_timestamp")
+            end
+          else
+            provided_signature = normalized_headers[signature_header.downcase]
+          end
 
           # Validate timestamp if required (for services that include timestamp validation)
           if validator_config[:timestamp_header]
@@ -176,7 +201,10 @@ def self.build_config(config)
             algorithm: algorithm,
             format: validator_config[:format] || DEFAULT_CONFIG[:format],
             version_prefix: validator_config[:version_prefix] || DEFAULT_CONFIG[:version_prefix],
-            payload_template: validator_config[:payload_template]
+            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"
           })
         end
 
@@ -321,6 +349,42 @@ def self.format_signature(hash, config)
             "#{config[:algorithm]}=#{hash}"
           end
         end
+
+        # Parse structured signature header containing comma-separated key-value pairs
+        #
+        # Parses signature headers like "t=1663781880,v1=0123456789abcdef..." used by
+        # providers like Tailscale that include multiple values in a single header.
+        #
+        # @param header_value [String] Raw signature header value
+        # @param config [Hash<Symbol, Object>] Validator configuration
+        # @return [Hash<Symbol, String>, nil] Parsed data with :signature and :timestamp keys, or nil if parsing fails
+        # @note Returns nil if the header format is invalid or required keys are missing
+        # @api private
+        def self.parse_structured_header(header_value, config)
+          signature_key = config[:signature_key]
+          timestamp_key = config[:timestamp_key]
+
+          # Parse comma-separated key-value pairs
+          pairs = {}
+          header_value.split(",").each do |pair|
+            key, value = pair.split("=", 2)
+            return nil if key.nil? || value.nil?
+
+            pairs[key.strip] = value.strip
+          end
+
+          # Extract required signature
+          signature = pairs[signature_key]
+          return nil if signature.nil? || signature.empty?
+
+          result = { signature: signature }
+
+          # Extract optional timestamp
+          timestamp = pairs[timestamp_key]
+          result[:timestamp] = timestamp if timestamp && !timestamp.empty?
+
+          result
+        end
       end
     end
   end

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

@@ -696,4 +696,162 @@ def test_iso_timestamp(iso_timestamp, should_be_valid)
       expect(Hooks::Log.instance).to have_received(:warn).with("Auth::HMAC validation failed: Signature mismatch")
     end
   end
+
+  describe ".parse_structured_header" do
+    it "parses valid structured header with timestamp and signature" do
+      config = { signature_key: "v1", timestamp_key: "t" }
+      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" }
+      header_value = "v1=abcdef123456"
+
+      result = described_class.send(:parse_structured_header, header_value, config)
+
+      expect(result).to eq({
+        signature: "abcdef123456"
+      })
+    end
+
+    it "handles extra whitespace in key-value pairs" do
+      config = { signature_key: "v1", timestamp_key: "t" }
+      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 "returns nil for malformed header (missing equals)" do
+      config = { signature_key: "v1", timestamp_key: "t" }
+      header_value = "t,v1=abcdef"
+
+      result = described_class.send(:parse_structured_header, header_value, config)
+
+      expect(result).to be_nil
+    end
+
+    it "returns nil when signature key is missing" do
+      config = { signature_key: "v1", timestamp_key: "t" }
+      header_value = "t=1663781880,other=value"
+
+      result = described_class.send(:parse_structured_header, header_value, config)
+
+      expect(result).to be_nil
+    end
+
+    it "returns nil when signature value is empty" do
+      config = { signature_key: "v1", timestamp_key: "t" }
+      header_value = "t=1663781880,v1="
+
+      result = described_class.send(:parse_structured_header, header_value, config)
+
+      expect(result).to be_nil
+    end
+
+    it "ignores extra key-value pairs not in config" do
+      config = { signature_key: "v1", timestamp_key: "t" }
+      header_value = "t=1663781880,v1=abcdef,extra=ignored,another=also_ignored"
+
+      result = described_class.send(:parse_structured_header, header_value, config)
+
+      expect(result).to eq({
+        signature: "abcdef",
+        timestamp: "1663781880"
+      })
+    end
+  end
+
+  describe "structured header format validation" do
+    let(:secret) { "supersecret" }
+    let(:payload) { '{"event":"test"}' }
+    let(:timestamp) { Time.now.to_i.to_s }
+
+    def create_tailscale_signature(payload, timestamp, secret)
+      signing_payload = "#{timestamp}.#{payload}"
+      signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), secret, signing_payload)
+      "t=#{timestamp},v1=#{signature}"
+    end
+
+    context "with structured header format" do
+      let(:config) do
+        {
+          auth: {
+            header: "Tailscale-Webhook-Signature",
+            algorithm: "sha256",
+            format: "signature_only",
+            header_format: "structured",
+            signature_key: "v1",
+            timestamp_key: "t",
+            payload_template: "{timestamp}.{body}",
+            timestamp_tolerance: 300,
+            secret_env_key: "HMAC_TEST_SECRET"
+          }
+        }
+      end
+
+      it "validates Tailscale-style structured signatures" do
+        signature_header_value = create_tailscale_signature(payload, timestamp, secret)
+        headers = { "Tailscale-Webhook-Signature" => signature_header_value }
+
+        expect(valid_with(payload:, headers:, config:)).to be true
+      end
+
+      it "fails with invalid structured signature" do
+        headers = { "Tailscale-Webhook-Signature" => "t=#{timestamp},v1=invalid_signature" }
+
+        expect(valid_with(payload:, headers:, config:)).to be false
+      end
+
+      it "fails with malformed structured header" do
+        headers = { "Tailscale-Webhook-Signature" => "malformed_header" }
+
+        expect(valid_with(payload:, headers:, config:)).to be false
+      end
+
+      it "fails when signature key is missing from structured header" do
+        headers = { "Tailscale-Webhook-Signature" => "t=#{timestamp},other=value" }
+
+        expect(valid_with(payload:, headers:, config:)).to be false
+      end
+
+      it "validates with timestamp tolerance" do
+        old_timestamp = (Time.now.to_i - 250).to_s  # Within 300s tolerance
+        signature_header_value = create_tailscale_signature(payload, old_timestamp, secret)
+        headers = { "Tailscale-Webhook-Signature" => signature_header_value }
+
+        expect(valid_with(payload:, headers:, config:)).to be true
+      end
+
+      it "fails when timestamp is too old" do
+        old_timestamp = (Time.now.to_i - 400).to_s  # Beyond 300s tolerance
+        signature_header_value = create_tailscale_signature(payload, old_timestamp, secret)
+        headers = { "Tailscale-Webhook-Signature" => signature_header_value }
+
+        expect(valid_with(payload:, headers:, config:)).to be false
+      end
+
+      it "works without timestamp when not required" do
+        config_no_timestamp = config[:auth].dup
+        config_no_timestamp.delete(:payload_template)
+        config_with_no_timestamp = { auth: config_no_timestamp }
+
+        signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), secret, payload)
+        headers = { "Tailscale-Webhook-Signature" => "v1=#{signature}" }
+
+        expect(valid_with(payload:, headers:, config: config_with_no_timestamp)).to be true
+      end
+    end
+  end
 end