@dereekb/firebase-server 13.37.0 → 13.38.0

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;
+}

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

@@ -0,0 +1,49 @@
+import { type ModuleMetadata } from '@nestjs/common';
+import { type ClassType } from '@dereekb/util';
+/**
+ * Configuration for {@link sessionApiModuleMetadata}.
+ */
+export interface SessionApiModuleMetadataConfig extends Pick<ModuleMetadata, 'imports' | 'exports' | 'providers'> {
+    /**
+     * Module that exports the session endpoint's dependencies.
+     *
+     * Should provide:
+     * - `FIRESTORE_SESSION_ADMIN_PREDICATE` — the app's admin check. Without it the endpoint rejects
+     *   EVERY caller (fail-closed), and logs a warning at boot.
+     * - {@link SessionApiModuleConfig} — the registered web app's `appId` to mint App Check tokens for,
+     *   plus optional TTL / scope overrides. Without it sessions carry no App Check attestation.
+     *
+     * `FIREBASE_APP_TOKEN` is not listed because `nestServerInstance` provides it globally.
+     */
+    readonly dependencyModule: ClassType;
+}
+/**
+ * Generates NestJS module metadata for the direct-Firestore session API.
+ *
+ * Mirrors the convention used by `modelApiModuleMetadata` and `mcpModuleMetadata`: the consumer
+ * provides a dependency module exposing the required tokens, and this factory wires the controller +
+ * service.
+ *
+ * Remember to add `FIREBASE_SERVER_SESSION_API_PROTECTED_PATH` (`'/api/session'`) to the OIDC module's
+ * `protectedPaths` — the controller relies on the bearer middleware having populated `req.auth`.
+ *
+ * @param metadataConfig - Configuration including the dependency module.
+ * @returns NestJS module metadata exposing the session controller + service.
+ *
+ * @example
+ * ```typescript
+ * @Module({
+ *   imports: [DemoApiAuthModule],
+ *   providers: [
+ *     { provide: SessionApiModuleConfig, useValue: { appCheckAppId: environment.firebase.appId } },
+ *     { provide: FIRESTORE_SESSION_ADMIN_PREDICATE, useValue: (auth) => DEMO_AUTH_CLAIMS_SERVICE.toRoles(auth?.token ?? {}).has('admin') }
+ *   ],
+ *   exports: [SessionApiModuleConfig, FIRESTORE_SESSION_ADMIN_PREDICATE]
+ * })
+ * export class DemoSessionApiDependencyModule {}
+ *
+ * @Module(sessionApiModuleMetadata({ dependencyModule: DemoSessionApiDependencyModule }))
+ * export class DemoSessionApiModule {}
+ * ```
+ */
+export declare function sessionApiModuleMetadata(metadataConfig: SessionApiModuleMetadataConfig): ModuleMetadata;

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

