us-ssn-tools 1.0.0

package/LICENSE

@@ -0,0 +1,7 @@
+ISC License
+
+Copyright 2025 backupbrain@gmail.com
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,319 @@
+# US Social Security Tools
+
+A small, well-tested TypeScript library for **working with U.S. Social Security Numbers (SSNs)** in UI and backend code.
+
+It provides:
+
+* ✅ **Validation** (strict + typing-as-you-go)
+* 🔁 **Normalization** (canonical `###-##-####` formatting)
+* 🎭 **Masking** (UI-safe, best-effort, privacy-first)
+* 🎲 **Generation** (pre-2011, post-2011, random, and publicly advertised SSNs)
+* 🧩 **Zod & Yup adapters** for form validation
+
+> **Design principle:**
+> Validation enforces rules.
+> Masking never leaks data.
+> Normalization is deterministic and UI-friendly.
+
+---
+
+## Installation
+
+```bash
+npm install us-ssn-tools
+```
+
+or
+
+```bash
+yarn add us-ssn-tools
+```
+
+---
+
+## Imports
+
+```ts
+import {
+  validateSsn,
+  normalizeSsnInput,
+  formatSsnFromDigits,
+  maskSsn,
+  generateSsn,
+} from "us-ssn-tools";
+
+import { zodSsnTyping, zodSsnSubmit } from "us-ssn-tools/zod";
+import { yupSsnTyping, yupSsnSubmit } from "us-ssn-tools/yup";
+```
+
+---
+
+## Validation
+
+### `validateSsn(input, options)`
+
+Validates an SSN according to U.S. rules.
+
+```ts
+const result = validateSsn("123-45-6789");
+
+if (result.ok) {
+  console.log(result.normalized); // "123-45-6789"
+} else {
+  console.log(result.error);   // e.g. "INVALID_AREA"
+  console.log(result.message); // human-readable explanation
+}
+```
+
+### Options
+
+```ts
+type ValidateSsnOptions = {
+  allowNoDashes?: boolean; // default true
+  allowPartial?: boolean; // default false
+  ruleMode?: "pre2011" | "post2011" | "both"; // default "both"
+};
+```
+
+#### Examples
+
+```ts
+validateSsn("123456789"); // ok (normalized to "123-45-6789")
+
+validateSsn("9", { allowPartial: true }); 
+// ❌ INVALID_AREA (impossible prefix)
+
+validateSsn("773-12-3456", { ruleMode: "pre2011" });
+// ❌ INVALID_AREA
+
+validateSsn("773-12-3456", { ruleMode: "post2011" });
+// ✅ ok
+```
+
+---
+
+## Normalization
+
+### `normalizeSsnInput(input, options)`
+
+Parses and formats SSNs **without enforcing full validity**.
+Ideal for **typing-as-you-go**.
+
+```ts
+const res = normalizeSsnInput("1234", { allowPartial: true });
+
+if (res.ok) {
+  res.digits;     // "1234"
+  res.normalized; // "123-4"
+}
+```
+
+### Options
+
+```ts
+type NormalizeSsnOptions = {
+  allowPartial?: boolean;
+  allowNoDashes?: boolean;
+};
+```
+
+### Examples
+
+```ts
+normalizeSsnInput("123456789");
+// → { digits: "123456789", normalized: "123-45-6789" }
+
+normalizeSsnInput("123-45-6", { allowPartial: true });
+// → { digits: "123456", normalized: "123-45-6" }
+```
+
+---
+
+## Formatting (UI helper)
+
+### `formatSsnFromDigits(digits)`
+
+Formats a **digit string** into SSN shape.
+This function **does not validate**.
+
+```ts
+formatSsnFromDigits("123");       // "123"
+formatSsnFromDigits("1234");      // "123-4"
+formatSsnFromDigits("123456789"); // "123-45-6789"
+```
+
+Used internally by normalization and masking, but safe to use directly for UI.
+
+---
+
+## Masking (UI-safe)
+
+### `maskSsn(input, options)`
+
+Masks digits while **never masking dashes**.
+Designed for **privacy-safe UI rendering**, not validation.
+
+```ts
+maskSsn("123-45-6789");
+// "***-**-****"
+
+maskSsn("123-45-6789", { revealLast4: true });
+// "***-**-6789"
+```
+
+### Options
+
+```ts
+type MaskSsnOptions = {
+  allowPartial?: boolean;      // default false
+  revealLast4?: boolean;       // default false
+  maskChar?: string;           // default "*"
+  dashMode?: "normalize" | "preserve"; // default "normalize"
+  allowNoDashes?: boolean;     // default true
+};
+```
+
+### Partial / typing behavior
+
+```ts
+maskSsn("123", { allowPartial: true });
+// "***"
+
+maskSsn("123-45-6", { allowPartial: true, revealLast4: true });
+// "***-**-6"
+```
+
+### Important guarantees
+
+* ✔️ **Digits are always masked** (even on invalid input)
+* ✔️ Dashes are never masked
+* ✔️ No validation required — safe for UI display
+
+---
+
+## Generation
+
+### `generateSsn(options)`
+Absolutely — that’s an important point, and it’s worth stating **clearly but professionally**, without sounding alarmist.
+
+Here’s a **polished replacement** for the **Generation** section note that you can drop straight into the README.
+
+---
+
+## Generation
+
+Generates realistic-looking SSNs for testing, demos, and development.
+
+```ts
+generateSsn(); 
+// e.g. "509-21-4837"
+```
+
+### ⚠️ Important note on public usage
+
+> **Only use `mode: "public"` for any SSNs that may be displayed publicly.**
+
+SSNs generated with `"pre2011"`, `"post2011"`, or `"any"` modes are **syntactically valid** and may correspond to **real individuals**.
+
+If such a value is:
+
+* rendered in documentation
+* shown in screenshots
+* logged to public consoles
+* included in sample data or demos
+
+you risk **exposing a real person to identity theft** if the generated SSN happens to match an existing one.
+
+To prevent this, the library includes a special `"public"` generation mode that returns **historically documented, non-random, publicly advertised SSNs** that are known to be unsafe for real-world use but safe for examples.
+
+### Recommended usage
+
+```ts
+// ✅ Safe for docs, demos, screenshots, and public output
+generateSsn({ mode: "public" });
+
+// ❌ Do NOT use in any public or user-visible context
+generateSsn({ mode: "any" });
+generateSsn({ mode: "pre2011" });
+generateSsn({ mode: "post2011" });
+```
+
+Use non-public modes **only** for:
+
+* internal testing
+* private development environments
+* automated test data that is never exposed
+
+This distinction exists to protect real people, not just to satisfy validation rules.
+
+---
+
+## Zod Adapters
+
+### Typing (partial + normalized)
+
+```ts
+const schema = zodSsnTyping();
+
+schema.parse("1234"); // "123-4"
+schema.parse("9");    // ❌ throws (impossible prefix)
+```
+
+### Submit (strict)
+
+```ts
+const schema = zodSsnSubmit();
+
+schema.parse("123456789"); // "123-45-6789"
+schema.parse("123-45-6");  // ❌ throws
+```
+
+---
+
+## Yup Adapters
+
+```ts
+await yupSsnTyping().validate("1234");
+// "123-4"
+
+await yupSsnSubmit().validate("123456789");
+// "123-45-6789"
+```
+
+---
+
+## Testing & Guarantees
+
+* ✔️ 100% table-driven Jest tests
+* ✔️ Deterministic RNG support
+* ✔️ Strict separation between:
+
+  * validation
+  * formatting
+  * masking
+  * generation
+
+---
+
+## Non-Goals
+
+* ❌ No storage or encryption
+* ❌ No non-US SSNs (yet)
+* ❌ No implicit trimming or mutation of user input
+
+---
+
+## License
+
+ISC
+
+## Support This Project
+
+If you find this project useful, consider supporting me to help keep it maintained and improved:
+
+- [Sponsor on GitHub](https://github.com/sponsors/backupbrain)
+- [Buy Me a Coffee](https://www.buymeacoffee.com/backupbrain)
+- [Ko-fi](https://ko-fi.com/backupbrain)
+- [Thanks.dev](https://thanks.dev/u/gh/backupbrain)
+
+Your support is greatly appreciated!

package/dist/generate.d.ts

@@ -0,0 +1,23 @@
+export type GenerateSsnMode = 'pre2011' | 'post2011' | 'any' | 'public';
+export interface GenerateSsnOptions {
+    /**
+     * What kind of SSN to generate.
+     * - "any" (default): may produce either pre2011-valid or post2011-valid
+     * - "pre2011": uses stricter pre-2011 area rules
+     * - "post2011": uses post-2011 relaxed area rules
+     * - "public": returns one of the publicly-advertised SSNs (intentionally invalid)
+     */
+    mode?: GenerateSsnMode;
+    /** Output format (default: "dashed") */
+    format?: 'dashed' | 'digits';
+    /**
+     * Optional RNG injection for determinism in tests.
+     * Must return a float in [0, 1).
+     */
+    rng?: () => number;
+    /**
+     * For mode="public": choose a specific advertised SSN, otherwise random.
+     */
+    publicValue?: '078-05-1120' | '721-07-4426' | '219-09-9999';
+}
+export declare function generateSsn(opts?: GenerateSsnOptions): string;

package/dist/generate.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateSsn = generateSsn;
+const PUBLICLY_ADVERTISED = [
+    '078-05-1120',
+    '721-07-4426',
+    '219-09-9999',
+];
+function generateSsn(opts = {}) {
+    var _a, _b, _c, _d;
+    const mode = (_a = opts.mode) !== null && _a !== void 0 ? _a : 'any';
+    const format = (_b = opts.format) !== null && _b !== void 0 ? _b : 'dashed';
+    const rng = (_c = opts.rng) !== null && _c !== void 0 ? _c : defaultRng;
+    if (mode === 'public') {
+        const chosen = (_d = opts.publicValue) !== null && _d !== void 0 ? _d : PUBLICLY_ADVERTISED[randomInt(rng, 0, PUBLICLY_ADVERTISED.length - 1)];
+        return format === 'digits' ? chosen.replace(/-/g, '') : chosen;
+    }
+    // "any" => randomly choose pre or post
+    const effectiveMode = mode === 'any' ? (rng() < 0.5 ? 'pre2011' : 'post2011') : mode;
+    const area = generateArea(effectiveMode, rng);
+    const group = generateNonZeroFixedWidth(rng, 2); // 01..99 (not 00)
+    const serial = generateNonZeroFixedWidth(rng, 4); // 0001..9999 (not 0000)
+    const dashed = `${area}-${group}-${serial}`;
+    // Avoid accidentally returning a "publicly advertised" SSN unless explicitly requested.
+    if (PUBLICLY_ADVERTISED.includes(dashed)) {
+        return generateSsn(Object.assign(Object.assign({}, opts), { mode })); // retry (very unlikely)
+    }
+    return format === 'digits' ? dashed.replace(/-/g, '') : dashed;
+}
+/* ---------------------------- helpers ---------------------------- */
+function generateArea(mode, rng) {
+    // Base rules always:
+    // - not 000
+    // - not 666
+    // - not 900-999
+    //
+    // Pre-2011 additionally:
+    // - not 734-749
+    // - not >= 773
+    //
+    // Strategy: generate until it passes constraints (fast, tiny rejection rate).
+    while (true) {
+        const n = randomInt(rng, 1, 899); // 001..899
+        if (n === 666)
+            continue;
+        if (mode === 'pre2011') {
+            if (n >= 734 && n <= 749)
+                continue;
+            if (n >= 773)
+                continue; // excludes 773..899
+        }
+        return pad3(n);
+    }
+}
+function generateNonZeroFixedWidth(rng, width) {
+    if (width === 2) {
+        // 01..99
+        const n = randomInt(rng, 1, 99);
+        return n.toString().padStart(2, '0');
+    }
+    // 0001..9999
+    const n = randomInt(rng, 1, 9999);
+    return n.toString().padStart(4, '0');
+}
+function pad3(n) {
+    return n.toString().padStart(3, '0');
+}
+function randomInt(rng, min, max) {
+    // inclusive min/max
+    const r = rng();
+    return Math.floor(r * (max - min + 1)) + min;
+}
+function defaultRng() {
+    var _a;
+    // Prefer crypto when available; fall back to Math.random.
+    // Works in browsers; in Node 19+ crypto.getRandomValues exists on globalThis.crypto.
+    const g = globalThis;
+    if ((_a = g.crypto) === null || _a === void 0 ? void 0 : _a.getRandomValues) {
+        const buf = new Uint32Array(1);
+        g.crypto.getRandomValues(buf);
+        return buf[0] / Math.pow(2, 32);
+    }
+    return Math.random();
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { validateSsn } from './validate';
+export { normalizeSsnInput } from './normalize';
+export { maskSsn } from './mask';
+export { formatSsnFromDigits } from './utils';
+export { generateSsn } from './generate';

package/dist/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateSsn = exports.formatSsnFromDigits = exports.maskSsn = exports.normalizeSsnInput = exports.validateSsn = void 0;
+// Exporting all functions
+var validate_1 = require("./validate");
+Object.defineProperty(exports, "validateSsn", { enumerable: true, get: function () { return validate_1.validateSsn; } });
+var normalize_1 = require("./normalize");
+Object.defineProperty(exports, "normalizeSsnInput", { enumerable: true, get: function () { return normalize_1.normalizeSsnInput; } });
+var mask_1 = require("./mask");
+Object.defineProperty(exports, "maskSsn", { enumerable: true, get: function () { return mask_1.maskSsn; } });
+var utils_1 = require("./utils");
+Object.defineProperty(exports, "formatSsnFromDigits", { enumerable: true, get: function () { return utils_1.formatSsnFromDigits; } });
+var generate_1 = require("./generate");
+Object.defineProperty(exports, "generateSsn", { enumerable: true, get: function () { return generate_1.generateSsn; } });

package/dist/mask.d.ts

@@ -0,0 +1,25 @@
+export interface MaskSsnOptions {
+    /** Allow masking partial SSNs (typing-as-you-go). */
+    allowPartial?: boolean;
+    /** If true, reveal last 4 digits when present (>= 4 digits typed). */
+    revealLast4?: boolean;
+    /** Mask character (default: "*"). Only first char is used. */
+    maskChar?: string;
+    /** Accept digit-only input (default: true). */
+    allowNoDashes?: boolean;
+    /**
+     * Controls dash output:
+     * - "preserve": keep dashes only if the input already contains '-'
+     * - "normalize": always insert dashes in ###-##-#### style (even for digits-only)
+     *
+     * Default: "normalize"
+     */
+    dashMode?: 'preserve' | 'normalize';
+    /**
+     * If true (default), and allowPartial=true, invalid partial input will be masked
+     * in a best-effort way (digits masked, dashes preserved).
+     * If false, invalid input is returned unchanged.
+     */
+    bestEffortOnInvalidPartial?: boolean;
+}
+export declare function maskSsn(input: string, opts?: MaskSsnOptions): string;

package/dist/mask.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.maskSsn = maskSsn;
+const normalize_1 = require("./normalize");
+const utils_1 = require("./utils");
+function maskSsn(input, opts = {}) {
+    var _a, _b, _c, _d, _e;
+    const allowPartial = (_a = opts.allowPartial) !== null && _a !== void 0 ? _a : false;
+    const revealLast4 = (_b = opts.revealLast4) !== null && _b !== void 0 ? _b : false;
+    const maskChar = ((_c = opts.maskChar) !== null && _c !== void 0 ? _c : '*').slice(0, 1) || '*';
+    const allowNoDashes = (_d = opts.allowNoDashes) !== null && _d !== void 0 ? _d : true;
+    const dashMode = (_e = opts.dashMode) !== null && _e !== void 0 ? _e : 'normalize';
+    const hadDashes = input.includes('-');
+    const normalized = (0, normalize_1.normalizeSsnInput)(input, { allowPartial, allowNoDashes });
+    if (!normalized.ok) {
+        // Masking is UI-safety, not validation: never return raw digits.
+        // Best-effort: mask digits, keep '-' unmasked, keep any other characters as-is.
+        const masked = maskBestEffort(input, { maskChar });
+        // If caller wants normalized dashes, we can try to normalize by extracting digits
+        // from the best-effort masked string is not possible (digits are already masked),
+        // so we simply return the best-effort output.
+        return masked;
+    }
+    const digits = normalized.digits; // 0..9 digits (partial) or 9 digits (full)
+    // Determine how many digits to reveal (last 4) if present.
+    const total = digits.length;
+    // digits.length = total typed digits (0..9)
+    const serialTyped = Math.max(0, total - 5); // digits 6..9 => 1..4
+    const revealCount = revealLast4 ? Math.min(4, serialTyped) : 0;
+    const maskedCount = Math.max(0, total - revealCount);
+    const maskedDigits = maskChar.repeat(maskedCount) + digits.slice(maskedCount);
+    // Output formatting
+    if (dashMode === 'normalize') {
+        // Insert dashes as ###-##-#### prefix (even while typing).
+        return (0, utils_1.formatSsnFromDigits)(maskedDigits);
+    }
+    // dashMode === "preserve"
+    if (hadDashes) {
+        // Input had dashes -> keep dashed presentation (normalized positions).
+        return (0, utils_1.formatSsnFromDigits)(maskedDigits);
+    }
+    // Input had no dashes -> keep digits-only.
+    return maskedDigits;
+}
+function maskBestEffort(input, opts) {
+    const m = opts.maskChar;
+    let out = '';
+    for (const ch of input) {
+        if (ch >= '0' && ch <= '9')
+            out += m;
+        else
+            out += ch; // dashes and any other characters preserved
+    }
+    return out;
+}

package/dist/normalize.d.ts

@@ -0,0 +1,15 @@
+export interface NormalizeSsnOptions {
+    allowNoDashes?: boolean;
+    allowPartial?: boolean;
+}
+export type NormalizeSsnOk = {
+    ok: true;
+    digits: string;
+    normalized: string;
+};
+export type NormalizeSsnErr = {
+    ok: false;
+    message: string;
+};
+export type NormalizeSsnResult = NormalizeSsnOk | NormalizeSsnErr;
+export declare function normalizeSsnInput(input: string, opts?: NormalizeSsnOptions): NormalizeSsnResult;

package/dist/normalize.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeSsnInput = normalizeSsnInput;
+const utils_1 = require("./utils");
+function normalizeSsnInput(input, opts = {}) {
+    var _a, _b;
+    const allowNoDashes = (_a = opts.allowNoDashes) !== null && _a !== void 0 ? _a : true;
+    const allowPartial = (_b = opts.allowPartial) !== null && _b !== void 0 ? _b : false;
+    const raw = input;
+    // Full (non-partial) normalization
+    if (!allowPartial) {
+        if (/^\d{3}-\d{2}-\d{4}$/.test(raw)) {
+            return {
+                ok: true,
+                digits: raw.replace(/-/g, ''),
+                normalized: raw,
+            };
+        }
+        if (allowNoDashes && /^\d{9}$/.test(raw)) {
+            return {
+                ok: true,
+                digits: raw,
+                normalized: `${raw.slice(0, 3)}-${raw.slice(3, 5)}-${raw.slice(5)}`,
+            };
+        }
+        return { ok: false, message: 'Invalid SSN format.' };
+    }
+    // ---- Partial / typing-as-you-go normalization ----
+    if (!/^[0-9-]*$/.test(raw)) {
+        return { ok: false, message: "Only digits and '-' are allowed." };
+    }
+    let digits = '';
+    let sawDashAt3 = false;
+    let sawDashAt5 = false;
+    for (const ch of raw) {
+        if (ch >= '0' && ch <= '9') {
+            digits += ch;
+            if (digits.length > 9) {
+                return { ok: false, message: 'SSN is too long.' };
+            }
+            continue;
+        }
+        // ch === '-'
+        if (!allowNoDashes) {
+            return { ok: false, message: 'Dashes are not allowed.' };
+        }
+        if (digits.length === 3 && !sawDashAt3) {
+            sawDashAt3 = true;
+        }
+        else if (digits.length === 5 && !sawDashAt5) {
+            sawDashAt5 = true;
+        }
+        else {
+            return { ok: false, message: 'Dash is in an invalid position.' };
+        }
+    }
+    return {
+        ok: true,
+        digits,
+        normalized: (0, utils_1.formatSsnFromDigits)(digits),
+    };
+}

package/dist/utils.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Format SSN from digits. Used for UI formatting.
+ */
+export declare function formatSsnFromDigits(digits: string): string;

package/dist/utils.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatSsnFromDigits = formatSsnFromDigits;
+/**
+ * Format SSN from digits. Used for UI formatting.
+ */
+function formatSsnFromDigits(digits) {
+    if (digits.length <= 3)
+        return digits;
+    if (digits.length <= 5)
+        return `${digits.slice(0, 3)}-${digits.slice(3)}`;
+    return `${digits.slice(0, 3)}-${digits.slice(3, 5)}-${digits.slice(5)}`;
+}

package/dist/validate.d.ts

@@ -0,0 +1,43 @@
+export type SsnValidationFailureReason = 'INVALID_FORMAT' | 'INVALID_AREA' | 'INVALID_GROUP' | 'INVALID_SERIAL' | 'PUBLICLY_ADVERTISED';
+export type SsnRuleMode = 'pre2011' | 'post2011' | 'both';
+export type SsnValidationOkResult = {
+    ok: true;
+    normalized: string;
+};
+export type SsnValidationErrorResult = {
+    ok: false;
+    error: SsnValidationFailureReason;
+    message: string;
+};
+export type SsnValidationResult = SsnValidationOkResult | SsnValidationErrorResult;
+export interface ValidateSsnOptions {
+    /**
+     * If true, accept either "#########" or "###-##-####" as input.
+     * If false, require exact "###-##-####" (or partial prefix of it if allowPartial=true).
+     */
+    allowNoDashes?: boolean;
+    /**
+     * Which rule-set(s) to accept.
+     * - "pre2011": apply stricter pre–Jun 25 2011 area rules (734–749, >=773 invalid)
+     * - "post2011": do NOT apply those extra area restrictions
+     * - "both": accept either (default)
+     *
+     * Note: base rules (area 000/666/900-999, group 00, serial 0000, public list) still apply.
+     */
+    ruleMode?: SsnRuleMode;
+    /**
+     * If true, allow "checking-as-you-go":
+     * - partial prefixes are accepted as long as they could still become valid
+     * - returned normalized string is the sanitized, dash-normalized prefix
+     */
+    allowPartial?: boolean;
+}
+/**
+ * Validates a US SSN with support for:
+ * - strict full validation
+ * - optional acceptance of no-dash input
+ * - rule modes: pre2011 | post2011 | both (default)
+ * - optional "checking-as-you-go" partial validation
+ */ export declare function validateSsn(input: string, opts?: ValidateSsnOptions): SsnValidationResult;
+/** Convenience boolean wrapper */
+export declare function isValidSsn(input: string, opts?: ValidateSsnOptions): boolean;

package/dist/validate.js

@@ -0,0 +1,179 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateSsn = validateSsn;
+exports.isValidSsn = isValidSsn;
+const normalize_1 = require("./normalize");
+const PUBLICLY_ADVERTISED = new Set([
+    '078-05-1120',
+    '721-07-4426',
+    '219-09-9999',
+]);
+/**
+ * Validates a US SSN with support for:
+ * - strict full validation
+ * - optional acceptance of no-dash input
+ * - rule modes: pre2011 | post2011 | both (default)
+ * - optional "checking-as-you-go" partial validation
+ */ function validateSsn(input, opts = {}) {
+    var _a, _b, _c;
+    const allowNoDashes = (_a = opts.allowNoDashes) !== null && _a !== void 0 ? _a : true;
+    const ruleMode = (_b = opts.ruleMode) !== null && _b !== void 0 ? _b : 'both';
+    const allowPartial = (_c = opts.allowPartial) !== null && _c !== void 0 ? _c : false;
+    const normalized = (0, normalize_1.normalizeSsnInput)(input, {
+        allowNoDashes,
+        allowPartial,
+    });
+    if (!normalized.ok) {
+        return {
+            ok: false,
+            error: 'INVALID_FORMAT',
+            message: normalized.message,
+        };
+    }
+    const digits = normalized.digits;
+    const area = digits.slice(0, 3);
+    const group = digits.slice(3, 5);
+    const serial = digits.slice(5, 9);
+    if (!allowPartial && PUBLICLY_ADVERTISED.has(normalized.normalized)) {
+        return {
+            ok: false,
+            error: 'PUBLICLY_ADVERTISED',
+            message: 'This SSN is a known publicly advertised (and invalid) value.',
+        };
+    }
+    const ruleCheck = allowPartial
+        ? validatePartialSegments(area, group, serial, ruleMode)
+        : validateFullSegments(area, group, serial, ruleMode);
+    if (!ruleCheck.ok)
+        return ruleCheck;
+    return { ok: true, normalized: normalized.normalized };
+}
+/** Convenience boolean wrapper */
+function isValidSsn(input, opts) {
+    return validateSsn(input, opts).ok;
+}
+function normalizePrefix(digits) {
+    // digits: 0..9 chars
+    if (digits.length <= 3)
+        return digits;
+    if (digits.length <= 5)
+        return `${digits.slice(0, 3)}-${digits.slice(3)}`;
+    return `${digits.slice(0, 3)}-${digits.slice(3, 5)}-${digits.slice(5)}`;
+}
+/* -------------------------- Rules -------------------------- */
+function validateFullSegments(area, group, serial, ruleMode) {
+    const areaNum = Number(area);
+    const groupNum = Number(group);
+    const serialNum = Number(serial);
+    // Base Rule 2: area cannot be 000, 666, or 900–999
+    if (areaNum === 0 || areaNum === 666 || areaNum >= 900) {
+        return {
+            ok: false,
+            error: 'INVALID_AREA',
+            message: 'Area number is not allowed (000, 666, and 900–999 are invalid).',
+        };
+    }
+    // Ruleset selection:
+    // - pre2011: apply extra reserved ranges
+    // - post2011: do not
+    // - both: accept if EITHER passes (so we only fail if it violates post rules AND pre rules)
+    const violatesPre2011 = (areaNum >= 734 && areaNum <= 749) || areaNum >= 773;
+    if (ruleMode === 'pre2011' && violatesPre2011) {
+        return {
+            ok: false,
+            error: 'INVALID_AREA',
+            message: 'Area number is not allowed under pre–June 25, 2011 rules (734–749 and >= 773 are invalid).',
+        };
+    }
+    if (ruleMode === 'both') {
+        // If it violates pre2011, it's still acceptable as post2011.
+        // So no action needed.
+    }
+    // Rule 3: group cannot be 00
+    if (groupNum === 0) {
+        return {
+            ok: false,
+            error: 'INVALID_GROUP',
+            message: 'Group number may not be 00.',
+        };
+    }
+    // Rule 4: serial cannot be 0000
+    if (serialNum === 0) {
+        return {
+            ok: false,
+            error: 'INVALID_SERIAL',
+            message: 'Serial number may not be 0000.',
+        };
+    }
+    // Rule 7: publicly advertised checked in validateSsn (full only)
+    return { ok: true, normalized: `${area}-${group}-${serial}` };
+}
+function validatePartialSegments(area, group, serial, ruleMode) {
+    // AREA checks while typing:
+    // - if first digit is '9', area can never be valid (since 900–999 invalid)
+    if (area.length >= 1 && area[0] === '9') {
+        return {
+            ok: false,
+            error: 'INVALID_AREA',
+            message: 'Area numbers starting with 9 are not allowed.',
+        };
+    }
+    // - if area is complete (3 digits), enforce base rule 2 and (optionally) pre2011 when in pre-only mode
+    if (area.length === 3) {
+        const areaNum = Number(area);
+        if (areaNum === 0 || areaNum === 666 || areaNum >= 900) {
+            return {
+                ok: false,
+                error: 'INVALID_AREA',
+                message: 'Area number is not allowed (000, 666, and 900–999 are invalid).',
+            };
+        }
+        const violatesPre2011 = (areaNum >= 734 && areaNum <= 749) || areaNum >= 773;
+        if (ruleMode === 'pre2011' && violatesPre2011) {
+            return {
+                ok: false,
+                error: 'INVALID_AREA',
+                message: 'Area number is not allowed under pre–June 25, 2011 rules (734–749 and >= 773 are invalid).',
+            };
+        }
+        // ruleMode "both" accepts either; "post2011" ignores extra restrictions.
+    }
+    // GROUP checks while typing:
+    // Only enforce once group is complete (2 digits)
+    if (group.length === 2) {
+        const groupNum = Number(group);
+        if (groupNum === 0) {
+            return {
+                ok: false,
+                error: 'INVALID_GROUP',
+                message: 'Group number may not be 00.',
+            };
+        }
+    }
+    // SERIAL checks while typing:
+    // Only enforce once serial is complete (4 digits)
+    if (serial.length === 4) {
+        const serialNum = Number(serial);
+        if (serialNum === 0) {
+            return {
+                ok: false,
+                error: 'INVALID_SERIAL',
+                message: 'Serial number may not be 0000.',
+            };
+        }
+        // Now that we have a full SSN in partial mode, also block publicly advertised.
+        const fullNormalized = `${area}-${group}-${serial}`;
+        if (PUBLICLY_ADVERTISED.has(fullNormalized)) {
+            return {
+                ok: false,
+                error: 'PUBLICLY_ADVERTISED',
+                message: 'This SSN is a known publicly advertised (and invalid) value.',
+            };
+        }
+    }
+    // If we haven't hit a definitive violation yet, it's valid "so far".
+    return {
+        ok: true,
+        normalized: normalizePrefix((area + group + serial).slice(0, 9)),
+    };
+}

package/dist/yup.d.ts

@@ -0,0 +1,9 @@
+import * as yup from 'yup';
+import { type ValidateSsnOptions } from './validate';
+/**
+ * Yup schema for "typing": normalizes to a prefix and allows partial validity.
+ * Note: transform runs before test in Yup.
+ */
+export declare function yupSsnTyping(opts?: Omit<ValidateSsnOptions, 'allowPartial'>): yup.StringSchema<string | undefined, yup.AnyObject, undefined, "">;
+/** Yup schema for full submit */
+export declare function yupSsnSubmit(opts?: Omit<ValidateSsnOptions, 'allowPartial'>): yup.StringSchema<string | undefined, yup.AnyObject, undefined, "">;

package/dist/yup.js

@@ -0,0 +1,80 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.yupSsnTyping = yupSsnTyping;
+exports.yupSsnSubmit = yupSsnSubmit;
+const yup = __importStar(require("yup"));
+const validate_1 = require("./validate");
+/**
+ * Yup schema for "typing": normalizes to a prefix and allows partial validity.
+ * Note: transform runs before test in Yup.
+ */
+function yupSsnTyping(opts = {}) {
+    return yup
+        .string()
+        .transform((value) => {
+        const v = (value !== null && value !== void 0 ? value : '').toString();
+        const res = (0, validate_1.validateSsn)(v, Object.assign(Object.assign({}, opts), { allowPartial: true }));
+        return res.ok ? res.normalized : v; // keep original if invalid; test will fail
+    })
+        .test('ssn-typing-valid', 'Invalid SSN', function (value) {
+        const v = (value !== null && value !== void 0 ? value : '').toString();
+        const res = (0, validate_1.validateSsn)(v, Object.assign(Object.assign({}, opts), { allowPartial: true }));
+        return res.ok
+            ? true
+            : this.createError({
+                message: res.message,
+            });
+    });
+}
+/** Yup schema for full submit */
+function yupSsnSubmit(opts = {}) {
+    return yup
+        .string()
+        .transform((value) => {
+        const v = (value !== null && value !== void 0 ? value : '').toString();
+        const res = (0, validate_1.validateSsn)(v, Object.assign(Object.assign({}, opts), { allowPartial: false }));
+        return res.ok ? res.normalized : v;
+    })
+        .test('ssn-submit-valid', 'Invalid SSN', function (value) {
+        const v = (value !== null && value !== void 0 ? value : '').toString();
+        const res = (0, validate_1.validateSsn)(v, Object.assign(Object.assign({}, opts), { allowPartial: false }));
+        return res.ok
+            ? true
+            : this.createError({
+                message: res.message,
+            });
+    });
+}

package/dist/zod.d.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+import { type ValidateSsnOptions } from './validate';
+/**
+ * Zod schema for "typing": normalizes on every parse and allows partial input.
+ * Output is a normalized prefix in ###-##-#### style (e.g. "1234" -> "123-4").
+ */
+export declare function zodSsnTyping(opts?: Omit<ValidateSsnOptions, 'allowPartial'>): z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+/**
+ * Zod schema for "submit": requires a full SSN and returns fully normalized ###-##-####.
+ */
+export declare function zodSsnSubmit(opts?: Omit<ValidateSsnOptions, 'allowPartial'>): z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;

package/dist/zod.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.zodSsnTyping = zodSsnTyping;
+exports.zodSsnSubmit = zodSsnSubmit;
+const zod_1 = require("zod");
+const validate_1 = require("./validate");
+/**
+ * Zod schema for "typing": normalizes on every parse and allows partial input.
+ * Output is a normalized prefix in ###-##-#### style (e.g. "1234" -> "123-4").
+ */
+function zodSsnTyping(opts = {}) {
+    return zod_1.z.string().transform((val, ctx) => {
+        const res = (0, validate_1.validateSsn)(val, Object.assign(Object.assign({}, opts), { allowPartial: true }));
+        if (!res.ok) {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: res.message,
+                params: { ssnError: res.error },
+            });
+            return zod_1.z.NEVER;
+        }
+        return res.normalized; // normalized prefix
+    });
+}
+/**
+ * Zod schema for "submit": requires a full SSN and returns fully normalized ###-##-####.
+ */
+function zodSsnSubmit(opts = {}) {
+    return zod_1.z.string().transform((val, ctx) => {
+        const res = (0, validate_1.validateSsn)(val, Object.assign(Object.assign({}, opts), { allowPartial: false }));
+        if (!res.ok) {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                message: res.message,
+                params: { ssnError: res.error },
+            });
+            return zod_1.z.NEVER;
+        }
+        return res.normalized; // full normalized ###-##-####
+    });
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "us-ssn-tools",
+  "version": "1.0.0",
+  "description": "Validate, format, mask, and generate US social security numbers",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "test": "npx jest",
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "lint": "eslint 'src/**/*.ts' 'tests/**/*.ts'",
+    "format": "prettier --write 'src/**/*.ts' 'tests/**/*.ts'"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/backupbrain/us-ssn-tools.git"
+  },
+  "keywords": [
+    "identity",
+    "social",
+    "security",
+    "ssn",
+    "social",
+    "security",
+    "number",
+    "us",
+    "social",
+    "security",
+    "number",
+    "identity",
+    "verification"
+  ],
+  "author": "backupbrain@gmail.com",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/backupbrain/us-ssn-tools/issues"
+  },
+  "homepage": "https://github.com/backupbrain/us-ssn-tools#readme",
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@types/jest": "^30.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.52.0",
+    "@typescript-eslint/parser": "^8.52.0",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "globals": "^17.0.0",
+    "jest": "^30.2.0",
+    "jiti": "^2.6.1",
+    "prettier": "^3.7.4",
+    "ts-jest": "^29.4.6",
+    "typescript-eslint": "^8.52.0",
+    "yup": "^1.7.1",
+    "zod": "^4.3.5"
+  }
+}