npm - @insforge/nextjs - Versions diffs - 0.4.0 → 0.6.5 - Mend

@insforge/nextjs 0.4.0 → 0.6.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (23) hide show

package/README.md CHANGED Viewed

@@ -4,115 +4,249 @@ Pre-built authentication UI components for Next.js applications using Insforge b
 ## Features
+- **Built-in Authentication (v0.6.0+)**: Zero-config authentication using backend-hosted pages
 - **Drop-in UI Components**: Pre-styled SignIn, SignUp, and UserButton components
+- **Auth Primitives (v0.5.0+)**: 10 low-level components for building custom auth UIs
 - **React Hooks**: Easy access to auth state with `useAuth()`, `useUser()`, `useSession()`
 - **Control Components**: `<SignedIn>`, `<SignedOut>`, `<Protect>` for conditional rendering
 - **Next.js Middleware**: Server-side route protection
-- **OAuth Support**: Built-in Google and GitHub authentication
+- **OAuth Support**: 11 providers (Google, GitHub, Discord, Facebook, LinkedIn, Microsoft, Apple, X, Instagram, TikTok, Spotify)
+- **Smart OAuth Layout**: Adaptive grid (1/2/3 columns) based on provider count
 - **TypeScript**: Full type safety out of the box
-- **Customizable**: Override styles with the `appearance` prop
+- **Customizable**: Override styles with the `appearance` prop or build from primitives
 ## Installation
 ```bash
-npm install @insforge/nextjs lucide-react
+npm install @insforge/nextjs
 # or
-yarn add @insforge/nextjs lucide-react
+yarn add @insforge/nextjs
 ```
-**Required peer dependencies:**
-- `lucide-react` - Icon library (used for icons in components)
 ## Quick Start
-### 1. Check Your Backend OAuth Configuration
+### 1. Wrap your app with InsforgeProvider
-First, query your Insforge backend to see what OAuth providers are configured:
+```tsx
+// app/layout.tsx
+import { InsforgeProvider } from '@insforge/nextjs';
+import '@insforge/nextjs/styles.css';
-```bash
-# Using curl (requires admin authentication)
-curl -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
-  https://your-backend.insforge.app/api/metadata/auth
-```
-**Response example:**
-```json
-{
-  "oauths": [
-    { "provider": "github", "clientId": "...", ... },
-    { "provider": "google", "clientId": "...", ... }
-  ]
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  const baseUrl = process.env.NEXT_PUBLIC_INSFORGE_BASE_URL!;
+  return (
+    <html lang="en">
+      <body>
+        <InsforgeProvider baseUrl={baseUrl}>
+          {children}
+        </InsforgeProvider>
+      </body>
+    </html>
+  );
 }
 ```
-**For AI Agents:** Use the Insforge MCP tool `get-backend-metadata` to automatically retrieve this configuration.
+**That's it!** By default, the package uses **built-in authentication** - users will be automatically redirected to your backend's authentication pages when not signed in. No additional setup required!
+## Built-in Authentication (Default)
+The package now includes **built-in authentication** by default, which means:
+- ✅ **Zero UI Code**: No need to create SignIn/SignUp pages
+- ✅ **Automatic Redirects**: Users are redirected to backend auth pages when not signed in
+- ✅ **Same-Domain Performance**: Faster API calls without CORS overhead
+- ✅ **Unified Experience**: Consistent auth UI across all Insforge apps
+### How it works
+1. User visits a protected page (e.g., `/dashboard`)
+2. Provider detects user is not signed in
+3. Automatically redirects to: `https://your-backend.insforge.app/auth/signin?redirect=https://yourapp.com/auth/callback`
+4. User signs in on the backend's authentication page
+5. Backend redirects back to: `https://yourapp.com/auth/callback?access_token=xxx`
+6. Your callback page stores the token and redirects to the original destination
+### Local Development Setup
-### 2. Wrap your app with AuthProvider
+For local development, your backend API and frontend typically run on different ports. You can configure this in two ways:
+**Option 1: Using environment variables (recommended)**
+```bash
+# .env.local
+NEXT_PUBLIC_INSFORGE_BASE_URL=http://localhost:7130          # Backend API
+NEXT_PUBLIC_INSFORGE_FRONTEND_URL=http://localhost:7131      # Backend Frontend
+```
 ```tsx
 // app/layout.tsx
-import { AuthProvider } from '@insforge/nextjs';
+import { InsforgeProvider } from '@insforge/nextjs';
 export default function RootLayout({ children }: { children: React.ReactNode }) {
-  const baseUrl = process.env.NEXT_PUBLIC_INSFORGE_BASE_URL!;
+  return (
+    <html lang="en">
+      <body>
+        <InsforgeProvider baseUrl={process.env.NEXT_PUBLIC_INSFORGE_BASE_URL!}>
+          {children}
+        </InsforgeProvider>
+      </body>
+    </html>
+  );
+}
+```
+**Option 2: Using the `frontendUrl` prop**
+```tsx
+// app/layout.tsx
+import { InsforgeProvider } from '@insforge/nextjs';
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <InsforgeProvider
+          baseUrl={process.env.NEXT_PUBLIC_INSFORGE_BASE_URL!}
+          frontendUrl={process.env.NEXT_PUBLIC_INSFORGE_FRONTEND_URL}
+        >
+          {children}
+        </InsforgeProvider>
+      </body>
+    </html>
+  );
+}
+```
+**Priority:** `frontendUrl` prop > `NEXT_PUBLIC_INSFORGE_FRONTEND_URL` env var > `baseUrl` (fallback)
+**Production:** If your API and frontend share the same URL, you only need `NEXT_PUBLIC_INSFORGE_BASE_URL`.
+### Using Custom SignIn/SignUp Components
+If you prefer to use your own authentication UI, set `useBuiltInAuth={false}`:
+```tsx
+// app/layout.tsx
+import { InsforgeProvider } from '@insforge/nextjs';
+export default function RootLayout({ children }: { children: React.ReactNode }) {
   return (
     <html lang="en">
       <body>
-        <AuthProvider baseUrl={baseUrl}>
+        <InsforgeProvider
+          baseUrl={process.env.NEXT_PUBLIC_INSFORGE_BASE_URL!}
+          useBuiltInAuth={false} // Use custom components instead
+        >
           {children}
-        </AuthProvider>
+        </InsforgeProvider>
       </body>
     </html>
   );
 }
 ```
