@artatol-acp/auth-nextjs 0.5.18 → 0.5.19

package/README.md

@@ -32,7 +32,7 @@ The SDK uses **httpOnly cookies** for secure token storage:
 
 ### 1. Set Up Proxy/Middleware (REQUIRED)
 
-> **⚠️ CRITICAL:** The proxy is **required** for automatic token refresh. Without it, users will be logged out when their access token expires (every 5 minutes).
+> **CRITICAL:** The proxy is **required** for automatic token refresh. Without it, users will be logged out when their access token expires (every 5 minutes).
 
 **Why is proxy required?**
 
@@ -56,8 +56,9 @@ Server Components **cannot** set cookies. When a user visits a protected page wi
 // src/proxy.ts (Next.js 16+)
 // or src/middleware.ts (Next.js 14-15)
 
-import { createACPAuthMiddleware } from '@artatol-acp/auth-nextjs/proxy';
-// For Next.js 14-15: import { createACPAuthMiddleware } from '@artatol-acp/auth-nextjs/middleware';
+import { NextRequest, NextResponse } from 'next/server'
+import { createACPAuthMiddleware } from '@artatol-acp/auth-nextjs/proxy'
+// For Next.js 14-15: import { createACPAuthMiddleware } from '@artatol-acp/auth-nextjs/middleware'
 
 const acpMiddleware = createACPAuthMiddleware({
   baseUrl: process.env.ACP_AUTH_URL!,
@@ -68,40 +69,37 @@ const acpMiddleware = createACPAuthMiddleware({
   cookies: {
     domain: process.env.NODE_ENV === 'production' ? '.yourdomain.com' : undefined,
   },
-});
+})
 
-export default acpMiddleware;
+export default async function middleware(request: NextRequest) {
+  // Homepage is public - handle with exact match
+  if (request.nextUrl.pathname === '/') {
+    return NextResponse.next()
+  }
+
+  return acpMiddleware(request)
+}
 
 export const config = {
   matcher: ['/((?!api|_next/static|_next/image|favicon.ico|icon).*)'],
-};
+}
 ```
 
-**⚠️ WARNING about `publicPaths`:**
+**WARNING about `publicPaths`:**
 
 The `publicPaths` option uses **prefix matching** (`pathname.startsWith(path)`). This means:
 
 - `/login` matches `/login`, `/login/`, `/login/callback`, etc.
-- `/` would match **ALL paths** - never include just `/` in publicPaths!
+- **NEVER include just `/` in publicPaths** - it would match ALL paths!
 
-If you need the homepage (`/`) to be public, handle it separately:
-
-```typescript
-export default async function middleware(request: NextRequest) {
-  // Homepage is public - skip auth
-  if (request.nextUrl.pathname === '/') {
-    return NextResponse.next();
-  }
-  return acpMiddleware(request);
-}
-```
+Always handle the homepage (`/`) with an exact match check as shown above.
 
 ### 2. Create API Route Handlers
 
 Create `app/api/auth/[action]/route.ts`:
 
 ```typescript
-import { createAuthHandlers } from '@artatol-acp/auth-nextjs/handlers';
+import { createAuthHandlers } from '@artatol-acp/auth-nextjs/handlers'
 
 const { authHandler } = createAuthHandlers({
   baseUrl: process.env.ACP_AUTH_URL!,
@@ -109,15 +107,15 @@ const { authHandler } = createAuthHandlers({
   cookies: {
     domain: process.env.NODE_ENV === 'production' ? '.yourdomain.com' : undefined,
   },
-});
+})
 
-export const POST = authHandler;
+export const POST = authHandler
 ```
 
 This creates these endpoints:
 - `POST /api/auth/login` - Login
 - `POST /api/auth/logout` - Logout
-- `POST /api/auth/session` - Refresh session & get user
+- `POST /api/auth/session` - Refresh session & get user (used by client-side refresh)
 - `POST /api/auth/register` - Register
 - `POST /api/auth/verify-2fa` - Complete 2FA login
 - `POST /api/auth/resend-verification` - Resend verification email
@@ -129,7 +127,7 @@ This creates these endpoints:
 Create `lib/auth.ts`:
 
 ```typescript
