@startsimpli/auth 0.4.15 → 0.4.16

package/README.md

@@ -1,54 +1,38 @@
 # @startsimpli/auth
 
-Shared authentication package for StartSimpli Next.js applications. Provides JWT-based authentication with Django backend integration.
-
-## Features
-
-- JWT access token authentication
-- Automatic token refresh with refresh tokens (httpOnly cookies)
-- React Context and hooks for client-side auth
-- Server-side session validation for SSR and API routes
-- Next.js middleware helpers
-- Auth guards for API routes
-- Permission/role checks (owner > admin > member > viewer)
-- TypeScript support with full type safety
-
-## Installation
-
-This package is part of the StartSimpli monorepo. It uses NPM workspaces and TypeScript path aliases for direct source imports during development.
-
-```bash
-# In your Next.js app's package.json
-{
-  "dependencies": {
-    "@startsimpli/auth": "*"
-  }
-}
-```
-
-## Django Backend Integration
-
-This package is designed to work with the StartSimpli Django API (`start-simpli-api`).
-
-**Required Django endpoints:**
-- `POST /api/v1/auth/token/` - Login (returns JWT access token + sets refresh token cookie)
-- `POST /api/v1/auth/token/refresh/` - Refresh access token using cookie
-- `POST /api/v1/auth/logout/` - Logout
-- `GET /api/v1/auth/me/` - Get current user data
-
-**Token flow:**
-1. Login returns `{ access: "jwt-token", user: {...} }`
-2. Refresh token stored as httpOnly cookie (managed by Django)
-3. Access token stored in memory (not localStorage)
-4. Automatic refresh before expiration (default: 4 minutes)
-
-## Usage
-
-### Client-Side Authentication
-
-#### 1. Setup Auth Provider
-
-Wrap your app with `AuthProvider` in your root layout:
+Shared authentication for every StartSimpli frontend. JWT lifecycle, React
+context, an `authFetch` with transparent 401-retry, Next.js server helpers,
+session-storage adapters for web **and** React Native, and an in-memory mock
+backend for tests/demos.
+
+Drives auth in `raise-simpli`, `market-simpli`, `trade-simpli`, `vault-web`,
+and the `examples/mobile-rn` Expo demo on the in-progress
+`react-native-enablement` branch.
+
+## Subpath exports
+
+The package ships TypeScript source — consumers bundle it directly. The
+`package.json` `exports` map is the contract:
+
+| Import | Use from | Notes |
+|---|---|---|
+| `@startsimpli/auth` | anywhere (client-safe) | Re-exports `./client` + `./types` + `./utils` (no `next/headers`). |
+| `@startsimpli/auth/client` | browser / RN | `AuthProvider`, `useAuth`, `authFetch`, session-storage factories, mock backend. |
+| `@startsimpli/auth/server` | Next.js server | `getServerSession`, `requireAuth`, `createAuthMiddleware`, `withAuth`, `withRole`, `getTokenFromRequest`. Uses `next/headers` — never import from a client component. |
+| `@startsimpli/auth/token` | React Native | DOM-free `TokenAuthClient` + `SecureTokenStorage` (Keychain/Keystore via `expo-secure-store`). |
+| `@startsimpli/auth/components` | browser | `GoogleSignInButton`, `OAuthCallback`, `useOAuthCallback`, `OAuthConnectionCard`. |
+| `@startsimpli/auth/email` | server | `createEmailService` (Resend, optional peer). |
+| `@startsimpli/auth/types` | anywhere | Shared types — `Session`, `AuthUser`, `AuthConfig`, `CompanyRole`. |
+
+> The native/web split for storage is resolved by **Metro file extensions**
+> (`secure-session-storage.native.ts` / `secure-token-storage.native.ts`), not a
+> `./native` subpath. Import the same `createSecureSessionStorage` /
+> `SecureTokenStorage` from `@startsimpli/auth/client` (or `/token`) and the
+> bundler picks the right file. `expo-secure-store` is an optional peer; when
+> the native module is missing, both adapters degrade to in-memory storage
+> instead of crashing.
+
+## Quick start (Next.js)
 
 ```tsx
 // app/layout.tsx
@@ -63,9 +47,7 @@ export default function RootLayout({ children }) {
         <AuthProvider
           config={{
             apiBaseUrl: process.env.NEXT_PUBLIC_API_URL!,
-            onSessionExpired: () => {
-              window.location.href = '/login';
-            },
+            loginPath: '/auth/signin',
           }}
         >
           {children}
@@ -76,409 +58,241 @@ export default function RootLayout({ children }) {
 }
 ```
 
