feat(auth0-server-js): add revokeRefreshToken and logout revocation support

[jd3vi1]

Summary

• Adds ServerClient.revokeRefreshToken() — reads the refresh token from the session and delegates to AuthClient.revokeToken(), wrapping errors in TokenRevocationError
• logout() now always attempts revocation best-effort before clearing the session; revocation failure never blocks logout
• In resolver mode, both revocation and session deletion are gated by a domain-match guard (session domain must match resolved domain)
• Re-exports TokenRevocationError from the server-js public surface
• Adds /auth/revoke route to the Express example app
• Documents revocation behavior in EXAMPLES.md

Depends on

Requires #221 to be merged and released first.

Test plan

• revokeRefreshToken — success, missing session, missing refresh token, wraps error as TokenRevocationError
• logout (static mode) — revokes then deletes session; revocation failure does not block logout
• logout (resolver mode) — revokes and deletes when domains match; skips both when domains differ

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds ServerClient.revokeRefreshToken(), integrates best-effort revocation into logout, re-exports TokenRevocationError, and updates tests, documentation, and the Express example.

Changes

Refresh token revocation

Layer / File(s)	Summary
Revocation API and implementation packages/auth0-server-js/src/types.ts, packages/auth0-server-js/src/server-client.ts, packages/auth0-server-js/src/index.ts	Adds revocation options, session or explicit token handling, resolver-mode domain checks, and the TokenRevocationError export.
Logout integration and validation packages/auth0-server-js/src/server-client.ts, packages/auth0-server-js/src/server-client.spec.ts	Revokes tokens before session deletion, continues after failures, and tests static and resolver-mode behavior.
Examples and documentation examples/example-express-web/..., packages/auth0-server-js/EXAMPLES.md	Adds the Express revoke form and route and documents session, explicit-token, and logout revocation.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant ExpressApp
  participant ServerClient
  participant Auth0
  User->>ExpressApp: Submit POST /auth/revoke
  ExpressApp->>ServerClient: revokeRefreshToken()
  ServerClient->>Auth0: Revoke refresh token
  Auth0-->>ServerClient: Success or TokenRevocationError
  ServerClient-->>ExpressApp: Complete request
  ExpressApp-->>User: Redirect to /private

Loading

Possibly related PRs

• auth0/auth0-auth-js#214: Implements the same refresh-token revocation, logout integration, and related tests, documentation, and examples.
• auth0/auth0-auth-js#216: Reverts the same revocation and logout integration changes.
• auth0/auth0-auth-js#223: Adds the underlying revocation support used by this server-client integration.

Suggested reviewers: piyush-85

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly captures the main change: adding refresh-token revocation and logout revocation support in auth0-server-js.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/token-revocation-server-js

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 6

🧹 Nitpick comments (1)

packages/auth0-server-js/src/server-client.spec.ts (1)

7022-7059: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Actually assert that revocation precedes deletion.

The test only checks that both operations occurred, so it would pass if their order were reversed. Record both callbacks and assert ['revoke', 'delete'].

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/auth0-server-js/src/server-client.spec.ts` around lines 7022 - 7059,
Update the “should revoke refresh token before clearing session on logout” test
to record the operation order in both the revocation callback configured by
setupRevocation and mockStateStore.delete. Assert the recorded sequence is
['revoke', 'delete'] instead of only checking that each operation occurred,
while preserving the existing logout setup and expectations.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@examples/example-express-web/src/auth0.ts`:
- Around line 87-90: Update the Auth0 authorizationParams configuration used by
the example’s login flow to include offline_access in the existing scope
alongside openid, profile, and email, so the /auth/revoke handler has a refresh
token available.

In `@packages/auth0-server-js/src/index.ts`:
- Line 5: Remove TokenRevocationError from the re-export in the package
entrypoint until `@auth0/auth0-auth-js` provides the revocation API. Keep
TokenExchangeError, MissingClientAuthError, and OrganizationValidationError
re-exported unchanged.

In `@packages/auth0-server-js/src/server-client.ts`:
- Around line 1136-1141: Update the logout revocation error handling around
revokeRefreshToken to detect and suppress the expected MissingSessionError
caused by absent refresh tokens, while continuing to console.warn for all other
revocation failures. Apply the same handling to the additional logout path noted
in the comment, preserving successful best-effort logout behavior.
- Around line 1082-1085: Update the JSDoc for the token-revocation method near
the explicit token parameter to state that explicit tokens bypass session lookup
only in static mode; in resolver mode, session state is consulted and revocation
may be skipped on a domain mismatch. Also update the corresponding example in
packages/auth0-server-js/EXAMPLES.md at lines 1501-1505 to document the same
resolver-mode lookup and mismatch behavior.
- Around line 1113-1120: Update the resolver-mode branch around
`#getSessionDomain` so that when stateData exists, its session domain must be
present and match resolvedDomain; return without revoking when the domain is
missing, uninferable, or different. Preserve the current resolved-domain
behavior only when no stateData is provided, and add a regression test covering
a session without domain or an inferable issuer.
- Around line 1094-1109: Update the refresh-token handling around options.token
and the fallback in the revocation flow to distinguish an omitted token from an
explicitly blank token. Reject an explicitly empty token before reading or using
stateData.refreshToken, while preserving the existing session-token fallback
only when token was not supplied.

---

Nitpick comments:
In `@packages/auth0-server-js/src/server-client.spec.ts`:
- Around line 7022-7059: Update the “should revoke refresh token before clearing
session on logout” test to record the operation order in both the revocation
callback configured by setupRevocation and mockStateStore.delete. Assert the
recorded sequence is ['revoke', 'delete'] instead of only checking that each
operation occurred, while preserving the existing logout setup and expectations.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 96a1fd7b-1f08-4b72-b874-fb3fdb93f1c8

📥 Commits

Reviewing files that changed from the base of the PR and between 21e9777 and a6cda83.

📒 Files selected for processing (7)

• examples/example-express-web/src/auth0.ts
• examples/example-express-web/views/private.ejs
• packages/auth0-server-js/EXAMPLES.md
• packages/auth0-server-js/src/index.ts
• packages/auth0-server-js/src/server-client.spec.ts
• packages/auth0-server-js/src/server-client.ts
• packages/auth0-server-js/src/types.ts

[tusharpandey13]

PTAL