@visns-studio/visns-components 6.6.4 → 6.15.0

package/src/components/vault/vaultHelpers.js

@@ -0,0 +1,547 @@
+/**
+ * Pure helpers for the vault.
+ *
+ * No React and no DOM beyond `globalThis.crypto`, so `node --test` can import
+ * this directly (tests/vault.test.mjs). Everything the vault components do
+ * that can be reasoned about without a browser lives here: parsing a 2FA
+ * secret, generating and scoring a password, formatting a code, and matching
+ * the keyboard shortcut.
+ */
+
+/* -------------------------------------------------------------------------
+ * 2FA secrets
+ * ---------------------------------------------------------------------- */
+
+/** RFC 4648 base32, which is the alphabet every authenticator app speaks. */
+const BASE32_ALPHABET = /^[A-Z2-7]+$/;
+
+/** What an `otpauth://` URI leaves out, and what a bare secret always means. */
+export const OTP_DEFAULTS = Object.freeze({
+    digits: 6,
+    period: 30,
+    algorithm: 'SHA1',
+});
+
+const OTP_ALGORITHMS = ['SHA1', 'SHA256', 'SHA512'];
+
+/** The one message a user ever sees for an unreadable secret. */
+export const OTP_PARSE_ERROR =
+    "That doesn't look like a 2FA secret or otpauth link.";
+
+/**
+ * Strip the decoration authenticator apps and password managers add when they
+ * print a secret: spaces, hyphens, underscores, and base32's `=` padding.
+ * Case is not meaningful in base32, so lowercase input is simply uppercased.
+ */
+export const cleanBase32 = (value) =>
+    String(value ?? '')
+        .replace(/[\s\-_]/g, '')
+        .replace(/=+$/, '')
+        .toUpperCase();
+
+/**
+ * Is this a base32 secret, once the decoration is stripped?
+ *
+ * Format only — length is the backend's business, and inventing a minimum
+ * here would reject secrets that work perfectly well in an authenticator app.
+ */
+export const isValidBase32 = (value) => {
+    const cleaned = cleanBase32(value);
+
+    return cleaned.length > 0 && BASE32_ALPHABET.test(cleaned);
+};
+
+/** A query value that is a positive integer inside `[min, max]`, or null. */
+const boundedInt = (raw, min, max) => {
+    if (raw === null || raw === undefined || raw === '') return null;
+
+    const parsed = Number(raw);
+
+    if (!Number.isInteger(parsed) || parsed < min || parsed > max) return null;
+
+    return parsed;
+};
+
+/**
+ * Read a 2FA secret out of whatever the user pasted.
+ *
+ * Accepts either a full `otpauth://totp/...` URI — the thing a QR code
+ * actually encodes, and what every "copy setup link" button hands over — or a
+ * bare base32 secret. Both come back in the same shape, so the caller never
+ * has to care which it was handed:
+ *
+ *     { secret, digits, period, algorithm, issuer, account }
+ *
+ * Parameters absent from the URI take the values in `OTP_DEFAULTS`, which are
+ * also what a bare secret means. Anything unreadable throws `OTP_PARSE_ERROR`
+ * — a sentence, because it is shown to the user verbatim.
+ *
+ * Note the URI is parsed by hand rather than through `new URL()`: `otpauth:`
+ * is a non-special scheme, so the label lands in `host` or `pathname`
+ * depending on the engine, and hosts get lowercased. The issuer is part of
+ * that label and its case matters.
+ */
+export const parseOtpAuthUri = (input) => {
+    const raw = String(input ?? '').trim();
+
+    if (raw === '') throw new Error(OTP_PARSE_ERROR);
+
+    if (!/^otpauth:\/\//i.test(raw)) {
+        // Not a link, so it has to be a bare secret.
+        if (!isValidBase32(raw)) throw new Error(OTP_PARSE_ERROR);
+
+        return {
+            secret: cleanBase32(raw),
+            ...OTP_DEFAULTS,
+            issuer: '',
+            account: '',
+        };
+    }
+
+    const withoutScheme = raw.slice(raw.indexOf('//') + 2);
+    const queryAt = withoutScheme.indexOf('?');
+    const path = queryAt === -1 ? withoutScheme : withoutScheme.slice(0, queryAt);
+    const query = queryAt === -1 ? '' : withoutScheme.slice(queryAt + 1);
+
+    const [type, ...labelParts] = path.split('/');
+
+    // `hotp` is counter-based: there is no clock to read, so a code cannot be
+    // shown on demand. Saying so beats a generic parse failure.
+    if (String(type).toLowerCase() !== 'totp') {
+        throw new Error('Only time-based (TOTP) 2FA links are supported.');
+    }
+
+    const params = new URLSearchParams(query);
+    const secretParam = params.get('secret');
+
+    if (!secretParam || !isValidBase32(secretParam)) {
+        throw new Error(OTP_PARSE_ERROR);
+    }
+
+    // The label is `Issuer:account`, percent-encoded — `ACME%20Co:john%40x.com`.
+    let label = '';
+    try {
+        label = decodeURIComponent(labelParts.join('/'));
+    } catch {
+        label = labelParts.join('/');
+    }
+
+    const separator = label.indexOf(':');
+    let issuer = separator === -1 ? '' : label.slice(0, separator).trim();
+    const account =
+        separator === -1 ? label.trim() : label.slice(separator + 1).trim();
+
+    // The explicit `issuer` parameter is authoritative when both are present.
+    const issuerParam = params.get('issuer');
+    if (issuerParam) issuer = issuerParam.trim();
+
+    const algorithmParam = String(params.get('algorithm') || '').toUpperCase();
+
+    return {
+        secret: cleanBase32(secretParam),
+        // An out-of-range or non-numeric parameter falls back to the default
+        // rather than throwing: the secret is the part that must be right.
+        digits: boundedInt(params.get('digits'), 6, 10) ?? OTP_DEFAULTS.digits,
+        period: boundedInt(params.get('period'), 1, 300) ?? OTP_DEFAULTS.period,
+        algorithm: OTP_ALGORITHMS.includes(algorithmParam)
+            ? algorithmParam
+            : OTP_DEFAULTS.algorithm,
+        issuer,
+        account,
+    };
+};
+
+/** `6 digits · 30 s · SHA1` — the live feedback line under the secret field. */
+export const describeOtpConfig = (parsed) => {
+    if (!parsed) return '';
+
+    return `${parsed.digits} digits · ${parsed.period} s · ${parsed.algorithm}`;
+};
+
+/* -------------------------------------------------------------------------
+ * Password generation
+ * ---------------------------------------------------------------------- */
+
+const POOLS = {
+    lowercase: 'abcdefghijklmnopqrstuvwxyz',
+    uppercase: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ',
+    digits: '0123456789',
+    symbols: '!@#$%^&*()-_=+[]{};:,.?',
+};
+
+/**
+ * Characters that are read wrong when a password is dictated over the phone or
+ * copied off a screen. Excluded by default, which is what `ambiguous: false`
+ * means.
+ */
+const AMBIGUOUS = new Set(['I', 'l', '1', 'O', '0', 'o', 'S', '5', 'B', '8']);
+
+const getCrypto = () => {
+    const c = globalThis.crypto;
+
+    if (!c || typeof c.getRandomValues !== 'function') {
+        // Deliberately fatal. `Math.random` is seeded, predictable and utterly
+        // unfit to generate a credential — a silent fallback here would hand
+        // out guessable passwords that look exactly like good ones.
+        throw new Error(
+            'A secure random source is unavailable, so no password was generated.'
+        );
+    }
+
+    return c;
+};
+
+/**
+ * A uniform integer in `[0, max)`.
+ *
+ * Rejection sampling rather than `% max`, which skews towards the low end of
+ * the pool whenever the pool size does not divide 2^32 — a real, if small,
+ * bias in every character of every password.
+ */
+const randomBelow = (max) => {
+    const crypto = getCrypto();
+    const limit = Math.floor(0xffffffff / max) * max;
+    const buffer = new Uint32Array(1);
+
+    for (;;) {
+        crypto.getRandomValues(buffer);
+        if (buffer[0] < limit) return buffer[0] % max;
+    }
+};
+
+/** Fisher-Yates, drawing from the same source as the characters themselves. */
+const shuffle = (items) => {
+    const out = items.slice();
+
+    for (let i = out.length - 1; i > 0; i -= 1) {
+        const j = randomBelow(i + 1);
+        [out[i], out[j]] = [out[j], out[i]];
+    }
+
+    return out;
+};
+
+const MIN_LENGTH = 8;
+const MAX_LENGTH = 128;
+
+/**
+ * Generate a password.
+ *
+ * Lowercase is always in play; the other three classes are opt-out. The result
+ * is guaranteed to contain at least one character from every enabled class —
+ * a password that happens to contain no digit will still be rejected by the
+ * next system that demands one, and "generate again until it looks right" is
+ * not a workflow.
+ *
+ * `ambiguous: false` (the default) excludes look-alike characters.
+ */
+export const generatePassword = ({
+    length = 20,
+    symbols = true,
+    digits = true,
+    uppercase = true,
+    ambiguous = false,
+} = {}) => {
+    const enabled = ['lowercase'];
+    if (uppercase) enabled.push('uppercase');
+    if (digits) enabled.push('digits');
+    if (symbols) enabled.push('symbols');
+
+    const filter = (pool) =>
+        ambiguous
+            ? pool.split('')
+            : pool.split('').filter((ch) => !AMBIGUOUS.has(ch));
+
+    const pools = enabled
+        .map((name) => filter(POOLS[name]))
+        .filter((pool) => pool.length > 0);
+
+    // Clamped, not thrown: the slider cannot produce anything outside this
+    // range, and a caller passing 4 wants the shortest usable password rather
+    // than an exception.
+    const target = Math.min(
+        MAX_LENGTH,
+        Math.max(MIN_LENGTH, pools.length, Math.floor(length) || 0)
+    );
+
+    // One from each class first, so the guarantee holds however short it is.
+    const chars = pools.map((pool) => pool[randomBelow(pool.length)]);
+    const all = pools.flat();
+
+    while (chars.length < target) {
+        chars.push(all[randomBelow(all.length)]);
+    }
+
+    // Without this the first N characters are one-per-class in a fixed order.
+    return shuffle(chars).join('');
+};
+
+/* -------------------------------------------------------------------------
+ * Password strength
+ * ---------------------------------------------------------------------- */
+
+const STRENGTH_LABELS = ['Weak', 'Fair', 'Good', 'Strong', 'Excellent'];
+
+/** Three or more of the same character in a row: `aaa`, `111`. */
+const hasRun = (pw) => /(.)\1{2,}/.test(pw);
+
+/** Three or more consecutive code points, either direction: `abc`, `321`. */
+const hasSequence = (pw) => {
+    for (let i = 0; i + 2 < pw.length; i += 1) {
+        const a = pw.charCodeAt(i);
+        const b = pw.charCodeAt(i + 1);
+        const c = pw.charCodeAt(i + 2);
+
+        if (b - a === 1 && c - b === 1) return true;
+        if (a - b === 1 && b - c === 1) return true;
+    }
+
+    return false;
+};
+
+/**
+ * Score a password out of 4.
+ *
+ * Length carries most of the weight because it genuinely does, class variety
+ * carries the rest, and the two obvious patterns cost a point each. This is a
+ * meter to steer someone away from `Password123`, not an entropy estimate —
+ * anything stronger belongs to the generator, which is one click away.
+ */
+export const scorePassword = (password) => {
+    const pw = String(password ?? '');
+
+    if (pw === '') return { score: 0, label: STRENGTH_LABELS[0] };
+
+    let points = 0;
+
+    if (pw.length >= 8) points += 1;
+    if (pw.length >= 12) points += 1;
+    if (pw.length >= 16) points += 1;
+    if (pw.length >= 20) points += 1;
+
+    const classes = [/[a-z]/, /[A-Z]/, /[0-9]/, /[^a-zA-Z0-9]/].filter((re) =>
+        re.test(pw)
+    ).length;
+
+    if (classes >= 2) points += 1;
+    if (classes >= 3) points += 1;
+    if (classes >= 4) points += 1;
+
+    if (hasRun(pw)) points -= 1;
+    if (hasSequence(pw)) points -= 1;
+
+    // points runs 0..7; these thresholds map it onto the five labels.
+    let score;
+    if (points <= 1) score = 0;
+    else if (points <= 3) score = 1;
+    else if (points <= 4) score = 2;
+    else if (points <= 6) score = 3;
+    else score = 4;
+
+    return { score, label: STRENGTH_LABELS[score] };
+};
+
+/* -------------------------------------------------------------------------
+ * Codes and clocks
+ * ---------------------------------------------------------------------- */
+
+/**
+ * Space a one-time code so it can be read off the screen and typed.
+ *
+ * Even lengths split down the middle (`482119` -> `482 119`, the grouping
+ * every authenticator app uses); odd lengths group in threes from the left.
+ */
+export const formatOtp = (code) => {
+    const digits = String(code ?? '').replace(/\s/g, '');
+
+    if (digits === '') return '';
+    if (digits.length % 2 === 0) {
+        const half = digits.length / 2;
+        return `${digits.slice(0, half)} ${digits.slice(half)}`;
+    }
+
+    return digits.match(/.{1,3}/g).join(' ');
+};
+
+/**
+ * Seconds left in the current TOTP window.
+ *
+ * Returns `period` exactly on a boundary — a whole window remains — and never
+ * 0, so a countdown driven by this never renders an expired-looking code that
+ * is in fact still valid.
+ */
+export const secondsUntilBoundary = (period = OTP_DEFAULTS.period, now = Date.now()) => {
+    const size = Number.isFinite(period) && period > 0 ? Math.floor(period) : OTP_DEFAULTS.period;
+    const seconds = Math.floor(now / 1000);
+
+    return size - (seconds % size);
+};
+
+/* -------------------------------------------------------------------------
+ * Keyboard shortcut
+ * ---------------------------------------------------------------------- */
+
+/**
+ * Best-effort platform sniff, used only to decide what `mod` means and which
+ * glyph to print. Guarded for non-browser environments.
+ */
+export const isMacPlatform = () => {
+    const nav = globalThis.navigator;
+
+    if (!nav) return false;
+
+    const source = String(nav.userAgentData?.platform || nav.platform || nav.userAgent || '');
+
+    return /mac|iphone|ipad|ipod/i.test(source);
+};
+
+const parseShortcut = (shortcut) => {
+    const parts = String(shortcut ?? '')
+        .toLowerCase()
+        .split('+')
+        .map((part) => part.trim())
+        .filter(Boolean);
+
+    return {
+        mod: parts.includes('mod'),
+        shift: parts.includes('shift'),
+        alt: parts.includes('alt') || parts.includes('option'),
+        ctrl: parts.includes('ctrl') || parts.includes('control'),
+        meta: parts.includes('meta') || parts.includes('cmd'),
+        key: parts[parts.length - 1] || '',
+    };
+};
+
+/**
+ * Does this keydown event match a shortcut like `mod+shift+k`?
+ *
+ * `mod` is Command on a Mac and Control everywhere else — the convention every
+ * cross-platform app follows, and the reason a hard-coded `ctrl+` shortcut
+ * fights the OS on one of the two platforms.
+ *
+ * The modifiers the shortcut does *not* name must be absent, so `mod+shift+k`
+ * is not fired by `mod+shift+alt+k` — that is somebody else's shortcut. That
+ * strictness is also why an array is accepted: `⌘K` and `⌘⇧K` are two
+ * shortcuts, not one with an optional modifier, and both should open the
+ * vault.
+ *
+ * `isMac` is a parameter rather than a lookup so this stays pure and testable;
+ * it defaults to sniffing the platform.
+ */
+export const matchesShortcut = (
+    event,
+    shortcut = 'mod+shift+k',
+    isMac = isMacPlatform()
+) => {
+    if (!event || !event.key) return false;
+
+    if (Array.isArray(shortcut)) {
+        return shortcut.some((one) => matchesShortcut(event, one, isMac));
+    }
+
+    const wanted = parseShortcut(shortcut);
+
+    if (wanted.key === '') return false;
+    // `event.key` is layout-aware and already lowercase for letters unless
+    // shift is held, in which case it arrives uppercase.
+    if (String(event.key).toLowerCase() !== wanted.key) return false;
+
+    const wantCtrl = wanted.ctrl || (wanted.mod && !isMac);
+    const wantMeta = wanted.meta || (wanted.mod && isMac);
+
+    return (
+        Boolean(event.ctrlKey) === wantCtrl &&
+        Boolean(event.metaKey) === wantMeta &&
+        Boolean(event.shiftKey) === wanted.shift &&
+        Boolean(event.altKey) === wanted.alt
+    );
+};
+
+/**
+ * `⌘⇧K` on a Mac, `Ctrl+Shift+K` elsewhere — for the hint line.
+ *
+ * Given several shortcuts, the first is the one printed: it is the one the
+ * hint is teaching, and a footer listing every accepted chord teaches nothing.
+ */
+export const shortcutLabel = (shortcut = 'mod+shift+k', isMac = isMacPlatform()) => {
+    if (Array.isArray(shortcut)) {
+        return shortcut.length ? shortcutLabel(shortcut[0], isMac) : '';
+    }
+
+    const wanted = parseShortcut(shortcut);
+    const key = wanted.key.toUpperCase();
+
+    if (isMac) {
+        return `${wanted.ctrl ? '⌃' : ''}${wanted.alt ? '⌥' : ''}${
+            wanted.mod || wanted.meta ? '⌘' : ''
+        }${wanted.shift ? '⇧' : ''}${key}`;
+    }
+
+    const parts = [];
+    if (wanted.mod || wanted.ctrl) parts.push('Ctrl');
+    if (wanted.alt) parts.push('Alt');
+    if (wanted.shift) parts.push('Shift');
+    if (wanted.meta && !wanted.mod) parts.push('Meta');
+    parts.push(key);
+
+    return parts.join('+');
+};
+
+/* -------------------------------------------------------------------------
+ * Small display helpers
+ * ---------------------------------------------------------------------- */
+
+/**
+ * The host of a stored URL, for the second line of a result row.
+ *
+ * Entries are typed by hand, so `mybank.com.au` arrives as often as a full
+ * URL; a missing scheme is assumed to be https rather than discarded. `www.`
+ * is dropped because it is never the distinguishing part.
+ */
+export const hostFromUrl = (url) => {
+    const raw = String(url ?? '').trim();
+
+    if (raw === '') return '';
+
+    try {
+        const parsed = new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(raw) ? raw : `https://${raw}`);
+
+        return parsed.hostname.replace(/^www\./i, '');
+    } catch {
+        return raw;
+    }
+};
+
+/** A URL safe to hand to `window.open`, or '' when there is nothing to open. */
+export const openableUrl = (url) => {
+    const raw = String(url ?? '').trim();
+
+    if (raw === '') return '';
+
+    // Anything that is not http(s) — `javascript:` above all — is refused
+    // rather than opened. These values are typed by staff and stored verbatim.
+    if (/^[a-z][a-z0-9+.-]*:/i.test(raw)) {
+        return /^https?:\/\//i.test(raw) ? raw : '';
+    }
+
+    return `https://${raw}`;
+};
+
+/** `a, b , a` -> `['a', 'b']`. Order kept, blanks and duplicates dropped. */
+export const parseTags = (input) => {
+    const source = Array.isArray(input) ? input : String(input ?? '').split(',');
+    const seen = new Set();
+    const out = [];
+
+    source.forEach((tag) => {
+        const clean = String(tag ?? '').trim();
+        const key = clean.toLowerCase();
+
+        if (clean === '' || seen.has(key)) return;
+
+        seen.add(key);
+        out.push(clean);
+    });
+
+    return out;
+};

