epithet 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3695519b4c82955cf40a1d3b5109fbeaf3458085146500eea600c0fa8ce86bb0
-  data.tar.gz: f527803fc071230ae440b9e199f65ad890a0bf8778d643258b0c58b1a0f53b78
+  metadata.gz: 40b8e5a401923aeaaf82f8340d43747433ea1440f7de4b1628087c326a916622
+  data.tar.gz: bf139e16eecab4aa544981b15f28fb267f1e55e38ca37a0828c6836c064319c3
 SHA512:
-  metadata.gz: 725d659f196c53fc6ea438607dd9319b95b5aac8b61a68c5708b62f9eed26fd76012b3addb45a9a9880952c7275bbc2e5aace3390998c082e6dedd48c76fc174
-  data.tar.gz: aa15ac11d2ae8c1454ce5d086c25fbae5aee1957747e77dfcbdf626c470ddf438df69a3580eee98ecca7131243ed175d53c5edbc245b6b8c3c96b01742cf2914
+  metadata.gz: 324dec4e145ca1d5e8f3b9a22c3788ab3e9d1771d614c7dab5c94288888c59ce7235cbdd1a2dcd878015321f2264ae21702020b8bc9f8b6aaf3191bc50df9adc
+  data.tar.gz: 55f0b6b5bd0061c3545f9c644bfaec6eb3e7721d0df33b1217a52384da63b4ff96c0d5848f2d0340460bf3e3b8c6e9aef38cd9e677665e6abcfa09f1fd4a9024

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 2.0.0 - 2026-07-16
+
+### Breaking changes
+
+- The subkey-derivation option `context:` replaces `salt:`, to avoid confusion with scrypt's salt parameter.
+- Subkey derivation now binds the configured cipher and digest names (lowercased) into the HKDF info.
+- Nil and empty-string prefixes now yield bare params with no separator.
+- Config no longer exposes the alphabet string, it carries the Block58 codec around instead.
+- Drop support for Rubies < 3.4.
+
+### Other changes
+
+- Raise Epithet::FormatError (< ArgumentError) on invalid wire format
+- Improve handling of string encodings
+- Additional invariants
+- Friendlier errors
+- Documentation improvements
+
+## 1.1.0 - 2026-07-14
+
+- Freeze config strings upon object initialization
+- Merge custom scrypt params
+- Block58 now defaults to a generic s2i that handles any block size
+- Optimised 16-byte unrolled s2i selected via `Block58::build`
+- Recognize unprefixed decodes by payload length
+- Fix github CI warnings
+- Write notes on salt & improve examples
+
 ## 1.0.0 - 2026-07-14
 
 ### Breaking changes

data/README.md

@@ -1,6 +1,6 @@
 # Epithet
 
-Epithet generates stable, compact, purposefully prefixed Base58 identifiers from 64-bit integers for reversible obfuscation and tamper detection.
+Epithet generates stable, compact, purposefully prefixed base58 identifiers from 64-bit integers for reversible obfuscation and tamper detection.
 
 * https://github.com/inopinatus/epithet
 * https://inopinatus.github.io/epithet/
@@ -21,13 +21,16 @@ gem install epithet
 
 ## Usage
 
+With `EPITHET_PASSPHRASE=example_only`:
+
 ```ruby
 require 'epithet'
 
 def epithet_initialize
   Epithet.configure(
-    passphrase: ENV.fetch('EPITHET_PASSPHRASE') { 'example only' },
-    salt: 'v1'
+    passphrase: ENV.fetch('EPITHET_PASSPHRASE'),
+    scrypt: { salt: 'myapp/production' },
+    context: 'v1'
   )
 end
 
@@ -36,17 +39,17 @@ user_epithet = Epithet.new('user')
 
 id = 42
 param = user_epithet.encode(id)
-# => "user_VsuNnfEYQJJTJYE3n28jaY"
+# => "user_GikJf7Y58t5sgqJpifjgZy"
 
 user_epithet.decode(param)
 # => 42
 ```
 
-Configuration at initialisation is recommended, because deriving key material from the passphrase uses scrypt, and is consequently expensive. The `salt:` is optional; it's included when deriving the subkey material for obfuscating and tamper resistance, and may be useful for additional context discrimination or during secrets rotation.
+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.
 
 Refer to the Epithet rdoc for the full set of configuration options.
 
-Note that `decode` returns `nil` when authentication fails and raises ArgumentError on invalid formats.
+Note that `decode` returns `nil` when authentication fails, and raises `Epithet::FormatError` (an ArgumentError) on invalid formats.
 
 ## Development
 