-import { initACPAuth } from '@artatol-acp/auth-nextjs/server';
+import { initACPAuth } from '@artatol-acp/auth-nextjs/server'
 
 // Initialize once at module load
 initACPAuth({
@@ -139,7 +137,7 @@ initACPAuth({
   cookies: {
     domain: process.env.NODE_ENV === 'production' ? '.yourdomain.com' : undefined,
   },
-});
+})
 
 // Re-export server functions
 export {
@@ -155,7 +153,7 @@ export {
   resetPassword,
   deleteAccount,
   refreshAccessToken,
-} from '@artatol-acp/auth-nextjs/server';
+} from '@artatol-acp/auth-nextjs/server'
 ```
 
 ### 4. Add Client Provider
@@ -163,11 +161,13 @@ export {
 In your root layout (`app/layout.tsx`):
 
 ```typescript
-import { ACPAuthProvider } from '@artatol-acp/auth-nextjs/client';
-import { getUser } from '@/lib/auth';
+import { ACPAuthProvider } from '@artatol-acp/auth-nextjs/client'
+import { getUser } from '@/lib/auth'
 
 export default async function RootLayout({ children }) {
-  const user = await getUser();
+  // getUser() is fast - just verifies JWT locally, no API call
+  // Returns { id, email } or null
+  const user = await getUser()
 
   return (
     <html>
@@ -177,78 +177,89 @@ export default async function RootLayout({ children }) {
         </ACPAuthProvider>
       </body>
     </html>
-  );
+  )
 }
 ```
 
+**How client-side refresh works:**
+
+When `initialUser` is `null` (no access_token or expired), `ACPAuthProvider` automatically calls `/api/auth/session` to attempt a refresh using the refresh_token. If successful, the user state updates and new cookies are set. This enables seamless client-side navigation even when access_token has expired.
+
 ## Usage
 
 ### Server Components
 
 ```typescript
-import { getUser, me } from '@/lib/auth';
+import { getUser, me } from '@/lib/auth'
 
 export default async function ProfilePage() {
   // Fast local JWT verification (returns { id, email } or null)
-  const user = await getUser();
+  const user = await getUser()
 
   // Or fetch full user from API (returns { id, email, twoFactorEnabled } or null)
-  const fullUser = await me();
+  const fullUser = await me()
 
   if (!user) {
-    return <div>Not logged in</div>;
+    return <div>Not logged in</div>
   }
 
-  return <div>Welcome {user.email}</div>;
+  return <div>Welcome {user.email}</div>
 }
 ```
 
+**When to use `getUser()` vs `me()`:**
+
+| Function | Speed | Returns | Use when |
+|----------|-------|---------|----------|
+| `getUser()` | Fast (local JWT) | `{ id, email }` | You only need basic user info |
+| `me()` | Slower (API call) | `{ id, email, twoFactorEnabled }` | You need `twoFactorEnabled` status |
+
 ### Server Actions
 
 ```typescript
-'use server';
+'use server'
 
-import { login, logout, verify2FALogin } from '@/lib/auth';
-import { redirect } from 'next/navigation';
+import { login, logout, verify2FALogin } from '@/lib/auth'
+import { redirect } from 'next/navigation'
 
 export async function loginAction(formData: FormData) {
-  const email = formData.get('email') as string;
-  const password = formData.get('password') as string;
+  const email = formData.get('email') as string
+  const password = formData.get('password') as string
 
-  const result = await login(email, password);
+  const result = await login(email, password)
 
   if ('requiresTwoFactor' in result) {
-    return { requires2FA: true, tempToken: result.tempToken };
+    return { requires2FA: true, tempToken: result.tempToken }
   }
 
-  redirect('/dashboard');
+  redirect('/dashboard')
 }
 
 export async function logoutAction() {
-  await logout();
-  redirect('/login');
+  await logout()
+  redirect('/login')
 }
 ```
 
 ### Client Components
 
 ```typescript
-'use client';
+'use client'
 
-import { useAuth } from '@artatol-acp/auth-nextjs/client';
+import { useAuth } from '@artatol-acp/auth-nextjs/client'
 
 export function UserMenu() {
-  const { user, logout, isLoading } = useAuth();
+  const { user, logout, isLoading } = useAuth()
 
-  if (isLoading) return <div>Loading...</div>;
-  if (!user) return <a href="/login">Sign In</a>;
+  if (isLoading) return <div>Loading...</div>
+  if (!user) return <a href="/login">Sign In</a>
 
   return (
     <div>
       <span>{user.email}</span>
       <button onClick={logout}>Logout</button>
     </div>
-  );
+  )
 }
 ```
 
@@ -277,7 +288,7 @@ createACPAuthMiddleware({
     secure?: boolean,        // HTTPS only (default: NODE_ENV === 'production')
     sameSite?: 'strict' | 'lax' | 'none', // (default: 'lax')
   },
-});
+})
 ```
 
 ### Server Functions
