firebase-functions 4.3.0 → 4.4.0

package/lib/common/providers/https.d.ts

@@ -12,8 +12,25 @@ export interface Request extends express.Request {
  * The interface for AppCheck tokens verified in Callable functions
  */
 export interface AppCheckData {
+    /**
+     * The app ID of a Firebase App attested by the App Check token.
+     */
     appId: string;
+    /**
+     * Decoded App Check token.
+     */
     token: DecodedAppCheckToken;
+    /**
+     * Indicates if the token has been consumed.
+     *
+     * @remarks
+     * `false` value indicates that this is the first time the App Check service has seen this token and marked the
+     * token as consumed for future use of the token.
+     *
+     * `true` value indicates the token has previously been marked as consumed by the App Check service. In this case,
+     *  consider taking extra precautions, such as rejecting the request or requiring additional security checks.
+     */
+    alreadyConsumed?: boolean;
 }
 /**
  * The interface for Auth tokens verified in Callable functions

package/lib/common/providers/https.js

@@ -276,7 +276,7 @@ exports.unsafeDecodeAppCheckToken = unsafeDecodeAppCheckToken;
  * @returns {CallableTokenStatus} Status of the token verifications.
  */
 /** @internal */
-async function checkTokens(req, ctx) {
+async function checkTokens(req, ctx, options) {
     const verifications = {
         app: "INVALID",
         auth: "INVALID",
@@ -286,7 +286,7 @@ async function checkTokens(req, ctx) {
             verifications.auth = await checkAuthToken(req, ctx);
         }),
         Promise.resolve().then(async () => {
-            verifications.app = await checkAppCheckToken(req, ctx);
+            verifications.app = await checkAppCheckToken(req, ctx, options);
         }),
     ]);
     const logPayload = {
@@ -342,25 +342,45 @@ async function checkAuthToken(req, ctx) {
 }
 exports.checkAuthToken = checkAuthToken;
 /** @internal */
-async function checkAppCheckToken(req, ctx) {
-    const appCheck = req.header("X-Firebase-AppCheck");
-    if (!appCheck) {
+async function checkAppCheckToken(req, ctx, options) {
+    var _a;
+    const appCheckToken = req.header("X-Firebase-AppCheck");
+    if (!appCheckToken) {
         return "MISSING";
     }
     try {
         let appCheckData;
         if ((0, debug_1.isDebugFeatureEnabled)("skipTokenVerification")) {
-            const decodedToken = unsafeDecodeAppCheckToken(appCheck);
+            const decodedToken = unsafeDecodeAppCheckToken(appCheckToken);
             appCheckData = { appId: decodedToken.app_id, token: decodedToken };
+            if (options.consumeAppCheckToken) {
+                appCheckData.alreadyConsumed = false;
+            }
         }
         else {
-            appCheckData = await (0, app_check_1.getAppCheck)((0, app_1.getApp)()).verifyToken(appCheck);
+            const appCheck = (0, app_check_1.getAppCheck)((0, app_1.getApp)());
+            if (options.consumeAppCheckToken) {
+                if (((_a = appCheck.verifyToken) === null || _a === void 0 ? void 0 : _a.length) === 1) {
+                    const errorMsg = "Unsupported version of the Admin SDK." +
+                        " App Check token will not be consumed." +
+                        " Please upgrade the firebase-admin to the latest version.";
+                    logger.error(errorMsg);
+                    throw new HttpsError("internal", "Internal Error");
+                }
+                appCheckData = await (0, app_check_1.getAppCheck)((0, app_1.getApp)()).verifyToken(appCheckToken, { consume: true });
+            }
+            else {
+                appCheckData = await (0, app_check_1.getAppCheck)((0, app_1.getApp)()).verifyToken(appCheckToken);
+            }
         }
         ctx.app = appCheckData;
         return "VALID";
     }
     catch (err) {
         logger.warn("Failed to validate AppCheck token.", err);
+        if (err instanceof HttpsError) {
+            throw err;
+        }
         return "INVALID";
     }
 }
@@ -409,7 +429,7 @@ function wrapOnCallHandler(options, handler) {
                     delete context.rawRequest.headers[exports.ORIGINAL_AUTH_HEADER];
                 }
             }
-            const tokenStatus = await checkTokens(req, context);
+            const tokenStatus = await checkTokens(req, context, options);
             if (tokenStatus.auth === "INVALID") {
                 throw new HttpsError("unauthenticated", "Unauthenticated");
             }

package/lib/v1/function-configuration.d.ts

@@ -172,6 +172,29 @@ export interface RuntimeOptions {
      * When false, requests with invalid tokens set context.app to undefiend.
      */
     enforceAppCheck?: boolean;
+    /**
+     * Determines whether Firebase App Check token is consumed on request. Defaults to false.
+     *
+     * @remarks
+     * Set this to true to enable the App Check replay protection feature by consuming the App Check token on callable
+     * request. Tokens that are found to be already consumed will have request.app.alreadyConsumed property set true.
+     *
+     *
+     * Tokens are only considered to be consumed if it is sent to the App Check service by setting this option to true.
+     * Other uses of the token do not consume it.
+     *
+     * This replay protection feature requires an additional network call to the App Check backend and forces the clients
+     * to obtain a fresh attestation from the chosen attestation providers. This can therefore negatively impact
+     * performance and can potentially deplete your attestation providers' quotas faster. Use this feature only for
+     * protecting low volume, security critical, or expensive operations.
+     *
+     * This option does not affect the enforceAppCheck option. Setting the latter to true will cause the callable function
+     * to automatically respond with a 401 Unauthorized status code when request includes an invalid App Check token.
+     * When request includes valid but consumed App Check tokens, requests will not be automatically rejected. Instead,
+     * the request.app.alreadyConsumed property will be set to true and pass the execution to the handler code for making
+     * further decisions, such as requiring additional security checks or rejecting the request.
+     */
+    consumeAppCheckToken?: boolean;
     /**
      * Controls whether function configuration modified outside of function source is preserved. Defaults to false.
      *

package/lib/v1/index.d.ts

@@ -18,3 +18,5 @@ export * from "./cloud-functions";
 export * from "./config";
 export * from "./function-builder";
 export * from "./function-configuration";
+import * as params from "../params";
+export { params };

package/lib/v1/index.js

@@ -35,7 +35,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.app = exports.logger = exports.testLab = exports.tasks = exports.storage = exports.remoteConfig = exports.pubsub = exports.https = exports.firestore = exports.database = exports.auth = exports.analytics = void 0;
+exports.params = exports.app = exports.logger = exports.testLab = exports.tasks = exports.storage = exports.remoteConfig = exports.pubsub = exports.https = exports.firestore = exports.database = exports.auth = exports.analytics = void 0;
 // Providers:
 const logger = require("../logger");
 exports.logger = logger;
@@ -66,3 +66,6 @@ __exportStar(require("./cloud-functions"), exports);
 __exportStar(require("./config"), exports);
 __exportStar(require("./function-builder"), exports);
 __exportStar(require("./function-configuration"), exports);
+// NOTE: Equivalent to `export * as params from "../params"` but api-extractor doesn't support that syntax.
+const params = require("../params");
+exports.params = params;

package/lib/v1/providers/https.js

@@ -74,6 +74,7 @@ function _onCallWithOptions(handler, options) {
     const fixedLen = (data, context) => handler(data, context);
     const func = (0, https_1.onCallHandler)({
         enforceAppCheck: options.enforceAppCheck,
+        consumeAppCheckToken: options.consumeAppCheckToken,
         cors: { origin: true, methods: "POST" },
     }, fixedLen);
     func.__trigger = {

package/lib/v2/index.d.ts

@@ -22,3 +22,5 @@ export { alerts, database, storage, https, identity, pubsub, logger, tasks, even
 export { setGlobalOptions, GlobalOptions, SupportedRegion, MemoryOption, VpcEgressSetting, IngressSetting, EventHandlerOptions, } from "./options";
 export { CloudFunction, CloudEvent, ParamsOf } from "./core";
 export { Change } from "../common/change";
+import * as params from "../params";
+export { params };

package/lib/v2/index.js

@@ -21,7 +21,7 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Change = exports.setGlobalOptions = exports.firestore = exports.testLab = exports.remoteConfig = exports.scheduler = exports.eventarc = exports.tasks = exports.logger = exports.pubsub = exports.identity = exports.https = exports.storage = exports.database = exports.alerts = void 0;
+exports.params = exports.Change = exports.setGlobalOptions = exports.firestore = exports.testLab = exports.remoteConfig = exports.scheduler = exports.eventarc = exports.tasks = exports.logger = exports.pubsub = exports.identity = exports.https = exports.storage = exports.database = exports.alerts = void 0;
 /**
  * The V2 API for Cloud Functions for Firebase.
  * This SDK also supports deep imports. For example, the namespace
@@ -59,3 +59,6 @@ var options_1 = require("./options");
 Object.defineProperty(exports, "setGlobalOptions", { enumerable: true, get: function () { return options_1.setGlobalOptions; } });
 var change_1 = require("../common/change");
 Object.defineProperty(exports, "Change", { enumerable: true, get: function () { return change_1.Change; } });
+// NOTE: Equivalent to `export * as params from "../params"` but api-extractor doesn't support that syntax.
+const params = require("../params");
+exports.params = params;

package/lib/v2/options.d.ts

@@ -111,7 +111,7 @@ export interface GlobalOptions {
      * @remarks
      * When true, requests with invalid tokens autorespond with a 401
      * (Unauthorized) error.
-     * When false, requests with invalid tokens set event.app to undefiend.
+     * When false, requests with invalid tokens set event.app to undefined.
      */
     enforceAppCheck?: boolean;
     /**

package/lib/v2/providers/alerts/alerts.d.ts

@@ -31,7 +31,7 @@ export interface AlertEvent<T> extends CloudEvent<FirebaseAlertData<T>> {
     data: FirebaseAlertData<T>;
 }
 /** The underlying alert type of the Firebase Alerts provider. */
-export type AlertType = "crashlytics.newFatalIssue" | "crashlytics.newNonfatalIssue" | "crashlytics.regression" | "crashlytics.stabilityDigest" | "crashlytics.velocity" | "crashlytics.newAnrIssue" | "billing.planUpdate" | "billing.automatedPlanUpdate" | "appDistribution.newTesterIosDevice" | "appDistribution.inAppFeedback" | "performance.threshold" | string;
+export type AlertType = "crashlytics.newFatalIssue" | "crashlytics.newNonfatalIssue" | "crashlytics.regression" | "crashlytics.stabilityDigest" | "crashlytics.velocity" | "crashlytics.newAnrIssue" | "billing.planUpdate" | "billing.planAutomatedUpdate" | "appDistribution.newTesterIosDevice" | "appDistribution.inAppFeedback" | "performance.threshold" | string;
 /**
  * Configuration for Firebase Alert functions.
  */

package/lib/v2/providers/firestore.d.ts

@@ -2,6 +2,7 @@ import * as firestore from "firebase-admin/firestore";
 import { ParamsOf } from "../../common/params";
 import { Change, CloudEvent, CloudFunction } from "../core";
 import { EventHandlerOptions } from "../options";
+export { Change };
 /** A Firestore DocumentSnapshot */
 export type DocumentSnapshot = firestore.DocumentSnapshot;
 /** A Firestore QueryDocumentSnapshot */

package/lib/v2/providers/firestore.js

@@ -21,12 +21,13 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.onChangedOperation = exports.onOperation = exports.makeEndpoint = exports.makeChangedFirestoreEvent = exports.makeFirestoreEvent = exports.makeParams = exports.createBeforeSnapshot = exports.createSnapshot = exports.getOpts = exports.onDocumentDeleted = exports.onDocumentUpdated = exports.onDocumentCreated = exports.onDocumentWritten = exports.deletedEventType = exports.updatedEventType = exports.createdEventType = exports.writtenEventType = void 0;
+exports.onChangedOperation = exports.onOperation = exports.makeEndpoint = exports.makeChangedFirestoreEvent = exports.makeFirestoreEvent = exports.makeParams = exports.createBeforeSnapshot = exports.createSnapshot = exports.getOpts = exports.onDocumentDeleted = exports.onDocumentUpdated = exports.onDocumentCreated = exports.onDocumentWritten = exports.deletedEventType = exports.updatedEventType = exports.createdEventType = exports.writtenEventType = exports.Change = void 0;
 const logger = require("../../logger");
 const path_1 = require("../../common/utilities/path");
 const path_pattern_1 = require("../../common/utilities/path-pattern");
 const manifest_1 = require("../../runtime/manifest");
 const core_1 = require("../core");
+Object.defineProperty(exports, "Change", { enumerable: true, get: function () { return core_1.Change; } });
 const options_1 = require("../options");
 const firestore_1 = require("../../common/providers/firestore");
 /** @internal */

package/lib/v2/providers/https.d.ts

@@ -109,6 +109,29 @@ export interface CallableOptions extends HttpsOptions {
      * When false, requests with invalid tokens set event.app to undefiend.
      */
     enforceAppCheck?: boolean;
+    /**
+     * Determines whether Firebase App Check token is consumed on request. Defaults to false.
+     *
+     * @remarks
+     * Set this to true to enable the App Check replay protection feature by consuming the App Check token on callable
+     * request. Tokens that are found to be already consumed will have request.app.alreadyConsumed property set true.
+     *
+     *
+     * Tokens are only considered to be consumed if it is sent to the App Check service by setting this option to true.
+     * Other uses of the token do not consume it.
+     *
+     * This replay protection feature requires an additional network call to the App Check backend and forces the clients
+     * to obtain a fresh attestation from the chosen attestation providers. This can therefore negatively impact
+     * performance and can potentially deplete your attestation providers' quotas faster. Use this feature only for
+     * protecting low volume, security critical, or expensive operations.
+     *
+     * This option does not affect the enforceAppCheck option. Setting the latter to true will cause the callable function
+     * to automatically respond with a 401 Unauthorized status code when request includes an invalid App Check token.
+     * When request includes valid but consumed App Check tokens, requests will not be automatically rejected. Instead,
+     * the request.app.alreadyConsumed property will be set to true and pass the execution to the handler code for making
+     * further decisions, such as requiring additional security checks or rejecting the request.
+     */
+    consumeAppCheckToken?: boolean;
 }
 /**
  * Handles HTTPS requests.

package/lib/v2/providers/https.js

@@ -119,6 +119,7 @@ function onCall(optsOrHandler, handler) {
     const func = (0, https_1.onCallHandler)({
         cors: { origin, methods: "POST" },
         enforceAppCheck: (_a = opts.enforceAppCheck) !== null && _a !== void 0 ? _a : options.getGlobalOptions().enforceAppCheck,
+        consumeAppCheckToken: opts.consumeAppCheckToken,
     }, fixedLen);
     Object.defineProperty(func, "__trigger", {
         get: () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "firebase-functions",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "description": "Firebase SDK for Cloud Functions",
   "keywords": [
     "firebase",
@@ -225,7 +225,7 @@
     "eslint-config-prettier": "^8.3.0",
     "eslint-plugin-jsdoc": "^39.2.9",
     "eslint-plugin-prettier": "^4.0.0",
-    "firebase-admin": "^10.3.0",
+    "firebase-admin": "^11.8.0",
     "js-yaml": "^3.13.1",
     "jsdom": "^16.2.1",
     "jsonwebtoken": "^9.0.0",