@dereekb/firebase-server 13.11.18 → 13.12.0

package/index.cjs.js

@@ -1,5 +1,6 @@
 'use strict';
 
+var node_crypto = require('node:crypto');
 var firebase = require('@dereekb/firebase');
 var util = require('@dereekb/util');
 var https = require('firebase-functions/https');
@@ -1241,12 +1242,14 @@ function _ts_generator$g(thisArg, body) {
             key: "beginResetPassword",
             value: function beginResetPassword() {
                 return _async_to_generator$g(function() {
-                    var password, _obj, passwordClaimsData;
+                    var password, now, expiresAt, _obj, passwordClaimsData;
                     return _ts_generator$g(this, function(_state) {
                         switch(_state.label){
                             case 0:
                                 password = this._generateResetPasswordKey();
-                                passwordClaimsData = (_obj = {}, _define_property$x(_obj, firebase.FIREBASE_SERVER_AUTH_CLAIMS_RESET_PASSWORD_KEY, password), _define_property$x(_obj, firebase.FIREBASE_SERVER_AUTH_CLAIMS_RESET_LAST_COM_DATE_KEY, date.toISODateString(new Date())), _obj);
+                                now = new Date();
+                                expiresAt = new Date(now.getTime() + this._resetCodeExpiresInMs());
+                                passwordClaimsData = (_obj = {}, _define_property$x(_obj, firebase.FIREBASE_SERVER_AUTH_CLAIMS_RESET_PASSWORD_KEY, password), _define_property$x(_obj, firebase.FIREBASE_SERVER_AUTH_CLAIMS_RESET_LAST_COM_DATE_KEY, date.toISODateString(now)), _define_property$x(_obj, firebase.FIREBASE_SERVER_AUTH_CLAIMS_RESET_EXPIRES_AT_KEY, date.toISODateString(expiresAt)), _obj);
                                 // set the claims
                                 return [
                                     4,
@@ -1272,6 +1275,17 @@ function _ts_generator$g(thisArg, body) {
                 }).call(this);
             }
         },
+        {
+            /**
+     * Returns the TTL (in milliseconds) for newly-generated reset codes. Subclasses may override
+     * to customize expiry.
+     *
+     * @returns The TTL in milliseconds for newly-generated reset codes.
+     */ key: "_resetCodeExpiresInMs",
+            value: function _resetCodeExpiresInMs() {
+                return DEFAULT_RESET_CODE_EXPIRES_IN;
+            }
+        },
         {
             key: "loadResetPasswordClaims",
             value: function loadResetPasswordClaims() {
@@ -1315,7 +1329,7 @@ function _ts_generator$g(thisArg, body) {
                                 // clear password reset claims
                                 return [
                                     4,
-                                    this.updateClaims((_obj = {}, _define_property$x(_obj, firebase.FIREBASE_SERVER_AUTH_CLAIMS_RESET_PASSWORD_KEY, null), _define_property$x(_obj, firebase.FIREBASE_SERVER_AUTH_CLAIMS_RESET_LAST_COM_DATE_KEY, null), _obj))
+                                    this.updateClaims((_obj = {}, _define_property$x(_obj, firebase.FIREBASE_SERVER_AUTH_CLAIMS_RESET_PASSWORD_KEY, null), _define_property$x(_obj, firebase.FIREBASE_SERVER_AUTH_CLAIMS_RESET_LAST_COM_DATE_KEY, null), _define_property$x(_obj, firebase.FIREBASE_SERVER_AUTH_CLAIMS_RESET_EXPIRES_AT_KEY, null), _obj))
                                 ];
                             case 2:
                                 _state.sent();
@@ -2110,10 +2124,17 @@ function _ts_generator$g(thisArg, body) {
     return NoSetupContentFirebaseServerNewUserService;
 }(AbstractFirebaseServerNewUserService);
 /**
- * Default throttle duration (1 hour) between reset content sends to prevent spam.
+ * Default throttle duration (60 seconds) between reset content re-sends to prevent spam while
+ * remaining responsive for legitimate users who didn't receive the first email.
  *
  * Used by {@link AbstractFirebaseServerUserPasswordResetService.sendResetContent} to rate-limit delivery.
- */ var DEFAULT_RESET_COM_THROTTLE_TIME = date.hoursToMs(1);
+ */ var DEFAULT_RESET_COM_THROTTLE_TIME = date.minutesToMs(1);
+/**
+ * Default lifetime (15 minutes) of a reset code before it expires.
+ *
+ * Used by {@link AbstractFirebaseServerAuthUserContext.beginResetPassword} to set
+ * `resetExpiresAt` in the user's claims.
+ */ var DEFAULT_RESET_CODE_EXPIRES_IN = date.minutesToMs(15);
 /**
  * Base implementation of {@link FirebaseServerUserPasswordResetService} that handles reset initiation,
  * claims management, throttled reset content delivery, and reset completion.
@@ -2194,12 +2215,15 @@ function _ts_generator$g(thisArg, body) {
                                     3,
                                     7
                                 ];
+                                // beginResetPassword() just refreshed the claims (including resetCommunicationAt = now),
+                                // so the throttle window from any previous send no longer applies — this is the first send
+                                // of the newly-rotated code and must not be self-throttled.
                                 return [
                                     4,
                                     this.sendResetContent(resolvedUid, {
                                         data: data,
                                         sendResetDetailsOnce: sendResetDetailsOnce,
-                                        ignoreSendThrottleTime: sendResetIgnoreThrottle,
+                                        ignoreSendThrottleTime: sendResetIgnoreThrottle !== null && sendResetIgnoreThrottle !== void 0 ? sendResetIgnoreThrottle : true,
                                         throwErrors: sendResetThrowErrors,
                                         sendDetailsInTestEnvironment: sendDetailsInTestEnvironment
                                     })
@@ -2353,7 +2377,8 @@ function _ts_generator$g(thisArg, body) {
                                         userContext: userContext,
                                         claims: {
                                             resetPassword: claims.resetPassword,
-                                            resetCommunicationAt: claims.resetCommunicationAt
+                                            resetCommunicationAt: claims.resetCommunicationAt,
+                                            resetExpiresAt: claims.resetExpiresAt
                                         },
                                         data: config === null || config === void 0 ? void 0 : config.data,
                                         sendDetailsInTestEnvironment: config === null || config === void 0 ? void 0 : config.sendDetailsInTestEnvironment
@@ -2399,7 +2424,7 @@ function _ts_generator$g(thisArg, body) {
             key: "completePasswordReset",
             value: function completePasswordReset(uid, input) {
                 return _async_to_generator$g(function() {
-                    var userContext, claims;
+                    var userContext, claims, storedCode, expiresAt, storedBuf, inputBuf;
                     return _ts_generator$g(this, function(_state) {
                         switch(_state.label){
                             case 0:
@@ -2410,7 +2435,18 @@ function _ts_generator$g(thisArg, body) {
                                 ];
                             case 1:
                                 claims = _state.sent();
-                                if ((claims === null || claims === void 0 ? void 0 : claims.resetPassword) !== input.resetPassword) {
+                                storedCode = claims === null || claims === void 0 ? void 0 : claims.resetPassword;
+                                expiresAt = claims === null || claims === void 0 ? void 0 : claims.resetExpiresAt;
+                                // Reject if no active reset OR the stored code is missing/wrong length OR the code is expired.
+                                // All failure cases throw the same opaque error so callers cannot distinguish them.
+                                if (!storedCode || !expiresAt || storedCode.length !== input.resetPassword.length || new Date(expiresAt).getTime() <= Date.now()) {
+                                    throw new FirebaseServerAuthPasswordResetInvalidCodeError();
+                                }
+                                // Constant-time comparison to avoid leaking timing information about how many leading
+                                // characters of the provided code matched. Lengths are equal per the guard above.
+                                storedBuf = Buffer.from(storedCode);
+                                inputBuf = Buffer.from(input.resetPassword);
+                                if (!node_crypto.timingSafeEqual(storedBuf, inputBuf)) {
                                     throw new FirebaseServerAuthPasswordResetInvalidCodeError();
                                 }
                                 return [
@@ -2919,7 +2955,7 @@ function _async_to_generator$e(fn) {
         });
     };
 }
-function _instanceof$2(left, right) {
+function _instanceof$3(left, right) {
     "@swc/helpers - instanceof";
     if (right != null && typeof Symbol !== "undefined" && right[Symbol.hasInstance]) {
         return !!right[Symbol.hasInstance](left);
@@ -3031,15 +3067,28 @@ function _ts_generator$e(thisArg, body) {
  * catching password-reset-specific errors and re-throwing them as appropriate {@link HttpsError} instances
  * suitable for returning to clients.
  *
- * Error mapping:
+ * Default mapping (security-hardened — enumeration-safe, for end-user callers):
+ * - {@link FirebaseServerAuthPasswordResetInvalidCodeError} → permission-denied (403)
+ * - {@link FirebaseServerAuthPasswordResetNoResetConfigError} → permission-denied (403), same opaque
+ *   response as InvalidCode so callers cannot distinguish "wrong code" from "no reset active".
+ * - {@link FirebaseServerAuthPasswordResetSendOnceError} → permission-denied (403), same opaque
+ *   response so callers cannot probe whether a reset was already initiated.
+ * - {@link FirebaseServerAuthPasswordResetThrottleError} → unavailable (503) with a generic message
+ *   (no `lastSentAt` is leaked).
+ *
+ * Admin mapping (`isAdmin: true`) — preserves distinct error codes and statuses so an admin
+ * resetting on behalf of another user can see the actual reason. Used when the call originates
+ * from an authenticated admin, where enumeration is not a concern:
  * - {@link FirebaseServerAuthPasswordResetInvalidCodeError} → permission-denied (403)
- * - {@link FirebaseServerAuthPasswordResetNoResetConfigError} → bad-request (400)
- * - {@link FirebaseServerAuthPasswordResetThrottleError} → unavailable (503)
- * - {@link FirebaseServerAuthPasswordResetSendOnceError} → bad-request (400)
+ * - {@link FirebaseServerAuthPasswordResetNoResetConfigError} → bad-request (400), distinct message
+ * - {@link FirebaseServerAuthPasswordResetSendOnceError} → bad-request (400), distinct message
+ * - {@link FirebaseServerAuthPasswordResetThrottleError} → unavailable (503), same as default
  *
  * @param fn - The async function to execute.
+ * @param isAdmin - When `true`, returns distinct error codes/messages instead of the
+ *   enumeration-safe opaque response. Pass the caller's admin status here.
  * @returns The result of the function.
- */ function catchAndThrowPasswordResetServerErrors(fn) {
+ */ function catchAndThrowPasswordResetServerErrors(fn, isAdmin) {
     return _async_to_generator$e(function() {
         var result, error;
         return _ts_generator$e(this, function(_state) {
@@ -3063,14 +3112,14 @@ function _ts_generator$e(thisArg, body) {
                     ];
                 case 2:
                     error = _state.sent();
-                    if (_instanceof$2(error, FirebaseServerAuthPasswordResetInvalidCodeError)) {
+                    if (_instanceof$3(error, FirebaseServerAuthPasswordResetInvalidCodeError)) {
                         throw authServicePasswordResetInvalidCodeError();
-                    } else if (_instanceof$2(error, FirebaseServerAuthPasswordResetNoResetConfigError)) {
-                        throw authServicePasswordResetNoConfigError();
-                    } else if (_instanceof$2(error, FirebaseServerAuthPasswordResetThrottleError)) {
+                    } else if (_instanceof$3(error, FirebaseServerAuthPasswordResetNoResetConfigError)) {
+                        throw isAdmin ? authServicePasswordResetNoConfigError() : authServicePasswordResetInvalidCodeError();
+                    } else if (_instanceof$3(error, FirebaseServerAuthPasswordResetSendOnceError)) {
+                        throw isAdmin ? authServicePasswordResetSendOnceError() : authServicePasswordResetInvalidCodeError();
+                    } else if (_instanceof$3(error, FirebaseServerAuthPasswordResetThrottleError)) {
                         throw authServicePasswordResetThrottleError();
-                    } else if (_instanceof$2(error, FirebaseServerAuthPasswordResetSendOnceError)) {
-                        throw authServicePasswordResetSendOnceError();
                     }
                     throw error;
                 case 3:
@@ -3089,12 +3138,17 @@ function _ts_generator$e(thisArg, body) {
  */ function authServicePasswordResetInvalidCodeError() {
     return permissionDeniedError({
         code: firebase.DBX_FIREBASE_SERVER_PASSWORD_RESET_INVALID_CODE_ERROR_CODE,
-        message: 'Invalid or expired reset password code.'
+        message: 'Invalid or expired reset code.'
     });
 }
 /**
  * Creates a bad-request (400) server error when no active password reset exists for the user.
  *
+ * Distinct from {@link authServicePasswordResetInvalidCodeError}. Use only when the caller is
+ * trusted (e.g., an admin) and revealing "no reset active" is not an enumeration risk; for
+ * end-user callers, {@link catchAndThrowPasswordResetServerErrors} maps this case to the same
+ * opaque response as `InvalidCodeError`.
+ *
  * @returns An {@link HttpsError} with code `invalid-argument`.
  */ function authServicePasswordResetNoConfigError() {
     return badRequestError({
@@ -6183,6 +6237,49 @@ function _ts_generator$b(thisArg, body) {
     })();
 }
 
+/**
+ * Factory that creates a callable function handling model invokes for multiple model types.
+ *
+ * Dispatches to the correct handler based on the `modelType` field in the request,
+ * enforces auth requirements per handler, and aggregates API details for MCP introspection.
+ *
+ * @param map - Maps model type strings to their invoke handler functions.
+ * @param config - Optional configuration including a pre-assertion hook.
+ * @returns A callable function for the 'invoke' call operation.
+ *
+ * @example
+ * ```typescript
+ * const invokeHandler = onCallInvokeModel<DemoNestContext>({
+ *   guestbookEntry: onCallSpecifierHandler({
+ *     recomputeLikes: guestbookEntryRecomputeLikes
+ *   })
+ * });
+ * ```
+ */ function onCallInvokeModel(map) {
+    var config = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : {};
+    var preAssert = config.preAssert;
+    return _onCallWithCallTypeFunction(map, {
+        callType: 'invoke',
+        preAssert: preAssert,
+        throwOnUnknownModelType: invokeModelUnknownModelTypeError
+    });
+}
+/**
+ * Creates a bad-request error indicating the requested model type is not valid for invoking.
+ *
+ * @param modelType - The unrecognized model type string.
+ * @returns A bad-request error with {@link UNKNOWN_MODEL_TYPE_ERROR_CODE} code.
+ */ function invokeModelUnknownModelTypeError(modelType) {
+    return badRequestError(util.serverError({
+        status: 400,
+        code: firebase.UNKNOWN_MODEL_TYPE_ERROR_CODE,
+        message: 'Invalid type to invoke.',
+        data: {
+            modelType: modelType
+        }
+    }));
+}
+
 function _array_like_to_array$8(arr, len) {
     if (len == null || len > arr.length) len = arr.length;
     for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
@@ -7203,6 +7300,14 @@ function _define_property$l(obj, key, value) {
     }
     return obj;
 }
+function _instanceof$2(left, right) {
+    "@swc/helpers - instanceof";
+    if (right != null && typeof Symbol !== "undefined" && right[Symbol.hasInstance]) {
+        return !!right[Symbol.hasInstance](left);
+    } else {
+        return left instanceof right;
+    }
+}
 function _object_spread$c(target) {
     for(var i = 1; i < arguments.length; i++){
         var source = arguments[i] != null ? arguments[i] : {};
@@ -7321,6 +7426,28 @@ function _ts_generator$9(thisArg, body) {
 /**
  * Maximum number of keys allowed in a multi-read request.
  */ var MAX_MODEL_ACCESS_MULTI_READ_KEYS = 50;
+/**
+ * Maps a single `useMultipleModels` failure entry into the public {@link ModelAccessReadError}
+ * shape. Unwraps the typical Firebase error shapes via {@link firebaseServerErrorInfo} so
+ * permission-denied / not-found errors surface a real message + code instead of the generic
+ * `"Unknown error"` fallback the inline mapping used previously.
+ *
+ * @param entry - A failed-key entry from the underlying multi-read.
+ * @returns A `{ key, message, code? }` triple safe to return to API/MCP callers.
+ */ function modelAccessReadErrorFromUseMultipleModelsFailure(entry) {
+    var _info_serverErrorCode, _ref, _ref1;
+    var _info_httpsErrorDetailsServerError, _info_httpsError;
+    var info = firebaseServerErrorInfo(entry.error);
+    var serverMessage = (_info_httpsErrorDetailsServerError = info.httpsErrorDetailsServerError) === null || _info_httpsErrorDetailsServerError === void 0 ? void 0 : _info_httpsErrorDetailsServerError.message;
+    var httpsMessage = (_info_httpsError = info.httpsError) === null || _info_httpsError === void 0 ? void 0 : _info_httpsError.message;
+    var plainMessage = _instanceof$2(entry.error, Error) ? entry.error.message : undefined;
+    var code = (_info_serverErrorCode = info.serverErrorCode) !== null && _info_serverErrorCode !== void 0 ? _info_serverErrorCode : info.firebaseErrorCode;
+    return {
+        key: entry.key,
+        message: (_ref = (_ref1 = serverMessage !== null && serverMessage !== void 0 ? serverMessage : httpsMessage) !== null && _ref1 !== void 0 ? _ref1 : plainMessage) !== null && _ref !== void 0 ? _ref : 'permission denied or not found',
+        code: code
+    };
+}
 // MARK: Service
 /**
  * Service for direct document reads using the `useModel()` permission-checking pattern.
@@ -7332,9 +7459,67 @@ function _ts_generator$9(thisArg, body) {
     function ModelApiGetService(config, nestApplication) {
         _class_call_check$e(this, ModelApiGetService);
         _define_property$l(this, "_nestContext", void 0);
+        _define_property$l(this, "_identityByModelType", void 0);
         this._nestContext = config.makeNestContext(nestApplication);
     }
     _create_class$9(ModelApiGetService, [
+        {
+            /**
+     * Returns the registered {@link FirestoreModelIdentity} for the given `modelType` string, or
+     * `undefined` when no model of that type is registered.
+     *
+     * Identities are read from `firebaseModelsService` and cached on first successful call. The
+     * lookup uses the provided `auth` to build a real model context — `getFirestoreCollection(ctx)`
+     * is context-dependent (calls `ctx.collection(...)` or similar), so a synthetic empty context
+     * is not sufficient.
+     *
+     * @param modelType - The Firestore model type string (e.g., 'guestbook', 'profile').
+     * @param auth - The request's auth data; used to build a context for the (one-time) lookup.
+     * @returns The matching identity or `undefined`.
+     */ key: "getModelIdentity",
+            value: function getModelIdentity(modelType, auth) {
+                var _this__identityByModelType;
+                (_this__identityByModelType = this._identityByModelType) !== null && _this__identityByModelType !== void 0 ? _this__identityByModelType : this._identityByModelType = this._buildIdentityMap(auth);
+                return this._identityByModelType.get(modelType);
+            }
+        },
+        {
+            key: "_buildIdentityMap",
+            value: function _buildIdentityMap(auth) {
+                var map = new Map();
+                var authRef = this._makeAuthRef(auth);
+                var inContextService = this._nestContext.model(authRef);
+                var allTypes = inContextService.allTypes();
+                var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+                try {
+                    for(var _iterator = allTypes[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
+                        var type = _step.value;
+                        try {
+                            var modelService = inContextService(type);
+                            var identity = modelService.getFirestoreCollection().modelIdentity;
+                            map.set(type, identity);
+                        } catch (unused) {
+                        // identity unavailable for this type — skipped silently. A subsequent get attempt for a
+                        // missing type surfaces a user-visible "Unknown modelType" error at the tool layer.
+                        }
+                    }
+                } catch (err) {
+                    _didIteratorError = true;
+                    _iteratorError = err;
+                } finally{
+                    try {
+                        if (!_iteratorNormalCompletion && _iterator.return != null) {
+                            _iterator.return();
+                        }
+                    } finally{
+                        if (_didIteratorError) {
+                            throw _iteratorError;
+                        }
+                    }
+                }
+                return map;
+            }
+        },
         {
             key: "readDocument",
             value: /**
@@ -7441,15 +7626,7 @@ function _ts_generator$9(thisArg, body) {
                                                     ];
                                                 case 1:
                                                     results = _state.sent();
-                                                    errors = failure.errors.map(function(e) {
-                                                        var _ref;
-                                                        var _e_error, _e_error1;
-                                                        return {
-                                                            key: e.key,
-                                                            message: (_ref = (_e_error = e.error) === null || _e_error === void 0 ? void 0 : _e_error.message) !== null && _ref !== void 0 ? _ref : 'Unknown error',
-                                                            code: (_e_error1 = e.error) === null || _e_error1 === void 0 ? void 0 : _e_error1.code
-                                                        };
-                                                    });
+                                                    errors = failure.errors.map(modelAccessReadErrorFromUseMultipleModelsFailure);
                                                     return [
                                                         2,
                                                         {
@@ -8911,6 +9088,12 @@ function _is_native_reflect_construct$1() {
                 return this._appUrlDetails();
             }
         },
+        {
+            key: "appMcpUrl",
+            get: function get() {
+                return this.env.appMcpUrl;
+            }
+        },
         {
             key: "appWebhookUrl",
             get: function get() {
@@ -12743,6 +12926,7 @@ exports.AbstractFirebaseServerUserPasswordResetService = AbstractFirebaseServerU
 exports.AbstractNestContext = AbstractNestContext;
 exports.AbstractServerFirebaseNestContext = AbstractServerFirebaseNestContext;
 exports.DEFAULT_FIREBASE_PASSWORD_NUMBER_GENERATOR = DEFAULT_FIREBASE_PASSWORD_NUMBER_GENERATOR;
+exports.DEFAULT_RESET_CODE_EXPIRES_IN = DEFAULT_RESET_CODE_EXPIRES_IN;
 exports.DEFAULT_RESET_COM_THROTTLE_TIME = DEFAULT_RESET_COM_THROTTLE_TIME;
 exports.DEFAULT_SERVER_ASSETS_BASE_PATH = DEFAULT_SERVER_ASSETS_BASE_PATH;
 exports.DEFAULT_SETUP_COM_THROTTLE_TIME = DEFAULT_SETUP_COM_THROTTLE_TIME;
@@ -12868,6 +13052,7 @@ exports.inAuthContext = inAuthContext;
 exports.injectNestApplicationContextIntoRequest = injectNestApplicationContextIntoRequest;
 exports.injectNestIntoRequest = injectNestIntoRequest;
 exports.internalServerError = internalServerError;
+exports.invokeModelUnknownModelTypeError = invokeModelUnknownModelTypeError;
 exports.isActualSpecifier = isActualSpecifier;
 exports.isAdminInRequest = isAdminInRequest;
 exports.isAdminOrTargetUserInRequestData = isAdminOrTargetUserInRequestData;
@@ -12881,6 +13066,7 @@ exports.isOnCallSpecifierApiDetails = isOnCallSpecifierApiDetails;
 exports.makeBlockingFunctionWithHandler = makeBlockingFunctionWithHandler;
 exports.makeOnScheduleHandlerWithNestApplicationRequest = makeOnScheduleHandlerWithNestApplicationRequest;
 exports.makeScheduledFunctionDevelopmentFunction = makeScheduledFunctionDevelopmentFunction;
+exports.modelAccessReadErrorFromUseMultipleModelsFailure = modelAccessReadErrorFromUseMultipleModelsFailure;
 exports.modelApiModuleMetadata = modelApiModuleMetadata;
 exports.modelNotAvailableError = modelNotAvailableError;
 exports.nestAppHasDevelopmentSchedulerEnabled = nestAppHasDevelopmentSchedulerEnabled;
@@ -12898,6 +13084,7 @@ exports.onCallDeleteModel = onCallDeleteModel;
 exports.onCallDevelopmentFunction = onCallDevelopmentFunction;
 exports.onCallHandlerWithNestApplicationFactory = onCallHandlerWithNestApplicationFactory;
 exports.onCallHandlerWithNestContextFactory = onCallHandlerWithNestContextFactory;
+exports.onCallInvokeModel = onCallInvokeModel;
 exports.onCallModel = onCallModel;
 exports.onCallModelMissingCallTypeError = onCallModelMissingCallTypeError;
 exports.onCallModelUnknownCallTypeError = onCallModelUnknownCallTypeError;