Add unit tests for utils/jwt

Author: lahirumaramba

src/auth/token-verifier.ts

@@ -19,7 +19,7 @@ import * as util from '../utils/index';
 import * as validator from '../utils/validator';
 import { 
   DecodedToken, decodeJwt, JwtError, JwtErrorCode,
-  EmulatorSignatureVerifier, PublicKeySignatureVerifier,
+  EmulatorSignatureVerifier, PublicKeySignatureVerifier, ALGORITHM_RS256, SignatureVerifier,
 } from '../utils/jwt';
 import { FirebaseApp } from '../firebase-app';
 import { auth } from './index';
@@ -29,8 +29,6 @@ import DecodedIdToken = auth.DecodedIdToken;
 // Audience to use for Firebase Auth Custom tokens
 const FIREBASE_AUDIENCE = 'https://identitytoolkit.googleapis.com/google.identity.identitytoolkit.v1.IdentityToolkit';
 
-const ALGORITHM_RS256 = 'RS256' as const;
-
 // URL containing the public keys for the Google certs (whose private keys are used to sign Firebase
 // Auth ID tokens)
 const CLIENT_CERT_URL = 'https://www.googleapis.com/robot/v1/metadata/x509/[email protected]';
@@ -77,7 +75,7 @@ export interface FirebaseTokenInfo {
  */
 export class FirebaseTokenVerifier {
   private readonly shortNameArticle: string;
-  private readonly signatureVerifier: PublicKeySignatureVerifier;
+  private readonly signatureVerifier: SignatureVerifier;
 
   constructor(clientCertUrl: string, private issuer: string, private tokenInfo: FirebaseTokenInfo,
               private readonly app: FirebaseApp) {
@@ -196,6 +194,13 @@ export class FirebaseTokenVerifier {
       });
   }
 
+  /**
+   * Verifies the content of a Firebase Auth JWT.
+   *
+   * @param fullDecodedToken The decoded JWT.
+   * @param projectId The Firebase Project Id.
+   * @param isEmulator Whether the token is an Emulator token.
+   */
   private verifyContent(
     fullDecodedToken: DecodedToken,
     projectId: string | null,
@@ -258,23 +263,24 @@ export class FirebaseTokenVerifier {
       });
   }
 