-#### 2. Use Authentication Hook
-
 ```tsx
-// app/dashboard/page.tsx
+// any client component
 'use client';
 
 import { useAuth } from '@startsimpli/auth/client';
 
-export default function DashboardPage() {
-  const { user, isLoading, isAuthenticated, logout } = useAuth();
-
-  if (isLoading) {
-    return <div>Loading...</div>;
-  }
-
-  if (!isAuthenticated) {
-    return <div>Please login</div>;
-  }
-
+export function Header() {
+  const { user, isAuthenticated, logout } = useAuth();
+  if (!isAuthenticated) return null;
   return (
     <div>
-      <h1>Welcome, {user.firstName}!</h1>
-      <button onClick={logout}>Logout</button>
+      Hi {user!.firstName} · <button onClick={logout}>Sign out</button>
     </div>
   );
 }
 ```
 
-#### 3. Login Form
+## `authFetch` — token attach + 401-retry + base-URL resolution
 
-```tsx
-// app/login/page.tsx
-'use client';
+`authFetch` is the only HTTP helper every app should use for authenticated
+calls. It:
 
-import { useState } from 'react';
-import { useAuth } from '@startsimpli/auth/client';
-import { useRouter } from 'next/navigation';
-
-export default function LoginPage() {
-  const { login } = useAuth();
-  const router = useRouter();
-  const [email, setEmail] = useState('');
-  const [password, setPassword] = useState('');
+1. Pulls the current access token from storage (see below) and attaches
+   `Authorization: Bearer <token>` if no header is set already.
+2. Resolves relative URLs against `NEXT_PUBLIC_API_URL` (or
+   `NEXT_PUBLIC_API_BASE_URL`) via `resolveAuthUrl`.
+3. Sets `credentials: 'include'` by default so the refresh cookie travels.
+4. On `401`, calls `refreshAccessToken()` **once** (concurrent 401s share one
+   refresh promise) and retries the original request with the new token.
+5. If the refresh fails or the retried request is still `401`, clears the
+   stored token and fires `notifySessionExpired()` — which calls the callback
+   registered via `setOnSessionExpired` (wired automatically by
+   `AuthProvider`).
 
-  const handleSubmit = async (e) => {
-    e.preventDefault();
-
-    try {
-      await login(email, password);
-      router.push('/dashboard');
-    } catch (error) {
-      console.error('Login failed:', error);
-    }
-  };
+```ts
+import { authFetch } from '@startsimpli/auth/client';
 
-  return (
-    <form onSubmit={handleSubmit}>
-      <input
-        type="email"
-        value={email}
-        onChange={(e) => setEmail(e.target.value)}
-        placeholder="Email"
-      />
-      <input
-        type="password"
-        value={password}
-        onChange={(e) => setPassword(e.target.value)}
-        placeholder="Password"
-      />
-      <button type="submit">Login</button>
-    </form>
-  );
+const res = await authFetch('/api/v1/me/');   // resolved to NEXT_PUBLIC_API_URL
+if (res.ok) {
+  const me = await res.json();
 }
 ```
 
-#### 4. Permission Checks
+`@startsimpli/api`'s `FetchWrapper` routes its own 401-after-refresh through
+the same `notifySessionExpired` sink so every consumer hits a single redirect
+path.
 
-```tsx
-'use client';
+### Refresh-token classification
 
-import { usePermissions } from '@startsimpli/auth/client';
+`refreshAccessToken` distinguishes "session is dead" from "backend is sick":
 
