mailcycle 0.1.0

data/lib/mailcycle/webhook_signature.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Mailcycle
+  # Checking a webhook came from Mailcycle.
+  #
+  # `Mailcycle-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "t.body">`,
+  # keyed with the webhook's secret. Pass the raw body, before any parsing: a
+  # body that has been through a JSON round trip is a different string and
+  # will not verify.
+  module WebhookSignature
+    DEFAULT_TOLERANCE_SECONDS = 300
+
+    module_function
+
+    # The header Mailcycle would send for this body at this second.
+    #
+    # Here so a test suite can build a believable delivery without a live
+    # webhook, and so this implementation can be checked against the shared
+    # vectors rather than trusted.
+    def header(secret, raw_body, timestamp)
+      "t=#{timestamp},v1=#{Encoding.to_hex(sign(secret, raw_body, timestamp))}"
+    end
+
+    # True if the signature is Mailcycle's, recent, and over this exact body.
+    #
+    # `now` defaults to the system clock; pass it to test, or from a trusted
+    # time source.
+    def verify(secret, raw_body, header, tolerance: DEFAULT_TOLERANCE_SECONDS, now: Time.now.to_i)
+      return false unless header.is_a?(String)
+
+      timestamp = nil
+      given = nil
+      header.split(",").each do |part|
+        name, value = part.split("=", 2)
+        next if value.nil?
+
+        # Trim the name as well as the value, matching the other SDKs, so a
+        # header written with spaces around the keys still verifies.
+        case name.strip
+        when "t" then timestamp = value.strip.match?(/\A[+-]?[0-9]+\z/) ? value.strip.to_i : nil
+        when "v1" then given = value.strip
+        end
+      end
+
+      return false if timestamp.nil? || given.nil?
+      return false if (now - timestamp).abs > tolerance
+      return false unless given.bytesize == 64
+
+      signature = Encoding.from_hex(given)
+      return false if signature.nil?
+
+      Crypto::Primitives.constant_time_equal(sign(secret, raw_body, timestamp), signature)
+    end
+
+    def sign(secret, raw_body, timestamp)
+      Crypto::Primitives.hmac_sha256(secret.to_s.b, "#{timestamp}.".b + raw_body.to_s.b)
+    end
+    private_class_method :sign
+  end
+end

data/lib/mailcycle/websocket.rb

