local-lite 0.0.11 → 0.0.12

package/README.md

@@ -87,6 +87,8 @@ This recovers sync state; it does not repair corrupt SQLite files or cancel hung
 * **📶 Network-Aware:** Automatically pauses polling when offline and triggers immediate sync flushes the instant connectivity is restored.
 * **🔄 Infinite-Loop Safe:** Incoming remote deltas update local tables and fire reactive UI listeners without echoing back into the outbox.
 * **☁️ Database Backups:** Export and restore SQLite snapshots independently of your live sync backend.
+* **🔑 Google Sign-In Out of the Box:** Secure, zero-backend Google OAuth 2.0 (PKCE) authentication with automatic token refresh, user profile retrieval, persistent session storage, and `useGoogleAuth()` hook.
+
 
 ---
 
@@ -244,8 +246,50 @@ export function TodoScreen() {
 }
 ```
 
+### 3. Google Sign-In (Out of the Box)
+
+`local-lite` provides a zero-backend, PKCE-secured Google OAuth 2.0 client with automatic token refreshing, user profile retrieval, and React hooks.
+
+```tsx
+import * as WebBrowser from 'expo-web-browser';
+import * as Linking from 'expo-linking';
+import { GoogleAuthClient } from 'local-lite/auth';
+import { useGoogleAuth } from 'local-lite/react';
+
+const googleAuth = new GoogleAuthClient({
+  clientId: 'YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com',
+  redirectUri: Linking.createURL('oauth'),
+  authorize: async ({ authorizationUrl, redirectUri }) => {
+    const res = await WebBrowser.openAuthSessionAsync(authorizationUrl, redirectUri);
+    if (res.type !== 'success' || !res.url) return null;
+    const url = new URL(res.url);
+    return {
+      code: url.searchParams.get('code') || '',
+      state: url.searchParams.get('state') || '',
+    };
+  },
+});
+
+export function UserProfileHeader() {
+  const { user, isSignedIn, loading, signIn, signOut } = useGoogleAuth(googleAuth);
+
+  if (loading) return <Text>Loading...</Text>;
+  if (!isSignedIn) {
+    return <Button title="Sign in with Google" onPress={signIn} />;
+  }
+
+  return (
+    <View>
+      <Text>Welcome, {user?.name} ({user?.email})</Text>
+      <Button title="Sign Out" onPress={signOut} />
+    </View>
+  );
+}
+```
+
 ---
 
+
 ## Supabase Backend Setup & Schema
 
 To synchronize with Supabase using zero-clock-skew delta queries and `deleted: true` soft deletes, execute the following script in your Supabase project (**Dashboard → SQL Editor**):

package/dist/auth/google.d.ts

@@ -0,0 +1,75 @@
+import { GoogleDriveBackupStorage } from '../backups/cloud-storage.js';
+export declare const GOOGLE_AUTHORIZATION_ENDPOINT = "https://accounts.google.com/o/oauth2/v2/auth";
+export declare const GOOGLE_TOKEN_ENDPOINT = "https://oauth2.googleapis.com/token";
+export declare const GOOGLE_USERINFO_ENDPOINT = "https://www.googleapis.com/oauth2/v3/userinfo";
+export declare const DEFAULT_GOOGLE_AUTH_SCOPES: string[];
+export interface GoogleUser {
+    id: string;
+    email: string;
+    emailVerified: boolean;
+    name: string;
+    givenName?: string;
+    familyName?: string;
+    picture?: string;
+    locale?: string;
+}
+export interface GoogleAuthTokens {
+    accessToken: string;
+    refreshToken?: string;
+    idToken?: string;
+    expiresAt: number;
+    tokenType?: string;
+    scope?: string;
+}
+export interface GoogleAuthTokenStore {
+    getTokens(): Promise<GoogleAuthTokens | null>;
+    setTokens(tokens: GoogleAuthTokens): Promise<void>;
+    removeTokens(): Promise<void>;
+    getUser(): Promise<GoogleUser | null>;
+    setUser(user: GoogleUser | null): Promise<void>;
+}
+export interface GoogleAuthKeyValueStorage {
+    getItem(key: string): Promise<unknown>;
+    setItem(key: string, value: unknown): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+export interface GoogleAuthorizationRequest {
+    authorizationUrl: string;
+    redirectUri: string;
+    state: string;
+}
+export interface GoogleAuthorizationResponse {
+    code: string;
+    state: string;
+}
+export interface GoogleAuthClientOptions {
+    clientId: string;
+    redirectUri: string;
+    scopes?: string[];
+    authorize: (request: GoogleAuthorizationRequest) => Promise<GoogleAuthorizationResponse | null>;
+    tokenStore?: GoogleAuthTokenStore;
+    storage?: GoogleAuthKeyValueStorage;
+    randomBytes?: (length: number) => Uint8Array;
+    fetch?: typeof fetch;
+    prompt?: 'consent' | 'select_account' | 'none';
+    accessType?: 'offline' | 'online';
+}
+export declare function createInMemoryGoogleTokenStore(): GoogleAuthTokenStore;
+export declare function createGoogleAuthTokenStore(storage: GoogleAuthKeyValueStorage, prefix?: string): GoogleAuthTokenStore;
+export declare class GoogleAuthClient {
+    private readonly options;
+    private readonly tokenStore;
+    private readonly fetcher;
+    private readonly listeners;
+    private currentUser;
+    constructor(options: GoogleAuthClientOptions);
+    onAuthStateChange(listener: (user: GoogleUser | null) => void): () => void;
+    private notify;
+    signIn(): Promise<GoogleUser | null>;
+    signOut(): Promise<void>;
+    isSignedIn(): Promise<boolean>;
+    getUser(): Promise<GoogleUser | null>;
+    getValidAccessToken(): Promise<string>;
+    private fetchUserProfile;
+    createDriveBackupStorage(): GoogleDriveBackupStorage;
+}

package/dist/auth/google.js

@@ -0,0 +1,323 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GoogleAuthClient = exports.DEFAULT_GOOGLE_AUTH_SCOPES = exports.GOOGLE_USERINFO_ENDPOINT = exports.GOOGLE_TOKEN_ENDPOINT = exports.GOOGLE_AUTHORIZATION_ENDPOINT = void 0;
+exports.createInMemoryGoogleTokenStore = createInMemoryGoogleTokenStore;
+exports.createGoogleAuthTokenStore = createGoogleAuthTokenStore;
+const sha2_js_1 = require("@noble/hashes/sha2.js");
+const utils_js_1 = require("@noble/hashes/utils.js");
+const cloud_storage_js_1 = require("../backups/cloud-storage.js");
+exports.GOOGLE_AUTHORIZATION_ENDPOINT = 'https://accounts.google.com/o/oauth2/v2/auth';
+exports.GOOGLE_TOKEN_ENDPOINT = 'https://oauth2.googleapis.com/token';
+exports.GOOGLE_USERINFO_ENDPOINT = 'https://www.googleapis.com/oauth2/v3/userinfo';
+exports.DEFAULT_GOOGLE_AUTH_SCOPES = ['openid', 'email', 'profile'];
+function secureRandomBytes(length) {
+    const crypto = globalThis.crypto;
+    if (!crypto?.getRandomValues) {
+        throw new Error('Secure random number generation is unavailable.');
+    }
+    return crypto.getRandomValues(new Uint8Array(length));
+}
+function base64UrlEncode(bytes) {
+    const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+    let result = '';
+    for (let index = 0; index < bytes.length; index += 3) {
+        const first = bytes[index];
+        const second = bytes[index + 1];
+        const third = bytes[index + 2];
+        result += alphabet[first >> 2];
+        result += alphabet[((first & 3) << 4) | (second === undefined ? 0 : second >> 4)];
+        if (second !== undefined) {
+            result += alphabet[((second & 15) << 2) | (third === undefined ? 0 : third >> 6)];
+        }
+        if (third !== undefined)
+            result += alphabet[third & 63];
+    }
+    return result;
+}
+function validateTokens(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const tokens = value;
+    return (typeof tokens.accessToken === 'string' &&
+        typeof tokens.expiresAt === 'number' &&
+        (tokens.refreshToken === undefined || typeof tokens.refreshToken === 'string') &&
+        (tokens.idToken === undefined || typeof tokens.idToken === 'string'));
+}
+function validateUser(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const user = value;
+    return (typeof user.id === 'string' &&
+        typeof user.email === 'string' &&
+        typeof user.name === 'string');
+}
+function createInMemoryGoogleTokenStore() {
+    let storedTokens = null;
+    let storedUser = null;
+    return {
+        getTokens: async () => storedTokens,
+        setTokens: async (tokens) => {
+            storedTokens = tokens;
+        },
+        removeTokens: async () => {
+            storedTokens = null;
+        },
+        getUser: async () => storedUser,
+        setUser: async (user) => {
+            storedUser = user;
+        },
+    };
+}
+function createGoogleAuthTokenStore(storage, prefix = 'local-lite-google-auth') {
+    const tokensKey = `${prefix}-tokens`;
+    const userKey = `${prefix}-user`;
+    return {
+        getTokens: async () => {
+            const raw = await storage.getItem(tokensKey);
+            return validateTokens(raw) ? raw : null;
+        },
+        setTokens: tokens => storage.setItem(tokensKey, tokens),
+        removeTokens: () => storage.removeItem(tokensKey),
+        getUser: async () => {
+            const raw = await storage.getItem(userKey);
+            return validateUser(raw) ? raw : null;
+        },
+        setUser: async (user) => {
+            if (user) {
+                await storage.setItem(userKey, user);
+            }
+            else {
+                await storage.removeItem(userKey);
+            }
+        },
+    };
+}
+async function parseTokenResponse(response) {
+    try {
+        return (await response.json());
+    }
+    catch {
+        throw new Error(`Google OAuth request failed (${response.status}).`);
+    }
+}
+function throwOAuthError(payload, status) {
+    throw new Error(payload.error_description ||
+        payload.error ||
+        `Google OAuth request failed (${status}).`);
+}
+class GoogleAuthClient {
+    options;
+    tokenStore;
+    fetcher;
+    listeners = new Set();
+    currentUser = null;
+    constructor(options) {
+        this.options = options;
+        if (!options.clientId?.trim()) {
+            throw new Error('Google OAuth client ID is required.');
+        }
+        if (!options.redirectUri?.trim()) {
+            throw new Error('Google OAuth redirect URI is required.');
+        }
+        this.fetcher = options.fetch ?? fetch;
+        if (options.tokenStore) {
+            this.tokenStore = options.tokenStore;
+        }
+        else if (options.storage) {
+            this.tokenStore = createGoogleAuthTokenStore(options.storage);
+        }
+        else {
+            this.tokenStore = createInMemoryGoogleTokenStore();
+        }
+    }
+    onAuthStateChange(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    notify(user) {
+        this.currentUser = user;
+        for (const listener of this.listeners) {
+            try {
+                listener(user);
+            }
+            catch (err) {
+                console.error('Error in GoogleAuthClient auth listener:', err);
+            }
+        }
+    }
+    async signIn() {
+        const randomBytes = this.options.randomBytes ?? secureRandomBytes;
+        const verifierBytes = randomBytes(32);
+        const stateBytes = randomBytes(32);
+        if (verifierBytes.length !== 32 || stateBytes.length !== 32) {
+            throw new Error('The randomBytes provider returned an invalid number of bytes.');
+        }
+        const codeVerifier = base64UrlEncode(verifierBytes);
+        const codeChallenge = base64UrlEncode((0, sha2_js_1.sha256)((0, utils_js_1.utf8ToBytes)(codeVerifier)));
+        const state = base64UrlEncode(stateBytes);
+        const scopes = this.options.scopes && this.options.scopes.length > 0
+            ? this.options.scopes
+            : exports.DEFAULT_GOOGLE_AUTH_SCOPES;
+        const authorizationParams = new URLSearchParams({
+            client_id: this.options.clientId,
+            redirect_uri: this.options.redirectUri,
+            response_type: 'code',
+            scope: scopes.join(' '),
+            access_type: this.options.accessType ?? 'offline',
+            prompt: this.options.prompt ?? 'select_account',
+            code_challenge: codeChallenge,
+            code_challenge_method: 'S256',
+            state,
+        });
+        const authorization = await this.options.authorize({
+            authorizationUrl: `${exports.GOOGLE_AUTHORIZATION_ENDPOINT}?${authorizationParams.toString()}`,
+            redirectUri: this.options.redirectUri,
+            state,
+        });
+        if (!authorization) {
+            return null;
+        }
+        if (authorization.state !== state) {
+            throw new Error('Google OAuth state validation failed. Please try connecting again.');
+        }
+        if (!authorization.code) {
+            throw new Error('Google OAuth did not return an authorization code.');
+        }
+        const response = await this.fetcher(exports.GOOGLE_TOKEN_ENDPOINT, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({
+                client_id: this.options.clientId,
+                code: authorization.code,
+                code_verifier: codeVerifier,
+                grant_type: 'authorization_code',
+                redirect_uri: this.options.redirectUri,
+            }).toString(),
+        });
+        const payload = await parseTokenResponse(response);
+        if (!response.ok) {
+            throwOAuthError(payload, response.status);
+        }
+        if (!payload.access_token) {
+            throw new Error('Google OAuth did not return an access token.');
+        }
+        const priorTokens = await this.tokenStore.getTokens();
+        const storedTokens = {
+            accessToken: payload.access_token,
+            refreshToken: payload.refresh_token ?? priorTokens?.refreshToken,
+            idToken: payload.id_token ?? priorTokens?.idToken,
+            expiresAt: Date.now() + (payload.expires_in ?? 3600) * 1000,
+            tokenType: payload.token_type,
+            scope: payload.scope,
+        };
+        await this.tokenStore.setTokens(storedTokens);
+        const user = await this.fetchUserProfile(storedTokens.accessToken);
+        if (this.tokenStore.setUser) {
+            await this.tokenStore.setUser(user);
+        }
+        this.notify(user);
+        return user;
+    }
+    async signOut() {
+        await this.tokenStore.removeTokens();
+        if (this.tokenStore.setUser) {
+            await this.tokenStore.setUser(null);
+        }
+        this.notify(null);
+    }
+    async isSignedIn() {
+        const tokens = await this.tokenStore.getTokens();
+        return validateTokens(tokens);
+    }
+    async getUser() {
+        if (this.currentUser) {
+            return this.currentUser;
+        }
+        if (this.tokenStore.getUser) {
+            const cached = await this.tokenStore.getUser();
+            if (cached) {
+                this.currentUser = cached;
+                return cached;
+            }
+        }
+        const tokens = await this.tokenStore.getTokens();
+        if (!validateTokens(tokens)) {
+            return null;
+        }
+        try {
+            const accessToken = await this.getValidAccessToken();
+            const user = await this.fetchUserProfile(accessToken);
+            if (this.tokenStore.setUser) {
+                await this.tokenStore.setUser(user);
+            }
+            this.currentUser = user;
+            return user;
+        }
+        catch {
+            return null;
+        }
+    }
+    async getValidAccessToken() {
+        const tokens = await this.tokenStore.getTokens();
+        if (!validateTokens(tokens)) {
+            throw new Error('No Google account signed in. Please sign in first.');
+        }
+        if (tokens.expiresAt > Date.now() + 60_000) {
+            return tokens.accessToken;
+        }
+        if (!tokens.refreshToken) {
+            throw new Error('Your Google sign-in session expired. Please sign in again.');
+        }
+        const response = await this.fetcher(exports.GOOGLE_TOKEN_ENDPOINT, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({
+                client_id: this.options.clientId,
+                grant_type: 'refresh_token',
+                refresh_token: tokens.refreshToken,
+            }).toString(),
+        });
+        const payload = await parseTokenResponse(response);
+        if (!response.ok) {
+            throwOAuthError(payload, response.status);
+        }
+        if (!payload.access_token) {
+            throw new Error('Google OAuth token refresh did not return an access token.');
+        }
+        const updatedTokens = {
+            accessToken: payload.access_token,
+            refreshToken: payload.refresh_token ?? tokens.refreshToken,
+            idToken: payload.id_token ?? tokens.idToken,
+            expiresAt: Date.now() + (payload.expires_in ?? 3600) * 1000,
+            tokenType: payload.token_type ?? tokens.tokenType,
+            scope: payload.scope ?? tokens.scope,
+        };
+        await this.tokenStore.setTokens(updatedTokens);
+        return updatedTokens.accessToken;
+    }
+    async fetchUserProfile(accessToken) {
+        const res = await this.fetcher(exports.GOOGLE_USERINFO_ENDPOINT, {
+            headers: { Authorization: `Bearer ${accessToken}` },
+        });
+        if (!res.ok) {
+            throw new Error(`Failed to fetch Google user profile (${res.status}).`);
+        }
+        const raw = (await res.json());
+        return {
+            id: raw.sub,
+            email: raw.email,
+            emailVerified: Boolean(raw.email_verified),
+            name: raw.name || raw.email || 'Google User',
+            givenName: raw.given_name,
+            familyName: raw.family_name,
+            picture: raw.picture,
+            locale: raw.locale,
+        };
+    }
+    createDriveBackupStorage() {
+        return new cloud_storage_js_1.GoogleDriveBackupStorage(() => this.getValidAccessToken(), this.fetcher);
+    }
+}
+exports.GoogleAuthClient = GoogleAuthClient;

package/dist/auth/index.d.ts

@@ -0,0 +1 @@
+export * from './google.js';

package/dist/auth/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./google.js"), exports);

package/dist/index.d.ts

@@ -18,3 +18,5 @@ export * from './utils/uuid.js';
 export * from './utils/sql.js';
 export * from './utils/logger.js';
 export * from './schema/index.js';
+export * from './auth/index.js';
+export * from './backups/index.js';

package/dist/index.js

@@ -33,3 +33,5 @@ __exportStar(require("./utils/uuid.js"), exports);
 __exportStar(require("./utils/sql.js"), exports);
 __exportStar(require("./utils/logger.js"), exports);
 __exportStar(require("./schema/index.js"), exports);
+__exportStar(require("./auth/index.js"), exports);
+__exportStar(require("./backups/index.js"), exports);

package/dist/react/auth.d.ts

@@ -0,0 +1,11 @@
+import type { GoogleAuthClient, GoogleUser } from '../auth/google.js';
+export interface UseGoogleAuthResult {
+    user: GoogleUser | null;
+    isSignedIn: boolean;
+    loading: boolean;
+    error: Error | null;
+    signIn: () => Promise<GoogleUser | null>;
+    signOut: () => Promise<void>;
+    refetchUser: () => Promise<GoogleUser | null>;
+}
+export declare function useGoogleAuth(client: GoogleAuthClient | null | undefined): UseGoogleAuthResult;

package/dist/react/auth.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useGoogleAuth = useGoogleAuth;
+const react_1 = require("react");
+function useGoogleAuth(client) {
+    const [user, setUser] = (0, react_1.useState)(null);
+    const [loading, setLoading] = (0, react_1.useState)(true);
+    const [error, setError] = (0, react_1.useState)(null);
+    (0, react_1.useEffect)(() => {
+        if (!client) {
+            setUser(null);
+            setLoading(false);
+            return;
+        }
+        let isMounted = true;
+        client
+            .getUser()
+            .then(currentUser => {
+            if (isMounted) {
+                setUser(currentUser);
+                setLoading(false);
+            }
+        })
+            .catch(err => {
+            if (isMounted) {
+                setError(err instanceof Error ? err : new Error(String(err)));
+                setLoading(false);
+            }
+        });
+        const unsubscribe = client.onAuthStateChange(updatedUser => {
+            if (isMounted) {
+                setUser(updatedUser);
+            }
+        });
+        return () => {
+            isMounted = false;
+            unsubscribe();
+        };
+    }, [client]);
+    const signIn = (0, react_1.useCallback)(async () => {
+        if (!client)
+            throw new Error('GoogleAuthClient is not initialized.');
+        setError(null);
+        setLoading(true);
+        try {
+            const res = await client.signIn();
+            setUser(res);
+            return res;
+        }
+        catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err));
+            setError(e);
+            throw e;
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [client]);
+    const signOut = (0, react_1.useCallback)(async () => {
+        if (!client)
+            return;
+        setError(null);
+        setLoading(true);
+        try {
+            await client.signOut();
+            setUser(null);
+        }
+        catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err));
+            setError(e);
+            throw e;
+        }
+        finally {
+            setLoading(false);
+        }
+    }, [client]);
+    const refetchUser = (0, react_1.useCallback)(async () => {
+        if (!client)
+            return null;
+        const res = await client.getUser();
+        setUser(res);
+        return res;
+    }, [client]);
+    return {
+        user,
+        isSignedIn: Boolean(user),
+        loading,
+        error,
+        signIn,
+        signOut,
+        refetchUser,
+    };
+}

package/dist/react/index.d.ts

@@ -117,3 +117,4 @@ export * from './theme.js';
 export * from './BenchmarkModal.js';
 export { SyncInspector, SyncIndicator } from './SyncInspector.js';
 export type { SyncInspectorProps, SyncIndicatorProps } from './SyncInspector.js';
+export * from './auth.js';

package/dist/react/index.js

@@ -594,3 +594,4 @@ __exportStar(require("./BenchmarkModal.js"), exports);
 var SyncInspector_js_1 = require("./SyncInspector.js");
 Object.defineProperty(exports, "SyncInspector", { enumerable: true, get: function () { return SyncInspector_js_1.SyncInspector; } });
 Object.defineProperty(exports, "SyncIndicator", { enumerable: true, get: function () { return SyncInspector_js_1.SyncIndicator; } });
+__exportStar(require("./auth.js"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "local-lite",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "description": "Never let a lost connection break a promise. Local-first sync that faithfully keeps data safe until you're back online.",
   "license": "MIT",
   "main": "dist/index.js",
@@ -46,6 +46,11 @@
       "import": "./dist/adapters/remote/firestore.js",
       "default": "./dist/adapters/remote/firestore.js"
     },
+    "./auth": {
+      "types": "./dist/auth/index.d.ts",
+      "import": "./dist/auth/index.js",
+      "default": "./dist/auth/index.js"
+    },
     "./backups": {
       "types": "./dist/backups/index.d.ts",
       "import": "./dist/backups/index.js",