Add support for App Check replay protection in callable functions (#7296)

* Add limited token support for functions * add test, works as a unit test, broken karma * Finish adding support for app check callable functions SDK * PR Feedback * Doc feedback Co-authored-by: Kevin Cheung <kevinthecheung@users.noreply.github.com> * s/useLimitedUseAppCheckToken/limitedUseAppCheckTokens/g * PR Feedback --------- Co-authored-by: Samuel Bushi <ssbushi@google.com> Co-authored-by: Kevin Cheung <kevinthecheung@users.noreply.github.com>

Author: 3 people

.changeset/rude-adults-rest.md

@@ -0,0 +1,7 @@
+---
+'@firebase/app-check-interop-types': minor
+'@firebase/app-check': minor
+'@firebase/functions': minor
+---
+
+Add support for App Check replay protection in callable functions

common/api-review/functions.api.md

@@ -43,6 +43,7 @@ export function httpsCallableFromURL<RequestData = unknown, ResponseData = unkno
 
 // @public
 exportinterfaceHttpsCallableOptions {
+ limitedUseAppCheckTokens?:boolean;
  timeout?:number;
 }
 

config/functions/index.js

@@ -76,6 +76,15 @@ exports.instanceIdTest = functions.https.onRequest((request, response) => {
 });
 });
 
