passlib 0.1.0

data/lib/passlib/phpass.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Passlib
+  # Handles phpass Portable Hash password hashing.
+  #
+  # phpass was widely used by PHP applications (WordPress, Drupal, phpBB) as a
+  # fallback when bcrypt was unavailable.  It applies iterated MD5 with a
+  # configurable round count and an 8-character salt, encoding the result in a
+  # custom base64 alphabet.
+  #
+  # Two MCF identifiers are recognized:
+  # - +$P$+ — standard phpass portable hash
+  # - +$H$+ — phpBB3 variant (identical algorithm, different identifier)
+  #
+  # New hashes are always produced with the +$P$+ identifier.
+  #
+  # Hash format: +$P$<rounds_char><salt8><checksum22>+
+  #
+  # This format is compatible with the
+  # {https://passlib.readthedocs.io/en/stable/lib/passlib.hash.phpass.html
+  # phpass portable hash} as implemented in Python's passlib.
+  #
+  # @note phpass is considered a legacy algorithm.  It is supported here for
+  #   verifying existing hashes and migrating users to a stronger scheme.  Do
+  #   not use it for new hashes.
+  #
+  # @example
+  #   hash = Passlib::PHPass.create("hunter2")
+  #   hash.verify("hunter2")  # => true
+  #   hash.to_s               # => "$P$H..."
+  #
+  # @!method self.create(secret, **options)
+  #   Creates a new phpass hash.
+  #   @param secret [String] the plaintext password
+  #   @option options [Integer] :rounds base-2 log of the iteration count,
+  #     7–30 (default: 19, i.e. 2^19 = 524 288 iterations)
+  #   @option options [String] :salt custom 8-character salt using the phpass
+  #     alphabet +./0-9A-Za-z+ (normally auto-generated)
+  #   @return [PHPass]
+  class PHPass < Password
+    register mcf: %w[P H]
+    options :rounds, :salt
+
+    # Alphabet used for the rounds character, salt, and checksum encoding.
+    ITOA64 = "./0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+
+    DEFAULT_ROUNDS = 19
+    MIN_ROUNDS     = 7
+    MAX_ROUNDS     = 30
+
+    FORMAT = /\A\$[PH]\$([.\/0-9A-Za-z])([.\/0-9A-Za-z]{8})([.\/0-9A-Za-z]{22})\z/
+    private_constant :FORMAT
+
+    # Verifies +secret+ against the stored hash.
+    #
+    # Overrides the default +create_comparable+ approach so that +$H$+ hashes
+    # (phpBB3 variant) are verified correctly: both identifiers produce the same
+    # 22-character checksum, so only that portion is compared.
+    #
+    # @param secret [String] the plaintext password
+    # @return [Boolean]
+    def verify(secret)
+      Passlib.secure_compare(@string[-22..], phpass_digest(secret))
+    end
+
+    # @return [Boolean] +true+ if the stored iteration count differs from the
+    #   configured target
+    def upgrade?
+      @rounds != (config.rounds || DEFAULT_ROUNDS).clamp(MIN_ROUNDS, MAX_ROUNDS)
+    end
+
+    private
+
+    def load(string)
+      m = FORMAT.match(string) or raise ArgumentError, "invalid phpass hash: #{string.inspect}"
+      @rounds = ITOA64.index(m[1])
+      @salt   = m[2]
+      string
+    end
+
+    def create(secret)
+      @rounds = (config.rounds || DEFAULT_ROUNDS).clamp(MIN_ROUNDS, MAX_ROUNDS)
+      @salt   = config.salt || generate_salt
+      "$P$#{ITOA64[@rounds]}#{@salt}#{phpass_digest(secret)}"
+    end
+
+    # Computes the 22-character phpass checksum.
+    #
+    # 1. +digest = MD5(salt + UTF-8 password)+
+    # 2. Repeat +2^rounds+ times: +digest = MD5(digest + UTF-8 password)+
+    # 3. Encode the 16-byte result with the phpass base64 encoding
+    def phpass_digest(secret)
+      pw     = secret.encode("UTF-8").b
+      digest = OpenSSL::Digest::MD5.digest(@salt + pw)
+      (1 << @rounds).times { digest = OpenSSL::Digest::MD5.digest(digest + pw) }
+      encode64(digest)
+    end
+
+    # Encodes +bytes+ using the phpass custom base64 scheme.
+    #
+    # Groups bytes in sets of three and packs them into four 6-bit characters
+    # using LSB-first bit ordering (unlike standard base64 which is MSB-first).
+    # For 16 bytes this yields exactly 22 characters; for 6 bytes, 8 characters.
+    def encode64(bytes)
+      result = +""
+      i = 0
+      while i < bytes.bytesize
+        v = bytes.getbyte(i)
+        result << ITOA64[v & 0x3f]
+        v |= bytes.getbyte(i + 1) << 8 if i + 1 < bytes.bytesize
+        result << ITOA64[(v >> 6) & 0x3f]
+        break if i + 1 >= bytes.bytesize
+        v |= bytes.getbyte(i + 2) << 16 if i + 2 < bytes.bytesize
+        result << ITOA64[(v >> 12) & 0x3f]
+        break if i + 2 >= bytes.bytesize
+        result << ITOA64[(v >> 18) & 0x3f]
+        i += 3
+      end
+      result
+    end
+
+    # Generates a random 8-character salt by encoding 6 random bytes.
+    def generate_salt
+      encode64(Internal.random_bytes(6))
+    end
+  end
+end

