@dereekb/firebase-server 13.29.0 → 13.30.0

package/mcp/index.esm.js

@@ -2,12 +2,12 @@ import { Injectable, Inject, Optional, Logger, Post, Req, Res, Controller, Get }
 import { existsSync, readFileSync } from 'node:fs';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { callModelOidcScopeForCallType, resolveEffectiveOidcScopeTerms, inferKeyFromTwoWayFlatFirestoreModelKey, oidcScopeTermsSatisfied } from '@dereekb/firebase';
 import { getOidcScopesFromRequest, OidcProviderConfigService } from '@dereekb/firebase-server/oidc';
-import { filterMaybeArrayValues, makeValuesGroupMap, IMPERSONATION_URL_QUERY_PARAM, performAsyncTasks, authRolesSetHasRoles } from '@dereekb/util';
+import { makeValuesGroupMap, IMPERSONATION_URL_QUERY_PARAM, performAsyncTasks, authRolesSetHasRoles } from '@dereekb/util';
 import { ModelApiCallModelDispatchService, ModelApiGetService, FirebaseServerStorageService, FirebaseServerEnvService, FirebaseServerAnalyticsService } from '@dereekb/firebase-server';
 import { inspect } from 'node:util';
 import { arktypeToJsonSchemaForExport } from '@dereekb/model';
-import { callModelOidcScopeForCallType, inferKeyFromTwoWayFlatFirestoreModelKey } from '@dereekb/firebase';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 
 function _class_call_check$5(instance, Constructor) {
@@ -165,6 +165,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.
@@ -1398,6 +1414,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;
@@ -1409,6 +1427,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,
@@ -1580,7 +1600,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
@@ -1630,13 +1650,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 = 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 = 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);
@@ -1645,20 +1670,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
         };
     }
@@ -6161,7 +6186,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;
@@ -6630,7 +6657,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.
@@ -6674,9 +6701,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 && !oidcScopeTermsSatisfied(filterMetadata.requiredScopeTerms, scopes)) {
                             continue;
                         }
                         if (readOnlyMode && filterMetadata.effectiveReadOnly !== true) {

package/mcp/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@dereekb/firebase-server/mcp",
-  "version": "13.29.0",
+  "version": "13.30.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.29.0",
-    "@dereekb/date": "13.29.0",
-    "@dereekb/firebase": "13.29.0",
-    "@dereekb/firebase-server": "13.29.0",
-    "@dereekb/firebase-server/oidc": "13.29.0",
-    "@dereekb/model": "13.29.0",
-    "@dereekb/nestjs": "13.29.0",
-    "@dereekb/rxjs": "13.29.0",
-    "@dereekb/util": "13.29.0",
-    "@dereekb/zoho": "13.29.0",
+    "@dereekb/analytics": "13.30.0",
+    "@dereekb/date": "13.30.0",
+    "@dereekb/firebase": "13.30.0",
+    "@dereekb/firebase-server": "13.30.0",
+    "@dereekb/firebase-server/oidc": "13.30.0",
+    "@dereekb/model": "13.30.0",
+    "@dereekb/nestjs": "13.30.0",
+    "@dereekb/rxjs": "13.30.0",
+    "@dereekb/util": "13.30.0",
+    "@dereekb/zoho": "13.30.0",
     "@modelcontextprotocol/sdk": "1.29.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/core": "^11.1.19",

package/mcp/src/lib/mcp.config.d.ts

@@ -1,5 +1,5 @@
 import { type AuthClaims, type AuthRoleSet } from '@dereekb/util';
-import { type OidcScope } from '@dereekb/firebase';
+import { type FirestoreModelType, type OidcModelScopeRequirement, type OidcScope, type OidcScopeTerm } from '@dereekb/firebase';
 /**
  * Default path the MCP Streamable HTTP transport is mounted at.
  *
@@ -200,6 +200,24 @@ export declare abstract class McpModuleConfig {
      * from the dispatched handler body. See {@link McpReasonParameterConfig}.
      */
     readonly reasonParameter?: McpReasonParameterConfig | boolean;
+    /**
+     * 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.
+     */
+    readonly defaultRequiredScope?: OidcScopeTerm;
+    /**
+     * 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.
+     */
+    readonly modelRequiredScopes?: Record<FirestoreModelType, OidcModelScopeRequirement>;
 }
 /**
  * Signature for the optional role reader the MCP module uses when evaluating

package/mcp/src/lib/service/mcp.server.factory.d.ts

@@ -152,7 +152,7 @@ export declare class McpServerFactoryService {
      * 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.

package/mcp/src/lib/service/mcp.tool-generator.d.ts

@@ -1,5 +1,5 @@
 import { type Maybe } from '@dereekb/util';
-import { type KnownOnCallFunctionType } from '@dereekb/firebase';
+import { type FirestoreModelType, type KnownOnCallFunctionType, type OidcModelScopeRequirement, type OidcScopeTerm } from '@dereekb/firebase';
 import { type ModelApiDetailsResult, type OnCallModelFunctionApiDetails, type FirebaseServerAuthData, type McpToolDetailsBuilder, type McpVisibilityRule } from '@dereekb/firebase-server';
 import { type Request } from 'express';
 import { type CallToolResult, type ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
@@ -452,6 +452,17 @@ export interface GenerateMcpToolDefinitionsContext {
      * Per-model name segment overrides (e.g. collection prefixes).
      */
     readonly naming?: McpToolGenerationNamingOptions;
