@authaz/next 0.0.1 → 1.0.1

package/README.md

@@ -1,6 +1,6 @@
 # @authaz/next
 
-Next.js integration for Authaz authentication. Provides server-side session management with cookie-based authentication for Next.js applications.
+Next.js SDK for Authaz authentication.
 
 ## Installation
 
@@ -12,198 +12,53 @@ pnpm add @authaz/next @authaz/sdk
 yarn add @authaz/next @authaz/sdk
 ```
 
-### Peer Dependencies
+## Usage
 
-```bash
-npm install next@">=15" react@">=17" @authaz/sdk@workspace:*
-```
-
-## Features
-
-- **Server-Side Session Management** - Secure cookie-based authentication
-- **Next.js 15+ Support** - Built for the latest Next.js features
-- **Type-Safe** - Full TypeScript support
-- **Cookie Integration** - Uses Next.js cookies API for secure token storage
-- **Debug Mode** - Optional debug logging for development
-- **Zero Configuration** - Works with sensible defaults
-
-## Quick Start
-
-### 1. Configure Authaz SDK
-
-```typescript
-// lib/authaz.ts
-import { authazNext } from "@authaz/next";
-
-export const authaz = authazNext(
-    {
-        clientId: process.env.AUTHAZ_CLIENT_ID!,
-        clientSecret: process.env.AUTHAZ_CLIENT_SECRET!,
-        tenantId: process.env.AUTHAZ_TENANT_ID!,
-        organizationId: process.env.AUTHAZ_ORG_ID!,
-        redirectUri: process.env.AUTHAZ_REDIRECT_URI!,
-    },
-    {
-        debug: process.env.NODE_ENV === "development",
-        cookies: {
-            accessToken: "accessToken", // optional
-        },
-    }
-);
-```
-
-### 2. Use in Server Components
-
-```tsx
-// app/dashboard/page.tsx
-import { authaz } from "@/lib/authaz";
-import { redirect } from "next/navigation";
-
-export default async function DashboardPage() {
-    const user = await authaz.getUserSession();
-
-    if (!user) {
-        redirect("/login");
-    }
-
-    return (
-        <div>
-            <h1>Welcome, {user.name}</h1>
-            <p>Email: {user.email}</p>
-        </div>
-    );
-}
-```
-
-### 3. Use in API Routes
-
-```typescript
-// app/api/user/route.ts
-import { authaz } from "@/lib/authaz";
-import { NextResponse } from "next/server";
-
-export async function GET() {
-    const user = await authaz.getUserSession();
-
-    if (!user) {
-        return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
-    }
-
-    return NextResponse.json({ user });
-}
-```
-
-## API Reference
-
-### `authazNext(config, options?)`
-
-Creates an Authaz instance configured for Next.js.
-
-```typescript
-// SDK Configuration (required)
-config: {
-    clientId: string;
-    clientSecret: string;
-    tenantId: string;
-    organizationId: string;
-    redirectUri?: string;
-    authPoolId?: string;
-}
-
-// SDK Options (optional)
-options?: {
-    debug?: boolean;
-    cookies?: {
-        accessToken?: string; // Default: "accessToken"
-    }
-}
-```
-
-Returns:
+### API Routes Setup
 
 ```typescript
-{
-    getUserSession: () => Promise<UserProfile | null>
-}
-```
-
-### `getUserSession()`
+// app/api/auth/[...authaz]/route.ts
+import { createAuthazHandler } from '@authaz/next';
 
-Retrieves the authenticated user's session from cookies.
-
-Returns `UserProfile | null`:
-
-```typescript
-interface UserProfile {
-    id: string;
-    email: string;
-    name: string;
-    role?: string;
-    createdAt?: string;
-    updatedAt?: string;
-}
+export const { GET, POST } = createAuthazHandler({
+  clientId: process.env.AUTHAZ_CLIENT_ID!,
+  clientSecret: process.env.AUTHAZ_CLIENT_SECRET!,
+});
 ```
 
-## Environment Variables
-
-Create a `.env.local` file:
-
-```env
-AUTHAZ_CLIENT_ID=your_client_id
-AUTHAZ_CLIENT_SECRET=your_client_secret
-AUTHAZ_TENANT_ID=your_tenant_id
-AUTHAZ_ORG_ID=your_organization_id
-AUTHAZ_REDIRECT_URI=http://localhost:3000/callback
-```
-
-## Middleware Protection
-
-Protect multiple routes with Next.js middleware:
+### Middleware
 
 ```typescript
 // middleware.ts
-import { NextResponse } from "next/server";
-import type { NextRequest } from "next/server";
-import { authaz } from "@/lib/authaz";
+import { withAuthaz } from '@authaz/next';
 
