use-password-policy 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 3.1.0
+
+### Added
+- **`patternCheck`** rejects predictable passwords: repeated characters (`aaaaaaaaaaaaaaa`), repeated chunks (`qwertyqwertyqwerty`, `dragon dragon dragon`), sequences and keyboard runs (`123456789012345`, `abcdefghijk`), and passwords made of only a few distinct characters, including all spaces. It's on in `presets.nist` and `presets.nistMfa`.
+- **`breachCheck`** puts Have I Been Pwned into the normal result. The hook checks once the other rules pass and adds a `notBreached` requirement that is `pending` until answered. `isValid` waits for it, and the component shows it automatically. `failOpen` decides what happens when the service is down (default: let through).
+- **`validatePasswordAsync()`** for servers, with the same result plus the breach check. Also `zodPasswordRuleAsync()`, `passwordValidatorAsync()` and `applyBreachResult()`.
+- Results include `breach: { status, count }`, and requirements can be `pending`.
+- `isPredictablePattern()` and `passwordLength()` helpers.
+
+### Fixed
+- Length rules count Unicode code points, as NIST specifies. 8 emoji no longer pass a 15-character minimum.
+- The common-password check now catches list words joined together (`passwordpassword`, `Summer2024!Summer`).
+- `<PasswordPolicyInput />` calls `onPasswordChange` again when an async check settles.
+- Repeated breach checks for the same hash prefix reuse the previous response.
+
 ## 3.0.0
 
 ### Added

package/README.md

@@ -12,7 +12,7 @@
 - A **NIST SP 800-63B** preset, a common-password blocklist and **Have I Been Pwned** breach checks
 - Optional **zxcvbn** scoring, so "strength" means how hard a password is to guess, not how many boxes it ticks
 - **Zod** and **react-hook-form** helpers
-- No runtime dependencies. About 3 KB gzipped for the core, about 5.5 KB with the React parts.
+- No runtime dependencies. About 4 KB gzipped for the core, about 6.5 KB with the React parts.
 
 ### [➡️ Live demo & playground](https://rahulpatwa1303.github.io/use-password-policy/)
 
@@ -78,18 +78,20 @@ const { isValid, requirements, strengthLabel, strengthPercent } = usePasswordPol
 ```ts
 // password-policy.ts — shared by client and server
 import { presets, type PasswordPolicyOptions } from 'use-password-policy/core';
-export const policy: PasswordPolicyOptions = { ...presets.nist };
+export const policy: PasswordPolicyOptions = { ...presets.nist, breachCheck: true };
 ```
 
 ```ts
 // api/sign-up.ts (Node, Next.js route handler, Express, Cloudflare Worker…)
-import { validatePassword } from 'use-password-policy/core';
+import { validatePasswordAsync } from 'use-password-policy/core';
 import { policy } from './password-policy';
 
-const { isValid, errors } = validatePassword(body.password, policy);
+const { isValid, errors } = await validatePasswordAsync(body.password, policy);
 if (!isValid) return Response.json({ errors }, { status: 400 });
 ```
 
+Use `validatePasswordAsync` when the policy has `breachCheck`. Without it, the synchronous `validatePassword` returns the same result.
+
 `use-password-policy/core` doesn't import React, so it's safe in server bundles.
 
 ## Presets
@@ -102,13 +104,13 @@ usePasswordPolicy({ ...presets.nistMfa, password });       // NIST, password is
 usePasswordPolicy({ ...presets.classic, password });       // 8+ chars, upper, lower, number, symbol (the default)
 ```
 
-| Preset | Min | Max | Composition rules | Blocks common passwords |
-| --- | --- | --- | --- | --- |
-| `classic` (default) | 8 | – | upper, lower, number, symbol | no |
-| `nist` | 15 | 64 | none | yes |
-| `nistMfa` | 8 | 64 | none | yes |
+| Preset | Min | Max | Composition rules | Blocks common passwords | Blocks patterns |
+| --- | --- | --- | --- | --- | --- |
+| `classic` (default) | 8 | – | upper, lower, number, symbol | no | no |
+| `nist` | 15 | 64 | none | yes | yes |
+| `nistMfa` | 8 | 64 | none | yes | yes |
 
-The NIST presets follow [SP 800-63B-4](https://pages.nist.gov/800-63-4/sp800-63b.html). It asks for length and a blocklist check, and says not to require "mixtures of different character types".
+The NIST presets follow [SP 800-63B-4](https://pages.nist.gov/800-63-4/sp800-63b.html). It asks for length and a blocklist check, and says not to require "mixtures of different character types". Length is counted in Unicode code points, as NIST specifies, so an emoji counts as one character. To also check known breaches, add `breachCheck: true`.
 
 ## Security add-ons
 
@@ -118,19 +120,34 @@ The NIST presets follow [SP 800-63B-4](https://pages.nist.gov/800-63-4/sp800-63b
 usePasswordPolicy({ password, commonPasswordCheck: true });
 ```
 
