epithet 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8d4c22a2ee0f83df400b54761a8e5c0a03df04390c6c9cdbb486a8c907f1812
-  data.tar.gz: a8507f28f992f524284262d498b107cfb566f9fefb66c5d97e2f29322d7a9fe4
+  metadata.gz: 3695519b4c82955cf40a1d3b5109fbeaf3458085146500eea600c0fa8ce86bb0
+  data.tar.gz: f527803fc071230ae440b9e199f65ad890a0bf8778d643258b0c58b1a0f53b78
 SHA512:
-  metadata.gz: bc64b08e053da076bab07709bed61f1ff0c41ebcdb59a3963f63b7846b897efa2b8a2de43330b8bb0a3d7b473d377dc676da2ef4331ebcd52d18749809b8b1c3
-  data.tar.gz: 8495ae0d1ed045619ed752ef55cc240ff5180b6da68bf27f2cc858e6ec1a190eb93e10c5dc1e23665a363ee42448dc1df6d23f3522ab03813f6d2f48da322b44
+  metadata.gz: 725d659f196c53fc6ea438607dd9319b95b5aac8b61a68c5708b62f9eed26fd76012b3addb45a9a9880952c7275bbc2e5aace3390998c082e6dedd48c76fc174
+  data.tar.gz: aa15ac11d2ae8c1454ce5d086c25fbae5aee1957747e77dfcbdf626c470ddf438df69a3580eee98ecca7131243ed175d53c5edbc245b6b8c3c96b01742cf2914

data/CHANGELOG.md

@@ -1,4 +1,21 @@
 # Changelog
 
+## 1.0.0 - 2026-07-14
+
+### Breaking changes
+
+- Treat out-of-range base58 strings as invalid instead of wrapping them.
+- Reject separators that share codepoints with the encoding alphabet.
+- Drop support for Rubies < 3.3.
+
+### Other changes
+
+- Code style nitpicks.
+- Support for 32-bit Rubies.
+- Support for Ruby 4.0.
+- Documentation improvements.
+- A custom alphabet may be configured via `Epithet::Config`.
+- Custom alphabets must be strictly ascending byte codepoints.
+
 ## 0.1.0 - 2025-12-22
 - Initial release.

data/SECURITY.md

@@ -8,18 +8,21 @@ HMAC are by default derived with HKDF using an internal key generator that takes
 a passphrase via scrypt, salting generated keys by prefix and purpose.
 
 This library is intended for high-performance obfuscation of integer sequences, deflection
-of casual tampering, and conversion to a compact, stable wire parameter format.  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.
+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 purposes must still be addressed
+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.
+
 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;
@@ -37,5 +40,3 @@ Use Epithet at your own risk.
 If you think you've found a vulnerability in Epithet that compromises its design or behaviour, please
 [report it via a private advisory](https://github.com/inopinatus/epithet/security/advisories/new).
 Do not open a public issue or pull request.
-
-

data/examples/basic.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'epithet'
 
 def epithet_initialize

data/lib/epithet/version.rb

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

data/lib/epithet.rb

@@ -13,6 +13,8 @@ require 'openssl'
 # Pseudo-AEAD is via `AES-256-ECB(id(8B) + HMAC-SHA256(id)[0,7])` with the result
 # base58 encoded for transmission and the contextual prefix prepended.
 #
+# Encodings are canonical; a given configuration accepts 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
@@ -43,14 +45,14 @@ class Epithet
   #
   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)
+    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}"
 
     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:ecb', key_salt, cipher_key_len)
+    digest_key = config.keygen.generate('epithet:mac', 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 }
@@ -60,7 +62,7 @@ class Epithet
   # 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.size == 8 && id >= 0
+    raise ArgumentError, 'not a 64-bit unsigned integer' unless Integer === id && id.bit_length <= 64 && id >= 0
 
     e = @encryptor.dup
     h = @hmac.dup
@@ -75,10 +77,10 @@ class Epithet
   # Decode a prefixed or raw Base58 string to an Integer.
   #
   # Returns the Integer on success, nil if authentication fails.
-  # Raises ArgumentError on invalid formats.
+  # Raises ArgumentError on invalid wire format (see Block58#valid?).
   def decode(s)
     s = s.delete_prefix(@prefix_s)
-    raise ArgumentError, "unexpected format" unless @block58.valid?(s)
+    raise ArgumentError, 'unexpected format' unless @block58.valid?(s)
 
     d = @decryptor.dup
     h = @hmac.dup
