mailcycle 0.1.0

data/lib/mailcycle/crypto/asymmetric.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Mailcycle
+  module Crypto
+    # The wire shape the mail server writes into a message's content.
+    AsymmetricBox = Struct.new(:v, :epk, :n, :c, :t, keyword_init: true) do
+      # The box a wire value describes, or nil if it is not one.
+      def self.from_wire(value)
+        return nil unless value.is_a?(Hash)
+
+        fields = value.values_at("epk", "n", "c", "t")
+        return nil unless fields.all?(String)
+
+        version = value.fetch("v", 1)
+        return nil unless version.is_a?(Integer) && version.between?(0, 255)
+
+        epk, n, c, t = fields
+        new(v: version, epk: epk, n: n, c: c, t: t)
+      end
+
+      def version
+        v == 2 ? 2 : 1
+      end
+
+      def to_wire
+        { "v" => v, "epk" => epk, "n" => n, "c" => c, "t" => t }
+      end
+
+      def to_json(*args)
+        to_wire.to_json(*args)
+      end
+    end
+
+    # The wire shapes around SealedBoxes: the JSON box the API stores for a
+    # message, and the fixed-width framing an attachment body uses in object
+    # storage.
+    module Asymmetric
+      # "MCA1" and "MCA2": Mailcycle attachment, by version. The layout is the
+      # same; the magic is the only thing that says whether the MAC framed the
+      # additional data.
+      MAGIC_V1 = "MCA1".b
+      MAGIC_V2 = "MCA2".b
+      ATTACHMENT_HEADER = 4 + Primitives::KEY_BYTES + 12 + 32
+
+      module_function
+
+      def seal_to_public_key(recipient_public_key, plaintext, aad, version = Cipher::SEAL_VERSION)
+        box = SealedBoxes.seal_raw(recipient_public_key, plaintext, aad, version)
+        AsymmetricBox.new(
+          v: version,
+          epk: Mailcycle::Encoding.to_b64u(box.ephemeral_public_key),
+          n: Mailcycle::Encoding.to_b64u(box.nonce),
+          c: Mailcycle::Encoding.to_b64u(box.ciphertext),
+          t: Mailcycle::Encoding.to_b64u(box.tag)
+        )
+      end
+
+      def open_with_private_key(private_key, box, aad)
+        SealedBoxes.open_raw(private_key, decode(box), aad, box.version)
+      end
+
+      def open_json_with_private_key(private_key, box, aad)
+        Crypto.parse_json(open_with_private_key(private_key, box, aad))
+      end
+
+      def decode(box)
+        epk, nonce, ciphertext, tag = [box.epk, box.n, box.c, box.t].map { |f| Mailcycle::Encoding.from_b64u(f) }
+        SealedBoxes::RawSealedBox.new(ephemeral_public_key: epk, nonce: nonce, ciphertext: ciphertext, tag: tag)
+      rescue Base64UrlError
+        raise DecryptionError
+      end
+      private_class_method :decode
+
+      # Opens mail the mail server sealed for one address.
+      #
+      # The additional data is the address id AND the message id, matching
+      # what the server seals with. The address binding stops a ciphertext
+      # being moved between mailboxes; the message binding stops it being
+      # replayed within one. Without the second, a server holding no key could
+      # re-file an old message as a new arrival.
+      def open_inbound_mail(vault_key, address_id, message_id, box)
+        pair = Identity.address_key_pair(vault_key, address_id)
+        raise DecryptionError if pair.nil?
+
+        open_with_private_key(pair[0], box, "#{address_id}:#{message_id}")
+      end
+
+      # Opens an attachment body.
+      #
+      # Raw bytes rather than JSON, because object storage holds bytes and
+      # base64 would cost a third of the size for nothing. The layout is
+      # fixed-width, so this slices rather than parses:
+      #
+      #   magic(4) | ephemeral public key(32) | nonce(12) | tag(32) | ciphertext
+      #
+      # The additional data is the address id and the object's own key, so an
+      # object served from the wrong row fails the MAC instead of handing back
+      # the wrong file under the right name.
+      def open_attachment_with_key(private_key, address_id, object_key, data)
+        data = data.b
+        raise DecryptionError if data.bytesize < ATTACHMENT_HEADER
+
+        version = case data.byteslice(0, 4)
+                  when MAGIC_V1 then 1
+                  when MAGIC_V2 then 2
+                  else raise DecryptionError
+                  end
+
+        box = SealedBoxes::RawSealedBox.new(
+          ephemeral_public_key: data.byteslice(4, 32),
+          nonce: data.byteslice(36, 12),
+          tag: data.byteslice(48, 32),
+          ciphertext: data.byteslice(ATTACHMENT_HEADER, data.bytesize - ATTACHMENT_HEADER)
+        )
+        SealedBoxes.open_raw(private_key, box, "#{address_id}:#{object_key}", version)
+      end
+
+      def open_attachment(vault_key, address_id, object_key, data)
+        pair = Identity.address_key_pair(vault_key, address_id)
+        raise DecryptionError if pair.nil?
+
+        open_attachment_with_key(pair[0], address_id, object_key, data)
+      end
+    end
+  end
+end