package/src/components/vault/vaultNavigation.jsx

@@ -0,0 +1,58 @@
+import React, { useCallback } from 'react';
+import { useInRouterContext, useLocation, useNavigate } from 'react-router-dom';
+
+/**
+ * Give a component a `navigate` that works whether or not it is inside a
+ * Router.
+ *
+ * The vault's surfaces mount in two quite different places: the CRM header,
+ * which is inside a `<BrowserRouter>`, and the standalone fixture, which is
+ * not. `useNavigate` throws outside a Router and hooks cannot be called
+ * conditionally, so the choice is made by rendering one of two components —
+ * each of which calls its own hooks unconditionally. A component does not
+ * move in or out of a Router during its life, so the branch is stable.
+ *
+ * The wrapped component receives `navigate(to)` and `locationSearch`.
+ */
+export const withVaultNavigation = (Inner) => {
+    const Routed = (props) => {
+        const navigate = useNavigate();
+        const location = useLocation();
+
+        return (
+            <Inner {...props} navigate={navigate} locationSearch={location.search} />
+        );
+    };
+
+    const Plain = (props) => {
+        // A full page load, which is the only thing available here — and the
+        // right behaviour for a link out of a standalone fixture.
+        const navigate = useCallback((to) => {
+            if (typeof window !== 'undefined') window.location.href = to;
+        }, []);
+
+        return (
+            <Inner
+                {...props}
+                navigate={navigate}
+                locationSearch={
+                    typeof window !== 'undefined' ? window.location.search : ''
+                }
+            />
+        );
+    };
+
+    const name = Inner.displayName || Inner.name || 'Component';
+
+    Routed.displayName = `Routed(${name})`;
+    Plain.displayName = `Plain(${name})`;
+
+    const Wrapper = (props) =>
+        useInRouterContext() ? <Routed {...props} /> : <Plain {...props} />;
+
+    Wrapper.displayName = `withVaultNavigation(${name})`;
+
+    return Wrapper;
+};
+
+export default withVaultNavigation;