truelayer-signing 0.1.0

data/examples/webhook-server/main.rb

@@ -0,0 +1,98 @@
+require "socket"
+require "truelayer-signing"
+
+class TrueLayerSigningExamples
+  # Note: the webhook path can be whatever is configured for your application.
+  # Here a unique path is used, matching the example signature in the README.
+  WEBHOOK_PATH = "/hook/d7a2c49d-110a-4ed2-a07d-8fdb3ea6424b".freeze
+  PUBLIC_KEY_PEM = "-----BEGIN PUBLIC KEY-----\n" +
+    "MIGbMBAGByqGSM49AgEGBSuBBAAjA4GGAAQBJ6ET9XeVCyMy+yOetZaNNCXPhwr5\n" +
+    "BlyDDg1CLmyNM5SvqOs8RveL6dYl4lpPur4xrPQl04ggYlVd9wnHkZnp3jcBlXw8\n" +
+    "Lc5phyYF1q2/QV/5wp2WHIhKDqUiXC0TvlE8d7MdTAN9yolcwrh6aWZ3kesTMZif\n" +
+    "BgItyT6PXUab8mMdI8k=\n-----END PUBLIC KEY-----"
+
+  class << self
+    def run_webhook_server
+      server = TCPServer.new(4567)
+
+      puts "Server running at http://localhost:4567"
+
+      loop do
+        Thread.start(server.accept) do |client|
+          begin
+            request = parse_request(client)
+            status, body = handle_request.call(request)
+            headers = { "Content-Type" => "text/plain" }
+
+            send_response(client, status, headers, body)
+          rescue => error
+            puts error
+          ensure
+            client.close
+          end
+        end
+      end
+    end
+
+    private def parse_request(client)
+      request = client.gets
+      headers, body = client.readpartial(2048).split("\r\n\r\n", 2)
+      method, remainder = request.split(" ", 2)
+      url = remainder.split(" ").first
+      path, _query_strings = url.split("?", 2)
+
+      {
+        method: method,
+        path: path,
+        headers: headers_to_hash(headers),
+        body: body
+      }
+    end
+
+    private def handle_request
+      Proc.new do |request|
+        if request[:method] == "POST" and request[:path] == WEBHOOK_PATH
+          verify_webhook(request[:path], request[:headers], request[:body])
+        else
+          ["403", "Forbidden"]
+        end
+      end
+    end
+
+    private def verify_webhook(path, headers, body)
+      tl_signature = headers["tl-signature"]
+
+      return ["400", "Bad Request – Header `Tl-Signature` missing"] unless tl_signature
+
+      begin
+        TrueLayerSigning.verify_with_pem(PUBLIC_KEY_PEM)
+          .set_method(:post)
+          .set_path(path)
+          .set_headers(headers)
+          .set_body(body)
+          .verify(tl_signature)
+
+        ["202", "Accepted"]
+      rescue TrueLayerSigning::Error
+        ["401", "Unauthorized"]
+      end
+    end
+
+    private def send_response(client, status, headers, body)
+      client.print("HTTP/1.1 #{status}\r\n")
+      headers.each { |key, value| client.print("#{key}: #{value}\r\n") }
+      client.print("\r\n#{body}")
+    end
+
+    private def headers_to_hash(headers_string, hash = Hash.new)
+      headers_string.split("\r\n").each do |line|
+        pair = line.split(":")
+        hash[pair.first.to_s.strip.downcase] = pair.last.to_s.strip
+      end
+
+      hash
+    end
+  end
+end
+
+TrueLayerSigningExamples.run_webhook_server

data/lib/truelayer-signing/config.rb

@@ -0,0 +1,21 @@
+module TrueLayerSigning
+  class Config
+    attr_accessor :certificate_id, :private_key
+    attr_reader :algorithm, :version
+
+    # @return [TrueLayerSigning::Config]
+    def self.setup
+      new.tap do |instance|
+        yield(instance) if block_given?
+      end
+    end
+
+    # @return [TrueLayerSigning::Config]
+    def initialize
+      @algorithm = "ES512".freeze
+      @certificate_id = ENV.fetch("TRUELAYER_SIGNING_CERTIFICATE_ID", nil).freeze
+      @private_key = ENV.fetch("TRUELAYER_SIGNING_PRIVATE_KEY", nil)&.gsub(/\\n/, "\n").freeze
+      @version = "2".freeze
+    end
+  end
+end

data/lib/truelayer-signing/errors.rb