+    /**
+     * Default OIDC scope group term required on every op unless a finer term overrides it. Mirrors the
+     * model-api layer's `ModelApiDispatchConfig.defaultRequiredScope` so a tool is advertised only when
+     * the caller could invoke it.
+     */
+    readonly defaultRequiredScope?: OidcScopeTerm;
+    /**
+     * Per-model OIDC scope group-term overrides, keyed by {@link FirestoreModelType}. Mirrors the model-api
+     * layer's `ModelApiDispatchConfig.modelRequiredScopes` so per-model / verb-keyed restrictions apply to tool visibility.
+     */
+    readonly modelRequiredScopes?: Record<FirestoreModelType, OidcModelScopeRequirement>;
 }
 /**
  * Generates MCP tool definitions from a model-first API details tree.

package/mcp/src/lib/service/mcp.visibility.d.ts

@@ -1,5 +1,5 @@
 import { type Maybe } from '@dereekb/util';
-import { type CallModelOidcScope, type OidcScope } from '@dereekb/firebase';
+import { type CallModelOidcScope, type OidcScopeTerm } from '@dereekb/firebase';
 import { type McpToolVisibility, type McpVisibilityContext, type McpVisibilityRule } from '@dereekb/firebase-server';
 import { type ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
 /**
@@ -41,12 +41,15 @@ export interface ClassifiedMcpToolVisibilityDynamic {
 export type McpToolFilterMetadata = McpToolFilterMetadataAlways | McpToolFilterMetadataNever | McpToolFilterMetadataDeclarative | McpToolFilterMetadataDynamic;
 interface McpToolFilterMetadataBase {
     /**
-     * OIDC scopes required to invoke this tool (AND-semantics — the caller must hold every entry).
-     * Precomputed from the dispatch call type's per-verb scope (`model.<call>`) plus any per-function
-     * scope declared via `withApiDetails({ requiredScope })`. Empty when no scope is enforced (a
-     * non-CRUD call type with no per-function scope); apps gate custom verbs via their own preAssert.
+     * OIDC scope TERMS required to invoke this tool, evaluated AND-of-ORs — the caller must satisfy
+     * EVERY term, and an array term (OR-group) is satisfied by holding ANY member. Checked with the
+     * shared `oidcScopeTermsSatisfied` so tool-list visibility matches the server-side `callModel` gate
+     * exactly. Precomputed from the dispatch call type's per-verb scope (`model.<call>`) plus the
+     * effective group term (per-function `requiredScope` > per-model requirement > module default).
+     * Empty when no scope is enforced (a non-CRUD call type with no per-function/model/default term);
+     * apps gate custom verbs via their own preAssert.
      */
