stellar-drive 1.0.0

package/dist/auth/resolveAuthState.js

@@ -0,0 +1,249 @@
+/**
+ * @fileoverview Auth State Resolution
+ *
+ * Determines the current authentication state for single-user mode by checking
+ * Supabase session, offline session, and cached credentials. Used by app layouts
+ * and route guards to determine whether the user is authenticated and in which
+ * mode (online Supabase session vs. offline cached session).
+ *
+ * Architecture:
+ * - Requires `auth.singleUser` to be configured in the engine config.
+ *   If not configured, returns `authMode: 'none'` immediately.
+ * - Checks local `singleUserConfig` in IndexedDB, handles legacy migration,
+ *   PIN length migration, session refresh, and offline fallback.
+ * - The resolver does NOT start the sync engine -- callers decide whether to
+ *   start sync based on the returned `authMode`.
+ * - On catastrophic failure (corrupted auth state), all Supabase localStorage
+ *   keys (`sb-*`) are purged and `authMode: 'none'` is returned, ensuring the
+ *   user can start fresh rather than being permanently locked out.
+ *
+ * Security considerations:
+ * - In single-user mode, legacy configs without an email (from the anonymous
+ *   auth era) are nuked entirely -- anonymous data is inaccessible under
+ *   ownership-based RLS anyway.
+ * - The `singleUserConfig` table has been moved to IndexedDB + Supabase
+ *   `user_metadata`; there is no longer a Supabase `single_user_config` table.
+ * - Session refresh is attempted for expired single-user sessions before
+ *   falling back to the PIN gate, preventing unnecessary re-authentication
+ *   when only the access token (not the refresh token) has expired.
+ *
+ * @module auth/resolveAuthState
+ */
+import { getSession, isSessionExpired } from '../supabase/auth';
+import { getValidOfflineSession } from './offlineSession';
+import { resetSingleUserRemote } from './singleUser';
+import { getEngineConfig, waitForDb } from '../config';
+import { supabase } from '../supabase/client';
+import { debugLog, debugWarn, debugError } from '../debug';
+import { isDemoMode } from '../demo';
+// =============================================================================
+// PUBLIC API
+// =============================================================================
+/**
+ * Resolve the current authentication state.
+ *
+ * Requires `auth.singleUser` to be configured. Delegates to
+ * {@link resolveSingleUserAuthState} for the full resolution flow.
+ * If single-user mode is not configured, returns `authMode: 'none'`.
+ *
+ * Handles corrupted state cleanup by purging `sb-*` localStorage keys if
+ * session retrieval throws.
+ *
+ * @returns A promise resolving to an {@link AuthStateResult} describing the
+ *          current auth mode, session, and offline profile (if applicable).
+ *
+ * @example
+ * ```ts
+ * const { authMode, session, singleUserSetUp } = await resolveAuthState();
+ * if (authMode === 'supabase') {
+ *   startSyncEngine(session);
+ * } else if (authMode === 'offline') {
+ *   enterOfflineMode();
+ * } else {
+ *   redirectToLogin();
+ * }
+ * ```
+ *
+ * @see {@link AuthStateResult} for the return type shape.
+ */
+export async function resolveAuthState() {
+    /* Demo mode short-circuit: skip all real auth resolution. */
+    if (isDemoMode()) {
+        return { session: null, authMode: 'demo', offlineProfile: null, singleUserSetUp: true };
+    }
+    try {
+        /* Ensure DB is open and upgraded before any IndexedDB access.
+           This is critical during cold start when the DB may still be initializing. */
+        await waitForDb();
+        const engineConfig = getEngineConfig();
+        if (engineConfig.auth?.singleUser) {
+            return resolveSingleUserAuthState();
+        }
+        /* Single-user mode not configured -- no auth available. */
+        return { session: null, authMode: 'none', offlineProfile: null };
+    }
+    catch (e) {
+        /* Catastrophic failure: session retrieval threw (corrupted auth state).
+           Clear all Supabase auth data from localStorage so the user can start
+           fresh rather than being permanently locked out. */
+        debugError('[Auth] Failed to resolve auth state, clearing auth storage:', e);
+        try {
+            if (typeof localStorage !== 'undefined') {
+                const keys = Object.keys(localStorage).filter((k) => k.startsWith('sb-'));
+                keys.forEach((k) => localStorage.removeItem(k));
+            }
+        }
+        catch {
+            /* Ignore storage errors -- we are already in error recovery. */
+        }
+        return { session: null, authMode: 'none', offlineProfile: null };
+    }
+}
+// =============================================================================
+// INTERNAL -- Single-User Mode Resolution
+// =============================================================================
+/**
+ * Resolve auth state for single-user mode.
+ *
+ * Handles the following scenarios in order:
+ *
+ * 1. **No local config**: User has not set up on this device.
+ *    Returns `authMode: 'none'`, `singleUserSetUp: false`.
+ *
+ * 2. **Legacy config without email**: Config from the anonymous auth era.
+ *    Nukes all local auth artifacts and returns `singleUserSetUp: false`.
+ *
+ * 3. **Code-length migration**: The engine config specifies a different PIN
+ *    length than what is stored locally. Resets remote and local state, forcing
+ *    re-setup with the new PIN length.
+ *
+ * 4. **Valid Supabase session**: Returns `authMode: 'supabase'`, `singleUserSetUp: true`.
+ *
+ * 5. **Expired session with valid refresh token**: Attempts token refresh.
+ *    On success, returns `authMode: 'supabase'`. On failure, falls through.
+ *
+ * 6. **Offline with cached session**: Even an expired Supabase session is usable
+ *    offline (RLS is not enforced client-side).
+ *    Returns `authMode: 'supabase'`, `singleUserSetUp: true`.
+ *
+ * 7. **Offline with offline session**: Falls back to offline credentials.
+ *    Returns `authMode: 'offline'`, `singleUserSetUp: true`.
+ *
+ * 8. **No valid session (locked)**: User must re-enter their PIN.
+ *    Returns `authMode: 'none'`, `singleUserSetUp: true`.
+ *
+ * @returns A promise resolving to an {@link AuthStateResult} with the
+ *          `singleUserSetUp` field populated.
+ */
+async function resolveSingleUserAuthState() {
+    try {
+        const db = getEngineConfig().db;
+        if (!db) {
+            return { session: null, authMode: 'none', offlineProfile: null, singleUserSetUp: false };
+        }
+        const config = (await db.table('singleUserConfig').get('config'));
+        if (!config) {
+            /* No local config -- user has not set up on this device.
+               With real email/password auth, new devices go through the login flow
+               (email + PIN) which creates the local config after signInWithPassword. */
+            return { session: null, authMode: 'none', offlineProfile: null, singleUserSetUp: false };
+        }
+        if (!config.email) {
+            /* Config without email is invalid — user needs to go through setup. */
+            return { session: null, authMode: 'none', offlineProfile: null, singleUserSetUp: false };
+        }
+        /* codeLength migration: if the engine config specifies a different PIN length
+           than what is stored locally, the user must re-setup. This handles the case
+           where the app developer changes the codeLength in their engine config. */
+        const expectedCodeLength = getEngineConfig().auth?.singleUser?.codeLength;
+        const storedCodeLength = config.codeLength;
+        if (expectedCodeLength && storedCodeLength !== expectedCodeLength) {
+            debugLog('[Auth] codeLength mismatch detected:', storedCodeLength, '→', expectedCodeLength);
+            try {
+                await resetSingleUserRemote();
+            }
+            catch (e) {
+                debugWarn('[Auth] Failed to reset remote single user:', e);
+            }
+            /* Sign out to kill in-memory and persisted Supabase session. */
+            try {
+                await supabase.auth.signOut();
+            }
+            catch {
+                /* Ignore -- session may already be cleared by resetSingleUserRemote. */
+            }
+            /* Clear local state so the setup flow starts fresh. */
+            try {
+                await db.table('singleUserConfig').delete('config');
+                await db.table('offlineCredentials').delete('current_user');
+                await db.table('offlineSession').delete('current_session');
+            }
+            catch (e) {
+                debugWarn('[Auth] Failed to clear local auth state:', e);
+            }
+            return { session: null, authMode: 'none', offlineProfile: null, singleUserSetUp: false };
+        }
+        // =========================================================================
+        // Config exists -- check for an active session
+        // =========================================================================
+        let session = await getSession();
+        /* If the access token is expired, try refreshing before giving up.
+           Refresh tokens outlive the access token -- without this, users are forced
+           to re-enter their PIN on every page load once the access token expires
+           (default Supabase access token lifetime: 1 hour). */
+        if (session && isSessionExpired(session)) {
+            debugLog('[Auth] Single-user session expired, attempting refresh...');
+            try {
+                const { data, error } = await supabase.auth.refreshSession();
+                if (!error && data.session) {
+                    session = data.session;
+                    debugLog('[Auth] Single-user session refreshed successfully');
+                }
+                else {
+                    debugWarn('[Auth] Single-user session refresh failed:', error?.message);
+                    session = null;
+                }
+            }
+            catch {
+                session = null;
+            }
+        }
+        const hasValidSession = session && !isSessionExpired(session);
+        if (hasValidSession) {
+            return { session, authMode: 'supabase', offlineProfile: null, singleUserSetUp: true };
+        }
+        // =========================================================================
+        // No valid online session -- check offline fallbacks
+        // =========================================================================
+        const isOffline = typeof navigator !== 'undefined' && !navigator.onLine;
+        if (isOffline) {
+            /* Even an expired cached Supabase session is usable offline because RLS
+               is not enforced on the client side -- it only matters when syncing. */
+            if (session) {
+                return { session, authMode: 'supabase', offlineProfile: null, singleUserSetUp: true };
+            }
+            const offlineSession = await getValidOfflineSession();
+            if (offlineSession) {
+                /* Construct an OfflineCredentials-shaped object from the local config
+                   so the caller has profile data available for the offline UI. */
+                const offlineProfile = {
+                    id: 'current_user',
+                    userId: offlineSession.userId,
+                    email: config.email || '',
+                    password: config.gateHash || '',
+                    profile: config.profile,
+                    cachedAt: new Date().toISOString()
+                };
+                return { session: null, authMode: 'offline', offlineProfile, singleUserSetUp: true };
+            }
+        }
+        /* No valid session -- the single-user app is "locked" and the user must
+           re-enter their PIN to unlock. */
+        return { session: null, authMode: 'none', offlineProfile: null, singleUserSetUp: true };
+    }
+    catch (e) {
+        debugError('[Auth] Failed to resolve single-user auth state:', e);
+        return { session: null, authMode: 'none', offlineProfile: null, singleUserSetUp: false };
+    }
+}
+//# sourceMappingURL=resolveAuthState.js.map

package/dist/auth/resolveAuthState.js.map

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