@monocloud/auth-nextjs 0.1.9 → 0.1.11

package/dist/initialize.cjs

@@ -0,0 +1,284 @@
+const require_monocloud_next_client = require('./monocloud-next-client.cjs');
+
+//#region src/initialize.ts
+let instance;
+/**
+* Retrieves the singleton instance of the MonoCloudNextClient.
+* Initializes it lazily on the first call.
+*/
+const getInstance = () => {
+	instance ??= new require_monocloud_next_client.MonoCloudNextClient();
+	return instance;
+};
+/**
+* Creates a Next.js catch-all auth route handler (Pages Router and App Router) for the built-in routes (`/signin`, `/callback`, `/userinfo`, `/signout`).
+*
+* Mount this handler on a catch-all route (e.g. `/api/auth/[...monocloud]`).
+*
+* > If you already use `authMiddleware()`, you typically don’t need this handler. Use `monoCloudAuth()` when middleware cannot be used or when auth routes need customization.
+*
+* @example App Router
+* ```tsx:src/app/api/auth/[...monocloud]/route.ts tab="App Router" tab-group="monoCloudAuth"
+* import { monoCloudAuth } from "@monocloud/auth-nextjs";
+*
+* export const GET = monoCloudAuth();
+*```
+*
+* @example App Router (Response)
+* ```tsx:src/app/api/auth/[...monocloud]/route.ts tab="App Router (Response)" tab-group="monoCloudAuth"
+* import { monoCloudAuth } from "@monocloud/auth-nextjs";
+* import { NextRequest, NextResponse } from "next/server";
+*
+* export const GET = (req: NextRequest) => {
+*   const authHandler = monoCloudAuth();
+*
+*   const res = new NextResponse();
+*
+*   res.cookies.set("last_auth_requested", `${Date.now()}`);
+*
+*   return authHandler(req, res);
+* };
+* ```
+*
+* @example Pages Router
+* ```tsx:src/pages/api/auth/[...monocloud].ts tab="Pages Router" tab-group="monoCloudAuth"
+* import { monoCloudAuth } from "@monocloud/auth-nextjs";
+*
+* export default monoCloudAuth();
+*```
+*
+* @example Pages Router (Response)
+* ```tsx:src/pages/api/auth/[...monocloud].ts tab="Pages Router (Response)" tab-group="monoCloudAuth"
+* import { monoCloudAuth } from "@monocloud/auth-nextjs";
+* import { NextApiRequest, NextApiResponse } from "next";
+*
+* export default function handler(req: NextApiRequest, res: NextApiResponse) {
+*   const authHandler = monoCloudAuth();
+*
+*   res.setHeader("last_auth_requested", `${Date.now()}`);
+*
+*   return authHandler(req, res);
+* }
+* ```
+*
+* @param options Optional configuration for the auth handler.
+* @returns Returns a Next.js-compatible handler for App Router route handlers or Pages Router API routes.
+*
+* @category Functions
+*/
+function monoCloudAuth(options) {
+	return getInstance().monoCloudAuth(options);
+}
+function authMiddleware(...args) {
+	return getInstance().authMiddleware(...args);
+}
+function getSession(...args) {
+	return getInstance().getSession(...args);
+}
+function getTokens(...args) {
+	return getInstance().getTokens(...args);
+}
+function isAuthenticated(...args) {
+	return getInstance().isAuthenticated(...args);
+}
+/**
+* Ensures the current user is authenticated. If not, redirects to the sign-in flow.
+*
+* > **App Router only.** Intended for Server Components, Route Handlers, and Server Actions.
+*
+* @example Server Component
+* ```tsx:src/app/page.tsx tab="Server Component" tab-group="protect"
+* import { protect } from "@monocloud/auth-nextjs";
+*
+* export default async function Home() {
+*   await protect();
+*
+*   return <>You are signed in.</>;
+* }
+* ```
+*
+* @example Server Action
+* ```tsx:src/action.ts tab="Server Action" tab-group="protect"
+* "use server";
+*
+* import { protect } from "@monocloud/auth-nextjs";
+*
+* export async function getMessage() {
+*   await protect();
+*
+*   return { secret: "sssshhhhh!!!" };
+* }
+* ```
+*
+* @example API Handler
+* ```tsx:src/app/api/protected/route.ts tab="API Handler" tab-group="protect"
+* import { protect } from "@monocloud/auth-nextjs";
+* import { NextResponse } from "next/server";
+*
+* export const GET = async () => {
+*   await protect();
+*
+*   return NextResponse.json({ secret: "ssshhhh!!!" });
+* };
+* ```
+*
+* @param options Optional configuration for redirect behavior (for example, return URL or sign-in parameters).
+* @returns Resolves if the user is authenticated; otherwise triggers a redirect.
+*
+* @category Functions
+*/
+function protect(options) {
+	return getInstance().protect(options);
+}
+function protectApi(handler, options) {
+	return getInstance().protectApi(handler, options);
+}
+function protectPage(...args) {
+	return getInstance().protectPage(...args);
+}
+function isUserInGroup(...args) {
+	return getInstance().isUserInGroup(...args);
+}
+/**
+* Redirects the user to the sign-in flow.
+*
+* > **App Router only**. Intended for use in Server Components, Route Handlers, and Server Actions.
+*
+* This helper performs a server-side redirect to the configured sign-in route. Execution does not continue after the redirect is triggered.
+*
+* @example Server Component
+* ```tsx:src/app/page.tsx tab="Server Component" tab-group="redirect-to-sign-in"
+* import { isUserInGroup, redirectToSignIn } from "@monocloud/auth-nextjs";
+*
+* export default async function Home() {
+*   const allowed = await isUserInGroup(["admin"]);
+*
+*   if (!allowed) {
+*     await redirectToSignIn({ returnUrl: "/home" });
+*   }
+*
+*   return <>You are signed in.</>;
+* }
+* ```
+*
+* @example Server Action
+* ```tsx:src/action.ts tab="Server Action" tab-group="redirect-to-sign-in"
+* "use server";
+*
+* import { getSession, redirectToSignIn } from "@monocloud/auth-nextjs";
+*
+* export async function protectedAction() {
+*   const session = await getSession();
+*
+*   if (!session) {
+*     await redirectToSignIn();
+*   }
+*
+*   return { data: "Sensitive Data" };
+* }
+* ```
+*
+* @example API Handler
+* ```tsx:src/app/api/protected/route.ts tab="API Handler" tab-group="redirect-to-sign-in"
+* import { getSession, redirectToSignIn } from "@monocloud/auth-nextjs";
+* import { NextResponse } from "next/server";
+*
+* export const GET = async () => {
+*   const session = await getSession();
+*
+*   if (!session) {
+*     await redirectToSignIn({
+*       returnUrl: "/dashboard",
+*     });
+*   }
+*
+*   return NextResponse.json({ data: "Protected content" });
+* };
+* ```
+*
+* @param options Optional configuration for the redirect, such as `returnUrl` or additional sign-in parameters.
+* @returns Never resolves. Triggers a redirect to the sign-in flow.
+*
+* @category Functions
+*/
+function redirectToSignIn(options) {
+	return getInstance().redirectToSignIn(options);
+}
+/**
+* Redirects the user to the sign-out flow.
+*
+* > **App Router only**. Intended for use in Server Components, Route Handlers, and Server Actions.
+*
+* This helper performs a server-side redirect to the configured sign-out route. Execution does not continue after the redirect is triggered.
+*
+* @example Server Component
+* ```tsx:src/app/page.tsx tab="Server Component" tab-group="redirect-to-sign-out"
+* import { getSession, redirectToSignOut } from "@monocloud/auth-nextjs";
+*
+* export default async function Page() {
+*   const session = await getSession();
+*
+*   // Example: Force sign-out if a specific condition is met (e.g., account suspended)
+*   if (session?.user.isSuspended) {
+*     await redirectToSignOut();
+*   }
+*
+*   return <>Welcome User</>;
+* }
+* ```
+*
+* @example Server Action
+* ```tsx:src/action.ts tab="Server Action" tab-group="redirect-to-sign-out"
+* "use server";
+*
+* import { getSession, redirectToSignOut } from "@monocloud/auth-nextjs";
+*
+* export async function signOutAction() {
+*   const session = await getSession();
+*
+*   if (session) {
+*     await redirectToSignOut();
+*   }
+* }
+* ```
+*
+* @example API Handler
+* ```tsx:src/app/api/signout/route.ts tab="API Handler" tab-group="redirect-to-sign-out"
+* import { getSession, redirectToSignOut } from "@monocloud/auth-nextjs";
+* import { NextResponse } from "next/server";
+*
+* export const GET = async () => {
+*   const session = await getSession();
+*
+*   if (session) {
+*     await redirectToSignOut({
+*       postLogoutRedirectUri: "/goodbye",
+*     });
+*   }
+*
+*   return NextResponse.json({ status: "already_signed_out" });
+* };
+* ```
+*
+* @param options Optional configuration for the redirect, such as `postLogoutRedirectUri` or additional sign-out parameters.
+* @returns Never resolves. Triggers a redirect to the sign-out flow.
+*
+* @category Functions
+*/
+function redirectToSignOut(options) {
+	return getInstance().redirectToSignOut(options);
+}
+
+//#endregion
+exports.authMiddleware = authMiddleware;
+exports.getSession = getSession;
+exports.getTokens = getTokens;
+exports.isAuthenticated = isAuthenticated;
+exports.isUserInGroup = isUserInGroup;
+exports.monoCloudAuth = monoCloudAuth;
+exports.protect = protect;
+exports.protectApi = protectApi;
+exports.protectPage = protectPage;
+exports.redirectToSignIn = redirectToSignIn;
+exports.redirectToSignOut = redirectToSignOut;
+//# sourceMappingURL=initialize.cjs.map

