mailcycle 0.1.0

data/lib/mailcycle/crypto/primitives.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "securerandom"
+
+module Mailcycle
+  # Mailcycle's encryption, in the order an implementation needs it.
+  #
+  # The scheme is specified in `packages/crypto-vectors/README.md` and pinned by
+  # `packages/crypto-vectors/vectors.json`, which this library's test suite runs
+  # against. Nothing here should be changed without changing that file too.
+  module Crypto
+    # The primitives, borrowed rather than written again.
+    #
+    # The app implements SHA-256, HMAC, PBKDF2, ChaCha20 and X25519 in its own
+    # JavaScript because React Native has no WebCrypto. Ruby does not have that
+    # problem: OpenSSL has every one of them, better tested and faster. What is
+    # written here is only what is specific to Mailcycle, and HKDF-Expand, which
+    # is four lines of HMAC.
+    #
+    # The one thing worth spelling out is ChaCha20. Mailcycle's counter starts
+    # at zero, as RFC 8439 and `src/crypto/chacha20.ts` do. OpenSSL's `chacha20`
+    # takes a 16-byte IV that is the 32-bit little-endian block counter followed
+    # by the 12-byte nonce, so the IV here is four zero bytes and then the nonce.
+    module Primitives
+      NONCE_BYTES = 12
+      KEY_BYTES = 32
+
+      module_function
+
+      def sha256(data)
+        OpenSSL::Digest::SHA256.digest(data)
+      end
+
+      def hmac_sha256(key, message)
+        OpenSSL::HMAC.digest("SHA256", key, message)
+      end
+
+      def pbkdf2_sha256(password, salt, iterations, length)
+        OpenSSL::KDF.pbkdf2_hmac(password, salt: salt, iterations: iterations, length: length, hash: "SHA256")
+      end
+
+      # HKDF-Expand-SHA256 (RFC 5869), with `prk` used as it is: no extract
+      # step. nil for a length outside 1 to 8160 bytes, or a PRK shorter than
+      # the hash, which the RFC rules out.
+      def hkdf_expand(prk, info, length)
+        return nil unless length.is_a?(Integer) && length.between?(1, 255 * 32)
+        return nil if prk.bytesize < 32
+
+        out = +"".b
+        block = "".b
+        counter = 1
+        while out.bytesize < length
+          block = hmac_sha256(prk, block + info.b + [counter].pack("C"))
+          out << block
+          counter += 1
+        end
+        out.byteslice(0, length)
+      end
+
+      def constant_time_equal(left, right)
+        left = left.b
+        right = right.b
+        return false unless left.bytesize == right.bytesize
+
+        OpenSSL.fixed_length_secure_compare(left, right)
+      end
+
+      # RFC 8439 ChaCha20, counter from zero. The same call decrypts.
+      def chacha20(key, nonce, data)
+        raise ArgumentError, "ChaCha20 key must be 32 bytes" unless key.bytesize == KEY_BYTES
+        raise ArgumentError, "ChaCha20 nonce must be 12 bytes" unless nonce.bytesize == NONCE_BYTES
+        return "".b if data.empty?
+
+        cipher = OpenSSL::Cipher.new("chacha20")
+        cipher.encrypt
+        cipher.key = key
+        cipher.iv = "\x00\x00\x00\x00".b + nonce.b
+        cipher.update(data.b) + cipher.final
+      end
+
+      # The X25519 public half. The scalar is clamped, so any 32 bytes work.
+      def public_key_from(private_key)
+        OpenSSL::PKey.new_raw_private_key("X25519", private_key.b).raw_public_key
+      end
+
+      # X25519.
+      #
+      # Returns all zeroes where the public key had small order and contributed
+      # nothing; OpenSSL refuses to derive that at all, and the refusal is
+      # reported the same way. Every caller here checks the result before using
+      # it, because encrypting under a shared secret the other side already
+      # knows is the difference between encrypting and appearing to.
+      def shared_secret(private_key, public_key)
+        mine = OpenSSL::PKey.new_raw_private_key("X25519", private_key.b)
+        theirs = OpenSSL::PKey.new_raw_public_key("X25519", public_key.b)
+        mine.derive(theirs)
+      rescue OpenSSL::PKey::PKeyError
+        ("\x00" * 32).b
+      end
+
+      def all_zero?(data)
+        data.each_byte.all?(&:zero?)
+      end
+
+      # Bytes from the operating system's CSPRNG.
+      #
+      # A failure here is not recoverable and must never be papered over with
+      # a weaker source: a predictable nonce or ephemeral key would break the
+      # encryption while leaving it looking like it worked.
+      def random_bytes(length)
+        SecureRandom.random_bytes(length)
+      end
+    end
+  end
+end

