firebase-admin 9.12.0 → 10.0.0

package/lib/auth/user-import-builder.d.ts

@@ -0,0 +1,322 @@
+/*! firebase-admin v10.0.0 */
+/*!
+ * Copyright 2018 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.
+ */
+/// <reference types="node" />
+import { FirebaseArrayIndexError } from '../app/index';
+import { UpdateMultiFactorInfoRequest, MultiFactorUpdateSettings } from './auth-config';
+export declare type HashAlgorithmType = 'SCRYPT' | 'STANDARD_SCRYPT' | 'HMAC_SHA512' | 'HMAC_SHA256' | 'HMAC_SHA1' | 'HMAC_MD5' | 'MD5' | 'PBKDF_SHA1' | 'BCRYPT' | 'PBKDF2_SHA256' | 'SHA512' | 'SHA256' | 'SHA1';
+/**
+   * Interface representing the user import options needed for
+   * {@link BaseAuth.importUsers} method. This is used to
+   * provide the password hashing algorithm information.
+   */
+export interface UserImportOptions {
+    /**
+     * The password hashing information.
+     */
+    hash: {
+        /**
+         * The password hashing algorithm identifier. The following algorithm
+         * identifiers are supported:
+         * `SCRYPT`, `STANDARD_SCRYPT`, `HMAC_SHA512`, `HMAC_SHA256`, `HMAC_SHA1`,
+         * `HMAC_MD5`, `MD5`, `PBKDF_SHA1`, `BCRYPT`, `PBKDF2_SHA256`, `SHA512`,
+         * `SHA256` and `SHA1`.
+         */
+        algorithm: HashAlgorithmType;
+        /**
+         * The signing key used in the hash algorithm in buffer bytes.
+         * Required by hashing algorithms `SCRYPT`, `HMAC_SHA512`, `HMAC_SHA256`,
+         * `HAMC_SHA1` and `HMAC_MD5`.
+         */
+        key?: Buffer;
+        /**
+         * The salt separator in buffer bytes which is appended to salt when
+         * verifying a password. This is only used by the `SCRYPT` algorithm.
+         */
+        saltSeparator?: Buffer;
+        /**
+         * The number of rounds for hashing calculation.
+         * Required for `SCRYPT`, `MD5`, `SHA512`, `SHA256`, `SHA1`, `PBKDF_SHA1` and
+         * `PBKDF2_SHA256`.
+         */
+        rounds?: number;
+        /**
+         * The memory cost required for `SCRYPT` algorithm, or the CPU/memory cost.
+         * Required for `STANDARD_SCRYPT` algorithm.
+         */
+        memoryCost?: number;
+        /**
+         * The parallelization of the hashing algorithm. Required for the
+         * `STANDARD_SCRYPT` algorithm.
+         */
+        parallelization?: number;
+        /**
+         * The block size (normally 8) of the hashing algorithm. Required for the
+         * `STANDARD_SCRYPT` algorithm.
+         */
+        blockSize?: number;
+        /**
+         * The derived key length of the hashing algorithm. Required for the
+         * `STANDARD_SCRYPT` algorithm.
+         */
+        derivedKeyLength?: number;
+    };
+}
+/**
+ * Interface representing a user to import to Firebase Auth via the
+ * {@link BaseAuth.importUsers} method.
+ */
+export interface UserImportRecord {
+    /**
+     * The user's `uid`.
+     */
+    uid: string;
+    /**
+     * The user's primary email, if set.
+     */
+    email?: string;
+    /**
+     * Whether or not the user's primary email is verified.
+     */
+    emailVerified?: boolean;
+    /**
+     * The user's display name.
+     */
+    displayName?: string;
+    /**
+     * The user's primary phone number, if set.
+     */
+    phoneNumber?: string;
+    /**
+     * The user's photo URL.
+     */
+    photoURL?: string;
+    /**
+     * Whether or not the user is disabled: `true` for disabled; `false` for
+     * enabled.
+     */
+    disabled?: boolean;
+    /**
+     * Additional metadata about the user.
+     */
+    metadata?: UserMetadataRequest;
+    /**
+     * An array of providers (for example, Google, Facebook) linked to the user.
+     */
+    providerData?: UserProviderRequest[];
+    /**
+     * The user's custom claims object if available, typically used to define
+     * user roles and propagated to an authenticated user's ID token.
+     */
+    customClaims?: {
+        [key: string]: any;
+    };
+    /**
+     * The buffer of bytes representing the user's hashed password.
+     * When a user is to be imported with a password hash,
+     * {@link UserImportOptions} are required to be
+     * specified to identify the hashing algorithm used to generate this hash.
+     */
+    passwordHash?: Buffer;
+    /**
+     * The buffer of bytes representing the user's password salt.
+     */
+    passwordSalt?: Buffer;
+    /**
+     * The identifier of the tenant where user is to be imported to.
+     * When not provided in an `admin.auth.Auth` context, the user is uploaded to
+     * the default parent project.
+     * When not provided in an `admin.auth.TenantAwareAuth` context, the user is uploaded
+     * to the tenant corresponding to that `TenantAwareAuth` instance's tenant ID.
+     */
+    tenantId?: string;
+    /**
+     * The user's multi-factor related properties.
+     */
+    multiFactor?: MultiFactorUpdateSettings;
+}
+/**
+ * User metadata to include when importing a user.
+ */
+export interface UserMetadataRequest {
+    /**
+     * The date the user last signed in, formatted as a UTC string.
+     */
+    lastSignInTime?: string;
+    /**
+     * The date the user was created, formatted as a UTC string.
+     */
+    creationTime?: string;
+}
+/**
+ * User provider data to include when importing a user.
+ */
+export interface UserProviderRequest {
+    /**
+     * The user identifier for the linked provider.
+     */
+    uid: string;
+    /**
+     * The display name for the linked provider.
+     */
+    displayName?: string;
+    /**
+     * The email for the linked provider.
+     */
+    email?: string;
+    /**
+     * The phone number for the linked provider.
+     */
+    phoneNumber?: string;
+    /**
+     * The photo URL for the linked provider.
+     */
+    photoURL?: string;
+    /**
+     * The linked provider ID (for example, "google.com" for the Google provider).
+     */
+    providerId: string;
+}
+/**
+   * Interface representing the response from the
+   * {@link BaseAuth.importUsers} method for batch
+   * importing users to Firebase Auth.
+   */
+export interface UserImportResult {
+    /**
+     * The number of user records that failed to import to Firebase Auth.
+     */
+    failureCount: number;
+    /**
+     * The number of user records that successfully imported to Firebase Auth.
+     */
+    successCount: number;
+    /**
+     * An array of errors corresponding to the provided users to import. The
+     * length of this array is equal to [`failureCount`](#failureCount).
+     */
+    errors: FirebaseArrayIndexError[];
+}
+/** Interface representing an Auth second factor in Auth server format. */
+export interface AuthFactorInfo {
+    mfaEnrollmentId?: string;
+    displayName?: string;
+    phoneInfo?: string;
+    enrolledAt?: string;
+    [key: string]: any;
+}
+/** UploadAccount endpoint request user interface. */
+interface UploadAccountUser {
+    localId: string;
+    email?: string;
+    emailVerified?: boolean;
+    displayName?: string;
+    disabled?: boolean;
+    photoUrl?: string;
+    phoneNumber?: string;
+    providerUserInfo?: Array<{
+        rawId: string;
+        providerId: string;
+        email?: string;
+        displayName?: string;
+        photoUrl?: string;
+    }>;
+    mfaInfo?: AuthFactorInfo[];
+    passwordHash?: string;
+    salt?: string;
+    lastLoginAt?: number;
+    createdAt?: number;
+    customAttributes?: string;
+    tenantId?: string;
+}
+/** UploadAccount endpoint request hash options. */
+export interface UploadAccountOptions {
+    hashAlgorithm?: string;
+    signerKey?: string;
+    rounds?: number;
+    memoryCost?: number;
+    saltSeparator?: string;
+    cpuMemCost?: number;
+    parallelization?: number;
+    blockSize?: number;
+    dkLen?: number;
+}
+/** UploadAccount endpoint complete request interface. */
+export interface UploadAccountRequest extends UploadAccountOptions {
+    users?: UploadAccountUser[];
+}
+/** Callback function to validate an UploadAccountUser object. */
+export declare type ValidatorFunction = (data: UploadAccountUser) => void;
+/**
+ * Converts a client format second factor object to server format.
+ * @param multiFactorInfo - The client format second factor.
+ * @returns The corresponding AuthFactorInfo server request format.
+ */
+export declare function convertMultiFactorInfoToServerFormat(multiFactorInfo: UpdateMultiFactorInfoRequest): AuthFactorInfo;
+/**
+ * Class that provides a helper for building/validating uploadAccount requests and
+ * UserImportResult responses.
+ */
+export declare class UserImportBuilder {
+    private requiresHashOptions;
+    private validatedUsers;
+    private validatedOptions;
+    private indexMap;
+    private userImportResultErrors;
+    /**
+     * @param {UserImportRecord[]} users The list of user records to import.
+     * @param {UserImportOptions=} options The import options which includes hashing
+     *     algorithm details.
+     * @param {ValidatorFunction=} userRequestValidator The user request validator function.
+     * @constructor
+     */
+    constructor(users: UserImportRecord[], options?: UserImportOptions, userRequestValidator?: ValidatorFunction);
+    /**
+     * Returns the corresponding constructed uploadAccount request.
+     * @returns {UploadAccountRequest} The constructed uploadAccount request.
+     */
+    buildRequest(): UploadAccountRequest;
+    /**
+     * Populates the UserImportResult using the client side detected errors and the server
+     * side returned errors.
+     * @returns {UserImportResult} The user import result based on the returned failed
+     *     uploadAccount response.
+     */
+    buildResponse(failedUploads: Array<{
+        index: number;
+        message: string;
+    }>): UserImportResult;
+    /**
+     * Validates and returns the hashing options of the uploadAccount request.
+     * Throws an error whenever an invalid or missing options is detected.
+     * @param {UserImportOptions} options The UserImportOptions.
+     * @param {boolean} requiresHashOptions Whether to require hash options.
+     * @returns {UploadAccountOptions} The populated UploadAccount options.
+     */
+    private populateOptions;
+    /**
+     * Validates and returns the users list of the uploadAccount request.
+     * Whenever a user with an error is detected, the error is cached and will later be
+     * merged into the user import result. This allows the processing of valid users without
+     * failing early on the first error detected.
+     * @param {UserImportRecord[]} users The UserImportRecords to convert to UnploadAccountUser
+     *     objects.
+     * @param {ValidatorFunction=} userValidator The user validator function.
+     * @returns {UploadAccountUser[]} The populated uploadAccount users.
+     */
+    private populateUsers;
+}
+export {};

