@visns-studio/visns-components 6.6.3 → 6.15.0

package/src/components/auth/authHelpers.js

@@ -0,0 +1,465 @@
+/**
+ * Pure helpers shared by the auth screens.
+ *
+ * Everything here is deliberately free of React and of the DOM so it can be
+ * unit-tested with `node --test` (see tests/authHelpers.test.mjs) — the screens
+ * themselves are verified by hand.
+ */
+
+/* -------------------------------------------------------------------------- */
+/* contact-type classifier                                                    */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * The copy the portal's login page shows under the contact field, one line per
+ * classification. Overridable per-screen via the `contactHints` prop.
+ */
+export const DEFAULT_CONTACT_HINTS = {
+    email: 'Email address detected',
+    mobile: 'Mobile number detected',
+    username: 'Username detected',
+    empty: 'Enter username, email, or mobile number',
+};
+
+/**
+ * What kind of contact did the user just type?
+ *
+ * Mirrors app/portal/page.js exactly, including its order of tests: an '@'
+ * anywhere wins (so `04@x` is an email), then a leading digit means a phone
+ * number, then anything else non-empty is a username. Whitespace is trimmed
+ * first, so a field holding only spaces still reads as empty.
+ *
+ * Returns one of 'email' | 'mobile' | 'username' | 'empty'.
+ */
+export const classifyContact = (value) => {
+    const trimmed = String(value ?? '').trim();
+
+    if (trimmed.includes('@')) {
+        return 'email';
+    }
+
+    if (/^\d/.test(trimmed)) {
+        return 'mobile';
+    }
+
+    if (trimmed.length > 0) {
+        return 'username';
+    }
+
+    return 'empty';
+};
+
+/**
+ * The hint line for a typed value. `hints` is merged over the defaults, so a
+ * consumer can reword one line without restating the other three.
+ */
+export const contactHint = (value, hints) => {
+    const table = { ...DEFAULT_CONTACT_HINTS, ...(hints || {}) };
+
+    return table[classifyContact(value)] ?? table.empty;
+};
+
+/**
+ * Append `@domain` to a bare username, the way the portal does before it asks
+ * for an OTP. Emails and phone numbers are handed back untouched, and so is
+ * everything when no domain is configured — which is the library default, so
+ * this is a no-op unless a consumer opts in.
+ */
+export const applyUsernameDomain = (value, domain) => {
+    const trimmed = String(value ?? '').trim();
+
+    if (!domain || trimmed === '') {
+        return trimmed;
+    }
+
+    if (classifyContact(trimmed) !== 'username') {
+        return trimmed;
+    }
+
+    return `${trimmed}@${String(domain).replace(/^@/, '')}`;
+};
+
+/* -------------------------------------------------------------------------- */
+/* one-time-code input                                                        */
+/* -------------------------------------------------------------------------- */
+
+/** How many digits a one-time code holds unless a screen says otherwise. */
+export const OTP_LENGTH = 6;
+
+/**
+ * Reduce whatever landed in a one-time-code field to digits, capped at
+ * `length`.
+ *
+ * Stripping rather than rejecting is what makes pasting work: a code copied out
+ * of a text message often arrives as `123 456`, and the previous
+ * `/^\d*$/`-or-ignore test dropped the paste on the floor entirely. For input
+ * that was already all digits the result is identical, so nothing that worked
+ * before behaves differently.
+ */
+export const clampOtp = (value, length = OTP_LENGTH) => {
+    const digits = String(value ?? '').replace(/\D/g, '');
+    const max = Number.isFinite(length) && length > 0 ? length : OTP_LENGTH;
+
+    return digits.slice(0, max);
+};
+
+/** Is this a complete code? Used to gate the submit handler. */
+export const isCompleteOtp = (value, length = OTP_LENGTH) =>
+    clampOtp(value, length).length === (length > 0 ? length : OTP_LENGTH);
+
+/* -------------------------------------------------------------------------- */
+/* error normalisation                                                        */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Turn whatever a failed request handed back into one displayable line.
+ *
+ * The screens see three shapes in practice:
+ *   - a string, from CustomFetch's `errorCallback` (already flattened)
+ *   - an Error, from a rejected promise
+ *   - a response body, `{error}` / `{message}` / `{errors: {...}}`
+ * …and an `{error: '…'}`-only body on a non-200 is the one CustomFetch itself
+ * cannot flatten, which is why the screens normalise rather than trusting it.
+ *
+ * `fallback` is returned when nothing readable is present, so a caller never has
+ * to render an empty toast.
+ */
+export const normaliseAuthError = (error, fallback = '') => {
+    const clean = (value) => {
+        if (typeof value !== 'string') {
+            return '';
+        }
+
+        const trimmed = value.trim();
+
+        // `String(undefined)` and friends reach here through `String(error)`
+        // call sites; none of them is worth showing a user.
+        if (
+            trimmed === '' ||
+            trimmed === 'undefined' ||
+            trimmed === 'null' ||
+            trimmed === '[object Object]'
+        ) {
+            return '';
+        }
+
+        return trimmed;
+    };
+
+    const fromBag = (bag) => {
+        if (!bag) {
+            return '';
+        }
+
+        if (Array.isArray(bag)) {
+            for (const entry of bag) {
+                const line = fromBag(entry);
+
+                if (line) {
+                    return line;
+                }
+            }
+
+            return '';
+        }
+
+        if (typeof bag === 'object') {
+            if (clean(bag.message)) {
+                return clean(bag.message);
+            }
+
+            for (const value of Object.values(bag)) {
+                const line = fromBag(value);
+
+                if (line) {
+                    return line;
+                }
+            }
+
+            return '';
+        }
+
+        return clean(bag);
+    };
+
+    const fromBody = (body) => {
+        if (!body) {
+            return '';
+        }
+
+        if (typeof body === 'string') {
+            return clean(body);
+        }
+
+        if (typeof body !== 'object') {
+            return '';
+        }
+
+        // `error` first: it is the field this library's own backends use, and
+        // the one CustomFetch's flattener does not look at.
+        return (
+            clean(body.error) ||
+            clean(body.message) ||
+            fromBag(body.errors) ||
+            ''
+        );
+    };
+
+    if (error === null || error === undefined) {
+        return fallback;
+    }
+
+    if (typeof error === 'string') {
+        return clean(error) || fallback;
+    }
+
+    if (typeof error === 'object') {
+        const body = error.response?.data ?? error.data;
+        const fromResponse = fromBody(body);
+
+        if (fromResponse) {
+            return fromResponse;
+        }
+
+        const direct = fromBody(error);
+
+        if (direct) {
+            return direct;
+        }
+
+        if (clean(error.statusText)) {
+            return clean(error.statusText);
+        }
+    }
+
+    return fallback;
+};
+
+/**
+ * Did a response actually succeed?
+ *
+ * The client endpoints answer `{success: true}`; the staff endpoints answer
+ * `{error: ''}`. A body carrying neither is treated as a success only when it
+ * has no error field at all, which is what the screens assumed before.
+ */
+export const isSuccessBody = (body) => {
+    if (!body || typeof body !== 'object') {
+        return false;
+    }
+
+    if (body.success === true) {
+        return true;
+    }
+
+    if (body.success === false) {
+        return false;
+    }
+
+    return body.error === '' || body.error === null || body.error === undefined;
+};
+
+/* -------------------------------------------------------------------------- */
+/* contact masking                                                            */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * A local fallback for the server's `masked_contact`, used only when the
+ * response does not carry one: `jane@example.com` -> `j***@example.com`,
+ * `0412345678` -> `*** *** 678`.
+ */
+export const maskContact = (value) => {
+    const trimmed = String(value ?? '').trim();
+
+    if (trimmed === '') {
+        return '';
+    }
+
+    if (trimmed.includes('@')) {
+        const [local, ...rest] = trimmed.split('@');
+        const domain = rest.join('@');
+
+        if (local.length <= 1) {
+            return `${local}***@${domain}`;
+        }
+
+        return `${local[0]}***@${domain}`;
+    }
+
+    const digits = trimmed.replace(/\D/g, '');
+
+    if (digits.length <= 3) {
+        return trimmed;
+    }
+
+    return `*** *** ${digits.slice(-3)}`;
+};
+
+/* -------------------------------------------------------------------------- */
+/* two-factor challenge hand-over                                             */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Is a two-factor challenge in progress, given the state Login handed over?
+ *
+ * The marker is the STATE, never the user payload inside it. This existed as
+ * `if (!userData) navigate('/login')` inside TwoFactorAuth, and it broke every
+ * code-driver sign-in: the packages' AuthController answers a code challenge
+ * with `user: null` on purpose — there the account is identified by a code sent
+ * out of band, so echoing the record would hand an unauthenticated caller a
+ * user lookup. The SMS arrived and the screen to type it into bounced straight
+ * back to the login form.
+ *
+ * `challenge === true` is what Login sends. `userData` on its own is still
+ * accepted, so a consumer running an older Login — or driving the screen
+ * itself — keeps working. Only a completely absent state means "no challenge",
+ * which is the direct-URL-hit and reload case the guard is actually for.
+ */
+export const hasChallengeState = (state) =>
+    Boolean(state && (state.challenge === true || state.userData));
+
+/* -------------------------------------------------------------------------- */
+/* pending states and transitions                                             */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Which label a resend control should be showing.
+ *
+ * Three states, and the middle one used to be missing: while the request was
+ * actually in flight the link went on saying "Resend Code", so pressing it
+ * looked like it had done nothing. A cooldown counted down visibly, but the
+ * flight itself — the part the user is waiting on — said nothing at all.
+ *
+ * In-flight wins over the countdown: both can be true at once for a component
+ * configured with a cooldown, and "Sending…" is the more informative of the
+ * two at that moment.
+ */
+export const resendLabelFor = ({
+    isResending = false,
+    countdown = 0,
+    labels = {},
+} = {}) => {
+    if (isResending) {
+        return labels.resending ?? 'Sending…';
+    }
+
+    if (countdown > 0) {
+        return String(labels.resendIn ?? 'Resend in {seconds}s').replace(
+            '{seconds}',
+            String(countdown)
+        );
+    }
+
+    return labels.resend ?? 'Resend code';
+};
+
+/**
+ * Where a successful two-factor verification goes, and how.
+ *
+ * Two answers, and picking the wrong one is what made the screen feel broken:
+ *
+ *   - `hard` — a real navigation, because the destination is an arbitrary URL
+ *     from before sign-in (or a `successPath` the consumer set deliberately)
+ *     and may not be inside the SPA at all. The caller must raise a curtain
+ *     and leave it up: the browser will take its time, and until it does the
+ *     old page is still on screen.
+ *   - `handoff` — no navigation here at all. Setting the auth state is enough;
+ *     GenericAuth notices, drops its own curtain, re-reads the profile with the
+ *     session the challenge just issued, and performs the one route change.
+ *
+ * `handoff` is the default case, and it is the fix: the screen used to
+ * hard-reload unconditionally, which bypassed that curtain entirely and gave
+ * the "flickers, then nothing, then the page reloads" the review reported.
+ */
+export const twoFactorSuccessTarget = ({
+    previousUrl = '',
+    successPath = '/',
+    defaultSuccessPath = '/',
+} = {}) => {
+    if (previousUrl && previousUrl !== '') {
+        return { mode: 'hard', url: previousUrl };
+    }
+
+    // A consumer that set successPath to something of its own is asking to
+    // land there specifically, which this component cannot do through
+    // GenericAuth — that always goes to '/'.
+    if (successPath && successPath !== defaultSuccessPath) {
+        return { mode: 'hard', url: successPath };
+    }
+
+    return { mode: 'handoff', url: '' };
+};
+
+/* -------------------------------------------------------------------------- */
+/* CSRF token resync                                                          */
+/* -------------------------------------------------------------------------- */
+
+/** Where Laravel-style apps park the CSRF token for the SPA to read. */
+export const CSRF_META_SELECTOR = 'meta[name="csrf-token"]';
+
+/**
+ * Point the page's CSRF meta tag at a freshly-issued token.
+ *
+ * This exists because of what the no-reload 2FA hand-off exposed. The backend
+ * rotated the CSRF token on a successful challenge, and every sign-in before
+ * 6.8.1 ended in a full page load — which fetched a new document, with a new
+ * meta tag, and nobody had to think about it. Handing off without a reload kept
+ * the document, and with it a token the server had just invalidated: every
+ * subsequent POST came back 419 and the user got a toast storm instead of an
+ * application.
+ *
+ * The rotation is being removed on the backend, and auth responses are growing
+ * a `csrf_token` field so the SPA can resync from any of them. This is the one
+ * place that consumes it. CustomFetch re-reads the meta on every single
+ * request, so updating the attribute is the whole of the fix — nothing needs to
+ * be told the value changed.
+ *
+ * Entirely inert when the field is absent, which is what makes it safe to call
+ * unconditionally at every hand-off point: a backend that never sends one sees
+ * no change at all.
+ *
+ * Returns true only when a token was actually written, so a caller can tell
+ * "nothing to do" from "there was something to do and it did not happen".
+ */
+export const syncCsrfToken = (token) => {
+    if (typeof token !== 'string' || token.trim() === '') {
+        return false;
+    }
+
+    if (typeof document === 'undefined' || !document) {
+        return false;
+    }
+
+    try {
+        const meta = document.querySelector(CSRF_META_SELECTOR);
+
+        // An app that never had the meta tag is not broken by its absence —
+        // it simply was not using CSRF tokens this way to begin with.
+        if (!meta || typeof meta.setAttribute !== 'function') {
+            return false;
+        }
+
+        meta.setAttribute('content', token);
+
+        return true;
+    } catch (error) {
+        // A resync that cannot happen must never take the sign-in down with
+        // it: the worst case is the 419s this was written to prevent, which is
+        // still better than a white screen at the moment of authentication.
+        return false;
+    }
+};
+
+/**
+ * Pull `csrf_token` out of an auth response and apply it.
+ *
+ * The shape differs by endpoint — the authenticate response is an envelope, the
+ * challenge response is the user record itself — but the field name is the same
+ * in both, so call sites do not need to care which they are holding.
+ */
+export const syncCsrfFromResponse = (response) => {
+    if (!response || typeof response !== 'object') {
+        return false;
+    }
+
+    return syncCsrfToken(response.csrf_token);
+};