-This uses a small built-in list of the most common passwords and base words. It also catches simple variations such as `Password123!`, `P@ssw0rd`, `123qwerty` and `Monkey!!`. Pass `commonPasswords: [...]` to use your own list, for example your product name.
+This uses a small built-in list of the most common passwords and base words. It also catches simple variations such as `Password123!`, `P@ssw0rd`, `123qwerty` and `Monkey!!`, and list words joined together such as `passwordpassword` or `Summer2024!Summer`. Pass `commonPasswords: [...]` to use your own list, for example your product name.
+
+### Block predictable patterns
+
+```ts
+usePasswordPolicy({ password, patternCheck: true });   // on in the NIST presets
+```
+
+Rejects repeated characters (`aaaaaaaaaaaaaaa`), repeated chunks (`qwertyqwertyqwerty`, `dragon dragon dragon`), sequences and keyboard runs (`123456789012345`, `abcdefghijk`, `qwertyuiop`), and passwords made of only a few distinct characters, including all spaces.
 
 ### Check breached passwords (Have I Been Pwned)
 
 ```tsx
-import { usePwnedPassword } from 'use-password-policy';
-
-const pwned = usePwnedPassword(password, { enabled: isValid }); // debounced, cancels stale requests
-// pwned.status: 'idle' | 'checking' | 'safe' | 'pwned' | 'error'
-{pwned.isPwned && <p>Seen {pwned.count.toLocaleString()} times in data breaches. Pick another.</p>}
+const { isValid, requirements, breach } = usePasswordPolicy({ ...presets.nist, breachCheck: true, password });
 ```
 
-On the server: `await checkPwnedPassword(password)` from `use-password-policy/core` returns the breach count.
+With `breachCheck`, the check is part of the normal result:
+- Once every other rule passes, the hook checks Have I Been Pwned (debounced, stale requests cancelled).
+- A "Not found in known data breaches" requirement is `pending` until the check answers, and `isValid` stays `false` until then.
+- A breached password fails with that message and is marked Very Weak. `breach` gives `{ status, count }`, e.g. `{ status: 'pwned', count: 10434004 }`.
+- `<PasswordPolicyInput policyOptions={{ breachCheck: true }} />` shows it in the checklist automatically.
+
+On the server, `await validatePasswordAsync(password, policy)` does the same.
+
+If the service can't be reached, the password is let through by default and `breach.status` is `'error'`. Pass `breachCheck: { failOpen: false }` to block instead. Other settings: `debounceMs` (default 500), `fetch`, `endpoint`, `padding`.
+
+For a custom flow, the lower-level `usePwnedPassword(password)` hook and `checkPwnedPassword(password)` (returns the breach count) are still available.
+
 Only the first 5 characters of the password's SHA-1 hash are sent ([k-anonymity](https://haveibeenpwned.com/API/v3#SearchingPwnedPasswordsByRange)), never the password. It needs `crypto.subtle`, which means HTTPS or `localhost` in browsers and Node 20+ on the server.
 
 ### Real strength scoring with zxcvbn
