@proveanything/smartlinks-auth-ui 0.5.21 → 0.6.0

package/AUTH_STATE_MANAGEMENT.md

@@ -0,0 +1,262 @@
+# Authentication State Management
+
+## Overview
+
+The Smartlinks Auth UI module provides comprehensive authentication state management with real-time synchronization across browser tabs and multiple ways for your application to respond to authentication changes.
+
+## Accessing Authentication State
+
+### 1. Using the `useAuth` Hook
+
+The primary way to access authentication state in React components:
+
+```tsx
+import { useAuth } from '@smartlinks/auth-ui';
+
+function MyComponent() {
+  const { user, token, accountData, isAuthenticated, isLoading } = useAuth();
+
+  if (isLoading) return <div>Loading...</div>;
+  if (!isAuthenticated) return <div>Please log in</div>;
+
+  return (
+    <div>
+      <h1>Welcome, {user.displayName}!</h1>
+      <p>Email: {user.email}</p>
+    </div>
+  );
+}
+```
+
+**Properties:**
+- `user: AuthUser | null` - Current authenticated user object
+- `token: string | null` - Current authentication token
+- `accountData: Record<string, any> | null` - Additional account metadata
+- `isAuthenticated: boolean` - Whether a user is currently logged in
+- `isLoading: boolean` - Whether initial auth state is still loading
+
+### 2. Using `onAuthStateChange` Callback
+
+Subscribe to all authentication state changes including login, logout, cross-tab synchronization, and token refresh:
+
+```tsx
+import { useAuth } from '@smartlinks/auth-ui';
+import { useEffect } from 'react';
+import { useNavigate } from 'react-router-dom';
+
+function App() {
+  const { onAuthStateChange } = useAuth();
+  const navigate = useNavigate();
+
+  useEffect(() => {
+    // Subscribe to auth state changes
+    const unsubscribe = onAuthStateChange((event) => {
+      console.log('Auth state changed:', event.type);
+      
+      if (event.type === 'LOGIN' || event.type === 'CROSS_TAB_SYNC') {
+        if (event.user) {
+          // User logged in (in this tab or another)
+          navigate('/dashboard');
+        }
+      } else if (event.type === 'LOGOUT') {
+        // User logged out
+        navigate('/login');
+      }
+    });
+
+    // Cleanup subscription on unmount
+    return unsubscribe;
+  }, [onAuthStateChange, navigate]);
+
+  return <YourAppComponents />;
+}
+```
+
+**Event Types:**
+- `LOGIN` - User logged in via the auth UI
+- `LOGOUT` - User logged out
+- `CROSS_TAB_SYNC` - Authentication state synchronized from another browser tab
+- `TOKEN_REFRESH` - Authentication token was refreshed (future feature)
+- `ACCOUNT_REFRESH` - Account information was fetched/refreshed
+
+**Event Object:**
+```typescript
+{
+  type: 'LOGIN' | 'LOGOUT' | 'TOKEN_REFRESH' | 'CROSS_TAB_SYNC' | 'ACCOUNT_REFRESH';
+  user: AuthUser | null;
+  token: string | null;
+  accountData: Record<string, any> | null;
+  accountInfo?: Record<string, any> | null;
+}
+```
+
+### 3. Using Auth Operation Callbacks
+
+Handle specific authentication operations with callbacks:
+
+```tsx
+<SmartlinksAuthUI
+  clientId="your-client-id"
+  apiEndpoint="https://smartlinks.app/api/v1"
+  onAuthSuccess={(response) => {
+    console.log('User authenticated:', response.user);
+    // Redirect or update UI
+    window.location.href = '/dashboard';
+  }}
+  onAuthError={(error) => {
+    console.error('Authentication failed:', error);
+    // Show error message to user
+  }}
+/>
+```
+
+## Cross-Tab Synchronization
+
+The auth module automatically synchronizes authentication state across all open browser tabs:
+
+- **Login in one tab** → All tabs automatically update to authenticated state
+- **Logout in one tab** → All tabs automatically clear authentication state
+- **Session expiration** → All tabs receive the update simultaneously
+
+This is implemented using:
+- **IndexedDB** for persistent token storage
+- **BroadcastChannel API** for cross-tab messaging
+- **Storage events** for fallback synchronization
+
+## Protected Routes
+
+Use the `ProtectedRoute` component to restrict access to authenticated users:
+
+```tsx
+import { ProtectedRoute } from '@smartlinks/auth-ui';
+
+function App() {
+  return (
+    <Routes>
+      <Route path="/login" element={<LoginPage />} />
+      <Route
+        path="/dashboard"
+        element={
+          <ProtectedRoute fallback={<LoginPage />}>
+            <DashboardPage />
+          </ProtectedRoute>
+        }
+      />
+    </Routes>
+  );
+}
+```
+
+**Props:**
+- `children` - Protected content to render when authenticated
+- `fallback` - Component to render when not authenticated (optional)
+- `redirectTo` - URL to redirect to when not authenticated (optional)
+
+## Complete Example: App with Auth State Management
+
+```tsx
+import React, { useEffect } from 'react';
+import { BrowserRouter, Routes, Route, useNavigate } from 'react-router-dom';
+import { AuthProvider, useAuth, SmartlinksAuthUI, ProtectedRoute } from '@smartlinks/auth-ui';
+
+// Login page component
+function LoginPage() {
+  const navigate = useNavigate();
+  const { isAuthenticated } = useAuth();
+
+  // Redirect if already authenticated
+  useEffect(() => {
+    if (isAuthenticated) {
+      navigate('/dashboard');
+    }
+  }, [isAuthenticated, navigate]);
+
+  return (
+    <div>
+      <h1>Sign In</h1>
+      <SmartlinksAuthUI
+        clientId="your-client-id"
+        apiEndpoint="https://smartlinks.app/api/v1"
+        onAuthSuccess={() => navigate('/dashboard')}
+        onAuthError={(error) => alert(error.message)}
+      />
+    </div>
+  );
+}
+
+// Protected dashboard component
+function DashboardPage() {
+  const { user, logout } = useAuth();
+
+  return (
+    <div>
+      <h1>Dashboard</h1>
+      <p>Welcome, {user?.displayName}!</p>
+      <button onClick={logout}>Sign Out</button>
+    </div>
+  );
+}
+
+// App root with auth state monitoring
+function AppContent() {
+  const { onAuthStateChange } = useAuth();
+  const navigate = useNavigate();
+
+  useEffect(() => {
+    const unsubscribe = onAuthStateChange((event) => {
+      if (event.type === 'LOGOUT') {
+        navigate('/login');
+      } else if (event.type === 'LOGIN' || event.type === 'CROSS_TAB_SYNC') {
+        if (event.user) {
+          navigate('/dashboard');
+        }
+      }
+    });
+
+    return unsubscribe;
+  }, [onAuthStateChange, navigate]);
+
+  return (
+    <Routes>
+      <Route path="/login" element={<LoginPage />} />
+      <Route
+        path="/dashboard"
+        element={
+          <ProtectedRoute fallback={<LoginPage />}>
+            <DashboardPage />
+          </ProtectedRoute>
+        }
+      />
+    </Routes>
+  );
+}
+
+// App root
+export default function App() {
+  return (
+    <AuthProvider>
+      <BrowserRouter>
+        <AppContent />
+      </BrowserRouter>
+    </AuthProvider>
+  );
+}
+```
+
+## Best Practices
+
+1. **Always wrap your app with `AuthProvider`** at the root level
+2. **Use `onAuthStateChange`** for app-level routing and state synchronization
+3. **Use `useAuth` hook** for component-level auth state access
+4. **Use `ProtectedRoute`** to guard authenticated routes
+5. **Handle loading states** with `isLoading` to avoid flickering
+6. **Subscribe to `onAuthStateChange` early** in your app initialization to catch cross-tab events
+
+## Session Persistence
+
+Sessions are automatically persisted using:
+- **Primary:** IndexedDB (survives browser restart, shared across tabs)
+- **Fallback:** localStorage (for browsers without IndexedDB support)
+- **In-memory:** Last resort for restricted environments
+
+Tokens are stored with expiration metadata and automatically validated on load. Expired tokens are automatically cleared.