data/SECURITY.md

@@ -2,39 +2,70 @@
 
 ## Cryptographic considerations
 
-The primary construction is `AES-256-ECB(id(8B) + HMAC-SHA256(id)[0,7])` with the result
-base58 encoded for transmission and a contextual prefix prepended. Subkeys for AES and
-HMAC are by default derived with HKDF using an internal key generator that takes IKM from
-a passphrase via scrypt, salting generated keys by prefix and purpose.
+The primary construction is `AES-256-ECB(id(8B) + MSB_64(HMAC-SHA256(id)))` with the result base58
+encoded for transmission and a contextual prefix prepended.  Subkeys for AES and HMAC are by default
+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.
+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.
 
-The identifiers produced are intentionally deterministic i.e. replayable and reusable. For
-privacy, confidentiality, and authentication purposes they should therefore be considered
-equivalent to the plaintext integer they represent, and those concerns must still be addressed
-in the usual manner.
+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
+forgery attempts, expected success is approximately (N/2^{64}).  The identifiers produced are
+intentionally deterministic i.e. replayable and reusable.  For privacy, confidentiality, and
+authentication purposes they should be considered equivalent to the plaintext integer they
+represent, and those concerns must still be addressed in the usual manner.
 
-The tamper detection is necessarily probabilistic, because the MAC is truncated.
+If configuring alternative cipher algorithms, note that only 128-bit block ciphers that function
+without IV/nonce requirements are accepted.  Streaming ciphers (e.g. chacha20) or block ciphers in
+streaming modes (e.g. aes-256-ctr) must not be used; no nonce/IV value is included in construction,
+making them trivially vulnerable to known-plaintext attacks.  These, CBC/OCB, and other IV/nonce
+modes may also be rejected by Epithet's guardrails.
 
-Encodings are canonical, producing exactly one string per id, and Epithet will reject attempts
-to decode a value exceeding the 128-bit block.
+If configuring alternative digest algorithms, note that any algorithm may be accepted that produces
+at least 64 bits of output.  HMAC does not rest on collision resistance, so even dated digests are
+not trivially forgeable here, but algorithms other than the defaults step outside the supported
+profile.  If you must stray, we recommend staying within the SHA-2 family.
 
-If configuring alternative cipher and digest algorithms, note that only 128-bit block
-ciphers that function without IV/nonce requirements are accepted. Streaming ciphers
-(e.g. chacha20) or block ciphers in streaming modes (e.g. aes-256-ctr) must not be used;
-no nonce/IV value is included in construction, making them trivially vulnerable to
-known-plaintext attacks. These, CBC/OCB, and other IV/nonce modes may also be rejected
-by Epithet's guardrails.
+Encodings are canonical, producing exactly one string per id, and Epithet will reject attempts to
+decode a value exceeding the 128-bit block.
 
-A weak, guessable, or disclosed passphrase will compromise the obfuscation and
-tamper-detection properties.
+A weak, guessable, or disclosed passphrase will compromise the obfuscation and tamper-detection
+properties.
 
 Use Epithet at your own risk.
 
+## On seasoning
+
+Epithet uses salt in two ways.  Firstly, if the default key generator is in use, as part of the
+setup-time scrypt operation turning the configured passphrase into initial keying material.
+Secondly, for the HKDF extract phase to separate derived subkeys by some application-specific
+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.
+
+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.
+
+## On rotation
+
+This gem provides a deterministic primitive; managing lifecycle, policy, and application-aware
+responses to legacy identifiers is intentionally left to framework/application-specific adapters.
+When implementing an adapter, the context parameter is recommended as the basis for key rotation.
+
+## Startup cost
+
+Turning a passphrase into initial keying material is intrinsically expensive.  The default scrypt
+parameters (N=2^17, r=8) cost roughly 128 MiB of peak memory and a fraction of a second of CPU.
+When deployed as indicated this is a boot-time cost, incurred once per configuration rather than
+per encode/decode, but budget for it in memory-constrained deployments.
+
 ## Vulnerabilities
 
 If you think you've found a vulnerability in Epithet that compromises its design or behaviour, please

data/examples/basic.rb

@@ -2,10 +2,13 @@
 
 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') { 'example only' },
-    salt: 'v1'
+    passphrase: ENV.fetch('EPITHET_PASSPHRASE') { Random.bytes(32) },
+    scrypt: { salt: 'myapp/production' },
+    context: 'v1'
   )
 end
 
