@dereekb/firebase-server 13.28.0 → 13.29.0

package/package.json

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

package/src/lib/nest/model/api.details.d.ts

@@ -1,5 +1,5 @@
 import { type AuthRole, type Maybe, type PromiseOrValue } from '@dereekb/util';
-import { type OnCallFunctionType, type OnCallTypedModelParams, type FirestoreModelType, type ModelFirebaseCrudFunctionSpecifier } from '@dereekb/firebase';
+import { type OnCallFunctionType, type OnCallTypedModelParams, type FirestoreModelType, type ModelFirebaseCrudFunctionSpecifier, type OidcScope } from '@dereekb/firebase';
 import { type FirebaseServerAuthData } from '../controller/auth.context.server';
 import { type OnCallModelFunctionAnalyticsDetails } from './analytics.details';
 /**
@@ -302,6 +302,16 @@ export interface OnCallModelFunctionApiDetails<R = unknown, M = unknown> {
      * When provided, the dispatch chain will call lifecycle hooks around handler execution.
      */
     readonly analytics?: OnCallModelFunctionAnalyticsDetails;
+    /**
+     * Optional per-function OIDC scope an OIDC-authenticated caller must additionally hold to
+     * invoke this handler, on top of the per-verb `model.<call>` scope.
+     *
+     * Composes additively with the CRUD-verb scope enforced by `oidcCallModelScopePreAssert`: an
+     * OIDC caller still needs `model.<call>` AND this scope. Non-OIDC callers (Firebase ID tokens)
+     * bypass scope enforcement entirely and are unaffected. Also folded into the MCP tool-list
+     * visibility filter, so a tool the caller lacks this scope for is neither listed nor callable.
+     */
+    readonly requiredScope?: OidcScope;
 }
 /**
  * Ref interface for objects (functions) that carry handler-level _apiDetails.
@@ -564,6 +574,20 @@ export declare function getModelApiDetails(callModelFn: Maybe<OnCallApiDetailsRe
  * @returns The analytics details for the resolved handler, or undefined.
  */
 export declare function resolveAnalyticsFromApiDetails(apiDetails: OnCallModelApiDetails, call: OnCallFunctionType, modelType: FirestoreModelType, specifier?: ModelFirebaseCrudFunctionSpecifier): Maybe<OnCallModelFunctionAnalyticsDetails>;
+/**
+ * Resolves the leaf-level per-function required OIDC scope from the aggregated _apiDetails tree.
+ *
+ * Walks: call -> modelType -> specifier (if specifier-level), then reads the `requiredScope`
+ * field from the handler-level {@link OnCallModelFunctionApiDetails}. Mirrors
+ * {@link resolveAnalyticsFromApiDetails}.
+ *
+ * @param apiDetails - The top-level aggregated API details.
+ * @param call - The CRUD operation type to look up.
+ * @param modelType - The Firestore model type to look up.
+ * @param specifier - Optional specifier key for variant handlers.
+ * @returns The per-function required scope for the resolved handler, or undefined.
+ */
+export declare function resolveRequiredScopeFromApiDetails(apiDetails: OnCallModelApiDetails, call: OnCallFunctionType, modelType: FirestoreModelType, specifier?: ModelFirebaseCrudFunctionSpecifier): Maybe<OidcScope>;
 /**
  * @deprecated Use {@link OnCallModelTypeApiDetails} instead.
  */

package/src/lib/nest/model/crud.assert.function.d.ts

@@ -1,6 +1,6 @@
 import { type Maybe } from '@dereekb/util';
 import { type NestContextCallableRequest } from '../function/nest';
-import { type OnCallFunctionType, type FirestoreModelType } from '@dereekb/firebase';
+import { type OnCallFunctionType, type FirestoreModelType, type OidcScope } from '@dereekb/firebase';
 /**
  * Discriminator for the category of CRUD operation being asserted.
  *
@@ -34,6 +34,14 @@ export interface AssertModelCrudRequestFunctionContext<N, I = unknown> {
      * The optional sub-operation specifier (e.g., 'username', 'fromUpload').
      */
     readonly specifier: Maybe<string>;
