feat(auth0-auth-js): add revokeToken support (SDK-8850) (#221)

Adds AuthClient.revokeToken() which calls the RFC 7009 /oauth/revoke
endpoint. Introduces TokenRevocationError for failed revocations.

Author: jd3vi1

packages/auth0-auth-js/src/auth-client.spec.ts

@@ -3992,3 +3992,93 @@ test('database.changePassword request carries the Auth0-Client telemetry header'
   await c.database.changePassword({ email: 'a@b.com', connection: 'db' });
   expect(headers?.get('Auth0-Client')).toBeTruthy();
 });
+
+describe('revokeToken', () => {
+  const revocationEndpoint = `https://${domain}/oauth/revoke`;
+
+  const setupRevocationHandlers = (handler: Parameters<typeof http.post>[1]) => {
+    server.use(
+      http.get(`https://${domain}/.well-known/openid-configuration`, () =>
+        HttpResponse.json({ ...buildOpenIdConfiguration(domain), revocation_endpoint: revocationEndpoint })
+      ),
+      http.post(revocationEndpoint, handler)
+    );
+  };
+
+  const makeClient = () =>
+    new AuthClient({
+      domain,
+      clientId: '<client_id>',
+      clientSecret: '<client_secret>',
+      discoveryCache: { ttl: 0 },
+    });
+
+  test('should successfully revoke a token', async () => {
+    let capturedToken: string | null = null;
+    let capturedHint: string | null = null;
+    setupRevocationHandlers(async ({ request }) => {
+      const body = await request.formData();
+      capturedToken = body.get('token') as string;
+      capturedHint = body.get('token_type_hint') as string;
+      return new HttpResponse(null, { status: 200 });
+    });
+
+    await expect(
+      makeClient().revokeToken({ token: '<refresh_token>', tokenTypeHint: 'refresh_token' })
+    ).resolves.toBeUndefined();
+    expect(capturedToken).toBe('<refresh_token>');
+    expect(capturedHint).toBe('refresh_token');
+  });
+
+  test('should revoke a token without tokenTypeHint', async () => {
+    let capturedHint: FormDataEntryValue | null = null;
+    setupRevocationHandlers(async ({ request }) => {
+      const body = await request.formData();
+      capturedHint = body.get('token_type_hint');
+      return new HttpResponse(null, { status: 200 });
+    });
+
+    await expect(
+      makeClient().revokeToken({ token: '<refresh_token>' })
+    ).resolves.toBeUndefined();
+    expect(capturedHint).toBeNull();
+  });
+
+  test('should throw TokenRevocationError when revocation fails', async () => {
+    setupRevocationHandlers(() =>
+      HttpResponse.json(
+        { error: '<error_code>', error_description: '<error_description>' },
+        { status: 400 }
+      )
+    );
+
+    await expect(
+      makeClient().revokeToken({ token: '<invalid_token>' })
+    ).rejects.toThrowError(
+      expect.objectContaining({
+        code: 'token_revocation_error',
+        message: 'An error occurred while trying to revoke the token.',
+        cause: expect.objectContaining({
+          error: '<error_code>',
+          error_description: '<error_description>',
+        }),
+      })
+    );
+  });
+
+  test('should send client credentials on the revocation request', async () => {
+    let capturedClientId: string | null = null;
+    let capturedClientSecret: string | null = null;
+    setupRevocationHandlers(async ({ request }) => {
+      const body = await request.formData();
+      capturedClientId = body.get('client_id') as string;
+      capturedClientSecret = body.get('client_secret') as string;
+      return new HttpResponse(null, { status: 200 });
+    });
+
+    await makeClient().revokeToken({ token: '<refresh_token>', tokenTypeHint: 'refresh_token' });
+
+    expect(capturedClientId).toBe('<client_id>');
+    expect(capturedClientSecret).toBe('<client_secret>');
+  });
+});

packages/auth0-auth-js/src/auth-client.ts

@@ -7,6 +7,7 @@ import {
   BuildLinkUserUrlError,
   BuildUnlinkUserUrlError,
   TokenExchangeError,
+  TokenRevocationError,
   MissingClientAuthError,
   NotSupportedError,
   NotSupportedErrorCode,
@@ -46,6 +47,7 @@ import {
   TokenByPasswordlessEmailOptions,
   TokenByPasswordlessSmsOptions,
   TokenByRefreshTokenOptions,
+  RevokeTokenOptions,
   TokenForConnectionOptions,
   TokenResponse,
   ActClaim,
@@ -1113,6 +1115,27 @@ export class AuthClient {
     }
   }
 
+  /**
+   * Revokes a token at the Auth0 /oauth/revoke endpoint.
+   *
+   * @throws {TokenRevocationError} If the revocation request fails.
+   */
+  public async revokeToken(options: RevokeTokenOptions): Promise<void> {
+    const { configuration } = await this.#discover();
+    const params: Record<string, string> = {};
+    if (options.tokenTypeHint) {
+      params['token_type_hint'] = options.tokenTypeHint;
+    }
+    try {
+      await client.tokenRevocation(configuration, options.token, params);
+    } catch (e) {
+      throw new TokenRevocationError(
+        'An error occurred while trying to revoke the token.',
+        toOAuth2Error(e)
+      );
+    }
+  }
+
   /**
    * Retrieves a token using Resource Owner Password Grant.
    * @param options Options for authenticating with username and password.

packages/auth0-auth-js/src/errors.ts

@@ -171,6 +171,16 @@ export class TokenExchangeError extends ApiError {
   }
 }
 
+/**
+ * Error thrown when revoking a token fails.
+ */
+export class TokenRevocationError extends ApiError {
+  constructor(message: string, cause?: OAuth2Error) {
+    super('token_revocation_error', message, cause);
+    this.name = 'TokenRevocationError';
+  }
+}
+
 /**
  * Error thrown when verifying the logout token.
  */

packages/auth0-auth-js/src/types.ts

@@ -605,6 +605,13 @@ export interface TokenVaultExchangeOptions {
   extra?: Record<string, string | string[]>;
 }
 
+export interface RevokeTokenOptions {
+  /** The token to revoke. */
+  token: string;
+  /** Hint about the token type. Per RFC 7009. */
+  tokenTypeHint?: 'refresh_token' | 'access_token';
+}
+
 export interface BuildLogoutUrlOptions {
   /**
    * The URL to which the user should be redirected after the logout.