@@ -0,0 +1,320 @@
+# frozen_string_literal: true
+
+require "io/wait"
+require "openssl"
+require "socket"
+require "uri"
+
+module Mailcycle
+  # The client half of RFC 6455, as much of it as the event stream uses.
+  #
+  # Ruby's standard library has no WebSocket, and the stream is too small a
+  # part of this library to take a dependency for. The protocol's client side
+  # is short: an HTTP upgrade, then frames, masked going out and unmasked
+  # coming in. Text and close frames are what the server sends, with pings
+  # answered as they arrive. TLS is OpenSSL's, with the peer's certificate and
+  # host name checked.
+  class WebSocket
+    GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
+    # Generous for one event, which is a few hundred bytes of ids.
+    MAX_MESSAGE_BYTES = 16 * 1024 * 1024
+
+    OP_CONTINUATION = 0x0
+    OP_TEXT = 0x1
+    OP_BINARY = 0x2
+    OP_CLOSE = 0x8
+    OP_PING = 0x9
+    OP_PONG = 0xA
+
+    # The server answered the upgrade with something other than 101.
+    class Refused < StandardError
+      attr_reader :status
+
+      def initialize(status)
+        @status = status
+        super("the server answered #{status} to the upgrade")
+      end
+    end
+
+    # The connection broke, or the server spoke something that is not the
+    # protocol.
+    class Broken < StandardError; end
+
+    # What `read` returns: a whole text or binary message, or the server's
+    # close.
+    Frame = Struct.new(:type, :data, :code, :reason, keyword_init: true)
+
+    # Connects and upgrades. Raises Refused for an answer other than 101, and
+    # Broken or a socket error for anything else.
+    def self.connect(url, protocols: [], headers: {}, timeout: 15)
+      uri = URI.parse(url)
+      secure = uri.scheme == "wss"
+      raise Broken, "not a WebSocket address: #{url}" unless %w[ws wss].include?(uri.scheme) && uri.host
+
+      socket = Socket.tcp(uri.host, uri.port || (secure ? 443 : 80), connect_timeout: timeout)
+      socket = tls(socket, uri.host, timeout) if secure
+      client = new(socket)
+      client.__send__(:handshake, uri, protocols, headers, timeout)
+      client
+    rescue StandardError
+      socket&.close
+      raise
+    end
+
+    # TLS over a connected socket, with the certificate and host name checked.
+    def self.tls(socket, host, timeout)
+      context = OpenSSL::SSL::SSLContext.new
+      context.set_params(verify_mode: OpenSSL::SSL::VERIFY_PEER)
+      ssl = OpenSSL::SSL::SSLSocket.new(socket, context)
+      ssl.hostname = host
+      ssl.sync_close = true
+      loop do
+        case ssl.connect_nonblock(exception: false)
+        when :wait_readable
+          raise Broken, "the TLS handshake timed out" unless socket.wait_readable(timeout)
+        when :wait_writable
+          raise Broken, "the TLS handshake timed out" unless socket.wait_writable(timeout)
+        else
+          break
+        end
+      end
+      ssl.post_connection_check(host)
+      ssl
+    rescue StandardError
+      socket.close
+      raise
+    end
+    private_class_method :tls
+
+    def initialize(socket)
+      @socket = socket
+      @buffer = +"".b
+      @write_lock = Mutex.new
+      @fragments = nil
+      @closed = false
+    end
+
+    # The subprotocol the server chose.
+    attr_reader :protocol
+
+    # The next message, or nil when `timeout` seconds pass without one. Pings
+    # are answered on the way.
+    def read(timeout: nil)
+      deadline = timeout && (monotonic + timeout)
+      loop do
+        frame = take_frame
+        if frame.nil?
+          remaining = deadline && (deadline - monotonic)
+          return nil if remaining && remaining <= 0
+
+          fill(remaining)
+          next
+        end
+        message = handle(*frame)
+        return message if message
+      end
+    end
+
+    def send_text(text)
+      write_frame(OP_TEXT, text.to_s.b)
+    end
+
+    # Sends a close frame, best effort, and closes the socket.
+    def close(code = 1000, reason = "")
+      return if @closed
+
+      begin
+        write_frame(OP_CLOSE, [code].pack("n") + reason.to_s.b)
+      rescue StandardError
+        # Already gone: closing is all that is left.
+      end
+      close_socket
+    end
+
+    def close_socket
+      @closed = true
+      @socket.close
+    rescue StandardError
+      nil
+    end
+
+    def closed?
+      @closed
+    end
+
+    private
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def handshake(uri, protocols, headers, timeout)
+      key = [Crypto::Primitives.random_bytes(16)].pack("m0")
+      path = uri.request_uri
+      host = uri.port == uri.default_port ? uri.host : "#{uri.host}:#{uri.port}"
+      lines = [
+        "GET #{path} HTTP/1.1",
+        "Host: #{host}",
+        "Upgrade: websocket",
+        "Connection: Upgrade",
+        "Sec-WebSocket-Key: #{key}",
+        "Sec-WebSocket-Version: 13"
+      ]
+      lines << "Sec-WebSocket-Protocol: #{protocols.join(', ')}" unless protocols.empty?
+      headers.each { |name, value| lines << "#{name}: #{value}" }
+      @write_lock.synchronize { @socket.write("#{lines.join("\r\n")}\r\n\r\n") }
+
+      status, answer = read_response_head(timeout)
+      raise Refused, status unless status == 101
+
+      expected = [OpenSSL::Digest::SHA1.digest(key + GUID)].pack("m0")
+      raise Broken, "the server's handshake does not match" unless answer["sec-websocket-accept"] == expected
+
+      @protocol = answer["sec-websocket-protocol"]
+      return unless !protocols.empty? && !@protocol.nil? && !protocols.include?(@protocol)
+
+      raise Broken, "the server chose a subprotocol that was not offered"
+    end
+
+    def read_response_head(timeout)
+      deadline = monotonic + timeout
+      until (ends = @buffer.index("\r\n\r\n"))
+        raise Broken, "the upgrade answer is too long" if @buffer.bytesize > 64 * 1024
+
+        remaining = deadline - monotonic
+        raise Broken, "the upgrade timed out" if remaining <= 0
+
+        fill(remaining)
+      end
+      head = @buffer.byteslice(0, ends).force_encoding(::Encoding::BINARY)
+      @buffer = @buffer.byteslice(ends + 4, @buffer.bytesize - ends - 4)
+      status_line, *header_lines = head.split("\r\n")
+      status = status_line.to_s[%r{\AHTTP/1\.[01] ([0-9]{3})}, 1].to_i
+      answer = {}
+      header_lines.each do |line|
+        name, value = line.split(":", 2)
+        answer[name.strip.downcase] = value.to_s.strip if value
+      end
+      [status, answer]
+    end
+
+    # Reads whatever is there into the buffer, waiting up to `timeout`
+    # seconds (forever when nil). Raises Broken at the end of the stream.
+    def fill(timeout)
+      chunk = @socket.read_nonblock(64 * 1024, exception: false)
+      case chunk
+      when :wait_readable
+        @socket.to_io.wait_readable(timeout)
+      when :wait_writable
+        @socket.to_io.wait_writable(timeout)
+      when nil
+        raise Broken, "the connection closed"
+      else
+        @buffer << chunk
+      end
+    rescue IOError, SystemCallError, OpenSSL::SSL::SSLError => e
+      raise Broken, e.message
+    end
+
+    # One whole frame off the front of the buffer, or nil if it has not all
+    # arrived: `[fin, opcode, payload]`.
+    def take_frame
+      return nil if @buffer.bytesize < 2
+
+      first = @buffer.getbyte(0)
+      second = @buffer.getbyte(1)
+      raise Broken, "the server masked a frame" if second & 0x80 != 0
+      raise Broken, "a frame used reserved bits" if first & 0x70 != 0
+
+      length = second & 0x7f
+      offset = 2
+      if length == 126
+        return nil if @buffer.bytesize < 4
+
+        length = @buffer.byteslice(2, 2).unpack1("n")
+        offset = 4
+      elsif length == 127
+        return nil if @buffer.bytesize < 10
+
+        length = @buffer.byteslice(2, 8).unpack1("Q>")
+        offset = 10
+      end
+      raise Broken, "a frame is too large" if length > MAX_MESSAGE_BYTES
+      return nil if @buffer.bytesize < offset + length
+
+      payload = @buffer.byteslice(offset, length)
+      @buffer = @buffer.byteslice(offset + length, @buffer.bytesize - offset - length)
+      [first & 0x80 != 0, first & 0x0f, payload]
+    end
+
+    # A Frame for a whole message or a close, nil for anything handled here.
+    def handle(fin, opcode, payload)
+      case opcode
+      when OP_PING
+        write_frame(OP_PONG, payload)
+        nil
+      when OP_PONG
+        nil
+      when OP_CLOSE
+        code = payload.bytesize >= 2 ? payload.unpack1("n") : 1005
+        reason = if payload.bytesize > 2
+                   payload.byteslice(2,
+                                     payload.bytesize - 2).force_encoding(::Encoding::UTF_8)
+                 else
+                   ""
+                 end
+        Frame.new(type: :close, code: code, reason: reason.valid_encoding? ? reason : reason.scrub)
+      when OP_TEXT, OP_BINARY
+        raise Broken, "a new message began inside another" if @fragments
+
+        return message(opcode, payload) if fin
+
+        @fragments = [opcode, payload.dup]
+        nil
+      when OP_CONTINUATION
+        raise Broken, "a continuation with nothing to continue" unless @fragments
+
+        @fragments[1] << payload
+        raise Broken, "a message is too large" if @fragments[1].bytesize > MAX_MESSAGE_BYTES
+        return nil unless fin
+
+        opcode, data = @fragments
+        @fragments = nil
+        message(opcode, data)
+      else
+        raise Broken, "an unknown frame type #{opcode}"
+      end
+    end
+
+    def message(opcode, data)
+      return Frame.new(type: :binary, data: data) if opcode == OP_BINARY
+
+      text = data.force_encoding(::Encoding::UTF_8)
+      raise Broken, "a text frame that is not UTF-8" unless text.valid_encoding?
+
+      Frame.new(type: :text, data: text)
+    end
+
+    def write_frame(opcode, payload)
+      payload = payload.b
+      mask = Crypto::Primitives.random_bytes(4)
+      head = [0x80 | opcode].pack("C")
+      length = payload.bytesize
+      head << if length < 126
+                [0x80 | length].pack("C")
+              elsif length < 65_536
+                [0x80 | 126, length].pack("Cn")
+              else
+                [0x80 | 127, length].pack("CQ>")
+              end
+      @write_lock.synchronize { @socket.write(head + mask + masked(payload, mask)) }
+    end
+
+    def masked(payload, mask)
+      keys = mask.bytes
+      out = payload.bytes
+      out.each_index { |i| out[i] ^= keys[i & 3] }
+      out.pack("C*")
+    end
+  end
+end

