patchwork-rb 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5b4e037d427bdd50e672f5f08ff93f8f4e129c42c998224162f7a6296988d2c
-  data.tar.gz: 59c03fbcbbfff9f6b6c27a006f3b37da9f8d995c3bb1f29d1168af2c619d6f17
+  metadata.gz: 374df53edc622840cc719b9bb341ae9ff6272fbb71cde1f71df2cb3a46819f09
+  data.tar.gz: 5d147937164ef2fdaf16d067f586c9bf83dc13fc8b8eed578bf5ce22a4495864
 SHA512:
-  metadata.gz: ee481c8625a8556c87f7924a4766e77588c0dbcd9a3529cb1041b74cafcc4610cdb1063f00ff607daac78eb1ef93861086926be81b2a897d029b47bfbc472a08
-  data.tar.gz: b0392464c771cfd3323ac2384cce4982f9bf75f62fbe79f7c03f578480b9ed1be0817a6f5e4ad89a7dd0c23161e5306d693fa878c5098121e366d9d56191ecb3
+  metadata.gz: dbf196787290106a3380d963f513f40ffba9327ce7c10b33ec307fa7eb4ff1b08182b7850b63b7d05be435fdeb3b427d385f5f2e23c69281350956a29ba40832
+  data.tar.gz: 95ee3747bab93b373d1a39ca115df1eab44a73fef3f0b49e7a2029a1d9df5418f4b7c0a23dc9197481dcf3333c9b928aeb65658639f390d74fd97a2177019521

data/README.md

@@ -232,7 +232,11 @@ Failure behaviour:
 
 ### What the signature does and doesn't cover
 
-The signature covers the method, the path and the raw body, as specified in the [Signing guide](https://docs.usepatchwork.co/guides/signing). **It does not cover the query string**, and Patchwork sends a GET tool's arguments as query parameters. So a GET tool's arguments are not integrity-protected. Anyone who can alter a request in flight (a TLS-terminating proxy, for example) can change them without breaking the signature. Give any tool whose arguments matter, such as ids, amounts or anything that writes, a `POST` binding, where the arguments travel in the signed body.
+A signature carries a label. `v1` covers the method, the path and the raw body. `v2` covers the same with the query string, exactly as sent. The scheme is specified in the [Signing guide](https://docs.usepatchwork.co/guides/signing).
+
+The gateway and the concern verify either label, and pass the query for you. If you verify with the primitives instead, pass `query:` — the raw query string, `request.query_string` in Rack and Rails. Leave it out and a `v2` value is checked against the bare path, which will not match.
+
+**A GET tool's arguments are still not protected yet.** Patchwork sends both labels while consumers upgrade, and `v1` does not cover the query, so altering a GET tool's arguments in flight still passes. That closes when Patchwork stops sending `v1`. Until then, give any tool whose arguments matter — ids, amounts, anything that writes — a `POST` binding, where the arguments travel in the signed body.
 
 The signed path is the one your app sees. If a proxy rewrites paths before your app does, mount the gateway where the original path is still intact.
 

data/lib/patchwork/gateway.rb

@@ -131,6 +131,7 @@ module Patchwork
         header: signature,
         method: method,
         path: request.path,
+        query: request.query_string,
         body: body
       )
       body

data/lib/patchwork/rails.rb

@@ -32,6 +32,7 @@ module Patchwork
           header: signature,
           method: signed,
           path: request.path,
+          query: request.query_string,
           body: request.raw_post
         )
 

data/lib/patchwork/signature.rb

@@ -6,39 +6,58 @@ module Patchwork
     SKEW = 300
     HEADER = "Patchwork-Signature".freeze
 
-    # Patchwork sends one v1 per live secret — two during a rotation. The cap
-    # stops an unauthenticated header of thousands of candidates from turning
-    # verification into a CPU amplifier.
+    # Patchwork sends one value per live secret per label — two during a
+    # rotation. The cap stops an unauthenticated header of thousands of
+    # candidates from turning verification into a CPU amplifier.
     MAX_SIGNATURES = 8
     MAX_HEADER_BYTES = 1024
     TIMESTAMP = /\A\d{1,12}\z/
     HEX_SHA256 = /\A\h{64}\z/
 
+    # v1 covers the method, the path and the body. v2 covers the same with the
+    # query string, as sent. Its payload carries a "v2." prefix, so a v1
+    # signature can never read as a v2 one even where the two cover the same
+    # bytes — a request with no query.
+    V1 = "v1".freeze
+    V2 = "v2".freeze
+    LABELS = [ V1, V2 ].freeze
+
     Parsed = Struct.new(:timestamp, :signatures, keyword_init: true)
 
-    def self.sign(secret:, timestamp:, method:, path:, body:)
+    def self.sign(secret:, timestamp:, method:, path:, body:, query: nil, label: V1)
       secret = usable!([ secret ]).first
-      mac(secret, payload(timestamp, method, path, digest(body)))
+      mac(secret, payload(label, timestamp, method, path, query, digest(body)))
     end
 
