next-token-auth 1.0.15 → 1.0.17

package/README.md

@@ -1,55 +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.
 
-> **Breaking change in v1.1.0:** The secret is now server-side only. You must split your config into `AuthConfig` (server) and `ClientAuthConfig` (client), and mount `createAuthHandlers` at `app/api/auth/[action]/route.ts`. See the Quick Start below.
+> **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.
 
 ---
 
-## The Problem
+## Why This Exists
 
-Authentication in Next.js involves a lot of moving parts:
+Authentication in Next.js is tedious. You need to:
 
-- 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
+- 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
 
-Most projects end up with hundreds of lines of boilerplate before a single feature is built.
+Most projects spend days on auth boilerplate before shipping a single feature.
 
----
-
-## The Solution
-
-`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:
-
-- 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
 
 ---
 
@@ -57,30 +43,23 @@ 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 server 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 (SERVER-SIDE ONLY — never import in client components)
+// lib/auth.ts
 import type { AuthConfig } from "next-token-auth";
 
 interface User {
@@ -90,23 +69,27 @@ interface User {
 }
 
 export const authConfig: AuthConfig<User> = {
-  baseUrl: process.env.API_URL!,  // No NEXT_PUBLIC_ prefix needed
+  // 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*"],
-    loginPath: "/login",
-    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",
@@ -114,33 +97,48 @@ export const authConfig: AuthConfig<User> = {
     sameSite: "lax",
   },
 
-  secret: process.env.AUTH_SECRET!,  // SERVER-SIDE ONLY
+  // 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
   },
 };
 ```
 
-### 2. Create your client 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 (safe to import anywhere, including client components)
+// lib/auth.client.ts
 import type { ClientAuthConfig } from "next-token-auth";
 
 export const clientAuthConfig: ClientAuthConfig = {
   token: {
-    cookieName: "myapp.session",
+    cookieName: "myapp.session",  // must match server config
   },
   autoRefresh: true,
 };
 ```
 
-### 3. Mount the Route Handlers
+---
+
+### Step 3: Mount the Route Handlers
+
+Create this file to handle login, logout, refresh, and session endpoints automatically.
+
+**Important:** The file path must be exactly `app/api/auth/[action]/route.ts` — the `[action]` part is a Next.js dynamic route segment (keep the square brackets as-is). Do not rename it.
 
 ```ts
 // app/api/auth/[action]/route.ts
@@ -150,13 +148,17 @@ import { authConfig } from "@/lib/auth";
 export const { GET, POST } = createAuthHandlers(authConfig);
 ```
 
-This creates four endpoints automatically:
+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
 
-### 4. Wrap your app with `AuthProvider`
+Your `AuthProvider` calls these automatically. You never call them directly.
+
+---
+
+### Step 4: Wrap your app
 
 ```tsx
 // app/layout.tsx
@@ -167,36 +169,63 @@ export default function RootLayout({ children }: { children: React.ReactNode })
   return (
     <html lang="en">
       <body>
-        <AuthProvider config={clientAuthConfig}>{children}</AuthProvider>
+        <AuthProvider config={clientAuthConfig}>
+          {children}
+        </AuthProvider>
       </body>
     </html>
   );
 }
 ```
 
-### 5. 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") });
-    window.location.href = "/dashboard";
+    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>
   );
@@ -205,101 +234,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 calls `/api/auth/session` on mount to restore the session from the HttpOnly cookie, then subscribes to session changes.
+import { useRequireAuth, useSession } from "next-token-auth/react";
 
-```tsx
-<AuthProvider config={clientAuthConfig}>
-  {children}
-</AuthProvider>
-```
+export default function DashboardPage() {
+  // Redirects to /login if not authenticated
+  useRequireAuth();
 
-When `autoRefresh: true` is set, the provider calls `/api/auth/refresh` periodically based on `refreshThreshold`.
+  const { user, isAuthenticated } = useSession();
 
-#### Client config reference (`ClientAuthConfig`)
+  if (!isAuthenticated) return null; // while redirecting
 
-This is what you pass to `AuthProvider` — it does NOT contain `secret` or `baseUrl`.
+  return (
+    <main>
+      <h1>Dashboard</h1>
+      <p>Welcome, {user?.name}</p>
+    </main>
+  );
+}
+```
 
