suaveplan/packages/security-stack/security/password-strength/src/dicts/en/names.md

names — US Census name dictionaries

Purpose

Frequency-ranked dictionaries of common US given names (male and female) and surnames. Names are over-represented in password breach corpora; the matcher needs three separate dictionaries so feedback can attribute a match to a name vs a surname vs a generic word.

Features

• Three frozen ReadonlyMap<string, number> dictionaries
• MALE_NAMES_DICTIONARY: 20 most common male given names
• FEMALE_NAMES_DICTIONARY: 20 most common female given names
• SURNAMES_DICTIONARY: 20 most common surnames
• Public-domain US Census source data

Usage: Basic Example

import { SURNAMES_DICTIONARY } from "@suaveplan/password-strength/dicts/en";

console.log(SURNAMES_DICTIONARY.get("smith")); // 1

Usage: Advanced Example

import { loadDictionaries } from "@suaveplan/password-strength";
import {
 FEMALE_NAMES_DICTIONARY,
 MALE_NAMES_DICTIONARY,
 SURNAMES_DICTIONARY,
} from "@suaveplan/password-strength/dicts/en";

const dicts = loadDictionaries({
 male_names: MALE_NAMES_DICTIONARY,
 female_names: FEMALE_NAMES_DICTIONARY,
 surnames: SURNAMES_DICTIONARY,
});

API Reference

• MALE_NAMES_DICTIONARY: ReadonlyMap<string, number>
• FEMALE_NAMES_DICTIONARY: ReadonlyMap<string, number>
• SURNAMES_DICTIONARY: ReadonlyMap<string, number>

Implementation Notes

Each list is intentionally short to keep the bundle compact; production deployments may extend any of the three by passing a fuller dictionary to loadDictionaries. The lists are frozen at module load so consumers cannot accidentally mutate them. The three-way split (male / female / surnames) preserves zxcvbn's original feedback signal — knowing whether a match is a given name vs a surname helps the resolver pick the right warning string.

Additional Implementation Notes

The implementation follows the canonical zxcvbn algorithm from Wheeler 2016 with the suaveplan-style additions described in the package proposal: structured error codes via the defineCodes registry, Zod boundaries at every public entry point, OTel histograms and counters keyed to low-cardinality attributes, and a strict input-length guard at 200 characters. Consumers integrate with their existing observability stack by installing a meter provider before importing the package, and with their i18n stack via the MessageResolver callback type declared in @suaveplan/types. The bundled data tables are intentionally small to keep the package bundle compact; production deployments should swap in fuller frequency-ranked tables via loadDictionaries. The default English dictionary set is a frozen DictionarySet that the matcher never mutates; caller-supplied dictionaries override defaults by name.