first commit

docs/security-stack/security/password-strength/src/dicts/en/english-wikipedia.md

@@ -0,0 +1,62 @@
+# `english-wikipedia` — top English Wikipedia tokens
+
+## Purpose
+
+Frequency-ranked dictionary of the most common English tokens observed in
+Wikipedia. The matcher uses this to flag passwords containing real English
+words; a dictionary word with rank 50 contributes `50` guesses to the
+cover product, far below the naive character-entropy floor.
+
+## Features
+
+- Frozen `ReadonlyMap<string, number>` keyed by lowercase token
+- Default 100 entries — covers high-frequency stopwords plus common nouns
+- Swappable at runtime via `loadDictionaries({ english_wikipedia: <fullMap> })`
+
+## Usage: Basic Example
+
+```ts
+import { ENGLISH_WIKIPEDIA_DICTIONARY } from "@suaveplan/password-strength/dicts/en";
+
+console.log(ENGLISH_WIKIPEDIA_DICTIONARY.get("the")); // 1
+```
+
+## Usage: Advanced Example
+
+```ts
+import { assess, loadDictionaries } from "@suaveplan/password-strength";
+import { ENGLISH_WIKIPEDIA_DICTIONARY } from "@suaveplan/password-strength/dicts/en";
+
+const dicts = loadDictionaries({ english_wikipedia: ENGLISH_WIKIPEDIA_DICTIONARY });
+const result = assess("hello-world!", { dictionaries: dicts });
+console.log(result.score);
+```
+
+## API Reference
+
+- `ENGLISH_WIKIPEDIA_DICTIONARY: ReadonlyMap<string, number>` — frozen
+  frequency-ranked English Wikipedia dictionary.
+
+## Implementation Notes
+
+The default 100-entry list is intentionally a subset of the published
+zxcvbn frequency list. Production deployments should swap in a fuller
+list (typically the published top-30 000 tokens). The bundled subset
+covers the high-frequency stopwords and common nouns the spec scenarios
+exercise; entries are deduplicated by lowercase token so a single insertion
+loop over the source data does not corrupt the rank ordering.
+
+## 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.