@dereekb/firebase-server 13.1.0 → 13.2.1

package/index.esm.js

@@ -1,10 +1,11 @@
-import { DBX_FIREBASE_SERVER_NO_AUTH_ERROR_CODE, FIREBASE_AUTH_USER_NOT_FOUND_ERROR, FIREBASE_SERVER_AUTH_CLAIMS_RESET_LAST_COM_DATE_KEY, FIREBASE_SERVER_AUTH_CLAIMS_RESET_PASSWORD_KEY, FIREBASE_SERVER_AUTH_CLAIMS_SETUP_PASSWORD_KEY, FIREBASE_SERVER_AUTH_CLAIMS_SETUP_LAST_COM_DATE_KEY, FirestoreDocumentContextType, streamFromOnSnapshot, makeFirestoreQueryConstraintFunctionsDriver, FIRESTORE_END_BEFORE_QUERY_CONSTRAINT_TYPE, FIRESTORE_END_AT_VALUE_QUERY_CONSTRAINT_TYPE, FIRESTORE_END_AT_QUERY_CONSTRAINT_TYPE, FIRESTORE_START_AFTER_QUERY_CONSTRAINT_TYPE, FIRESTORE_START_AT_VALUE_QUERY_CONSTRAINT_TYPE, FIRESTORE_START_AT_QUERY_CONSTRAINT_TYPE, FIRESTORE_OFFSET_QUERY_CONSTRAINT_TYPE, FIRESTORE_WHERE_DOCUMENT_ID_QUERY_CONSTRAINT_TYPE, FIRESTORE_WHERE_QUERY_CONSTRAINT_TYPE, FIRESTORE_ORDER_BY_DOCUMENT_ID_QUERY_CONSTRAINT_TYPE, FIRESTORE_ORDER_BY_QUERY_CONSTRAINT_TYPE, FIRESTORE_LIMIT_TO_LAST_QUERY_CONSTRAINT_TYPE, FIRESTORE_LIMIT_QUERY_CONSTRAINT_TYPE, firestoreContextFactory, setIdAndKeyFromKeyIdRefOnDocumentData, SCHEDULED_FUNCTION_DEV_FUNCTION_SPECIFIER, MODEL_FUNCTION_FIREBASE_CRUD_FUNCTION_SPECIFIER_DEFAULT, storageListFilesResultFactory, assertStorageUploadOptionsStringFormat, firebaseStorageContextFactory, inContextFirebaseModelsServiceFactory, useFirebaseModelsService } from '@dereekb/firebase';
+import { DBX_FIREBASE_SERVER_NO_AUTH_ERROR_CODE, FIREBASE_AUTH_USER_NOT_FOUND_ERROR, FIREBASE_SERVER_AUTH_CLAIMS_RESET_LAST_COM_DATE_KEY, FIREBASE_SERVER_AUTH_CLAIMS_RESET_PASSWORD_KEY, FIREBASE_SERVER_AUTH_CLAIMS_SETUP_PASSWORD_KEY, FIREBASE_SERVER_AUTH_CLAIMS_SETUP_LAST_COM_DATE_KEY, FirestoreDocumentContextType, streamFromOnSnapshot, makeFirestoreQueryConstraintFunctionsDriver, FIRESTORE_END_BEFORE_QUERY_CONSTRAINT_TYPE, FIRESTORE_END_AT_VALUE_QUERY_CONSTRAINT_TYPE, FIRESTORE_END_AT_QUERY_CONSTRAINT_TYPE, FIRESTORE_START_AFTER_QUERY_CONSTRAINT_TYPE, FIRESTORE_START_AT_VALUE_QUERY_CONSTRAINT_TYPE, FIRESTORE_START_AT_QUERY_CONSTRAINT_TYPE, FIRESTORE_OFFSET_QUERY_CONSTRAINT_TYPE, FIRESTORE_WHERE_DOCUMENT_ID_QUERY_CONSTRAINT_TYPE, FIRESTORE_WHERE_QUERY_CONSTRAINT_TYPE, FIRESTORE_ORDER_BY_DOCUMENT_ID_QUERY_CONSTRAINT_TYPE, FIRESTORE_ORDER_BY_QUERY_CONSTRAINT_TYPE, FIRESTORE_LIMIT_TO_LAST_QUERY_CONSTRAINT_TYPE, FIRESTORE_LIMIT_QUERY_CONSTRAINT_TYPE, firestoreContextFactory, firestoreField, optionalFirestoreField, setIdAndKeyFromKeyIdRefOnDocumentData, SCHEDULED_FUNCTION_DEV_FUNCTION_SPECIFIER, MODEL_FUNCTION_FIREBASE_CRUD_FUNCTION_SPECIFIER_DEFAULT, storageListFilesResultFactory, assertStorageUploadOptionsStringFormat, firebaseStorageContextFactory, inContextFirebaseModelsServiceFactory, useFirebaseModelsService } from '@dereekb/firebase';
 import { partialServerError, isServerError, randomNumberFactory, cachedGetter, AUTH_ADMIN_ROLE, AUTH_TOS_SIGNED_ROLE, forEachKeyValue, KeyValueTypleValueFilter, filterNullAndUndefinedValues, asSet, filterUndefinedValues, isThrottled, mapObjectMap, batch, asArray, containsAllValues, serverError, mergeObjects, cronExpressionRepeatingEveryNMinutes, mapIdentityFunction, objectToMap, slashPathName, SLASH_PATH_SEPARATOR, toRelativeSlashPathStartType, fixMultiSlashesInSlashPath, objectHasNoKeys, makeGetter, asGetter, pushItemOrArrayItemsIntoArray, build } from '@dereekb/util';
 import { HttpsError } from 'firebase-functions/https';
 import { hoursToMs, toISODateString } from '@dereekb/date';
 import { BaseError } from 'make-error';
 import { from } from 'rxjs';
 import { FieldValue, FieldPath } from '@google-cloud/firestore';