data/lib/mailcycle/crypto/sealed_box.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Mailcycle
+  module Crypto
+    # Sealing to a public key: how inbound mail reaches an address the server
+    # cannot read.
+    #
+    # Ephemeral-static ECDH, in the shape of a NaCl sealed box:
+    #
+    #   shared  = X25519(ephemeral_private, recipient_public)
+    #   secret  = HMAC(shared, transcript | "/enc") | HMAC(shared, transcript | "/mac")
+    #   box     = ChaCha20(secret[0..32], nonce, plaintext)
+    #             + HMAC(secret[32..64], nonce | ciphertext | aad)
+    #
+    # where `transcript` is `"mailcycle/v1/seal-to-public" | shared |
+    # ephemeral_public | recipient_public`. Binding both public keys is what
+    # stops a box sealed to one address being replayed as one sealed to
+    # another. The raw curve output is never used as a key: it is a point, not
+    # uniform bytes, which is what the HMAC step fixes.
+    #
+    # It is NOT forward secrecy. The recipient's key is
+    # `subkey(vault_key, "inbox-sealing/...")`: deterministic, permanent, and
+    # re-derivable from the recovery phrase for as long as that phrase exists.
+    # Anyone who ever obtains the phrase can decrypt every message ever sealed
+    # to that address, including ones captured years earlier. There is no
+    # ratchet and no key rotation.
+    #
+    # It also does NOT authenticate the sender. Anyone holding the address's
+    # public key can seal to it, which is what an email address is. A
+    # successful open says the ciphertext is intact, never who wrote it.
+    module SealedBoxes
+      DOMAIN = "mailcycle/v1/seal-to-public"
+
+      # A sealed box in raw bytes. Callers choose how to encode it.
+      RawSealedBox = Struct.new(:ephemeral_public_key, :nonce, :ciphertext, :tag, keyword_init: true)
+
+      module_function
+
+      def derive_secret(shared, ephemeral_public, recipient_public)
+        transcript = DOMAIN.b + shared.b + ephemeral_public.b + recipient_public.b
+        Primitives.hmac_sha256(shared, transcript + "/enc".b) + Primitives.hmac_sha256(shared, transcript + "/mac".b)
+      end
+      private_class_method :derive_secret
+
+      # Seals to a public key.
+      #
+      # Randomness is a parameter so the test vectors can pin it; everywhere
+      # else it is the operating system's CSPRNG.
+      def seal_raw(recipient_public_key, plaintext, aad, version, random: Primitives.method(:random_bytes))
+        unless recipient_public_key.bytesize == Primitives::KEY_BYTES
+          raise UnsupportedError, "Recipient public key must be 32 bytes."
+        end
+
+        ephemeral_private = random.call(Primitives::KEY_BYTES)
+        unless ephemeral_private.bytesize == Primitives::KEY_BYTES
+          raise UnsupportedError, "Random source returned short."
+        end
+
+        ephemeral_public = Primitives.public_key_from(ephemeral_private)
+        shared = Primitives.shared_secret(ephemeral_private, recipient_public_key)
+        # All zero means the recipient key had small order and contributed
+        # nothing. Refusing here is the difference between encrypting and
+        # appearing to.
+        raise UnsupportedError, "Recipient public key is not usable." if Primitives.all_zero?(shared)
+
+        secret = derive_secret(shared, ephemeral_public, recipient_public_key.b)
+        nonce = random.call(Primitives::NONCE_BYTES)
+        ciphertext = Primitives.chacha20(secret.byteslice(0, 32), nonce, plaintext)
+        tag = Primitives.hmac_sha256(secret.byteslice(32, 32), Cipher.mac_input(nonce, ciphertext, aad, version))
+        RawSealedBox.new(ephemeral_public_key: ephemeral_public, nonce: nonce, ciphertext: ciphertext, tag: tag)
+      end
+
+      def open_raw(private_key, box, aad, version)
+        unless private_key.bytesize == Primitives::KEY_BYTES &&
+               box.ephemeral_public_key.bytesize == Primitives::KEY_BYTES &&
+               box.nonce.bytesize == Primitives::NONCE_BYTES
+          raise DecryptionError
+        end
+
+        shared = Primitives.shared_secret(private_key, box.ephemeral_public_key)
+        raise DecryptionError if Primitives.all_zero?(shared)
+
+        secret = derive_secret(shared, box.ephemeral_public_key.b, Primitives.public_key_from(private_key))
+        expected = Primitives.hmac_sha256(secret.byteslice(32, 32),
+                                          Cipher.mac_input(box.nonce, box.ciphertext, aad, version))
+        # Verify before decrypting. Never act on unauthenticated ciphertext.
+        raise DecryptionError unless Primitives.constant_time_equal(expected, box.tag)
+
+        Primitives.chacha20(secret.byteslice(0, 32), box.nonce, box.ciphertext)
+      end
+    end
+  end
+end

