next-token-auth 1.0.14 → 1.0.16

package/README.md

@@ -1,53 +1,41 @@
 # next-token-auth
 
-A production-grade authentication library for Next.js. Handles access tokens, refresh tokens, session management, and route protection — so you don't have to wire it all up yourself.
+A production-grade authentication library for Next.js that handles the hard parts of auth so you can focus on building features.
 
-Works with both the App Router and Pages Router. Fully typed with TypeScript.
+Works with both App Router and Pages Router. Fully typed with TypeScript.
 
----
-
-## The Problem
-
-Authentication in Next.js involves a lot of moving parts:
+> **Breaking change in v1.1.0:** The secret is now server-side only for security. You'll need to split your config and add one Route Handler file. See the Quick Start below — it takes 5 minutes.
 
-- Storing tokens securely
-- Refreshing access tokens before they expire
-- Keeping client and server sessions in sync
-- Protecting routes on both the client and server
-- Wiring up login, logout, and user fetching from scratch
+---
 
-Most projects end up with hundreds of lines of boilerplate before a single feature is built.
+## Why This Exists
 
----
+Authentication in Next.js is tedious. You need to:
 
-## The Solution
+- Store tokens securely
+- Refresh access tokens before they expire
+- Keep client and server sessions in sync
+- Protect routes on both the client and server
+- Handle login, logout, and session restoration
+- Wire up API calls with Bearer tokens
 
-`next-token-auth` gives you a single `AuthProvider` and a set of hooks that handle the entire auth lifecycle. You configure your API endpoints once, and the library takes care of the rest:
+Most projects spend days on auth boilerplate before shipping a single feature.
 
-- Tokens are stored in cookies or memory
-- Access tokens are automatically refreshed before they expire
-- Sessions are restored on page load from stored tokens
-- Routes can be protected client-side with a hook or server-side with middleware
-- Every API request made through the built-in fetch wrapper gets a `Bearer` token injected automatically
+`next-token-auth` gives you all of this in a single `AuthProvider` and a few hooks. Configure your API endpoints once, and the library handles the rest.
 
 ---
 
-## Features
-
-- `AuthProvider` — React context provider that initializes and manages auth state
-- `useAuth` — login, logout, refresh, and session in one hook
-- `useSession` — read-only access to the current session
-- `useRequireAuth` — redirects unauthenticated users, works in App Router and Pages Router
-- Token storage in cookies or in-memory
-- AES-GCM encrypted session cookies (server-side)
-- Automatic access token refresh on a 30-second interval (when `autoRefresh` is enabled)
-- 401 → refresh → retry built into the HTTP client
-- `getServerSession` — read and validate the session in server components and API routes
-- `withAuth` — higher-order function to protect App Router route handlers
-- `authMiddleware` — Next.js middleware factory for edge-level route protection with guest-only route support
-- Flexible expiry parsing: `"15m"`, `"2h"`, `"2d"`, `"7d"`, `"1w"`, or plain seconds
-- Three expiry strategies: `backend`, `config`, `hybrid`
-- Fully typed with TypeScript generics for custom user shapes
+## What You Get
+
+- One `<AuthProvider>` wrapper for your entire app
+- Three hooks: `useAuth()`, `useSession()`, `useRequireAuth()`
+- Automatic token refresh before expiry
+- HttpOnly encrypted cookies (tokens never exposed to JavaScript)
+- Server-side session validation via `getServerSession()`
+- Next.js middleware for edge-level route protection
+- Guest-only routes (redirect authenticated users away from login pages)
+- Flexible expiry formats: `"15m"`, `"2h"`, `"2d"`, `"7d"`, or plain seconds
+- Full TypeScript support with generics for your custom user shape
 
 ---
 
@@ -55,27 +43,20 @@ Most projects end up with hundreds of lines of boilerplate before a single featu
 
 ```bash
 npm install next-token-auth
-# or
-yarn add next-token-auth
-# or
-pnpm add next-token-auth
-# or
-bun add next-token-auth
 ```
 
-**Peer dependencies** (already installed in any Next.js project):
-
-```
-next >= 13
-react >= 18
-react-dom >= 18
-```
+Peer dependencies (already in any Next.js project):
+- `next >= 15.5.14`
+- `react >= 18`
+- `react-dom >= 18`
 
 ---
 
 ## Quick Start
 
