epithet 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40b8e5a401923aeaaf82f8340d43747433ea1440f7de4b1628087c326a916622
-  data.tar.gz: bf139e16eecab4aa544981b15f28fb267f1e55e38ca37a0828c6836c064319c3
+  metadata.gz: 8065749fc3d0aaf89280bc7238f8dfe30ce749bf9c09c84fbec0406bde779d1b
+  data.tar.gz: 8e42aeba4a5f3bae8cec60bac6719a1214f6750de8a8b33ce009af8d7c8dd20c
 SHA512:
-  metadata.gz: 324dec4e145ca1d5e8f3b9a22c3788ab3e9d1771d614c7dab5c94288888c59ce7235cbdd1a2dcd878015321f2264ae21702020b8bc9f8b6aaf3191bc50df9adc
-  data.tar.gz: 55f0b6b5bd0061c3545f9c644bfaec6eb3e7721d0df33b1217a52384da63b4ff96c0d5848f2d0340460bf3e3b8c6e9aef38cd9e677665e6abcfa09f1fd4a9024
+  metadata.gz: 6946cf232b610670fd5cdd5c1293f1d3c882a4efa36f3e1a9971ce667f9291130372f2106b83cf8bbad16673d1b13fbb5e7b1475989a2b2dc7b201fc44347562
+  data.tar.gz: 3437d52226de8303e23db85c11dd803ac1556f267b067696822f864b17d8b1ed1b314ec421074da0766e23ecd2efb926c6cb58dfefc7d7f0d1272e804d3ddcce

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 2.1.0 - 2026-07-23
+
+- Add support for JRuby and TruffleRuby
+- Support multiple scrypt providers (OpenSSL, BouncyCastle, and the `scrypt` gem)
+- Raise `Epithet::ConfigurationError` (< `RuntimeError`) if config missing
+- Unknown cipher/digest names now raise `ArgumentError`
+- Internal reorganisation into separate files
+- Robustness improvements inc. broader CI coverage & concurrency hammer
+- Documentation edits
+
 ## 2.0.0 - 2026-07-16
 
 ### Breaking changes

data/README.md

@@ -45,11 +45,15 @@ user_epithet.decode(param)
 # => 42
 ```
 
-Configuration once at initialisation is recommended, because deriving key material from the passphrase uses scrypt, and is consequently expensive.  The `context:` is optional; this parameter is included when deriving the subkey material for obfuscating and tamper resistance, and support purpose separation such as key rotation.  The scrypt step is seasoned by a salt, which defaults to a fixed constant; set an application-specific salt, as in the example above, so that two applications inadvertently sharing a passphrase never derive the same keys.
+Configuration once at initialisation is recommended, because deriving key material from the passphrase uses scrypt, and is consequently expensive.  The `context:` is optional; this parameter is included when deriving the subkey material for obfuscating and tamper resistance, and may be used for separation of purpose or key rotation.  The scrypt step is seasoned by a salt, which defaults to a fixed constant; set an application-specific salt, as in the example above, so that two applications inadvertently sharing a passphrase never derive the same keys.
 
-Refer to the Epithet rdoc for the full set of configuration options.
+Refer to the [Epithet rdoc](https://inopinatus.github.io/epithet/) for the full set of configuration options.
 
-Note that `decode` returns `nil` when authentication fails, and raises `Epithet::FormatError` (an ArgumentError) on invalid formats.
+Note that `Epithet#decode` returns `nil` when authentication fails, and raises `Epithet::FormatError` (an ArgumentError) on invalid formats.
+
+## Platform support
+
+Epithet supports standard Ruby (aka MRI/CRuby), JRuby, and TruffleRuby.  It uses your platform's OpenSSL scrypt where available; on JRuby it falls back to the BouncyCastle provider bundled with jruby-openssl, and LibreSSL builds can fall back to the optional [scrypt gem](https://rubygems.org/gems/scrypt).  To use the latter gem provider, your application must bundle and require `scrypt` before Epithet, we won't require it on your behalf.  All three providers produce identical key material.  To force a provider without a capability check, pass its class in the scrypt parameters, e.g. `scrypt: { provider: Epithet::Scrypt::BouncyCastle }`; omit `provider:` to select one automatically.
 
 ## Development
 

data/SECURITY.md

@@ -1,5 +1,12 @@
 # Epithet security
 
+This library is intended for high-performance obfuscation of integer sequences, deflection of casual
+tampering, and conversion to a compact, stable wire parameter format that is hard to guess and hard
+to predict.  Epithet forms a single-block deterministic PRP with an embedded truncated tag, and
+although it uses standard cryptographic primitives to do so, the design trade-off of the compact
+format means it is not intended to defeat nation-state security services, talented cryptographers,
+or even a well-resourced enterprise.
+
 ## Cryptographic considerations
 
 The primary construction is `AES-256-ECB(id(8B) + MSB_64(HMAC-SHA256(id)))` with the result base58