+import { randomBytes, createCipheriv, createDecipheriv } from 'crypto';
 import { Module, Injectable, Optional, Inject, Logger, ForbiddenException, createParamDecorator } from '@nestjs/common';
 import { mergeModuleMetadata, ServerEnvironmentService, DEFAULT_BASE_WEBHOOK_PATH, DEFAULT_WEBHOOK_MIDDLEWARE_ROUTE_INFO, isTestNodeEnv, injectionTokensFromProviders, serverEnvTokenProvider } from '@dereekb/nestjs';
 import { https, scheduler } from 'firebase-functions/v2';
@@ -269,7 +270,34 @@ class FirebaseServerAuthNewUserSendSetupDetailsSendOnceError extends BaseError {
     }
 }
 
-const DEFAULT_FIREBASE_PASSWORD_NUMBER_GENERATOR = 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 = 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;
@@ -293,6 +321,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());
     }
@@ -317,9 +348,6 @@ class AbstractFirebaseServerAuthUserContext {
             return undefined;
         }
     }
-    /**
-     * Sets the user's password.
-     */
     async setPassword(password) {
         const record = await this.updateUser({ password });
         // clear password reset claims
@@ -352,15 +380,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 = {
@@ -369,8 +401,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 filterNullAndUndefinedValues(this.service.claimsForRoles(asSet(roles)));
     }
     loadClaims() {
@@ -400,6 +435,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;
@@ -441,15 +485,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 = 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;
@@ -561,19 +642,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 = 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();
@@ -582,6 +659,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();
@@ -600,6 +684,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_SERVER_AUTH_CLAIMS_SETUP_PASSWORD_KEY]: null,
@@ -607,18 +694,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;
@@ -1046,6 +1180,140 @@ function googleCloudFirestoreDrivers() {
  */
 const googleCloudFirestoreContextFactory = 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 = randomBytes(ENCRYPTED_FIELD_IV_LENGTH);
+    const cipher = 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 = 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 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 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();
@@ -1890,6 +2158,163 @@ ConfigureFirebaseWebhookMiddlewareModule = __decorate([
     Module({})
 ], 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: {
@@ -1922,6 +2347,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) {
@@ -1943,7 +2373,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];
@@ -1960,6 +2390,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(serverError({
@@ -1980,7 +2416,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) {
@@ -1997,6 +2433,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 = {}) {
@@ -2682,5 +3124,5 @@ class AbstractFirebaseNestContext extends AbstractNestContext {
     }
 }
 
-export { ALREADY_EXISTS_ERROR_CODE, AbstractFirebaseNestContext, AbstractFirebaseServerActionsContext, AbstractFirebaseServerAuthContext, AbstractFirebaseServerAuthService, AbstractFirebaseServerAuthUserContext, AbstractFirebaseServerNewUserService, AbstractNestContext, BAD_REQUEST_ERROR_CODE, CONFLICT_ERROR_CODE, ConfigureFirebaseAppCheckMiddlewareModule, ConfigureFirebaseWebhookMiddlewareModule, DEFAULT_FIREBASE_PASSWORD_NUMBER_GENERATOR, DEFAULT_SETUP_COM_THROTTLE_TIME, DefaultFirebaseServerEnvService, FIREBASE_APP_TOKEN, FIREBASE_AUTH_TOKEN, FIREBASE_FIRESTORE_CONTEXT_TOKEN, FIREBASE_FIRESTORE_TOKEN, FIREBASE_SERVER_VALIDATION_ERROR_CODE, FIREBASE_STORAGE_CONTEXT_FACTORY_CONFIG_TOKEN, FIREBASE_STORAGE_CONTEXT_TOKEN, FIREBASE_STORAGE_TOKEN, FIRESTORE_CLIENT_QUERY_CONSTRAINT_HANDLER_MAPPING, FORBIDDEN_ERROR_CODE, FirebaseAppCheckMiddleware, FirebaseNestServerRootModule, FirebaseRawBodyMiddleware, FirebaseServerAuthModule, FirebaseServerAuthNewUserSendSetupDetailsNoSetupConfigError, FirebaseServerAuthNewUserSendSetupDetailsSendOnceError, FirebaseServerAuthNewUserSendSetupDetailsThrottleError, FirebaseServerAuthService, FirebaseServerEnvService, FirebaseServerFirestoreContextModule, FirebaseServerFirestoreModule, FirebaseServerStorageContextModule, FirebaseServerStorageModule, FirebaseServerStorageService, INTERNAL_SERVER_ERROR_CODE, MODEL_NOT_AVAILABLE_ERROR_CODE, NOT_FOUND_ERROR_CODE, NO_RUN_NAME_SPECIFIED_FOR_SCHEDULED_FUNCTION_DEVELOPMENT_FUNCTION_CODE, NoSetupContentFirebaseServerNewUserService, PERMISSION_DENIED_ERROR_CODE, PHONE_NUMBER_ALREADY_EXISTS_ERROR_CODE, SkipAppCheck, UNAUTHENTICATED_ERROR_CODE, UNAVAILABLE_ERROR_CODE, UNAVAILABLE_OR_DEACTIVATED_FUNCTION_ERROR_CODE, UNKNOWN_SCHEDULED_FUNCTION_DEVELOPMENT_FUNCTION_NAME_CODE, UNKNOWN_SCHEDULED_FUNCTION_DEVELOPMENT_FUNCTION_TYPE_CODE, _onCallWithCallTypeFunction, alreadyExistsError, appFirestoreModuleMetadata, assertContextHasAuth, assertDocumentExists, assertHasRolesInRequest, assertHasSignedTosInRequest, assertIsAdminInRequest, assertIsAdminOrTargetUserInRequestData, assertIsContextWithAuthData, assertRequestRequiresAuthForFunction, assertSnapshotData, assertSnapshotDataWithKey, badRequestError, blockingFunctionHandlerWithNestContextFactory, cloudEventHandlerWithNestContextFactory, collectionRefForPath, createModelUnknownModelTypeError, defaultFirebaseServerActionsTransformFactoryLogErrorFunction, defaultProvideFirebaseServerStorageServiceSimple, deleteModelUnknownModelTypeError, developmentUnknownSpecifierError, docRefForPath, documentModelNotAvailableError, firebaseAuthTokenFromDecodedIdToken, firebaseServerActionsContext, firebaseServerActionsTransformContext, firebaseServerActionsTransformFactory, firebaseServerAppTokenProvider, firebaseServerAuthModuleMetadata, firebaseServerDevFunctions, firebaseServerErrorInfo, firebaseServerErrorInfoCodePair, firebaseServerErrorInfoServerErrorCodePair, firebaseServerErrorInfoServerErrorPair, firebaseServerStorageDefaultBucketIdTokenProvider, firebaseServerStorageModuleMetadata, firebaseServerValidationError, firebaseServerValidationServerError, firestoreClientQueryConstraintFunctionsDriver, firestoreServerIncrementUpdateToUpdateData, forbiddenError, getAuthUserOrUndefined, googleCloudFileMetadataToStorageMetadata, googleCloudFirebaseStorageContextFactory, googleCloudFirebaseStorageDrivers, googleCloudFirestoreAccessorDriver, googleCloudFirestoreContextFactory, googleCloudFirestoreDrivers, googleCloudFirestoreQueryDriver, googleCloudStorageAccessorFile, googleCloudStorageAccessorFolder, googleCloudStorageBucketForStorageFilePath, googleCloudStorageFileForStorageFilePath, googleCloudStorageFirebaseStorageAccessorDriver, googleCloudStorageFromFirebaseAdminStorage, googleCloudStorageListFilesResultFactory, handleFirebaseAuthError, handleFirebaseError, hasAuthRolesInRequest, hasNewUserSetupPasswordInRequest, hasSignedTosInRequest, inAuthContext, injectNestApplicationContextIntoRequest, injectNestIntoRequest, internalServerError, isAdminInRequest, isAdminOrTargetUserInRequestData, isContextWithAuthData, isFirebaseError, isFirebaseHttpsError, makeBlockingFunctionWithHandler, makeOnScheduleHandlerWithNestApplicationRequest, makeScheduledFunctionDevelopmentFunction, modelNotAvailableError, nestAppHasDevelopmentSchedulerEnabled, nestAppIsProductionEnvironment, nestFirebaseDoesNotExistError, nestFirebaseForbiddenPermissionError, nestServerInstance, noRunNameSpecifiedForScheduledFunctionDevelopmentFunction, notFoundError, onCallCreateModel, onCallDeleteModel, onCallDevelopmentFunction, onCallHandlerWithNestApplicationFactory, onCallHandlerWithNestContextFactory, onCallModel, onCallModelMissingCallTypeError, onCallModelUnknownCallTypeError, onCallReadModel, onCallSpecifierHandler, onCallUpdateModel, onScheduleHandlerWithNestApplicationFactory, onScheduleHandlerWithNestContextFactory, optionalAuthContext, permissionDeniedError, phoneNumberAlreadyExistsError, preconditionConflictError, provideAppFirestoreCollections, provideFirebaseServerAuthService, provideFirebaseServerStorageService, readModelUnknownModelTypeError, setNestContextOnRequest, setNestContextOnScheduleRequest, taskQueueFunctionHandlerWithNestContextFactory, unauthenticatedContextHasNoAuthData, unauthenticatedContextHasNoUidError, unauthenticatedError, unavailableError, unavailableOrDeactivatedFunctionError, unknownModelCrudFunctionSpecifierError, unknownScheduledFunctionDevelopmentFunctionName, unknownScheduledFunctionDevelopmentFunctionType, updateModelUnknownModelTypeError, userContextFromUid, verifyAppCheckInRequest };
+export { ALREADY_EXISTS_ERROR_CODE, AbstractFirebaseNestContext, AbstractFirebaseServerActionsContext, AbstractFirebaseServerAuthContext, AbstractFirebaseServerAuthService, AbstractFirebaseServerAuthUserContext, AbstractFirebaseServerNewUserService, AbstractNestContext, BAD_REQUEST_ERROR_CODE, CONFLICT_ERROR_CODE, ConfigureFirebaseAppCheckMiddlewareModule, ConfigureFirebaseWebhookMiddlewareModule, DEFAULT_FIREBASE_PASSWORD_NUMBER_GENERATOR, DEFAULT_SETUP_COM_THROTTLE_TIME, DefaultFirebaseServerEnvService, FIREBASE_APP_TOKEN, FIREBASE_AUTH_TOKEN, FIREBASE_FIRESTORE_CONTEXT_TOKEN, FIREBASE_FIRESTORE_TOKEN, FIREBASE_SERVER_VALIDATION_ERROR_CODE, FIREBASE_STORAGE_CONTEXT_FACTORY_CONFIG_TOKEN, FIREBASE_STORAGE_CONTEXT_TOKEN, FIREBASE_STORAGE_TOKEN, FIRESTORE_CLIENT_QUERY_CONSTRAINT_HANDLER_MAPPING, FORBIDDEN_ERROR_CODE, FirebaseAppCheckMiddleware, FirebaseNestServerRootModule, FirebaseRawBodyMiddleware, FirebaseServerAuthModule, FirebaseServerAuthNewUserSendSetupDetailsNoSetupConfigError, FirebaseServerAuthNewUserSendSetupDetailsSendOnceError, FirebaseServerAuthNewUserSendSetupDetailsThrottleError, FirebaseServerAuthService, FirebaseServerEnvService, FirebaseServerFirestoreContextModule, FirebaseServerFirestoreModule, FirebaseServerStorageContextModule, FirebaseServerStorageModule, FirebaseServerStorageService, INTERNAL_SERVER_ERROR_CODE, MODEL_NOT_AVAILABLE_ERROR_CODE, NOT_FOUND_ERROR_CODE, NO_RUN_NAME_SPECIFIED_FOR_SCHEDULED_FUNCTION_DEVELOPMENT_FUNCTION_CODE, NoSetupContentFirebaseServerNewUserService, PERMISSION_DENIED_ERROR_CODE, PHONE_NUMBER_ALREADY_EXISTS_ERROR_CODE, SkipAppCheck, UNAUTHENTICATED_ERROR_CODE, UNAVAILABLE_ERROR_CODE, UNAVAILABLE_OR_DEACTIVATED_FUNCTION_ERROR_CODE, UNKNOWN_SCHEDULED_FUNCTION_DEVELOPMENT_FUNCTION_NAME_CODE, UNKNOWN_SCHEDULED_FUNCTION_DEVELOPMENT_FUNCTION_TYPE_CODE, _onCallWithCallTypeFunction, aggregateCrudModelApiDetails, aggregateModelApiDetails, aggregateSpecifierApiDetails, alreadyExistsError, appFirestoreModuleMetadata, assertContextHasAuth, assertDocumentExists, assertHasRolesInRequest, assertHasSignedTosInRequest, assertIsAdminInRequest, assertIsAdminOrTargetUserInRequestData, assertIsContextWithAuthData, assertRequestRequiresAuthForFunction, assertSnapshotData, assertSnapshotDataWithKey, badRequestError, blockingFunctionHandlerWithNestContextFactory, cloudEventHandlerWithNestContextFactory, collectionRefForPath, createModelUnknownModelTypeError, defaultFirebaseServerActionsTransformFactoryLogErrorFunction, defaultProvideFirebaseServerStorageServiceSimple, deleteModelUnknownModelTypeError, developmentUnknownSpecifierError, docRefForPath, documentModelNotAvailableError, firebaseAuthTokenFromDecodedIdToken, firebaseServerActionsContext, firebaseServerActionsTransformContext, firebaseServerActionsTransformFactory, firebaseServerAppTokenProvider, firebaseServerAuthModuleMetadata, firebaseServerDevFunctions, firebaseServerErrorInfo, firebaseServerErrorInfoCodePair, firebaseServerErrorInfoServerErrorCodePair, firebaseServerErrorInfoServerErrorPair, firebaseServerStorageDefaultBucketIdTokenProvider, firebaseServerStorageModuleMetadata, firebaseServerValidationError, firebaseServerValidationServerError, firestoreClientQueryConstraintFunctionsDriver, firestoreEncryptedField, firestoreServerIncrementUpdateToUpdateData, forbiddenError, getAuthUserOrUndefined, getModelApiDetails, googleCloudFileMetadataToStorageMetadata, googleCloudFirebaseStorageContextFactory, googleCloudFirebaseStorageDrivers, googleCloudFirestoreAccessorDriver, googleCloudFirestoreContextFactory, googleCloudFirestoreDrivers, googleCloudFirestoreQueryDriver, googleCloudStorageAccessorFile, googleCloudStorageAccessorFolder, googleCloudStorageBucketForStorageFilePath, googleCloudStorageFileForStorageFilePath, googleCloudStorageFirebaseStorageAccessorDriver, googleCloudStorageFromFirebaseAdminStorage, googleCloudStorageListFilesResultFactory, handleFirebaseAuthError, handleFirebaseError, hasAuthRolesInRequest, hasNewUserSetupPasswordInRequest, hasSignedTosInRequest, inAuthContext, injectNestApplicationContextIntoRequest, injectNestIntoRequest, internalServerError, isAdminInRequest, isAdminOrTargetUserInRequestData, isContextWithAuthData, isFirebaseError, isFirebaseHttpsError, isOnCallCrudModelApiDetails, isOnCallHandlerApiDetails, isOnCallSpecifierApiDetails, makeBlockingFunctionWithHandler, makeOnScheduleHandlerWithNestApplicationRequest, makeScheduledFunctionDevelopmentFunction, modelNotAvailableError, nestAppHasDevelopmentSchedulerEnabled, nestAppIsProductionEnvironment, nestFirebaseDoesNotExistError, nestFirebaseForbiddenPermissionError, nestServerInstance, noRunNameSpecifiedForScheduledFunctionDevelopmentFunction, notFoundError, onCallCreateModel, onCallDeleteModel, onCallDevelopmentFunction, onCallHandlerWithNestApplicationFactory, onCallHandlerWithNestContextFactory, onCallModel, onCallModelMissingCallTypeError, onCallModelUnknownCallTypeError, onCallReadModel, onCallSpecifierHandler, onCallUpdateModel, onScheduleHandlerWithNestApplicationFactory, onScheduleHandlerWithNestContextFactory, optionalAuthContext, optionalFirestoreEncryptedField, permissionDeniedError, phoneNumberAlreadyExistsError, preconditionConflictError, provideAppFirestoreCollections, provideFirebaseServerAuthService, provideFirebaseServerStorageService, readApiDetails, readModelUnknownModelTypeError, setNestContextOnRequest, setNestContextOnScheduleRequest, taskQueueFunctionHandlerWithNestContextFactory, unauthenticatedContextHasNoAuthData, unauthenticatedContextHasNoUidError, unauthenticatedError, unavailableError, unavailableOrDeactivatedFunctionError, unknownModelCrudFunctionSpecifierError, unknownScheduledFunctionDevelopmentFunctionName, unknownScheduledFunctionDevelopmentFunctionType, updateModelUnknownModelTypeError, userContextFromUid, verifyAppCheckInRequest, withApiDetails };
 //# sourceMappingURL=index.esm.js.map