@@ -285,9 +296,9 @@ createACPAuthMiddleware({
 | Function | Description |
 |----------|-------------|
 | `initACPAuth(options)` | Initialize auth configuration (call once) |
-| `getUser()` | Get user from JWT (local, fast) → `{ id, email }` or `null` |
-| `me()` | Get user from API (full data) → `{ id, email, twoFactorEnabled }` or `null` |
-| `login(email, password)` | Login, sets cookies → `{ accessToken, user }` or `{ requiresTwoFactor, tempToken }` |
+| `getUser()` | Get user from JWT (local, fast) -> `{ id, email }` or `null` |
+| `me()` | Get user from API (full data) -> `{ id, email, twoFactorEnabled }` or `null` |
+| `login(email, password)` | Login, sets cookies -> `{ accessToken, user }` or `{ requiresTwoFactor, tempToken }` |
 | `verify2FALogin(tempToken, code)` | Complete 2FA login |
 | `logout()` | Logout, clears cookies |
 | `register(email, password)` | Register new user |
@@ -303,13 +314,13 @@ createACPAuthMiddleware({
 ```typescript
 const {
   user,           // Current user or null
-  isLoading,      // True during initial load
+  isLoading,      // True during initial load or refresh
   login,          // (email, password) => Promise<{ requiresTwoFactor?, tempToken? }>
   verify2FA,      // (tempToken, code) => Promise<void>
   logout,         // () => Promise<void>
-  refresh,        // () => Promise<boolean>
+  refresh,        // () => Promise<boolean> - manually trigger session refresh
   resendVerification, // (email) => Promise<void>
-} = useAuth();
+} = useAuth()
 ```
 
 ### ACPAuthProvider Props
@@ -317,7 +328,7 @@ const {
 ```typescript
 <ACPAuthProvider
   apiBasePath="/api/auth"  // Optional, default: "/api/auth"
-  initialUser={user}       // Optional, SSR user data
+  initialUser={user}       // Optional, from getUser() - { id, email } or null
 >
   {children}
 </ACPAuthProvider>
@@ -325,27 +336,39 @@ const {
 
 ## Token Refresh Flow
 
-1. **User visits protected page** with expired `access_token`
+### Server-side (hard refresh, direct URL access)
+
+1. User visits protected page with expired `access_token`
 2. **Proxy intercepts** the request before page renders
-3. **Proxy calls** auth server `/refresh` endpoint with `refresh_token`
-4. **Auth server** validates refresh token, rotates it, returns new tokens
-5. **Proxy sets** new `access_token` and `refresh_token` cookies
-6. **Page renders** with valid tokens
+3. Proxy calls auth server `/refresh` with `refresh_token`
+4. Auth server validates, **rotates** refresh token, returns new tokens
+5. Proxy sets new `access_token` and `refresh_token` cookies
+6. Page renders with valid tokens
+
+### Client-side (navigation within app)
+
+1. User clicks link to protected page (client-side navigation)
+2. Proxy does NOT run (client navigation doesn't hit server)
+3. `ACPAuthProvider` detects `initialUser` is `null`
+4. Calls `/api/auth/session` which refreshes tokens and sets cookies
+5. User state updates, navigation proceeds
+
+**If API handlers are missing:** Client-side refresh won't work, user gets logged out on navigation when access_token expires.
 
-**If proxy is missing:** Step 2-5 would happen during page render, but cookies can't be set from Server Components, so the new tokens are lost and the old refresh token is now invalid → user gets logged out.
+**If proxy is missing:** Server-side refresh won't work, user gets logged out on hard refresh when access_token expires.
 
 ## Error Handling
 
 ```typescript
-import { ACPAuthError } from '@artatol-acp/auth-nextjs/server';
+import { ACPAuthError } from '@artatol-acp/auth-nextjs/server'
 
 try {
-  await login(email, password);
+  await login(email, password)
 } catch (error) {
   if (error instanceof ACPAuthError) {
-    console.error('Status:', error.statusCode);
-    console.error('Message:', error.message);
-    console.error('Code:', error.code);
+    console.error('Status:', error.statusCode)
+    console.error('Message:', error.message)
+    console.error('Code:', error.code)
   }
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@artatol-acp/auth-nextjs",
-  "version": "0.5.18",
+  "version": "0.5.19",
   "description": "Next.js SDK for Artatol Cloud Platform Authentication with support for App Router, Server Actions, and Middleware",
   "type": "module",
   "main": "./dist/index.js",