@@ -7,12 +14,6 @@ encoded for transmission and a contextual prefix prepended.  Subkeys for AES and
 derived with HKDF using an internal key generator that takes IKM from a passphrase via scrypt,
 salting generated keys by prefix and context and binding them by algorithm.
 
-This library is intended for high-performance obfuscation of integer sequences, deflection of casual
-tampering, and conversion to a compact, stable wire parameter format that is hard to guess and hard
-to predict.  Although it uses standard cryptographic primitives to do so, the design trade-off of
-the compact format means it is not intended to defeat nation-state security services, talented
-cryptographers, or even a well-resourced enterprise.
-
 An epithet should never be used as an authentication token, only as an object identifier.  The
 64-bit tag is shorter than the minimum RFC 2104 §5 recommends for message authentication, and the
 tamper detection is necessarily probabilistic because the MAC is truncated.  After N independent
@@ -38,7 +39,9 @@ decode a value exceeding the 128-bit block.
 A weak, guessable, or disclosed passphrase will compromise the obfuscation and tamper-detection
 properties.
 
-Use Epithet at your own risk.
+To sum up: neither the design nor implementation of this library has received an independent
+cryptographic review.  It leaks equality, offers a 64-bit forgery bound, and supplies no
+authorization or privacy boundary.  Use Epithet at your own risk.
 
 ## On seasoning
 
@@ -48,7 +51,7 @@ Secondly, for the HKDF extract phase to separate derived subkeys by some applica
 division such as purpose or rotation epoch.
 
 To avoid confusing the two uses, the HKDF salt is not referred to directly in Epithet's public API,
-and is instead derived from the context and prefix parameters that are documented instead.
+and is instead derived from the context and prefix parameters.
 
 Epithet does not store or verify passwords; the scrypt salt, and the context & prefix parameters
 used in the HKDF salt, are non-secret configuration and may be safely committed to source control.

data/examples/basic.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
+require 'securerandom'
 require 'epithet'
 
 # Using a random passphrase means that epithet identifiers are effectively
 # ephemeral, since decoding is limited to the lifetime of this process.
 def epithet_initialize
   Epithet.configure(
-    passphrase: ENV.fetch('EPITHET_PASSPHRASE') { Random.bytes(32) },
+    passphrase: ENV.fetch('EPITHET_PASSPHRASE') { SecureRandom.random_bytes(32) },
     scrypt: { salt: 'myapp/production' },
     context: 'v1'
   )
@@ -16,6 +17,6 @@ epithet_initialize
 user_epithet = Epithet.new('user')
 
 id = Integer(ARGV.shift || 42)
-param = user_epithet.encode(id) #=> "user_KYM3B4d5ce1NNsv52rAoPg"
+param = user_epithet.encode(id)
 
 puts "User(#{user_epithet.decode(param)}) => #{param}"