data/lib/mailcycle/crypto/auth_proof.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Mailcycle
+  module Crypto
+    # Proving an account without handing over its secret.
+    #
+    # The account holds an X25519 keypair derived from the seed. Only the
+    # public half is uploaded, once, at account creation. Unlocking is a
+    # challenge-response and the private half never leaves this machine:
+    #
+    # 1. The client asks for a challenge, naming the account id.
+    # 2. The server mints a single-use nonce AND an ephemeral X25519 keypair,
+    #    keeps the private half, and returns the nonce with the public half.
+    # 3. The client computes `X25519(account_private, ephemeral_public)` and
+    #    answers with an HMAC over the nonce under that shared secret.
+    # 4. The server computes `X25519(ephemeral_private, account_public)`, which
+    #    is the same value, and compares in constant time.
+    #
+    # Nothing secret is transmitted in either direction, and the answer is
+    # worthless afterwards because the nonce is consumed and the ephemeral key
+    # discarded.
+    #
+    # What is given up is third-party verifiability: an HMAC under a shared
+    # secret proves possession to THIS server and to nobody else, because the
+    # server can compute the same value. That is the correct shape for a login
+    # and the wrong shape for a signature, so nothing here should ever be
+    # repurposed as one.
+    module AuthProof
+      DOMAIN = "mailcycle/v1/auth-proof"
+      # Confirming the account's erasure, so an unlock proof cannot stand in for it.
+      DELETE_DOMAIN = "mailcycle/v1/delete-proof"
+
+      module_function
+
+      # The answer to a challenge.
+      #
+      # The account id is inside the MAC as well as the nonce, so a proof
+      # captured for one account cannot be presented for another even if a
+      # server reused a nonce across them.
+      def prove_account(account_private_key, ephemeral_public_key_b64u, nonce, account_id, domain = DOMAIN)
+        begin
+          ephemeral_public_key = Mailcycle::Encoding.from_b64u(ephemeral_public_key_b64u)
+        rescue Base64UrlError
+          raise AuthProofError, "The server offered a malformed challenge key."
+        end
+        raise AuthProofError, "The server offered a malformed challenge key." unless ephemeral_public_key.bytesize == 32
+
+        shared = Primitives.shared_secret(account_private_key, ephemeral_public_key)
+        # A server that sent a small-order point would get back a MAC under a
+        # secret it already knows, which proves nothing and would let it accept
+        # anyone.
+        raise AuthProofError, "The server offered an unusable challenge key." if Primitives.all_zero?(shared)
+
+        Mailcycle::Encoding.to_b64u(Primitives.hmac_sha256(shared, "#{domain}:#{nonce}:#{account_id}"))
+      end
+    end
+  end
+end