-```ts
-interface ClientAuthConfig {
-  token?: {
-    cookieName?: string;   // default: "next-token-auth.session"
-  };
+---
 
-  routes?: {
-    loginPath?: string;   // where to redirect unauthenticated users (default: "/login")
-    redirectAuthenticatedTo?: string; // where to redirect authenticated users on guestOnly routes (default: "/dashboard")
-  };
+### Step 7: Add middleware (optional but recommended)
 
-  autoRefresh?: boolean;  // automatically refresh tokens before expiry
+Protect routes at the edge for better performance and security.
 
-  refreshThreshold?: number; // seconds before expiry to trigger refresh (default: 60)
+```ts
+// middleware.ts (project root, next to app/)
+import { authMiddleware } from "next-token-auth/server";
+import { authConfig } from "@/lib/auth";
 
-  // Lifecycle callbacks
-  onLogin?: (session: AuthSession) => void;
-  onLogout?: () => void;
-}
-```
+export const middleware = authMiddleware(authConfig);
 
-#### Server config reference (`AuthConfig`)
+export const config = {
+  // Run middleware on these routes
+  matcher: ["/login", "/register", "/dashboard*", "/profile*"],
+};
+```
 
-This is used in `createAuthHandlers`, `authMiddleware`, `getServerSession`, and `withAuth`. Never import this in a client component.
+**Next.js 16+ users:** Rename the file to `proxy.ts` and export `proxy` instead of `middleware`:
 
 ```ts
-interface AuthConfig<User = unknown> {
-  baseUrl: string;  // Backend API base URL (no NEXT_PUBLIC_ needed)
+// proxy.ts
+export const proxy = authMiddleware(authConfig);
+```
 
-  endpoints: {
-    login: string;       // required
-    refresh: string;     // required
-    register?: string;
-    logout?: string;
-    me?: string;         // fetched to populate session.user
-  };
+---
 
-  routes?: {
-    public: string[];     // always accessible
-    protected: string[];  // require auth, supports wildcard: "/dashboard*"
-    guestOnly?: string[]; // only accessible when NOT authenticated
-    loginPath?: string;   // where to redirect unauthenticated users (default: "/login")
-    redirectAuthenticatedTo?: string; // where to redirect authenticated users on guestOnly routes (default: "/dashboard")
-  };
+## How It Works
 
-  token: {
-    storage: "cookie" | "memory";
-    cookieName?: string;
-    secure?: boolean;      // default: true
-    sameSite?: "strict" | "lax" | "none"; // default: "lax"
-  };
+### The Flow
 
-  secret: string;  // AES-GCM encryption key — SERVER-SIDE ONLY
+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 }`
 
-  autoRefresh?: boolean;
-  refreshThreshold?: number;
+### Why HttpOnly Cookies?
 
-  expiry?: {
-    accessTokenExpiresIn?: number | string;  // e.g. "2d", 3600
-    refreshTokenExpiresIn?: number | string; // e.g. "7d"
-    strategy?: "backend" | "config" | "hybrid"; // default: "hybrid"
-  };
+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.
 
-  fetchFn?: typeof fetch;
+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).
 
-  // Lifecycle callbacks
-  onLogin?: (session: AuthSession<User>) => void;
-  onLogout?: () => void;
-  onRefreshError?: (error: unknown) => void;
-}
-```
+### 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
+
+### `useAuth()`
 
