1 | /**
|
2 | * @license
|
3 | * Copyright 2019 Google LLC
|
4 | *
|
5 | * Licensed under the Apache License, Version 2.0 (the "License");
|
6 | * you may not use this file except in compliance with the License.
|
7 | * You may obtain a copy of the License at
|
8 | *
|
9 | * http://www.apache.org/licenses/LICENSE-2.0
|
10 | *
|
11 | * Unless required by applicable law or agreed to in writing, software
|
12 | * distributed under the License is distributed on an "AS IS" BASIS,
|
13 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
14 | * See the License for the specific language governing permissions and
|
15 | * limitations under the License.
|
16 | */
|
17 | import { FirebaseApp } from '@firebase/app';
|
18 | import { CompleteFn, ErrorFn, FirebaseError, NextFn, Observer, Unsubscribe } from '@firebase/util';
|
19 | import { FactorId as FactorIdMap, OperationType as OperationTypeMap, ActionCodeOperation as ActionCodeOperationMap } from './enum_maps';
|
20 | export { CompleteFn, ErrorFn, NextFn, Unsubscribe };
|
21 | /**
|
22 | * Interface representing the `Auth` config.
|
23 | *
|
24 | * @public
|
25 | */
|
26 | export interface Config {
|
27 | /**
|
28 | * The API Key used to communicate with the Firebase Auth backend.
|
29 | */
|
30 | apiKey: string;
|
31 | /**
|
32 | * The host at which the Firebase Auth backend is running.
|
33 | */
|
34 | apiHost: string;
|
35 | /**
|
36 | * The scheme used to communicate with the Firebase Auth backend.
|
37 | */
|
38 | apiScheme: string;
|
39 | /**
|
40 | * The host at which the Secure Token API is running.
|
41 | */
|
42 | tokenApiHost: string;
|
43 | /**
|
44 | * The SDK Client Version.
|
45 | */
|
46 | sdkClientVersion: string;
|
47 | /**
|
48 | * The domain at which the web widgets are hosted (provided via Firebase Config).
|
49 | */
|
50 | authDomain?: string;
|
51 | }
|
52 | /**
|
53 | * Interface representing reCAPTCHA parameters.
|
54 | *
|
55 | * See the [reCAPTCHA docs](https://developers.google.com/recaptcha/docs/display#render_param)
|
56 | * for the list of accepted parameters. All parameters are accepted except for `sitekey`: Firebase Auth
|
57 | * provisions a reCAPTCHA for each project and will configure the site key upon rendering.
|
58 | *
|
59 | * For an invisible reCAPTCHA, set the `size` key to `invisible`.
|
60 | *
|
61 | * @public
|
62 | */
|
63 | export interface RecaptchaParameters {
|
64 | [key: string]: any;
|
65 | }
|
66 | /**
|
67 | * Interface representing a parsed ID token.
|
68 | *
|
69 | * @privateRemarks TODO(avolkovi): consolidate with parsed_token in implementation.
|
70 | *
|
71 | * @public
|
72 | */
|
73 | export interface ParsedToken {
|
74 | /** Expiration time of the token. */
|
75 | 'exp'?: string;
|
76 | /** UID of the user. */
|
77 | 'sub'?: string;
|
78 | /** Time at which authentication was performed. */
|
79 | 'auth_time'?: string;
|
80 | /** Issuance time of the token. */
|
81 | 'iat'?: string;
|
82 | /** Firebase specific claims, containing the provider(s) used to authenticate the user. */
|
83 | 'firebase'?: {
|
84 | 'sign_in_provider'?: string;
|
85 | 'sign_in_second_factor'?: string;
|
86 | 'identities'?: Record<string, string>;
|
87 | };
|
88 | /** Map of any additional custom claims. */
|
89 | [key: string]: string | object | undefined;
|
90 | }
|
91 | /**
|
92 | * Type definition for an event callback.
|
93 | *
|
94 | * @privateRemarks TODO(avolkovi): should we consolidate with Subscribe<T> since we're changing the API anyway?
|
95 | *
|
96 | * @public
|
97 | */
|
98 | export declare type NextOrObserver<T> = NextFn<T | null> | Observer<T | null>;
|
99 | /**
|
100 | * Interface for an `Auth` error.
|
101 | *
|
102 | * @public
|
103 | */
|
104 | export interface AuthError extends FirebaseError {
|
105 | /** Details about the Firebase Auth error. */
|
106 | readonly customData: {
|
107 | /** The name of the Firebase App which triggered this error. */
|
108 | readonly appName: string;
|
109 | /** The email address of the user's account, used for sign-in and linking. */
|
110 | readonly email?: string;
|
111 | /** The phone number of the user's account, used for sign-in and linking. */
|
112 | readonly phoneNumber?: string;
|
113 | /**
|
114 | * The tenant ID being used for sign-in and linking.
|
115 | *
|
116 | * @remarks
|
117 | * If you use {@link signInWithRedirect} to sign in,
|
118 | * you have to set the tenant ID on the {@link Auth} instance again as the tenant ID is not persisted
|
119 | * after redirection.
|
120 | */
|
121 | readonly tenantId?: string;
|
122 | };
|
123 | }
|
124 | /**
|
125 | * Interface representing an {@link Auth} instance's settings.
|
126 | *
|
127 | * @remarks Currently used for enabling/disabling app verification for phone Auth testing.
|
128 | *
|
129 | * @public
|
130 | */
|
131 | export interface AuthSettings {
|
132 | /**
|
133 | * When set, this property disables app verification for the purpose of testing phone
|
134 | * authentication. For this property to take effect, it needs to be set before rendering a
|
135 | * reCAPTCHA app verifier. When this is disabled, a mock reCAPTCHA is rendered instead. This is
|
136 | * useful for manual testing during development or for automated integration tests.
|
137 | *
|
138 | * In order to use this feature, you will need to
|
139 | * {@link https://firebase.google.com/docs/auth/web/phone-auth#test-with-whitelisted-phone-numbers | whitelist your phone number}
|
140 | * via the Firebase Console.
|
141 | *
|
142 | * The default value is false (app verification is enabled).
|
143 | */
|
144 | appVerificationDisabledForTesting: boolean;
|
145 | }
|
146 | /**
|
147 | * Interface representing Firebase Auth service.
|
148 | *
|
149 | * @remarks
|
150 | * See {@link https://firebase.google.com/docs/auth/ | Firebase Authentication} for a full guide
|
151 | * on how to use the Firebase Auth service.
|
152 | *
|
153 | * @public
|
154 | */
|
155 | export interface Auth {
|
156 | /** The {@link @firebase/app#FirebaseApp} associated with the `Auth` service instance. */
|
157 | readonly app: FirebaseApp;
|
158 | /** The name of the app associated with the `Auth` service instance. */
|
159 | readonly name: string;
|
160 | /** The {@link Config} used to initialize this instance. */
|
161 | readonly config: Config;
|
162 | /**
|
163 | * Changes the type of persistence on the `Auth` instance.
|
164 | *
|
165 | * @remarks
|
166 | * This will affect the currently saved Auth session and applies this type of persistence for
|
167 | * future sign-in requests, including sign-in with redirect requests.
|
168 | *
|
169 | * This makes it easy for a user signing in to specify whether their session should be
|
170 | * remembered or not. It also makes it easier to never persist the Auth state for applications
|
171 | * that are shared by other users or have sensitive data.
|
172 | *
|
173 | * @example
|
174 | * ```javascript
|
175 | * auth.setPersistence(browserSessionPersistence);
|
176 | * ```
|
177 | *
|
178 | * @param persistence - The {@link Persistence} to use.
|
179 | */
|
180 | setPersistence(persistence: Persistence): Promise<void>;
|
181 | /**
|
182 | * The {@link Auth} instance's language code.
|
183 | *
|
184 | * @remarks
|
185 | * This is a readable/writable property. When set to null, the default Firebase Console language
|
186 | * setting is applied. The language code will propagate to email action templates (password
|
187 | * reset, email verification and email change revocation), SMS templates for phone authentication,
|
188 | * reCAPTCHA verifier and OAuth popup/redirect operations provided the specified providers support
|
189 | * localization with the language code specified.
|
190 | */
|
191 | languageCode: string | null;
|
192 | /**
|
193 | * The {@link Auth} instance's tenant ID.
|
194 | *
|
195 | * @remarks
|
196 | * This is a readable/writable property. When you set the tenant ID of an {@link Auth} instance, all
|
197 | * future sign-in/sign-up operations will pass this tenant ID and sign in or sign up users to
|
198 | * the specified tenant project. When set to null, users are signed in to the parent project.
|
199 | *
|
200 | * @example
|
201 | * ```javascript
|
202 | * // Set the tenant ID on Auth instance.
|
203 | * auth.tenantId = 'TENANT_PROJECT_ID';
|
204 | *
|
205 | * // All future sign-in request now include tenant ID.
|
206 | * const result = await signInWithEmailAndPassword(auth, email, password);
|
207 | * // result.user.tenantId should be 'TENANT_PROJECT_ID'.
|
208 | * ```
|
209 | *
|
210 | * @defaultValue null
|
211 | */
|
212 | tenantId: string | null;
|
213 | /**
|
214 | * The {@link Auth} instance's settings.
|
215 | *
|
216 | * @remarks
|
217 | * This is used to edit/read configuration related options such as app verification mode for
|
218 | * phone authentication.
|
219 | */
|
220 | readonly settings: AuthSettings;
|
221 | /**
|
222 | * Adds an observer for changes to the user's sign-in state.
|
223 | *
|
224 | * @remarks
|
225 | * To keep the old behavior, see {@link Auth.onIdTokenChanged}.
|
226 | *
|
227 | * @param nextOrObserver - callback triggered on change.
|
228 | * @param error - Deprecated. This callback is never triggered. Errors
|
229 | * on signing in/out can be caught in promises returned from
|
230 | * sign-in/sign-out functions.
|
231 | * @param completed - Deprecated. This callback is never triggered.
|
232 | */
|
233 | onAuthStateChanged(nextOrObserver: NextOrObserver<User | null>, error?: ErrorFn, completed?: CompleteFn): Unsubscribe;
|
234 | /**
|
235 | * Adds a blocking callback that runs before an auth state change
|
236 | * sets a new user.
|
237 | *
|
238 | * @param callback - callback triggered before new user value is set.
|
239 | * If this throws, it blocks the user from being set.
|
240 | * @param onAbort - callback triggered if a later `beforeAuthStateChanged()`
|
241 | * callback throws, allowing you to undo any side effects.
|
242 | */
|
243 | beforeAuthStateChanged(callback: (user: User | null) => void | Promise<void>, onAbort?: () => void): Unsubscribe;
|
244 | /**
|
245 | * Adds an observer for changes to the signed-in user's ID token.
|
246 | *
|
247 | * @remarks
|
248 | * This includes sign-in, sign-out, and token refresh events.
|
249 | *
|
250 | * @param nextOrObserver - callback triggered on change.
|
251 | * @param error - Deprecated. This callback is never triggered. Errors
|
252 | * on signing in/out can be caught in promises returned from
|
253 | * sign-in/sign-out functions.
|
254 | * @param completed - Deprecated. This callback is never triggered.
|
255 | */
|
256 | onIdTokenChanged(nextOrObserver: NextOrObserver<User | null>, error?: ErrorFn, completed?: CompleteFn): Unsubscribe;
|
257 | /** The currently signed-in user (or null). */
|
258 | readonly currentUser: User | null;
|
259 | /** The current emulator configuration (or null). */
|
260 | readonly emulatorConfig: EmulatorConfig | null;
|
261 | /**
|
262 | * Asynchronously sets the provided user as {@link Auth.currentUser} on the {@link Auth} instance.
|
263 | *
|
264 | * @remarks
|
265 | * A new instance copy of the user provided will be made and set as currentUser.
|
266 | *
|
267 | * This will trigger {@link Auth.onAuthStateChanged} and {@link Auth.onIdTokenChanged} listeners
|
268 | * like other sign in methods.
|
269 | *
|
270 | * The operation fails with an error if the user to be updated belongs to a different Firebase
|
271 | * project.
|
272 | *
|
273 | * @param user - The new {@link User}.
|
274 | */
|
275 | updateCurrentUser(user: User | null): Promise<void>;
|
276 | /**
|
277 | * Sets the current language to the default device/browser preference.
|
278 | */
|
279 | useDeviceLanguage(): void;
|
280 | /**
|
281 | * Signs out the current user.
|
282 | */
|
283 | signOut(): Promise<void>;
|
284 | }
|
285 | /**
|
286 | * An interface covering the possible persistence mechanism types.
|
287 | *
|
288 | * @public
|
289 | */
|
290 | export interface Persistence {
|
291 | /**
|
292 | * Type of Persistence.
|
293 | * - 'SESSION' is used for temporary persistence such as `sessionStorage`.
|
294 | * - 'LOCAL' is used for long term persistence such as `localStorage` or `IndexedDB`.
|
295 | * - 'NONE' is used for in-memory, or no persistence.
|
296 | */
|
297 | readonly type: 'SESSION' | 'LOCAL' | 'NONE';
|
298 | }
|
299 | /**
|
300 | * Interface representing ID token result obtained from {@link User.getIdTokenResult}.
|
301 | *
|
302 | * @remarks
|
303 | * `IdTokenResult` contains the ID token JWT string and other helper properties for getting different data
|
304 | * associated with the token as well as all the decoded payload claims.
|
305 | *
|
306 | * Note that these claims are not to be trusted as they are parsed client side. Only server side
|
307 | * verification can guarantee the integrity of the token claims.
|
308 | *
|
309 | * @public
|
310 | */
|
311 | export interface IdTokenResult {
|
312 | /**
|
313 | * The authentication time formatted as a UTC string.
|
314 | *
|
315 | * @remarks
|
316 | * This is the time the user authenticated (signed in) and not the time the token was refreshed.
|
317 | */
|
318 | authTime: string;
|
319 | /** The ID token expiration time formatted as a UTC string. */
|
320 | expirationTime: string;
|
321 | /** The ID token issuance time formatted as a UTC string. */
|
322 | issuedAtTime: string;
|
323 | /**
|
324 | * The sign-in provider through which the ID token was obtained (anonymous, custom, phone,
|
325 | * password, etc).
|
326 | *
|
327 | * @remarks
|
328 | * Note, this does not map to provider IDs.
|
329 | */
|
330 | signInProvider: string | null;
|
331 | /**
|
332 | * The type of second factor associated with this session, provided the user was multi-factor
|
333 | * authenticated (eg. phone, etc).
|
334 | */
|
335 | signInSecondFactor: string | null;
|
336 | /** The Firebase Auth ID token JWT string. */
|
337 | token: string;
|
338 | /**
|
339 | * The entire payload claims of the ID token including the standard reserved claims as well as
|
340 | * the custom claims.
|
341 | */
|
342 | claims: ParsedToken;
|
343 | }
|
344 | /**
|
345 | * A response from {@link checkActionCode}.
|
346 | *
|
347 | * @public
|
348 | */
|
349 | export interface ActionCodeInfo {
|
350 | /**
|
351 | * The data associated with the action code.
|
352 | *
|
353 | * @remarks
|
354 | * For the {@link ActionCodeOperation}.PASSWORD_RESET, {@link ActionCodeOperation}.VERIFY_EMAIL, and
|
355 | * {@link ActionCodeOperation}.RECOVER_EMAIL actions, this object contains an email field with the address
|
356 | * the email was sent to.
|
357 | *
|
358 | * For the {@link ActionCodeOperation}.RECOVER_EMAIL action, which allows a user to undo an email address
|
359 | * change, this object also contains a `previousEmail` field with the user account's current
|
360 | * email address. After the action completes, the user's email address will revert to the value
|
361 | * in the `email` field from the value in `previousEmail` field.
|
362 | *
|
363 | * For the {@link ActionCodeOperation}.VERIFY_AND_CHANGE_EMAIL action, which allows a user to verify the
|
364 | * email before updating it, this object contains a `previousEmail` field with the user account's
|
365 | * email address before updating. After the action completes, the user's email address will be
|
366 | * updated to the value in the `email` field from the value in `previousEmail` field.
|
367 | *
|
368 | * For the {@link ActionCodeOperation}.REVERT_SECOND_FACTOR_ADDITION action, which allows a user to
|
369 | * unenroll a newly added second factor, this object contains a `multiFactorInfo` field with
|
370 | * the information about the second factor. For phone second factor, the `multiFactorInfo`
|
371 | * is a {@link MultiFactorInfo} object, which contains the phone number.
|
372 | */
|
373 | data: {
|
374 | email?: string | null;
|
375 | multiFactorInfo?: MultiFactorInfo | null;
|
376 | previousEmail?: string | null;
|
377 | };
|
378 | /**
|
379 | * The type of operation that generated the action code.
|
380 | */
|
381 | operation: typeof ActionCodeOperationMap[keyof typeof ActionCodeOperationMap];
|
382 | }
|
383 | /**
|
384 | * An enumeration of the possible email action types.
|
385 | *
|
386 | * @internal
|
387 | */
|
388 | export declare const enum ActionCodeOperation {
|
389 | /** The email link sign-in action. */
|
390 | EMAIL_SIGNIN = "EMAIL_SIGNIN",
|
391 | /** The password reset action. */
|
392 | PASSWORD_RESET = "PASSWORD_RESET",
|
393 | /** The email revocation action. */
|
394 | RECOVER_EMAIL = "RECOVER_EMAIL",
|
395 | /** The revert second factor addition email action. */
|
396 | REVERT_SECOND_FACTOR_ADDITION = "REVERT_SECOND_FACTOR_ADDITION",
|
397 | /** The revert second factor addition email action. */
|
398 | VERIFY_AND_CHANGE_EMAIL = "VERIFY_AND_CHANGE_EMAIL",
|
399 | /** The email verification action. */
|
400 | VERIFY_EMAIL = "VERIFY_EMAIL"
|
401 | }
|
402 | /**
|
403 | * An interface that defines the required continue/state URL with optional Android and iOS
|
404 | * bundle identifiers.
|
405 | *
|
406 | * @public
|
407 | */
|
408 | export interface ActionCodeSettings {
|
409 | /**
|
410 | * Sets the Android package name.
|
411 | *
|
412 | * @remarks
|
413 | * This will try to open the link in an android app if it is
|
414 | * installed. If `installApp` is passed, it specifies whether to install the Android app if the
|
415 | * device supports it and the app is not already installed. If this field is provided without
|
416 | * a `packageName`, an error is thrown explaining that the `packageName` must be provided in
|
417 | * conjunction with this field. If `minimumVersion` is specified, and an older version of the
|
418 | * app is installed, the user is taken to the Play Store to upgrade the app.
|
419 | */
|
420 | android?: {
|
421 | installApp?: boolean;
|
422 | minimumVersion?: string;
|
423 | packageName: string;
|
424 | };
|
425 | /**
|
426 | * When set to true, the action code link will be be sent as a Universal Link or Android App
|
427 | * Link and will be opened by the app if installed.
|
428 | *
|
429 | * @remarks
|
430 | * In the false case, the code will be sent to the web widget first and then on continue will
|
431 | * redirect to the app if installed.
|
432 | *
|
433 | * @defaultValue false
|
434 | */
|
435 | handleCodeInApp?: boolean;
|
436 | /**
|
437 | * Sets the iOS bundle ID.
|
438 | *
|
439 | * @remarks
|
440 | * This will try to open the link in an iOS app if it is installed.
|
441 | *
|
442 | * App installation is not supported for iOS.
|
443 | */
|
444 | iOS?: {
|
445 | bundleId: string;
|
446 | };
|
447 | /**
|
448 | * Sets the link continue/state URL.
|
449 | *
|
450 | * @remarks
|
451 | * This has different meanings in different contexts:
|
452 | * - When the link is handled in the web action widgets, this is the deep link in the
|
453 | * `continueUrl` query parameter.
|
454 | * - When the link is handled in the app directly, this is the `continueUrl` query parameter in
|
455 | * the deep link of the Dynamic Link.
|
456 | */
|
457 | url: string;
|
458 | /**
|
459 | * When multiple custom dynamic link domains are defined for a project, specify which one to use
|
460 | * when the link is to be opened via a specified mobile app (for example, `example.page.link`).
|
461 | *
|
462 | *
|
463 | * @defaultValue The first domain is automatically selected.
|
464 | */
|
465 | dynamicLinkDomain?: string;
|
466 | }
|
467 | /**
|
468 | * A verifier for domain verification and abuse prevention.
|
469 | *
|
470 | * @remarks
|
471 | * Currently, the only implementation is {@link RecaptchaVerifier}.
|
472 | *
|
473 | * @public
|
474 | */
|
475 | export interface ApplicationVerifier {
|
476 | /**
|
477 | * Identifies the type of application verifier (e.g. "recaptcha").
|
478 | */
|
479 | readonly type: string;
|
480 | /**
|
481 | * Executes the verification process.
|
482 | *
|
483 | * @returns A Promise for a token that can be used to assert the validity of a request.
|
484 | */
|
485 | verify(): Promise<string>;
|
486 | }
|
487 | /**
|
488 | * Interface that represents an auth provider, used to facilitate creating {@link AuthCredential}.
|
489 | *
|
490 | * @public
|
491 | */
|
492 | export interface AuthProvider {
|
493 | /**
|
494 | * Provider for which credentials can be constructed.
|
495 | */
|
496 | readonly providerId: string;
|
497 | }
|
498 | /**
|
499 | * An enum of factors that may be used for multifactor authentication.
|
500 | *
|
501 | * @internal
|
502 | */
|
503 | export declare const enum FactorId {
|
504 | /** Phone as second factor */
|
505 | PHONE = "phone"
|
506 | }
|
507 | /**
|
508 | * A result from a phone number sign-in, link, or reauthenticate call.
|
509 | *
|
510 | * @public
|
511 | */
|
512 | export interface ConfirmationResult {
|
513 | /**
|
514 | * The phone number authentication operation's verification ID.
|
515 | *
|
516 | * @remarks
|
517 | * This can be used along with the verification code to initialize a
|
518 | * {@link PhoneAuthCredential}.
|
519 | */
|
520 | readonly verificationId: string;
|
521 | /**
|
522 | * Finishes a phone number sign-in, link, or reauthentication.
|
523 | *
|
524 | * @example
|
525 | * ```javascript
|
526 | * const confirmationResult = await signInWithPhoneNumber(auth, phoneNumber, applicationVerifier);
|
527 | * // Obtain verificationCode from the user.
|
528 | * const userCredential = await confirmationResult.confirm(verificationCode);
|
529 | * ```
|
530 | *
|
531 | * @param verificationCode - The code that was sent to the user's mobile device.
|
532 | */
|
533 | confirm(verificationCode: string): Promise<UserCredential>;
|
534 | }
|
535 | /**
|
536 | * The base class for asserting ownership of a second factor.
|
537 | *
|
538 | * @remarks
|
539 | * This is used to facilitate enrollment of a second factor on an existing user or sign-in of a
|
540 | * user who already verified the first factor.
|
541 | *
|
542 | * @public
|
543 | */
|
544 | export interface MultiFactorAssertion {
|
545 | /** The identifier of the second factor. */
|
546 | readonly factorId: typeof FactorIdMap[keyof typeof FactorIdMap];
|
547 | }
|
548 | /**
|
549 | * The error thrown when the user needs to provide a second factor to sign in successfully.
|
550 | *
|
551 | * @remarks
|
552 | * The error code for this error is `auth/multi-factor-auth-required`.
|
553 | *
|
554 | * @example
|
555 | * ```javascript
|
556 | * let resolver;
|
557 | * let multiFactorHints;
|
558 | *
|
559 | * signInWithEmailAndPassword(auth, email, password)
|
560 | * .then((result) => {
|
561 | * // User signed in. No 2nd factor challenge is needed.
|
562 | * })
|
563 | * .catch((error) => {
|
564 | * if (error.code == 'auth/multi-factor-auth-required') {
|
565 | * resolver = getMultiFactorResolver(auth, error);
|
566 | * multiFactorHints = resolver.hints;
|
567 | * } else {
|
568 | * // Handle other errors.
|
569 | * }
|
570 | * });
|
571 | *
|
572 | * // Obtain a multiFactorAssertion by verifying the second factor.
|
573 | *
|
574 | * const userCredential = await resolver.resolveSignIn(multiFactorAssertion);
|
575 | * ```
|
576 | *
|
577 | * @public
|
578 | */
|
579 | export interface MultiFactorError extends AuthError {
|
580 | /** Details about the MultiFactorError. */
|
581 | readonly customData: AuthError['customData'] & {
|
582 | /**
|
583 | * The type of operation (sign-in, linking, or re-authentication) that raised the error.
|
584 | */
|
585 | readonly operationType: typeof OperationTypeMap[keyof typeof OperationTypeMap];
|
586 | };
|
587 | }
|
588 | /**
|
589 | * A structure containing the information of a second factor entity.
|
590 | *
|
591 | * @public
|
592 | */
|
593 | export interface MultiFactorInfo {
|
594 | /** The multi-factor enrollment ID. */
|
595 | readonly uid: string;
|
596 | /** The user friendly name of the current second factor. */
|
597 | readonly displayName?: string | null;
|
598 | /** The enrollment date of the second factor formatted as a UTC string. */
|
599 | readonly enrollmentTime: string;
|
600 | /** The identifier of the second factor. */
|
601 | readonly factorId: typeof FactorIdMap[keyof typeof FactorIdMap];
|
602 | }
|
603 | /**
|
604 | * The subclass of the {@link MultiFactorInfo} interface for phone number
|
605 | * second factors. The `factorId` of this second factor is {@link FactorId}.PHONE.
|
606 | * @public
|
607 | */
|
608 | export interface PhoneMultiFactorInfo extends MultiFactorInfo {
|
609 | /** The phone number associated with the current second factor. */
|
610 | readonly phoneNumber: string;
|
611 | }
|
612 | /**
|
613 | * The class used to facilitate recovery from {@link MultiFactorError} when a user needs to
|
614 | * provide a second factor to sign in.
|
615 | *
|
616 | * @example
|
617 | * ```javascript
|
618 | * let resolver;
|
619 | * let multiFactorHints;
|
620 | *
|
621 | * signInWithEmailAndPassword(auth, email, password)
|
622 | * .then((result) => {
|
623 | * // User signed in. No 2nd factor challenge is needed.
|
624 | * })
|
625 | * .catch((error) => {
|
626 | * if (error.code == 'auth/multi-factor-auth-required') {
|
627 | * resolver = getMultiFactorResolver(auth, error);
|
628 | * // Show UI to let user select second factor.
|
629 | * multiFactorHints = resolver.hints;
|
630 | * } else {
|
631 | * // Handle other errors.
|
632 | * }
|
633 | * });
|
634 | *
|
635 | * // The enrolled second factors that can be used to complete
|
636 | * // sign-in are returned in the `MultiFactorResolver.hints` list.
|
637 | * // UI needs to be presented to allow the user to select a second factor
|
638 | * // from that list.
|
639 | *
|
640 | * const selectedHint = // ; selected from multiFactorHints
|
641 | * const phoneAuthProvider = new PhoneAuthProvider(auth);
|
642 | * const phoneInfoOptions = {
|
643 | * multiFactorHint: selectedHint,
|
644 | * session: resolver.session
|
645 | * };
|
646 | * const verificationId = phoneAuthProvider.verifyPhoneNumber(phoneInfoOptions, appVerifier);
|
647 | * // Store `verificationId` and show UI to let user enter verification code.
|
648 | *
|
649 | * // UI to enter verification code and continue.
|
650 | * // Continue button click handler
|
651 | * const phoneAuthCredential = PhoneAuthProvider.credential(verificationId, verificationCode);
|
652 | * const multiFactorAssertion = PhoneMultiFactorGenerator.assertion(phoneAuthCredential);
|
653 | * const userCredential = await resolver.resolveSignIn(multiFactorAssertion);
|
654 | * ```
|
655 | *
|
656 | * @public
|
657 | */
|
658 | export interface MultiFactorResolver {
|
659 | /**
|
660 | * The list of hints for the second factors needed to complete the sign-in for the current
|
661 | * session.
|
662 | */
|
663 | readonly hints: MultiFactorInfo[];
|
664 | /**
|
665 | * The session identifier for the current sign-in flow, which can be used to complete the second
|
666 | * factor sign-in.
|
667 | */
|
668 | readonly session: MultiFactorSession;
|
669 | /**
|
670 | * A helper function to help users complete sign in with a second factor using an
|
671 | * {@link MultiFactorAssertion} confirming the user successfully completed the second factor
|
672 | * challenge.
|
673 | *
|
674 | * @example
|
675 | * ```javascript
|
676 | * const phoneAuthCredential = PhoneAuthProvider.credential(verificationId, verificationCode);
|
677 | * const multiFactorAssertion = PhoneMultiFactorGenerator.assertion(phoneAuthCredential);
|
678 | * const userCredential = await resolver.resolveSignIn(multiFactorAssertion);
|
679 | * ```
|
680 | *
|
681 | * @param assertion - The multi-factor assertion to resolve sign-in with.
|
682 | * @returns The promise that resolves with the user credential object.
|
683 | */
|
684 | resolveSignIn(assertion: MultiFactorAssertion): Promise<UserCredential>;
|
685 | }
|
686 | /**
|
687 | * An interface defining the multi-factor session object used for enrolling a second factor on a
|
688 | * user or helping sign in an enrolled user with a second factor.
|
689 | *
|
690 | * @public
|
691 | */
|
692 | export interface MultiFactorSession {
|
693 | }
|
694 | /**
|
695 | * An interface that defines the multi-factor related properties and operations pertaining
|
696 | * to a {@link User}.
|
697 | *
|
698 | * @public
|
699 | */
|
700 | export interface MultiFactorUser {
|
701 | /** Returns a list of the user's enrolled second factors. */
|
702 | readonly enrolledFactors: MultiFactorInfo[];
|
703 | /**
|
704 | * Returns the session identifier for a second factor enrollment operation. This is used to
|
705 | * identify the user trying to enroll a second factor.
|
706 | *
|
707 | * @example
|
708 | * ```javascript
|
709 | * const multiFactorUser = multiFactor(auth.currentUser);
|
710 | * const multiFactorSession = await multiFactorUser.getSession();
|
711 | *
|
712 | * // Send verification code.
|
713 | * const phoneAuthProvider = new PhoneAuthProvider(auth);
|
714 | * const phoneInfoOptions = {
|
715 | * phoneNumber: phoneNumber,
|
716 | * session: multiFactorSession
|
717 | * };
|
718 | * const verificationId = await phoneAuthProvider.verifyPhoneNumber(phoneInfoOptions, appVerifier);
|
719 | *
|
720 | * // Obtain verification code from user.
|
721 | * const phoneAuthCredential = PhoneAuthProvider.credential(verificationId, verificationCode);
|
722 | * const multiFactorAssertion = PhoneMultiFactorGenerator.assertion(phoneAuthCredential);
|
723 | * await multiFactorUser.enroll(multiFactorAssertion);
|
724 | * ```
|
725 | *
|
726 | * @returns The promise that resolves with the {@link MultiFactorSession}.
|
727 | */
|
728 | getSession(): Promise<MultiFactorSession>;
|
729 | /**
|
730 | *
|
731 | * Enrolls a second factor as identified by the {@link MultiFactorAssertion} for the
|
732 | * user.
|
733 | *
|
734 | * @remarks
|
735 | * On resolution, the user tokens are updated to reflect the change in the JWT payload.
|
736 | * Accepts an additional display name parameter used to identify the second factor to the end
|
737 | * user. Recent re-authentication is required for this operation to succeed. On successful
|
738 | * enrollment, existing Firebase sessions (refresh tokens) are revoked. When a new factor is
|
739 | * enrolled, an email notification is sent to the user’s email.
|
740 | *
|
741 | * @example
|
742 | * ```javascript
|
743 | * const multiFactorUser = multiFactor(auth.currentUser);
|
744 | * const multiFactorSession = await multiFactorUser.getSession();
|
745 | *
|
746 | * // Send verification code.
|
747 | * const phoneAuthProvider = new PhoneAuthProvider(auth);
|
748 | * const phoneInfoOptions = {
|
749 | * phoneNumber: phoneNumber,
|
750 | * session: multiFactorSession
|
751 | * };
|
752 | * const verificationId = await phoneAuthProvider.verifyPhoneNumber(phoneInfoOptions, appVerifier);
|
753 | *
|
754 | * // Obtain verification code from user.
|
755 | * const phoneAuthCredential = PhoneAuthProvider.credential(verificationId, verificationCode);
|
756 | * const multiFactorAssertion = PhoneMultiFactorGenerator.assertion(phoneAuthCredential);
|
757 | * await multiFactorUser.enroll(multiFactorAssertion);
|
758 | * // Second factor enrolled.
|
759 | * ```
|
760 | *
|
761 | * @param assertion - The multi-factor assertion to enroll with.
|
762 | * @param displayName - The display name of the second factor.
|
763 | */
|
764 | enroll(assertion: MultiFactorAssertion, displayName?: string | null): Promise<void>;
|
765 | /**
|
766 | * Unenrolls the specified second factor.
|
767 | *
|
768 | * @remarks
|
769 | * To specify the factor to remove, pass a {@link MultiFactorInfo} object (retrieved from
|
770 | * {@link MultiFactorUser.enrolledFactors}) or the
|
771 | * factor's UID string. Sessions are not revoked when the account is unenrolled. An email
|
772 | * notification is likely to be sent to the user notifying them of the change. Recent
|
773 | * re-authentication is required for this operation to succeed. When an existing factor is
|
774 | * unenrolled, an email notification is sent to the user’s email.
|
775 | *
|
776 | * @example
|
777 | * ```javascript
|
778 | * const multiFactorUser = multiFactor(auth.currentUser);
|
779 | * // Present user the option to choose which factor to unenroll.
|
780 | * await multiFactorUser.unenroll(multiFactorUser.enrolledFactors[i])
|
781 | * ```
|
782 | *
|
783 | * @param option - The multi-factor option to unenroll.
|
784 | * @returns - A `Promise` which resolves when the unenroll operation is complete.
|
785 | */
|
786 | unenroll(option: MultiFactorInfo | string): Promise<void>;
|
787 | }
|
788 | /**
|
789 | * The class for asserting ownership of a phone second factor. Provided by
|
790 | * {@link PhoneMultiFactorGenerator.assertion}.
|
791 | *
|
792 | * @public
|
793 | */
|
794 | export interface PhoneMultiFactorAssertion extends MultiFactorAssertion {
|
795 | }
|
796 | /**
|
797 | * The information required to verify the ownership of a phone number.
|
798 | *
|
799 | * @remarks
|
800 | * The information that's required depends on whether you are doing single-factor sign-in,
|
801 | * multi-factor enrollment or multi-factor sign-in.
|
802 | *
|
803 | * @public
|
804 | */
|
805 | export declare type PhoneInfoOptions = PhoneSingleFactorInfoOptions | PhoneMultiFactorEnrollInfoOptions | PhoneMultiFactorSignInInfoOptions;
|
806 | /**
|
807 | * Options used for single-factor sign-in.
|
808 | *
|
809 | * @public
|
810 | */
|
811 | export interface PhoneSingleFactorInfoOptions {
|
812 | /** Phone number to send a verification code to. */
|
813 | phoneNumber: string;
|
814 | }
|
815 | /**
|
816 | * Options used for enrolling a second factor.
|
817 | *
|
818 | * @public
|
819 | */
|
820 | export interface PhoneMultiFactorEnrollInfoOptions {
|
821 | /** Phone number to send a verification code to. */
|
822 | phoneNumber: string;
|
823 | /** The {@link MultiFactorSession} obtained via {@link MultiFactorUser.getSession}. */
|
824 | session: MultiFactorSession;
|
825 | }
|
826 | /**
|
827 | * Options used for signing in with a second factor.
|
828 | *
|
829 | * @public
|
830 | */
|
831 | export interface PhoneMultiFactorSignInInfoOptions {
|
832 | /**
|
833 | * The {@link MultiFactorInfo} obtained via {@link MultiFactorResolver.hints}.
|
834 | *
|
835 | * One of `multiFactorHint` or `multiFactorUid` is required.
|
836 | */
|
837 | multiFactorHint?: MultiFactorInfo;
|
838 | /**
|
839 | * The uid of the second factor.
|
840 | *
|
841 | * One of `multiFactorHint` or `multiFactorUid` is required.
|
842 | */
|
843 | multiFactorUid?: string;
|
844 | /** The {@link MultiFactorSession} obtained via {@link MultiFactorResolver.session}. */
|
845 | session: MultiFactorSession;
|
846 | }
|
847 | /**
|
848 | * Interface for a supplied `AsyncStorage`.
|
849 | *
|
850 | * @public
|
851 | */
|
852 | export interface ReactNativeAsyncStorage {
|
853 | /**
|
854 | * Persist an item in storage.
|
855 | *
|
856 | * @param key - storage key.
|
857 | * @param value - storage value.
|
858 | */
|
859 | setItem(key: string, value: string): Promise<void>;
|
860 | /**
|
861 | * Retrieve an item from storage.
|
862 | *
|
863 | * @param key - storage key.
|
864 | */
|
865 | getItem(key: string): Promise<string | null>;
|
866 | /**
|
867 | * Remove an item from storage.
|
868 | *
|
869 | * @param key - storage key.
|
870 | */
|
871 | removeItem(key: string): Promise<void>;
|
872 | }
|
873 | /**
|
874 | * A user account.
|
875 | *
|
876 | * @public
|
877 | */
|
878 | export interface User extends UserInfo {
|
879 | /**
|
880 | * Whether the email has been verified with {@link sendEmailVerification} and
|
881 | * {@link applyActionCode}.
|
882 | */
|
883 | readonly emailVerified: boolean;
|
884 | /**
|
885 | * Whether the user is authenticated using the {@link ProviderId}.ANONYMOUS provider.
|
886 | */
|
887 | readonly isAnonymous: boolean;
|
888 | /**
|
889 | * Additional metadata around user creation and sign-in times.
|
890 | */
|
891 | readonly metadata: UserMetadata;
|
892 | /**
|
893 | * Additional per provider such as displayName and profile information.
|
894 | */
|
895 | readonly providerData: UserInfo[];
|
896 | /**
|
897 | * Refresh token used to reauthenticate the user. Avoid using this directly and prefer
|
898 | * {@link User.getIdToken} to refresh the ID token instead.
|
899 | */
|
900 | readonly refreshToken: string;
|
901 | /**
|
902 | * The user's tenant ID.
|
903 | *
|
904 | * @remarks
|
905 | * This is a read-only property, which indicates the tenant ID
|
906 | * used to sign in the user. This is null if the user is signed in from the parent
|
907 | * project.
|
908 | *
|
909 | * @example
|
910 | * ```javascript
|
911 | * // Set the tenant ID on Auth instance.
|
912 | * auth.tenantId = 'TENANT_PROJECT_ID';
|
913 | *
|
914 | * // All future sign-in request now include tenant ID.
|
915 | * const result = await signInWithEmailAndPassword(auth, email, password);
|
916 | * // result.user.tenantId should be 'TENANT_PROJECT_ID'.
|
917 | * ```
|
918 | */
|
919 | readonly tenantId: string | null;
|
920 | /**
|
921 | * Deletes and signs out the user.
|
922 | *
|
923 | * @remarks
|
924 | * Important: this is a security-sensitive operation that requires the user to have recently
|
925 | * signed in. If this requirement isn't met, ask the user to authenticate again and then call
|
926 | * one of the reauthentication methods like {@link reauthenticateWithCredential}.
|
927 | */
|
928 | delete(): Promise<void>;
|
929 | /**
|
930 | * Returns a JSON Web Token (JWT) used to identify the user to a Firebase service.
|
931 | *
|
932 | * @remarks
|
933 | * Returns the current token if it has not expired or if it will not expire in the next five
|
934 | * minutes. Otherwise, this will refresh the token and return a new one.
|
935 | *
|
936 | * @param forceRefresh - Force refresh regardless of token expiration.
|
937 | */
|
938 | getIdToken(forceRefresh?: boolean): Promise<string>;
|
939 | /**
|
940 | * Returns a deserialized JSON Web Token (JWT) used to identitfy the user to a Firebase service.
|
941 | *
|
942 | * @remarks
|
943 | * Returns the current token if it has not expired or if it will not expire in the next five
|
944 | * minutes. Otherwise, this will refresh the token and return a new one.
|
945 | *
|
946 | * @param forceRefresh - Force refresh regardless of token expiration.
|
947 | */
|
948 | getIdTokenResult(forceRefresh?: boolean): Promise<IdTokenResult>;
|
949 | /**
|
950 | * Refreshes the user, if signed in.
|
951 | */
|
952 | reload(): Promise<void>;
|
953 | /**
|
954 | * Returns a JSON-serializable representation of this object.
|
955 | *
|
956 | * @returns A JSON-serializable representation of this object.
|
957 | */
|
958 | toJSON(): object;
|
959 | }
|
960 | /**
|
961 | * A structure containing a {@link User}, the {@link OperationType}, and the provider ID.
|
962 | *
|
963 | * @remarks
|
964 | * `operationType` could be {@link OperationType}.SIGN_IN for a sign-in operation,
|
965 | * {@link OperationType}.LINK for a linking operation and {@link OperationType}.REAUTHENTICATE for
|
966 | * a reauthentication operation.
|
967 | *
|
968 | * @public
|
969 | */
|
970 | export interface UserCredential {
|
971 | /**
|
972 | * The user authenticated by this credential.
|
973 | */
|
974 | user: User;
|
975 | /**
|
976 | * The provider which was used to authenticate the user.
|
977 | */
|
978 | providerId: string | null;
|
979 | /**
|
980 | * The type of operation which was used to authenticate the user (such as sign-in or link).
|
981 | */
|
982 | operationType: typeof OperationTypeMap[keyof typeof OperationTypeMap];
|
983 | }
|
984 | /**
|
985 | * User profile information, visible only to the Firebase project's apps.
|
986 | *
|
987 | * @public
|
988 | */
|
989 | export interface UserInfo {
|
990 | /**
|
991 | * The display name of the user.
|
992 | */
|
993 | readonly displayName: string | null;
|
994 | /**
|
995 | * The email of the user.
|
996 | */
|
997 | readonly email: string | null;
|
998 | /**
|
999 | * The phone number normalized based on the E.164 standard (e.g. +16505550101) for the
|
1000 | * user.
|
1001 | *
|
1002 | * @remarks
|
1003 | * This is null if the user has no phone credential linked to the account.
|
1004 | */
|
1005 | readonly phoneNumber: string | null;
|
1006 | /**
|
1007 | * The profile photo URL of the user.
|
1008 | */
|
1009 | readonly photoURL: string | null;
|
1010 | /**
|
1011 | * The provider used to authenticate the user.
|
1012 | */
|
1013 | readonly providerId: string;
|
1014 | /**
|
1015 | * The user's unique ID, scoped to the project.
|
1016 | */
|
1017 | readonly uid: string;
|
1018 | }
|
1019 | /**
|
1020 | * Interface representing a user's metadata.
|
1021 | *
|
1022 | * @public
|
1023 | */
|
1024 | export interface UserMetadata {
|
1025 | /** Time the user was created. */
|
1026 | readonly creationTime?: string;
|
1027 | /** Time the user last signed in. */
|
1028 | readonly lastSignInTime?: string;
|
1029 | }
|
1030 | /**
|
1031 | * A structure containing additional user information from a federated identity provider.
|
1032 | *
|
1033 | * @public
|
1034 | */
|
1035 | export interface AdditionalUserInfo {
|
1036 | /**
|
1037 | * Whether the user is new (created via sign-up) or existing (authenticated using sign-in).
|
1038 | */
|
1039 | readonly isNewUser: boolean;
|
1040 | /**
|
1041 | * Map containing IDP-specific user data.
|
1042 | */
|
1043 | readonly profile: Record<string, unknown> | null;
|
1044 | /**
|
1045 | * Identifier for the provider used to authenticate this user.
|
1046 | */
|
1047 | readonly providerId: string | null;
|
1048 | /**
|
1049 | * The username if the provider is GitHub or Twitter.
|
1050 | */
|
1051 | readonly username?: string | null;
|
1052 | }
|
1053 | /**
|
1054 | * User profile used in {@link AdditionalUserInfo}.
|
1055 | *
|
1056 | * @public
|
1057 | */
|
1058 | export declare type UserProfile = Record<string, unknown>;
|
1059 | /**
|
1060 | * A resolver used for handling DOM specific operations like {@link signInWithPopup}
|
1061 | * or {@link signInWithRedirect}.
|
1062 | *
|
1063 | * @public
|
1064 | */
|
1065 | export interface PopupRedirectResolver {
|
1066 | }
|
1067 | declare module '@firebase/component' {
|
1068 | interface NameServiceMapping {
|
1069 | 'auth': Auth;
|
1070 | }
|
1071 | }
|
1072 | /**
|
1073 | * Configuration of Firebase Authentication Emulator.
|
1074 | * @public
|
1075 | */
|
1076 | export interface EmulatorConfig {
|
1077 | /**
|
1078 | * The protocol used to communicate with the emulator ("http"/"https").
|
1079 | */
|
1080 | readonly protocol: string;
|
1081 | /**
|
1082 | * The hostname of the emulator, which may be a domain ("localhost"), IPv4 address ("127.0.0.1")
|
1083 | * or quoted IPv6 address ("[::1]").
|
1084 | */
|
1085 | readonly host: string;
|
1086 | /**
|
1087 | * The port of the emulator, or null if port isn't specified (i.e. protocol default).
|
1088 | */
|
1089 | readonly port: number | null;
|
1090 | /**
|
1091 | * The emulator-specific options.
|
1092 | */
|
1093 | readonly options: {
|
1094 | /**
|
1095 | * Whether the warning banner attached to the DOM was disabled.
|
1096 | */
|
1097 | readonly disableWarnings: boolean;
|
1098 | };
|
1099 | }
|
1100 | /**
|
1101 | * A mapping of error codes to error messages.
|
1102 | *
|
1103 | * @remarks
|
1104 | *
|
1105 | * While error messages are useful for debugging (providing verbose textual
|
1106 | * context around what went wrong), these strings take up a lot of space in the
|
1107 | * compiled code. When deploying code in production, using {@link prodErrorMap}
|
1108 | * will save you roughly 10k compressed/gzipped over {@link debugErrorMap}. You
|
1109 | * can select the error map during initialization:
|
1110 | *
|
1111 | * ```javascript
|
1112 | * initializeAuth(app, {errorMap: debugErrorMap})
|
1113 | * ```
|
1114 | *
|
1115 | * When initializing Auth, {@link prodErrorMap} is default.
|
1116 | *
|
1117 | * @public
|
1118 | */
|
1119 | export interface AuthErrorMap {
|
1120 | }
|
1121 | /**
|
1122 | * The dependencies that can be used to initialize an {@link Auth} instance.
|
1123 | *
|
1124 | * @remarks
|
1125 | *
|
1126 | * The modular SDK enables tree shaking by allowing explicit declarations of
|
1127 | * dependencies. For example, a web app does not need to include code that
|
1128 | * enables Cordova redirect sign in. That functionality is therefore split into
|
1129 | * {@link browserPopupRedirectResolver} and
|
1130 | * {@link cordovaPopupRedirectResolver}. The dependencies object is how Auth is
|
1131 | * configured to reduce bundle sizes.
|
1132 | *
|
1133 | * There are two ways to initialize an {@link Auth} instance: {@link getAuth} and
|
1134 | * {@link initializeAuth}. `getAuth` initializes everything using
|
1135 | * platform-specific configurations, while `initializeAuth` takes a
|
1136 | * `Dependencies` object directly, giving you more control over what is used.
|
1137 | *
|
1138 | * @public
|
1139 | */
|
1140 | export interface Dependencies {
|
1141 | /**
|
1142 | * Which {@link Persistence} to use. If this is an array, the first
|
1143 | * `Persistence` that the device supports is used. The SDK searches for an
|
1144 | * existing account in order and, if one is found in a secondary
|
1145 | * `Persistence`, the account is moved to the primary `Persistence`.
|
1146 | *
|
1147 | * If no persistence is provided, the SDK falls back on
|
1148 | * {@link inMemoryPersistence}.
|
1149 | */
|
1150 | persistence?: Persistence | Persistence[];
|
1151 | /**
|
1152 | * The {@link PopupRedirectResolver} to use. This value depends on the
|
1153 | * platform. Options are {@link browserPopupRedirectResolver} and
|
1154 | * {@link cordovaPopupRedirectResolver}. This field is optional if neither
|
1155 | * {@link signInWithPopup} or {@link signInWithRedirect} are being used.
|
1156 | */
|
1157 | popupRedirectResolver?: PopupRedirectResolver;
|
1158 | /**
|
1159 | * Which {@link AuthErrorMap} to use.
|
1160 | */
|
1161 | errorMap?: AuthErrorMap;
|
1162 | }
|