stellar-drive 1.0.0

package/dist/auth/displayUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"displayUtils.d.ts","sourceRoot":"","sources":["../../src/auth/displayUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAQnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,OAAO,GAAG,IAAI,EACvB,cAAc,EAAE,kBAAkB,GAAG,IAAI,EACzC,QAAQ,GAAE,MAAmB,GAC5B,MAAM,CA6BR;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,OAAO,GAAG,IAAI,EACvB,cAAc,EAAE,kBAAkB,GAAG,IAAI,GACxC,MAAM,CAaR;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,GAAG,IAAI,EACvB,cAAc,EAAE,kBAAkB,GAAG,IAAI,EACzC,QAAQ,GAAE,MAAY,GACrB,MAAM,CAMR"}

package/dist/auth/displayUtils.js

@@ -0,0 +1,145 @@
+/**
+ * @fileoverview Auth Display Utilities
+ *
+ * Pure helper functions that resolve user-facing display values (first name,
+ * user ID, avatar initial) from the auth state. Each function handles the
+ * full fallback chain across online (Supabase session) and offline (cached
+ * credentials) modes, so consuming components don't need to duplicate the
+ * resolution logic.
+ *
+ * Resolution strategy (consistent across all helpers):
+ *   1. Check the Supabase session (`Session.user`) first.
+ *   2. Fall back to the offline credential cache (`OfflineCredentials`).
+ *   3. Return a caller-provided fallback or a sensible default.
+ *
+ * These functions are stateless and framework-agnostic — they accept plain
+ * data and return plain values. Wrap them in `$derived` / `$derived.by` in
+ * Svelte 5 components to make them reactive.
+ *
+ * @module auth/displayUtils
+ */
+import { getUserProfile } from '../supabase/auth';
+import { isDemoMode, getDemoConfig } from '../demo';
+// =============================================================================
+// PUBLIC API
+// =============================================================================
+/**
+ * Resolve the user's first name for greeting / display purposes.
+ *
+ * Fallback chain:
+ *   1. `firstName` / `first_name` from the Supabase session profile
+ *      (extracted via `getUserProfile()`, which respects the app's
+ *      `profileExtractor` config)
+ *   2. Email username (everything before `@`) from the Supabase session
+ *   3. `firstName` from the offline cached profile
+ *   4. Email username from the offline cached profile
+ *   5. The provided `fallback` string (default: `'Explorer'`)
+ *
+ * @param session - The current Supabase session, or `null`.
+ * @param offlineProfile - The cached offline credentials, or `null`.
+ * @param fallback - Value returned when no name can be resolved.
+ *                   Defaults to `'Explorer'`.
+ * @returns The resolved first name string.
+ *
+ * @example
+ * ```ts
+ * // In a Svelte 5 component:
+ * const firstName = $derived(
+ *   resolveFirstName($authState.session, $authState.offlineProfile)
+ * );
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With a custom fallback:
+ * const greeting = resolveFirstName(session, offline, 'there');
+ * // → "Hey, there!" when no name is available
+ * ```
+ */
+export function resolveFirstName(session, offlineProfile, fallback = 'Explorer') {
+    /* ── Demo: use mock profile from config ── */
+    if (isDemoMode()) {
+        const config = getDemoConfig();
+        if (config?.mockProfile.firstName) {
+            return config.mockProfile.firstName;
+        }
+    }
+    /* ── Online: check session profile fields ── */
+    if (session?.user) {
+        const profile = getUserProfile(session.user);
+        if (profile.firstName || profile.first_name) {
+            return (profile.firstName || profile.first_name);
+        }
+        if (session.user.email) {
+            return session.user.email.split('@')[0];
+        }
+    }
+    /* ── Offline: check cached credential profile ── */
+    if (offlineProfile?.profile?.firstName) {
+        return offlineProfile.profile.firstName;
+    }
+    if (offlineProfile?.email) {
+        return offlineProfile.email.split('@')[0];
+    }
+    return fallback;
+}
+/**
+ * Resolve the current user's UUID from auth state.
+ *
+ * Checks the Supabase session first, then falls back to the offline
+ * credential cache. Returns an empty string when no user is authenticated.
+ *
+ * @param session - The current Supabase session, or `null`.
+ * @param offlineProfile - The cached offline credentials, or `null`.
+ * @returns The user's UUID, or `''` if unauthenticated.
+ *
+ * @example
+ * ```ts
+ * const userId = resolveUserId(data.session, data.offlineProfile);
+ * if (!userId) {
+ *   error = 'Not authenticated';
+ *   return;
+ * }
+ * ```
+ */
+export function resolveUserId(session, offlineProfile) {
+    /* ── Demo: return synthetic user ID ── */
+    if (isDemoMode()) {
+        return 'demo-user';
+    }
+    if (session?.user?.id) {
+        return session.user.id;
+    }
+    if (offlineProfile?.userId) {
+        return offlineProfile.userId;
+    }
+    return '';
+}
+/**
+ * Resolve a single uppercase initial letter for avatar display.
+ *
+ * Uses {@link resolveFirstName} to derive the name, then returns the
+ * first character uppercased. If the resolved name is empty, returns
+ * the `fallback` character.
+ *
+ * @param session - The current Supabase session, or `null`.
+ * @param offlineProfile - The cached offline credentials, or `null`.
+ * @param fallback - Character to use when no initial can be derived.
+ *                   Defaults to `'?'`.
+ * @returns A single uppercase character.
+ *
+ * @example
+ * ```svelte
+ * <span class="avatar">
+ *   {resolveAvatarInitial($authState.session, $authState.offlineProfile)}
+ * </span>
+ * ```
+ */
+export function resolveAvatarInitial(session, offlineProfile, fallback = '?') {
+    const name = resolveFirstName(session, offlineProfile, '');
+    if (name) {
+        return name.charAt(0).toUpperCase();
+    }
+    return fallback;
+}
+//# sourceMappingURL=displayUtils.js.map

