Fixing error handling in Firebase credentials (#448)

* Fixing error handling in Firebase credentials

* Added comments

* Updated changelog

Author: hiranya911

CHANGELOG.md

@@ -1,6 +1,7 @@
 # Unreleased
 
--
+- [fixed] Including additional helpful details in the errors thrown due to
+  credentials-related problems.
 
 # v6.5.1
 

src/auth/credential.ts

@@ -20,7 +20,7 @@ import os = require('os');
 import path = require('path');
 
 import {AppErrorCodes, FirebaseAppError} from '../utils/error';
-import {HttpClient, HttpRequestConfig} from '../utils/api-request';
+import {HttpClient, HttpRequestConfig, HttpError, HttpResponse} from '../utils/api-request';
 import {Agent} from 'http';
 
 const GOOGLE_TOKEN_AUDIENCE = 'https://accounts.google.com/o/oauth2/token';
@@ -190,28 +190,43 @@ export interface GoogleOAuthAccessToken {
 function requestAccessToken(client: HttpClient, request: HttpRequestConfig): Promise<GoogleOAuthAccessToken> {
   return client.send(request).then((resp) => {
     const json = resp.data;
-    if (json.error) {
-      let errorMessage = 'Error fetching access token: ' + json.error;
-      if (json.error_description) {
-        errorMessage += ' (' + json.error_description + ')';
-      }
-      throw new FirebaseAppError(AppErrorCodes.INVALID_CREDENTIAL, errorMessage);
-    } else if (!json.access_token || !json.expires_in) {
+    if (!json.access_token || !json.expires_in) {
       throw new FirebaseAppError(
         AppErrorCodes.INVALID_CREDENTIAL,
         `Unexpected response while fetching access token: ${ JSON.stringify(json) }`,
       );
-    } else {
-      return json;
     }
+    return json;
   }).catch((err) => {
-    throw new FirebaseAppError(
-      AppErrorCodes.INVALID_CREDENTIAL,
-      `Failed to parse access token response: ${err.toString()}`,
-    );
+    throw new FirebaseAppError(AppErrorCodes.INVALID_CREDENTIAL, getErrorMessage(err));
   });
 }
 
+/**
+ * Constructs a human-readable error message from the given Error.
+ */
+function getErrorMessage(err: Error): string {
+  const detail: string = (err instanceof HttpError) ? getDetailFromResponse(err.response) : err.message;
+  return `Error fetching access token: ${detail}`;
+}
+
+/**
+ * Extracts details from the given HTTP error response, and returns a human-readable description. If
+ * the response is JSON-formatted, looks up the error and error_description fields sent by the
+ * Google Auth servers. Otherwise returns the entire response payload as the error detail.
+ */
+function getDetailFromResponse(response: HttpResponse): string {
+  if (response.isJson() && response.data.error) {
+    const json = response.data;
+    let detail = json.error;
+    if (json.error_description) {
+      detail += ' (' + json.error_description + ')';
+    }
+    return detail;
+  }
+  return response.text;
+}
+
 /**
  * Implementation of Credential that uses a service account certificate.
  */

test/unit/auth/credential.spec.ts

@@ -31,8 +31,8 @@ import * as utils from '../utils';
 import * as mocks from '../../resources/mocks';
 
 import {
-  ApplicationDefaultCredential, CertCredential, Certificate, Credential, GoogleOAuthAccessToken,
-  MetadataServiceCredential, RefreshToken, RefreshTokenCredential,
+  ApplicationDefaultCredential, CertCredential, Certificate, GoogleOAuthAccessToken,
+  MetadataServiceCredential, RefreshTokenCredential,
 } from '../../../src/auth/credential';
 import { HttpClient } from '../../../src/utils/api-request';
 import {Agent} from 'https';
@@ -262,6 +262,31 @@ describe('Credential', () => {
         expect(token.expires_in).to.equal(ONE_HOUR_IN_SECONDS);
       });
     });
+
+    describe('Error Handling', () => {
+      let httpStub: sinon.SinonStub;
+      before(() => {
+        httpStub = sinon.stub(HttpClient.prototype, 'send');
+      });
+      after(() => httpStub.restore());
+
+      it('should throw an error including error details', () => {
+        httpStub.rejects(utils.errorFrom({
+          error: 'invalid_grant',
+          error_description: 'reason',
+        }));
+        const c = new CertCredential(mockCertificateObject);
+        return expect(c.getAccessToken()).to.be
+          .rejectedWith('Error fetching access token: invalid_grant (reason)');
+      });
+
+      it('should throw an error including error text payload', () => {
+        httpStub.rejects(utils.errorFrom('not json'));
+        const c = new CertCredential(mockCertificateObject);
+        return expect(c.getAccessToken()).to.be
+          .rejectedWith('Error fetching access token: not json');
+      });
+    });
   });
 
   describe('RefreshTokenCredential', () => {

test/unit/firebase-app.spec.ts

@@ -40,6 +40,7 @@ import {Firestore} from '@google-cloud/firestore';
 import {Database} from '@firebase/database';
 import {InstanceId} from '../../src/instance-id/instance-id';
 import {ProjectManagement} from '../../src/project-management/project-management';
+import { FirebaseAppError, AppErrorCodes } from '../../src/utils/error';
 
 chai.should();
 chai.use(sinonChai);
@@ -910,6 +911,31 @@ describe('FirebaseApp', () => {
         });
       });
     });
+
+    it('Includes the original error in exception', () => {
+      getTokenStub.restore();
+      const mockError = new FirebaseAppError(
+        AppErrorCodes.INVALID_CREDENTIAL, 'Something went wrong');
+      getTokenStub = sinon.stub(CertCredential.prototype, 'getAccessToken').rejects(mockError);
+      const detailedMessage = 'Credential implementation provided to initializeApp() via the "credential" property'
+        + ' failed to fetch a valid Google OAuth2 access token with the following error: "Something went wrong".';
+      expect(mockApp.INTERNAL.getToken(true)).to.be.rejectedWith(detailedMessage);
+    });
+
+    it('Returns a detailed message when an error is due to an invalid_grant', () => {
+      getTokenStub.restore();
+      const mockError = new FirebaseAppError(
+        AppErrorCodes.INVALID_CREDENTIAL, 'Failed to get credentials: invalid_grant (reason)');
+      getTokenStub = sinon.stub(CertCredential.prototype, 'getAccessToken').rejects(mockError);
+      const detailedMessage = 'Credential implementation provided to initializeApp() via the "credential" property'
+        + ' failed to fetch a valid Google OAuth2 access token with the following error: "Failed to get credentials:'
+        + ' invalid_grant (reason)". There are two likely causes: (1) your server time is not properly synced or (2)'
+        + ' your certificate key file has been revoked. To solve (1), re-sync the time on your server. To solve (2),'
+        + ' make sure the key ID for your key file is still present at '
+        + 'https://console.firebase.google.com/iam-admin/serviceaccounts/project. If not, generate a new key file '
+        + 'at https://console.firebase.google.com/project/_/settings/serviceaccounts/adminsdk.';
+      expect(mockApp.INTERNAL.getToken(true)).to.be.rejectedWith(detailedMessage);
+    });
   });
 
   describe('INTERNAL.addAuthTokenListener()', () => {