@dereekb/firebase-server 13.37.0 → 13.39.0

package/mcp/package.json

@@ -1,17 +1,18 @@
 {
   "name": "@dereekb/firebase-server/mcp",
-  "version": "13.37.0",
+  "version": "13.39.0",
+  "type": "module",
   "peerDependencies": {
-    "@dereekb/analytics": "13.37.0",
-    "@dereekb/date": "13.37.0",
-    "@dereekb/firebase": "13.37.0",
-    "@dereekb/firebase-server": "13.37.0",
-    "@dereekb/firebase-server/oidc": "13.37.0",
-    "@dereekb/model": "13.37.0",
-    "@dereekb/nestjs": "13.37.0",
-    "@dereekb/rxjs": "13.37.0",
-    "@dereekb/util": "13.37.0",
-    "@dereekb/zoho": "13.37.0",
+    "@dereekb/analytics": "13.39.0",
+    "@dereekb/date": "13.39.0",
+    "@dereekb/firebase": "13.39.0",
+    "@dereekb/firebase-server": "13.39.0",
+    "@dereekb/firebase-server/oidc": "13.39.0",
+    "@dereekb/model": "13.39.0",
+    "@dereekb/nestjs": "13.39.0",
+    "@dereekb/rxjs": "13.39.0",
+    "@dereekb/util": "13.39.0",
+    "@dereekb/zoho": "13.39.0",
     "@modelcontextprotocol/node": "2.0.0",
     "@modelcontextprotocol/server": "2.0.0",
     "@nestjs/common": "^11.1.19",
@@ -23,13 +24,12 @@
   "exports": {
     "./package.json": "./package.json",
     ".": {
-      "module": "./index.esm.js",
       "types": "./index.d.ts",
-      "import": "./index.cjs.mjs",
-      "default": "./index.cjs.js"
+      "import": "./index.esm.js",
+      "default": "./index.esm.js"
     }
   },
   "module": "./index.esm.js",
-  "main": "./index.cjs.js",
+  "main": "./index.esm.js",
   "types": "./index.d.ts"
-}
+}

package/mcp/src/lib/mcp.config.d.ts

@@ -1,4 +1,5 @@
-import { type AuthClaims, type AuthRoleSet } from '@dereekb/util';
+import { type AuthClaims, type AuthRoleSet, type Maybe, type PromiseOrValue } from '@dereekb/util';
+import { type FirebaseServerAuthData } from '@dereekb/firebase-server';
 import { type FirestoreModelType, type OidcModelScopeRequirement, type OidcScope, type OidcScopeTerm } from '@dereekb/firebase';
 /**
  * Default path the MCP Streamable HTTP transport is mounted at.
@@ -238,3 +239,23 @@ export type McpAuthRoleReader = (claims: AuthClaims) => AuthRoleSet;
  * NestJS injection token for the optional {@link McpAuthRoleReader} provider.
  */
 export declare const MCP_AUTH_ROLE_READER = "MCP_AUTH_ROLE_READER";
+/**
+ * Signature for the optional predicate that authorizes `model-roles` calls which target another
+ * user's uid.
+ *
+ * `model-roles` resolves permissions for the calling user by default, which is always safe. Passing
+ * a `uid` asks the server "what can *that* user do here?" — an answer that leaks the target's
+ * effective access, so it is gated behind this app-supplied predicate rather than being open.
+ *
+ * Receives the calling request's auth data (`undefined` for an unauthenticated request) and returns
+ * true if that caller may resolve roles for arbitrary uids. Typically an admin check, e.g.
+ * `(auth) => authRoleClaimsService.toRoles(auth?.token ?? {}).has('admin')`.
+ *
+ * When no predicate is provided the `uid` parameter fails closed for every caller — the tool is
+ * still registered and still answers for the caller themselves.
+ */
+export type McpModelRolesTargetUidPredicate = (auth: Maybe<FirebaseServerAuthData>) => PromiseOrValue<boolean>;
+/**
+ * NestJS injection token for the optional {@link McpModelRolesTargetUidPredicate} provider.
+ */
+export declare const MCP_MODEL_ROLES_TARGET_UID_PREDICATE = "MCP_MODEL_ROLES_TARGET_UID_PREDICATE";