-export async function middleware(request: NextRequest) {
-    const user = await authaz.getUserSession();
-
-    if (request.nextUrl.pathname.startsWith("/dashboard") && !user) {
-        return NextResponse.redirect(new URL("/login", request.url));
-    }
-
-    return NextResponse.next();
-}
+export default withAuthaz();
 
 export const config = {
-    matcher: ["/dashboard/:path*"],
+  matcher: ['/dashboard/:path*', '/api/:path*'],
 };
 ```
 
-## Security Best Practices
-
-1. **Use HTTP-Only Cookies** - Always set `httpOnly: true`
-2. **Enable Secure Flag in Production** - Set `secure: true` when `NODE_ENV === "production"`
-3. **Set SameSite** - Use `sameSite: "lax"` or `"strict"`
-4. **Never Expose Client Secret** - Only use this package in server-side code
-5. **Implement Token Refresh** - Refresh tokens before expiration
-
-## TypeScript Support
-
-Full TypeScript support with type inference:
+### Server Components
 
 ```typescript
-import type { UserProfile } from "@authaz/sdk";
-
-const user: UserProfile | null = await authaz.getUserSession();
+import { getSession } from '@authaz/next';
+
+async function Page() {
+  const session = await getSession();
+  
+  if (!session) {
+    return <div>Not authenticated</div>;
+  }
+  
+  return <div>Hello, {session.user?.name}</div>;
+}
 ```
 
-## License
+## Documentation
 
-MIT
+For full documentation, visit [https://authaz.io/docs](https://authaz.io/docs)
 
-## Support
+## License
 
-- GitHub: https://github.com/Authaz/authaz-sdk-js
-- Documentation: https://www.authaz.io/docs
+MIT

package/dist/index.d.ts

@@ -1,17 +1,215 @@
-import * as _authaz_sdk0 from "@authaz/sdk";
-import { UserProfile, authaz } from "@authaz/sdk";
+import { AuthazClient, AuthazConfig, AuthazError, AuthazUser, LoginResult, TokenSet } from "@authaz/sdk";
+import { NextRequest, NextResponse } from "next/server";
 
 //#region src/index.d.ts
-type SdkConfig = {
+type AuthazNextConfig = AuthazConfig & {
+  /**
+   * Base path for auth routes (default: "/api/auth")
+   * Routes will be: {basePath}/login, {basePath}/callback, {basePath}/logout
+   */
+  basePath?: string;
+  /**
+   * URL to redirect to after successful login (default: "/")
+   */
+  afterLoginUrl?: string;
+  /**
+   * URL to redirect to after logout (default: "/")
+   */
+  afterLogoutUrl?: string;
+  /**
+   * Fixed redirect URI for OAuth callback.
+   * This should match exactly what's registered in the Identity Provider.
+   * Example: "https://dashboard:3000/auth/redirect"
+   * If not provided, the SDK will construct it from the request URL.
+   */
+  redirectUri?: string;
+  /**
+   * API key for API requests (X-API-Key header).
+   * Falls back to clientSecret if not provided.
+   */
+  apiKey?: string;
+  /**
+   * Enable debug logging
+   */
   debug?: boolean;
-  cookies?: {
-    accessToken?: string;
-  };
 };
-type AuthazArgs = Parameters<typeof authaz>[0];
-declare const authazNext: (config: AuthazArgs, args?: SdkConfig) => {
-  getUserSession: () => Promise<UserProfile | null>;
-  sdk: _authaz_sdk0.ApiService;
+type AuthHandler = {
+  GET: (request: NextRequest) => Promise<NextResponse>;
+  POST: (request: NextRequest) => Promise<NextResponse>;
+};
+/**
+ * Creates the Authaz Next.js authentication handler.
+ *
+ * This creates a route handler that manages the complete OAuth flow:
+ * - GET /api/auth/login - Redirects to Universal Login
+ * - POST /api/auth/callback - Handles OAuth callback (receives code via form POST)
+ * - POST /api/auth/logout - Clears session and redirects to logout (POST-only for CSRF protection)
+ * - GET /api/auth/me - Returns current user info (requires valid session)
+ * - POST /api/auth/refresh - Refreshes the access token
+ *
+ * IMPORTANT: The OAuth callback from the identity provider arrives as GET.
+ * You need a callback page that POSTs to /api/auth/callback:
+ *
+ * ```tsx
+ * // app/auth/callback/page.tsx
+ * 'use client';
+ * import { useEffect } from 'react';
+ * import { useSearchParams } from 'next/navigation';
+ *
+ * export default function CallbackPage() {
+ *   const searchParams = useSearchParams();
+ *
+ *   useEffect(() => {
+ *     const form = document.createElement('form');
+ *     form.method = 'POST';
+ *     form.action = '/api/auth/callback';
+ *
+ *     const code = searchParams.get('code');
+ *     const state = searchParams.get('state');
+ *     const error = searchParams.get('error');
+ *
+ *     ['code', 'state', 'error', 'error_description'].forEach(param => {
+ *       const value = searchParams.get(param);
+ *       if (value) {
+ *         const input = document.createElement('input');
+ *         input.type = 'hidden';
+ *         input.name = param;
+ *         input.value = value;
+ *         form.appendChild(input);
+ *       }
+ *     });
+ *
+ *     document.body.appendChild(form);
+ *     form.submit();
+ *   }, [searchParams]);
+ *
+ *   return <div>Completing login...</div>;
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // app/api/auth/[...authaz]/route.ts
+ * import { createAuthazHandler } from '@authaz/next';
+ *
+ * export const { GET, POST } = createAuthazHandler({
+ *   clientId: process.env.AUTHAZ_CLIENT_ID!,
+ *   clientSecret: process.env.AUTHAZ_CLIENT_SECRET!,
+ *   tenantId: process.env.AUTHAZ_TENANT_ID!,
+ *   organizationId: process.env.AUTHAZ_ORGANIZATION_ID!,
+ * });
+ * ```
+ */
+declare const createAuthazHandler: (config: AuthazNextConfig) => AuthHandler;
+/**
+ * Gets the current access token from cookies.
+ */
+declare const getAccessToken: () => Promise<string | null>;
+/**
+ * Gets the current refresh token from cookies.
+ */
+declare const getRefreshToken: () => Promise<string | null>;
+/**
+ * Checks if the user is authenticated (has an access token).
+ */
+declare const isAuthenticated: () => Promise<boolean>;
+/**
+ * Creates helper functions that require the authazDomain for API calls.
+ */
+declare const createAuthazHelpers: (config: {
+  authazDomain?: string;
+  clientSecret?: string;
+  apiKey?: string;
+}) => {
+  getUser: () => Promise<AuthazUser | null>;
+};
+/**
+ * Creates middleware config for protecting routes in Next.js middleware.ts
+ *
+ * @example
+ * ```typescript
+ * // middleware.ts
+ * import { createAuthMiddleware } from '@authaz/next';
+ *
+ * export const middleware = createAuthMiddleware({
+ *   publicPaths: ['/', '/login', '/api/auth'],
+ *   loginPath: '/api/auth/login',
+ * });
+ *
+ * export const config = {
+ *   matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
+ * };
+ * ```
+ */
+declare const createAuthMiddleware: (options: {
+  /**
+   * Paths that don't require authentication (supports wildcards with *)
+   */
+  publicPaths?: string[];
+  /**
+   * Path to redirect unauthenticated users to (default: '/api/auth/login')
+   */
+  loginPath?: string;
+}) => (request: NextRequest) => Promise<NextResponse>;
+/**
+ * Wrapper for API route handlers that require authentication.
+ * Returns 401 if not authenticated.
+ *
+ * @example
+ * ```typescript
+ * // app/api/protected/route.ts
+ * import { withAuth } from '@authaz/next';
+ *
+ * export const GET = withAuth(async (request) => {
+ *   // User is authenticated
+ *   return Response.json({ message: 'Protected data' });
+ * });
+ * ```
+ */
+declare const withAuth: (handler: (request: NextRequest) => Promise<Response>) => ((request: NextRequest) => Promise<Response>);
+/**
+ * Server Component helper that throws redirect if not authenticated.
+ * Use in Server Components to protect pages.
+ *
+ * @example
+ * ```typescript
+ * // app/dashboard/page.tsx
+ * import { requireAuth } from '@authaz/next';
+ *
+ * export default async function DashboardPage() {
+ *   await requireAuth(); // Redirects to login if not authenticated
+ *
+ *   return <div>Dashboard</div>;
+ * }
+ * ```
+ */
+declare const requireAuth: (loginPath?: string) => Promise<void>;
+/**
+ * Server Component helper that returns user or redirects if not authenticated.
+ *
+ * @example
+ * ```typescript
+ * // app/profile/page.tsx
+ * import { requireUser } from '@authaz/next';
+ *
+ * const helpers = requireUser({
+ *   authazDomain: 'https://authaz.com',
+ *   apiKey: process.env.AUTHAZ_API_KEY!,
+ * });
+ *
+ * export default async function ProfilePage() {
+ *   const user = await helpers.getOrRedirect();
+ *   return <div>Hello {user.name}</div>;
+ * }
+ * ```
+ */
+declare const requireUser: (config: {
+  authazDomain?: string;
+  clientSecret?: string;
+  apiKey?: string;
+  loginPath?: string;
+}) => {
+  getOrRedirect: () => Promise<AuthazUser>;
 };
 //#endregion
-export { authazNext };
+export { type AuthazClient, type AuthazConfig, AuthazError, AuthazNextConfig, type AuthazUser, type LoginResult, type TokenSet, createAuthMiddleware, createAuthazHandler, createAuthazHelpers, getAccessToken, getRefreshToken, isAuthenticated, requireAuth, requireUser, withAuth };