@@ -119,7 +121,9 @@ class Epithet
     # *   `:keygen` - Install 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` - Inserted as string between the prefix and the generated param. may be nil; omit for underscore.
+    # *   `: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
     #
     # At minimum, one of `passphrase:` or `keygen:` is required.
@@ -149,20 +153,23 @@ class Epithet
     #     acct_epithet = Epithet.new('acct', config: cfg)
     #
     def configure(opts) = @defaults = Config === opts ? opts : Config.new(opts)
-    def defaults() = @defaults || raise(RuntimeError, "no Epithet defaults configured")
+    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, :salt, :separator, :cipher, :digest # :nodoc:
+    attr_reader :keygen, :salt, :separator, :alphabet, :cipher, :digest # :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'
 
       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
@@ -182,7 +189,7 @@ class Epithet
     # ```ruby
     # DEFAULT_SCRYPT_PARAMS = {
     #   salt: 'epithet-default',
-    #   N: 1<<17,
+    #   N: 1 << 17,
     #   r: 8,
     #   p: 1,
     #   length: 32
@@ -190,16 +197,16 @@ class Epithet
     # ```
     DEFAULT_SCRYPT_PARAMS = {
       salt: 'epithet-default',
-      N: 1<<17,
+      N: 1 << 17,
       r: 8,
       p: 1,
       length: 32
     }.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)
+    def initialize(ikm: nil, passphrase: nil, digest: 'sha256', scrypt: DEFAULT_SCRYPT_PARAMS)
       if (passphrase.nil? && ikm.nil?) || (!passphrase.nil? && !ikm.nil?)
-        raise ArgumentError, "keygen requires either ikm or passphrase"
+        raise ArgumentError, 'keygen requires either ikm or passphrase'
       end
 
       @ikm = ikm || OpenSSL::KDF.scrypt(passphrase, **scrypt)
@@ -218,29 +225,35 @@ class Epithet
 
   # Fixed-length Base58 codec for a fixed-size block.
   class Block58
-    # `= "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"`
-    Alphabet = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+    # `= '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'`
+    Alphabet = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'
 
     # 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)
       @alphabet = alphabet.b.freeze
-      raise ArgumentError, "invalid alphabet length" unless @alphabet.bytesize == 58
+      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)
       @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
     end
 
     def inspect
       "#<#{self.class}:#{'%#016x' % (object_id << 1)} size=#{@size} alphabet=#{@alphabet}>"
     end
 
-    # Return true if the string has the right size and alphabet.
+    # Return true if the string is in range with the right size and alphabet.
     def valid?(s)
-      String === s && s.bytesize == @size && s.count(@charsel) == @size
+      String === s && s.bytesize == @size && s <= @max && s.count(@charsel) == @size
     end
 
     # Encode a non-negative Integer to fixed-length Base58.
+    # Truncates if int >= 58**size.
     def i2s(int)
       # Using divmod+setbyte is faster than Integer#digits under YJIT,
       # and about equal in plain MRI.
@@ -257,8 +270,10 @@ class Epithet
     end
 
     # Decode a fixed-length Base58 string to an Integer.
-    # Assumes the input passes `#valid?`.
+    # Assumes the input passes `#valid?`. Wraps at 58**size on the i2s round trip.
     def s2i(str)
+      # rubocop:disable Style/NumericLiterals, Lint/AmbiguousOperatorPrecedence, Layout
+      #
       # By unrolling coefficients, this is ~8x faster than Horner's scheme
       #
       #   str.each_byte.inject(0) { _1 * 58 + @lut[_2] }
@@ -293,6 +308,8 @@ class Epithet
                           58 * lut.getbyte(str.getbyte(20)) +
                         3364 * acc1 +
       1449225352009601191936 * acc0
+
+      # rubocop:enable Style/NumericLiterals, Lint/AmbiguousOperatorPrecedence, Layout
     end
   end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: epithet
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Josh Goodall
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-12-22 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -52,6 +51,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Epithet generates stable, prefixed, Base58 identifiers from 64-bit integers
   using AES and HMAC.
 email:
@@ -76,7 +89,6 @@ metadata:
   changelog_uri: https://github.com/inopinatus/epithet/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/inopinatus/epithet/issues
   rubygems_mfa_required: 'true'
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -84,15 +96,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
-signing_key: 
+rubygems_version: 4.0.10
 specification_version: 4
 summary: External base58 identifiers with reversible, authenticated obfuscation.
 test_files: []