data/lib/epithet/block58.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+class Epithet
+  # Fixed-length base58 codec for a fixed-size block.
+  #
+  # Obtain codecs via Block58::build, which selects the fastest variant for
+  # the block size, an unrolled decoder for 16-byte blocks, or the generic
+  # chunked decoder otherwise.
+  class Block58
+    # `= '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'`
+    Alphabet = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'
+
+    POW58 = Array.new(11) { 58**it }.freeze # :nodoc:
+
+    attr_reader :size
+
+    # Same as ::new but may select a tuned subclass for performance.
+    def self.build(block_size, ...) = (block_size == 16 ? Unrolled16 : self).new(block_size, ...)
+
+    # Create a codec for a block size in bytes.
+    #
+    # The alphabet must be 58 distinct bytes in ascending order, so that
+    # lexicographic order agrees with numeric order.
+    def initialize(block_size, alphabet: Alphabet)
+      raise ArgumentError, 'invalid block size' unless Integer === block_size && block_size > 0
+      @alphabet = alphabet.b.freeze
+      raise ArgumentError, 'invalid alphabet length' unless @alphabet.bytesize == 58
+      raise ArgumentError, 'alphabet not strictly ascending' unless @alphabet.bytes.each_cons(2).all? { _2 > _1 }
+      @size = ((block_size * 8) / Math.log2(58)).ceil
+      @charsel = @alphabet.gsub(/[\^\-\\]/, '\\\\\&').freeze
+      @blank = (@alphabet[0] * @size).freeze
+      @lut = @alphabet.each_byte.with_index.with_object("\0" * 256) { |(val, idx), lut| lut.setbyte(val, idx) }.freeze
+      @limit = 1 << (block_size * 8)
+      @max = i2s(@limit - 1).freeze
+    end
+
+    def inspect
+      "#<#{self.class}:#{'%#016x' % (object_id << 1)} size=#{@size} alphabet=#{@alphabet}>"
+    end
+
+    # Return true if the string is in range with the right size and alphabet.
+    # The input is read as bytes, whatever its encoding.
+    def valid?(s)
+      String === s && s.bytesize == @size && (s = s.b) <= @max && s.count(@charsel) == @size
+    end
+
+    # Encode an acceptable integer to fixed-length base58.
+    def i2s(int)
+      raise ArgumentError, 'integer out of block range' unless Integer === int && int >= 0 && int < @limit
+
+      # Using divmod+setbyte is faster than Integer#digits under YJIT,
+      # and about equal in plain MRI.
+      alphabet = @alphabet
+      out = @blank.dup
+      idx = @size - 1
+      n = int
+      while idx >= 0 && n > 0
+        n, rem = n.divmod(58)
+        out.setbyte(idx, alphabet.getbyte(rem))
+        idx -= 1
+      end
+      out
+    end
+
+    # Decode a fixed-length base58 string to an integer.
+    # Assumes the input passes `#valid?`, behaviour undefined if it doesn't.
+    def s2i(str)
+      # Chunking intermediate results into 64-bit integers is ~5x faster
+      # under YJIT than Horner's scheme
+      #
+      #   str.each_byte.inject(0) { _1 * 58 + @lut[_2] }
+      #
+      # at computing the inner product.
+      lut = @lut
+      size = @size
+      pow = POW58
+      acc = 0
+      pos = 0
+      while pos < size
+        n = size - pos
+        n = 10 if n > 10
+        chunk = 0
+        i = 0
+        while i < n
+          chunk = (chunk * 58) + lut.getbyte(str.getbyte(pos))
+          pos += 1
+          i += 1
+        end
+        acc = (acc * pow[n]) + chunk
+      end
+      acc
+    end
+
+    # Specialised decoder for 16-byte blocks (22 digits) with a fully unrolled inner product.
+    class Unrolled16 < Block58
+      def initialize(...)
+        super
+        raise ArgumentError, 'unrolled codec requires a 16-byte block' unless @size == 22
+      end
+
+      # Decode a 22-digit base58 string to an integer.
+      # Assumes the input passes `#valid?`, behaviour undefined if it doesn't.
+      def s2i(str)
+        # rubocop:disable Style/NumericLiterals, Lint/AmbiguousOperatorPrecedence, Layout
+        #
+        # By unrolling the chunks against literal coefficients, this tested with Ruby 4.0
+        # at ~1.5x faster under YJIT than the generic chunked Block58#s2i, and ~6x faster
+        # than Horner's scheme.
+        lut = @lut
+
+        acc0 = lut.getbyte(str.getbyte(0)) * 7427658739644928 +
+               lut.getbyte(str.getbyte(1)) * 128063081718016 +
+               lut.getbyte(str.getbyte(2)) * 2207984167552 +
+               lut.getbyte(str.getbyte(3)) * 38068692544 +
+               lut.getbyte(str.getbyte(4)) * 656356768 +
+               lut.getbyte(str.getbyte(5)) * 11316496 +
+               lut.getbyte(str.getbyte(6)) * 195112 +
+               lut.getbyte(str.getbyte(7)) * 3364 +
+               lut.getbyte(str.getbyte(8)) * 58 +
+               lut.getbyte(str.getbyte(9))
+
+        acc1 = lut.getbyte(str.getbyte(10)) * 7427658739644928 +
+               lut.getbyte(str.getbyte(11)) * 128063081718016 +
+               lut.getbyte(str.getbyte(12)) * 2207984167552 +
+               lut.getbyte(str.getbyte(13)) * 38068692544 +
+               lut.getbyte(str.getbyte(14)) * 656356768 +
+               lut.getbyte(str.getbyte(15)) * 11316496 +
+               lut.getbyte(str.getbyte(16)) * 195112 +
+               lut.getbyte(str.getbyte(17)) * 3364 +
+               lut.getbyte(str.getbyte(18)) * 58 +
+               lut.getbyte(str.getbyte(19))
+
+               lut.getbyte(str.getbyte(21)) +
+               lut.getbyte(str.getbyte(20)) * 58 +
+                                       acc1 * 3364 +
+                                       acc0 * 1449225352009601191936
+
+        # rubocop:enable Style/NumericLiterals, Lint/AmbiguousOperatorPrecedence, Layout
+      end
+    end
+  end
+end

