Module: Philiprehberger::Password

Defined in:
lib/philiprehberger/password.rb,
lib/philiprehberger/password/policy.rb,
lib/philiprehberger/password/zxcvbn.rb,
lib/philiprehberger/password/hashing.rb,
lib/philiprehberger/password/version.rb,
lib/philiprehberger/password/patterns.rb,
lib/philiprehberger/password/strength.rb,
lib/philiprehberger/password/generator.rb,
lib/philiprehberger/password/common_passwords.rb

Defined Under Namespace

Modules: CommonPasswords, Generator, Hashing, Patterns, Strength, Zxcvbn Classes: Policy

Constant Summary collapse

VERSION = 
'0.6.0'

Class Method Summary collapse

Class Method Details

.common?(password) ⇒ Boolean

Check if a password appears in the common password dictionary.

Parameters:

  • password (String) —

    the password to check

Returns:

  • (Boolean) —

    true if the password is common



20
21
22
 
# File 'lib/philiprehberger/password.rb', line 20

def self.common?(password)
  CommonPasswords.include?(password.to_s.downcase)
end

.entropy(password) ⇒ Float

Estimated entropy of the password in bits (log2(pool_size ^ length)). Pool size is inferred from the character classes present.

Parameters:

  • password (String) —

    the password to evaluate

Returns:

  • (Float) —

    estimated entropy in bits (0.0 for empty passwords)



33
34
35
 
# File 'lib/philiprehberger/password.rb', line 33

def self.entropy(password)
  Strength.entropy(password)
end

.generate(**options) ⇒ Object 



46
47
48
 
# File 'lib/philiprehberger/password.rb', line 46

def self.generate(**options)
  Generator.generate(**options)
end

.hash(password, cost: 12) ⇒ Object

Hash a password using bcrypt. Requires the bcrypt gem to be installed.



58
59
60
 
# File 'lib/philiprehberger/password.rb', line 58

def self.hash(password, cost: 12)
  Hashing.hash(password, cost: cost)
end

.keyboard_patterns(password) ⇒ Object

Detect keyboard patterns, sequences, and repeated characters. Returns an array of pattern hashes.



52
53
54
 
# File 'lib/philiprehberger/password.rb', line 52

def self.keyboard_patterns(password)
  Patterns.detect(password)
end

.mask(password, visible: 0, mask: '*') ⇒ String

Mask a password for safe display in logs, diagnostics, or UI surfaces. Reveals the trailing ‘visible` characters and replaces the rest with `mask` so that the full length of the password is still preserved. When `visible` is 0 (default) the entire password is masked.

Parameters:

  • password (String) —

    the password to mask

  • visible (Integer) (defaults to: 0) —

    number of trailing characters to expose (>= 0)

  • mask (String) (defaults to: '*') —

    single-character replacement for masked positions

Returns:

  • (String) —

    the masked password

Raises:

  • (ArgumentError) —

    if visible is negative or mask is not one character



84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/philiprehberger/password.rb', line 84

def self.mask(password, visible: 0, mask: '*')
  raise ArgumentError, 'visible must be >= 0' if visible.negative?
  raise ArgumentError, 'mask must be a single character' unless mask.is_a?(String) && mask.length == 1

  str = password.to_s
  return '' if str.empty?

  reveal = [visible, str.length].min
  masked_length = str.length - reveal
  (mask * masked_length) + str[-reveal, reveal].to_s
end

.score(password) ⇒ Integer

Strength score as a 0-4 integer. Convenience accessor that returns only the ‘:score` from strength.

Parameters:

  • password (String) —

    the password to evaluate

Returns:

  • (Integer) —

    strength score (0 = very weak, 4 = very strong)



42
43
44
 
# File 'lib/philiprehberger/password.rb', line 42

def self.score(password)
  Strength.compute(password)[:score]
end

.strength(password) ⇒ Object 



24
25
26
 
# File 'lib/philiprehberger/password.rb', line 24

def self.strength(password)
  Strength.compute(password)
end

.verify(password, hash) ⇒ Object

Verify a password against a bcrypt hash. Requires the bcrypt gem to be installed.



64
65
66
 
# File 'lib/philiprehberger/password.rb', line 64

def self.verify(password, hash)
  Hashing.verify(password, hash)
end

.zxcvbn(password) ⇒ Object

Perform zxcvbn-style strength estimation. Returns a hash with :score, :patterns, and :crack_time_display.



70
71
72
 
# File 'lib/philiprehberger/password.rb', line 70

def self.zxcvbn(password)
  Zxcvbn.estimate(password)
end