epithet 1.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 100d3ac2b640a77419d9d6f45228ed67251285ed6f0bf390b9249573d20db887
-  data.tar.gz: 5350064afb6799feec528888c475bcc0d8e403272f13332d00bdcd43b7bcd47c
+  metadata.gz: 40b8e5a401923aeaaf82f8340d43747433ea1440f7de4b1628087c326a916622
+  data.tar.gz: bf139e16eecab4aa544981b15f28fb267f1e55e38ca37a0828c6836c064319c3
 SHA512:
-  metadata.gz: 77e5c3acde924854471a36ede3d43e010fcf4f2bd7f4a49b75c753e7c80e4c0651355c0c33ec28a9d1c229abf14fd5da61b40c1eae2a23cbd31f8c8ef94cd9a5
-  data.tar.gz: 21a8c95376177e30642bed7aefd1b1f87ccd5f0a00d489592c154ed1ecf86cdf076df57f04f98d01ad802b4ea1c62367b5afcc0fdd165501f95fe081ac10efd9
+  metadata.gz: 324dec4e145ca1d5e8f3b9a22c3788ab3e9d1771d614c7dab5c94288888c59ce7235cbdd1a2dcd878015321f2264ae21702020b8bc9f8b6aaf3191bc50df9adc
+  data.tar.gz: 55f0b6b5bd0061c3545f9c644bfaec6eb3e7721d0df33b1217a52384da63b4ff96c0d5848f2d0340460bf3e3b8c6e9aef38cd9e677665e6abcfa09f1fd4a9024

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # 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

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,7 +21,7 @@ gem install epithet
 
 ## Usage
 
-With `EPITHET_PASSPHRASE="example only"`:
+With `EPITHET_PASSPHRASE=example_only`:
 
 ```ruby
 require 'epithet'
@@ -29,7 +29,8 @@ require 'epithet'
 def epithet_initialize
   Epithet.configure(
     passphrase: ENV.fetch('EPITHET_PASSPHRASE'),
-    salt: 'v1'
+    scrypt: { salt: 'myapp/production' },
+    context: 'v1'
   )
 end
 
@@ -38,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,10 +2,10 @@
 
 ## 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
+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 purpose.
+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
@@ -13,38 +13,58 @@ to predict.  Although it uses standard cryptographic primitives to do so, the de
 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.
-
-The tamper detection is necessarily probabilistic, because the MAC is truncated.
-
-Encodings are canonical, producing exactly one string per id, and Epithet will reject attempts to
-decode a value exceeding the 128-bit block.
+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.
 
 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
+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.
 
-If configuring alternative digest algorithms, note that any algorithm may be accepted whenever they
-it 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 security profile.  If you must stray, stay within the SHA-2 family.
+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.
+
+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.
 
 Use Epithet at your own risk.
 
-## On salt
+## 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
 
-Epithet uses salt in two ways.  Firstly, as part of a scrypt operation to turn the configured
-passphrase into initial keying material.  Secondly, to supply an additional affordance to separate
-derived subkeys by some application-specific division such as purpose or rotation epoch.  Epithet
-does not store or verify passwords; both uses of salt are non-secret configuration and may safely be
-committed to source control.
+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
 

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.1.0'`
-  VERSION = '1.1.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.build(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,21 +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. Raw inputs are
+  # 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) unless s.bytesize == @block58.size
-    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>')
@@ -110,28 +119,29 @@ class Epithet
     #       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, merged over `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.
@@ -162,27 +172,28 @@ 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')
+      @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) || {})
+      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
@@ -196,26 +207,25 @@ 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.
-    # Supplied scrypt params are merged over 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 ? ikm.b : OpenSSL::KDF.scrypt(passphrase, **DEFAULT_SCRYPT_PARAMS, **scrypt)).freeze
+      @ikm = (ikm&.b || OpenSSL::KDF.scrypt(passphrase, **DEFAULT_SCRYPT_PARAMS, **scrypt, length: 32)).freeze
       @digest = -String(digest)
       freeze
     end
@@ -226,11 +236,11 @@ 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
@@ -239,7 +249,7 @@ class Epithet
     # `= '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'`
     Alphabet = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'
 
-    POW58 = Array.new(11) { 58**_1 }.freeze # :nodoc:
+    POW58 = Array.new(11) { 58**it }.freeze # :nodoc:
 
     attr_reader :size
 
@@ -255,11 +265,12 @@ class Epithet
       @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
@@ -267,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
@@ -288,8 +301,8 @@ 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)
       # Chunking intermediate results into 64-bit integers is ~5x faster
       # under YJIT than Horner's scheme
@@ -324,14 +337,14 @@ class Epithet
         raise ArgumentError, 'unrolled codec requires a 16-byte block' unless @size == 22
       end
 
-      # Decode a fixed-length Base58 string to an Integer.
-      # Assumes the input passes `#valid?`.
+      # 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 is ~1.6x
-        # faster under YJIT than the generic chunked Block58#s2i, and ~8x
-        # faster than Horner's scheme.
+        # 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 +
@@ -356,10 +369,10 @@ class Epithet
                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
+               lut.getbyte(str.getbyte(21)) +
+               lut.getbyte(str.getbyte(20)) * 58 +
+                                       acc1 * 3364 +
+                                       acc0 * 1449225352009601191936
 
         # rubocop:enable Style/NumericLiterals, Lint/AmbiguousOperatorPrecedence, Layout
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: epithet
 version: !ruby/object:Gem::Version
-  version: 1.1.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: []