-**Note:** Import the component styles:
+### 2. Set up API route for authentication (Required for SSR)
+Create an API route to handle authentication cookies. This is **essential** for Next.js server-side rendering and middleware to work properly.
 ```tsx
-// In your layout.tsx or _app.tsx
-import '@insforge/nextjs/styles.css';
+// app/api/auth/route.ts
+import { createAuthRouteHandlers } from '@insforge/nextjs/api';
+const handlers = createAuthRouteHandlers({
+  baseUrl: process.env.INSFORGE_BASE_URL || process.env.NEXT_PUBLIC_INSFORGE_BASE_URL!,
+  cookieName: 'insforge_token',
+});
+export const POST = handlers.POST;
+export const GET = handlers.GET;
+export const DELETE = handlers.DELETE;
 ```
-**That's it!** No Tailwind configuration needed. The package now uses standalone CSS.
+**Why is this needed?**
+Next.js middleware runs on the server and cannot access `localStorage` (which is browser-only). This API route:
+- Syncs tokens from `localStorage` to HTTP-only cookies
+- Enables server-side authentication in middleware
+- Provides server-side sign-in/sign-up endpoints
-### 3. Add OAuth callback page (Required for OAuth)
+### 3. Add authentication callback page (Required for Next.js SSR)
-If you're using OAuth providers, you **must** create a callback page:
+Create a callback page to handle post-authentication token synchronization. This is **required for all authentication methods** (email/password and OAuth) when using Next.js middleware:
 ```tsx
 // app/auth/callback/page.tsx
 'use client';
-import { useEffect, Suspense } from 'react';
+import { useEffect, useRef, Suspense } from 'react';
 import { useRouter, useSearchParams } from 'next/navigation';
 function CallbackContent() {
   const router = useRouter();
   const searchParams = useSearchParams();
+  const isProcessingRef = useRef(false);
   useEffect(() => {
-    const processOAuthCallback = () => {
+    const processOAuthCallback = async () => {
+      // Prevent double-processing in React Strict Mode
+      if (isProcessingRef.current) return;
+      isProcessingRef.current = true;
       const accessToken = searchParams.get('access_token');
       const error = searchParams.get('error');
       if (error) {
+        console.error('OAuth error:', error);
         router.push('/sign-in?error=' + encodeURIComponent(error));
         return;
       }
       if (accessToken) {
-        // Store token in localStorage (where SDK expects it)
+        // 1. Store token in localStorage (for SDK client-side operations)
         localStorage.setItem('insforge-auth-token', accessToken);
-        // Get final destination
+        console.log('✅ OAuth token stored in localStorage');
+        // 2. Sync token to HTTP-only cookie (for server-side middleware)
+        try {
+          const syncResponse = await fetch('/api/auth', {
+            method: 'POST',
+            headers: {
+              'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+              action: 'sync-token',
+              token: accessToken,
+            }),
+          });
+          if (syncResponse.ok) {
+            console.log('✅ OAuth token synced to cookie');
+          } else {
+            console.warn('⚠️ Failed to sync token to cookie, but localStorage has it');
+          }
+        } catch (syncError) {
+          console.warn('⚠️ Cookie sync failed:', syncError);
+        }
+        // 3. Get the final destination from sessionStorage
         const finalDestination = sessionStorage.getItem('oauth_final_destination') || '/dashboard';
         sessionStorage.removeItem('oauth_final_destination');
-        router.push(finalDestination);
+        // 4. Clean up URL to remove OAuth params before redirect
+        window.history.replaceState({}, '', '/auth/callback');
+        // 5. Small delay to ensure cookie is set before redirect
+        setTimeout(() => {
+          router.push(finalDestination);
+        }, 100);
       } else {
-        router.push('/sign-in?error=no_token');
+        if (searchParams.toString()) {
+          console.error('No token received from OAuth');
+          router.push('/sign-in?error=no_token');
+        }
       }
     };
@@ -131,14 +265,28 @@ function CallbackContent() {
 export default function OAuthCallbackPage() {
   return (
-    <Suspense fallback={<div>Loading...</div>}>
+    <Suspense fallback={
+      <div className="flex items-center justify-center min-h-screen">
+        <div>Loading...</div>
+      </div>
+    }>
       <CallbackContent />
     </Suspense>
   );
 }
 ```
