@dereekb/firebase-server 13.1.0 → 13.2.1

package/index.cjs.js

@@ -7,6 +7,7 @@ var date = require('@dereekb/date');
 var makeError = require('make-error');
 var rxjs = require('rxjs');
 var firestore = require('@google-cloud/firestore');
+var crypto = require('crypto');
 var common = require('@nestjs/common');
 var nestjs = require('@dereekb/nestjs');
 var v2 = require('firebase-functions/v2');
@@ -271,7 +272,34 @@ class FirebaseServerAuthNewUserSendSetupDetailsSendOnceError extends makeError.B
     }
 }
 
-const DEFAULT_FIREBASE_PASSWORD_NUMBER_GENERATOR = util.randomNumberFactory({ min: 100000, max: 1000000, round: 'floor' }); // 6 digits
+/**
+ * Generates a random 6-digit number for use as a temporary password or reset token.
+ *
+ * Used internally by {@link AbstractFirebaseServerAuthUserContext.beginResetPassword} and
+ * {@link AbstractFirebaseServerNewUserService.generateRandomSetupPassword} for one-time codes.
+ *
+ * @example
+ * ```typescript
+ * const pin = DEFAULT_FIREBASE_PASSWORD_NUMBER_GENERATOR(); // e.g. 482910
+ * ```
+ */
+const DEFAULT_FIREBASE_PASSWORD_NUMBER_GENERATOR = util.randomNumberFactory({ min: 100000, max: 1000000, round: 'floor' });
+/**
+ * Base implementation of {@link FirebaseServerAuthUserContext} that manages a single user's
+ * auth state (record, claims, roles, password) through the Firebase Admin Auth API.
+ *
+ * Caches the user record on first load and resets the cache automatically when claims are modified
+ * via {@link setClaims}. Subclass this to bind it to a specific {@link FirebaseServerAuthService} type.
+ *
+ * @example
+ * ```typescript
+ * export class MyAuthUserContext extends AbstractFirebaseServerAuthUserContext<MyAuthService> {}
+ *
+ * const ctx = new MyAuthUserContext(authService, 'some-uid');
+ * const roles = await ctx.loadRoles();
+ * await ctx.addRoles(AUTH_ADMIN_ROLE);
+ * ```
+ */
 class AbstractFirebaseServerAuthUserContext {
     _service;
     _uid;
@@ -295,6 +323,9 @@ class AbstractFirebaseServerAuthUserContext {
     loadDetails() {
         return this.loadRecord().then((record) => this.service.authDetailsForRecord(record));
     }
+    /**
+     * Generates a random numeric string for use as a temporary reset password.
+     */
     _generateResetPasswordKey() {
         return String(DEFAULT_FIREBASE_PASSWORD_NUMBER_GENERATOR());
     }
@@ -319,9 +350,6 @@ class AbstractFirebaseServerAuthUserContext {
             return undefined;
         }
     }
-    /**
-     * Sets the user's password.
-     */
     async setPassword(password) {
         const record = await this.updateUser({ password });
         // clear password reset claims
@@ -354,15 +382,19 @@ class AbstractFirebaseServerAuthUserContext {
         return this.updateClaims(claims);
     }
     /**
-     * Sets the claims using the input roles and roles set.
+     * Replaces all role-based claims with those derived from the given roles.
      *
-     * All other claims are cleared.
+     * All existing claims are cleared first. Use `claimsToRetain` to preserve non-role claims
+     * (e.g., setup or application-specific claims) through the replacement.
      *
-     * Use the claimsToRetain input to retain other claims that are outside of the roles.
+     * @param roles - The complete set of roles to assign.
+     * @param claimsToRetain - Additional claims to merge in alongside the role-derived claims.
      *
-     * @param roles
-     * @param claimsToRetain
-     * @returns
+     * @example
+     * ```typescript
+     * // Set roles while preserving a custom claim
+     * await userCtx.setRoles([AUTH_ADMIN_ROLE], { customFlag: 1 });
+     * ```
      */
     async setRoles(roles, claimsToRetain) {
         const claims = {
@@ -371,8 +403,11 @@ class AbstractFirebaseServerAuthUserContext {
         };
         return this.setClaims(claims);
     }
+    /**
+     * Converts roles to their corresponding claim keys, filtering out null/undefined entries
+     * that represent unrelated claims in the service's {@link FirebaseServerAuthService.claimsForRoles} output.
+     */
     _claimsForRolesChange(roles) {
-        // filter null/undefined since the claims will contain null values for claims that are not related.
         return util.filterNullAndUndefinedValues(this.service.claimsForRoles(util.asSet(roles)));
     }
     loadClaims() {
@@ -402,6 +437,15 @@ class AbstractFirebaseServerAuthUserContext {
         });
     }
 }
+/**
+ * Base implementation of {@link FirebaseServerAuthContext} with cached getters for roles, admin status,
+ * and ToS status to avoid redundant computation within a single request.
+ *
+ * @example
+ * ```typescript
+ * export class MyAuthContext extends AbstractFirebaseServerAuthContext<MyAuthContext, MyUserContext, MyAuthService> {}
+ * ```
+ */
 class AbstractFirebaseServerAuthContext {
     _service;
     _context;
@@ -443,15 +487,52 @@ class AbstractFirebaseServerAuthContext {
     }
 }
 /**
- * 1 hour
+ * Default throttle duration (1 hour) between setup content sends to prevent spam.
+ *
+ * Used by {@link AbstractFirebaseServerNewUserService.sendSetupContent} to rate-limit delivery.
  */
 const DEFAULT_SETUP_COM_THROTTLE_TIME = date.hoursToMs(1);
+/**
+ * Resolves a {@link UserContextOrUid} to a concrete user context instance.
+ *
+ * If a string UID is provided, creates a new user context via the auth service.
+ * If an existing context is provided, returns it as-is.
+ *
+ * @param authService - The auth service to create a context from if needed.
+ * @param userContextOrUid - A user context or UID string.
+ *
+ * @example
+ * ```typescript
+ * const ctx = userContextFromUid(authService, 'some-uid');
+ * const sameCtx = userContextFromUid(authService, ctx); // returns ctx unchanged
+ * ```
+ */
 function userContextFromUid(authService, userContextOrUid) {
     const userContext = typeof userContextOrUid === 'string' ? authService.userContext(userContextOrUid) : userContextOrUid;
     return userContext;
 }
+/**
+ * Base implementation of {@link FirebaseServerNewUserService} that handles user creation,
+ * setup claims management, throttled setup content delivery, and setup completion.
+ *
+ * Subclasses must implement {@link sendSetupContentToUser} to define how setup content
+ * (e.g., invitation email, SMS) is delivered to the user.
+ *
+ * @example
+ * ```typescript
+ * export class MyNewUserService extends AbstractFirebaseServerNewUserService<MyUserContext> {
+ *   protected async sendSetupContentToUser(details: FirebaseServerAuthNewUserSetupDetails<MyUserContext>): Promise<void> {
+ *     await this.emailService.sendInvite(details.userContext.uid, details.claims.setupPassword);
+ *   }
+ * }
+ * ```
+ */
 class AbstractFirebaseServerNewUserService {
     _authService;
+    /**
+     * Minimum time between setup content sends. Defaults to {@link DEFAULT_SETUP_COM_THROTTLE_TIME} (1 hour).
+     * Override in subclasses to customize the throttle window.
+     */
     setupThrottleTime = DEFAULT_SETUP_COM_THROTTLE_TIME;
     constructor(authService) {
         this._authService = authService;
@@ -563,19 +644,15 @@ class AbstractFirebaseServerNewUserService {
         }
         return details;
     }
+    /**
+     * Records the current timestamp as the last setup content communication date in the user's claims.
+     */
     async updateSetupContentSentTime(details) {
         const setupCommunicationAt = date.toISODateString(new Date());
         await details.userContext.updateClaims({
             setupCommunicationAt
         });
     }
-    /**
-     * Update a user's claims to clear any setup-related content.
-     *
-     * Returns true if a user was updated.
-     *
-     * @param uid
-     */
     async markUserSetupAsComplete(uid) {
         const userContext = this.authService.userContext(uid);
         const userExists = await userContext.exists();
@@ -584,6 +661,13 @@ class AbstractFirebaseServerNewUserService {
         }
         return userExists;
     }
+    /**
+     * Creates a new Firebase Auth user from the initialization input.
+     *
+     * Generates a random setup password if none is provided. Override to customize user creation behavior.
+     *
+     * @throws Throws if the Firebase Admin SDK rejects the user creation.
+     */
     async createNewUser(input) {
         const { uid, displayName, email, phone: phoneNumber, setupPassword: inputPassword } = input;
         const password = inputPassword ?? this.generateRandomSetupPassword();
@@ -602,6 +686,9 @@ class AbstractFirebaseServerNewUserService {
     generateRandomSetupPassword() {
         return `${DEFAULT_FIREBASE_PASSWORD_NUMBER_GENERATOR()}`;
     }
+    /**
+     * Clears setup-related claims (setup password and last communication date) from the user.
+     */
     async updateClaimsToClearUser(userContext) {
         await userContext.updateClaims({
             [firebase.FIREBASE_SERVER_AUTH_CLAIMS_SETUP_PASSWORD_KEY]: null,
@@ -609,18 +696,65 @@ class AbstractFirebaseServerNewUserService {
         });
     }
 }
+/**
+ * No-op implementation of {@link AbstractFirebaseServerNewUserService} that skips sending setup content.
+ *
+ * Used as the default {@link FirebaseServerNewUserService} when no custom delivery mechanism is configured.
+ */
 class NoSetupContentFirebaseServerNewUserService extends AbstractFirebaseServerNewUserService {
-    async sendSetupContentToUser(user) {
+    async sendSetupContentToUser(_details) {
         // send nothing.
     }
 }
 /**
- * FirebaseServer auth service that provides accessors to auth-related components.
+ * Abstract contract for a Firebase Server authentication service.
+ *
+ * Provides the core API for creating auth contexts from callable requests, managing user contexts,
+ * checking admin/ToS status, converting between roles and claims, and creating new users.
+ *
+ * Implement this by extending {@link AbstractFirebaseServerAuthService}, which provides default
+ * implementations for most methods and only requires `readRoles`, `claimsForRoles`,
+ * `userContext`, and `_context` to be defined.
+ *
+ * @example
+ * ```typescript
+ * class MyAuthService extends AbstractFirebaseServerAuthService<MyUserContext, MyAuthContext> {
+ *   readRoles(claims: AuthClaims): AuthRoleSet { ... }
+ *   claimsForRoles(roles: AuthRoleSet): AuthClaimsUpdate { ... }
+ *   userContext(uid: string): MyUserContext { ... }
+ *   protected _context(ctx: CallableContextWithAuthData): MyAuthContext { ... }
+ * }
+ * ```
  */
 class FirebaseServerAuthService {
 }
 /**
- * Abstract FirebaseServerAuthService implementation.
+ * Base implementation of {@link FirebaseServerAuthService} providing standard admin/ToS checks,
+ * auth context creation with assertion, and a default no-op new user service.
+ *
+ * Subclasses must implement:
+ * - {@link _context} - to create the concrete auth context type.
+ * - {@link userContext} - to create the concrete user context type.
+ * - {@link readRoles} - to define the claims-to-roles mapping.
+ * - {@link claimsForRoles} - to define the roles-to-claims mapping.
+ *
+ * @example
+ * ```typescript
+ * export class MyAuthService extends AbstractFirebaseServerAuthService<MyUserContext, MyAuthContext> {
+ *   protected _context(context: CallableContextWithAuthData): MyAuthContext {
+ *     return new MyAuthContext(this, context);
+ *   }
+ *   userContext(uid: string): MyUserContext {
+ *     return new MyUserContext(this, uid);
+ *   }
+ *   readRoles(claims: AuthClaims): AuthRoleSet {
+ *     return MY_CLAIMS_SERVICE.toRoles(claims);
+ *   }
+ *   claimsForRoles(roles: AuthRoleSet): AuthClaimsUpdate {
+ *     return MY_CLAIMS_SERVICE.toClaims(roles);
+ *   }
+ * }
+ * ```
  */
 class AbstractFirebaseServerAuthService {
     _auth;
@@ -1048,6 +1182,140 @@ function googleCloudFirestoreDrivers() {
  */
 const googleCloudFirestoreContextFactory = firebase.firestoreContextFactory(googleCloudFirestoreDrivers());
 
+// MARK: Encrypted Field
+/**
+ * AES-256-GCM encryption constants.
+ */
+const ENCRYPTED_FIELD_ALGORITHM = 'aes-256-gcm';
+const ENCRYPTED_FIELD_IV_LENGTH = 12;
+const ENCRYPTED_FIELD_AUTH_TAG_LENGTH = 16;
+const ENCRYPTED_FIELD_KEY_LENGTH = 32;
+/**
+ * Resolves the encryption key Buffer from a secret source.
+ *
+ * @param source - The secret source configuration.
+ * @returns A 32-byte Buffer for AES-256 encryption.
+ * @throws Error if the resolved key is not 64 hex characters.
+ */
+function resolveEncryptionKey(source) {
+    let hex;
+    if (typeof source === 'string') {
+        hex = source;
+    }
+    else if (typeof source === 'function') {
+        hex = source();
+    }
+    else {
+        const envValue = process.env[source.env];
+        if (!envValue) {
+            throw new Error(`firestoreEncryptedField: environment variable "${source.env}" is not set.`);
+        }
+        hex = envValue;
+    }
+    if (hex.length !== ENCRYPTED_FIELD_KEY_LENGTH * 2) {
+        throw new Error(`firestoreEncryptedField: expected a ${ENCRYPTED_FIELD_KEY_LENGTH * 2}-character hex key, got ${hex.length} characters.`);
+    }
+    return Buffer.from(hex, 'hex');
+}
+/**
+ * Encrypts a JSON-serializable value to a base64-encoded string.
+ *
+ * Format: base64(IV (12 bytes) + ciphertext + authTag (16 bytes))
+ *
+ * @param value - The value to encrypt.
+ * @param key - The 32-byte encryption key.
+ * @returns The encrypted value as a base64 string.
+ */
+function encryptValue(value, key) {
+    const iv = crypto.randomBytes(ENCRYPTED_FIELD_IV_LENGTH);
+    const cipher = crypto.createCipheriv(ENCRYPTED_FIELD_ALGORITHM, key, iv);
+    const plaintext = JSON.stringify(value);
+    const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    const combined = Buffer.concat([iv, encrypted, authTag]);
+    return combined.toString('base64');
+}
+/**
+ * Decrypts a base64-encoded string back to the original value.
+ *
+ * @param encoded - The base64-encoded encrypted string (IV + ciphertext + authTag).
+ * @param key - The 32-byte encryption key.
+ * @returns The decrypted value.
+ */
+function decryptValue(encoded, key) {
+    const combined = Buffer.from(encoded, 'base64');
+    const iv = combined.subarray(0, ENCRYPTED_FIELD_IV_LENGTH);
+    const authTag = combined.subarray(combined.length - ENCRYPTED_FIELD_AUTH_TAG_LENGTH);
+    const ciphertext = combined.subarray(ENCRYPTED_FIELD_IV_LENGTH, combined.length - ENCRYPTED_FIELD_AUTH_TAG_LENGTH);
+    const decipher = crypto.createDecipheriv(ENCRYPTED_FIELD_ALGORITHM, key, iv);
+    decipher.setAuthTag(authTag);
+    const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    return JSON.parse(decrypted.toString('utf8'));
+}
+/**
+ * Creates a Firestore field mapping that encrypts/decrypts a JSON-serializable value
+ * using AES-256-GCM. The value is stored in Firestore as a base64-encoded string.
+ *
+ * The encryption key is resolved from the configured secret source on each read/write,
+ * allowing for key rotation via environment variable changes.
+ *
+ * @example
+ * ```typescript
+ * const jwksField = firestoreEncryptedField<JWKSet>({
+ *   secret: { env: 'FIRESTORE_ENCRYPTION_KEY' },
+ *   default: () => ({ keys: [] })
+ * });
+ * ```
+ *
+ * @template T - The JSON-serializable value type.
+ * @param config - Encryption field configuration.
+ * @returns A field mapping configuration for encrypted values.
+ */
+function firestoreEncryptedField(config) {
+    const { secret, default: defaultValue } = config;
+    return firebase.firestoreField({
+        default: defaultValue,
+        fromData: (data) => {
+            const key = resolveEncryptionKey(secret);
+            return decryptValue(data, key);
+        },
+        toData: (value) => {
+            const key = resolveEncryptionKey(secret);
+            return encryptValue(value, key);
+        }
+    });
+}
+/**
+ * Creates a Firestore field mapping for an optional encrypted field.
+ *
+ * When the value is null/undefined, it is stored/read as null. When present, it is
+ * encrypted/decrypted using AES-256-GCM.
+ *
+ * @example
+ * ```typescript
+ * const optionalSecretField = optionalFirestoreEncryptedField<OAuthClientSecret>({
+ *   secret: { env: 'FIRESTORE_ENCRYPTION_KEY' }
+ * });
+ * ```
+ *
+ * @template T - The JSON-serializable value type.
+ * @param config - Encryption field configuration.
+ * @returns A field mapping configuration for optional encrypted values.
+ */
+function optionalFirestoreEncryptedField(config) {
+    const { secret } = config;
+    return firebase.optionalFirestoreField({
+        transformFromData: (data) => {
+            const key = resolveEncryptionKey(secret);
+            return decryptValue(data, key);
+        },
+        transformToData: (value) => {
+            const key = resolveEncryptionKey(secret);
+            return encryptValue(value, key);
+        }
+    });
+}
+
 function assertContextHasAuth(context) {
     if (!isContextWithAuthData(context)) {
         throw unauthenticatedContextHasNoUidError();
@@ -1892,6 +2160,163 @@ exports.ConfigureFirebaseWebhookMiddlewareModule = __decorate([
     common.Module({})
 ], exports.ConfigureFirebaseWebhookMiddlewareModule);
 
+// MARK: Type Guards
+/**
+ * Whether the details are specifier-level (has specifiers map).
+ */
+function isOnCallSpecifierApiDetails(details) {
+    return details != null && 'specifiers' in details;
+}
+/**
+ * Whether the details are CRUD-model-level (has modelTypes map).
+ */
+function isOnCallCrudModelApiDetails(details) {
+    return details != null && 'modelTypes' in details;
+}
+/**
+ * Whether the details are handler-level (leaf node — no specifiers or modelTypes).
+ */
+function isOnCallHandlerApiDetails(details) {
+    return details != null && !('specifiers' in details) && !('modelTypes' in details);
+}
+/**
+ * Attaches API details metadata to a handler function.
+ *
+ * The handler function is provided in the config object alongside its metadata.
+ * The function is returned unchanged but with the _apiDetails property set.
+ * Compatible with all handler types (create, read, update, delete, specifier).
+ *
+ * When `optionalAuth: true` is set, also marks the function as not requiring auth
+ * (same effect as optionalAuthContext). This avoids the composition issue where
+ * optionalAuthContext(withApiDetails(...)) would lose the _apiDetails.
+ *
+ * @example
+ * ```typescript
+ * // Handler with api details (auth required by default)
+ * export const createGuestbook: DemoCreateModelFunction<CreateGuestbookParams> = withApiDetails({
+ *   inputType: createGuestbookParamsType,
+ *   fn: async (request) => {
+ *     const { nest, auth, data } = request;
+ *     const result = await nest.guestbookActions.createGuestbook(data);
+ *     return onCallCreateModelResultWithDocs(await result());
+ *   }
+ * });
+ *
+ * // Handler with optional auth
+ * export const profileCreate: DemoCreateModelFunction<{}> = withApiDetails({
+ *   optionalAuth: true,
+ *   fn: async (request) => { ... }
+ * });
+ * ```
+ */
+function withApiDetails(config) {
+    const { optionalAuth, fn, ...apiDetails } = config;
+    fn._apiDetails = apiDetails;
+    if (optionalAuth) {
+        fn._requireAuth = false;
+    }
+    return fn;
+}
+// MARK: Aggregation Utilities
+/**
+ * Reads _apiDetails from a function if present.
+ */
+function readApiDetails(fn) {
+    return fn?._apiDetails;
+}
+/**
+ * Aggregates _apiDetails from a specifier handler config object.
+ *
+ * Returns OnCallSpecifierApiDetails if any handlers have _apiDetails, otherwise undefined.
+ */
+function aggregateSpecifierApiDetails(config) {
+    const specifiers = {};
+    let hasAny = false;
+    for (const [key, handler] of Object.entries(config)) {
+        const details = readApiDetails(handler);
+        if (details != null) {
+            // At the specifier level, details should be handler-level (OnCallModelFunctionApiDetails)
+            specifiers[key] = details;
+            hasAny = true;
+        }
+    }
+    return hasAny ? { specifiers } : undefined;
+}
+/**
+ * Aggregates _apiDetails from a model type map (used by onCallCreateModel, etc.).
+ *
+ * Returns OnCallCrudModelApiDetails if any handlers have _apiDetails, otherwise undefined.
+ */
+function aggregateCrudModelApiDetails(map) {
+    const modelTypes = {};
+    let hasAny = false;
+    for (const [key, handler] of Object.entries(map)) {
+        const details = readApiDetails(handler);
+        if (details != null) {
+            modelTypes[key] = details;
+            hasAny = true;
+        }
+    }
+    return hasAny ? { modelTypes } : undefined;
+}
+/**
+ * Aggregates _apiDetails from the top-level call model map.
+ *
+ * Returns OnCallModelApiDetails if any CRUD handlers have _apiDetails, otherwise undefined.
+ */
+function aggregateModelApiDetails(map) {
+    const result = {};
+    let hasAny = false;
+    for (const [call, handler] of Object.entries(map)) {
+        const details = readApiDetails(handler);
+        if (details != null) {
+            result[call] = details;
+            hasAny = true;
+        }
+    }
+    return hasAny ? result : undefined;
+}
+/**
+ * Extracts and pivots API details from a call model function into a model-first view.
+ *
+ * The internal aggregation tree is organized as CRUD → modelType. This function
+ * pivots it to modelType → CRUD, which is the natural shape for MCP tool generation
+ * and schema introspection.
+ *
+ * @param callModelFn The function returned by onCallModel(), or any object with _apiDetails.
+ * @returns Model-first API details, or undefined if no _apiDetails are present.
+ *
+ * @example
+ * ```typescript
+ * const details = getModelApiDetails(demoCallModel);
+ * // details.models['guestbook'].calls.create => { inputType: createGuestbookParamsType }
+ * // details.models['profile'].calls.update => { specifiers: { _: {...}, username: {...} } }
+ * ```
+ */
+function getModelApiDetails(callModelFn) {
+    const topDetails = readApiDetails(callModelFn);
+    if (topDetails == null) {
+        return undefined;
+    }
+    const models = {};
+    // Pivot: iterate CRUD types, then model types within each
+    for (const [callType, crudDetails] of Object.entries(topDetails)) {
+        if (crudDetails == null) {
+            continue;
+        }
+        for (const [modelType, modelDetails] of Object.entries(crudDetails.modelTypes)) {
+            if (modelDetails == null) {
+                continue;
+            }
+            if (!models[modelType]) {
+                models[modelType] = { calls: {} };
+            }
+            models[modelType].calls[callType] = modelDetails;
+        }
+    }
+    return Object.keys(models).length > 0 ? { models } : undefined;
+}
+
 const nestFirebaseDoesNotExistError = (firebaseContextGrantedModelRoles) => {
     return modelNotAvailableError({
         data: {
@@ -1924,6 +2349,11 @@ function onCallSpecifierHandler(config) {
         }
     };
     fn._requireAuth = false;
+    // Aggregate _apiDetails from handler functions in the config
+    const specifierApiDetails = aggregateSpecifierApiDetails(config);
+    if (specifierApiDetails != null) {
+        fn._apiDetails = specifierApiDetails;
+    }
     return fn;
 }
 function unknownModelCrudFunctionSpecifierError(specifier) {
@@ -1945,7 +2375,7 @@ function unknownModelCrudFunctionSpecifierError(specifier) {
  */
 function onCallModel(map, config = {}) {
     const { preAssert = () => undefined } = config;
-    return (request) => {
+    const fn = (request) => {
         const call = request.data?.call;
         if (call) {
             const callFn = map[call];
@@ -1962,6 +2392,12 @@ function onCallModel(map, config = {}) {
             throw onCallModelMissingCallTypeError();
         }
     };
+    // Aggregate _apiDetails from CRUD handlers in the map
+    const modelApiDetails = aggregateModelApiDetails(map);
+    if (modelApiDetails != null) {
+        fn._apiDetails = modelApiDetails;
+    }
+    return fn;
 }
 function onCallModelMissingCallTypeError() {
     return badRequestError(util.serverError({
@@ -1982,7 +2418,7 @@ function onCallModelUnknownCallTypeError(call) {
 }
 function _onCallWithCallTypeFunction(map, config) {
     const { callType, crudType, preAssert = () => undefined, throwOnUnknownModelType } = config;
-    return (request) => {
+    const fn = (request) => {
         const modelType = request.data?.modelType;
         const crudFn = map[modelType];
         if (crudFn) {
@@ -1999,6 +2435,12 @@ function _onCallWithCallTypeFunction(map, config) {
             throw throwOnUnknownModelType(modelType);
         }
     };
+    // Aggregate _apiDetails from model type handlers in the map
+    const crudModelApiDetails = aggregateCrudModelApiDetails(map);
+    if (crudModelApiDetails != null) {
+        fn._apiDetails = crudModelApiDetails;
+    }
+    return fn;
 }
 
 function onCallCreateModel(map, config = {}) {
@@ -2727,6 +3169,9 @@ exports.UNAVAILABLE_OR_DEACTIVATED_FUNCTION_ERROR_CODE = UNAVAILABLE_OR_DEACTIVA
 exports.UNKNOWN_SCHEDULED_FUNCTION_DEVELOPMENT_FUNCTION_NAME_CODE = UNKNOWN_SCHEDULED_FUNCTION_DEVELOPMENT_FUNCTION_NAME_CODE;
 exports.UNKNOWN_SCHEDULED_FUNCTION_DEVELOPMENT_FUNCTION_TYPE_CODE = UNKNOWN_SCHEDULED_FUNCTION_DEVELOPMENT_FUNCTION_TYPE_CODE;
 exports._onCallWithCallTypeFunction = _onCallWithCallTypeFunction;
+exports.aggregateCrudModelApiDetails = aggregateCrudModelApiDetails;
+exports.aggregateModelApiDetails = aggregateModelApiDetails;
+exports.aggregateSpecifierApiDetails = aggregateSpecifierApiDetails;
 exports.alreadyExistsError = alreadyExistsError;
 exports.appFirestoreModuleMetadata = appFirestoreModuleMetadata;
 exports.assertContextHasAuth = assertContextHasAuth;
@@ -2766,9 +3211,11 @@ exports.firebaseServerStorageModuleMetadata = firebaseServerStorageModuleMetadat
 exports.firebaseServerValidationError = firebaseServerValidationError;
 exports.firebaseServerValidationServerError = firebaseServerValidationServerError;
 exports.firestoreClientQueryConstraintFunctionsDriver = firestoreClientQueryConstraintFunctionsDriver;
+exports.firestoreEncryptedField = firestoreEncryptedField;
 exports.firestoreServerIncrementUpdateToUpdateData = firestoreServerIncrementUpdateToUpdateData;
 exports.forbiddenError = forbiddenError;
 exports.getAuthUserOrUndefined = getAuthUserOrUndefined;
+exports.getModelApiDetails = getModelApiDetails;
 exports.googleCloudFileMetadataToStorageMetadata = googleCloudFileMetadataToStorageMetadata;
 exports.googleCloudFirebaseStorageContextFactory = googleCloudFirebaseStorageContextFactory;
 exports.googleCloudFirebaseStorageDrivers = googleCloudFirebaseStorageDrivers;
@@ -2797,6 +3244,9 @@ exports.isAdminOrTargetUserInRequestData = isAdminOrTargetUserInRequestData;
 exports.isContextWithAuthData = isContextWithAuthData;
 exports.isFirebaseError = isFirebaseError;
 exports.isFirebaseHttpsError = isFirebaseHttpsError;
+exports.isOnCallCrudModelApiDetails = isOnCallCrudModelApiDetails;
+exports.isOnCallHandlerApiDetails = isOnCallHandlerApiDetails;
+exports.isOnCallSpecifierApiDetails = isOnCallSpecifierApiDetails;
 exports.makeBlockingFunctionWithHandler = makeBlockingFunctionWithHandler;
 exports.makeOnScheduleHandlerWithNestApplicationRequest = makeOnScheduleHandlerWithNestApplicationRequest;
 exports.makeScheduledFunctionDevelopmentFunction = makeScheduledFunctionDevelopmentFunction;
@@ -2822,12 +3272,14 @@ exports.onCallUpdateModel = onCallUpdateModel;
 exports.onScheduleHandlerWithNestApplicationFactory = onScheduleHandlerWithNestApplicationFactory;
 exports.onScheduleHandlerWithNestContextFactory = onScheduleHandlerWithNestContextFactory;
 exports.optionalAuthContext = optionalAuthContext;
+exports.optionalFirestoreEncryptedField = optionalFirestoreEncryptedField;
 exports.permissionDeniedError = permissionDeniedError;
 exports.phoneNumberAlreadyExistsError = phoneNumberAlreadyExistsError;
 exports.preconditionConflictError = preconditionConflictError;
 exports.provideAppFirestoreCollections = provideAppFirestoreCollections;
 exports.provideFirebaseServerAuthService = provideFirebaseServerAuthService;
 exports.provideFirebaseServerStorageService = provideFirebaseServerStorageService;
+exports.readApiDetails = readApiDetails;
 exports.readModelUnknownModelTypeError = readModelUnknownModelTypeError;
 exports.setNestContextOnRequest = setNestContextOnRequest;
 exports.setNestContextOnScheduleRequest = setNestContextOnScheduleRequest;
@@ -2843,4 +3295,5 @@ exports.unknownScheduledFunctionDevelopmentFunctionType = unknownScheduledFuncti
 exports.updateModelUnknownModelTypeError = updateModelUnknownModelTypeError;
 exports.userContextFromUid = userContextFromUid;
 exports.verifyAppCheckInRequest = verifyAppCheckInRequest;
+exports.withApiDetails = withApiDetails;
 //# sourceMappingURL=index.cjs.js.map