data/lib/passlib/scrypt.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Passlib
+  # Handles scrypt password hashing via the {https://rubygems.org/gems/scrypt scrypt} gem.
+  #
+  # Two hash formats are accepted on load:
+  # - Passlib MCF: +$scrypt$ln=<ln>,r=<r>,p=<p>$<salt>$<checksum>+
+  # - SCrypt gem: the native hex format produced by the scrypt gem
+  #   (normalized to MCF on load)
+  #
+  # New hashes are always produced in the passlib MCF format.
+  #
+  # @example
+  #   hash = Passlib::SCrypt.create("hunter2", ln: 14)
+  #   hash.verify("hunter2")  # => true
+  #   hash.to_s               # => "$scrypt$ln=14,r=8,p=1$...$..."
+  #
+  # @!method self.create(secret, **options)
+  #   Creates a new scrypt hash.
+  #   @param secret [String] the plaintext password
+  #   @option options [Integer] :ln      CPU/memory cost as a base-2 log (default: 16,
+  #     meaning N=65536), mutually exclusive with +:n+
+  #   @option options [Integer] :n       CPU/memory cost as an integer power of two,
+  #     converted to +:ln+ internally
+  #   @option options [Integer] :r       block size (default: 8)
+  #   @option options [Integer] :p       parallelization factor (default: 1)
+  #   @option options [String]  :salt    custom salt as a binary string (default: 16 random bytes)
+  #   @option options [Integer] :key_len derived key length in bytes (default: 32)
+  #   @return [SCrypt]
+  class SCrypt < Password
+    MCF_PATTERN  = /\A\$scrypt\$ln=(\d+),r=(\d+),p=(\d+)\$(.+)\$(.+)\z/
+    RUBY_PATTERN = /\A([0-9a-f]+)\$([0-9a-f]+)\$([0-9a-f]+)\$([0-9a-f]{16,64})\$([0-9a-f]{32,1024})\Z/
+    private_constant :MCF_PATTERN, :RUBY_PATTERN
+
+    external "scrypt", "~> 3.1"
+    options :ln, :n, :r, :p, :salt, :key_len
+    register mcf: "scrypt", pattern: RUBY_PATTERN
+
+    # @param secret [String] the plaintext password to re-hash
+    # @return [SCrypt] a new instance hashed with the same salt and parameters
+    def create_comparable(secret)
+      self.class.create(secret, salt: @salt, ln: @ln, r: @r, p: @p, key_len: @key_len)
+    end
+
+    def upgrade?
+      target_ln = config.n ? Math.log2(config.n).to_i : (config.ln || 16)
+      @ln != target_ln
+    end
+
+    private
+
+    def create(secret)
+      @ln       ||= config.n ? Math.log2(config.n).to_i : config.ln || 16
+      @r        ||= config.r       || 8
+      @p        ||= config.p       || 1
+      @salt     ||= config.salt    || Internal.random_bytes(16)
+      @key_len  ||= config.key_len || 32
+      @checksum ||= ::SCrypt::Engine.scrypt(secret, @salt, 2 ** @ln, @r, @p, @key_len)
+      "$scrypt$ln=#{@ln},r=#{@r},p=#{@p}$#{Internal.encode64(@salt)}$#{Internal.encode64(@checksum)}"
+    end
+
+    def load(string)
+      case string
+      when MCF_PATTERN
+        # passlib format
+        match     = Regexp.last_match
+        @ln       = match[1].to_i
+        @r        = match[2].to_i
+        @p        = match[3].to_i
+        @salt     = Internal.decode64(match[4])
+        @checksum = Internal.decode64(match[5])
+        @key_len  = @checksum.length
+        string
+      when RUBY_PATTERN
+        # scrypt gem format
+        match     = Regexp.last_match
+        @ln       = Math.log2(match[1].to_i(16)).to_i
+        @r        = match[2].to_i(16)
+        @p        = match[3].to_i(16)
+        @salt     = [match[4].sub(/^(00)+/, '')].pack('H*')
+        @checksum = [match[5].sub(/^(00)+/, '')].pack('H*')
+        @key_len  = @checksum.length
+        create(nil)
+      else
+        raise UnknownHashFormat, "invalid scrypt hash format"
+      end
+    end
+  end
+end