-The primary hook. Gives you everything you need to build auth flows.
+The main hook for authentication operations.
 
 ```ts
 const { session, login, logout, refresh, isLoading } = useAuth<User>();
@@ -307,27 +324,37 @@ const { session, login, logout, refresh, isLoading } = useAuth<User>();
 
 | Property    | Type                                    | Description                                      |
 |-------------|-----------------------------------------|--------------------------------------------------|
-| `session`   | `AuthSession<User>`                     | Current auth session (user + isAuthenticated)    |
-| `login`     | `(input: LoginInput) => Promise<void>`  | POST to `/api/auth/login`, sets HttpOnly cookie  |
-| `logout`    | `() => Promise<void>`                   | POST to `/api/auth/logout`, clears cookie        |
-| `refresh`   | `() => Promise<void>`                   | POST to `/api/auth/refresh`, updates cookie      |
-| `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 an open object (`{ [key: string]: unknown }`), so you can pass any fields your backend expects.
+`LoginInput` is flexible — 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.
 
@@ -335,45 +362,49 @@ 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
 
-Since tokens are stored in HttpOnly cookies (inaccessible to JavaScript), you cannot manually add `Authorization` headers from the client. Instead, your backend API routes should read the session cookie and extract the access token server-side.
+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.
 
-For client-side requests to your own API:
+**Client-side:**
 
 ```ts
 "use client";
 
-export default function Orders() {
-  async function fetchOrders() {
+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>;
 }
 ```
 
-Then in your API route, read the session:
+**Server-side (your API route):**
 
 ```ts
 // app/api/orders/route.ts
@@ -381,7 +412,7 @@ import { getServerSession } from "next-token-auth/server";
 import { authConfig } from "@/lib/auth";
 import { cookies } from "next/headers";
 
-export async function GET(req: Request) {
+export async function GET() {
   const cookieStore = await cookies();
   const session = await getServerSession(
     { cookies: { get: (name) => cookieStore.get(name) } },
@@ -392,9 +423,11 @@ export async function GET(req: Request) {
     return Response.json({ error: "Unauthorized" }, { status: 401 });
   }
 
-  // Use session.tokens.accessToken to call your backend
+  // Now call your backend with the access token
   const res = await fetch(`${authConfig.baseUrl}/orders`, {
-    headers: { Authorization: `Bearer ${session.tokens!.accessToken}` },
+    headers: {
+      Authorization: `Bearer ${session.tokens!.accessToken}`,
+    },
   });
 
   return Response.json(await res.json());
@@ -405,9 +438,44 @@ This keeps tokens secure — they never leave the server.
 
 ---
 
-### Protecting API Routes with `withAuth`
+### `getServerSession(req, config)`
+
+Reads and validates the session in server components and API routes.
+
+```ts
+// 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 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>;
+}
+```
+
+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 }`
+
+---
+
+### `withAuth(config, handler, options?)`
 
-Wrap App Router route handlers to require authentication:
+Wraps App Router route handlers to require authentication.
 
 ```ts
 // app/api/profile/route.ts
@@ -415,86 +483,109 @@ 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 });
 });
 ```
 
-Unauthenticated requests are redirected to `/login` by default. Pass `{ redirectTo: "/your-path" }` as the third argument to override.
+Unauthenticated requests are redirected to `/login` by default. Override with:
+
+```ts
+export const GET = withAuth(
+  authConfig,
+  async (req, session) => { /* ... */ },
+  { redirectTo: "/sign-in" }
+);
+```
 
 ---
 
-### Middleware (Edge Route Protection)
+### `authMiddleware(config)`
 
-Protect entire route groups at the edge using Next.js middleware. The middleware supports three route categories:
+Creates a Next.js middleware function for edge-level route protection.
 
-- `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
+// middleware.ts (project root, next to app/)
+import { authMiddleware } from "next-token-auth/server";
+import { authConfig } from "@/lib/auth";
 
-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.
+export const middleware = authMiddleware(authConfig);
 
-```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 config = {
+  matcher: ["/login", "/register", "/dashboard*", "/profile*"],
 };
 ```
 
+**Next.js 16+ users:** Rename the file to `proxy.ts` and change the export:
+
 ```ts
