fix(shared): handle banned/deactivated 403 as unauthenticated

[jacekradko]

#8004 narrowed ClerkJS token/session sign-out from any 4xx to isUnauthenticatedError, but that helper only matched 401 and 422. Terminal 403s (user_banned, user_deactivated) stopped triggering sign-out.

This adds those two codes into the predicate. Generic 403 and 429 stay out of the sign-out path on purpose.

return status === 401 || status === 422 || (status === 403 && hasTerminalUserErrorCode);

Cross-checked against clerk_go: apierror.UserBanned() / UserDeactivated() return http.StatusForbidden with codes user_banned / user_deactivated, serialized as { errors: [{ code, ... }] }, and are emitted on the session-token / handshake path in api/shared/sessions/service.go. So the predicate matches the API contract 1:1.

Test additions cover both directions: terminal codes return true, other 403 codes (e.g. not_allowed_access) still return false.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	May 27, 2026 12:58am

[changeset-bot]

🦋 Changeset detected

Latest commit: ceacf3b

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

This PR includes changesets to release 20 packages

Name	Type
@clerk/clerk-js	Patch
@clerk/shared	Patch
@clerk/chrome-extension	Patch
@clerk/expo	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/expo-passkeys	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/hono	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/react	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/ui	Patch
@clerk/vue	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

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR refines unauthenticated error detection by updating the isUnauthenticatedError helper to treat HTTP 403 responses as unauthenticated when they contain terminal user-state error codes (user_banned or user_deactivated). The implementation introduces an internal set of these codes, updates the function logic to check 403 responses against this set, adds test cases covering both true and false scenarios, and documents the change in the changeset for @clerk/clerk-js and @clerk/shared patch releases.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description clearly relates to the changeset, explaining the problem (terminal 403s not triggering sign-out), the solution (adding terminal user error codes to the unauthenticated predicate), and providing implementation details and test coverage.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and specifically describes the main change: updating the unauthenticated error handler to treat HTTP 403 responses with terminal user status codes (banned/deactivated) as unauthenticated, which aligns with the core fix implemented in the changeset.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@8649

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@8649

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@8649

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@8649

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@8649

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@8649

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@8649

@clerk/express

npm i https://pkg.pr.new/@clerk/express@8649

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@8649

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@8649

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@8649

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@8649

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@8649

@clerk/react

npm i https://pkg.pr.new/@clerk/react@8649

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@8649

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@8649

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@8649

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@8649

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@8649

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@8649

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@8649

commit: ceacf3b