@wenathlan/saddle 2.0.151 → 2.0.152

package/dist/onboardingstate.js

@@ -0,0 +1,282 @@
+/**
+ * onboardingstate.ts — the ONE writer of the visitor's first-run flags, the
+ * state of the entry-flow contract (intro → onboarding → the platform). The
+ * state is { introseen, onboardingseen } and it is catalogued, not just
+ * browser: the accessor consults the platform database over GET
+ * /api/v1/onboarding and writes it over POST /api/v1/onboarding, both HTTPS
+ * only — the base url arrives through VITE_ONBOARDING_URL and every
+ * candidate host is validated first (localhost, loopback, private,
+ * link-local, CGNAT and the reserved documentation ranges are refused, so
+ * the flags never ride a dev or internal endpoint; mapped IPv6 literals are
+ * normalized back to their embedded IPv4 before the public check). The
+ * localStorage key saddle.onboarding.seen is purely the offline cache of
+ * the database (the DB is the source of truth; the cache avoids replaying
+ * the flow offline) and module memory covers client-side re-navigation.
+ * Reads reconcile with a seen-wins merge — a stage seen anywhere stays
+ * seen, the flow is never forced twice. The page anchors never touch the
+ * flags directly: the intro marks introseen, the onboarding marks
+ * onboardingseen, the home entry gate only reads.
+ */
+/** the localStorage cache key (the DB mirror, never the source of truth). */
+const CACHE_KEY = 'saddle.onboarding.seen';
+/** the localStorage key of the stable per-browser visitor id. */
+const VISITOR_KEY = 'saddle.visitor.id';
+/** the configured platform base (HTTPS self-hosted gateway); empty answers cache-only. */
+const BASE = (typeof import.meta !== 'undefined'
+    ? import.meta.env?.VITE_ONBOARDING_URL
+    : undefined)?.trim().replace(/\/+$/, '') ?? '';
+/** the platform route the accessor rides (the gateway serves /api/v1/*). */
+const API_PATH = '/api/v1/onboarding';
+/** the abort window of the platform read (ms) — the flow never blocks on a slow gateway. */
+const READ_TIMEOUT_MS = 2500;
+/** module memory: the flags of the session, consulted before any i/o. */
+let memory = null;
+/**
+ * Validates a platform base url: HTTPS only, and the host must be public —
+ * localhost, loopback, private, link-local, CGNAT, benchmarking,
+ * unique-local and the reserved documentation ranges are refused; a mapped
+ * IPv6 literal is normalized to its embedded IPv4 first; any other IPv6
+ * literal is refused (the gateway rides a name).
+ *
+ * @param base the configured base url candidate.
+ * @returns true when the base may be consulted.
+ */
+export function hostallowed(base) {
+    try {
+        const url = new URL(base);
+        if (url.protocol !== 'https:')
+            return false;
+        const host = url.hostname
+            .toLowerCase()
+            .replace(/\.+$/, '')
+            .replace(/^\[|\]$/g, '');
+        if (host.length === 0)
+            return false;
+        if (host === 'localhost' || host === '0.0.0.0' || host === '::1' || host === '::')
+            return false;
+        if (host.endsWith('.localhost') || host.endsWith('.local') || host.endsWith('.internal')) {
+            return false;
+        }
+        if (host.endsWith('.home.arpa'))
+            return false;
+        if (host.includes(':'))
+            return mappedipv6(host);
+        const v4 = host.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+        if (v4)
+            return publicipv4(Number(v4[1]), Number(v4[2]));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Answers whether an IPv6 literal is the IPv4-mapped form of a PUBLIC
+ * address (the url parser normalizes `::ffff:127.0.0.1` to hex hextets, so
+ * both spellings are normalized here and the embedded IPv4 decides).
+ *
+ * @param host the bracket-free ipv6 literal.
+ * @returns true when the literal maps to a public ipv4 address.
+ */
+function mappedipv6(host) {
+    if (!host.startsWith('::ffff:'))
+        return false;
+    const tail = host.slice('::ffff:'.length);
+    const decimals = tail.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+    if (decimals)
+        return publicipv4(Number(decimals[1]), Number(decimals[2]));
+    // the hex spelling the url parser produces: the first hextet of the pair
+    // carries the first two ipv4 octets, and they alone decide the ranges
+    const hextets = tail.match(/^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+    if (hextets) {
+        const high = Number.parseInt(hextets[1], 16);
+        return publicipv4((high >> 8) & 0xff, high & 0xff);
+    }
+    return false;
+}
+/** the public side of an ipv4 address (the first two octets decide). */
+function publicipv4(a, b) {
+    if (a === 0 || a === 10 || a === 127)
+        return false;
+    if (a === 172 && b >= 16 && b <= 31)
+        return false;
+    if (a === 192 && b === 168)
+        return false;
+    if (a === 169 && b === 254)
+        return false;
+    if (a === 100 && b >= 64 && b <= 127)
+        return false;
+    if (a === 192 && b === 0)
+        return false;
+    if (a === 198 && (b === 18 || b === 19))
+        return false;
+    if (a === 198 && (b === 51 || b === 52))
+        return false;
+    if (a === 203 && b === 0)
+        return false;
+    if (a >= 224)
+        return false;
+    return true;
+}
+/**
+ * Answers the flags after one stage was marked seen (pure: the writer and
+ * the tests share this merge — seen-wins, a stage never unsees).
+ *
+ * @param state the flags before the write.
+ * @param stage the stage being marked seen.
+ * @returns the flags after the write.
+ */
+export function mergeStage(state, stage) {
+    return stage === 'intro'
+        ? { ...state, introseen: true }
+        : { ...state, introseen: true, onboardingseen: true };
+}
+/** Reads the localStorage cache; any corruption answers null (the cache is best effort). */
+function readCache() {
+    if (typeof window === 'undefined')
+        return null;
+    try {
+        const raw = window.localStorage.getItem(CACHE_KEY);
+        if (!raw)
+            return null;
+        const parsed = JSON.parse(raw);
+        return { introseen: parsed.introseen === true, onboardingseen: parsed.onboardingseen === true };
+    }
+    catch {
+        return null;
+    }
+}
+/** Mirrors the flags into the localStorage cache (silently skipped when storage is sealed). */
+function writeCache(state) {
+    if (typeof window === 'undefined')
+        return;
+    try {
+        window.localStorage.setItem(CACHE_KEY, JSON.stringify(state));
+    }
+    catch {
+        // the cache is best effort: the DB and the memory stay authoritative
+    }
+}
+/**
+ * The stable per-browser visitor id (generated once, cached beside the
+ * flags); storage unavailable answers the shared web key.
+ *
+ * @returns the visitor string the gateway rows are keyed by.
+ */
+function visitor() {
+    if (typeof window === 'undefined')
+        return 'web';
+    try {
+        const existing = window.localStorage.getItem(VISITOR_KEY);
+        if (existing)
+            return existing;
+        const fresh = crypto.randomUUID();
+        window.localStorage.setItem(VISITOR_KEY, fresh);
+        return fresh;
+    }
+    catch {
+        return 'web';
+    }
+}
+/** Reads the flags off the platform database; unreachable or unconfigured answers null. */
+async function readRemote() {
+    if (!BASE || !hostallowed(BASE) || typeof fetch === 'undefined')
+        return null;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), READ_TIMEOUT_MS);
+    try {
+        const response = await fetch(`${BASE}${API_PATH}?visitor=${encodeURIComponent(visitor())}`, {
+            headers: { accept: 'application/json' },
+            signal: controller.signal,
+        });
+        if (!response.ok)
+            return null;
+        const answer = (await response.json());
+        return { introseen: answer.introseen === true, onboardingseen: answer.onboardingseen === true };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Writes the flags to the platform database over POST; failures leave the cache holding them. */
+async function writeRemote(state) {
+    if (!BASE || !hostallowed(BASE) || typeof fetch === 'undefined')
+        return;
+    try {
+        await fetch(`${BASE}${API_PATH}`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ visitor: visitor(), ...state }),
+        });
+    }
+    catch {
+        // the cache mirrors the flags until the platform answers again
+    }
+}
+/**
+ * Synchronous read of the known state: module memory first, then the
+ * localStorage cache. The entry gate uses this for the flash-free fast
+ * path; null means the state is still unknown and the caller must await
+ * loadOnboardingState.
+ *
+ * @returns the known flags, or null when nothing is known yet.
+ */
+export function readOnboardingState() {
+    if (memory)
+        return memory;
+    const cached = readCache();
+    if (cached) {
+        memory = cached;
+        return cached;
+    }
+    return null;
+}
+/**
+ * Full resolve of the flags: memory/cache first, then the platform database
+ * over GET /api/v1/onboarding — reconciled with the seen-wins merge so a
+ * stage seen anywhere stays seen. The session answer is memoized;
+ * re-navigation never refetches.
+ *
+ * @returns the resolved visitor onboarding flags.
+ */
+export async function loadOnboardingState() {
+    const local = readOnboardingState() ?? { introseen: false, onboardingseen: false };
+    if (!BASE || !hostallowed(BASE) || (local.introseen && local.onboardingseen))
+        return local;
+    const remote = await readRemote();
+    if (!remote)
+        return local;
+    const merged = {
+        introseen: local.introseen || remote.introseen,
+        onboardingseen: local.onboardingseen || remote.onboardingseen,
+    };
+    memory = merged;
+    writeCache(merged);
+    return merged;
+}
+/**
+ * Marks the intro stage seen and persists it everywhere: module memory, the
+ * localStorage cache and — when a platform base is configured — the
+ * database over POST /api/v1/onboarding. The ONLY writer of the intro flag.
+ */
+export function markIntroSeen() {
+    memory = mergeStage(memory ?? readCache() ?? { introseen: false, onboardingseen: false }, 'intro');
+    writeCache(memory);
+    void writeRemote(memory);
+}
+/**
+ * Marks the onboarding stage seen (finish or skip — both imply the intro)
+ * and persists it everywhere. The ONLY writer of the onboarding flag.
+ */
+export function markOnboardingSeen() {
+    memory = mergeStage(memory ?? readCache() ?? { introseen: false, onboardingseen: false }, 'onboarding');
+    writeCache(memory);
+    void writeRemote(memory);
+}
+/** Test seam: clears the module memory (the cache and the platform are untouched). */
+export function resetOnboardingMemory() {
+    memory = null;
+}