findxpand 0.1.0

data/lib/findxpand/signature.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+# Is this manifest push signed by the holder of the token, and is it recent?
+#
+# A bearer token proves who sent a push and says nothing about what was in it.
+# Anything holding the token — a logging proxy, a mirrored request, an old CI
+# secret — could replay a captured manifest forever, or swap the body inside one,
+# and a manifest is production content. So every push carries an HMAC-SHA256 over
+# `timestamp.body`, with the timestamp inside the digest so a captured request
+# expires rather than working indefinitely.
+#
+# The scheme is `engine.publish.notify`'s, unchanged and deliberately so: we
+# already ship three verified implementations of it, and a second scheme here
+# would be a second thing to get right. The secret is the middleware token rather
+# than a new credential — whoever holds the token can already push, so a separate
+# secret would add distribution and rotation for no gain.
+#
+# §3 rule 7: this is a write, so every branch here fails closed. The only
+# question the module answers is *why* a push is unacceptable.
+#
+# Frozen string literals: on. The one accumulator is `String#+`, never `<<`.
+
+require 'openssl'
+
+module Findxpand
+  module Signature
+    # Mirrors `engine.fix.origin.SIGNATURE_HEADER` and `TIMESTAMP_HEADER`.
+    SIGNATURE_HEADER = 'x-findxpand-signature'
+    TIMESTAMP_HEADER = 'x-findxpand-timestamp'
+
+    # The same names as Rack presents them. A Rack server upcases a header,
+    # replaces the hyphens and prefixes `HTTP_`, so these are the keys actually
+    # read out of `env` — written out rather than computed at each call site so
+    # that a rename cannot leave one of the two spellings behind.
+    SIGNATURE_ENV = 'HTTP_X_FINDXPAND_SIGNATURE'
+    TIMESTAMP_ENV = 'HTTP_X_FINDXPAND_TIMESTAMP'
+
+    # How far out of date a push may be, in seconds. Mirrors
+    # `engine.fix.origin.TOLERANCE_S` and `sdk/next/src/webhook.ts`.
+    TOLERANCE_S = 300
+
+    # The reason this push is not acceptable, or `''` when it is.
+    #
+    # A reason rather than a boolean: "the signature does not match" and "the
+    # timestamp is forty minutes old" send an operator to completely different
+    # places — a wrong token versus a clock that has drifted — and a bare `false`
+    # makes them guess.
+    def self.problem(signature, timestamp, body, token, now: nil)
+      signature = signature.to_s
+      timestamp = timestamp.to_s
+      return 'unsigned manifest push' if signature.empty? || timestamp.empty?
+
+      begin
+        # `Float()`, never `String#to_f`. `'nonsense'.to_f` is `0.0` and raises
+        # nothing, so a garbled header would be read as the epoch and rejected
+        # as 1.7 billion seconds stale — a true refusal reported with a reason
+        # that sends an operator to look at a clock that is perfectly correct.
+        # `Float()` raises on anything that is not a number, which is the
+        # distinction this method exists to make.
+        age = ((now || Time.now.to_f) - Float(timestamp)).abs
+      rescue ArgumentError, TypeError
+        return 'manifest push carries an unreadable timestamp'
+      end
+      if age > TOLERANCE_S
+        return "manifest push is #{age.round}s out of date - replay, or a clock that has drifted"
+      end
+
+      unless secure_compare(signature, expected(timestamp, body, token))
+        return 'manifest signature does not match'
+      end
+
+      ''
+    end
+
+    # The digest we should have been sent, over the raw bytes.
+    #
+    # **Binary throughout, and that is not a detail.** `"#{timestamp}.#{body}"`
+    # is the obvious line and it raises `Encoding::CompatibilityError` the first
+    # time a manifest carries a non-ASCII byte: `rack.input` hands back an
+    # ASCII-8BIT String, the literal in the interpolation is UTF-8, and Ruby
+    # refuses to join the two once either holds a byte above 0x7F. Our market is
+    # Arabic (§14), so the first manifest with an Arabic title in it is the first
+    # push this would have rejected — with a 500 out of the middleware rather
+    # than a reason, since the raise happens before any verdict is reached.
+    # `String#b` gives a binary copy of each half and the concatenation is then
+    # always legal.
+    #
+    # Over the raw bytes, never over a re-serialised parse: re-encoding the JSON
+    # to check it would reorder keys and reject every legitimate push.
+    def self.expected(timestamp, body, token)
+      signed = "#{timestamp}.".b + body.to_s.b
+      OpenSSL::HMAC.hexdigest('SHA256', token.to_s, signed)
+    end
+
+    # Constant-time comparison of two digests.
+    #
+    # `==` on Strings returns as soon as two bytes differ, so the time it takes
+    # is a function of how many leading characters an attacker guessed right —
+    # which is enough, over enough requests, to recover a signature byte by byte
+    # without ever knowing the token. The endpoint being compared against is a
+    # manifest push, so the prize is arbitrary content on the customer's pages.
+    #
+    # `OpenSSL.secure_compare` is preferred because it is the audited C
+    # implementation, and it hashes both inputs before comparing so the lengths
+    # cannot leak either. The fallback is the same construction in Ruby, for a
+    # build whose bundled openssl predates it: SHA-256 both sides so the loop
+    # length is fixed, then OR the XOR of every byte pair and test once at the
+    # end. `Rack::Utils.secure_compare` would do as well and is not used, because
+    # this gem declares no runtime dependency on Rack — it is a Rack middleware
+    # that needs nothing of Rack but the calling convention.
+    def self.secure_compare(given, expected)
+      given = given.to_s
+      expected = expected.to_s
+      return OpenSSL.secure_compare(given, expected) if OpenSSL.respond_to?(:secure_compare)
+
+      # `OpenSSL::Digest.digest(name, data)` rather than the
+      # `OpenSSL::Digest::SHA256` constant, which successive openssl releases
+      # have deprecated and un-deprecated. This branch exists for an old build;
+      # writing it against the newest spelling of the API would defeat it.
+      left = OpenSSL::Digest.digest('SHA256', given)
+      right = OpenSSL::Digest.digest('SHA256', expected)
+      difference = 0
+      left.bytes.each_with_index { |byte, index| difference |= byte ^ right.getbyte(index).to_i }
+      difference.zero?
+    end
+  end
+end