data/lib/mailcycle/crypto/cipher.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Mailcycle
+  module Crypto
+    # Authenticated encryption: ChaCha20 for confidentiality, HMAC-SHA-256 for
+    # integrity, composed encrypt-then-MAC.
+    #
+    # ChaCha20-Poly1305 would be the textbook pairing. Mailcycle does not use it
+    # because the app's JavaScript cannot implement Poly1305 safely, and the
+    # format is the format everywhere or it is nothing. Encrypt-then-MAC with
+    # HMAC-SHA-256 is provably secure given independent keys, which is why one
+    # 64-byte secret is split into an encryption key and a separate MAC key
+    # rather than used for both.
+    #
+    # Versions:
+    #
+    # 1. The tag covers `nonce | ciphertext | additional data`, which does not
+    #    say where the ciphertext ends, so bytes can be moved across that
+    #    boundary and the tag still verifies.
+    # 2. The additional data's length, eight bytes big-endian, is appended,
+    #    which makes the split unambiguous.
+    #
+    # Every reader must open both. New boxes are written as version 2 since
+    # 2026-09-19.
+    module Cipher
+      # Which version new boxes are written as.
+      SEAL_VERSION = 2
+
+      module_function
+
+      # Splits a 64-byte secret into the two independent keys the scheme needs.
+      def derive_subkeys(secret)
+        raise DecryptionError unless secret.is_a?(String) && secret.bytesize == 64
+
+        [secret.byteslice(0, 32), secret.byteslice(32, 32)]
+      end
+
+      # What the tag covers, which is the only difference between the versions.
+      def mac_input(nonce, ciphertext, aad, version)
+        out = nonce.b + ciphertext.b + aad.b
+        out << Mailcycle::Encoding.be64(aad.bytesize) unless version == 1
+        out
+      end
+
+      def seal(secret, plaintext, aad, version = SEAL_VERSION)
+        encryption, mac = derive_subkeys(secret)
+        nonce = Primitives.random_bytes(Primitives::NONCE_BYTES)
+        ciphertext = Primitives.chacha20(encryption, nonce, plaintext.b)
+        tag = Primitives.hmac_sha256(mac, mac_input(nonce, ciphertext, aad, version))
+        SealedBox.new(v: version, n: Mailcycle::Encoding.to_b64u(nonce),
+                      c: Mailcycle::Encoding.to_b64u(ciphertext), t: Mailcycle::Encoding.to_b64u(tag))
+      end
+
+      def open(secret, box, aad)
+        encryption, mac = derive_subkeys(secret)
+        nonce, ciphertext, tag = decode(box)
+
+        # Shape first, then authenticity, then decrypt. A wrong-length nonce
+        # could not produce a valid tag anyway, but the cheap structural check
+        # belongs before the cryptographic one rather than after it.
+        raise DecryptionError unless nonce.bytesize == Primitives::NONCE_BYTES
+
+        expected = Primitives.hmac_sha256(mac, mac_input(nonce, ciphertext, aad, box.version))
+        # Verify before decrypting. Never act on unauthenticated ciphertext.
+        raise DecryptionError unless Primitives.constant_time_equal(expected, tag)
+
+        Primitives.chacha20(encryption, nonce, ciphertext)
+      end
+
+      def decode(box)
+        [box.n, box.c, box.t].map { |field| Mailcycle::Encoding.from_b64u(field) }
+      rescue Base64UrlError
+        raise DecryptionError
+      end
+      private_class_method :decode
+
+      def seal_json(secret, value, aad, version = SEAL_VERSION)
+        seal(secret, JSON.generate(value), aad, version)
+      end
+
+      # A box whose plaintext is not JSON is unreadable, not a crash.
+      #
+      # That is reachable without the key: in version 1 the MAC does not frame
+      # the boundary between ciphertext and additional data, so a server can
+      # move bytes across it and leave the plaintext malformed.
+      def open_json(secret, box, aad)
+        Crypto.parse_json(Cipher.open(secret, box, aad))
+      end
+    end
+
+    # A sealed payload, in the wire shape the API uses.
+    SealedBox = Struct.new(:v, :n, :c, :t, keyword_init: true) do
+      # The box a wire value describes, or nil if it is not one.
+      def self.from_wire(value)
+        return nil unless value.is_a?(Hash)
+
+        n, c, t = value.values_at("n", "c", "t")
+        return nil unless [n, c, t].all?(String)
+
+        version = value.fetch("v", 1)
+        return nil unless version.is_a?(Integer) && version.between?(0, 255)
+
+        new(v: version, n: n, c: c, t: t)
+      end
+
+      # The version this box says it is.
+      #
+      # A box claiming the wrong one computes a different tag and fails, so
+      # this is not something a server can talk a reader into.
+      def version
+        v == 2 ? 2 : 1
+      end
+
+      def to_wire
+        { "v" => v, "n" => n, "c" => c, "t" => t }
+      end
+
+      def to_json(*args)
+        to_wire.to_json(*args)
+      end
+    end
+
+    # JSON text to a value, or a DecryptionError for anything that is not
+    # UTF-8 JSON.
+    def self.parse_json(bytes)
+      text = bytes.dup.force_encoding(::Encoding::UTF_8)
+      raise DecryptionError unless text.valid_encoding?
+
+      JSON.parse(text)
+    rescue JSON::ParserError
+      raise DecryptionError
+    end
+  end
+end

