Upgrade @auth0/nextjs-auth0 from v3 to v4 in the identity webapp

[kenoir]

What does this change?

Upgrades @auth0/nextjs-auth0 from 3.5.0 to 4.22.0 in identity/webapp.

v4 is a ground-up rewrite of the SDK. The biggest structural change is that the auth routes (login, logout and the OAuth callback) are now served by Next.js middleware rather than a catch-all API route. The client is configured with new Auth0Client(...) in utils/auth0.ts, reading from process.env because the middleware bundle cannot use next/config.

The upgrade is deliberately conservative, and nothing outside the identity webapp changes:

• The auth routes keep their existing public URLs (/account/api/auth/*), so links in the common and content webapps, and the callback/logout URLs registered with the Auth0 tenant, are untouched.
• A beforeSessionSaved hook keeps every ID-token claim on the session. By default v4 strips non-standard claims, which would have dropped the namespaced patron_barcode and patron_role claims that sign-in state across the site relies on.
• A custom onCallback reproduces v3's redirect behaviour: errors land on /account/error, and returnTo paths pointing outside the identity app (for example signing in from a works page) are not prefixed with /account as the v4 default would have done.
• /account/api/auth/me is now our own handler, preserving the contract that UserContextProvider depends on: a 204 when signed out (v4's profile route returns a 401) and the ?refetch option for re-syncing the profile, which v4 removed.
• Signup redirects to the login route with screen_hint=signup, which v4 forwards to the authorization endpoint.
• Logout requests with a relative returnTo are absolutised in the middleware to match v3, since v4 forwards them verbatim to Auth0.
• A single transaction cookie is used (enableParallelTransactions: false), as in v3. The v4 default sets one cookie per login attempt, and abandoned attempts accumulated until requests exceeded proxy header size limits.
• In development the auth base URL is inferred from each request, so the app works on localhost, through the www-dev nginx proxy and via the content webapp rewrite. Production keeps the configured SITE_BASE_URL.

The PR also adds a manual BDD regression script covering all the identity user flows: playwright/user-stories/identity.md.

How to test

Unit tests pass (yarn test:identity, 112 tests), along with typecheck, eslint and next build.

All flows have been manually tested locally through the www-dev nginx proxy: signing in and out from the content app header, the account page, signup, the full registration flow, email validation, changing email (including the UserContext refetch), and item requests.

After the stage deployment, and again after the production deployment, run the manual regression script linked above. It covers signup and registration, signing in and out, email verification, account management, item requesting and restricted access. It is environment aware: each environment's base URL is listed, and email lands in Mailtrap on stage but in real inboxes in production. The registration flow particularly needs the stage run, because the local test had to detour via the stage registration form (the stage Auth0 Action always redirects to www-stage).

Note that both stage and production work against production Sierra, so a registration test creates a real patron record. Always finish the script with its account deletion feature so the cleanup request is raised with the library team.

Have we considered potential risks?

• Everyone is signed out once on deploy. v4's session cookie encryption is incompatible with v3, so existing sessions become unreadable and users will need to sign in again.
• Session secret rotation behaves differently. v4 supports a single secret, so only the first SESSION_KEYS entry is used, and rotating it now signs everyone out (sessions last at most 7 days).
• No Auth0 tenant or infrastructure changes are required. All public URLs and environment variable names are unchanged, and NEXT_PUBLIC_BASE_PATH is set by next.config.js.

Generated with Claude Code

[Copilot]

Pull request overview

This PR upgrades @auth0/nextjs-auth0 in identity/webapp from v3 to v4, moving Auth0 route handling to Next.js middleware while preserving the existing public /account/api/auth/* URLs and the session/profile behaviours relied on across the Wellcome Collection webapps.

Changes:

• Upgrade to @auth0/nextjs-auth0@^4.22.0 and introduce middleware-based auth route handling (login/logout/callback).
• Rewrite identity/webapp/utils/auth0.ts around new Auth0Client(...), reading configuration directly from process.env for edge compatibility.
• Reintroduce the v3 /account/api/auth/me contract (204 when signed out + ?refetch) via a custom API route and add dedicated unit tests.

Reviewed changes

Copilot reviewed 14 out of 15 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
yarn.lock	Updates dependency lockfile for @auth0/nextjs-auth0 v4 and transitive deps.
identity/webapp/package.json	Bumps @auth0/nextjs-auth0 dependency to v4.
identity/webapp/utils/auth0.ts	Replaces initAuth0() with Auth0Client config suitable for middleware/edge bundling; custom callback handling and session settings.
identity/webapp/middleware.ts	Adds Auth0 middleware integration and logout returnTo absolutisation.
identity/webapp/pages/api/auth/me.ts	Implements a v3-compatible /api/auth/me endpoint (204 + ?refetch).
identity/webapp/test/api-auth-me.test.ts	Adds unit tests for the new /api/auth/me behaviour.
identity/webapp/pages/api/auth/signup.ts	Changes signup to redirect to login with screen_hint=signup.
identity/webapp/pages/api/users/[[...users]].ts	Updates imports and token extraction for Auth0 v4 API surface.
identity/webapp/pages/index.tsx	Adjusts SSR session lookup for v4 getSession usage and email nullability.
identity/webapp/pages/validated.tsx	Removes redundant getSession call after forced token refresh.
identity/webapp/views/pages/index.tsx	Updates Auth0 user typing to v4 types.
identity/webapp/next.config.js	Ensures NEXT_PUBLIC_BASE_PATH is set for SDK URL construction under basePath.
identity/webapp/config.js	Removes Auth0/session config that can’t be read from next/config in middleware/edge.
identity/webapp/test/registration.test.ts	Updates next/config mock to match the reduced runtime config shape.
identity/webapp/pages/api/auth/[...auth0].ts	Removes the v3 catch-all API route handler (replaced by middleware).

[gestchild]

I went through the manual test script and most things worked as described, save the following:

Scenario 1.4

"Then I am signed out and land on the application-received page showing the email address I signed up with"

I remained signed in and was taken back to the work I clicked the sign in link from (i.e. the behaviour described in 2.3). The weird thing was it showed my initials as 'AA' at the top of the page.

When I clicked on the my account link then it did log me out and land me on the application-received page.

Scenario 2.1. and 2.2

"...the header shows my name instead of Sign in"

"... the menu shows my name"

In 2.1 I see my initials and 'library account' and 'sign out' links in the dropdown
In 2.2 I see 'library account' and 'sign out' links at the bottom of the menu (no name)

I think these behaviours are correct though

Scenario 3.2: unverified email banner (which I've suggested)

Given my email address is not verified
When I view my account page
Then I see a banner asking me to verify my email
And when I choose "Send a new verification email" I see a confirmation message and a new email arrives in the test inbox

I got a "something went wrong message" and no email was sent (this was after I changed my email to get the banner to appear again)

[kenoir]

Following up on the "Send a new verification email" failure (Scenario 3.2) from the manual test pass: I investigated and confirmed it's a pre-existing bug, not introduced by this v4 upgrade.

It reproduces identically on main (v3 SDK 3.8.0) and on this branch: the empty-body POST /account/api/users/me/send-verification-email is serialised to invalid JSON by the shared FetchClient and rejected by the Identity API with a 500, which the client collapses into the generic "something went wrong". The FetchClient (commit 8e96225) is already on main, and this PR doesn't touch the hook, api-client.ts, fetch-helpers.ts, or the proxy's body-forwarding.

Raised separately as #13185 — out of scope for this PR.

[kenoir]

@gestchild thanks for the thorough test pass. The missing account options turned out to be a real v4 bug, and a couple of the others are behaviour/wording clarifications. Here's what was going on.

The broken header (and a lot of the odd registration behaviour in 1.4) came down to our namespaced patron claims (patron_barcode / patron_role) going missing from the session.

Those claims get added to the ID token by the add_custom_claims Auth0 Action, but only when the matching weco: scope is in event.transaction.requested_scopes. That's present on an interactive login, but not on a refresh-token grant, so a refreshed ID token comes back without them. The v4 SDK rebuilds session.user from whatever ID token it last saw, so the first token refresh (the /api/users proxy when you change your email, or just an expiry-driven refresh) overwrites session.user with a claim-less token. Once that happens isFullAuth0Profile fails, UserContextProvider (which every webapp uses) drops into its failed state, and the signed-in header and library card number disappear until the next login. v3 didn't hit this because it kept the login claims and never re-derived them on refresh.

I could reproduce it locally: a fresh login has the claims, a forced refresh drops them, and after an email change the session stayed broken, which matches what you saw.

The fix (babd514) keeps the claims in beforeSessionSaved, the one hook that runs on every session save. It stashes them when a login provides them and restores them onto session.user when a refresh has dropped them. After the fix, a forced refresh and an email change both keep the claims, and the header and card number stay put. Unit tests added.

On the initials in the header (2.1/2.2): that's intended, the header shows initials rather than the full name, so I've tweaked the scenario wording to match (44023a9).

I think the header bug is fixed, but it's worth confirming on stage rather than locally. The full registration flow can't run locally (the post-signup Action redirects to www-stage), and stage exercises the claims fix against the real Action and the real registration and email journeys, including 1.4. Want to deploy this branch to stage and try running through the script again?

[gestchild]

this looks good to go, we'll plan at FE catch up when it will be best to merge and test