@sentinel-password/entropy

@sentinel-password/entropy

Shannon entropy estimator for sentinel-password with dictionary, l33t, and pattern detection. Zero runtime dependencies. ≤ 30 KB gzipped (CI enforced).

This package complements @sentinel-password/core, which performs rule-based validation (length, character types, common passwords). The entropy package answers a different question: how long would this password survive a brute-force attack?

Installation

pnpm add @sentinel-password/entropy

The package has no peer dependencies. It can be used standalone or alongside @sentinel-password/core.

Quick start

import { estimateEntropy } from '@sentinel-password/entropy'

const result = estimateEntropy('Tr0ub4dor&3')
// {
//   bits: 28.4,
//   score: 1,
//   crackTime: {
//     onlineThrottled:   { seconds: 6.5e6, display: '2 months' },
//     onlineUnthrottled: { seconds: 1.8e4, display: '5 hours' },
//     offlineSlowHash:   { seconds: 18,    display: 'less than a minute' },
//     offlineFastHash:   { seconds: 0.018, display: 'instant' },
//   },
//   patterns: ['dictionary', 'l33t', 'capitalization'],
// }

Composition with @sentinel-password/core

The two packages do not share types or runtime; consumers compose them explicitly:

import { validatePassword } from '@sentinel-password/core'
import { estimateEntropy } from '@sentinel-password/entropy'

function check(pwd: string, email: string) {
  const rule = validatePassword(pwd, { personalInfo: [email] })
  const ent = estimateEntropy(pwd, { personalInfo: [email] })
  return {
    valid: rule.valid && ent.bits >= 40,
    score: Math.min(rule.score, ent.score),
    suggestions: rule.feedback.suggestions,
    crackTime: ent.crackTime.offlineSlowHash.display,
  }
}

API

estimateEntropy(password, options?)

Returns an EntropyResult describing the password's effective entropy in bits, a 0-4 score, four crack-time estimates under standard attack models, and the list of entropy-reducing patterns detected.

Options

Option	Type	Default	Description
personalInfo	readonly string[]	[]	Strings whose presence in the password reduces effective entropy to 0.
customDictionary	readonly string[]	[]	Extra dictionary words to match alongside the built-in 15K-word dictionary.
scoreThresholds	readonly [number, number, number, number]	[28, 36, 60, 128]	Bit cutoffs for scores 1/2/3/4. Defaults align with NIST 800-63B guidance.

Result

Field	Type	Description
bits	number	Effective entropy after pattern/dictionary/l33t reduction.
score	0 | 1 | 2 | 3 | 4	Banded score derived from bits via scoreThresholds. Aligns with core's StrengthScore.
crackTime	CrackTimePresets	Four attack-model estimates (see below).
patterns	readonly EntropyPattern[]	Reducing patterns detected, in order.

Crack-time attack models

Preset	Guesses/sec	Scenario
onlineThrottled	100/hour	Rate-limited login form.
onlineUnthrottled	10/sec	No rate limit.
offlineSlowHash	10⁴/sec	Bcrypt cost 10, scrypt, argon2.
offlineFastHash	10¹⁰/sec	Raw MD5/SHA1 on a single modern GPU.

Detected patterns

• 'sequence' — abc, 123, qwerty, …
• 'repetition' — aaaa, abab, …
• 'dictionary' — match against the built-in 15 K dictionary or customDictionary.
• 'l33t' — match after un-substituting @→a, 0→o, etc.
• 'capitalization' — initial capital on a dictionary word.
• 'personalInfo' — substring match against personalInfo (case-insensitive); forces bits: 0.

Bundle size

The built bundle is checked in CI and must stay under 30 720 bytes (30 KB) gzipped. If you add code, run:

pnpm --filter @sentinel-password/entropy build
gzip -c packages/entropy/dist/index.js | wc -c

Regenerating the dictionary

The bloom filter at src/data/dict-bloom.ts is generated from the seed files in data/. Regenerate after changing those files:

pnpm --filter @sentinel-password/entropy generate:dict

License

MIT. See LICENSE.