-    readonly requiredScopes?: readonly OidcScope[];
+    readonly requiredScopeTerms?: readonly OidcScopeTerm[];
     /**
      * Effective read-only classification used by the module-level `readOnly` filter.
      *

package/model/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@dereekb/firebase-server/model",
-  "version": "13.29.0",
+  "version": "13.30.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.29.0",
-    "@dereekb/date": "13.29.0",
-    "@dereekb/firebase": "13.29.0",
-    "@dereekb/firebase-server": "13.29.0",
-    "@dereekb/model": "13.29.0",
-    "@dereekb/nestjs": "13.29.0",
-    "@dereekb/rxjs": "13.29.0",
-    "@dereekb/util": "13.29.0",
+    "@dereekb/analytics": "13.30.0",
+    "@dereekb/date": "13.30.0",
+    "@dereekb/firebase": "13.30.0",
+    "@dereekb/firebase-server": "13.30.0",
+    "@dereekb/model": "13.30.0",
+    "@dereekb/nestjs": "13.30.0",
+    "@dereekb/rxjs": "13.30.0",
+    "@dereekb/util": "13.30.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "archiver": "^7.0.1",

package/oidc/index.cjs.js

@@ -5395,7 +5395,7 @@ function _unsupported_iterable_to_array$2(o, minLen) {
  * `request.auth.token.scope` for OIDC callers and is `undefined` for non-OIDC
  * (regular Firebase ID-token) callers.
  *
- * Returning `undefined` for non-OIDC callers lets callers (e.g. `oidcCallModelScopePreAssert`)
+ * Returning `undefined` for non-OIDC callers lets consumers (e.g. the MCP tool-visibility filter)
  * skip scope enforcement instead of falsely treating the missing claim as "no scopes granted".
  *
  * The parameter is intentionally typed as `unknown` because `DecodedIdToken` (Firebase
@@ -5407,10 +5407,7 @@ function _unsupported_iterable_to_array$2(o, minLen) {
  */ function getOidcScopesFromRequest(request) {
     var _request_auth_token, _request_auth;
     var scope = request === null || request === void 0 ? void 0 : (_request_auth = request.auth) === null || _request_auth === void 0 ? void 0 : (_request_auth_token = _request_auth.token) === null || _request_auth_token === void 0 ? void 0 : _request_auth_token.scope;
-    var result = typeof scope === 'string' ? new Set(scope.split(' ').filter(function(value) {
-        return value.length > 0;
-    })) : undefined;
-    return result;
+    return firebase.oidcScopesFromScopeClaim(scope);
 }
 
 function asyncGeneratorStep$3(gen, resolve, reject, _next, _throw, key, arg) {
@@ -7781,53 +7778,6 @@ function _unsupported_iterable_to_array(o, minLen) {
     };
 }
 
-/**
- * Builds a {@link AssertModelCrudRequestFunction} that rejects callModel requests
- * lacking the required OIDC scope(s) for the call.
- *
- * Enforcement is additive: an OIDC caller must hold BOTH the per-verb scope mapped
- * from the call type (`model.<call>`) AND any per-function scope a handler declared
- * via `withApiDetails({ requiredScope })` — surfaced on `context.requiredScope`.
- *
- * Bypasses the check (no-op) when the request is not OIDC-authenticated — i.e.
- * when {@link getOidcScopesFromRequest} returns `undefined` because there is no
- * `auth.token.scope` claim on the request. Regular Firebase ID-token callers are
- * unaffected and continue to be gated by auth roles.
- *
- * Bypasses the check for custom (non-CRUD) call types that declare no per-function
- * scope, so app-specific verbs remain unrestricted unless an app wires its own
- * assertion or declares a `requiredScope`.
- *
- * Wire as the `preAssert` of {@link onCallModel}.
- *
- * @returns The pre-assertion function ready to plug into `OnCallModelConfig.preAssert`.
- */ function oidcCallModelScopePreAssert() {
-    var fn = function fn(context) {
-        var requiredScopes = util.filterMaybeArrayValues([
-            firebase.callModelOidcScopeForCallType(context.call),
-            context.requiredScope
-        ]);
-        // No requirement (custom verb + no per-function scope) short-circuits without reading scopes.
-        // A non-OIDC caller yields `undefined` scopes below and bypasses just like the per-verb check.
-        var scopes = requiredScopes.length === 0 ? undefined : getOidcScopesFromRequest(context.request);
-        var missingScopes = scopes == null ? [] : requiredScopes.filter(function(scope) {
-            return !scopes.has(scope);
-        });
-        if (missingScopes.length > 0) {
-            throw firebaseServer.forbiddenError({
-                status: 403,
-                code: firebase.CALL_MODEL_MISSING_OIDC_SCOPE_ERROR_CODE,
-                message: "Missing required OIDC scope for callModel: ".concat(missingScopes.join(', ')),
-                data: {
-                    requiredScopes: missingScopes,
-                    call: context.call
-                }
-            });
-        }
-    };
-    return fn;
-}
-
 exports.DBX_FIREBASE_SERVER_OIDC_PROVIDER_PROFILES_CLIENT_METADATA = DBX_FIREBASE_SERVER_OIDC_PROVIDER_PROFILES_CLIENT_METADATA;
 exports.DEFAULT_APP_OAUTH_CONSENT_PATH_PART = DEFAULT_APP_OAUTH_CONSENT_PATH_PART;
 exports.DEFAULT_APP_OAUTH_INTERACTION_PATH = DEFAULT_APP_OAUTH_INTERACTION_PATH;
