@enigmax/primitives 0.5.0 → 0.7.0

package/src/core/button.ts

@@ -0,0 +1,238 @@
+/**
+ * Button behaviour: what makes it unavailable, and everything that follows from that.
+ *
+ * Disabled, loading and a cooldown are three reasons for the same state, so they collapse
+ * into one `available` the renderer reads, instead of three flags every call site has to
+ * combine correctly. The element to render is reported rather than chosen, because a
+ * framework-agnostic package cannot import next/link.
+ */
+
+/** Which tag the consumer should render. An href makes it a link, and a link is not a button. */
+export type ButtonElement = "button" | "a";
+
+export interface ButtonCooldown {
+    /** How long the button stays unavailable after a press, in ms. */
+    ms: number;
+    /**
+     * Survive a reload under this key. Without it the cooldown is in memory only, and a
+     * refresh is a free retry - which is the whole thing a cooldown exists to prevent.
+     */
+    key?: string;
+    storage?: "local" | "session";
+}
+
+export interface ButtonOptions {
+    /** Turns into an `a`, and a link cannot be `disabled` - only `aria-disabled`. */
+    href?: string;
+    disabled?: boolean;
+    /** Unavailable and busy. Set it yourself, or let an async `onPress` manage it. */
+    loading?: boolean;
+    /** ms, or the full shape for a cooldown that outlives a reload. */
+    cooldown?: number | ButtonCooldown;
+    /**
+     * A single key that presses the button. Ignored while the visitor is typing, and
+     * while any modifier is held, so it never steals a real shortcut.
+     */
+    shortcut?: string;
+    /** Async work flips `loading` for its duration and only then starts the cooldown. */
+    onPress?: (event?: Event) => void | Promise<void>;
+    /** Called whenever anything below changes. */
+    onChange?: (state: ButtonState) => void;
+}
+
+export interface ButtonState {
+    /** The tag to render. */
+    element: ButtonElement;
+    /** Pressable: not disabled, not loading, not cooling down. */
+    available: boolean;
+    loading: boolean;
+    disabled: boolean;
+    /** ms left on the cooldown, 0 when there is none. */
+    cooldown: number;
+    /** The accessible name for the shortcut, when there is one. */
+    shortcut: string | null;
+}
+
+export interface ButtonInstance {
+    readonly state: ButtonState;
+    /** Run the press as if it had been clicked. Ignored while unavailable. */
+    press(event?: Event): Promise<void>;
+    update(options: Partial<ButtonOptions>): void;
+    /** Clear a cooldown early, including its stored entry. */
+    reset(): void;
+    subscribe(listener: (state: ButtonState) => void): () => void;
+    destroy(): void;
+}
+
+const TICK_MS = 100;
+
+function store(cooldown: ButtonCooldown): Storage | null {
+    if (!cooldown.key || typeof window === "undefined") return null;
+    try {
+        const target = cooldown.storage === "local" ? window.localStorage : window.sessionStorage;
+        const probe = "__enigma_probe__";
+        target.setItem(probe, "1");
+        target.removeItem(probe);
+        return target;
+    } catch {
+        // Private-mode Safari exposes the object and throws on write.
+        return null;
+    }
+}
+
+function normalize(cooldown: ButtonOptions["cooldown"]): ButtonCooldown | null {
+    if (cooldown == null) return null;
+    return typeof cooldown === "number" ? { ms: cooldown } : cooldown;
+}
+
+/** A shortcut must not fire while the visitor is writing, or it types into the page. */
+function isTyping(target: EventTarget | null): boolean {
+    const element = target as HTMLElement | null;
+    if (!element) return false;
+    const tag = element.tagName;
+    return tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT" || element.isContentEditable === true;
+}
+
+export function createButton(options: ButtonOptions = {}): ButtonInstance {
+    let opts: ButtonOptions = { ...options };
+    let loading = Boolean(opts.loading);
+    let readyAt = 0;
+    let timer: ReturnType<typeof setInterval> | null = null;
+    let destroyed = false;
+    const listeners = new Set<(state: ButtonState) => void>();
+
+    const storageKey = () => {
+        const cooldown = normalize(opts.cooldown);
+        return cooldown?.key ? `enigma:cooldown:${cooldown.key}` : null;
+    };
+
+    function restore(): void {
+        const cooldown = normalize(opts.cooldown);
+        if (!cooldown) return;
+        const target = store(cooldown);
+        const key = storageKey();
+        if (!target || !key) return;
+        const saved = Number(target.getItem(key));
+        // A stored time in the past is finished, not pending.
+        if (Number.isFinite(saved) && saved > Date.now()) readyAt = saved;
+    }
+
+    function remaining(): number {
+        return Math.max(0, readyAt - Date.now());
+    }
+
+    function snapshot(): ButtonState {
+        const disabled = Boolean(opts.disabled);
+        const cooldown = remaining();
+        return {
+            element: opts.href ? "a" : "button",
+            available: !disabled && !loading && cooldown === 0,
+            loading,
+            disabled,
+            cooldown,
+            shortcut: opts.shortcut ?? null
+        };
+    }
+
+    function emit(): void {
+        const state = snapshot();
+        opts.onChange?.(state);
+        for (const listener of listeners) listener(state);
+    }
+
+    function stopTicking(): void {
+        if (timer === null) return;
+        clearInterval(timer);
+        timer = null;
+    }
+
+    function startTicking(): void {
+        if (timer !== null || remaining() === 0) return;
+        timer = setInterval(() => {
+            if (remaining() > 0) { emit(); return; }
+            stopTicking();
+            emit();
+        }, TICK_MS);
+    }
+
+    function beginCooldown(): void {
+        const cooldown = normalize(opts.cooldown);
+        if (!cooldown || cooldown.ms <= 0) return;
+        readyAt = Date.now() + cooldown.ms;
+        const target = store(cooldown);
+        const key = storageKey();
+        if (target && key) {
+            try { target.setItem(key, String(readyAt)); } catch { /* quota */ }
+        }
+        startTicking();
+    }
+
+    async function press(event?: Event): Promise<void> {
+        if (destroyed || !snapshot().available) return;
+        const result = opts.onPress?.(event);
+
+        if (result instanceof Promise) {
+            loading = true;
+            emit();
+            try {
+                await result;
+            } finally {
+                loading = false;
+                // The cooldown starts when the work FINISHES, not when it was asked for -
+                // otherwise a slow request eats its own cooldown and the button is free
+                // again the moment it returns.
+                beginCooldown();
+                emit();
+            }
+            return;
+        }
+
+        beginCooldown();
+        emit();
+    }
+
+    function onKeyDown(event: KeyboardEvent): void {
+        if (!opts.shortcut || isTyping(event.target)) return;
+        if (event.ctrlKey || event.metaKey || event.altKey || event.shiftKey) return;
+        if (event.key.toLowerCase() !== opts.shortcut.toLowerCase()) return;
+        if (!snapshot().available) return;
+        event.preventDefault();
+        void press(event);
+    }
+
+    if (typeof window !== "undefined") {
+        restore();
+        startTicking();
+        window.addEventListener("keydown", onKeyDown);
+    }
+
+    return {
+        get state() { return snapshot(); },
+        press,
+        update(next: Partial<ButtonOptions>) {
+            const hadCooldown = JSON.stringify(normalize(opts.cooldown));
+            opts = { ...opts, ...next };
+            if (next.loading !== undefined) loading = Boolean(next.loading);
+            if (JSON.stringify(normalize(opts.cooldown)) !== hadCooldown) restore();
+            emit();
+        },
+        reset() {
+            readyAt = 0;
+            stopTicking();
+            const cooldown = normalize(opts.cooldown);
+            const key = storageKey();
+            if (cooldown && key) store(cooldown)?.removeItem(key);
+            emit();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => { listeners.delete(listener); };
+        },
+        destroy() {
+            destroyed = true;
+            stopTicking();
+            listeners.clear();
+            if (typeof window !== "undefined") window.removeEventListener("keydown", onKeyDown);
+        }
+    };
+}

