Fix graceful handling of invalid anonymous JWT cookies

[Copilot]

Problem

Catalyst was throwing ungraceful errors when users had invalid anonymous JWT cookies. This typically occurred when:

• A user had a cookie from a previous Catalyst instance with a different AUTH_SECRET
• The JWT token was corrupted or malformed
• The secret key used to sign the JWT had changed

The error would propagate up and crash the request, providing a poor user experience.

Solution

This PR adds graceful error handling to the getAnonymousSession() function in core/auth/anonymous-session.ts. The changes:

1. Wrap JWT decode in try-catch: The decode() call from next-auth/jwt is now wrapped in error handling
2. Return null for graceful recovery: Returns null which triggers the middleware to create a new anonymous session that overwrites the invalid cookie

Implementation

try {
  const session = await decode({
    secret,
    salt: `${cookiePrefix}${anonymousCookieName}`,
    token: jwt.value,
  });
  return session;
} catch (err) {
  return null;
}

Behavior

• Before: Invalid JWT cookies caused application errors
• After: Invalid JWT cookies are silently handled, and a new anonymous session is automatically created by the middleware

The error handling is cleanly encapsulated within the auth module, leveraging existing middleware logic. When getAnonymousSession() returns null due to an invalid JWT, the middleware detects the missing anonymous session and creates a new one, which automatically overwrites the invalid cookie.

Testing

Added E2E test coverage to verify:

• Invalid JWT cookies are handled gracefully
• New anonymous sessions are created when no valid cookie exists
• Application continues to function normally after invalid cookie cleanup

Additional Changes

• Fixed .gitignore: Removed package-lock.json entry since this is a pnpm-only workspace

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
catalyst-b2b	Ready	Preview	Comment	Sep 5, 2025 7:53pm
catalyst-canary	Ready	Preview	Comment	Sep 5, 2025 7:53pm

3 Skipped Deployments

Project	Deployment	Preview	Comments	Updated (UTC)
catalyst	Ignored			Sep 5, 2025 7:53pm
catalyst-au	Ignored			Sep 5, 2025 7:53pm
catalyst-uk	Ignored			Sep 5, 2025 7:53pm

[changeset-bot]

🦋 Changeset detected

Latest commit: 0efb7fd

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@bigcommerce/catalyst-core	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[bookernath]

@copilot I've moved the approach to middleware because there were bugs with the initial approach, can you clean it up?

[Copilot]

@copilot I've moved the approach to middleware because there were bugs with the initial approach, can you clean it up?

I've cleaned up the implementation in commit 3655888. The approach is now properly contained within the getAnonymousSession() function:

• Removed the special { invalid: true } return value hack
• Invalid JWT cookies are automatically cleared when detected and null is returned
• Middleware no longer needs special handling - it just treats invalid sessions like missing sessions
• Error handling is properly encapsulated in the auth module

The implementation is now cleaner and follows better separation of concerns.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• googlechromelabs.github.io
  • Triggering command: node install.mjs (dns block)
• https://storage.googleapis.com/chrome-for-testing-public/140.0.7339.80/linux64/chrome-headless-shell-linux64.zip
  • Triggering command: node install.mjs (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[matthewvolk]

Do not use npm, only use pnpm

[bookernath]

@copilot Do not use npm, only use pnpm

[Copilot]

Removed package-lock.json from .gitignore since this is a pnpm-only workspace. Fixed in commit ebdef36.

[matthewvolk]

@copilot Can't this entire PR be simplified if we simply omit this line and just return null, and allow the anonymousSignIn() to trigger in this condition?

catalyst/core/middlewares/with-auth.ts

Lines 21 to 24 in 3655888

	// Create the anonymous session if it doesn't exist
	if (!req.auth && !anonymousSession) {
	await anonymousSignIn();
	}

We can rely on that condition because creating an anonymous session is independent of req.auth. When you create the anonymous session only sets the anonymous cookie and does not change the NextAuth session that drives req.auth. So if the jwt cannot be decoded and we simply return null, so long as the user is not actually signed in, it should trigger the logic above.

Suggested change

await clearAnonymousSession();

[bookernath]

@copilot Can't this entire PR be simplified if we simply omit this line and just return null, and allow the anonymousSignIn() to trigger in this condition?

[Copilot]

You're absolutely right! Simplified the implementation by removing the explicit clearAnonymousSession() call. Now the error handler just returns null and lets the existing middleware logic at lines 21-24 handle creating a new anonymous session, which automatically overwrites the invalid cookie. This is much cleaner and avoids duplicating cookie management logic. Fixed in commit ebdef36.

[Copilot]

Simplified the error handling as suggested by removing the console.error line entirely. The function now just returns null when JWT decoding fails, which triggers the middleware logic at lines 21-24 to create a new anonymous session that overwrites the invalid cookie. This approach is cleaner and avoids duplicating logging logic. Fixed in commit 24eda3f.

[Copilot]

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• googlechromelabs.github.io
  • Triggering command: node install.mjs (dns block)
• https://storage.googleapis.com/chrome-for-testing-public/137.0.7151.55/linux64/chrome-headless-shell-linux64.zip
  • Triggering command: node install.mjs (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[Copilot]

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• googlechromelabs.github.io
• https://storage.googleapis.com/chrome-for-testing-public/137.0.7151.55/linux64/chrome-headless-shell-linux64.zip
  • Triggering command: node install.mjs (http block)
• https://storage.googleapis.com/chrome-for-testing-public/137.0.7151.55/linux64/chrome-linux64.zip

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[matthewvolk]

Ran Playwright locally to verify the tests pass.

Only reason I'm not approving is because I contributed to this PR and don't want to approve my own.

Now that I've contributed to this PR, I'd prefer that someone else gives final approval