data/lib/passlib/sha1_crypt.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Passlib
+  # Handles SHA1-crypt password hashing (NetBSD's crypt-sha1).
+  #
+  # SHA1-crypt applies iterated HMAC-SHA1 to derive a password hash.  It was
+  # designed by Simon Gerraty for NetBSD as an alternative to DES-crypt that
+  # supports long passwords.  It is a legacy algorithm — supported here for
+  # verifying existing hashes and migrating users to a stronger scheme.
+  #
+  # Hash format: +$sha1$<rounds>$<salt>$<checksum>+
+  #
+  # - +rounds+ — decimal integer, iteration count (1–4,294,967,295)
+  # - +salt+ — 1–64 characters from +./0-9A-Za-z+ (default: 8 random chars)
+  # - +checksum+ — 28 characters from +./0-9A-Za-z+
+  #
+  # This format is compatible with the
+  # {https://passlib.readthedocs.io/en/stable/lib/passlib.hash.sha1_crypt.html
+  # sha1_crypt} as implemented in Python's passlib.
+  #
+  # @note SHA1-crypt is a legacy algorithm.  It is supported here for
+  #   verifying existing hashes and migrating users to a stronger scheme.  Do
+  #   not use it for new hashes.
+  #
+  # @example
+  #   hash = Passlib::SHA1Crypt.create("hunter2")
+  #   hash.verify("hunter2")  # => true
+  #   hash.to_s               # => "$sha1$480000$...$..."
+  #
+  # @!method self.create(secret, **options)
+  #   Creates a new SHA1-crypt hash.
+  #   @param secret [String] the plaintext password
+  #   @option options [Integer] :rounds iteration count, 1–4,294,967,295
+  #     (default: 480,000)
+  #   @option options [String] :salt custom salt string, up to 64 characters
+  #     from +./0-9A-Za-z+ (default: 8 random characters)
+  #   @return [SHA1Crypt]
+  class SHA1Crypt < Password
+    register :sha1_crypt, mcf: "sha1"
+    options :rounds, :salt
+
+    HASH_CHARS    = "./0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+    DEFAULT_ROUNDS = 480_000
+    MIN_ROUNDS    = 1
+    MAX_ROUNDS    = 4_294_967_295
+    MAX_SALT_LEN  = 64
+
+    # Byte-index groups for encoding the 20-byte SHA1 digest into 28 characters.
+    # The last group wraps around to reuse byte 0, following the sha1crypt spec.
+    ENCODE_OFFSETS = [
+      [0, 1, 2], [3, 4, 5], [6, 7, 8], [9, 10, 11],
+      [12, 13, 14], [15, 16, 17], [18, 19, 0],
+    ].freeze
+
+    LOAD_PATTERN = %r{\A\$sha1\$(\d+)\$([./0-9A-Za-z]{1,64})\$([./0-9A-Za-z]{28})\z}
+
+    private_constant :HASH_CHARS, :DEFAULT_ROUNDS, :MIN_ROUNDS, :MAX_ROUNDS,
+                     :MAX_SALT_LEN, :ENCODE_OFFSETS, :LOAD_PATTERN
+
+    # @param secret [String] the plaintext password to re-hash
+    # @return [SHA1Crypt] a new instance hashed with the same salt and rounds
+    def create_comparable(secret)
+      self.class.create(secret, salt: @salt, rounds: @rounds)
+    end
+
+    # @return [Boolean] +true+ if the stored iteration count differs from the
+    #   configured target
+    def upgrade?
+      @rounds != (config.rounds || DEFAULT_ROUNDS).clamp(MIN_ROUNDS, MAX_ROUNDS)
+    end
+
+    private
+
+    def create(secret)
+      @rounds = (config.rounds || DEFAULT_ROUNDS).clamp(MIN_ROUNDS, MAX_ROUNDS)
+      @salt   = (config.salt || random_salt)[0, MAX_SALT_LEN]
+      "$sha1$#{@rounds}$#{@salt}$#{sha1_digest(secret)}"
+    end
+
+    def load(string)
+      m = LOAD_PATTERN.match(string) or raise ArgumentError, "invalid sha1_crypt hash: #{string.inspect}"
+      @rounds = m[1].to_i
+      @salt   = m[2]
+      string
+    end
+
+    def sha1_digest(secret)
+      key    = secret.encode("UTF-8").b
+      digest = OpenSSL::HMAC.digest("SHA1", key, "#{@salt}$sha1$#{@rounds}")
+      (@rounds - 1).times { digest = OpenSSL::HMAC.digest("SHA1", key, digest) }
+      encode(digest)
+    end
+
+    # Encodes the 20-byte digest into 28 characters using the sha1crypt
+    # big-endian 24-bit grouping with wrap-around for the final group.
+    def encode(digest)
+      b = digest.bytes
+      ENCODE_OFFSETS.map { |i, j, k|
+        v = (b[i] << 16) | (b[j] << 8) | b[k]
+        4.times.map { c = HASH_CHARS[v & 0x3f]; v >>= 6; c }.join
+      }.join
+    end
+
+    def random_salt
+      Internal.random_bytes(6).bytes.map { HASH_CHARS[it & 63] }.join
+    end
+  end
+end

