@enigmax/primitives 0.6.0 → 0.7.0

package/dist/{chunk-WCB7V7XO.js → chunk-42Y7OOJM.js}

@@ -293,8 +293,21 @@ function createMarquee(lane, track, options = {}) {
 }
 
 // src/core/input.ts
-var EYE = '<svg viewBox="0 0 24 24" width="1em" height="1em" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M2 12s3.5-7 10-7 10 7 10 7-3.5 7-10 7-10-7-10-7Z"/><circle cx="12" cy="12" r="3"/></svg>';
-var EYE_OFF = '<svg viewBox="0 0 24 24" width="1em" height="1em" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M10.6 5.2A9.8 9.8 0 0 1 12 5c6.5 0 10 7 10 7a17.6 17.6 0 0 1-3.2 4.2M6.2 6.2A17.7 17.7 0 0 0 2 12s3.5 7 10 7a9.6 9.6 0 0 0 4.2-.9"/><path d="m2 2 20 20"/><path d="M9.9 9.9a3 3 0 0 0 4.2 4.2"/></svg>';
+var INPUT_ICON_PATHS = {
+  eye: ["M2 12s3.5-7 10-7 10 7 10 7-3.5 7-10 7-10-7-10-7Z", "M15 12a3 3 0 1 1-6 0 3 3 0 0 1 6 0Z"],
+  eyeOff: [
+    "M10.6 5.2A9.8 9.8 0 0 1 12 5c6.5 0 10 7 10 7a17.6 17.6 0 0 1-3.2 4.2M6.2 6.2A17.7 17.7 0 0 0 2 12s3.5 7 10 7a9.6 9.6 0 0 0 4.2-.9",
+    "m2 2 20 20",
+    "M9.9 9.9a3 3 0 0 0 4.2 4.2"
+  ],
+  generate: ["m12 3 1.9 4.6L18.5 9.5 13.9 11.4 12 16l-1.9-4.6L5.5 9.5l4.6-1.9Z", "M19 15l.8 2.2 2.2.8-2.2.8-.8 2.2-.8-2.2-2.2-.8 2.2-.8Z"]
+};
+function iconMarkup(paths) {
+  const body = paths.map((path) => `<path d="${path}"/>`).join("");
+  return `<svg viewBox="0 0 24 24" width="1em" height="1em" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${body}</svg>`;
+}
+var EYE = iconMarkup(INPUT_ICON_PATHS.eye);
+var EYE_OFF = iconMarkup(INPUT_ICON_PATHS.eyeOff);
 function resolve(value, state) {
   return typeof value === "function" ? value(state) : value;
 }
@@ -637,4 +650,171 @@ function createButton(options = {}) {
   };
 }
 
