@rqdhw3n/react-auth-flow 1.0.5 → 1.0.6

package/README.md

@@ -1,17 +1,6 @@
 # @rqdhw3n/react-auth-flow
 
-A TypeScript-first authentication flow package for React applications with built-in, production-ready auth form styling.
-
-## Features
-
-- Secure by default with cookie-based auth support
-- Zero UI framework dependency
-- Built-in stylesheet loaded automatically from the package entry
-- Ready-to-use `LoginForm`, `RegisterForm`, `ForgotPasswordForm`, `ResetPasswordForm`, and `VerifyEmailForm`
-- `AuthProvider` and `useAuth()` for auth state management
-- `ProtectedRoute` support for React Router
-- Customizable endpoints, headers, and request adapters
-- Override-friendly class name props for consumer styling
+Reusable auth flows for React apps with packaged UI, route guards, mock mode, theming, and cookie-friendly request handling.
 
 ## Installation
 
@@ -19,243 +8,452 @@ A TypeScript-first authentication flow package for React applications with built
 npm install @rqdhw3n/react-auth-flow react react-dom react-router-dom
 ```
 
-No Tailwind, PostCSS, `tailwind.config.js`, or manual CSS import is required. Importing the package automatically loads the packaged auth stylesheet.
-
-## Quick Setup
+The package injects its own auth CSS automatically. Consumers do not need Tailwind or a manual CSS import.
 
-### Wrap your app with `AuthProvider`
+## Basic setup
 
 ```tsx
-import { AuthProvider } from "@rqdhw3n/react-auth-flow";
+import {
+  AuthLayout,
+  AuthProvider,
+  LoginForm,
+  ProtectedRoute,
+} from "@rqdhw3n/react-auth-flow";
+import { BrowserRouter, Route, Routes } from "react-router-dom";
 
