@dereekb/firebase-server 13.36.0 → 13.38.0

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/index.cjs.js

@@ -824,7 +824,7 @@ function _ts_generator$a(thisArg, body) {
         auth_time: decoded.iat,
         firebase: (_ref = (_decoded_claims = decoded.claims) === null || _decoded_claims === void 0 ? void 0 : _decoded_claims.firebase) !== null && _ref !== void 0 ? _ref : {}
     });
-    delete decodedToken.claims; // remove the "claims" item if it exists.
+    delete decodedToken['claims']; // remove the "claims" item if it exists.
     return decodedToken;
 }
 /**
@@ -1318,8 +1318,8 @@ var adminEnvironmentInitialized = false;
  * @returns The newly generated project ID.
  */ function rollNewGCloudProjectEnvironmentVariable() {
     var projectId = generateNewProjectId();
-    process.env.GCLOUD_TEST_PROJECT = projectId;
-    process.env.GCLOUD_PROJECT = projectId;
+    process.env['GCLOUD_TEST_PROJECT'] = projectId;
+    process.env['GCLOUD_PROJECT'] = projectId;
     applyFirebaseGCloudTestProjectIdToFirebaseConfigEnv();
     return projectId;
 }
@@ -1330,7 +1330,7 @@ var adminEnvironmentInitialized = false;
  *
  * @returns The current value of `process.env.GCLOUD_PROJECT`, or `undefined` when unset.
  */ function getGCloudProjectId() {
-    return process.env.GCLOUD_PROJECT;
+    return process.env['GCLOUD_PROJECT'];
 }
 /**
  * Reads the current `GCLOUD_TEST_PROJECT` environment variable.
@@ -1341,7 +1341,7 @@ var adminEnvironmentInitialized = false;
  *
  * @returns The current value of `process.env.GCLOUD_TEST_PROJECT`, or `undefined` when unset.
  */ function getGCloudTestProjectId() {
-    return process.env.GCLOUD_TEST_PROJECT;
+    return process.env['GCLOUD_TEST_PROJECT'];
 }
 /**
  * Applies the current GCLOUD_PROJECT to FIREBASE_CONFIG.
@@ -1360,10 +1360,10 @@ var adminEnvironmentInitialized = false;
     if (!testProjectId) {
         throw new Error('No test project id was available in the environment. Did you call initFirebaseAdminTestEnvironment() first?');
     }
-    var config = JSON.parse((_process_env_FIREBASE_CONFIG = process.env.FIREBASE_CONFIG) !== null && _process_env_FIREBASE_CONFIG !== void 0 ? _process_env_FIREBASE_CONFIG : '{}');
+    var config = JSON.parse((_process_env_FIREBASE_CONFIG = process.env['FIREBASE_CONFIG']) !== null && _process_env_FIREBASE_CONFIG !== void 0 ? _process_env_FIREBASE_CONFIG : '{}');
     config.projectId = testProjectId;
-    process.env.FIREBASE_CONFIG = JSON.stringify(config);
-    process.env.GCLOUD_PROJECT = testProjectId; // re-apply to GCLOUD_PROJECT too
+    process.env['FIREBASE_CONFIG'] = JSON.stringify(config);
+    process.env['GCLOUD_PROJECT'] = testProjectId; // re-apply to GCLOUD_PROJECT too
     return testProjectId;
 }
 /**

package/test/index.esm.js

@@ -823,7 +823,7 @@ function _ts_generator$a(thisArg, body) {
         auth_time: decoded.iat,
         firebase: (_ref = (_decoded_claims = decoded.claims) === null || _decoded_claims === void 0 ? void 0 : _decoded_claims.firebase) !== null && _ref !== void 0 ? _ref : {}
     });
-    delete decodedToken.claims; // remove the "claims" item if it exists.
+    delete decodedToken['claims']; // remove the "claims" item if it exists.
     return decodedToken;
 }
 /**
@@ -1317,8 +1317,8 @@ var adminEnvironmentInitialized = false;
  * @returns The newly generated project ID.
  */ function rollNewGCloudProjectEnvironmentVariable() {
     var projectId = generateNewProjectId();
-    process.env.GCLOUD_TEST_PROJECT = projectId;
-    process.env.GCLOUD_PROJECT = projectId;
+    process.env['GCLOUD_TEST_PROJECT'] = projectId;
+    process.env['GCLOUD_PROJECT'] = projectId;
     applyFirebaseGCloudTestProjectIdToFirebaseConfigEnv();
     return projectId;
 }
