Add support for token revocation

src/client.ts

@@ -5,7 +5,10 @@ import {
   IntrospectionRequest,
   IntrospectionResponse,
   PasswordRequest,
+  OAuth2TokenTypeHint,
   RefreshRequest,
+  RevocationRequest,
+  RevocationResponse,
   ServerMetadataResponse,
   TokenResponse,
 } from './messages';
@@ -61,6 +64,14 @@ export interface ClientSettings {
    */
   introspectionEndpoint?: string;
 
+  /**
+   * Revocation endpoint.
+   *
+   * Required for revoking tokens. Not supported by all servers.
+   * If not provided we'll try to discover it, or otherwise default to /revoke
+   */
+  revocationEndpoint?: string;
+
   /**
    * OAuth 2.0 Authorization Server Metadata endpoint or OpenID
    * Connect Discovery 1.0 endpoint.
@@ -92,7 +103,7 @@ export interface ClientSettings {
 }
 
 
-type OAuth2Endpoint = 'tokenEndpoint' | 'authorizationEndpoint' | 'discoveryEndpoint' | 'introspectionEndpoint';
+type OAuth2Endpoint = 'tokenEndpoint' | 'authorizationEndpoint' | 'discoveryEndpoint' | 'introspectionEndpoint' | 'revocationEndpoint';
 
 export class OAuth2Client {
 
@@ -197,6 +208,27 @@ export class OAuth2Client {
 
   }
 
+  /**
+   * Revoke a token
+   *
+   * This will revoke a token, provided that the server supports this feature.
+   *
+   * @see https://datatracker.ietf.org/doc/html/rfc7009
+   */
+  async revoke(token: OAuth2Token, tokenTypeHint: OAuth2TokenTypeHint = 'access_token'): Promise<RevocationResponse> {
+    let tokenValue = token.accessToken;
+    if (tokenTypeHint === 'refresh_token') {
+      tokenValue = token.refreshToken!;
+    }
+
+    const body: RevocationRequest = {
+      token: tokenValue,
+      token_type_hint: tokenTypeHint,
+    };
+    return this.request('revocationEndpoint', body);
+
+  }
+
   /**
    * Returns a url for an OAuth2 endpoint.
    *
@@ -230,6 +262,8 @@ export class OAuth2Client {
         return resolve('/.well-known/oauth-authorization-server', this.settings.server);
       case 'introspectionEndpoint':
         return resolve('/introspect', this.settings.server);
+      case 'revocationEndpoint':
+        return resolve('/revoke', this.settings.server);
     }
 
   }
@@ -267,6 +301,7 @@ export class OAuth2Client {
       ['authorization_endpoint', 'authorizationEndpoint'],
       ['token_endpoint', 'tokenEndpoint'],
       ['introspection_endpoint', 'introspectionEndpoint'],
+      ['revocation_endpoint', 'revocationEndpoint'],
     ] as const;
 
     if (this.serverMetadata === null) return;
@@ -287,6 +322,7 @@ export class OAuth2Client {
    */
   async request(endpoint: 'tokenEndpoint', body: RefreshRequest | ClientCredentialsRequest | PasswordRequest | AuthorizationCodeRequest): Promise<TokenResponse>;
   async request(endpoint: 'introspectionEndpoint', body: IntrospectionRequest): Promise<IntrospectionResponse>;
+  async request(endpoint: 'revocationEndpoint', body: RevocationRequest): Promise<RevocationResponse>;
   async request(endpoint: OAuth2Endpoint, body: Record<string, any>): Promise<unknown> {
 
     const uri = await this.getEndpoint(endpoint);

src/messages.ts

@@ -266,3 +266,10 @@ export type IntrospectionResponse = {
   jti?: string;
 
 }
+
+export type RevocationRequest = {
+  token: string;
+  token_type_hint?: OAuth2TokenTypeHint;
+}
+
+export type RevocationResponse = Record<string, never>;

test/revoke.ts

@@ -0,0 +1,68 @@
+import { testServer } from './test-server';
+import { OAuth2Client } from '../src';
+import { expect } from 'chai';
+
+describe('Token revocation', () => {
+  const server = testServer();
+  describe('should revoke access token when requested', async () => {
+
+    const client = new OAuth2Client({
+      server: server.url,
+      tokenEndpoint: '/token',
+      revocationEndpoint: '/revoke',
+      clientId: 'test-client-id',
+      clientSecret: 'test-client-secret',
+    });
+
+    const token = await client.clientCredentials();
+
+    describe('When token type hint is not specified', () => {
+      it('should assume token type is access token', async () => {
+        await client.revoke(token);
+
+        const request = server.lastRequest();
+        expect(request.body).to.eql({
+          token: token.accessToken,
+          token_type_hint: 'access_token',
+        });
+      });
+    });
+
+    describe('When token type is specified as access token', () => {
+      it('should supply access token', async () => {
+        await client.revoke(token, 'access_token');
+
+        const request = server.lastRequest();
+        expect(request.body).to.eql({
+          token: token.accessToken,
+          token_type_hint: 'access_token',
+        });
+      });
+    });
+
+    describe('When token type is specified as refresh token', () => {
+      it('should supply access token', async () => {
+        await client.revoke(token, 'refresh_token');
+
+        const request = server.lastRequest();
+        expect(request.body).to.eql({
+          token: token.refreshToken,
+          token_type_hint: 'refresh_token',
+        });
+      });
+    });
+  });
+
+  describe('Discovery', () => {
+    const client = new OAuth2Client({
+      server: server.url,
+      discoveryEndpoint: '/discover',
+      clientId: 'test-client-id',
+    });
+
+    it('Should discover revocation endpoint', async () => {
+      const result = await client.getEndpoint('revocationEndpoint');
+      expect(result).to.equal(server.url + '/revoke');
+    });
+  });
+});

test/test-server.ts

@@ -27,6 +27,8 @@ export function testServer() {
     return next();
   });
   app.use(issueToken);
+  app.use(revokeToken);
+  app.use(discover);
   const port = 40000 + Math.round(Math.random()*9999);
   const server = app.listen(port);
 
@@ -65,3 +67,27 @@ const issueToken: Middleware = (ctx, next) => {
   };
 
 };
+
+
+const revokeToken: Middleware = (ctx, next) => {
+
+  if (ctx.path !== '/revoke') {
+    return next();
+  }
+
+  ctx.response.type = 'application/json';
+  ctx.response.body = {};
+};
+
+
+const discover: Middleware = (ctx, next) => {
+
+  if (ctx.path !== '/discover') {
+    return next();
+  }
+
+  ctx.response.type = 'application/json';
+  ctx.response.body = {
+    revocation_endpoint: '/revoke',
+  };
+};