@dereekb/firebase-server 13.10.8 → 13.11.0

package/mailgun/package.json

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

package/model/package.json

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

package/oidc/index.cjs.js

@@ -4076,6 +4076,33 @@ var _logger = new common.Logger('applyOidcAuthMiddleware');
     _logger.debug("Applied OAuth bearer token middleware for paths: ".concat(protectedPaths.join(', ')));
 }
 
+// MARK: Scopes
+/**
+ * Reads the set of OIDC scopes carried by a callable request's bearer token.
+ *
+ * The `ModelApiCallModelDispatchService` builds a synthetic `CallableRequest` with
+ * `auth.token = oidcValidatedToken ?? {}`, so the OIDC scope string lives at
+ * `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`)
+ * skip scope enforcement instead of falsely treating the missing claim as "no scopes granted".
+ *
+ * The parameter is intentionally typed as `unknown` because `DecodedIdToken` (Firebase
+ * Auth's typed token shape) does not declare a `scope` field, while OIDC bearer-token
+ * callers attach one at runtime. Reading is done defensively.
+ *
+ * @param request - The callable request as seen inside an `onCallModel` handler.
+ * @returns A `Set<string>` of granted scopes, or `undefined` when the request carries no OIDC `scope` claim.
+ */ 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;
+}
+
 function asyncGeneratorStep$3(gen, resolve, reject, _next, _throw, key, arg) {
     try {
         var info = gen[key](arg);
@@ -5163,16 +5190,38 @@ function _ts_generator$1(thisArg, body) {
  * The provider's callback strips the controller prefix from the URL so that
  * the provider sees paths relative to its issuer (e.g., `/auth` instead of `/oidc/auth`).
  */ exports.OidcProviderController = /*#__PURE__*/ function() {
-    function OidcProviderController(oidcService) {
+    function OidcProviderController(oidcService, oidcProviderConfigService) {
         _class_call_check$1(this, OidcProviderController);
         _define_property$2(this, "oidcService", void 0);
+        _define_property$2(this, "oidcProviderConfigService", void 0);
         _define_property$2(this, "_callback", void 0);
         this.oidcService = oidcService;
+        this.oidcProviderConfigService = oidcProviderConfigService;
         this._callback = this.oidcService.getProvider().then(function(p) {
             return p.callback();
         });
     }
     _create_class$1(OidcProviderController, [
+        {
+            /**
+     * GET /oidc/login/client
+     *
+     * Convenience redirect from the API issuer path back to the frontend app's
+     * OAuth login page. Lets a user who lands on the API host get bounced to the
+     * client-side login UI. Any incoming query string is forwarded so flow params
+     * (e.g., `uid`, `state`) survive the redirect, merged with any params already
+     * baked into `appLoginUrl`.
+     *
+     * @param req - Inbound Express request; only `originalUrl` is used so any incoming query string can be forwarded to the redirect target.
+     * @param res - Express response used to issue the 302 redirect to the configured `appLoginUrl`.
+     */ key: "redirectToClientLogin",
+            value: function redirectToClientLogin(req, res) {
+                res.redirect(mergeQueryParamsFromOriginalUrl({
+                    baseUrl: this.oidcProviderConfigService.appLoginUrl,
+                    originalUrl: req.originalUrl
+                }));
+            }
+        },
         {
             key: "handleOidcRequest",
             value: function handleOidcRequest(req, res) {
@@ -5201,6 +5250,11 @@ function _ts_generator$1(thisArg, body) {
     ]);
     return OidcProviderController;
 }();
+__decorate([
+    common.Get('login/client'),
+    __param(0, common.Req()),
+    __param(1, common.Res())
+], exports.OidcProviderController.prototype, "redirectToClientLogin", null);
 __decorate([
     common.All('{*path}'),
     __param(0, common.Req()),
@@ -5208,8 +5262,31 @@ __decorate([
 ], exports.OidcProviderController.prototype, "handleOidcRequest", null);
 exports.OidcProviderController = __decorate([
     common.Controller('oidc'),
-    __param(0, common.Inject(exports.OidcService))
+    __param(0, common.Inject(exports.OidcService)),
+    __param(1, common.Inject(exports.OidcProviderConfigService))
 ], exports.OidcProviderController);
+/**
+ * Merges any query string present on `originalUrl` into `baseUrl`, preserving any params already
+ * baked into `baseUrl`. Bare-string concatenation would produce malformed URLs (`?foo=1?bar=2`)
+ * when `baseUrl` already contains a `?`.
+ *
+ * @param input - The base/original URL pair to merge.
+ * @param input.baseUrl - The destination URL whose query string should be augmented with any incoming params.
+ * @param input.originalUrl - The inbound request URL whose query string is appended onto `baseUrl`.
+ * @returns The base URL with the original URL's query string appended using the appropriate `?`/`&` separator.
+ */ function mergeQueryParamsFromOriginalUrl(input) {
+    var queryIndex = input.originalUrl.indexOf('?');
+    if (queryIndex < 0) {
+        return input.baseUrl;
+    }
+    var incomingSearch = input.originalUrl.slice(queryIndex + 1);
+    if (incomingSearch.length === 0) {
+        return input.baseUrl;
+    }
+    var baseQueryIndex = input.baseUrl.indexOf('?');
+    var separator = baseQueryIndex < 0 ? '?' : '&';
+    return "".concat(input.baseUrl).concat(separator).concat(incomingSearch);
+}
 
 function asyncGeneratorStep(gen, resolve, reject, _next, _throw, key, arg) {
     try {
@@ -5735,6 +5812,90 @@ function _unsupported_iterable_to_array(o, minLen) {
     };
 }
 
+/**
+ * Prefix shared by every callModel OIDC scope (e.g., `model.create`).
+ *
+ * Kept stable so OAuth consent screens render consistent labels and so
+ * future per-resource scopes (e.g., `model.create:profile`) compose cleanly.
+ */ var CALL_MODEL_OIDC_SCOPE_PREFIX = 'model.';
+/**
+ * Canonical CRUD scopes enforced on the `callModel` API.
+ *
+ * Each scope corresponds 1:1 to a {@link KnownOnCallFunctionType}; see
+ * {@link CALL_MODEL_OIDC_SCOPE_FOR_CALL_TYPE}.
+ */ var CALL_MODEL_OIDC_SCOPES = [
+    'model.create',
+    'model.read',
+    'model.update',
+    'model.delete',
+    'model.query'
+];
+/**
+ * Maps each known CRUD call type to the scope an OIDC token must carry to invoke it.
+ */ var CALL_MODEL_OIDC_SCOPE_FOR_CALL_TYPE = {
+    create: 'model.create',
+    read: 'model.read',
+    update: 'model.update',
+    delete: 'model.delete',
+    query: 'model.query'
+};
+/**
+ * Resolves the OIDC scope that an OIDC-authenticated caller must hold to invoke
+ * the given callModel `call` type.
+ *
+ * Returns `undefined` for non-CRUD (custom) call types so that scope enforcement
+ * is opt-in for app-specific verbs — apps can still gate them via their own
+ * `preAssert` if needed.
+ *
+ * @param call - The CRUD call type from {@link OnCallTypedModelParams.call}.
+ * @returns The required scope, or `undefined` if `call` is not one of the known CRUD verbs.
+ */ function callModelOidcScopeForCallType(call) {
+    var result = call == null ? undefined : CALL_MODEL_OIDC_SCOPE_FOR_CALL_TYPE[call];
+    return result;
+}
+/**
+ * Error code used when an OIDC-authenticated caller is missing the required
+ * `model.*` scope for a callModel CRUD operation.
+ */ var CALL_MODEL_MISSING_OIDC_SCOPE_ERROR_CODE = 'CALL_MODEL_MISSING_OIDC_SCOPE';
+/**
+ * Builds a {@link AssertModelCrudRequestFunction} that rejects callModel requests
+ * lacking the OIDC scope mapped from the call type.
+ *
+ * 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.
+ *
+ * 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) {
+            throw firebaseServer.forbiddenError({
+                status: 403,
+                code: CALL_MODEL_MISSING_OIDC_SCOPE_ERROR_CODE,
+                message: "Missing required OIDC scope for callModel: ".concat(requiredScope),
+                data: {
+                    requiredScope: requiredScope,
+                    call: context.call
+                }
+            });
+        }
+    };
+    return fn;
+}
+
+exports.CALL_MODEL_MISSING_OIDC_SCOPE_ERROR_CODE = CALL_MODEL_MISSING_OIDC_SCOPE_ERROR_CODE;
+exports.CALL_MODEL_OIDC_SCOPES = CALL_MODEL_OIDC_SCOPES;
+exports.CALL_MODEL_OIDC_SCOPE_FOR_CALL_TYPE = CALL_MODEL_OIDC_SCOPE_FOR_CALL_TYPE;
+exports.CALL_MODEL_OIDC_SCOPE_PREFIX = CALL_MODEL_OIDC_SCOPE_PREFIX;
 exports.DEFAULT_APP_OAUTH_CONSENT_PATH_PART = DEFAULT_APP_OAUTH_CONSENT_PATH_PART;
 exports.DEFAULT_APP_OAUTH_INTERACTION_PATH = DEFAULT_APP_OAUTH_INTERACTION_PATH;
 exports.DEFAULT_APP_OAUTH_LOGIN_PATH_PART = DEFAULT_APP_OAUTH_LOGIN_PATH_PART;
@@ -5765,15 +5926,18 @@ exports.OidcServerFirestoreCollections = OidcServerFirestoreCollections;
 exports.activeJwksKeysQuery = activeJwksKeysQuery;
 exports.appOidcModelModuleMetadata = appOidcModelModuleMetadata;
 exports.applyOidcAuthMiddleware = applyOidcAuthMiddleware;
+exports.callModelOidcScopeForCallType = callModelOidcScopeForCallType;
 exports.createAdapterFactory = createAdapterFactory;
 exports.createOidcClientFactory = createOidcClientFactory;
 exports.deleteOidcClientFactory = deleteOidcClientFactory;
+exports.getOidcScopesFromRequest = getOidcScopesFromRequest;
 exports.jwksKeyCollectionReference = jwksKeyCollectionReference;
 exports.jwksKeyConverter = jwksKeyConverter;
 exports.jwksKeyFirestoreCollection = jwksKeyFirestoreCollection;
 exports.jwksKeyIdentity = jwksKeyIdentity;
 exports.jwksKeysWithStatusQuery = jwksKeysWithStatusQuery;
 exports.nonRetiredJwksKeysQuery = nonRetiredJwksKeysQuery;
+exports.oidcCallModelScopePreAssert = oidcCallModelScopePreAssert;
 exports.oidcFirestoreCollectionsFactory = oidcFirestoreCollectionsFactory;
 exports.oidcModelServerActions = oidcModelServerActions;
 exports.oidcModelServerActionsFactory = oidcModelServerActionsFactory;

package/oidc/index.esm.js

@@ -3,7 +3,7 @@ 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, rotateOidcClientSecretParamsType, updateOidcClientParamsType, firestoreModelKey, oidcEntryIdentity, OIDC_ENTRY_CLIENT_TYPE, oidcEntriesByUserCodeQuery, oidcEntriesByUidQuery, oidcEntriesByGrantIdQuery, oidcEntryFirestoreCollection } from '@dereekb/firebase';
 import { cachedGetter, unixDateTimeSecondsNumberToDate, unixDateTimeSecondsNumberForNow, selectiveFieldEncryptor, filterUndefinedValues, websiteUrlFromPaths, firstValue, hasHttpPrefix } from '@dereekb/util';
-import { firestoreEncryptedField, firebaseServerActionsContext, FirebaseServerEnvService, FIREBASE_FIRESTORE_CONTEXT_TOKEN, FirebaseServerFirestoreContextModule } from '@dereekb/firebase-server';
+import { firestoreEncryptedField, firebaseServerActionsContext, FirebaseServerEnvService, FIREBASE_FIRESTORE_CONTEXT_TOKEN, FirebaseServerFirestoreContextModule, forbiddenError } from '@dereekb/firebase-server';
 import { nanoid } from 'nanoid';
 import { makeUrlSearchParamsString } from '@dereekb/util/fetch';
 import { ConfigService, ConfigModule } from '@nestjs/config';
@@ -4074,6 +4074,33 @@ var _logger = new Logger('applyOidcAuthMiddleware');
     _logger.debug("Applied OAuth bearer token middleware for paths: ".concat(protectedPaths.join(', ')));
 }
 
+// MARK: Scopes
+/**
+ * Reads the set of OIDC scopes carried by a callable request's bearer token.
+ *
+ * The `ModelApiCallModelDispatchService` builds a synthetic `CallableRequest` with
+ * `auth.token = oidcValidatedToken ?? {}`, so the OIDC scope string lives at
+ * `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`)
+ * skip scope enforcement instead of falsely treating the missing claim as "no scopes granted".
+ *
+ * The parameter is intentionally typed as `unknown` because `DecodedIdToken` (Firebase
+ * Auth's typed token shape) does not declare a `scope` field, while OIDC bearer-token
+ * callers attach one at runtime. Reading is done defensively.
+ *
+ * @param request - The callable request as seen inside an `onCallModel` handler.
+ * @returns A `Set<string>` of granted scopes, or `undefined` when the request carries no OIDC `scope` claim.
+ */ 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;
+}
+
 function asyncGeneratorStep$3(gen, resolve, reject, _next, _throw, key, arg) {
     try {
         var info = gen[key](arg);
@@ -5161,16 +5188,38 @@ function _ts_generator$1(thisArg, body) {
  * The provider's callback strips the controller prefix from the URL so that
  * the provider sees paths relative to its issuer (e.g., `/auth` instead of `/oidc/auth`).
  */ var OidcProviderController = /*#__PURE__*/ function() {
-    function OidcProviderController(oidcService) {
+    function OidcProviderController(oidcService, oidcProviderConfigService) {
         _class_call_check$1(this, OidcProviderController);
         _define_property$2(this, "oidcService", void 0);
+        _define_property$2(this, "oidcProviderConfigService", void 0);
         _define_property$2(this, "_callback", void 0);
         this.oidcService = oidcService;
+        this.oidcProviderConfigService = oidcProviderConfigService;
         this._callback = this.oidcService.getProvider().then(function(p) {
             return p.callback();
         });
     }
     _create_class$1(OidcProviderController, [
+        {
+            /**
+     * GET /oidc/login/client
+     *
+     * Convenience redirect from the API issuer path back to the frontend app's
+     * OAuth login page. Lets a user who lands on the API host get bounced to the
+     * client-side login UI. Any incoming query string is forwarded so flow params
+     * (e.g., `uid`, `state`) survive the redirect, merged with any params already
+     * baked into `appLoginUrl`.
+     *
+     * @param req - Inbound Express request; only `originalUrl` is used so any incoming query string can be forwarded to the redirect target.
+     * @param res - Express response used to issue the 302 redirect to the configured `appLoginUrl`.
+     */ key: "redirectToClientLogin",
+            value: function redirectToClientLogin(req, res) {
+                res.redirect(mergeQueryParamsFromOriginalUrl({
+                    baseUrl: this.oidcProviderConfigService.appLoginUrl,
+                    originalUrl: req.originalUrl
+                }));
+            }
+        },
         {
             key: "handleOidcRequest",
             value: function handleOidcRequest(req, res) {
@@ -5199,6 +5248,11 @@ function _ts_generator$1(thisArg, body) {
     ]);
     return OidcProviderController;
 }();
+__decorate([
+    Get('login/client'),
+    __param(0, Req()),
+    __param(1, Res())
+], OidcProviderController.prototype, "redirectToClientLogin", null);
 __decorate([
     All('{*path}'),
     __param(0, Req()),
@@ -5206,8 +5260,31 @@ __decorate([
 ], OidcProviderController.prototype, "handleOidcRequest", null);
 OidcProviderController = __decorate([
     Controller('oidc'),
-    __param(0, Inject(OidcService))
+    __param(0, Inject(OidcService)),
+    __param(1, Inject(OidcProviderConfigService))
 ], OidcProviderController);
+/**
+ * Merges any query string present on `originalUrl` into `baseUrl`, preserving any params already
+ * baked into `baseUrl`. Bare-string concatenation would produce malformed URLs (`?foo=1?bar=2`)
+ * when `baseUrl` already contains a `?`.
+ *
+ * @param input - The base/original URL pair to merge.
+ * @param input.baseUrl - The destination URL whose query string should be augmented with any incoming params.
+ * @param input.originalUrl - The inbound request URL whose query string is appended onto `baseUrl`.
+ * @returns The base URL with the original URL's query string appended using the appropriate `?`/`&` separator.
+ */ function mergeQueryParamsFromOriginalUrl(input) {
+    var queryIndex = input.originalUrl.indexOf('?');
+    if (queryIndex < 0) {
+        return input.baseUrl;
+    }
+    var incomingSearch = input.originalUrl.slice(queryIndex + 1);
+    if (incomingSearch.length === 0) {
+        return input.baseUrl;
+    }
+    var baseQueryIndex = input.baseUrl.indexOf('?');
+    var separator = baseQueryIndex < 0 ? '?' : '&';
+    return "".concat(input.baseUrl).concat(separator).concat(incomingSearch);
+}
 
 function asyncGeneratorStep(gen, resolve, reject, _next, _throw, key, arg) {
     try {
@@ -5733,4 +5810,84 @@ function _unsupported_iterable_to_array(o, minLen) {
     };
 }
 
-export { DEFAULT_APP_OAUTH_CONSENT_PATH_PART, DEFAULT_APP_OAUTH_INTERACTION_PATH, DEFAULT_APP_OAUTH_LOGIN_PATH_PART, 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_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE, JwksFirestoreCollections, JwksKeyDocument, JwksService, JwksServiceConfig, JwksServiceStorageConfig, OIDC_ENCRYPTED_PAYLOAD_FIELDS, OIDC_JWKS_ENCRYPTION_SECRET_ENV_KEY, OidcAccountService, OidcAccountServiceDelegate, OidcAccountServiceUserContext, OidcAuth, OidcAuthBearerTokenMiddleware, OidcAuthMiddlewareConfig, OidcClientService, OidcEncryptionService, OidcInteractionController, OidcInteractionService, OidcModelServerActions, OidcModuleConfig, OidcProviderConfigService, OidcProviderController, OidcServerFirestoreCollections, OidcService, OidcWellKnownController, activeJwksKeysQuery, appOidcModelModuleMetadata, applyOidcAuthMiddleware, createAdapterFactory, createOidcClientFactory, deleteOidcClientFactory, jwksKeyCollectionReference, jwksKeyConverter, jwksKeyFirestoreCollection, jwksKeyIdentity, jwksKeysWithStatusQuery, nonRetiredJwksKeysQuery, oidcFirestoreCollectionsFactory, oidcModelServerActions, oidcModelServerActionsFactory, oidcModuleConfigFactory, oidcModuleMetadata, rotateOidcClientSecretFactory, rotatedJwksKeysQuery, updateOidcClientFactory };
+/**
+ * Prefix shared by every callModel OIDC scope (e.g., `model.create`).
+ *
+ * Kept stable so OAuth consent screens render consistent labels and so
+ * future per-resource scopes (e.g., `model.create:profile`) compose cleanly.
+ */ var CALL_MODEL_OIDC_SCOPE_PREFIX = 'model.';
+/**
+ * Canonical CRUD scopes enforced on the `callModel` API.
+ *
+ * Each scope corresponds 1:1 to a {@link KnownOnCallFunctionType}; see
+ * {@link CALL_MODEL_OIDC_SCOPE_FOR_CALL_TYPE}.
+ */ var CALL_MODEL_OIDC_SCOPES = [
+    'model.create',
+    'model.read',
+    'model.update',
+    'model.delete',
+    'model.query'
+];
+/**
+ * Maps each known CRUD call type to the scope an OIDC token must carry to invoke it.
+ */ var CALL_MODEL_OIDC_SCOPE_FOR_CALL_TYPE = {
+    create: 'model.create',
+    read: 'model.read',
+    update: 'model.update',
+    delete: 'model.delete',
+    query: 'model.query'
+};
+/**
+ * Resolves the OIDC scope that an OIDC-authenticated caller must hold to invoke
+ * the given callModel `call` type.
+ *
+ * Returns `undefined` for non-CRUD (custom) call types so that scope enforcement
+ * is opt-in for app-specific verbs — apps can still gate them via their own
+ * `preAssert` if needed.
+ *
+ * @param call - The CRUD call type from {@link OnCallTypedModelParams.call}.
+ * @returns The required scope, or `undefined` if `call` is not one of the known CRUD verbs.
+ */ function callModelOidcScopeForCallType(call) {
+    var result = call == null ? undefined : CALL_MODEL_OIDC_SCOPE_FOR_CALL_TYPE[call];
+    return result;
+}
+/**
+ * Error code used when an OIDC-authenticated caller is missing the required
+ * `model.*` scope for a callModel CRUD operation.
+ */ var CALL_MODEL_MISSING_OIDC_SCOPE_ERROR_CODE = 'CALL_MODEL_MISSING_OIDC_SCOPE';
+/**
+ * Builds a {@link AssertModelCrudRequestFunction} that rejects callModel requests
+ * lacking the OIDC scope mapped from the call type.
+ *
+ * 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.
+ *
+ * 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) {
+            throw forbiddenError({
+                status: 403,
+                code: CALL_MODEL_MISSING_OIDC_SCOPE_ERROR_CODE,
+                message: "Missing required OIDC scope for callModel: ".concat(requiredScope),
+                data: {
+                    requiredScope: requiredScope,
+                    call: context.call
+                }
+            });
+        }
+    };
+    return fn;
+}
+
+export { CALL_MODEL_MISSING_OIDC_SCOPE_ERROR_CODE, CALL_MODEL_OIDC_SCOPES, CALL_MODEL_OIDC_SCOPE_FOR_CALL_TYPE, CALL_MODEL_OIDC_SCOPE_PREFIX, DEFAULT_APP_OAUTH_CONSENT_PATH_PART, DEFAULT_APP_OAUTH_INTERACTION_PATH, DEFAULT_APP_OAUTH_LOGIN_PATH_PART, 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_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE, JwksFirestoreCollections, JwksKeyDocument, JwksService, JwksServiceConfig, JwksServiceStorageConfig, OIDC_ENCRYPTED_PAYLOAD_FIELDS, OIDC_JWKS_ENCRYPTION_SECRET_ENV_KEY, OidcAccountService, OidcAccountServiceDelegate, OidcAccountServiceUserContext, OidcAuth, OidcAuthBearerTokenMiddleware, OidcAuthMiddlewareConfig, OidcClientService, OidcEncryptionService, OidcInteractionController, OidcInteractionService, OidcModelServerActions, OidcModuleConfig, OidcProviderConfigService, OidcProviderController, OidcServerFirestoreCollections, OidcService, OidcWellKnownController, activeJwksKeysQuery, appOidcModelModuleMetadata, applyOidcAuthMiddleware, callModelOidcScopeForCallType, createAdapterFactory, createOidcClientFactory, deleteOidcClientFactory, getOidcScopesFromRequest, jwksKeyCollectionReference, jwksKeyConverter, jwksKeyFirestoreCollection, jwksKeyIdentity, jwksKeysWithStatusQuery, nonRetiredJwksKeysQuery, oidcCallModelScopePreAssert, oidcFirestoreCollectionsFactory, oidcModelServerActions, oidcModelServerActionsFactory, oidcModuleConfigFactory, oidcModuleMetadata, rotateOidcClientSecretFactory, rotatedJwksKeysQuery, updateOidcClientFactory };

package/oidc/package.json

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

package/oidc/src/lib/controller/oidc.provider.controller.d.ts

@@ -1,5 +1,6 @@
 import { type Request, type Response } from 'express';
 import { OidcService } from '../service/oidc.service';
+import { OidcProviderConfigService } from '../service/oidc.config.service';
 /**
  * Catch-all controller that proxies requests to the oidc-provider callback.
  *
@@ -12,7 +13,21 @@ import { OidcService } from '../service/oidc.service';
  */
 export declare class OidcProviderController {
     private readonly oidcService;
+    private readonly oidcProviderConfigService;
     private _callback;
-    constructor(oidcService: OidcService);
+    constructor(oidcService: OidcService, oidcProviderConfigService: OidcProviderConfigService);
+    /**
+     * GET /oidc/login/client
+     *
+     * Convenience redirect from the API issuer path back to the frontend app's
+     * OAuth login page. Lets a user who lands on the API host get bounced to the
+     * client-side login UI. Any incoming query string is forwarded so flow params
+     * (e.g., `uid`, `state`) survive the redirect, merged with any params already
+     * baked into `appLoginUrl`.
+     *
+     * @param req - Inbound Express request; only `originalUrl` is used so any incoming query string can be forwarded to the redirect target.
+     * @param res - Express response used to issue the 302 redirect to the configured `appLoginUrl`.
+     */
+    redirectToClientLogin(req: Request, res: Response): void;
     handleOidcRequest(req: Request, res: Response): Promise<void>;
 }

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

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

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

@@ -0,0 +1,59 @@
+import { type Maybe } from '@dereekb/util';
+import { type KnownOnCallFunctionType, type OnCallFunctionType, type OnCallTypedModelParams } from '@dereekb/firebase';
+import { type AssertModelCrudRequestFunction } from '@dereekb/firebase-server';
+/**
+ * Prefix shared by every callModel OIDC scope (e.g., `model.create`).
+ *
+ * Kept stable so OAuth consent screens render consistent labels and so
+ * future per-resource scopes (e.g., `model.create:profile`) compose cleanly.
+ */
+export declare const CALL_MODEL_OIDC_SCOPE_PREFIX = "model.";
+/**
+ * Canonical CRUD scopes enforced on the `callModel` API.
+ *
+ * Each scope corresponds 1:1 to a {@link KnownOnCallFunctionType}; see
+ * {@link CALL_MODEL_OIDC_SCOPE_FOR_CALL_TYPE}.
+ */
+export declare const CALL_MODEL_OIDC_SCOPES: readonly ["model.create", "model.read", "model.update", "model.delete", "model.query"];
+/**
+ * Union of the five canonical callModel CRUD scope strings.
+ */
+export type CallModelOidcScope = (typeof CALL_MODEL_OIDC_SCOPES)[number];
+/**
+ * Maps each known CRUD call type to the scope an OIDC token must carry to invoke it.
+ */
+export declare const CALL_MODEL_OIDC_SCOPE_FOR_CALL_TYPE: Readonly<Record<KnownOnCallFunctionType, CallModelOidcScope>>;
+/**
+ * Resolves the OIDC scope that an OIDC-authenticated caller must hold to invoke
+ * the given callModel `call` type.
+ *
+ * Returns `undefined` for non-CRUD (custom) call types so that scope enforcement
+ * is opt-in for app-specific verbs — apps can still gate them via their own
+ * `preAssert` if needed.
+ *
+ * @param call - The CRUD call type from {@link OnCallTypedModelParams.call}.
+ * @returns The required scope, or `undefined` if `call` is not one of the known CRUD verbs.
+ */
+export declare function callModelOidcScopeForCallType(call: Maybe<OnCallFunctionType>): Maybe<CallModelOidcScope>;
+/**
+ * Error code used when an OIDC-authenticated caller is missing the required
+ * `model.*` scope for a callModel CRUD operation.
+ */
+export declare const CALL_MODEL_MISSING_OIDC_SCOPE_ERROR_CODE = "CALL_MODEL_MISSING_OIDC_SCOPE";
+/**
+ * Builds a {@link AssertModelCrudRequestFunction} that rejects callModel requests
+ * lacking the OIDC scope mapped from the call type.
+ *
+ * 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.
+ *
+ * Wire as the `preAssert` of {@link onCallModel}.
+ *
+ * @returns The pre-assertion function ready to plug into `OnCallModelConfig.preAssert`.
+ */
+export declare function oidcCallModelScopePreAssert(): AssertModelCrudRequestFunction<unknown, OnCallTypedModelParams>;

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

@@ -1,3 +1,4 @@
+import { type Maybe } from '@dereekb/util';
 import { type OidcEntryClientId } from '@dereekb/firebase';
 import { type FirebaseServerAuthData, type FirebaseServerAuthenticatedRequest } from '@dereekb/firebase-server';
 /**
@@ -24,3 +25,22 @@ export interface OidcAuthData extends FirebaseServerAuthData {
  * successful bearer token verification.
  */
 export type OidcAuthenticatedRequest = FirebaseServerAuthenticatedRequest<OidcAuthData>;
+/**
+ * Reads the set of OIDC scopes carried by a callable request's bearer token.
+ *
+ * The `ModelApiCallModelDispatchService` builds a synthetic `CallableRequest` with
+ * `auth.token = oidcValidatedToken ?? {}`, so the OIDC scope string lives at
+ * `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`)
+ * skip scope enforcement instead of falsely treating the missing claim as "no scopes granted".
+ *
+ * The parameter is intentionally typed as `unknown` because `DecodedIdToken` (Firebase
+ * Auth's typed token shape) does not declare a `scope` field, while OIDC bearer-token
+ * callers attach one at runtime. Reading is done defensively.
+ *
+ * @param request - The callable request as seen inside an `onCallModel` handler.
+ * @returns A `Set<string>` of granted scopes, or `undefined` when the request carries no OIDC `scope` claim.
+ */
+export declare function getOidcScopesFromRequest(request: unknown): Maybe<Set<string>>;