@dereekb/firebase-server 13.29.0 → 13.31.0

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, oidcProviderProfilesForClient, requiredScopesForOidcProviderProfiles, scopesForOidcProviderProfiles, oidcScopesFromScopeClaim, adminOnlyScopesForOidcProviderProfiles, 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';
@@ -3553,11 +3553,18 @@ OidcProviderConfigService = __decorate([
  * Resolves the unlocked + required scope sets for a client from the provider-profile registry and
  * the profile keys assigned to that client.
  *
+ * A client with NO assigned profiles resolves to the registry's default profiles (those marked
+ * `isDefault`), so a registry declaring no default resolves exactly as it would from the assigned
+ * keys alone.
+ *
+ * This is the single choke point for a client's profile resolution — the consent unlock gate, the
+ * consent required gate, and the `requiredScopes` interaction param all read through it.
+ *
  * @param providerProfiles - The provider-profile registry (from {@link OidcProviderConfig.providerProfiles}).
  * @param clientProfileKeys - The profile keys assigned to the client (its `dbx_provider_profiles`).
  * @returns The unlocked and required scope sets for the client.
  */ function oidcClientProviderProfileScopes(providerProfiles, clientProfileKeys) {
-    var clientProfiles = oidcProviderProfilesForKeys(providerProfiles !== null && providerProfiles !== void 0 ? providerProfiles : [], clientProfileKeys);
+    var clientProfiles = oidcProviderProfilesForClient(providerProfiles !== null && providerProfiles !== void 0 ? providerProfiles : [], clientProfileKeys);
     return {
         unlocked: scopesForOidcProviderProfiles(clientProfiles),
         required: requiredScopesForOidcProviderProfiles(clientProfiles)
@@ -5393,7 +5400,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 +5412,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) {
@@ -6213,7 +6217,7 @@ var OidcInteractionController_1;
      * @throws {HttpException} HTTP 400 when the consent interaction cannot be completed.
      */ function postConsent(uid, body, res) {
                 return _async_to_generator$2(function() {
-                    var startedAt, clientId, accountId, _ref, _prompt_details_missingOIDCScope, _this_accountService_providerConfig_adminOnlyScopes, _ref1, _ref2, _ref3, _prompt_details_missingOIDCClaims, _prompt_details_missingResourceScopes, _this_accountService_delegate_isAdminUser, _this_accountService_delegate, _ref4, redirectTo, interaction, prompt, params, session, missingOIDCScope, existingGrant, _tmp, encounteredOIDCScopes, clientPayload, requestedOIDCScopeSet, adminOnlyScopes, requestsServiceToken, isAdmin, _tmp1, _ref5, redirectTo1, providerProfiles, _oidcClientProviderProfileScopes, clientUnlockedScopes, clientRequiredScopes, profileGatedScopes, disallowedGatedScopes, _ref6, redirectTo2, missingRequiredScopes, _ref7, redirectTo3, requestedRawTtl, clientMaxSessionTtl, expiresInSeconds, grant, _tmp2, _resolveEffectiveSubset, granted, rejected, _iteratorNormalCompletion, _didIteratorError, _iteratorError, _iterator, _step, value, encounteredOIDCClaims, missingOIDCClaims, _resolveEffectiveSubset1, granted1, rejected1, missingResourceScopes, _iteratorNormalCompletion1, _didIteratorError1, _iteratorError1, _iterator1, _step1, _step_value, indicator, scopes, _body_grantedResourceScopes, requestedSubset, encounteredResourceScopes, _resolveEffectiveSubset2, granted2, rejected2, _iteratorNormalCompletion2, _didIteratorError2, _iteratorError2, _iterator2, _step2, value1, grantId, _ref8, redirectTo4, err;
+                    var startedAt, clientId, accountId, _ref, _prompt_details_missingOIDCScope, _this_accountService_providerConfig_adminOnlyScopes, _ref1, _ref2, _ref3, _prompt_details_missingOIDCClaims, _prompt_details_missingResourceScopes, _this_accountService_delegate_isAdminUser, _this_accountService_delegate, _ref4, redirectTo, interaction, prompt, params, session, missingOIDCScope, existingGrant, _tmp, encounteredOIDCScopes, clientPayload, requestedOIDCScopeSet, providerProfiles, configAdminOnlyScopes, adminOnlyScopes, requestedAdminOnlyScopes, requestsServiceToken, isAdmin, _tmp1, _ref5, redirectTo1, _oidcClientProviderProfileScopes, clientUnlockedScopes, clientRequiredScopes, profileGatedScopes, disallowedGatedScopes, _ref6, redirectTo2, missingRequiredScopes, _ref7, redirectTo3, requestedRawTtl, clientMaxSessionTtl, expiresInSeconds, grant, _tmp2, _resolveEffectiveSubset, granted, rejected, _iteratorNormalCompletion, _didIteratorError, _iteratorError, _iterator, _step, value, encounteredOIDCClaims, missingOIDCClaims, _resolveEffectiveSubset1, granted1, rejected1, missingResourceScopes, _iteratorNormalCompletion1, _didIteratorError1, _iteratorError1, _iterator1, _step1, _step_value, indicator, scopes, _body_grantedResourceScopes, requestedSubset, encounteredResourceScopes, _resolveEffectiveSubset2, granted2, rejected2, _iteratorNormalCompletion2, _didIteratorError2, _iteratorError2, _iterator2, _step2, value1, grantId, _ref8, redirectTo4, err;
                     return _ts_generator$2(this, function(_state) {
                         switch(_state.label){
                             case 0:
@@ -6297,11 +6301,20 @@ var OidcInteractionController_1;
                                 clientPayload = _state.sent();
                                 // Admin-only scope gate. The requested OIDC scope set is `missingOIDCScope ∪ encounteredOIDCScopes`
                                 // (a fresh consent has everything in `missing`; a re-consent may carry already-granted scopes in
-                                // `encountered`). If that set intersects the provider's `adminOnlyScopes` and the resolving user is
-                                // not an admin, hard-reject with `access_denied` rather than silently dropping the scope.
+                                // `encountered`). If that set intersects the admin-only scopes — the provider's `adminOnlyScopes`
+                                // unioned with the scopes of every profile marked `adminOnly` — and the resolving user is not an
+                                // admin, hard-reject with `access_denied` rather than silently dropping the scope.
                                 requestedOIDCScopeSet = new Set(_to_consumable_array$1(missingOIDCScope).concat(_to_consumable_array$1(encounteredOIDCScopes)));
-                                adminOnlyScopes = (_this_accountService_providerConfig_adminOnlyScopes = this.accountService.providerConfig.adminOnlyScopes) !== null && _this_accountService_providerConfig_adminOnlyScopes !== void 0 ? _this_accountService_providerConfig_adminOnlyScopes : [];
-                                requestsServiceToken = adminOnlyScopes.some(function(scope) {
+                                providerProfiles = this.accountService.providerConfig.providerProfiles;
+                                configAdminOnlyScopes = (_this_accountService_providerConfig_adminOnlyScopes = this.accountService.providerConfig.adminOnlyScopes) !== null && _this_accountService_providerConfig_adminOnlyScopes !== void 0 ? _this_accountService_providerConfig_adminOnlyScopes : [];
+                                adminOnlyScopes = new Set(_to_consumable_array$1(configAdminOnlyScopes).concat(_to_consumable_array$1(adminOnlyScopesForOidcProviderProfiles(providerProfiles !== null && providerProfiles !== void 0 ? providerProfiles : []))));
+                                requestedAdminOnlyScopes = Array.from(adminOnlyScopes).filter(function(scope) {
+                                    return requestedOIDCScopeSet.has(scope);
+                                });
+                                // Deliberately sourced from the provider config's `adminOnlyScopes` ALONE, unlike the gate above:
+                                // this flag also selects the (highest) service-token TTL tier further down, and a profile marked
+                                // `adminOnly` must gate by admin status WITHOUT widening its grant's lifetime to that tier.
+                                requestsServiceToken = configAdminOnlyScopes.some(function(scope) {
                                     return requestedOIDCScopeSet.has(scope);
                                 });
                                 if (!accountId) return [
@@ -6323,7 +6336,7 @@ var OidcInteractionController_1;
                                 _state.label = 12;
                             case 12:
                                 isAdmin = _tmp1;
-                                if (!(requestsServiceToken && !isAdmin)) return [
+                                if (!(requestedAdminOnlyScopes.length > 0 && !isAdmin)) return [
                                     3,
                                     14
                                 ];
@@ -6331,7 +6344,7 @@ var OidcInteractionController_1;
                                     4,
                                     this.oidcInteractionService.finishInteractionByUid(uid, {
                                         error: 'access_denied',
-                                        error_description: 'token.service is restricted to admins.'
+                                        error_description: "The following scope(s) are restricted to admins: ".concat(requestedAdminOnlyScopes.join(', '), ".")
                                     }, {
                                         mergeWithLastSubmission: true
                                     })
@@ -6343,7 +6356,7 @@ var OidcInteractionController_1;
                                     isSuccessful: false,
                                     uid: accountId,
                                     clientId: clientId,
-                                    serviceToken: true,
+                                    serviceToken: requestsServiceToken,
                                     isAdmin: false,
                                     reason: 'service_token_non_admin',
                                     durationMs: Date.now() - startedAt
@@ -6356,9 +6369,9 @@ var OidcInteractionController_1;
                                 ];
                             case 14:
                                 // Provider-profile scope gate. Any scope referenced by a provider profile is "gated" — available
-                                // only to clients whose assigned profiles unlock it. Independent of the admin-only gate above; a
-                                // scope may be subject to both.
-                                providerProfiles = this.accountService.providerConfig.providerProfiles;
+                                // only to clients whose assigned profiles unlock it (a client with NO assigned profiles resolves
+                                // to the registry's default profiles). Independent of the admin-only gate above; a scope may be
+                                // subject to both.
                                 _oidcClientProviderProfileScopes = oidcClientProviderProfileScopes(providerProfiles, (_ref2 = clientPayload === null || clientPayload === void 0 ? void 0 : clientPayload.dbx_provider_profiles) !== null && _ref2 !== void 0 ? _ref2 : undefined), clientUnlockedScopes = _oidcClientProviderProfileScopes.unlocked, clientRequiredScopes = _oidcClientProviderProfileScopes.required;
                                 profileGatedScopes = scopesForOidcProviderProfiles(providerProfiles !== null && providerProfiles !== void 0 ? providerProfiles : []);
                                 // Unlock gate: reject any requested gated scope this client's profiles do not unlock.
@@ -7779,51 +7792,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.31.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.31.0",
+    "@dereekb/date": "13.31.0",
+    "@dereekb/firebase": "13.31.0",
+    "@dereekb/firebase-server": "13.31.0",
+    "@dereekb/model": "13.31.0",
+    "@dereekb/nestjs": "13.31.0",
+    "@dereekb/rxjs": "13.31.0",
+    "@dereekb/util": "13.31.0",
+    "@dereekb/zoho": "13.31.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/oidc.config.d.ts

@@ -94,6 +94,11 @@ export interface OidcProviderConfig<S extends OidcScope = OidcScope> {
      *
      * Keeps the generic package app-agnostic: apps opt a scope (e.g. `token.service`) into admin-only
      * behavior by listing it here, rather than the package hard-coding any scope name.
+     *
+     * The consent gate applies this list UNIONED with the scopes of every {@link providerProfiles} entry
+     * marked `adminOnly`. Only the scopes listed HERE additionally select the (highest) service-token
+     * login-duration tier — a profile marked `adminOnly` gates by admin status without widening its
+     * grant's lifetime.
      */
     readonly adminOnlyScopes?: readonly string[];
     /**
@@ -111,6 +116,12 @@ export interface OidcProviderConfig<S extends OidcScope = OidcScope> {
      * metadata) unlocks it. A profile scope marked `require: 'required'` is force-required — surfaced
      * as a required scope at consent and hard-rejected if not granted.
      *
+     * A profile marked `isDefault` applies to a client with NO profiles assigned, so an app can make a
+     * coarse, broadly-available scope profile-gated without breaking already-registered clients. The
+     * fallback is exclusive — assigning any other profile does not additionally confer the default's
+     * scopes. A profile marked `adminOnly` has its scopes unioned into {@link adminOnlyScopes} for the
+     * consent gate.
+     *
      * Keeps the generic package app-agnostic: apps declare their profiles statically and list them
      * here, rather than the package hard-coding any profile or scope name. This gate is independent of
      * {@link adminOnlyScopes} (which gates by the resolving user's admin status); a scope may be

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

@@ -22,6 +22,13 @@ export interface OidcClientProviderProfileScopes<S extends OidcScope = OidcScope
  * Resolves the unlocked + required scope sets for a client from the provider-profile registry and
  * the profile keys assigned to that client.
  *
+ * A client with NO assigned profiles resolves to the registry's default profiles (those marked
+ * `isDefault`), so a registry declaring no default resolves exactly as it would from the assigned
+ * keys alone.
+ *
+ * This is the single choke point for a client's profile resolution — the consent unlock gate, the
+ * consent required gate, and the `requiredScopes` interaction param all read through it.
+ *
  * @param providerProfiles - The provider-profile registry (from {@link OidcProviderConfig.providerProfiles}).
  * @param clientProfileKeys - The profile keys assigned to the client (its `dbx_provider_profiles`).
  * @returns The unlocked and required scope sets for the client.

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.31.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.31.0",
+    "@dereekb/date": "13.31.0",
+    "@dereekb/dbx-core": "13.31.0",
+    "@dereekb/firebase": "13.31.0",
+    "@dereekb/model": "13.31.0",
+    "@dereekb/nestjs": "13.31.0",
+    "@dereekb/rxjs": "13.31.0",
+    "@dereekb/util": "13.31.0",
+    "@dereekb/zoho": "13.31.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.

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

@@ -0,0 +1,102 @@
+import { type Maybe } from '@dereekb/util';
+import { type FirestoreModelType, type OidcModelScopeRequirement, type OidcScope, type OidcScopeTerm, type OnCallFunctionType } from '@dereekb/firebase';
+import { type FirebaseServerAuthData } from '../auth.context.server';
+/**
+ * OIDC scope-grouping configuration for the model-api layer, mixed into {@link ModelApiDispatchConfig}
+ * and read by both {@link ModelApiCallModelDispatchService} and {@link ModelApiGetService}.
+ *
+ * This is the model-api-layer home for the callModel group-scope requirements. Providing them here
+ * enforces them uniformly across ALL three `ModelApiController` access patterns — path/direct
+ * dispatch AND the `/get` direct reads — and
+ * (via the MCP server routing through the same services) the MCP surface, without riding the shared
+ * callModel function that also serves the app's first-party Firebase `onCall` path.
+ *
+ * With NEITHER field supplied, enforcement is byte-for-byte the pre-grouping behavior: an OIDC caller
+ * still needs the per-verb `model.<call>` scope (plus any per-function `requiredScope` on dispatch),
+ * and non-OIDC callers bypass entirely.
+ */
+export interface ModelApiOidcScopeConfig {
+    /**
+     * Group term required on EVERY model-api op unless a finer term overrides it (a per-function
+     * `requiredScope`, then a {@link ModelApiOidcScopeConfig.modelRequiredScopes} entry). Lets an app
+     * require e.g. `'hellosubs'` across all models without editing individual handlers. Set this to the
+     * SAME value passed to the MCP `McpModuleConfig.defaultRequiredScope` so tool listing == callability.
+     */
+    readonly defaultRequiredScope?: OidcScopeTerm;
+    /**
+     * Per-model group-term overrides keyed by {@link FirestoreModelType}. The ONLY place a plain `/get`
+     * read (which has no per-function handler) can be scope-gated beyond the per-verb `model.read` scope.
+     * A verb-keyed entry can require different terms per verb (e.g. `lms` reads, `hellosubs` writes). Set
+     * this to the SAME value passed to the MCP `McpModuleConfig.modelRequiredScopes` so tool listing ==
+     * callability.
+     */
+    readonly modelRequiredScopes?: Record<FirestoreModelType, OidcModelScopeRequirement>;
+}
+/**
+ * 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.
+ */
+export declare function oidcScopesFromModelApiAuth(auth: Maybe<FirebaseServerAuthData>): Maybe<Set<OidcScope>>;
+/**
+ * Inputs to {@link assertModelApiOidcScope}.
+ *
+ * Standalone (not extending {@link ModelApiOidcScopeConfig}) because the group fields here receive the
+ * services' stored config values, which are {@link Maybe} (nullable) — matching the shipped
+ * `ResolveEffectiveOidcScopeTermsInput` — whereas the config surface exposes them as plain optionals.
+ */
+export interface AssertModelApiOidcScopeInput {
+    /**
+     * The call verb being enforced (e.g. `create`, `read`). `/get` direct reads pass `'read'`.
+     */
+    readonly call: OnCallFunctionType;
+    /**
+     * The Firestore model type being targeted.
+     */
+    readonly modelType: FirestoreModelType;
+    /**
+     * The per-function `requiredScope` declared via `withApiDetails`, if resolvable (dispatch only — a
+     * plain `/get` read has no per-function handler). The finest (highest-precedence) group term.
+     */
+    readonly requiredScope?: Maybe<OidcScopeTerm>;
+    /**
+     * The module-level default group term (see {@link ModelApiOidcScopeConfig.defaultRequiredScope}).
+     */
+    readonly defaultRequiredScope?: Maybe<OidcScopeTerm>;
+    /**
+     * The per-model group-term overrides (see {@link ModelApiOidcScopeConfig.modelRequiredScopes}).
+     */
+    readonly modelRequiredScopes?: Maybe<Record<FirestoreModelType, OidcModelScopeRequirement>>;
+    /**
+     * The scopes the caller was granted, or `undefined` for a non-OIDC caller (bypasses enforcement).
+     */
+    readonly grantedScopes: Maybe<ReadonlySet<OidcScope>>;
+}
+/**
+ * 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.
+ */
+export declare function assertModelApiOidcScope(input: AssertModelApiOidcScopeInput): void;

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, type OidcScope } from '@dereekb/firebase';
+import { type OnCallFunctionType, type OnCallTypedModelParams, type FirestoreModelType, type ModelFirebaseCrudFunctionSpecifier, type OidcScopeTerm } from '@dereekb/firebase';
 import { type FirebaseServerAuthData } from '../controller/auth.context.server';
 import { type OnCallModelFunctionAnalyticsDetails } from './analytics.details';
 /**
@@ -74,7 +74,7 @@ export interface McpVisibilityContext {
     readonly auth?: FirebaseServerAuthData;
     /**
      * The caller's OIDC scopes, when the request was authenticated with a `scope`-bearing token.
-     * `undefined` for non-OIDC callers — treated the same as `oidcCallModelScopePreAssert` bypass.
+     * `undefined` for non-OIDC callers — treated the same as the model-api scope gate's non-OIDC bypass.
      */
     readonly scopes?: ReadonlySet<string>;
     /**
@@ -303,15 +303,20 @@ export interface OnCallModelFunctionApiDetails<R = unknown, M = unknown> {
      */
     readonly analytics?: OnCallModelFunctionAnalyticsDetails;
     /**
-     * Optional per-function OIDC scope an OIDC-authenticated caller must additionally hold to
+     * Optional per-function OIDC scope TERM 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)
+     * A single scope string requires that exact scope; a `readonly` array is an OR-group the caller
+     * satisfies by holding ANY member (see {@link OidcScopeTerm}). This term is the finest (highest
+     * precedence) source for the effective group requirement — it overrides any model-level or default
+     * requirement configured on the model-api layer (`ModelApiDispatchConfig`).
+     *
+     * Composes with the CRUD-verb scope enforced by the model-api scope gate (`assertModelApiOidcScope`) as AND-of-ORs: an
+     * OIDC caller still needs `model.<call>` AND this term. 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.
+     * visibility filter, so a tool the caller cannot satisfy this term for is neither listed nor callable.
      */
-    readonly requiredScope?: OidcScope;
+    readonly requiredScope?: OidcScopeTerm;
 }
 /**
  * Ref interface for objects (functions) that carry handler-level _apiDetails.
@@ -587,7 +592,7 @@ export declare function resolveAnalyticsFromApiDetails(apiDetails: OnCallModelAp
  * @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>;
+export declare function resolveRequiredScopeFromApiDetails(apiDetails: OnCallModelApiDetails, call: OnCallFunctionType, modelType: FirestoreModelType, specifier?: ModelFirebaseCrudFunctionSpecifier): Maybe<OidcScopeTerm>;
 /**
  * @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, type OidcScope } from '@dereekb/firebase';
+import { type OnCallFunctionType, type FirestoreModelType, type OidcScopeTerm } from '@dereekb/firebase';
 /**
  * Discriminator for the category of CRUD operation being asserted.
  *
@@ -35,13 +35,14 @@ export interface AssertModelCrudRequestFunctionContext<N, I = unknown> {
      */
     readonly specifier: Maybe<string>;
     /**
-     * The per-function required OIDC scope declared via `withApiDetails({ requiredScope })`, when present.
+     * The per-function required OIDC scope TERM 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.
+     * A single scope string, or a `readonly` array as an OR-group (see {@link OidcScopeTerm}). Resolved
+     * from the handler's `_apiDetails` at dispatch so the model-api scope gate (`assertModelApiOidcScope`)
+     * can enforce it as the finest group term (AND-ed with the per-verb `model.<call>` scope).
+     * `undefined` when the handler declares no extra scope.
      */
-    readonly requiredScope?: Maybe<OidcScope>;
+    readonly requiredScope?: Maybe<OidcScopeTerm>;
 }
 /**
  * Pre-assertion hook invoked before a model CRUD handler executes.