@auth-gate/nextjs 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,224 @@
+import * as next_server_js from 'next/server.js';
+import * as _auth_gate_core from '@auth-gate/core';
+import { AuthGateClient, AuthGateUser, AuthGateConfig } from '@auth-gate/core';
+export { AuthGateConfig, AuthGateUser, CookieOptions, OAuthProvider, SUPPORTED_PROVIDERS, TokenVerifyResult, createAuthGateClient } from '@auth-gate/core';
+import { NextRequest, NextResponse } from 'next/server';
+
+/**
+ * Server-side session helpers for Next.js App Router.
+ *
+ * These functions use the Next.js `cookies()` API to read and write
+ * the encrypted session cookie. They must be called from Server Components,
+ * Server Actions, or Route Handlers — never from Client Components.
+ *
+ * @module
+ */
+
+/**
+ * Create session helper functions bound to an {@link AuthGateClient}.
+ *
+ * @param client - A configured AuthGateClient instance.
+ * @returns `{ getSession, setSession, clearSession }` — server-side session helpers.
+ *
+ * @example
+ * ```ts
+ * const { getSession, setSession, clearSession } = createSessionHelpers(client);
+ *
+ * // In a Server Component
+ * const user = await getSession();
+ * if (!user) redirect("/login");
+ * ```
+ */
+declare function createSessionHelpers(client: AuthGateClient): {
+    getSession: () => Promise<AuthGateUser | null>;
+    setSession: (user: AuthGateUser) => Promise<void>;
+    clearSession: () => Promise<void>;
+};
+
+/**
+ * Next.js App Router request handlers for all AuthGate authentication flows.
+ *
+ * These handlers are designed to be mounted as API routes. The recommended
+ * approach is to use {@link createCatchAllHandler} with a catch-all route:
+ *
+ * ```ts
+ * // app/api/auth/[...authgate]/route.ts
+ * import { handlers } from "@/lib/auth";
+ * export const { GET, POST } = handlers;
+ * ```
+ *
+ * Supported routes:
+ * - `GET  /:provider/login` — Initiate OAuth flow
+ * - `GET  /callback` — Handle OAuth/magic-link callback
+ * - `GET  /me` — Return current session user
+ * - `POST /email/signup` — Email + password registration
+ * - `POST /email/signin` — Email + password sign-in
+ * - `POST /email/forgot-password` — Send password reset email
+ * - `POST /email/reset-password` — Confirm password reset
+ * - `POST /email/verify-code` — Verify email with OTP code
+ * - `POST /magic-link/send` — Send magic link email
+ * - `POST /sms/send-code` — Send SMS verification code
+ * - `POST /sms/verify-code` — Verify SMS code
+ * - `POST /mfa/verify` — Complete MFA challenge
+ * - `POST /refresh` — Refresh JWT using refresh token cookie
+ * - `POST /logout` — Revoke session and clear cookies
+ *
+ * @module
+ */
+
+/**
+ * Create individual route handler functions for each auth endpoint.
+ *
+ * For most apps, prefer {@link createCatchAllHandler} which maps these
+ * handlers to URL paths automatically.
+ *
+ * @param client - A configured AuthGateClient instance.
+ * @param appUrl - Your app's public URL (e.g. `"http://localhost:3000"`).
+ */
+declare function createHandlers(client: AuthGateClient, appUrl: string): {
+    providerLogin: (_request: Request, { params }: {
+        params: Promise<{
+            provider: string;
+        }>;
+    }) => Promise<Response>;
+    callback: (request: NextRequest) => Promise<Response>;
+    emailSignup: (request: Request) => Promise<Response>;
+    emailSignin: (request: Request) => Promise<Response>;
+    emailForgotPassword: (request: Request) => Promise<Response>;
+    emailResetPassword: (request: Request) => Promise<Response>;
+    emailVerifyCode: (request: Request) => Promise<Response>;
+    magicLinkSend: (request: Request) => Promise<Response>;
+    smsSendCode: (request: Request) => Promise<Response>;
+    smsVerifyCode: (request: Request) => Promise<Response>;
+    mfaVerify: (request: Request) => Promise<Response>;
+    mfaTotpSetup: () => Promise<Response>;
+    refresh: () => Promise<Response>;
+    logout: () => Promise<Response>;
+    me: () => Promise<Response>;
+};
+/**
+ * Create a catch-all `{ GET, POST }` handler for the `[...authgate]` route.
+ *
+ * Mount this at `app/api/auth/[...authgate]/route.ts` to handle all
+ * AuthGate authentication endpoints with a single file.
+ *
+ * @param client - A configured AuthGateClient instance.
+ * @param appUrl - Your app's public URL (e.g. `"http://localhost:3000"`).
+ * @returns `{ GET, POST }` — Next.js route handlers.
+ *
+ * @example
+ * ```ts
+ * // app/api/auth/[...authgate]/route.ts
+ * import { client } from "@/lib/auth";
+ * import { createCatchAllHandler } from "@auth-gate/nextjs";
+ *
+ * export const { GET, POST } = createCatchAllHandler(client, process.env.NEXT_PUBLIC_APP_URL!);
+ * ```
+ */
+declare function createCatchAllHandler(client: AuthGateClient, appUrl: string): {
+    GET: (request: NextRequest, context: {
+        params: Promise<{
+            authgate: string[];
+        }>;
+    }) => Promise<Response>;
+    POST: (request: NextRequest, context: {
+        params: Promise<{
+            authgate: string[];
+        }>;
+    }) => Promise<Response>;
+};
+
+/**
+ * Composable authentication middleware for Next.js.
+ *
+ * Protects routes by checking for a valid encrypted session cookie.
+ * Periodically revalidates the session against the server using the
+ * refresh token, so revoked sessions are detected within minutes.
+ *
+ * Designed to compose with other middleware — returns `null` when no
+ * action is needed, or a redirect `NextResponse` when auth is required.
+ *
+ * @module
+ */
+
+/**
+ * Options for {@link createAuthGateMiddleware}.
+ */
+interface AuthGateMiddlewareOptions {
+    /**
+     * Path to redirect unauthenticated users to.
+     * @defaultValue `"/login"`
+     */
+    loginPath?: string;
+    /**
+     * URL patterns to protect. Uses Next.js-style matcher syntax
+     * (e.g. `"/dashboard/:path*"`).
+     * @defaultValue `["/dashboard/:path*"]`
+     */
+    matcher?: string[];
+}
+/**
+ * Creates a composable auth middleware function.
+ *
+ * Returns `null` when the request path doesn't match or the user is
+ * authenticated — letting your own middleware chain continue.
+ * Returns a redirect `NextResponse` when a matched path has no valid session.
+ *
+ * When a refresh token cookie is present, the middleware periodically
+ * revalidates the session against the server (every 5 minutes). If the
+ * session has been revoked, the user is redirected to the login page.
+ *
+ * @example
+ * ```ts
+ * // middleware.ts — compose with other middleware
+ * import { authMiddleware } from "@/lib/auth";
+ *
+ * export default async function middleware(request: NextRequest) {
+ *   const authResponse = await authMiddleware(request);
+ *   if (authResponse) return authResponse;
+ *
+ *   // ...other middleware logic
+ *   return NextResponse.next();
+ * }
+ *
+ * export const config = {
+ *   matcher: ["/dashboard/:path*", "/settings/:path*"],
+ * };
+ * ```
+ */
+declare function createAuthGateMiddleware(clientOrGetter: AuthGateClient | (() => AuthGateClient), options?: AuthGateMiddlewareOptions): (request: NextRequest) => Promise<NextResponse | null>;
+
+/**
+ * Initialize AuthGate for a Next.js App Router application.
+ *
+ * Returns three objects:
+ * - `client` — the underlying {@link AuthGateClient} for direct API access.
+ * - `handlers` — `{ GET, POST }` route handlers to mount at `app/api/auth/[...authgate]/route.ts`.
+ * - `session` — `{ getSession, setSession, clearSession }` helpers for reading/writing the session cookie.
+ *
+ * @param config - AuthGate config plus `appUrl` (your app's public URL, e.g. `"http://localhost:3000"`).
+ */
+declare function createAuthGate(config: AuthGateConfig & {
+    appUrl: string;
+}): {
+    client: _auth_gate_core.AuthGateClient;
+    handlers: {
+        GET: (request: next_server_js.NextRequest, context: {
+            params: Promise<{
+                authgate: string[];
+            }>;
+        }) => Promise<Response>;
+        POST: (request: next_server_js.NextRequest, context: {
+            params: Promise<{
+                authgate: string[];
+            }>;
+        }) => Promise<Response>;
+    };
+    session: {
+        getSession: () => Promise<_auth_gate_core.AuthGateUser | null>;
+        setSession: (user: _auth_gate_core.AuthGateUser) => Promise<void>;
+        clearSession: () => Promise<void>;
+    };
+};
+
+export { type AuthGateMiddlewareOptions, createAuthGate, createAuthGateMiddleware, createCatchAllHandler, createHandlers, createSessionHelpers };

