@auth-gate/nextjs 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,221 @@
+# @auth-gate/nextjs
+
+Next.js SDK for [AuthGate](https://authgate.dev) — drop-in authentication with OAuth, email, SMS, and MFA for Next.js App Router.
+
+## Installation
+
+```bash
+npm install @auth-gate/nextjs
+```
+
+## Quick Start
+
+### 1. Environment Variables
+
+```env
+AUTHGATE_API_KEY=your_api_key
+AUTHGATE_PROJECT_ID=your_project_id
+SESSION_SECRET=your-secret-at-least-32-characters-long
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+```
+
+### 2. Initialize the SDK
+
+```ts
+// lib/auth.ts
+import { createAuthGate } from "@auth-gate/nextjs";
+
+export const { client, handlers, session } = createAuthGate({
+  apiKey: process.env.AUTHGATE_API_KEY!,
+  projectId: process.env.AUTHGATE_PROJECT_ID!,
+  baseUrl: "https://authgate.dev",
+  sessionSecret: process.env.SESSION_SECRET!,
+  appUrl: process.env.NEXT_PUBLIC_APP_URL!,
+});
+```
+
+### 3. Create the Catch-All Route
+
+```ts
+// app/api/auth/[...authgate]/route.ts
+import { handlers } from "@/lib/auth";
+
+export const { GET, POST } = handlers;
+```
+
+That's it — all auth routes are now available.
+
+### 4. Read the Session
+
+```tsx
+// app/dashboard/page.tsx
+import { session } from "@/lib/auth";
+import { redirect } from "next/navigation";
+
+export default async function DashboardPage() {
+  const user = await session.getSession();
+  if (!user) redirect("/login");
+
+  return <p>Hello, {user.name}</p>;
+}
+```
+
+## Route Map
+
+The catch-all handler registers these routes under `/api/auth/`:
+
+| Method | Route | Description |
+|--------|-------|-------------|
+| GET | `/api/auth/[provider]/login` | Start OAuth flow (google, github, discord, azure, apple) |
+| GET | `/api/auth/callback` | OAuth / magic link callback |
+| POST | `/api/auth/email/signup` | Email registration |
+| POST | `/api/auth/email/signin` | Email sign-in |
+| POST | `/api/auth/email/forgot-password` | Request password reset |
+| POST | `/api/auth/email/reset-password` | Confirm password reset |
+| POST | `/api/auth/email/verify-code` | Verify email with OTP |
+| POST | `/api/auth/magic-link/send` | Send magic link |
+| POST | `/api/auth/sms/send-code` | Send SMS code |
+| POST | `/api/auth/sms/verify-code` | Verify SMS code |
+| POST | `/api/auth/mfa/verify` | Complete MFA challenge |
+| POST | `/api/auth/refresh` | Refresh session token |
+| POST | `/api/auth/logout` | Sign out and revoke session |
+| GET | `/api/auth/me` | Get current user |
+
+## Route Protection
+
+### Layout-Level (Recommended)
+
+```tsx
+// app/dashboard/layout.tsx
+import { session } from "@/lib/auth";
+import { redirect } from "next/navigation";
+
+export default async function DashboardLayout({ children }) {
+  const user = await session.getSession();
+  if (!user) redirect("/login");
+
+  return <>{children}</>;
+}
+```
+
+### Middleware (Optional)
+
+For protecting multiple route groups at the edge:
+
+```ts
+// middleware.ts
+import { createAuthGateMiddleware } from "@auth-gate/nextjs";
+import { client } from "@/lib/auth";
+
+const authMiddleware = createAuthGateMiddleware(client, {
+  loginPath: "/login",
+  matcher: ["/dashboard/:path*", "/settings/:path*"],
+});
+
+export async function middleware(request) {
+  const response = await authMiddleware(request);
+  if (response) return response;
+  // ...other middleware
+}
+
+export const config = {
+  matcher: ["/dashboard/:path*", "/settings/:path*"],
+};
+```
+
+The middleware decrypts the session cookie at the edge and redirects unauthenticated users. It also periodically revalidates sessions (every 5 minutes) using the refresh token.
+
+## Session Helpers
+
+```ts
+import { session } from "@/lib/auth";
+
+// Read the current user (server components, actions, route handlers)
+const user = await session.getSession();
+
+// Set a session (used internally by handlers)
+await session.setSession(user);
+
+// Clear the session
+await session.clearSession();
+```
+
+Sessions are AES-256-GCM encrypted cookies with a 7-day default TTL.
+
+## Authentication Examples
+
+### OAuth Sign-In
+
+```html
+<a href="/api/auth/google/login">Sign in with Google</a>
+<a href="/api/auth/github/login">Sign in with GitHub</a>
+```
+
+### Email Sign-In
+
+```ts
+const res = await fetch("/api/auth/email/signin", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ email, password }),
+});
+
+const data = await res.json();
+
+if (data.mfa_required) {
+  // Handle MFA challenge
+  const mfaRes = await fetch("/api/auth/mfa/verify", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      mfa_challenge: data.mfa_challenge,
+      code: totpCode,
+      method: "totp",
+    }),
+  });
+}
+```
+
+### SMS Sign-In
+
+```ts
+await fetch("/api/auth/sms/send-code", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ phone: "+15551234567" }),
+});
+
+await fetch("/api/auth/sms/verify-code", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ phone: "+15551234567", code: "123456" }),
+});
+```
+
+## API Reference
+
+### `createAuthGate(config)`
+
+Creates the SDK instance. Returns `{ client, handlers, session }`.
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `apiKey` | `string` | Yes | AuthGate API key |
+| `projectId` | `string` | Yes | AuthGate project ID |
+| `baseUrl` | `string` | Yes | AuthGate instance URL |
+| `sessionSecret` | `string` | Yes | Encryption secret (min 32 chars) |
+| `appUrl` | `string` | Yes | Your app's URL |
+| `cookieName` | `string` | No | Cookie name (default: `__authgate`) |
+| `sessionMaxAge` | `number` | No | Session TTL in seconds (default: `604800`) |
+| `callbackPath` | `string` | No | Callback path (default: `/api/auth/callback`) |
+
+### `createAuthGateMiddleware(client, options?)`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `loginPath` | `string` | `"/login"` | Redirect path for unauthenticated users |
+| `matcher` | `string[]` | `["/dashboard/:path*"]` | Route patterns to protect |
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@auth-gate/nextjs",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "exports": {
     ".": {
@@ -16,7 +16,7 @@
     "dist"
   ],
   "dependencies": {
-    "@auth-gate/core": "0.1.0"
+    "@auth-gate/core": "0.2.0"
   },
   "peerDependencies": {
     "next": ">=14"