package/lib/auth/user-import-builder.js

@@ -1,4 +1,4 @@
-/*! firebase-admin v9.12.0 */
+/*! firebase-admin v10.0.0 */
 "use strict";
 /*!
  * Copyright 2018 Google Inc.
@@ -23,8 +23,8 @@ var validator = require("../utils/validator");
 var error_1 = require("../utils/error");
 /**
  * Converts a client format second factor object to server format.
- * @param multiFactorInfo The client format second factor.
- * @return The corresponding AuthFactorInfo server request format.
+ * @param multiFactorInfo - The client format second factor.
+ * @returns The corresponding AuthFactorInfo server request format.
  */
 function convertMultiFactorInfoToServerFormat(multiFactorInfo) {
     var enrolledAt;
@@ -67,7 +67,7 @@ function isPhoneFactor(multiFactorInfo) {
 /**
  * @param {any} obj The object to check for number field within.
  * @param {string} key The entry key.
- * @return {number} The corresponding number if available. Otherwise, NaN.
+ * @returns {number} The corresponding number if available. Otherwise, NaN.
  */
 function getNumberField(obj, key) {
     if (typeof obj[key] !== 'undefined' && obj[key] !== null) {
@@ -80,7 +80,7 @@ function getNumberField(obj, key) {
  * fields are provided.
  * @param {UserImportRecord} user The UserImportRecord to conver to UploadAccountUser.
  * @param {ValidatorFunction=} userValidator The user validator function.
- * @return {UploadAccountUser} The corresponding UploadAccountUser to return.
+ * @returns {UploadAccountUser} The corresponding UploadAccountUser to return.
  */
 function populateUploadAccountUser(user, userValidator) {
     var result = {
@@ -176,7 +176,7 @@ var UserImportBuilder = /** @class */ (function () {
     }
     /**
      * Returns the corresponding constructed uploadAccount request.
-     * @return {UploadAccountRequest} The constructed uploadAccount request.
+     * @returns {UploadAccountRequest} The constructed uploadAccount request.
      */
     UserImportBuilder.prototype.buildRequest = function () {
         var users = this.validatedUsers.map(function (user) {
@@ -187,7 +187,7 @@ var UserImportBuilder = /** @class */ (function () {
     /**
      * Populates the UserImportResult using the client side detected errors and the server
      * side returned errors.
-     * @return {UserImportResult} The user import result based on the returned failed
+     * @returns {UserImportResult} The user import result based on the returned failed
      *     uploadAccount response.
      */
     UserImportBuilder.prototype.buildResponse = function (failedUploads) {
@@ -219,7 +219,7 @@ var UserImportBuilder = /** @class */ (function () {
      * Throws an error whenever an invalid or missing options is detected.
      * @param {UserImportOptions} options The UserImportOptions.
      * @param {boolean} requiresHashOptions Whether to require hash options.
-     * @return {UploadAccountOptions} The populated UploadAccount options.
+     * @returns {UploadAccountOptions} The populated UploadAccount options.
      */
     UserImportBuilder.prototype.populateOptions = function (options, requiresHashOptions) {
         var populatedOptions;
@@ -356,7 +356,7 @@ var UserImportBuilder = /** @class */ (function () {
      * @param {UserImportRecord[]} users The UserImportRecords to convert to UnploadAccountUser
      *     objects.
      * @param {ValidatorFunction=} userValidator The user validator function.
-     * @return {UploadAccountUser[]} The populated uploadAccount users.
+     * @returns {UploadAccountUser[]} The populated uploadAccount users.
      */
     UserImportBuilder.prototype.populateUsers = function (users, userValidator) {
         var _this = this;

package/lib/auth/user-record.d.ts

@@ -0,0 +1,265 @@
+/*! firebase-admin v10.0.0 */
+/*!
+ * @license
+ * Copyright 2017 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.
+ */
+export interface MultiFactorInfoResponse {
+    mfaEnrollmentId: string;
+    displayName?: string;
+    phoneInfo?: string;
+    enrolledAt?: string;
+    [key: string]: any;
+}
+export interface ProviderUserInfoResponse {
+    rawId: string;
+    displayName?: string;
+    email?: string;
+    photoUrl?: string;
+    phoneNumber?: string;
+    providerId: string;
+    federatedId?: string;
+}
+export interface GetAccountInfoUserResponse {
+    localId: string;
+    email?: string;
+    emailVerified?: boolean;
+    phoneNumber?: string;
+    displayName?: string;
+    photoUrl?: string;
+    disabled?: boolean;
+    passwordHash?: string;
+    salt?: string;
+    customAttributes?: string;
+    validSince?: string;
+    tenantId?: string;
+    providerUserInfo?: ProviderUserInfoResponse[];
+    mfaInfo?: MultiFactorInfoResponse[];
+    createdAt?: string;
+    lastLoginAt?: string;
+    lastRefreshAt?: string;
+    [key: string]: any;
+}
+/**
+ * Interface representing the common properties of a user-enrolled second factor.
+ */
+export declare abstract class MultiFactorInfo {
+    /**
+     * The ID of the enrolled second factor. This ID is unique to the user.
+     */
+    readonly uid: string;
+    /**
+     * The optional display name of the enrolled second factor.
+     */
+    readonly displayName?: string;
+    /**
+     * The type identifier of the second factor. For SMS second factors, this is `phone`.
+     */
+    readonly factorId: string;
+    /**
+     * The optional date the second factor was enrolled, formatted as a UTC string.
+     */
+    readonly enrollmentTime?: string;
+    /**
+     * Returns a JSON-serializable representation of this object.
+     *
+     * @returns A JSON-serializable representation of this object.
+     */
+    toJSON(): object;
+    /**
+     * Initializes the MultiFactorInfo object using the provided server response.
+     *
+     * @param response - The server side response.
+     */
+    private initFromServerResponse;
+}
+/**
+ * Interface representing a phone specific user-enrolled second factor.
+ */
+export declare class PhoneMultiFactorInfo extends MultiFactorInfo {
+    /**
+     * The phone number associated with a phone second factor.
+     */
+    readonly phoneNumber: string;
+    /**
+     * {@inheritdoc MultiFactorInfo.toJSON}
+     */
+    toJSON(): object;
+}
+/**
+ * The multi-factor related user settings.
+ */
+export declare class MultiFactorSettings {
+    /**
+     * List of second factors enrolled with the current user.
+     * Currently only phone second factors are supported.
+     */
+    enrolledFactors: MultiFactorInfo[];
+    /**
+     * Returns a JSON-serializable representation of this multi-factor object.
+     *
+     * @returns A JSON-serializable representation of this multi-factor object.
+     */
+    toJSON(): object;
+}
+/**
+ * Represents a user's metadata.
+ */
+export declare class UserMetadata {
+    /**
+     * The date the user was created, formatted as a UTC string.
+     */
+    readonly creationTime: string;
+    /**
+     * The date the user last signed in, formatted as a UTC string.
+     */
+    readonly lastSignInTime: string;
+    /**
+     * The time at which the user was last active (ID token refreshed),
+     * formatted as a UTC Date string (eg 'Sat, 03 Feb 2001 04:05:06 GMT').
+     * Returns null if the user was never active.
+     */
+    readonly lastRefreshTime?: string | null;
+    /**
+     * Returns a JSON-serializable representation of this object.
+     *
+     * @returns A JSON-serializable representation of this object.
+     */
+    toJSON(): object;
+}
+/**
+ * Represents a user's info from a third-party identity provider
+ * such as Google or Facebook.
+ */
+export declare class UserInfo {
+    /**
+     * The user identifier for the linked provider.
+     */
+    readonly uid: string;
+    /**
+     * The display name for the linked provider.
+     */
+    readonly displayName: string;
+    /**
+     * The email for the linked provider.
+     */
+    readonly email: string;
+    /**
+     * The photo URL for the linked provider.
+     */
+    readonly photoURL: string;
+    /**
+     * The linked provider ID (for example, "google.com" for the Google provider).
+     */
+    readonly providerId: string;
+    /**
+     * The phone number for the linked provider.
+     */
+    readonly phoneNumber: string;
+    /**
+     * Returns a JSON-serializable representation of this object.
+     *
+     * @returns A JSON-serializable representation of this object.
+     */
+    toJSON(): object;
+}
+/**
+ * Represents a user.
+ */
+export declare class UserRecord {
+    /**
+     * The user's `uid`.
+     */
+    readonly uid: string;
+    /**
+     * The user's primary email, if set.
+     */
+    readonly email?: string;
+    /**
+     * Whether or not the user's primary email is verified.
+     */
+    readonly emailVerified: boolean;
+    /**
+     * The user's display name.
+     */
+    readonly displayName?: string;
+    /**
+     * The user's photo URL.
+     */
+    readonly photoURL?: string;
+    /**
+     * The user's primary phone number, if set.
+     */
+    readonly phoneNumber?: string;
+    /**
+     * Whether or not the user is disabled: `true` for disabled; `false` for
+     * enabled.
+     */
+    readonly disabled: boolean;
+    /**
+     * Additional metadata about the user.
+     */
+    readonly metadata: UserMetadata;
+    /**
+     * An array of providers (for example, Google, Facebook) linked to the user.
+     */
+    readonly providerData: UserInfo[];
+    /**
+     * The user's hashed password (base64-encoded), only if Firebase Auth hashing
+     * algorithm (SCRYPT) is used. If a different hashing algorithm had been used
+     * when uploading this user, as is typical when migrating from another Auth
+     * system, this will be an empty string. If no password is set, this is
+     * null. This is only available when the user is obtained from
+     * {@link BaseAuth.listUsers}.
+     */
+    readonly passwordHash?: string;
+    /**
+     * The user's password salt (base64-encoded), only if Firebase Auth hashing
+     * algorithm (SCRYPT) is used. If a different hashing algorithm had been used to
+     * upload this user, typical when migrating from another Auth system, this will
+     * be an empty string. If no password is set, this is null. This is only
+     * available when the user is obtained from {@link BaseAuth.listUsers}.
+     */
+    readonly passwordSalt?: string;
+    /**
+     * The user's custom claims object if available, typically used to define
+     * user roles and propagated to an authenticated user's ID token.
+     * This is set via {@link BaseAuth.setCustomUserClaims}
+     */
+    readonly customClaims?: {
+        [key: string]: any;
+    };
+    /**
+     * The ID of the tenant the user belongs to, if available.
+     */
+    readonly tenantId?: string | null;
+    /**
+     * The date the user's tokens are valid after, formatted as a UTC string.
+     * This is updated every time the user's refresh token are revoked either
+     * from the {@link BaseAuth.revokeRefreshTokens}
+     * API or from the Firebase Auth backend on big account changes (password
+     * resets, password or email updates, etc).
+     */
+    readonly tokensValidAfterTime?: string;
+    /**
+     * The multi-factor related properties for the current user, if available.
+     */
+    readonly multiFactor?: MultiFactorSettings;
+    /**
+     * Returns a JSON-serializable representation of this object.
+     *
+     * @returns A JSON-serializable representation of this object.
+     */
+    toJSON(): object;
+}