data/lib/epithet/config.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'epithet/block58'
+require 'epithet/keygen'
+
+class Epithet
+  # Class for passing around preset configs. See Epithet::configure for options.
+  class Config
+    attr_reader :keygen, :context, :separator, :cipher, :digest, :codec # :nodoc:
+
+    def initialize(opts = {})
+      opts = opts.dup
+      @separator = -String(opts.delete(:separator) { '_' })
+      @context = -String(opts.delete(:context))
+      alphabet = String(opts.delete(:alphabet) { Block58::Alphabet })
+      @cipher = -(opts.delete(:cipher) || 'aes-256-ecb').downcase
+      @digest = -(opts.delete(:digest) || 'sha256').downcase
+      keygen, passphrase, scrypt = %i[keygen passphrase scrypt].map { opts.delete it }
+
+      cipher = probe(OpenSSL::Cipher, @cipher)
+      digest = probe(OpenSSL::Digest, @digest)
+
+      raise ArgumentError, 'separator intersects alphabet' if @separator.bytes.intersect?(alphabet.bytes)
+      raise ArgumentError, "#{@cipher} not a 128-bit block cipher" if cipher.block_size != 16
+      raise ArgumentError, "#{@cipher} requires an IV/nonce" if cipher.iv_len != 0
+      raise ArgumentError, "#{@digest} produces < 64-bit digest" if digest.digest_length < 8
+      raise ArgumentError, 'use keygen: or passphrase:, not both' if keygen && (passphrase || scrypt)
+      raise ArgumentError, 'one of passphrase: or keygen: is required' unless keygen || passphrase
+      raise ArgumentError, "unused option(s) #{opts.keys}" unless opts.empty?
+
+      @codec = Block58.build(cipher.block_size, alphabet:)
+      @keygen = keygen || Keygen.new(passphrase:, digest: @digest, scrypt:)
+      freeze
+    end
+
+    # The openssl gem <4.0 raises bare RuntimeError for unrecognised algorithm
+    # names; jruby-openssl raises NotImplementedError.
+    def probe(kind, name) # :nodoc:
+      kind.new(name)
+    rescue OpenSSL::OpenSSLError, RuntimeError, NotImplementedError
+      raise ArgumentError, "unknown #{kind.name[/\w+\z/].downcase} #{name}"
+    end
+  end
+end

data/lib/epithet/keygen.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'epithet/scrypt'
+
+class Epithet
+  # Key derivation helper
+  class Keygen
+    # Default parameters for scrypt.
+    #
+    # ```ruby
+    # DEFAULT_SCRYPT_PARAMS = {
+    #   provider: Epithet::Scrypt,
+    #   salt: 'epithet-default',
+    #   N: 1 << 17,
+    #   r: 8,
+    #   p: 1,
+    #   length: 32
+    # }.freeze
+    # ```
+    DEFAULT_SCRYPT_PARAMS = {
+      provider: Epithet::Scrypt,
+      salt: 'epithet-default',
+      N: 1 << 17,
+      r: 8,
+      p: 1,
+      length: 32
+    }.freeze
+
+    # Create a new key generator from a supplied passphrase, or from high-entropy initial key
+    # material if already prepared.  The passphrase will be hashed with scrypt.  Supplied scrypt
+    # params, if any, are merged over DEFAULT_SCRYPT_PARAMS, so this works:
+    #
+    #     Epithet::Keygen.new(
+    #       passphrase: ENV.fetch('EPITHET_PASSPHRASE'),
+    #       scrypt: { salt: "#{MyApp.name}/#{MyApp.env}" }
+    #     )
+    #
+    # A scrypt provider will be chosen by `Epithet::Scrypt`.  To override automatic selection
+    # and use a specific scrypt provider class, pass it as `provider` in the scrypt parameters:
+    #
+    #     kg = Epithet::Keygen.new(passphrase: 'pw', scrypt: { provider: Epithet::Scrypt::OpenSSL })
+    #
+    # but this should be unnecessary in the common case.
+    def initialize(ikm: nil, passphrase: nil, digest: 'sha256', scrypt: {})
+      raise ArgumentError, 'keygen requires either ikm or passphrase' unless passphrase.nil? ^ ikm.nil?
+
+      @ikm = (ikm&.b || build_scrypt(Hash(scrypt)).ikm(passphrase)).freeze
+      @digest = -String(digest)
+      freeze
+    end
+
+    def inspect
+      "#<#{self.class}:#{'%#016x' % (object_id << 1)} digest=#{@digest}>"
+    end
+
+    # Derive a key via HKDF.
+    def generate(info, salt, length)
+      OpenSSL::KDF.hkdf(@ikm, hash: @digest, info:, salt:, length:)
+    end
+
+    private
+
+    def build_scrypt(opts)
+      params = DEFAULT_SCRYPT_PARAMS.merge(opts)
+      params.delete(:provider).new(**params)
+    end
+  end
+end