-export { createButton, createInput, createMarquee };
+// src/core/password.ts
+var LOWERCASE = "abcdefghijklmnopqrstuvwxyz";
+var UPPERCASE = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+var DIGITS = "0123456789";
+var SYMBOLS = "!@#$%^&*()-_=+[]{};:,.?";
+var AMBIGUOUS = "Il1O0";
+function randomIndex(bound) {
+  const random = globalThis.crypto?.getRandomValues?.bind(globalThis.crypto);
+  if (!random) {
+    throw new Error("Generating a password needs crypto.getRandomValues, which browsers only expose over HTTPS (or on localhost).");
+  }
+  const limit = Math.floor(2 ** 32 / bound) * bound;
+  const buffer = new Uint32Array(1);
+  let value;
+  do {
+    random(buffer);
+    value = buffer[0];
+  } while (value >= limit);
+  return value % bound;
+}
+function pick(alphabet) {
+  return alphabet[randomIndex(alphabet.length)];
+}
+function classes(options) {
+  const { lowercase = true, uppercase = true, digits = true, symbols = true, excludeAmbiguous = false, exclude = "" } = options;
+  const banned = /* @__PURE__ */ new Set([...excludeAmbiguous ? AMBIGUOUS : "", ...exclude]);
+  const clean = (source) => [...source].filter((character) => !banned.has(character)).join("");
+  return [
+    lowercase ? clean(LOWERCASE) : "",
+    uppercase ? clean(UPPERCASE) : "",
+    digits ? clean(DIGITS) : "",
+    symbols ? clean(SYMBOLS) : ""
+  ].filter(Boolean);
+}
+function shuffle(characters) {
+  for (let index = characters.length - 1; index > 0; index--) {
+    const swap = randomIndex(index + 1);
+    [characters[index], characters[swap]] = [characters[swap], characters[index]];
+  }
+  return characters;
+}
+function generatePassword(options = {}) {
+  const { length = 20, requireEachClass = true } = options;
+  const pools = classes(options);
+  if (!pools.length) throw new Error("generatePassword: every character class was excluded.");
+  if (length < 1) throw new Error("generatePassword: length must be at least 1.");
+  if (requireEachClass && length < pools.length) {
+    throw new Error(`generatePassword: length ${length} cannot hold one character from each of the ${pools.length} classes requested.`);
+  }
+  const everything = pools.join("");
+  const required = requireEachClass ? pools.map(pick) : [];
+  const rest = Array.from({ length: length - required.length }, () => pick(everything));
+  return shuffle([...required, ...rest]).join("");
+}
+var COMMON = /* @__PURE__ */ new Set([
+  "password",
+  "passwd",
+  "123456",
+  "12345678",
+  "123456789",
+  "1234567890",
+  "qwerty",
+  "qwertyuiop",
+  "abc123",
+  "111111",
+  "123123",
+  "admin",
+  "letmein",
+  "welcome",
+  "monkey",
+  "dragon",
+  "sunshine",
+  "iloveyou",
+  "princess",
+  "football",
+  "baseball",
+  "master",
+  "shadow",
+  "superman",
+  "batman",
+  "trustno1",
+  "hello",
+  "freedom",
+  "whatever",
+  "starwars",
+  "changeme",
+  "secret",
+  "login",
+  "root",
+  "toor",
+  "test",
+  "guest",
+  "azerty",
+  "1q2w3e4r",
+  "zaq12wsx"
+]);
+var SEQUENCES = ["abcdefghijklmnopqrstuvwxyz", "0123456789", "qwertyuiop", "asdfghjkl", "zxcvbnm"];
+function poolSize(password) {
+  let size = 0;
+  if (/[a-z]/.test(password)) size += 26;
+  if (/[A-Z]/.test(password)) size += 26;
+  if (/\d/.test(password)) size += 10;
+  if (/[^\w\s]|_/.test(password)) size += SYMBOLS.length;
+  if (/\s/.test(password)) size += 1;
+  return size || 1;
+}
+function longestRun(password) {
+  let longest = 1, run = 1;
+  for (let index = 1; index < password.length; index++) {
+    run = password[index] === password[index - 1] ? run + 1 : 1;
+    longest = Math.max(longest, run);
+  }
+  return longest;
+}
+function longestSequence(password) {
+  const lower = password.toLowerCase();
+  let longest = 0;
+  for (const line of SEQUENCES) {
+    const reversed = [...line].reverse().join("");
+    for (const source of [line, reversed]) {
+      for (let start = 0; start < source.length; start++) {
+        for (let end = source.length; end > start + longest; end--) {
+          if (lower.includes(source.slice(start, end))) {
+            longest = Math.max(longest, end - start);
+            break;
+          }
+        }
+      }
+    }
+  }
+  return longest;
+}
+function core(password) {
+  return password.toLowerCase().replace(/^[^a-z]+/, "").replace(/[^a-z]+$/, "").replace(/[0!@$]/g, (character) => ({ "0": "o", "!": "i", "@": "a", "$": "s" })[character] ?? character);
+}
+function estimatePasswordStrength(password, options = {}) {
+  if (!password) return { score: 0, bits: 0, warnings: [], empty: true };
+  const warnings = [];
+  let bits = password.length * Math.log2(poolSize(password));
+  const stripped = core(password);
+  if (COMMON.has(password.toLowerCase()) || COMMON.has(stripped)) {
+    bits = Math.min(bits, 8);
+    warnings.push("This is one of the most common passwords there is.");
+  }
+  for (const input of options.userInputs ?? []) {
+    const needle = input.trim().toLowerCase();
+    if (needle.length < 4 || !password.toLowerCase().includes(needle)) continue;
+    bits = Math.min(bits, 16);
+    warnings.push("It contains something you already typed on this form.");
+    break;
+  }
+  const run = longestRun(password);
+  if (run >= 3) {
+    bits -= (run - 2) * Math.log2(poolSize(password));
+    warnings.push("A character repeats several times in a row.");
+  }
+  const sequence = longestSequence(password);
+  if (sequence >= 4) {
+    bits -= sequence * Math.log2(poolSize(password)) * 0.75;
+    warnings.push("Part of it runs straight along the keyboard or the alphabet.");
+  }
+  if (password.length < 8) warnings.push("Short passwords fall to a brute force whatever they contain.");
+  bits = Math.max(0, Math.round(bits));
+  const score = bits < 28 ? 0 : bits < 40 ? 1 : bits < 60 ? 2 : bits < 80 ? 3 : 4;
+  return { score, bits, warnings, empty: false };
+}
+
+export { INPUT_ICON_PATHS, createButton, createInput, createMarquee, estimatePasswordStrength, generatePassword, iconMarkup };