-### 1. Create your config
+### Step 1: Create your server config
+
+This file contains your `secret` and backend API URL. Never import it in client components.
 
 ```ts
 // lib/auth.ts
@@ -88,22 +69,27 @@ interface User {
 }
 
 export const authConfig: AuthConfig<User> = {
-  baseUrl: process.env.NEXT_PUBLIC_API_URL!,
+  // Your backend API base URL (no NEXT_PUBLIC_ prefix needed)
+  baseUrl: process.env.API_URL!,
 
+  // Your backend auth endpoints
   endpoints: {
-    login: "/auth/login",
-    refresh: "/auth/refresh",
-    logout: "/auth/logout",
-    me: "/auth/me",
+    login: "/auth/login",      // POST { email, password } → returns tokens + user
+    refresh: "/auth/refresh",  // POST { refreshToken } → returns new tokens
+    logout: "/auth/logout",    // POST (optional)
+    me: "/auth/me",            // GET → returns user profile (optional)
   },
 
+  // Route protection rules
   routes: {
-    public: ["/", "/about"],
-    guestOnly: ["/login", "/register"],
-    protected: ["/dashboard/*"],
-    redirectAuthenticatedTo: "/dashboard",
+    public: ["/", "/about"],              // always accessible
+    guestOnly: ["/login", "/register"],   // only when NOT logged in
+    protected: ["/dashboard*", "/profile*"], // requires auth
+    loginPath: "/login",                  // where to send unauthenticated users
+    redirectAuthenticatedTo: "/dashboard", // where to send authenticated users who hit guestOnly routes
   },
 
+  // Token storage settings
   token: {
     storage: "cookie",
     cookieName: "myapp.session",
@@ -111,58 +97,133 @@ export const authConfig: AuthConfig<User> = {
     sameSite: "lax",
   },
 
+  // Encryption secret (32+ random characters)
   secret: process.env.AUTH_SECRET!,
 
+  // Auto-refresh tokens before they expire
   autoRefresh: true,
 
+  // Token expiry (matches your backend JWT settings)
   expiry: {
-    accessTokenExpiresIn: "2d",
+    accessTokenExpiresIn: "2d",   // can also be a number in seconds
     refreshTokenExpiresIn: "7d",
-    strategy: "hybrid",
+    strategy: "hybrid",            // backend first, fallback to config
+  },
+};
+```
+
+**Important:** Use any route names you want. The library doesn't enforce `/login` or `/dashboard` — everything is driven by your config.
+
+---
+
+### Step 2: Create your client config
+
+This is safe to import anywhere, including client components. It doesn't contain secrets.
+
+```ts
+// lib/auth.client.ts
+import type { ClientAuthConfig } from "next-token-auth";
+
+export const clientAuthConfig: ClientAuthConfig = {
+  token: {
+    cookieName: "myapp.session",  // must match server config
   },
+  autoRefresh: true,
 };
 ```
 
-### 2. Wrap your app with `AuthProvider`
+---
+
+### Step 3: Mount the Route Handlers
+
+Create this file to handle login, logout, refresh, and session endpoints automatically.
+
+```ts
+// app/api/auth/[action]/route.ts
+import { createAuthHandlers } from "next-token-auth/server";
+import { authConfig } from "@/lib/auth";
+
+export const { GET, POST } = createAuthHandlers(authConfig);
+```
+
+This creates four internal endpoints:
+- `POST /api/auth/login` — authenticates and sets HttpOnly cookie
+- `POST /api/auth/logout` — clears the session cookie
+- `POST /api/auth/refresh` — refreshes the access token
+- `GET /api/auth/session` — returns current user and auth status
+
+Your `AuthProvider` calls these automatically. You never call them directly.
+
+---
+
+### Step 4: Wrap your app
 
 ```tsx
 // app/layout.tsx
 import { AuthProvider } from "next-token-auth/react";
-import { authConfig } from "@/lib/auth";
+import { clientAuthConfig } from "@/lib/auth.client";
 
 export default function RootLayout({ children }: { children: React.ReactNode }) {
   return (
     <html lang="en">
       <body>
-        <AuthProvider config={authConfig}>{children}</AuthProvider>
+        <AuthProvider config={clientAuthConfig}>
+          {children}
+        </AuthProvider>
       </body>
     </html>
   );
 }
 ```
 
-### 3. Use the hooks
+---
+
+### Step 5: Build your login page
 
 ```tsx
+// app/login/page.tsx
 "use client";
 
 import { useAuth } from "next-token-auth/react";
+import { useState } from "react";
 
 export default function LoginPage() {
   const { login, isLoading } = useAuth();
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = useState("");
+  const [error, setError] = useState("");
 
-  async function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
+  async function handleSubmit(e: React.FormEvent) {
     e.preventDefault();
-    const form = new FormData(e.currentTarget);
-    await login({ email: form.get("email"), password: form.get("password") });
+    setError("");
+
+    try {
+      await login({ email, password });
+      window.location.href = "/dashboard";
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Login failed");
+    }
   }
 
   return (
     <form onSubmit={handleSubmit}>
-      <input name="email" type="email" required />
-      <input name="password" type="password" required />
+      <input
+        type="email"
+        value={email}
+        onChange={(e) => setEmail(e.target.value)}
+        placeholder="Email"
+        required
+      />
+      <input
+        type="password"
+        value={password}
+        onChange={(e) => setPassword(e.target.value)}
+        placeholder="Password"
+        required
+      />
+      {error && <p style={{ color: "red" }}>{error}</p>}
       <button type="submit" disabled={isLoading}>
-        {isLoading ? "Signing in…" : "Sign in"}
+        {isLoading ? "Signing in..." : "Sign in"}
       </button>
     </form>
   );
@@ -171,80 +232,89 @@ export default function LoginPage() {
 
 ---
 
-## Usage
+### Step 6: Protect a page
 
-### `AuthProvider`
+```tsx
+// app/dashboard/page.tsx
+"use client";
 
