@dereekb/firebase-server 13.29.0 → 13.30.0

package/index.cjs.js

@@ -7059,6 +7059,78 @@ exports.FirebaseServerAuthModule = __decorate([
     return claims[firebase.FIREBASE_SERVER_AUTH_CLAIMS_SETUP_PASSWORD_KEY] != null;
 }
 
+// MARK: Scope Reading
+/**
+ * Reads the set of OIDC scopes carried by a model-api request's auth, or `undefined` for a non-OIDC
+ * (regular Firebase ID-token) caller.
+ *
+ * The OIDC bearer-token middleware attaches the validated access-token claims at
+ * `auth.oidcValidatedToken` (with the space-delimited `scope` string); a non-OIDC caller has neither
+ * that field nor a `scope` on `auth.token`. Reading is defensive (the auth shape is only typed as
+ * {@link FirebaseServerAuthData} here — the OIDC-specific `oidcValidatedToken` lives in the
+ * `@dereekb/firebase-server/oidc` sub-package this core layer cannot import), delegating the actual
+ * parse to the shared {@link oidcScopesFromScopeClaim} so there is no drift with `getOidcScopesFromRequest`.
+ *
+ * @param auth - The request auth data, or undefined for unauthenticated requests.
+ * @returns The granted scope set, or `undefined` when the request carries no OIDC `scope` claim.
+ */ function oidcScopesFromModelApiAuth(auth) {
+    var _auth_oidcValidatedToken, _auth_token;
+    var oidcScope = auth === null || auth === void 0 ? void 0 : (_auth_oidcValidatedToken = auth.oidcValidatedToken) === null || _auth_oidcValidatedToken === void 0 ? void 0 : _auth_oidcValidatedToken.scope;
+    var tokenScope = auth === null || auth === void 0 ? void 0 : (_auth_token = auth.token) === null || _auth_token === void 0 ? void 0 : _auth_token.scope;
+    var scope = oidcScope !== null && oidcScope !== void 0 ? oidcScope : tokenScope;
+    return firebase.oidcScopesFromScopeClaim(scope);
+}
+/**
+ * Enforces the OIDC scope requirement for a single model-api op, throwing a `403`
+ * {@link CALL_MODEL_MISSING_OIDC_SCOPE_ERROR_CODE} error when the caller does not satisfy it.
+ *
+ * The single home of callModel OIDC scope enforcement. It reuses the shipped composition + evaluation
+ * (`resolveEffectiveOidcScopeTerms` / `oidcScopeTermsSatisfied`) so enforcement and the MCP
+ * tool-visibility filter never drift. Enforcement is AND-of-ORs across the per-verb `model.<call>`
+ * scope and the effective GROUP term (per-function `requiredScope` > per-model requirement >
+ * configured default).
+ *
+ * Bypasses (no-op) when `grantedScopes` is `undefined` — i.e. a non-OIDC caller — and short-circuits
+ * without any check when the op resolves no requirement at all (a custom, non-CRUD verb with no
+ * per-function/model/default term).
+ *
+ * @param input - The verb, model type, per-function scope, group config, and the caller's granted scopes.
+ * @throws A `403` forbidden error (code {@link CALL_MODEL_MISSING_OIDC_SCOPE_ERROR_CODE}) when an OIDC
+ *   caller does not satisfy the effective requirement.
+ */ function assertModelApiOidcScope(input) {
+    var call = input.call, modelType = input.modelType, requiredScope = input.requiredScope, defaultRequiredScope = input.defaultRequiredScope, modelRequiredScopes = input.modelRequiredScopes, grantedScopes = input.grantedScopes;
+    var terms = firebase.resolveEffectiveOidcScopeTerms({
+        perVerbScope: firebase.callModelOidcScopeForCallType(call),
+        requiredScope: requiredScope,
+        modelRequirement: modelRequiredScopes === null || modelRequiredScopes === void 0 ? void 0 : modelRequiredScopes[modelType],
+        call: call,
+        defaultRequiredScope: defaultRequiredScope
+    });
+    if (terms.length > 0 && grantedScopes != null && !firebase.oidcScopeTermsSatisfied(terms, grantedScopes)) {
+        var missingTerms = terms.filter(function(term) {
+            return !firebase.oidcScopeTermSatisfied(term, grantedScopes);
+        });
+        throw forbiddenError({
+            status: 403,
+            code: firebase.CALL_MODEL_MISSING_OIDC_SCOPE_ERROR_CODE,
+            message: "Missing required OIDC scope for callModel: ".concat(missingTerms.map(formatModelApiScopeTerm).join(', ')),
+            data: {
+                requiredScopes: missingTerms,
+                call: call
+            }
+        });
+    }
+}
+/**
+ * Renders a scope term for the human-readable error message: a single scope as-is, an OR-group as its
+ * alternatives joined by `|` (so a single-scope term reads as itself).
+ *
+ * @param term - The unsatisfied scope term.
+ * @returns The display string for the term.
+ */ function formatModelApiScopeTerm(term) {
+    return typeof term === 'string' ? term : term.join('|');
+}
+
 function _define_property$n(obj, key, value) {
     if (key in obj) {
         Object.defineProperty(obj, key, {
@@ -7335,6 +7407,15 @@ function _ts_generator$a(thisArg, body) {
     /**
      * Factory to create typed nest context from INestApplicationContext.
      */ _define_property$m(this, "makeNestContext", void 0);
+    /**
+     * Optional model-api-layer OIDC group-scope default. See {@link ModelApiOidcScopeConfig.defaultRequiredScope}.
+     * This is the home for the callModel group-scope default; providing it here enforces it across
+     * dispatch AND the `/get` reads.
+     */ _define_property$m(this, "defaultRequiredScope", void 0);
+    /**
+     * Optional per-model OIDC group-scope overrides. See {@link ModelApiOidcScopeConfig.modelRequiredScopes}.
+     * The only place a plain `/get` read (no per-function handler) can be scope-gated beyond `model.read`.
+     */ _define_property$m(this, "modelRequiredScopes", void 0);
 };
 /**
  * Injection token for providing the NestJS application context to the dispatch service.
@@ -7369,8 +7450,25 @@ function _ts_generator$a(thisArg, body) {
      * @returns The handler's return value.
      */ function dispatch(params, auth, rawRequest) {
                 return _async_to_generator$a(function() {
-                    var callableRequest, appRequest, contextRequest;
+                    var call, modelType, specifier, apiDetails, requiredScope, callableRequest, appRequest, contextRequest;
                     return _ts_generator$a(this, function(_state) {
+                        // Enforce OIDC scope BEFORE dispatching — the relocated home of the callModel scope check.
+                        // AND-of-ORs across the per-verb `model.<call>` scope and the effective group term (per-function
+                        // `requiredScope` > per-model requirement > module default), bypassing non-OIDC callers. A nullish
+                        // `call` is a malformed request the callModel chain rejects downstream (no model op to authorize).
+                        call = params.call, modelType = params.modelType, specifier = params.specifier;
+                        if (call != null) {
+                            apiDetails = this.config.callModelFn._apiDetails;
+                            requiredScope = apiDetails == null ? undefined : resolveRequiredScopeFromApiDetails(apiDetails, call, modelType, specifier);
+                            assertModelApiOidcScope({
+                                call: call,
+                                modelType: modelType,
+                                requiredScope: requiredScope,
+                                defaultRequiredScope: this.config.defaultRequiredScope,
+                                modelRequiredScopes: this.config.modelRequiredScopes,
+                                grantedScopes: oidcScopesFromModelApiAuth(auth)
+                            });
+                        }
                         // Build a synthetic CallableRequest that the dispatch chain expects. Layer the
                         // OIDC-validated claim subset over the base token so standard JWT claims
                         // (`iat`, `auth_time`, `email`, …) survive — the callModel chain and any
@@ -7657,12 +7755,38 @@ 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, "_defaultRequiredScope", void 0);
+        _define_property$l(this, "_modelRequiredScopes", void 0);
         _define_property$l(this, "_identityByModelType", void 0);
         this._nestContext = config.makeNestContext(nestApplication);
+        this._defaultRequiredScope = config.defaultRequiredScope;
+        this._modelRequiredScopes = config.modelRequiredScopes;
     }
     _create_class$9(ModelApiGetService, [
         {
             /**
+     * Enforces the OIDC read-scope requirement for a direct document read before it hits Firestore.
+     *
+     * A direct `/get` read is the `read` verb: it requires the per-verb `model.read` scope AND any
+     * effective group term for the target model (per-model requirement > module default). This is the
+     * ONLY gate on the direct-read path — it does not touch the callModel dispatch chain — so without it
+     * an OIDC client scoped to a subset could read any model through `/get`. Non-OIDC callers bypass.
+     *
+     * @param modelType - The Firestore model type being read.
+     * @param auth - The request's auth data (OIDC scopes are read from it).
+     */ key: "_assertReadScope",
+            value: function _assertReadScope(modelType, auth) {
+                assertModelApiOidcScope({
+                    call: 'read',
+                    modelType: modelType,
+                    defaultRequiredScope: this._defaultRequiredScope,
+                    modelRequiredScopes: this._modelRequiredScopes,
+                    grantedScopes: oidcScopesFromModelApiAuth(auth)
+                });
+            }
+        },
+        {
+            /**
      * Returns the registered {@link FirestoreModelIdentity} for the given `modelType` string, or
      * `undefined` when no model of that type is registered.
      *
@@ -7734,6 +7858,7 @@ function _ts_generator$9(thisArg, body) {
                     return _ts_generator$9(this, function(_state) {
                         switch(_state.label){
                             case 0:
+                                this._assertReadScope(modelType, auth);
                                 authRef = this._makeAuthRef(auth);
                                 return [
                                     4,
@@ -7782,6 +7907,7 @@ function _ts_generator$9(thisArg, body) {
                 return _async_to_generator$9(function() {
                     var authRef;
                     return _ts_generator$9(this, function(_state) {
+                        this._assertReadScope(modelType, auth);
                         authRef = this._makeAuthRef(auth);
                         return [
                             2,
@@ -13185,6 +13311,7 @@ exports.assertHasSignedTosInRequest = assertHasSignedTosInRequest;
 exports.assertIsAdminInRequest = assertIsAdminInRequest;
 exports.assertIsAdminOrTargetUserInRequestData = assertIsAdminOrTargetUserInRequestData;
 exports.assertIsContextWithAuthData = assertIsContextWithAuthData;
+exports.assertModelApiOidcScope = assertModelApiOidcScope;
 exports.assertRequestRequiresAuthForFunction = assertRequestRequiresAuthForFunction;
 exports.assertSnapshotData = assertSnapshotData;
 exports.assertSnapshotDataWithKey = assertSnapshotDataWithKey;
@@ -13282,6 +13409,7 @@ exports.noRunNameSpecifiedForScheduledFunctionDevelopmentFunction = noRunNameSpe
 exports.noopFirebaseServerAnalyticsServiceListener = noopFirebaseServerAnalyticsServiceListener;
 exports.noopOnCallModelAnalyticsService = noopOnCallModelAnalyticsService;
 exports.notFoundError = notFoundError;
+exports.oidcScopesFromModelApiAuth = oidcScopesFromModelApiAuth;
 exports.onCallAnalyticsEmitterInstance = onCallAnalyticsEmitterInstance;
 exports.onCallCreateModel = onCallCreateModel;
 exports.onCallDeleteModel = onCallDeleteModel;

package/index.esm.js

@@ -1,5 +1,5 @@
 import { timingSafeEqual } from 'node:crypto';
-import { DBX_FIREBASE_SERVER_NO_AUTH_ERROR_CODE, UNAUTHENTICATED_ERROR_CODE, FORBIDDEN_ERROR_CODE, PERMISSION_DENIED_ERROR_CODE, NOT_FOUND_ERROR_CODE, MODEL_NOT_AVAILABLE_ERROR_CODE, BAD_REQUEST_ERROR_CODE, CONFLICT_ERROR_CODE, ALREADY_EXISTS_ERROR_CODE, UNAVAILABLE_ERROR_CODE, UNAVAILABLE_OR_DEACTIVATED_FUNCTION_ERROR_CODE, INTERNAL_SERVER_ERROR_CODE, FIREBASE_AUTH_USER_NOT_FOUND_ERROR, FIREBASE_SERVER_AUTH_CLAIMS_RESET_PASSWORD_KEY, FIREBASE_SERVER_AUTH_CLAIMS_RESET_LAST_COM_DATE_KEY, FIREBASE_SERVER_AUTH_CLAIMS_RESET_EXPIRES_AT_KEY, FIREBASE_AUTH_PHONE_NUMBER_ALREADY_EXISTS_ERROR, FIREBASE_AUTH_EMAIL_ALREADY_EXISTS_ERROR, FIREBASE_AUTH_INVALID_PHONE_NUMBER_ERROR, FIREBASE_SERVER_AUTH_CLAIMS_SETUP_PASSWORD_KEY, FIREBASE_SERVER_AUTH_CLAIMS_SETUP_LAST_COM_DATE_KEY, setIdAndKeyFromKeyIdRefOnDocumentData, DBX_FIREBASE_SERVER_PASSWORD_RESET_INVALID_CODE_ERROR_CODE, DBX_FIREBASE_SERVER_PASSWORD_RESET_NO_CONFIG_ERROR_CODE, DBX_FIREBASE_SERVER_PASSWORD_RESET_SEND_ONCE_ERROR_CODE, DBX_FIREBASE_SERVER_PASSWORD_RESET_THROTTLE_ERROR_CODE, FirestoreDocumentContextType, streamFromOnSnapshot, FIRESTORE_LIMIT_QUERY_CONSTRAINT_TYPE, FIRESTORE_LIMIT_TO_LAST_QUERY_CONSTRAINT_TYPE, FIRESTORE_ORDER_BY_QUERY_CONSTRAINT_TYPE, FIRESTORE_ORDER_BY_DOCUMENT_ID_QUERY_CONSTRAINT_TYPE, FIRESTORE_WHERE_QUERY_CONSTRAINT_TYPE, FIRESTORE_WHERE_DOCUMENT_ID_QUERY_CONSTRAINT_TYPE, FIRESTORE_OFFSET_QUERY_CONSTRAINT_TYPE, FIRESTORE_START_AT_QUERY_CONSTRAINT_TYPE, FIRESTORE_START_AT_VALUE_QUERY_CONSTRAINT_TYPE, FIRESTORE_START_AFTER_QUERY_CONSTRAINT_TYPE, FIRESTORE_END_AT_QUERY_CONSTRAINT_TYPE, FIRESTORE_END_AT_VALUE_QUERY_CONSTRAINT_TYPE, FIRESTORE_END_BEFORE_QUERY_CONSTRAINT_TYPE, makeFirestoreQueryConstraintFunctionsDriver, firestoreContextFactory, firestoreField, optionalFirestoreField, DEFAULT_MODEL_FUNCTION_FIREBASE_CRUD_FUNCTION_SPECIFIER, UNKNOWN_MODEL_TYPE_ERROR_CODE, BAD_DOCUMENT_QUERY_CURSOR_ERROR_CODE, limit, startAfter, DEFAULT_ON_CALL_QUERY_MODEL_LIMIT, MAX_ON_CALL_QUERY_MODEL_LIMIT, ScheduledFunctionDevelopmentFunctionTypeEnum, SCHEDULED_FUNCTION_DEV_FUNCTION_SPECIFIER, storageListFilesResultFactory, assertStorageUploadOptionsStringFormat, firebaseStorageContextFactory, inContextFirebaseModelsServiceFactory, useFirebaseModelsService } from '@dereekb/firebase';
+import { DBX_FIREBASE_SERVER_NO_AUTH_ERROR_CODE, UNAUTHENTICATED_ERROR_CODE, FORBIDDEN_ERROR_CODE, PERMISSION_DENIED_ERROR_CODE, NOT_FOUND_ERROR_CODE, MODEL_NOT_AVAILABLE_ERROR_CODE, BAD_REQUEST_ERROR_CODE, CONFLICT_ERROR_CODE, ALREADY_EXISTS_ERROR_CODE, UNAVAILABLE_ERROR_CODE, UNAVAILABLE_OR_DEACTIVATED_FUNCTION_ERROR_CODE, INTERNAL_SERVER_ERROR_CODE, FIREBASE_AUTH_USER_NOT_FOUND_ERROR, FIREBASE_SERVER_AUTH_CLAIMS_RESET_PASSWORD_KEY, FIREBASE_SERVER_AUTH_CLAIMS_RESET_LAST_COM_DATE_KEY, FIREBASE_SERVER_AUTH_CLAIMS_RESET_EXPIRES_AT_KEY, FIREBASE_AUTH_PHONE_NUMBER_ALREADY_EXISTS_ERROR, FIREBASE_AUTH_EMAIL_ALREADY_EXISTS_ERROR, FIREBASE_AUTH_INVALID_PHONE_NUMBER_ERROR, FIREBASE_SERVER_AUTH_CLAIMS_SETUP_PASSWORD_KEY, FIREBASE_SERVER_AUTH_CLAIMS_SETUP_LAST_COM_DATE_KEY, setIdAndKeyFromKeyIdRefOnDocumentData, DBX_FIREBASE_SERVER_PASSWORD_RESET_INVALID_CODE_ERROR_CODE, DBX_FIREBASE_SERVER_PASSWORD_RESET_NO_CONFIG_ERROR_CODE, DBX_FIREBASE_SERVER_PASSWORD_RESET_SEND_ONCE_ERROR_CODE, DBX_FIREBASE_SERVER_PASSWORD_RESET_THROTTLE_ERROR_CODE, FirestoreDocumentContextType, streamFromOnSnapshot, FIRESTORE_LIMIT_QUERY_CONSTRAINT_TYPE, FIRESTORE_LIMIT_TO_LAST_QUERY_CONSTRAINT_TYPE, FIRESTORE_ORDER_BY_QUERY_CONSTRAINT_TYPE, FIRESTORE_ORDER_BY_DOCUMENT_ID_QUERY_CONSTRAINT_TYPE, FIRESTORE_WHERE_QUERY_CONSTRAINT_TYPE, FIRESTORE_WHERE_DOCUMENT_ID_QUERY_CONSTRAINT_TYPE, FIRESTORE_OFFSET_QUERY_CONSTRAINT_TYPE, FIRESTORE_START_AT_QUERY_CONSTRAINT_TYPE, FIRESTORE_START_AT_VALUE_QUERY_CONSTRAINT_TYPE, FIRESTORE_START_AFTER_QUERY_CONSTRAINT_TYPE, FIRESTORE_END_AT_QUERY_CONSTRAINT_TYPE, FIRESTORE_END_AT_VALUE_QUERY_CONSTRAINT_TYPE, FIRESTORE_END_BEFORE_QUERY_CONSTRAINT_TYPE, makeFirestoreQueryConstraintFunctionsDriver, firestoreContextFactory, firestoreField, optionalFirestoreField, DEFAULT_MODEL_FUNCTION_FIREBASE_CRUD_FUNCTION_SPECIFIER, UNKNOWN_MODEL_TYPE_ERROR_CODE, BAD_DOCUMENT_QUERY_CURSOR_ERROR_CODE, limit, startAfter, DEFAULT_ON_CALL_QUERY_MODEL_LIMIT, MAX_ON_CALL_QUERY_MODEL_LIMIT, resolveEffectiveOidcScopeTerms, callModelOidcScopeForCallType, oidcScopeTermsSatisfied, oidcScopeTermSatisfied, CALL_MODEL_MISSING_OIDC_SCOPE_ERROR_CODE, oidcScopesFromScopeClaim, ScheduledFunctionDevelopmentFunctionTypeEnum, SCHEDULED_FUNCTION_DEV_FUNCTION_SPECIFIER, storageListFilesResultFactory, assertStorageUploadOptionsStringFormat, firebaseStorageContextFactory, inContextFirebaseModelsServiceFactory, useFirebaseModelsService } from '@dereekb/firebase';
 import { partialServerError, isServerError, randomNumberFactory, cachedGetter, filterNullAndUndefinedValues, asSet, AUTH_ADMIN_ROLE, AUTH_TOS_SIGNED_ROLE, forEachKeyValue, KeyValueTypleValueFilter, filterUndefinedValues, isThrottled, mapObjectMap, batch, objectToMap, serverError, asArray, containsAllValues, websiteUrlDetails, mergeObjects, cronExpressionRepeatingEveryNMinutes, mapIdentityFunction, slashPathName, toRelativeSlashPathStartType, fixMultiSlashesInSlashPath, SLASH_PATH_SEPARATOR, objectHasNoKeys, websiteUrlFromPaths, pushItemOrArrayItemsIntoArray, makeGetter, asGetter, build, performAsyncTasks } from '@dereekb/util';
 import { HttpsError } from 'firebase-functions/https';
 import { hoursToMs, minutesToMs, toISODateString } from '@dereekb/date';
@@ -7057,6 +7057,78 @@ FirebaseServerAuthModule = __decorate([
     return claims[FIREBASE_SERVER_AUTH_CLAIMS_SETUP_PASSWORD_KEY] != null;
 }
 
+// MARK: Scope Reading
+/**
+ * Reads the set of OIDC scopes carried by a model-api request's auth, or `undefined` for a non-OIDC
+ * (regular Firebase ID-token) caller.
+ *
+ * The OIDC bearer-token middleware attaches the validated access-token claims at
+ * `auth.oidcValidatedToken` (with the space-delimited `scope` string); a non-OIDC caller has neither
+ * that field nor a `scope` on `auth.token`. Reading is defensive (the auth shape is only typed as
+ * {@link FirebaseServerAuthData} here — the OIDC-specific `oidcValidatedToken` lives in the
+ * `@dereekb/firebase-server/oidc` sub-package this core layer cannot import), delegating the actual
+ * parse to the shared {@link oidcScopesFromScopeClaim} so there is no drift with `getOidcScopesFromRequest`.
+ *
+ * @param auth - The request auth data, or undefined for unauthenticated requests.
+ * @returns The granted scope set, or `undefined` when the request carries no OIDC `scope` claim.
+ */ function oidcScopesFromModelApiAuth(auth) {
+    var _auth_oidcValidatedToken, _auth_token;
+    var oidcScope = auth === null || auth === void 0 ? void 0 : (_auth_oidcValidatedToken = auth.oidcValidatedToken) === null || _auth_oidcValidatedToken === void 0 ? void 0 : _auth_oidcValidatedToken.scope;
+    var tokenScope = auth === null || auth === void 0 ? void 0 : (_auth_token = auth.token) === null || _auth_token === void 0 ? void 0 : _auth_token.scope;
+    var scope = oidcScope !== null && oidcScope !== void 0 ? oidcScope : tokenScope;
+    return oidcScopesFromScopeClaim(scope);
+}
+/**
+ * Enforces the OIDC scope requirement for a single model-api op, throwing a `403`
+ * {@link CALL_MODEL_MISSING_OIDC_SCOPE_ERROR_CODE} error when the caller does not satisfy it.
+ *
+ * The single home of callModel OIDC scope enforcement. It reuses the shipped composition + evaluation
+ * (`resolveEffectiveOidcScopeTerms` / `oidcScopeTermsSatisfied`) so enforcement and the MCP
+ * tool-visibility filter never drift. Enforcement is AND-of-ORs across the per-verb `model.<call>`
+ * scope and the effective GROUP term (per-function `requiredScope` > per-model requirement >
+ * configured default).
+ *
+ * Bypasses (no-op) when `grantedScopes` is `undefined` — i.e. a non-OIDC caller — and short-circuits
+ * without any check when the op resolves no requirement at all (a custom, non-CRUD verb with no
+ * per-function/model/default term).
+ *
+ * @param input - The verb, model type, per-function scope, group config, and the caller's granted scopes.
+ * @throws A `403` forbidden error (code {@link CALL_MODEL_MISSING_OIDC_SCOPE_ERROR_CODE}) when an OIDC
+ *   caller does not satisfy the effective requirement.
+ */ function assertModelApiOidcScope(input) {
+    var call = input.call, modelType = input.modelType, requiredScope = input.requiredScope, defaultRequiredScope = input.defaultRequiredScope, modelRequiredScopes = input.modelRequiredScopes, grantedScopes = input.grantedScopes;
+    var terms = resolveEffectiveOidcScopeTerms({
+        perVerbScope: callModelOidcScopeForCallType(call),
+        requiredScope: requiredScope,
+        modelRequirement: modelRequiredScopes === null || modelRequiredScopes === void 0 ? void 0 : modelRequiredScopes[modelType],
+        call: call,
+        defaultRequiredScope: defaultRequiredScope
+    });
+    if (terms.length > 0 && grantedScopes != null && !oidcScopeTermsSatisfied(terms, grantedScopes)) {
+        var missingTerms = terms.filter(function(term) {
+            return !oidcScopeTermSatisfied(term, grantedScopes);
+        });
+        throw forbiddenError({
+            status: 403,
+            code: CALL_MODEL_MISSING_OIDC_SCOPE_ERROR_CODE,
+            message: "Missing required OIDC scope for callModel: ".concat(missingTerms.map(formatModelApiScopeTerm).join(', ')),
+            data: {
+                requiredScopes: missingTerms,
+                call: call
+            }
+        });
+    }
+}
+/**
+ * Renders a scope term for the human-readable error message: a single scope as-is, an OR-group as its
+ * alternatives joined by `|` (so a single-scope term reads as itself).
+ *
+ * @param term - The unsatisfied scope term.
+ * @returns The display string for the term.
+ */ function formatModelApiScopeTerm(term) {
+    return typeof term === 'string' ? term : term.join('|');
+}
+
 function _define_property$n(obj, key, value) {
     if (key in obj) {
         Object.defineProperty(obj, key, {
@@ -7333,6 +7405,15 @@ function _ts_generator$a(thisArg, body) {
     /**
      * Factory to create typed nest context from INestApplicationContext.
      */ _define_property$m(this, "makeNestContext", void 0);
+    /**
+     * Optional model-api-layer OIDC group-scope default. See {@link ModelApiOidcScopeConfig.defaultRequiredScope}.
+     * This is the home for the callModel group-scope default; providing it here enforces it across
+     * dispatch AND the `/get` reads.
+     */ _define_property$m(this, "defaultRequiredScope", void 0);
+    /**
+     * Optional per-model OIDC group-scope overrides. See {@link ModelApiOidcScopeConfig.modelRequiredScopes}.
+     * The only place a plain `/get` read (no per-function handler) can be scope-gated beyond `model.read`.
+     */ _define_property$m(this, "modelRequiredScopes", void 0);
 };
 /**
  * Injection token for providing the NestJS application context to the dispatch service.
@@ -7367,8 +7448,25 @@ function _ts_generator$a(thisArg, body) {
      * @returns The handler's return value.
      */ function dispatch(params, auth, rawRequest) {
                 return _async_to_generator$a(function() {
-                    var callableRequest, appRequest, contextRequest;
+                    var call, modelType, specifier, apiDetails, requiredScope, callableRequest, appRequest, contextRequest;
                     return _ts_generator$a(this, function(_state) {
+                        // Enforce OIDC scope BEFORE dispatching — the relocated home of the callModel scope check.
+                        // AND-of-ORs across the per-verb `model.<call>` scope and the effective group term (per-function
+                        // `requiredScope` > per-model requirement > module default), bypassing non-OIDC callers. A nullish
+                        // `call` is a malformed request the callModel chain rejects downstream (no model op to authorize).
+                        call = params.call, modelType = params.modelType, specifier = params.specifier;
+                        if (call != null) {
+                            apiDetails = this.config.callModelFn._apiDetails;
+                            requiredScope = apiDetails == null ? undefined : resolveRequiredScopeFromApiDetails(apiDetails, call, modelType, specifier);
+                            assertModelApiOidcScope({
+                                call: call,
+                                modelType: modelType,
+                                requiredScope: requiredScope,
+                                defaultRequiredScope: this.config.defaultRequiredScope,
+                                modelRequiredScopes: this.config.modelRequiredScopes,
+                                grantedScopes: oidcScopesFromModelApiAuth(auth)
+                            });
+                        }
                         // Build a synthetic CallableRequest that the dispatch chain expects. Layer the
                         // OIDC-validated claim subset over the base token so standard JWT claims
                         // (`iat`, `auth_time`, `email`, …) survive — the callModel chain and any
@@ -7655,12 +7753,38 @@ 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, "_defaultRequiredScope", void 0);
+        _define_property$l(this, "_modelRequiredScopes", void 0);
         _define_property$l(this, "_identityByModelType", void 0);
         this._nestContext = config.makeNestContext(nestApplication);
+        this._defaultRequiredScope = config.defaultRequiredScope;
+        this._modelRequiredScopes = config.modelRequiredScopes;
     }
     _create_class$9(ModelApiGetService, [
         {
             /**
+     * Enforces the OIDC read-scope requirement for a direct document read before it hits Firestore.
+     *
+     * A direct `/get` read is the `read` verb: it requires the per-verb `model.read` scope AND any
+     * effective group term for the target model (per-model requirement > module default). This is the
+     * ONLY gate on the direct-read path — it does not touch the callModel dispatch chain — so without it
+     * an OIDC client scoped to a subset could read any model through `/get`. Non-OIDC callers bypass.
+     *
+     * @param modelType - The Firestore model type being read.
+     * @param auth - The request's auth data (OIDC scopes are read from it).
+     */ key: "_assertReadScope",
+            value: function _assertReadScope(modelType, auth) {
+                assertModelApiOidcScope({
+                    call: 'read',
+                    modelType: modelType,
+                    defaultRequiredScope: this._defaultRequiredScope,
+                    modelRequiredScopes: this._modelRequiredScopes,
+                    grantedScopes: oidcScopesFromModelApiAuth(auth)
+                });
+            }
+        },
+        {
+            /**
      * Returns the registered {@link FirestoreModelIdentity} for the given `modelType` string, or
      * `undefined` when no model of that type is registered.
      *
@@ -7732,6 +7856,7 @@ function _ts_generator$9(thisArg, body) {
                     return _ts_generator$9(this, function(_state) {
                         switch(_state.label){
                             case 0:
+                                this._assertReadScope(modelType, auth);
                                 authRef = this._makeAuthRef(auth);
                                 return [
                                     4,
@@ -7780,6 +7905,7 @@ function _ts_generator$9(thisArg, body) {
                 return _async_to_generator$9(function() {
                     var authRef;
                     return _ts_generator$9(this, function(_state) {
+                        this._assertReadScope(modelType, auth);
                         authRef = this._makeAuthRef(auth);
                         return [
                             2,
@@ -13116,4 +13242,4 @@ function _define_property(obj, key, value) {
 } 
 ();
 
-export { AbstractFirebaseNestContext, AbstractFirebaseServerActionsContext, AbstractFirebaseServerAuthContext, AbstractFirebaseServerAuthService, AbstractFirebaseServerAuthUserContext, AbstractFirebaseServerNewUserService, AbstractFirebaseServerUserPasswordResetService, AbstractNestContext, AbstractServerFirebaseNestContext, ConfigureFirebaseAppCheckMiddlewareModule, ConfigureFirebaseWebhookMiddlewareModule, DEFAULT_FIREBASE_PASSWORD_NUMBER_GENERATOR, DEFAULT_RESET_CODE_EXPIRES_IN, DEFAULT_RESET_COM_THROTTLE_TIME, DEFAULT_SERVER_ASSETS_BASE_PATH, DEFAULT_SETUP_COM_THROTTLE_TIME, DefaultFirebaseServerEnvService, FIREBASE_APP_TOKEN, FIREBASE_AUTH_TOKEN, FIREBASE_FIRESTORE_CONTEXT_TOKEN, FIREBASE_FIRESTORE_TOKEN, FIREBASE_SERVER_ENV_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, FirebaseAppCheckMiddleware, FirebaseAppCheckMiddlewareConfig, FirebaseNestServerRootModule, FirebaseRawBodyMiddleware, FirebaseServerAnalyticsSegmentListenerService, FirebaseServerAnalyticsSegmentModule, FirebaseServerAnalyticsService, FirebaseServerAnalyticsServiceListener, FirebaseServerAuthModule, FirebaseServerAuthNewUserSendSetupDetailsNoSetupConfigError, FirebaseServerAuthNewUserSendSetupDetailsSendOnceError, FirebaseServerAuthNewUserSendSetupDetailsThrottleError, FirebaseServerAuthPasswordResetInvalidCodeError, FirebaseServerAuthPasswordResetNoResetConfigError, FirebaseServerAuthPasswordResetSendOnceError, FirebaseServerAuthPasswordResetThrottleError, FirebaseServerAuthService, FirebaseServerAuthUserBadInputError, FirebaseServerAuthUserExistsError, FirebaseServerEnvService, FirebaseServerFirestoreContextModule, FirebaseServerFirestoreModule, FirebaseServerStorageContextModule, FirebaseServerStorageModule, FirebaseServerStorageService, GlobalRoutePrefixConfig, MAX_MODEL_ACCESS_MULTI_READ_KEYS, MODEL_API_NEST_APPLICATION_CONTEXT, ModelApiCallModelDispatchService, ModelApiController, ModelApiDispatchConfig, ModelApiGetService, NO_RUN_NAME_SPECIFIED_FOR_SCHEDULED_FUNCTION_DEVELOPMENT_FUNCTION_CODE, NoContentFirebaseServerUserPasswordResetService, NoSetupContentFirebaseServerNewUserService, ON_CALL_MODEL_ANALYTICS_HANDLER, ON_CALL_MODEL_ANALYTICS_SERVICE, OnCallModelAnalyticsService, PHONE_NUMBER_ALREADY_EXISTS_ERROR_CODE, SkipAppCheck, UNKNOWN_SCHEDULED_FUNCTION_DEVELOPMENT_FUNCTION_NAME_CODE, UNKNOWN_SCHEDULED_FUNCTION_DEVELOPMENT_FUNCTION_TYPE_CODE, _onCallWithCallTypeFunction, aggregateCrudModelApiDetails, aggregateModelApiDetails, aggregateSpecifierApiDetails, alreadyExistsError, appAnalyticsModuleMetadata, appFirestoreModuleMetadata, assertContextHasAuth, assertDocumentExists, assertHasRolesInRequest, assertHasSignedTosInRequest, assertIsAdminInRequest, assertIsAdminOrTargetUserInRequestData, assertIsContextWithAuthData, assertRequestRequiresAuthForFunction, assertSnapshotData, assertSnapshotDataWithKey, authServicePasswordResetInvalidCodeError, authServicePasswordResetNoConfigError, authServicePasswordResetSendOnceError, authServicePasswordResetThrottleError, badRequestError, blockingFunctionHandlerWithNestContextFactory, buildNestServerRootModule, callWithAnalytics, catchAndThrowPasswordResetServerErrors, cloudEventHandlerWithNestContextFactory, collectionRefForPath, createModelUnknownModelTypeError, decodeFirebaseServerUserPasswordResetOobCode, defaultFirebaseServerActionsTransformFactoryLogErrorFunction, defaultProvideFirebaseServerStorageServiceSimple, deleteModelUnknownModelTypeError, developmentUnknownSpecifierError, docRefForPath, documentModelNotAvailableError, encodeFirebaseServerUserPasswordResetOobCode, executeOnCallQuery, firebaseAuthTokenFromDecodedIdToken, firebaseServerActionsContext, firebaseServerActionsTransformContext, firebaseServerActionsTransformFactory, firebaseServerAppTokenProvider, firebaseServerAuthModuleMetadata, firebaseServerDevFunctions, firebaseServerEnvTokenProvider, firebaseServerEnvTokenProviders, firebaseServerErrorInfo, firebaseServerErrorInfoCodePair, firebaseServerErrorInfoServerErrorCodePair, firebaseServerErrorInfoServerErrorPair, firebaseServerFirestoreContextModuleMetadata, 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, invokeModelUnknownModelTypeError, isActualSpecifier, isAdminInRequest, isAdminOrTargetUserInRequestData, isContextWithAuthData, isFirebaseError, isFirebaseHttpsError, isOnCallCrudModelApiDetails, isOnCallHandlerApiDetails, isOnCallModelTypeApiDetails, isOnCallSpecifierApiDetails, makeBlockingFunctionWithHandler, makeOnScheduleHandlerWithNestApplicationRequest, makeScheduledFunctionDevelopmentFunction, modelAccessReadErrorFromUseMultipleModelsFailure, modelApiModuleMetadata, modelNotAvailableError, nestAppHasDevelopmentSchedulerEnabled, nestAppIsProductionEnvironment, nestFirebaseDoesNotExistError, nestFirebaseForbiddenPermissionError, nestServerInstance, noRunNameSpecifiedForScheduledFunctionDevelopmentFunction, noopFirebaseServerAnalyticsServiceListener, noopOnCallModelAnalyticsService, notFoundError, onCallAnalyticsEmitterInstance, onCallCreateModel, onCallDeleteModel, onCallDevelopmentFunction, onCallHandlerWithNestApplicationFactory, onCallHandlerWithNestContextFactory, onCallInvokeModel, onCallModel, onCallModelMissingCallTypeError, onCallModelUnknownCallTypeError, onCallQueryModel, onCallReadModel, onCallSpecifierHandler, onCallUpdateModel, onScheduleHandlerWithNestApplicationFactory, onScheduleHandlerWithNestContextFactory, optionalAuthContext, optionalFirestoreEncryptedField, permissionDeniedError, phoneNumberAlreadyExistsError, preconditionConflictError, provideAppFirestoreCollections, provideFirebaseServerAuthService, provideFirebaseServerStorageService, queryModelBadCursorError, queryModelUnknownModelTypeError, readApiDetails, readModelUnknownModelTypeError, resolveAdminOnlyValue, resolveAnalyticsFromApiDetails, resolveRequiredScopeFromApiDetails, setNestContextOnRequest, setNestContextOnScheduleRequest, taskQueueFunctionHandlerWithNestContextFactory, unauthenticatedContextHasNoAuthData, unauthenticatedContextHasNoUidError, unauthenticatedError, unavailableError, unavailableOrDeactivatedFunctionError, unknownModelCrudFunctionSpecifierError, unknownScheduledFunctionDevelopmentFunctionName, unknownScheduledFunctionDevelopmentFunctionType, updateModelUnknownModelTypeError, userContextFromUid, verifyAppCheckInRequest, withApiDetails };
+export { AbstractFirebaseNestContext, AbstractFirebaseServerActionsContext, AbstractFirebaseServerAuthContext, AbstractFirebaseServerAuthService, AbstractFirebaseServerAuthUserContext, AbstractFirebaseServerNewUserService, AbstractFirebaseServerUserPasswordResetService, AbstractNestContext, AbstractServerFirebaseNestContext, ConfigureFirebaseAppCheckMiddlewareModule, ConfigureFirebaseWebhookMiddlewareModule, DEFAULT_FIREBASE_PASSWORD_NUMBER_GENERATOR, DEFAULT_RESET_CODE_EXPIRES_IN, DEFAULT_RESET_COM_THROTTLE_TIME, DEFAULT_SERVER_ASSETS_BASE_PATH, DEFAULT_SETUP_COM_THROTTLE_TIME, DefaultFirebaseServerEnvService, FIREBASE_APP_TOKEN, FIREBASE_AUTH_TOKEN, FIREBASE_FIRESTORE_CONTEXT_TOKEN, FIREBASE_FIRESTORE_TOKEN, FIREBASE_SERVER_ENV_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, FirebaseAppCheckMiddleware, FirebaseAppCheckMiddlewareConfig, FirebaseNestServerRootModule, FirebaseRawBodyMiddleware, FirebaseServerAnalyticsSegmentListenerService, FirebaseServerAnalyticsSegmentModule, FirebaseServerAnalyticsService, FirebaseServerAnalyticsServiceListener, FirebaseServerAuthModule, FirebaseServerAuthNewUserSendSetupDetailsNoSetupConfigError, FirebaseServerAuthNewUserSendSetupDetailsSendOnceError, FirebaseServerAuthNewUserSendSetupDetailsThrottleError, FirebaseServerAuthPasswordResetInvalidCodeError, FirebaseServerAuthPasswordResetNoResetConfigError, FirebaseServerAuthPasswordResetSendOnceError, FirebaseServerAuthPasswordResetThrottleError, FirebaseServerAuthService, FirebaseServerAuthUserBadInputError, FirebaseServerAuthUserExistsError, FirebaseServerEnvService, FirebaseServerFirestoreContextModule, FirebaseServerFirestoreModule, FirebaseServerStorageContextModule, FirebaseServerStorageModule, FirebaseServerStorageService, GlobalRoutePrefixConfig, MAX_MODEL_ACCESS_MULTI_READ_KEYS, MODEL_API_NEST_APPLICATION_CONTEXT, ModelApiCallModelDispatchService, ModelApiController, ModelApiDispatchConfig, ModelApiGetService, NO_RUN_NAME_SPECIFIED_FOR_SCHEDULED_FUNCTION_DEVELOPMENT_FUNCTION_CODE, NoContentFirebaseServerUserPasswordResetService, NoSetupContentFirebaseServerNewUserService, ON_CALL_MODEL_ANALYTICS_HANDLER, ON_CALL_MODEL_ANALYTICS_SERVICE, OnCallModelAnalyticsService, PHONE_NUMBER_ALREADY_EXISTS_ERROR_CODE, SkipAppCheck, UNKNOWN_SCHEDULED_FUNCTION_DEVELOPMENT_FUNCTION_NAME_CODE, UNKNOWN_SCHEDULED_FUNCTION_DEVELOPMENT_FUNCTION_TYPE_CODE, _onCallWithCallTypeFunction, aggregateCrudModelApiDetails, aggregateModelApiDetails, aggregateSpecifierApiDetails, alreadyExistsError, appAnalyticsModuleMetadata, appFirestoreModuleMetadata, assertContextHasAuth, assertDocumentExists, assertHasRolesInRequest, assertHasSignedTosInRequest, assertIsAdminInRequest, assertIsAdminOrTargetUserInRequestData, assertIsContextWithAuthData, assertModelApiOidcScope, assertRequestRequiresAuthForFunction, assertSnapshotData, assertSnapshotDataWithKey, authServicePasswordResetInvalidCodeError, authServicePasswordResetNoConfigError, authServicePasswordResetSendOnceError, authServicePasswordResetThrottleError, badRequestError, blockingFunctionHandlerWithNestContextFactory, buildNestServerRootModule, callWithAnalytics, catchAndThrowPasswordResetServerErrors, cloudEventHandlerWithNestContextFactory, collectionRefForPath, createModelUnknownModelTypeError, decodeFirebaseServerUserPasswordResetOobCode, defaultFirebaseServerActionsTransformFactoryLogErrorFunction, defaultProvideFirebaseServerStorageServiceSimple, deleteModelUnknownModelTypeError, developmentUnknownSpecifierError, docRefForPath, documentModelNotAvailableError, encodeFirebaseServerUserPasswordResetOobCode, executeOnCallQuery, firebaseAuthTokenFromDecodedIdToken, firebaseServerActionsContext, firebaseServerActionsTransformContext, firebaseServerActionsTransformFactory, firebaseServerAppTokenProvider, firebaseServerAuthModuleMetadata, firebaseServerDevFunctions, firebaseServerEnvTokenProvider, firebaseServerEnvTokenProviders, firebaseServerErrorInfo, firebaseServerErrorInfoCodePair, firebaseServerErrorInfoServerErrorCodePair, firebaseServerErrorInfoServerErrorPair, firebaseServerFirestoreContextModuleMetadata, 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, invokeModelUnknownModelTypeError, isActualSpecifier, isAdminInRequest, isAdminOrTargetUserInRequestData, isContextWithAuthData, isFirebaseError, isFirebaseHttpsError, isOnCallCrudModelApiDetails, isOnCallHandlerApiDetails, isOnCallModelTypeApiDetails, isOnCallSpecifierApiDetails, makeBlockingFunctionWithHandler, makeOnScheduleHandlerWithNestApplicationRequest, makeScheduledFunctionDevelopmentFunction, modelAccessReadErrorFromUseMultipleModelsFailure, modelApiModuleMetadata, modelNotAvailableError, nestAppHasDevelopmentSchedulerEnabled, nestAppIsProductionEnvironment, nestFirebaseDoesNotExistError, nestFirebaseForbiddenPermissionError, nestServerInstance, noRunNameSpecifiedForScheduledFunctionDevelopmentFunction, noopFirebaseServerAnalyticsServiceListener, noopOnCallModelAnalyticsService, notFoundError, oidcScopesFromModelApiAuth, onCallAnalyticsEmitterInstance, onCallCreateModel, onCallDeleteModel, onCallDevelopmentFunction, onCallHandlerWithNestApplicationFactory, onCallHandlerWithNestContextFactory, onCallInvokeModel, onCallModel, onCallModelMissingCallTypeError, onCallModelUnknownCallTypeError, onCallQueryModel, onCallReadModel, onCallSpecifierHandler, onCallUpdateModel, onScheduleHandlerWithNestApplicationFactory, onScheduleHandlerWithNestContextFactory, optionalAuthContext, optionalFirestoreEncryptedField, permissionDeniedError, phoneNumberAlreadyExistsError, preconditionConflictError, provideAppFirestoreCollections, provideFirebaseServerAuthService, provideFirebaseServerStorageService, queryModelBadCursorError, queryModelUnknownModelTypeError, readApiDetails, readModelUnknownModelTypeError, resolveAdminOnlyValue, resolveAnalyticsFromApiDetails, resolveRequiredScopeFromApiDetails, setNestContextOnRequest, setNestContextOnScheduleRequest, taskQueueFunctionHandlerWithNestContextFactory, unauthenticatedContextHasNoAuthData, unauthenticatedContextHasNoUidError, unauthenticatedError, unavailableError, unavailableOrDeactivatedFunctionError, unknownModelCrudFunctionSpecifierError, unknownScheduledFunctionDevelopmentFunctionName, unknownScheduledFunctionDevelopmentFunctionType, updateModelUnknownModelTypeError, userContextFromUid, verifyAppCheckInRequest, withApiDetails };

package/mailgun/package.json

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

package/mcp/index.cjs.js

@@ -4,12 +4,12 @@ var common = require('@nestjs/common');
 var node_fs = require('node:fs');
 var mcp_js = require('@modelcontextprotocol/sdk/server/mcp.js');
 var types_js = require('@modelcontextprotocol/sdk/types.js');
+var firebase = require('@dereekb/firebase');
 var oidc = require('@dereekb/firebase-server/oidc');
 var util = require('@dereekb/util');
 var firebaseServer = require('@dereekb/firebase-server');
 var node_util = require('node:util');
 var model = require('@dereekb/model');
-var firebase = require('@dereekb/firebase');
 var streamableHttp_js = require('@modelcontextprotocol/sdk/server/streamableHttp.js');
 
 function _class_call_check$5(instance, Constructor) {
@@ -167,6 +167,22 @@ function _define_property$9(obj, key, value) {
      * fills with a short justification for the call. The value is forwarded to analytics and stripped
      * from the dispatched handler body. See {@link McpReasonParameterConfig}.
      */ _define_property$9(this, "reasonParameter", void 0);
+    /**
+     * Default OIDC scope group term required on EVERY `callModel` op, mirrored into MCP tool-list
+     * visibility, unless a finer term overrides it (a per-function `requiredScope`, then a
+     * {@link McpModuleConfig.modelRequiredScopes} entry). Threaded into the same
+     * `resolveEffectiveOidcScopeTerms` composition the server-side model-api scope gate
+     * (`assertModelApiOidcScope`) uses, so a tool is advertised only when the caller could actually invoke it.
+     *
+     * Set this to the SAME value passed to `ModelApiDispatchConfig.defaultRequiredScope` to
+     * keep tool visibility and enforcement in lockstep.
+     */ _define_property$9(this, "defaultRequiredScope", void 0);
+    /**
+     * Per-model OIDC scope group-term overrides, keyed by {@link FirestoreModelType}, mirrored into MCP
+     * tool-list visibility. Set this to the SAME value passed to
+     * `ModelApiDispatchConfig.modelRequiredScopes` so per-model / verb-keyed restrictions that
+     * confine a subset client apply identically to the advertised tool list.
+     */ _define_property$9(this, "modelRequiredScopes", void 0);
 };
 /**
  * NestJS injection token for the optional {@link McpAuthRoleReader} provider.
@@ -1400,6 +1416,8 @@ function _unsupported_iterable_to_array$9(o, minLen) {
     var seenNames = new Set();
     var manifest = context === null || context === void 0 ? void 0 : context.manifest;
     var naming = context === null || context === void 0 ? void 0 : context.naming;
+    var defaultRequiredScope = context === null || context === void 0 ? void 0 : context.defaultRequiredScope;
+    var modelRequiredScopes = context === null || context === void 0 ? void 0 : context.modelRequiredScopes;
     var candidates = planMcpToolCandidates(apiDetails, naming);
     var clashCounts = countVisibleAutoNameClashes(candidates);
     var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
@@ -1411,6 +1429,8 @@ function _unsupported_iterable_to_array$9(o, minLen) {
                 clashCounts: clashCounts,
                 options: options,
                 manifest: manifest,
+                defaultRequiredScope: defaultRequiredScope,
+                modelRequiredScopes: modelRequiredScopes,
                 seenNames: seenNames,
                 outTools: tools,
                 outNeverVisibleTools: neverVisibleTools,
@@ -1582,7 +1602,7 @@ function _unsupported_iterable_to_array$9(o, minLen) {
  */ function buildToolFromCandidate(context) {
     var _clashCounts_get, _ref;
     var _handlerDetails_mcp, _handlerDetails_mcp1;
-    var candidate = context.candidate, clashCounts = context.clashCounts, options = context.options, manifest = context.manifest, seenNames = context.seenNames, outTools = context.outTools, outNeverVisibleTools = context.outNeverVisibleTools, outSkipped = context.outSkipped, outWarnings = context.outWarnings;
+    var candidate = context.candidate, clashCounts = context.clashCounts, options = context.options, manifest = context.manifest, defaultRequiredScope = context.defaultRequiredScope, modelRequiredScopes = context.modelRequiredScopes, seenNames = context.seenNames, outTools = context.outTools, outNeverVisibleTools = context.outNeverVisibleTools, outSkipped = context.outSkipped, outWarnings = context.outWarnings;
     var modelType = candidate.modelType, callType = candidate.callType, handlerDetails = candidate.handlerDetails, specifier = candidate.specifier, dispatch = candidate.dispatch, modelSegment = candidate.modelSegment, overrideName = candidate.overrideName, baseName = candidate.baseName, classified = candidate.classified, isVisible = candidate.isVisible;
     // A visible auto-named tool whose preferred name is produced by more than one visible tool is
     // re-derived with the abbreviated call type so both survive on the wire. Overrides and hidden tools
@@ -1632,13 +1652,18 @@ function _unsupported_iterable_to_array$9(o, minLen) {
             });
         }
     }
-    // Additive scope set: the per-verb call-type scope (model.<call>) plus any per-function scope
-    // declared via withApiDetails({ requiredScope }). Nullish entries drop out, so a non-CRUD call
-    // type with no per-function scope yields an empty set (no scope gate).
-    var requiredScopes = util.filterMaybeArrayValues([
-        resolveRequiredScope(callType),
-        handlerDetails.requiredScope
-    ]);
+    // AND-of-ORs scope terms: the per-verb call-type scope (model.<call>) plus the effective group term,
+    // resolved by the same precedence the server model-api scope gate uses (per-function requiredScope > per-model
+    // requirement > module default) via the shared resolveEffectiveOidcScopeTerms — so tool visibility
+    // tracks callability. Empty when no term applies (a non-CRUD call type with no per-function/model/
+    // default term → no scope gate).
+    var requiredScopeTerms = firebase.resolveEffectiveOidcScopeTerms({
+        perVerbScope: resolveRequiredScope(callType),
+        requiredScope: handlerDetails.requiredScope,
+        modelRequirement: modelRequiredScopes === null || modelRequiredScopes === void 0 ? void 0 : modelRequiredScopes[modelType],
+        call: callType,
+        defaultRequiredScope: defaultRequiredScope
+    });
     var effectiveReadOnly = resolveEffectiveReadOnly((_handlerDetails_mcp = handlerDetails.mcp) === null || _handlerDetails_mcp === void 0 ? void 0 : _handlerDetails_mcp.readOnly, callType);
     var annotations = resolveMcpToolAnnotations(effectiveReadOnly);
     var description = applyWriteMarker(baseDescription, annotations);
@@ -1647,20 +1672,20 @@ function _unsupported_iterable_to_array$9(o, minLen) {
         filterMetadata = {
             visibilityKind: 'declarative',
             rule: classified.rule,
-            requiredScopes: requiredScopes,
+            requiredScopeTerms: requiredScopeTerms,
             effectiveReadOnly: effectiveReadOnly
         };
     } else if (classified.visibilityKind === 'dynamic') {
         filterMetadata = {
             visibilityKind: 'dynamic',
             visibilityFn: classified.visibilityFn,
-            requiredScopes: requiredScopes,
+            requiredScopeTerms: requiredScopeTerms,
             effectiveReadOnly: effectiveReadOnly
         };
     } else {
         filterMetadata = {
             visibilityKind: classified.visibilityKind,
-            requiredScopes: requiredScopes,
+            requiredScopeTerms: requiredScopeTerms,
             effectiveReadOnly: effectiveReadOnly
         };
     }
@@ -6163,7 +6188,9 @@ var McpServerFactoryService_1;
                     } else {
                         result = generateMcpToolDefinitions(apiDetails, undefined, {
                             manifest: manifest,
-                            naming: this._resolveToolNamingOptions()
+                            naming: this._resolveToolNamingOptions(),
+                            defaultRequiredScope: this.mcpConfig.defaultRequiredScope,
+                            modelRequiredScopes: this.mcpConfig.modelRequiredScopes
                         });
                     }
                     this._cachedTools = result;
@@ -6632,7 +6659,7 @@ var McpServerFactoryService_1;
      * Synthesizes the same `{ auth: { token } }` shape that `getOidcScopesFromRequest`
      * expects post-dispatch, so the upstream helper stays the single source of scope parsing.
      * Returns `undefined` for non-OIDC callers (no `oidcValidatedToken.scope`) — the filter
-     * loop treats that as "skip scope enforcement", matching `oidcCallModelScopePreAssert`.
+     * loop treats that as "skip scope enforcement", matching the model-api scope gate (`assertModelApiOidcScope`).
      *
      * @param ctx - The per-request context carrying the validated auth payload.
      * @returns The set of granted OIDC scopes, or `undefined` when scope enforcement should be skipped.
@@ -6676,9 +6703,7 @@ var McpServerFactoryService_1;
                     for(var _iterator = tools[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true){
                         var tool = _step.value;
                         var filterMetadata = tool.filterMetadata;
-                        if (scopes != null && filterMetadata.requiredScopes != null && !filterMetadata.requiredScopes.every(function(scope) {
-                            return scopes.has(scope);
-                        })) {
+                        if (scopes != null && filterMetadata.requiredScopeTerms != null && !firebase.oidcScopeTermsSatisfied(filterMetadata.requiredScopeTerms, scopes)) {
                             continue;
                         }
                         if (readOnlyMode && filterMetadata.effectiveReadOnly !== true) {