package/src/components/auth/clientAuthProtocols.js

@@ -0,0 +1,240 @@
+/**
+ * Wire protocols for the client portal sign-in screens.
+ *
+ * There are two of them in the wild and they disagree about nearly everything:
+ * the request bodies, how success is signalled, and whether a challenge even
+ * has an id. Rather than let one of them be "the" protocol and make the other
+ * a consumer's problem, both are described here as data and the screens read
+ * whichever they were given.
+ *
+ * `uuid` is the default and is exactly what 6.6.3/6.7.0 did. `contact` is the
+ * protocol behind ThroughLife's `/api/auth/*` routes (visns-packages'
+ * OtpController) — it has no uuid at all, signals success with `error: ''`, and
+ * returns a bearer token the consumer has to store.
+ *
+ * Pure module (no React, no DOM) so it can be unit-tested with `node --test`.
+ */
+
+/**
+ * Read a body's `error` field as a string, whatever it actually holds. A body
+ * with no `error` at all yields '' — absence is not a failure.
+ */
+const errorOf = (body) => {
+    if (!body || typeof body !== 'object') {
+        return '';
+    }
+
+    const value = body.error;
+
+    if (value === null || value === undefined) {
+        return '';
+    }
+
+    return typeof value === 'string' ? value : String(value);
+};
+
+/**
+ * The uuid protocol — the library's original, and still the default.
+ *
+ * Step one answers `{success, uuid, message, …}` and step two is only
+ * meaningful with that uuid in hand, so a verify screen reached without one
+ * has no challenge to answer and bounces back.
+ */
+const UUID_PROTOCOL = {
+    name: 'uuid',
+
+    /**
+     * Does a challenge carry an id that step two cannot proceed without? When
+     * true, ClientOTPVerify redirects to step one if it has no `challengeId`.
+     */
+    requiresChallengeId: true,
+
+    /** Default request-body key holding the identifier. */
+    contactField: 'email',
+
+    /**
+     * Which form of the identifier step two sends. `false` means the same
+     * value step one sent (domain-completed, if `usernameDomain` is set).
+     */
+    verifyUsesRawContact: false,
+
+    /** Body for the request-a-code call. */
+    requestBody: ({ contact, contactField, previousUrl, resend }) =>
+        resend
+            ? { [contactField]: contact, resend: true }
+            : { [contactField]: contact, location: previousUrl || '' },
+
+    /** Body for the verify-the-code call. */
+    verifyBody: ({ contact, contactField, code, challengeId, previousUrl }) => ({
+        [contactField]: contact,
+        uuid: challengeId,
+        otp: code,
+        previous_url: previousUrl || '',
+    }),
+
+    /**
+     * Strictly `body.success`, which is what the screens tested before. A body
+     * that merely lacks an error is NOT a success here.
+     */
+    isSuccess: (body) => Boolean(body && body.success),
+
+    /** Everything step two needs, read out of step one's response. */
+    readChallenge: (body) => ({
+        challengeId: body?.uuid ?? null,
+        maskedContact: body?.masked_contact ?? '',
+        contactMethod: body?.contact_method ?? '',
+        devOtp: body?.dev_otp ?? body?.otp ?? null,
+        message: body?.message ?? '',
+    }),
+
+    /** The session, read out of step two's response. */
+    readSession: (body) => ({
+        user: body?.user ?? null,
+        // This protocol's backend sets a cookie; there is no bearer token for
+        // the consumer to store.
+        token: null,
+        redirectUrl: body?.redirect_url ?? '',
+        message: body?.message ?? '',
+    }),
+};
+
+/**
+ * The contact protocol — ThroughLife's `/api/auth/request-otp` and
+ * `/api/auth/login-otp`, served by visns-packages' OtpController.
+ *
+ * Three things make it incompatible with the uuid protocol, and all three are
+ * load-bearing:
+ *
+ *  - There is no uuid. The code is stored against the contact record itself,
+ *    so the identifier IS the challenge id. A verify screen must not demand
+ *    one.
+ *  - `login-otp` answers `{error: '', access_token, user, full_data_available}`
+ *    and carries no `success` key at all, so testing `body.success` would read
+ *    a correct code as a wrong one.
+ *  - Failures arrive as non-200 `{error: '…'}` bodies (404/401/403/429, and a
+ *    500 for a validation failure — see the controller's own note about that
+ *    wart being contract). They reach the screens through CustomFetch's
+ *    rejection path, not its success path.
+ *
+ * The `verifyUsesRawContact` flag mirrors a real asymmetry in the portal page
+ * this was ported from: a bare username is completed to `name@domain` for
+ * request-otp, but sent as typed to login-otp.
+ */
+const CONTACT_PROTOCOL = {
+    name: 'contact',
+
+    requiresChallengeId: false,
+
+    contactField: 'contact',
+
+    verifyUsesRawContact: true,
+
+    /** A resend is simply another request — there is no resend flag. */
+    requestBody: ({ contact, contactField }) => ({ [contactField]: contact }),
+
+    verifyBody: ({ contact, contactField, code, minimalResponse }) => ({
+        [contactField]: contact,
+        otp_code: code,
+        // The whitelisted user payload, small enough to live in a cookie. The
+        // full model does not fit in one and should not travel there anyway.
+        minimal_response: minimalResponse !== false,
+    }),
+
+    /**
+     * `error === ''` is the signal, for both steps. request-otp happens to
+     * also send `success: true`; login-otp does not, so the error field is the
+     * only thing both have in common.
+     */
+    isSuccess: (body) =>
+        Boolean(body) && typeof body === 'object' && errorOf(body) === '',
+
+    readChallenge: (body) => ({
+        // No uuid in this contract. Stated explicitly rather than left to
+        // `?? null` so the absence reads as deliberate.
+        challengeId: null,
+        maskedContact: body?.masked_contact ?? '',
+        contactMethod: body?.contact_method ?? '',
+        devOtp: body?.dev_otp ?? null,
+        message: body?.message ?? '',
+    }),
+
+    readSession: (body) => ({
+        user: body?.user ?? null,
+        // The reason this protocol needed `onAuthenticated`: the token is the
+        // session, and it has to reach the consumer to be stored.
+        token: body?.access_token ?? null,
+        redirectUrl: body?.redirect_url ?? '',
+        message: body?.message ?? '',
+        fullDataAvailable: body?.full_data_available ?? null,
+    }),
+};
+
+/** The protocols shipped by name. */
+export const CLIENT_AUTH_PROTOCOLS = {
+    uuid: UUID_PROTOCOL,
+    contact: CONTACT_PROTOCOL,
+};
+
+/** What a screen falls back to when nothing is configured. */
+export const DEFAULT_CLIENT_PROTOCOL = 'uuid';
+
+/**
+ * Resolve the `protocol` prop.
+ *
+ * Accepts a name (`'uuid'` / `'contact'`), or an object of overrides. An object
+ * may name the protocol it starts from with `extends`; without one it builds on
+ * `uuid`, so a partial object is a tweak rather than a rewrite. An unknown name
+ * falls back to the default rather than throwing — a typo in a prop should not
+ * white-screen a login page.
+ */
+export const resolveClientProtocol = (protocol) => {
+    if (!protocol) {
+        return CLIENT_AUTH_PROTOCOLS[DEFAULT_CLIENT_PROTOCOL];
+    }
+
+    if (typeof protocol === 'string') {
+        return (
+            CLIENT_AUTH_PROTOCOLS[protocol] ||
+            CLIENT_AUTH_PROTOCOLS[DEFAULT_CLIENT_PROTOCOL]
+        );
+    }
+
+    if (typeof protocol !== 'object') {
+        return CLIENT_AUTH_PROTOCOLS[DEFAULT_CLIENT_PROTOCOL];
+    }
+
+    const base =
+        CLIENT_AUTH_PROTOCOLS[protocol.extends] ||
+        CLIENT_AUTH_PROTOCOLS[DEFAULT_CLIENT_PROTOCOL];
+
+    const merged = { ...base };
+
+    Object.keys(protocol).forEach((key) => {
+        if (key === 'extends' || protocol[key] === undefined) {
+            return;
+        }
+
+        merged[key] = protocol[key];
+    });
+
+    return merged;
+};
+
+/**
+ * The identifier step two should send, given a challenge.
+ *
+ * `contact` is what step one actually put on the wire (domain-completed);
+ * `rawContact` is what the user typed. Which one step two wants is the
+ * protocol's business, not the screen's.
+ */
+export const verifyContactFor = (resolved, challenge) => {
+    if (!challenge) {
+        return '';
+    }
+
+    if (resolved?.verifyUsesRawContact) {
+        return challenge.rawContact ?? challenge.contact ?? '';
+    }
+
+    return challenge.contact ?? challenge.rawContact ?? '';
+};