package/CAPACITOR_INTEGRATION.md

@@ -0,0 +1,244 @@
+# Capacitor Native Auth (Google & Apple)
+
+This guide shows how to enable **native** Google and Apple sign-in for apps that
+wrap the auth UI in a [Capacitor](https://capacitorjs.com/) shell (including apps
+shipped with [Capgo](https://capgo.app/) OTA updates).
+
+Unlike the legacy [`window.AuthKit` bridge](./ANDROID_NATIVE_BRIDGE.md) — which
+uses a stringified-JSON + `callbackId` callback structure — Capacitor plugins are
+**Promise-based**. So instead of that bridge, you inject a small **`nativeAuth`
+adapter** and the auth UI `await`s it directly.
+
+> The library stays plugin-agnostic: it depends on **no** Capacitor packages. Your
+> app owns the plugin and wires it into the adapter shape below.
+
+---
+
+## 1. Install a native social-login plugin
+
+Any plugin works as long as you can produce a Google **ID token** and an Apple
+**identity token**. The natural fit for Capgo apps is
+[`@capgo/capacitor-social-login`](https://github.com/Cap-go/capacitor-social-login):
+
+```bash
+npm install @capgo/capacitor-social-login
+npx cap sync
+```
+
+Configure native projects per that plugin's README (iOS: add the Sign in with
+Apple capability + URL scheme; Android: add your Google **Web Client ID** /
+`serverClientId` and SHA-1). See [ANDROID_NATIVE_BRIDGE.md](./ANDROID_NATIVE_BRIDGE.md#prerequisites)
+for the Google Cloud Console setup — the client IDs are identical.
+
+---
+
+## 2. Build the adapter
+
+The adapter implements the `NativeAuthAdapter` interface exported by this package.
+Each method resolves a `NativeAuthResult` whose `idToken` is the token your backend
+verifies (`googleLogin` / the Apple endpoint).
+
+```ts
+import { SocialLogin } from '@capgo/capacitor-social-login';
+import { Capacitor } from '@capacitor/core';
+import type { NativeAuthAdapter } from '@proveanything/smartlinks-auth-ui';
+
+const GOOGLE_WEB_CLIENT_ID = '696509063554-xxx.apps.googleusercontent.com';
+const APPLE_SERVICES_ID = 'com.yourapp.signin';
+
+let initialized = false;
+async function ensureInit() {
+  if (initialized) return;
+  await SocialLogin.initialize({
+    google: { webClientId: GOOGLE_WEB_CLIENT_ID },
+    apple: { clientId: APPLE_SERVICES_ID },
+  });
+  initialized = true;
+}
+
+export const capacitorNativeAuth: NativeAuthAdapter = {
+  async signInWithGoogle() {
+    await ensureInit();
+    const { result } = await SocialLogin.login({
+      provider: 'google',
+      options: { scopes: ['email', 'profile'] },
+    });
+    // Field names vary slightly by plugin version — log `result` once to confirm.
+    return {
+      idToken: (result as any).idToken,
+      email: (result as any).profile?.email,
+      name: (result as any).profile?.name,
+      picture: (result as any).profile?.imageUrl,
+    };
+  },
+
+  async signInWithApple() {
+    await ensureInit();
+    const { result } = await SocialLogin.login({
+      provider: 'apple',
+      options: { scopes: ['email', 'name'] },
+    });
+    return {
+      idToken: (result as any).idToken,          // Apple identity token (JWT)
+      authorizationCode: (result as any).accessToken,
+      email: (result as any).profile?.email,
+      name: (result as any).profile?.name,
+    };
+  },
+
+  async signOut() {
+    try { await SocialLogin.logout({ provider: 'google' }); } catch {}
+  },
+};
+
+// Only attach native auth when actually running in a native shell —
+// on the web, leave it undefined so the normal browser OAuth flow is used.
+export const nativeAuth = Capacitor.isNativePlatform() ? capacitorNativeAuth : undefined;
+```
+
+---
+
+## 3. Pass it to the auth UI
+
+```tsx
+import { SmartlinksAuthUI } from '@proveanything/smartlinks-auth-ui';
+import { nativeAuth } from './capacitorNativeAuth';
+
+<SmartlinksAuthUI
+  clientId="your-client-id"
+  enabledProviders={['email', 'google', 'apple']}
+  nativeAuth={nativeAuth}
+  enableSilentNativeSignIn          // optional: auto sign-in if a native session exists
+  customization={{ appleClientId: APPLE_SERVICES_ID }}
+  onAuthSuccess={(token, user) => console.log('Authenticated:', user.email)}
+/>
+```
+
+That's it. When `nativeAuth` is present:
+
+- **Google** → uses `nativeAuth.signInWithGoogle()` (highest priority, before the
+  legacy `window.AuthKit` bridge, proxy popup, and in-browser GIS flow).
+- **Apple** → uses `nativeAuth.signInWithApple()`. Apple is **native-only** in this
+  kit; without an adapter the Apple button reports it's unavailable.
+- On the **web** build (`nativeAuth` undefined) everything falls back to the
+  existing browser flows automatically.
+
+---
+
+## 4. Mobile session persistence ("stay logged in forever")
+
+Mobile users expect to open the app weeks later and still be signed in. The web
+defaults (IndexedDB, 7-day token cache, refresh on next page load) are not enough.
+Wire up the three pieces below in your Capacitor shell.
+
+### 4a. Use OS-secure storage for tokens
+
+By default the kit persists tokens in IndexedDB inside the WebView. That survives
+app restarts and Capgo OTA updates, but it is **not encrypted at rest**. For any
+app that handles sensitive data, swap in the OS keychain via the
+`setStorageAdapter` hook exported from the kit. Install a secure-storage plugin
+(e.g. [`capacitor-secure-storage-plugin`](https://github.com/martinkasa/capacitor-secure-storage-plugin)
+or `@capacitor/preferences` for non-sensitive cases) and implement the
+`PersistentStorage` interface against it:
+
+```ts
+import { SecureStoragePlugin } from 'capacitor-secure-storage-plugin';
+import { setStorageAdapter, type PersistentStorage } from '@proveanything/smartlinks-auth-ui';
+
+const keychainStorage: PersistentStorage = {
+  async setItem(key, value)  { await SecureStoragePlugin.set({ key, value: JSON.stringify(value) }); },
+  async getItem(key)         { try { const { value } = await SecureStoragePlugin.get({ key }); return JSON.parse(value); } catch { return null; } },
+  async removeItem(key)      { try { await SecureStoragePlugin.remove({ key }); } catch {} },
+  async clear()              { const { keys } = await SecureStoragePlugin.keys(); await Promise.all(keys.map(k => SecureStoragePlugin.remove({ key: k }))); },
+  async isAvailable()        { return true; },
+  getBackend()               { return 'none'; }, // not one of the built-ins
+};
+
+// Call ONCE, before <SmartlinksAuthUI /> mounts (e.g. in main.tsx).
+if (Capacitor.isNativePlatform()) setStorageAdapter(keychainStorage);
+```
+
+### 4b. Refresh the session on app resume
+
+Capacitor fires `appStateChange` when the OS hands the app back. Call
+`useAuth().refreshToken()` there so a cold-open after days re-validates the
+session before the user touches anything. Today this re-verifies the existing
+JWT and extends the local cache window; once the optional refresh-token endpoint
+(see §5) is deployed it will also rotate to a fresh long-lived token.
+
+```tsx
+import { App } from '@capacitor/app';
+import { useAuth } from '@proveanything/smartlinks-auth-ui';
+
+function ResumeRefresh() {
+  const { refreshToken, token } = useAuth();
+  useEffect(() => {
+    const sub = App.addListener('appStateChange', ({ isActive }) => {
+      if (isActive && token) refreshToken().catch(() => {});
+    });
+    return () => { sub.remove(); };
+  }, [refreshToken, token]);
+  return null;
+}
+```
+
+### 4c. Wire logout to the native provider
+
+`useAuth().logout()` clears the SmartLinks session. If the user signed in with
+Google or Apple natively, also call `nativeAuth.signOut()` so the OS-level
+session is dropped — otherwise the next "Continue with Google" silently
+re-uses the previous account.
+
+### 4d. Biometric gate (host responsibility)
+
+Best mobile UX is "session lives forever, Face ID unlocks the UI on cold start".
+That belongs in the host app (e.g.
+[`@capgo/capacitor-native-biometric`](https://github.com/Cap-go/capacitor-native-biometric)) —
+gate your protected routes behind a biometric prompt and leave the SmartLinks
+session alone.
+
+### 4e. Deep links (magic-link & email verify)
+
+Magic-link and email-verification URLs must open the app, not Safari/Chrome.
+Configure your custom scheme + Universal/App Links in `capacitor.config.ts`,
+then forward the URL into the SDK:
+
+```ts
+import { App } from '@capacitor/app';
+
+App.addListener('appUrlOpen', ({ url }) => {
+  // Strip the scheme/host and replace the WebView's hash so the kit's
+  // existing deep-link detector (mode=verifyEmail|magicLink, token=...) picks it up.
+  const u = new URL(url);
+  window.location.hash = u.hash || `#${u.pathname}${u.search}`;
+});
+```
+
+---
+
+## 5. Backend: long-lived tokens & refresh
+
+The kit's `tokenStorage` caches the JWT for 7 days by default; the real ceiling
+is the JWT's own `exp` claim. Two backend options if you want true "never log out"
+sessions:
+
+1. **Issue longer JWTs for native clients.** Detect a `X-Client-Platform: native`
+   header on `/auth/*` endpoints and mint a 90-day token. Simplest path — no new
+   endpoints, no rotation logic. Trade-off: longer revocation window.
+2. **Add a refresh-token endpoint** (recommended for production). Spec lives at
+   [`backend-reference/REFRESH_TOKEN_BACKEND_SPEC.md`](../backend-reference/REFRESH_TOKEN_BACKEND_SPEC.md).
+   The kit's `useAuth().refreshToken()` will start calling it transparently once
+   the endpoint ships.
+
+---
+
+## Apple backend (already shipped)
+
+Sign in with Apple is delegated to `smartlinks.authKit.appleLogin()` in the SDK
+(≥ 1.14.15) which posts to `POST /authkit/{clientId}/auth/apple`. No additional
+work needed in this kit.
+
+> **App Store note:** Apple's [App Store Review Guideline 4.8](https://developer.apple.com/app-store/review/guidelines/#sign-in-with-apple)
+> requires offering Sign in with Apple when you offer Google sign-in in an iOS app,
+> which is the main reason Apple support is bundled here.
+