package/dist/index.d.ts

@@ -155,6 +155,21 @@ interface InputInstance {
     update(options: Partial<InputOptions>): void;
     destroy(): void;
 }
+/**
+ * The built-in glyphs, as path data.
+ *
+ * Path data rather than markup because there are two renderers: this file writes an SVG
+ * string into a button it created, and the React component builds elements. Keeping the
+ * shapes here means one definition, and a theme that replaces an icon replaces it in both.
+ * Everything is stroked with `currentColor` at 1em, so an icon inherits the field's text.
+ */
+declare const INPUT_ICON_PATHS: {
+    readonly eye: readonly ["M2 12s3.5-7 10-7 10 7 10 7-3.5 7-10 7-10-7-10-7Z", "M15 12a3 3 0 1 1-6 0 3 3 0 0 1 6 0Z"];
+    readonly eyeOff: readonly ["M10.6 5.2A9.8 9.8 0 0 1 12 5c6.5 0 10 7 10 7a17.6 17.6 0 0 1-3.2 4.2M6.2 6.2A17.7 17.7 0 0 0 2 12s3.5 7 10 7a9.6 9.6 0 0 0 4.2-.9", "m2 2 20 20", "M9.9 9.9a3 3 0 0 0 4.2 4.2"];
+    readonly generate: readonly ["m12 3 1.9 4.6L18.5 9.5 13.9 11.4 12 16l-1.9-4.6L5.5 9.5l4.6-1.9Z", "M19 15l.8 2.2 2.2.8-2.2.8-.8 2.2-.8-2.2-2.2-.8 2.2-.8Z"];
+};
+/** The same shapes as a standalone SVG string, for the DOM renderer below. */
+declare function iconMarkup(paths: readonly string[]): string;
 /**
  * Wire a field's in-field actions.
  *
@@ -224,4 +239,74 @@ interface ButtonInstance {
 }
 declare function createButton(options?: ButtonOptions): ButtonInstance;
 
-export { type ButtonCooldown, type ButtonElement, type ButtonInstance, type ButtonOptions, type ButtonState, type InputAction, type InputActionState, type InputIcon, type InputInstance, type InputOptions, type MarqueeHover, type MarqueeInstance, type MarqueeOptions, createButton, createInput, createMarquee };
+/**
+ * Making a password, and judging one.
+ *
+ * Both are opt-in. A sign-in form wants neither: offering to generate a password where one
+ * already exists is noise, and scoring one the visitor cannot change is worse. They belong
+ * on a registration form and a change-password form, which is where an agent should switch
+ * them on.
+ */
+/** Character classes a generated password can draw from. */
+interface PasswordAlphabet {
+    lowercase?: boolean;
+    uppercase?: boolean;
+    digits?: boolean;
+    symbols?: boolean;
+}
+interface GeneratePasswordOptions extends PasswordAlphabet {
+    /** Default 20. Long beats clever: length is the only term that scales. */
+    length?: number;
+    /**
+     * Drop the characters that are read wrong off a screen or off paper - I l 1 O 0.
+     * Worth it when the password will be typed by hand, not worth the entropy otherwise.
+     */
+    excludeAmbiguous?: boolean;
+    /** Characters to remove from every class, e.g. ones your backend rejects. */
+    exclude?: string;
+    /**
+     * Guarantee at least one character from every class asked for. Most password policies
+     * demand it; it costs a little entropy, because it removes every password that happens
+     * to lack one.
+     */
+    requireEachClass?: boolean;
+}
+/**
+ * A random password from the classes asked for.
+ *
+ * @throws when the runtime has no CSPRNG, or when the options ask for something impossible
+ *         (every class excluded, or a length too short to hold one of each).
+ */
+declare function generatePassword(options?: GeneratePasswordOptions): string;
+type PasswordScore = 0 | 1 | 2 | 3 | 4;
+interface PasswordStrengthReport {
+    /** 0 worst, 4 best. What the bars under the field render. */
+    score: PasswordScore;
+    /** Estimated bits of entropy after the penalties below. */
+    bits: number;
+    /**
+     * Why it scored what it scored, worst first. Show the first one; showing all of them
+     * turns a hint into a lecture.
+     */
+    warnings: string[];
+    /** Empty field. Render nothing rather than a zero score, which reads as a failure. */
+    empty: boolean;
+}
+interface EstimateOptions {
+    /**
+     * Values the visitor has already typed elsewhere - email, name, company. A password
+     * containing one of them is guessable by anyone who has the sign-up form in front of
+     * them, and no character-class rule catches it.
+     */
+    userInputs?: string[];
+}
+/**
+ * Score a password.
+ *
+ * The bits are an estimate and the bands are a convention, not a measurement - they exist
+ * to move a bar, not to certify anything. Swap this out for zxcvbn where the number has to
+ * mean something, and check the breach corpus for the cases no estimator can see.
+ */
+declare function estimatePasswordStrength(password: string, options?: EstimateOptions): PasswordStrengthReport;
+
+export { type ButtonCooldown, type ButtonElement, type ButtonInstance, type ButtonOptions, type ButtonState, type EstimateOptions, type GeneratePasswordOptions, INPUT_ICON_PATHS, type InputAction, type InputActionState, type InputIcon, type InputInstance, type InputOptions, type MarqueeHover, type MarqueeInstance, type MarqueeOptions, type PasswordAlphabet, type PasswordScore, type PasswordStrengthReport, createButton, createInput, createMarquee, estimatePasswordStrength, generatePassword, iconMarkup };

