Password Policy

PasswordPolicy grades a password and, on request, gates on it. It is the same measurement the library applies to the secrets that protect a workspace or account, exposed so you can screen a password before you ever hand it to Workspace.open or accounts.create. A check returns a structured PasswordCheckResult — a numeric score, an entropy estimate, and a list of typed PasswordWeakness entries — rather than a bare boolean, so your UI can explain why a password was refused.

import { PasswordPolicy, PasswordScore } from "wative-core";

const policy = new PasswordPolicy({ minLength: 12, minScore: PasswordScore.Fair });

const result = policy.check("correct horse battery staple");
result.passable; // true
result.summary;  // "Password OK (score 3, ~132 bits)."

// Or gate on it — throws WativeError("WEAK_PASSWORD") when not passable.
policy.enforce("hunter2");

Constructing a policy

new PasswordPolicy(opts?: PasswordPolicyOptions). Every option is optional; an omitted option takes its default, and passing undefined for an option is treated as "not supplied" (so new PasswordPolicy({ minLength: undefined }) keeps the default floor rather than removing it). Construct one policy and reuse it — instances are stateless between calls.

check vs enforce

Both take the password plus an optional PasswordCheckContext. They differ only in what they do with a failing result.

enforce throws WativeError("WEAK_PASSWORD", summary, { details: { result } }) — the details.result field carries the same PasswordCheckResult check would have returned, so a handler can render the specific weaknesses. check itself throws only when its input is not a string (WativeError("PROVIDER_IO")).

Options

interface PasswordPolicyOptions {
  minScore?: PasswordScore;
  minLength?: number;
  requireUppercase?: boolean;
  requireLowercase?: boolean;
  requireDigit?: boolean;
  requireSymbol?: boolean;
  forbiddenWords?: string[];
}

PasswordCheckContext

The optional second argument supplies per-user context the policy cannot know on its own.

interface PasswordCheckContext {
  username?: string;
  history?: string[];
}

Result and weakness codes

interface PasswordCheckResult {
  readonly score: PasswordScore;
  readonly entropyBits: number;
  readonly weaknesses: ReadonlyArray<PasswordWeakness>;
  readonly passable: boolean;
  readonly summary: string;
}

PasswordScore is a named enum that replaces bare 0..4 magic numbers:

Each PasswordWeakness is { code, severity, message, fix? }, where severity is one of "critical" | "warning" | "info" and fix is an optional remediation hint:

interface PasswordWeakness {
  readonly code: PasswordWeaknessCode;
  readonly severity: "critical" | "warning" | "info";
  readonly message: string;
  readonly fix?: string;
}

PasswordWeaknessCode is the closed union below. Only critical codes can flip passable to false; warning and info codes lower the score but never reject on their own.

NFC-normalized measurement

The KDF normalizes a password to NFC before deriving a key, so check measures the NFC form too — length, character-class rules, entropy, username and history comparisons all run against password.normalize("NFC"). A decomposed password is longer than its composed form; measuring the raw string would report a stronger secret than the one actually protecting the wallet, and could pass a length rule the derived form fails.

See also