build(auth): added full implementation of GoogleToken (#814)

Author: miguelvelezsa

packages/google-auth-library-nodejs/src/gtoken/googleToken.ts

@@ -14,9 +14,34 @@
 
 import {request} from 'gaxios';
 import {TokenOptions, Transporter} from './tokenOptions';
+import {TokenHandler} from './tokenHandler';
+import {revokeToken} from './revokeToken';
+import {TokenData} from './getToken';
 
+/**
+ * Options for fetching an access token.
+ */
+export interface GetTokenOptions {
+  /**
+   * If true, a new token will be fetched, ignoring any cached token.
+   */
+  forceRefresh?: boolean;
+}
+
+/**
+ * Callback type for the `getToken` method.
+ */
+export type GetTokenCallback = (err: Error | null, token?: TokenData) => void;
+
+/**
+ * The GoogleToken class is used to manage authentication with Google's OAuth 2.0 authorization server.
+ * It handles fetching, caching, and refreshing of access tokens.
+ */
 class GoogleToken {
+  /** The configuration options for this token instance. */
   private tokenOptions: TokenOptions;
+  /** The handler for token fetching and caching logic. */
+  private tokenHandler: TokenHandler;
 
   /**
    * Create a GoogleToken.
@@ -25,17 +50,121 @@ class GoogleToken {
    */
   constructor(options?: TokenOptions) {
     this.tokenOptions = options || {};
-    // If transporter is not set, by default set Gaxios.request.
-    if (!this.tokenOptions.transporter) {
-      this.tokenOptions.transporter = {
-        request: opts => request(opts),
-      };
+    // If a transporter is not set, by default set it to use gaxios.
+    this.tokenOptions.transporter = this.tokenOptions.transporter || {
+      request: opts => request(opts),
+    };
+    if (!this.tokenOptions.iss) {
+      this.tokenOptions.iss = this.tokenOptions.email;
+    }
+    if (typeof this.tokenOptions.scope === 'object') {
+      this.tokenOptions.scope = this.tokenOptions.scope.join(' ');
+    }
+    this.tokenHandler = new TokenHandler(this.tokenOptions);
+  }
+
+  get expiresAt(): number | undefined {
+    return this.tokenHandler.tokenExpiresAt;
+  }
+
+  /**
+   * The most recent access token obtained by this client.
+   */
+  get accessToken(): string | undefined {
+    return this.tokenHandler.token?.access_token;
+  }
+
+  /**
+   * The most recent ID token obtained by this client.
+   */
+  get idToken(): string | undefined {
+    return this.tokenHandler.token?.id_token;
+  }
+
+  /**
+   * The token type of the most recent access token.
+   */
+  get tokenType(): string | undefined {
+    return this.tokenHandler.token?.token_type;
+  }
+
+  /**
+   * The refresh token for the current credentials.
+   */
+  get refreshToken(): string | undefined {
+    return this.tokenHandler.token?.refresh_token;
+  }
+
+  /**
+   * A boolean indicating if the current token has expired.
+   */
+  hasExpired(): boolean {
+    return this.tokenHandler.hasExpired();
+  }
+
+  /**
+   * A boolean indicating if the current token is expiring soon,
+   * based on the `eagerRefreshThresholdMillis` option.
+   */
+  isTokenExpiring(): boolean {
+    return this.tokenHandler.isTokenExpiring();
+  }
+
+  /**
+   * Fetches a new access token and returns it.
+   * @param opts Options for fetching the token.
+   */
+  getToken(opts?: GetTokenOptions): Promise<TokenData>;
+  getToken(callback: GetTokenCallback, opts?: GetTokenOptions): void;
+  getToken(
+    callbackOrOptions?: GetTokenCallback | GetTokenOptions,
+    opts: GetTokenOptions = {forceRefresh: false},
+  ): void | Promise<TokenData> {
+    // Handle the various method overloads.
+    let callback: GetTokenCallback | undefined;
+    if (typeof callbackOrOptions === 'function') {
+      callback = callbackOrOptions;
+    } else if (typeof callbackOrOptions === 'object') {
+      opts = callbackOrOptions;
+    }
+
+    // Delegate the token fetching to the token handler.
+    const promise = this.tokenHandler.getToken(opts.forceRefresh ?? false);
+
+    // If a callback is provided, use it, otherwise return the promise.
+    if (callback) {
+      promise.then(token => callback(null, token), callback);
     }
+    return promise;
   }
 
+  /**
+   * Revokes the current access token and resets the token handler.
+   */
+  revokeToken(): Promise<void>;
+  revokeToken(callback: (err?: Error) => void): void;
+  revokeToken(callback?: (err?: Error) => void): void | Promise<void> {
+    if (!this.accessToken) {
+      return Promise.reject(new Error('No token to revoke.'));
+    }
+    const promise = revokeToken(
+      this.accessToken,
+      this.tokenOptions.transporter as Transporter,
+    );
+
+    // If a callback is provided, use it.
+    if (callback) {
+      promise.then(() => callback(), callback);
+    }
+    // After revoking, reset the token handler to clear the cached token.
+    this.tokenHandler = new TokenHandler(this.tokenOptions);
+  }
+  /**
+   * Returns the configuration options for this token instance.
+   */
   get googleTokenOptions(): TokenOptions {
     return this.tokenOptions;
   }
 }
 
-export {GoogleToken, Transporter, TokenOptions};
+export {GoogleToken, Transporter, TokenOptions, TokenData};

packages/google-auth-library-nodejs/test/gtoken/test.googleToken.ts

@@ -13,15 +13,34 @@
 // limitations under the License.
 
 import * as assert from 'assert';
-import {describe, it} from 'mocha';
+import {describe, it, beforeEach, afterEach} from 'mocha';
+import * as sinon from 'sinon';
 import {
   GoogleToken,
   TokenOptions,
   Transporter,
+  TokenData,
 } from '../../src/gtoken/googleToken';
-import {GaxiosOptions, GaxiosResponse, request} from 'gaxios';
+import {GaxiosOptions, GaxiosResponse} from 'gaxios';
+import * as tokenHandler from '../../src/gtoken/tokenHandler';
+import * as revokeTokenModule from '../../src/gtoken/revokeToken';
 
 describe('GoogleToken', () => {
+  const sandbox = sinon.createSandbox();
+  let tokenHandlerStub: sinon.SinonStubbedInstance<tokenHandler.TokenHandler>;
+  let revokeTokenStub: sinon.SinonStub;
+
+  beforeEach(() => {
+    // Stub the TokenHandler constructor to control its behavior
+    tokenHandlerStub = sandbox.createStubInstance(tokenHandler.TokenHandler);
+    sandbox.stub(tokenHandler, 'TokenHandler').returns(tokenHandlerStub);
+    revokeTokenStub = sandbox.stub(revokeTokenModule, 'revokeToken');
+  });
+
+  afterEach(() => {
+    sandbox.restore();
+  });
+
   it('should initialize with default options if none are provided', () => {
     const token: GoogleToken = new GoogleToken();
     const options: TokenOptions = token.googleTokenOptions;
@@ -60,6 +79,30 @@ describe('GoogleToken', () => {
     assert.ok(typeof options.transporter.request === 'function');
   });
 
+  it('should set iss from email if provided', () => {
+    const providedOptions: TokenOptions = {
+      email: '[email protected]',
+    };
+    const token: GoogleToken = new GoogleToken(providedOptions);
+    const options: TokenOptions = token.googleTokenOptions;
+    assert.strictEqual(options.iss, '[email protected]');
+  });
+
+  it('should not override iss with email if both are provided', () => {
+    const providedOptions: TokenOptions = {
+      email: '[email protected]',
+      iss: '[email protected]',
+    };
+    const token: GoogleToken = new GoogleToken(providedOptions);
+    const options: TokenOptions = token.googleTokenOptions;
+    assert.strictEqual(options.iss, '[email protected]');
+  });
+
+  it('should convert array of scopes to a space-delimited string', () => {
+    const token = new GoogleToken({scope: ['scope1', 'scope2']});
+    assert.strictEqual(token.googleTokenOptions.scope, 'scope1 scope2');
+  });
+
   it('should use a custom transporter if provided in options', () => {
     const customTransporter: Transporter = {
       request: async <T>(opts: GaxiosOptions) => {
@@ -89,4 +132,122 @@ describe('GoogleToken', () => {
       providedOptions.email,
     );
   });
+
+  describe('Getters', () => {
+    it('should return undefined for token properties if no token is set', () => {
+      const token = new GoogleToken();
+      assert.strictEqual(token.accessToken, undefined);
+      assert.strictEqual(token.idToken, undefined);
+      assert.strictEqual(token.tokenType, undefined);
+      assert.strictEqual(token.refreshToken, undefined);
+    });
+
+    it('should return correct values from the cached token', () => {
+      const tokenData: TokenData = {
+        access_token: 'access',
+        id_token: 'id',
+        token_type: 'Bearer',
+        refresh_token: 'refresh',
+      };
+      tokenHandlerStub.token = tokenData;
+      const token = new GoogleToken();
+      assert.strictEqual(token.accessToken, 'access');
+      assert.strictEqual(token.idToken, 'id');
+      assert.strictEqual(token.tokenType, 'Bearer');
+      assert.strictEqual(token.refreshToken, 'refresh');
+    });
+  });
+
+  describe('Expiration methods', () => {
+    it('should delegate hasExpired to the token handler', () => {
+      tokenHandlerStub.hasExpired.returns(true);
+      const token = new GoogleToken();
+      assert.strictEqual(token.hasExpired(), true);
+      assert.ok(tokenHandlerStub.hasExpired.calledOnce);
+    });
+
+    it('should delegate isTokenExpiring to the token handler', () => {
+      tokenHandlerStub.isTokenExpiring.returns(false);
+      const token = new GoogleToken();
+      assert.strictEqual(token.isTokenExpiring(), false);
+      assert.ok(tokenHandlerStub.isTokenExpiring.calledOnce);
+    });
+  });
+
+  describe('getToken', () => {
+    it('should call tokenHandler.getToken and return a promise', async () => {
+      const tokenData: TokenData = {access_token: 'new-token'};
+      tokenHandlerStub.getToken.resolves(tokenData);
+      const token = new GoogleToken();
+      const result = await token.getToken({forceRefresh: true});
+      assert.strictEqual(result, tokenData);
+      assert.ok(tokenHandlerStub.getToken.calledOnceWith(true));
+    });
+
+    it('should work with a callback on success', done => {
+      const tokenData: TokenData = {access_token: 'new-token'};
+      tokenHandlerStub.getToken.resolves(tokenData);
+      const token = new GoogleToken();
+      token.getToken((err, result) => {
+        assert.ifError(err);
+        assert.strictEqual(result, tokenData);
+        assert.ok(tokenHandlerStub.getToken.calledOnceWith(false));
+        done();
+      });
+    });
+
+    it('should work with a callback on error', done => {
+      const error = new Error('getToken failed');
+      tokenHandlerStub.getToken.rejects(error);
+      const token = new GoogleToken();
+      token.getToken((err, result) => {
+        assert.strictEqual(err, error);
+        assert.strictEqual(result, undefined);
+        done();
+      });
+    });
+  });
+
+  describe('revokeToken', () => {
+    it('should call revokeToken and reset the handler', async () => {
+      const tokenData: TokenData = {access_token: 'token-to-revoke'};
+      tokenHandlerStub.token = tokenData;
+      revokeTokenStub.resolves();
+      const token = new GoogleToken();
+      await token.revokeToken();
+      assert.ok(revokeTokenStub.calledOnceWith('token-to-revoke'));
+      // Check that a new handler was created (initial creation + reset)
+      assert.ok(
+        (tokenHandler.TokenHandler as unknown as sinon.SinonStub).calledTwice,
+      );
+    });
+
+    it('should reject if there is no token to revoke', async () => {
+      const token = new GoogleToken();
+      await assert.rejects(() => token.revokeToken(), /No token to revoke/);
+    });
+
+    it('should work with a callback on success', done => {
+      const tokenData: TokenData = {access_token: 'token-to-revoke'};
+      tokenHandlerStub.token = tokenData;
+      revokeTokenStub.resolves();
+      const token = new GoogleToken();
+      token.revokeToken(err => {
+        assert.ifError(err);
+        assert.ok(revokeTokenStub.calledOnce);
+        done();
+      });
+    });
+
+    it('should work with a callback on error', done => {
+      const error = new Error('Revoke failed');
+      revokeTokenStub.rejects(error);
+      tokenHandlerStub.token = {access_token: 'token'};
+      const token = new GoogleToken();
+      token.revokeToken(err => {
+        assert.strictEqual(err, error);
+        done();
+      });
+    });
+  });
 });