-### 4. Add sign-in page with OAuth providers
+**What this does:**
+1. Receives authentication callback with `access_token` from backend (works for both OAuth and email/password)
+2. Stores token in `localStorage` for SDK client-side operations
+3. Syncs token to HTTP-only cookie via `/api/auth` for server-side middleware
+4. Redirects user to their intended destination
+**Note:** This callback page handles returns from:
+- OAuth providers (Google, GitHub, etc.)
+- Email/password sign-in/sign-up when using the pre-built components
+### 4. Add sign-in page
 ```tsx
 // app/sign-in/page.tsx
@@ -147,8 +295,6 @@ import { SignIn } from '@insforge/nextjs';
 export default function SignInPage() {
   return (
     <SignIn
-      baseUrl={process.env.NEXT_PUBLIC_INSFORGE_BASE_URL!}
-      providers={['github', 'google']}  // Based on your backend config
       afterSignInUrl="/dashboard"
       title="Welcome to MyApp"
       subtitle="Sign in to continue"
@@ -157,7 +303,7 @@ export default function SignInPage() {
 }
 ```
-**Note:** The `providers` prop should match what you've configured in your Insforge backend. OAuth buttons will only render for providers specified in this array.
+**OAuth Providers:** The package automatically detects which OAuth providers are configured on your backend. You don't need to specify them manually!
 ### 5. Add sign-up page