data/lib/mailcycle/crypto/identity.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Mailcycle
+  module Crypto
+    # Account identity derived from a recovery phrase.
+    #
+    # Everything below comes out of one 64-byte root seed, which never leaves
+    # this machine. The split matters, so it is spelled out rather than left
+    # implicit:
+    #
+    # - `account_id`, public: the ONLY identifier the server learns. An opaque
+    #   hash. It carries no email, no name, no device, and nothing that links
+    #   two accounts to one person.
+    # - `auth_secret`, private: the old proof of possession. Still derived,
+    #   because an account created before the keypair existed was registered
+    #   with its hash.
+    # - `auth_key`, private: the X25519 key that proves this account now. Only
+    #   its public half is ever uploaded, once.
+    # - `vault_key`, private: encrypts mail, address labels and device names.
+    #   Never transmitted in any form. Lose the phrase and the mail is gone;
+    #   nobody at Mailcycle can help.
+    #
+    # The domain-separation strings are part of the format. Changing one
+    # changes every account id and every key derived after it.
+    module Identity
+      LABEL_PREFIX = "mailcycle/v1/"
+      LABEL_PREFIX_V2 = "mailcycle/v2/"
+      MAX_EPOCH = (1 << 31) - 1
+      SAFE_LABEL = /\A[A-Za-z0-9_-]{1,64}\z/
+
+      AccountIdentity = Struct.new(:account_id, :auth_secret, :auth_key, :auth_public_key, :vault_key,
+                                   keyword_init: true) do
+        def inspect
+          # Never the key material, however convenient that would be in a log.
+          "#<Mailcycle::Crypto::Identity::AccountIdentity account_id=#{account_id.inspect}>"
+        end
+        alias_method :to_s, :inspect
+      end
+
+      module_function
+
+      # A labelled subkey of a seed. The labels are part of the format.
+      def subkey(seed, label, length)
+        first = Primitives.hmac_sha256(seed, "#{LABEL_PREFIX}#{label}")
+        return first.byteslice(0, length) if length <= first.bytesize
+
+        second = Primitives.hmac_sha256(seed, "#{LABEL_PREFIX}#{label}/2")
+        (first + second).byteslice(0, length)
+      end
+
+      # A labelled subkey under the version 2 derivation: HKDF-Expand-SHA256
+      # (RFC 5869) with the key as the PRK and `mailcycle/v2/<label>` as the
+      # info.
+      #
+      # `subkey` concatenates its label and makes its second block by appending
+      # `/2`, so one label's second block can be another label's first. Here
+      # the counter sits outside the label, so two labels share output only if
+      # they are the same label. Only new kinds of key use it, so no account id
+      # or existing key changes. nil for a length outside 1 to 8160 bytes.
+      def subkey_v2(key, label, length)
+        Primitives.hkdf_expand(key, "#{LABEL_PREFIX_V2}#{label}", length)
+      end
+
+      # Refuses an identifier that could reshape the derivation label around it.
+      #
+      # `subkey` builds its second block by appending `/2`, and the label is
+      # concatenated rather than length-prefixed. So for an id `X`, the MAC
+      # half of `address_key(X)` is also the ENCRYPTION half of
+      # `address_key("X/2")`. A server that handed one account the ids `X` and
+      # `X/2` could recover keystream from the second and hold the first's MAC
+      # key.
+      #
+      # Length-prefixing inside `subkey` is the deeper fix and would change
+      # every key this product has ever derived, account ids included.
+      # Rejecting the characters that make the collision reachable costs
+      # nothing and closes it, because the attack needs a separator inside the
+      # id.
+      def safe_label?(id)
+        id.is_a?(String) && id.match?(SAFE_LABEL)
+      end
+
+      def identity_from_seed(seed)
+        auth_key = subkey(seed, "auth-key", 32)
+        AccountIdentity.new(
+          account_id: "acct_#{Mailcycle::Encoding.to_hex(subkey(seed, 'account-id', 16))}",
+          auth_secret: subkey(seed, "auth", 32),
+          auth_key: auth_key,
+          auth_public_key: Mailcycle::Encoding.to_b64u(Primitives.public_key_from(auth_key)),
+          vault_key: subkey(seed, "vault", 64)
+        )
+      end
+
+      def identity_from_phrase(phrase, passphrase = "")
+        identity_from_seed(Mnemonic.phrase_to_seed(phrase, passphrase))
+      end
+
+      # The verifier the server is allowed to store.
+      #
+      # It is a hash, so a database dump does not let an attacker authenticate
+      # anywhere else and cannot be run backwards into the phrase or the vault
+      # key.
+      def auth_verifier(auth_secret)
+        Mailcycle::Encoding.to_b64u(Primitives.sha256(auth_secret))
+      end
+
+      # The symmetric key for one address, 64 bytes, or nil for an unsafe id.
+      #
+      # Per address, so a key handed to one device unlocks that device's mail
+      # and nothing else, and removing a device does not mean re-encrypting the
+      # rest.
+      def address_key(vault_key, address_id)
+        return nil unless safe_label?(address_id)
+
+        subkey(vault_key, "inbox/#{address_id}", 64)
+      end
+
+      # The address's X25519 `[private, public]` pair, derived and never
+      # stored, or nil for an unsafe id.
+      #
+      # Separate from `address_key` and under a different label: the symmetric
+      # key seals mail the account's own devices deliver, and this pair is what
+      # lets a mail server seal what arrives from outside without ever being
+      # able to read it. One secret for both roles would mean handing a paired
+      # device a key that also opens inbound mail for an address it was never
+      # assigned.
+      def address_key_pair(vault_key, address_id)
+        return nil unless safe_label?(address_id)
+
+        private_key = subkey(vault_key, "inbox-sealing/#{address_id}", 32)
+        [private_key, Primitives.public_key_from(private_key)]
+      end
+
+      def valid_epoch?(epoch)
+        epoch.is_a?(Integer) && epoch.between?(0, MAX_EPOCH)
+      end
+
+      # The address's symmetric key at a key epoch.
+      #
+      # Epoch 0 is `address_key`, the key every address has had from the
+      # start. Later epochs come from `subkey_v2`: under `subkey`,
+      # `inbox/<id>/2` would be the second half of epoch 0's key. Old epochs
+      # stay derivable, so mail sealed under them still opens.
+      def address_key_at(vault_key, address_id, epoch)
+        return nil unless valid_epoch?(epoch)
+        return address_key(vault_key, address_id) if epoch.zero?
+        return nil unless safe_label?(address_id)
+
+        subkey_v2(vault_key, "inbox/#{address_id}/#{epoch}", 64)
+      end
+
+      # The address's X25519 pair at a key epoch. Epoch 0 is `address_key_pair`.
+      def address_key_pair_at(vault_key, address_id, epoch)
+        return nil unless valid_epoch?(epoch)
+        return address_key_pair(vault_key, address_id) if epoch.zero?
+        return nil unless safe_label?(address_id)
+
+        private_key = subkey_v2(vault_key, "inbox-sealing/#{address_id}/#{epoch}", 32)
+        return nil if private_key.nil?
+
+        [private_key, Primitives.public_key_from(private_key)]
+      end
+
+      # Short, human-comparable fingerprint, as the app shows when pairing.
+      def fingerprint(account_id)
+        digest = Mailcycle::Encoding.to_hex(Primitives.sha256(account_id))[0, 12].upcase
+        "#{digest[0, 4]}-#{digest[4, 4]}-#{digest[8, 4]}"
+      end
+    end
+  end
+end

