use-password-policy 2.0.0 → 3.1.0

package/dist/core.d.mts

@@ -0,0 +1,339 @@
+/**
+ * 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[];
+
+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>;
+
+/** 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[];
+    /**
+     * Reject predictable patterns: repeated characters (`aaaaaaaa`), repeated chunks
+     * (`abcabcabc`), sequences and keyboard runs (`123456789`, `qwertyuiop`), and passwords
+     * made of only a few distinct characters (including all spaces). Default `false`;
+     * on in the NIST presets.
+     */
+    patternCheck?: boolean;
+    /**
+     * Check Have I Been Pwned as part of the result. The hook runs it automatically once
+     * every other rule passes; on the server use `validatePasswordAsync`. The synchronous
+     * `validatePassword` ignores this option. Default `false`.
+     */
+    breachCheck?: boolean | BreachCheckOptions;
+    /**
+     * 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;
+}
+interface BreachCheckOptions {
+    /**
+     * What to do when the breach service can't be reached: `true` lets the password
+     * through (the requirement passes and `breach.status` is `'error'`), `false` blocks it.
+     * Default `true`.
+     */
+    failOpen?: boolean;
+    /** Hook only: wait this long after the last keystroke. Default `500` ms. */
+    debounceMs?: number;
+    /** Custom fetch implementation. */
+    fetch?: typeof fetch;
+    /** Range API base URL. Defaults to Have I Been Pwned. */
+    endpoint?: string;
+    /** Send the `Add-Padding` header. Default `false`. */
+    padding?: boolean;
+}
+type BreachStatus = 'idle' | 'checking' | 'safe' | 'pwned' | 'error';
+interface BreachResult {
+    /**
+     * `idle`: not checked yet (other rules still failing, or no input).
+     * `checking`: request in flight. `safe` / `pwned`: answered. `error`: couldn't reach the service.
+     */
+    status: BreachStatus;
+    /** Times seen in breaches (0 unless `pwned`). */
+    count: number;
+}
+/** Options after defaults are applied. Passed to every rule's `test`. */
+type ResolvedPolicyOptions = Required<Omit<PasswordPolicyOptions, 'password' | 'confirmPassword' | 'strengthEstimator' | 'minStrength' | 'breachCheck'>> & Pick<PasswordPolicyOptions, 'confirmPassword' | 'strengthEstimator' | 'minStrength' | 'breachCheck'>;
+/** @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;
+    /** `true` while the result isn't known yet (the breach check before it has answered). */
+    pending?: boolean;
+}
+/** 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;
+    /** Breach-check state, when `breachCheck` is on (hook and `validatePasswordAsync`). */
+    breach?: BreachResult;
+}
+/** What `usePasswordPolicy` returns. */
+interface HookReturnValue extends ValidationResult {
+    password?: string;
+}
+
+/**
+ * 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
+     * and predictable patterns. Add `breachCheck: true` to also check known breaches.
+     */
+    nist: {
+        minLength: number;
+        maxLength: number;
+        lowercaseCheck: false;
+        uppercaseCheck: false;
+        numberCheck: false;
+        specialCharCheck: false;
+        commonPasswordCheck: true;
+        patternCheck: 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;
+        patternCheck: 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;
+/** Length in Unicode code points, so an emoji counts as one character (as NIST specifies). */
+declare const passwordLength: (password: string) => number;
+/**
+ * `true` if the password is on the list, is a list entry with simple decoration
+ * (trailing digits/symbols "password123!", a leading number "123qwerty", leet swaps
+ * "p@ssw0rd"), or is only list words joined together ("passwordpassword",
+ * "dragon dragon dragon", "Summer2024!Summer").
+ */
+declare function isCommonPassword(password: string, list?: readonly string[]): boolean;
+/**
+ * `true` for passwords that follow a predictable pattern: only whitespace, three or
+ * fewer distinct characters ("aaaaaaaa", "abababab"), a repeated chunk ("abcabcabc",
+ * "qwertyqwertyqwerty"), or mostly sequences and keyboard runs ("123456789012345",
+ * "abcdefghijk", "qwertyuiop", "987654321").
+ */
+declare function isPredictablePattern(password: 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;
+/**
+ * Fold a breach-check outcome into a validation result: adds a `notBreached`
+ * requirement (pending while unanswered), makes `isValid` depend on it, and marks a
+ * breached password Very Weak. The hook and `validatePasswordAsync` use this; you
+ * only need it for custom flows.
+ */
+declare function applyBreachResult(result: ValidationResult, breach: BreachResult, options?: PasswordPolicyOptions): ValidationResult;
+/**
+ * Like `validatePassword`, plus the Have I Been Pwned check when `breachCheck` is on.
+ * The breach lookup only runs once every other rule passes. Use this on the server.
+ *
+ * ```ts
+ * const { isValid, errors, breach } = await validatePasswordAsync(password, { ...presets.nist, breachCheck: true });
+ * ```
+ */
+declare function validatePasswordAsync(password: string, options?: PasswordPolicyOptions): Promise<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;
+/**
+ * Async version of `zodPasswordRule` that also runs the breach check when
+ * `breachCheck` is on. Use it with `safeParseAsync` / `parseAsync`.
+ */
+declare function zodPasswordRuleAsync(options?: PasswordPolicyOptions, { allErrors }?: {
+    allErrors?: boolean | undefined;
+}): (value: string, ctx: ZodLikeRefinementCtx) => Promise<void>;
+/**
+ * Async version of `passwordValidator` that also runs the breach check when
+ * `breachCheck` is on. react-hook-form accepts async `validate` functions.
+ */
+declare function passwordValidatorAsync(options?: PasswordPolicyOptions): (value: string) => Promise<true | string>;
+/**
+ * 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 { type BreachCheckOptions, type BreachResult, type BreachStatus, 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, applyBreachResult, checkPwnedPassword, fromZxcvbn, isCommonPassword, isPredictablePattern, passwordLength, passwordValidator, passwordValidatorAsync, presets, resolveOptions, validatePassword, validatePasswordAsync, zodPasswordRule, zodPasswordRuleAsync };

package/dist/core.d.ts

@@ -0,0 +1,339 @@
+/**
+ * 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[];
+
+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>;
+
+/** 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[];
+    /**
+     * Reject predictable patterns: repeated characters (`aaaaaaaa`), repeated chunks
+     * (`abcabcabc`), sequences and keyboard runs (`123456789`, `qwertyuiop`), and passwords
+     * made of only a few distinct characters (including all spaces). Default `false`;
+     * on in the NIST presets.
+     */
+    patternCheck?: boolean;
+    /**
+     * Check Have I Been Pwned as part of the result. The hook runs it automatically once
+     * every other rule passes; on the server use `validatePasswordAsync`. The synchronous
+     * `validatePassword` ignores this option. Default `false`.
+     */
+    breachCheck?: boolean | BreachCheckOptions;
+    /**
+     * 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;
+}
+interface BreachCheckOptions {
+    /**
+     * What to do when the breach service can't be reached: `true` lets the password
+     * through (the requirement passes and `breach.status` is `'error'`), `false` blocks it.
+     * Default `true`.
+     */
+    failOpen?: boolean;
+    /** Hook only: wait this long after the last keystroke. Default `500` ms. */
+    debounceMs?: number;
+    /** Custom fetch implementation. */
+    fetch?: typeof fetch;
+    /** Range API base URL. Defaults to Have I Been Pwned. */
+    endpoint?: string;
+    /** Send the `Add-Padding` header. Default `false`. */
+    padding?: boolean;
+}
+type BreachStatus = 'idle' | 'checking' | 'safe' | 'pwned' | 'error';
+interface BreachResult {
+    /**
+     * `idle`: not checked yet (other rules still failing, or no input).
+     * `checking`: request in flight. `safe` / `pwned`: answered. `error`: couldn't reach the service.
+     */
+    status: BreachStatus;
+    /** Times seen in breaches (0 unless `pwned`). */
+    count: number;
+}
+/** Options after defaults are applied. Passed to every rule's `test`. */
+type ResolvedPolicyOptions = Required<Omit<PasswordPolicyOptions, 'password' | 'confirmPassword' | 'strengthEstimator' | 'minStrength' | 'breachCheck'>> & Pick<PasswordPolicyOptions, 'confirmPassword' | 'strengthEstimator' | 'minStrength' | 'breachCheck'>;
+/** @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;
+    /** `true` while the result isn't known yet (the breach check before it has answered). */
+    pending?: boolean;
+}
+/** 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;
+    /** Breach-check state, when `breachCheck` is on (hook and `validatePasswordAsync`). */
+    breach?: BreachResult;
+}
+/** What `usePasswordPolicy` returns. */
+interface HookReturnValue extends ValidationResult {
+    password?: string;
+}
+
+/**
+ * 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
+     * and predictable patterns. Add `breachCheck: true` to also check known breaches.
+     */
+    nist: {
+        minLength: number;
+        maxLength: number;
+        lowercaseCheck: false;
+        uppercaseCheck: false;
+        numberCheck: false;
+        specialCharCheck: false;
+        commonPasswordCheck: true;
+        patternCheck: 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;
+        patternCheck: 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;
+/** Length in Unicode code points, so an emoji counts as one character (as NIST specifies). */
+declare const passwordLength: (password: string) => number;
+/**
+ * `true` if the password is on the list, is a list entry with simple decoration
+ * (trailing digits/symbols "password123!", a leading number "123qwerty", leet swaps
+ * "p@ssw0rd"), or is only list words joined together ("passwordpassword",
+ * "dragon dragon dragon", "Summer2024!Summer").
+ */
+declare function isCommonPassword(password: string, list?: readonly string[]): boolean;
+/**
+ * `true` for passwords that follow a predictable pattern: only whitespace, three or
+ * fewer distinct characters ("aaaaaaaa", "abababab"), a repeated chunk ("abcabcabc",
+ * "qwertyqwertyqwerty"), or mostly sequences and keyboard runs ("123456789012345",
+ * "abcdefghijk", "qwertyuiop", "987654321").
+ */
+declare function isPredictablePattern(password: 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;
+/**
+ * Fold a breach-check outcome into a validation result: adds a `notBreached`
+ * requirement (pending while unanswered), makes `isValid` depend on it, and marks a
+ * breached password Very Weak. The hook and `validatePasswordAsync` use this; you
+ * only need it for custom flows.
+ */
+declare function applyBreachResult(result: ValidationResult, breach: BreachResult, options?: PasswordPolicyOptions): ValidationResult;
+/**
+ * Like `validatePassword`, plus the Have I Been Pwned check when `breachCheck` is on.
+ * The breach lookup only runs once every other rule passes. Use this on the server.
+ *
+ * ```ts
+ * const { isValid, errors, breach } = await validatePasswordAsync(password, { ...presets.nist, breachCheck: true });
+ * ```
+ */
+declare function validatePasswordAsync(password: string, options?: PasswordPolicyOptions): Promise<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;
+/**
+ * Async version of `zodPasswordRule` that also runs the breach check when
+ * `breachCheck` is on. Use it with `safeParseAsync` / `parseAsync`.
+ */
+declare function zodPasswordRuleAsync(options?: PasswordPolicyOptions, { allErrors }?: {
+    allErrors?: boolean | undefined;
+}): (value: string, ctx: ZodLikeRefinementCtx) => Promise<void>;
+/**
+ * Async version of `passwordValidator` that also runs the breach check when
+ * `breachCheck` is on. react-hook-form accepts async `validate` functions.
+ */
+declare function passwordValidatorAsync(options?: PasswordPolicyOptions): (value: string) => Promise<true | string>;
+/**
+ * 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 { type BreachCheckOptions, type BreachResult, type BreachStatus, 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, applyBreachResult, checkPwnedPassword, fromZxcvbn, isCommonPassword, isPredictablePattern, passwordLength, passwordValidator, passwordValidatorAsync, presets, resolveOptions, validatePassword, validatePasswordAsync, zodPasswordRule, zodPasswordRuleAsync };