@@ -1329,7 +1329,7 @@ var adminEnvironmentInitialized = false;
  *
  * @returns The current value of `process.env.GCLOUD_PROJECT`, or `undefined` when unset.
  */ function getGCloudProjectId() {
-    return process.env.GCLOUD_PROJECT;
+    return process.env['GCLOUD_PROJECT'];
 }
 /**
  * Reads the current `GCLOUD_TEST_PROJECT` environment variable.
@@ -1340,7 +1340,7 @@ var adminEnvironmentInitialized = false;
  *
  * @returns The current value of `process.env.GCLOUD_TEST_PROJECT`, or `undefined` when unset.
  */ function getGCloudTestProjectId() {
-    return process.env.GCLOUD_TEST_PROJECT;
+    return process.env['GCLOUD_TEST_PROJECT'];
 }
 /**
  * Applies the current GCLOUD_PROJECT to FIREBASE_CONFIG.
@@ -1359,10 +1359,10 @@ var adminEnvironmentInitialized = false;
     if (!testProjectId) {
         throw new Error('No test project id was available in the environment. Did you call initFirebaseAdminTestEnvironment() first?');
     }
-    var config = JSON.parse((_process_env_FIREBASE_CONFIG = process.env.FIREBASE_CONFIG) !== null && _process_env_FIREBASE_CONFIG !== void 0 ? _process_env_FIREBASE_CONFIG : '{}');
+    var config = JSON.parse((_process_env_FIREBASE_CONFIG = process.env['FIREBASE_CONFIG']) !== null && _process_env_FIREBASE_CONFIG !== void 0 ? _process_env_FIREBASE_CONFIG : '{}');
     config.projectId = testProjectId;
-    process.env.FIREBASE_CONFIG = JSON.stringify(config);
-    process.env.GCLOUD_PROJECT = testProjectId; // re-apply to GCLOUD_PROJECT too
+    process.env['FIREBASE_CONFIG'] = JSON.stringify(config);
+    process.env['GCLOUD_PROJECT'] = testProjectId; // re-apply to GCLOUD_PROJECT too
     return testProjectId;
 }
 /**

package/test/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/firebase-server/test",
-  "version": "13.36.0",
+  "version": "13.38.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.36.0",
-    "@dereekb/date": "13.36.0",
-    "@dereekb/firebase": "13.36.0",
-    "@dereekb/firebase-server": "13.36.0",
-    "@dereekb/firebase-server/oidc": "13.36.0",
-    "@dereekb/model": "13.36.0",
-    "@dereekb/nestjs": "13.36.0",
-    "@dereekb/rxjs": "13.36.0",
-    "@dereekb/util": "13.36.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.36.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.36.0",
+  "version": "13.38.0",
   "peerDependencies": {
-    "@dereekb/date": "13.36.0",
-    "@dereekb/firebase": "13.36.0",
-    "@dereekb/firebase-server": "13.36.0",
-    "@dereekb/model": "13.36.0",
-    "@dereekb/nestjs": "13.36.0",
-    "@dereekb/rxjs": "13.36.0",
-    "@dereekb/util": "13.36.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.36.0",
+  "version": "13.38.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.36.0",
-    "@dereekb/date": "13.36.0",
-    "@dereekb/model": "13.36.0",
-    "@dereekb/nestjs": "13.36.0",
-    "@dereekb/rxjs": "13.36.0",
-    "@dereekb/firebase": "13.36.0",
-    "@dereekb/firebase-server": "13.36.0",
-    "@dereekb/util": "13.36.0",
-    "@dereekb/zoho": "13.36.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"