@@ -168,7 +185,7 @@ const schema = z.object({ password: z.string().superRefine(zodPasswordRule(polic
 register('password', { validate: passwordValidator(policy) });
 ```
 
-Neither helper imports Zod or react-hook-form, so they add no dependencies.
+With `breachCheck`, use the async versions, `zodPasswordRuleAsync(policy)` (with `parseAsync`) and `passwordValidatorAsync(policy)`, so the breach check runs too. None of these helpers import Zod or react-hook-form, so they add no dependencies.
 
 ## Confirm-password field
 
@@ -206,6 +223,8 @@ Rule names: `minLength`, `maxLength`, `uppercase`, `lowercase`, `number`, `speci
 | `numberCheck` | `boolean` | `true` | Require a digit. |
 | `specialCharCheck` | `boolean` | `true` | Require a special character. |
 | `commonPasswordCheck` | `boolean` | `false` | Reject common passwords. |
+| `patternCheck` | `boolean` | `false` | Reject repeats, sequences and keyboard patterns. |
+| `breachCheck` | `boolean \| { failOpen, debounceMs, fetch, endpoint, padding }` | `false` | Include the Have I Been Pwned check (hook and `validatePasswordAsync`). |
 | `commonPasswords` | `string[]` | built-in | Replace the blocklist. |
 | `confirmPassword` | `string` | – | Adds a `match` rule when set. |
 | `strengthEstimator` | `(pw) => { score, feedback? }` | – | For example `fromZxcvbn(zxcvbn)`. |
@@ -226,6 +245,9 @@ Rule names: `minLength`, `maxLength`, `uppercase`, `lowercase`, `number`, `speci
 | `strengthPercent` | `number` (0–1) | Fill for a meter. |
 | `strengthScore` | `number` | Number of rules passed. |
 | `estimate` | `{ score, feedback? }` | Only with `strengthEstimator`. |
+| `breach` | `{ status, count }` | Only with `breachCheck`. `status` is `idle`, `checking`, `safe`, `pwned` or `error`. |
+
+Each requirement is `{ name, passed, message, pending? }`. `pending` is `true` while the breach check hasn't answered.
 
 ### `<PasswordPolicyInput />` props
 

package/dist/core.d.mts

@@ -9,6 +9,28 @@
  */
 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). */
@@ -56,6 +78,19 @@ interface PasswordPolicyOptions {
     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`.
@@ -77,8 +112,34 @@ interface PasswordPolicyOptions {
     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'>> & Pick<PasswordPolicyOptions, 'confirmPassword' | 'strengthEstimator' | 'minStrength'>;
+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. */
@@ -90,6 +151,8 @@ 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 {
@@ -108,34 +171,14 @@ interface ValidationResult {
     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;
 }
 
-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
  *
@@ -160,7 +203,8 @@ declare const presets: {
     };
     /**
      * 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.
+     * 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;
@@ -170,6 +214,7 @@ declare const presets: {
         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: {
@@ -180,17 +225,28 @@ declare const presets: {
         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, or is a list entry with simple
- * decoration: trailing digits/symbols ("password123!"), a leading number
- * ("123qwerty") or leet swaps ("p@ssw0rd").
+ * `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.
  *
@@ -200,6 +256,22 @@ declare function isCommonPassword(password: string, list?: readonly string[]): b
  * ```
  */
 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;
@@ -241,6 +313,18 @@ interface ZodLikeRefinementCtx {
 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
@@ -252,4 +336,4 @@ declare function zodPasswordRule(options?: PasswordPolicyOptions, { allErrors }?
  */
 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 };
+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

@@ -9,6 +9,28 @@
  */
 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). */
@@ -56,6 +78,19 @@ interface PasswordPolicyOptions {
     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`.
@@ -77,8 +112,34 @@ interface PasswordPolicyOptions {
     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'>> & Pick<PasswordPolicyOptions, 'confirmPassword' | 'strengthEstimator' | 'minStrength'>;
+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. */
@@ -90,6 +151,8 @@ 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 {
@@ -108,34 +171,14 @@ interface ValidationResult {
     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;
 }
 
-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
  *
@@ -160,7 +203,8 @@ declare const presets: {
     };
     /**
      * 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.
+     * 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;
@@ -170,6 +214,7 @@ declare const presets: {
         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: {
@@ -180,17 +225,28 @@ declare const presets: {
         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, or is a list entry with simple
- * decoration: trailing digits/symbols ("password123!"), a leading number
- * ("123qwerty") or leet swaps ("p@ssw0rd").
+ * `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.
  *
@@ -200,6 +256,22 @@ declare function isCommonPassword(password: string, list?: readonly string[]): b
  * ```
  */
 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;
@@ -241,6 +313,18 @@ interface ZodLikeRefinementCtx {
 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
@@ -252,4 +336,4 @@ declare function zodPasswordRule(options?: PasswordPolicyOptions, { allErrors }?
  */
 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 };
+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 };