feat: add withPageAuthRequired for protecting pages client side

[guabu]

📋 Changes

Adds the withPageAuthRequired HoC to protect pages, client side.

withPageAuthRequired for SSR and APIs will follow in subsequent PRs.

📎 References

• v4 - replacements for with_____Required methods? #1790

🎯 Testing

1. Create a page, wrapped with withPageAuthRequired (see sample below)
2. Attempt to access that page without a session
3. Notice you will be redirected to the login page

"use client";

import Link from "next/link";
import { withPageAuthRequired } from "@auth0/nextjs-auth0";

export default withPageAuthRequired(function Page({ user }) {
  return (
    <div>
      <div>Hello, {user.name}!</div>
      <Link href="/">Home</Link>
    </div>
  );
});

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 83.96%. Comparing base (65d682c) to head (ff2ebfa).
Report is 3 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2193      +/-   ##
==========================================
+ Coverage   82.91%   83.96%   +1.05%     
==========================================
  Files          21       22       +1     
  Lines        2095     2133      +38     
  Branches      372      386      +14     
==========================================
+ Hits         1737     1791      +54     
+ Misses        351      336      -15     
+ Partials        7        6       -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[tusharpandey13]

Can we add docs in README.md and EXAMPLES.md too?

[guabu]

@tusharpandey13 The EXAMPLES.md already contains the newly added section, see: Protecting a Client-Side Rendered (CSR) Page. As well as a callout in the Custom routes section when specifying a custom login route.

Is there anything in particular that you see missing we should include?

[tusharpandey13]

my bad, missed the diff for EXAMPLES.md, this look good 👍

[frederikprijck]

What's the reason not to use this?

const currentLocation = window.location.toString();
returnToPath = currentLocation.replace(new URL(currentLocation).origin, '') || '/';

[guabu]

window.location contains the complete URL path which also includes the base path — this means we would end up with /dashboard/dashboard/profile if the base path was configured as /dashboard and had a returnTo of /dashboard/profile.

We would have to handle this manually, if a base path is configured, which was the first approach I went with: #2193 (comment)

Ultimately, I decided it's cleaner to let Next.js handle this via usePathname since it does not include the base path which avoids having to manually handle the removal of the base path.