-    def self.header(secrets:, timestamp:, method:, path:, body:)
-      base = payload(timestamp, method, path, digest(body))
-      signatures = usable!(secrets).map { |secret| mac(secret, base) }
-      "t=#{timestamp},#{signatures.map { |signature| "v1=#{signature}" }.join(",")}"
+    def self.header(secrets:, timestamp:, method:, path:, body:, query: nil, labels: nil)
+      labels = (labels || (query.nil? ? [ V1 ] : LABELS)).map(&:to_s)
+      usable = usable!(secrets)
+
+      values = labels.flat_map do |label|
+        base = payload(label, timestamp, method, path, query, digest(body))
+        usable.map { |secret| "#{label}=#{mac(secret, base)}" }
+      end
+
+      "t=#{timestamp},#{values.join(",")}"
     end
 
     # Structural parse, with no secret and no body. Returns nil for anything
     # Patchwork would never send, so a malformed header is rejected before the
-    # body is read.
+    # body is read. Unknown labels are ignored rather than refused, so an older
+    # reader keeps working when a new one is added.
     def self.parse(header)
       value = header.to_s
       return nil if value.empty? || value.bytesize > MAX_HEADER_BYTES
 
       pairs = value.split(",").map { |pair| pair.strip.split("=", 2) }
       timestamps = pairs.select { |key, _| key == "t" }.map(&:last)
-      signatures = pairs.select { |key, _| key == "v1" }.map(&:last)
       return nil unless timestamps.size == 1 && TIMESTAMP.match?(timestamps.first.to_s)
-      return nil if signatures.empty? || signatures.size > MAX_SIGNATURES
+
+      signatures = LABELS.to_h do |label|
+        [ label, pairs.select { |key, _| key == label }.map(&:last) ]
+      end
+      return nil if signatures.values.all?(&:empty?)
+      return nil if signatures.values.any? { |values| values.size > MAX_SIGNATURES }
 
       Parsed.new(timestamp: Integer(timestamps.first, 10), signatures: signatures)
     end
@@ -47,24 +66,33 @@ module Patchwork
       (now - parsed.timestamp).abs <= skew
     end
 
-    def self.verify(secrets:, header:, method:, path:, body:, skew: SKEW, now: Time.now.to_i)
+    # Accepts either label. During the migration Patchwork sends both, so a
+    # reader that understands v2 must still accept v1 from a platform that has
+    # not started sending it.
+    def self.verify(secrets:, header:, method:, path:, body:, query: nil, skew: SKEW, now: Time.now.to_i)
       secrets = usable!(secrets)
       parsed = parse(header)
       return :bad if parsed.nil?
       return :stale unless fresh?(parsed, skew: skew, now: now)
 
-      # The body is hashed once and each secret MACs once, however many
-      # candidates the header carries.
-      base = payload(parsed.timestamp, method, path, digest(body))
-      expected = secrets.map { |secret| mac(secret, base) }
-      candidates = parsed.signatures.select { |candidate| HEX_SHA256.match?(candidate) }
+      # The body is hashed once however many candidates the header carries.
+      body_digest = digest(body)
+
+      matched = LABELS.any? do |label|
+        candidates = parsed.signatures.fetch(label, []).select { |value| HEX_SHA256.match?(value) }
+        next false if candidates.empty?
+
+        base = payload(label, parsed.timestamp, method, path, query, body_digest)
+        expected = secrets.map { |secret| mac(secret, base) }
+        expected.product(candidates).any? { |mine, theirs| secure_compare(mine, theirs) }
+      end
 
-      matched = expected.product(candidates).any? { |mine, theirs| secure_compare(mine, theirs) }
       matched ? :ok : :bad
     end
 
-    def self.verify!(secrets:, header:, method:, path:, body:, skew: SKEW, now: Time.now.to_i)
-      case verify(secrets: secrets, header: header, method: method, path: path, body: body, skew: skew, now: now)
+    def self.verify!(secrets:, header:, method:, path:, body:, query: nil, skew: SKEW, now: Time.now.to_i)
+      case verify(secrets: secrets, header: header, method: method, path: path, body: body,
+                  query: query, skew: skew, now: now)
       when :stale then raise StaleSignature, "signature timestamp outside the #{skew}s window"
       when :bad then raise InvalidSignature, "signature did not match"
       else true
@@ -76,8 +104,20 @@ module Patchwork
     end
     private_class_method :digest
 
-    def self.payload(timestamp, method, path, digest)
-      "#{timestamp}.#{method.to_s.upcase}.#{path}.#{digest}"
+    # The request target: the path as signed by v1, and the path with the query
+    # exactly as sent by v2. No query means no "?", because that is what goes
+    # on the wire.
+    def self.target(label, path, query)
+      return path.to_s if label == V1
+
+      value = query.to_s
+      value.empty? ? path.to_s : "#{path}?#{value}"
+    end
+    private_class_method :target
+
+    def self.payload(label, timestamp, method, path, query, digest)
+      base = "#{timestamp}.#{method.to_s.upcase}.#{target(label, path, query)}.#{digest}"
+      label == V2 ? "#{V2}.#{base}" : base
     end
     private_class_method :payload
 

data/lib/patchwork/version.rb

@@ -1,3 +1,3 @@
 module Patchwork
-  VERSION = "0.1.4".freeze
+  VERSION = "0.1.5".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: patchwork-rb
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - Chromablue Labs
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-05 00:00:00.000000000 Z
+date: 2026-10-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jwt