hook0-client 2.0.0

data/lib/hook0/runtime.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+require "date"
+require "json"
+require "time"
+
+module Hook0
+  # What the generated half of this gem reads and writes values through.
+  #
+  # Everything here is hand-written and never regenerated. It is the one seam between what the API
+  # declares — the classes, the problems and the methods the generator writes under `generated/` —
+  # and what it does not: how a JSON document is turned into a value, and what happens to a document
+  # that does not say what it was declared to say.
+  #
+  # Reading is deliberately strict. A member the document declares as a string and the API answered
+  # as a number stops the read with the name of that member, rather than yielding an object whose
+  # documentation lies about what it holds. Every failure of that kind is a {DecodeError}, so a
+  # caller has one thing to rescue whatever the shape of the answer was.
+  #
+  # A reader is anything answering to `call`. The scalar ones are constants, since there is exactly
+  # one of each; the ones built around another reader are methods, since there is one per shape.
+  module Runtime
+    # What the API answered is not what it declares it answers.
+    class DecodeError < StandardError; end
+
+    # Longest fragment of a response body an error message carries. Bodies are answered by a server
+    # this gem does not control, so they are cut at a fixed budget rather than echoed whole into
+    # whatever the caller logs.
+    MAX_PREVIEW_BYTES = 256
+
+    # Largest JSON document read out of a response body, in bytes. The transport caps what it reads
+    # off a socket; this caps what is handed to the parser whichever way the bytes arrived.
+    MAX_PAYLOAD_BYTES = 8 * 1024 * 1024
+
+    # Deepest a JSON document may nest before the parser gives up, which is what keeps a document
+    # that is nothing but brackets from growing the stack.
+    MAX_PAYLOAD_NESTING = 64
+
+    # The characters a path segment carries as themselves; everything else travels percent-encoded.
+    UNRESERVED = /[^A-Za-z0-9\-._~]/
+
+    # The shape a UUID is written in, whichever version it carries.
+    UUID_PATTERN = /\A\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\z/
+
+    # A string, refusing what merely spells like one.
+    TEXT = lambda { |value|
+      raise DecodeError, "expected a string, got #{value.class}" unless value.is_a?(String)
+
+      value
+    }
+
+    # A UUID, as the document spells one. It travels as the text the API answered, since that text
+    # is what has to go back out unchanged.
+    UUID = lambda { |value|
+      text = TEXT.call(value)
+      raise DecodeError, "expected a UUID, got `#{text}`" unless UUID_PATTERN.match?(text)
+
+      text
+    }
+
+    # A whole number. `true` is not one, here or on the wire.
+    INTEGER = lambda { |value|
+      raise DecodeError, "expected a whole number, got #{value.class}" unless value.is_a?(Integer)
+
+      value
+    }
+
+    # A number, whether the document wrote it with a fractional part or not.
+    FLOAT = lambda { |value|
+      raise DecodeError, "expected a number, got #{value.class}" unless value.is_a?(Integer) || value.is_a?(Float)
+
+      value.to_f
+    }
+
+    # A boolean, refusing the numbers that stand in for one elsewhere.
+    BOOLEAN = lambda { |value|
+      raise DecodeError, "expected a boolean, got #{value.class}" unless [true, false].include?(value)
+
+      value
+    }
+
+    # A moment, as RFC 3339 spells one.
+    DATE_TIME = lambda { |value|
+      text = TEXT.call(value)
+      begin
+        Time.iso8601(text)
+      rescue ArgumentError => e
+        raise DecodeError, "expected a date and a time, got `#{text}`: #{e.message}"
+      end
+    }
+
+    # A day, as ISO 8601 spells one.
+    DATE = lambda { |value|
+      text = TEXT.call(value)
+      begin
+        Date.iso8601(text)
+      rescue ArgumentError => e
+        # `Date::Error` is an `ArgumentError`, so rescuing the one covers the other.
+        raise DecodeError, "expected a date, got `#{text}`: #{e.message}"
+      end
+    }
+
+    # A value the document does not describe, which is therefore kept as it arrived.
+    JSON_VALUE = ->(value) { value }
+
+    # As much of a response body as a message may carry.
+    #
+    # @param payload [String]
+    # @return [String]
+    def self.preview(payload)
+      bytes = payload.to_s.b
+      kept = bytes.byteslice(0, MAX_PREVIEW_BYTES).force_encoding(Encoding::UTF_8)
+      rendered = kept.scrub("�")
+      bytes.bytesize > MAX_PREVIEW_BYTES ? "#{rendered}…" : rendered
+    end
+
+    # What to say about an answer the API document does not describe.
+    #
+    # @param status [Integer]
+    # @param payload [String]
+    # @return [String]
+    def self.unreadable(status, payload)
+      "the API answered #{status} with a body this client cannot read: #{preview(payload)}"
+    end
+
+    # What to say about a problem the API reported.
+    #
+    # @param status [Integer]
+    # @param problem [#to_h] the problem document the API answered
+    # @return [String]
+    def self.reported(status, problem)
+      "the API answered #{status}: #{problem.to_h}"
+    end
+
+    # The JSON document a response body carries.
+    #
+    # @param payload [String]
+    # @return [Object]
+    # @raise [DecodeError] when the body is larger than this gem reads, or is not JSON
+    def self.decode_payload(payload)
+      bytes = payload.to_s
+      if bytes.bytesize > MAX_PAYLOAD_BYTES
+        raise DecodeError, "the response is #{bytes.bytesize} bytes, above the #{MAX_PAYLOAD_BYTES} accepted"
+      end
+
+      begin
+        JSON.parse(bytes, max_nesting: MAX_PAYLOAD_NESTING)
+      rescue JSON::ParserError, EncodingError => e
+        raise DecodeError, "the response is not JSON: #{preview(bytes)} (#{e.message})"
+      end
+    end
+
+    # The members of an object the document declares, under the name it declares it with.
+    #
+    # @param value [Object]
+    # @param owner [String] what the document calls the object being read
+    # @return [Hash]
+    # @raise [DecodeError] when the API answered something that is not an object
+    def self.as_fields(value, owner)
+      raise DecodeError, "#{owner} is not a JSON object" unless value.is_a?(Hash)
+
+      value
+    end
+
+    # A member the document requires, which is therefore missing when it is absent.
+    #
+    # @param fields [Hash]
+    # @param key [String] the name the member travels under
+    # @param reader [#call]
+    # @return [Object]
+    # @raise [DecodeError]
+    def self.read(fields, key, reader)
+      raise DecodeError, "`#{key}` is required and was not answered" unless fields.key?(key)
+
+      named(key) { reader.call(fields[key]) }
+    end
+
+    # A member the document does not require, absent as readily as answered as null.
+    #
+    # @param fields [Hash]
+    # @param key [String] the name the member travels under
+    # @param reader [#call]
+    # @return [Object, nil]
+    # @raise [DecodeError]
+    def self.maybe(fields, key, reader)
+      return nil if fields[key].nil?
+
+      named(key) { reader.call(fields[key]) }
+    end
+
+    # Every item of an array, each one read the same way.
+    #
+    # @param reader [#call]
+    # @return [Proc]
+    def self.list(reader)
+      lambda { |value|
+        raise DecodeError, "expected an array, got #{value.class}" unless value.is_a?(Array)
+
+        value.map { |item| reader.call(item) }
+      }
+    end
+
+    # Every value of an object whose keys the document leaves open.
+    #
+    # @param reader [#call]
+    # @return [Proc]
+    def self.map(reader)
+      lambda { |value|
+        raise DecodeError, "expected an object, got #{value.class}" unless value.is_a?(Hash)
+
+        value.to_h { |key, item| [TEXT.call(key), reader.call(item)] }
+      }
+    end
+
+    # One of the values a closed list declares, refusing anything the list does not carry.
+    #
+    # @param declared [#member?] the module the generator wrote for that list
+    # @return [Proc]
+    def self.member_of(declared)
+      lambda { |value|
+        text = TEXT.call(value)
+        raise DecodeError, "`#{text}` is not one of the values #{declared} declares" unless declared.member?(text)
+
+        text
+      }
+    end
+
+    # A moment, written the way the API reads one.
+    #
+    # A moment carrying no fraction of a second is written without one, and one that does keeps
+    # every digit it has, so that what was read comes back out unchanged either way.
+    #
+    # @param moment [Time]
+    # @return [String]
+    def self.moment(moment)
+      moment.nsec.zero? ? moment.iso8601 : moment.iso8601(9)
+    end
+
+    # A day, written the way the API reads one.
+    #
+    # @param day [Date]
+    # @return [String]
+    def self.day(day)
+      day.iso8601
+    end
+
+    # Where a request lands, with each placeholder of the template filled in.
+    #
+    # @param template [String] the path as the document writes it, placeholders included
+    # @param filled [Hash{String => Object}] the value each placeholder carries
+    # @return [String]
+    def self.path(template, filled = {})
+      filled.reduce(template) do |written, (name, value)|
+        written.gsub("{#{name}}", path_segment(value))
+      end
+    end
+
+    # A value as one segment of a path, with nothing left in it that could name another one.
+    #
+    # @param value [Object]
+    # @return [String]
+    def self.path_segment(value)
+      written(value).b.gsub(UNRESERVED) { |byte| format("%%%02X", byte.ord) }
+    end
+
+    # What travels in the query string: everything the document requires, and everything it does not
+    # that the caller actually passed.
+    #
+    # @param required [Array<Array>] name and value pairs the operation always sends
+    # @param optional [Array<Array>] name and value pairs it sends only when they carry something
+    # @return [Array<Array<String>>]
+    def self.query(required, optional = [])
+      asked = required.map { |name, value| [name, written(value)] }
+      asked + optional.filter_map { |name, value| [name, written(value)] unless value.nil? }
+    end
+
+    # How a value travels in a request line, which is not always how Ruby prints it.
+    #
+    # @param value [Object]
+    # @return [String]
+    def self.written(value)
+      case value
+      when true then "true"
+      when false then "false"
+      when Time then moment(value)
+      when Date then day(value)
+      else value.to_s
+      end
+    end
+
+    # Reads a member, saying which member it was that could not be read.
+    def self.named(key)
+      yield
+    rescue DecodeError => e
+      raise DecodeError, "`#{key}`: #{e.message}"
+    end
+    private_class_method :named
+  end
+end