data/lib/mailcycle.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+# Mailcycle for Ruby.
+#
+# Privacy-first email you can automate. Create addresses that receive mail,
+# read and decrypt it on your own machine, send, and listen for events.
+#
+#   require "mailcycle"
+#
+#   mc = Mailcycle.sign_in(ENV.fetch("MAILCYCLE_PHRASE"))
+#   address = mc.addresses.create(label: "Sign-in codes")
+#   message = mc.messages.wait_for(address_id: address.id)
+#   puts "#{message.subject}: #{message.text}"
+#
+# The recovery phrase never leaves this machine. Mail is sealed to a key
+# derived from it, so the API serves ciphertext it cannot read, and this
+# library opens it locally. Lose the phrase and the mail is gone; nobody at
+# Mailcycle can help.
+#
+# Documentation: https://docs.mailcycle.email/
+
+require_relative "mailcycle/version"
+require_relative "mailcycle/errors"
+require_relative "mailcycle/encoding"
+require_relative "mailcycle/crypto/primitives"
+require_relative "mailcycle/crypto/wordlist"
+require_relative "mailcycle/crypto/mnemonic"
+require_relative "mailcycle/crypto/identity"
+require_relative "mailcycle/crypto/cipher"
+require_relative "mailcycle/crypto/sealed_box"
+require_relative "mailcycle/crypto/asymmetric"
+require_relative "mailcycle/crypto/auth_proof"
+require_relative "mailcycle/keys"
+require_relative "mailcycle/http"
+require_relative "mailcycle/models"
+require_relative "mailcycle/trackers"
+require_relative "mailcycle/mail"
+require_relative "mailcycle/webhook_signature"
+require_relative "mailcycle/websocket"
+require_relative "mailcycle/events"
+require_relative "mailcycle/client"
+require_relative "mailcycle/manage"
+require_relative "mailcycle/pairing"
+
+# The library's namespace, and shortcuts to what most programs need.
+module Mailcycle
+  module_function
+
+  # Signs in with the recovery phrase. See Client.sign_in.
+  def sign_in(phrase, **options)
+    Client.sign_in(phrase, **options)
+  end
+
+  # Picks up a session from an earlier sign-in. See Client.resume.
+  def resume(session_token, phrase, **options)
+    Client.resume(session_token, phrase, **options)
+  end
+
+  # Uses an API key, with or without the phrase. See Client.with_api_key.
+  def with_api_key(api_key, phrase: nil, **options)
+    Client.with_api_key(api_key, phrase: phrase, **options)
+  end
+
+  # Creates an account and signs in. Returns `[client, phrase]`. See
+  # Client.create_account.
+  def create_account(phrase = nil, **options)
+    Client.create_account(phrase, **options)
+  end
+
+  # A new twelve-word recovery phrase, generated on this machine.
+  def generate_phrase
+    Client.generate_phrase
+  end
+
+  # nil for a good phrase, otherwise a PhraseProblem saying what is wrong.
+  def validate_phrase(phrase)
+    Crypto::Mnemonic.validate(phrase)
+  end
+
+  # True if a webhook delivery is Mailcycle's, recent, and over this exact
+  # body. Pass the body exactly as it arrived, before any parsing, and the
+  # `Mailcycle-Signature` header.
+  def verify_webhook_signature(secret, raw_body, header, tolerance: WebhookSignature::DEFAULT_TOLERANCE_SECONDS,
+                               now: Time.now.to_i)
+    WebhookSignature.verify(secret, raw_body, header, tolerance: tolerance, now: now)
+  end
+
+  # The `Mailcycle-Signature` header Mailcycle would send for this body at
+  # this second, for building a believable delivery in a test.
+  def webhook_signature_header(secret, raw_body, timestamp)
+    WebhookSignature.header(secret, raw_body, timestamp)
+  end
+
+  # Reads a pairing QR code's text or a typed code. See
+  # Pairing.parse_scanned_value.
+  def parse_scanned_value(raw)
+    Pairing.parse_scanned_value(raw)
+  end
+
+  # The HTML with everything remote removed, and what was. See Trackers.
+  def strip_remote_content(html)
+    Trackers.strip_remote_content(html)
+  end
+
+  # A one-line summary of what was blocked, as the app shows above a message.
+  def summarize_blocked(blocked)
+    Trackers.summarize_blocked(blocked)
+  end
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: mailcycle
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Northlab Studios Ltd
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: openssl
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Create addresses that receive mail, read and decrypt it on your machine,
+  send, and listen for events.
+email:
+- hello@mailcycle.email
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/mailcycle.rb
+- lib/mailcycle/client.rb
+- lib/mailcycle/crypto/asymmetric.rb
+- lib/mailcycle/crypto/auth_proof.rb
+- lib/mailcycle/crypto/cipher.rb
+- lib/mailcycle/crypto/identity.rb
+- lib/mailcycle/crypto/mnemonic.rb
+- lib/mailcycle/crypto/primitives.rb
+- lib/mailcycle/crypto/sealed_box.rb
+- lib/mailcycle/crypto/wordlist.rb
+- lib/mailcycle/encoding.rb
+- lib/mailcycle/errors.rb
+- lib/mailcycle/events.rb
+- lib/mailcycle/http.rb
+- lib/mailcycle/keys.rb
+- lib/mailcycle/mail.rb
+- lib/mailcycle/manage.rb
+- lib/mailcycle/models.rb
+- lib/mailcycle/pairing.rb
+- lib/mailcycle/trackers.rb
+- lib/mailcycle/version.rb
+- lib/mailcycle/webhook_signature.rb
+- lib/mailcycle/websocket.rb
+homepage: https://mailcycle.email/
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://mailcycle.email/
+  documentation_uri: https://docs.mailcycle.email/
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Ruby client for the Mailcycle API.
+test_files: []