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

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

Adds ServerClient.revokeRefreshToken() which reads the refresh token
from the session and delegates to AuthClient.revokeToken(). Logout now
always attempts revocation best-effort before clearing the session. In
resolver mode, both revocation and session deletion are gated by a
domain-match guard. Exports TokenRevocationError from the public surface.

* fix(auth0-server-js): add domain-match guard to revokeRefreshToken in resolver mode

* fix(auth0-server-js): remove console.warn from logout catch blocks, strengthen revoke test assertion

* fix(auth0-server-js): treat session with no stored domain as mismatch in resolver mode

* fix(auth0-server-js): address review comments - bump auth-js dep, empty token guard, docs

- Bump @auth0/auth0-auth-js dependency from ^1.11.0 to ^1.12.0
- Add explicit empty-string token guard in revokeRefreshToken (throws MissingRequiredArgumentError)
- Add offline_access scope to example-express-web authorizationParams
- Expand JSDoc and EXAMPLES.md to document resolver-mode behavior for explicit tokens
- Assert revoke-before-delete ordering in logout test using ops array

Author: jd3vi1

examples/example-express-web/src/auth0.ts

@@ -32,6 +32,7 @@ export function auth0(options: Auth0ExpressOptions) {
     clientSecret: options.clientSecret,
     authorizationParams: {
       redirect_uri: redirectUri.toString(),
+      scope: 'openid profile email offline_access',
     },
     transactionStore: new CookieTransactionStore(
       {
@@ -84,5 +85,10 @@ export function auth0(options: Auth0ExpressOptions) {
     response.redirect(logoutUrl.href);
   });
 
+  router.post('/auth/revoke', async (request: Request, response: Response) => {
+    await request.auth0Client.revokeRefreshToken({}, { request, response });
+    response.redirect('/private');
+  });
+
   return router;
 }

examples/example-express-web/views/private.ejs

@@ -1 +1,5 @@
-This is a private page.
+This is a private page.
+
+<form method="POST" action="/auth/revoke" class="mt-3">
+  <button type="submit" class="btn btn-warning">Revoke Refresh Token</button>
+</form>

packages/auth0-server-js/EXAMPLES.md

@@ -58,6 +58,10 @@
   - [Passing `StoreOptions`](#passing-storeoptions-9)
 - [Retrieving an Access Token for a Connection](#retrieving-an-access-token-for-a-connection)
   - [Passing `StoreOptions`](#passing-storeoptions-10)
+- [Revoking a Refresh Token](#revoking-a-refresh-token)
+  - [Revoking the session token](#revoking-the-session-token)
+  - [Revoking an explicit token](#revoking-an-explicit-token)
+  - [Revoking on logout](#revoking-on-logout)
 - [Logout](#logout)
   - [Passing the `returnTo` parameter](#passing-the-returnto-parameter)
   - [Passing `StoreOptions`](#passing-storeoptions-11)
@@ -1473,6 +1477,47 @@ Once an enterprise connection has the option enabled, `getSession()` / `getUser(
 - The connection must be an `okta` or `oidc` enterprise connection with `id_token_session_expiry_supported: true` (Dashboard toggle "Use ID Token for Session Expiry", Management API, or Terraform).
 - Authorization Code flow.
 
+## Revoking a Refresh Token
+
+Revoking a refresh token invalidates it at Auth0 so it can no longer be used to obtain new access tokens.
+This is useful when implementing secure logout flows or when a user's session needs to be forcibly terminated.
+
+Revocation requires the application to have been granted `offline_access` scope so Auth0 issues a refresh token, and the target API must have **Allow Offline Access** enabled.
+
+> **Note:** Revocation does not affect access tokens that have already been issued. They remain valid until their expiry. For immediate session termination, combine revocation with `logout()`.
+
+### Revoking the session token
+
+When called without arguments, `revokeRefreshToken()` reads the refresh token directly from the current session:
+
+```ts
+await serverClient.revokeRefreshToken();
+```
+
+If no session exists or the session has no refresh token, a `MissingSessionError` is thrown.
+
+### Revoking an explicit token
+
+A specific token can be passed via `options.token`, bypassing the session lookup:
+
+```ts
+await serverClient.revokeRefreshToken({ token: '<refresh_token>' });
+```
+
+In resolver mode, the domain-match guard still applies even when a token is supplied explicitly. If the session domain does not match the domain resolved for the current request (or if the session has no stored domain), the call returns without revoking. Pass an empty string to `options.token` to get a `MissingRequiredArgumentError` rather than a silent no-op.
+
+### Revoking on logout
+
+`logout()` automatically revokes the session's refresh token before clearing the local session.
+Revocation is best-effort: if it fails for any reason (network error, token already revoked, misconfiguration), logout still proceeds. In resolver mode, both revocation and local session deletion only occur when the stored session domain matches the resolved domain — if they differ, the session belongs to a different tenant and is left untouched.
+
+```ts
+const logoutUrl = await serverClient.logout({
+  returnTo: 'http://localhost:3000',
+});
+// Redirect user to logoutUrl
+```
+
 ## Logout
 
 Logging out ensures the stored tokens and user information are removed, and that the user is no longer considered logged-in by the SDK.

packages/auth0-server-js/package.json

@@ -25,7 +25,7 @@
     }
   },
   "dependencies": {
-    "@auth0/auth0-auth-js": "^1.11.0",
+    "@auth0/auth0-auth-js": "^1.12.0",
     "jose": "^6.0.8"
   },
   "devDependencies": {

packages/auth0-server-js/src/index.ts

@@ -2,7 +2,7 @@ export { ServerClient } from './server-client.js';
 export { AbstractStateStore } from './store/abstract-state-store.js';
 export { AbstractTransactionStore } from './store/abstract-transaction-store.js';
 export type { TokenResponse, ActClaim } from '@auth0/auth0-auth-js';
-export { TokenExchangeError, MissingClientAuthError, OrganizationValidationError } from '@auth0/auth0-auth-js';
+export { TokenExchangeError, TokenRevocationError, MissingClientAuthError, OrganizationValidationError } from '@auth0/auth0-auth-js';
 
 export type { CookieHandler, CookieSerializeOptions } from './store/cookie-handler.js';
 export { CookieTransactionStore } from './store/cookie-transaction-store.js';