mailcycle 0.1.0

data/lib/mailcycle/client.rb

@@ -0,0 +1,803 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Mailcycle
+  # A file to send with a message.
+  #
+  # `filename` is what the recipient saves it as; program and script files
+  # (.exe, .js, .ps1 and the like) are refused. `content` is the raw bytes.
+  # `mime_type` defaults to application/octet-stream. `content_id` makes the
+  # file inline, shown where the HTML says `cid:<content_id>`.
+  OutgoingAttachment = Struct.new(:filename, :content, :mime_type, :content_id, keyword_init: true)
+
+  # Records sealed under the vault key: address details, device profiles, and
+  # the names on keys and webhooks.
+  module Vault
+    ID_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789"
+
+    module_function
+
+    def new_id(prefix, length)
+      out = +""
+      # Rejection sampling, so every character is equally likely. 252 is the
+      # largest multiple of 36 below 256.
+      while out.length < length
+        Crypto::Primitives.random_bytes(length * 2).each_byte do |byte|
+          break if out.length == length
+
+          out << ID_ALPHABET[byte % 36] if byte < 252
+        end
+      end
+      "#{prefix}_#{out}"
+    end
+
+    # What a record sealed under the vault key is bound to.
+    #
+    # The kind of record as well as its id, so a box from one kind cannot be
+    # read as another. Records sealed before that change carry the bare id,
+    # and still open; `open_record` tries both.
+    def aad(kind, id)
+      "mailcycle/v1/#{kind}:#{id}"
+    end
+
+    def seal(keys, kind, id, value)
+      Crypto::Cipher.seal_json(keys.vault_key, value, aad(kind, id)).to_wire
+    end
+
+    def open_record(vault_key, kind, id, box)
+      Crypto::Cipher.open_json(vault_key, box, aad(kind, id))
+    rescue DecryptionError
+      Crypto::Cipher.open_json(vault_key, box, id)
+    end
+
+    def sealed_box?(value)
+      value.is_a?(Hash) && value.key?("c") && !value.key?("epk")
+    end
+
+    # The record, opened, as a Hash; empty if there are no keys or it will not
+    # open.
+    def open_or_empty(keys, kind, id, value)
+      return {} if keys.nil? || !sealed_box?(value)
+
+      box = Crypto::SealedBox.from_wire(value)
+      return {} if box.nil?
+
+      Wire.object(open_record(keys.vault_key, kind, id, box))
+    rescue Error
+      {}
+    end
+  end
+
+  # A client for one Mailcycle account.
+  #
+  # Signed in with the recovery phrase, it can do everything the app can: open
+  # mail, create addresses that receive it, and read the labels and names the
+  # app seals. With an API key alone it manages addresses, devices and
+  # metadata; add the phrase to open mail too.
+  #
+  # The phrase never leaves this machine, and nothing derived from it is sent
+  # anywhere. What reaches the API is an account id, a public key, and a proof
+  # that this machine holds the matching private one.
+  #
+  # Every constructor takes the same options: `api_url` (the live API by
+  # default), `passphrase` (empty unless the account was made with one) and
+  # `timeout` in seconds (30).
+  class Client
+    attr_reader :http, :keys
+
+    # A new twelve-word recovery phrase, generated on this machine.
+    def self.generate_phrase
+      Crypto::Mnemonic.generate.join(" ")
+    end
+
+    # Signs in with the recovery phrase.
+    #
+    # The same challenge-response the app uses, in which nothing secret
+    # crosses the wire. Sessions last 30 days; keep `session_token` and pass
+    # it to `resume` rather than deriving the keys again every run.
+    def self.sign_in(phrase, api_url: Http::DEFAULT_API_URL, passphrase: "", timeout: Http::DEFAULT_TIMEOUT_SECONDS)
+      keys = Keys.from_phrase(phrase, passphrase)
+      http = Http.new(api_url, nil, timeout)
+
+      challenge = Wire.object(http.request("POST", "/accounts/challenge", body: { "accountId" => keys.account_id }))
+      nonce = Wire.text(challenge["nonce"])
+      proof = Crypto::AuthProof.prove_account(keys.auth_key, Wire.text(challenge["challengeKey"]), nonce,
+                                              keys.account_id, Crypto::AuthProof::DOMAIN)
+
+      session = Wire.object(http.request("POST", "/accounts/verify",
+                                         body: { "accountId" => keys.account_id, "nonce" => nonce,
+                                                 "proof" => proof }))
+      http.token = Wire.maybe_text(session["token"])
+      new(http, keys, api_key: false)
+    end
+
+    # Picks up a session from an earlier `sign_in`.
+    #
+    # The phrase is still needed to open mail, and is checked against the
+    # session's account before it is used.
+    def self.resume(session_token, phrase, api_url: Http::DEFAULT_API_URL, passphrase: "",
+                    timeout: Http::DEFAULT_TIMEOUT_SECONDS)
+      keys = Keys.from_phrase(phrase, passphrase)
+      client = new(Http.new(api_url, session_token, timeout), keys, api_key: false)
+      client.__send__(:check_phrase_matches, "session")
+      client
+    end
+
+    # Uses an API key, `mak_...`. Operator plan and up.
+    #
+    # With the phrase as well, the client can open mail and create addresses
+    # that receive it; the phrase is checked against the key's account first.
+    def self.with_api_key(api_key, phrase: nil, api_url: Http::DEFAULT_API_URL, passphrase: "",
+                          timeout: Http::DEFAULT_TIMEOUT_SECONDS)
+      keys = phrase.nil? ? nil : Keys.from_phrase(phrase, passphrase)
+      client = new(Http.new(api_url, api_key, timeout), keys, api_key: true)
+      client.__send__(:check_phrase_matches, "API key") if keys
+      client
+    end
+
+    # Creates an account and signs in. Returns `[client, phrase]`.
+    #
+    # Keep the phrase. Nothing can recover the account without it, and nobody
+    # at Mailcycle can help.
+    def self.create_account(phrase = nil, api_url: Http::DEFAULT_API_URL, passphrase: "",
+                            timeout: Http::DEFAULT_TIMEOUT_SECONDS)
+      words = phrase || generate_phrase
+      keys = Keys.from_phrase(words, passphrase)
+      http = Http.new(api_url, nil, timeout)
+      session = Wire.object(http.request("POST", "/accounts", body: {
+                                           "accountId" => keys.account_id,
+                                           "authVerifier" => keys.auth_verifier,
+                                           "authPublicKey" => keys.auth_public_key
+                                         }))
+      http.token = Wire.maybe_text(session["token"])
+      [new(http, keys, api_key: false), words]
+    end
+
+    def initialize(http, keys, api_key:)
+      @http = http
+      @keys = keys
+      # Built with an API key rather than a session.
+      @api_key = api_key
+    end
+
+    # -- the account -------------------------------------------------------
+
+    # The account id, when the phrase is known. Public, and safe to log.
+    def account_id
+      @keys&.account_id
+    end
+
+    # The bearer this client uses: the session from `sign_in`, or the API key.
+    def session_token
+      @http.token
+    end
+
+    # Whether this client can open mail and create addresses that receive it.
+    def can_decrypt?
+      !@keys.nil?
+    end
+
+    def account
+      result = Wire.object(@http.request("GET", "/accounts/me"))
+      operator = Wire.object(result["operator"])
+      Account.new(
+        id: Wire.text(operator["id"]),
+        plan_id: Wire.text(operator["planId"]),
+        created_at: Wire.text(operator["createdAt"]),
+        plan: Plan.from_wire(result["plan"])
+      )
+    end
+
+    # Recent account events, newest first: ids and times, never content.
+    def activity(limit = 20)
+      activity_page(limit: limit).activity
+    end
+
+    # One page of account events, newest first.
+    #
+    # `cursor` is the `next_cursor` of the page before, passed back as it is.
+    # It is opaque: do not build one or read a time out of it.
+    def activity_page(limit: nil, cursor: nil)
+      query = []
+      query << ["limit", limit.to_s] if limit
+      query << ["cursor", cursor] if cursor
+      result = Wire.object(@http.request("GET", "/activity", query: query))
+      ActivityPage.new(activity: Wire.array(result["activity"]).map { |entry| ActivityEntry.from_wire(entry) },
+                       next_cursor: Wire.maybe_text(result["nextCursor"]))
+    end
+
+    # Every event the server still holds (the last 90 days), newest first,
+    # walking the pages.
+    def all_activity
+      out = []
+      cursor = nil
+      loop do
+        page = activity_page(limit: 200, cursor: cursor)
+        out.concat(page.activity)
+        cursor = page.next_cursor
+        return out if cursor.nil?
+      end
+    end
+
+    # What the account has used, against what its plan allows.
+    def usage
+      @http.request("GET", "/usage")
+    end
+
+    # Ends this session.
+    #
+    # Does nothing for a client built with an API key: a key is not a
+    # session, and it keeps working until it is revoked with
+    # `api_keys.revoke` or in the app.
+    def sign_out
+      return nil if @api_key
+
+      @http.request("POST", "/accounts/signout", body: {})
+      @http.token = nil
+      nil
+    end
+
+    # Erases the account and everything in it, at once. Session only.
+    #
+    # There is no undo and no grace period. Its addresses are retired and
+    # never issued again.
+    #
+    # It answers a fresh challenge with the phrase, so a copied session token
+    # alone cannot erase the account.
+    def delete_account
+      body = nil
+      if @keys && !@api_key
+        challenge = Wire.object(@http.request("POST", "/accounts/challenge",
+                                              body: { "accountId" => @keys.account_id }))
+        nonce = Wire.text(challenge["nonce"])
+        proof = Crypto::AuthProof.prove_account(@keys.auth_key, Wire.text(challenge["challengeKey"]), nonce,
+                                                @keys.account_id, Crypto::AuthProof::DELETE_DOMAIN)
+        body = { "nonce" => nonce, "proof" => proof }
+      end
+      @http.request("DELETE", "/accounts/me", body: body)
+      @http.token = nil
+      nil
+    end
+
+    # The account's subscription and balance.
+    def subscription
+      result = Wire.object(@http.request("GET", "/subscription"))
+      subscription = Wire.object(result["subscription"])
+      balance = result["balanceMinor"]
+      Subscription.new(
+        id: Wire.text(subscription["id"]),
+        plan_id: Wire.text(subscription["planId"]),
+        status: Wire.text(subscription["status"]),
+        renewal_date: Wire.text(subscription["renewalDate"]),
+        pending_plan_id: Wire.maybe_text(subscription["pendingPlanId"]),
+        balance_minor: balance.is_a?(Integer) ? balance : 0,
+        pause: result["pause"]
+      )
+    end
+
+    # Every plan, with what each includes and costs.
+    def plans
+      Wire.array(Wire.object(@http.request("GET", "/plans"))["plans"]).map { |plan| Plan.from_wire(plan) }
+    end
+
+    def addresses
+      Addresses.new(self)
+    end
+
+    def messages
+      Messages.new(self)
+    end
+
+    def devices
+      Devices.new(self)
+    end
+
+    def domains
+      Domains.new(self)
+    end
+
+    def events
+      Events.new(self)
+    end
+
+    # API keys. Session only.
+    def api_keys
+      ApiKeys.new(self)
+    end
+
+    # Webhooks, Operator and up.
+    def webhooks
+      Webhooks.new(self)
+    end
+
+    # The account's signed-in sessions. Session only.
+    def sessions
+      Sessions.new(self)
+    end
+
+    def require_keys(what)
+      return @keys if @keys
+
+      raise UnsupportedError, "The recovery phrase is needed to #{what}. Pass it when building the client."
+    end
+
+    def inspect
+      "#<Mailcycle::Client account_id=#{account_id.inspect} api_url=#{@http.base_url.inspect}>"
+    end
+    alias to_s inspect
+
+    private
+
+    def check_phrase_matches(what)
+      return if account.id == @keys.account_id
+
+      raise UnsupportedError, "That phrase belongs to a different account from the #{what}."
+    end
+  end
+
+  # Email addresses on the account.
+  class Addresses
+    UNCHANGED = Object.new.freeze
+    private_constant :UNCHANGED
+
+    def initialize(client)
+      @client = client
+    end
+
+    def list
+      result = Wire.object(@client.http.request("GET", "/inboxes"))
+      Wire.array(result["inboxes"]).map { |item| to_address(item) }
+    end
+
+    # Up to eight names in one style that are free on the domain right now.
+    #
+    # Pass one to `create` as `local_part`. Somebody may take it first, and
+    # then `create` is refused. `domain` defaults to the one `create` would
+    # use. `style` is one of NameStyle's, as a string or a symbol.
+    def roll_names(style, domain: nil)
+      wire_style = NameStyle.wire(style)
+      query = [["style", wire_style], ["domain", domain || default_domain]]
+      Wire.strings(Wire.object(@client.http.request("GET", "/inboxes/names", query: query))["names"])
+    end
+
+    # Creates an address that can receive mail.
+    #
+    # Needs the phrase: the address's public key is derived from it here, and
+    # only the public half is uploaded. Mail sealed to it opens nowhere else.
+    #
+    # - `domain`: from `domains.list`. Defaults to the first one available.
+    # - `prefix`: the start of the address; the server adds a random ending.
+    # - `local_part`: the whole part before the `@`. A name from `roll_names`
+    #   works on every plan; any other name needs Scale and up.
+    # - `style`: the kind of name the server rolls, used only when neither
+    #   `local_part` nor `prefix` is given. The server picks neutral by
+    #   default.
+    # - `label`: a private label, sealed on this machine.
+    # - `retention_days`: 1 to 90. Defaults to 7.
+    def create(domain: nil, prefix: nil, local_part: nil, style: nil, label: nil, retention_days: nil)
+      keys = @client.require_keys("create an address that receives mail")
+      id = Vault.new_id("ibx", 12)
+      domain ||= default_domain
+
+      body = {
+        "id" => id,
+        "domain" => domain,
+        "meta" => Vault.seal(keys, "inbox", id, label.nil? ? {} : { "label" => label }),
+        # The public half only. Mail is sealed to it and opens only with the phrase.
+        "publicKey" => keys.address_public_key(id)
+      }
+      if local_part
+        body["localPart"] = local_part
+      elsif prefix
+        body["prefix"] = prefix
+      elsif style
+        body["style"] = NameStyle.wire(style)
+      end
+      body["retentionDays"] = retention_days if retention_days
+
+      to_address(Wire.object(@client.http.request("POST", "/inboxes", body: body))["inbox"])
+    end
+
+    # Changes a label, a retention window, or both. Leave a keyword out to
+    # leave that alone; a nil or empty label clears it.
+    def update(address_id, label: UNCHANGED, retention_days: nil)
+      body = {}
+      body["retentionDays"] = retention_days if retention_days
+      unless label.equal?(UNCHANGED)
+        keys = @client.require_keys("change a label")
+        value = label.nil? || label.empty? ? {} : { "label" => label }
+        body["meta"] = Vault.seal(keys, "inbox", address_id, value)
+      end
+      result = @client.http.request("PATCH", "/inboxes/#{Mailcycle.path_segment(address_id)}", body: body)
+      to_address(Wire.object(result)["inbox"])
+    end
+
+    # Deletes the address and its mail. It is never issued again.
+    def delete(address_id)
+      @client.http.request("DELETE", "/inboxes/#{Mailcycle.path_segment(address_id)}")
+      nil
+    end
+
+    # How many addresses the plan allows and how many are left.
+    def allocation
+      @client.http.request("GET", "/inboxes/allocation")
+    end
+
+    private
+
+    def to_address(wire)
+      wire = Wire.object(wire)
+      id = Wire.text(wire["id"])
+      meta = Vault.open_or_empty(@client.keys, "inbox", id, wire["meta"])
+      label = Wire.maybe_text(meta["label"])
+      sender_name = Wire.maybe_text(meta["senderName"])
+      Address.new(
+        id: id,
+        email_address: Wire.text(wire["emailAddress"]),
+        status: Wire.text(wire["status"]),
+        created_at: Wire.text(wire["createdAt"]),
+        retention_days: Wire.count(wire["retentionDays"]),
+        assigned_worker_id: Wire.maybe_text(wire["assignedWorkerId"]),
+        paused_at: Wire.maybe_text(wire["pausedAt"]),
+        label: label && label.empty? ? nil : label,
+        sender_name: sender_name && sender_name.empty? ? nil : sender_name,
+        receives: Wire.flag(wire["receives"], true)
+      )
+    end
+
+    # The first domain the account can create addresses on.
+    def default_domain
+      first = @client.domains.list.first
+      raise UnsupportedError, "The account has no domain to create addresses on." if first.nil?
+
+      first.domain
+    end
+  end
+
+  # Mail: list, read, organise, send, and wait for new mail.
+  class Messages
+    # How long `wait_for` gives the event stream to come up before it polls.
+    STREAM_OPEN_SECONDS = 10
+    # How far the server's clock may trail this one, in seconds, before mail
+    # received just after `since` is taken for older mail.
+    CLOCK_SKEW_SECONDS = 5
+    # The API's limits on what a message can carry. It is the authority; these
+    # only refuse early what it would refuse anyway.
+    MAX_ATTACHMENTS = 10
+    MAX_ATTACHMENT_BYTES = 7 * 1024 * 1024 / 2
+
+    def initialize(client)
+      @client = client
+    end
+
+    # One page of a folder, newest first.
+    #
+    # `cursor` is the `next_cursor` of the page before, passed back as it is.
+    # It is opaque: do not build one or read a time out of it.
+    def list(address_id, folder: nil, limit: nil, cursor: nil)
+      query = []
+      query << ["folder", folder] if folder
+      query << ["limit", limit.to_s] if limit
+      query << ["cursor", cursor] if cursor
+      path = "/inboxes/#{Mailcycle.path_segment(address_id)}/messages"
+      result = Wire.object(@client.http.request("GET", path, query: query))
+      MessagePage.new(messages: Wire.array(result["messages"]).map { |item| Mail.to_message(@client.keys, item) },
+                      next_cursor: Wire.maybe_text(result["nextCursor"]))
+    end
+
+    # Every message in a folder, walking the pages.
+    def all(address_id, folder: nil)
+      out = []
+      cursor = nil
+      loop do
+        page = list(address_id, folder: folder, limit: 100, cursor: cursor)
+        out.concat(page.messages)
+        cursor = page.next_cursor
+        return out if cursor.nil?
+      end
+    end
+
+    def get(message_id)
+      result = @client.http.request("GET", "/messages/#{Mailcycle.path_segment(message_id)}")
+      Mail.to_message(@client.keys, Wire.object(result)["message"])
+    end
+
+    # The attachment's bytes, opened on this machine. Needs the phrase.
+    def attachment(message, index)
+      keys = @client.require_keys("open an attachment")
+      path = "/messages/#{Mailcycle.path_segment(message.id)}/attachments/#{Integer(index)}"
+      data = @client.http.request_bytes("GET", path)
+      Mail.open_attachment_bytes(keys, message.address_id, message.id, index, data, epoch: message.key_epoch)
+    end
+
+    def mark_read(message_id, read = true) # rubocop:disable Style/OptionalBooleanParameter
+      post(message_id, "read", { "read" => read })
+    end
+
+    def star(message_id, starred = true) # rubocop:disable Style/OptionalBooleanParameter
+      post(message_id, "star", { "starred" => starred })
+    end
+
+    # Moves to `inbox`, `junk` or `trash`, or `restore` to put it back.
+    def move_to(message_id, folder)
+      post(message_id, "move", { "folder" => folder })
+    end
+
+    def delete(message_id)
+      @client.http.request("DELETE", "/messages/#{Mailcycle.path_segment(message_id)}")
+      nil
+    end
+
+    def empty_trash
+      Wire.count(Wire.object(@client.http.request("POST", "/messages/empty-trash", body: {}))["deleted"])
+    end
+
+    # Sends mail from an address on this account.
+    #
+    # `reply_to` is a Message to reply to, and the threading headers are
+    # filled in from it. `attachments` are up to ten OutgoingAttachment, 3.5 MB
+    # between them.
+    #
+    # Returns a SendResult: the Message-ID the sending service gave it, and
+    # the id of the copy kept in Sent.
+    def send(from:, to:, subject:, text:, html: nil, from_name: nil, reply_to: nil, attachments: [])
+      body = { "from" => from, "to" => to, "subject" => subject, "text" => text }
+      body["html"] = html if html
+      body["fromName"] = from_name if from_name
+      if reply_to
+        body["inReplyTo"] = reply_to.id
+        body["inReplyToHeader"] = reply_to.message_id unless reply_to.message_id.to_s.empty?
+      end
+      body["attachments"] = attachments_body(attachments) unless attachments.empty?
+      result = Wire.object(@client.http.request("POST", "/messages/send", body: body))
+      SendResult.new(message_id: Wire.text(result["messageId"]), sent_copy_id: Wire.maybe_text(result["sentCopyId"]))
+    end
+
+    # The next message that arrives and matches, opened.
+    #
+    # - `address_id`: only mail to this address. Needed when the stream is
+    #   unavailable.
+    # - `from`: only mail whose From contains this, case-insensitive.
+    # - `subject`: only mail whose subject contains this, case-insensitive.
+    # - `timeout`, `poll_every` and `stream_open` are seconds: how long to
+    #   wait in all, how often to check when polling, and how long to give the
+    #   stream to come up before polling instead.
+    # - `since`: counts mail received from this time on, including mail that
+    #   arrived before the stream was up. Defaults to when `wait_for` is
+    #   called; set it to just before a send to wait for the reply. Five
+    #   seconds are allowed for the difference between this clock and the
+    #   server's.
+    #
+    # Listens on the event stream, and polls `address_id` where the stream
+    # will not open. Raises an ApiError with code `timeout` if nothing arrives
+    # in time.
+    def wait_for(address_id: nil, from: nil, subject: nil, timeout: 60, poll_every: 5,
+                 stream_open: STREAM_OPEN_SECONDS, since: nil)
+      wanted = { address_id: address_id, from: from, subject: subject, since: since || Time.now }
+      deadline = monotonic + timeout
+
+      found = wait_on_stream(wanted, deadline, stream_open)
+      return found if found
+      raise ApiError.new(0, "timeout", "No matching mail arrived in time.") if monotonic >= deadline
+
+      wait_by_polling(wanted, deadline, poll_every)
+    end
+
+    private
+
+    def post(message_id, action, body)
+      @client.http.request("POST", "/messages/#{Mailcycle.path_segment(message_id)}/#{action}", body: body)
+      nil
+    end
+
+    def attachments_body(attachments)
+      if attachments.length > MAX_ATTACHMENTS
+        raise ApiError.new(0, "too_many_attachments",
+                           "A message can have at most #{MAX_ATTACHMENTS} attachments.")
+      end
+      files = attachments.map { |file| file.is_a?(Hash) ? OutgoingAttachment.new(**file) : file }
+      if files.sum { |file| file.content.to_s.bytesize } > MAX_ATTACHMENT_BYTES
+        raise ApiError.new(0, "attachments_too_large", "Attachments can add up to 3.5 MB per message.")
+      end
+
+      files.map do |file|
+        item = { "filename" => file.filename, "content" => Encoding.to_b64(file.content.to_s) }
+        item["mimeType"] = file.mime_type if file.mime_type
+        item["contentId"] = file.content_id if file.content_id
+        item
+      end
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def matches?(wanted, message)
+      return false if wanted[:address_id] && message.address_id != wanted[:address_id]
+      if wanted[:from] && !"#{message.from_name} #{message.from_address}".downcase.include?(wanted[:from].downcase)
+        return false
+      end
+      return false if wanted[:subject] && !message.subject.downcase.include?(wanted[:subject].downcase)
+
+      true
+    end
+
+    # Whether the message arrived at or after `since`, less the clock skew.
+    def received_since?(message, since)
+      Time.iso8601(message.received_at.to_s) >= since - CLOCK_SKEW_SECONDS
+    rescue ArgumentError
+      false
+    end
+
+    # A message that arrived since the wait's `since` and matches.
+    def fresh?(wanted, message)
+      received_since?(message, wanted[:since]) && matches?(wanted, message)
+    end
+
+    # Watches the event stream until the deadline, or gives up early.
+    #
+    # nil means "not on the stream": either it was never available, or the
+    # server ended it for good, in which case the caller falls back to polling
+    # rather than failing. Only the deadline is fatal.
+    def wait_on_stream(wanted, deadline, stream_open)
+      begin
+        stream = @client.events.stream
+      rescue Error
+        return nil
+      end
+
+      begin
+        # Connecting is retried in the background forever, so a stream that
+        # cannot open is indistinguishable from a quiet one. Give it a few
+        # seconds and then go and poll instead.
+        opening = [stream_open, deadline - monotonic].min
+        return nil if opening <= 0 || !stream.wait_until_open(opening) || stream.ended?
+
+        # Mail that landed before the stream was up raised no event this
+        # stream saw, so look for it once now.
+        if wanted[:address_id]
+          begin
+            found = list(wanted[:address_id], limit: 50).messages.find { |message| fresh?(wanted, message) }
+            return found if found
+          rescue Error
+            nil
+          end
+        end
+
+        loop do
+          remaining = deadline - monotonic
+          return nil if remaining <= 0
+
+          # nil is the deadline, or a stream that ended and will not come back.
+          event = stream.next_event(timeout: remaining)
+          return nil if event.nil?
+          next unless event.event_type == "message.received"
+          next if wanted[:address_id] && event.payload["inboxId"] != wanted[:address_id]
+
+          begin
+            message = get(Wire.text(event.payload["messageId"]))
+            return message if matches?(wanted, message)
+          rescue Error
+            # A message that would not fetch is not a reason to give up on the
+            # wait; polling is the documented fallback.
+            next
+          end
+        end
+      ensure
+        stream.close
+      end
+    end
+
+    def wait_by_polling(wanted, deadline, poll_every)
+      address_id = wanted[:address_id]
+      if address_id.nil?
+        raise UnsupportedError,
+              "The event stream is not available here. Pass address_id to wait by polling instead."
+      end
+
+      # One look back, for mail that landed between `since` and now.
+      first = list(address_id, limit: 50).messages
+      found = first.find { |message| fresh?(wanted, message) }
+      return found if found
+
+      # Then only what is newer than the newest seen: each message read is
+      # metered, and asking for the page again every few seconds spent a small
+      # plan's hourly reads in minutes while nothing arrived.
+      top = first.first
+      newest = top && "#{top.received_at}~#{top.id}"
+      loop do
+        remaining = deadline - monotonic
+        raise ApiError.new(0, "timeout", "No matching mail arrived in time.") if remaining <= 0
+
+        sleep([poll_every, remaining].min)
+        query = [["inboxIds", address_id], %w[folder inbox], %w[limit 50]]
+        query << ["newer", newest] if newest
+        result = Wire.object(@client.http.request("GET", "/messages", query: query))
+        arrived = Wire.array(result["messages"]).map { |item| Mail.to_message(@client.keys, item) }
+        next if arrived.empty?
+
+        newest = "#{arrived.first.received_at}~#{arrived.first.id}"
+        # Oldest first, so the first match is the first to arrive.
+        found = arrived.reverse.find { |message| matches?(wanted, message) }
+        return found if found
+      end
+    end
+  end
+
+  # Paired devices and AI agents. Pairing and handing over keys are in
+  # pairing.rb.
+  class Devices
+    def initialize(client)
+      @client = client
+    end
+
+    def list
+      out = []
+      cursor = nil
+      loop do
+        query = [%w[limit 200]]
+        query << ["cursor", cursor] if cursor
+        page = Wire.object(@client.http.request("GET", "/workers", query: query))
+        out.concat(Wire.array(page["workers"]).map { |item| to_device(item) })
+        cursor = Wire.maybe_text(page["nextCursor"])
+        return out if cursor.nil?
+      end
+    end
+
+    def get(device_id)
+      to_device(Wire.object(@client.http.request("GET", worker_path(device_id)))["worker"])
+    end
+
+    private
+
+    def to_device(wire)
+      wire = Wire.object(wire)
+      id = Wire.text(wire["id"])
+      profile = Vault.open_or_empty(@client.keys, Pairing::WORKER_RECORD, id, wire["profile"])
+      Device.new(
+        id: id,
+        platform: Wire.text(wire["platform"]),
+        kind: Wire.text(wire["kind"], "device"),
+        send_mode: Wire.text(wire["sendMode"], "full"),
+        status: Wire.text(wire["status"]),
+        created_at: Wire.text(wire["createdAt"]),
+        last_active_at: Wire.maybe_text(wire["lastActiveAt"]),
+        paused_at: Wire.maybe_text(wire["pausedAt"]),
+        name: Wire.maybe_text(profile["name"]),
+        tags: Wire.strings(profile["tags"])
+      )
+    end
+
+    def worker_path(device_id)
+      "/workers/#{Mailcycle.path_segment(device_id)}"
+    end
+  end
+
+  # Domains the account can create addresses on.
+  class Domains
+    def initialize(client)
+      @client = client
+    end
+
+    def list
+      Wire.array(Wire.object(@client.http.request("GET", "/domains"))["domains"]).map { |d| Domain.from_wire(d) }
+    end
+  end
+
+  # The live event stream.
+  class Events
+    def initialize(client)
+      @client = client
+    end
+
+    # Every account event as it happens. Sessions on any plan; API keys on
+    # Operator and up. See EventStream for the hooks.
+    def stream(on_reconnect: nil, on_error: nil)
+      token = @client.session_token
+      raise UnsupportedError, "Sign in first." if token.nil?
+
+      EventStream.new(@client.http.base_url, token, on_reconnect: on_reconnect, on_error: on_error)
+    end
+  end
+end