Initial Commit

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

@@ -0,0 +1,71 @@
+# `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
+
+```ts
+import { SURNAMES_DICTIONARY } from "@suaveplan/password-strength/dicts/en";
+
+console.log(SURNAMES_DICTIONARY.get("smith")); // 1
+```
+
+## Usage: Advanced Example
+
+```ts
+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.