epithet 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c8d4c22a2ee0f83df400b54761a8e5c0a03df04390c6c9cdbb486a8c907f1812
+  data.tar.gz: a8507f28f992f524284262d498b107cfb566f9fefb66c5d97e2f29322d7a9fe4
+SHA512:
+  metadata.gz: bc64b08e053da076bab07709bed61f1ff0c41ebcdb59a3963f63b7846b897efa2b8a2de43330b8bb0a3d7b473d377dc676da2ef4331ebcd52d18749809b8b1c3
+  data.tar.gz: 8495ae0d1ed045619ed752ef55cc240ff5180b6da68bf27f2cc858e6ec1a190eb93e10c5dc1e23665a363ee42448dc1df6d23f3522ab03813f6d2f48da322b44

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog
+
+## 0.1.0 - 2025-12-22
+- Initial release.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Josh Goodall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,70 @@
+# Epithet
+
+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/
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'epithet'
+```
+
+Or install directly:
+
+```bash
+gem install epithet
+```
+
+## Usage
+
+```ruby
+require 'epithet'
+
+def epithet_initialize
+  Epithet.configure(
+    passphrase: ENV.fetch('EPITHET_PASSPHRASE') { 'example only' },
+    salt: 'v1'
+  )
+end
+
+epithet_initialize
+user_epithet = Epithet.new('user')
+
+id = 42
+param = user_epithet.encode(id)
+# => "user_VsuNnfEYQJJTJYE3n28jaY"
+
+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.
+
+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.
+
+## Development
+
+Install dependencies and run tests:
+
+```bash
+bundle install
+rake test
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/inopinatus/epithet.
+
+## Security considerations
+
+See [`SECURITY.md`](SECURITY.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/SECURITY.md

@@ -0,0 +1,41 @@
+# Epithet security
+
+## 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.
+
+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.
+
+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
+in the usual manner.
+
+The tamper detection is necessarily probabilistic, because the MAC is truncated.
+
+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.
+
+A weak, guessable, or disclosed passphrase will compromise the obfuscation and
+tamper-detection properties.
+
+Use Epithet at your own risk.
+
+## Vulnerabilities
+
+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

@@ -0,0 +1,16 @@
+require 'epithet'
+
+def epithet_initialize
+  Epithet.configure(
+    passphrase: ENV.fetch('EPITHET_PASSPHRASE') { 'example only' },
+    salt: 'v1'
+  )
+end
+
+epithet_initialize
+user_epithet = Epithet.new('user')
+
+id = Integer(ARGV.shift || 42)
+param = user_epithet.encode(id) #=> "user_VsuNnfEYQJJTJYE3n28jaY"
+
+puts "User(#{user_epithet.decode(param)}) => #{param}"

data/lib/epithet/version.rb

@@ -0,0 +1,4 @@
+class Epithet
+  # `= "0.1.0"`
+  VERSION = "0.1.0"
+end

data/lib/epithet.rb

@@ -0,0 +1,298 @@
+# frozen_string_literal: true
+
+require 'epithet/version'
+require 'openssl'
+
+#
+# Epithet, a tool for external identifiers.
+#
+# Given a 64-bit value such as a database sequence ID, and a context-specific
+# 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
+# base58 encoded for transmission and the 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.  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.
+#
+# Example usage:
+#
+#     # in setup-environment.sh
+#     EPITHET_PASSPHRASE='example only'
+#
+#     # ... later, in Ruby ...
+#     Epithet.configure(passphrase: ENV.fetch('EPITHET_PASSPHRASE'))
+#     user_epithet = Epithet.new('user')
+#     user_epithet.encode(1) #=> "user_DAG6Joc5JmgygTBuEo8a9K"
+#
+class Epithet
+  # 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)
+  #
+  # * `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 needed finer control than global defaults.
+  #
+  # 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)
+    @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)
+
+    @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.
+  # Raises ArgumentError on invalid values.
+  def encode(id)
+    raise ArgumentError, "not a 64-bit unsigned integer" unless Integer === id && id.size == 8 && id >= 0
+
+    e = @encryptor.dup
+    h = @hmac.dup
+    pt = [id].pack('Q>')
+    m = h.update(pt).digest
+    block = e.update([pt, m].pack('a8a8')) + e.final
+    ct = block.unpack('Q>2').then { (_1 << 64) + _2 }
+
+    @prefix_s + @block58.i2s(ct)
+  end
+
+  # Decode a prefixed or raw Base58 string to an Integer.
+  #
+  # Returns the Integer on success, nil if authentication fails.
+  # Raises ArgumentError on invalid formats.
+  def decode(s)
+    s = s.delete_prefix(@prefix_s)
+    raise ArgumentError, "unexpected format" unless @block58.valid?(s)
+
+    d = @decryptor.dup
+    h = @hmac.dup
+    ct = @block58.s2i(s)
+    block = d.update([ct >> 64, ct].pack('Q>2')) + d.final
+    pt, m = block.unpack('a8a8')
+    id = pt.unpack1('Q>')
+
+    cteq([h.update(pt).digest].pack('a8'), m) ? id : nil
+  end
+
+  # Constant time octet-string comparison.
+  def cteq(a, b) # :nodoc:
+    return false unless a.bytesize == b.bytesize
+    OpenSSL.fixed_length_secure_compare(a, b)
+  end
+
+  class << self
+    # Configure the library.
+    #
+    # #### Examples
+    #
+    #     # As it might appear in an initializer
+    #     Epithet.configure(passphrase: ENV.fetch('EPITHET_PASSPHRASE'))
+    #
+    #     # Retaining already-configured passphrase but updating salt,
+    #     # and using a custom separator.
+    #     Epithet.configure(
+    #       keygen: Epithet.defaults.keygen,
+    #       salt: '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
+    # *   `: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.
+    # *   `:salt` - If supplied, stringified form is included in subkey derivation
+    #
+    # 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.
+    #
+    # See [`SECURITY.md`](SECURITY.md) for discussion of ciphers & digests.
+    #
+    # #### Multiple configurations
+    #
+    # You can produce & store configurations, thus:
+    #
+    #     cfg = Epithet::Config.new(
+    #       keygen: my_key_gen,
+    #       cipher: 'stronk-512-jcb',
+    #       digest: 'md7'
+    #     )
+    #
+    # and either install this as default with
+    #
+    #     Epithet.configure(cfg)
+    #
+    # or pass it to `Epithet::new` as
+    #
+    #     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")
+  end
+
+  # Class for passing around preset configs. See Epithet::configure for options.
+  class Config
+    attr_reader :keygen, :salt, :separator, :cipher, :digest # :nodoc:
+    def initialize(opts = {})
+      opts = opts.dup
+      @separator = String(opts.delete(:separator) { '_' })
+      @salt = String(opts.delete(:salt))
+      @cipher = opts.delete(:cipher) || 'aes-256-ecb'
+      @digest = opts.delete(:digest) || 'sha256'
+
+      cipher = OpenSSL::Cipher.new(@cipher)
+      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, "unused option(s) #{opts.keys}" unless opts.empty?
+    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,
+    #   length: 32
+    # }.freeze
+    # ```
+    DEFAULT_SCRYPT_PARAMS = {
+      salt: 'epithet-default',
+      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)
+      if (passphrase.nil? && ikm.nil?) || (!passphrase.nil? && !ikm.nil?)
+        raise ArgumentError, "keygen requires either ikm or passphrase"
+      end
+
+      @ikm = ikm || OpenSSL::KDF.scrypt(passphrase, **scrypt)
+      @digest = digest
+    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: info, salt: salt, length: length)
+    end
+  end
+
+  # Fixed-length Base58 codec for a fixed-size block.
+  class Block58
+    # `= "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"`
+    Alphabet = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+
+    # Create a codec for a block size in bytes.
+    def initialize(block_size, alphabet: Alphabet)
+      @alphabet = alphabet.b.freeze
+      raise ArgumentError, "invalid alphabet length" unless @alphabet.bytesize == 58
+      @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
+    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.
+    def valid?(s)
+      String === s && s.bytesize == @size && s.count(@charsel) == @size
+    end
+
+    # Encode a non-negative Integer to fixed-length Base58.
+    def i2s(int)
+      # 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?`.
+    def s2i(str)
+      # By unrolling coefficients, this is ~8x faster 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.
+      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)) +
+                          58 * lut.getbyte(str.getbyte(20)) +
+                        3364 * acc1 +
+      1449225352009601191936 * acc0
+    end
+  end
+end

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: epithet
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Josh Goodall
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2025-12-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  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'
+- !ruby/object:Gem::Dependency
+  name: rake
+  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'
+- !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'
+description: Epithet generates stable, prefixed, Base58 identifiers from 64-bit integers
+  using AES and HMAC.
+email:
+- inopinatus@hey.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- SECURITY.md
+- examples/basic.rb
+- lib/epithet.rb
+- lib/epithet/version.rb
+homepage: https://github.com/inopinatus/epithet
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://inopinatus.github.io/epithet/
+  source_code_uri: https://github.com/inopinatus/epithet
+  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
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: External base58 identifiers with reversible, authenticated obfuscation.
+test_files: []