@dereekb/firebase-server 13.6.17 → 13.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/index.cjs.js +4233 -1923
  2. package/index.esm.js +4204 -1904
  3. package/mailgun/index.cjs.js +91 -1
  4. package/mailgun/index.esm.js +92 -3
  5. package/mailgun/package.json +9 -9
  6. package/mailgun/src/lib/auth.mailgun.d.ts +37 -1
  7. package/model/package.json +10 -10
  8. package/model/src/lib/storagefile/storagefile.action.server.d.ts +1 -1
  9. package/oidc/index.cjs.js +245 -180
  10. package/oidc/index.esm.js +242 -178
  11. package/oidc/package.json +12 -12
  12. package/oidc/src/lib/middleware/oauth-auth.module.d.ts +18 -25
  13. package/package.json +15 -14
  14. package/src/lib/auth/auth.service.d.ts +233 -0
  15. package/src/lib/auth/auth.service.error.d.ts +29 -0
  16. package/src/lib/auth/auth.service.error.util.d.ts +40 -0
  17. package/src/lib/auth/index.d.ts +1 -0
  18. package/src/lib/function/error.d.ts +11 -28
  19. package/src/lib/nest/app.d.ts +4 -45
  20. package/src/lib/nest/app.module.d.ts +4 -2
  21. package/src/lib/nest/auth/auth.util.d.ts +71 -5
  22. package/src/lib/nest/controller/index.d.ts +1 -0
  23. package/src/lib/nest/controller/model/index.d.ts +4 -0
  24. package/src/lib/nest/controller/model/model.api.controller.d.ts +93 -0
  25. package/src/lib/nest/controller/model/model.api.dispatch.d.ts +73 -0
  26. package/src/lib/nest/controller/model/model.api.get.service.d.ts +73 -0
  27. package/src/lib/nest/controller/model/model.api.module.d.ts +32 -0
  28. package/src/lib/nest/model/analytics.handler.d.ts +2 -0
  29. package/src/lib/nest/model/api.details.d.ts +53 -1
  30. package/src/lib/nest/model/call.model.function.d.ts +8 -5
  31. package/src/lib/nest/model/create.model.function.d.ts +1 -1
  32. package/src/lib/nest/model/crud.assert.function.d.ts +1 -1
  33. package/src/lib/nest/model/delete.model.function.d.ts +1 -1
  34. package/src/lib/nest/model/index.d.ts +1 -0
  35. package/src/lib/nest/model/query.model.function.d.ts +207 -0
  36. package/src/lib/nest/model/read.model.function.d.ts +1 -1
  37. package/src/lib/nest/model/update.model.function.d.ts +1 -1
  38. package/src/lib/nest/nest.provider.d.ts +19 -0
  39. package/test/index.cjs.js +1358 -398
  40. package/test/index.esm.js +1355 -400
  41. package/test/package.json +14 -12
  42. package/test/src/lib/firebase/firebase.test.d.ts +1 -1
  43. package/test/src/lib/index.d.ts +1 -0
  44. package/test/src/lib/oidc/index.d.ts +2 -0
  45. package/test/src/lib/oidc/oidc.test.fixture.d.ts +126 -0
  46. package/test/src/lib/oidc/oidc.test.flow.d.ts +43 -0
  47. package/zoho/package.json +9 -9