-Wrap your application once at the root. It initializes the `AuthClient`, restores any existing session from stored tokens on mount, and subscribes all child hooks to session changes.
+import { useRequireAuth, useSession } from "next-token-auth/react";
 
-```tsx
-<AuthProvider config={authConfig}>
-  {children}
-</AuthProvider>
+export default function DashboardPage() {
+  // Redirects to /login if not authenticated
+  useRequireAuth();
+
+  const { user, isAuthenticated } = useSession();
+
+  if (!isAuthenticated) return null; // while redirecting
+
+  return (
+    <main>
+      <h1>Dashboard</h1>
+      <p>Welcome, {user?.name}</p>
+    </main>
+  );
+}
 ```
 
-When `autoRefresh: true` is set, the provider checks every 30 seconds whether the access token is near expiry and refreshes it silently in the background.
+---
+
+### Step 7: Add middleware (optional but recommended)
 
-#### Full config reference
+Protect routes at the edge for better performance and security.
 
 ```ts
-interface AuthConfig<User = unknown> {
-  // Base URL of your backend API
-  baseUrl: string;
+// middleware.ts (project root, next to app/)
+import { authMiddleware } from "next-token-auth/server";
+import { authConfig } from "@/lib/auth";
 
-  endpoints: {
-    login: string;       // required
-    refresh: string;     // required
-    register?: string;
-    logout?: string;
-    me?: string;         // fetched after login/session restore to populate user
-  };
+export const middleware = authMiddleware(authConfig);
 
-  routes?: {
-    public: string[];     // always accessible regardless of auth state
-    protected: string[];  // require auth, supports wildcard: "/dashboard*"
-    guestOnly?: string[]; // only accessible when NOT authenticated — any route name works
-    loginPath?: string;   // where to redirect unauthenticated users (default: "/login")
-    redirectAuthenticatedTo?: string; // where to send authenticated users who hit a guestOnly route (default: "/dashboard")
-  };
+export const config = {
+  // Run middleware on these routes
+  matcher: ["/login", "/register", "/dashboard*", "/profile*"],
+};
+```
 
-  token: {
-    storage: "cookie" | "memory";
-    cookieName?: string;   // default: "next-token-auth.session"
-    secure?: boolean;      // default: true
-    sameSite?: "strict" | "lax" | "none"; // default: "lax"
-  };
+**Next.js 16+ users:** Rename the file to `proxy.ts` and export `proxy` instead of `middleware`:
 
-  // Used to AES-GCM encrypt session cookies server-side
-  secret: string;
+```ts
+// proxy.ts
+export const proxy = authMiddleware(authConfig);
+```
 
-  // Automatically refresh the access token before it expires
-  autoRefresh?: boolean;
+---
 
-  // Seconds before expiry to trigger a proactive refresh (default: 60)
-  refreshThreshold?: number;
+## How It Works
 
-  expiry?: {
-    accessTokenExpiresIn?: number | string;  // e.g. "2d", 3600
-    refreshTokenExpiresIn?: number | string; // e.g. "7d"
-    strategy?: "backend" | "config" | "hybrid"; // default: "hybrid"
-  };
+### The Flow
 
-  // Provide a custom fetch implementation (e.g. for testing)
-  fetchFn?: typeof fetch;
+1. User submits login form → `useAuth().login()` is called
+2. Client sends credentials to `POST /api/auth/login` (your Route Handler)
+3. Route Handler calls your backend API, gets tokens back
+4. Route Handler encrypts tokens with your `secret` and sets an HttpOnly cookie
+5. Client receives `{ ok: true, user }` (no tokens — they're in the cookie)
+6. `AuthProvider` updates state → `session.isAuthenticated = true`
+7. On page reload, `AuthProvider` calls `GET /api/auth/session` to restore the session
+8. Route Handler decrypts the cookie, validates expiry, fetches user profile, returns `{ user, isAuthenticated }`
 
-  // Lifecycle callbacks
-  onLogin?: (session: AuthSession<User>) => void;
-  onLogout?: () => void;
-  onRefreshError?: (error: unknown) => void;
-}
-```
+### Why HttpOnly Cookies?
+
+Tokens stored in HttpOnly cookies cannot be read by JavaScript, which protects against XSS attacks. The browser automatically sends the cookie with every request to your domain, so you don't need to manually attach tokens.
+
+The downside: you can't call external APIs directly from the client with the access token. Instead, proxy through your own API routes (see "Making Authenticated API Requests" below).
+
+### Why Split the Config?
+
+If `secret` is in the client config, it gets bundled into your JavaScript and exposed to the browser. Splitting the config ensures the secret only exists server-side.
 
 ---
 
-### `useAuth`
+## API Reference
 
-The primary hook. Gives you everything you need to build auth flows.
+### `useAuth()`
+
+The main hook for authentication operations.
 
 ```ts
 const { session, login, logout, refresh, isLoading } = useAuth<User>();
@@ -252,27 +322,37 @@ const { session, login, logout, refresh, isLoading } = useAuth<User>();
 
 | Property    | Type                                    | Description                                      |
 |-------------|-----------------------------------------|--------------------------------------------------|