data/lib/epithet/scrypt.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'monitor'
+
+class Epithet
+  # Provider registry & classes for the scrypt implementations.
+  #
+  # A scrypt provider is any class that can be instantiated with the scrypt
+  # parameters `salt`, `N`, `r`, `p`, and `length`, has a predicate singleton
+  # method `auto?` indicating willingness to operate, and an instance method
+  # `ikm(passphrase)` that derives the key material.  Automatic selection picks
+  # the most recently registered willing provider.
+  #
+  # Of the builtin providers, we prefer `OpenSSL::KDF.scrypt` when the platform
+  # supplies it, then JRuby's BouncyCastle implementation, and finally an
+  # already-loaded [`scrypt`](https://rubygems.org/gems/scrypt) gem.  If none of
+  # these are available, selection falls through to a base class which raises
+  # `NotImplementedError` at the point of use.
+  #
+  # Epithet deliberately does not require the optional `scrypt` gem itself; an
+  # application relying on the `SCryptGem` provider should bundle and require
+  # `scrypt` before configuring Epithet.
+  #
+  # You may register a custom scrypt provider with the necessary signature, even
+  # after Epithet has loaded:
+  #
+  #     class MyProvider < Epithet::Scrypt::Base
+  #       def ikm(passphrase)
+  #         #...
+  #       end
+  #     end
+  #     Epithet::Scrypt.register(MyProvider)
+  #
+  # and this will be unconditionally preferred unless you also define a selective
+  # `auto?` method.
+  #
+  # Your `ikm` method should return `length` bytes of key material.
+  #
+  # Using this mechanism as a hook to deviate from the scrypt algorithm is not
+  # recommended; the better move would be to substitute a variant key
+  # generator in the `Epithet::Config` parameters, or supply IKM to an
+  # `Epithet::Keygen`.
+  module Scrypt
+    extend MonitorMixin
+
+    class << self
+      # The registered providers, in automatic-selection order.
+      def providers = synchronize { @providers }
+
+      # Registers `klass` ahead of the existing providers.
+      def register(klass) = synchronize { @providers = [klass, *@providers].freeze }
+
+      # Returns the first registered provider willing to operate.
+      def auto = providers.detect(&:auto?)
+
+      # Instantiates the automatically selected provider.
+      def new(...) = auto.new(...)
+    end
+
+    # :section: Providers
+    #
+    # ### `Base` class
+    #
+    # Defines the common `salt`, `N`, `r`, `p`, and `length` parameters.  It is
+    # the last-resort provider: `ikm(passphrase)` raises `NotImplementedError`
+    # when no scrypt implementation is available.
+    #
+    # ### `OpenSSL` class
+    #
+    # The default, preferred provider.  It uses `OpenSSL::KDF.scrypt` when the
+    # platform's OpenSSL supplies it.
+    #
+    # ### `BouncyCastle` class
+    #
+    # The JRuby fallback.  JRuby's `openssl` is a BouncyCastle wrapper, but does
+    # not expose BouncyCastle's scrypt, so this provider invokes it directly.
+    #
+    # ### `SCryptGem` class
+    #
+    # A fallback for LibreSSL and other OpenSSLs that lack scrypt.  It is
+    # available when the application has already loaded the optional
+    # [`scrypt`](https://rubygems.org/gems/scrypt) gem.
+    Base = Data.define(:salt, :N, :r, :p, :length) do # :nodoc: # rubocop:disable Naming/MethodName
+      def self.auto? = true
+      def ikm(passphrase) = raise NotImplementedError, 'no scrypt available'
+    end
+
+    class SCryptGem < Base # :nodoc:
+      def self.auto? = defined? ::SCrypt::Engine
+
+      def ikm(passphrase)
+        ::SCrypt::Engine.scrypt(passphrase, salt, self.N, r, p, length)
+      end
+    end
+
+    class BouncyCastle < Base # :nodoc:
+      def self.auto? = RUBY_ENGINE == 'jruby'
+
+      def ikm(passphrase)
+        String.from_java_bytes(
+          Java::OrgBouncycastleCryptoGenerators::SCrypt.generate(
+            passphrase.to_java_bytes, salt.to_java_bytes, self.N, r, p, length
+          )
+        )
+      end
+    end
+
+    class OpenSSL < Base # :nodoc:
+      def self.auto? = ::OpenSSL::KDF.respond_to? :scrypt
+
+      def ikm(passphrase)
+        ::OpenSSL::KDF.scrypt(passphrase, **to_h)
+      end
+    end
+
+    @providers = [OpenSSL, BouncyCastle, SCryptGem, Base].freeze
+  end
+end