data/lib/mailcycle/crypto/wordlist.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Mailcycle
+  module Crypto
+    # Mailcycle recovery-phrase wordlist.
+    #
+    # 2048 words, 11 bits each, so a twelve-word phrase carries 128 bits of
+    # entropy plus a 4-bit checksum. The same construction as BIP-39 but NOT
+    # BIP-39's list: every word here is 3-8 lowercase ASCII letters and no two
+    # share their first four, so a phrase survives being written down in a hurry.
+    #
+    # Frozen. A word's index is its value, so reordering, replacing or appending
+    # an entry invalidates every phrase ever generated from it. Kept identical to
+    # `src/crypto/wordlist.ts` in the app.
+    module Wordlist
+      # The list, in the order that gives each word its value.
+      WORDS = %w[
+        able about above absent absorb abstract accent accident account accuse ache achieve acid acorn
+        acquire across action actor actual adapt addict address adjust admit adopt adult advance
+        advice affair afford afraid after again agent agree ahead aim air alarm album alert alien
+        align alike alive allow almost alone alpha already also alter always amateur amazing amber
+        ambush among amount ample amused anchor ancient anger angle angry animal ankle announce annual
+        another answer antenna antique anxiety any apart apology appear apple april arch arctic area
+        arena argue arise armed armor army around arrange arrest arrive arrow art artist artwork
+        ashamed aside ask aspect asphalt assault asset assist assume asthma athlete atlas atom attack
+        attend attitude attract auction audit august aunt author auto autumn average avocado avoid
+        awake aware away awesome awful awkward axis baby bachelor bacon badge bag balance balcony ball
+        bamboo banana banner bar barely bargain barrel base basic basket battle beach bean beauty
+        because become beef before begin behave behind believe below belt bench benefit berry best
+        betray better between beyond bicycle bid bike bind biology birch bird birth bitter black blade
+        blame blanket blast bleak bless blind blood blossom blouse blue blur blush board boat body
+        boil bomb bone bonus book boost border boring borrow boss bottom bounce box boy bracket brain
+        brand brass brave bread breeze brick bridge brief bright bring brisk broccoli broken bronze
+        broom brother brown brush bubble buddy budget buffalo build bulb bulk bullet bundle bunker
+        burden burger burst bus business busy butter buyer buzz cabbage cabin cable cactus cage cake
+        call calm camera camp canal cancel candy cannon canoe canvas canyon capable capital captain
+        carbon card cargo carpet carry cart case cash casino castle casual cat catalog catch cattle
+        caught cause caution cave cedar ceiling celery cement census century cereal certain chair
+        chalk champion change chaos chapter charge chase chat cheap check cheese chef cherry chest
+        chicken chief child chimney choice choose chronic chuckle chunk churn cigar cinnamon circle
+        citizen city civil claim clap clarify claw clay clean clerk clever click client cliff climb
+        clinic clip clock clog close cloth cloud clown club clump cluster clutch coach coast coconut
+        code coffee coil coin collect color column combine come comfort comic common company concert
+        conduct confirm congress connect consider control convince cook cool copper copy coral core
+        corn correct cost cotton couch country couple course cousin cover coyote crack cradle craft
+        cram crane crash crater crawl crazy cream credit creek crew cricket crime crisp critic crop
+        cross crouch crowd crucial cruel cruise crumble crunch crush cry crystal cube culture cup
+        curious current curtain curve cushion custom cute cycle dad damage damp dance danger daring
+        dash daughter dawn day deal debate debris decade december decide decline decorate decrease
+        deer defense define defy degree delay deliver demand demise denial dentist deny depart depend
+        deposit depth deputy derive describe desert design desk despair destroy detail detect develop
+        device devote diagram dial diamond diary dice diesel diet differ digital dignity dilemma
+        dinner dinosaur direct dirt disagree discover disease dish dismiss disorder display distance
+        divert divide divorce dizzy doctor document dog doll dolphin domain donate donkey donor door
+        dose double dove draft dragon drama drastic draw dream dress drift drill drink drip drive drop
+        drum dry duck dumb dune during dust dutch duty dwarf dynamic eager eagle early earn earth
+        easily east easy echo ecology economy edge edit educate effort egg eight either elbow elder
+        electric elegant element elephant elevator elite else embark embody embrace emerge emotion
+        employ empower empty enable enact end endless endorse enemy energy enforce engage engine
+        enhance enjoy enlist enough enrich enroll ensure enter entire entry envelope episode equal
+        equip era erase erode erosion error erupt escape essay essence estate eternal ethics evidence
+        evil evoke evolve exact example excess exchange excite exclude excuse execute exercise exhaust
+        exhibit exile exist exit exotic expand expect expire explain expose express extend extra eye
+        eyebrow fabric face faculty fade faint faith fall false fame family famous fan fancy fantasy
+        farm fashion fat fatal father fatigue fault favorite feature february federal fee feed feel
+        female fence fern festival fetch fever few fiber fiction field figure file film filter final
+        find fine finger finish fire firm first fiscal fish fit fitness fix flag flame flash flat
+        flavor flee flight flip float flock floor flower fluid flush fly foam focus fog foil fold
+        follow food foot force forest forget fork fortune forum forward fossil foster found fox
+        fragile frame frequent fresh friend fringe frog front frost frown frozen fruit fuel fun funny
+        furnace fury future gadget gain galaxy gallery game gap garage garbage garden garlic garment
+        gas gasp gate gather gauge gaze general genius genre gentle genuine gesture ghost giant gift
+        giggle ginger giraffe girl give glad glance glare glass glide glimpse globe gloom glory glove
+        glow glue goat goddess gold good goose gorilla gospel gossip govern gown grab grace grain
+        grant grape grass gravity great green grid grief grit grocery group grow grunt guard guess
+        guide guilt guitar gun gym habit hair half hammer hamster hand happy harbor hard harsh harvest
+        hat have hawk hazard head health heart heavy hedgehog height hello helmet help hen hero hidden
+        high hill hint hip hire history hobby hockey hold hole holiday hollow home honey hood hope
+        horn horror horse hospital host hotel hour hover hub huge human humble humor hundred hungry
+        hunt hurdle hurry hurt husband hybrid ice icon idea identify idle ignore ill illegal illness
+        image imitate immense immune impact impose improve impulse inch include income increase index
+        indicate indoor industry infant inflict inform inhale inherit initial inject injury inmate
+        inner innocent input inquiry insane insect inside inspire install intact interest into invest
+        invite involve iron island isolate issue item ivory ivy jacket jaguar jar jazz jealous jeans
+        jelly jewel job join joke journey joy judge juice jump jungle junior junk just kangaroo keen
+        keep ketchup key kick kid kidney kind kingdom kiss kit kitchen kite kitten kiwi knee knife
+        knock know lab label labor ladder lady lake lamp language laptop large later latin laugh
+        laundry lava law lawn lawsuit layer lazy leader leaf learn leave lecture left leg legal legend
+        leisure lemon lend length lens leopard lesson letter level liar liberty library license life
+        lift light like limb limit link lion liquid list little live lizard load loan lobster local
+        lock logic lonely long loop lottery loud lounge love loyal lucky luggage lumber lunar lunch
+        luxury lyrics machine mad magic magnet maid mail main major make mammal man manage mandate
+        mango mansion manual maple marble march margin marine market marriage mask mass master match
+        material math matrix matter maximum maze meadow mean measure meat mechanic medal media melody
+        melt member memory mention menu mercy merge merit merry mesh message metal method middle
+        midnight milk million mimic mind minimum minor minute miracle mirror misery miss mistake mix
+        mixed mixture mobile model modify mom moment monitor monkey monster month moon moral more
+        morning mosquito moss mother motion motor mountain mouse move movie much muffin mule multiply
+        muscle museum mushroom music must mutual myself mystery myth naive name napkin narrow nasty
+        nation nature near neck need negative neglect neither nephew nerve nest net network neutral
+        never news next nice night noble noise nominee noodle normal north nose notable note nothing
+        notice novel now nuclear number nurse nut oak obey object oblige obscure observe obtain
+        obvious occur ocean october odor off offer office often oil okay old olive olympic omit once
+        one onion online only open opera opinion oppose option orange orbit orchard order ordinary
+        organ orient original orphan ostrich other outdoor outer output outside oval oven over own
+        owner oxygen oyster ozone pact paddle page pair palace palm panda panel panic panther paper
+        parade parent park parrot party pass patch path patient patrol pattern pause pave payment
+        peace peanut pear peasant pelican pen penalty pencil people pepper perfect permit person pet
+        phone photo phrase physical piano picnic picture piece pig pigeon pill pilot pink pioneer pipe
+        pistol pitch pizza place planet plastic plate play please pledge pluck plug plum plunge poem
+        poet point polar pole police pond pony pool popular portion position possible post potato
+        pottery poverty powder power practice praise predict prefer prepare present pretty prevent
+        price pride primary print priority prison private prize problem process produce profit program
+        project promote proof property prosper protect proud provide public pudding pull pulp pulse
+        pumpkin punch pupil puppy purchase purity purpose purse push put puzzle pyramid quality
+        quantum quarter question quick quiet quit quiz quote rabbit raccoon race rack radar radio rail
+        rain raise rally ramp ranch random range rapid rare rate rather raven raw razor ready real
+        reason rebel rebuild recall receive recipe record recycle reduce reflect reform refuse region
+        regret regular reject relax release relief rely remain remember remind remove render renew
+        rent reopen repair repeat replace report require rescue resemble resist resource response
+        result retire retreat return reunion reveal review reward rhythm rib ribbon rice rich ride
+        ridge rifle right rigid ring riot ripple risk ritual rival river road roast robot robust
+        rocket romance roof rookie room rose rotate rough round route royal rubber rude rug rule run
+        runway rural sad saddle sadness safe sail salad salmon salon salt salute same sample sand
+        satisfy satoshi sauce sausage save say scale scan scare scatter scene scheme school science
+        scissors scorpion scout scrap screen script scrub sea search season seat second secret section
+        security seed seek segment select sell seminar senior sense sentence series service session
+        settle setup seven shadow shaft shallow share shed shell sheriff shield shift shine ship
+        shiver shock shoe shoot shop short shoulder shove shrimp shrug shuffle shy sibling sick side
+        siege sight sign silent silk silly silver similar simple since sing siren sister situate six
+        size skate sketch ski skill skin skirt skull slab slam sleep slender slice slide slight slim
+        slogan slot slow slush small smart smile smoke smooth snack snake snap sniff snow soap soccer
+        social sock soda soft solar soldier solid solution solve someone song soon sorry sort soul
+        sound soup source south space spare spatial spawn speak special speed spell spend sphere spice
+        spider spike spin spirit split spoil sponsor spoon sport spot spray spread spring spy square
+        squeeze squirrel stable stadium staff stage stairs stamp stand start state stay steak steel
+        stem step stereo stick still sting stock stomach stone stool story stove strategy street
+        strike strong struggle student stuff stumble style subject submit subway success such sudden
+        suffer sugar suggest suit summer sun sunny sunset super supply supreme sure surface surge
+        surprise surround survey suspect sustain swallow swamp swap swarm swear sweet swift swim swing
+        switch sword symbol symptom syrup system table tackle tag tail talent talk tank tape target
+        task taste tattoo taxi teach team tell ten tenant tennis tent term test text thank that theme
+        then theory there they thing this thought three thrive throw thumb thunder ticket tide tiger
+        tilt timber time tiny tip tired tissue title toast tobacco today toddler toe together toilet
+        token tomato tomorrow tone tongue tonight tool tooth top topic topple torch tornado tortoise
+        toss total tourist toward tower town toy track trade traffic tragic train transfer trap trash
+        travel tray treat tree trend trial tribe trick trigger trim trip trophy trouble truck true
+        truly trumpet trust truth try tube tuition tumble tuna tunnel turkey turn turtle twelve twenty
+        twice twin twist two type typical ugly umbrella unable unaware uncle uncover under undo unfair
+        unfold unhappy uniform unique unit universe unknown unlock until unusual unveil update upgrade
+        uphold upon upper upset urban urge usage use used useful useless usual utility vacant vacuum
+        vague valid valley valve van vanish vapor various vast vault vehicle velvet vendor venture
+        venue verb verify version very vessel veteran viable vibrant vicious victory video view
+        village vintage violin virtual virus visa visit visual vital vivid vocal voice void volcano
+        volume vote voyage wage wagon wait walk wall walnut want warfare warm warrior wash wasp waste
+        water wave way wealth weapon wear weasel weather web wedding weekend weird welcome west wet
+        whale what wheat wheel when where whip whisper wide width wife wild will win window wine wing
+        wink winner winter wire wisdom wise wish witness wolf woman wonder wood wool word work world
+        worry worth wrap wreck wrestle wrist write wrong yard year yellow you young youth zebra zero
+        zone zoo
+      ].map(&:freeze).freeze
+
+      INDEX = WORDS.each_with_index.to_h.freeze
+
+      # The index of a word, or nil if it is not in the list.
+      def self.index_of(word)
+        INDEX[word]
+      end
+    end
+  end
+end