-// middleware.ts (Next.js 13–15) or proxy.ts (Next.js 16+)
-import { authMiddleware } from "next-token-auth/server";
-import { authConfig } from "@/lib/auth";
+// proxy.ts
+export const proxy = authMiddleware(authConfig);
+```
 
-// Next.js 13–15
-export const middleware = authMiddleware(authConfig);
+---
 
-// Next.js 16+
-export const proxy = authMiddleware(authConfig);
+## Route Protection Explained
 
-export const config = {
-  matcher: ["/sign-in", "/sign-up", "/app*", "/account*"],
-};
+The middleware supports three route categories:
+
+### 1. Public routes
+
+Always accessible, no auth check. Example: homepage, about page.
+
+```ts
+routes: {
+  public: ["/", "/about", "/pricing"],
+}
 ```
 
-Some other valid setups:
+### 2. Protected routes
+
+Require authentication. Unauthenticated users are redirected to `loginPath`.
 
 ```ts
-// Using /auth/* convention
 routes: {
-  guestOnly: ["/auth/login", "/auth/register"],
-  protected: ["/dashboard*"],
-  loginPath: "/auth/login",
-  redirectAuthenticatedTo: "/dashboard",
+  protected: ["/dashboard*", "/settings*"],
+  loginPath: "/login",  // where to send unauthenticated users
 }
+```
+
+Wildcard matching:
+- `"/dashboard*"` matches `/dashboard`, `/dashboard/`, `/dashboard/settings`
+- `"/api/admin*"` matches `/api/admin`, `/api/admin/users`
+
+### 3. Guest-only routes
+
+Only accessible when NOT authenticated. Authenticated users are redirected away.
+
+Use this for login and register pages so logged-in users can't access them.
 
-// Using a portal pattern
+```ts
 routes: {
-  guestOnly: ["/portal"],
-  protected: ["/admin*", "/workspace*"],
-  loginPath: "/portal",
-  redirectAuthenticatedTo: "/admin",
+  guestOnly: ["/login", "/register"],
+  redirectAuthenticatedTo: "/dashboard",  // where to send authenticated users
 }
 ```
 
-Route resolution order inside the middleware:
+### Resolution order
+
+When a request hits the middleware:
 
-1. `guestOnly` — if authenticated, redirect to `redirectAuthenticatedTo`
-2. `public` — always allow through
-3. `protected` — require valid session, redirect to `loginPath` if missing
+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`
 
-Two things to keep in mind:
+### Matcher vs routes config
 
-- 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
+The `matcher` in your middleware file controls which routes Next.js runs the middleware on at all:
+
+```ts
+export const config = {
+  matcher: ["/login", "/dashboard*"],
+};
+```
+
+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.
 
 ---
 
@@ -502,9 +593,9 @@ Two things to keep in mind:
 
 ### How tokens are stored
 
-Tokens are always stored in HttpOnly cookies (encrypted with AES-GCM). The `storage: "memory"` option is deprecated — HttpOnly cookies are more secure because JavaScript in the browser cannot access them.
+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`.
 
-The cookie is set by the `/api/auth/login` Route Handler (created via `createAuthHandlers`) and read by the middleware and `getServerSession`.
+JavaScript in the browser cannot read the cookie — only the server can decrypt it.
 
 ### Session restore on page load
 
@@ -512,67 +603,31 @@ When `AuthProvider` mounts, it calls `GET /api/auth/session`, which:
 
 1. Reads the encrypted session cookie server-side
 2. Decrypts it using your `secret`
-3. Checks whether the refresh token is expired
-4. If a `me` endpoint is configured, fetches the user profile
+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
 
 The client never sees the raw tokens — only the user object and auth status.
 
-### Automatic refresh
+### Automatic token refresh
 
-When `autoRefresh: true`, the provider calls `POST /api/auth/refresh` periodically (based on `refreshThreshold`, default 60 seconds before expiry). The Route Handler:
+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
 
-### Refresh flow
-
-```
-Client detects expiry → POST /api/auth/refresh → backend refresh endpoint → new encrypted cookie set
-```
-
 If the refresh token is expired, the session is cleared.
 
 ---
 
-## Server-Side Session (`getServerSession`)
+## Backend API Requirements
 
-Use this in App Router server components and API routes to read the session without going through the client:
-
-```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";
+Your backend needs to implement these endpoints:
 