@@ -0,0 +1,3 @@
+module TrueLayerSigning
+  class Error < StandardError; end
+end

data/lib/truelayer-signing/jwt.rb

@@ -0,0 +1,20 @@
+# TODO: this is a custom patch of payload-related methods, from the 'jwt' gem.
+# It prevents the payload from being systematically converted to and from JSON.
+# To be changed in the 'jwt' gem directly, or hard-coded in this library.
+module JWT
+  class Encode
+    # See https://github.com/jwt/ruby-jwt/blob/main/lib/jwt/encode.rb#L53-L55
+    private def encode_payload
+      ::JWT::Base64.url_encode(@payload)
+    end
+  end
+
+  class Decode
+    # See https://github.com/jwt/ruby-jwt/blob/main/lib/jwt/decode.rb#L154-L156
+    private def payload
+      @payload ||= ::JWT::Base64.url_decode(@segments[1])
+    rescue ::JSON::ParserError
+      raise JWT::DecodeError, 'Invalid segment encoding'
+    end
+  end
+end

data/lib/truelayer-signing/signer.rb

@@ -0,0 +1,34 @@
+module TrueLayerSigning
+  class Signer < JwsBase
+    attr_reader :jws_jku
+
+    def sign
+      ensure_signer_config!
+
+      private_key = OpenSSL::PKey.read(TrueLayerSigning.private_key)
+      jws_header_args = { tl_headers: headers }
+      jws_header_args[:jku] = jws_jku if jws_jku
+      jws_header = TrueLayerSigning::JwsHeader.new(jws_header_args).to_h
+      jwt = JWT.encode(build_signing_payload, private_key, TrueLayerSigning.algorithm, jws_header)
+      header, _, signature = jwt.split(".")
+
+      "#{header}..#{signature}"
+    end
+
+    def set_jku(jku)
+      @jws_jku = jku
+      self
+    end
+
+    private def ensure_signer_config!
+      raise(Error, "TRUELAYER_SIGNING_CERTIFICATE_ID missing") \
+        if TrueLayerSigning.certificate_id.nil? ||
+          TrueLayerSigning.certificate_id.empty?
+      raise(Error, "TRUELAYER_SIGNING_PRIVATE_KEY missing") \
+        if TrueLayerSigning.private_key.nil? ||
+          TrueLayerSigning.private_key.empty?
+      raise(Error, "Request path missing") unless path
+      raise(Error, "Request body missing") unless body
+    end
+  end
+end

data/lib/truelayer-signing/utils.rb

@@ -0,0 +1,90 @@
+module TrueLayerSigning
+  class JwsHeader
+    attr_reader :alg, :kid, :tl_version, :tl_headers, :jku
+
+    def initialize(args = {})
+      raise(Error, "TRUELAYER_SIGNING_CERTIFICATE_ID is missing") \
+        if TrueLayerSigning.certificate_id.nil? ||
+          TrueLayerSigning.certificate_id.empty?
+
+      @alg = args[:alg] || TrueLayerSigning.algorithm
+      @kid = args[:kid] || TrueLayerSigning.certificate_id
+      @tl_version = TrueLayerSigning.version
+      @tl_headers = retrieve_headers(args[:tl_headers])
+      @jku = args[:jku] || nil
+    end
+
+    def to_h
+      hash = instance_variables.map { |var| [var[1..-1].to_sym, instance_variable_get(var)] }.to_h
+      hash.reject { |key, _value| hash[key].nil? }
+    end
+
+    def filter_headers(headers)
+      required_header_keys = tl_headers.split(",").reject { |key| key.empty? }
+      normalised_headers = {}
+      headers.to_a.each { |header| normalised_headers[header.first.downcase] = header.last }
+
+      ordered_headers = required_header_keys.map do |key|
+        value = normalised_headers[key.downcase]
+
+        raise(Error, "Missing header(s) declared in signature") unless value
+
+        [key, value]
+      end
+
+      ordered_headers.to_h
+    end
+
+    private def retrieve_headers(tl_headers)
+      tl_headers && tl_headers.is_a?(Hash) && tl_headers.keys.join(",") || tl_headers || ""
+    end
+  end
+
+  class JwsBase
+    attr_reader :method, :path, :headers, :body
+
+    def initialize(args = {})
+      @method = "POST"
+      @headers = {}
+    end
+
+    def set_method(method)
+      @method = method.to_s.upcase
+      self
+    end
+
+    def set_path(path)
+      raise(Error, "Path must start with '/'") unless path.start_with?("/")
+
+      @path = path
+      self
+    end
+
+    def add_header(name, value)
+      @headers[name.to_s] = value
+      self
+    end
+
+    def set_headers(headers)
+      headers.each { |name, value| @headers[name.to_s] = value }
+      self
+    end
+
+    def set_body(body)
+      @body = body
+      self
+    end
+
+    private def build_signing_payload(custom_headers = nil)
+      parts = []
+      parts.push("#{method.upcase} #{path}")
+      parts.push(custom_headers && format_headers(custom_headers) || format_headers(headers))
+      parts.push(body)
+      parts.reject { |elem| elem.nil? || elem.empty? }.join("\n")
+    end
+
+    private def format_headers(headers)
+      headers.map { |key, value| "#{key}: #{value}" }.join("\n")
+    end
+  end
+end

