auth.password-policy

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

import { POLICIES } from "./auth_password_policy_data.ts";  ← this capability’s own data, compiled from data/policies.json into the same file by fune build
import { type PasswordPolicy } from "./auth_password_policy_types.ts";

/**
 * A named policy from the data, so a browser and an API that both ask for
 * "nist-800-63b-4-single-factor" enforce exactly the same numbers.
 */
export function passwordPolicy(name: string): PasswordPolicy {
  for (const row of POLICIES) {
    if (row.name === name) {
      return {
        name: row.name,
        minLength: row.minLength,
        maxLength: row.maxLength,
        minCharacterClasses: row.minCharacterClasses,
        blockCommon: row.blockCommon,
        blockPersonal: row.blockPersonal,
      };
    }
  }
  throw new RangeError(`unknown password policy "${name}"; known policies: ${POLICIES.map((row) => row.name).join(", ")}`);
}

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

import { COMMON_PASSWORDS } from "./auth_password_policy_data.ts";  ← this capability’s own data, compiled from data/policies.json into the same file by fune build
import { type PasswordCheck, type PasswordFailure, type PasswordPolicy } from "./auth_password_policy_types.ts";

/** Words shorter than this in a name or email are not refused inside a password: "al" or "jo" would refuse half of all passwords. */
const MIN_PERSONAL = 3;

let commonSet: Set<string> | null = null;

/** ASCII-only lower-casing, the same in every language (toLowerCase folds non-ASCII letters Python and Rust fold differently). */
function asciiLower(text: string): string {
  let out = "";
  for (let i = 0; i < text.length; i++) {
    const c = text.charCodeAt(i);
    out += c >= 65 && c <= 90 ? String.fromCharCode(c + 32) : text[i];
  }
  return out;
}

function isAsciiAlnum(ch: string): boolean {
  return (ch >= "a" && ch <= "z") || (ch >= "A" && ch <= "Z") || (ch >= "0" && ch <= "9");
}

/** Pieces of text between ASCII punctuation and spaces, lower-cased, of 3 or more characters. */
function words(text: string): string[] {
  const out: string[] = [];
  let current = "";
  for (const ch of Array.from(text)) {
    if (ch.length === 1 && ch.charCodeAt(0) < 128 && !isAsciiAlnum(ch)) {
      if (Array.from(current).length >= MIN_PERSONAL) out.push(asciiLower(current));
      current = "";
    } else {
      current += ch;
    }
  }
  if (Array.from(current).length >= MIN_PERSONAL) out.push(asciiLower(current));
  return out;
}

function checkPolicy(policy: PasswordPolicy): void {
  if (typeof policy !== "object" || policy === null) throw new TypeError("policy must be a PasswordPolicy");
  if (!Number.isInteger(policy.minLength) || policy.minLength < 1) {
    throw new RangeError("policy minLength must be a whole number of at least 1");
  }
  if (!Number.isInteger(policy.maxLength) || policy.maxLength < policy.minLength) {
    throw new RangeError("policy maxLength must be a whole number no smaller than minLength");
  }
  if (!Number.isInteger(policy.minCharacterClasses) || policy.minCharacterClasses < 0 || policy.minCharacterClasses > 4) {
    throw new RangeError("policy minCharacterClasses must be a whole number from 0 to 4");
  }
}

/**
 * Every rule of the policy the password breaks, in a fixed order, each with
 * a sentence to show beside the field. The same function runs in the
 * browser, for instant feedback, and on the server, which decides.
 */
export function checkPassword(password: string, email: string | null, name: string | null, policy: PasswordPolicy): PasswordCheck {
  if (typeof password !== "string") throw new TypeError("password must be a string");
  checkPolicy(policy);
  const failures: PasswordFailure[] = [];
  const chars = Array.from(password);

  if (chars.length < policy.minLength) {
    failures.push({ code: "too_short", message: `Use at least ${policy.minLength} characters.` });
  }
  if (chars.length > policy.maxLength) {
    failures.push({ code: "too_long", message: `Use no more than ${policy.maxLength} characters.` });
  }
  if (policy.minCharacterClasses > 0) {
    let lower = 0, upper = 0, digit = 0, other = 0;
    for (const ch of chars) {
      if (ch >= "a" && ch <= "z") lower = 1;
      else if (ch >= "A" && ch <= "Z") upper = 1;
      else if (ch >= "0" && ch <= "9") digit = 1;
      else other = 1;
    }
    if (lower + upper + digit + other < policy.minCharacterClasses) {
      failures.push({
        code: "too_few_character_classes",
        message: `Use at least ${policy.minCharacterClasses} of these: lower-case letters, capital letters, digits, symbols.`,
      });
    }
  }

  const folded = asciiLower(password);
  if (policy.blockCommon) {
    if (commonSet === null) commonSet = new Set(COMMON_PASSWORDS.map((row) => row.password));
    if (commonSet.has(folded)) {
      failures.push({ code: "too_common", message: "This password is too common. Choose something harder to guess." });
    }
  }
  if (policy.blockPersonal) {
    if (typeof email === "string") {
      const at = email.lastIndexOf("@");
      const local = at >= 0 ? email.slice(0, at) : email;
      const candidates = words(local);
      if (Array.from(local).length >= MIN_PERSONAL) candidates.push(asciiLower(local));
      if (candidates.some((word) => folded.includes(word))) {
        failures.push({ code: "contains_email", message: "Do not include your email address in your password." });
      }
    }
    if (typeof name === "string" && words(name).some((word) => folded.includes(word))) {
      failures.push({ code: "contains_name", message: "Do not include your name in your password." });
    }
  }
  return { valid: failures.length === 0, failures };
}