data/lib/epithet/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 class Epithet
-  # `= '2.0.0'`
-  VERSION = '2.0.0'
+  # `= '2.1.0'`
+  VERSION = '2.1.0'
 end

data/lib/epithet.rb

@@ -2,6 +2,10 @@
 
 require 'epithet/version'
 require 'openssl'
+require 'epithet/scrypt'
+require 'epithet/keygen'
+require 'epithet/block58'
+require 'epithet/config'
 
 #
 # Epithet, a tool for external identifiers.
@@ -35,6 +39,9 @@ class Epithet
   # Raised by #decode when the input is not valid wire format.
   FormatError = Class.new(ArgumentError)
 
+  # Raised if no defaults are configured.
+  ConfigurationError = Class.new(RuntimeError)
+
   # Create an encoder/decoder.
   #
   # Setup could be moderately expensive due to key derivation; you are recommended to cache
@@ -45,14 +52,15 @@ class Epithet
   #
   # * `config` is optional and intended for cases where you need finer control than global defaults.
   #
-  # Mixed character encodings across prefix & separator may raise Encoding::CompatibilityError.
+  # Mixing incompatible character encodings across prefix/separator/payload may raise
+  # Encoding::CompatibilityError or Epithet::FormatError.  Don't expect UTF-16LE to work.
   #
   # The simplest typical invocation is `Epithet.new('prefix')`.
   #
   def initialize(prefix, config: Epithet.defaults)
-    prefix = String(prefix)
-    @prefix = prefix.empty? ? prefix : prefix + config.separator
-    @wire_prefix = @prefix.b
+    prefix = -String(prefix)
+    @prefix = prefix.empty? ? prefix : -(prefix + config.separator)
+    @wire_prefix = @prefix.b.freeze
     key_salt = [prefix.bytesize, prefix, config.context.bytesize, config.context].pack('Q>Z*Q>Z*')
     @codec = config.codec
 
@@ -130,7 +138,7 @@ class Epithet
     # #### Options
     #
     # *   `:passphrase` - Install new key generator with scrypt-derived key material
-    # *   `:scrypt` - Merge params for scrypt
+    # *   `:scrypt` - Override scrypt parameters (cost, salt, provider etc); see Epithet::Scrypt
     # *   `:keygen` - Use an existing key generator
     # *   `:cipher` - Must be a 128-bit block cipher in ECB mode or equivalent; omit for standard `aes-256-ecb`
     # *   `:digest` - Must be >= 64 bits digest; omit for standard `sha256`
@@ -145,6 +153,7 @@ class Epithet
     #
     # If passing an existing key generator, the object must respond to `generate(info, salt, length)`
     # and return a byte string suitable for use with OpenSSL cryptographic primitives.
+    # Configuration sharing means an alternative keygen must support concurrent `generate` calls.
     #
     # See [`SECURITY.md`](SECURITY.md) for discussion of ciphers & digests.
     #
@@ -154,8 +163,8 @@ class Epithet
     #
     #     cfg = Epithet::Config.new(
     #       keygen: my_key_gen,
-    #       cipher: 'stronk-512-jcb',
-    #       digest: 'md7'
+    #       cipher: 'camellia-256-ecb',
+    #       digest: 'sha224'
     #     )
     #
     # and either install this as default with
@@ -167,215 +176,6 @@ class Epithet
     #     acct_epithet = Epithet.new('acct', config: cfg)
     #
     def configure(opts) = @defaults = Config === opts ? opts : Config.new(opts)