-| `session`   | `AuthSession<User>`                     | Current auth session                             |
-| `login`     | `(input: LoginInput) => Promise<void>`  | POST to your login endpoint, stores tokens       |
-| `logout`    | `() => Promise<void>`                   | Clears tokens, calls logout endpoint if set      |
-| `refresh`   | `() => Promise<void>`                   | Manually trigger a token refresh                 |
-| `isLoading` | `boolean`                               | `true` while initializing or during login        |
+| `session`   | `AuthSession<User>`                     | Current user and auth status                     |
+| `login`     | `(input: LoginInput) => Promise<void>`  | Authenticate user, sets HttpOnly cookie          |
+| `logout`    | `() => Promise<void>`                   | Clears session, calls backend logout if configured |
+| `refresh`   | `() => Promise<void>`                   | Manually refresh the access token                |
+| `isLoading` | `boolean`                               | `true` during initialization or login            |
+
+`LoginInput` is flexible — pass any fields your backend expects:
 
-`LoginInput` is an open object (`{ [key: string]: unknown }`), so you can pass any fields your backend expects.
+```ts
+await login({ email, password });
+await login({ username, password, rememberMe: true });
+```
 
 ---
 
-### `useSession`
+### `useSession()`
 
-Read-only access to the current session. Use this in components that only need to display user data.
+Read-only access to the current session. Use this in components that only display user data.
 
 ```ts
-const { user, tokens, isAuthenticated } = useSession<User>();
+const { user, isAuthenticated } = useSession<User>();
 ```
 
+Returns:
+- `user` — your user object (or `null` if not authenticated)
+- `tokens` — always `null` on the client (tokens are HttpOnly)
+- `isAuthenticated` — `true` if the user is logged in
+
 ---
 
-### `useRequireAuth`
+### `useRequireAuth(options?)`
 
 Redirects unauthenticated users. Call it at the top of any protected client component.
 
@@ -280,223 +360,272 @@ Redirects unauthenticated users. Call it at the top of any protected client comp
 useRequireAuth({ redirectTo: "/login" });
 ```
 
-You can also pass a custom handler instead of a redirect path:
+Options:
+
+| Option              | Type         | Default    | Description                                      |
+|---------------------|--------------|------------|--------------------------------------------------|
+| `redirectTo`        | `string`     | `"/login"` | Where to send unauthenticated users              |
+| `onUnauthenticated` | `() => void` | —          | Custom handler instead of redirect               |
+
+The hook waits for `isLoading` to finish before redirecting, so you won't see a flash.
+
+Custom redirect example:
 
 ```ts
+import { useRouter } from "next/navigation";
+
 useRequireAuth({
   onUnauthenticated: () => router.push("/login?from=/dashboard"),
 });
 ```
 
-The hook waits for `isLoading` to be `false` before acting, so it won't flash a redirect during the initial session restore.
-
-| Option              | Type         | Default    |
-|---------------------|--------------|------------|
-| `redirectTo`        | `string`     | `"/login"` |
-| `onUnauthenticated` | `() => void` | —          |
-
 ---
 
 ### Making Authenticated API Requests
 
-When you need to call your own backend endpoints that require an access token, use `client.fetch` from the `useAuth` hook. It automatically injects `Authorization: Bearer <token>` and handles 401 → refresh → retry for you.
+Since tokens are in HttpOnly cookies (inaccessible to JavaScript), you can't add `Authorization` headers from the client. Instead, proxy through your own API routes.
+
+**Client-side:**
 
 ```ts
 "use client";
 