@@ -7890,7 +7840,6 @@ exports.jwksKeyIdentity = jwksKeyIdentity;
 exports.jwksKeysWithStatusQuery = jwksKeysWithStatusQuery;
 exports.nonRetiredJwksKeysQuery = nonRetiredJwksKeysQuery;
 exports.noopOidcAnalyticsService = noopOidcAnalyticsService;
-exports.oidcCallModelScopePreAssert = oidcCallModelScopePreAssert;
 exports.oidcClientProviderProfileScopes = oidcClientProviderProfileScopes;
 exports.oidcCorsOriginDelegate = oidcCorsOriginDelegate;
 exports.oidcFirestoreCollectionsFactory = oidcFirestoreCollectionsFactory;

package/oidc/index.esm.js

@@ -1,10 +1,10 @@
 import { createParamDecorator, Injectable, Inject, Optional, Logger, UnauthorizedException, Get, Param, Req, Res, Post, HttpCode, HttpStatus, Body, Controller, HttpException, All } from '@nestjs/common';
 import { errors } from 'oidc-provider';
-import { SECONDS_IN_MINUTE, SECONDS_IN_DAY, cachedGetter, unixDateTimeSecondsNumberToDate, unixDateTimeSecondsNumberForNow, selectiveFieldEncryptor, filterUndefinedValues, websiteUrlFromPaths, firstValue, hasHttpPrefix, filterMaybeArrayValues } from '@dereekb/util';
+import { SECONDS_IN_MINUTE, SECONDS_IN_DAY, cachedGetter, unixDateTimeSecondsNumberToDate, unixDateTimeSecondsNumberForNow, selectiveFieldEncryptor, filterUndefinedValues, websiteUrlFromPaths, firstValue, hasHttpPrefix } from '@dereekb/util';
 import { generateKeyPairSync, randomBytes } from 'node:crypto';
 import { resolveEncryptionKey, encryptValue, decryptValue, createAesStringEncryptionProvider, isValidAES256GCMEncryptionSecret } from '@dereekb/nestjs';
-import { where, iterateFirestoreDocumentSnapshotPairs, firestoreModelIdentity, snapshotConverterFunctions, optionalFirestoreDate, firestoreDate, firestoreEnum, firestorePassThroughField, AbstractFirestoreDocument, createOidcClientParamsType, deleteOidcClientParamsType, deleteOidcTokenParamsType, rotateOidcClientSecretParamsType, updateOidcClientParamsType, firestoreModelKey, oidcEntryIdentity, PUBLIC_PKCE_TOKEN_ENDPOINT_AUTH_METHOD, OIDC_ENTRY_CLIENT_TYPE, oidcEntriesByUserCodeQuery, oidcEntriesByUidQuery, oidcEntriesByGrantIdQuery, oidcProviderProfilesForKeys, requiredScopesForOidcProviderProfiles, scopesForOidcProviderProfiles, oidcEntryFirestoreCollection, callModelOidcScopeForCallType, CALL_MODEL_MISSING_OIDC_SCOPE_ERROR_CODE } from '@dereekb/firebase';
-import { firestoreEncryptedField, firebaseServerActionsContext, FirebaseServerEnvService, FirebaseServerAnalyticsService, FIREBASE_FIRESTORE_CONTEXT_TOKEN, FirebaseServerFirestoreContextModule, forbiddenError } from '@dereekb/firebase-server';
+import { where, iterateFirestoreDocumentSnapshotPairs, firestoreModelIdentity, snapshotConverterFunctions, optionalFirestoreDate, firestoreDate, firestoreEnum, firestorePassThroughField, AbstractFirestoreDocument, createOidcClientParamsType, deleteOidcClientParamsType, deleteOidcTokenParamsType, rotateOidcClientSecretParamsType, updateOidcClientParamsType, firestoreModelKey, oidcEntryIdentity, PUBLIC_PKCE_TOKEN_ENDPOINT_AUTH_METHOD, OIDC_ENTRY_CLIENT_TYPE, oidcEntriesByUserCodeQuery, oidcEntriesByUidQuery, oidcEntriesByGrantIdQuery, oidcProviderProfilesForKeys, requiredScopesForOidcProviderProfiles, scopesForOidcProviderProfiles, oidcScopesFromScopeClaim, oidcEntryFirestoreCollection } from '@dereekb/firebase';
+import { firestoreEncryptedField, firebaseServerActionsContext, FirebaseServerEnvService, FirebaseServerAnalyticsService, FIREBASE_FIRESTORE_CONTEXT_TOKEN, FirebaseServerFirestoreContextModule } from '@dereekb/firebase-server';
 import { nanoid } from 'nanoid';
 import { safeToJsDate } from '@dereekb/date';
 import { makeUrlSearchParamsString } from '@dereekb/util/fetch';
