use-password-policy 2.0.0 → 3.0.0

package/dist/core.d.mts

@@ -0,0 +1,255 @@
+/**
+ * A small, bundled list of the most common passwords and password "base words".
+ * Matching is case-insensitive and also catches simple variations
+ * (trailing digits/symbols, a leading number, and common leet swaps),
+ * so "Password123!", "P@ssw0rd" and "qwerty2024" are all caught.
+ *
+ * It is intentionally small (a few KB) — for full coverage, pair it with
+ * `checkPwnedPassword` / `usePwnedPassword` (Have I Been Pwned).
+ */
+declare const COMMON_PASSWORDS: readonly string[];
+
+/** Built-in strength labels, weakest to strongest. */
+type StrengthLabel = 'Very Weak' | 'Weak' | 'Medium' | 'Strong' | 'Very Strong';
+/** Text for a rule: a plain string, or a function of the resolved options (handy for i18n). */
+type RuleMessage = string | ((options: ResolvedPolicyOptions) => string);
+/**
+ * A single validation rule. Used for both built-in and custom rules.
+ */
+interface PolicyRule {
+    /** Unique key. Appears in `policyState` and `requirements`. */
+    name: string;
+    /** For built-in rules: the option that switches the rule on. */
+    optionsKey?: keyof PasswordPolicyOptions;
+    /** Return `true` when the password passes. */
+    test: (password: string, options: ResolvedPolicyOptions) => boolean;
+    /** Human-readable requirement, e.g. "No spaces". Falls back to a prettified `name`. */
+    message?: RuleMessage;
+}
+/**
+ * Result of a strength estimator such as zxcvbn.
+ * `score` uses the zxcvbn scale: 0 (too guessable) … 4 (very unguessable).
+ */
+interface StrengthEstimate {
+    score: 0 | 1 | 2 | 3 | 4;
+    /** Optional hint to show the user, e.g. "This is a very common password". */
+    feedback?: string;
+}
+type StrengthEstimator = (password: string) => StrengthEstimate;
+/** Every option is optional. Omitted options fall back to the defaults. */
+interface PasswordPolicyOptions {
+    /** The password to validate (hook only — `validatePassword` takes it as the first argument). */
+    password?: string;
+    /** Minimum length. Default `8`. */
+    minLength?: number;
+    /** Maximum length. Default `0` (no maximum). */
+    maxLength?: number;
+    /** Require a lowercase letter. Default `true`. */
+    lowercaseCheck?: boolean;
+    /** Require an uppercase letter. Default `true`. */
+    uppercaseCheck?: boolean;
+    /** Require a digit. Default `true`. */
+    numberCheck?: boolean;
+    /** Require a special character. Default `true`. */
+    specialCharCheck?: boolean;
+    /** Reject very common passwords ("password", "qwerty123", "Password1!" …). Default `false`. */
+    commonPasswordCheck?: boolean;
+    /** Replace the built-in common-password list. */
+    commonPasswords?: readonly string[];
+    /**
+     * When set (even to `''`), adds a `match` rule that passes only if
+     * `password === confirmPassword`.
+     */
+    confirmPassword?: string;
+    /**
+     * Plug in a real strength estimator (e.g. zxcvbn via `fromZxcvbn`).
+     * When set, `strengthLabel` and `strengthPercent` come from the estimator.
+     */
+    strengthEstimator?: StrengthEstimator;
+    /** With `strengthEstimator`: minimum score (0–4) required. Adds a `strength` rule. */
+    minStrength?: 0 | 1 | 2 | 3 | 4;
+    /** Your own rules, checked after the built-in ones. */
+    customRules?: PolicyRule[];
+    /** Override requirement text per rule name, e.g. `{ minLength: 'Mindestens 8 Zeichen' }`. */
+    messages?: Partial<Record<string, RuleMessage>>;
+    lowercaseRegex?: RegExp;
+    uppercaseRegex?: RegExp;
+    numberRegex?: RegExp;
+    specialCharRegex?: RegExp;
+}
+/** Options after defaults are applied. Passed to every rule's `test`. */
+type ResolvedPolicyOptions = Required<Omit<PasswordPolicyOptions, 'password' | 'confirmPassword' | 'strengthEstimator' | 'minStrength'>> & Pick<PasswordPolicyOptions, 'confirmPassword' | 'strengthEstimator' | 'minStrength'>;
+/** @deprecated Use `ResolvedPolicyOptions`. */
+type PolicyDefaults = ResolvedPolicyOptions;
+/** Pass/fail for each active rule, keyed by rule name. */
+interface PasswordPolicyState {
+    [key: string]: boolean;
+}
+/** One row of a requirements checklist. */
+interface Requirement {
+    name: string;
+    passed: boolean;
+    message: string;
+}
+/** Result of `validatePassword` (and the hook). */
+interface ValidationResult {
+    /** `true` only when every active rule passes. */
+    isValid: boolean;
+    /** Pass/fail per rule name. */
+    policyState: PasswordPolicyState;
+    /** Ordered checklist with human-readable messages. */
+    requirements: Requirement[];
+    /** Messages of the rules that failed, in order. Handy for form errors. */
+    errors: string[];
+    /** Number of rules that passed. */
+    strengthScore: number;
+    /** 0–1. Share of rules passed, or the estimator score / 4 when an estimator is set. */
+    strengthPercent: number;
+    strengthLabel: StrengthLabel;
+    /** The estimator's result, if `strengthEstimator` is set. */
+    estimate?: StrengthEstimate;
+}
+/** What `usePasswordPolicy` returns. */
+interface HookReturnValue extends ValidationResult {
+    password?: string;
+}
+
+interface CheckPwnedOptions {
+    /** Abort the request (e.g. when the user keeps typing). */
+    signal?: AbortSignal;
+    /** Custom fetch implementation. Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+    /** Range API base URL. Defaults to Have I Been Pwned. */
+    endpoint?: string;
+    /**
+     * Ask HIBP to pad the response so its size doesn't hint at the result.
+     * Sends an `Add-Padding` header. Default `false`.
+     */
+    padding?: boolean;
+}
+/**
+ * How many times this password appears in known data breaches, using the
+ * Have I Been Pwned range API (k-anonymity). Only the first 5 characters of
+ * the password's SHA-1 hash leave the device — never the password itself.
+ *
+ * Resolves to `0` when the password was not found.
+ */
+declare function checkPwnedPassword(password: string, options?: CheckPwnedOptions): Promise<number>;
+
+/**
+ * use-password-policy/core
+ *
+ * Framework-free password validation. No React import, so it runs anywhere:
+ * the browser, Node, Deno, Bun, edge functions — which lets you enforce the
+ * exact same policy on the client and the server.
+ */
+
+declare const DEFAULT_OPTIONS: ResolvedPolicyOptions;
+/**
+ * Ready-made policies. Spread one and override what you need:
+ * `usePasswordPolicy({ ...presets.nist, password })`
+ */
+declare const presets: {
+    /** The classic checklist (these are also the defaults): 8+ chars, upper, lower, number, symbol. */
+    classic: {
+        minLength: number;
+        lowercaseCheck: true;
+        uppercaseCheck: true;
+        numberCheck: true;
+        specialCharCheck: true;
+    };
+    /**
+     * NIST SP 800-63B-4 (Aug 2025) for passwords used on their own:
+     * at least 15 characters, allow up to 64, no composition rules, block common passwords.
+     */
+    nist: {
+        minLength: number;
+        maxLength: number;
+        lowercaseCheck: false;
+        uppercaseCheck: false;
+        numberCheck: false;
+        specialCharCheck: false;
+        commonPasswordCheck: true;
+    };
+    /** NIST SP 800-63B-4 when the password is one factor of MFA: at least 8 characters. */
+    nistMfa: {
+        minLength: number;
+        maxLength: number;
+        lowercaseCheck: false;
+        uppercaseCheck: false;
+        numberCheck: false;
+        specialCharCheck: false;
+        commonPasswordCheck: true;
+    };
+};
+declare const DEFAULT_MESSAGES: Record<string, RuleMessage>;
+/** Merge user options over the defaults, ignoring keys set to `undefined`. */
+declare function resolveOptions(options?: PasswordPolicyOptions): ResolvedPolicyOptions;
+/**
+ * `true` if the password is on the list, or is a list entry with simple
+ * decoration: trailing digits/symbols ("password123!"), a leading number
+ * ("123qwerty") or leet swaps ("p@ssw0rd").
+ */
+declare function isCommonPassword(password: string, list?: readonly string[]): boolean;
+/**
+ * Validate a password against a policy. Pure and synchronous.
+ *
+ * ```ts
+ * import { validatePassword, presets } from 'use-password-policy/core';
+ * const { isValid, errors } = validatePassword(req.body.password, presets.nist);
+ * ```
+ */
+declare function validatePassword(password: string, options?: PasswordPolicyOptions): ValidationResult;
+/** Anything shaped like the result of `zxcvbn(password)` or `@zxcvbn-ts/core`'s `zxcvbn(password)`. */
+interface ZxcvbnLikeResult {
+    score: number;
+    feedback?: {
+        warning?: string | null;
+        suggestions?: readonly string[];
+    };
+}
+type ZxcvbnFn = (password: string, userInputs?: (string | number)[]) => ZxcvbnLikeResult;
+/**
+ * Wrap zxcvbn as a `strengthEstimator`. Accepts either a function
+ * (`zxcvbn` package, @zxcvbn-ts v3) or an object with `check`
+ * (@zxcvbn-ts v4's `new ZxcvbnFactory(options)`).
+ *
+ * ```ts
+ * import { ZxcvbnFactory } from '@zxcvbn-ts/core';
+ * const zxcvbn = new ZxcvbnFactory(options);
+ * usePasswordPolicy({ password, strengthEstimator: fromZxcvbn(zxcvbn), minStrength: 3 });
+ * ```
+ */
+declare function fromZxcvbn(zxcvbn: ZxcvbnFn | {
+    check: ZxcvbnFn;
+}, userInputs?: (string | number)[]): StrengthEstimator;
+/** Minimal shape of Zod's refinement context (works with Zod 3 and 4). */
+interface ZodLikeRefinementCtx {
+    addIssue(issue: {
+        code: 'custom';
+        message: string;
+    }): void;
+}
+/**
+ * Use your policy inside a Zod schema:
+ *
+ * ```ts
+ * const schema = z.object({ password: z.string().superRefine(zodPasswordRule(policy)) });
+ * ```
+ * Adds one issue per failed rule (or only the first with `{ allErrors: false }`).
+ */
+declare function zodPasswordRule(options?: PasswordPolicyOptions, { allErrors }?: {
+    allErrors?: boolean | undefined;
+}): (value: string, ctx: ZodLikeRefinementCtx) => void;
+/**
+ * A validate function that returns `true` or the first error message.
+ * Drops straight into react-hook-form's `validate`, and works with anything
+ * that uses the same convention.
+ *
+ * ```ts
+ * register('password', { validate: passwordValidator(policy) })
+ * ```
+ */
+declare function passwordValidator(options?: PasswordPolicyOptions): (value: string) => true | string;
+
+export { COMMON_PASSWORDS, type CheckPwnedOptions, DEFAULT_MESSAGES, DEFAULT_OPTIONS, type HookReturnValue, type PasswordPolicyOptions, type PasswordPolicyState, type PolicyDefaults, type PolicyRule, type Requirement, type ResolvedPolicyOptions, type RuleMessage, type StrengthEstimate, type StrengthEstimator, type StrengthLabel, type ValidationResult, type ZodLikeRefinementCtx, type ZxcvbnLikeResult, checkPwnedPassword, fromZxcvbn, isCommonPassword, passwordValidator, presets, resolveOptions, validatePassword, zodPasswordRule };