@@ -13,6 +16,6 @@ epithet_initialize
 user_epithet = Epithet.new('user')
 
 id = Integer(ARGV.shift || 42)
-param = user_epithet.encode(id) #=> "user_VsuNnfEYQJJTJYE3n28jaY"
+param = user_epithet.encode(id) #=> "user_KYM3B4d5ce1NNsv52rAoPg"
 
 puts "User(#{user_epithet.decode(param)}) => #{param}"

data/lib/epithet/version.rb

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

data/lib/epithet.rb

@@ -10,56 +10,63 @@ require 'openssl'
 # prefix (typically a model or table name), produces a replayable string parameter of
 # consistent length, with modest obfuscation and authentication properties.
 #
-# Pseudo-AEAD is via `AES-256-ECB(id(8B) + HMAC-SHA256(id)[0,7])` with the result
+# Pseudo-AEAD is via `AES-256-ECB(id(8B) + MSB_64(HMAC-SHA256(id)))` with the result
 # base58 encoded for transmission and the contextual prefix prepended.
 #
-# Encodings are canonical; a given configuration accepts exactly one string per id.
+# Encodings are canonical; a given configuration produces exactly one string per id.
 #
 # Subkeys for AES and HMAC are by default derived with HKDF using an internal key
 # generator that takes IKM from a passphrase via scrypt.  An alternative key generator
-# may be injected via Config objects. Subkeys are salted by prefix and an optional
-# additional salt, which may be useful for purpose separation or rotation.
+# may be injected via Config objects.  Subkeys are salted by prefix and an optional
+# context string, which may be useful for purpose separation or rotation, and each
+# subkey is bound to the configured name of the algorithm that consumes it.
 #
 # Example usage:
 #
 #     # in setup-environment.sh
-#     EPITHET_PASSPHRASE='example only'
+#     EPITHET_PASSPHRASE='example_only' ; export EPITHET_PASSPHRASE
 #
 #     # ... later, in Ruby ...
 #     Epithet.configure(passphrase: ENV.fetch('EPITHET_PASSPHRASE'))
 #     user_epithet = Epithet.new('user')
-#     user_epithet.encode(1) #=> "user_DAG6Joc5JmgygTBuEo8a9K"
+#     user_epithet.encode(1) #=> "user_NEwRoiarS9wdmiLmjEtti3"
 #
 class Epithet
+  # Raised by #decode when the input is not valid wire format.
+  FormatError = Class.new(ArgumentError)
+
   # Create an encoder/decoder.
   #
   # Setup could be moderately expensive due to key derivation; you are recommended to cache
-  # and reuse instances with equal parameters (e.g. setup once per model)
+  # and reuse instances with equal parameters (e.g. setup the key generation once per runtime).
+  #
+  # * The stringified `prefix` is included in key derivation.  It may be nil or empty, in which
+  #   case the separator is ignored and a bare param will be produced.
   #
-  # * `prefix` is stringified, and may be nil, producing an empty prefix.
-  #   The prefix is included in the salt for key generation.
+  # * `config` is optional and intended for cases where you need finer control than global defaults.
   #
-  # * `config` is optional and intended for cases where you needed finer control than global defaults.
+  # Mixed character encodings across prefix & separator may raise Encoding::CompatibilityError.
   #
   # The simplest typical invocation is `Epithet.new('prefix')`.
   #
   def initialize(prefix, config: Epithet.defaults)
     prefix = String(prefix)
-    key_salt = [prefix.bytesize, prefix, config.salt.bytesize, config.salt].pack('Q>Z*Q>Z*')
-    @block58 = Block58.new(16, alphabet: config.alphabet)
-    @prefix_s = "#{prefix}#{config.separator}"
+    @prefix = prefix.empty? ? prefix : prefix + config.separator
+    @wire_prefix = @prefix.b
+    key_salt = [prefix.bytesize, prefix, config.context.bytesize, config.context].pack('Q>Z*Q>Z*')
+    @codec = config.codec
 
     cipher_key_len = OpenSSL::Cipher.new(config.cipher).key_len
     digest_key_len = OpenSSL::Digest.new(config.digest).block_length
