feat(auth): implements auth.setCustomUserClaims and auth.listUsers. (#86)

* feat(auth): implements auth.setCustomUserClaims and auth.listUsers.

Adds all relevant unit tests and integration tests.

* Applied various fixes based on PR review feedback.

* Improves error message for custom claims argument error.

Author: bojeil-google

src/auth/auth-api-request.ts

@@ -41,6 +41,19 @@ const FIREBASE_AUTH_HEADER = {
 const FIREBASE_AUTH_TIMEOUT = 10000;
 
 
+/** List of reserved claims which cannot be provided when creating a custom token. */
+export const RESERVED_CLAIMS = [
+  'acr', 'amr', 'at_hash', 'aud', 'auth_time', 'azp', 'cnf', 'c_hash', 'exp', 'iat',
+  'iss', 'jti', 'nbf', 'nonce', 'sub', 'firebase',
+];
+
+/** Maximum allowed number of characters in the custom claims payload. */
+const MAX_CLAIMS_PAYLOAD_SIZE = 1000;
+
+/** Maximum allowed number of users to batch download at one time. */
+const MAX_DOWNLOAD_ACCOUNT_PAGE_SIZE = 1000;
+
+
 /**
  * Validates a create/edit request object. All unsupported parameters
  * are removed from the original request. If an invalid field is passed
@@ -64,6 +77,7 @@ function validateCreateEditRequest(request: any) {
       deleteProvider: true,
       sanityCheck: true,
       phoneNumber: true,
+      customAttributes: true,
     };
     // Remove invalid keys from original request.
     for (let key in request) {
@@ -127,9 +141,67 @@ function validateCreateEditRequest(request: any) {
       // disabled externally. So the error message should use the client facing name.
       throw new FirebaseAuthError(AuthClientErrorCode.INVALID_DISABLED_FIELD);
     }
+    // customAttributes should be stringified JSON with no blacklisted claims.
+    // The payload should not exceed 1KB.
+    if (typeof request.customAttributes !== 'undefined') {
+      let developerClaims;
+      try {
+        developerClaims = JSON.parse(request.customAttributes);
+      } catch (error) {
+        // JSON parsing error. This should never happen as we stringify the claims internally.
+        // However, we still need to check since setAccountInfo via edit requests could pass
+        // this field.
+        throw new FirebaseAuthError(AuthClientErrorCode.INVALID_CLAIMS, error.message);
+      }
+      const invalidClaims = [];
+      // Check for any invalid claims.
+      RESERVED_CLAIMS.forEach((blacklistedClaim) => {
+        if (developerClaims.hasOwnProperty(blacklistedClaim)) {
+          invalidClaims.push(blacklistedClaim);
+        }
+      });
+      // Throw an error if an invalid claim is detected.
+      if (invalidClaims.length > 0) {
+        throw new FirebaseAuthError(
+          AuthClientErrorCode.FORBIDDEN_CLAIM,
+          invalidClaims.length > 1 ?
+          `Developer claims "${invalidClaims.join('", "')}" are reserved and cannot be specified.` :
+          `Developer claim "${invalidClaims[0]}" is reserved and cannot be specified.`,
+        );
+      }
+      // Check claims payload does not exceed maxmimum size.
+      if (request.customAttributes.length > MAX_CLAIMS_PAYLOAD_SIZE) {
+        throw new FirebaseAuthError(
+          AuthClientErrorCode.CLAIMS_TOO_LARGE,
+          `Developer claims payload should not exceed ${MAX_CLAIMS_PAYLOAD_SIZE} characters.`,
+        );
+      }
+    }
 };
 
 
+/** Instantiates the downloadAccount endpoint settings. */
+export const FIREBASE_AUTH_DOWNLOAD_ACCOUNT = new ApiSettings('downloadAccount', 'POST')
+  // Set request validator.
+  .setRequestValidator((request: any) => {
+    // Validate next page token.
+    if (typeof request.nextPageToken !== 'undefined' &&
+        !validator.isNonEmptyString(request.nextPageToken)) {
+      throw new FirebaseAuthError(AuthClientErrorCode.INVALID_PAGE_TOKEN);
+    }
+    // Validate max results.
+    if (!validator.isNumber(request.maxResults) ||
+        request.maxResults <= 0 ||
+        request.maxResults > MAX_DOWNLOAD_ACCOUNT_PAGE_SIZE) {
+      throw new FirebaseAuthError(
+        AuthClientErrorCode.INVALID_ARGUMENT,
+        `Required "maxResults" must be a positive non-zero number that does not exceed ` +
+        `the allowed ${MAX_DOWNLOAD_ACCOUNT_PAGE_SIZE}.`
+      );
+    }
+  });
+
+
 /** Instantiates the getAccountInfo endpoint settings. */
 export const FIREBASE_AUTH_GET_ACCOUNT_INFO = new ApiSettings('getAccountInfo', 'POST')
   // Set request validator.
@@ -185,6 +257,13 @@ export const FIREBASE_AUTH_SET_ACCOUNT_INFO = new ApiSettings('setAccountInfo',
 export const FIREBASE_AUTH_SIGN_UP_NEW_USER = new ApiSettings('signupNewUser', 'POST')
   // Set request validator.
   .setRequestValidator((request: any) => {
+    // signupNewUser does not support customAttributes.
+    if (typeof request.customAttributes !== 'undefined') {
+      throw new FirebaseAuthError(
+        AuthClientErrorCode.INVALID_ARGUMENT,
+        `"customAttributes" cannot be set when creating a new user.`,
+      );
+    }
     validateCreateEditRequest(request);
   })
   // Set response validator.
@@ -275,6 +354,40 @@ export class FirebaseAuthRequestHandler {
     return this.invokeRequestHandler(FIREBASE_AUTH_GET_ACCOUNT_INFO, request);
   }
 
+  /**
+   * Exports the users (single batch only) with a size of maxResults and starting from
+   * the offset as specified by pageToken.
+   *
+   * @param {number=} maxResults The page size, 1000 if undefined. This is also the maximum
+   *     allowed limit.
+   * @param {string=} pageToken The next page token. If not specified, returns users starting
+   *     without any offset. Users are returned in the order they were created from oldest to
+   *     newest, relative to the page token offset.
+   * @return {Promise<Object>} A promise that resolves with the current batch of downloaded
+   *     users and the next page token if available. For the last page, an empty list of users
+   *     and no page token are returned.
+   */
+  public downloadAccount(
+      maxResults: number = MAX_DOWNLOAD_ACCOUNT_PAGE_SIZE,
+      pageToken?: string): Promise<{users: Object[], nextPageToken?: string}> {
+    // Construct request.
+    const request = {
+      maxResults,
+      nextPageToken: pageToken,
+    };
+    // Remove next page token if not provided.
+    if (typeof request.nextPageToken === 'undefined') {
+      delete request.nextPageToken;
+    }
+    return this.invokeRequestHandler(FIREBASE_AUTH_DOWNLOAD_ACCOUNT, request)
+        .then((response: any) => {
+          // No more users available.
+          if (!response.users) {
+            response.users = [];
+          }
+          return response as {users: Object[], nextPageToken?: string};
+        });
+  }
 
   /**
    * Deletes an account identified by a uid.
@@ -293,6 +406,41 @@ export class FirebaseAuthRequestHandler {
     return this.invokeRequestHandler(FIREBASE_AUTH_DELETE_ACCOUNT, request);
   }
 
+  /**
+   * Sets additional developer claims on an existing user identified by provided UID.
+   *
+   * @param {string} uid The user to edit.
+   * @param {Object} customUserClaims The developer claims to set.
+   * @return {Promise<string>} A promise that resolves when the operation completes
+   *     with the user id that was edited.
+   */
+  public setCustomUserClaims(uid: string, customUserClaims: Object): Promise<string> {
+    // Validate user UID.
+    if (!validator.isUid(uid)) {
+      return Promise.reject(new FirebaseAuthError(AuthClientErrorCode.INVALID_UID));
+    } else if (!validator.isObject(customUserClaims)) {
+      return Promise.reject(
+        new FirebaseAuthError(
+          AuthClientErrorCode.INVALID_ARGUMENT,
+          'CustomUserClaims argument must be an object or null.',
+        ),
+      );
+    }
+    // Delete operation. Replace null with an empty object.
+    if (customUserClaims === null) {
+      customUserClaims = {};
+    }
+    // Construct custom user attribute editting request.
+    let request: any = {
+      localId: uid,
+      customAttributes: JSON.stringify(customUserClaims),
+    };
+    return this.invokeRequestHandler(FIREBASE_AUTH_SET_ACCOUNT_INFO, request)
+        .then((response: any) => {
+          return response.localId as string;
+        });
+  }
+
   /**
    * Edits an existing user.
    *

src/auth/auth.ts

@@ -41,6 +41,13 @@ export class AuthInternals implements FirebaseServiceInternalsInterface {
 }
 
 
+/** Response object for a listUsers operation. */
+export interface ListUsersResult {
+  users: UserRecord[];
+  pageToken?: string;
+}
+
+
 /**
  * Auth service bound to the provided app.
  */
@@ -178,6 +185,40 @@ class Auth implements FirebaseServiceInterface {
       });
   };
 
+  /**
+   * Exports a batch of user accounts. Batch size is determined by the maxResults argument.
+   * Starting point of the batch is determined by the pageToken argument.
+   *
+   * @param {number=} maxResults The page size, 1000 if undefined. This is also the maximum
+   *     allowed limit.
+   * @param {string=} pageToken The next page token. If not specified, returns users starting
+   *     without any offset.
+   * @return {Promise<{users: UserRecord[], pageToken?: string}>} A promise that resolves with
+   *     the current batch of downloaded users and the next page token. For the last page, an
+   *     empty list of users and no page token are returned.
+   */
+  public listUsers(maxResults?: number, pageToken?: string): Promise<ListUsersResult> {
+    return this.authRequestHandler.downloadAccount(maxResults, pageToken)
+      .then((response: any) => {
+        // List of users to return.
+        const users: UserRecord[] = [];
+        // Convert each user response to a UserRecord.
+        response.users.forEach((userResponse) => {
+          users.push(new UserRecord(userResponse));
+        });
+        // Return list of user records and the next page token if available.
+        let result = {
+          users,
+          pageToken: response.nextPageToken,
+        };
+        // Delete result.pageToken if undefined.
+        if (typeof result.pageToken === 'undefined') {
+          delete result.pageToken;
+        }
+        return result;
+      });
+  };
+
   /**
    * Creates a new user with the properties provided.
    *
@@ -229,6 +270,21 @@ class Auth implements FirebaseServiceInterface {
         return this.getUser(existingUid);
       });
   };
+
+  /**
+   * Sets additional developer claims on an existing user identified by the provided UID.
+   *
+   * @param {string} uid The user to edit.
+   * @param {Object} customUserClaims The developer claims to set.
+   * @return {Promise<void>} A promise that resolves when the operation completes
+   *     successfully.
+   */
+  public setCustomUserClaims(uid: string, customUserClaims: Object): Promise<void> {
+    return this.authRequestHandler.setCustomUserClaims(uid, customUserClaims)
+      .then((existingUid) => {
+        // Return nothing on success.
+      });
+  };
 };
 
 

