App Check: Token API for 3P use (#8266)

* Initial API implementation

* Update CHANGELOG

* Update test imports

* Make API async/await friendly by default

* Make API async friendly by default 2

* Fix CI

* Remove async/await example to fix CI

* Edit comment spacing

* Keychain error handling

* API rename and tests

* Add comments to tests

* Add public errors to umbrella header

* Refactor remaining test logic

* Remove newline

* Review

* Fix import style

* Fix import style 2

Author: ncooke3

FirebaseAppCheck/CHANGELOG.md

@@ -1,5 +1,7 @@
+# Unreleased
+- [added] Token API for 3P use. (#8266)
 # 8.2.0 -- M98
 - [added] Apple's App Attest attestation provider support. (#8133)
 - [changed] Token auto-refresh optimizations. (#8232)
 # v8.0.0 -- M95
-- [added] Firebase abuse reduction support SDK. (#7928, #7937, #7948)
+- [added] Firebase abuse reduction support SDK. (#7928, #7937, #7948)

FirebaseAppCheck/Sources/AppAttestProvider/Errors/FIRAppAttestRejectionError.m

@@ -14,16 +14,16 @@
  * limitations under the License.
  */
 
+#import "FirebaseAppCheck/Sources/Public/FirebaseAppCheck/FIRAppCheckErrors.h"
+
 #import "FirebaseAppCheck/Sources/AppAttestProvider/Errors/FIRAppAttestRejectionError.h"
 
 #import "FirebaseAppCheck/Sources/Core/Errors/FIRAppCheckErrorUtil.h"
 
 @implementation FIRAppAttestRejectionError
 
 - (instancetype)init {
-  return [self initWithDomain:kFIRAppCheckErrorDomain
-                         code:FIRAppCheckErrorCodeUnknown
-                     userInfo:nil];
+  return [self initWithDomain:FIRAppCheckErrorDomain code:FIRAppCheckErrorCodeUnknown userInfo:nil];
 }
 
 @end

FirebaseAppCheck/Sources/AppAttestProvider/Storage/FIRAppAttestArtifactStorage.h

@@ -17,6 +17,7 @@
 #import <Foundation/Foundation.h>
 
 @class FBLPromise<ValueType>;
+@class GULKeychainStorage;
 
 NS_ASSUME_NONNULL_BEGIN
 
@@ -46,7 +47,7 @@ NS_ASSUME_NONNULL_BEGIN
 
 - (instancetype)init NS_UNAVAILABLE;
 
-/// A default initializer.
+/// Default convenience initializer.
 /// @param appName A Firebase App name (`FirebaseApp.name`). The app name will be used as a part of
 /// the key to store the token for the storage instance.
 /// @param appID A Firebase App identifier (`FirebaseOptions.googleAppID`). The app ID will be used
@@ -55,6 +56,19 @@ NS_ASSUME_NONNULL_BEGIN
 - (instancetype)initWithAppName:(NSString *)appName
                           appID:(NSString *)appID
                     accessGroup:(nullable NSString *)accessGroup;
+
+/// Designated initializer.
+/// @param appName A Firebase App name (`FirebaseApp.name`). The app name will be used as a part of
+/// the key to store the token for the storage instance.
+/// @param appID A Firebase App identifier (`FirebaseOptions.googleAppID`). The app ID will be used
+/// as a part of the key to store the token for the storage instance.
+/// @param keychainStorage An instance of `GULKeychainStorage` used as an underlying secure storage.
+/// @param accessGroup The Keychain Access Group.
+- (instancetype)initWithAppName:(NSString *)appName
+                          appID:(NSString *)appID
+                keychainStorage:(GULKeychainStorage *)keychainStorage
+                    accessGroup:(nullable NSString *)accessGroup NS_DESIGNATED_INITIALIZER;
+
 @end
 
 NS_ASSUME_NONNULL_END

FirebaseAppCheck/Sources/AppAttestProvider/Storage/FIRAppAttestArtifactStorage.m

@@ -22,10 +22,11 @@
 #import "FBLPromises.h"
 #endif
 
-#import "FirebaseAppCheck/Sources/AppAttestProvider/Storage/FIRAppAttestStoredArtifact.h"
-
 #import <GoogleUtilities/GULKeychainStorage.h>
 
+#import "FirebaseAppCheck/Sources/AppAttestProvider/Storage/FIRAppAttestStoredArtifact.h"
+#import "FirebaseAppCheck/Sources/Core/Errors/FIRAppCheckErrorUtil.h"
+
 NS_ASSUME_NONNULL_BEGIN
 
 static NSString *const kKeychainService = @"com.firebase.app_check.app_attest_artifact_storage";
@@ -78,27 +79,42 @@ - (instancetype)initWithAppName:(NSString *)appName
         } else {
           return nil;
         }
+      })
+      .recover(^NSError *(NSError *error) {
+        return [FIRAppCheckErrorUtil keychainErrorWithError:error];
       });
 }
 
 - (FBLPromise<NSData *> *)setArtifact:(nullable NSData *)artifact forKey:(nonnull NSString *)keyID {
   if (artifact) {
-    FIRAppAttestStoredArtifact *storedArtifact =
-        [[FIRAppAttestStoredArtifact alloc] initWithKeyID:keyID artifact:artifact];
-    return [self.keychainStorage setObject:storedArtifact
-                                    forKey:[self artifactKey]
-                               accessGroup:self.accessGroup]
-        .then(^id _Nullable(NSNull *_Nullable value) {
-          return artifact;
-        });
+    return [self storeArtifact:artifact forKey:keyID].recover(^NSError *(NSError *error) {
+      return [FIRAppCheckErrorUtil keychainErrorWithError:error];
+    });
   } else {
     return [self.keychainStorage removeObjectForKey:[self artifactKey] accessGroup:self.accessGroup]
         .then(^id _Nullable(NSNull *_Nullable value) {
           return nil;
+        })
+        .recover(^NSError *(NSError *error) {
+          return [FIRAppCheckErrorUtil keychainErrorWithError:error];
         });
   }
 }
 
+#pragma mark - Helpers
+
+- (FBLPromise<NSData *> *)storeArtifact:(nullable NSData *)artifact
+                                 forKey:(nonnull NSString *)keyID {
+  FIRAppAttestStoredArtifact *storedArtifact =
+      [[FIRAppAttestStoredArtifact alloc] initWithKeyID:keyID artifact:artifact];
+  return [self.keychainStorage setObject:storedArtifact
+                                  forKey:[self artifactKey]
+                             accessGroup:self.accessGroup]
+      .then(^id _Nullable(NSNull *_Nullable value) {
+        return artifact;
+      });
+}
+
 - (NSString *)artifactKey {
   return
       [NSString stringWithFormat:@"app_check_app_attest_artifact.%@.%@", self.appName, self.appID];

FirebaseAppCheck/Sources/Core/Errors/FIRAppCheckErrorUtil.h

@@ -20,17 +20,20 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
-FOUNDATION_EXTERN NSErrorDomain const kFIRAppCheckErrorDomain NS_SWIFT_NAME(AppCheckErrorDomain);
-
 void FIRAppCheckSetErrorToPointer(NSError *error, NSError **pointer);
 
 @interface FIRAppCheckErrorUtil : NSObject
 
-// Internal errors.
++ (NSError *)publicDomainErrorWithError:(NSError *)error;
+
+// MARK: - Internal errors
 
 + (NSError *)cachedTokenNotFound;
+
 + (NSError *)cachedTokenExpired;
 
++ (NSError *)keychainErrorWithError:(NSError *)error;
+
 + (FIRAppCheckHTTPError *)APIErrorWithHTTPResponse:(NSHTTPURLResponse *)HTTPResponse
                                               data:(nullable NSData *)data;
 
@@ -50,20 +53,4 @@ void FIRAppCheckSetErrorToPointer(NSError *error, NSError **pointer);
 
 @end
 
-typedef NS_ERROR_ENUM(kFIRAppCheckErrorDomain, FIRAppCheckErrorCode){
-    /// An unknown or non-actionable error.
-    FIRAppCheckErrorCodeUnknown = 0,
-
-    /// A network connection error.
-    FIRAppCheckErrorCodeServerUnreachable = 1,
-
-    /// Invalid configuration error.
-    FIRAppCheckErrorCodeInvalidConfiguration = 2,
-
-    /// System keychain access error.
-    FIRAppCheckErrorCodeKeychain = 3,
-
-    /// Selected app attestation provider is not supported on the current platform or OS version.
-    FIRAppCheckErrorCodeUnsupported = 4} NS_SWIFT_NAME(AppCheckErrorCode);
-
 NS_ASSUME_NONNULL_END

FirebaseAppCheck/Sources/Core/Errors/FIRAppCheckErrorUtil.m

@@ -15,12 +15,24 @@
  */
 
 #import "FirebaseAppCheck/Sources/Core/Errors/FIRAppCheckErrorUtil.h"
-#import "FirebaseAppCheck/Sources/Core/Errors/FIRAppCheckHTTPError.h"
 
-NSString *const kFIRAppCheckErrorDomain = @"com.firebase.appCheck";
+#import <GoogleUtilities/GULKeychainUtils.h>
+
+#import "FirebaseAppCheck/Sources/Core/Errors/FIRAppCheckHTTPError.h"
+#import "FirebaseAppCheck/Sources/Public/FirebaseAppCheck/FIRAppCheckErrors.h"
 
 @implementation FIRAppCheckErrorUtil
 
++ (NSError *)publicDomainErrorWithError:(NSError *)error {
+  if ([error.domain isEqualToString:FIRAppCheckErrorDomain]) {
+    return error;
+  }
+
+  return [self unknownErrorWithError:error];
+}
+
+#pragma mark - Internal errors
+
 + (NSError *)cachedTokenNotFound {
   NSString *failureReason = [NSString stringWithFormat:@"Cached token not found."];
   return [self appCheckErrorWithCode:FIRAppCheckErrorCodeUnknown
@@ -35,14 +47,25 @@ + (NSError *)cachedTokenExpired {
                      underlyingError:nil];
 }
 
++ (NSError *)keychainErrorWithError:(NSError *)error {
+  if ([error.domain isEqualToString:kGULKeychainUtilsErrorDomain]) {
+    NSString *failureReason = [NSString stringWithFormat:@"Keychain access error."];
+    return [self appCheckErrorWithCode:FIRAppCheckErrorCodeKeychain
+                         failureReason:failureReason
+                       underlyingError:error];
+  }
+
+  return [self unknownErrorWithError:error];
+}
+
 + (FIRAppCheckHTTPError *)APIErrorWithHTTPResponse:(NSHTTPURLResponse *)HTTPResponse
                                               data:(nullable NSData *)data {
   return [[FIRAppCheckHTTPError alloc] initWithHTTPResponse:HTTPResponse data:data];
 }
 
 + (NSError *)APIErrorWithNetworkError:(NSError *)networkError {
   NSString *failureReason = [NSString stringWithFormat:@"API request error."];
-  return [self appCheckErrorWithCode:FIRAppCheckErrorCodeUnknown
+  return [self appCheckErrorWithCode:FIRAppCheckErrorCodeServerUnreachable
                        failureReason:failureReason
                      underlyingError:networkError];
 }
@@ -83,7 +106,7 @@ + (NSError *)unsupportedAttestationProvider:(NSString *)providerName {
 }
 
 + (NSError *)appAttestKeyIDNotFound {
-  NSString *failureReason = @"App attest key ID not found.";
+  NSString *failureReason = [NSString stringWithFormat:@"App attest key ID not found."];
   return [self appCheckErrorWithCode:FIRAppCheckErrorCodeUnknown
                        failureReason:failureReason
                      underlyingError:nil];
@@ -95,14 +118,23 @@ + (NSError *)errorWithFailureReason:(NSString *)failureReason {
                      underlyingError:nil];
 }
 
+#pragma mark - Helpers
+
++ (NSError *)unknownErrorWithError:(NSError *)error {
+  NSString *failureReason = error.userInfo[NSLocalizedFailureReasonErrorKey];
+  return [self appCheckErrorWithCode:FIRAppCheckErrorCodeUnknown
+                       failureReason:failureReason
+                     underlyingError:error];
+}
+
 + (NSError *)appCheckErrorWithCode:(FIRAppCheckErrorCode)code
                      failureReason:(nullable NSString *)failureReason
                    underlyingError:(nullable NSError *)underlyingError {
   NSMutableDictionary *userInfo = [NSMutableDictionary dictionary];
   userInfo[NSUnderlyingErrorKey] = underlyingError;
   userInfo[NSLocalizedFailureReasonErrorKey] = failureReason;
 
-  return [NSError errorWithDomain:kFIRAppCheckErrorDomain code:code userInfo:userInfo];
+  return [NSError errorWithDomain:FIRAppCheckErrorDomain code:code userInfo:userInfo];
 }
 
 @end

FirebaseAppCheck/Sources/Core/Errors/FIRAppCheckErrors.m

@@ -0,0 +1,21 @@
+/*
+ * Copyright 2021 Google LLC
+ *
+ * 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 <Foundation/Foundation.h>
+
+#import "FirebaseAppCheck/Sources/Public/FirebaseAppCheck/FIRAppCheckErrors.h"
+
+NSErrorDomain const FIRAppCheckErrorDomain = @"com.firebase.appCheck";

FirebaseAppCheck/Sources/Core/Errors/FIRAppCheckHTTPError.m

@@ -17,13 +17,14 @@
 #import "FirebaseAppCheck/Sources/Core/Errors/FIRAppCheckHTTPError.h"
 
 #import "FirebaseAppCheck/Sources/Core/Errors/FIRAppCheckErrorUtil.h"
+#import "FirebaseAppCheck/Sources/Public/FirebaseAppCheck/FIRAppCheckErrors.h"
 
 @implementation FIRAppCheckHTTPError
 
 - (instancetype)initWithHTTPResponse:(NSHTTPURLResponse *)HTTPResponse
                                 data:(nullable NSData *)data {
   NSDictionary *userInfo = [[self class] userInfoWithHTTPResponse:HTTPResponse data:data];
-  self = [super initWithDomain:kFIRAppCheckErrorDomain
+  self = [super initWithDomain:FIRAppCheckErrorDomain
                           code:FIRAppCheckErrorCodeUnknown
                       userInfo:userInfo];
   if (self) {

FirebaseAppCheck/Sources/Core/FIRAppCheck.m

@@ -22,6 +22,7 @@
 #import "FBLPromises.h"
 #endif
 
+#import "FirebaseAppCheck/Sources/Public/FirebaseAppCheck/FIRAppCheckErrors.h"
 #import "FirebaseAppCheck/Sources/Public/FirebaseAppCheck/FIRAppCheckProvider.h"
 #import "FirebaseAppCheck/Sources/Public/FirebaseAppCheck/FIRAppCheckProviderFactory.h"
 
@@ -171,7 +172,7 @@ - (instancetype)initWithAppName:(NSString *)appName
 + (instancetype)appCheck {
   FIRApp *defaultApp = [FIRApp defaultApp];
   if (!defaultApp) {
-    [NSException raise:kFIRAppCheckErrorDomain
+    [NSException raise:FIRAppCheckErrorDomain
                 format:@"The default FirebaseApp instance must be configured before the default"
                        @"AppCheck instance can be initialized. One way to ensure that is to "
                        @"call `[FIRApp configure];` (`FirebaseApp.configure()` in Swift) in the App"
@@ -186,6 +187,19 @@ + (nullable instancetype)appCheckWithApp:(FIRApp *)firebaseApp {
   return (FIRAppCheck *)appCheck;
 }
 
+- (void)tokenForcingRefresh:(BOOL)forcingRefresh
+                 completion:(void (^)(FIRAppCheckToken *_Nullable token,
+                                      NSError *_Nullable error))handler {
+  [self retrieveOrRefreshTokenForcingRefresh:forcingRefresh]
+      .then(^id _Nullable(FIRAppCheckToken *token) {
+        handler(token, nil);
+        return token;
+      })
+      .catch(^(NSError *_Nonnull error) {
+        handler(nil, [FIRAppCheckErrorUtil publicDomainErrorWithError:error]);
+      });
+}
+
 + (void)setAppCheckProviderFactory:(nullable id<FIRAppCheckProviderFactory>)factory {
   self.providerFactory = factory;
 }