data/lib/mailcycle/encoding.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Mailcycle
+  # base64url without padding, decoded strictly.
+  #
+  # The permissive decoders accept several spellings of the same bytes, which
+  # matters here: these strings are compared, stored and fed to a MAC, and a
+  # server picks how they are spelled. So unknown characters are an error,
+  # padding is an error, a length that cannot come from whole bytes is an
+  # error, and the unused low bits of the final character must be zero. This is
+  # `fromBase64Url` in the app's `src/crypto/bytes.ts`, rule for rule.
+  #
+  # Every function here takes and returns binary strings for bytes.
+  module Encoding
+    ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"
+    STANDARD_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
+    VALUES = ALPHABET.each_char.with_index.to_h { |char, index| [char.ord, index] }.freeze
+    private_constant :VALUES
+
+    module_function
+
+    def encode(data, alphabet, pad)
+      bytes = data.b.bytes
+      out = +""
+      bytes.each_slice(3) do |chunk|
+        n = (chunk[0] << 16) | ((chunk[1] || 0) << 8) | (chunk[2] || 0)
+        take = chunk.length + 1
+        take.times { |i| out << alphabet[(n >> (18 - (6 * i))) & 0x3f] }
+        (4 - take).times { out << "=" } if pad
+      end
+      out
+    end
+    private_class_method :encode
+
+    # Bytes to base64url, unpadded.
+    def to_b64u(data)
+      encode(data, ALPHABET, false)
+    end
+
+    # Bytes to standard, padded base64, as a file's content goes to the API.
+    def to_b64(data)
+      encode(data, STANDARD_ALPHABET, true)
+    end
+
+    # base64url to bytes, refusing anything non-canonical.
+    def from_b64u(value)
+      raise Base64UrlError, "unexpected character" unless value.is_a?(String)
+
+      text = value.b
+      # One leftover character cannot encode any whole byte.
+      raise Base64UrlError, "truncated" if text.bytesize % 4 == 1
+
+      out = +"".b
+      buffer = 0
+      bits = 0
+      text.each_byte do |byte|
+        index = VALUES[byte]
+        raise Base64UrlError, "unexpected character" if index.nil?
+
+        buffer = (buffer << 6) | index
+        bits += 6
+        next unless bits >= 8
+
+        bits -= 8
+        out << ((buffer >> bits) & 0xff)
+        buffer &= (1 << bits) - 1
+      end
+
+      # Whatever is left is padding bits, and in a canonical encoding they are
+      # zero. Non-zero means two strings would decode to the same bytes.
+      raise Base64UrlError, "non-canonical trailing bits" if bits.positive? && buffer != 0
+
+      out
+    end
+
+    # Eight bytes, big-endian: the additional data's length, in a MAC input.
+    def be64(value)
+      [value].pack("Q>")
+    end
+
+    # Lowercase hex, for a webhook signature.
+    def to_hex(data)
+      data.b.unpack1("H*")
+    end
+
+    # Lowercase hex back to bytes, or nil if it is not exactly that.
+    def from_hex(value)
+      return nil unless value.is_a?(String) && value.bytesize.even? && value.match?(/\A[0-9a-f]*\z/)
+
+      [value].pack("H*")
+    end
+  end
+end