data/lib/mailcycle/crypto/mnemonic.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Mailcycle
+  module Crypto
+    # Recovery phrases.
+    #
+    # A Mailcycle account is a twelve-word phrase. Nothing server-side can
+    # reset it.
+    #
+    # Encoding, as BIP-39 does it but over Mailcycle's own Wordlist: 128 bits
+    # of entropy, plus a 4-bit checksum taken from the first bits of
+    # SHA-256(entropy), split into twelve 11-bit groups, each an index into the
+    # list.
+    module Mnemonic
+      PHRASE_WORD_COUNT = 12
+      ENTROPY_BITS = 128
+      CHECKSUM_BITS = ENTROPY_BITS / 32
+
+      # Derivation cost.
+      #
+      # Changing it changes every account id ever derived, so this number is
+      # part of the format, not a tuning knob. Stretching buys little over a
+      # 128-bit phrase and earns its keep only for the optional passphrase,
+      # which may be low entropy.
+      SEED_ITERATIONS = 120_000
+      SEED_BYTES = 64
+      SEED_SALT_PREFIX = "mailcycle-seed"
+
+      # What JavaScript's `\s` matches, which is what the app splits on.
+      JS_WHITESPACE = "\t\n\v\f\r    - 

  　"
+      NOT_A_LETTER = /[^a-z#{JS_WHITESPACE}]/
+      WHITESPACE_RUN = /[#{JS_WHITESPACE}]+/
+      private_constant :NOT_A_LETTER, :WHITESPACE_RUN
+
+      module_function
+
+      # Lowercases, turns everything that is not a letter into a space, and
+      # splits on whitespace, as `normalizePhrase` in the app does.
+      def normalize(phrase)
+        text = phrase.to_s.dup.force_encoding(::Encoding::UTF_8).scrub
+        text.downcase.gsub(NOT_A_LETTER, " ").split(WHITESPACE_RUN).reject(&:empty?)
+      end
+
+      def entropy_to_phrase(entropy)
+        raise ArgumentError, "a phrase needs exactly 16 bytes of entropy" unless entropy.bytesize == ENTROPY_BITS / 8
+
+        checksum = Primitives.sha256(entropy).getbyte(0) >> (8 - CHECKSUM_BITS)
+        words = []
+        buffer = 0
+        bits = 0
+        entropy.each_byte do |byte|
+          buffer = (buffer << 8) | byte
+          bits += 8
+          while bits >= 11
+            bits -= 11
+            words << Wordlist::WORDS[(buffer >> bits) & 0x7ff]
+            buffer &= (1 << bits) - 1
+          end
+        end
+
+        # 128 bits leaves 7 over; the 4 checksum bits complete the last word.
+        words << Wordlist::WORDS[((buffer << CHECKSUM_BITS) | checksum) & 0x7ff]
+        words
+      end
+
+      # A fresh twelve-word phrase from the operating system's CSPRNG, as words.
+      def generate
+        entropy_to_phrase(Primitives.random_bytes(ENTROPY_BITS / 8))
+      end
+
+      # Full validation, checksum included. nil when the phrase is good,
+      # otherwise a PhraseProblem.
+      #
+      # A single mistyped word fails here roughly fifteen times out of sixteen,
+      # which is what the checksum is for: it turns "your mail is gone" into
+      # "word 7 is wrong".
+      def validate(phrase)
+        words = normalize(phrase)
+        return PhraseProblem.new(kind: :length, count: words.length) if words.length != PHRASE_WORD_COUNT
+
+        indices = []
+        words.each_with_index do |word, position|
+          index = Wordlist.index_of(word)
+          return PhraseProblem.new(kind: :unknown_word, word: word, index: position) if index.nil?
+
+          indices << index
+        end
+
+        entropy = Array.new(ENTROPY_BITS / 8, 0)
+        buffer = 0
+        bits = 0
+        written = 0
+        indices.each do |index|
+          buffer = (buffer * 2048) + index
+          bits += 11
+          while bits >= 8 && written < entropy.length
+            bits -= 8
+            entropy[written] = (buffer >> bits) & 0xff
+            buffer %= 1 << bits
+            written += 1
+          end
+        end
+
+        expected = Primitives.sha256(entropy.pack("C*")).getbyte(0) >> (8 - CHECKSUM_BITS)
+        return PhraseProblem.new(kind: :checksum) if (buffer & ((1 << CHECKSUM_BITS) - 1)) != expected
+
+        nil
+      end
+
+      def valid_word?(word)
+        !Wordlist.index_of(word.to_s.downcase).nil?
+      end
+
+      # Phrase to 64-byte root seed.
+      #
+      # The optional passphrase is BIP-39's "25th word": it changes which
+      # account the phrase opens, and nothing anywhere records whether one was
+      # used.
+      def phrase_to_seed(phrase, passphrase = "")
+        words = normalize(phrase).join(" ")
+        salt = SEED_SALT_PREFIX.b + passphrase.to_s.b
+        Primitives.pbkdf2_sha256(words, salt, SEED_ITERATIONS, SEED_BYTES)
+      end
+    end
+  end
+end