@dereekb/firebase-server 13.28.0 → 13.29.0

package/oidc/index.esm.js

@@ -1,9 +1,9 @@
 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 } from '@dereekb/util';
+import { SECONDS_IN_MINUTE, SECONDS_IN_DAY, cachedGetter, unixDateTimeSecondsNumberToDate, unixDateTimeSecondsNumberForNow, selectiveFieldEncryptor, filterUndefinedValues, websiteUrlFromPaths, firstValue, hasHttpPrefix, filterMaybeArrayValues } 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, oidcEntryFirestoreCollection, callModelOidcScopeForCallType, CALL_MODEL_MISSING_OIDC_SCOPE_ERROR_CODE } from '@dereekb/firebase';
+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 { nanoid } from 'nanoid';
 import { safeToJsDate } from '@dereekb/date';
@@ -2429,6 +2429,9 @@ function _ts_generator$7(thisArg, body) {
                                 if (params.dbx_max_session_ttl != null) {
                                     properties.dbx_max_session_ttl = params.dbx_max_session_ttl;
                                 }
+                                if (params.dbx_provider_profiles != null) {
+                                    properties.dbx_provider_profiles = params.dbx_provider_profiles;
+                                }
                                 // Merge any pre-validated metadata (e.g., inline jwks for private_key_jwt in tests)
                                 if (validatedMetadata === null || validatedMetadata === void 0 ? void 0 : validatedMetadata.jwks) {
                                     properties.jwks = validatedMetadata.jwks;
@@ -2486,7 +2489,7 @@ function _ts_generator$7(thisArg, body) {
      * @throws {Error} When the client is not found.
      */ function updateClient(clientId, params) {
                 return _async_to_generator$7(function() {
-                    var provider, ProviderClient, existing, updatedMetadata, _params_logo_uri, _params_client_uri, _params_dbx_max_session_ttl, client;
+                    var provider, ProviderClient, existing, updatedMetadata, _params_logo_uri, _params_client_uri, _params_dbx_max_session_ttl, _params_dbx_provider_profiles, client;
                     return _ts_generator$7(this, function(_state) {
                         switch(_state.label){
                             case 0:
@@ -2518,6 +2521,12 @@ function _ts_generator$7(thisArg, body) {
                                 if (params.dbx_max_session_ttl !== undefined) {
                                     updatedMetadata.dbx_max_session_ttl = (_params_dbx_max_session_ttl = params.dbx_max_session_ttl) !== null && _params_dbx_max_session_ttl !== void 0 ? _params_dbx_max_session_ttl : undefined;
                                 }
+                                // Only overwrite the profile assignment when the field is explicitly provided. An omitted value
+                                // (including one stripped for a non-admin caller) preserves the existing assignment; `null`/`[]`
+                                // clears it. This is what makes the non-admin strip a no-op rather than a wipe.
+                                if (params.dbx_provider_profiles !== undefined) {
+                                    updatedMetadata.dbx_provider_profiles = (_params_dbx_provider_profiles = params.dbx_provider_profiles) !== null && _params_dbx_provider_profiles !== void 0 ? _params_dbx_provider_profiles : undefined;
+                                }
                                 // Mirrors oidc-provider's lib/helpers/add_client.js: re-validates and persists.
                                 return [
                                     4,
@@ -3536,6 +3545,25 @@ OidcProviderConfigService = __decorate([
     __param(2, Inject(FirebaseServerEnvService))
 ], OidcProviderConfigService);
 
+/**
+ * Custom oidc-provider client metadata field holding the {@link OidcProviderProfile} keys assigned
+ * to a client. Registered via `extraClientMetadata` and persisted on the client's `OidcEntry` payload.
+ */ var DBX_FIREBASE_SERVER_OIDC_PROVIDER_PROFILES_CLIENT_METADATA = 'dbx_provider_profiles';
+/**
+ * Resolves the unlocked + required scope sets for a client from the provider-profile registry and
+ * the profile keys assigned to that client.
+ *
+ * @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);
+    return {
+        unlocked: scopesForOidcProviderProfiles(clientProfiles),
+        required: requiredScopesForOidcProviderProfiles(clientProfiles)
+    };
+}
+
 function _array_like_to_array$4(arr, len) {
     if (len == null || len > arr.length) len = arr.length;
     for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
@@ -4040,7 +4068,8 @@ function _ts_generator$5(thisArg, body) {
                                         logo_uri: existing.logo_uri,
                                         client_uri: existing.client_uri,
                                         created_at: existing.created_at,
-                                        dbx_max_session_ttl: existing.dbx_max_session_ttl
+                                        dbx_max_session_ttl: existing.dbx_max_session_ttl,
+                                        dbx_provider_profiles: existing.dbx_provider_profiles
                                     };
                                 }
                                 return [
@@ -4147,7 +4176,8 @@ function _ts_generator$5(thisArg, body) {
                     ],
                     extraClientMetadata: {
                         properties: [
-                            DBX_FIREBASE_SERVER_OIDC_MAX_SESSION_TTL_CLIENT_METADATA
+                            DBX_FIREBASE_SERVER_OIDC_MAX_SESSION_TTL_CLIENT_METADATA,
+                            DBX_FIREBASE_SERVER_OIDC_PROVIDER_PROFILES_CLIENT_METADATA
                         ],
                         validator: function validator(_ctx, key, value) {
                             if (key === DBX_FIREBASE_SERVER_OIDC_MAX_SESSION_TTL_CLIENT_METADATA && value !== undefined && value !== null) {
@@ -4157,6 +4187,22 @@ function _ts_generator$5(thisArg, body) {
                                 if (value > serverMaxSeconds) {
                                     throw new errors.InvalidClientMetadata("".concat(DBX_FIREBASE_SERVER_OIDC_MAX_SESSION_TTL_CLIENT_METADATA, " cannot exceed the server max of ").concat(serverMaxSeconds, " seconds."));
                                 }
+                            } else if (key === DBX_FIREBASE_SERVER_OIDC_PROVIDER_PROFILES_CLIENT_METADATA && value !== undefined && value !== null) {
+                                var _providerConfig_providerProfiles;
+                                if (!Array.isArray(value) || value.some(function(entry) {
+                                    return typeof entry !== 'string';
+                                })) {
+                                    throw new errors.InvalidClientMetadata("".concat(DBX_FIREBASE_SERVER_OIDC_PROVIDER_PROFILES_CLIENT_METADATA, " must be an array of provider profile keys."));
+                                }
+                                var knownProfileKeys = new Set(((_providerConfig_providerProfiles = providerConfig.providerProfiles) !== null && _providerConfig_providerProfiles !== void 0 ? _providerConfig_providerProfiles : []).map(function(profile) {
+                                    return profile.key;
+                                }));
+                                var unknownKey = value.find(function(entry) {
+                                    return !knownProfileKeys.has(entry);
+                                });
+                                if (unknownKey !== undefined) {
+                                    throw new errors.InvalidClientMetadata("".concat(DBX_FIREBASE_SERVER_OIDC_PROVIDER_PROFILES_CLIENT_METADATA, " contains an unknown provider profile key: ").concat(unknownKey, "."));
+                                }
                             }
                         }
                     },
@@ -4184,7 +4230,7 @@ function _ts_generator$5(thisArg, body) {
                     interactions: {
                         url: function url(_ctx, interaction) {
                             return _async_to_generator$5(function() {
-                                var baseUrl, client_id, paramsToEncode, client, scopes, interactionLoginDetails, paramsString;
+                                var baseUrl, client_id, paramsToEncode, client, _client_dbx_provider_profiles, scopes, requestedScopeSet, required, requiredScopes, interactionLoginDetails, paramsString;
                                 return _ts_generator$5(this, function(_state) {
                                     switch(_state.label){
                                         case 0:
@@ -4212,13 +4258,23 @@ function _ts_generator$5(thisArg, body) {
                                             client = _state.sent();
                                             if (client) {
                                                 scopes = interaction.params.scope;
-                                                interactionLoginDetails = {
+                                                // Surface the scopes the client's provider profiles force-require so the consent UI can
+                                                // render them as required. Intersect with the actually-requested scopes so only visible
+                                                // scope rows are flagged.
+                                                requestedScopeSet = new Set(scopes.split(' ').filter(Boolean));
+                                                required = oidcClientProviderProfileScopes(providerConfig.providerProfiles, (_client_dbx_provider_profiles = client.dbx_provider_profiles) !== null && _client_dbx_provider_profiles !== void 0 ? _client_dbx_provider_profiles : undefined).required;
+                                                requiredScopes = Array.from(required).filter(function(scope) {
+                                                    return requestedScopeSet.has(scope);
+                                                });
+                                                interactionLoginDetails = _object_spread$3({
                                                     client_id: client_id,
                                                     client_name: client.client_name,
                                                     client_uri: client.client_uri,
                                                     logo_uri: client.logo_uri,
                                                     scopes: scopes
-                                                };
+                                                }, requiredScopes.length > 0 ? {
+                                                    requiredScopes: requiredScopes.join(' ')
+                                                } : {});
                                                 paramsToEncode = _object_spread$3({}, paramsToEncode, interactionLoginDetails);
                                             }
                                             _state.label = 3;
@@ -6157,7 +6213,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, _prompt_details_missingOIDCClaims, _prompt_details_missingResourceScopes, _this_accountService_delegate_isAdminUser, _this_accountService_delegate, _ref3, redirectTo, interaction, prompt, params, session, missingOIDCScope, existingGrant, _tmp, encounteredOIDCScopes, requestedOIDCScopeSet, adminOnlyScopes, requestsServiceToken, isAdmin, _tmp1, _ref4, redirectTo1, requestedRawTtl, clientPayload, 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, _ref5, redirectTo2, 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, 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;
                     return _ts_generator$2(this, function(_state) {
                         switch(_state.label){
                             case 0:
@@ -6172,9 +6228,9 @@ var OidcInteractionController_1;
                             case 2:
                                 _state.trys.push([
                                     2,
-                                    20,
+                                    24,
                                     ,
-                                    21
+                                    25
                                 ]);
                                 if (!!body.approved) return [
                                     3,
@@ -6190,7 +6246,7 @@ var OidcInteractionController_1;
                                     })
                                 ];
                             case 3:
-                                _ref3 = _state.sent(), redirectTo = _ref3.returnTo;
+                                _ref4 = _state.sent(), redirectTo = _ref4.returnTo;
                                 res.json({
                                     redirectTo: redirectTo
                                 });
@@ -6233,6 +6289,12 @@ var OidcInteractionController_1;
                                 // and re-submits them all. We accept already-encountered values as silent no-ops so a re-consent on a
                                 // client the user has previously authorized doesn't fail validation.
                                 encounteredOIDCScopes = existingGrant ? existingGrant.getOIDCScopeEncountered().split(' ').filter(Boolean) : [];
+                                return [
+                                    4,
+                                    this.oidcService.findClientPayload(clientId)
+                                ];
+                            case 9:
+                                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
@@ -6244,26 +6306,26 @@ var OidcInteractionController_1;
                                 });
                                 if (!accountId) return [
                                     3,
-                                    10
+                                    11
                                 ];
                                 return [
                                     4,
                                     (_ref1 = (_this_accountService_delegate_isAdminUser = (_this_accountService_delegate = this.accountService.delegate).isAdminUser) === null || _this_accountService_delegate_isAdminUser === void 0 ? void 0 : _this_accountService_delegate_isAdminUser.call(_this_accountService_delegate, this.accountService.userContext(accountId).authUserContext)) !== null && _ref1 !== void 0 ? _ref1 : false
                                 ];
-                            case 9:
+                            case 10:
                                 _tmp1 = _state.sent();
                                 return [
                                     3,
-                                    11
+                                    12
                                 ];
-                            case 10:
-                                _tmp1 = false;
-                                _state.label = 11;
                             case 11:
+                                _tmp1 = false;
+                                _state.label = 12;
+                            case 12:
                                 isAdmin = _tmp1;
                                 if (!(requestsServiceToken && !isAdmin)) return [
                                     3,
-                                    13
+                                    14
                                 ];
                                 return [
                                     4,
@@ -6274,8 +6336,8 @@ var OidcInteractionController_1;
                                         mergeWithLastSubmission: true
                                     })
                                 ];
-                            case 12:
-                                _ref4 = _state.sent(), redirectTo1 = _ref4.returnTo;
+                            case 13:
+                                _ref5 = _state.sent(), redirectTo1 = _ref5.returnTo;
                                 emitOidcAnalyticsEvent(this._analytics, {
                                     type: 'consent',
                                     isSuccessful: false,
@@ -6292,20 +6354,89 @@ var OidcInteractionController_1;
                                 return [
                                     2
                                 ];
-                            case 13:
+                            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;
+                                _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.
+                                disallowedGatedScopes = Array.from(requestedOIDCScopeSet).filter(function(scope) {
+                                    return profileGatedScopes.has(scope) && !clientUnlockedScopes.has(scope);
+                                });
+                                if (!(disallowedGatedScopes.length > 0)) return [
+                                    3,
+                                    16
+                                ];
+                                return [
+                                    4,
+                                    this.oidcInteractionService.finishInteractionByUid(uid, {
+                                        error: 'access_denied',
+                                        error_description: "The following scope(s) are not available to this client: ".concat(disallowedGatedScopes.join(', '), ".")
+                                    }, {
+                                        mergeWithLastSubmission: true
+                                    })
+                                ];
+                            case 15:
+                                _ref6 = _state.sent(), redirectTo2 = _ref6.returnTo;
+                                emitOidcAnalyticsEvent(this._analytics, {
+                                    type: 'consent',
+                                    isSuccessful: false,
+                                    uid: accountId,
+                                    clientId: clientId,
+                                    reason: 'scope_not_unlocked_for_client',
+                                    durationMs: Date.now() - startedAt
+                                }, this._logger);
+                                res.json({
+                                    redirectTo: redirectTo2
+                                });
+                                return [
+                                    2
+                                ];
+                            case 16:
+                                // Required gate: a scope a client's profiles force-require (`require: 'required'`) must be present
+                                // in the request. Reject when the client did not request a required scope.
+                                missingRequiredScopes = Array.from(clientRequiredScopes).filter(function(scope) {
+                                    return !requestedOIDCScopeSet.has(scope);
+                                });
+                                if (!(missingRequiredScopes.length > 0)) return [
+                                    3,
+                                    18
+                                ];
+                                return [
+                                    4,
+                                    this.oidcInteractionService.finishInteractionByUid(uid, {
+                                        error: 'access_denied',
+                                        error_description: "This client must request the required scope(s): ".concat(missingRequiredScopes.join(', '), ".")
+                                    }, {
+                                        mergeWithLastSubmission: true
+                                    })
+                                ];
+                            case 17:
+                                _ref7 = _state.sent(), redirectTo3 = _ref7.returnTo;
+                                emitOidcAnalyticsEvent(this._analytics, {
+                                    type: 'consent',
+                                    isSuccessful: false,
+                                    uid: accountId,
+                                    clientId: clientId,
+                                    reason: 'required_scope_missing',
+                                    durationMs: Date.now() - startedAt
+                                }, this._logger);
+                                res.json({
+                                    redirectTo: redirectTo3
+                                });
+                                return [
+                                    2
+                                ];
+                            case 18:
                                 // Resolve the requested login duration up-front. The configured Grant TTL function (in
                                 // OidcService.buildProviderConfiguration) only fires when oidc-provider's koa middleware
                                 // drives `grant.save()`, so its `ctx.oidc.params` lookup of `dbx_session_ttl` returns
                                 // undefined when the consent submit runs in this controller. We pre-set `expiresIn` on
                                 // newly-created grants so they persist with the correct (tiered) TTL.
                                 requestedRawTtl = params[DBX_FIREBASE_SERVER_OIDC_SESSION_TTL_PARAM];
-                                return [
-                                    4,
-                                    this.oidcService.findClientPayload(clientId)
-                                ];
-                            case 14:
-                                clientPayload = _state.sent();
-                                clientMaxSessionTtl = (_ref2 = clientPayload === null || clientPayload === void 0 ? void 0 : clientPayload.dbx_max_session_ttl) !== null && _ref2 !== void 0 ? _ref2 : undefined;
+                                clientMaxSessionTtl = (_ref3 = clientPayload === null || clientPayload === void 0 ? void 0 : clientPayload.dbx_max_session_ttl) !== null && _ref3 !== void 0 ? _ref3 : undefined;
                                 expiresInSeconds = this.oidcService.resolveLoginDurationForGrant(requestedRawTtl, {
                                     dbx_max_session_ttl: clientMaxSessionTtl
                                 }, {
@@ -6314,28 +6445,30 @@ var OidcInteractionController_1;
                                 });
                                 if (!(existingGrant !== null && existingGrant !== void 0)) return [
                                     3,
-                                    15
+                                    19
                                 ];
                                 _tmp2 = existingGrant;
                                 return [
                                     3,
-                                    17
+                                    21
                                 ];
-                            case 15:
+                            case 19:
                                 return [
                                     4,
                                     this.oidcInteractionService.findOrCreateGrant(interaction.grantId, accountId, clientId, expiresInSeconds)
                                 ];
-                            case 16:
+                            case 20:
                                 _tmp2 = _state.sent();
-                                _state.label = 17;
-                            case 17:
+                                _state.label = 21;
+                            case 21:
                                 grant = _tmp2;
                                 if (missingOIDCScope.length > 0) {
+                                    // Force-grant the client's required profile scopes (in addition to `openid`) so they cannot be
+                                    // dropped at consent — the required gate above already guarantees they were requested.
                                     _resolveEffectiveSubset = resolveEffectiveSubset({
                                         missing: missingOIDCScope,
                                         requestedSubset: body.grantedOIDCScopes,
-                                        alwaysGranted: ALWAYS_GRANTED_OIDC_SCOPES,
+                                        alwaysGranted: _to_consumable_array$1(ALWAYS_GRANTED_OIDC_SCOPES).concat(_to_consumable_array$1(clientRequiredScopes)),
                                         alreadyEncountered: encounteredOIDCScopes
                                     }), granted = _resolveEffectiveSubset.granted, rejected = _resolveEffectiveSubset.rejected;
                                     if (granted.length > 0) {
@@ -6432,7 +6565,7 @@ var OidcInteractionController_1;
                                     4,
                                     grant.save()
                                 ];
-                            case 18:
+                            case 22:
                                 grantId = _state.sent();
                                 return [
                                     4,
@@ -6444,8 +6577,8 @@ var OidcInteractionController_1;
                                         mergeWithLastSubmission: true
                                     })
                                 ];
-                            case 19:
-                                _ref5 = _state.sent(), redirectTo2 = _ref5.returnTo;
+                            case 23:
+                                _ref8 = _state.sent(), redirectTo4 = _ref8.returnTo;
                                 emitOidcAnalyticsEvent(this._analytics, {
                                     type: 'consent',
                                     isSuccessful: true,
@@ -6457,13 +6590,13 @@ var OidcInteractionController_1;
                                     durationMs: Date.now() - startedAt
                                 }, this._logger);
                                 res.json({
-                                    redirectTo: redirectTo2
+                                    redirectTo: redirectTo4
                                 });
                                 return [
                                     3,
-                                    21
+                                    25
                                 ];
-                            case 20:
+                            case 24:
                                 err = _state.sent();
                                 emitOidcAnalyticsEvent(this._analytics, {
                                     type: 'consent',
@@ -6478,7 +6611,7 @@ var OidcInteractionController_1;
                                     throw err;
                                 }
                                 throw new HttpException('Consent interaction failed', HttpStatus.BAD_REQUEST);
-                            case 21:
+                            case 25:
                                 return [
                                     2
                                 ];
@@ -7648,31 +7781,43 @@ function _unsupported_iterable_to_array(o, minLen) {
 
 /**
  * Builds a {@link AssertModelCrudRequestFunction} that rejects callModel requests
- * lacking the OIDC scope mapped from the call type.
+ * 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 so app-specific verbs
- * remain unrestricted unless an app wires its own assertion.
+ * 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 requiredScope = callModelOidcScopeForCallType(context.call);
-        var scopes = requiredScope == null ? undefined : getOidcScopesFromRequest(context.request);
-        var isMissingScope = requiredScope != null && scopes != null && !scopes.has(requiredScope);
-        if (isMissingScope) {
+        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(requiredScope),
+                message: "Missing required OIDC scope for callModel: ".concat(missingScopes.join(', ')),
                 data: {
-                    requiredScope: requiredScope,
+                    requiredScopes: missingScopes,
                     call: context.call
                 }
             });
@@ -7681,4 +7826,4 @@ function _unsupported_iterable_to_array(o, minLen) {
     return fn;
 }
 
-export { 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, 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, oidcCallModelScopePreAssert, 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.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/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/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",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "express": "^5.2.1",

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

@@ -3,5 +3,6 @@ export * from './model';
 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

@@ -1,6 +1,6 @@
 import type { Configuration } from 'oidc-provider';
 import { type WebsitePath, type SlashPath, type Seconds } from '@dereekb/util';
-import { type OidcScope, type OidcTokenEndpointAuthMethod } from '@dereekb/firebase';
+import { type OidcProviderProfile, type OidcScope, type OidcTokenEndpointAuthMethod } from '@dereekb/firebase';
 import { type JwksServiceConfig } from './service/oidc.jwks.service';
 import { type JwksKeyConverterConfig } from './model';
 /**
@@ -104,6 +104,19 @@ export interface OidcProviderConfig<S extends OidcScope = OidcScope> {
      * All other grants keep oidc-provider's default rotation behavior.
      */
     readonly nonRotatingScopes?: readonly string[];
+    /**
+     * Named provider profiles that unlock (and optionally force-require) scopes for the OIDC clients
+     * they are assigned to. Any scope referenced by a profile is treated as restricted: a client may
+     * only obtain it when one of its assigned profiles (persisted as `dbx_provider_profiles` client
+     * 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.
+     *
+     * 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
+     * subject to both.
+     */
+    readonly providerProfiles?: readonly OidcProviderProfile<S>[];
 }
 /**
  * Returns the space-delimited list of every scope declared on `providerConfig.claims`.

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

@@ -0,0 +1,29 @@
+import { type OidcProviderProfile, type OidcScope, type OidcProviderProfileKey } from '@dereekb/firebase';
+/**
+ * Custom oidc-provider client metadata field holding the {@link OidcProviderProfile} keys assigned
+ * to a client. Registered via `extraClientMetadata` and persisted on the client's `OidcEntry` payload.
+ */
+export declare const DBX_FIREBASE_SERVER_OIDC_PROVIDER_PROFILES_CLIENT_METADATA = "dbx_provider_profiles";
+/**
+ * The scopes a client with the given assigned profile keys is allowed/required to obtain, resolved
+ * against the provider-profile registry.
+ */
+export interface OidcClientProviderProfileScopes<S extends OidcScope = OidcScope> {
+    /**
+     * Scopes unlocked for the client (the union of its assigned profiles' scopes).
+     */
+    readonly unlocked: Set<S>;
+    /**
+     * Scopes the client's profiles force-require (`require: 'required'`).
+     */
+    readonly required: Set<S>;
+}
+/**
+ * Resolves the unlocked + required scope sets for a client from the provider-profile registry and
+ * the profile keys assigned to that client.
+ *
+ * @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.
+ */
+export declare function oidcClientProviderProfileScopes<S extends OidcScope = OidcScope>(providerProfiles: readonly OidcProviderProfile<S>[] | undefined, clientProfileKeys: readonly OidcProviderProfileKey[] | undefined): OidcClientProviderProfileScopes<S>;

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

@@ -2,15 +2,20 @@ import { type OnCallTypedModelParams } from '@dereekb/firebase';
 import { type AssertModelCrudRequestFunction } from '@dereekb/firebase-server';
 /**
  * Builds a {@link AssertModelCrudRequestFunction} that rejects callModel requests
- * lacking the OIDC scope mapped from the call type.
+ * 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 so app-specific verbs
- * remain unrestricted unless an app wires its own assertion.
+ * 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}.
  *