@@ -168,8 +314,6 @@ import { SignUp } from '@insforge/nextjs';
 export default function SignUpPage() {
   return (
     <SignUp
-      baseUrl={process.env.NEXT_PUBLIC_INSFORGE_BASE_URL!}
-      providers={['github', 'google']}  // Based on your backend config
       afterSignUpUrl="/dashboard"
     />
   );
@@ -210,41 +354,127 @@ export default function Home() {
 ### 7. Protect routes with middleware
 ```ts
-// middleware.ts
-import { withAuth } from '@insforge/nextjs/middleware';
+// middleware.ts - Built-in authentication (default)
+import { InsforgeMiddleware } from '@insforge/nextjs/middleware';
+export default InsforgeMiddleware({
+  baseUrl: process.env.INSFORGE_BASE_URL!,
+  publicRoutes: ['/auth/callback', '/'],  // Include callback!
+  cookieName: 'insforge_token',  // Must match API route cookie name
+});
+export const config = {
+  matcher: ['/((?!api|_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)'],
+};
+```
+```ts
+// middleware.ts - Custom SignIn/SignUp components
+import { InsforgeMiddleware } from '@insforge/nextjs/middleware';
-export default withAuth({
+export default InsforgeMiddleware({
   baseUrl: process.env.INSFORGE_BASE_URL!,
-  publicRoutes: ['/sign-in', '/sign-up', '/'],
+  publicRoutes: ['/sign-in', '/sign-up', '/', '/auth/callback'],
   signInUrl: '/sign-in',
+  cookieName: 'insforge_token',
+  useBuiltInAuth: false,  // Use custom components
 });
 export const config = {
-  matcher: ['/((?!_next|api|.*\\..*).*)'],
+  matcher: ['/((?!api|_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)'],
 };
 ```
+**Important:**
+- **Must include** `/auth/callback` in `publicRoutes` to allow authentication returns
+- Use the same `cookieName` in both middleware and API route
+- With built-in auth, middleware won't redirect to local sign-in pages
+**Alternative imports:**
+- `InsforgeMiddleware` - Recommended, most descriptive
+- `withInsforgeAuth` - Alternative with Insforge branding
+- `withAuth` - Deprecated but still supported for backward compatibility
+---
+## Architecture: Why Callback + API Route?
+This package is specifically designed for **Next.js App Router with Server-Side Rendering (SSR)**. Here's why both the callback page and API route are essential:
+### The Challenge
+Next.js has two execution environments:
+- **Client-side**: Browser, can access `localStorage`
+- **Server-side**: Middleware, Server Components, cannot access `localStorage`
+The Insforge SDK stores authentication tokens in `localStorage` (client-side only), but Next.js middleware needs to verify authentication on the server.
+### The Solution
+**Two-Storage Architecture:**
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Authentication Flow (Email/Password & OAuth)                 │
+└─────────────────────────────────────────────────────────────┘
+1. User signs in (email/password OR OAuth)
+   ↓
+2. Backend redirects to: /auth/callback?access_token=xxx
+   ↓
+3. Callback Page (Client-side)
+   ├─ Stores token in localStorage (for SDK)
+   └─ Calls /api/auth with "sync-token" action
+   ↓
+4. API Route (Server-side)
+   ├─ Validates token with backend
+   └─ Sets HTTP-only cookie
+   ↓
+5. Middleware (Server-side)
+   └─ Reads cookie to protect routes
+```
+**Why this matters:**
+- **Client-side operations** (SDK calls) use `localStorage`
+- **Server-side operations** (middleware, SSR) use HTTP-only cookies
+- Both storages stay synchronized through the `/api/auth` endpoint
+### What Each Component Does
+| Component | Purpose | Runs On |
+|-----------|---------|---------|
+| **Callback Page** | Receives auth token (any method), stores in localStorage, syncs to cookie | Client |
+| **API Route** | Validates tokens, manages cookies, provides server-side auth | Server |
+| **Middleware** | Protects routes, reads cookies, validates sessions | Server |
+| **SDK** | Makes API calls, reads from localStorage | Client |
+This architecture enables full-stack authentication in Next.js while maintaining security with HTTP-only cookies.
+**Note:** All authentication methods (email/password, OAuth) use this same flow for consistency and SSR support.
 ## API Reference
 ### Components
-#### `<AuthProvider>`
+#### `<InsforgeProvider>`
-Wraps your application and provides auth context.
+Wraps your application and provides auth context. Automatically fetches OAuth provider configuration from your backend.
 ```tsx
-<AuthProvider
+<InsforgeProvider
   baseUrl="https://your-backend.insforge.app"
   onAuthChange={(user) => console.log('Auth changed:', user)}
 >
   {children}
-</AuthProvider>
+</InsforgeProvider>
 ```
 **Props:**
 - `baseUrl` (required): Your Insforge backend URL
 - `onAuthChange`: Optional callback when auth state changes
+**Note:** The provider automatically queries your backend's OAuth configuration, so components like `<SignIn>` and `<SignUp>` will display the correct OAuth buttons without manual configuration.
 ---
 #### `<SignIn>`
@@ -253,8 +483,6 @@ Pre-built sign-in form with email/password and OAuth.
 ```tsx
 <SignIn
-  baseUrl="https://your-backend.insforge.app"
-  providers={['github', 'google']}
   afterSignInUrl="/dashboard"
   appearance={{
     container: { background: '#f5f5f5' },
@@ -266,13 +494,13 @@ Pre-built sign-in form with email/password and OAuth.
 ```
 **Props:**
-- `baseUrl` (required): Your Insforge backend URL
-- `providers`: Array of OAuth providers to display (e.g., `['github', 'google']`). Omit or pass empty array for email/password only
 - `afterSignInUrl`: Redirect URL after successful sign-in (default: `/`)
 - `appearance`: Custom styles for container, form, and button
 - `onSuccess`: Callback on successful sign-in
 - `onError`: Callback on error
+**Note:** OAuth providers are automatically detected from your backend configuration via `InsforgeProvider`. No need to manually specify them!
 ---
 #### `<SignUp>`
@@ -281,8 +509,6 @@ Pre-built sign-up form with email/password and OAuth.
 ```tsx
 <SignUp
-  baseUrl="https://your-backend.insforge.app"
-  providers={['github', 'google']}
   afterSignUpUrl="/onboarding"
   appearance={{
     container: { background: '#f5f5f5' }
@@ -291,13 +517,135 @@ Pre-built sign-up form with email/password and OAuth.
 ```
 **Props:**
-- `baseUrl` (required): Your Insforge backend URL
-- `providers`: Array of OAuth providers to display (e.g., `['github', 'google']`). Omit or pass empty array for email/password only
 - `afterSignUpUrl`: Redirect URL after successful sign-up (default: `/`)
 - `appearance`: Custom styles for container, form, and button
 - `onSuccess`: Callback on successful sign-up
 - `onError`: Callback on error
+**Note:** OAuth providers are automatically detected from your backend configuration via `InsforgeProvider`. No need to manually specify them!
+---
+### Auth Component Primitives (v0.5.0+)
+For advanced customization, use the low-level Auth primitives to build your own authentication UI:
+```tsx
+import {
+  AuthContainer,
+  AuthHeader,
+  AuthErrorBanner,
+  AuthFormField,
+  AuthPasswordField,
+  AuthSubmitButton,
+  AuthDivider,
+  AuthLink,
+  AuthOAuthProviders,
+  AuthBranding,
+} from '@insforge/nextjs';
+import '@insforge/nextjs/styles.css';
+function CustomSignIn() {
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [error, setError] = useState('');
+  const [loading, setLoading] = useState(false);
+  async function handleSubmit(e) {
+    e.preventDefault();
+    // Your custom auth logic
+  }
+  return (
+    <AuthContainer>
+      <AuthHeader title="Welcome Back" subtitle="Sign in to continue" />
+      <AuthErrorBanner error={error} />
+      <form onSubmit={handleSubmit} className="insforge-form">
+        <AuthFormField
+          id="email"
+          type="email"
+          label="Email"
+          placeholder="you@example.com"
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+          required
+        />
+        <AuthPasswordField
+          id="password"
+          label="Password"
+          value={password}
+          onChange={(e) => setPassword(e.target.value)}
+          required
+          forgotPasswordLink={{
+            href: '/forgot-password',
+            text: 'Forgot Password?'
+          }}
+        />
+        <AuthSubmitButton isLoading={loading}>
+          Sign In
+        </AuthSubmitButton>
+      </form>
+      <AuthLink
+        text="Don't have an account?"
+        linkText="Sign up"
+        href="/sign-up"
+      />
+      <AuthDivider text="or" />
+      <AuthOAuthProviders
+        providers={['google', 'github', 'discord']}
+        onClick={(provider) => handleOAuth(provider)}
+        loading={null}
+      />
+      <AuthBranding />
+    </AuthContainer>
+  );
+}
+```
+#### Available Primitives
+| Component | Description |
+|-----------|-------------|
+| `<AuthContainer>` | Main wrapper with card styling. Accepts `style` prop for customization |
+| `<AuthHeader>` | Displays `title` and optional `subtitle` |
+| `<AuthErrorBanner>` | Shows error messages. Pass `error` string prop |
+| `<AuthFormField>` | Standard input field. Supports all HTML input props + `label` |
+| `<AuthPasswordField>` | Password input with visibility toggle, optional strength indicator, and forgot password link |
+| `<AuthSubmitButton>` | Submit button with loading state. Pass `isLoading` and optional `loadingText` |
+| `<AuthDivider>` | Visual separator with customizable `text` (default: "or") |
+| `<AuthLink>` | Call-to-action link. Props: `text`, `linkText`, `href` |
+| `<AuthOAuthProviders>` | Smart grid of OAuth buttons. Props: `providers`, `onClick`, `loading` |
+| `<AuthBranding>` | "Powered by InsForge" branding. Optional `text` and `href` props |
+**`AuthPasswordField` Props:**
+- All standard input props (`value`, `onChange`, `required`, etc.)
+- `label`: Field label text
+- `id`: Input element ID
+- `showStrengthIndicator`: Show password strength indicator (default: `false`)
+- `forgotPasswordLink`: Object with `{ href: string, text?: string }`
+**`AuthOAuthProviders` Smart Layout:**
+- 1 provider: Full-width button with "Continue with Google"
+- 2 providers: Two columns with short text "Google", "GitHub"
+- 3+ providers: Three columns with icons only
+- Auto-centers incomplete last rows (e.g., 5, 8, 11 providers)
+**When to use primitives vs pre-built components:**
+- Use `<SignIn>` / `<SignUp>` for quick setup with minimal customization
+- Use Auth primitives when you need:
+  - Custom form layouts
+  - Additional fields (username, terms checkbox, etc.)
+  - Integration with your own state management
+  - Unique branding and styling
 ---
 #### `<UserButton>`
@@ -442,16 +790,68 @@ function Component() {
 ---
+### API Route Handlers
+#### `createAuthRouteHandlers(config)`
+Creates Next.js App Router API handlers for authentication with HTTP-only cookie management.
+```tsx
+// app/api/auth/route.ts
+import { createAuthRouteHandlers } from '@insforge/nextjs/api';
+const handlers = createAuthRouteHandlers({
+  baseUrl: process.env.INSFORGE_BASE_URL!,
+  cookieName: 'insforge_token',
+  cookieMaxAge: 7 * 24 * 60 * 60, // 7 days
+});
+export const POST = handlers.POST;
+export const GET = handlers.GET;
+export const DELETE = handlers.DELETE;
+```
+**Config:**
+- `baseUrl` (required): Your Insforge backend URL
+- `cookieName`: Cookie name for auth token (default: `insforge_token`)
+- `cookieMaxAge`: Cookie expiration in seconds (default: 7 days)
+- `secure`: Use secure cookies (auto-detected, `true` in production)
+**Supported Actions (POST):**
+- `sign-in`: Email/password sign-in with cookie creation
+- `sign-up`: Email/password sign-up with cookie creation
+- `sync-token`: Sync token from localStorage to cookie (for OAuth)
+**Example: Sync token after OAuth**
+```typescript
+// In your OAuth callback page
+const response = await fetch('/api/auth', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    action: 'sync-token',
+    token: accessToken,
+  }),
+});
+```
+**Endpoints:**
+- `POST /api/auth` - Sign in, sign up, or sync token
+- `GET /api/auth` - Check current session
+- `DELETE /api/auth` - Sign out and clear cookies
+---
 ### Middleware
-#### `withAuth(config)`
+#### `InsforgeMiddleware(config)`
 Create Next.js middleware for route protection.
 ```ts
-import { withAuth } from '@insforge/nextjs/middleware';
+import { InsforgeMiddleware } from '@insforge/nextjs/middleware';
-export default withAuth({
+export default InsforgeMiddleware({
   baseUrl: process.env.INSFORGE_BASE_URL!,
   publicRoutes: ['/sign-in', '/sign-up', '/', '/about'],
   signInUrl: '/sign-in',
@@ -465,18 +865,22 @@ export default withAuth({
 - `signInUrl`: URL to redirect to when not authenticated (default: `/sign-in`)
 - `cookieName`: Cookie name for auth token (default: `insforge_token`)
+**Alternative exports:**
+- `withInsforgeAuth` - Same as `InsforgeMiddleware` with Insforge branding
+- `withAuth` - Deprecated alias for backward compatibility
 ---
-#### `getAuthUser(headers)` and `getAuthToken(headers)`
+#### `getAuthUserId(headers)` and `getAuthToken(headers)`
 Get authenticated user ID or token in server components.
 ```tsx
 import { headers } from 'next/headers';
-import { getAuthUser, getAuthToken } from '@insforge/nextjs/middleware';
+import { getAuthUserId, getAuthToken } from '@insforge/nextjs/middleware';
 export default async function ServerComponent() {
-  const userId = getAuthUser(headers());
+  const userId = getAuthUserId(headers());
   const token = getAuthToken(headers());
   // Fetch user-specific data
@@ -486,6 +890,9 @@ export default async function ServerComponent() {
 }
 ```
+**Alternative exports:**
+- `getAuthUser` - Deprecated alias for `getAuthUserId` (backward compatibility)
 ---
 ## Styling
@@ -623,7 +1030,7 @@ All components use semantic CSS class names prefixed with `insforge-`:
 ### Custom Auth Callbacks
 ```tsx
-<AuthProvider
+<InsforgeProvider
   baseUrl={baseUrl}
   onAuthChange={(user) => {
     if (user) {
@@ -634,7 +1041,7 @@ All components use semantic CSS class names prefixed with `insforge-`:
   }}
 >
   {children}
-</AuthProvider>
+</InsforgeProvider>
 ```
 ### Server-Side User Data
@@ -642,11 +1049,11 @@ All components use semantic CSS class names prefixed with `insforge-`:
 ```tsx
 // app/dashboard/page.tsx
 import { headers } from 'next/headers';
-import { getAuthUser } from '@insforge/nextjs/middleware';
+import { getAuthUserId } from '@insforge/nextjs/middleware';
 import { createClient } from '@insforge/sdk';
 export default async function Dashboard() {
-  const userId = getAuthUser(headers());
+  const userId = getAuthUserId(headers());
   const insforge = createClient({
     baseUrl: process.env.INSFORGE_BASE_URL!
@@ -693,31 +1100,25 @@ INSFORGE_BASE_URL=https://your-backend.insforge.app
 When building Next.js apps with authentication:
 1. **Connect to Insforge MCP** - Access the user's Insforge backend
-2. **Query metadata** - Call `get-backend-metadata` to get OAuth configuration
-3. **Generate code** - Write auth pages with explicit `providers={['github', 'google']}` based on backend config
-4. **User sees OAuth buttons** - Components render buttons for configured providers
-**Example MCP Response:**
-```json
-{
-  "auth": {
-    "oauths": [
-      { "provider": "github", "clientId": "..." },
-      { "provider": "google", "clientId": "..." }
-    ]
-  }
-}
-```
+2. **Generate code** - Use `<SignIn>` and `<SignUp>` components
+3. **Automatic configuration** - OAuth providers are detected automatically from backend
 **Agent generates:**
 ```tsx
-<SignIn
-  baseUrl={process.env.NEXT_PUBLIC_INSFORGE_BASE_URL!}
-  providers={['github', 'google']}  // From metadata
-  afterSignInUrl="/dashboard"
-/>
+// Step 1: Wrap app with InsforgeProvider
+<InsforgeProvider baseUrl={process.env.NEXT_PUBLIC_INSFORGE_BASE_URL!}>
+  {children}
+</InsforgeProvider>
+// Step 2: Add sign-in page (OAuth auto-detected)
+<SignIn afterSignInUrl="/dashboard" />
 ```
+**Benefits:**
+- No need to query OAuth configuration manually
+- Components automatically render correct OAuth buttons
+- Backend configuration is the single source of truth
 ---
 ## TypeScript
@@ -754,6 +1155,6 @@ MIT
 ## Support
-- Documentation: https://docs.insforge.app
-- Issues: https://github.com/insforge/nextjs/issues
-- Discord: https://discord.gg/insforge
+- Documentation: https://docs.insforge.dev/introduction
+- Issues: https://github.com/InsForge/InsForge/issues
+- Discord: https://discord.com/invite/DvBtaEc9Jz