@dereekb/firebase-server 13.12.3 → 13.12.4

package/oidc/src/lib/service/oidc.client.service.d.ts

@@ -13,14 +13,19 @@ export declare class OidcClientService {
     /**
      * Creates a new OIDC client through the oidc-provider.
      *
-     * Generates `client_id` and `client_secret` using the same defaults as oidc-provider's
-     * registration flow, validates via `Client.validate`, and persists through the adapter.
+     * Generates `client_id` (and, when the auth method requires one, a `client_secret`) using the
+     * same defaults as oidc-provider's registration flow, validates via `Client.validate`, and
+     * persists through the adapter.
+     *
+     * A secret is only generated when `ProviderClient.needsSecret()` returns `true`. The secret-less
+     * methods `private_key_jwt` and `'none'` (public PKCE client) therefore persist no secret and the
+     * returned `client_secret` is `undefined`.
      *
      * @param params - Client registration parameters.
      * @param validatedMetadata - Optional pre-validated metadata to merge into the client properties.
      *   Use this for server-side fields (e.g., inline `jwks`) that have already been validated
      *   and should not be exposed through the API params.
-     * @returns The generated client ID and secret (plaintext, returned only once).
+     * @returns The generated client ID and, for secret-based methods, the secret (plaintext, returned only once).
      */
     createClient(params: CreateOidcClientParams, validatedMetadata?: Partial<Pick<ClientMetadata, 'jwks'>>): Promise<CreateOidcClientResult>;
     /**
@@ -42,9 +47,12 @@ export declare class OidcClientService {
      * Generates a new `client_secret`, re-validates via `Client.validate()`, and persists.
      * The new secret is returned in plaintext — this is the only time it is available.
      *
+     * Rejects public PKCE clients (`token_endpoint_auth_method === 'none'`): they have no secret,
+     * so there is nothing to rotate.
+     *
      * @param clientId - The client's document/adapter entry ID.
      * @returns The client ID and new secret (plaintext, returned only once).
-     * @throws {Error} When the client is not found.
+     * @throws {Error} When the client is not found, or is a public PKCE (`none`) client.
      */
     rotateClientSecret(clientId: OidcEntryClientId): Promise<RotateOidcClientSecretResult>;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase-server",
-  "version": "13.12.3",
+  "version": "13.12.4",
   "sideEffects": false,
   "exports": {
     "./test": {
@@ -57,15 +57,15 @@
   "types": "./src/index.d.ts",
   "peerDependencies": {
     "@cantoo/pdf-lib": "^2.6.5",
-    "@dereekb/analytics": "13.12.3",
-    "@dereekb/date": "13.12.3",
-    "@dereekb/dbx-core": "13.12.3",
-    "@dereekb/firebase": "13.12.3",
-    "@dereekb/model": "13.12.3",
-    "@dereekb/nestjs": "13.12.3",
-    "@dereekb/rxjs": "13.12.3",
-    "@dereekb/util": "13.12.3",
-    "@dereekb/zoho": "13.12.3",
+    "@dereekb/analytics": "13.12.4",
+    "@dereekb/date": "13.12.4",
+    "@dereekb/dbx-core": "13.12.4",
+    "@dereekb/firebase": "13.12.4",
+    "@dereekb/model": "13.12.4",
+    "@dereekb/nestjs": "13.12.4",
+    "@dereekb/rxjs": "13.12.4",
+    "@dereekb/util": "13.12.4",
+    "@dereekb/zoho": "13.12.4",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.19.0",
     "@modelcontextprotocol/sdk": "1.29.0",

package/src/lib/auth/auth.service.d.ts

@@ -669,23 +669,82 @@ export interface FirebaseServerAuthPasswordResetSendContentConfig<D = unknown> {
      */
     readonly data?: Maybe<D>;
 }
+/**
+ * Opaque composite token returned to the user during a password reset. Encodes both
+ * the raw reset code and the target uid in a single value so the completion call does
+ * not need a separate uid argument (which a logged-out forgot-password flow cannot provide).
+ *
+ * The on-the-wire shape is `<code>-<uid>`. The raw code is the numeric string produced by
+ * {@link DEFAULT_FIREBASE_PASSWORD_NUMBER_GENERATOR}, so the first `-` cleanly splits the token.
+ * Do not split or mutate the token outside of {@link decodeFirebaseServerUserPasswordResetOobCode}.
+ */
+export type FirebaseServerUserPasswordResetOobCode = string & {
+    __firebaseServerUserPasswordResetOobCode: true;
+};
+/**
+ * Builds the composite oob code from a raw reset code (the numeric value stored in
+ * {@link FirebaseServerAuthResetUserPasswordClaims.resetPassword}) and the target user's uid.
+ *
+ * @param uid - The target user's UID.
+ * @param code - The raw reset code from the user's claims.
+ *
+ * @example
+ * ```typescript
+ * const oobCode = encodeFirebaseServerUserPasswordResetOobCode(user.uid, claims.resetPassword);
+ * // e.g. '482910-abcDEF123'
+ * ```
+ */
+export declare function encodeFirebaseServerUserPasswordResetOobCode(uid: FirebaseAuthUserId, code: string): FirebaseServerUserPasswordResetOobCode;
+/**
+ * Decodes a composite oob code back into its `{ uid, code }` parts. Returns `undefined`
+ * when the token is malformed (missing separator, non-numeric code, empty uid).
+ *
+ * @param token - The composite oob token, typically received from the password-reset email.
+ *
+ * @example
+ * ```typescript
+ * const decoded = decodeFirebaseServerUserPasswordResetOobCode('482910-abcDEF123');
+ * // decoded = { uid: 'abcDEF123', code: '482910' }
+ * ```
+ */
+export declare function decodeFirebaseServerUserPasswordResetOobCode(token: string): {
+    uid: FirebaseAuthUserId;
+    code: string;
+} | undefined;
 /**
  * Details about a user that is in the password reset phase, including their user context,
- * reset claims data, and the send configuration that was used.
+ * reset claims data, the encoded oob code intended for the user, and the send configuration that was used.
  */
 export interface FirebaseServerAuthPasswordResetDetails<U extends FirebaseServerAuthUserContext = FirebaseServerAuthUserContext, D = unknown> extends FirebaseServerAuthPasswordResetSendContentConfig<D> {
     readonly userContext: U;
     readonly claims: FirebaseAuthResetUserPasswordClaimsData;
+    /**
+     * The encoded oob code intended for the user (carries the raw reset code AND the target uid).
+     * Subclasses that send password-reset emails should embed this value, not `claims.resetPassword`.
+     */
+    readonly oobCode: FirebaseServerUserPasswordResetOobCode;
 }
 /**
- * Input for completing a password reset, containing the temporary reset code
- * and the desired new password.
+ * Result of {@link FirebaseServerUserPasswordResetService.beginPasswordReset}, exposing both the
+ * stored reset claims and the encoded composite oob code intended for the user.
+ */
+export interface FirebaseServerAuthBeginPasswordResetResult {
+    readonly claims: FirebaseServerAuthResetUserPasswordClaims;
+    /**
+     * The encoded oob code that should be delivered to the user (e.g. embedded in the reset email).
+     */
+    readonly oobCode: FirebaseServerUserPasswordResetOobCode;
+}
+/**
+ * Input for completing a password reset, containing the composite oob code from the recovery email
+ * (which encodes both the temporary reset code AND the target uid) and the desired new password.
  */
 export interface FirebaseServerAuthCompletePasswordResetInput {
     /**
-     * The temporary reset code from the reset email, to be verified against claims.
+     * The full oob token from the recovery email — encodes both the raw reset code AND the target uid.
+     * The service decodes this internally to resolve the user and verify the embedded code.
      */
-    readonly resetPassword: string;
+    readonly oobCode: FirebaseServerUserPasswordResetOobCode;
     /**
      * The new password to set after verification succeeds.
      */
@@ -700,9 +759,9 @@ export interface FirebaseServerAuthCompletePasswordResetInput {
  * @example
  * ```typescript
  * const resetSvc = authService.passwordReset();
- * const claims = await resetSvc.beginPasswordReset({ uid: 'some-uid', sendResetContent: true });
- * // Later, after user verifies identity:
- * await resetSvc.completePasswordReset('some-uid', { resetPassword: '123456', newPassword: 'newSecure' });
+ * const { oobCode } = await resetSvc.beginPasswordReset({ uid: 'some-uid', sendResetContent: true });
+ * // Later, after the user clicks the link in their reset email:
+ * await resetSvc.completePasswordReset({ oobCode, newPassword: 'newSecure' });
  * ```
  */
 export interface FirebaseServerUserPasswordResetService<D = unknown, U extends FirebaseServerAuthUserContext = FirebaseServerAuthUserContext> {
@@ -713,13 +772,16 @@ export interface FirebaseServerUserPasswordResetService<D = unknown, U extends F
      * When `sendResetContent` is true, this method delegates to {@link sendResetContent} and
      * may throw the same errors (throttle, send-once, no-config) depending on the configuration.
      *
+     * Returns both the stored reset claims and the encoded composite oob code that should be
+     * delivered to the user (the value the user will later submit to {@link completePasswordReset}).
+     *
      * @param input - Configuration for the reset, including user identification and send options.
      * @throws {Error} Throws if neither uid nor email is provided.
      * @throws {FirebaseServerAuthPasswordResetThrottleError} When send is throttled and `sendResetThrowErrors` is true.
      * @throws {FirebaseServerAuthPasswordResetSendOnceError} When already sent and `sendResetDetailsOnce` + `sendResetThrowErrors` are true.
      * @throws {FirebaseServerAuthPasswordResetNoResetConfigError} When no reset claims exist and `sendResetThrowErrors` is true.
      */
-    beginPasswordReset(input: FirebaseServerAuthInitiatePasswordReset<D>): Promise<FirebaseServerAuthResetUserPasswordClaims>;
+    beginPasswordReset(input: FirebaseServerAuthInitiatePasswordReset<D>): Promise<FirebaseServerAuthBeginPasswordResetResult>;
     /**
      * Sends reset content (e.g., a reset email) to the user.
      *
@@ -750,14 +812,19 @@ export interface FirebaseServerUserPasswordResetService<D = unknown, U extends F
      */
     loadResetDetailsForUserContext(userContext: U, config?: FirebaseServerAuthPasswordResetSendContentConfig<D>): Promise<Maybe<FirebaseServerAuthPasswordResetDetails<U, D>>>;
     /**
-     * Completes the password reset by verifying the temporary reset code against the user's
-     * claims and setting the new password. Clears reset claims on success.
+     * Completes the password reset by decoding the composite oob token, resolving the target user,
+     * verifying the embedded reset code against the user's claims, and setting the new password.
+     * Clears reset claims on success.
      *
-     * @param uid - The target user's UID.
-     * @param input - The reset code and new password.
-     * @throws {FirebaseServerAuthPasswordResetInvalidCodeError} When the reset code is invalid or no reset is active.
+     * The target uid is read from the encoded token — callers do not need to know it separately,
+     * which is what enables the logged-out "forgot password" flow.
+     *
+     * @param input - The encoded oob token and new password.
+     * @throws {FirebaseServerAuthPasswordResetInvalidCodeError} When the token is malformed, the
+     *   embedded uid does not own an active reset, the code is expired, or the code does not match.
+     *   The same opaque error is thrown for every failure mode.
      */
-    completePasswordReset(uid: FirebaseAuthUserId, input: FirebaseServerAuthCompletePasswordResetInput): Promise<admin.auth.UserRecord>;
+    completePasswordReset(input: FirebaseServerAuthCompletePasswordResetInput): Promise<admin.auth.UserRecord>;
 }
 /**
  * Default throttle duration (60 seconds) between reset content re-sends to prevent spam while
@@ -798,7 +865,7 @@ export declare abstract class AbstractFirebaseServerUserPasswordResetService<U e
     protected resetThrottleTime: Milliseconds;
     constructor(authService: FirebaseServerAuthService<U, C>);
     get authService(): FirebaseServerAuthService<U, C>;
-    beginPasswordReset(input: FirebaseServerAuthInitiatePasswordReset<D>): Promise<FirebaseServerAuthResetUserPasswordClaims>;
+    beginPasswordReset(input: FirebaseServerAuthInitiatePasswordReset<D>): Promise<FirebaseServerAuthBeginPasswordResetResult>;
     sendResetContent(uid: FirebaseAuthUserId, config?: FirebaseServerAuthPasswordResetSendContentConfig<D>): Promise<boolean>;
     loadResetDetails(uid: FirebaseAuthUserId, config?: FirebaseServerAuthPasswordResetSendContentConfig<D>): Promise<Maybe<FirebaseServerAuthPasswordResetDetails<U, D>>>;
     loadResetDetailsForUserContext(userContext: U, config?: FirebaseServerAuthPasswordResetSendContentConfig<D>): Promise<Maybe<FirebaseServerAuthPasswordResetDetails<U, D>>>;
@@ -808,7 +875,7 @@ export declare abstract class AbstractFirebaseServerUserPasswordResetService<U e
      * @param details - The user's reset details containing the user context.
      */
     protected updateResetContentSentTime(details: FirebaseServerAuthPasswordResetDetails<U, D>): Promise<void>;
-    completePasswordReset(uid: FirebaseAuthUserId, input: FirebaseServerAuthCompletePasswordResetInput): Promise<admin.auth.UserRecord>;
+    completePasswordReset(input: FirebaseServerAuthCompletePasswordResetInput): Promise<admin.auth.UserRecord>;
     /**
      * Delivers reset content (e.g., reset email, SMS) to the user.
      *

package/test/index.cjs.js

@@ -320,6 +320,20 @@ function _ts_generator$a(thisArg, body) {
                 return this.instance.callWrappedFunction(fn, params, skipJsonConversion);
             }
         },
+        {
+            /**
+     * Convenience function for calling the function without an authenticated user context.
+     *
+     * Equivalent to `fn(params, options ?? {})`.
+     *
+     * @param fn
+     * @param params
+     * @returns
+     */ key: "callWrappedFunctionWithoutUserContext",
+            value: function callWrappedFunctionWithoutUserContext(fn, params, options) {
+                return this.instance.callWrappedFunctionWithoutUserContext(fn, params, options);
+            }
+        },
         {
             key: "callCloudFunction",
             value: function callCloudFunction(fn, params) {
@@ -436,6 +450,21 @@ function _ts_generator$a(thisArg, body) {
                 });
             }
         },
+        {
+            /**
+     * Convenience function for calling the function without an authenticated user context.
+     *
+     * Equivalent to `fn(params, options ?? {})`.
+     *
+     * @param fn - Wrapped gen 2 callable request to invoke.
+     * @param params - Request payload to pass to the callable, simulating the JSON body of an HTTP call.
+     * @param options - Optional callable options.
+     * @returns Promise resolving to the callable's return value.
+     */ key: "callWrappedFunctionWithoutUserContext",
+            value: function callWrappedFunctionWithoutUserContext(fn, params, options) {
+                return fn(params, options !== null && options !== void 0 ? options : {});
+            }
+        },
         {
             key: "callCloudFunction",
             value: function callCloudFunction(fn, params) {

package/test/index.esm.js

@@ -319,6 +319,20 @@ function _ts_generator$a(thisArg, body) {
                 return this.instance.callWrappedFunction(fn, params, skipJsonConversion);
             }
         },
+        {
+            /**
+     * Convenience function for calling the function without an authenticated user context.
+     *
+     * Equivalent to `fn(params, options ?? {})`.
+     *
+     * @param fn
+     * @param params
+     * @returns
+     */ key: "callWrappedFunctionWithoutUserContext",
+            value: function callWrappedFunctionWithoutUserContext(fn, params, options) {
+                return this.instance.callWrappedFunctionWithoutUserContext(fn, params, options);
+            }
+        },
         {
             key: "callCloudFunction",
             value: function callCloudFunction(fn, params) {
@@ -435,6 +449,21 @@ function _ts_generator$a(thisArg, body) {
                 });
             }
         },
+        {
+            /**
+     * Convenience function for calling the function without an authenticated user context.
+     *
+     * Equivalent to `fn(params, options ?? {})`.
+     *
+     * @param fn - Wrapped gen 2 callable request to invoke.
+     * @param params - Request payload to pass to the callable, simulating the JSON body of an HTTP call.
+     * @param options - Optional callable options.
+     * @returns Promise resolving to the callable's return value.
+     */ key: "callWrappedFunctionWithoutUserContext",
+            value: function callWrappedFunctionWithoutUserContext(fn, params, options) {
+                return fn(params, options !== null && options !== void 0 ? options : {});
+            }
+        },
         {
             key: "callCloudFunction",
             value: function callCloudFunction(fn, params) {

package/test/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/firebase-server/test",
-  "version": "13.12.3",
+  "version": "13.12.4",
   "peerDependencies": {
-    "@dereekb/analytics": "13.12.3",
-    "@dereekb/date": "13.12.3",
-    "@dereekb/firebase": "13.12.3",
-    "@dereekb/firebase-server": "13.12.3",
-    "@dereekb/firebase-server/oidc": "13.12.3",
-    "@dereekb/model": "13.12.3",
-    "@dereekb/nestjs": "13.12.3",
-    "@dereekb/rxjs": "13.12.3",
-    "@dereekb/util": "13.12.3",
+    "@dereekb/analytics": "13.12.4",
+    "@dereekb/date": "13.12.4",
+    "@dereekb/firebase": "13.12.4",
+    "@dereekb/firebase-server": "13.12.4",
+    "@dereekb/firebase-server/oidc": "13.12.4",
+    "@dereekb/model": "13.12.4",
+    "@dereekb/nestjs": "13.12.4",
+    "@dereekb/rxjs": "13.12.4",
+    "@dereekb/util": "13.12.4",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.19.0",
     "@nestjs/common": "^11.1.19",
@@ -23,7 +23,7 @@
     "supertest": "^7.2.2"
   },
   "devDependencies": {
-    "@dereekb/nestjs": "13.12.3"
+    "@dereekb/nestjs": "13.12.4"
   },
   "exports": {
     "./package.json": "./package.json",

package/test/src/lib/firebase/firebase.admin.auth.d.ts

@@ -42,6 +42,7 @@ export interface AuthorizedUserTestContext {
     loadDecodedIdToken(): Promise<DecodedIdToken>;
     makeContextOptions(): Promise<ContextOptions>;
     callWrappedFunction<F extends WrappedCallableRequest<any, any>>(fn: F, params: WrappedCallableRequestParams<F>, skipJsonConversion?: boolean): Promise<WrappedCallableRequestOutput<F>>;
+    callWrappedFunctionWithoutUserContext<F extends WrappedCallableRequest<any, any>>(fn: F, params: WrappedCallableRequestParams<F>, options?: CallableContextOptions): Promise<WrappedCallableRequestOutput<F>>;
     /**
      * Used for calling any non-callable gen 2 function (e.g. scheduled functions, cloud functions, blocking functions) or any gen 1 function.
      *
@@ -75,6 +76,16 @@ export declare class AuthorizedUserTestContextFixture<PI extends FirebaseAdminTe
     loadDecodedIdToken(): Promise<DecodedIdToken>;
     makeContextOptions(): Promise<ContextOptions>;
     callWrappedFunction<F extends WrappedCallableRequest<any, any>>(fn: F, params: WrappedCallableRequestParams<F>, skipJsonConversion?: boolean): Promise<WrappedCallableRequestOutput<F>>;
+    /**
+     * Convenience function for calling the function without an authenticated user context.
+     *
+     * Equivalent to `fn(params, options ?? {})`.
+     *
+     * @param fn
+     * @param params
+     * @returns
+     */
+    callWrappedFunctionWithoutUserContext<F extends WrappedCallableRequest<any, any>>(fn: F, params: WrappedCallableRequestParams<F>, options?: CallableContextOptions): Promise<WrappedCallableRequestOutput<F>>;
     callCloudFunction<F extends WrappedCloudFunction<I, O>, I extends object, O = unknown>(fn: F, params: I, skipJsonConversion?: boolean): Promise<O>;
     callCloudFunction<F extends WrappedScheduledFunction, O = unknown>(fn: F): Promise<O>;
     callCloudFunction<F extends WrappedBlockingFunctionWithHandler<E, O>, E extends object, O>(fn: F, params: E): Promise<O>;
@@ -115,6 +126,17 @@ export declare class AuthorizedUserTestContextInstance<PI extends FirebaseAdminT
      * @returns Promise resolving to the callable's return value.
      */
     callWrappedFunction<F extends WrappedCallableRequest<any, any>>(fn: F, params: WrappedCallableRequestParams<F>, skipJsonConversion?: boolean): Promise<WrappedCallableRequestOutput<F>>;
+    /**
+     * Convenience function for calling the function without an authenticated user context.
+     *
+     * Equivalent to `fn(params, options ?? {})`.
+     *
+     * @param fn - Wrapped gen 2 callable request to invoke.
+     * @param params - Request payload to pass to the callable, simulating the JSON body of an HTTP call.
+     * @param options - Optional callable options.
+     * @returns Promise resolving to the callable's return value.
+     */
+    callWrappedFunctionWithoutUserContext<F extends WrappedCallableRequest<any, any>>(fn: F, params: WrappedCallableRequestParams<F>, options?: CallableContextOptions): Promise<WrappedCallableRequestOutput<F>>;
     /**
      * Calls a wrapped gen 2 scheduled/blocking/event function with the input params and context options from makeContextOptions().
      *

package/twilio/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@dereekb/firebase-server/twilio",
-  "version": "13.12.3",
+  "version": "13.12.4",
   "peerDependencies": {
-    "@dereekb/date": "13.12.3",
-    "@dereekb/firebase": "13.12.3",
-    "@dereekb/firebase-server": "13.12.3",
-    "@dereekb/model": "13.12.3",
-    "@dereekb/nestjs": "13.12.3",
-    "@dereekb/rxjs": "13.12.3",
-    "@dereekb/util": "13.12.3"
+    "@dereekb/date": "13.12.4",
+    "@dereekb/firebase": "13.12.4",
+    "@dereekb/firebase-server": "13.12.4",
+    "@dereekb/model": "13.12.4",
+    "@dereekb/nestjs": "13.12.4",
+    "@dereekb/rxjs": "13.12.4",
+    "@dereekb/util": "13.12.4"
   },
   "exports": {
     "./package.json": "./package.json",

package/zoho/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@dereekb/firebase-server/zoho",
-  "version": "13.12.3",
+  "version": "13.12.4",
   "peerDependencies": {
-    "@dereekb/analytics": "13.12.3",
-    "@dereekb/date": "13.12.3",
-    "@dereekb/model": "13.12.3",
-    "@dereekb/nestjs": "13.12.3",
-    "@dereekb/rxjs": "13.12.3",
-    "@dereekb/firebase": "13.12.3",
-    "@dereekb/util": "13.12.3",
-    "@dereekb/zoho": "13.12.3"
+    "@dereekb/analytics": "13.12.4",
+    "@dereekb/date": "13.12.4",
+    "@dereekb/model": "13.12.4",
+    "@dereekb/nestjs": "13.12.4",
+    "@dereekb/rxjs": "13.12.4",
+    "@dereekb/firebase": "13.12.4",
+    "@dereekb/util": "13.12.4",
+    "@dereekb/zoho": "13.12.4"
   },
   "exports": {
     "./package.json": "./package.json",