+  /**
+   * Maps JwtError to FirebaseAuthError
+   * 
+   * @param error JwtError to be mapped.
+   * @returns FirebaseAuthError or Error instance.
+   */
   private mapJwtErrorToAuthError(error: JwtError): Error {
     const verifyJwtTokenDocsMessage = ` See ${this.tokenInfo.url} ` +
       `for details on how to retrieve ${this.shortNameArticle} ${this.tokenInfo.shortName}.`;
-    if (!(error instanceof JwtError)) {
-      return (error);
-    }
     if (error.code === JwtErrorCode.TOKEN_EXPIRED) {
       const errorMessage = `${this.tokenInfo.jwtName} has expired. Get a fresh ${this.tokenInfo.shortName}` +
         ` from your client app and try again (auth/${this.tokenInfo.expiredErrorCode.code}).` +
         verifyJwtTokenDocsMessage;
       return new FirebaseAuthError(this.tokenInfo.expiredErrorCode, errorMessage);
-    }
-    else if (error.code === JwtErrorCode.INVALID_SIGNATURE) {
+    } else if (error.code === JwtErrorCode.INVALID_SIGNATURE) {
       const errorMessage = `${this.tokenInfo.jwtName} has invalid signature.` + verifyJwtTokenDocsMessage;
       return new FirebaseAuthError(AuthClientErrorCode.INVALID_ARGUMENT, errorMessage);
-    }
-    else if (error.code === JwtErrorCode.KEY_FETCH_ERROR) {
+    } else if (error.code === JwtErrorCode.NO_MATCHING_KID) {
       const errorMessage = `${this.tokenInfo.jwtName} has "kid" claim which does not ` +
         `correspond to a known public key. Most likely the ${this.tokenInfo.shortName} ` +
         'is expired, so get a fresh token from your client app and try again.';

src/utils/jwt.ts

@@ -19,7 +19,7 @@ import * as jwt from 'jsonwebtoken';
 import { HttpClient, HttpRequestConfig, HttpError } from '../utils/api-request';
 import { Agent } from 'http';
 
-const ALGORITHM_RS256: jwt.Algorithm = 'RS256' as const;
+export const ALGORITHM_RS256: jwt.Algorithm = 'RS256' as const;
 
 // `jsonwebtoken` converts errors from the `getKey` callback to its own `JsonWebTokenError` type
 // and prefixes the error message with the following. Use the prefix to identify errors thrown
@@ -29,7 +29,7 @@ const JWT_CALLBACK_ERROR_PREFIX = 'error in secret or public key callback: ';
 
 const NO_MATCHING_KID_ERROR_MESSAGE = 'no-matching-kid-error';
 
-export type Dictionary = {[key: string]: any}
+export type Dictionary = { [key: string]: any }
 
 export type DecodedToken = {
   header: Dictionary;
@@ -44,14 +44,17 @@ interface KeyFetcher {
   fetchPublicKeys(): Promise<{ [key: string]: string }>;
 }
 
-class UrlKeyFetcher implements KeyFetcher {
+/**
+ * Class to fetch public keys from a client certificates URL.
+ */
+export class UrlKeyFetcher implements KeyFetcher {
   private publicKeys: { [key: string]: string };
   private publicKeysExpireAt = 0;
 
   constructor(private clientCertUrl: string, private readonly httpAgent?: Agent) {
     if (!validator.isURL(clientCertUrl)) {
       throw new Error(
-        'The provided public client certificate URL is an invalid URL.',
+        'The provided public client certificate URL is not a valid URL.',
       );
     }
   }
@@ -68,6 +71,11 @@ class UrlKeyFetcher implements KeyFetcher {
     return Promise.resolve(this.publicKeys);
   }
 
+  /**
+   * Checks if the cached public keys need to be refreshed.
+   * 
+   * @returns Whether the keys should be fetched from the client certs url or not.
+   */
   private shouldRefresh(): boolean {
     return !this.publicKeys || this.publicKeysExpireAt <= Date.now();
   }
@@ -120,7 +128,7 @@ class UrlKeyFetcher implements KeyFetcher {
 }
 
 /**
- * Verifies JWT signature with a public key.
+ * Class for verifing JWT signature with a public key.
  */
 export class PublicKeySignatureVerifier implements SignatureVerifier {
   constructor(private keyFetcher: KeyFetcher) {
@@ -134,10 +142,31 @@ export class PublicKeySignatureVerifier implements SignatureVerifier {
   }
 
   public verify(token: string): Promise<void> {
+    if (!validator.isString(token)) {
+      return Promise.reject(new JwtError(JwtErrorCode.INVALID_ARGUMENT,
+        'The provided token must be a string.'));
+    }
+
     return verifyJwtSignature(token, getKeyCallback(this.keyFetcher), { algorithms: [ALGORITHM_RS256] });
   }
 }
 
+/**
+ * Class for verifing unsigned (emulator) JWTs.
+ */
+export class EmulatorSignatureVerifier implements SignatureVerifier {
+  public verify(token: string): Promise<void> {
+    // Signature checks skipped for emulator; no need to fetch public keys.
+    return verifyJwtSignature(token, '');
+  }
+}
+
+/**
+ * Provides a callback to fetch public keys.
+ * 
+ * @param fetcher KeyFetcher to fetch the keys from.
+ * @returns A callback function that can be used to get keys in `jsonwebtoken`.
+ */
 function getKeyCallback(fetcher: KeyFetcher): jwt.GetPublicKeyOrSecret {
   return (header: jwt.JwtHeader, callback: jwt.SigningKeyCallback) => {
     const kid = header.kid || '';
@@ -154,15 +183,22 @@ function getKeyCallback(fetcher: KeyFetcher): jwt.GetPublicKeyOrSecret {
   }
 }
 
-export class EmulatorSignatureVerifier implements SignatureVerifier {
-  public verify(token: string): Promise<void> {
-    // Signature checks skipped for emulator; no need to fetch public keys.
-    return verifyJwtSignature(token, '');
+/**
+ * Verifies the signature of a JWT using the provided secret or a function to fetch
+ * the secret or public key.
+ * 
+ * @param token The JWT to be verfied.
+ * @param secretOrPublicKey The secret or a function to fetch the secret or public key.
+ * @param options JWT verification options.
+ * @returns A Promise resolving for a token with a valid signature.
+ */
+export function verifyJwtSignature(token: string, secretOrPublicKey: jwt.Secret | jwt.GetPublicKeyOrSecret,
+  options?: jwt.VerifyOptions): Promise<void> {
+  if (!validator.isString(token)) {
+    return Promise.reject(new JwtError(JwtErrorCode.INVALID_ARGUMENT,
+      'The provided token must be a string.'));
   }
-}
 
-function verifyJwtSignature(token: string, secretOrPublicKey: jwt.Secret | jwt.GetPublicKeyOrSecret,
-  options?: jwt.VerifyOptions): Promise<void> {
   return new Promise((resolve, reject) => {
     jwt.verify(token, secretOrPublicKey, options,
       (error: jwt.VerifyErrors | null) => {
@@ -176,12 +212,10 @@ function verifyJwtSignature(token: string, secretOrPublicKey: jwt.Secret | jwt.G
         } else if (error.name === 'JsonWebTokenError') {
           if (error.message && error.message.includes(JWT_CALLBACK_ERROR_PREFIX)) {
             const message = error.message.split(JWT_CALLBACK_ERROR_PREFIX).pop() || 'Error fetching public keys.';
-            const code = (message === NO_MATCHING_KID_ERROR_MESSAGE) ? JwtErrorCode.KEY_FETCH_ERROR :
-              JwtErrorCode.INVALID_ARGUMENT;
+            const code = (message === NO_MATCHING_KID_ERROR_MESSAGE) ? JwtErrorCode.NO_MATCHING_KID :
+              JwtErrorCode.KEY_FETCH_ERROR;
             return reject(new JwtError(code, message));
           }
-          return reject(new JwtError(JwtErrorCode.INVALID_SIGNATURE,
-            'The provided token has invalid signature.'));
         }
         return reject(new JwtError(JwtErrorCode.INVALID_SIGNATURE, error.message));
       });
@@ -190,6 +224,9 @@ function verifyJwtSignature(token: string, secretOrPublicKey: jwt.Secret | jwt.G
 
 /**
  * Decodes general purpose Firebase JWTs.
+ * 
+ * @param jwtToken JWT token to be decoded.
+ * @returns Decoded token containing the header and payload.
  */
 export function decodeJwt(jwtToken: string): Promise<DecodedToken> {
   if (!validator.isString(jwtToken)) {
@@ -233,5 +270,6 @@ export enum JwtErrorCode {
   INVALID_CREDENTIAL = 'invalid-credential',
   TOKEN_EXPIRED = 'token-expired',
   INVALID_SIGNATURE = 'invalid-token',
-  KEY_FETCH_ERROR = 'no-matching-kid-error',
+  NO_MATCHING_KID = 'no-matching-kid-error',
+  KEY_FETCH_ERROR = 'key-fetch-error',
 }

test/unit/auth/token-verifier.spec.ts

@@ -77,33 +77,6 @@ function mockFetchWrongPublicKeys(): nock.Scope {
     });
 }
 
-/**
- * Returns a mocked out error response from the URL containing the public keys for the Google certs.
- * The status code is 200 but the response itself will contain an 'error' key.
- *
- * @return {Object} A nock response object.
- */
-function mockFetchPublicKeysWithErrorResponse(): nock.Scope {
-  return nock('https://www.googleapis.com')
-    .get('/robot/v1/metadata/x509/[email protected]')
-    .reply(200, {
-      error: 'message',
-      error_description: 'description', // eslint-disable-line @typescript-eslint/camelcase
-    });
-}
-
-/**
- * Returns a mocked out failed response from the URL containing the public keys for the Google certs.
- * The status code is non-200 and the response itself will fail.
- *
- * @return {Object} A nock response object.
- */
-function mockFailedFetchPublicKeys(): nock.Scope {
-  return nock('https://www.googleapis.com')
-    .get('/robot/v1/metadata/x509/[email protected]')
-    .replyWithError('message');
-}
-
 function createTokenVerifier(
   app: FirebaseApp
 ): verifier.FirebaseTokenVerifier {
@@ -554,108 +527,5 @@ describe('FirebaseTokenVerifier', () => {
       await tokenVerifier.verifyJWT(idTokenNoHeader)
         .should.eventually.be.rejectedWith('Firebase ID token has no "kid" claim.');
     });
-
-    it('should use the given HTTP Agent', () => {
-      const agent = new https.Agent();
-      const appWithAgent = mocks.appWithOptions({
-        credential: mocks.credential,
-        httpAgent: agent,
-      });
-      tokenVerifier = new verifier.FirebaseTokenVerifier(
-        'https://www.googleapis.com/robot/v1/metadata/x509/[email protected]',
-        'https://securetoken.google.com/',
-        verifier.ID_TOKEN_INFO,
-        appWithAgent,
-      );
-      mockedRequests.push(mockFetchPublicKeys());
-
-      clock = sinon.useFakeTimers(1000);
-
-      const mockIdToken = mocks.generateIdToken();
-
-      return tokenVerifier.verifyJWT(mockIdToken)
-        .then(() => {
-          expect(https.request).to.have.been.calledOnce;
-          expect(httpsSpy.args[0][0].agent).to.equal(agent);
-        });
-    });
-
-    it('should not fetch the Google cert public keys until the first time verifyJWT() is called', () => {
-      mockedRequests.push(mockFetchPublicKeys());
-
-      const testTokenVerifier = new verifier.FirebaseTokenVerifier(
-        'https://www.googleapis.com/robot/v1/metadata/x509/[email protected]',
-        'https://securetoken.google.com/',
-        verifier.ID_TOKEN_INFO,
-        app,
-      );
-      expect(https.request).not.to.have.been.called;
-
-      const mockIdToken = mocks.generateIdToken();
-
-      return testTokenVerifier.verifyJWT(mockIdToken)
-        .then(() => expect(https.request).to.have.been.calledOnce);
-    });
-
-    it('should not re-fetch the Google cert public keys every time verifyJWT() is called', () => {
-      mockedRequests.push(mockFetchPublicKeys());
-
-      const mockIdToken = mocks.generateIdToken();
-
-      return tokenVerifier.verifyJWT(mockIdToken).then(() => {
-        expect(https.request).to.have.been.calledOnce;
-        return tokenVerifier.verifyJWT(mockIdToken);
-      }).then(() => expect(https.request).to.have.been.calledOnce);
-    });
-
-    it('should refresh the Google cert public keys after the "max-age" on the request expires', () => {
-      mockedRequests.push(mockFetchPublicKeys());
-      mockedRequests.push(mockFetchPublicKeys());
-      mockedRequests.push(mockFetchPublicKeys());
-
-      clock = sinon.useFakeTimers(1000);
-
-      const mockIdToken = mocks.generateIdToken();
-
-      return tokenVerifier.verifyJWT(mockIdToken).then(() => {
-        expect(https.request).to.have.been.calledOnce;
-        clock!.tick(999);
-        return tokenVerifier.verifyJWT(mockIdToken);
-      }).then(() => {
-        expect(https.request).to.have.been.calledOnce;
-        clock!.tick(1);
-        return tokenVerifier.verifyJWT(mockIdToken);
-      }).then(() => {
-        // One second has passed
-        expect(https.request).to.have.been.calledTwice;
-        clock!.tick(999);
-        return tokenVerifier.verifyJWT(mockIdToken);
-      }).then(() => {
-        expect(https.request).to.have.been.calledTwice;
-        clock!.tick(1);
-        return tokenVerifier.verifyJWT(mockIdToken);
-      }).then(() => {
-        // Two seconds have passed
-        expect(https.request).to.have.been.calledThrice;
-      });
-    });
-
-    it('should be rejected if fetching the Google public keys fails', () => {
-      mockedRequests.push(mockFailedFetchPublicKeys());
-
-      const mockIdToken = mocks.generateIdToken();
-
-      return tokenVerifier.verifyJWT(mockIdToken)
-        .should.eventually.be.rejectedWith('message');
-    });
-
-    it('should be rejected if fetching the Google public keys returns a response with an error message', () => {
-      mockedRequests.push(mockFetchPublicKeysWithErrorResponse());
-
-      const mockIdToken = mocks.generateIdToken();
-
-      return tokenVerifier.verifyJWT(mockIdToken)
-        .should.eventually.be.rejectedWith('Error fetching public keys for Google certs: message (description)');
-    });
   });
 });

test/unit/index.spec.ts

@@ -25,6 +25,7 @@ import './utils/index.spec';
 import './utils/error.spec';
 import './utils/validator.spec';
 import './utils/api-request.spec';
+import './utils/jwt.spec';
 
 // Auth
 import './auth/auth.spec';