-export default function SettingsPage() {
-  const { isAdmin, canEdit, currentRole } = usePermissions();
+| Status | Result |
+|---|---|
+| `401` / `403` / `400` | Clear the stored token, return `null`. |
+| `5xx` / network error | Throw `TransientRefreshError`. Do **NOT** log the user out — the access token still lives, callers should surface a retry. |
+| `200` | Return the new access token; persist via `setAccessToken`. |
 
-  return (
-    <div>
-      <h1>Settings</h1>
-      <p>Your role: {currentRole}</p>
-
-      {isAdmin() && (
-        <button>Admin Settings</button>
-      )}
-
-      {canEdit() ? (
-        <button>Edit</button>
-      ) : (
-        <p>View only</p>
-      )}
-    </div>
-  );
+## Storage adapters (`SessionStorage`)
+
+Backends that own their session (the mock backend, the React Native
+`TokenAuthClient`, offline-first clients) need somewhere to persist it across
+reloads/app restarts. The shared contract:
+
+```ts
+interface SessionStorage {
+  load(): Promise<Session | null>;
+  save(session: Session): Promise<void>;
+  clear(): Promise<void>;
 }
 ```
 
-### Server-Side Authentication
+Factories in `@startsimpli/auth/client`:
 
-#### 1. Protect Server Components
+- `createMemorySessionStorage()` — the safe default for SSR + tests.
+- `createWebSessionStorage({ key?, storage? })` — `localStorage` by default;
+  silently falls back to memory when no Storage is available.
+- `createSecureSessionStorage(key?)` — **Metro-resolved**. On the web it
+  delegates to `createWebSessionStorage`; on React Native it persists to the
+  iOS Keychain / Android Keystore via `expo-secure-store`. Falls back to
+  in-memory when the native module isn't in the build.
+- `createRememberAwareSessionStorage(persistent, shouldRemember, transient?)`
+  — wraps two storages. When `shouldRemember()` is true at save time, the
+  session goes to `persistent` and `transient` is cleared; otherwise the
+  reverse. `load` always reads `persistent`, so a session restores only if
+  the last save was "remembered".
 
-```tsx
-// app/dashboard/page.tsx
-import { getServerSession } from '@startsimpli/auth/server';
-import { redirect } from 'next/navigation';
+The web Django client doesn't take a `SessionStorage` at all — its refresh
+token lives in an httpOnly cookie managed by the browser. The token-mode
+client (`@startsimpli/auth/token`) is the one that needs storage on RN.
 
-export default async function DashboardPage() {
-  const session = await getServerSession(process.env.API_BASE_URL!);
+### React Native parity (`TokenAuthClient`)
 
-  if (!session) {
-    redirect('/login');
-  }
+```ts
+// On RN (Expo)
+import { TokenAuthClient, SecureTokenStorage } from '@startsimpli/auth/token';
 
-  return (
-    <div>
-      <h1>Welcome, {session.user.firstName}!</h1>
-    </div>
-  );
-}
+const auth = new TokenAuthClient({
+  apiBaseUrl: 'https://api.example.com',
+  storage: new SecureTokenStorage(),
+});
 ```
 
-#### 2. Next.js Middleware
+This is the same lifecycle as the web `AuthClient` (login, refresh, logout,
+getCurrentUser) but DOM-free: no cookies, no `window`/`document`. It opts
+into the backend's token mode via `X-Auth-Mode: token` and persists the
+refresh token through the injected `TokenStorage`. See
+`examples/mobile-rn/App.tsx` for the wiring used by the Expo demo.
 
-Protect routes with authentication middleware:
+## Server helpers (Next.js)
 
 ```ts
 // middleware.ts
 import { createAuthMiddleware } from '@startsimpli/auth/server';
 
 export const middleware = createAuthMiddleware({
-  apiBaseUrl: process.env.API_BASE_URL!,
-  publicPaths: ['/login', '/register', '/forgot-password'],
-  loginPath: '/login',
+  loginPath: '/auth/signin',
+  publicPaths: ['/auth/signin', '/auth/signup', '/auth/forgot-password'],
 });
 
 export const config = {
-  matcher: [
-    '/((?!api|_next/static|_next/image|favicon.ico).*)',
-  ],
+  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
 };
 ```
 
-#### 3. API Route Protection
+The middleware uses a two-tier check: it lets the request through if either
+a fresh access cookie (`auth_session` / `access_token`) is present OR a
+`refresh_token` cookie is present (the client will refresh on mount). This
+avoids the every-30-minute redirect dance when the access JWT expires
+mid-session (see raise-simpli-qcw).
 
-Protect API routes with auth guards:
+### Route-handler guards
 
 ```ts
-// app/api/users/route.ts
-import { NextRequest } from 'next/server';
+// app/api/me/route.ts
+import { NextResponse, type NextRequest } from 'next/server';
 import { withAuth } from '@startsimpli/auth/server';
 
