@dereekb/firebase-server 13.37.0 → 13.38.0

package/mcp/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@dereekb/firebase-server/mcp",
-  "version": "13.37.0",
+  "version": "13.38.0",
   "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.38.0",
+    "@dereekb/date": "13.38.0",
+    "@dereekb/firebase": "13.38.0",
+    "@dereekb/firebase-server": "13.38.0",
+    "@dereekb/firebase-server/oidc": "13.38.0",
+    "@dereekb/model": "13.38.0",
+    "@dereekb/nestjs": "13.38.0",
+    "@dereekb/rxjs": "13.38.0",
+    "@dereekb/util": "13.38.0",
+    "@dereekb/zoho": "13.38.0",
     "@modelcontextprotocol/node": "2.0.0",
     "@modelcontextprotocol/server": "2.0.0",
     "@nestjs/common": "^11.1.19",

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,15 @@
 {
   "name": "@dereekb/firebase-server/model",
-  "version": "13.37.0",
+  "version": "13.38.0",
   "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.38.0",
+    "@dereekb/date": "13.38.0",
+    "@dereekb/firebase": "13.38.0",
+    "@dereekb/firebase-server": "13.38.0",
+    "@dereekb/model": "13.38.0",
+    "@dereekb/nestjs": "13.38.0",
+    "@dereekb/rxjs": "13.38.0",
+    "@dereekb/util": "13.38.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "archiver": "^7.0.1",

package/oidc/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/firebase-server/oidc",
-  "version": "13.37.0",
+  "version": "13.38.0",
   "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.38.0",
+    "@dereekb/date": "13.38.0",
+    "@dereekb/firebase": "13.38.0",
+    "@dereekb/firebase-server": "13.38.0",
+    "@dereekb/model": "13.38.0",
+    "@dereekb/nestjs": "13.38.0",
+    "@dereekb/rxjs": "13.38.0",
+    "@dereekb/util": "13.38.0",
+    "@dereekb/zoho": "13.38.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "express": "^5.2.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase-server",
-  "version": "13.37.0",
+  "version": "13.38.0",
   "sideEffects": false,
   "exports": {
     "./test": {
@@ -69,17 +69,17 @@
   "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.38.0",
+    "@dereekb/calcom": "13.38.0",
+    "@dereekb/date": "13.38.0",
+    "@dereekb/dbx-core": "13.38.0",
+    "@dereekb/discord": "13.38.0",
+    "@dereekb/firebase": "13.38.0",
+    "@dereekb/model": "13.38.0",
+    "@dereekb/nestjs": "13.38.0",
+    "@dereekb/rxjs": "13.38.0",
+    "@dereekb/util": "13.38.0",
+    "@dereekb/zoho": "13.38.0",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.19.0",
     "@modelcontextprotocol/node": "2.0.0",

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';

package/src/lib/nest/controller/model/model.api.get.service.d.ts

@@ -1,5 +1,6 @@
 import { type Maybe } from '@dereekb/util';
-import { type FirestoreModelIdentity, type FirestoreModelKey, type FirestoreModelType } from '@dereekb/firebase';
+import { type GrantedRoleMap } from '@dereekb/model';
+import { type FirebaseAuthUserId, type FirestoreModelIdentity, type FirestoreModelKey, type FirestoreModelType } from '@dereekb/firebase';
 import { type INestApplicationContext } from '@nestjs/common';
 import { ModelApiDispatchConfig } from './model.api.dispatch';
 import { type FirebaseServerAuthData } from '../auth.context.server';
@@ -7,6 +8,13 @@ import { type FirebaseServerAuthData } from '../auth.context.server';
  * Maximum number of keys allowed in a multi-read request.
  */
 export declare const MAX_MODEL_ACCESS_MULTI_READ_KEYS = 50;
+/**
+ * Error code returned when a read targets a model the app declared SERVER-ONLY.
+ *
+ * Deliberately distinct from a permission error: nothing the caller can be granted will make this
+ * read succeed, so the message needs to say WHY rather than implying a missing role.
+ */
+export declare const MODEL_IS_SERVER_ONLY_ERROR_CODE = "MODEL_IS_SERVER_ONLY";
 /**
  * Result of a single document access read.
  */
@@ -29,6 +37,90 @@ export interface ModelAccessReadError {
     readonly message: string;
     readonly code?: string;
 }
+/**
+ * The resolved permission state for a single model key, as computed by that model's
+ * `roleMapForModel()` delegate for a specific user.
+ */
+export interface ModelAccessRoleMapResult {
+    readonly key: FirestoreModelKey;
+    /**
+     * Whether the underlying document exists.
+     *
+     * Roles are only computed for documents that exist — `FirebaseModelPermissionServiceInstance`
+     * gates on `isUsableOutputForRoles(output) => output.exists`, so a missing document always
+     * resolves to an empty role set. Surfacing existence separately is what lets a caller tell
+     * "the document is not there" apart from "the document is there and you may not touch it";
+     * both otherwise present as `roles: []`.
+     */
+    readonly exists: boolean;
+    /**
+     * True when the model granted the full-access marker ({@link FULL_ACCESS_ROLE_KEY}) rather than
+     * an enumerated role set — the shape admin short-circuits like `fullAccessRoleMap()` produce.
+     * When true, {@link roles} is empty and every role is implicitly granted.
+     */
+    readonly fullAccess: boolean;
+    /**
+     * The granted role names, sorted. Empty when {@link fullAccess} is true or nothing was granted.
+     */
+    readonly roles: string[];
+}
+/**
+ * Result of a multi-key role-map resolution.
+ */
+export interface ModelAccessMultiRoleMapResult {
+    /**
+     * The uid the roles were resolved for — the caller's own uid unless the request targeted
+     * another user. `undefined` for an unauthenticated resolution.
+     */
+    readonly uid?: string;
+    /**
+     * True when {@link uid} is someone other than the calling user.
+     */
+    readonly targeted: boolean;
+    readonly results: ModelAccessRoleMapResult[];
+    readonly errors: ModelAccessReadError[];
+}
+/**
+ * Input for {@link ModelApiGetService.readRoleMaps}.
+ */
+export interface ModelAccessRoleMapParams {
+    readonly modelType: FirestoreModelType;
+    readonly keys: FirestoreModelKey[];
+    /**
+     * The calling request's auth data.
+     */
+    readonly auth: Maybe<FirebaseServerAuthData>;
+    /**
+     * Resolve roles as this user instead of the caller. Callers are responsible for authorizing
+     * this before passing it — the service performs no permission check of its own on the target.
+     */
+    readonly targetUid?: Maybe<FirebaseAuthUserId>;
+}
+/**
+ * Input for {@link modelAccessRoleMapResultFromGrantedRoles}.
+ */
+export interface ModelAccessRoleMapResultParams {
+    readonly key: FirestoreModelKey;
+    /**
+     * The resolved `ContextGrantedModelRoles` for the key. Typed structurally (rather than importing
+     * the generic) so the mapper stays testable with a plain object.
+     */
+    readonly granted: {
+        readonly data?: Maybe<{
+            readonly exists?: boolean;
+        }>;
+        readonly roleMap: GrantedRoleMap<string>;
+    };
+}
+/**
+ * Maps a resolved `ContextGrantedModelRoles` into the flat {@link ModelAccessRoleMapResult} wire
+ * shape — collapsing the full-access marker into a boolean, dropping the structural marker keys, and
+ * sorting the enumerated role keys so output is stable across calls.
+ *
+ * @param input - The key and its resolved granted-roles result.
+ * @returns The flattened per-key permission state.
+ */
+export declare function modelAccessRoleMapResultFromGrantedRoles(input: ModelAccessRoleMapResultParams): ModelAccessRoleMapResult;
 /**
  * Shape of a single failed-key entry from `useMultipleModels({ throwOnFirstError: false })`.
  * Exposed so the mapper below stays testable without a live nest context.
@@ -77,6 +169,29 @@ export declare class ModelApiGetService {
      * @param auth - The request's auth data (OIDC scopes are read from it).
      */
     private _assertReadScope;
+    /**
+     * Refuses a read of a model the app declared SERVER-ONLY, BEFORE `useModel` runs.
+     *
+     * The model API authorizes through `roleMapForModel` under the Admin SDK, which bypasses
+     * `firestore.rules` entirely. For a model the rules file deliberately leaves unmatched (or denies
+     * outright), those two systems disagree and the model API is the one handing out the document.
+     * Gating here — ahead of the role map, and on the ONE service both `/model/<type>/get` and the
+     * `model-get` MCP tool share — is what makes the two read paths agree.
+     *
+     * @param modelType - The Firestore model type being read.
+     * @param auth - The request's auth data; used to build the context the service lookup needs.
+     * @throws {HttpsError} `MODEL_IS_SERVER_ONLY` when the model opted in via `serverOnly`.
+     */
+    private _assertNotServerOnly;
+    /**
+     * Reads the `serverOnly` flag off the registered model service, tolerating a type whose service
+     * cannot be constructed (which `readDocument` then reports as an unknown model).
+     *
+     * @param modelType - The Firestore model type to inspect.
+     * @param auth - The request's auth data.
+     * @returns `true` when the model declared itself server-only.
+     */
+    private _isServerOnlyModel;
     /**
      * Returns the registered {@link FirestoreModelIdentity} for the given `modelType` string, or
      * `undefined` when no model of that type is registered.
@@ -114,6 +229,36 @@ export declare class ModelApiGetService {
      * @returns Results and errors for each requested key.
      */
     readDocuments(modelType: FirestoreModelType, keys: FirestoreModelKey[], auth: Maybe<FirebaseServerAuthData>): Promise<ModelAccessMultiReadResult>;
+    /**
+     * Resolves the granted role map for one or more keys of the same model type — i.e. "what is this
+     * user actually allowed to do with this document?".
+     *
+     * This is the same computation the permission-checked read path runs (`roleMapForModel()` on the
+     * model's registered service factory), but the resolved roles are returned instead of being
+     * consumed to allow/deny an operation. Because it runs the model's real delegate, derived and
+     * cascading roles are included exactly as the API would grant them.
+     *
+     * Per-key failures are captured in `errors` rather than thrown, matching {@link readDocuments}.
+     * A key that resolves to a missing document is NOT an error — it comes back with
+     * `exists: false, roles: []`, which is what distinguishes "not there" from "no access".
+     *
+     * @param params - Model type, keys, calling auth, and an optional target uid.
+     * @returns The per-key permission state plus the uid the roles were resolved for.
+     */
+    readRoleMaps(params: ModelAccessRoleMapParams): Promise<ModelAccessMultiRoleMapResult>;
+    /**
+     * Builds a synthetic {@link AuthData} for an arbitrary uid so role resolution can run *as* that
+     * user rather than as the caller.
+     *
+     * The target's custom claims are read from their Firebase Auth record and spread into the
+     * synthetic token, mirroring how Firebase merges custom claims into a real decoded ID token —
+     * so claim-reading permission delegates behave identically to a live request from that user.
+     *
+     * @param uid - The uid to resolve as.
+     * @returns An auth ref carrying the target user's claims.
+     * @throws {Error} If no Firebase Auth user exists for the uid.
+     */
+    private _makeAuthRefForUid;
     /**
      * Builds an {@link AuthDataRef} compatible with `useModel()` from the HTTP request auth.
      *

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

@@ -40,8 +40,9 @@ export interface ModelApiOidcScopeConfig {
  * `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`.
+ * `@dereekb/firebase-server/oidc` sub-package this core layer cannot import), delegating entirely to the
+ * shared {@link oidcScopesFromRequestAuth} so there is no drift with `getOidcScopesFromRequest` or with
+ * the non-model endpoints that read scopes the same way.
  *
  * @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.

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

@@ -0,0 +1,4 @@
+export * from './session.api.config';
+export * from './session.api.service';
+export * from './session.api.controller';
+export * from './session.api.module';