package/dist/initialize.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"initialize.cjs","names":["MonoCloudNextClient"],"sources":["../src/initialize.ts"],"sourcesContent":["import type { ParsedUrlQuery } from 'node:querystring';\nimport { MonoCloudNextClient } from './monocloud-next-client';\nimport type {\n  AppRouterApiHandlerFn,\n  AppRouterPageHandler,\n  IsUserInGroupOptions,\n  MonoCloudAuthHandler,\n  MonoCloudAuthOptions,\n  MonoCloudMiddlewareOptions,\n  NextMiddlewareResult,\n  ProtectApiAppOptions,\n  ProtectApiPageOptions,\n  ProtectAppPageOptions,\n  ProtectedAppServerComponent,\n  ProtectOptions,\n  ProtectPagePageOptions,\n  ProtectPagePageReturnType,\n  RedirectToSignInOptions,\n  RedirectToSignOutOptions,\n} from './types';\nimport type {\n  NextMiddleware,\n  NextProxy,\n  NextRequest,\n  NextFetchEvent,\n  NextResponse,\n} from 'next/server';\nimport type { MonoCloudSession } from '@monocloud/auth-core';\nimport type { IncomingMessage, ServerResponse } from 'node:http';\nimport type { NextApiHandler, NextApiRequest, NextApiResponse } from 'next';\nimport type {\n  GetSessionOptions,\n  GetTokensOptions,\n  MonoCloudTokens,\n} from '@monocloud/auth-node-core';\n\nlet instance: MonoCloudNextClient | undefined;\n\n/**\n * Retrieves the singleton instance of the MonoCloudNextClient.\n * Initializes it lazily on the first call.\n */\nconst getInstance = (): MonoCloudNextClient => {\n  instance ??= new MonoCloudNextClient();\n  return instance;\n};\n\n/**\n * Creates a Next.js catch-all auth route handler (Pages Router and App Router) for the built-in routes (`/signin`, `/callback`, `/userinfo`, `/signout`).\n *\n * Mount this handler on a catch-all route (e.g. `/api/auth/[...monocloud]`).\n *\n * > If you already use `authMiddleware()`, you typically don’t need this handler. Use `monoCloudAuth()` when middleware cannot be used or when auth routes need customization.\n *\n * @example App Router\n * ```tsx:src/app/api/auth/[...monocloud]/route.ts tab=\"App Router\" tab-group=\"monoCloudAuth\"\n * import { monoCloudAuth } from \"@monocloud/auth-nextjs\";\n *\n * export const GET = monoCloudAuth();\n *```\n *\n * @example App Router (Response)\n * ```tsx:src/app/api/auth/[...monocloud]/route.ts tab=\"App Router (Response)\" tab-group=\"monoCloudAuth\"\n * import { monoCloudAuth } from \"@monocloud/auth-nextjs\";\n * import { NextRequest, NextResponse } from \"next/server\";\n *\n * export const GET = (req: NextRequest) => {\n *   const authHandler = monoCloudAuth();\n *\n *   const res = new NextResponse();\n *\n *   res.cookies.set(\"last_auth_requested\", `${Date.now()}`);\n *\n *   return authHandler(req, res);\n * };\n * ```\n *\n * @example Pages Router\n * ```tsx:src/pages/api/auth/[...monocloud].ts tab=\"Pages Router\" tab-group=\"monoCloudAuth\"\n * import { monoCloudAuth } from \"@monocloud/auth-nextjs\";\n *\n * export default monoCloudAuth();\n *```\n *\n * @example Pages Router (Response)\n * ```tsx:src/pages/api/auth/[...monocloud].ts tab=\"Pages Router (Response)\" tab-group=\"monoCloudAuth\"\n * import { monoCloudAuth } from \"@monocloud/auth-nextjs\";\n * import { NextApiRequest, NextApiResponse } from \"next\";\n *\n * export default function handler(req: NextApiRequest, res: NextApiResponse) {\n *   const authHandler = monoCloudAuth();\n *\n *   res.setHeader(\"last_auth_requested\", `${Date.now()}`);\n *\n *   return authHandler(req, res);\n * }\n * ```\n *\n * @param options Optional configuration for the auth handler.\n * @returns Returns a Next.js-compatible handler for App Router route handlers or Pages Router API routes.\n *\n * @category Functions\n */\nexport function monoCloudAuth(\n  options?: MonoCloudAuthOptions\n): MonoCloudAuthHandler {\n  return getInstance().monoCloudAuth(options);\n}\n\n/**\n * Creates a Next.js authentication middleware that protects routes.\n *\n * By default, all routes matched by `config.matcher` are protected unless configured otherwise.\n *\n * @example Protect All Routes\n * ```tsx:src/proxy.ts tab=\"Protect All Routes\" tab-group=\"auth-middleware\"\n * import { authMiddleware } from \"@monocloud/auth-nextjs\";\n *\n * export default authMiddleware();\n *\n * export const config = {\n *   matcher: [\n *     \"/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)\",\n *   ],\n * };\n * ```\n *\n * @example Protect Selected Routes\n * ```tsx:src/proxy.ts tab=\"Protect Selected Routes\" tab-group=\"auth-middleware\"\n * import { authMiddleware } from \"@monocloud/auth-nextjs\";\n *\n * export default authMiddleware({\n *   protectedRoutes: [\"/api/admin\", \"^/api/protected(/.*)?$\"],\n * });\n *\n * export const config = {\n *   matcher: [\n *     \"/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)\",\n *   ],\n * };\n *```\n *\n * @example No Protected Routes\n * ```tsx:src/proxy.ts tab=\"No Protected Routes\" tab-group=\"auth-middleware\"\n * import { authMiddleware } from \"@monocloud/auth-nextjs\";\n *\n * export default authMiddleware({\n *   protectedRoutes: [],\n * });\n *\n * export const config = {\n *   matcher: [\n *     \"/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)\",\n *   ],\n * };\n * ```\n *\n * @example Dynamic\n * ```tsx:src/proxy.ts tab=\"Dynamic\" tab-group=\"auth-middleware\"\n * import { authMiddleware } from \"@monocloud/auth-nextjs\";\n *\n * export default authMiddleware({\n *   protectedRoutes: (req) => {\n *     return req.nextUrl.pathname.startsWith(\"/api/protected\");\n *   },\n * });\n *\n * export const config = {\n *   matcher: [\n *     \"/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)\",\n *   ],\n * };\n * ```\n *\n * @example Group Protection\n * ```tsx:src/proxy.ts tab=\"Group Protection\" tab-group=\"auth-middleware\"\n * import { authMiddleware } from \"@monocloud/auth-nextjs\";\n *\n * export default authMiddleware({\n *   protectedRoutes: [\n *     {\n *       groups: [\"admin\", \"editor\", \"537e7c3d-a442-4b5b-b308-30837aa045a4\"],\n *       routes: [\"/internal\", \"/api/internal(.*)\"],\n *     },\n *   ],\n * });\n *\n * export const config = {\n *   matcher: [\n *     \"/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)\",\n *   ],\n * };\n * ```\n *\n * @param options Optional configuration that controls how authentication is enforced (for example, redirect behavior, route matching, or custom handling of unauthenticated requests).\n * @returns Returns a Next.js middleware result, such as a `NextResponse`, `redirect`, or `undefined` to continue processing.\n *\n * @category Functions\n */\nexport function authMiddleware(\n  options?: MonoCloudMiddlewareOptions\n): NextMiddleware | NextProxy;\n\n/**\n * Executes the authentication middleware manually.\n *\n * Intended for advanced scenarios where the middleware is composed within custom logic.\n *\n * @example Composing with custom middleware\n *\n * ```tsx:src/proxy.ts title=\"Composing with custom middleware\"\n * import { authMiddleware } from \"@monocloud/auth-nextjs\";\n * import { NextFetchEvent, NextRequest, NextResponse } from \"next/server\";\n *\n * export default function customMiddleware(req: NextRequest, evt: NextFetchEvent) {\n *   if (req.nextUrl.pathname.startsWith(\"/api/protected\")) {\n *     return authMiddleware(req, evt);\n *   }\n *\n *   return NextResponse.next();\n * }\n *\n * export const config = {\n *   matcher: [\n *     \"/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)\",\n *   ],\n * };\n * ```\n *\n * @param request Incoming Next.js middleware request used to resolve authentication state.\n * @param event Next.js middleware event providing lifecycle hooks such as `waitUntil`.\n * @returns Returns a Next.js middleware result (`NextResponse`, redirect, or `undefined` to continue processing).\n *\n * @category Functions\n */\nexport function authMiddleware(\n  request: NextRequest,\n  event: NextFetchEvent\n): Promise<NextMiddlewareResult> | NextMiddlewareResult;\n\nexport function authMiddleware(\n  ...args: any[]\n):\n  | NextMiddleware\n  | NextProxy\n  | Promise<NextMiddlewareResult>\n  | NextMiddlewareResult {\n  return getInstance().authMiddleware(...args);\n}\n\n/**\n * Retrieves the current user's session using the active server request context.\n *\n * Intended for Server Components, Server Actions, Route Handlers, and Middleware where the request is implicitly available.\n *\n * @example Server Component\n * ```tsx:src/app/page.tsx tab=\"Server Component\" tab-group=\"session-ssr\"\n * import { getSession } from \"@monocloud/auth-nextjs\";\n *\n * export default async function Home() {\n *   const session = await getSession();\n *\n *   return <div>{session?.user.name}</div>;\n * }\n * ```\n *\n * @example Server Action\n * ```tsx:src/action.ts tab=\"Server Action\" tab-group=\"session-ssr\"\n * \"use server\";\n *\n * import { getSession } from \"@monocloud/auth-nextjs\";\n *\n * export async function getUserAction() {\n *   const session = await getSession();\n *\n *   return { name: session?.user.name };\n * }\n * ```\n *\n * @example API Handler\n * ```tsx:src/app/api/user/route.ts tab=\"API Handler\" tab-group=\"session-ssr\"\n * import { getSession } from \"@monocloud/auth-nextjs\";\n * import { NextResponse } from \"next/server\";\n *\n * export const GET = async () => {\n *   const session = await getSession();\n *\n *   return NextResponse.json({ name: session?.user.name });\n * };\n * ```\n *\n * @example Middleware\n * ```tsx:src/proxy.ts tab=\"Middleware\" tab-group=\"session-ssr\"\n * import { getSession } from \"@monocloud/auth-nextjs\";\n * import { NextResponse } from \"next/server\";\n *\n * export default async function proxy() {\n *   const session = await getSession();\n *\n *   if (!session) {\n *     return new NextResponse(\"User not signed in\", { status: 401 });\n *   }\n *\n *   return NextResponse.next();\n * }\n * ```\n * @param options Optional configuration to control session retrieval behavior.\n * @returns Returns the resolved session, or `undefined` if none exists.\n *\n * @category Functions\n */\nexport function getSession(\n  options?: GetSessionOptions\n): Promise<MonoCloudSession | undefined>;\n\n/**\n * Retrieves the current user's session using an explicit Web or Next.js request.\n *\n * Use this overload when you already have access to a `Request` or `NextRequest` (for example in Middleware or Route Handlers).\n *\n * @example Middleware (Request)\n * ```tsx:src/proxy.ts tab=\"Middleware (Request)\" tab-group=\"session-route-handler\"\n * import { getSession } from \"@monocloud/auth-nextjs\";\n * import { NextRequest, NextResponse } from \"next/server\";\n *\n * export default async function proxy(req: NextRequest) {\n *   const session = await getSession(req);\n *\n *   if (!session) {\n *     return new NextResponse(\"User not signed in\", { status: 401 });\n *   }\n *\n *   return NextResponse.next();\n * }\n * ```\n *\n * @example API Handler (Request)\n * ```tsx:src/app/api/user/route.ts tab=\"API Handler (Request)\" tab-group=\"session-route-handler\"\n * import { getSession } from \"@monocloud/auth-nextjs\";\n * import { NextRequest, NextResponse } from \"next/server\";\n *\n * export const GET = async (req: NextRequest) => {\n *   const session = await getSession(req);\n *\n *   return NextResponse.json({ name: session?.user.name });\n * };\n * ```\n *\n * @param req Incoming request used to read authentication cookies and headers to resolve the current user's session.\n * @param options Optional configuration to control session retrieval behavior.\n * @returns Returns the resolved session, or `undefined` if none exists.\n *\n * @category Functions\n */\nexport function getSession(\n  req: NextRequest | Request,\n  options?: GetSessionOptions\n): Promise<MonoCloudSession | undefined>;\n\n/**\n * Retrieves the current user's session using explicit request and response objects.\n *\n * Use this overload when you have already created a response and want refreshed authentication cookies or headers applied to it.\n *\n * @example Middleware (Response)\n * ```tsx:src/proxy.ts tab=\"Middleware (Response)\" tab-group=\"session-route-handler\"\n * import { getSession } from \"@monocloud/auth-nextjs\";\n * import { NextRequest, NextResponse } from \"next/server\";\n *\n * export default async function proxy(req: NextRequest) {\n *   const res = NextResponse.next();\n *\n *   const session = await getSession(req, res);\n *\n *   if (!session) {\n *     return new NextResponse(\"User not signed in\", { status: 401 });\n *   }\n *\n *   res.headers.set(\"x-auth-status\", \"active\");\n *\n *   return res;\n * }\n * ```\n *\n * @example API Handler (Response)\n * ```tsx:src/app/api/user/route.ts tab=\"API Handler (Response)\" tab-group=\"session-route-handler\"\n * import { getSession } from \"@monocloud/auth-nextjs\";\n * import { NextRequest, NextResponse } from \"next/server\";\n *\n * export const GET = async (req: NextRequest) => {\n *   const res = new NextResponse(\"YOUR CUSTOM RESPONSE\");\n *\n *   const session = await getSession(req, res);\n *\n *   if (session?.user) {\n *     res.cookies.set(\"something\", \"important\");\n *   }\n *\n *   return res;\n * };\n * ```\n *\n * @param req Incoming request used to read authentication cookies and headers to resolve the current user's session.\n * @param res Response object to update when session resolution requires refreshed authentication cookies or headers.\n * @param options Optional configuration to control session retrieval behavior.\n * @returns Returns the resolved session, or `undefined` if none exists.\n *\n * @category Functions\n */\nexport function getSession(\n  req: NextRequest | Request,\n  res: NextResponse | Response,\n  options?: GetSessionOptions\n): Promise<MonoCloudSession | undefined>;\n\n/**\n * Retrieves the current user's session in the Pages Router or Node.js runtime.\n *\n * Use this overload in API routes or `getServerSideProps`, where Node.js request and response objects are available.\n *\n * @example Pages Router (Pages)\n * ```tsx:src/pages/index.tsx tab=\"Pages Router (Pages)\" tab-group=\"session-pages\"\n * import { getSession, MonoCloudSession } from \"@monocloud/auth-nextjs\";\n * import { GetServerSideProps } from \"next\";\n *\n * type Props = {\n *   session?: MonoCloudSession;\n * };\n *\n * export default function Home({ session }: Props) {\n *   return <pre>Session: {JSON.stringify(session, null, 2)}</pre>;\n * }\n *\n * export const getServerSideProps: GetServerSideProps<Props> = async (ctx) => {\n *   const session = await getSession(ctx.req, ctx.res);\n *\n *   return {\n *     props: {\n *       session\n *     }\n *   };\n * };\n * ```\n * @example Pages Router (API)\n * ```tsx:src/pages/api/user.ts tab=\"Pages Router (API)\" tab-group=\"session-pages\"\n * import { getSession } from \"@monocloud/auth-nextjs\";\n * import { NextApiRequest, NextApiResponse } from \"next\";\n *\n * export default async function handler(\n *   req: NextApiRequest,\n *   res: NextApiResponse\n * ) {\n *   const session = await getSession(req, res);\n *\n *   res.status(200).json({ name: session?.user.name });\n * }\n * ```\n *\n * @param req Incoming Node.js request used to read authentication cookies and resolve the current user's session.\n * @param res Outgoing Node.js response used to apply refreshed authentication cookies when required.\n * @param options Optional configuration to control session retrieval behavior.\n * @returns Returns the resolved session, or `undefined` if none exists.\n *\n * @category Functions\n */\nexport function getSession(\n  req: NextApiRequest | IncomingMessage,\n  res: NextApiResponse | ServerResponse<IncomingMessage>,\n  options?: GetSessionOptions\n): Promise<MonoCloudSession | undefined>;\n\nexport function getSession(\n  ...args: any[]\n): Promise<MonoCloudSession | undefined> {\n  return (getInstance().getSession as any)(...args);\n}\n\n/**\n * Retrieves the current user's tokens using the active server request context.\n *\n * @example Server Component\n * ```tsx:src/app/page.tsx tab=\"Server Component\" tab-group=\"tokens-ssr\"\n * import { getTokens } from \"@monocloud/auth-nextjs\";\n *\n * export default async function Home() {\n *   const tokens = await getTokens();\n *\n *   return <div>Expired: {tokens.isExpired.toString()}</div>;\n * }\n * ```\n *\n * @example Server Action\n * ```tsx:src/action.ts tab=\"Server Action\" tab-group=\"tokens-ssr\"\n * \"use server\";\n *\n * import { getTokens } from \"@monocloud/auth-nextjs\";\n *\n * export async function getExpiredAction() {\n *   const tokens = await getTokens();\n *\n *   return { expired: tokens.isExpired };\n * }\n * ```\n *\n * @example API Handler\n * ```tsx:src/app/api/tokens/route.ts tab=\"API Handler\" tab-group=\"tokens-ssr\"\n * import { getTokens } from \"@monocloud/auth-nextjs\";\n * import { NextResponse } from \"next/server\";\n *\n * export const GET = async () => {\n *   const tokens = await getTokens();\n *\n *   return NextResponse.json({ expired: tokens.isExpired });\n * };\n * ```\n *\n * @example Middleware\n * ```tsx:src/proxy.ts tab=\"Middleware\" tab-group=\"tokens-ssr\"\n * import { getTokens } from \"@monocloud/auth-nextjs\";\n * import { NextResponse } from \"next/server\";\n *\n * export default async function proxy() {\n *   const tokens = await getTokens();\n *\n *   if (tokens.isExpired) {\n *     return new NextResponse(\"Tokens expired\", { status: 401 });\n *   }\n *\n *   return NextResponse.next();\n * }\n * ```\n *\n * @example Refresh the default token\n *\n * The **default token** is the access token associated with your default authorization parameters:\n * - Scopes: `MONOCLOUD_AUTH_SCOPES` or `options.defaultAuthParams.scopes`\n * - Resource: `MONOCLOUD_AUTH_RESOURCE` or `options.defaultAuthParams.resource`\n *\n * Calling `getTokens()` returns the current token set and **refreshes the default token automatically when needed** (for example, if it has expired). To force a refresh even when it isn’t expired, use `forceRefresh: true`.\n *\n * ```tsx:src/app/page.tsx title=\"Refresh default token\"\n * import { getTokens } from \"@monocloud/auth-nextjs\";\n * import { NextResponse } from \"next/server\";\n *\n * export const GET = async () => {\n *   // Forces a refresh of the default token\n *   const tokens = await getTokens({ forceRefresh: true });\n *\n *   return NextResponse.json({ accessToken: tokens?.accessToken });\n * };\n * ```\n *\n * @example Request an access token for resource(s)\n *\n * Use `resource` and `scopes` to request an access token for one or more resources.\n *\n * > The requested resource and scopes must be included in the initial authorization flow (so the user has consented / the session is eligible to mint that token).\n *\n * ```tsx:src/app/page.tsx title=\"Request a new access token for resource(s)\"\n * import { getTokens } from \"@monocloud/auth-nextjs\";\n * import { NextResponse } from \"next/server\";\n *\n * export const GET = async () => {\n *   const tokens = await getTokens({\n *     resource: \"https://first.example.com https://second.example.com\",\n *     scopes: \"read:first read:second shared\",\n *   });\n *\n *   return NextResponse.json({ accessToken: tokens?.accessToken });\n * };\n * ```\n *\n * @param options Optional configuration controlling refresh behavior and resource/scope selection.\n * @returns The current user's tokens, refreshed if necessary.\n * @throws {@link MonoCloudValidationError} If no valid session exists.\n *\n * @category Functions\n */\nexport function getTokens(options?: GetTokensOptions): Promise<MonoCloudTokens>;\n\n/**\n * Retrieves the current user's tokens using an explicit Web or Next.js request.\n *\n * Use this overload when you already have access to a `Request` or `NextRequest` (for example, in Middleware or Route Handlers).\n *\n * @example Middleware (Request)\n * ```tsx:src/proxy.ts tab=\"Middleware (Request)\" tab-group=\"tokens-route-handler-request\"\n * import { getTokens } from \"@monocloud/auth-nextjs\";\n * import { NextRequest, NextResponse } from \"next/server\";\n *\n * export default async function proxy(req: NextRequest) {\n *   const tokens = await getTokens(req);\n *\n *   if (tokens.isExpired) {\n *     return new NextResponse(\"Tokens expired\", { status: 401 });\n *   }\n *\n *   return NextResponse.next();\n * }\n * ```\n *\n * @example API Handler (Request)\n * ```tsx:src/app/api/tokens/route.ts tab=\"API Handler (Request)\" tab-group=\"tokens-route-handler-request\"\n * import { getTokens } from \"@monocloud/auth-nextjs\";\n * import { NextRequest, NextResponse } from \"next/server\";\n *\n * export const GET = async (req: NextRequest) => {\n *   const tokens = await getTokens(req);\n *\n *   return NextResponse.json({ expired: tokens?.isExpired });\n * };\n * ```\n *\n * @param req Incoming request used to resolve authentication from cookies and headers.\n * @param options Optional configuration controlling refresh behavior and resource/scope selection.\n * @returns The current user's tokens, refreshed if necessary.\n * @throws {@link MonoCloudValidationError} If no valid session exists.\n *\n * @category Functions\n */\nexport function getTokens(\n  req: NextRequest | Request,\n  options?: GetTokensOptions\n): Promise<MonoCloudTokens>;\n\n/**\n * Retrieves the current user's tokens using an explicit request and response.\n *\n * Use this overload when you have already created a response and want refreshed authentication cookies or headers applied to it.\n *\n * @example Middleware (Response)\n *```tsx:src/proxy.ts tab=\"Middleware (Response)\" tab-group=\"tokens-route-handler-response\"\n * import { getTokens } from \"@monocloud/auth-nextjs\";\n * import { NextRequest, NextResponse } from \"next/server\";\n *\n * export default async function proxy(req: NextRequest) {\n *   const res = NextResponse.next();\n *\n *   const tokens = await getTokens(req, res);\n *\n *   res.headers.set(\"x-tokens-expired\", tokens.isExpired.toString());\n *\n *   return res;\n * }\n * ```\n *\n * @example API Handler (Response)\n * ```tsx:src/app/api/tokens/route.ts tab=\"API Handler (Response)\" tab-group=\"tokens-route-handler-response\"\n * import { getTokens } from \"@monocloud/auth-nextjs\";\n * import { NextRequest, NextResponse } from \"next/server\";\n *\n * export const GET = async (req: NextRequest) => {\n *   const res = new NextResponse(\"Custom Body\");\n *\n *   const tokens = await getTokens(req, res);\n *\n *   if (!tokens.isExpired) {\n *     res.headers.set(\"x-auth-status\", \"active\");\n *   }\n *\n *   return res;\n * };\n * ```\n *\n * @param req Incoming request used to resolve authentication from cookies and headers.\n * @param res Existing response to update with refreshed authentication cookies or headers.\n * @param options Optional configuration controlling refresh behavior and resource/scope selection.\n * @returns The current user's tokens, refreshed if necessary.\n * @throws {@link MonoCloudValidationError} If no valid session exists.\n *\n * @category Functions\n */\nexport function getTokens(\n  req: NextRequest | Request,\n  res: NextResponse | Response,\n  options?: GetTokensOptions\n): Promise<MonoCloudTokens>;\n\n/**\n * Retrieves the current user's tokens in the Pages Router or Node.js runtime.\n *\n * Use this overload in API routes or `getServerSideProps`, where Node.js request and response objects are available.\n *\n * @example Pages Router (Pages)\n * ```tsx:src/pages/index.tsx tab=\"Pages Router (Pages)\" tab-group=\"tokens-pages\"\n * import { getTokens, MonoCloudTokens } from \"@monocloud/auth-nextjs\";\n * import { GetServerSideProps } from \"next\";\n *\n * type Props = {\n *   tokens: MonoCloudTokens;\n * };\n *\n * export default function Home({ tokens }: Props) {\n *   return <pre>Tokens: {JSON.stringify(tokens, null, 2)}</pre>;\n * }\n *\n * export const getServerSideProps: GetServerSideProps<Props> = async (ctx) => {\n *   const tokens = await getTokens(ctx.req, ctx.res);\n *\n *   return {\n *     props: {\n *       tokens: tokens\n *     }\n *   };\n * };\n * ```\n *\n * @example Pages Router (API)\n * ```tsx:src/pages/api/tokens.ts tab=\"Pages Router (API)\" tab-group=\"tokens-pages\"\n * import { getTokens } from \"@monocloud/auth-nextjs\";\n * import { NextApiRequest, NextApiResponse } from \"next\";\n *\n * export default async function handler(\n *   req: NextApiRequest,\n *   res: NextApiResponse\n * ) {\n *   const tokens = await getTokens(req, res);\n *\n *   res.status(200).json({ accessToken: tokens?.accessToken });\n * }\n * ```\n *\n * @param req Incoming Node.js request used to resolve authentication from cookies.\n * @param res Outgoing Node.js response used to apply refreshed authentication cookies when required.\n * @param options Optional configuration controlling refresh behavior and resource/scope selection.\n * @returns The current user's tokens, refreshed if necessary.\n * @throws {@link MonoCloudValidationError} If no valid session exists.\n *\n * @category Functions\n */\nexport function getTokens(\n  req: NextApiRequest | IncomingMessage,\n  res: NextApiResponse | ServerResponse<IncomingMessage>,\n  options?: GetTokensOptions\n): Promise<MonoCloudTokens>;\n\nexport function getTokens(...args: any[]): Promise<MonoCloudTokens> {\n  return getInstance().getTokens(...args);\n}\n\n/**\n * Checks whether the current user is authenticated using the active server request context.\n *\n * Intended for Server Components, Server Actions, Route Handlers, and Middleware where the request is implicitly available.\n *\n * @example Server Component\n * ```tsx:src/app/page.tsx tab=\"Server Component\" tab-group=\"is-authenticated-ssr\"\n * import { isAuthenticated } from \"@monocloud/auth-nextjs\";\n *\n * export default async function Home() {\n *   const authenticated = await isAuthenticated();\n *\n *   return <div>Authenticated: {authenticated.toString()}</div>;\n * }\n * ```\n *\n * @example Server Action\n * ```tsx:src/action.ts tab=\"Server Action\" tab-group=\"is-authenticated-ssr\"\n * \"use server\";\n *\n * import { isAuthenticated } from \"@monocloud/auth-nextjs\";\n *\n * export async function checkAuthAction() {\n *   const authenticated = await isAuthenticated();\n *\n *   return { authenticated };\n * }\n * ```\n *\n * @example API Handler\n * ```tsx:src/app/api/authenticated/route.ts tab=\"API Handler\" tab-group=\"is-authenticated-ssr\"\n * import { isAuthenticated } from \"@monocloud/auth-nextjs\";\n * import { NextResponse } from \"next/server\";\n *\n * export const GET = async () => {\n *   const authenticated = await isAuthenticated();\n *\n *   return NextResponse.json({ authenticated });\n * };\n * ```\n *\n * @example Middleware\n * ```tsx:src/proxy.ts tab=\"Middleware\" tab-group=\"is-authenticated-ssr\"\n * import { isAuthenticated } from \"@monocloud/auth-nextjs\";\n * import { NextResponse } from \"next/server\";\n *\n * export default async function proxy() {\n *   const authenticated = await isAuthenticated();\n *\n *   if (!authenticated) {\n *     return new NextResponse(\"User not signed in\", { status: 401 });\n *   }\n *\n *   return NextResponse.next();\n * }\n * ```\n *\n * @returns Returns `true` if a valid session exists; otherwise `false`.\n *\n * @category Functions\n */\nexport function isAuthenticated(): Promise<boolean>;\n\n/**\n * Checks whether the current user is authenticated using an explicit Web or Next.js request.\n *\n * Use this overload when you already have access to a `Request` or `NextRequest` (for example, in Middleware or Route Handlers).\n *\n * @example Middleware (Request)\n * ```tsx:src/proxy.ts tab=\"Middleware (Request)\" tab-group=\"is-authenticated-route-handler\"\n * import { isAuthenticated } from \"@monocloud/auth-nextjs\";\n * import { NextRequest, NextResponse } from \"next/server\";\n *\n * export default async function proxy(req: NextRequest) {\n *   const authenticated = await isAuthenticated(req);\n *\n *   if (!authenticated) {\n *     return new NextResponse(\"User not signed in\", { status: 401 });\n *   }\n *\n *   return NextResponse.next();\n * }\n * ```\n *\n * @example Middleware (Response)\n * ```tsx:src/proxy.ts tab=\"Middleware (Response)\" tab-group=\"is-authenticated-route-handler\"\n * import { isAuthenticated } from \"@monocloud/auth-nextjs\";\n * import { NextRequest, NextResponse } from \"next/server\";\n *\n * export default async function proxy(req: NextRequest) {\n *   const res = NextResponse.next();\n *\n *   const authenticated = await isAuthenticated(req, res);\n *\n *   if (!authenticated) {\n *     return new NextResponse(\"User not signed in\", { status: 401 });\n *   }\n *\n *   res.headers.set(\"x-authenticated\", \"true\");\n *\n *   return res;\n * }\n * ```\n *\n * @example API Handler (Request)\n * ```tsx:src/app/api/authenticated/route.ts tab=\"API Handler (Request)\" tab-group=\"is-authenticated-route-handler\"\n * import { isAuthenticated } from \"@monocloud/auth-nextjs\";\n * import { NextRequest, NextResponse } from \"next/server\";\n *\n * export const GET = async (req: NextRequest) => {\n *   const authenticated = await isAuthenticated(req);\n *\n *   return NextResponse.json({ authenticated });\n * };\n * ```\n *\n * @example API Handler (Response)\n * ```tsx:src/app/api/authenticated/route.ts tab=\"API Handler (Response)\" tab-group=\"is-authenticated-route-handler\"\n * import { isAuthenticated } from \"@monocloud/auth-nextjs\";\n * import { NextRequest, NextResponse } from \"next/server\";\n *\n * export const GET = async (req: NextRequest) => {\n *   const res = new NextResponse(\"YOUR CUSTOM RESPONSE\");\n *\n *   const authenticated = await isAuthenticated(req, res);\n *\n *   if (authenticated) {\n *     res.cookies.set(\"something\", \"important\");\n *   }\n *\n *   return res;\n * };\n * ```\n *\n * @param req Incoming request used to resolve authentication from cookies and headers.\n * @param res Optional response to update if refreshed authentication cookies or headers are required.\n * @returns Returns `true` if a valid session exists; otherwise `false`.\n *\n * @category Functions\n */\nexport function isAuthenticated(\n  req: NextRequest | Request,\n  res?: NextResponse | Response\n): Promise<boolean>;\n\n/**\n * Checks whether the current user is authenticated in the Pages Router or Node.js runtime.\n *\n * Use this overload in API routes or `getServerSideProps`, where Node.js request and response objects are available.\n *\n * @example Pages Router (Pages)\n * ```tsx:src/pages/index.tsx tab=\"Pages Router (Pages)\" tab-group=\"is-authenticated-pages\"\n * import { isAuthenticated } from \"@monocloud/auth-nextjs\";\n * import { GetServerSideProps } from \"next\";\n *\n * type Props = {\n *   authenticated: boolean;\n * };\n *\n * export default function Home({ authenticated }: Props) {\n *   return <pre>User is {authenticated ? \"logged in\" : \"guest\"}</pre>;\n * }\n *\n * export const getServerSideProps: GetServerSideProps<Props> = async (ctx) => {\n *   const authenticated = await isAuthenticated(ctx.req, ctx.res);\n *\n *   return {\n *     props: {\n *       authenticated\n *     }\n *   };\n * };\n * ```\n *\n * @example Pages Router (API)\n * ```tsx:src/pages/api/authenticated.ts tab=\"Pages Router (API)\" tab-group=\"is-authenticated-pages\"\n * import { isAuthenticated } from \"@monocloud/auth-nextjs\";\n * import { NextApiRequest, NextApiResponse } from \"next\";\n *\n * export default async function handler(\n *   req: NextApiRequest,\n *   res: NextApiResponse\n * ) {\n *   const authenticated = await isAuthenticated(req, res);\n *\n *   res.status(200).json({ authenticated });\n * }\n * ```\n *\n * @param req Incoming Node.js request used to resolve authentication from cookies.\n * @param res Outgoing Node.js response used to apply refreshed authentication cookies when required.\n * @returns Returns `true` if a valid session exists; otherwise `false`.\n *\n * @category Functions\n */\nexport function isAuthenticated(\n  req: NextApiRequest | IncomingMessage,\n  res: NextApiResponse | ServerResponse<IncomingMessage>\n): Promise<boolean>;\n\nexport function isAuthenticated(...args: any[]): Promise<boolean> {\n  return (getInstance().isAuthenticated as any)(...args);\n}\n\n/**\n * Ensures the current user is authenticated. If not, redirects to the sign-in flow.\n *\n * > **App Router only.** Intended for Server Components, Route Handlers, and Server Actions.\n *\n * @example Server Component\n * ```tsx:src/app/page.tsx tab=\"Server Component\" tab-group=\"protect\"\n * import { protect } from \"@monocloud/auth-nextjs\";\n *\n * export default async function Home() {\n *   await protect();\n *\n *   return <>You are signed in.</>;\n * }\n * ```\n *\n * @example Server Action\n * ```tsx:src/action.ts tab=\"Server Action\" tab-group=\"protect\"\n * \"use server\";\n *\n * import { protect } from \"@monocloud/auth-nextjs\";\n *\n * export async function getMessage() {\n *   await protect();\n *\n *   return { secret: \"sssshhhhh!!!\" };\n * }\n * ```\n *\n * @example API Handler\n * ```tsx:src/app/api/protected/route.ts tab=\"API Handler\" tab-group=\"protect\"\n * import { protect } from \"@monocloud/auth-nextjs\";\n * import { NextResponse } from \"next/server\";\n *\n * export const GET = async () => {\n *   await protect();\n *\n *   return NextResponse.json({ secret: \"ssshhhh!!!\" });\n * };\n * ```\n *\n * @param options Optional configuration for redirect behavior (for example, return URL or sign-in parameters).\n * @returns Resolves if the user is authenticated; otherwise triggers a redirect.\n *\n * @category Functions\n */\nexport function protect(options?: ProtectOptions): Promise<void> {\n  return getInstance().protect(options);\n}\n\n/**\n * Wraps an App Router API route handler and ensures that only authenticated (and optionally authorized) requests can access the route.\n *\n * Intended for Next.js App Router Route Handlers.\n *\n * @example\n * ```tsx:src/app/api/protected/route.ts\n * import { protectApi } from \"@monocloud/auth-nextjs\";\n * import { NextResponse } from \"next/server\";\n *\n * export const GET = protectApi(async () => {\n *   return NextResponse.json({\n *     message: \"You accessed a protected endpoint\",\n *   });\n * });\n * ```\n *\n * @param handler The route handler to protect.\n * @param options Optional configuration controlling authentication and authorization behavior.\n * @returns Returns a wrapped handler that enforces authentication (and optional authorization) before invoking the original handler.\n *\n * @category Functions\n */\nexport function protectApi(\n  handler: AppRouterApiHandlerFn,\n  options?: ProtectApiAppOptions\n): AppRouterApiHandlerFn;\n\n/**\n * Wraps a Pages Router API route handler and ensures that only authenticated (and optionally authorized) requests can access the route.\n *\n * Intended for Next.js Pages Router API routes.\n *\n * @example\n * ```tsx:src/pages/api/protected.ts\n * import { protectApi } from \"@monocloud/auth-nextjs\";\n * import { NextApiRequest, NextApiResponse } from \"next\";\n *\n * export default protectApi(\n *   async (req: NextApiRequest, res: NextApiResponse) => {\n *     return res.json({\n *       message: \"You accessed a protected endpoint\",\n *     });\n *   }\n * );\n * ```\n *\n * @param handler - The route handler to protect.\n * @param options Optional configuration controlling authentication and authorization behavior.\n * @returns Returns a wrapped handler that enforces authentication (and optional authorization) before invoking the original handler.\n *\n * @category Functions\n */\nexport function protectApi(\n  handler: NextApiHandler,\n  options?: ProtectApiPageOptions\n): NextApiHandler;\n\nexport function protectApi(\n  handler: AppRouterApiHandlerFn | NextApiHandler,\n  options?: ProtectApiAppOptions | ProtectApiPageOptions\n): AppRouterApiHandlerFn | NextApiHandler {\n  return (getInstance().protectApi as any)(handler, options);\n}\n\n/**\n * Restricts access to App Router server-rendered pages.\n *\n * **Access control**\n * - If the user is not authenticated, `onAccessDenied` is invoked (or default behavior applies).\n * - If the user is authenticated but fails group checks, `onGroupAccessDenied` is invoked (or the default \"Access Denied\" view is rendered).\n *\n * Both behaviors can be customized via options.\n *\n * @example Basic Usage\n * ```tsx:src/app/page.tsx tab=\"Basic Usage\" tab-group=\"protectPage-app\"\n * import { protectPage } from \"@monocloud/auth-nextjs\";\n *\n * export default protectPage(async function Home({ user }) {\n *  return <>Hi {user.email}. You accessed a protected page.</>;\n * });\n * ```\n *\n * @example With Options\n * ```tsx:src/app/page.tsx tab=\"With Options\" tab-group=\"protectPage-app\"\n * import { protectPage } from \"@monocloud/auth-nextjs\";\n *\n * export default protectPage(\n *   async function Home({ user }) {\n *     return <>Hi {user.email}. You accessed a protected page.</>;\n *   },\n *   {\n *     returnUrl: \"/dashboard\",\n *     groups: [\"admin\"],\n *   }\n * );\n * ```\n *\n * @param component The App Router server component to protect.\n * @param options Optional configuration for authentication, authorization, and custom access handling (`onAccessDenied`, `onGroupAccessDenied`).\n * @returns A wrapped page component that enforces authentication before rendering.\n *\n * @category Functions\n */\nexport function protectPage(\n  component: ProtectedAppServerComponent,\n  options?: ProtectAppPageOptions\n): AppRouterPageHandler;\n\n/**\n * Restricts access to Pages Router server-rendered pages using `getServerSideProps`.\n *\n * **Access control**\n * - If the user is not authenticated, `onAccessDenied` is invoked (or default behavior applies).\n * - If the user is authenticated but fails group checks, the page can still render and `groupAccessDenied` is provided in props. Use `onGroupAccessDenied` to customize the props or behavior.\n *\n * Both behaviors can be customized via options.\n *\n * @example Basic Usage\n * ```tsx:src/pages/index.tsx tab=\"Basic Usage\" tab-group=\"protectPage-page\"\n * import { protectPage, MonoCloudUser } from \"@monocloud/auth-nextjs\";\n *\n * type Props = {\n *   user: MonoCloudUser;\n * };\n *\n * export default function Home({ user }: Props) {\n *   return <>Hi {user.email}. You accessed a protected page.</>;\n * }\n *\n * export const getServerSideProps = protectPage();\n * ```\n *\n * @example With Options\n * ```tsx:src/pages/index.tsx tab=\"With Options\" tab-group=\"protectPage-page\"\n * import { protectPage, MonoCloudUser } from \"@monocloud/auth-nextjs\";\n * import { GetServerSidePropsContext } from \"next\";\n *\n * type Props = {\n *   user: MonoCloudUser;\n *   url: string;\n * };\n *\n * export default function Home({ user, url }: Props) {\n *   console.log(url);\n *   return <div>Hi {user?.email}. You accessed a protected page.</div>;\n * }\n *\n * export const getServerSideProps = protectPage({\n *   returnUrl: \"/dashboard\",\n *   groups: [\"admin\"],\n *   getServerSideProps: async (context: GetServerSidePropsContext) => ({\n *     props: { url: context.resolvedUrl }\n *   })\n * });\n * ```\n *\n * @param options Optional configuration for authentication, authorization, and custom access handling (`onAccessDenied`, `onGroupAccessDenied`).\n * @typeParam P - Props returned from `getServerSideProps`.\n * @typeParam Q - Query parameters parsed from the URL.\n * @returns A getServerSideProps wrapper that enforces authentication before executing the page logic.\n *\n * @category Functions\n */\nexport function protectPage<\n  P extends Record<string, any> = Record<string, any>,\n  Q extends ParsedUrlQuery = ParsedUrlQuery,\n>(options?: ProtectPagePageOptions<P, Q>): ProtectPagePageReturnType<P, Q>;\n\nexport function protectPage(...args: any[]): any {\n  return getInstance().protectPage(...args);\n}\n\n/**\n * Checks whether the currently authenticated user is a member of **any** of the specified groups.\n *\n * The `groups` parameter accepts group identifiers (IDs or names).\n *\n * The authenticated user's session may contain groups represented as:\n * - Group IDs\n * - Group names\n * - `Group` objects (for example, `{ id: string; name: string }`)\n *\n * Matching is always performed against the group's **ID** and **name**, regardless of how the group is represented in the session.\n *\n * @example Server Component\n * ```tsx:src/app/page.tsx tab=\"Server Component\" tab-group=\"is-user-in-group-rsc\"\n * import { isUserInGroup } from \"@monocloud/auth-nextjs\";\n *\n * export default async function AdminPanel() {\n *   const isAdmin = await isUserInGroup([\"admin\"]);\n *\n *   if (!isAdmin) {\n *     return <div>Access Denied</div>;\n *   }\n *\n *   return <div>Admin Control Panel</div>;\n * }\n * ```\n *\n * @example Server Action\n * ```tsx:src/action.ts tab=\"Server Action\" tab-group=\"is-user-in-group-rsc\"\n * \"use server\";\n *\n * import { isUserInGroup } from \"@monocloud/auth-nextjs\";\n *\n * export async function deletePostAction() {\n *   const canDelete = await isUserInGroup([\"admin\", \"editor\"]);\n *\n *   if (!canDelete) {\n *     return { success: false };\n *   }\n *\n *   return { success: true };\n * }\n * ```\n *\n * @example API Handler\n * ```tsx:src/app/api/group-check/route.ts tab=\"API Handler\" tab-group=\"is-user-in-group-rsc\"\n * import { isUserInGroup } from \"@monocloud/auth-nextjs\";\n * import { NextResponse } from \"next/server\";\n *\n * export const GET = async () => {\n *   const allowed = await isUserInGroup([\"admin\", \"editor\"]);\n *\n *   if (!allowed) {\n *     return new NextResponse(\"Forbidden\", { status: 403 });\n *   }\n *\n *   return NextResponse.json({ status: \"success\" });\n * };\n * ```\n *\n * @example Middleware\n * ```tsx:src/proxy.ts tab=\"Middleware\" tab-group=\"is-user-in-group-rsc\"\n * import { isUserInGroup } from \"@monocloud/auth-nextjs\";\n * import { NextResponse } from \"next/server\";\n *\n * export default async function proxy() {\n *   const isAdmin = await isUserInGroup([\"admin\"]);\n *\n *   if (!isAdmin) {\n *     return new NextResponse(\"User is not admin\", { status: 403 });\n *   }\n *\n *   return NextResponse.next();\n * }\n * ```\n *\n * @param groups Group IDs or names to check against the user's group memberships.\n * @param options Optional configuration controlling how group membership is evaluated.\n * @returns Returns `true` if the user belongs to at least one specified group; otherwise `false`.\n *\n * @category Functions\n */\nexport function isUserInGroup(\n  groups: string[],\n  options?: IsUserInGroupOptions\n): Promise<boolean>;\n\n/**\n * Checks group membership using an explicit Web or Next.js request.\n *\n * Use this overload when you already have access to a `Request` or `NextRequest` (for example, in Middleware or Route Handlers).\n *\n * @example Middleware (Request)\n * ```tsx:src/proxy.ts tab=\"Middleware (Request)\" tab-group=\"is-user-in-group-request\"\n * import { isUserInGroup } from \"@monocloud/auth-nextjs\";\n * import { NextRequest, NextResponse } from \"next/server\";\n *\n * export default async function proxy(req: NextRequest) {\n *   const isAdmin = await isUserInGroup(req, [\"admin\"]);\n *\n *   if (!isAdmin) {\n *     return new NextResponse(\"User is not admin\", { status: 403 });\n *   }\n *\n *   return NextResponse.next();\n * }\n * ```\n *\n * @example API Handler (Request)\n * ```tsx:src/app/api/group-check/route.ts tab=\"API Handler (Request)\" tab-group=\"is-user-in-group-request\"\n * import { isUserInGroup } from \"@monocloud/auth-nextjs\";\n * import { NextRequest, NextResponse } from \"next/server\";\n *\n * export const GET = async (req: NextRequest) => {\n *   const isMember = await isUserInGroup(req, [\"admin\", \"editor\"]);\n *\n *   return NextResponse.json({ isMember });\n * };\n * ```\n *\n * @param req Incoming request used to resolve authentication from cookies and headers.\n * @param groups Group IDs or names to check against the user's group memberships.\n * @param options Optional configuration controlling how group membership is evaluated.\n * @returns Returns `true` if the user belongs to at least one specified group; otherwise `false`.\n *\n * @category Functions\n */\nexport function isUserInGroup(\n  req: NextRequest | Request,\n  groups: string[],\n  options?: IsUserInGroupOptions\n): Promise<boolean>;\n\n/**\n * Checks group membership using an explicit request and response.\n *\n * Use this overload when you have already created a response and want refreshed authentication cookies or headers applied to it.\n *\n * @example Middleware (Response)\n * ```tsx:src/proxy.ts tab=\"Middleware (Response)\" tab-group=\"is-user-in-group-response\"\n * import { isUserInGroup } from \"@monocloud/auth-nextjs\";\n * import { NextRequest, NextResponse } from \"next/server\";\n *\n * export default async function proxy(req: NextRequest) {\n *   const res = NextResponse.next();\n *\n *   const isAdmin = await isUserInGroup(req, res, [\"admin\"]);\n *\n *   if (!isAdmin) {\n *     return new NextResponse(\"User is not admin\", { status: 403 });\n *   }\n *\n *   res.headers.set(\"x-user\", \"admin\");\n *\n *   return res;\n * }\n * ```\n *\n * @example API Handler (Response)\n * ```tsx:src/app/api/group-check/route.ts tab=\"API Handler (Response)\" tab-group=\"is-user-in-group-response\"\n * import { isUserInGroup } from \"@monocloud/auth-nextjs\";\n * import { NextRequest, NextResponse } from \"next/server\";\n *\n * export const GET = async (req: NextRequest) => {\n *   const res = new NextResponse(\"Restricted Content\");\n *\n *   const allowed = await isUserInGroup(req, res, [\"admin\"]);\n *\n *   if (!allowed) {\n *     return new NextResponse(\"Not Allowed\", res);\n *   }\n *\n *   return res;\n * };\n * ```\n *\n * @param req Incoming request used to resolve authentication from cookies and headers.\n * @param res Existing response to update with refreshed authentication cookies or headers when required.\n * @param groups Group IDs or names to check against the user's group memberships.\n * @param options Optional configuration controlling how group membership is evaluated.\n * @returns Returns `true` if the user belongs to at least one specified group; otherwise `false`.\n *\n * @category Functions\n */\nexport function isUserInGroup(\n  req: NextRequest | Request,\n  res: NextResponse | Response,\n  groups: string[],\n  options?: IsUserInGroupOptions\n): Promise<boolean>;\n\n/**\n * Checks group membership in the Pages Router or Node.js runtime.\n *\n * Use this overload in API routes or `getServerSideProps`, where Node.js request and response objects are available.\n *\n * @example Pages Router (Pages)\n * ```tsx:src/pages/index.tsx tab=\"Pages Router (Pages)\" tab-group=\"is-user-in-group-pages\"\n * import { isUserInGroup } from \"@monocloud/auth-nextjs\";\n * import { GetServerSideProps } from \"next\";\n *\n * type Props = {\n *   isAdmin: boolean;\n * };\n *\n * export default function Home({ isAdmin }: Props) {\n *   return <div>User is admin: {isAdmin.toString()}</div>;\n * }\n *\n * export const getServerSideProps: GetServerSideProps<Props> = async (ctx) => {\n *   const isAdmin = await isUserInGroup(ctx.req, ctx.res, [\"admin\"]);\n *\n *   return {\n *     props: {\n *       isAdmin\n *     }\n *   };\n * };\n * ```\n *\n * @example Pages Router (API)\n * ```tsx:src/pages/api/group-check.ts tab=\"Pages Router (API)\" tab-group=\"is-user-in-group-pages\"\n * import { isUserInGroup } from \"@monocloud/auth-nextjs\";\n * import { NextApiRequest, NextApiResponse } from \"next\";\n *\n * export default async function handler(\n *   req: NextApiRequest,\n *   res: NextApiResponse\n * ) {\n *   const isAdmin = await isUserInGroup(req, res, [\"admin\"]);\n *\n *   if (!isAdmin) {\n *     return res.status(403).json({ error: \"Forbidden\" });\n *   }\n *\n *   res.status(200).json({ message: \"Welcome Admin\" });\n * }\n * ```\n *\n * @param req Incoming Node.js request used to resolve authentication from cookies.\n * @param res Outgoing Node.js response used to apply refreshed authentication cookies when required.\n * @param groups Group IDs or names to check against the user's group memberships.\n * @param options Optional configuration controlling how group membership is evaluated.\n * @returns Returns `true` if the user belongs to at least one specified group; otherwise `false`.\n *\n * @category Functions\n */\nexport function isUserInGroup(\n  req: NextApiRequest | IncomingMessage,\n  res: NextApiResponse | ServerResponse<IncomingMessage>,\n  groups: string[],\n  options?: IsUserInGroupOptions\n): Promise<boolean>;\n\nexport function isUserInGroup(...args: any[]): Promise<boolean> {\n  return (getInstance().isUserInGroup as any)(...args);\n}\n\n/**\n * Redirects the user to the sign-in flow.\n *\n * > **App Router only**. Intended for use in Server Components, Route Handlers, and Server Actions.\n *\n * This helper performs a server-side redirect to the configured sign-in route. Execution does not continue after the redirect is triggered.\n *\n * @example Server Component\n * ```tsx:src/app/page.tsx tab=\"Server Component\" tab-group=\"redirect-to-sign-in\"\n * import { isUserInGroup, redirectToSignIn } from \"@monocloud/auth-nextjs\";\n *\n * export default async function Home() {\n *   const allowed = await isUserInGroup([\"admin\"]);\n *\n *   if (!allowed) {\n *     await redirectToSignIn({ returnUrl: \"/home\" });\n *   }\n *\n *   return <>You are signed in.</>;\n * }\n * ```\n *\n * @example Server Action\n * ```tsx:src/action.ts tab=\"Server Action\" tab-group=\"redirect-to-sign-in\"\n * \"use server\";\n *\n * import { getSession, redirectToSignIn } from \"@monocloud/auth-nextjs\";\n *\n * export async function protectedAction() {\n *   const session = await getSession();\n *\n *   if (!session) {\n *     await redirectToSignIn();\n *   }\n *\n *   return { data: \"Sensitive Data\" };\n * }\n * ```\n *\n * @example API Handler\n * ```tsx:src/app/api/protected/route.ts tab=\"API Handler\" tab-group=\"redirect-to-sign-in\"\n * import { getSession, redirectToSignIn } from \"@monocloud/auth-nextjs\";\n * import { NextResponse } from \"next/server\";\n *\n * export const GET = async () => {\n *   const session = await getSession();\n *\n *   if (!session) {\n *     await redirectToSignIn({\n *       returnUrl: \"/dashboard\",\n *     });\n *   }\n *\n *   return NextResponse.json({ data: \"Protected content\" });\n * };\n * ```\n *\n * @param options Optional configuration for the redirect, such as `returnUrl` or additional sign-in parameters.\n * @returns Never resolves. Triggers a redirect to the sign-in flow.\n *\n * @category Functions\n */\nexport function redirectToSignIn(\n  options?: RedirectToSignInOptions\n): Promise<void> {\n  return getInstance().redirectToSignIn(options);\n}\n\n/**\n * Redirects the user to the sign-out flow.\n *\n * > **App Router only**. Intended for use in Server Components, Route Handlers, and Server Actions.\n *\n * This helper performs a server-side redirect to the configured sign-out route. Execution does not continue after the redirect is triggered.\n *\n * @example Server Component\n * ```tsx:src/app/page.tsx tab=\"Server Component\" tab-group=\"redirect-to-sign-out\"\n * import { getSession, redirectToSignOut } from \"@monocloud/auth-nextjs\";\n *\n * export default async function Page() {\n *   const session = await getSession();\n *\n *   // Example: Force sign-out if a specific condition is met (e.g., account suspended)\n *   if (session?.user.isSuspended) {\n *     await redirectToSignOut();\n *   }\n *\n *   return <>Welcome User</>;\n * }\n * ```\n *\n * @example Server Action\n * ```tsx:src/action.ts tab=\"Server Action\" tab-group=\"redirect-to-sign-out\"\n * \"use server\";\n *\n * import { getSession, redirectToSignOut } from \"@monocloud/auth-nextjs\";\n *\n * export async function signOutAction() {\n *   const session = await getSession();\n *\n *   if (session) {\n *     await redirectToSignOut();\n *   }\n * }\n * ```\n *\n * @example API Handler\n * ```tsx:src/app/api/signout/route.ts tab=\"API Handler\" tab-group=\"redirect-to-sign-out\"\n * import { getSession, redirectToSignOut } from \"@monocloud/auth-nextjs\";\n * import { NextResponse } from \"next/server\";\n *\n * export const GET = async () => {\n *   const session = await getSession();\n *\n *   if (session) {\n *     await redirectToSignOut({\n *       postLogoutRedirectUri: \"/goodbye\",\n *     });\n *   }\n *\n *   return NextResponse.json({ status: \"already_signed_out\" });\n * };\n * ```\n *\n * @param options Optional configuration for the redirect, such as `postLogoutRedirectUri` or additional sign-out parameters.\n * @returns Never resolves. Triggers a redirect to the sign-out flow.\n *\n * @category Functions\n */\nexport function redirectToSignOut(\n  options?: RedirectToSignOutOptions\n): Promise<void> {\n  return getInstance().redirectToSignOut(options);\n}\n"],"mappings":";;;AAoCA,IAAI;;;;;AAMJ,MAAM,oBAAyC;AAC7C,cAAa,IAAIA,mDAAqB;AACtC,QAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2DT,SAAgB,cACd,SACsB;AACtB,QAAO,aAAa,CAAC,cAAc,QAAQ;;AAsI7C,SAAgB,eACd,GAAG,MAKoB;AACvB,QAAO,aAAa,CAAC,eAAe,GAAG,KAAK;;AAgO9C,SAAgB,WACd,GAAG,MACoC;AACvC,QAAQ,aAAa,CAAC,WAAmB,GAAG,KAAK;;AAsQnD,SAAgB,UAAU,GAAG,MAAuC;AAClE,QAAO,aAAa,CAAC,UAAU,GAAG,KAAK;;AA2MzC,SAAgB,gBAAgB,GAAG,MAA+B;AAChE,QAAQ,aAAa,CAAC,gBAAwB,GAAG,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiDxD,SAAgB,QAAQ,SAAyC;AAC/D,QAAO,aAAa,CAAC,QAAQ,QAAQ;;AA6DvC,SAAgB,WACd,SACA,SACwC;AACxC,QAAQ,aAAa,CAAC,WAAmB,SAAS,QAAQ;;AA2G5D,SAAgB,YAAY,GAAG,MAAkB;AAC/C,QAAO,aAAa,CAAC,YAAY,GAAG,KAAK;;AAiQ3C,SAAgB,cAAc,GAAG,MAA+B;AAC9D,QAAQ,aAAa,CAAC,cAAsB,GAAG,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiEtD,SAAgB,iBACd,SACe;AACf,QAAO,aAAa,CAAC,iBAAiB,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgEhD,SAAgB,kBACd,SACe;AACf,QAAO,aAAa,CAAC,kBAAkB,QAAQ"}