package/mcp/src/lib/service/index.d.ts

@@ -7,6 +7,7 @@ export * from './mcp.server.factory';
 export * from './mcp.tool-generator';
 export * from './mcp.visibility';
 export * from './tools/mcp.tool.model-get';
+export * from './tools/mcp.tool.model-roles';
 export * from './tools/mcp.tool.model-info';
 export * from './tools/mcp.tool.model-decode';
 export * from './tools/mcp.tool.enum-info';

package/mcp/src/lib/service/mcp.server.factory.d.ts

@@ -1,7 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/server';
 import { type Request } from 'express';
 import { ModelApiCallModelDispatchService, ModelApiGetService, FirebaseServerStorageService, type FirebaseServerAuthData } from '@dereekb/firebase-server';
-import { McpModuleConfig, type McpAuthRoleReader } from '../mcp.config';
+import { McpModuleConfig, type McpAuthRoleReader, type McpModelRolesTargetUidPredicate } from '../mcp.config';
 import { type McpAnalyticsService } from './analytics/mcp.analytics.handler';
 /**
  * Optional per-request context passed when invoking the MCP server through a
@@ -28,6 +28,7 @@ export declare class McpServerFactoryService {
     private readonly modelApiGetService?;
     private readonly roleReader?;
     private readonly storageService?;
+    private readonly modelRolesTargetUidPredicate?;
     private readonly _logger;
     private _cachedTools;
     private _cachedStaticTools;
@@ -42,7 +43,7 @@ export declare class McpServerFactoryService {
     private _warnedMissingRoleReader;
     private _resolvedReasonConfig?;
     private readonly _analyticsService;
-    constructor(mcpConfig: McpModuleConfig, dispatchService: ModelApiCallModelDispatchService, modelApiGetService?: ModelApiGetService | undefined, roleReader?: McpAuthRoleReader | undefined, analyticsService?: McpAnalyticsService, storageService?: FirebaseServerStorageService | undefined);
+    constructor(mcpConfig: McpModuleConfig, dispatchService: ModelApiCallModelDispatchService, modelApiGetService?: ModelApiGetService | undefined, roleReader?: McpAuthRoleReader | undefined, analyticsService?: McpAnalyticsService, storageService?: FirebaseServerStorageService | undefined, modelRolesTargetUidPredicate?: McpModelRolesTargetUidPredicate | undefined);
     /**
      * Builds a configured MCP server with tool listing + dispatch handlers wired up.
      *

package/mcp/src/lib/service/tools/mcp.tool.model-roles.d.ts

@@ -0,0 +1,95 @@
+import { type Maybe, type PromiseOrValue } from '@dereekb/util';
+import { type FirebaseAuthUserId, type FirestoreModelIdentity, type FirestoreModelKey, type FirestoreModelType } from '@dereekb/firebase';
+import { type ModelAccessMultiRoleMapResult, type FirebaseServerAuthData } from '@dereekb/firebase-server';
+import { type McpToolDefinition } from '../mcp.tool-generator';
+/**
+ * Reserved tool name for the built-in `model-roles` static tool.
+ */
+export declare const MODEL_ROLES_TOOL_NAME = "model-roles";
+/**
+ * Synthetic call type used in the tool's dispatch identity. Distinct from `model-get`'s `get` so
+ * visibility predicates can target the two independently.
+ */
+export declare const MODEL_ROLES_DISPATCH_CALL = "roles";
+/**
+ * Synthetic model type used in the tool's dispatch identity. Mirrors {@link MODEL_GET_DISPATCH_MODEL_TYPE}
+ * — the tool isn't bound to one model type, so the literal "model" stands in.
+ */
+export declare const MODEL_ROLES_DISPATCH_MODEL_TYPE = "model";
+/**
+ * Maximum number of keys accepted per `model-roles` call. Role resolution runs the model's real
+ * permission delegate per key (which may itself read parent documents), so this is deliberately
+ * lower than the `model-get` batch size.
+ */
+export declare const MCP_MODEL_ROLES_MAX_KEYS = 25;
+/**
+ * Resolves granted role maps for a batch of keys. Signature matches
+ * `ModelApiGetService.readRoleMaps` so the service method can be passed directly.
+ */
+export type McpModelRolesReadRoleMaps = (params: {
+    readonly modelType: FirestoreModelType;
+    readonly keys: FirestoreModelKey[];
+    readonly auth: Maybe<FirebaseServerAuthData>;
+    readonly targetUid?: Maybe<FirebaseAuthUserId>;
+}) => Promise<ModelAccessMultiRoleMapResult>;
+/**
+ * Lookup that resolves a `modelType` to its registered {@link FirestoreModelIdentity}, so bare ids
+ * can be promoted to full keys. Mirrors `McpModelGetResolveIdentity`.
+ */
+export type McpModelRolesResolveIdentity = (modelType: FirestoreModelType, auth: Maybe<FirebaseServerAuthData>) => Maybe<FirestoreModelIdentity>;
+/**
+ * Predicate authorizing a caller to resolve roles for a uid other than their own. Mirrors
+ * `McpModelRolesTargetUidPredicate` from the module config; redeclared here so this module does not
+ * depend on the config module.
+ */
+export type McpModelRolesTargetUidCheck = (auth: Maybe<FirebaseServerAuthData>) => PromiseOrValue<boolean>;
+/**
+ * Constructor dependencies for {@link createModelRolesTool}.
+ */
+export interface CreateModelRolesToolDeps {
+    /**
+     * Resolves the granted role maps for a batch of keys.
+     */
+    readonly readRoleMaps: McpModelRolesReadRoleMaps;
+    /**
+     * Resolves the registered identity for a model type so bare ids can be promoted into full keys.
+     */
+    readonly resolveIdentity: McpModelRolesResolveIdentity;
+    /**
+     * Authorizes use of the `uid` parameter. Omitted means the parameter fails closed for everyone;
+     * the tool still answers for the calling user.
+     */
+    readonly canTargetOtherUids?: Maybe<McpModelRolesTargetUidCheck>;
+}
+/**
+ * Shape of the `model-roles` tool input.
+ */
+export interface ModelRolesToolInput {
+    readonly modelType: string;
+    readonly keys: ReadonlyArray<string>;
+    readonly uid?: string;
+}
+/**
+ * Builds the built-in `model-roles` MCP tool definition.
+ *
+ * Answers "what is this user actually allowed to do with this document?" by running the same
+ * `roleMapForModel()` delegate the permission-checked read/write paths use, and returning the
+ * resolved roles instead of consuming them. Because the model's real delegate runs, derived and
+ * cascading roles appear exactly as the API grants them — there is no second implementation of the
+ * rules to drift.
+ *
+ * Two things it disambiguates that a plain read cannot:
+ * - **Missing vs. forbidden.** A key that resolves to a missing document returns
+ *   `exists: false, roles: []` rather than an error, so "the document is not there" reads
+ *   differently from "it is there and you have no access" (`exists: true, roles: []`).
+ * - **Full access.** Admin short-circuits that grant the full-access marker come back as
+ *   `fullAccess: true` rather than as an opaque enumerated set.
+ *
+ * By default roles are resolved for the calling user. Passing `uid` resolves them for another user
+ * and is gated behind {@link CreateModelRolesToolDeps.canTargetOtherUids}.
+ *
+ * @param deps - Role-map reader, identity resolver, and the target-uid authorization predicate.
+ * @returns A statically-registered {@link McpToolDefinition} ready to be appended to the MCP
+ *   server factory's tool registry.
+ */
+export declare function createModelRolesTool(deps: CreateModelRolesToolDeps): McpToolDefinition;

