@dereekb/firebase-server 13.36.0 → 13.38.0

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

@@ -34,3 +34,24 @@ export interface OidcClientProviderProfileScopes<S extends OidcScope = OidcScope
  * @returns The unlocked and required scope sets for the client.
  */
 export declare function oidcClientProviderProfileScopes<S extends OidcScope = OidcScope>(providerProfiles: readonly OidcProviderProfile<S>[] | undefined, clientProfileKeys: readonly OidcProviderProfileKey[] | undefined): OidcClientProviderProfileScopes<S>;
+/**
+ * The subset of an {@link OidcProviderConfig} needed to resolve its admin-only scopes. Declared
+ * structurally so this module stays free of a dependency on the config type.
+ */
+export interface OidcAdminOnlyScopesInput<S extends OidcScope = OidcScope> {
+    readonly adminOnlyScopes?: readonly string[];
+    readonly providerProfiles?: readonly OidcProviderProfile<S>[];
+}
+/**
+ * Resolves every scope restricted to admin users: the provider config's own `adminOnlyScopes`
+ * unioned with the scopes of each profile marked {@link OidcProviderProfile.adminOnly}.
+ *
+ * The single choke point for that union — the consent admin-only gate (which hard-rejects a
+ * non-admin who consented to one) and the consent URL builder (which withholds them from a
+ * non-admin's consent screen in the first place) both read through it, so the set a user is
+ * offered and the set they are judged against cannot drift apart.
+ *
+ * @param providerConfig - The provider config supplying `adminOnlyScopes` and the profile registry.
+ * @returns The union of config-level and profile-level admin-only scopes.
+ */
+export declare function adminOnlyScopesForOidcProviderConfig<S extends OidcScope = OidcScope>(providerConfig: OidcAdminOnlyScopesInput<S>): Set<string>;

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

@@ -9,3 +9,4 @@ export * from './oidc.jwks.service';
 export * from './oidc.config.service';
 export * from './oidc.client.service';
 export * from './oidc.interaction.service';
+export * from './oidc.interaction-policy';

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