package/dist/index.d.ts

@@ -0,0 +1,224 @@
+import * as next_server_js from 'next/server.js';
+import * as _auth_gate_core from '@auth-gate/core';
+import { AuthGateClient, AuthGateUser, AuthGateConfig } from '@auth-gate/core';
+export { AuthGateConfig, AuthGateUser, CookieOptions, OAuthProvider, SUPPORTED_PROVIDERS, TokenVerifyResult, createAuthGateClient } from '@auth-gate/core';
+import { NextRequest, NextResponse } from 'next/server';
+
+/**
+ * Server-side session helpers for Next.js App Router.
+ *
+ * These functions use the Next.js `cookies()` API to read and write
+ * the encrypted session cookie. They must be called from Server Components,
+ * Server Actions, or Route Handlers — never from Client Components.
+ *
+ * @module
+ */
+
+/**
+ * Create session helper functions bound to an {@link AuthGateClient}.
+ *
+ * @param client - A configured AuthGateClient instance.
+ * @returns `{ getSession, setSession, clearSession }` — server-side session helpers.
+ *
+ * @example
+ * ```ts
+ * const { getSession, setSession, clearSession } = createSessionHelpers(client);
+ *
+ * // In a Server Component
+ * const user = await getSession();
+ * if (!user) redirect("/login");
+ * ```
+ */
+declare function createSessionHelpers(client: AuthGateClient): {
+    getSession: () => Promise<AuthGateUser | null>;
+    setSession: (user: AuthGateUser) => Promise<void>;
+    clearSession: () => Promise<void>;
+};
+
+/**
+ * Next.js App Router request handlers for all AuthGate authentication flows.
+ *
+ * These handlers are designed to be mounted as API routes. The recommended
+ * approach is to use {@link createCatchAllHandler} with a catch-all route:
+ *
+ * ```ts
+ * // app/api/auth/[...authgate]/route.ts
+ * import { handlers } from "@/lib/auth";
+ * export const { GET, POST } = handlers;
+ * ```
+ *
+ * Supported routes:
+ * - `GET  /:provider/login` — Initiate OAuth flow
+ * - `GET  /callback` — Handle OAuth/magic-link callback
+ * - `GET  /me` — Return current session user
+ * - `POST /email/signup` — Email + password registration
+ * - `POST /email/signin` — Email + password sign-in
+ * - `POST /email/forgot-password` — Send password reset email
+ * - `POST /email/reset-password` — Confirm password reset
+ * - `POST /email/verify-code` — Verify email with OTP code
+ * - `POST /magic-link/send` — Send magic link email
+ * - `POST /sms/send-code` — Send SMS verification code
+ * - `POST /sms/verify-code` — Verify SMS code
+ * - `POST /mfa/verify` — Complete MFA challenge
+ * - `POST /refresh` — Refresh JWT using refresh token cookie
+ * - `POST /logout` — Revoke session and clear cookies
+ *
+ * @module
+ */
+
+/**
+ * Create individual route handler functions for each auth endpoint.
+ *
+ * For most apps, prefer {@link createCatchAllHandler} which maps these
+ * handlers to URL paths automatically.
+ *
+ * @param client - A configured AuthGateClient instance.
+ * @param appUrl - Your app's public URL (e.g. `"http://localhost:3000"`).
+ */
+declare function createHandlers(client: AuthGateClient, appUrl: string): {
+    providerLogin: (_request: Request, { params }: {
+        params: Promise<{
+            provider: string;
+        }>;
+    }) => Promise<Response>;
+    callback: (request: NextRequest) => Promise<Response>;
+    emailSignup: (request: Request) => Promise<Response>;
+    emailSignin: (request: Request) => Promise<Response>;
+    emailForgotPassword: (request: Request) => Promise<Response>;
+    emailResetPassword: (request: Request) => Promise<Response>;
+    emailVerifyCode: (request: Request) => Promise<Response>;
+    magicLinkSend: (request: Request) => Promise<Response>;
+    smsSendCode: (request: Request) => Promise<Response>;
+    smsVerifyCode: (request: Request) => Promise<Response>;
+    mfaVerify: (request: Request) => Promise<Response>;
+    mfaTotpSetup: () => Promise<Response>;
+    refresh: () => Promise<Response>;
+    logout: () => Promise<Response>;
+    me: () => Promise<Response>;
+};
+/**
+ * Create a catch-all `{ GET, POST }` handler for the `[...authgate]` route.
+ *
+ * Mount this at `app/api/auth/[...authgate]/route.ts` to handle all
+ * AuthGate authentication endpoints with a single file.
+ *
+ * @param client - A configured AuthGateClient instance.
+ * @param appUrl - Your app's public URL (e.g. `"http://localhost:3000"`).
+ * @returns `{ GET, POST }` — Next.js route handlers.
+ *
+ * @example
+ * ```ts
+ * // app/api/auth/[...authgate]/route.ts
+ * import { client } from "@/lib/auth";
+ * import { createCatchAllHandler } from "@auth-gate/nextjs";
+ *
+ * export const { GET, POST } = createCatchAllHandler(client, process.env.NEXT_PUBLIC_APP_URL!);
+ * ```
+ */
+declare function createCatchAllHandler(client: AuthGateClient, appUrl: string): {
+    GET: (request: NextRequest, context: {
+        params: Promise<{
+            authgate: string[];
+        }>;
+    }) => Promise<Response>;
+    POST: (request: NextRequest, context: {
+        params: Promise<{
+            authgate: string[];
+        }>;
+    }) => Promise<Response>;
+};
+
+/**
+ * Composable authentication middleware for Next.js.
+ *
+ * Protects routes by checking for a valid encrypted session cookie.
+ * Periodically revalidates the session against the server using the
+ * refresh token, so revoked sessions are detected within minutes.
+ *
+ * Designed to compose with other middleware — returns `null` when no
+ * action is needed, or a redirect `NextResponse` when auth is required.
+ *
+ * @module
+ */
+
+/**
+ * Options for {@link createAuthGateMiddleware}.
+ */
+interface AuthGateMiddlewareOptions {
+    /**
+     * Path to redirect unauthenticated users to.
+     * @defaultValue `"/login"`
+     */
+    loginPath?: string;
+    /**
+     * URL patterns to protect. Uses Next.js-style matcher syntax
+     * (e.g. `"/dashboard/:path*"`).
+     * @defaultValue `["/dashboard/:path*"]`
+     */
+    matcher?: string[];
+}
+/**
+ * Creates a composable auth middleware function.
+ *
+ * Returns `null` when the request path doesn't match or the user is
+ * authenticated — letting your own middleware chain continue.
+ * Returns a redirect `NextResponse` when a matched path has no valid session.
+ *
+ * When a refresh token cookie is present, the middleware periodically
+ * revalidates the session against the server (every 5 minutes). If the
+ * session has been revoked, the user is redirected to the login page.
+ *
+ * @example
+ * ```ts
+ * // middleware.ts — compose with other middleware
+ * import { authMiddleware } from "@/lib/auth";
+ *
+ * export default async function middleware(request: NextRequest) {
+ *   const authResponse = await authMiddleware(request);
+ *   if (authResponse) return authResponse;
+ *
+ *   // ...other middleware logic
+ *   return NextResponse.next();
+ * }
+ *
+ * export const config = {
+ *   matcher: ["/dashboard/:path*", "/settings/:path*"],
+ * };
+ * ```
+ */
+declare function createAuthGateMiddleware(clientOrGetter: AuthGateClient | (() => AuthGateClient), options?: AuthGateMiddlewareOptions): (request: NextRequest) => Promise<NextResponse | null>;
+
+/**
+ * Initialize AuthGate for a Next.js App Router application.
+ *
+ * Returns three objects:
+ * - `client` — the underlying {@link AuthGateClient} for direct API access.
+ * - `handlers` — `{ GET, POST }` route handlers to mount at `app/api/auth/[...authgate]/route.ts`.
+ * - `session` — `{ getSession, setSession, clearSession }` helpers for reading/writing the session cookie.
+ *
+ * @param config - AuthGate config plus `appUrl` (your app's public URL, e.g. `"http://localhost:3000"`).
+ */
+declare function createAuthGate(config: AuthGateConfig & {
+    appUrl: string;
+}): {
+    client: _auth_gate_core.AuthGateClient;
+    handlers: {
+        GET: (request: next_server_js.NextRequest, context: {
+            params: Promise<{
+                authgate: string[];
+            }>;
+        }) => Promise<Response>;
+        POST: (request: next_server_js.NextRequest, context: {
+            params: Promise<{
+                authgate: string[];
+            }>;
+        }) => Promise<Response>;
+    };
+    session: {
+        getSession: () => Promise<_auth_gate_core.AuthGateUser | null>;
+        setSession: (user: _auth_gate_core.AuthGateUser) => Promise<void>;
+        clearSession: () => Promise<void>;
+    };
+};
+
+export { type AuthGateMiddlewareOptions, createAuthGate, createAuthGateMiddleware, createCatchAllHandler, createHandlers, createSessionHelpers };