-function App() {
+function LoginPage() {
   return (
-    <AuthProvider
-      baseURL="https://api.example.com"
-      autoRefresh={true}
-      refreshInterval={5 * 60 * 1000}
+    <AuthLayout
+      title="Welcome back"
+      subtitle="Sign in to continue"
+      brand={<strong>Acme</strong>}
     >
-      {/* your app */}
-    </AuthProvider>
+      <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>
   );
 }
 ```
 
-### Use `useAuth()`
+`baseURL` and `baseUrl` are both supported.
 
-```tsx
-import { useAuth } from "@rqdhw3n/react-auth-flow";
+## Mock mode local test
 
-function Header() {
-  const { user, isAuthenticated, logout } = useAuth();
+Use mock mode when you want the package to work without a backend.
 
-  if (!isAuthenticated) {
-    return <span>Please log in</span>;
-  }
+```tsx
+import { AuthProvider } from "@rqdhw3n/react-auth-flow";
 
+export function Root() {
   return (
-    <div>
-      <p>Welcome, {user?.name}</p>
-      <button onClick={logout}>Logout</button>
-    </div>
+    <AuthProvider mock mockStorageKey="rq-auth-user">
+      <App />
+    </AuthProvider>
   );
 }
 ```
 
-## Forms
+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:
 
-### Styled out of the box
+1. `requestAdapter`
+2. built-in `fetch`
 
 ```tsx
-import { LoginForm } from "@rqdhw3n/react-auth-flow";
+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>;
+```
 
-function App() {
-  return <LoginForm />;
-}
+## 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>
 ```
 
-### Login form
+Available theme keys:
+
+- `primaryColor`
+- `primaryHoverColor`
+- `radius`
+- `fontFamily`
+
+## AuthLayout usage
 
 ```tsx
-import { LoginForm } from "@rqdhw3n/react-auth-flow";
-import { useNavigate } from "react-router-dom";
+import { AuthLayout, LoginForm } from "@rqdhw3n/react-auth-flow";
 
 function LoginPage() {
-  const navigate = useNavigate();
-
   return (
-    <div
-      style={{
-        minHeight: "100vh",
-        display: "grid",
-        placeItems: "center",
-        padding: 24,
-        background: "#f4f7fb",
-      }}
+    <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
-        title="Welcome back"
-        subtitle="Sign in to continue"
-        submitButtonText="Sign In"
-        loadingText="Signing in..."
-        labels={{
-          email: "Email Address",
-          password: "Password",
-          rememberMe: "Keep me signed in",
-        }}
-        onSuccess={() => navigate("/dashboard")}
-      />
-    </div>
+      <LoginForm />
+    </AuthLayout>
   );
 }
 ```
 
-### Register form
+## Login/Register/Forgot/Reset forms
+
+Included components:
+
+- `LoginForm`
+- `RegisterForm`
+- `ForgotPasswordForm`
+- `ResetPasswordForm`
+- `VerifyEmailForm`
+
+Example:
 
 ```tsx
-import { RegisterForm } from "@rqdhw3n/react-auth-flow";
+import {
+  ForgotPasswordForm,
+  LoginForm,
+  RegisterForm,
+  ResetPasswordForm,
+  VerifyEmailForm,
+} from "@rqdhw3n/react-auth-flow";
 
-function SignUpPage() {
-  return (
-    <RegisterForm
-      title="Create your account"
-      subtitle="Get started in seconds"
-      submitButtonText="Create Account"
-      loadingText="Creating account..."
-    />
-  );
-}
+<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" />;
 ```
 
-### Forgot password form
+## ProtectedRoute
 
 ```tsx
-import { ForgotPasswordForm } from "@rqdhw3n/react-auth-flow";
+import { ProtectedRoute } from "@rqdhw3n/react-auth-flow";
 
-function ForgotPasswordPage() {
-  return (
-    <ForgotPasswordForm
-      title="Reset your password"
-      subtitle="Enter your email to receive a reset link"
-    />
-  );
-}
+<ProtectedRoute
+  redirectTo="/login"
+  unauthorizedTo="/forbidden"
+  roles={["admin"]}
+  permissions={["users.manage", "billing.edit"]}
+  requireAllPermissions={true}
+  fallback={<div>Checking session...</div>}
+>
+  <AdminDashboard />
+</ProtectedRoute>;
 ```
 
-### Reset password form
+Behavior:
 
-```tsx
-import { ResetPasswordForm } from "@rqdhw3n/react-auth-flow";
-import { useSearchParams } from "react-router-dom";
+- loading: renders `fallback`
+- not authenticated: redirects to `redirectTo`
+- authenticated but unauthorized: redirects to `unauthorizedTo` or `redirectTo`
+- `requireAllPermissions={false}` switches permission checks to "any match"
 
-function ResetPasswordPage() {
-  const [searchParams] = useSearchParams();
-  const token = searchParams.get("token") || "";
+## GuestRoute
 
-  return (
-    <ResetPasswordForm
-      token={token}
-      title="Create a new password"
-      subtitle="Use at least 8 characters"
-    />
-  );
-}
+```tsx
+import { GuestRoute } from "@rqdhw3n/react-auth-flow";
+
+<GuestRoute redirectTo="/" fallback={<div>Loading...</div>}>
+  <LoginPage />
+</GuestRoute>;
 ```
 
-### Verify email form
+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 { VerifyEmailForm } from "@rqdhw3n/react-auth-flow";
-import { useSearchParams } from "react-router-dom";
+import { useAuth } from "@rqdhw3n/react-auth-flow";
 
-function VerifyEmailPage() {
-  const [searchParams] = useSearchParams();
+function Toolbar() {
+  const { user, hasRole, hasAnyPermission, logout } = useAuth();
 
   return (
-    <VerifyEmailForm
-      token={searchParams.get("token") || ""}
-      email={searchParams.get("email") || ""}
-      title="Verify your email"
-      subtitle="Enter the verification code you received"
-    />
+    <div>
+      <span>{user?.name}</span>
+      {hasRole("admin") && <button>Admin</button>}
+      {hasAnyPermission(["billing.edit", "users.manage"]) && (
+        <button>Manage</button>
+      )}
+      <button onClick={logout}>Logout</button>
+    </div>
   );
 }
 ```
 
-## Styling Overrides
+## OTP / 2FA
 
-The package ships with default classes and also supports consumer overrides through props:
+Included components:
 
-- `className`
-- `formClassName`
-- `fieldClassName`
-- `labelClassName`
-- `inputClassName`
-- `buttonClassName`
-- `errorClassName`
-- `successClassName`
-- `titleClassName`
-- `subtitleClassName`
+- `OtpInput`
+- `TwoFactorForm`
 
-Example:
+Provider support:
+
+- endpoint: `twoFactorVerify`, default `/auth/2fa/verify`
+- hook method: `verifyTwoFactor({ code })`
 
 ```tsx
-import { LoginForm } from "@rqdhw3n/react-auth-flow";
+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();
 
-function CustomLoginPage() {
   return (
-    <LoginForm
-      className="my-auth-card"
-      formClassName="my-auth-form"
-      labelClassName="my-auth-label"
-      inputClassName="my-auth-input"
-      buttonClassName="my-auth-button"
-      errorClassName="my-auth-error"
-      successClassName="my-auth-success"
-    />
+    <button onClick={() => verifyTwoFactor({ code: "123456" })}>
+      Verify
+    </button>
   );
 }
 ```
 
-Default packaged class names:
+## 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();
+};
+```
 
-- `.rq-auth-container`
-- `.rq-auth-form`
-- `.rq-auth-field`
-- `.rq-auth-label`
-- `.rq-auth-input`
-- `.rq-auth-button`
-- `.rq-auth-error`
-- `.rq-auth-success`
-- `.rq-auth-title`
-- `.rq-auth-subtitle`
-- `.rq-auth-checkbox`
+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']);
+```
 
-## Protected Routes
+Typical provider setup with Sanctum:
 
 ```tsx
-import { ProtectedRoute } from "@rqdhw3n/react-auth-flow";
-import { Routes, Route } from "react-router-dom";
+<AuthProvider baseURL="http://localhost:8000/api">
+  <App />
+</AuthProvider>
+```
 
-function AppRoutes() {
-  return (
-    <Routes>
-      <Route path="/login" element={<LoginPage />} />
-      <Route
-        path="/dashboard"
-        element={
-          <ProtectedRoute redirectTo="/login">
-            <Dashboard />
-          </ProtectedRoute>
-        }
-      />
-    </Routes>
-  );
-}
+## 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
 
-- The package stylesheet is imported from `src/index.ts`, so consumers do not need `import "./styles.css"` in their apps.
-- Build output includes JavaScript bundles and an emitted CSS asset in `dist`.
-- The components are responsive by default and work on desktop and mobile without extra setup.
+- `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.