@@ -81,6 +81,20 @@ export declare class OidcProviderConfigService {
      * Scopes derived from the claims configuration keys.
      */
     readonly scopesSupported: string[];
+    /**
+     * {@link scopesSupported} minus the scopes only an admin-assigned {@link OidcProviderProfile}
+     * unlocks — what an arbitrary client (a dynamically registered one included) may actually put in
+     * an authorization request.
+     *
+     * The issuer's own discovery document keeps advertising the full {@link scopesSupported}: the
+     * provider does support those scopes, for the clients holding the profile. This narrower list is
+     * for metadata a client treats as a request template — notably an MCP protected-resource
+     * document's `scopes_supported`, which dynamic-registration clients (the Claude Code CLI) copy
+     * verbatim onto `/authorize`. An assignment-only scope advertised there ends the flow in
+     * `access_denied`: the consent unlock gate judges the REQUEST, so unlike an admin-only scope
+     * there is no deselect-at-consent way through.
+     */
+    readonly clientRequestableScopesSupported: string[];
     /**
      * Flat list of all unique claim names from the claims configuration.
      */

package/oidc/src/lib/service/oidc.interaction-policy.d.ts

@@ -0,0 +1,35 @@
+import { type interactionPolicy } from 'oidc-provider';
+/**
+ * Reason string of the check {@link buildOidcInteractionPolicy} adds to the `login` prompt.
+ */
+export declare const STALE_SESSION_ACCOUNT_CHECK_REASON = "stale_session_account";
+/**
+ * The `interactionPolicy` namespace as imported at runtime.
+ *
+ * Passed in rather than imported here because `oidc-provider` is ESM-only and the service reaches
+ * it through a dynamic `import()`; taking it as an argument keeps this module synchronously
+ * testable.
+ */
+export type OidcInteractionPolicyNamespace = typeof interactionPolicy;
+/**
+ * Builds the interaction policy: oidc-provider's default prompts, plus a `login` check that
+ * catches a session whose account no longer resolves.
+ *
+ * The default policy crashes on that case. `login`'s `no_session` check passes on
+ * `oidc.session.accountId` alone — the value in the `_session` cookie — while `loadAccount` puts
+ * the result of `findAccount` on `oidc.account`, and `loadGrant` establishes `oidc.grant` ONLY when
+ * that account resolved. So a cookie naming a deleted account skips the login prompt, reaches the
+ * `consent` prompt's `op_scopes_missing` check, and dereferences `oidc.grant.getOIDCScopeEncountered()`
+ * on `undefined` — a `TypeError` that oidc-provider renders as an opaque `server_error`, on every
+ * authorization request, until the user clears the cookie by hand.
+ *
+ * Deleted accounts are ordinary: an emulator database reset in development, an account deletion in
+ * production. Re-authenticating is the correct response, so this requests the `login` prompt and the
+ * user recovers by logging in. The check is added to `login` rather than guarding `consent` so the
+ * prompt loop short-circuits before any consent check runs (it breaks on the first prompt that
+ * fires).
+ *
+ * @param policyNamespace - The `interactionPolicy` namespace from the runtime `oidc-provider` import.
+ * @returns The default policy with the stale-session check installed on the `login` prompt.
+ */
+export declare function buildOidcInteractionPolicy(policyNamespace: OidcInteractionPolicyNamespace): interactionPolicy.DefaultPolicy;

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

@@ -34,6 +34,7 @@ export declare class OidcService {
     private readonly accountService;
     private readonly collections;
     private readonly encryptionService;
+    private readonly _logger;
     private readonly _getProvider;
     constructor(config: OidcModuleConfig, providerConfigService: OidcProviderConfigService, jwksService: JwksService, accountService: OidcAccountService, collections: OidcServerFirestoreCollections, encryptionService: OidcEncryptionService);
     /**
@@ -108,4 +109,32 @@ export declare class OidcService {
      */
     buildProviderConfiguration(cookieKeys: string[]): Configuration;
     private _buildProvider;
+    /**
+     * Whether the user an interaction resolved to is an admin.
+     *
+     * Reads the same `isAdminUser` delegate the consent admin-only gate uses. Fails closed — an
+     * interaction with no resolved account (the login prompt, before authentication) or a delegate
+     * that does not implement the hook is treated as non-admin, so admin-only scopes are withheld
+     * unless admin status is positively established.
+     *
+     * @param interaction - The interaction whose session account should be checked.
+     * @returns True when the interaction's account resolves to an admin user.
+     */
+    private _isAdminInteractionUser;
+    /**
+     * Wires oidc-provider's error events to the Nest logger.
+     *
+     * oidc-provider catches everything thrown inside its koa stack and renders the generic
+     * `{"error":"server_error","error_description":"oops! something went wrong"}` body. The real
+     * cause is only ever handed to the `server_error` event — with no listener it is dropped, and a
+     * failing authorization request is undiagnosable from either the response or the function logs.
+     *
+     * `grant.error` / `introspection.error` / `revocation.error` cover the token-endpoint equivalents.
+     * These are all genuine server-side faults; expected protocol rejections (`invalid_client`,
+     * `access_denied`, …) travel as normal responses and are NOT emitted here, so this stays quiet in
+     * healthy operation.
+     *
+     * @param provider - The constructed oidc-provider instance to attach listeners to.
+     */
+    private _attachProviderErrorLogging;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase-server",
-  "version": "13.36.0",
+  "version": "13.38.0",
   "sideEffects": false,
   "exports": {
     "./test": {
@@ -69,20 +69,21 @@
   "types": "./src/index.d.ts",
   "peerDependencies": {
     "@cantoo/pdf-lib": "^2.6.5",
-    "@dereekb/analytics": "13.36.0",
-    "@dereekb/calcom": "13.36.0",
-    "@dereekb/date": "13.36.0",
-    "@dereekb/dbx-core": "13.36.0",
-    "@dereekb/discord": "13.36.0",
-    "@dereekb/firebase": "13.36.0",
-    "@dereekb/model": "13.36.0",
-    "@dereekb/nestjs": "13.36.0",
-    "@dereekb/rxjs": "13.36.0",
-    "@dereekb/util": "13.36.0",
-    "@dereekb/zoho": "13.36.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/sdk": "1.29.0",
+    "@modelcontextprotocol/node": "2.0.0",
+    "@modelcontextprotocol/server": "2.0.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "@nestjs/core": "^11.1.19",

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

package/src/lib/nest/controller/session/session.api.config.d.ts

@@ -0,0 +1,104 @@
+import { type Maybe, type Milliseconds, type PromiseOrValue } from '@dereekb/util';
+import { type OidcScopeTerm } from '@dereekb/firebase';
+import { type FirebaseServerAuthData } from '../auth.context.server';
+/**
+ * Route prefix the session API controller is mounted at. Under the `/api` global route prefix the
+ * routes become `/api/session/*`.
+ */
+export declare const SESSION_API_ROUTE_PREFIX = "session";
+/**
+ * Path (relative to the API base URL) of the direct-Firestore session endpoint.
+ *
+ * The `@dereekb/dbx-cli` client posts to `<apiBaseUrl>${FIRESTORE_SESSION_API_PATH}`.
+ */
+export declare const FIRESTORE_SESSION_API_PATH = "/session/firestore";
+/**
+ * Path prefix apps must add to their OIDC `protectedPaths` so the bearer-token middleware
+ * authenticates the session endpoint (today typically `['/api/model', '/mcp']`).
+ *
+ * Without this the endpoint is reachable unauthenticated — `req.auth` would be `undefined` and the
+ * request rejected as unauthenticated, but the gate belongs at the middleware, not the handler.
+ */
+export declare const FIREBASE_SERVER_SESSION_API_PROTECTED_PATH = "/api/session";
+/**
+ * Default lifetime requested for the minted App Check token. Matches the Admin SDK's own default.
+ */
+export declare const DEFAULT_FIRESTORE_SESSION_APP_CHECK_TTL_MILLIS: Milliseconds;
+/**
+ * Minimum lifetime the Admin SDK accepts for an App Check token (30 minutes).
+ */
+export declare const MIN_FIRESTORE_SESSION_APP_CHECK_TTL_MILLIS: Milliseconds;
+/**
+ * Maximum lifetime the Admin SDK accepts for an App Check token (7 days).
+ *
+ * Deliberately NOT the default: this endpoint mints a valid web-app App Check attestation for
+ * whoever calls it, so the shortest workable lifetime is the right one.
+ */
+export declare const MAX_FIRESTORE_SESSION_APP_CHECK_TTL_MILLIS: Milliseconds;
+/**
+ * Window a Firebase Auth custom token may be exchanged for an ID token within (1 hour, fixed by
+ * Firebase). The exchanged ID token then lives its own hour from sign-in.
+ */
+export declare const FIREBASE_CUSTOM_TOKEN_EXCHANGE_WINDOW_MILLIS: Milliseconds;
+/**
+ * Signature for the predicate that authorizes a caller to open a direct-Firestore session.
+ *
+ * Receives the calling request's auth data (`undefined` for an unauthenticated request) and returns
+ * true when that caller may be handed a custom token + App Check attestation. Typically an admin
+ * check, e.g. `(auth) => authRoleClaimsService.toRoles(auth?.token ?? {}).has('admin')`.
+ *
+ * This is the LOAD-BEARING gate. `assertIsAdminInRequest` cannot be used here — it needs a
+ * `NestContextCallableRequestWithOptionalAuth` with `.nest` attached, and a plain Nest controller
+ * only has an Express request carrying `req.auth` — so the check is delegated to the app, keeping
+ * `@dereekb/firebase-server` app-agnostic about what "admin" means.
+ *
+ * When no predicate is provided the endpoint fails closed for EVERY caller.
+ */
+export type FirestoreSessionAdminPredicate = (auth: Maybe<FirebaseServerAuthData>) => PromiseOrValue<boolean>;
+/**
+ * NestJS injection token for the {@link FirestoreSessionAdminPredicate} provider.
+ */
+export declare const FIRESTORE_SESSION_ADMIN_PREDICATE = "FIRESTORE_SESSION_ADMIN_PREDICATE";
+/**
+ * Optional configuration for the session API module, supplied by the app via its dependency module.
+ *
+ * Everything here is optional — with no config provided the endpoint still mints custom tokens, just
+ * without an App Check attestation (correct for a project that does not enforce App Check, and for
+ * emulator-backed local development).
+ */
+export declare abstract class SessionApiModuleConfig {
+    /**
+     * The Firebase `appId` of the registered **web** app to mint App Check tokens for. This is the same
+     * `appId` the browser client initializes with — the attestation must match an app the project's
+     * App Check enforcement recognizes.
+     *
+     * When unset, no App Check token is minted and the response's `appCheckToken` is omitted.
+     */
+    readonly appCheckAppId?: string;
+    /**
+     * Lifetime to request for the minted App Check token. Clamped to
+     * [{@link MIN_FIRESTORE_SESSION_APP_CHECK_TTL_MILLIS}, {@link MAX_FIRESTORE_SESSION_APP_CHECK_TTL_MILLIS}].
+     *
+     * Defaults to {@link DEFAULT_FIRESTORE_SESSION_APP_CHECK_TTL_MILLIS}.
+     */
+    readonly appCheckTokenTtlMillis?: Milliseconds;
+    /**
+     * OIDC scope term an OIDC caller must hold to open a session. Defaults to
+     * {@link FIRESTORE_SESSION_OIDC_SCOPE}. Pass `null` to disable scope enforcement entirely (the admin
+     * predicate remains the real gate either way).
+     */
+    readonly requiredScope?: Maybe<OidcScopeTerm>;
+}
+/**
+ * Resolves the effective App Check TTL from the module config, clamped to the Admin SDK's accepted range.
+ *
+ * @param ttlMillis - The configured TTL, or `undefined` to use the default.
+ * @returns The TTL to request, in milliseconds.
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function firestoreSessionAppCheckTtlMillis(ttlMillis: Maybe<Milliseconds>): Milliseconds;
+/**
+ * The default {@link SessionApiModuleConfig.requiredScope}, re-exported for apps that want to widen it
+ * into an OR-group rather than replace it.
+ */
+export declare const DEFAULT_FIRESTORE_SESSION_REQUIRED_OIDC_SCOPE: OidcScopeTerm;

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

@@ -0,0 +1,26 @@
+import { type Request } from 'express';
+import { FirestoreSessionApiService, type FirestoreSessionResult } from './session.api.service';
+/**
+ * REST controller that hands an authenticated admin caller the credentials needed to talk to
+ * Firestore directly, rather than only through the model HTTP API.
+ *
+ * Mounted at `session` — under the `/api` global prefix the route becomes `GET /api/session/firestore`.
+ *
+ * Auth comes from the global OIDC bearer middleware, so `'/api/session'` MUST be listed in the OIDC
+ * module's `protectedPaths` (see `FIREBASE_SERVER_SESSION_API_PROTECTED_PATH`). Follows `McpController`:
+ * there are no NestJS guards in this codebase — protection is path-prefix middleware plus the
+ * per-endpoint checks in {@link FirestoreSessionApiService}.
+ */
+export declare class SessionApiController {
+    private readonly sessionService;
+    constructor(sessionService: FirestoreSessionApiService);
+    /**
+     * Mints a short-lived Firebase Auth custom token (+ App Check attestation, when configured) for the
+     * calling user.
+     *
+     * @param req - The Express request carrying auth credentials on `req.auth`.
+     * @returns The {@link FirestoreSessionResult} credential bundle.
+     */
+    getFirestoreSession(req: Request): Promise<FirestoreSessionResult>;
+    private _toHttpException;
+}