@@ -5393,7 +5393,7 @@ function _unsupported_iterable_to_array$2(o, minLen) {
  * `request.auth.token.scope` for OIDC callers and is `undefined` for non-OIDC
  * (regular Firebase ID-token) callers.
  *
- * Returning `undefined` for non-OIDC callers lets callers (e.g. `oidcCallModelScopePreAssert`)
+ * Returning `undefined` for non-OIDC callers lets consumers (e.g. the MCP tool-visibility filter)
  * skip scope enforcement instead of falsely treating the missing claim as "no scopes granted".
  *
  * The parameter is intentionally typed as `unknown` because `DecodedIdToken` (Firebase
@@ -5405,10 +5405,7 @@ function _unsupported_iterable_to_array$2(o, minLen) {
  */ function getOidcScopesFromRequest(request) {
     var _request_auth_token, _request_auth;
     var scope = request === null || request === void 0 ? void 0 : (_request_auth = request.auth) === null || _request_auth === void 0 ? void 0 : (_request_auth_token = _request_auth.token) === null || _request_auth_token === void 0 ? void 0 : _request_auth_token.scope;
-    var result = typeof scope === 'string' ? new Set(scope.split(' ').filter(function(value) {
-        return value.length > 0;
-    })) : undefined;
-    return result;
+    return oidcScopesFromScopeClaim(scope);
 }
 
 function asyncGeneratorStep$3(gen, resolve, reject, _next, _throw, key, arg) {
@@ -7779,51 +7776,4 @@ function _unsupported_iterable_to_array(o, minLen) {
     };
 }
 
-/**
- * Builds a {@link AssertModelCrudRequestFunction} that rejects callModel requests
- * lacking the required OIDC scope(s) for the call.
- *
- * Enforcement is additive: an OIDC caller must hold BOTH the per-verb scope mapped
- * from the call type (`model.<call>`) AND any per-function scope a handler declared
- * via `withApiDetails({ requiredScope })` — surfaced on `context.requiredScope`.
- *
- * Bypasses the check (no-op) when the request is not OIDC-authenticated — i.e.
- * when {@link getOidcScopesFromRequest} returns `undefined` because there is no
- * `auth.token.scope` claim on the request. Regular Firebase ID-token callers are
- * unaffected and continue to be gated by auth roles.
- *
- * Bypasses the check for custom (non-CRUD) call types that declare no per-function
- * scope, so app-specific verbs remain unrestricted unless an app wires its own
- * assertion or declares a `requiredScope`.
- *
- * Wire as the `preAssert` of {@link onCallModel}.
- *
- * @returns The pre-assertion function ready to plug into `OnCallModelConfig.preAssert`.
- */ function oidcCallModelScopePreAssert() {
-    var fn = function fn(context) {
-        var requiredScopes = filterMaybeArrayValues([
-            callModelOidcScopeForCallType(context.call),
-            context.requiredScope
-        ]);
-        // No requirement (custom verb + no per-function scope) short-circuits without reading scopes.
-        // A non-OIDC caller yields `undefined` scopes below and bypasses just like the per-verb check.
-        var scopes = requiredScopes.length === 0 ? undefined : getOidcScopesFromRequest(context.request);
-        var missingScopes = scopes == null ? [] : requiredScopes.filter(function(scope) {
-            return !scopes.has(scope);
-        });
-        if (missingScopes.length > 0) {
-            throw forbiddenError({
-                status: 403,
-                code: CALL_MODEL_MISSING_OIDC_SCOPE_ERROR_CODE,
-                message: "Missing required OIDC scope for callModel: ".concat(missingScopes.join(', ')),
-                data: {
-                    requiredScopes: missingScopes,
-                    call: context.call
-                }
-            });
-        }
-    };
-    return fn;
-}
-
-export { DBX_FIREBASE_SERVER_OIDC_PROVIDER_PROFILES_CLIENT_METADATA, DEFAULT_APP_OAUTH_CONSENT_PATH_PART, DEFAULT_APP_OAUTH_INTERACTION_PATH, DEFAULT_APP_OAUTH_LOGIN_PATH_PART, DEFAULT_MAX_ADMIN_LOGIN_DURATION_SECONDS, DEFAULT_MAX_NONADMIN_LOGIN_DURATION_SECONDS, DEFAULT_MAX_REQUESTED_LOGIN_DURATION_SECONDS, DEFAULT_MAX_SERVICE_TOKEN_LOGIN_DURATION_SECONDS, DEFAULT_MIN_REQUESTED_LOGIN_DURATION_SECONDS, DEFAULT_OIDC_ANALYTICS_EVENT_NAMES, DEFAULT_OIDC_ANALYTICS_EVENT_NAME_PREFIX, DEFAULT_OIDC_CODE_CHALLENGE_METHODS, DEFAULT_OIDC_ID_TOKEN_SIGNING_ALG_VALUES, DEFAULT_OIDC_ISSUER_PATH, DEFAULT_OIDC_ROUTES, DEFAULT_OIDC_SUBJECT_TYPES, DEFAULT_OIDC_TOKEN_ENDPOINT_AUTH_METHODS, DEFAULT_OIDC_TOKEN_LIFETIMES, DEFAULT_ROTATED_KEY_MAX_AGE, FIREBASE_SERVER_OIDC_ANALYTICS_CONFIG, FIREBASE_SERVER_OIDC_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE, FirebaseServerOidcAnalyticsService, GRANTABLE_MODEL_NAMES, JwksFirestoreCollections, JwksKeyDocument, JwksService, JwksServiceConfig, JwksServiceStorageConfig, OIDC_ANALYTICS_SERVICE, OIDC_ENCRYPTED_PAYLOAD_FIELDS, OIDC_JSON_RENDER_ERROR_FUNCTION, OIDC_JWKS_ENCRYPTION_SECRET_ENV_KEY, OidcAccountService, OidcAccountServiceDelegate, OidcAccountServiceUserContext, OidcAnalyticsService, OidcAuth, OidcAuthBearerTokenMiddleware, OidcAuthMiddlewareConfig, OidcClientService, OidcEncryptionService, OidcInteractionController, OidcInteractionService, OidcModelServerActions, OidcModuleConfig, OidcProviderConfigService, OidcProviderController, OidcServerFirestoreCollections, OidcService, OidcWellKnownController, activeJwksKeysQuery, allOidcScopesStringForProviderConfig, appOidcAnalyticsModuleMetadata, appOidcModelModuleMetadata, applyOidcAuthMiddleware, applyOidcCorsMiddleware, buildBearerChallenge, buildFirebaseServerMcpResourceServer, createAdapterFactory, createOidcClientFactory, deleteOidcClientFactory, deleteOidcTokenFactory, deriveResourceMetadataUrlFromEnv, emitOidcAnalyticsEvent, getOidcScopesFromRequest, jwksKeyCollectionReference, jwksKeyConverter, jwksKeyFirestoreCollection, jwksKeyIdentity, jwksKeysWithStatusQuery, nonRetiredJwksKeysQuery, noopOidcAnalyticsService, oidcCallModelScopePreAssert, oidcClientProviderProfileScopes, oidcCorsOriginDelegate, oidcFirestoreCollectionsFactory, oidcModelServerActions, oidcModelServerActionsFactory, oidcModuleConfigFactory, oidcModuleMetadata, resolveEffectiveSubset, rotateOidcClientSecretFactory, rotatedJwksKeysQuery, updateOidcClientFactory };
+export { DBX_FIREBASE_SERVER_OIDC_PROVIDER_PROFILES_CLIENT_METADATA, DEFAULT_APP_OAUTH_CONSENT_PATH_PART, DEFAULT_APP_OAUTH_INTERACTION_PATH, DEFAULT_APP_OAUTH_LOGIN_PATH_PART, DEFAULT_MAX_ADMIN_LOGIN_DURATION_SECONDS, DEFAULT_MAX_NONADMIN_LOGIN_DURATION_SECONDS, DEFAULT_MAX_REQUESTED_LOGIN_DURATION_SECONDS, DEFAULT_MAX_SERVICE_TOKEN_LOGIN_DURATION_SECONDS, DEFAULT_MIN_REQUESTED_LOGIN_DURATION_SECONDS, DEFAULT_OIDC_ANALYTICS_EVENT_NAMES, DEFAULT_OIDC_ANALYTICS_EVENT_NAME_PREFIX, DEFAULT_OIDC_CODE_CHALLENGE_METHODS, DEFAULT_OIDC_ID_TOKEN_SIGNING_ALG_VALUES, DEFAULT_OIDC_ISSUER_PATH, DEFAULT_OIDC_ROUTES, DEFAULT_OIDC_SUBJECT_TYPES, DEFAULT_OIDC_TOKEN_ENDPOINT_AUTH_METHODS, DEFAULT_OIDC_TOKEN_LIFETIMES, DEFAULT_ROTATED_KEY_MAX_AGE, FIREBASE_SERVER_OIDC_ANALYTICS_CONFIG, FIREBASE_SERVER_OIDC_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE, FirebaseServerOidcAnalyticsService, GRANTABLE_MODEL_NAMES, JwksFirestoreCollections, JwksKeyDocument, JwksService, JwksServiceConfig, JwksServiceStorageConfig, OIDC_ANALYTICS_SERVICE, OIDC_ENCRYPTED_PAYLOAD_FIELDS, OIDC_JSON_RENDER_ERROR_FUNCTION, OIDC_JWKS_ENCRYPTION_SECRET_ENV_KEY, OidcAccountService, OidcAccountServiceDelegate, OidcAccountServiceUserContext, OidcAnalyticsService, OidcAuth, OidcAuthBearerTokenMiddleware, OidcAuthMiddlewareConfig, OidcClientService, OidcEncryptionService, OidcInteractionController, OidcInteractionService, OidcModelServerActions, OidcModuleConfig, OidcProviderConfigService, OidcProviderController, OidcServerFirestoreCollections, OidcService, OidcWellKnownController, activeJwksKeysQuery, allOidcScopesStringForProviderConfig, appOidcAnalyticsModuleMetadata, appOidcModelModuleMetadata, applyOidcAuthMiddleware, applyOidcCorsMiddleware, buildBearerChallenge, buildFirebaseServerMcpResourceServer, createAdapterFactory, createOidcClientFactory, deleteOidcClientFactory, deleteOidcTokenFactory, deriveResourceMetadataUrlFromEnv, emitOidcAnalyticsEvent, getOidcScopesFromRequest, jwksKeyCollectionReference, jwksKeyConverter, jwksKeyFirestoreCollection, jwksKeyIdentity, jwksKeysWithStatusQuery, nonRetiredJwksKeysQuery, noopOidcAnalyticsService, oidcClientProviderProfileScopes, oidcCorsOriginDelegate, oidcFirestoreCollectionsFactory, oidcModelServerActions, oidcModelServerActionsFactory, oidcModuleConfigFactory, oidcModuleMetadata, resolveEffectiveSubset, rotateOidcClientSecretFactory, rotatedJwksKeysQuery, updateOidcClientFactory };

package/oidc/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/firebase-server/oidc",
-  "version": "13.29.0",
+  "version": "13.30.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.29.0",
-    "@dereekb/date": "13.29.0",
-    "@dereekb/firebase": "13.29.0",
-    "@dereekb/firebase-server": "13.29.0",
-    "@dereekb/model": "13.29.0",
-    "@dereekb/nestjs": "13.29.0",
-    "@dereekb/rxjs": "13.29.0",
-    "@dereekb/util": "13.29.0",
-    "@dereekb/zoho": "13.29.0",
+    "@dereekb/analytics": "13.30.0",
+    "@dereekb/date": "13.30.0",
+    "@dereekb/firebase": "13.30.0",
+    "@dereekb/firebase-server": "13.30.0",
+    "@dereekb/model": "13.30.0",
+    "@dereekb/nestjs": "13.30.0",
+    "@dereekb/rxjs": "13.30.0",
+    "@dereekb/util": "13.30.0",
+    "@dereekb/zoho": "13.30.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "express": "^5.2.1",

package/oidc/src/lib/index.d.ts

@@ -4,5 +4,4 @@ export * from './oidc.config';
 export * from './controller';
 export * from './oidc.module';
 export * from './profile';
-export * from './scope';
 export * from './service';

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

@@ -33,7 +33,7 @@ export type OidcAuthenticatedRequest = FirebaseServerAuthenticatedRequest<OidcAu
  * `request.auth.token.scope` for OIDC callers and is `undefined` for non-OIDC
  * (regular Firebase ID-token) callers.
  *
- * Returning `undefined` for non-OIDC callers lets callers (e.g. `oidcCallModelScopePreAssert`)
+ * Returning `undefined` for non-OIDC callers lets consumers (e.g. the MCP tool-visibility filter)
  * skip scope enforcement instead of falsely treating the missing claim as "no scopes granted".
  *
  * The parameter is intentionally typed as `unknown` because `DecodedIdToken` (Firebase

package/package.json

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

package/src/lib/nest/controller/model/index.d.ts

@@ -1,3 +1,4 @@
+export * from './model.api.scope';
 export * from './model.api.get.service';
 export * from './model.api.dispatch';
 export * from './model.api.controller';

package/src/lib/nest/controller/model/model.api.dispatch.d.ts

@@ -1,11 +1,12 @@
 import { type Maybe } from '@dereekb/util';
-import { type OnCallTypedModelParams } from '@dereekb/firebase';
+import { type FirestoreModelType, type OidcModelScopeRequirement, type OidcScopeTerm, type OnCallTypedModelParams } from '@dereekb/firebase';
 import { type INestApplicationContext } from '@nestjs/common';
 import { type Request } from 'express';
 import { type OnCallWithNestContext } from '../../function/call';
 import { type OnCallApiDetailsRef, type ModelApiDetailsResult } from '../../model/api.details';
 import { type MakeNestContext } from '../../nest.provider';
 import { type FirebaseServerAuthData } from '../auth.context.server';
+import { type ModelApiOidcScopeConfig } from './model.api.scope';
 /**
  * The combined type of the function returned by onCallModel() with _apiDetails attached.
  */
@@ -27,7 +28,7 @@ export type OnCallModelFnWithApiDetails = OnCallWithNestContext<unknown, OnCallT
  * }
  * ```
  */
-export declare abstract class ModelApiDispatchConfig {
+export declare abstract class ModelApiDispatchConfig implements ModelApiOidcScopeConfig {
     /**
      * The onCallModel() return value with _apiDetails attached.
      */
@@ -36,6 +37,17 @@ export declare abstract class ModelApiDispatchConfig {
      * Factory to create typed nest context from INestApplicationContext.
      */
     readonly makeNestContext: MakeNestContext<unknown>;
+    /**
+     * 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.
+     */
+    readonly defaultRequiredScope?: OidcScopeTerm;
+    /**
+     * 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`.
+     */
+    readonly modelRequiredScopes?: Record<FirestoreModelType, OidcModelScopeRequirement>;
 }
 /**
  * Injection token for providing the NestJS application context to the dispatch service.

package/src/lib/nest/controller/model/model.api.get.service.d.ts

@@ -61,8 +61,22 @@ export declare function modelAccessReadErrorFromUseMultipleModelsFailure(entry:
  */
 export declare class ModelApiGetService {
     private readonly _nestContext;
+    private readonly _defaultRequiredScope;
+    private readonly _modelRequiredScopes;
     private _identityByModelType;
     constructor(config: ModelApiDispatchConfig, nestApplication: INestApplicationContext);
+    /**
+     * 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).
+     */
+    private _assertReadScope;
     /**
      * Returns the registered {@link FirestoreModelIdentity} for the given `modelType` string, or
      * `undefined` when no model of that type is registered.