-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>;
-}
-```
-
-`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.
-
----
-
-## Backend Requirements
-
-Your API needs to implement the following contract:
-
-### `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 }`)
 
@@ -580,9 +635,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",
@@ -598,39 +657,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   | 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         |
 
-| Input   | Seconds   |
-|---------|-----------|
-| `900`   | 900       |
-| `"15m"` | 900       |
-| `"2h"`  | 7 200     |
-| `"2d"`  | 172 800   |
-| `"7d"`  | 604 800   |
-| `"1w"`  | 604 800   |
+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) |
 
@@ -638,6 +711,79 @@ 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
@@ -651,7 +797,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> {
@@ -662,34 +808,102 @@ interface LoginResponse<User = unknown> {
   accessTokenExpiresIn?: number | string;
   refreshTokenExpiresIn?: number | string;
 }
+```
 
-// Server-side config (used in createAuthHandlers, middleware, getServerSession)
-interface AuthConfig<User = unknown> {
-  baseUrl: string;
-  secret: string;  // SERVER-SIDE ONLY
-  endpoints: { login: string; refresh: string; logout?: string; me?: string };
-  token: { storage: "cookie" | "memory"; cookieName?: string; secure?: boolean; sameSite?: string };
-  routes?: { public: string[]; protected: string[]; guestOnly?: string[]; loginPath?: string; redirectAuthenticatedTo?: string };
-  expiry?: { accessTokenExpiresIn?: number | string; refreshTokenExpiresIn?: number | string; strategy?: "backend" | "config" | "hybrid" };
-  autoRefresh?: boolean;
-  refreshThreshold?: number;
+All types are exported from `next-token-auth`.
+
+---
+
+## Common Patterns
+
+### Custom user type
+
+```ts
+interface MyUser {
+  id: string;
+  email: string;
+  role: "admin" | "user";
 }
 
-// Client-side config (used in AuthProvider)
-interface ClientAuthConfig {
-  token?: { cookieName?: string };
-  routes?: { loginPath?: string; redirectAuthenticatedTo?: string };
-  autoRefresh?: boolean;
-  refreshThreshold?: number;
-  onLogin?: (session: AuthSession) => void;
-  onLogout?: () => void;
+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>
+);
+```
+
+### 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");
+  }
 
-type ExpiryInput = number | string;
-type ExpiryStrategy = "backend" | "config" | "hybrid";
+  if (session.user.role !== "admin") {
+    redirect("/dashboard");
+  }
+
+  return <h1>Admin Panel</h1>;
+}
 ```
 
-All types are exported from the root `next-token-auth` import.
+---
+
+## 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)`
 
 ---
 
@@ -702,15 +916,14 @@ All types are exported from the root `next-token-auth` import.
 
 ---
 
-## Security Notes
+## Security
 
-- All tokens are stored in HttpOnly cookies — JavaScript in the browser cannot read them
-- Session cookies are AES-GCM encrypted server-side 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`
-- Use a random 32-character string for `secret` in production — never commit it
 - Cookies use `Secure` and `SameSite` flags by default for CSRF protection
-- The `"memory"` storage mode is no longer recommended — HttpOnly cookies are more secure
+- Use a random 32-character string for `secret` in production — never commit it
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-token-auth",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "description": "Production-grade authentication library for Next.js (App Router & Pages Router)",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",