+exports.appCheckTest=functions.https.onRequest((request,response)=>{
+cors(request,response,()=>{
+consttoken=request.get('X-Firebase-AppCheck');
+assert.equal(token!==undefined,true);
+assert.deepEqual(request.body,{data: {}});
+response.send({data: { token }});
+});
+});
+
 exports.nullTest=functions.https.onRequest((request,response)=>{
 cors(request,response,()=>{
 assert.deepEqual(request.body,{data: null});

docs-devsite/functions.httpscallableoptions.md

@@ -22,8 +22,19 @@ export interface HttpsCallableOptions
 
 | Property | Type | Description |
 | --- | --- | --- |
+| [limitedUseAppCheckTokens](./functions.httpscallableoptions.md#httpscallableoptionslimiteduseappchecktokens) | boolean | Ifsettotrue, useslimited-useAppChecktokenforcallablefunctionrequestsfromthisinstanceof [Functions](./functions.functions.md#functions_interface)<!-- -->. Youmustuselimited-usetokenstocallfunctionswithreplayprotectionenabled. Bydefault, thisisfalse. |
 | [timeout](./functions.httpscallableoptions.md#httpscallableoptionstimeout) | number | Timeinmillisecondsafterwhichtocancelifthereisnoresponse. Defaultis 70000. |
 
+## HttpsCallableOptions.limitedUseAppCheckTokens
+
+Ifsettotrue, useslimited-useAppChecktokenforcallablefunctionrequestsfromthisinstanceof [Functions](./functions.functions.md#functions_interface)<!-- -->. Youmustuselimited-usetokenstocallfunctionswithreplayprotectionenabled. Bydefault, thisisfalse.
+
+<b>Signature:</b>
+
+```typescript
+limitedUseAppCheckTokens?: boolean;
+```
+
 ## HttpsCallableOptions.timeout
 
 Timeinmillisecondsafterwhichtocancelifthereisnoresponse. Defaultis 70000.

packages/app-check-interop-types/index.d.ts

@@ -20,6 +20,10 @@ export interface FirebaseAppCheckInternal {
 // is present. Returns null if no token is present and no token requests are in-flight.
 getToken(forceRefresh?: boolean): Promise<AppCheckTokenResult>;
 
+// Always returns a fresh limited-use token suitable for Replay Protection.
+// The returned token must be used and consumed as soon as possible.
+getLimitedUseToken(): Promise<AppCheckTokenResult>;
+
 // Registers a listener to changes in the token state. There can be more than one listener
 // registered at the same time for one or more FirebaseAppAttestation instances. The
 // listeners call back on the UI thread whenever the current token associated with this

packages/app-check/src/factory.ts

@@ -20,6 +20,7 @@ import { FirebaseApp, _FirebaseService } from '@firebase/app';
 import{FirebaseAppCheckInternal,ListenerType}from'./types';
 import{
 getToken,
+getLimitedUseToken,
 addTokenListener,
 removeTokenListener
 }from'./internal-api';
@@ -55,6 +56,7 @@ export function internalFactory(
 ): FirebaseAppCheckInternal{
 return{
 getToken: forceRefresh=>getToken(appCheck,forceRefresh),
+getLimitedUseToken: ()=>getLimitedUseToken(appCheck),
 addTokenListener: listener=>
 addTokenListener(appCheck,ListenerType.INTERNAL,listener),
 removeTokenListener: listener=>removeTokenListener(appCheck.app,listener)

packages/app-check/src/types.ts

@@ -24,6 +24,10 @@ export interface FirebaseAppCheckInternal {
 // is present. Returns null if no token is present and no token requests are in-flight.
 getToken(forceRefresh?: boolean): Promise<AppCheckTokenResult>;
 
+// Get a Limited use Firebase App Check token. This method should be used
+// only if you need to authorize requests to a non-Firebase backend. Returns null if no token is present and no token requests are in-flight.
+getLimitedUseToken(): Promise<AppCheckTokenResult>;
+
 // Registers a listener to changes in the token state. There can be more than one listener
 // registered at the same time for one or more FirebaseAppAttestation instances. The
 // listeners call back on the UI thread whenever the current token associated with this

packages/functions/src/callable.test.ts

@@ -32,6 +32,10 @@ import {
 FirebaseAuthInternal,
 FirebaseAuthInternalName
 }from'@firebase/auth-interop-types';
+import{
+FirebaseAppCheckInternal,
+AppCheckInternalComponentName
+}from'@firebase/app-check-interop-types';
 import{makeFakeApp,createTestService}from'../test/utils';
 import{httpsCallable}from'./service';
 import{FUNCTIONS_TYPE}from'./constants';
@@ -108,7 +112,7 @@ describe('Firebase Functions > Call', () => {
 expect(result.data).to.equal(76);
 });
 
-it('token',async()=>{
+it('auth token',async()=>{
 // mock auth-internal service
 constauthMock: FirebaseAuthInternal={
 getToken: async()=>({accessToken: 'token'})
@@ -133,6 +137,74 @@ describe('Firebase Functions > Call', () => {
 stub.restore();
 });
 
+it('app check token',async()=>{
+constappCheckMock: FirebaseAppCheckInternal={
+getToken: async()=>({token: 'app-check-token'})
+}asunknownasFirebaseAppCheckInternal;
+constappCheckProvider=newProvider<AppCheckInternalComponentName>(
+'app-check-internal',
+newComponentContainer('test')
+);
+appCheckProvider.setComponent(
+newComponent(
+'app-check-internal',
+()=>appCheckMock,
+ComponentType.PRIVATE
+)
+);
+constfunctions=createTestService(
+app,
+region,
+undefined,
+undefined,
+appCheckProvider
+);
+
+// Stub out the internals to get an app check token.
+conststub=sinon.stub(appCheckMock,'getToken').callThrough();
+constfunc=httpsCallable(functions,'appCheckTest');
+constresult=awaitfunc({});
+expect(result.data).to.deep.equal({token: 'app-check-token'});
+
+expect(stub.callCount).to.equal(1);
+stub.restore();
+});
+
+it('app check limited use token',async()=>{
+constappCheckMock: FirebaseAppCheckInternal={
+getLimitedUseToken: async()=>({token: 'app-check-single-use-token'})
+}asunknownasFirebaseAppCheckInternal;
+constappCheckProvider=newProvider<AppCheckInternalComponentName>(
+'app-check-internal',
+newComponentContainer('test')
+);
+appCheckProvider.setComponent(
+newComponent(
+'app-check-internal',
+()=>appCheckMock,
+ComponentType.PRIVATE
+)
+);
+constfunctions=createTestService(
+app,
+region,
+undefined,
+undefined,
+appCheckProvider
+);
+
+// Stub out the internals to get an app check token.
+conststub=sinon.stub(appCheckMock,'getLimitedUseToken').callThrough();
+constfunc=httpsCallable(functions,'appCheckTest',{
+limitedUseAppCheckTokens: true
+});
+constresult=awaitfunc({});
+expect(result.data).to.deep.equal({token: 'app-check-single-use-token'});
+
+expect(stub.callCount).to.equal(1);
+stub.restore();
+});
+
 it('instance id',async()=>{
 // Should effectively skip this test in environments where messaging doesn't work.
 // (Node, IE)

packages/functions/src/context.ts

@@ -119,9 +119,13 @@ export class ContextProvider {
 }
 }
 
-asyncgetAppCheckToken(): Promise<string|null>{
+asyncgetAppCheckToken(
+limitedUseAppCheckTokens?: boolean
+): Promise<string|null>{
 if(this.appCheck){
-constresult=awaitthis.appCheck.getToken();
+constresult=limitedUseAppCheckTokens
+ ? awaitthis.appCheck.getLimitedUseToken()
+ : awaitthis.appCheck.getToken();
 if(result.error){
 // Do not send the App Check header to the functions endpoint if
 // there was an error from the App Check exchange endpoint. The App
@@ -133,10 +137,10 @@ export class ContextProvider {
 returnnull;
 }
 
-asyncgetContext(): Promise<Context>{
+asyncgetContext(limitedUseAppCheckTokens?: boolean): Promise<Context>{
 constauthToken=awaitthis.getAuthToken();
 constmessagingToken=awaitthis.getMessagingToken();
-constappCheckToken=awaitthis.getAppCheckToken();
+constappCheckToken=awaitthis.getAppCheckToken(limitedUseAppCheckTokens);
 return{ authToken, messagingToken, appCheckToken };
 }
 }

packages/functions/src/public-types.ts

@@ -47,6 +47,12 @@ export interface HttpsCallableOptions {
  * Default is 70000.
  */
 timeout?: number;
+/**
+ * If set to true, uses limited-use App Check token for callable function requests from this
+ * instance of {@link Functions}. You must use limited-use tokens to call functions with
+ * replay protection enabled. By default, this is false.
+ */
+limitedUseAppCheckTokens?: boolean;
 }
 
 /**

packages/functions/src/service.ts

@@ -277,7 +277,9 @@ async function callAtURL(
 
 // Add a header for the authToken.
 constheaders: {[key: string]: string}={};
-constcontext=awaitfunctionsInstance.contextProvider.getContext();
+constcontext=awaitfunctionsInstance.contextProvider.getContext(
+options.limitedUseAppCheckTokens
+);
 if(context.authToken){
 headers['Authorization']='Bearer '+context.authToken;
 }