package/dist/index.js

@@ -1,2 +1,2 @@
-export { createButton, createInput, createMarquee } from './chunk-WCB7V7XO.js';
+export { INPUT_ICON_PATHS, createButton, createInput, createMarquee, estimatePasswordStrength, generatePassword, iconMarkup } from './chunk-42Y7OOJM.js';
 export { createSearch } from './chunk-UZFEEFMF.js';

package/dist/react/index.d.ts

@@ -1,6 +1,7 @@
-import { RefObject } from 'react';
-import { MarqueeOptions, InputOptions, ButtonState, ButtonOptions } from '../index.js';
-export { InputAction, InputIcon, MarqueeHover, MarqueeInstance } from '../index.js';
+import * as react from 'react';
+import { RefObject, ReactNode, ComponentPropsWithoutRef } from 'react';
+import { MarqueeOptions, InputOptions, ButtonState, ButtonOptions, GeneratePasswordOptions, EstimateOptions, PasswordStrengthReport } from '../index.js';
+export { InputAction, InputIcon, MarqueeHover, MarqueeInstance, PasswordScore, estimatePasswordStrength, generatePassword } from '../index.js';
 import { b as SearchMatch, c as SearchOptions } from '../search-CsO3L1Lw.js';
 export { F as FuseConstructor } from '../search-CsO3L1Lw.js';
 