data/lib/mailcycle/errors.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Mailcycle
+  # Every error this library raises.
+  #
+  # One family, so a caller rescues `Mailcycle::Error` once and is done. An API
+  # failure carries the API's own stable `code` (`plan_required`,
+  # `rate_limited`) rather than a message to match on.
+  class Error < StandardError
+    # The API's code, for the failures that have one.
+    def code
+      nil
+    end
+  end
+
+  # A request the API refused, or one that never reached it.
+  class ApiError < Error
+    # The HTTP status, or 0 when the request never got an answer.
+    attr_reader :status
+    # The API's stable, machine-readable code.
+    attr_reader :code
+    # The message as the API wrote it, without the code in front.
+    attr_reader :detail
+
+    def initialize(status, code, message)
+      @status = status
+      @code = code
+      @detail = message
+      super("#{code}: #{message}")
+    end
+  end
+
+  # Data that would not open with the key provided.
+  #
+  # Every way an open can fail arrives as this one, including a box that is not
+  # a box at all. The fields come from a server, so "malformed" is a state the
+  # server can choose, and a reader that crashed on it would let the server
+  # decide that a program fails instead of showing one record as unreadable.
+  class DecryptionError < Error
+    def initialize(message = "This data could not be decrypted with the key provided.")
+      super
+    end
+  end
+
+  # Text that is not canonical base64url.
+  class Base64UrlError < Error
+    def initialize(why)
+      super("Not canonical base64url: #{why}")
+    end
+  end
+
+  # A recovery phrase that is not one. `problem` says why.
+  class PhraseError < Error
+    attr_reader :problem
+
+    def initialize(problem)
+      @problem = problem
+      super(problem.to_s)
+    end
+  end
+
+  # A challenge the server offered that cannot be answered safely.
+  class AuthProofError < Error; end
+
+  # Something the caller asked for that this client cannot do.
+  class UnsupportedError < Error; end
+
+  # Why a recovery phrase was refused.
+  #
+  # `kind` is `:length` (with `count`, how many words there were),
+  # `:unknown_word` (with the `word` and its zero-based `index`), or
+  # `:checksum` (twelve known words that do not agree with their checksum).
+  PhraseProblem = Struct.new(:kind, :count, :word, :index, keyword_init: true) do
+    def to_s
+      case kind
+      when :length then "A recovery phrase is twelve words; this one has #{count}."
+      when :unknown_word then "Word #{index + 1} is not in the list: #{word.inspect}."
+      else "Those twelve words do not check out; one of them is wrong."
+      end
+    end
+  end
+end