@dereekb/firebase-server 13.29.0 → 13.30.0

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.

package/test/package.json

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

package/twilio/package.json

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

package/zoho/package.json

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

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

@@ -1,24 +0,0 @@
-import { type OnCallTypedModelParams } from '@dereekb/firebase';
-import { type AssertModelCrudRequestFunction } from '@dereekb/firebase-server';
-/**
- * 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`.
- */
-export declare function oidcCallModelScopePreAssert(): AssertModelCrudRequestFunction<unknown, OnCallTypedModelParams>;