-    def defaults() = @defaults || raise('no Epithet defaults configured')
-  end
-
-  # Class for passing around preset configs. See Epithet::configure for options.
-  class Config
-    attr_reader :keygen, :context, :separator, :cipher, :digest, :codec # :nodoc:
-
-    def initialize(opts = {})
-      opts = opts.dup
-      @separator = -String(opts.delete(:separator) { '_' })
-      @context = -String(opts.delete(:context))
-      alphabet = String(opts.delete(:alphabet) { Block58::Alphabet })
-      @cipher = -(opts.delete(:cipher) || 'aes-256-ecb').downcase
-      @digest = -(opts.delete(:digest) || 'sha256').downcase
-      keygen, passphrase, scrypt = %i[keygen passphrase scrypt].map { opts.delete it }
-
-      cipher = OpenSSL::Cipher.new(@cipher)
-      raise ArgumentError, 'separator intersects alphabet' if @separator.bytes.intersect?(alphabet.bytes)
-      raise ArgumentError, "#{@cipher} not a 128-bit block cipher" if cipher.block_size != 16
-      raise ArgumentError, "#{@cipher} requires an IV/nonce" if cipher.iv_len != 0
-      raise ArgumentError, "#{@digest} produces < 64-bit digest" if OpenSSL::Digest.new(@digest).digest_length < 8
-      raise ArgumentError, 'use keygen: or passphrase:, not both' if keygen && (passphrase || scrypt)
-      raise ArgumentError, 'one of passphrase: or keygen: is required' unless keygen || passphrase
-      raise ArgumentError, "unused option(s) #{opts.keys}" unless opts.empty?
-
-      @codec = Block58.build(cipher.block_size, alphabet:)
-      @keygen = keygen || Keygen.new(passphrase:, digest: @digest, scrypt:)
-      freeze
-    end
-  end
-
-  # Key derivation helper
-  class Keygen
-    # Default parameters for scrypt.
-    #
-    # ```ruby
-    # DEFAULT_SCRYPT_PARAMS = {
-    #   salt: 'epithet-default',
-    #   N: 1 << 17,
-    #   r: 8,
-    #   p: 1
-    # }.freeze
-    # ```
-    DEFAULT_SCRYPT_PARAMS = {
-      salt: 'epithet-default',
-      N: 1 << 17,
-      r: 8,
-      p: 1
-    }.freeze
-
-    # Create a new key generator from either high-entropy key material, or a supplied passphrase.
-    # Supplied scrypt params, if any, are merged over DEFAULT_SCRYPT_PARAMS.
-    def initialize(ikm: nil, passphrase: nil, digest: 'sha256', scrypt: {})
-      if (passphrase.nil? && ikm.nil?) || (!passphrase.nil? && !ikm.nil?)
-        raise ArgumentError, 'keygen requires either ikm or passphrase'
-      end
-      raise ArgumentError, 'scrypt length is not configurable' if scrypt&.key?(:length)
-
-      @ikm = (ikm&.b || OpenSSL::KDF.scrypt(passphrase, **DEFAULT_SCRYPT_PARAMS, **scrypt, length: 32)).freeze
-      @digest = -String(digest)
-      freeze
-    end
-
-    def inspect
-      "#<#{self.class}:#{'%#016x' % (object_id << 1)} digest=#{@digest}>"
-    end
-
-    # Derive a key via HKDF.
-    def generate(info, salt, length)
-      OpenSSL::KDF.hkdf(@ikm, hash: @digest, info:, salt:, length:)
-    end
-  end
-
-  # Fixed-length base58 codec for a fixed-size block.
-  #
-  # Obtain codecs via Block58::build, which selects the fastest variant for
-  # the block size, an unrolled decoder for 16-byte blocks, or the generic
-  # chunked decoder otherwise.
-  class Block58
-    # `= '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'`
-    Alphabet = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'
-
-    POW58 = Array.new(11) { 58**it }.freeze # :nodoc:
-
-    attr_reader :size
-
-    # Same as ::new but may select a tuned subclass for performance.
-    def self.build(block_size, ...) = (block_size == 16 ? Unrolled16 : self).new(block_size, ...)
-
-    # Create a codec for a block size in bytes.
-    #
-    # The alphabet must be 58 distinct bytes in ascending order, so that
-    # lexicographic order agrees with numeric order.
-    def initialize(block_size, alphabet: Alphabet)
-      raise ArgumentError, 'invalid block size' unless Integer === block_size && block_size > 0
-      @alphabet = alphabet.b.freeze
-      raise ArgumentError, 'invalid alphabet length' unless @alphabet.bytesize == 58
-      raise ArgumentError, 'alphabet not strictly ascending' unless @alphabet.bytes.each_cons(2).all? { _2 > _1 }
-      @size = ((block_size * 8) / Math.log2(58)).ceil
-      @charsel = @alphabet.gsub(/[\^\-\\]/, '\\\\\&').freeze
-      @blank = @alphabet[0] * @size
-      @lut = @alphabet.each_byte.with_index.with_object("\0" * 256) { |(val, idx), lut| lut.setbyte(val, idx) }.freeze
-      @limit = 1 << (block_size * 8)
-      @max = i2s(@limit - 1).freeze
-    end
-
-    def inspect
-      "#<#{self.class}:#{'%#016x' % (object_id << 1)} size=#{@size} alphabet=#{@alphabet}>"
-    end
-
-    # Return true if the string is in range with the right size and alphabet.
-    # The input is read as bytes, whatever its encoding.
-    def valid?(s)
-      String === s && s.bytesize == @size && (s = s.b) <= @max && s.count(@charsel) == @size
-    end
-
-    # Encode an acceptable integer to fixed-length base58.
-    def i2s(int)
-      raise ArgumentError, 'integer out of block range' unless Integer === int && int >= 0 && int < @limit
-
-      # Using divmod+setbyte is faster than Integer#digits under YJIT,
-      # and about equal in plain MRI.
-      alphabet = @alphabet
-      out = @blank.dup
-      idx = @size - 1
-      n = int
-      while idx >= 0 && n > 0
-        n, rem = n.divmod(58)
-        out.setbyte(idx, alphabet.getbyte(rem))
-        idx -= 1
-      end
-      out
-    end
-
-    # Decode a fixed-length base58 string to an integer.
-    # Assumes the input passes `#valid?`, behaviour undefined if it doesn't.
-    def s2i(str)
-      # Chunking intermediate results into 64-bit integers is ~5x faster
-      # under YJIT than Horner's scheme
-      #
-      #   str.each_byte.inject(0) { _1 * 58 + @lut[_2] }
-      #
-      # at computing the inner product.
-      lut = @lut
-      size = @size
-      pow = POW58
-      acc = 0
-      pos = 0
-      while pos < size
-        n = size - pos
-        n = 10 if n > 10
-        chunk = 0
-        i = 0
-        while i < n
-          chunk = (chunk * 58) + lut.getbyte(str.getbyte(pos))
-          pos += 1
-          i += 1
-        end
-        acc = (acc * pow[n]) + chunk
-      end
-      acc
-    end
-
-    # Specialised decoder for 16-byte blocks (22 digits) with a fully unrolled inner product.
-    class Unrolled16 < Block58
-      def initialize(...)
-        super
-        raise ArgumentError, 'unrolled codec requires a 16-byte block' unless @size == 22
-      end
-
-      # Decode a 22-digit base58 string to an integer.
-      # Assumes the input passes `#valid?`, behaviour undefined if it doesn't.
-      def s2i(str)
-        # rubocop:disable Style/NumericLiterals, Lint/AmbiguousOperatorPrecedence, Layout
-        #
-        # By unrolling the chunks against literal coefficients, this tested with Ruby 4.0
-        # at ~1.5x faster under YJIT than the generic chunked Block58#s2i, and ~6x faster
-        # than Horner's scheme.
-        lut = @lut
-
-        acc0 = lut.getbyte(str.getbyte(0)) * 7427658739644928 +
-               lut.getbyte(str.getbyte(1)) * 128063081718016 +
-               lut.getbyte(str.getbyte(2)) * 2207984167552 +
-               lut.getbyte(str.getbyte(3)) * 38068692544 +
-               lut.getbyte(str.getbyte(4)) * 656356768 +
-               lut.getbyte(str.getbyte(5)) * 11316496 +
-               lut.getbyte(str.getbyte(6)) * 195112 +
-               lut.getbyte(str.getbyte(7)) * 3364 +
-               lut.getbyte(str.getbyte(8)) * 58 +
-               lut.getbyte(str.getbyte(9))
-
-        acc1 = lut.getbyte(str.getbyte(10)) * 7427658739644928 +
-               lut.getbyte(str.getbyte(11)) * 128063081718016 +
-               lut.getbyte(str.getbyte(12)) * 2207984167552 +
-               lut.getbyte(str.getbyte(13)) * 38068692544 +
-               lut.getbyte(str.getbyte(14)) * 656356768 +
-               lut.getbyte(str.getbyte(15)) * 11316496 +
-               lut.getbyte(str.getbyte(16)) * 195112 +
-               lut.getbyte(str.getbyte(17)) * 3364 +
-               lut.getbyte(str.getbyte(18)) * 58 +
-               lut.getbyte(str.getbyte(19))
-
-               lut.getbyte(str.getbyte(21)) +
-               lut.getbyte(str.getbyte(20)) * 58 +
-                                       acc1 * 3364 +
-                                       acc0 * 1449225352009601191936
-
-        # rubocop:enable Style/NumericLiterals, Lint/AmbiguousOperatorPrecedence, Layout
-      end
-    end
+    def defaults() = @defaults || raise(ConfigurationError, 'no Epithet defaults configured')
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: epithet
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Josh Goodall
@@ -37,20 +37,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: rdoc
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '7'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '7'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
@@ -79,6 +65,10 @@ files:
 - SECURITY.md
 - examples/basic.rb
 - lib/epithet.rb
+- lib/epithet/block58.rb
+- lib/epithet/config.rb
+- lib/epithet/keygen.rb
+- lib/epithet/scrypt.rb
 - lib/epithet/version.rb
 homepage: https://github.com/inopinatus/epithet
 licenses:
@@ -103,7 +93,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.16
 specification_version: 4
 summary: External base58 identifiers with reversible, tamper-evident obfuscation.
 test_files: []