-    cipher_key = config.keygen.generate('epithet:ecb', key_salt, cipher_key_len)
-    digest_key = config.keygen.generate('epithet:mac', key_salt, digest_key_len)
+    cipher_key = config.keygen.generate("epithet:cipher:#{config.cipher}", key_salt, cipher_key_len)
+    digest_key = config.keygen.generate("epithet:digest:#{config.digest}", key_salt, digest_key_len)
 
     @encryptor = OpenSSL::Cipher.new(config.cipher).encrypt.tap { |c| c.key = cipher_key; c.padding = 0 }
     @decryptor = OpenSSL::Cipher.new(config.cipher).decrypt.tap { |c| c.key = cipher_key; c.padding = 0 }
     @hmac = OpenSSL::HMAC.new(digest_key, config.digest)
   end
 
-  # Encode a 64-bit unsigned Integer to a prefixed Base58 string.
+  # Encode a 64-bit unsigned integer to a prefixed base58 string.
   # Raises ArgumentError on invalid values.
   def encode(id)
     raise ArgumentError, 'not a 64-bit unsigned integer' unless Integer === id && id.bit_length <= 64 && id >= 0
@@ -71,20 +78,23 @@ class Epithet
     block = e.update([pt, m].pack('a8a8')) + e.final
     ct = block.unpack('Q>2').then { (_1 << 64) + _2 }
 
-    @prefix_s + @block58.i2s(ct)
+    @prefix + @codec.i2s(ct)
   end
 
-  # Decode a prefixed or raw Base58 string to an Integer.
+  # Decode a prefixed or raw base58 string to an integer.  The input is
+  # stringified and read as bytes, whatever its encoding; raw inputs are
+  # recognised by their exact payload length.
   #
-  # Returns the Integer on success, nil if authentication fails.
-  # Raises ArgumentError on invalid wire format (see Block58#valid?).
+  # Returns the integer on success, nil if authentication fails.
+  # Raises FormatError on invalid wire format (see Block58#valid?).
   def decode(s)
-    s = s.delete_prefix(@prefix_s)
-    raise ArgumentError, 'unexpected format' unless @block58.valid?(s)
+    s = String(s).b
+    s = s.delete_prefix(@wire_prefix) unless s.bytesize == @codec.size
+    raise FormatError, 'unexpected format' unless @codec.valid?(s)
 
     d = @decryptor.dup
     h = @hmac.dup
-    ct = @block58.s2i(s)
+    ct = @codec.s2i(s)
     block = d.update([ct >> 64, ct].pack('Q>2')) + d.final
     pt, m = block.unpack('a8a8')
     id = pt.unpack1('Q>')
@@ -104,30 +114,34 @@ class Epithet
     # #### Examples
     #
     #     # As it might appear in an initializer
-    #     Epithet.configure(passphrase: ENV.fetch('EPITHET_PASSPHRASE'))
+    #     Epithet.configure(
+    #       passphrase: ENV.fetch('EPITHET_PASSPHRASE'),
+    #       scrypt: { salt: "#{MyApp.name}/#{MyApp.env}" }
+    #     )
     #
-    #     # Retaining already-configured passphrase but updating salt,
+    #     # Retaining already-configured passphrase but updating context,
     #     # and using a custom separator.
     #     Epithet.configure(
     #       keygen: Epithet.defaults.keygen,
-    #       salt: 'rotation-19',
+    #       context: 'rotation-19',
     #       separator: '-'
     #     )
     #
     # #### Options
     #
     # *   `:passphrase` - Install new key generator with scrypt-derived key material
-    # *   `:scrypt` - Params for scrypt; omit to use `Keygen::DEFAULT_SCRYPT_PARAMS`
-    # *   `:keygen` - Install an existing key generator
+    # *   `:scrypt` - Merge params for 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; omit for standard `sha256`
-    # *   `:separator` - String inserted between the prefix and the generated param; omit for standard `_`.
-    #                    May be `nil`. Must not share bytes with the alphabet.
-    # *   `:alphabet` - Alphabet for the wire encoding; must be 58 strictly ascending bytes; omit for `Block58::Alphabet`.
-    # *   `:salt` - If supplied, stringified form is included in subkey derivation
+    # *   `:digest` - Must be >= 64 bits digest; omit for standard `sha256`
+    # *   `:separator` - String inserted between the prefix and the generated param.
+    #                    Omit for standard `_`.  May be `nil`.  Must not share bytes with the alphabet.
+    #                    Not emitted when prefix is `nil` or empty.
+    # *   `:alphabet` - Custom base58 alphabet for the wire encoding.  Must be strictly ascending bytes.
+    # *   `:context` - If supplied, string form is included in subkey derivation.
+    #                  Useful for purpose separation, or rotation epochs.
     #
     # At minimum, one of `passphrase:` or `keygen:` is required.