-export const GET = withAuth(async (request: NextRequest, token: string) => {
-  const response = await fetch(`${process.env.API_BASE_URL}/api/v1/users/`, {
-    headers: {
-      Authorization: `Bearer ${token}`,
-    },
+export const GET = withAuth(async (req: NextRequest, token: string) => {
+  const res = await fetch(`${process.env.API_BASE_URL}/api/v1/auth/me/`, {
+    headers: { Authorization: `Bearer ${token}` },
   });
-
-  const data = await response.json();
-  return NextResponse.json(data);
+  return NextResponse.json(await res.json());
 });
 ```
 
-#### 4. Role-Based API Protection
+`withRole(requiredRole, getUserRole, handler)` adds an `owner > admin >
+member > viewer` check on top. Both extract the token via
+`getRequestToken(req)` (NextRequest).
 
-```ts
-// app/api/admin/users/route.ts
-import { NextRequest } from 'next/server';
-import { withRole } from '@startsimpli/auth/server';
+### Framework-agnostic token extraction
 
-async function getUserRole() {
-  // Fetch user's current role from your API
-  return 'admin';
-}
+`getTokenFromRequest(req: Request)` works on any `Request`-compatible
+object (Node, Edge, Bun). It checks `Authorization: Bearer ...` then falls
+back to an `access_token` cookie. It returns the raw token string without
+expiry validation — used by `vault-web` API routes that hand the token
+straight to a downstream Django call.
 
-export const GET = withRole(
-  'admin',
-  getUserRole,
-  async (request: NextRequest, token: string) => {
-    // Only accessible to admins
-    return NextResponse.json({ message: 'Admin data' });
-  }
-);
-```
-
-### Making Authenticated API Calls
+### Server components
 
 ```tsx
-'use client';
-
-import { useAuth } from '@startsimpli/auth/client';
-
-export default function DataFetcher() {
-  const { getAccessToken } = useAuth();
-
-  const fetchData = async () => {
-    const token = await getAccessToken();
-
-    if (!token) {
-      console.error('No access token');
-      return;
-    }
-
-    const response = await fetch('/api/data', {
-      headers: {
-        Authorization: `Bearer ${token}`,
-      },
-    });
-
-    return response.json();
-  };
-
-  return <button onClick={fetchData}>Fetch Data</button>;
-}
-```
-
-## API Reference
-
-### Client Exports
-
-#### `AuthProvider`
-
-React context provider for authentication.
-
-```tsx
-interface AuthProviderProps {
-  children: ReactNode;
-  config: AuthConfig;
-  initialSession?: Session | null;
-}
-```
-
-#### `useAuth()`
-
-Hook to access authentication state and methods.
-
-```tsx
-interface UseAuthReturn {
-  user: AuthUser | null;
-  session: Session | null;
-  isLoading: boolean;
-  isAuthenticated: boolean;
-  login: (email: string, password: string) => Promise<void>;
-  logout: () => Promise<void>;
-  refreshUser: () => Promise<void>;
-  getAccessToken: () => Promise<string | null>;
-}
-```
-
-#### `usePermissions()`
-
-Hook for permission/role checks.
-
-```tsx
-interface UsePermissionsReturn {
-  hasRole: (requiredRole: CompanyRole, companyId?: string) => boolean;
-  isOwner: (companyId?: string) => boolean;
-  isAdmin: (companyId?: string) => boolean;
-  canEdit: (companyId?: string) => boolean;
-  canView: (companyId?: string) => boolean;
-  currentRole: CompanyRole | null;
-  currentCompanyId: string | null;
-}
-```
-
-#### `AuthClient`
-
-Low-level authentication client (used internally by hooks).
+// app/dashboard/page.tsx
+import { getServerSession } from '@startsimpli/auth/server';
+import { redirect } from 'next/navigation';
 
-```tsx
-class AuthClient {
-  constructor(config: AuthConfig);
-  login(email: string, password: string): Promise<Session>;
-  logout(): Promise<void>;
-  refreshToken(): Promise<string>;
-  getCurrentUser(): Promise<AuthUser>;
-  getSession(): Session | null;
-  getAccessToken(): Promise<string | null>;
+export default async function Dashboard() {
+  const session = await getServerSession(process.env.API_BASE_URL!);
+  if (!session) redirect('/auth/signin');
+  return <div>Welcome, {session.user.firstName}</div>;
 }
 ```
 
-### Server Exports
-
-#### `getServerSession()`
-
-Get authenticated session from server-side cookies.
-
-```tsx
-async function getServerSession(apiBaseUrl: string): Promise<Session | null>;
-```
-
-#### `validateSession()`
-
-Validate session and return user or null.
-
-```tsx
-async function validateSession(apiBaseUrl: string): Promise<AuthUser | null>;
-```
-
-#### `requireAuth()`
-
-Require authenticated session (throws if not authenticated).
-
-```tsx
-async function requireAuth(apiBaseUrl: string): Promise<Session>;
-```
-
-#### `createAuthMiddleware()`
-
-Create Next.js middleware for route protection.
-
-```tsx
-function createAuthMiddleware(config: AuthMiddlewareConfig): Middleware;
-```
-
-#### `withAuth()`
-
-HOF to wrap API routes with auth guard.
-
-```tsx
-function withAuth<T>(
-  handler: (request: NextRequest, token: string) => Promise<NextResponse<T>>
-): (request: NextRequest) => Promise<NextResponse<T>>;
-```
-
-#### `withRole()`
+`validateSession(apiBaseUrl)` and `requireAuth(apiBaseUrl)` are the
+shorter forms. `refreshServerToken(apiBaseUrl)` hits the refresh endpoint
+from a server context with cookies forwarded.
 
-HOF to wrap API routes with role-based guard.
+## Mock backend (tests, Storybook, offline demos)
 
-```tsx
-function withRole<T>(
-  requiredRole: CompanyRole,
-  getUserRole: () => Promise<CompanyRole | null>,
-  handler: (request: NextRequest, token: string) => Promise<NextResponse<T>>
-): (request: NextRequest) => Promise<NextResponse<T>>;
-```
-
-### Types
+`createMockAuthBackend()` returns a full `AuthBackend` implementation —
+exactly what `AuthProvider` needs, with no network. Pair it with any
+`SessionStorage` to survive reloads.
 
-```tsx
-type CompanyRole = 'owner' | 'admin' | 'member' | 'viewer';
-
-interface AuthUser {
-  id: string;
-  email: string;
-  firstName: string;
-  lastName: string;
-  isEmailVerified: boolean;
-  createdAt: string;
-  updatedAt: string;
-  companies?: Array<{
-    id: string;
-    name: string;
-    role: CompanyRole;
-  }>;
-  currentCompanyId?: string;
-}
-
-interface Session {
-  user: AuthUser;
-  accessToken: string;
-  expiresAt: number;
-}
+```ts
+import {
+  AuthProvider,
+  createMockAuthBackend,
+  createWebSessionStorage,
+} from '@startsimpli/auth/client';
+
+const backend = createMockAuthBackend({
+  accounts: [
+    { email: 'demo@example.com', password: 'hunter2',
+      user: { id: 'u1', email: 'demo@example.com', firstName: 'Demo',
+              lastName: 'User', isEmailVerified: true,
+              createdAt: '', updatedAt: '' } },
+  ],
+  storage: createWebSessionStorage(),
+});
 
-interface AuthConfig {
-  apiBaseUrl: string;
-  tokenRefreshInterval?: number;
-  onSessionExpired?: () => void;
-  onUnauthorized?: () => void;
+export default function App() {
+  return <AuthProvider backend={backend}>{/* ... */}</AuthProvider>;
 }
 ```
 
-## Role Hierarchy
+Pass `backend` *instead of* `config` and `AuthProvider` skips constructing
+the Django `AuthClient` entirely. The mock surface adds `requestPasswordReset`,
+`resetPassword`, `requestEmailVerification`, `verifyEmail`, and
+`upsertAccount` on top of the base contract — see
+`packages/billing/src/mock` for an example consumer.
 
-Roles follow a hierarchy where higher roles inherit permissions from lower roles:
+## Verification
 
+```bash
+pnpm --filter @startsimpli/auth test          # 140 tests across 17 files
+pnpm --filter @startsimpli/auth type-check
 ```
-owner (4) > admin (3) > member (2) > viewer (1)
-```
-
-Use `hasRolePermission(userRole, requiredRole)` to check if a user has sufficient permissions.
 
-## Testing
+The suite covers `auth-client`, `authFetch` retry, middleware, the mock
+backend, the secure-storage adapters (native + web), the token-auth core,
+permissions, and validation.
 
-```bash
-npm test              # Run tests
-npm run test:watch    # Watch mode
-npm run test:coverage # Coverage report
-```
+**Browser verification is not optional.** Any sign-in / sign-out / OAuth
+flow change MUST be driven through a localhost dev server with
+`mcp__debugg-ai__check_app_in_browser` — type-checks and unit tests do not
+prove a redirect chain works. See the MCP-default rule in
+`/Users/qosha/Repos/start-simpli/CLAUDE.md` (rule 10 / the
+"feedback_verify_ui_with_mcp" memory).
 
-## Development
+## Shared-package policy
 
-```bash
-npm run type-check    # TypeScript validation
-```
+Per `CLAUDE.md` rule 9, every app-side auth helper that another app might
+plausibly want belongs here — **not** in `apps/*/src`. No new
+`AuthProvider`, no app-local `authFetch` wrapper, no per-app `useAuth`
+hook. Extend this package instead. The current consumers all go through
+the public surface above.
 
 ## License
 
-Private package for StartSimpli monorepo.
+Private package for the StartSimpli monorepo.