package/oidc/package.json CHANGED
@@ -1,20 +1,20 @@
1
1
  {
2
2
  "name": "@dereekb/firebase-server/oidc",
3
- "version": "13.6.17",
3
+ "version": "13.8.0",
4
4
  "peerDependencies": {
5
- "@dereekb/analytics": "13.6.17",
6
- "@dereekb/date": "13.6.17",
7
- "@dereekb/firebase": "13.6.17",
8
- "@dereekb/firebase-server": "13.6.17",
9
- "@dereekb/model": "13.6.17",
10
- "@dereekb/nestjs": "13.6.17",
11
- "@dereekb/rxjs": "13.6.17",
12
- "@dereekb/util": "13.6.17",
13
- "@dereekb/zoho": "13.6.17",
5
+ "@dereekb/analytics": "13.8.0",
6
+ "@dereekb/date": "13.8.0",
7
+ "@dereekb/firebase": "13.8.0",
8
+ "@dereekb/firebase-server": "13.8.0",
9
+ "@dereekb/model": "13.8.0",
10
+ "@dereekb/nestjs": "13.8.0",
11
+ "@dereekb/rxjs": "13.8.0",
12
+ "@dereekb/util": "13.8.0",
13
+ "@dereekb/zoho": "13.8.0",
14
14
  "@nestjs/common": "^11.1.17",
15
- "@nestjs/config": "^4.0.3",
15
+ "@nestjs/config": "^4.0.4",
16
16
  "express": "^5.0.0",
17
- "firebase-admin": "^13.0.0",
17
+ "firebase-admin": "^13.8.0",
18
18
  "nanoid": "^5.1.7",
19
19
  "oidc-provider": "^9.7.0"
20
20
  },
@@ -1,4 +1,4 @@
1
- import { type MiddlewareConsumer } from '@nestjs/common';
1
+ import { type INestApplication } from '@nestjs/common';
2
2
  import { type SlashPath } from '@dereekb/util';
3
3
  /**
4
4
  * Configuration for `OidcAuthBearerTokenMiddleware` route protection.
@@ -6,12 +6,6 @@ import { type SlashPath } from '@dereekb/util';
6
6
  * Works in reverse of `FirebaseAppCheckMiddlewareConfig`: instead of protecting
7
7
  * all routes and ignoring some, this only protects explicitly specified paths.
8
8
  * Routes under the global API prefix (protected by AppCheck) are excluded.
9
- *
10
- * @example
11
- * ```ts
12
- * // Provide in your module:
13
- * { provide: OidcAuthMiddlewareConfig, useValue: { protectedPaths: ['/mcp'] } }
14
- * ```
15
9
  */
16
10
  export declare abstract class OidcAuthMiddlewareConfig {
17
11
  /**
@@ -24,27 +18,26 @@ export declare abstract class OidcAuthMiddlewareConfig {
24
18
  readonly protectedPaths: SlashPath[];
25
19
  }
26
20
  /**
27
- * Middleware module that applies OAuth bearer token verification
28
- * to paths specified in `OidcAuthMiddlewareConfig`.
21
+ * Applies OAuth bearer token verification as global Express middleware on
22
+ * the given NestJS application.
29
23
  *
30
- * Only protects explicitly listed paths — all other routes pass through.
31
- * This is the inverse of `ConfigureFirebaseAppCheckMiddlewareModule`, which
32
- * protects everything and ignores specific paths.
24
+ * Resolves `OidcService` and `OidcAuthMiddlewareConfig` from the app's DI container,
25
+ * then registers an Express middleware that verifies bearer tokens for the configured
26
+ * protected paths and attaches auth data to `req.auth`.
27
+ *
28
+ * This is an alternative to {@link ConfigureOidcAuthMiddlewareModule} for cases where
29
+ * NestJS module scoping makes the module approach impractical.
30
+ *
31
+ * @param nestApp - The NestJS application instance used to resolve dependencies and register the middleware.
33
32
  *
34
33
  * @example
35
34
  * ```ts
36
- * @Module({
37
- * imports: [ConfigureOidcAuthMiddlewareModule],
38
- * providers: [
39
- * { provide: OidcAuthMiddlewareConfig, useValue: { protectedPaths: ['/mcp'] } }
40
- * ]
41
- * })
42
- * export class AppModule {}
35
+ * export const APP_NEST_SERVER_CONFIG: NestServerInstanceConfig<AppModule> = {
36
+ * moduleClass: AppModule,
37
+ * configureNestServerInstance: (nestApp) => {
38
+ * applyOidcAuthMiddleware(nestApp);
39
+ * }
40
+ * };
43
41
  * ```
44
42
  */
45
- export declare class ConfigureOidcAuthMiddlewareModule {
46
- private readonly config?;
47
- private readonly logger;
48
- constructor(config?: OidcAuthMiddlewareConfig | undefined);
49
- configure(consumer: MiddlewareConsumer): void;
50
- }
43
+ export declare function applyOidcAuthMiddleware(nestApp: INestApplication): void;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dereekb/firebase-server",
3
- "version": "13.6.17",
3
+ "version": "13.8.0",
4
4
  "exports": {
5
5
  "./test": {
6
6
  "module": "./test/index.esm.js",
@@ -43,27 +43,27 @@
43
43
  "main": "./index.cjs.js",
44
44
  "types": "./src/index.d.ts",
45
45
  "peerDependencies": {
46
- "@dereekb/analytics": "13.6.17",
47
- "@dereekb/date": "13.6.17",
48
- "@dereekb/dbx-core": "13.6.17",
49
- "@dereekb/firebase": "13.6.17",
50
- "@dereekb/model": "13.6.17",
51
- "@dereekb/nestjs": "13.6.17",
52
- "@dereekb/rxjs": "13.6.17",
53
- "@dereekb/util": "13.6.17",
54
- "@dereekb/zoho": "13.6.17",
46
+ "@dereekb/analytics": "13.8.0",
47
+ "@dereekb/date": "13.8.0",
48
+ "@dereekb/dbx-core": "13.8.0",
49
+ "@dereekb/firebase": "13.8.0",
50
+ "@dereekb/model": "13.8.0",
51
+ "@dereekb/nestjs": "13.8.0",
52
+ "@dereekb/rxjs": "13.8.0",
53
+ "@dereekb/util": "13.8.0",
54
+ "@dereekb/zoho": "13.8.0",
55
55
  "@google-cloud/firestore": "^7.11.6",
56
56
  "@google-cloud/storage": "^7.19.0",
57
57
  "@nestjs/common": "^11.1.17",
58
- "@nestjs/config": "^4.0.3",
59
- "@nestjs/core": "^11.1.17",
60
- "@nestjs/platform-express": "^11.1.17",
58
+ "@nestjs/config": "^4.0.4",
59
+ "@nestjs/core": "^11.1.18",
60
+ "@nestjs/platform-express": "^11.1.18",
61
61
  "@nestjs/testing": "^11.1.14",
62
62
  "archiver": "^7.0.0",
63
63
  "arktype": "^2.2.0",
64
64
  "date-fns": "^4.0.0",
65
65
  "express": "^5.0.0",
66
- "firebase-admin": "^13.0.0",
66
+ "firebase-admin": "^13.8.0",
67
67
  "firebase-functions": "^7.0.0",
68
68
  "firebase-functions-test": "3.4.1",
69
69
  "jsonwebtoken": "^9.0.0",
@@ -71,6 +71,7 @@
71
71
  "nanoid": "^5.1.7",
72
72
  "oidc-provider": "^9.7.0",
73
73
  "rxjs": "^7.8.0",
74
+ "supertest": "^7.2.2",
74
75
  "ts-essentials": "^10.0.0"
75
76
  },
76
77
  "module": "./index.esm.js"
@@ -583,6 +583,234 @@ export declare abstract class AbstractFirebaseServerNewUserService<U extends Fir
583
583
  export declare class NoSetupContentFirebaseServerNewUserService<U extends FirebaseServerAuthUserContext = FirebaseServerAuthUserContext> extends AbstractFirebaseServerNewUserService<U> {
584
584
  protected sendSetupContentToUser(_details: FirebaseServerAuthNewUserSetupDetails<U>): Promise<void>;
585
585
  }
586
+ /**
587
+ * Configuration for initiating a password reset flow for an existing Firebase Auth user.
588
+ *
589
+ * Supports identifying the user by UID or email, and optionally sending reset content
590
+ * (e.g., an email with the temporary password) immediately after initiation.
591
+ *
592
+ * @example
593
+ * ```typescript
594
+ * await passwordResetService.beginPasswordReset({
595
+ * uid: 'some-uid',
596
+ * sendResetContent: true,
597
+ * sendResetThrowErrors: true
598
+ * });
599
+ * ```
600
+ */
601
+ export interface FirebaseServerAuthInitiatePasswordReset<D = unknown> {
602
+ /**
603
+ * Specific user identifier to use.
604
+ */
605
+ readonly uid?: Maybe<FirebaseAuthUserId>;
606
+ /**
607
+ * Email for the user, if identifying by email.
608
+ */
609
+ readonly email?: Maybe<EmailAddress>;
610
+ /**
611
+ * Whether or not to send a reset email. Is false by default.
612
+ */
613
+ readonly sendResetContent?: Maybe<boolean>;
614
+ /**
615
+ * If true, and the reset content has been sent before, it will not be sent again.
616
+ */
617
+ readonly sendResetDetailsOnce?: Maybe<boolean>;
618
+ /**
619
+ * If true, will ignore throttling when sending reset content.
620
+ */
621
+ readonly sendResetIgnoreThrottle?: Maybe<boolean>;
622
+ /**
623
+ * Whether or not to throw an error if sending reset content fails. Is false by default.
624
+ */
625
+ readonly sendResetThrowErrors?: Maybe<boolean>;
626
+ /**
627
+ * Whether or not to force sending the test details.
628
+ */
629
+ readonly sendDetailsInTestEnvironment?: Maybe<boolean>;
630
+ /**
631
+ * Any additional reset context.
632
+ */
633
+ readonly data?: Maybe<D>;
634
+ }
635
+ /**
636
+ * Configuration options for sending password reset content (e.g., reset email) to a user.
637
+ *
638
+ * Controls throttling, send-once behavior, and error handling for the delivery process.
639
+ */
640
+ export interface FirebaseServerAuthPasswordResetSendContentConfig<D = unknown> {
641
+ /**
642
+ * Whether or not to force sending the test details. Usage differs between providers.
643
+ */
644
+ readonly sendDetailsInTestEnvironment?: Maybe<boolean>;
645
+ /**
646
+ * Whether or not to skip sending again if the reset content has already been sent once.
647
+ */
648
+ readonly sendResetDetailsOnce?: Maybe<boolean>;
649
+ /**
650
+ * Whether or not to force sending again even if the send is being throttled.
651
+ */
652
+ readonly ignoreSendThrottleTime?: Maybe<boolean>;
653
+ /**
654
+ * Whether or not to throw errors if the send fails, instead of returning false.
655
+ *
656
+ * @see FirebaseServerAuthPasswordResetNoResetConfigError
657
+ * @see FirebaseServerAuthPasswordResetThrottleError
658
+ */
659
+ readonly throwErrors?: Maybe<boolean>;
660
+ /**
661
+ * Any additional reset context.
662
+ */
663
+ readonly data?: Maybe<D>;
664
+ }
665
+ /**
666
+ * Details about a user that is in the password reset phase, including their user context,
667
+ * reset claims data, and the send configuration that was used.
668
+ */
669
+ export interface FirebaseServerAuthPasswordResetDetails<U extends FirebaseServerAuthUserContext = FirebaseServerAuthUserContext, D = unknown> extends FirebaseServerAuthPasswordResetSendContentConfig<D> {
670
+ readonly userContext: U;
671
+ readonly claims: FirebaseAuthResetUserPasswordClaimsData;
672
+ }
673
+ /**
674
+ * Input for completing a password reset, containing the temporary reset code
675
+ * and the desired new password.
676
+ */
677
+ export interface FirebaseServerAuthCompletePasswordResetInput {
678
+ /**
679
+ * The temporary reset code from the reset email, to be verified against claims.
680
+ */
681
+ readonly resetPassword: string;
682
+ /**
683
+ * The new password to set after verification succeeds.
684
+ */
685
+ readonly newPassword: PasswordString;
686
+ }
687
+ /**
688
+ * Service for managing password reset flows for existing Firebase Auth users.
689
+ *
690
+ * Handles initiating password resets (generating temporary passwords), sending reset content
691
+ * (with throttling), loading reset state, and completing the reset by setting a new password.
692
+ *
693
+ * @example
694
+ * ```typescript
695
+ * const resetSvc = authService.passwordReset();
696
+ * const claims = await resetSvc.beginPasswordReset({ uid: 'some-uid', sendResetContent: true });
697
+ * // Later, after user verifies identity:
698
+ * await resetSvc.completePasswordReset('some-uid', { resetPassword: '123456', newPassword: 'newSecure' });
699
+ * ```
700
+ */
701
+ export interface FirebaseServerUserPasswordResetService<D = unknown, U extends FirebaseServerAuthUserContext = FirebaseServerAuthUserContext> {
702
+ /**
703
+ * Initiates a password reset for the identified user, generating a temporary password
704
+ * and storing reset claims. Optionally sends reset content (e.g., email) immediately.
705
+ *
706
+ * When `sendResetContent` is true, this method delegates to {@link sendResetContent} and
707
+ * may throw the same errors (throttle, send-once, no-config) depending on the configuration.
708
+ *
709
+ * @param input - Configuration for the reset, including user identification and send options.
710
+ * @throws Throws if neither uid nor email is provided.
711
+ * @throws {FirebaseServerAuthPasswordResetThrottleError} When send is throttled and `sendResetThrowErrors` is true.
712
+ * @throws {FirebaseServerAuthPasswordResetSendOnceError} When already sent and `sendResetDetailsOnce` + `sendResetThrowErrors` are true.
713
+ * @throws {FirebaseServerAuthPasswordResetNoResetConfigError} When no reset claims exist and `sendResetThrowErrors` is true.
714
+ */
715
+ beginPasswordReset(input: FirebaseServerAuthInitiatePasswordReset<D>): Promise<FirebaseServerAuthResetUserPasswordClaims>;
716
+ /**
717
+ * Sends reset content (e.g., a reset email) to the user.
718
+ *
719
+ * Respects throttling and send-once constraints from the config. Returns `true` if
720
+ * content was actually sent, `false` if skipped due to throttling or send-once rules.
721
+ *
722
+ * @param uid - The target user's UID.
723
+ * @param config - Optional delivery configuration.
724
+ * @throws {FirebaseServerAuthPasswordResetThrottleError} When throttled and `throwErrors` is true.
725
+ * @throws {FirebaseServerAuthPasswordResetSendOnceError} When already sent and `sendResetDetailsOnce` + `throwErrors` are true.
726
+ * @throws {FirebaseServerAuthPasswordResetNoResetConfigError} When no reset claims exist and `throwErrors` is true.
727
+ */
728
+ sendResetContent(uid: FirebaseAuthUserId, config?: FirebaseServerAuthPasswordResetSendContentConfig<D>): Promise<boolean>;
729
+ /**
730
+ * Loads the reset details for the user if they are in the reset phase.
731
+ *
732
+ * @param uid - The target user's UID.
733
+ * @param config - Optional config to forward to the details.
734
+ * @returns The reset details, or `undefined` if the user does not exist or has no reset claims.
735
+ */
736
+ loadResetDetails(uid: FirebaseAuthUserId, config?: FirebaseServerAuthPasswordResetSendContentConfig<D>): Promise<Maybe<FirebaseServerAuthPasswordResetDetails<U, D>>>;
737
+ /**
738
+ * Loads the reset details for a user context that is already resolved.
739
+ *
740
+ * @param userContext - The resolved user context.
741
+ * @param config - Optional config to forward to the details.
742
+ * @returns The reset details, or `undefined` if the user has no reset claims.
743
+ */
744
+ loadResetDetailsForUserContext(userContext: U, config?: FirebaseServerAuthPasswordResetSendContentConfig<D>): Promise<Maybe<FirebaseServerAuthPasswordResetDetails<U, D>>>;
745
+ /**
746
+ * Completes the password reset by verifying the temporary reset code against the user's
747
+ * claims and setting the new password. Clears reset claims on success.
748
+ *
749
+ * @param uid - The target user's UID.
750
+ * @param input - The reset code and new password.
751
+ * @throws {FirebaseServerAuthPasswordResetInvalidCodeError} When the reset code is invalid or no reset is active.
752
+ */
753
+ completePasswordReset(uid: FirebaseAuthUserId, input: FirebaseServerAuthCompletePasswordResetInput): Promise<admin.auth.UserRecord>;
754
+ }
755
+ /**
756
+ * Default throttle duration (1 hour) between reset content sends to prevent spam.
757
+ *
758
+ * Used by {@link AbstractFirebaseServerUserPasswordResetService.sendResetContent} to rate-limit delivery.
759
+ */
760
+ export declare const DEFAULT_RESET_COM_THROTTLE_TIME: number;
761
+ /**
762
+ * Base implementation of {@link FirebaseServerUserPasswordResetService} that handles reset initiation,
763
+ * claims management, throttled reset content delivery, and reset completion.
764
+ *
765
+ * Subclasses must implement {@link sendPasswordResetContentToUser} to define how reset content
766
+ * (e.g., reset email, SMS) is delivered to the user.
767
+ *
768
+ * @example
769
+ * ```typescript
770
+ * export class MyPasswordResetService extends AbstractFirebaseServerUserPasswordResetService<MyUserContext> {
771
+ * protected async sendPasswordResetContentToUser(details: FirebaseServerAuthPasswordResetDetails<MyUserContext>): Promise<void> {
772
+ * await this.emailService.sendResetEmail(details.userContext.uid, details.claims.resetPassword);
773
+ * }
774
+ * }
775
+ * ```
776
+ */
777
+ export declare abstract class AbstractFirebaseServerUserPasswordResetService<U extends FirebaseServerAuthUserContext = FirebaseServerAuthUserContext, C extends FirebaseServerAuthContext = FirebaseServerAuthContext, D = unknown> implements FirebaseServerUserPasswordResetService<D, U> {
778
+ private readonly _authService;
779
+ /**
780
+ * Minimum time between reset content sends. Defaults to {@link DEFAULT_RESET_COM_THROTTLE_TIME} (1 hour).
781
+ * Override in subclasses to customize the throttle window.
782
+ */
783
+ protected resetThrottleTime: Milliseconds;
784
+ constructor(authService: FirebaseServerAuthService<U, C>);
785
+ get authService(): FirebaseServerAuthService<U, C>;
786
+ beginPasswordReset(input: FirebaseServerAuthInitiatePasswordReset<D>): Promise<FirebaseServerAuthResetUserPasswordClaims>;
787
+ sendResetContent(uid: FirebaseAuthUserId, config?: FirebaseServerAuthPasswordResetSendContentConfig<D>): Promise<boolean>;
788
+ loadResetDetails(uid: FirebaseAuthUserId, config?: FirebaseServerAuthPasswordResetSendContentConfig<D>): Promise<Maybe<FirebaseServerAuthPasswordResetDetails<U, D>>>;
789
+ loadResetDetailsForUserContext(userContext: U, config?: FirebaseServerAuthPasswordResetSendContentConfig<D>): Promise<Maybe<FirebaseServerAuthPasswordResetDetails<U, D>>>;
790
+ /**
791
+ * Records the current timestamp as the last reset content communication date in the user's claims.
792
+ *
793
+ * @param details - The user's reset details containing the user context.
794
+ */
795
+ protected updateResetContentSentTime(details: FirebaseServerAuthPasswordResetDetails<U, D>): Promise<void>;
796
+ completePasswordReset(uid: FirebaseAuthUserId, input: FirebaseServerAuthCompletePasswordResetInput): Promise<admin.auth.UserRecord>;
797
+ /**
798
+ * Delivers reset content (e.g., reset email, SMS) to the user.
799
+ *
800
+ * Subclasses must implement this to define the actual delivery mechanism.
801
+ *
802
+ * @param details - The user's reset details, including their context and reset claims.
803
+ */
804
+ protected abstract sendPasswordResetContentToUser(details: FirebaseServerAuthPasswordResetDetails<U, D>): Promise<void>;
805
+ }
806
+ /**
807
+ * No-op implementation of {@link AbstractFirebaseServerUserPasswordResetService} that skips sending reset content.
808
+ *
809
+ * Used as the default {@link FirebaseServerUserPasswordResetService} when no custom delivery mechanism is configured.
810
+ */
811
+ export declare class NoContentFirebaseServerUserPasswordResetService<U extends FirebaseServerAuthUserContext = FirebaseServerAuthUserContext> extends AbstractFirebaseServerUserPasswordResetService<U> {
812
+ protected sendPasswordResetContentToUser(_details: FirebaseServerAuthPasswordResetDetails<U>): Promise<void>;
813
+ }
586
814
  /**
587
815
  * Reference to a FirebaseServerAuthService
588
816
  */
@@ -686,6 +914,10 @@ export declare abstract class FirebaseServerAuthService<U extends FirebaseServer
686
914
  * Returns a {@link FirebaseServerNewUserService} for programmatic user creation and setup management.
687
915
  */
688
916
  abstract newUser(): FirebaseServerNewUserService;
917
+ /**
918
+ * Returns a {@link FirebaseServerUserPasswordResetService} for managing password reset flows.
919
+ */
920
+ abstract passwordReset(): FirebaseServerUserPasswordResetService;
689
921
  /**
690
922
  * Converts a Firebase Admin {@link admin.auth.UserRecord} into a normalized {@link FirebaseAuthDetails} object.
691
923
  *
@@ -735,6 +967,7 @@ export declare abstract class AbstractFirebaseServerAuthService<U extends Fireba
735
967
  abstract readRoles(claims: AuthClaims): AuthRoleSet;
736
968
  abstract claimsForRoles(roles: AuthRoleSet): AuthClaimsUpdate;
737
969
  newUser(): FirebaseServerNewUserService;
970
+ passwordReset(): FirebaseServerUserPasswordResetService;
738
971
  authContextInfo(context: AuthDataRef): Maybe<FirebaseAuthContextInfo>;
739
972
  authDetailsForRecord(record: admin.auth.UserRecord): FirebaseAuthDetails;
740
973
  }
@@ -65,3 +65,32 @@ export declare class FirebaseServerAuthNewUserSendSetupDetailsThrottleError exte
65
65
  export declare class FirebaseServerAuthNewUserSendSetupDetailsSendOnceError extends BaseError {
66
66
  constructor();
67
67
  }
68
+ /**
69
+ * Thrown by {@link AbstractFirebaseServerUserPasswordResetService.sendResetContent} when the user
70
+ * has no active password reset claims, meaning no reset has been initiated or it has already been completed.
71
+ */
72
+ export declare class FirebaseServerAuthPasswordResetNoResetConfigError extends BaseError {
73
+ constructor();
74
+ }
75
+ /**
76
+ * Thrown by {@link AbstractFirebaseServerUserPasswordResetService.sendResetContent} when the user
77
+ * was recently sent reset content and the throttle window has not elapsed.
78
+ */
79
+ export declare class FirebaseServerAuthPasswordResetThrottleError extends BaseError {
80
+ readonly lastSentAt: Date;
81
+ constructor(lastSentAt: Date);
82
+ }
83
+ /**
84
+ * Thrown by {@link AbstractFirebaseServerUserPasswordResetService.sendResetContent} when the user
85
+ * has already been sent reset content and the `sendResetDetailsOnce` option was enabled.
86
+ */
87
+ export declare class FirebaseServerAuthPasswordResetSendOnceError extends BaseError {
88
+ constructor();
89
+ }
90
+ /**
91
+ * Thrown by {@link AbstractFirebaseServerUserPasswordResetService.completePasswordReset} when the
92
+ * provided reset code does not match the one stored in the user's claims, or no reset is active.
93
+ */
94
+ export declare class FirebaseServerAuthPasswordResetInvalidCodeError extends BaseError {
95
+ constructor();
96
+ }
@@ -0,0 +1,40 @@
1
+ /**
2
+ * Wraps an async function that uses {@link FirebaseServerUserPasswordResetService} methods,
3
+ * catching password-reset-specific errors and re-throwing them as appropriate {@link HttpsError} instances
4
+ * suitable for returning to clients.
5
+ *
6
+ * Error mapping:
7
+ * - {@link FirebaseServerAuthPasswordResetInvalidCodeError} → permission-denied (403)
8
+ * - {@link FirebaseServerAuthPasswordResetNoResetConfigError} → bad-request (400)
9
+ * - {@link FirebaseServerAuthPasswordResetThrottleError} → unavailable (503)
10
+ * - {@link FirebaseServerAuthPasswordResetSendOnceError} → bad-request (400)
11
+ *
12
+ * @param fn - The async function to execute.
13
+ * @returns The result of the function.
14
+ */
15
+ export declare function catchAndThrowPasswordResetServerErrors<T>(fn: () => Promise<T>): Promise<T>;
16
+ /**
17
+ * Creates a permission-denied (403) server error for an invalid or expired password reset code.
18
+ *
19
+ * @returns An {@link HttpsError} with code `permission-denied`.
20
+ */
21
+ export declare function authServicePasswordResetInvalidCodeError(): import("firebase-functions/https").HttpsError;
22
+ /**
23
+ * Creates a bad-request (400) server error when no active password reset exists for the user.
24
+ *
25
+ * @returns An {@link HttpsError} with code `invalid-argument`.
26
+ */
27
+ export declare function authServicePasswordResetNoConfigError(): import("firebase-functions/https").HttpsError;
28
+ /**
29
+ * Creates an unavailable (503) server error when password reset email sending is throttled.
30
+ *
31
+ * @returns An {@link HttpsError} with code `unavailable`.
32
+ */
33
+ export declare function authServicePasswordResetThrottleError(): import("firebase-functions/https").HttpsError;
34
+ /**
35
+ * Creates a bad-request (400) server error when the password reset email has already been sent
36
+ * and the send-once constraint is active.
37
+ *
38
+ * @returns An {@link HttpsError} with code `invalid-argument`.
39
+ */
40
+ export declare function authServicePasswordResetSendOnceError(): import("firebase-functions/https").HttpsError;
@@ -1,4 +1,5 @@
1
1
  export * from './auth.service';
2
2
  export * from './auth.service.error';
3
+ export * from './auth.service.error.util';
3
4
  export * from './auth.context';
4
5
  export * from './auth.util';
@@ -14,100 +14,83 @@ export declare function unauthenticatedContextHasNoAuthData(): HttpsError;
14
14
  * @returns A new unauthenticated {@link HttpsError} with the no-auth error code.
15
15
  */
16
16
  export declare function unauthenticatedContextHasNoUidError(): HttpsError;
17
- /**
18
- * Standard error code constants and factory functions for creating typed {@link HttpsError} instances.
19
- *
20
- * Each factory wraps the Firebase `HttpsError` with a consistent shape: an HTTP status code,
21
- * a string error code, and an optional {@link ServerError} detail object.
22
- */
23
- export declare const UNAUTHENTICATED_ERROR_CODE = "UNAUTHENTICATED";
24
17
  /**
25
18
  * Creates an unauthenticated (401) {@link HttpsError}.
26
19
  *
27
20
  * @param messageOrError - Optional error message string or partial server error object.
28
21
  * @returns A new unauthenticated (401) {@link HttpsError}.
29
22
  */
30
- export declare function unauthenticatedError(messageOrError?: ErrorMessageOrPartialServerError): HttpsError;
31
- export declare const FORBIDDEN_ERROR_CODE = "FORBIDDEN";
23
+ export declare function unauthenticatedError(messageOrError?: Maybe<ErrorMessageOrPartialServerError>): HttpsError;
32
24
  /**
33
25
  * Creates a forbidden (403) {@link HttpsError}.
34
26
  *
35
27
  * @param messageOrError - Optional error message string or partial server error object.
36
28
  * @returns A new forbidden (403) {@link HttpsError}.
37
29
  */
38
- export declare function forbiddenError(messageOrError?: ErrorMessageOrPartialServerError): HttpsError;
39
- export declare const PERMISSION_DENIED_ERROR_CODE = "PERMISSION_DENIED";
30
+ export declare function forbiddenError(messageOrError?: Maybe<ErrorMessageOrPartialServerError>): HttpsError;
40
31
  /**
41
32
  * Creates a permission-denied (403) {@link HttpsError}.
42
33
  *
43
34
  * @param messageOrError - Optional error message string or partial server error object.
44
35
  * @returns A new permission-denied (403) {@link HttpsError}.
45
36
  */
46
- export declare function permissionDeniedError(messageOrError?: ErrorMessageOrPartialServerError): HttpsError;
47
- export declare const NOT_FOUND_ERROR_CODE = "NOT_FOUND";
37
+ export declare function permissionDeniedError(messageOrError?: Maybe<ErrorMessageOrPartialServerError>): HttpsError;
48
38
  /**
49
39
  * Creates a not-found (404) {@link HttpsError}.
50
40
  *
51
41
  * @param messageOrError - Optional error message string or partial server error object.
52
42
  * @returns A new not-found (404) {@link HttpsError}.
53
43
  */
54
- export declare function notFoundError(messageOrError?: ErrorMessageOrPartialServerError): HttpsError;
55
- export declare const MODEL_NOT_AVAILABLE_ERROR_CODE = "MODEL_NOT_AVAILABLE";
44
+ export declare function notFoundError(messageOrError?: Maybe<ErrorMessageOrPartialServerError>): HttpsError;
56
45
  /**
57
46
  * Creates a model-not-available (404) {@link HttpsError}, used when a Firestore document does not exist.
58
47
  *
59
48
  * @param messageOrError - Optional error message string or partial server error object.
60
49
  * @returns A new model-not-available (404) {@link HttpsError}.
61
50
  */
62
- export declare function modelNotAvailableError(messageOrError?: ErrorMessageOrPartialServerError): HttpsError;
63
- export declare const BAD_REQUEST_ERROR_CODE = "BAD_REQUEST";
51
+ export declare function modelNotAvailableError(messageOrError?: Maybe<ErrorMessageOrPartialServerError>): HttpsError;
64
52
  /**
65
53
  * Creates a bad-request (400) {@link HttpsError}.
66
54
  *
67
55
  * @param messageOrError - Optional error message string or partial server error object.
68
56
  * @returns A new bad-request (400) {@link HttpsError}.
69
57
  */
70
- export declare function badRequestError(messageOrError?: ErrorMessageOrPartialServerError): HttpsError;
71
- export declare const CONFLICT_ERROR_CODE = "CONFLICT";
58
+ export declare function badRequestError(messageOrError?: Maybe<ErrorMessageOrPartialServerError>): HttpsError;
72
59
  /**
73
60
  * Creates a precondition-conflict (409) {@link HttpsError}.
74
61
  *
75
62
  * @param messageOrError - Optional error message string or partial server error object.
76
63
  * @returns A new precondition-conflict (409) {@link HttpsError}.
77
64
  */
78
- export declare function preconditionConflictError(messageOrError?: ErrorMessageOrPartialServerError): HttpsError;
79
- export declare const ALREADY_EXISTS_ERROR_CODE = "ALREADY_EXISTS";
65
+ export declare function preconditionConflictError(messageOrError?: Maybe<ErrorMessageOrPartialServerError>): HttpsError;
80
66
  /**
81
67
  * Creates an already-exists (409) {@link HttpsError}.
82
68
  *
83
69
  * @param messageOrError - Optional error message string or partial server error object.
84
70
  * @returns A new already-exists (409) {@link HttpsError}.
85
71
  */
86
- export declare function alreadyExistsError(messageOrError?: ErrorMessageOrPartialServerError): HttpsError;
87
- export declare const UNAVAILABLE_ERROR_CODE = "UNAVAILABLE";
72
+ export declare function alreadyExistsError(messageOrError?: Maybe<ErrorMessageOrPartialServerError>): HttpsError;
88
73
  /**
89
74
  * Creates an unavailable (503) {@link HttpsError}.
90
75
  *
91
76
  * @param messageOrError - Optional error message string or partial server error object.
92
77
  * @returns A new unavailable (503) {@link HttpsError}.
93
78
  */
94
- export declare function unavailableError(messageOrError?: ErrorMessageOrPartialServerError): HttpsError;
95
- export declare const UNAVAILABLE_OR_DEACTIVATED_FUNCTION_ERROR_CODE = "UNAVAILABLE_OR_DEACTIVATED_FUNCTION";
79
+ export declare function unavailableError(messageOrError?: Maybe<ErrorMessageOrPartialServerError>): HttpsError;
96
80
  /**
97
81
  * Creates an unimplemented (501) {@link HttpsError} for deactivated or unavailable functions.
98
82
  *
99
83
  * @param messageOrError - Optional error message string or partial server error object.
100
84
  * @returns A new unimplemented (501) {@link HttpsError}.
101
85
  */
102
- export declare function unavailableOrDeactivatedFunctionError(messageOrError?: ErrorMessageOrPartialServerError): HttpsError;
103
- export declare const INTERNAL_SERVER_ERROR_CODE = "INTERNAL_ERROR";
86
+ export declare function unavailableOrDeactivatedFunctionError(messageOrError?: Maybe<ErrorMessageOrPartialServerError>): HttpsError;
104
87
  /**
105
88
  * Creates an internal-error (500) {@link HttpsError}.
106
89
  *
107
90
  * @param messageOrError - Optional error message string or partial server error object.
108
91
  * @returns A new internal-error (500) {@link HttpsError}.
109
92
  */
110
- export declare function internalServerError(messageOrError?: ErrorMessageOrPartialServerError): HttpsError;
93
+ export declare function internalServerError(messageOrError?: Maybe<ErrorMessageOrPartialServerError>): HttpsError;
111
94
  /**
112
95
  * Discriminator for the type of Firebase server error encountered.
113
96
  */