-    # Configuration via `passphrase` is recommended.
     #
     # 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.
@@ -158,27 +172,29 @@ class Epithet
 
   # Class for passing around preset configs. See Epithet::configure for options.
   class Config
-    attr_reader :keygen, :salt, :separator, :alphabet, :cipher, :digest # :nodoc:
+    attr_reader :keygen, :context, :separator, :cipher, :digest, :codec # :nodoc:
 
     def initialize(opts = {})
       opts = opts.dup
-      @separator = String(opts.delete(:separator) { '_' })
-      @salt = String(opts.delete(:salt))
-      @alphabet = String(opts.delete(:alphabet) { Block58::Alphabet })
-      @cipher = opts.delete(:cipher) || 'aes-256-ecb'
-      @digest = opts.delete(:digest) || 'sha256'
+      @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, '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
-
-      @keygen = opts.delete(:keygen) || Keygen.new(
-        passphrase: opts.delete(:passphrase),
-        digest: @digest,
-        scrypt: opts.delete(:scrypt) || Keygen::DEFAULT_SCRYPT_PARAMS)
+      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
 
@@ -191,26 +207,27 @@ class Epithet
     #   salt: 'epithet-default',
     #   N: 1 << 17,
     #   r: 8,
-    #   p: 1,
-    #   length: 32
+    #   p: 1
     # }.freeze
     # ```
     DEFAULT_SCRYPT_PARAMS = {
       salt: 'epithet-default',
       N: 1 << 17,
       r: 8,
-      p: 1,
-      length: 32
+      p: 1
     }.freeze
 
     # Create a new key generator from either high-entropy key material, or a supplied passphrase.
-    def initialize(ikm: nil, passphrase: nil, digest: 'sha256', scrypt: DEFAULT_SCRYPT_PARAMS)
+    # 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 || OpenSSL::KDF.scrypt(passphrase, **scrypt)
-      @digest = digest
+      @ikm = (ikm&.b || OpenSSL::KDF.scrypt(passphrase, **DEFAULT_SCRYPT_PARAMS, **scrypt, length: 32)).freeze
+      @digest = -String(digest)
+      freeze
     end
 
     def inspect
@@ -219,28 +236,41 @@ class Epithet
 
     # Derive a key via HKDF.
     def generate(info, salt, length)
-      OpenSSL::KDF.hkdf(@ikm, hash: @digest, info: info, salt: salt, length: length)
+      OpenSSL::KDF.hkdf(@ikm, hash: @digest, info:, salt:, length:)
     end
   end
 
-  # Fixed-length Base58 codec for a fixed-size block.
+  # 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(0)
+      @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
-      @max = i2s((1 << (block_size * 8)) - 1).freeze
+      @limit = 1 << (block_size * 8)
+      @max = i2s(@limit - 1).freeze
     end
 
     def inspect
@@ -248,13 +278,15 @@ class Epithet
     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 <= @max && s.count(@charsel) == @size
+      String === s && s.bytesize == @size && (s = s.b) <= @max && s.count(@charsel) == @size
     end
 
-    # Encode a non-negative Integer to fixed-length Base58.
-    # Truncates if int >= 58**size.
+    # 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
@@ -269,47 +301,81 @@ class Epithet
       out
     end
 
-    # Decode a fixed-length Base58 string to an Integer.
-    # Assumes the input passes `#valid?`. Wraps at 58**size on the i2s round trip.
+    # Decode a fixed-length 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 coefficients, this is ~8x faster than Horner's scheme
+      # 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 when using YJIT, by chunking
-      # intermediate results into 64-bit integers.
+      # 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
 
-      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)) +
-                          58 * lut.getbyte(str.getbyte(20)) +
-                        3364 * acc1 +
-      1449225352009601191936 * acc0
-
-      # rubocop:enable Style/NumericLiterals, Lint/AmbiguousOperatorPrecedence, Layout
+      # 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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: epithet
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Josh Goodall
@@ -65,7 +65,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Epithet generates stable, prefixed, Base58 identifiers from 64-bit integers
+description: Epithet generates stable, prefixed, base58 identifiers from 64-bit integers
   using AES and HMAC.
 email:
 - inopinatus@hey.com
@@ -96,7 +96,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.3'
+      version: '3.4'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -105,5 +105,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.10
 specification_version: 4
-summary: External base58 identifiers with reversible, authenticated obfuscation.
+summary: External base58 identifiers with reversible, tamper-evident obfuscation.
 test_files: []