@@ -128,4 +129,114 @@ interface UseButtonResult extends ButtonState {
  */
 declare function useButton(options?: ButtonOptions): UseButtonResult;
 
-export { ButtonOptions, ButtonState, InputOptions, MarqueeOptions, SearchMatch, SearchOptions, type UseButtonResult, type UseInputResult, type UseMarqueeResult, type UseSearchResult, useButton, useInput, useMarquee, useSearch };
+/** An extra button inside the field. The built-ins are the same shape. */
+interface FieldAction {
+    /** Stable id. Lands on `data-enigma-input-action`, and replaces a built-in of the same name. */
+    name: string;
+    /** Accessible name. Becomes `aria-label` and `title`. */
+    label: string;
+    icon: ReactNode;
+    onSelect: () => void;
+    /** Renders `aria-pressed`. Omit for actions that are not toggles. */
+    pressed?: boolean;
+    /** Default true. A false action is not rendered at all. */
+    visible?: boolean;
+}
+type BreachStatus = "idle" | "checking" | "safe" | "breached" | "error";
+interface BreachState {
+    status: BreachStatus;
+    /** How many breaches the password appears in. 0 unless `status` is "breached". */
+    count: number;
+    /** Whatever the checker threw. The form decides whether that is worth showing. */
+    error: unknown;
+}
+type BreachChecker = (password: string, options: {
+    signal: AbortSignal;
+}) => Promise<{
+    breached: boolean;
+    count: number;
+}>;
+interface InputProps extends Omit<ComponentPropsWithoutRef<"input">, "children"> {
+    /** The reveal toggle. Defaults to on for `type="password"` and off for everything else. */
+    reveal?: boolean;
+    revealLabels?: {
+        show?: string;
+        hide?: string;
+    };
+    /** Offer to generate a password. `true` for the defaults, or the generator's options. */
+    generate?: boolean | GeneratePasswordOptions;
+    generateLabel?: string;
+    /** Show what was generated. On by default - a password nobody can read is not usable. */
+    revealOnGenerate?: boolean;
+    /**
+     * Also copy it to the clipboard. OFF by default and worth leaving off: the clipboard is
+     * shared with every other app on the machine and is not cleared.
+     */
+    copyOnGenerate?: boolean;
+    onGenerate?: (password: string) => void;
+    /** Extra buttons, or a replacement for `reveal` / `generate` by name. */
+    actions?: FieldAction[];
+    /** Which end the buttons sit at. Position them yourself; this only orders the markup. */
+    position?: "start" | "end";
+    /** Score the password as it is typed, and render the meter under the field. */
+    strength?: boolean | EstimateOptions;
+    onStrengthChange?: (report: PasswordStrengthReport) => void;
+    /**
+     * Check the password against a breach corpus - pass `checkPasswordBreach` from
+     * @enigmax/utils, or your own. It is a prop rather than a built-in because it makes a
+     * network request, and that is not a decision a field should take on its own.
+     */
+    breach?: BreachChecker;
+    /** Quiet time before a check fires, in ms. Default 500. */
+    breachDelay?: number;
+    onBreachChange?: (state: BreachState) => void;
+    /** Props for the element wrapping the field, its buttons and the meter. */
+    wrapperProps?: ComponentPropsWithoutRef<"div">;
+    /** Props for the row holding the field and its buttons - this is what you position. */
+    fieldProps?: ComponentPropsWithoutRef<"div">;
+    /**
+     * Classes for the parts you cannot reach with a ref, which is what Tailwind needs.
+     * `className` still goes to the `<input>` itself, where you would expect it.
+     */
+    classNames?: {
+        actions?: string;
+        action?: string;
+        strength?: PasswordStrengthProps["classNames"];
+    };
+    /** Rendered inside the wrapper, after the meter. Your error message goes here. */
+    children?: ReactNode;
+}
+declare const Input: react.ForwardRefExoticComponent<InputProps & react.RefAttributes<HTMLInputElement>>;
+interface PasswordStrengthProps extends Omit<ComponentPropsWithoutRef<"div">, "children"> {
+    /** The password to score. Ignored when `report` is given. */
+    value?: string;
+    /** A report you already have, e.g. from `<Input onStrengthChange>`. */
+    report?: PasswordStrengthReport;
+    userInputs?: string[];
+    /** Bars to draw. Five, so each score has one of its own. */
+    segments?: number;
+    /** Your own wording, worst first. */
+    labels?: readonly string[];
+    /** Show the top warning under the bars. On by default; it is the useful half. */
+    showWarning?: boolean;
+    /**
+     * Classes for the inner parts. The score is on the ROOT, so a segment colours itself
+     * with a group variant - `group-data-[score=0]/strength:bg-red-600` and so on.
+     */
+    classNames?: {
+        track?: string;
+        segment?: string;
+        label?: string;
+        warning?: string;
+    };
+}
+/**
+ * The bars under a password field.
+ *
+ * Structure and state only - `data-score` on the root and `data-filled` per segment are
+ * where the colours attach. The component picks no colours, because red-through-green is a
+ * palette decision and this package does not own one.
+ */
+declare function PasswordStrength({ value, report, userInputs, segments, labels, showWarning, classNames, ...props }: PasswordStrengthProps): ReactNode;
+
+export { type BreachChecker, type BreachState, type BreachStatus, ButtonOptions, ButtonState, EstimateOptions, type FieldAction, GeneratePasswordOptions, Input, InputOptions, type InputProps, MarqueeOptions, PasswordStrength, type PasswordStrengthProps, PasswordStrengthReport, SearchMatch, SearchOptions, type UseButtonResult, type UseInputResult, type UseMarqueeResult, type UseSearchResult, useButton, useInput, useMarquee, useSearch };