feat: add support for withApiAuthRequired helper (#2230)

Author: guabu

EXAMPLES.md

@@ -95,9 +95,9 @@ By default, the SDK uses OpenID Connect's RP-Initiated Logout when available, fa
 
 ```ts
 export const auth0 = new Auth0Client({
-  logoutStrategy: "auto", // default behavior
+  logoutStrategy: "auto" // default behavior
   // ... other config
-})
+});
 ```
 
 Available strategies:
@@ -118,9 +118,9 @@ The `"v2"` strategy is useful for applications that:
 ```ts
 // Example: Using v2 logout for wildcard URL support
 export const auth0 = new Auth0Client({
-  logoutStrategy: "v2",
+  logoutStrategy: "v2"
   // ... other config
-})
+});
 
 // This allows logout URLs like:
 // /auth/logout?returnTo=https://localhost:3000/en/dashboard
@@ -300,6 +300,79 @@ export default withPageAuthRequired(function Page({ user }) {
 });
 ```
 
+## Protect an API Route
+
+### Page Router
+
+Requests to `/api/protected` without a valid session cookie will fail with `401`.
+
+```js
+// pages/api/protected.js
+import { auth0 } from "@/lib/auth0";
+
+export default auth0.withApiAuthRequired(async function myApiRoute(req, res) {
+  const { user } = await auth0.getSession(req);
+  res.json({ protected: "My Secret", id: user.sub });
+});
+```
+
+Then you can access your API from the frontend with a valid session cookie.
+
+```jsx
+// pages/products
+import { withPageAuthRequired } from "@auth0/nextjs-auth0/client";
+import useSWR from "swr";
+
+const fetcher = async (uri) => {
+  const response = await fetch(uri);
+  return response.json();
+};
+
+export default withPageAuthRequired(function Products() {
+  const { data, error } = useSWR("/api/protected", fetcher);
+  if (error) return <div>oops... {error.message}</div>;
+  if (data === undefined) return <div>Loading...</div>;
+  return <div>{data.protected}</div>;
+});
+```
+
+### App Router
+
+Requests to `/api/protected` without a valid session cookie will fail with `401`.
+
+```js
+// app/api/protected/route.js
+import { auth0 } from "@/lib/auth0";
+
+export const GET = auth0.withApiAuthRequired(async function myApiRoute(req) {
+  const res = new NextResponse();
+  const { user } = await auth0.getSession(req);
+  return NextResponse.json({ protected: "My Secret", id: user.sub }, res);
+});
+```
+
+Then you can access your API from the frontend with a valid session cookie.
+
+```jsx
+// app/products/page.jsx
+"use client";
+
+import { withPageAuthRequired } from "@auth0/nextjs-auth0/client";
+import useSWR from "swr";
+
+const fetcher = async (uri) => {
+  const response = await fetch(uri);
+  return response.json();
+};
+
+export default withPageAuthRequired(function Products() {
+  const { data, error } = useSWR("/api/protected", fetcher);
+  if (error) return <div>oops... {error.message}</div>;
+  if (data === undefined) return <div>Loading...</div>;
+  return <div>{data.protected}</div>;
+});
+```
+
 ## Accessing the idToken
 
 `idToken` can be accessed from the session in the following way:

src/server/client.ts

@@ -1,7 +1,7 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { cookies } from "next/headers.js";
 import { NextRequest, NextResponse } from "next/server.js";
-import { NextApiRequest, NextApiResponse } from "next/types.js";
+import { NextApiHandler, NextApiRequest, NextApiResponse } from "next/types.js";
 
 import {
   AccessTokenError,
@@ -18,6 +18,7 @@ import {
   StartInteractiveLoginOptions,
   User
 } from "../types/index.js";
+import { isRequest } from "../utils/request.js";
 import {
   AuthClient,
   BeforeSessionSavedHook,
@@ -26,6 +27,7 @@ import {
   RoutesOptions
 } from "./auth-client.js";
 import { RequestCookies, ResponseCookies } from "./cookies.js";
+import * as withApiAuthRequired from "./helpers/with-api-auth-required.js";
 import {
   appRouteHandlerFactory,
   AppRouterPageRoute,
@@ -741,6 +743,36 @@ export class Auth0Client {
     return pageRouteHandler(fnOrOpts);
   }
 
+  withApiAuthRequired(
+    apiRoute: withApiAuthRequired.AppRouteHandlerFn | NextApiHandler
+  ) {
+    const pageRouteHandler = withApiAuthRequired.pageRouteHandlerFactory(this);
+    const appRouteHandler = withApiAuthRequired.appRouteHandlerFactory(this);
+
+    return (
+      req: NextRequest | NextApiRequest,
+      resOrParams:
+        | withApiAuthRequired.AppRouteHandlerFnContext
+        | NextApiResponse
+    ) => {
+      if (isRequest(req)) {
+        return appRouteHandler(
+          apiRoute as withApiAuthRequired.AppRouteHandlerFn
+        )(
+          req as NextRequest,
+          resOrParams as withApiAuthRequired.AppRouteHandlerFnContext
+        );
+      }
+
+      return (
+        pageRouteHandler as withApiAuthRequired.WithApiAuthRequiredPageRoute
+      )(apiRoute as NextApiHandler)(
+        req as NextApiRequest,
+        resOrParams as NextApiResponse
+      );
+    };
+  }
+
   private async saveToSession(
     data: SessionData,
     req?: PagesRouterRequest | NextRequest,