philiprehberger-password

Password strength checking, policy validation, pattern detection, hashing, and secure generation

Requirements

Ruby >= 3.1
bcrypt gem (optional, for password hashing only)

Installation

Add to your Gemfile:

gem "philiprehberger-password"

Or install directly:

gem install philiprehberger-password

Usage

Strength Scoring

require "philiprehberger/password"

result = Philiprehberger::Password.strength("MyP@ssw0rd!")
result[:score]    # => 3
result[:label]    # => :strong
result[:entropy]  # => 72.08

Entropy Estimate

Estimated password entropy in bits — length * log2(pool_size) where the pool is inferred from the character classes present:

Philiprehberger::Password.entropy("aaaaaa")       # => 28.20
Philiprehberger::Password.entropy("MyP@ssw0rd!")  # => 72.08
Philiprehberger::Password.entropy("")             # => 0.0

Score Only

Return the 0-4 integer score without the full strength hash:

Philiprehberger::Password.score("password")    # => 0
Philiprehberger::Password.score("MyP@ssw0rd!") # => 4

Strong Enough Predicate

Philiprehberger::Password.strong?("password")                  # => false
Philiprehberger::Password.strong?("MyP@ssw0rd!")               # => true
Philiprehberger::Password.strong?("MyP@ssw0rd!", threshold: 4) # => true / false

Default threshold: is 3 (the "strong" tier on the 0-4 scale: terrible/weak/fair/strong/excellent). Raise it to 4 for stricter gating.

Common Password Check

Philiprehberger::Password.common?("password")   # => true
Philiprehberger::Password.common?("xK9#mZ2!pQ") # => false

Policy Validation

policy = Philiprehberger::Password::Policy.new(
  min_length: 12,
  require_uppercase: true,
  require_digit: true,
  require_symbol: true,
  reject_common: true,
  custom_passwords: ["companyname", "internalpass"]
)

result = policy.validate("short")
result.valid?  # => false
result.errors  # => ["must be at least 12 characters", ...]
result.score   # => 0

Context-Aware Validation

policy = Philiprehberger::Password::Policy.new

result = policy.validate("johndoe2024!", context: {
  username: "johndoe",
  email: "johndoe@example.com",
  app_name: "myapp"
})
result.valid?  # => false
result.errors  # => ["must not contain your username", "must not contain your email username"]

Keyboard Pattern Detection

patterns = Philiprehberger::Password.keyboard_patterns("qwertyaaa123456")
# => [
#   { type: :keyboard_row, token: "qwerty", start: 0, length: 6, direction: :forward },
#   { type: :repeated, token: "aaa", start: 6, length: 3, repeated_char: "a" },
#   { type: :sequence, token: "123456", start: 9, length: 6, sequence_type: :numeric, direction: :ascending }
# ]

Password Hashing

# Requires bcrypt gem: gem install bcrypt
hash = Philiprehberger::Password.hash("my-secret-password", cost: 12)
# => "$2a$12$..."

Philiprehberger::Password.verify("my-secret-password", hash)
# => true

Philiprehberger::Password.verify("wrong-password", hash)
# => false

Password Generation

# Random password
Philiprehberger::Password.generate(length: 20)
# => "kX9#mZ2!pQ7@wR4bN5&j"

# Passphrase (200+ word list)
Philiprehberger::Password.generate(style: :passphrase, words: 4, separator: "-")
# => "correct-horse-battery-staple"

# PIN
Philiprehberger::Password.generate(style: :pin, length: 6)
# => "482917"

zxcvbn-Style Strength Estimation

result = Philiprehberger::Password.zxcvbn("p@ssw0rd123")
result[:score]              # => 1
result[:crack_time_display] # => "minutes"
result[:patterns]           # => [{ type: :leet, token: "p@ssw0rd", ... }, ...]

Batch Strength

Grade many passwords in one call. Useful for password audits across user lists or seeded test fixtures. Results are returned in input order; each element is coerced via to_s so non-string entries don't raise.

results = Philiprehberger::Password.batch_strength([
  "hunter2",
  "P@ssw0rd!",
  "C0rr3ctH0rseB4tt3ryStapl3"
])
results.map { |r| r[:score] }
# => [0, 2, 4]

Masking for Display

Philiprehberger::Password.mask("hunter2")                 # => "*******"
Philiprehberger::Password.mask("hunter2", visible: 2)     # => "*****r2"
Philiprehberger::Password.mask("hunter2", mask: "•")      # => "•••••••"

API