@@ -0,0 +1,71 @@
+import type * as admin from 'firebase-admin';
+import { type ISO8601DateString, type Maybe } from '@dereekb/util';
+import { type FirebaseAuthUserId } from '@dereekb/firebase';
+import { type FirebaseServerAuthData } from '../auth.context.server';
+import { type FirestoreSessionAdminPredicate, SessionApiModuleConfig } from './session.api.config';
+/**
+ * Error code thrown when the caller is not authorized to open a direct-Firestore session.
+ */
+export declare const FIRESTORE_SESSION_FORBIDDEN_ERROR_CODE = "FIRESTORE_SESSION_FORBIDDEN_ERROR";
+/**
+ * A short-lived credential bundle that lets a headless client connect directly to Firestore as the
+ * authenticated user, through the app's security rules.
+ */
+export interface FirestoreSessionResult {
+    /**
+     * The uid the session was minted for — the calling user's real Firebase Auth uid.
+     */
+    readonly uid: FirebaseAuthUserId;
+    /**
+     * A Firebase Auth custom token to exchange via `signInWithCustomToken`. The user's stored
+     * `setCustomUserClaims` claims are spread at the TOP LEVEL of the exchanged ID token, so security
+     * rules reading `request.auth.token.<claim>` behave exactly as they do for the browser app.
+     */
+    readonly customToken: string;
+    /**
+     * An App Check attestation minted for the project's registered web app, for clients that cannot run
+     * a browser-only attestation provider (reCAPTCHA v3). Feed it to `initializeAppCheck` through a
+     * `CustomProvider`.
+     *
+     * Omitted when the app did not configure {@link SessionApiModuleConfig.appCheckAppId}.
+     */
+    readonly appCheckToken?: string;
+    /**
+     * When the session as a whole stops being usable — the earliest expiry among its credentials.
+     * A long-running client should re-fetch rather than assume one session covers the whole job.
+     */
+    readonly expiresAt: ISO8601DateString;
+}
+/**
+ * Mints the direct-Firestore session credential bundle returned by `SessionApiController`.
+ *
+ * ## Security
+ *
+ * This service hands out a valid web-app App Check token and a custom token for the caller's own uid.
+ * Two gates apply, in order:
+ *
+ * 1. The app-supplied {@link FirestoreSessionAdminPredicate} — the load-bearing check. **Fails closed**
+ *    when the app provides no predicate.
+ * 2. The OIDC scope requirement (default {@link FIRESTORE_SESSION_OIDC_SCOPE}) — defence in depth only.
+ *    It cannot stand alone: a non-OIDC caller carries no `scope` claim and every enforcement site in
+ *    this codebase treats that as "skip".
+ *
+ * The custom token is ALWAYS minted for `auth.uid`; there is no way to ask for someone else's session,
+ * so a granted session is exactly as privileged as the caller already is under Firestore rules.
+ */
+export declare class FirestoreSessionApiService {
+    private readonly _logger;
+    private readonly _app;
+    private readonly _config;
+    private readonly _adminPredicate;
+    constructor(app: admin.app.App, config?: SessionApiModuleConfig, adminPredicate?: FirestoreSessionAdminPredicate);
+    /**
+     * Mints a direct-Firestore session for the calling user after enforcing the admin predicate and the
+     * OIDC scope requirement.
+     *
+     * @param auth - The authenticated request's auth data (`req.auth`).
+     * @returns The credential bundle the client needs to connect to Firestore as this user.
+     * @throws {HttpsError} A `401` when the request carries no uid, or a `403` when either gate rejects the caller.
+     */
+    createFirestoreSession(auth: Maybe<FirebaseServerAuthData>): Promise<FirestoreSessionResult>;
+}

package/test/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/firebase-server/test",
-  "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/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",
     "@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.37.0"
+    "@dereekb/nestjs": "13.38.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/twilio/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@dereekb/firebase-server/twilio",
-  "version": "13.37.0",
+  "version": "13.38.0",
   "peerDependencies": {
-    "@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/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"
   },
   "exports": {
     "./package.json": "./package.json",

package/zoho/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/firebase-server/zoho",
-  "version": "13.37.0",
+  "version": "13.38.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.37.0",
-    "@dereekb/date": "13.37.0",
-    "@dereekb/model": "13.37.0",
-    "@dereekb/nestjs": "13.37.0",
-    "@dereekb/rxjs": "13.37.0",
-    "@dereekb/firebase": "13.37.0",
-    "@dereekb/firebase-server": "13.37.0",
-    "@dereekb/util": "13.37.0",
-    "@dereekb/zoho": "13.37.0",
+    "@dereekb/analytics": "13.38.0",
+    "@dereekb/date": "13.38.0",
+    "@dereekb/model": "13.38.0",
+    "@dereekb/nestjs": "13.38.0",
+    "@dereekb/rxjs": "13.38.0",
+    "@dereekb/firebase": "13.38.0",
+    "@dereekb/firebase-server": "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"