package/model/package.json

@@ -1,15 +1,16 @@
 {
   "name": "@dereekb/firebase-server/model",
-  "version": "13.37.0",
+  "version": "13.39.0",
+  "type": "module",
   "peerDependencies": {
-    "@dereekb/analytics": "13.37.0",
-    "@dereekb/date": "13.37.0",
-    "@dereekb/firebase": "13.37.0",
-    "@dereekb/firebase-server": "13.37.0",
-    "@dereekb/model": "13.37.0",
-    "@dereekb/nestjs": "13.37.0",
-    "@dereekb/rxjs": "13.37.0",
-    "@dereekb/util": "13.37.0",
+    "@dereekb/analytics": "13.39.0",
+    "@dereekb/date": "13.39.0",
+    "@dereekb/firebase": "13.39.0",
+    "@dereekb/firebase-server": "13.39.0",
+    "@dereekb/model": "13.39.0",
+    "@dereekb/nestjs": "13.39.0",
+    "@dereekb/rxjs": "13.39.0",
+    "@dereekb/util": "13.39.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "archiver": "^7.0.1",
@@ -23,13 +24,12 @@
   "exports": {
     "./package.json": "./package.json",
     ".": {
-      "module": "./index.esm.js",
       "types": "./index.d.ts",
-      "import": "./index.cjs.mjs",
-      "default": "./index.cjs.js"
+      "import": "./index.esm.js",
+      "default": "./index.esm.js"
     }
   },
   "module": "./index.esm.js",
-  "main": "./index.cjs.js",
+  "main": "./index.esm.js",
   "types": "./index.d.ts"
-}
+}