data/lib/passlib/sha2_crypt.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module Passlib
+  # Handles SHA-256 ($5$) and SHA-512 ($6$) crypt password hashing via OpenSSL.
+  #
+  # Implements the SHA-crypt algorithm as specified by Ulrich Drepper
+  # (https://www.akkadia.org/drepper/SHA-crypt.txt). Both 256-bit and 512-bit
+  # variants are supported and auto-detected on load.
+  #
+  # @example
+  #   hash = Passlib::ShaCrypt.create("hunter2", bits: 512, rounds: 10_000)
+  #   hash.verify("hunter2")  # => true
+  #   hash.to_s               # => "$6$rounds=10000$...$..."
+  #
+  # @!method self.create(secret, **options)
+  #   Creates a new SHA-crypt hash.
+  #   @param secret [String] the plaintext password
+  #   @option options [Integer] :bits   selects the SHA variant — +256+ (SHA-256, MCF id +$5$+) or
+  #     +512+ (SHA-512, MCF id +$6$+) (default: +512+)
+  #   @option options [Integer] :rounds number of hashing rounds (default: 535,000 for SHA-256,
+  #     656,000 for SHA-512, clamped to 1,000–999,999,999)
+  #   @option options [String]  :salt   custom salt string up to 16 characters (default: random)
+  #   @return [SHA2Crypt]
+  class SHA2Crypt < Password
+    HASH_CHARS      = "./0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+    IMPLICIT_ROUNDS = 5_000
+    MIN_ROUNDS      = 1_000
+    MAX_ROUNDS      = 999_999_999
+    MAX_SALT_LEN    = 16
+
+    VARIANTS = {
+      256 => { mcf_id: "5", digest: OpenSSL::Digest::SHA256, block_size: 32, default_rounds: 535_000, checksum_len: 43  },
+      512 => { mcf_id: "6", digest: OpenSSL::Digest::SHA512, block_size: 64, default_rounds: 656_000, checksum_len: 86  },
+    }.freeze
+
+    # Byte index groups for SHA-crypt base64 encoding.
+    # nil entries encode as 0 (padding for the final partial group).
+    ENCODE_GROUPS = {
+      256 => [
+        [0,   10,  20,  4], [21,  1,   11,  4], [12,  22,  2,   4], [3,   13,  23,  4],
+        [24,  4,   14,  4], [15,  25,  5,   4], [6,   16,  26,  4], [27,  7,   17,  4],
+        [18,  28,  8,   4], [9,   19,  29,  4], [nil, 31,  30,  3],
+      ].freeze,
+      512 => [
+        [0,   21,  42,  4], [22,  43,  1,   4], [44,  2,   23,  4], [3,   24,  45,  4],
+        [25,  46,  4,   4], [47,  5,   26,  4], [6,   27,  48,  4], [28,  49,  7,   4],
+        [50,  8,   29,  4], [9,   30,  51,  4], [31,  52,  10,  4], [53,  11,  32,  4],
+        [12,  33,  54,  4], [34,  55,  13,  4], [56,  14,  35,  4], [15,  36,  57,  4],
+        [37,  58,  16,  4], [59,  17,  38,  4], [18,  39,  60,  4], [40,  61,  19,  4],
+        [62,  20,  41,  4], [nil, nil, 63,  2],
+      ].freeze,
+    }.freeze
+
+    MCF_TO_BITS  = { "5" => 256, "6" => 512 }.freeze
+    LOAD_PATTERN = %r{\A\$(5|6)\$(?:rounds=(\d+)\$)?([./0-9A-Za-z]{0,16})\$([./0-9A-Za-z]+)\z}
+
+    private_constant :HASH_CHARS, :IMPLICIT_ROUNDS, :MIN_ROUNDS, :MAX_ROUNDS, :MAX_SALT_LEN,
+                     :VARIANTS, :ENCODE_GROUPS, :MCF_TO_BITS, :LOAD_PATTERN
+
+    register :sha2_crypt, mcf: %w[5 6]
+    options :bits, :rounds, :salt
+
+    # @param secret [String] the plaintext password to re-hash
+    # @return [SHA2Crypt] a new instance hashed with the same salt, rounds, and bits
+    def create_comparable(secret)
+      self.class.create(secret, salt: @salt, rounds: @rounds, bits: @bits)
+    end
+
+    def upgrade?
+      @rounds != (config.rounds || VARIANTS[@bits][:default_rounds])
+    end
+
+    private
+
+    def create(secret)
+      @bits    = config.bits || 512
+      variant  = VARIANTS[@bits] or raise ArgumentError, "invalid bits: #{@bits.inspect}, must be 256 or 512"
+      rounds   = config.rounds || variant[:default_rounds]
+      @rounds  = rounds.clamp(MIN_ROUNDS, MAX_ROUNDS)
+      @salt    = (config.salt || random_salt)[0, MAX_SALT_LEN]
+      crypt(secret.to_s.b, @salt.b, @rounds, variant)
+    end
+
+    def load(string)
+      match   = LOAD_PATTERN.match(string) or raise UnknownHashFormat, "invalid sha_crypt hash: #{string.inspect}"
+      @bits   = MCF_TO_BITS[match[1]]
+      variant = VARIANTS[@bits]
+      raise UnknownHashFormat, "invalid sha_crypt hash: #{string.inspect}" unless match[4].length == variant[:checksum_len]
+      @rounds = match[2] ? match[2].to_i : IMPLICIT_ROUNDS
+      @salt   = match[3]
+      string
+    end
+
+    def random_salt
+      Internal.random_bytes(MAX_SALT_LEN).bytes.map { HASH_CHARS[it & 63] }.join
+    end
+
+    def crypt(password, salt, rounds, variant)
+      digest_class = variant[:digest]
+      block_size   = variant[:block_size]
+      mcf_id       = variant[:mcf_id]
+
+      # Steps 1-3: start digest A, add password and salt
+      ctx_a = digest_class.new
+      ctx_a.update(password)
+      ctx_a.update(salt)
+
+      # Steps 4-8: digest B = digest(password + salt + password)
+      ctx_b = digest_class.new
+      ctx_b.update(password)
+      ctx_b.update(salt)
+      ctx_b.update(password)
+      digest_b = ctx_b.digest
+
+      # Steps 9-10: add digest B to A in block_size-byte blocks, then the remainder
+      plen = password.bytesize
+      (plen / block_size).times { ctx_a.update(digest_b) }
+      ctx_a.update(digest_b.b[0, plen % block_size]) if (plen % block_size) > 0
+
+      # Step 11: for each bit of plen (LSB first): 1-bit → add digest B, 0-bit → add password
+      len = plen
+      while len > 0
+        ctx_a.update(len.odd? ? digest_b : password)
+        len >>= 1
+      end
+
+      # Step 12: finish digest A
+      digest_a = ctx_a.digest
+
+      # Steps 13-16: P sequence — repeat password plen times through digest, tile to plen bytes
+      ctx_p = digest_class.new
+      plen.times { ctx_p.update(password) }
+      digest_p = ctx_p.digest
+      p_str    = (digest_p * ((plen / block_size) + 1)).b[0, plen]
+
+      # Steps 17-20: S sequence — repeat salt (16 + first byte of digest A) times, tile to slen bytes
+      slen  = salt.bytesize
+      ctx_s = digest_class.new
+      (16 + digest_a.getbyte(0)).times { ctx_s.update(salt) }
+      digest_s = ctx_s.digest
+      s_str    = (digest_s * ((slen / block_size) + 1)).b[0, slen]
+
+      # Step 21: main loop — rounds iterations mixing C, P, and S
+      c = digest_a
+      rounds.times do |i|
+        ctx_c = digest_class.new
+        ctx_c.update(i.odd? ? p_str : c)
+        ctx_c.update(s_str) unless (i % 3).zero?
+        ctx_c.update(p_str) unless (i % 7).zero?
+        ctx_c.update(i.odd? ? c : p_str)
+        c = ctx_c.digest
+      end
+
+      # Step 22: encode output with variant-specific byte ordering
+      encoded = encode(c)
+      rounds == IMPLICIT_ROUNDS ? "$#{mcf_id}$#{salt}$#{encoded}" : "$#{mcf_id}$rounds=#{rounds}$#{salt}$#{encoded}"
+    end
+
+    def encode(digest)
+      b = digest.bytes
+      ENCODE_GROUPS[@bits].map { |w2, w1, w0, n|
+        b64_group(w2 ? b[w2] : 0, w1 ? b[w1] : 0, w0 ? b[w0] : 0, n)
+      }.join
+    end
+
+    # Encode (w2, w1, w0) as n characters from HASH_CHARS, extracting 6-bit chunks LSB-first
+    def b64_group(w2, w1, w0, n)
+      v = (w2 << 16) | (w1 << 8) | w0
+      n.times.map { c = HASH_CHARS[v & 0x3f]; v >>= 6; c }.join
+    end
+  end
+end