data/lib/truelayer-signing/verifier.rb

@@ -0,0 +1,76 @@
+module TrueLayerSigning
+  class Verifier < JwsBase
+    attr_reader :required_headers, :key_value
+
+    def initialize(args)
+      super
+      @key_value = args[:key_value]
+    end
+
+    def verify(tl_signature)
+      ensure_verifier_config!
+
+      jws_header, jws_header_b64, signature_b64 = self.class.parse_tl_signature(tl_signature)
+      public_key = OpenSSL::PKey.read(key_value)
+
+      raise(Error, "Unexpected `alg` header value") if jws_header.alg != TrueLayerSigning.algorithm
+
+      ordered_headers = jws_header.filter_headers(headers)
+      normalised_headers = {}
+      ordered_headers.to_a.each { |header| normalised_headers[header.first.downcase] = header.last }
+
+      raise(Error, "Signature missing required header(s)") if required_headers &&
+        required_headers.any? { |key| !normalised_headers.has_key?(key.downcase) }
+
+      payload_b64 = Base64.urlsafe_encode64(build_signing_payload(ordered_headers), padding: false)
+      full_signature = [jws_header_b64, payload_b64, signature_b64].join(".")
+      jwt_options = { algorithm: TrueLayerSigning.algorithm }
+
+      begin
+        JWT.decode(full_signature, public_key, true, jwt_options)
+      rescue JWT::VerificationError
+        @path = path.end_with?("/") && path[0...-1] || path + "/"
+        payload_b64 = Base64.urlsafe_encode64(build_signing_payload(ordered_headers),
+                                              padding: false)
+        full_signature = [jws_header_b64, payload_b64, signature_b64].join(".")
+
+        begin
+          JWT.decode(full_signature, public_key, true, jwt_options)
+        rescue
+          raise(Error, "Signature verification failed")
+        end
+      end
+    end
+
+    def require_header(name)
+      @required_headers ||= []
+      @required_headers.push(name)
+      self
+    end
+
+    def require_headers(names)
+      @required_headers = names
+      self
+    end
+
+    def self.parse_tl_signature(tl_signature)
+      jws_header_b64, signature_b64 = tl_signature.split("..")
+
+      raise(Error, "Invalid signature format") unless signature_b64
+
+      begin
+        jws_header_raw = Base64.urlsafe_decode64(jws_header_b64)
+      rescue ArgumentError
+        raise(Error, "Invalid base64 for header")
+      else
+        jws_header = JwsHeader.new(JSON.parse(jws_header_raw, symbolize_names: true))
+      end
+
+      [jws_header, jws_header_b64, signature_b64]
+    end
+
+    private def ensure_verifier_config!
+      raise(Error, "Key value missing") unless key_value
+    end
+  end
+end

data/lib/truelayer-signing.rb

@@ -0,0 +1,35 @@
+require "base64"
+require "forwardable"
+require "jwt"
+
+# TODO: replace with a proper solution
+require "truelayer-signing/jwt"
+
+require "truelayer-signing/config"
+require "truelayer-signing/errors"
+require "truelayer-signing/utils"
+require "truelayer-signing/signer"
+require "truelayer-signing/verifier"
+
+module TrueLayerSigning
+  @config = Config.setup
+
+  class << self
+    extend Forwardable
+
+    attr_reader :config
+
+    def_delegators :@config, :certificate_id, :certificate_id=
+    def_delegators :@config, :private_key, :private_key=
+    def_delegator :@config, :algorithm
+    def_delegator :@config, :version
+
+    def sign_with_pem
+      Signer.new
+    end
+
+    def verify_with_pem(pem)
+      Verifier.new(key_value: pem)
+    end
+  end
+end