-import { useAuth } from "next-token-auth/react";
-
-export default function Orders() {
-  const { client } = useAuth();
-
-  async function fetchOrders() {
-    const res = await client.fetch("https://api.example.com/orders");
+export default function OrdersPage() {
+  async function loadOrders() {
+    // The session cookie is automatically sent with this request
+    const res = await fetch("/api/orders");
     const data = await res.json();
     console.log(data);
   }
 
-  return <button onClick={fetchOrders}>Load Orders</button>;
+  return <button onClick={loadOrders}>Load Orders</button>;
 }
 ```
 
-You can also read the token directly from the session if you need to pass it manually:
+**Server-side (your API route):**
 
 ```ts
-const { session } = useAuth();
+// app/api/orders/route.ts
+import { getServerSession } from "next-token-auth/server";
+import { authConfig } from "@/lib/auth";
+import { cookies } from "next/headers";
 
-const res = await fetch("https://api.example.com/orders", {
-  headers: {
-    Authorization: `Bearer ${session.tokens?.accessToken}`,
-  },
-});
+export async function GET() {
+  const cookieStore = await cookies();
+  const session = await getServerSession(
+    { cookies: { get: (name) => cookieStore.get(name) } },
+    authConfig
+  );
+
+  if (!session.isAuthenticated) {
+    return Response.json({ error: "Unauthorized" }, { status: 401 });
+  }
+
+  // Now call your backend with the access token
+  const res = await fetch(`${authConfig.baseUrl}/orders`, {
+    headers: {
+      Authorization: `Bearer ${session.tokens!.accessToken}`,
+    },
+  });
+
+  return Response.json(await res.json());
+}
 ```
 
-`client.fetch` is the recommended approach — it keeps your requests resilient to token expiry without any extra work on your end.
+This keeps tokens secure — they never leave the server.
 
 ---
 
-### Protecting API Routes with `withAuth`
+### `getServerSession(req, config)`
 
-Wrap App Router route handlers to require authentication:
+Reads and validates the session in server components and API routes.
 
 ```ts
-// app/api/profile/route.ts
-import { withAuth } from "next-token-auth/server";
+// app/dashboard/page.tsx (server component)
+import { redirect } from "next/navigation";
+import { cookies } from "next/headers";
+import { getServerSession } from "next-token-auth/server";
 import { authConfig } from "@/lib/auth";
 
-export const GET = withAuth(authConfig, async (req, session) => {
-  return Response.json({ user: session.user });
-});
+export default async function DashboardPage() {
+  const cookieStore = await cookies();
+  const session = await getServerSession(
+    { cookies: { get: (name) => cookieStore.get(name) } },
+    authConfig
+  );
+
+  if (!session.isAuthenticated) {
+    redirect("/login");
+  }
+
+  return <h1>Welcome, {session.user.name}</h1>;
+}
 ```
 
-Unauthenticated requests are redirected to `/login` by default. Pass `{ redirectTo: "/your-path" }` as the third argument to override.
+What it does:
+1. Reads the encrypted session cookie
+2. Decrypts it using your `secret`
+3. Validates token expiry
+4. Optionally fetches the user profile from your backend
+5. Returns `{ user, tokens, isAuthenticated }`
 
 ---
 
-### Middleware (Edge Route Protection)
+### `withAuth(config, handler, options?)`
 
-Protect entire route groups at the edge using Next.js middleware. The middleware supports three route categories:
+Wraps App Router route handlers to require authentication.
 
-- `public` — always accessible, no auth check
-- `protected` — requires authentication, redirects to `loginPath` if not
-- `guestOnly` — accessible only when NOT authenticated; authenticated users are redirected to `redirectAuthenticatedTo`
+```ts
+// app/api/profile/route.ts
+import { withAuth } from "next-token-auth/server";
+import { authConfig } from "@/lib/auth";
+
+export const GET = withAuth(authConfig, async (req, session) => {
+  // session.user is guaranteed to exist here
+  return Response.json({ user: session.user });
+});
+```
 
-You can use any route naming convention you want — the library doesn't enforce `/login`, `/dashboard`, or any specific path. Everything is driven by your config.
+Unauthenticated requests are redirected to `/login` by default. Override with:
 
 ```ts
-// lib/auth.ts
-export const authConfig: AuthConfig = {
-  // ...
-  routes: {
-    public: ["/", "/about"],
-    guestOnly: ["/sign-in", "/sign-up"],   // any names you want
-    protected: ["/app*", "/account*"],
-    loginPath: "/sign-in",                 // where unauthenticated users are sent
-    redirectAuthenticatedTo: "/app/home",  // where authenticated users are sent from guestOnly routes
-  },
-};
+export const GET = withAuth(
+  authConfig,
+  async (req, session) => { /* ... */ },
+  { redirectTo: "/sign-in" }
+);
 ```
 
+---
+
+### `authMiddleware(config)`
+
+Creates a Next.js middleware function for edge-level route protection.
+
 ```ts
-// middleware.ts (project root)
+// middleware.ts (project root, next to app/)
 import { authMiddleware } from "next-token-auth/server";
 import { authConfig } from "@/lib/auth";
 
 export const middleware = authMiddleware(authConfig);
 
 export const config = {
-  matcher: ["/sign-in", "/sign-up", "/app*", "/account*"],
+  matcher: ["/login", "/register", "/dashboard*", "/profile*"],
 };
 ```
 
-Some other valid setups:
+**Next.js 16+ users:** Rename the file to `proxy.ts` and change the export:
 
 ```ts
-// Using /auth/* convention
-routes: {
-  guestOnly: ["/auth/login", "/auth/register"],
-  protected: ["/dashboard*"],
-  loginPath: "/auth/login",
-  redirectAuthenticatedTo: "/dashboard",
-}
+// proxy.ts
+export const proxy = authMiddleware(authConfig);
+```
+
+---
+
+## Route Protection Explained
+
+The middleware supports three route categories:
 
-// Using a portal pattern
+### 1. Public routes
+
+Always accessible, no auth check. Example: homepage, about page.
+
+```ts
 routes: {
-  guestOnly: ["/portal"],
-  protected: ["/admin*", "/workspace*"],
-  loginPath: "/portal",
-  redirectAuthenticatedTo: "/admin",
+  public: ["/", "/about", "/pricing"],
 }
 ```
 
-Route resolution order inside the middleware:
+### 2. Protected routes
 
-1. `guestOnly` — if authenticated, redirect to `redirectAuthenticatedTo`
-2. `public` — always allow through
-3. `protected` — require valid session, redirect to `loginPath` if missing
+Require authentication. Unauthenticated users are redirected to `loginPath`.
 
-Two things to keep in mind:
+```ts
+routes: {
+  protected: ["/dashboard*", "/settings*"],
+  loginPath: "/login",  // where to send unauthenticated users
+}
+```
 
-- Wildcard patterns use `*` at the end: `"/dashboard*"` matches `/dashboard`, `/dashboard/`, and `/dashboard/settings`
-- The `matcher` in `export const config` controls which routes Next.js runs the middleware on at all — make sure it covers both your protected and guest-only routes
-- `loginPath` defaults to `"/login"` if not set
-- `redirectAuthenticatedTo` defaults to `"/dashboard"` if not set
+Wildcard matching:
+- `"/dashboard*"` matches `/dashboard`, `/dashboard/`, `/dashboard/settings`
+- `"/api/admin*"` matches `/api/admin`, `/api/admin/users`
 
----
+### 3. Guest-only routes
 
-## Session and Token Handling
+Only accessible when NOT authenticated. Authenticated users are redirected away.
 
-### How tokens are stored
+Use this for login and register pages so logged-in users can't access them.
 
-| Storage mode | Where                                                                 |
-|--------------|-----------------------------------------------------------------------|
-| `"cookie"`   | Serialized as JSON in a browser cookie with `Secure` + `SameSite`    |
-| `"memory"`   | Held in a JavaScript variable — cleared on page refresh               |
+```ts
+routes: {
+  guestOnly: ["/login", "/register"],
+  redirectAuthenticatedTo: "/dashboard",  // where to send authenticated users
+}
+```
 
-Server-side (in `getServerSession` and `authMiddleware`), the cookie value is expected to be AES-GCM encrypted using your `secret`. The `TokenManager` provides `encryptTokens` / `decryptTokens` helpers for this.
+### Resolution order
 
-### Session restore on page load
+When a request hits the middleware:
 
-When `AuthProvider` mounts, it calls `client.initialize()`, which:
+1. Check if it's a `guestOnly` route → if authenticated, redirect to `redirectAuthenticatedTo`
+2. Check if it's a `public` route → always allow through
+3. Check if it's a `protected` route → if not authenticated, redirect to `loginPath`
 
-1. Reads tokens from the configured storage
-2. Checks whether the access token is expired (accounting for `refreshThreshold`)
-3. If the access token is near expiry but the refresh token is still valid, it silently refreshes
-4. If a `me` endpoint is configured, it fetches the user profile to populate `session.user`
-5. Updates React state — `isLoading` flips to `false` once complete
+### Matcher vs routes config
 
-### Automatic refresh
+The `matcher` in your middleware file controls which routes Next.js runs the middleware on at all:
 
-When `autoRefresh: true`, the provider runs a check every 30 seconds. If the access token is within `refreshThreshold` seconds of expiry (default: 60s) and the refresh token is still valid, it calls the refresh endpoint automatically.
+```ts
+export const config = {
+  matcher: ["/login", "/dashboard*"],
+};
+```
 
-The HTTP client also handles 401 responses: it attempts a token refresh and retries the original request once. Multiple concurrent 401s share a single refresh request (deduplicated via a shared promise).
+If a route isn't in the `matcher`, the middleware never runs for it — so your `routes.protected` list won't help. Make sure the `matcher` covers all routes you want to protect or mark as guest-only.
 
-### Refresh flow
+---
 
-```
-Request → 401 → refresh endpoint → new tokens stored → original request retried
-```
+## Session and Token Handling
 
-If the refresh token is expired, the user is logged out and the session is cleared.
+### How tokens are stored
 
----
+Tokens are stored in HttpOnly cookies, encrypted with AES-GCM. The cookie is set by the `/api/auth/login` Route Handler and read by the middleware and `getServerSession`.
 
-## Server-Side Session (`getServerSession`)
+JavaScript in the browser cannot read the cookie — only the server can decrypt it.
 
-Use this in App Router server components and API routes to read the session without going through the client:
+### Session restore on page load
 
-```ts
-// app/dashboard/page.tsx
-import { redirect } from "next/navigation";
-import { cookies } from "next/headers";
-import { getServerSession } from "next-token-auth/server";
-import { authConfig } from "@/lib/auth";
+When `AuthProvider` mounts, it calls `GET /api/auth/session`, which:
 
-export default async function DashboardPage() {
-  const cookieStore = await cookies();
+1. Reads the encrypted session cookie server-side
+2. Decrypts it using your `secret`
+3. Checks if the refresh token is expired
+4. Fetches the user profile from your backend (if `me` endpoint is configured)
+5. Returns `{ user, isAuthenticated }` to the client
 
-  const session = await getServerSession(
-    { cookies: { get: (name) => cookieStore.get(name) } },
-    authConfig
-  );
+The client never sees the raw tokens — only the user object and auth status.
 
-  if (!session.isAuthenticated) {
-    redirect("/login");
-  }
+### Automatic token refresh
 
-  return <h1>Welcome, {session.user.name}</h1>;
-}
-```
+When `autoRefresh: true`, the provider periodically calls `POST /api/auth/refresh` (based on `refreshThreshold`, default 60 seconds before expiry).
+
+The Route Handler:
+1. Reads the encrypted cookie
+2. Checks if the refresh token is still valid
+3. Calls your backend's refresh endpoint with the refresh token
+4. Encrypts the new tokens and updates the HttpOnly cookie
 
-`getServerSession` decrypts the session cookie, validates expiry, and attempts a server-side token refresh if the access token is near expiry but the refresh token is still valid.
+If the refresh token is expired, the session is cleared.
 
 ---
 
-## Backend Requirements
+## Backend API Requirements
 
-Your API needs to implement the following contract:
+Your backend needs to implement these endpoints:
 
-### `POST /auth/login`
+### `POST /auth/login` (or whatever you set in `endpoints.login`)
 
 Request body: whatever fields you pass to `login()` (e.g. `{ email, password }`)
 
@@ -504,9 +633,13 @@ Response:
 
 ```json
 {
-  "accessToken": "eyJ...",
-  "refreshToken": "eyJ...",
-  "user": { "id": "1", "email": "user@example.com", "name": "Jane" },
+  "accessToken": "eyJhbGc...",
+  "refreshToken": "eyJhbGc...",
+  "user": {
+    "id": "123",
+    "email": "user@example.com",
+    "name": "Jane Doe"
+  },
 
   // Optional — used by "backend" and "hybrid" expiry strategies
   "accessTokenExpiresIn": "2d",
@@ -522,39 +655,53 @@ Response:
 Request body:
 
 ```json
-{ "refreshToken": "eyJ..." }
+{
+  "refreshToken": "eyJhbGc..."
+}
 ```
 
 Response: same shape as the login response (new `accessToken` + `refreshToken`).
 
-### `GET /auth/me` _(optional)_
+### `GET /auth/me` (optional)
 
 Returns the current user object. Called after login and on session restore if the `me` endpoint is configured.
 
-### `POST /auth/logout` _(optional)_
+Response:
+
+```json
+{
+  "id": "123",
+  "email": "user@example.com",
+  "name": "Jane Doe"
+}
+```
+
+### `POST /auth/logout` (optional)
 
-Called on logout. Failure is silently ignored — tokens are always cleared locally regardless.
+Called on logout. Failure is silently ignored — the session cookie is always cleared locally regardless.
 
 ---
 
 ## Expiry Formats
 
-The `parseExpiry` utility accepts:
+The library accepts expiry values in multiple formats:
 
-| Input   | Seconds   |
-|---------|-----------|
-| `900`   | 900       |
-| `"15m"` | 900       |
-| `"2h"`  | 7 200     |
-| `"2d"`  | 172 800   |
-| `"7d"`  | 604 800   |
-| `"1w"`  | 604 800   |
+| Input   | Seconds   | Human-readable |
+|---------|-----------|----------------|
+| `900`   | 900       | 15 minutes     |
+| `"15m"` | 900       | 15 minutes     |
+| `"2h"`  | 7,200     | 2 hours        |
+| `"2d"`  | 172,800   | 2 days         |
+| `"7d"`  | 604,800   | 7 days         |
+| `"1w"`  | 604,800   | 1 week         |
+
+Supported units: `s` (seconds), `m` (minutes), `h` (hours), `d` (days), `w` (weeks)
 
 ### Expiry strategies
 
-| Strategy  | Behaviour                                                        |
+| Strategy  | Behavior                                                         |
 |-----------|------------------------------------------------------------------|
-| `backend` | Use only the expiry values returned by the API                   |
+| `backend` | Use only the expiry values returned by your API                  |
 | `config`  | Use only the values set in `expiry` config                       |
 | `hybrid`  | API response first; fall back to config if not present (default) |
 
@@ -562,12 +709,85 @@ The `parseExpiry` utility accepts:
 
 ---
 
+## Configuration Reference
+
+### `ClientAuthConfig` (for `AuthProvider`)
+
+```ts
+interface ClientAuthConfig {
+  token?: {
+    cookieName?: string;  // default: "next-token-auth.session"
+  };
+
+  routes?: {
+    loginPath?: string;   // default: "/login"
+    redirectAuthenticatedTo?: string; // default: "/dashboard"
+  };
+
+  autoRefresh?: boolean;  // default: false
+  refreshThreshold?: number; // seconds before expiry to refresh (default: 60)
+
+  onLogin?: (session: AuthSession) => void;
+  onLogout?: () => void;
+}
+```
+
+### `AuthConfig` (for server-side functions)
+
+```ts
+interface AuthConfig<User = unknown> {
+  baseUrl: string;  // Your backend API base URL
+
+  endpoints: {
+    login: string;       // required
+    refresh: string;     // required
+    register?: string;
+    logout?: string;
+    me?: string;
+  };
+
+  routes?: {
+    public: string[];     // always accessible
+    protected: string[];  // require auth
+    guestOnly?: string[]; // only when NOT authenticated
+    loginPath?: string;   // default: "/login"
+    redirectAuthenticatedTo?: string; // default: "/dashboard"
+  };
+
+  token: {
+    storage: "cookie" | "memory";
+    cookieName?: string;
+    secure?: boolean;      // default: true
+    sameSite?: "strict" | "lax" | "none"; // default: "lax"
+  };
+
+  secret: string;  // AES-GCM encryption key
+
+  autoRefresh?: boolean;
+  refreshThreshold?: number;
+
+  expiry?: {
+    accessTokenExpiresIn?: number | string;
+    refreshTokenExpiresIn?: number | string;
+    strategy?: "backend" | "config" | "hybrid";
+  };
+
+  fetchFn?: typeof fetch;  // custom fetch for testing
+
+  onLogin?: (session: AuthSession<User>) => void;
+  onLogout?: () => void;
+  onRefreshError?: (error: unknown) => void;
+}
+```
+
+---
+
 ## TypeScript Types
 
 ```ts
 interface AuthSession<User = unknown> {
   user: User | null;
-  tokens: AuthTokens | null;
+  tokens: AuthTokens | null;  // always null on client-side (HttpOnly)
   isAuthenticated: boolean;
 }
 
@@ -575,7 +795,7 @@ interface AuthTokens {
   accessToken: string;
   refreshToken: string;
   accessTokenExpiresAt: number;   // Unix timestamp in ms
-  refreshTokenExpiresAt?: number; // Unix timestamp in ms
+  refreshTokenExpiresAt?: number;
 }
 
 interface LoginResponse<User = unknown> {
@@ -586,12 +806,102 @@ interface LoginResponse<User = unknown> {
   accessTokenExpiresIn?: number | string;
   refreshTokenExpiresIn?: number | string;
 }
+```
+
+All types are exported from `next-token-auth`.
+
+---
 
-type ExpiryInput = number | string;
-type ExpiryStrategy = "backend" | "config" | "hybrid";
+## Common Patterns
+
+### Custom user type
+
+```ts
+interface MyUser {
+  id: string;
+  email: string;
+  role: "admin" | "user";
+}
+
+const { session } = useAuth<MyUser>();
+console.log(session.user?.role);
+```
+
+### Logout with redirect
+
+```ts
+const { logout } = useAuth();
+
+async function handleLogout() {
+  await logout();
+  window.location.href = "/";
+}
+```
+
+### Conditional rendering based on auth
+
+```ts
+const { isAuthenticated } = useSession();
+
+return (
+  <nav>
+    {isAuthenticated ? (
+      <a href="/dashboard">Dashboard</a>
+    ) : (
+      <a href="/login">Sign in</a>
+    )}
+  </nav>
+);
 ```
 
-All types are exported from the root `next-token-auth` import.
+### Server-side redirect in a server component
+
+```ts
+import { redirect } from "next/navigation";
+import { getServerSession } from "next-token-auth/server";
+
+export default async function AdminPage() {
+  const session = await getServerSession(req, authConfig);
+
+  if (!session.isAuthenticated) {
+    redirect("/login");
+  }
+
+  if (session.user.role !== "admin") {
+    redirect("/dashboard");
+  }
+
+  return <h1>Admin Panel</h1>;
+}
+```
+
+---
+
+## Troubleshooting
+
+### "Cannot find module 'next-token-auth/server'"
+
+Run `npm run build` (or `pnpm build`) to generate the `dist/` folder. The package uses subpath exports (`/server`, `/react`) which require a build step.
+
+### Middleware always redirects to login
+
+Check three things:
+
+1. The `matcher` in your `middleware.ts` includes the route you're testing
+2. The route is listed in `routes.protected` or not listed in `routes.public`
+3. You're actually logged in — check the Application tab in DevTools for the session cookie
+
+### "secret is undefined"
+
+Make sure `AUTH_SECRET` is set in your `.env.local` file and you're importing `authConfig` (not `clientAuthConfig`) in your Route Handler and middleware.
+
+### Session is lost on page reload
+
+The session should persist via the HttpOnly cookie. If it's not:
+
+1. Check that `cookieName` matches in both `authConfig` and `clientAuthConfig`
+2. Verify the cookie exists in DevTools → Application → Cookies
+3. Make sure `app/api/auth/[action]/route.ts` exists and exports `createAuthHandlers(authConfig)`
 
 ---
 
@@ -604,13 +914,14 @@ All types are exported from the root `next-token-auth` import.
 
 ---
 
-## Security Notes
+## Security
 
-- Session cookies use `Secure` and `SameSite` flags by default
-- Server-side cookies are AES-GCM encrypted using your `secret`
+- Tokens are stored in HttpOnly cookies — JavaScript cannot read them
+- Cookies are AES-GCM encrypted server-side using your `secret`
+- The `secret` never leaves the server — it's only used in Route Handlers, middleware, and `getServerSession`
+- `AuthProvider` receives `ClientAuthConfig` which does not contain `secret` or `baseUrl`
+- Cookies use `Secure` and `SameSite` flags by default for CSRF protection
 - Use a random 32-character string for `secret` in production — never commit it
-- The `"memory"` storage mode keeps tokens out of cookies entirely, at the cost of losing the session on page refresh
-- Refresh tokens are never exposed to JavaScript when using server-side encrypted cookies
 
 ---