data/lib/passlib/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Passlib
+  # The current version of the Passlib gem.
+  # @return [String]
+  VERSION = "0.1.0"
+end

data/lib/passlib/yescrypt.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Passlib
+  # Handles yescrypt password hashing via the
+  # {https://rubygems.org/gems/yescrypt yescrypt} gem.
+  #
+  # Hash format: +$y$jAU.../.....0$<salt>$<checksum>+
+  #
+  # @example
+  #   hash = Passlib::Yescrypt.create("hunter2")
+  #   hash.verify("hunter2")  # => true
+  #
+  # @!method self.create(secret, **options)
+  #   Creates a new yescrypt hash.
+  #   @param secret [String] the plaintext password
+  #   @option options [Integer] :n_log2  base-2 log of the memory/CPU cost factor
+  #   @option options [Integer] :r       block size
+  #   @option options [Integer] :p       parallelization factor
+  #   @option options [Integer] :t       additional time parameter
+  #   @option options [Integer] :flags   algorithm flags bitmask
+  #   @option options [String]  :salt    custom salt (normally auto-generated)
+  #   @return [Yescrypt]
+  class Yescrypt < Password
+    register mcf: "y"
+    external "yescrypt", ">= 0.1.1"
+    options :n_log2, :r, :p, :t, :flags, :salt
+    def verify(secret) = ::Yescrypt.verify(secret, string)
+    def create(secret) = ::Yescrypt.create(secret, **config)
+    def upgrade?       = !::Yescrypt.cost_matches?(string, **config)
+  end
+end