package/dist/auth/displayUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"displayUtils.js","sourceRoot":"","sources":["../../src/auth/displayUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAEpD,gFAAgF;AAChF,aAAa;AACb,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAuB,EACvB,cAAyC,EACzC,WAAmB,UAAU;IAE7B,8CAA8C;IAC9C,IAAI,UAAU,EAAE,EAAE,CAAC;QACjB,MAAM,MAAM,GAAG,aAAa,EAAE,CAAC;QAC/B,IAAI,MAAM,EAAE,WAAW,CAAC,SAAS,EAAE,CAAC;YAClC,OAAO,MAAM,CAAC,WAAW,CAAC,SAAS,CAAC;QACtC,CAAC;IACH,CAAC;IAED,gDAAgD;IAChD,IAAI,OAAO,EAAE,IAAI,EAAE,CAAC;QAClB,MAAM,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC7C,IAAI,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;YAC5C,OAAO,CAAC,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC,UAAU,CAAW,CAAC;QAC7D,CAAC;QACD,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;YACvB,OAAO,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC;IAED,oDAAoD;IACpD,IAAI,cAAc,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;QACvC,OAAO,cAAc,CAAC,OAAO,CAAC,SAAmB,CAAC;IACpD,CAAC;IACD,IAAI,cAAc,EAAE,KAAK,EAAE,CAAC;QAC1B,OAAO,cAAc,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5C,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,aAAa,CAC3B,OAAuB,EACvB,cAAyC;IAEzC,0CAA0C;IAC1C,IAAI,UAAU,EAAE,EAAE,CAAC;QACjB,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,IAAI,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;QACtB,OAAO,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;IACzB,CAAC;IACD,IAAI,cAAc,EAAE,MAAM,EAAE,CAAC;QAC3B,OAAO,cAAc,CAAC,MAAM,CAAC;IAC/B,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAuB,EACvB,cAAyC,EACzC,WAAmB,GAAG;IAEtB,MAAM,IAAI,GAAG,gBAAgB,CAAC,OAAO,EAAE,cAAc,EAAE,EAAE,CAAC,CAAC;IAC3D,IAAI,IAAI,EAAE,CAAC;QACT,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IACtC,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/auth/loginGuard.d.ts

@@ -0,0 +1,134 @@
+/**
+ * @fileoverview Login Guard -- Local Credential Pre-Check & Rate Limiting
+ *
+ * Minimizes Supabase auth API requests by verifying credentials locally first.
+ * Only calls Supabase when the local hash matches (correct password) or when no
+ * local hash exists (with rate limiting).
+ *
+ * Architecture:
+ * - Maintains **in-memory-only** state (resets on page refresh) for failure
+ *   counters and rate-limit timers.
+ * - Two operational strategies:
+ *   1. `local-match`: A cached hash exists and the user's input matches it.
+ *      Proceed to Supabase for authoritative verification.
+ *   2. `no-cache`: No cached hash is available. Proceed to Supabase but apply
+ *      exponential backoff on repeated failures.
+ * - After a configurable number of consecutive local mismatches, the cached hash
+ *   is invalidated (it may be stale from a server-side password change) and the
+ *   guard falls back to rate-limited Supabase mode.
+ *
+ * Security considerations:
+ * - The guard is a **client-side optimization**, not a security boundary. It
+ *   reduces unnecessary network calls and provides a better UX (instant
+ *   rejection for wrong passwords) but Supabase remains the authoritative
+ *   verifier.
+ * - Rate limiting is in-memory only and resets on page refresh; server-side rate
+ *   limits in Supabase are still the primary defense against brute-force.
+ * - Cached hashes are SHA-256 digests stored in IndexedDB. They are invalidated
+ *   when stale-hash scenarios are detected (local match but Supabase rejects).
+ *
+ * @module auth/loginGuard
+ */
+/**
+ * Strategy used when proceeding to the Supabase auth call.
+ *
+ * - `'local-match'` -- The user's input matched a locally cached hash.
+ *   Supabase is called for authoritative confirmation.
+ * - `'no-cache'` -- No local hash was available (or it was invalidated).
+ *   Supabase is called directly, subject to rate limiting.
+ */
+export type PreCheckStrategy = 'local-match' | 'no-cache';
+/**
+ * Result of the local pre-check.
+ *
+ * - `proceed: true` -- The caller should continue with the Supabase auth call.
+ * - `proceed: false` -- The attempt was rejected locally; `error` contains a
+ *   user-facing message and `retryAfterMs` (if present) indicates how long
+ *   the user should wait.
+ */
+export type PreCheckResult = {
+    proceed: true;
+    strategy: PreCheckStrategy;
+} | {
+    proceed: false;
+    error: string;
+    retryAfterMs?: number;
+};
+/**
+ * Pre-check login credentials locally before calling Supabase.
+ *
+ * Reads `singleUserConfig.gateHash`, hashes input, and compares.
+ *
+ * Returns `{ proceed: true, strategy }` to allow Supabase call,
+ * or `{ proceed: false, error, retryAfterMs? }` to reject locally.
+ *
+ * @param input - The plaintext password or gate code entered by the user.
+ * @returns A promise resolving to a {@link PreCheckResult}.
+ *
+ * @example
+ * ```ts
+ * const result = await preCheckLogin(password);
+ * if (result.proceed) {
+ *   const { error } = await supabase.auth.signInWithPassword({ email, password });
+ *   if (error) await onLoginFailure(result.strategy);
+ *   else onLoginSuccess();
+ * } else {
+ *   showError(result.error);
+ * }
+ * ```
+ *
+ * @see {@link onLoginSuccess} -- must be called after a successful Supabase login.
+ * @see {@link onLoginFailure} -- must be called after a failed Supabase login.
+ */
+export declare function preCheckLogin(input: string): Promise<PreCheckResult>;
+/**
+ * Called after a successful Supabase login.
+ *
+ * Resets all login guard counters (local failure count, rate-limit attempts,
+ * and the next-allowed-attempt timestamp) so the user starts fresh.
+ *
+ * @example
+ * ```ts
+ * const { error } = await supabase.auth.signInWithPassword({ email, password });
+ * if (!error) onLoginSuccess();
+ * ```
+ */
+export declare function onLoginSuccess(): void;
+/**
+ * Called after a failed Supabase login.
+ *
+ * Behavior depends on the strategy that was used:
+ *
+ * - `'local-match'`: Supabase rejected a locally-matched password, meaning the
+ *   cached hash is **stale** (password changed server-side). The cached hash is
+ *   invalidated so future attempts go through rate-limited Supabase mode.
+ * - `'no-cache'`: Increment the rate-limit counter and apply exponential
+ *   backoff (base * 2^(n-1), capped at MAX_DELAY_MS).
+ *
+ * @param strategy - The {@link PreCheckStrategy} that was returned by
+ *                   {@link preCheckLogin} for this attempt.
+ *
+ * @example
+ * ```ts
+ * const result = await preCheckLogin(password);
+ * if (result.proceed) {
+ *   const { error } = await supabase.auth.signInWithPassword({ email, password });
+ *   if (error) await onLoginFailure(result.strategy);
+ * }
+ * ```
+ */
+export declare function onLoginFailure(strategy: PreCheckStrategy): Promise<void>;
+/**
+ * Full reset of all login guard state.
+ *
+ * Call on sign-out or app reset to clear failure counters and rate-limit
+ * timers so the next login attempt starts with a clean slate.
+ *
+ * @example
+ * ```ts
+ * await supabase.auth.signOut();
+ * resetLoginGuard();
+ * ```
+ */
+export declare function resetLoginGuard(): void;
+//# sourceMappingURL=loginGuard.d.ts.map

package/dist/auth/loginGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loginGuard.d.ts","sourceRoot":"","sources":["../../src/auth/loginGuard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAmDH;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GAAG,aAAa,GAAG,UAAU,CAAC;AAE1D;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,gBAAgB,CAAA;CAAE,GAC7C;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAoD7D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAuE1E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,IAAI,IAAI,CAKrC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,cAAc,CAAC,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiB9E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAKtC"}

package/dist/auth/loginGuard.js

@@ -0,0 +1,276 @@
+/**
+ * @fileoverview Login Guard -- Local Credential Pre-Check & Rate Limiting
+ *
+ * Minimizes Supabase auth API requests by verifying credentials locally first.
+ * Only calls Supabase when the local hash matches (correct password) or when no
+ * local hash exists (with rate limiting).
+ *
+ * Architecture:
+ * - Maintains **in-memory-only** state (resets on page refresh) for failure
+ *   counters and rate-limit timers.
+ * - Two operational strategies:
+ *   1. `local-match`: A cached hash exists and the user's input matches it.
+ *      Proceed to Supabase for authoritative verification.
+ *   2. `no-cache`: No cached hash is available. Proceed to Supabase but apply
+ *      exponential backoff on repeated failures.
+ * - After a configurable number of consecutive local mismatches, the cached hash
+ *   is invalidated (it may be stale from a server-side password change) and the
+ *   guard falls back to rate-limited Supabase mode.
+ *
+ * Security considerations:
+ * - The guard is a **client-side optimization**, not a security boundary. It
+ *   reduces unnecessary network calls and provides a better UX (instant
+ *   rejection for wrong passwords) but Supabase remains the authoritative
+ *   verifier.
+ * - Rate limiting is in-memory only and resets on page refresh; server-side rate
+ *   limits in Supabase are still the primary defense against brute-force.
+ * - Cached hashes are SHA-256 digests stored in IndexedDB. They are invalidated
+ *   when stale-hash scenarios are detected (local match but Supabase rejects).
+ *
+ * @module auth/loginGuard
+ */
+import { hashValue } from './crypto';
+import { getEngineConfig } from '../config';
+import { debugLog, debugWarn } from '../debug';
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+/**
+ * Number of consecutive local hash mismatches before the cached hash is
+ * invalidated. Prevents a permanently stale hash from locking out the user.
+ */
+const LOCAL_FAILURE_THRESHOLD = 5;
+/** Base delay (in milliseconds) for the first rate-limited retry. */
+const BASE_DELAY_MS = 1000;
+/** Maximum delay cap (in milliseconds) to prevent absurdly long waits. */
+const MAX_DELAY_MS = 30000;
+/** Multiplier for exponential backoff between rate-limited attempts. */
+const BACKOFF_MULTIPLIER = 2;
+// =============================================================================
+// IN-MEMORY STATE
+// =============================================================================
+/**
+ * Tracks how many times the local hash comparison has failed consecutively.
+ * Once this reaches `LOCAL_FAILURE_THRESHOLD`, the cached hash is invalidated.
+ */
+let consecutiveLocalFailures = 0;
+/**
+ * Number of failed Supabase login attempts in no-cache mode. Used to compute
+ * the exponential backoff delay.
+ */
+let rateLimitAttempts = 0;
+/**
+ * Timestamp (ms since epoch) before which the next login attempt is blocked.
+ * Zero means no rate limit is active.
+ */
+let nextAllowedAttempt = 0;
+// =============================================================================
+// INTERNAL HELPERS
+// =============================================================================
+/**
+ * Check whether the current rate-limit window allows a new attempt.
+ *
+ * @returns An object indicating whether the attempt is allowed, and if not,
+ *          how many milliseconds remain until the next allowed attempt.
+ */
+function checkRateLimit() {
+    const now = Date.now();
+    if (nextAllowedAttempt > now) {
+        return { allowed: false, retryAfterMs: nextAllowedAttempt - now };
+    }
+    return { allowed: true };
+}
+/**
+ * Invalidate the locally cached gate hash in IndexedDB.
+ *
+ * Called when the guard determines the cached hash is stale (e.g., the user
+ * changed their PIN on another device, or too many consecutive local
+ * mismatches have occurred).
+ *
+ * @throws Never -- errors are caught and logged via `debugWarn`.
+ */
+async function invalidateCachedHash() {
+    try {
+        const config = getEngineConfig();
+        const db = config.db;
+        if (db) {
+            const record = await db.table('singleUserConfig').get('config');
+            if (record && record.gateHash) {
+                await db.table('singleUserConfig').update('config', {
+                    gateHash: undefined,
+                    updatedAt: new Date().toISOString()
+                });
+                debugLog('[LoginGuard] Invalidated single-user gateHash');
+            }
+        }
+    }
+    catch (e) {
+        debugWarn('[LoginGuard] Failed to invalidate cached hash:', e);
+    }
+}
+// =============================================================================
+// PUBLIC API
+// =============================================================================
+/**
+ * Pre-check login credentials locally before calling Supabase.
+ *
+ * Reads `singleUserConfig.gateHash`, hashes input, and compares.
+ *
+ * Returns `{ proceed: true, strategy }` to allow Supabase call,
+ * or `{ proceed: false, error, retryAfterMs? }` to reject locally.
+ *
+ * @param input - The plaintext password or gate code entered by the user.
+ * @returns A promise resolving to a {@link PreCheckResult}.
+ *
+ * @example
+ * ```ts
+ * const result = await preCheckLogin(password);
+ * if (result.proceed) {
+ *   const { error } = await supabase.auth.signInWithPassword({ email, password });
+ *   if (error) await onLoginFailure(result.strategy);
+ *   else onLoginSuccess();
+ * } else {
+ *   showError(result.error);
+ * }
+ * ```
+ *
+ * @see {@link onLoginSuccess} -- must be called after a successful Supabase login.
+ * @see {@link onLoginFailure} -- must be called after a failed Supabase login.
+ */
+export async function preCheckLogin(input) {
+    try {
+        let cachedHash;
+        const config = getEngineConfig();
+        const db = config.db;
+        if (db) {
+            const record = await db.table('singleUserConfig').get('config');
+            cachedHash = record?.gateHash;
+        }
+        if (cachedHash) {
+            /* We have a cached hash -- compare locally before touching the network. */
+            const inputHash = await hashValue(input);
+            if (inputHash === cachedHash) {
+                /* Local match -- proceed to Supabase for authoritative verification.
+                   We never trust the local hash alone because it could be stale. */
+                debugLog('[LoginGuard] Local hash match, proceeding to Supabase');
+                return { proceed: true, strategy: 'local-match' };
+            }
+            /* Mismatch -- reject locally to avoid a needless Supabase round-trip. */
+            consecutiveLocalFailures++;
+            debugWarn(`[LoginGuard] Local hash mismatch (${consecutiveLocalFailures}/${LOCAL_FAILURE_THRESHOLD})`);
+            if (consecutiveLocalFailures >= LOCAL_FAILURE_THRESHOLD) {
+                /* Threshold exceeded -- the cached hash may be stale (password changed
+                   on another device). Invalidate it so subsequent attempts go directly
+                   to Supabase in rate-limited mode. */
+                debugWarn('[LoginGuard] Threshold exceeded, invalidating cached hash');
+                await invalidateCachedHash();
+                consecutiveLocalFailures = 0;
+                /* Fall through to rate-limited Supabase mode */
+                const rateCheck = checkRateLimit();
+                if (!rateCheck.allowed) {
+                    return {
+                        proceed: false,
+                        error: 'Too many attempts. Please wait before trying again.',
+                        retryAfterMs: rateCheck.retryAfterMs
+                    };
+                }
+                return { proceed: true, strategy: 'no-cache' };
+            }
+            return { proceed: false, error: 'Incorrect password or code' };
+        }
+        /* No cached hash -- rate-limited Supabase mode */
+        const rateCheck = checkRateLimit();
+        if (!rateCheck.allowed) {
+            return {
+                proceed: false,
+                error: 'Too many attempts. Please wait before trying again.',
+                retryAfterMs: rateCheck.retryAfterMs
+            };
+        }
+        debugLog('[LoginGuard] No cached hash, proceeding to Supabase (rate-limited mode)');
+        return { proceed: true, strategy: 'no-cache' };
+    }
+    catch (e) {
+        /* On any error, allow Supabase call (fail open for auth). A strict
+           "fail closed" policy here would lock users out of their own app
+           due to an IndexedDB read error. */
+        debugWarn('[LoginGuard] Pre-check error, falling through to Supabase:', e);
+        return { proceed: true, strategy: 'no-cache' };
+    }
+}
+/**
+ * Called after a successful Supabase login.
+ *
+ * Resets all login guard counters (local failure count, rate-limit attempts,
+ * and the next-allowed-attempt timestamp) so the user starts fresh.
+ *
+ * @example
+ * ```ts
+ * const { error } = await supabase.auth.signInWithPassword({ email, password });
+ * if (!error) onLoginSuccess();
+ * ```
+ */
+export function onLoginSuccess() {
+    consecutiveLocalFailures = 0;
+    rateLimitAttempts = 0;
+    nextAllowedAttempt = 0;
+    debugLog('[LoginGuard] Login success, counters reset');
+}
+/**
+ * Called after a failed Supabase login.
+ *
+ * Behavior depends on the strategy that was used:
+ *
+ * - `'local-match'`: Supabase rejected a locally-matched password, meaning the
+ *   cached hash is **stale** (password changed server-side). The cached hash is
+ *   invalidated so future attempts go through rate-limited Supabase mode.
+ * - `'no-cache'`: Increment the rate-limit counter and apply exponential
+ *   backoff (base * 2^(n-1), capped at MAX_DELAY_MS).
+ *
+ * @param strategy - The {@link PreCheckStrategy} that was returned by
+ *                   {@link preCheckLogin} for this attempt.
+ *
+ * @example
+ * ```ts
+ * const result = await preCheckLogin(password);
+ * if (result.proceed) {
+ *   const { error } = await supabase.auth.signInWithPassword({ email, password });
+ *   if (error) await onLoginFailure(result.strategy);
+ * }
+ * ```
+ */
+export async function onLoginFailure(strategy) {
+    if (strategy === 'local-match') {
+        /* Stale hash: local match but Supabase rejected -- invalidate the cache
+           so the user is not stuck in a loop of false local matches. */
+        debugWarn('[LoginGuard] Stale hash detected, invalidating cached hash');
+        await invalidateCachedHash();
+    }
+    else {
+        /* No-cache mode: apply exponential backoff to throttle brute-force
+           attempts that bypass the local pre-check. */
+        rateLimitAttempts++;
+        const delay = Math.min(BASE_DELAY_MS * Math.pow(BACKOFF_MULTIPLIER, rateLimitAttempts - 1), MAX_DELAY_MS);
+        nextAllowedAttempt = Date.now() + delay;
+        debugWarn(`[LoginGuard] Rate limit applied: ${delay}ms delay (attempt ${rateLimitAttempts})`);
+    }
+}
+/**
+ * Full reset of all login guard state.
+ *
+ * Call on sign-out or app reset to clear failure counters and rate-limit
+ * timers so the next login attempt starts with a clean slate.
+ *
+ * @example
+ * ```ts
+ * await supabase.auth.signOut();
+ * resetLoginGuard();
+ * ```
+ */
+export function resetLoginGuard() {
+    consecutiveLocalFailures = 0;
+    rateLimitAttempts = 0;
+    nextAllowedAttempt = 0;
+    debugLog('[LoginGuard] Guard reset');
+}
+//# sourceMappingURL=loginGuard.js.map

package/dist/auth/loginGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loginGuard.js","sourceRoot":"","sources":["../../src/auth/loginGuard.ts"],"names":[],"mappings":"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"}

package/dist/auth/offlineCredentials.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @fileoverview Offline Credentials Management
+ *
+ * Handles caching, retrieval, and update of user credentials in IndexedDB
+ * for offline fallback support. When the user successfully authenticates
+ * online via Supabase, their credentials are cached locally (with the
+ * password SHA-256-hashed) so profile data is available while offline.
+ *
+ * Architecture:
+ * - Credentials are stored as a singleton record (key: `'current_user'`) in the
+ *   `offlineCredentials` IndexedDB table.
+ * - Only one set of credentials is cached at a time.
+ * - The profile blob is extracted via the host app's `profileExtractor` config
+ *   callback, or falls back to raw Supabase `user_metadata`.
+ *
+ * Security considerations:
+ * - Passwords are **always** hashed with SHA-256 before storage. The plaintext
+ *   password is never persisted.
+ * - New writes always hash the password before storage.
+ * - A paranoid read-back verification is performed after `cacheOfflineCredentials`
+ *   to ensure the password was actually persisted (guards against silent
+ *   IndexedDB write failures).
+ * - Credentials are cleared on logout via `clearOfflineCredentials`.
+ *
+ * @module auth/offlineCredentials
+ */
+import type { OfflineCredentials } from '../types';
+import type { User, Session } from '@supabase/supabase-js';
+/**
+ * Cache user credentials for offline login.
+ *
+ * Called after a successful Supabase login to persist a hashed copy of the
+ * user's credentials in IndexedDB. Subsequent offline logins will verify
+ * against these cached credentials.
+ *
+ * @param email    - The user's email address (used for offline identity matching).
+ * @param password - The user's plaintext password. Will be SHA-256-hashed before storage.
+ * @param user     - The Supabase `User` object, used to extract `userId` and profile data.
+ * @param _session - The Supabase `Session` object. Currently unused but accepted for
+ *                   API symmetry with the online auth flow (reserved for future use).
+ *
+ * @throws {Error} If `email` or `password` is empty (prevents storing incomplete credentials).
+ * @throws {Error} If the write-back verification fails (password not persisted in IndexedDB).
+ *
+ * @example
+ * ```ts
+ * const { data } = await supabase.auth.signInWithPassword({ email, password });
+ * if (data.user && data.session) {
+ *   await cacheOfflineCredentials(email, password, data.user, data.session);
+ * }
+ * ```
+ *
+ * @see {@link getOfflineCredentials} to retrieve the cached credentials.
+ * @see {@link clearOfflineCredentials} to remove them on logout.
+ */
+export declare function cacheOfflineCredentials(email: string, password: string, user: User, _session: Session): Promise<void>;
+/**
+ * Get cached offline credentials from IndexedDB.
+ *
+ * Returns the singleton `OfflineCredentials` record, or `null` if no
+ * credentials have been cached (e.g., user has never logged in online
+ * on this device).
+ *
+ * @returns The cached credentials, or `null` if none exist.
+ *
+ * @example
+ * ```ts
+ * const creds = await getOfflineCredentials();
+ * if (creds) {
+ *   console.log('Cached user:', creds.email);
+ * }
+ * ```
+ */
+export declare function getOfflineCredentials(): Promise<OfflineCredentials | null>;
+/**
+ * Update the user profile in cached credentials after an online profile update.
+ *
+ * Replaces the entire `profile` blob with the provided object and updates
+ * the `cachedAt` timestamp.
+ *
+ * @param profile - The new profile data to cache (e.g., `{ firstName, lastName, avatar }`).
+ *
+ * @example
+ * ```ts
+ * await supabase.auth.updateUser({ data: { firstName: 'Jane' } });
+ * await updateOfflineCredentialsProfile({ firstName: 'Jane', lastName: 'Doe' });
+ * ```
+ */
+export declare function updateOfflineCredentialsProfile(profile: Record<string, unknown>): Promise<void>;
+/**
+ * Clear all cached offline credentials from IndexedDB.
+ *
+ * Must be called on logout to ensure no stale credentials remain on the
+ * device that could be used for unauthorized offline access.
+ *
+ * @example
+ * ```ts
+ * await supabase.auth.signOut();
+ * await clearOfflineCredentials();
+ * ```
+ *
+ * @see {@link cacheOfflineCredentials} for storing credentials on login.
+ */
+export declare function clearOfflineCredentials(): Promise<void>;
+//# sourceMappingURL=offlineCredentials.d.ts.map