package/dist/core.d.ts

@@ -0,0 +1,255 @@
+/**
+ * A small, bundled list of the most common passwords and password "base words".
+ * Matching is case-insensitive and also catches simple variations
+ * (trailing digits/symbols, a leading number, and common leet swaps),
+ * so "Password123!", "P@ssw0rd" and "qwerty2024" are all caught.
+ *
+ * It is intentionally small (a few KB) — for full coverage, pair it with
+ * `checkPwnedPassword` / `usePwnedPassword` (Have I Been Pwned).
+ */
+declare const COMMON_PASSWORDS: readonly string[];
+
+/** Built-in strength labels, weakest to strongest. */
+type StrengthLabel = 'Very Weak' | 'Weak' | 'Medium' | 'Strong' | 'Very Strong';
+/** Text for a rule: a plain string, or a function of the resolved options (handy for i18n). */
+type RuleMessage = string | ((options: ResolvedPolicyOptions) => string);
+/**
+ * A single validation rule. Used for both built-in and custom rules.
+ */
+interface PolicyRule {
+    /** Unique key. Appears in `policyState` and `requirements`. */
+    name: string;
+    /** For built-in rules: the option that switches the rule on. */
+    optionsKey?: keyof PasswordPolicyOptions;
+    /** Return `true` when the password passes. */
+    test: (password: string, options: ResolvedPolicyOptions) => boolean;
+    /** Human-readable requirement, e.g. "No spaces". Falls back to a prettified `name`. */
+    message?: RuleMessage;
+}
+/**
+ * Result of a strength estimator such as zxcvbn.
+ * `score` uses the zxcvbn scale: 0 (too guessable) … 4 (very unguessable).
+ */
+interface StrengthEstimate {
+    score: 0 | 1 | 2 | 3 | 4;
+    /** Optional hint to show the user, e.g. "This is a very common password". */
+    feedback?: string;
+}
+type StrengthEstimator = (password: string) => StrengthEstimate;
+/** Every option is optional. Omitted options fall back to the defaults. */
+interface PasswordPolicyOptions {
+    /** The password to validate (hook only — `validatePassword` takes it as the first argument). */
+    password?: string;
+    /** Minimum length. Default `8`. */
+    minLength?: number;
+    /** Maximum length. Default `0` (no maximum). */
+    maxLength?: number;
+    /** Require a lowercase letter. Default `true`. */
+    lowercaseCheck?: boolean;
+    /** Require an uppercase letter. Default `true`. */
+    uppercaseCheck?: boolean;
+    /** Require a digit. Default `true`. */
+    numberCheck?: boolean;
+    /** Require a special character. Default `true`. */
+    specialCharCheck?: boolean;
+    /** Reject very common passwords ("password", "qwerty123", "Password1!" …). Default `false`. */
+    commonPasswordCheck?: boolean;
+    /** Replace the built-in common-password list. */
+    commonPasswords?: readonly string[];
+    /**
+     * When set (even to `''`), adds a `match` rule that passes only if
+     * `password === confirmPassword`.
+     */
+    confirmPassword?: string;
+    /**
+     * Plug in a real strength estimator (e.g. zxcvbn via `fromZxcvbn`).
+     * When set, `strengthLabel` and `strengthPercent` come from the estimator.
+     */
+    strengthEstimator?: StrengthEstimator;
+    /** With `strengthEstimator`: minimum score (0–4) required. Adds a `strength` rule. */
+    minStrength?: 0 | 1 | 2 | 3 | 4;
+    /** Your own rules, checked after the built-in ones. */
+    customRules?: PolicyRule[];
+    /** Override requirement text per rule name, e.g. `{ minLength: 'Mindestens 8 Zeichen' }`. */
+    messages?: Partial<Record<string, RuleMessage>>;
+    lowercaseRegex?: RegExp;
+    uppercaseRegex?: RegExp;
+    numberRegex?: RegExp;
+    specialCharRegex?: RegExp;
+}
+/** Options after defaults are applied. Passed to every rule's `test`. */
+type ResolvedPolicyOptions = Required<Omit<PasswordPolicyOptions, 'password' | 'confirmPassword' | 'strengthEstimator' | 'minStrength'>> & Pick<PasswordPolicyOptions, 'confirmPassword' | 'strengthEstimator' | 'minStrength'>;
+/** @deprecated Use `ResolvedPolicyOptions`. */
+type PolicyDefaults = ResolvedPolicyOptions;
+/** Pass/fail for each active rule, keyed by rule name. */
+interface PasswordPolicyState {
+    [key: string]: boolean;
+}
+/** One row of a requirements checklist. */
+interface Requirement {
+    name: string;
+    passed: boolean;
+    message: string;
+}
+/** Result of `validatePassword` (and the hook). */
+interface ValidationResult {
+    /** `true` only when every active rule passes. */
+    isValid: boolean;
+    /** Pass/fail per rule name. */
+    policyState: PasswordPolicyState;
+    /** Ordered checklist with human-readable messages. */
+    requirements: Requirement[];
+    /** Messages of the rules that failed, in order. Handy for form errors. */
+    errors: string[];
+    /** Number of rules that passed. */
+    strengthScore: number;
+    /** 0–1. Share of rules passed, or the estimator score / 4 when an estimator is set. */
+    strengthPercent: number;
+    strengthLabel: StrengthLabel;
+    /** The estimator's result, if `strengthEstimator` is set. */
+    estimate?: StrengthEstimate;
+}
+/** What `usePasswordPolicy` returns. */
+interface HookReturnValue extends ValidationResult {
+    password?: string;
+}
+
+interface CheckPwnedOptions {
+    /** Abort the request (e.g. when the user keeps typing). */
+    signal?: AbortSignal;
+    /** Custom fetch implementation. Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+    /** Range API base URL. Defaults to Have I Been Pwned. */
+    endpoint?: string;
+    /**
+     * Ask HIBP to pad the response so its size doesn't hint at the result.
+     * Sends an `Add-Padding` header. Default `false`.
+     */
+    padding?: boolean;
+}
+/**
+ * How many times this password appears in known data breaches, using the
+ * Have I Been Pwned range API (k-anonymity). Only the first 5 characters of
+ * the password's SHA-1 hash leave the device — never the password itself.
+ *
+ * Resolves to `0` when the password was not found.
+ */
+declare function checkPwnedPassword(password: string, options?: CheckPwnedOptions): Promise<number>;
+
+/**
+ * use-password-policy/core
+ *
+ * Framework-free password validation. No React import, so it runs anywhere:
+ * the browser, Node, Deno, Bun, edge functions — which lets you enforce the
+ * exact same policy on the client and the server.
+ */
+
+declare const DEFAULT_OPTIONS: ResolvedPolicyOptions;
+/**
+ * Ready-made policies. Spread one and override what you need:
+ * `usePasswordPolicy({ ...presets.nist, password })`
+ */
+declare const presets: {
+    /** The classic checklist (these are also the defaults): 8+ chars, upper, lower, number, symbol. */
+    classic: {
+        minLength: number;
+        lowercaseCheck: true;
+        uppercaseCheck: true;
+        numberCheck: true;
+        specialCharCheck: true;
+    };
+    /**
+     * NIST SP 800-63B-4 (Aug 2025) for passwords used on their own:
+     * at least 15 characters, allow up to 64, no composition rules, block common passwords.
+     */
+    nist: {
+        minLength: number;
+        maxLength: number;
+        lowercaseCheck: false;
+        uppercaseCheck: false;
+        numberCheck: false;
+        specialCharCheck: false;
+        commonPasswordCheck: true;
+    };
+    /** NIST SP 800-63B-4 when the password is one factor of MFA: at least 8 characters. */
+    nistMfa: {
+        minLength: number;
+        maxLength: number;
+        lowercaseCheck: false;
+        uppercaseCheck: false;
+        numberCheck: false;
+        specialCharCheck: false;
+        commonPasswordCheck: true;
+    };
+};
+declare const DEFAULT_MESSAGES: Record<string, RuleMessage>;
+/** Merge user options over the defaults, ignoring keys set to `undefined`. */
+declare function resolveOptions(options?: PasswordPolicyOptions): ResolvedPolicyOptions;
+/**
+ * `true` if the password is on the list, or is a list entry with simple
+ * decoration: trailing digits/symbols ("password123!"), a leading number
+ * ("123qwerty") or leet swaps ("p@ssw0rd").
+ */
+declare function isCommonPassword(password: string, list?: readonly string[]): boolean;
+/**
+ * Validate a password against a policy. Pure and synchronous.
+ *
+ * ```ts
+ * import { validatePassword, presets } from 'use-password-policy/core';
+ * const { isValid, errors } = validatePassword(req.body.password, presets.nist);
+ * ```
+ */
+declare function validatePassword(password: string, options?: PasswordPolicyOptions): ValidationResult;
+/** Anything shaped like the result of `zxcvbn(password)` or `@zxcvbn-ts/core`'s `zxcvbn(password)`. */
+interface ZxcvbnLikeResult {
+    score: number;
+    feedback?: {
+        warning?: string | null;
+        suggestions?: readonly string[];
+    };
+}
+type ZxcvbnFn = (password: string, userInputs?: (string | number)[]) => ZxcvbnLikeResult;
+/**
+ * Wrap zxcvbn as a `strengthEstimator`. Accepts either a function
+ * (`zxcvbn` package, @zxcvbn-ts v3) or an object with `check`
+ * (@zxcvbn-ts v4's `new ZxcvbnFactory(options)`).
+ *
+ * ```ts
+ * import { ZxcvbnFactory } from '@zxcvbn-ts/core';
+ * const zxcvbn = new ZxcvbnFactory(options);
+ * usePasswordPolicy({ password, strengthEstimator: fromZxcvbn(zxcvbn), minStrength: 3 });
+ * ```
+ */
+declare function fromZxcvbn(zxcvbn: ZxcvbnFn | {
+    check: ZxcvbnFn;
+}, userInputs?: (string | number)[]): StrengthEstimator;
+/** Minimal shape of Zod's refinement context (works with Zod 3 and 4). */
+interface ZodLikeRefinementCtx {
+    addIssue(issue: {
+        code: 'custom';
+        message: string;
+    }): void;
+}
+/**
+ * Use your policy inside a Zod schema:
+ *
+ * ```ts
+ * const schema = z.object({ password: z.string().superRefine(zodPasswordRule(policy)) });
+ * ```
+ * Adds one issue per failed rule (or only the first with `{ allErrors: false }`).
+ */
+declare function zodPasswordRule(options?: PasswordPolicyOptions, { allErrors }?: {
+    allErrors?: boolean | undefined;
+}): (value: string, ctx: ZodLikeRefinementCtx) => void;
+/**
+ * A validate function that returns `true` or the first error message.
+ * Drops straight into react-hook-form's `validate`, and works with anything
+ * that uses the same convention.
+ *
+ * ```ts
+ * register('password', { validate: passwordValidator(policy) })
+ * ```
+ */
+declare function passwordValidator(options?: PasswordPolicyOptions): (value: string) => true | string;
+
+export { COMMON_PASSWORDS, type CheckPwnedOptions, DEFAULT_MESSAGES, DEFAULT_OPTIONS, type HookReturnValue, type PasswordPolicyOptions, type PasswordPolicyState, type PolicyDefaults, type PolicyRule, type Requirement, type ResolvedPolicyOptions, type RuleMessage, type StrengthEstimate, type StrengthEstimator, type StrengthLabel, type ValidationResult, type ZodLikeRefinementCtx, type ZxcvbnLikeResult, checkPwnedPassword, fromZxcvbn, isCommonPassword, passwordValidator, presets, resolveOptions, validatePassword, zodPasswordRule };