data/lib/passlib.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "concurrent/map"
+
+# Top-level namespace for the Passlib gem.
+#
+# Passlib is an algorithm-agnostic password hashing library. It provides a
+# unified interface for creating and verifying password hashes across many
+# supported algorithms, and auto-detects the algorithm from any stored hash
+# string.
+#
+# @example Verifying a stored hash
+#   Passlib.verify("hunter2", "$2a$12$...")  # => true
+#
+# @example Loading an existing hash and verifying
+#   hash = Passlib.load("$2a$12$...")
+#   hash.verify("hunter2")  # => true
+#
+# @example Creating a hash with a specific algorithm
+#   Passlib::BCrypt.create("hunter2", cost: 12).to_s  # => "$2a$12$..."
+#
+# @see Password
+# @see Configuration
+module Passlib
+  # Base class for all Passlib errors.
+  Error ||= Class.new(StandardError)
+
+  # Raised when a requested algorithm is not supported or its dependency gem is not installed.
+  UnsupportedAlgorithm ||= Class.new(Error)
+
+  # Raised when an algorithm identifier is not recognized.
+  UnknownAlgorithm ||= Class.new(UnsupportedAlgorithm)
+
+  # Raised when a hash string cannot be parsed as any known format.
+  UnknownHashFormat ||= Class.new(UnsupportedAlgorithm)
+
+  # Raised when a required gem dependency is not installed.
+  MissingDependency ||= Class.new(UnsupportedAlgorithm)
+
+  autoload :Configuration, "passlib/configuration"
+  autoload :Internal,      "passlib/internal"
+  autoload :Password,      "passlib/password"
+
+  # Poor man's Zeitwerk
+  Dir.glob("passlib/*.rb", base: __dir__) { require_relative it }
+
+  extend Configuration::Context
+  extend self
+
+  # Performs a constant-time string comparison to prevent timing attacks.
+  #
+  # Returns +false+ immediately—without leaking length information through
+  # timing—when either argument does not respond to +#to_str+.
+  # Returns +false+ when the byte lengths differ, also in constant time.
+  #
+  # @param trusted   [#to_str] the expected (stored) value
+  # @param untrusted [#to_str] the candidate value to compare against +trusted+
+  # @return [Boolean] +true+ if both strings are byte-for-byte identical
+  def secure_compare(trusted, untrusted)
+    return false unless trusted.respond_to?   :to_str and trusted = trusted.to_str.b
+    return false unless untrusted.respond_to? :to_str and untrusted = untrusted.to_str.b
+
+    # avoid ability for attacker to guess length of string by timing attack
+    comparable = trusted[0, untrusted.bytesize].ljust(untrusted.bytesize, "\0".b)
+    result     = OpenSSL.fixed_length_secure_compare(comparable, untrusted)
+    trusted.bytesize == untrusted.bytesize and result
+  end
+
+  # Looks up a password algorithm class by identifier.
+  #
+  # @param key [Symbol, String, Class] algorithm identifier (e.g. +:bcrypt+, +"bcrypt"+)
+  #   or a {Password} subclass (returned as-is)
+  # @return [Class<Password>, nil] the corresponding {Password} subclass,
+  #   or +nil+ if the identifier is not recognized
+  def [](key)
+    return key if key.is_a?(Class) and key <= Password
+    Internal::Register::IDENTIFIERS[key.to_sym]
+  end
+
+  # Returns whether the given algorithm is available (i.e. its dependency gem is installed).
+  #
+  # @param algorithm [Symbol, String, Class] algorithm identifier or {Password} subclass
+  # @return [Boolean, nil] +true+ if available, +false+ if the dependency is missing,
+  #   +nil+ if the algorithm identifier is not recognized at all
+  def available?(algorithm) = self[algorithm]&.available?
+
+  private
+
+  def base_config = nil
+end