+    /**
+     * The per-function required OIDC scope declared via `withApiDetails({ requiredScope })`, when present.
+     *
+     * Resolved from the handler's `_apiDetails` at dispatch and handed to the pre-assert so
+     * `oidcCallModelScopePreAssert` can require it additively alongside the per-verb `model.<call>`
+     * scope. `undefined` when the handler declares no extra scope.
+     */
+    readonly requiredScope?: Maybe<OidcScope>;
 }
 /**
  * Pre-assertion hook invoked before a model CRUD handler executes.

package/test/index.cjs.js

@@ -4922,18 +4922,24 @@ function _ts_generator$1(thisArg, body) {
 }
 /**
  * Resolves the scopes string from config, or falls back to all registered scopes
- * from the provider config — excluding any `adminOnlyScopes`.
+ * from the provider config — excluding any `adminOnlyScopes` or provider-profile-gated scopes.
  *
  * Admin-only scopes (e.g. `token.service`) are dropped from the default "all scopes" request because
  * the provider hard-rejects them for non-admin users, and this default flow logs in an arbitrary
  * (often non-admin) user. Tests that need an admin-only scope pass it explicitly via `config.scopes`.
  *
+ * Provider-profile-gated scopes (e.g. `lms`, `reports`) are dropped for the same reason: they are
+ * unlocked only for a client an admin has assigned the corresponding profile to, and this flow creates
+ * a fresh client with no profiles — so the consent unlock gate hard-rejects them (finishing the
+ * interaction with `access_denied` and no `code`). Tests that need a gated scope create a client with
+ * the profile and pass the scope explicitly via `config.scopes`.
+ *
  * @param nestApp - Initialized NestJS application used to resolve {@link OidcAccountService} when no scopes override is given.
  * @param config - Optional flow config; when `config.scopes` is set, it is returned verbatim.
  * @returns The space-separated scope string to pass to the `/oidc/auth` endpoint.
  */ function resolveScopes(nestApp, config) {
     return _async_to_generator$1(function() {
-        var result, _providerConfig_adminOnlyScopes, accountService, providerConfig, adminOnlyScopes;
+        var result, _providerConfig_adminOnlyScopes, _providerConfig_providerProfiles, accountService, providerConfig, adminOnlyScopes, profileGatedScopes;
         return _ts_generator$1(this, function(_state) {
             if (config === null || config === void 0 ? void 0 : config.scopes) {
                 result = config.scopes;
@@ -4941,8 +4947,9 @@ function _ts_generator$1(thisArg, body) {
                 accountService = nestApp.get(oidc.OidcAccountService);
                 providerConfig = accountService.providerConfig;
                 adminOnlyScopes = new Set((_providerConfig_adminOnlyScopes = providerConfig.adminOnlyScopes) !== null && _providerConfig_adminOnlyScopes !== void 0 ? _providerConfig_adminOnlyScopes : []);
+                profileGatedScopes = firebase.scopesForOidcProviderProfiles((_providerConfig_providerProfiles = providerConfig.providerProfiles) !== null && _providerConfig_providerProfiles !== void 0 ? _providerConfig_providerProfiles : []);
                 result = Object.keys(providerConfig.claims).filter(function(scope) {
-                    return !adminOnlyScopes.has(scope);
+                    return !adminOnlyScopes.has(scope) && !profileGatedScopes.has(scope);
                 }).join(' ');
             }
             return [

package/test/index.esm.js

@@ -1,7 +1,7 @@
 import { randomEmailFactory, randomPhoneNumberFactory, mapGetter, incrementingNumberFactory, asGetter, getValueFromGetter, cachedGetter, asArray, mapObjectMap, unixDateTimeSecondsNumberForNow } from '@dereekb/util';
 import { useTestContextFixture, AbstractChildTestContextFixture, testContextBuilder, AbstractTestContextFixture, useTestFunctionFixture, useTestFunctionMapFixture, ExpectedErrorOfSpecificTypeError } from '@dereekb/util/test';
 import { decode } from 'jsonwebtoken';
-import { flatFirestoreModelKey, twoWayFlatFirestoreModelKey, firestoreContextFactory, firebaseStorageContextFactory } from '@dereekb/firebase';
+import { flatFirestoreModelKey, twoWayFlatFirestoreModelKey, firestoreContextFactory, firebaseStorageContextFactory, scopesForOidcProviderProfiles } from '@dereekb/firebase';
 import admin from 'firebase-admin';
 import functions from 'firebase-functions-test';
 import { makeTestingFirestoreDrivers, TestFirestoreInstance, TestFirestoreContextFixture, makeTestingFirebaseStorageDrivers, TestFirebaseStorageInstance, TestFirebaseStorageContextFixture, mockItemFirestoreCollection, testWithMockItemCollectionFixture, testWithMockItemStorageFixture } from '@dereekb/firebase/test';
@@ -4921,18 +4921,24 @@ function _ts_generator$1(thisArg, body) {
 }
 /**
  * Resolves the scopes string from config, or falls back to all registered scopes
- * from the provider config — excluding any `adminOnlyScopes`.
+ * from the provider config — excluding any `adminOnlyScopes` or provider-profile-gated scopes.
  *
  * Admin-only scopes (e.g. `token.service`) are dropped from the default "all scopes" request because
  * the provider hard-rejects them for non-admin users, and this default flow logs in an arbitrary
  * (often non-admin) user. Tests that need an admin-only scope pass it explicitly via `config.scopes`.
  *
+ * Provider-profile-gated scopes (e.g. `lms`, `reports`) are dropped for the same reason: they are
+ * unlocked only for a client an admin has assigned the corresponding profile to, and this flow creates
+ * a fresh client with no profiles — so the consent unlock gate hard-rejects them (finishing the
+ * interaction with `access_denied` and no `code`). Tests that need a gated scope create a client with
+ * the profile and pass the scope explicitly via `config.scopes`.
+ *
  * @param nestApp - Initialized NestJS application used to resolve {@link OidcAccountService} when no scopes override is given.
  * @param config - Optional flow config; when `config.scopes` is set, it is returned verbatim.
  * @returns The space-separated scope string to pass to the `/oidc/auth` endpoint.
  */ function resolveScopes(nestApp, config) {
     return _async_to_generator$1(function() {
-        var result, _providerConfig_adminOnlyScopes, accountService, providerConfig, adminOnlyScopes;
+        var result, _providerConfig_adminOnlyScopes, _providerConfig_providerProfiles, accountService, providerConfig, adminOnlyScopes, profileGatedScopes;
         return _ts_generator$1(this, function(_state) {
             if (config === null || config === void 0 ? void 0 : config.scopes) {
                 result = config.scopes;
@@ -4940,8 +4946,9 @@ function _ts_generator$1(thisArg, body) {
                 accountService = nestApp.get(OidcAccountService);
                 providerConfig = accountService.providerConfig;
                 adminOnlyScopes = new Set((_providerConfig_adminOnlyScopes = providerConfig.adminOnlyScopes) !== null && _providerConfig_adminOnlyScopes !== void 0 ? _providerConfig_adminOnlyScopes : []);
+                profileGatedScopes = scopesForOidcProviderProfiles((_providerConfig_providerProfiles = providerConfig.providerProfiles) !== null && _providerConfig_providerProfiles !== void 0 ? _providerConfig_providerProfiles : []);
                 result = Object.keys(providerConfig.claims).filter(function(scope) {
-                    return !adminOnlyScopes.has(scope);
+                    return !adminOnlyScopes.has(scope) && !profileGatedScopes.has(scope);
                 }).join(' ');
             }
             return [

package/test/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/firebase-server/test",
-  "version": "13.28.0",
+  "version": "13.29.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.28.0",
-    "@dereekb/date": "13.28.0",
-    "@dereekb/firebase": "13.28.0",
-    "@dereekb/firebase-server": "13.28.0",
-    "@dereekb/firebase-server/oidc": "13.28.0",
-    "@dereekb/model": "13.28.0",
-    "@dereekb/nestjs": "13.28.0",
-    "@dereekb/rxjs": "13.28.0",
-    "@dereekb/util": "13.28.0",
+    "@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",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.19.0",
     "@nestjs/common": "^11.1.19",
@@ -23,7 +23,7 @@
     "supertest": "^7.2.2"
   },
   "devDependencies": {
-    "@dereekb/nestjs": "13.28.0"
+    "@dereekb/nestjs": "13.29.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/test/src/lib/oidc/oidc.test.flow.d.ts

@@ -1,5 +1,5 @@
 import { type INestApplication } from '@nestjs/common';
-import type { OidcTokenEndpointAuthMethod } from '@dereekb/firebase';
+import { type OidcTokenEndpointAuthMethod } from '@dereekb/firebase';
 import { OidcClientService } from '@dereekb/firebase-server/oidc';
 /**
  * Configuration for {@link performFullOAuthFlow}.

package/twilio/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@dereekb/firebase-server/twilio",
-  "version": "13.28.0",
+  "version": "13.29.0",
   "peerDependencies": {
-    "@dereekb/date": "13.28.0",
-    "@dereekb/firebase": "13.28.0",
-    "@dereekb/firebase-server": "13.28.0",
-    "@dereekb/model": "13.28.0",
-    "@dereekb/nestjs": "13.28.0",
-    "@dereekb/rxjs": "13.28.0",
-    "@dereekb/util": "13.28.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"
   },
   "exports": {
     "./package.json": "./package.json",

package/zoho/package.json

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