data/lib/hook0/signature.rb

@@ -0,0 +1,294 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+require_relative "errors"
+
+# Verifying that a webhook came from Hook0, and that nothing in it changed on the way.
+module Hook0
+  # A signature header, read into the pieces a verification needs.
+  #
+  # A signature names the moment it was signed and one or two message authentication codes over the
+  # body. The `v1` scheme also covers a list of request headers, so a receiver can tell apart two
+  # deliveries that carry the same body but not the same context; `v0` covers the body alone and is
+  # what an older sender still produces. When both are offered, `v1` is the one verified: accepting
+  # the weaker of two schemes on the strength of the sender offering it is how a downgrade works.
+  #
+  # Two things are refused before any code is computed. A header the signature says it covers but
+  # the request did not carry is refused outright, because signing over an absent value would let a
+  # sender drop a header and keep the signature valid. And a signature whose codes are not whole
+  # hexadecimal is refused rather than decoded as far as it goes: a decoder that stops at the first
+  # bad character compares a prefix, and a prefix of the right code is not the right code.
+  class Signature
+    # Longest signature header read. The header is written by whoever reached the endpoint, so its
+    # size is bounded before any of it is split, decoded or compared.
+    MAX_SIGNATURE_BYTES = 8 * 1024
+
+    # Most `key=value` parts one signature header is split into.
+    MAX_SIGNATURE_PARTS = 32
+
+    # Most header names one signature covers.
+    MAX_COVERED_HEADERS = 64
+
+    # Furthest from the epoch, in either direction, a signature's moment may sit. Ruby's integers
+    # grow without bound, so a header carrying thousands of digits would otherwise reach the
+    # arithmetic that holds it against the current time and cost more than reading it did.
+    MAX_TIMESTAMP = 10**12
+
+    # What separates one part of the signature header from the next.
+    PART_SEPARATOR = ","
+
+    # What separates the name of a part from its value. Only the first one counts: a value may hold
+    # further ones, and splitting on all of them would silently drop everything past the second.
+    PART_ASSIGNATOR = "="
+
+    # What separates two header names inside the `h` part, and what they are joined back with.
+    HEADER_NAME_SEPARATOR = " "
+
+    # What separates the pieces of the message a code is computed over.
+    MESSAGE_SEPARATOR = "."
+
+    # Part naming the moment the delivery was signed, in whole seconds since the Unix epoch.
+    TIMESTAMP_PART = "t"
+
+    # Part carrying the code covering the body alone.
+    BODY_SCHEME_PART = "v0"
+
+    # Part carrying the code covering the covered headers and the body.
+    HEADERS_SCHEME_PART = "v1"
+
+    # Part listing the headers the `v1` code covers, in the order it covers them.
+    COVERED_HEADERS_PART = "h"
+
+    # What a whole number of seconds reads as. `Integer()` would accept `1_0` as ten, which is a
+    # spelling no sender produces and no receiver should invent a meaning for.
+    WHOLE_SECONDS = /\A-?\d+\z/
+
+    # What a code reads as: whole pairs of hexadecimal digits, and nothing else.
+    WHOLE_HEXADECIMAL = /\A(?:\h\h)+\z/
+
+    # What a header name is written with, as RFC 9110 spells a token.
+    HEADER_NAME = /\A[A-Za-z0-9!\#$%&'*+\-.^_`|~]+\z/
+
+    # What the codes are computed with.
+    DIGEST = "SHA256"
+
+    # @return [Integer] the moment the delivery was signed, in whole seconds since the epoch
+    attr_reader :timestamp
+
+    # @return [Array<String>] the headers the stronger scheme covers, lowercased and in order
+    attr_reader :covered_headers
+
+    # @return [String, nil] the `v0` code, decoded
+    attr_reader :body_code
+
+    # @return [String, nil] the `v1` code, decoded
+    attr_reader :headers_code
+
+    # @param timestamp [Integer]
+    # @param covered_headers [Array<String>]
+    # @param body_code [String, nil]
+    # @param headers_code [String, nil]
+    def initialize(timestamp, covered_headers, body_code, headers_code)
+      @timestamp = timestamp
+      @covered_headers = covered_headers
+      @body_code = body_code
+      @headers_code = headers_code
+      freeze
+    end
+
+    # Reads a signature header, refusing anything it cannot read whole.
+    #
+    # @param signature [String] the value of the `X-Hook0-Signature` header
+    # @return [Signature]
+    # @raise [ClientError] for every way a header can fail to be one
+    def self.parse(signature)
+      raise ClientError, "the signature is #{signature.class}, not a header value" unless signature.is_a?(String)
+
+      if signature.length > MAX_SIGNATURE_BYTES
+        raise ClientError,
+              "the signature is #{signature.length} characters long, above the #{MAX_SIGNATURE_BYTES} accepted"
+      end
+
+      read = parts_of(signature)
+      raise ClientError, "the signature carries neither a timestamp nor a code" if read.size < 2
+
+      body_code = code_of(read, BODY_SCHEME_PART)
+      headers_code = code_of(read, HEADERS_SCHEME_PART)
+      if body_code.nil? && headers_code.nil?
+        raise ClientError, "the signature carries neither a `#{BODY_SCHEME_PART}` nor a `#{HEADERS_SCHEME_PART}` code"
+      end
+
+      new(timestamp_of(read), covered_headers_of(read), body_code, headers_code)
+    end
+
+    # The `key=value` parts of a header, split on the first assignator of each and trimmed.
+    def self.parts_of(signature)
+      parts = signature.split(PART_SEPARATOR, -1)
+      if parts.size > MAX_SIGNATURE_PARTS
+        raise ClientError, "the signature carries more than the #{MAX_SIGNATURE_PARTS} parts accepted"
+      end
+
+      parts.each_with_object({}) do |part, read|
+        name, assigned, value = part.partition(PART_ASSIGNATOR)
+        read[name.strip] = value.strip unless assigned.empty?
+      end
+    end
+    private_class_method :parts_of
+
+    # The moment the signature names, which it is not a signature without.
+    def self.timestamp_of(read)
+      written = read[TIMESTAMP_PART]
+      raise ClientError, "the signature carries no `#{TIMESTAMP_PART}` part" if written.nil?
+      raise ClientError, "`#{written}` is not a number of seconds" unless WHOLE_SECONDS.match?(written)
+
+      seconds = Integer(written, 10)
+      if seconds.abs > MAX_TIMESTAMP
+        raise ClientError, "the signature's moment is further than #{MAX_TIMESTAMP} seconds from the epoch"
+      end
+
+      seconds
+    end
+    private_class_method :timestamp_of
+
+    # One of the codes a signature offers, decoded whole or not at all.
+    def self.code_of(read, part)
+      written = read[part]
+      return nil if written.nil?
+      raise ClientError, "the `#{part}` code is not hexadecimal" unless WHOLE_HEXADECIMAL.match?(written)
+
+      [written].pack("H*")
+    end
+    private_class_method :code_of
+
+    # The headers the stronger scheme covers, in the order it covers them.
+    def self.covered_headers_of(read)
+      written = read[COVERED_HEADERS_PART]
+      return [] if written.nil? || written.empty?
+
+      names = written.split(HEADER_NAME_SEPARATOR, -1)
+      if names.size > MAX_COVERED_HEADERS
+        raise ClientError, "the signature covers more than the #{MAX_COVERED_HEADERS} headers accepted"
+      end
+
+      names.map do |name|
+        raise ClientError, "`#{name}` is not a header name" unless HEADER_NAME.match?(name)
+
+        name.downcase
+      end
+    end
+    private_class_method :covered_headers_of
+
+    # Whether the code this signature carries is the one the secret produces.
+    #
+    # The stronger scheme wins when both are offered, and the comparison is made in constant time:
+    # one that gave up at the first differing byte would say, by how long it took, how much of a
+    # guess was right.
+    #
+    # @param payload [String] the raw body of the webhook request
+    # @param covered_values [Array<String>] the values of the covered headers, in order
+    # @param subscription_secret [String]
+    # @return [Boolean]
+    def matches?(payload, covered_values, subscription_secret)
+      code = OpenSSL::HMAC.new(subscription_secret.to_s, DIGEST)
+      code << @timestamp.to_s
+      code << MESSAGE_SEPARATOR
+
+      unless @headers_code.nil?
+        code << @covered_headers.join(HEADER_NAME_SEPARATOR)
+        code << MESSAGE_SEPARATOR
+        code << covered_values.join(MESSAGE_SEPARATOR)
+        code << MESSAGE_SEPARATOR
+        code << payload
+        return Signature.same_code?(code.digest, @headers_code)
+      end
+
+      # A signature carrying neither code is refused while it is being read, so what is left here
+      # is the body-only scheme.
+      code << payload
+      Signature.same_code?(code.digest, @body_code)
+    end
+
+    # Whether two codes are the same, without saying by how long it took how much of one was right.
+    #
+    # @param left [String]
+    # @param right [String]
+    # @return [Boolean]
+    def self.same_code?(left, right)
+      left.bytesize == right.bytesize && OpenSSL.fixed_length_secure_compare(left, right)
+    end
+  end
+
+  # Verifies a webhook against a moment the caller names.
+  #
+  # The clock window is bilateral. A moment too far in the future is refused exactly like one too
+  # far in the past, so the window a given delivery is accepted in stays the width the caller asked
+  # for, whichever way a clock drifted.
+  #
+  # @param signature [String] the value of the `X-Hook0-Signature` header
+  # @param payload [String] the raw body of the webhook request
+  # @param headers [Hash, Array<Array>] the headers of the webhook request
+  # @param subscription_secret [String] the signing secret of the subscription it was delivered for
+  # @param tolerance [Numeric] how far, in seconds and in either direction, the moment the signature
+  #   names may sit from `current_time`. Five minutes is a reasonable trade-off between tolerating
+  #   clock drift and bounding how long a captured delivery can be replayed.
+  # @param current_time [Time] what to hold the signature's moment against
+  # @return [void]
+  # @raise [ClientError] for every reason a webhook may be refused
+  def self.verify_webhook_signature_with_current_time(
+    signature, payload, headers, subscription_secret, tolerance, current_time
+  )
+    parsed = Signature.parse(signature)
+
+    delivered = delivered_headers(headers)
+    covered_values = parsed.covered_headers.map do |name|
+      raise ClientError, "the `#{name}` header the signature covers was not delivered" unless delivered.key?(name)
+
+      delivered[name]
+    end
+
+    unless parsed.matches?(payload.to_s, covered_values, subscription_secret)
+      raise ClientError, "the signature does not match what the subscription secret produces"
+    end
+
+    drift = current_time.to_f - parsed.timestamp
+    if drift.abs > tolerance
+      raise ClientError,
+            "the signature was made #{format("%.0f", drift)} seconds from now, outside the #{tolerance} accepted"
+    end
+
+    nil
+  end
+
+  # Verifies a webhook against the current moment.
+  #
+  # See {verify_webhook_signature_with_current_time} for what each argument is.
+  #
+  # @return [void]
+  # @raise [ClientError]
+  def self.verify_webhook_signature(signature, payload, headers, subscription_secret, tolerance)
+    verify_webhook_signature_with_current_time(
+      signature, payload, headers, subscription_secret, tolerance, Time.now
+    )
+  end
+
+  # The headers of the request, under the names a signature refers to them by.
+  #
+  # A later value wins over an earlier one under the same name, which is what a hash built by the
+  # caller would have done.
+  def self.delivered_headers(headers)
+    headers.to_a.each_with_object({}) do |(name, value), delivered|
+      delivered[header_text(name).downcase] = header_text(value)
+    end
+  end
+  private_class_method :delivered_headers
+
+  # A header name or value as text, whichever way the caller holds it.
+  def self.header_text(value)
+    raise ClientError, "a header is #{value.class}, not a header value" unless value.is_a?(String)
+    raise ClientError, "a header is not UTF-8" unless value.dup.force_encoding(Encoding::UTF_8).valid_encoding?
+
+    value
+  end
+  private_class_method :header_text
+end