src/auth/user-record.ts

@@ -14,6 +14,7 @@
  * limitations under the License.
  */
 
+import {deepCopy} from '../utils/deep-copy';
 import * as utils from '../utils';
 import {AuthClientErrorCode, FirebaseAuthError} from '../utils/error';
 
@@ -144,6 +145,9 @@ export class UserRecord {
   public readonly disabled: boolean;
   public readonly metadata: UserMetadata;
   public readonly providerData: UserInfo[];
+  public readonly passwordHash?: string;
+  public readonly passwordSalt?: string;
+  public readonly customClaims: Object;
 
   constructor(response: any) {
     // The Firebase user id is required.
@@ -167,6 +171,15 @@ export class UserRecord {
       providerData.push(new UserInfo(entry));
     }
     utils.addReadonlyGetter(this, 'providerData', providerData);
+    utils.addReadonlyGetter(this, 'passwordHash', response.passwordHash);
+    utils.addReadonlyGetter(this, 'passwordSalt', response.salt);
+    try {
+      utils.addReadonlyGetter(
+          this, 'customClaims', JSON.parse(response.customAttributes));
+    } catch (e) {
+      // Ignore error.
+      utils.addReadonlyGetter(this, 'customClaims', undefined);
+    }
   }
 
   /** @return {Object} The plain object representation of the user record. */
@@ -181,6 +194,9 @@ export class UserRecord {
       disabled: this.disabled,
       // Convert metadata to json.
       metadata: this.metadata.toJSON(),
+      passwordHash: this.passwordHash,
+      passwordSalt: this.passwordSalt,
+      customClaims: deepCopy(this.customClaims),
     };
     json.providerData = [];
     for (let entry of this.providerData) {

src/index.d.ts

@@ -99,6 +99,9 @@ declare namespace admin.auth {
     disabled: boolean;
     metadata: admin.auth.UserMetadata;
     providerData: admin.auth.UserInfo[];
+    passwordHash?: string;
+    passwordSalt?: string;
+    customClaims?: Object;
 
     toJSON(): Object;
   }
@@ -135,6 +138,11 @@ declare namespace admin.auth {
     [key: string]: any;
   }
 
+  interface ListUsersResult {
+    users: admin.auth.UserRecord[];
+    pageToken?: string;
+  }
+
   interface Auth {
     app: admin.app.App;
 
@@ -144,8 +152,10 @@ declare namespace admin.auth {
     getUser(uid: string): Promise<admin.auth.UserRecord>;
     getUserByEmail(email: string): Promise<admin.auth.UserRecord>;
     getUserByPhoneNumber(phoneNumber: string): Promise<admin.auth.UserRecord>;
+    listUsers(maxResults?: number, pageToken?: string): Promise<admin.auth.ListUsersResult>;
     updateUser(uid: string, properties: admin.auth.UpdateRequest): Promise<admin.auth.UserRecord>;
     verifyIdToken(idToken: string): Promise<admin.auth.DecodedIdToken>;
+    setCustomUserClaims(uid: string, customUserClaims: Object): Promise<void>;
   }
 }