package/src/core/input.ts

@@ -72,9 +72,32 @@ export interface InputInstance {
     destroy(): void;
 }
 
-/** Neutral 1em glyphs that inherit `color`. Replace them with anything. */
-const 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>';
-const 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>';
+/**
+ * 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.
+ */
+export const 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"]
+} as const;
+
+/** The same shapes as a standalone SVG string, for the DOM renderer below. */
+export function iconMarkup(paths: readonly string[]): string {
+    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>`;
+}
+
+const EYE = iconMarkup(INPUT_ICON_PATHS.eye);
+const EYE_OFF = iconMarkup(INPUT_ICON_PATHS.eyeOff);
 
 function resolve<T>(value: T | ((state: InputActionState) => T), state: InputActionState): T {
     return typeof value === "function" ? (value as (state: InputActionState) => T)(state) : value;

package/src/core/password.ts

@@ -0,0 +1,252 @@
+/**
+ * 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. */
+export interface PasswordAlphabet {
+    lowercase?: boolean;
+    uppercase?: boolean;
+    digits?: boolean;
+    symbols?: boolean;
+}
+
+export 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;
+}
+
+const LOWERCASE = "abcdefghijklmnopqrstuvwxyz";
+const UPPERCASE = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+const DIGITS = "0123456789";
+/**
+ * No quotes, backslash, backtick or space: those are the characters that get mangled on the
+ * way through a shell, a CSV, a JSON blob written by hand, or a copy out of a terminal.
+ */
+const SYMBOLS = "!@#$%^&*()-_=+[]{};:,.?";
+const AMBIGUOUS = "Il1O0";
+
+/**
+ * Uniform in [0, bound), by rejection.
+ *
+ * `value % bound` is the version everyone writes and it is biased: 2^32 is not a multiple
+ * of most bounds, so the first few characters of the alphabet come up slightly more often.
+ * On a password that is a real, if small, loss of entropy, and it costs one comparison to
+ * avoid.
+ */
+function randomIndex(bound: number): number {
+    const random = globalThis.crypto?.getRandomValues?.bind(globalThis.crypto);
+    if (!random) {
+        // Never Math.random. A generator that silently produces predictable passwords is
+        // worse than one that refuses: nothing downstream can tell the difference.
+        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: number;
+    do {
+        random(buffer);
+        value = buffer[0];
+    } while (value >= limit);
+    return value % bound;
+}
+
+function pick(alphabet: string): string {
+    return alphabet[randomIndex(alphabet.length)];
+}
+
+function classes(options: GeneratePasswordOptions): string[] {
+    const { lowercase = true, uppercase = true, digits = true, symbols = true, excludeAmbiguous = false, exclude = "" } = options;
+    const banned = new Set([...(excludeAmbiguous ? AMBIGUOUS : ""), ...exclude]);
+    const clean = (source: string): string => [...source].filter((character) => !banned.has(character)).join("");
+
+    return [
+        lowercase ? clean(LOWERCASE) : "",
+        uppercase ? clean(UPPERCASE) : "",
+        digits ? clean(DIGITS) : "",
+        symbols ? clean(SYMBOLS) : ""
+    ].filter(Boolean);
+}
+
+/** Fisher-Yates, with the same unbiased source. A biased shuffle undoes a fair draw. */
+function shuffle(characters: string[]): string[] {
+    for (let index = characters.length - 1; index > 0; index--) {
+        const swap = randomIndex(index + 1);
+        [characters[index], characters[swap]] = [characters[swap], characters[index]];
+    }
+    return characters;
+}
+
+/**
+ * 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).
+ */
+export function generatePassword(options: GeneratePasswordOptions = {}): string {
+    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("");
+    // One from each class first, the rest uniform, then shuffled - so the guarantee does
+    // not put the digit in a predictable place.
+    const required = requireEachClass ? pools.map(pick) : [];
+    const rest = Array.from({ length: length - required.length }, () => pick(everything));
+    return shuffle([...required, ...rest]).join("");
+}
+
+export type PasswordScore = 0 | 1 | 2 | 3 | 4;
+
+export 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;
+}
+
+export 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[];
+}
+
+/**
+ * The forty or so passwords that turn up at the top of every breach corpus. Not a
+ * dictionary: it is here to catch `password1`, not to be exhaustive. For real coverage
+ * either replace the estimator with zxcvbn, or check the breach corpus - which is what
+ * `checkPasswordBreach` in @enigmax/utils is for.
+ */
+const COMMON = 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"
+]);
+
+const SEQUENCES = ["abcdefghijklmnopqrstuvwxyz", "0123456789", "qwertyuiop", "asdfghjkl", "zxcvbnm"];
+
+/** The pool an attacker would have to search, from the classes actually used. */
+function poolSize(password: string): number {
+    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;
+}
+
+/** Longest run of the same character, and longest run along a keyboard or alphabet line. */
+function longestRun(password: string): number {
+    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: string): number {
+    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;
+}
+
+/** Strip the decoration people add to satisfy a policy: Password1! is password. */
+function core(password: string): string {
+    return password.toLowerCase().replace(/^[^a-z]+/, "").replace(/[^a-z]+$/, "").replace(/[0!@$]/g, (character) => ({ "0": "o", "!": "i", "@": "a", "$": "s" })[character] ?? character);
+}
+
+/**
+ * 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.
+ */
+export function estimatePasswordStrength(password: string, options: EstimateOptions = {}): PasswordStrengthReport {
+    if (!password) return { score: 0, bits: 0, warnings: [], empty: true };
+
+    const warnings: string[] = [];
+    let bits = password.length * Math.log2(poolSize(password));
+
+    const stripped = core(password);
+    if (COMMON.has(password.toLowerCase()) || COMMON.has(stripped)) {
+        // A password on every list has no entropy at all, whatever its shape.
+        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();
+        // A three-letter name matches half the passwords in the world; ignore short ones.
+        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: PasswordScore = bits < 28 ? 0 : bits < 40 ? 1 : bits < 60 ? 2 : bits < 80 ? 3 : 4;
+    return { score, bits, warnings, empty: false };
+}

package/src/index.ts

@@ -1,3 +1,14 @@
 export { createMarquee, type MarqueeOptions, type MarqueeInstance, type MarqueeHover } from "@/core/marquee";
 export { createInput, type InputOptions, type InputInstance, type InputAction, type InputIcon, type InputActionState } from "@/core/input";
 export { createSearch, type SearchOptions, type SearchInstance, type SearchMatch, type FuseConstructor, type FuseLike } from "@/core/search";
+export { createButton, type ButtonOptions, type ButtonInstance, type ButtonState, type ButtonElement, type ButtonCooldown } from "@/core/button";
+export { INPUT_ICON_PATHS, iconMarkup } from "@/core/input";
+export {
+    generatePassword,
+    estimatePasswordStrength,
+    type GeneratePasswordOptions,
+    type PasswordAlphabet,
+    type EstimateOptions,
+    type PasswordStrengthReport,
+    type PasswordScore
+} from "@/core/password";

package/src/react/index.ts

@@ -1,6 +1,28 @@
+"use client";
+
 export { useMarquee, type UseMarqueeResult } from "@/react/use-marquee";
 export { type MarqueeOptions, type MarqueeInstance, type MarqueeHover } from "@/core/marquee";
 export { useInput, type UseInputResult } from "@/react/use-input";
 export { useSearch, type UseSearchResult } from "@/react/use-search";
 export { type InputOptions, type InputAction, type InputIcon } from "@/core/input";
 export { type SearchOptions, type SearchMatch, type FuseConstructor } from "@/core/search";
+export { useButton, type UseButtonResult } from "@/react/use-button";
+export { type ButtonOptions, type ButtonState } from "@/core/button";
+export {
+    Input,
+    PasswordStrength,
+    type InputProps,
+    type PasswordStrengthProps,
+    type FieldAction,
+    type BreachChecker,
+    type BreachState,
+    type BreachStatus
+} from "@/react/input";
+export {
+    generatePassword,
+    estimatePasswordStrength,
+    type GeneratePasswordOptions,
+    type EstimateOptions,
+    type PasswordStrengthReport,
+    type PasswordScore
+} from "@/core/password";