feat(fac): Implement the App Check API (#22)

* Implement the App Check API

Author: lahirumaramba

src/app-check/app-check-api-client-internal.ts

@@ -0,0 +1,227 @@
+/*!
+ * @license
+ * Copyright 2021 Google Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { appCheck } from './index';
+import {
+  HttpRequestConfig, HttpClient, HttpError, AuthorizedHttpClient, HttpResponse
+} from '../utils/api-request';
+import { FirebaseApp } from '../firebase-app';
+import { PrefixedFirebaseError } from '../utils/error';
+
+import * as utils from '../utils/index';
+import * as validator from '../utils/validator';
+
+import AppCheckToken = appCheck.AppCheckToken;
+
+// App Check backend constants
+const FIREBASE_APP_CHECK_V1_API_URL_FORMAT = 'https://firebaseappcheck.googleapis.com/v1alpha/projects/{projectId}/apps/{appId}:exchangeCustomToken';
+
+const FIREBASE_APP_CHECK_CONFIG_HEADERS = {
+  'X-Firebase-Client': `fire-admin-node/${utils.getSdkVersion()}`
+};
+
+/**
+ * Class that facilitates sending requests to the Firebase App Check backend API.
+ *
+ * @internal
+ */
+export class AppCheckApiClient {
+  private readonly httpClient: HttpClient;
+  private projectId?: string;
+
+  constructor(private readonly app: FirebaseApp) {
+    if (!validator.isNonNullObject(app) || !('options' in app)) {
+      throw new FirebaseAppCheckError(
+        'invalid-argument',
+        'First argument passed to admin.appCheck() must be a valid Firebase app instance.');
+    }
+    this.httpClient = new AuthorizedHttpClient(app);
+  }
+
+  /**
+   * Exchange a signed custom token to App Check token
+   * 
+   * @param customToken The custom token to be exchanged.
+   * @param appId The mobile App ID.
+   * @return A promise that fulfills with a `AppCheckToken`.
+   */
+  public exchangeToken(customToken: string, appId: string): Promise<AppCheckToken> {
+    if (!validator.isNonEmptyString(appId)) {
+      throw new FirebaseAppCheckError(
+        'invalid-argument',
+        '`appId` must be a non-empty string.');
+    }
+    if (!validator.isNonEmptyString(customToken)) {
+      throw new FirebaseAppCheckError(
+        'invalid-argument',
+        '`customToken` must be a non-empty string.');
+    }
+    return this.getUrl(appId)
+      .then((url) => {
+        const request: HttpRequestConfig = {
+          method: 'POST',
+          url,
+          headers: FIREBASE_APP_CHECK_CONFIG_HEADERS,
+          data: { customToken }
+        };
+        return this.httpClient.send(request);
+      })
+      .then((resp) => {
+        return this.toAppCheckToken(resp);
+      })
+      .catch((err) => {
+        throw this.toFirebaseError(err);
+      });
+  }
+
+  private getUrl(appId: string): Promise<string> {
+    return this.getProjectId()
+      .then((projectId) => {
+        const urlParams = {
+          projectId,
+          appId,
+        };
+        const baseUrl = utils.formatString(FIREBASE_APP_CHECK_V1_API_URL_FORMAT, urlParams);
+        return utils.formatString(baseUrl);
+      });
+  }
+
+  private getProjectId(): Promise<string> {
+    if (this.projectId) {
+      return Promise.resolve(this.projectId);
+    }
+    return utils.findProjectId(this.app)
+      .then((projectId) => {
+        if (!validator.isNonEmptyString(projectId)) {
+          throw new FirebaseAppCheckError(
+            'unknown-error',
+            'Failed to determine project ID. Initialize the '
+            + 'SDK with service account credentials or set project ID as an app option. '
+            + 'Alternatively, set the GOOGLE_CLOUD_PROJECT environment variable.');
+        }
+        this.projectId = projectId;
+        return projectId;
+      });
+  }
+
+  private toFirebaseError(err: HttpError): PrefixedFirebaseError {
+    if (err instanceof PrefixedFirebaseError) {
+      return err;
+    }
+
+    const response = err.response;
+    if (!response.isJson()) {
+      return new FirebaseAppCheckError(
+        'unknown-error',
+        `Unexpected response with status: ${response.status} and body: ${response.text}`);
+    }
+
+    const error: Error = (response.data as ErrorResponse).error || {};
+    let code: AppCheckErrorCode = 'unknown-error';
+    if (error.status && error.status in APP_CHECK_ERROR_CODE_MAPPING) {
+      code = APP_CHECK_ERROR_CODE_MAPPING[error.status];
+    }
+    const message = error.message || `Unknown server error: ${response.text}`;
+    return new FirebaseAppCheckError(code, message);
+  }
+
+  /**
+   * Creates an AppCheckToken from the API response.
+   *
+   * @param resp API response object.
+   * @return An AppCheckToken instance.
+   */
+  private toAppCheckToken(resp: HttpResponse): AppCheckToken {
+    const token = resp.data.attestationToken;
+    // `timeToLive` is a string with the suffix "s" preceded by the number of seconds,
+    // with nanoseconds expressed as fractional seconds.
+    const ttlMillis = this.stringToMilliseconds(resp.data.timeToLive);
+    return {
+      token,
+      ttlMillis
+    }
+  }
+
+  /**
+   * Converts a duration string with the suffix `s` to milliseconds.
+   *
+   * @param duration The duration as a string with the suffix "s" preceded by the
+   * number of seconds, with fractional seconds. For example, 3 seconds with 0 nanoseconds
+   * is expressed as "3s", while 3 seconds and 1 nanosecond is expressed as "3.000000001s", 
+   * and 3 seconds and 1 microsecond is expressed as "3.000001s".
+   * 
+   * @return The duration in milliseconds.
+   */
+  private stringToMilliseconds(duration: string): number {
+    if (!validator.isNonEmptyString(duration) || !duration.endsWith('s')) {
+      throw new FirebaseAppCheckError(
+        'invalid-argument', '`timeToLive` must be a valid duration string with the suffix `s`.');
+    }
+    const seconds = duration.slice(0, -1);
+    return Math.floor(Number(seconds) * 1000);
+  }
+}
+
+interface ErrorResponse {
+  error?: Error;
+}
+
+interface Error {
+  code?: number;
+  message?: string;
+  status?: string;
+}
+
+export const APP_CHECK_ERROR_CODE_MAPPING: { [key: string]: AppCheckErrorCode } = {
+  ABORTED: 'aborted',
+  INVALID_ARGUMENT: 'invalid-argument',
+  INVALID_CREDENTIAL: 'invalid-credential',
+  INTERNAL: 'internal-error',
+  PERMISSION_DENIED: 'permission-denied',
+  UNAUTHENTICATED: 'unauthenticated',
+  NOT_FOUND: 'not-found',
+  UNKNOWN: 'unknown-error',
+};
+
+export type AppCheckErrorCode =
+  'aborted'
+  | 'invalid-argument'
+  | 'invalid-credential'
+  | 'internal-error'
+  | 'permission-denied'
+  | 'unauthenticated'
+  | 'not-found'
+  | 'unknown-error';
+
+/**
+ * Firebase App Check error code structure. This extends PrefixedFirebaseError.
+ *
+ * @param {AppCheckErrorCode} code The error code.
+ * @param {string} message The error message.
+ * @constructor
+ */
+export class FirebaseAppCheckError extends PrefixedFirebaseError {
+  constructor(code: AppCheckErrorCode, message: string) {
+    super('app-check', code, message);
+
+    /* tslint:disable:max-line-length */
+    // Set the prototype explicitly. See the following link for more details:
+    // https://github.com/Microsoft/TypeScript/wiki/Breaking-Changes#extending-built-ins-like-error-array-and-map-may-no-longer-work
+    /* tslint:enable:max-line-length */
+    (this as any).__proto__ = FirebaseAppCheckError.prototype;
+  }
+}

src/app-check/app-check.ts

@@ -0,0 +1,62 @@
+/*!
+ * @license
+ * Copyright 2021 Google Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { FirebaseApp } from '../firebase-app';
+import { appCheck } from './index';
+import { AppCheckApiClient } from './app-check-api-client-internal';
+import { 
+  appCheckErrorFromCryptoSignerError, AppCheckTokenGenerator 
+} from './token-generator';
+import { cryptoSignerFromApp } from '../utils/crypto-signer';
+
+import AppCheckInterface = appCheck.AppCheck;
+import AppCheckToken = appCheck.AppCheckToken;
+
+/**
+ * AppCheck service bound to the provided app.
+ */
+export class AppCheck implements AppCheckInterface {
+
+  private readonly client: AppCheckApiClient;
+  private readonly tokenGenerator: AppCheckTokenGenerator;
+
+  /**
+   * @param app The app for this AppCheck service.
+   * @constructor
+   */
+  constructor(readonly app: FirebaseApp) {
+    this.client = new AppCheckApiClient(app);
+    try {
+      this.tokenGenerator = new AppCheckTokenGenerator(cryptoSignerFromApp(app));
+    } catch (err) {
+      throw appCheckErrorFromCryptoSignerError(err);
+    }
+  }
+
+  /**
+   * Creates a new {@link appCheck.AppCheckToken `AppCheckToken`} that can be sent
+   * back to a client.
+   *
+   * @return A promise that fulfills with a `AppCheckToken`.
+   */
+  public createToken(appId: string): Promise<AppCheckToken> {
+    return this.tokenGenerator.createCustomToken(appId)
+      .then((customToken) => {
+        return this.client.exchangeToken(customToken, appId);
+      });
+  }
+}

src/app-check/index.ts

@@ -0,0 +1,82 @@
+/*!
+ * @license
+ * Copyright 2021 Google Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { app } from '../firebase-namespace-api';
+
+/**
+ * Gets the {@link appCheck.AppCheck `AppCheck`} service for the
+ * default app or a given app.
+ *
+ * You can call `admin.appCheck()` with no arguments to access the default
+ * app's {@link appCheck.AppCheck `AppCheck`} service or as
+ * `admin.appCheck(app)` to access the
+ * {@link appCheck.AppCheck `AppCheck`} service associated with a
+ * specific app.
+ *
+ * @example
+ * ```javascript
+ * // Get the `AppCheck` service for the default app
+ * var defaultAppCheck = admin.appCheck();
+ * ```
+ *
+ * @example
+ * ```javascript
+ * // Get the `AppCheck` service for a given app
+ * var otherAppCheck = admin.appCheck(otherApp);
+ * ```
+ *
+ * @param app Optional app for which to return the `AppCheck` service.
+ *   If not provided, the default `AppCheck` service is returned.
+ *
+ * @return The default `AppCheck` service if no
+ *   app is provided, or the `AppCheck` service associated with the provided
+ *   app.
+ */
+export declare function appCheck(app?: app.App): appCheck.AppCheck;
+
+/* eslint-disable @typescript-eslint/no-namespace */
+export namespace appCheck {
+  /**
+   * The Firebase `AppCheck` service interface.
+   */
+  export interface AppCheck {
+    app: app.App;
+
+    /**
+     * Creates a new {@link appCheck.AppCheckToken `AppCheckToken`} that can be sent
+     * back to a client.
+     *
+     * @return A promise that fulfills with a `AppCheckToken`.
+     */
+    createToken(appId: string): Promise<AppCheckToken>;
+  }
+
+  /**
+   * Interface representing an App Check token.
+   */
+  export interface AppCheckToken {
+    /**
+     * Firebase App Check token
+     */
+    token: string;
+
+    /**
+     * Time-to-live duration of the token in milliseconds.
+     */
+    ttlMillis: number;
+  }
+}