@rqdhw3n/react-auth-flow 1.0.4 → 1.0.6

package/README.md

@@ -1,631 +1,459 @@
-# @rqdhw3n/react-auth-flow
-
-A production-ready, TypeScript-first authentication flow package for React applications. Provides a complete solution for handling user authentication with minimal configuration while maintaining flexibility.
-
-## Features
-
-- 🔐 **Secure by default**: HttpOnly cookie JWT support
-- ⚡ **Zero dependencies**: Uses native fetch API
-- 🎣 **Custom hooks**: `useAuth()` hook for accessing auth state
-- 🔄 **Auto-refresh**: Automatic session refresh capability
-- 🎨 **Unstyled components**: Ready-to-use forms with full customization
-- 🛣️ **Protected routes**: React Router v6 compatible route protection
-- 📦 **TypeScript support**: Full type safety throughout
-- 🔌 **Customizable**: Custom headers, endpoints, and request adapters
-- 🚀 **SSR-friendly**: Works with server-side rendering when configured properly
-
-## Installation
-
-```bash
-npm install @rqdhw3n/react-auth-flow react react-dom react-router-dom
-```
-
-or with yarn:
-
-```bash
-yarn add @rqdhw3n/react-auth-flow react react-dom react-router-dom
-```
-
-## Quick Setup
-
-### 1. Wrap your app with AuthProvider
-
-```tsx
-import { AuthProvider } from '@rqdhw3n/react-auth-flow';
-
-function App() {
-  return (
-    <AuthProvider
-      baseURL="https://api.example.com"
-      autoRefresh={true}
-      refreshInterval={5 * 60 * 1000} // 5 minutes
-    >
-      {/* Your app components */}
-    </AuthProvider>
-  );
-}
-```
-
-### 2. Use the useAuth hook
-
-```tsx
-import { useAuth } from '@rqdhw3n/react-auth-flow';
-
-function Header() {
-  const { user, isAuthenticated, logout } = useAuth();
-
-  if (!isAuthenticated) {
-    return <span>Please log in</span>;
-  }
-
-  return (
-    <div>
-      <p>Welcome, {user?.name}</p>
-      <button onClick={logout}>Logout</button>
-    </div>
-  );
-}
-```
-
-## Usage Examples
-
-### LoginForm Component with Tailwind CSS
-
-```tsx
-import { LoginForm } from '@rqdhw3n/react-auth-flow';
-import { useNavigate } from 'react-router-dom';
-
-function LoginPage() {
-  const navigate = useNavigate();
-
-  return (
-    <div className="flex min-h-screen items-center justify-center bg-slate-50 px-4 py-12">
-      <LoginForm
-        title="Welcome back"
-        subtitle="Sign in to your account"
-        className="w-full max-w-md rounded-2xl border border-slate-200 bg-white p-8 shadow-lg"
-        formClassName="space-y-5"
-        fieldClassName="space-y-2"
-        labelClassName="block text-sm font-medium text-slate-700"
-        inputClassName="w-full rounded-lg border border-slate-300 px-4 py-2 text-sm focus:border-blue-500 focus:ring-4 focus:ring-blue-100"
-        buttonClassName="w-full rounded-lg bg-blue-600 px-4 py-2.5 text-sm font-semibold text-white hover:bg-blue-700"
-        submitButtonText="Sign In"
-        loadingText="Signing in..."
-        labels={{
-          email: 'Email Address',
-          password: 'Password',
-          rememberMe: 'Keep me signed in',
-        }}
-        placeholders={{
-          email: 'you@example.com',
-          password: 'Enter your password',
-        }}
-        onSuccess={() => navigate('/dashboard')}
-        onError={(error) => console.error(error.message)}
-      />
-    </div>
-  );
-}
-```
-
-### RegisterForm Component with Tailwind CSS
-
-```tsx
-import { RegisterForm } from '@rqdhw3n/react-auth-flow';
-import { useNavigate, Link } from 'react-router-dom';
-
-function SignUpPage() {
-  const navigate = useNavigate();
-
-  return (
-    <div className="flex min-h-screen items-center justify-center bg-slate-50 px-4 py-12">
-      <div className="w-full max-w-md">
-        <RegisterForm
-          title="Create your account"
-          subtitle="Get started in seconds"
-          className="rounded-2xl border border-slate-200 bg-white p-8 shadow-lg"
-          formClassName="space-y-5"
-          fieldClassName="space-y-2"
-          labelClassName="block text-sm font-medium text-slate-700"
-          inputClassName="w-full rounded-lg border border-slate-300 px-4 py-2 text-sm focus:border-blue-500 focus:ring-4 focus:ring-blue-100"
-          buttonClassName="w-full rounded-lg bg-blue-600 px-4 py-2.5 text-sm font-semibold text-white hover:bg-blue-700"
-          submitButtonText="Create Account"
-          loadingText="Creating..."
-          labels={{
-            name: 'Full Name',
-            email: 'Email',
-            password: 'Password',
-            confirmPassword: 'Confirm Password',
-          }}
-          onSuccess={() => navigate('/email-verify')}
-        />
-        <p className="mt-4 text-center text-sm text-slate-600">
-          Already have an account?{' '}
-          <Link to="/login" className="font-semibold text-blue-600 hover:text-blue-700">
-            Sign in
-          </Link>
-        </p>
-      </div>
-    </div>
-  );
-}
-```
-
-### ForgotPasswordForm Component
-
-```tsx
-import { ForgotPasswordForm } from '@rqdhw3n/react-auth-flow';
-
-function ForgotPasswordPage() {
-  return (
-    <div className="flex min-h-screen items-center justify-center bg-slate-50 px-4 py-12">
-      <ForgotPasswordForm
-        title="Reset your password"
-        subtitle="Enter your email to receive a reset link"
-        className="w-full max-w-md rounded-2xl border border-slate-200 bg-white p-8 shadow-lg"
-        formClassName="space-y-5"
-        fieldClassName="space-y-2"
-        labelClassName="block text-sm font-medium text-slate-700"
-        inputClassName="w-full rounded-lg border border-slate-300 px-4 py-2 text-sm focus:border-blue-500 focus:ring-4 focus:ring-blue-100"
-        buttonClassName="w-full rounded-lg bg-blue-600 px-4 py-2.5 text-sm font-semibold text-white hover:bg-blue-700"
-        errorClassName="rounded-lg border border-red-200 bg-red-50 px-4 py-3 text-sm text-red-600"
-        successClassName="rounded-lg border border-emerald-200 bg-emerald-50 px-4 py-3 text-sm text-emerald-700"
-        submitButtonText="Send Reset Link"
-        loadingText="Sending..."
-        onSuccess={() => {
-          alert('Check your email for reset link');
-        }}
-      />
-    </div>
-  );
-}
-```
-
-### ResetPasswordForm Component
-
-```tsx
-import { ResetPasswordForm } from '@rqdhw3n/react-auth-flow';
-import { useSearchParams, useNavigate } from 'react-router-dom';
-
-function ResetPasswordPage() {
-  const [searchParams] = useSearchParams();
-  const navigate = useNavigate();
-  const token = searchParams.get('token') || '';
-
-  return (
-    <div className="flex min-h-screen items-center justify-center bg-slate-50 px-4 py-12">
-      <ResetPasswordForm
-        token={token}
-        title="Create new password"
-        subtitle="Enter your new password below"
-        className="w-full max-w-md rounded-2xl border border-slate-200 bg-white p-8 shadow-lg"
-        formClassName="space-y-5"
-        fieldClassName="space-y-2"
-        labelClassName="block text-sm font-medium text-slate-700"
-        inputClassName="w-full rounded-lg border border-slate-300 px-4 py-2 text-sm focus:border-blue-500 focus:ring-4 focus:ring-blue-100"
-        buttonClassName="w-full rounded-lg bg-blue-600 px-4 py-2.5 text-sm font-semibold text-white hover:bg-blue-700"
-        submitButtonText="Update Password"
-        loadingText="Updating..."
-        onSuccess={() => navigate('/login')}
-      />
-    </div>
-  );
-}
-```
-
-### VerifyEmailForm Component
-
-```tsx
-import { VerifyEmailForm } from '@rqdhw3n/react-auth-flow';
-import { useSearchParams } from 'react-router-dom';
-
-function VerifyEmailPage() {
-  const [searchParams] = useSearchParams();
-  const token = searchParams.get('token') || '';
-  const email = searchParams.get('email') || '';
-
-  return (
-    <div className="flex min-h-screen items-center justify-center bg-slate-50 px-4 py-12">
-      <VerifyEmailForm
-        token={token}
-        email={email}
-        title="Verify your email"
-        subtitle="Enter the code sent to your email address"
-        className="w-full max-w-md rounded-2xl border border-slate-200 bg-white p-8 shadow-lg"
-        formClassName="space-y-5"
-        fieldClassName="space-y-2"
-        labelClassName="block text-sm font-medium text-slate-700"
-        inputClassName="w-full rounded-lg border border-slate-300 px-4 py-2 text-sm focus:border-blue-500 focus:ring-4 focus:ring-blue-100"
-        buttonClassName="w-full rounded-lg bg-blue-600 px-4 py-2.5 text-sm font-semibold text-white hover:bg-blue-700"
-        submitButtonText="Verify Email"
-        loadingText="Verifying..."
-        onSuccess={() => {
-          alert('Email verified! You can now log in.');
-        }}
-      />
-    </div>
-  );
-}
-```
-
-### Simple Usage Without Custom Styling
-
-```tsx
-// Forms work with default Tailwind-friendly styling
-<LoginForm
-  onSuccess={() => navigate('/dashboard')}
-/>
-```
-
-### ProtectedRoute Component
-
-```tsx
-import { ProtectedRoute } from '@rqdhw3n/react-auth-flow';
-import { Routes, Route } from 'react-router-dom';
-
-function App() {
-  return (
-    <Routes>
-      <Route path="/login" element={<LoginPage />} />
-      <Route
-        path="/dashboard"
-        element={
-          <ProtectedRoute redirectTo="/login">
-            <Dashboard />
-          </ProtectedRoute>
-        }
-      />
-      <Route
-        path="/admin"
-        element={
-          <ProtectedRoute 
-            roles={['admin']} 
-            redirectTo="/unauthorized"
-          >
-            <AdminPanel />
-          </ProtectedRoute>
-        }
-      />
-      <Route
-        path="/manage-users"
-        element={
-          <ProtectedRoute 
-            permissions={['users.manage', 'users.delete']}
-            redirectTo="/unauthorized"
-          >
-            <UserManagement />
-          </ProtectedRoute>
-        }
-      />
-    </Routes>
-  );
-}
-```
-
-### useAuth Hook
-
-```tsx
-import { useAuth } from '@rqdhw3n/react-auth-flow';
-
-function UserProfile() {
-  const {
-    user,
-    isAuthenticated,
-    isLoading,
-    error,
-    login,
-    logout,
-    refreshSession,
-    setUser,
-  } = useAuth();
-
-  const handleLogin = async () => {
-    try {
-      const user = await login({
-        email: 'user@example.com',
-        password: 'password',
-        rememberMe: true,
-      });
-      console.log('Logged in as:', user);
-    } catch (err) {
-      console.error('Login failed:', err);
-    }
-  };
-
-  const handleLogout = async () => {
-    await logout();
-    console.log('Logged out');
-  };
-
-  if (isLoading) {
-    return <div>Loading...</div>;
-  }
-
-  if (error) {
-    return <div>Error: {error.message}</div>;
-  }
-
-  if (!isAuthenticated) {
-    return <button onClick={handleLogin}>Login</button>;
-  }
-
-  return (
-    <div>
-      <h1>Hello, {user?.name}</h1>
-      <p>Email: {user?.email}</p>
-      <p>Roles: {user?.roles?.join(', ')}</p>
-      <button onClick={handleLogout}>Logout</button>
-      <button onClick={refreshSession}>Refresh Session</button>
-    </div>
-  );
-}
-```
-
-## API Endpoints Configuration
-
-The package expects your backend to provide the following endpoints by default:
-
-### Default Endpoints
-
-- `POST /auth/login` - Login with email and password
-- `POST /auth/register` - Register a new account
-- `POST /auth/logout` - Logout the user
-- `GET /auth/me` - Get current user information
-- `POST /auth/refresh` - Refresh authentication token
-- `POST /auth/forgot-password` - Request password reset
-- `POST /auth/reset-password` - Reset password with token
-- `POST /auth/verify-email` - Verify email with token
-
-### Customizing Endpoints
-
-```tsx
-import { AuthProvider } from '@rqdhw3n/react-auth-flow';
-
-<AuthProvider
-  baseURL="https://api.example.com"
-  endpoints={{
-    login: '/auth/signin',
-    register: '/auth/signup',
-    me: '/user/profile',
-    // ... other endpoints
-  }}
->
-  {/* Your app */}
-</AuthProvider>
-```
-
-## Expected API Response Formats
-
-### Login Response
-
-```json
-{
-  "user": {
-    "id": 1,
-    "name": "John Doe",
-    "email": "john@example.com",
-    "roles": ["admin"],
-    "permissions": ["users.manage", "users.delete"]
-  }
-}
-```
-
-### Current User (Me) Response
-
-```json
-{
-  "user": {
-    "id": 1,
-    "name": "John Doe",
-    "email": "john@example.com",
-    "roles": ["admin"],
-    "permissions": ["users.manage", "users.delete"]
-  }
-}
-```
-
-### Error Response
-
-```json
-{
-  "error": {
-    "code": "INVALID_CREDENTIALS",
-    "message": "Invalid email or password",
-    "statusCode": 401
-  }
-}
-```
-
-## HttpOnly Cookie JWT Authentication
-
-For enhanced security, configure your backend to use HttpOnly cookies:
-
-```tsx
-// Backend should set a cookie like:
-// Set-Cookie: jwt=token; HttpOnly; Secure; SameSite=Strict; Max-Age=3600
-
-// The package will automatically include cookies with requests
-// because credentials: "include" is set by default
-```
-
-## Custom Headers and Request Adapter
-
-```tsx
-import { createAuthClient } from '@rqdhw3n/react-auth-flow';
-
-// Create a custom client
-const authClient = createAuthClient({
-  baseURL: 'https://api.example.com',
-  headers: {
-    'X-API-Key': 'your-api-key',
-    'X-Client-Version': '1.0.0',
-  },
-  credentials: 'include', // for HttpOnly cookies
-  adapter: async (url, options) => {
-    // Custom request logic
-    console.log('Making request to:', url);
-    return fetch(url, options);
-  },
-});
-
-// Use in AuthProvider
-<AuthProvider
-  baseURL="https://api.example.com"
-  // ... other config
->
-  {/* Your app */}
-</AuthProvider>
-```
-
-## TypeScript Customization
-
-Extend types for your application:
-
-```tsx
-import { AuthUser, AuthContextValue } from '@rqdhw3n/react-auth-flow';
-
-// Extend the AuthUser type
-interface AppUser extends AuthUser {
-  id: number;
-  name: string;
-  email: string;
-  roles: string[];
-  permissions: string[];
-  company?: string;
-  department?: string;
-}
-
-// Use in your components
-import { useAuth } from '@rqdhw3n/react-auth-flow';
-
-function MyComponent() {
-  const { user } = useAuth();
-  const appUser = user as AppUser;
-
-  return <div>Working in {appUser.department}</div>;
-}
-```
-
-## Styling Components
-
-All form components use semantic class names for styling:
-
-```css
-.auth-form-group {
-  margin-bottom: 1rem;
-}
-
-.auth-form-label {
-  display: block;
-  margin-bottom: 0.5rem;
-  font-weight: 500;
-}
-
-.auth-form-input {
-  width: 100%;
-  padding: 0.5rem;
-  border: 1px solid #ccc;
-  border-radius: 4px;
-  font-size: 1rem;
-}
-
-.auth-form-input:disabled {
-  background-color: #f5f5f5;
-  cursor: not-allowed;
-}
-
-.auth-form-error {
-  color: #dc3545;
-  margin-top: 0.5rem;
-  font-size: 0.875rem;
-}
-
-.auth-form-button {
-  padding: 0.5rem 1rem;
-  border: none;
-  border-radius: 4px;
-  font-size: 1rem;
-  cursor: pointer;
-  width: 100%;
-}
-
-.auth-form-button-primary {
-  background-color: #007bff;
-  color: white;
-}
-
-.auth-form-button-primary:hover {
-  background-color: #0056b3;
-}
-
-.auth-form-button:disabled {
-  opacity: 0.5;
-  cursor: not-allowed;
-}
-
-.auth-form-checkbox {
-  display: flex;
-  align-items: center;
-  gap: 0.5rem;
-}
-
-.auth-form-checkbox .auth-form-label {
-  margin-bottom: 0;
-}
-
-.auth-form-success {
-  padding: 1rem;
-  background-color: #d4edda;
-  border: 1px solid #c3e6cb;
-  border-radius: 4px;
-  color: #155724;
-}
-
-.auth-form-success-message {
-  margin: 0;
-}
-
-.auth-loading {
-  text-align: center;
-  padding: 2rem;
-  font-size: 1rem;
-}
-
-.auth-forbidden {
-  padding: 2rem;
-  text-align: center;
-  color: #dc3545;
-}
-```
-
-## Error Handling
-
-The package normalizes all errors to a consistent format:
-
-```tsx
-import { useAuth, AuthError } from '@rqdhw3n/react-auth-flow';
-
-function MyComponent() {
-  const { error } = useAuth();
-
-  if (error) {
-    const authError: AuthError = error;
-    console.log({
-      code: authError.code, // e.g., "INVALID_CREDENTIALS"
-      message: authError.message,
-      statusCode: authError.statusCode, // e.g., 401
-      details: authError.details, // additional error info
-    });
-  }
-
-  return <div>Status: {error?.message}</div>;
-}
-```
-
-## License
-
-MIT
-
-## Support
-
-For issues and feature requests, please visit the [GitHub repository](https://github.com/rqdhw3n/react-auth-flow).
+# @rqdhw3n/react-auth-flow
+
+Reusable auth flows for React apps with packaged UI, route guards, mock mode, theming, and cookie-friendly request handling.
+
+## Installation
+
+```bash
+npm install @rqdhw3n/react-auth-flow react react-dom react-router-dom
+```
+
+The package injects its own auth CSS automatically. Consumers do not need Tailwind or a manual CSS import.
+
+## Basic setup
+
+```tsx
+import {
+  AuthLayout,
+  AuthProvider,
+  LoginForm,
+  ProtectedRoute,
+} from "@rqdhw3n/react-auth-flow";
+import { BrowserRouter, Route, Routes } from "react-router-dom";
+
+function LoginPage() {
+  return (
+    <AuthLayout
+      title="Welcome back"
+      subtitle="Sign in to continue"
+      brand={<strong>Acme</strong>}
+    >
+      <LoginForm />
+    </AuthLayout>
+  );
+}
+
+function App() {
+  return (
+    <BrowserRouter>
+      <AuthProvider baseURL="http://localhost:8000/api">
+        <Routes>
+          <Route path="/login" element={<LoginPage />} />
+          <Route
+            path="/dashboard"
+            element={
+              <ProtectedRoute redirectTo="/login">
+                <div>Dashboard</div>
+              </ProtectedRoute>
+            }
+          />
+        </Routes>
+      </AuthProvider>
+    </BrowserRouter>
+  );
+}
+```
+
+`baseURL` and `baseUrl` are both supported.
+
+## Mock mode local test
+
+Use mock mode when you want the package to work without a backend.
+
+```tsx
+import { AuthProvider } from "@rqdhw3n/react-auth-flow";
+
+export function Root() {
+  return (
+    <AuthProvider mock mockStorageKey="rq-auth-user">
+      <App />
+    </AuthProvider>
+  );
+}
+```
+
+Mock behavior:
+
+- `login()` creates a fake admin user and stores it in `localStorage`
+- `register()` creates a fake normal user and stores it in `localStorage`
+- `logout()` clears the fake session
+- `restoreSession()` and `me()` read the fake session back
+- `forgotPassword()`, `resetPassword()`, and `verifyEmail()` return success
+- `verifyTwoFactor()` accepts any code with the configured length
+
+Custom mock user:
+
+```tsx
+<AuthProvider
+  mock
+  mockStorageKey="rq-auth-user"
+  mockUser={{
+    id: 99,
+    name: "Demo User",
+    email: "demo@example.com",
+    roles: ["admin"],
+    permissions: ["users.manage", "billing.edit"],
+  }}
+>
+  <App />
+</AuthProvider>
+```
+
+## Custom requestAdapter
+
+If `mock` is `true`, mock mode wins. Otherwise the provider uses:
+
+1. `requestAdapter`
+2. built-in `fetch`
+
+```tsx
+import { AuthProvider, type AuthRequestAdapter } from "@rqdhw3n/react-auth-flow";
+import axios from "axios";
+
+const requestAdapter: AuthRequestAdapter = async ({
+  endpoint,
+  method,
+  data,
+  headers,
+}) => {
+  const response = await axios({
+    url: `http://localhost:8000/api${endpoint}`,
+    method,
+    data,
+    withCredentials: true,
+    headers,
+  });
+
+  return response.data;
+};
+
+<AuthProvider requestAdapter={requestAdapter}>
+  <App />
+</AuthProvider>;
+```
+
+## Theme customization
+
+Theme values are applied through CSS variables on the provider wrapper.
+
+```tsx
+<AuthProvider
+  baseURL="http://localhost:8000/api"
+  theme={{
+    primaryColor: "#0f766e",
+    primaryHoverColor: "#115e59",
+    radius: "20px",
+    fontFamily: "'Manrope', sans-serif",
+  }}
+>
+  <App />
+</AuthProvider>
+```
+
+Available theme keys:
+
+- `primaryColor`
+- `primaryHoverColor`
+- `radius`
+- `fontFamily`
+
+## AuthLayout usage
+
+```tsx
+import { AuthLayout, LoginForm } from "@rqdhw3n/react-auth-flow";
+
+function LoginPage() {
+  return (
+    <AuthLayout
+      title="Welcome back"
+      subtitle="Login to continue"
+      brand={<img src="/logo.svg" alt="Brand" height={32} />}
+      footer={<a href="/register">Create account</a>}
+    >
+      <LoginForm />
+    </AuthLayout>
+  );
+}
+```
+
+## Login/Register/Forgot/Reset forms
+
+Included components:
+
+- `LoginForm`
+- `RegisterForm`
+- `ForgotPasswordForm`
+- `ResetPasswordForm`
+- `VerifyEmailForm`
+
+Example:
+
+```tsx
+import {
+  ForgotPasswordForm,
+  LoginForm,
+  RegisterForm,
+  ResetPasswordForm,
+  VerifyEmailForm,
+} from "@rqdhw3n/react-auth-flow";
+
+<LoginForm onSuccess={(user) => console.log("logged in", user)} />;
+
+<RegisterForm onSuccess={(user) => console.log("registered", user)} />;
+
+<ForgotPasswordForm onSuccess={() => console.log("email sent")} />;
+
+<ResetPasswordForm token="reset-token-from-url" />;
+
+<VerifyEmailForm token="email-token" email="hello@example.com" />;
+```
+
+## ProtectedRoute
+
+```tsx
+import { ProtectedRoute } from "@rqdhw3n/react-auth-flow";
+
+<ProtectedRoute
+  redirectTo="/login"
+  unauthorizedTo="/forbidden"
+  roles={["admin"]}
+  permissions={["users.manage", "billing.edit"]}
+  requireAllPermissions={true}
+  fallback={<div>Checking session...</div>}
+>
+  <AdminDashboard />
+</ProtectedRoute>;
+```
+
+Behavior:
+
+- loading: renders `fallback`
+- not authenticated: redirects to `redirectTo`
+- authenticated but unauthorized: redirects to `unauthorizedTo` or `redirectTo`
+- `requireAllPermissions={false}` switches permission checks to "any match"
+
+## GuestRoute
+
+```tsx
+import { GuestRoute } from "@rqdhw3n/react-auth-flow";
+
+<GuestRoute redirectTo="/" fallback={<div>Loading...</div>}>
+  <LoginPage />
+</GuestRoute>;
+```
+
+Authenticated users are redirected away from guest-only pages like login and register.
+
+## Roles and permissions helpers
+
+`useAuth()` now exposes:
+
+- `hasRole(role)`
+- `hasAnyRole(roles)`
+- `hasPermission(permission)`
+- `hasAnyPermission(permissions)`
+- `hasAllPermissions(permissions)`
+- `refreshSession()`
+- `restoreSession()`
+- `clearError()`
+- `setError()`
+
+```tsx
+import { useAuth } from "@rqdhw3n/react-auth-flow";
+
+function Toolbar() {
+  const { user, hasRole, hasAnyPermission, logout } = useAuth();
+
+  return (
+    <div>
+      <span>{user?.name}</span>
+      {hasRole("admin") && <button>Admin</button>}
+      {hasAnyPermission(["billing.edit", "users.manage"]) && (
+        <button>Manage</button>
+      )}
+      <button onClick={logout}>Logout</button>
+    </div>
+  );
+}
+```
+
+## OTP / 2FA
+
+Included components:
+
+- `OtpInput`
+- `TwoFactorForm`
+
+Provider support:
+
+- endpoint: `twoFactorVerify`, default `/auth/2fa/verify`
+- hook method: `verifyTwoFactor({ code })`
+
+```tsx
+import { TwoFactorForm } from "@rqdhw3n/react-auth-flow";
+
+<TwoFactorForm
+  length={6}
+  title="Enter your code"
+  subtitle="Check your authenticator app"
+  onSuccess={(response) => console.log(response)}
+/>;
+```
+
+Using the hook directly:
+
+```tsx
+import { useAuth } from "@rqdhw3n/react-auth-flow";
+
+function VerifyButton() {
+  const { verifyTwoFactor } = useAuth();
+
+  return (
+    <button onClick={() => verifyTwoFactor({ code: "123456" })}>
+      Verify
+    </button>
+  );
+}
+```
+
+## SocialLoginButton
+
+UI-only social button component. No OAuth flow is built in.
+
+```tsx
+import { SocialLoginButton } from "@rqdhw3n/react-auth-flow";
+
+<SocialLoginButton provider="google" onClick={() => startGoogleLogin()} />;
+<SocialLoginButton provider="github" label="Continue with GitHub" />;
+<SocialLoginButton provider="custom" icon={<span>SAML</span>} label="SSO" />;
+```
+
+## HttpOnly cookie JWT backend example
+
+This package works well with backends that issue cookies instead of exposing tokens to the browser.
+
+```ts
+// Example request adapter when the backend uses HttpOnly cookies
+const requestAdapter = async ({ endpoint, method, data, headers }) => {
+  const response = await fetch(`https://api.example.com${endpoint}`, {
+    method,
+    credentials: "include",
+    headers: {
+      "Content-Type": "application/json",
+      ...headers,
+    },
+    body: data ? JSON.stringify(data) : undefined,
+  });
+
+  if (!response.ok) {
+    throw await response.json();
+  }
+
+  return response.status === 204 ? {} : await response.json();
+};
+```
+
+Expected backend flow:
+
+- `POST /auth/login` sets the auth cookie and returns `{ user }`
+- `GET /auth/me` returns `{ user }`
+- `POST /auth/logout` clears the cookie
+- `POST /auth/refresh` rotates the session and returns `{ user }`
+
+## Laravel example
+
+```php
+// routes/api.php
+Route::post('/auth/login', [AuthController::class, 'login']);
+Route::post('/auth/register', [AuthController::class, 'register']);
+Route::middleware('auth:sanctum')->group(function () {
+    Route::get('/auth/me', [AuthController::class, 'me']);
+    Route::post('/auth/logout', [AuthController::class, 'logout']);
+    Route::post('/auth/refresh', [AuthController::class, 'refresh']);
+    Route::post('/auth/2fa/verify', [AuthController::class, 'verifyTwoFactor']);
+});
+Route::post('/auth/forgot-password', [PasswordController::class, 'forgot']);
+Route::post('/auth/reset-password', [PasswordController::class, 'reset']);
+Route::post('/auth/verify-email', [VerificationController::class, 'verify']);
+```
+
+Typical provider setup with Sanctum:
+
+```tsx
+<AuthProvider baseURL="http://localhost:8000/api">
+  <App />
+</AuthProvider>
+```
+
+## Express fake backend example
+
+```ts
+import cookieParser from "cookie-parser";
+import express from "express";
+
+const app = express();
+
+app.use(express.json());
+app.use(cookieParser());
+
+app.post("/api/auth/login", (_req, res) => {
+  res.cookie("session", "demo-session", { httpOnly: true, sameSite: "lax" });
+  res.json({
+    user: {
+      id: 1,
+      name: "Admin Test",
+      email: "admin@example.com",
+      roles: ["admin"],
+      permissions: ["users.manage", "billing.edit"],
+    },
+  });
+});
+
+app.get("/api/auth/me", (req, res) => {
+  if (!req.cookies.session) {
+    return res.status(401).json({
+      error: { code: "UNAUTHENTICATED", message: "Unauthenticated" },
+    });
+  }
+
+  return res.json({
+    user: {
+      id: 1,
+      name: "Admin Test",
+      email: "admin@example.com",
+      roles: ["admin"],
+      permissions: ["users.manage", "billing.edit"],
+    },
+  });
+});
+
+app.post("/api/auth/logout", (_req, res) => {
+  res.clearCookie("session");
+  res.status(204).end();
+});
+
+app.post("/api/auth/forgot-password", (_req, res) => {
+  res.json({ success: true, message: "Reset email queued" });
+});
+
+app.post("/api/auth/reset-password", (_req, res) => {
+  res.json({ success: true, message: "Password updated" });
+});
+
+app.post("/api/auth/verify-email", (_req, res) => {
+  res.json({ success: true, message: "Email verified" });
+});
+
+app.post("/api/auth/2fa/verify", (_req, res) => {
+  res.json({ success: true, message: "2FA verified" });
+});
+
+app.listen(8000);
+```
+
+## Notes
+
+- `AuthProvider` restores the session on mount by default. Disable with `autoRestore={false}`.
+- React 18 and React 19 are supported through peer dependencies.
+- React, React DOM, React Router, and `react/jsx-runtime` are externalized from the build.
+- The published package includes `dist/style.css` and also injects the auth CSS automatically from the package entry.