package/model/src/lib/notification/notification.module.d.ts

@@ -35,7 +35,7 @@ export declare function notificationServerActionsContextFactory(context: BaseNot
     notificationLoggedEventDayCollectionGroup: import("@dereekb/firebase").NotificationLoggedEventDayFirestoreCollectionGroup;
     notificationLoggedEventDayPagedItemsCollectionFactory: import("@dereekb/firebase").NotificationLoggedEventDayPagedItemsFirestoreCollectionFactory;
     notificationLoggedEventDayPageCollectionGroup: import("@dereekb/firebase").NotificationLoggedEventDayPageFirestoreCollectionGroup;
-    authService: import("dist/packages/firebase-server/src").FirebaseServerAuthService<import("dist/packages/firebase-server/src").FirebaseServerAuthUserContext, import("dist/packages/firebase-server/src").FirebaseServerAuthContext<import("dist/packages/firebase-server/src").FirebaseServerAuthUserContext>>;
+    authService: import("@dereekb/firebase-server").FirebaseServerAuthService<import("@dereekb/firebase-server").FirebaseServerAuthUserContext, import("@dereekb/firebase-server").FirebaseServerAuthContext<import("@dereekb/firebase-server").FirebaseServerAuthUserContext>>;
     firestoreContext: import("@dereekb/firebase").FirestoreContext<import("@dereekb/firebase").Firestore>;
 };
 /**

package/oidc/package.json

@@ -1,16 +1,17 @@
 {
   "name": "@dereekb/firebase-server/oidc",
-  "version": "13.37.0",
+  "version": "13.39.0",
+  "type": "module",
   "peerDependencies": {
-    "@dereekb/analytics": "13.37.0",
-    "@dereekb/date": "13.37.0",
-    "@dereekb/firebase": "13.37.0",
-    "@dereekb/firebase-server": "13.37.0",
-    "@dereekb/model": "13.37.0",
-    "@dereekb/nestjs": "13.37.0",
-    "@dereekb/rxjs": "13.37.0",
-    "@dereekb/util": "13.37.0",
-    "@dereekb/zoho": "13.37.0",
+    "@dereekb/analytics": "13.39.0",
+    "@dereekb/date": "13.39.0",
+    "@dereekb/firebase": "13.39.0",
+    "@dereekb/firebase-server": "13.39.0",
+    "@dereekb/model": "13.39.0",
+    "@dereekb/nestjs": "13.39.0",
+    "@dereekb/rxjs": "13.39.0",
+    "@dereekb/util": "13.39.0",
+    "@dereekb/zoho": "13.39.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "express": "^5.2.1",
@@ -21,13 +22,12 @@
   "exports": {
     "./package.json": "./package.json",
     ".": {
-      "module": "./index.esm.js",
       "types": "./index.d.ts",
-      "import": "./index.cjs.mjs",
-      "default": "./index.cjs.js"
+      "import": "./index.esm.js",
+      "default": "./index.esm.js"
     }
   },
   "module": "./index.esm.js",
-  "main": "./index.cjs.js",
+  "main": "./index.esm.js",
   "types": "./index.d.ts"
-}
+}

package/package.json

@@ -1,85 +1,74 @@
 {
   "name": "@dereekb/firebase-server",
-  "version": "13.37.0",
+  "version": "13.39.0",
+  "type": "module",
   "sideEffects": false,
   "exports": {
     "./test": {
-      "module": "./test/index.esm.js",
       "types": "./test/index.d.ts",
-      "import": "./test/index.cjs.mjs",
-      "default": "./test/index.cjs.js"
+      "import": "./test/index.esm.js",
+      "default": "./test/index.esm.js"
     },
     "./calcom": {
-      "module": "./calcom/index.esm.js",
       "types": "./calcom/index.d.ts",
-      "import": "./calcom/index.cjs.mjs",
-      "default": "./calcom/index.cjs.js"
+      "import": "./calcom/index.esm.js",
+      "default": "./calcom/index.esm.js"
     },
     "./discord": {
-      "module": "./discord/index.esm.js",
       "types": "./discord/index.d.ts",
-      "import": "./discord/index.cjs.mjs",
-      "default": "./discord/index.cjs.js"
+      "import": "./discord/index.esm.js",
+      "default": "./discord/index.esm.js"
     },
     "./mailgun": {
-      "module": "./mailgun/index.esm.js",
       "types": "./mailgun/index.d.ts",
-      "import": "./mailgun/index.cjs.mjs",
-      "default": "./mailgun/index.cjs.js"
+      "import": "./mailgun/index.esm.js",
+      "default": "./mailgun/index.esm.js"
     },
     "./twilio": {
-      "module": "./twilio/index.esm.js",
       "types": "./twilio/index.d.ts",
-      "import": "./twilio/index.cjs.mjs",
-      "default": "./twilio/index.cjs.js"
+      "import": "./twilio/index.esm.js",
+      "default": "./twilio/index.esm.js"
     },
     "./zoho": {
-      "module": "./zoho/index.esm.js",
       "types": "./zoho/index.d.ts",
-      "import": "./zoho/index.cjs.mjs",
-      "default": "./zoho/index.cjs.js"
+      "import": "./zoho/index.esm.js",
+      "default": "./zoho/index.esm.js"
     },
     "./model": {
-      "module": "./model/index.esm.js",
       "types": "./model/index.d.ts",
-      "import": "./model/index.cjs.mjs",
-      "default": "./model/index.cjs.js"
+      "import": "./model/index.esm.js",
+      "default": "./model/index.esm.js"
     },
     "./oidc": {
-      "module": "./oidc/index.esm.js",
       "types": "./oidc/index.d.ts",
-      "import": "./oidc/index.cjs.mjs",
-      "default": "./oidc/index.cjs.js"
+      "import": "./oidc/index.esm.js",
+      "default": "./oidc/index.esm.js"
     },
     "./mcp": {
-      "module": "./mcp/index.esm.js",
       "types": "./mcp/index.d.ts",
       "import": "./mcp/index.esm.js",
-      "default": "./mcp/index.cjs.js"
+      "default": "./mcp/index.esm.js"
     },
     "./package.json": "./package.json",
     ".": {
-      "module": "./index.esm.js",
       "types": "./index.d.ts",
-      "import": "./index.cjs.mjs",
-      "default": "./index.cjs.js"
+      "import": "./index.esm.js",
+      "default": "./index.esm.js"
     }
   },
-  "main": "./index.cjs.js",
-  "types": "./src/index.d.ts",
   "peerDependencies": {
     "@cantoo/pdf-lib": "^2.6.5",
-    "@dereekb/analytics": "13.37.0",
-    "@dereekb/calcom": "13.37.0",
-    "@dereekb/date": "13.37.0",
-    "@dereekb/dbx-core": "13.37.0",
-    "@dereekb/discord": "13.37.0",
-    "@dereekb/firebase": "13.37.0",
-    "@dereekb/model": "13.37.0",
-    "@dereekb/nestjs": "13.37.0",
-    "@dereekb/rxjs": "13.37.0",
-    "@dereekb/util": "13.37.0",
-    "@dereekb/zoho": "13.37.0",
+    "@dereekb/analytics": "13.39.0",
+    "@dereekb/calcom": "13.39.0",
+    "@dereekb/date": "13.39.0",
+    "@dereekb/dbx-core": "13.39.0",
+    "@dereekb/discord": "13.39.0",
+    "@dereekb/firebase": "13.39.0",
+    "@dereekb/model": "13.39.0",
+    "@dereekb/nestjs": "13.39.0",
+    "@dereekb/rxjs": "13.39.0",
+    "@dereekb/util": "13.39.0",
+    "@dereekb/zoho": "13.39.0",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.19.0",
     "@modelcontextprotocol/node": "2.0.0",
@@ -105,5 +94,7 @@
     "supertest": "^7.2.2",
     "ts-essentials": "^10.2.0"
   },
-  "module": "./index.esm.js"
-}
+  "module": "./index.esm.js",
+  "main": "./index.esm.js",
+  "types": "./index.d.ts"
+}

package/src/lib/env/env.service.d.ts

@@ -14,15 +14,39 @@ export interface FirebaseServerEnvServiceRef<S extends FirebaseServerEnvService
  */
 export declare abstract class FirebaseServerEnvService {
     /**
-     * Whether the server is running in a test/CI environment.
+     * Whether the server is running under a test runner / in CI.
+     *
+     * NOT the complement of {@link isProduction}. There are three distinct situations, and a local
+     * emulator run (`nx run <app>:serve`) is the third one — neither testing nor deployed:
+     *
+     * | situation                  | isTestingEnv | isProduction |
+     * | -------------------------- | ------------ | ------------ |
+     * | test / CI run              | true         | false        |
+     * | local emulator `serve`     | false        | false        |
+     * | deployed (staging or prod) | false        | true         |
+     *
+     * Use this only to branch on "a test runner is driving this" — seeded fixtures, relaxed timeouts,
+     * assertions. To decide whether real Firebase infrastructure is reachable, use {@link isProduction}:
+     * `!isTestingEnv` wrongly includes local emulator runs, which is a common source of calls to live
+     * backends (App Check, IAM signing, service-account discovery) that fail with no emulator behind them.
      */
     abstract readonly isTestingEnv: boolean;
     /**
-     * Whether the server is running in production mode. (This may be true in both prod or a staging running as production).
+     * Whether the server is DEPLOYED — true for every deployed environment, including staging.
+     *
+     * This is the gate for "real Firebase infrastructure is reachable": services with no emulator
+     * (App Check token minting, IAM signing, GCE metadata service-account discovery) may only be
+     * called when this is true. It is false for both a test run and a local emulator `serve`, which is
+     * what makes it — and not `!isTestingEnv` — the correct check for those calls.
+     *
+     * Use {@link isStaging} to distinguish staging from true production.
      */
     abstract readonly isProduction: boolean;
     /**
-     * Whether the server is running in a staging environment. isProduction is also typically true when this is true.
+     * Whether the server is running in a staging environment.
+     *
+     * Narrows within a deployed environment: {@link isProduction} is also true when this is true, since
+     * staging runs as production against real infrastructure.
      */
     abstract readonly isStaging: boolean;
     /**

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

@@ -0,0 +1,63 @@
+import { type Maybe } from '@dereekb/util';
+import { type OidcScope, type OidcScopeTerm } from '@dereekb/firebase';
+import { type FirebaseServerAuthData } from './auth.context.server';
+/**
+ * Error code thrown by {@link assertEndpointOidcScope} when an OIDC caller is missing the scope a
+ * non-model endpoint requires.
+ *
+ * Distinct from the callModel-layer code so a client can tell "you cannot call this endpoint" apart
+ * from "you cannot make this model call".
+ */
+export declare const MISSING_ENDPOINT_OIDC_SCOPE_ERROR_CODE = "MISSING_ENDPOINT_OIDC_SCOPE_ERROR";
+/**
+ * Reads the set of OIDC scopes carried by an authenticated request, 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, since the OIDC-specific `oidcValidatedToken` lives in the
+ * `@dereekb/firebase-server/oidc` sub-package this core layer cannot import — and the actual parse is
+ * delegated 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 oidcScopesFromRequestAuth(auth: Maybe<FirebaseServerAuthData>): Maybe<Set<OidcScope>>;
+/**
+ * Inputs to {@link assertEndpointOidcScope}.
+ */
+export interface AssertEndpointOidcScopeInput {
+    /**
+     * The scope term the endpoint requires — a single scope, or an OR-group satisfied by holding any
+     * one of its scopes. `undefined`/`null` imposes no requirement.
+     */
+    readonly requiredScope: Maybe<OidcScopeTerm>;
+    /**
+     * The scopes the caller was granted, or `undefined` for a non-OIDC caller (bypasses enforcement).
+     */
+    readonly grantedScopes: Maybe<ReadonlySet<OidcScope>>;
+    /**
+     * Human-readable endpoint identifier used in the thrown error message (e.g. `/api/session/firestore`).
+     */
+    readonly endpoint: string;
+}
+/**
+ * Enforces a single OIDC scope requirement for a plain (non-callModel) endpoint, throwing a `403`
+ * when an OIDC caller does not hold it.
+ *
+ * The non-model counterpart to `assertModelApiOidcScope`, which is unusable outside the model API
+ * because it requires a `{ call, modelType }` pair. Evaluation reuses the same shipped
+ * {@link oidcScopeTermSatisfied} primitive so a term means the same thing on both surfaces.
+ *
+ * Bypasses (no-op) when `grantedScopes` is `undefined` — i.e. a non-OIDC caller carrying a plain
+ * Firebase ID token, which has no `scope` claim to enforce against. **This is why scope-gating alone
+ * is never a sufficient gate**: an endpoint that must reject non-admins needs its own admin check,
+ * with the scope acting as defence in depth.
+ *
+ * @param input - The required term, the caller's granted scopes, and the endpoint name for the message.
+ * @throws A `403` forbidden error (code {@link MISSING_ENDPOINT_OIDC_SCOPE_ERROR_CODE}) when an OIDC
+ *   caller does not satisfy the requirement.
+ */
+export declare function assertEndpointOidcScope(input: AssertEndpointOidcScopeInput): void;

package/src/lib/nest/controller/index.d.ts

@@ -1,2 +1,4 @@
 export * from './auth.context.server';
+export * from './api.scope';
 export * from './model';
+export * from './session';