@dereekb/firebase-server 13.33.0 → 13.34.0

package/model/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@dereekb/firebase-server/model",
-  "version": "13.33.0",
+  "version": "13.34.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.33.0",
-    "@dereekb/date": "13.33.0",
-    "@dereekb/firebase": "13.33.0",
-    "@dereekb/firebase-server": "13.33.0",
-    "@dereekb/model": "13.33.0",
-    "@dereekb/nestjs": "13.33.0",
-    "@dereekb/rxjs": "13.33.0",
-    "@dereekb/util": "13.33.0",
+    "@dereekb/analytics": "13.34.0",
+    "@dereekb/date": "13.34.0",
+    "@dereekb/firebase": "13.34.0",
+    "@dereekb/firebase-server": "13.34.0",
+    "@dereekb/model": "13.34.0",
+    "@dereekb/nestjs": "13.34.0",
+    "@dereekb/rxjs": "13.34.0",
+    "@dereekb/util": "13.34.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "archiver": "^7.0.1",

package/model/src/lib/index.d.ts

@@ -1,4 +1,5 @@
 export * from './mailgun';
 export * from './notification';
 export * from './storagefile';
+export * from './system';
 export * from './userexternalconnection';

package/model/src/lib/system/index.d.ts

@@ -0,0 +1,2 @@
+export * from './system.private';
+export * from './system.private.module';

package/model/src/lib/system/system.private.d.ts

@@ -0,0 +1,63 @@
+import { type Maybe } from '@dereekb/util';
+import { AbstractFirestoreDocument, type CollectionReference, type FirestoreCollection, type FirestoreContext, type SystemState, type SystemStateStoredData, type SystemStateStoredDataConverterMap, type SystemStateUnknownTypeBehavior } from '@dereekb/firebase';
+/**
+ * Provides access to the {@link SystemStatePrivate} collection.
+ *
+ * Provided ONLY by a server module. This is deliberately never declared on an app's shared
+ * `FirestoreCollections` class: `provideAppFirestoreCollections()` hard-codes a
+ * `(context: FirestoreContext) => T` factory, which cannot carry the encryption secrets a private
+ * converter needs — so the private collection structurally cannot leak into the client-shared
+ * collection set.
+ */
+export declare abstract class SystemStatePrivateFirestoreCollections {
+    abstract readonly systemStatePrivateCollection: SystemStatePrivateFirestoreCollection;
+}
+/**
+ * Firestore model identity for {@link SystemStatePrivate} documents.
+ *
+ * The server-only counterpart of `systemStateIdentity` from `@dereekb/firebase`. Same document
+ * shape, same "document id is the type identifier" singleton convention — but a separate `sysp`
+ * collection, so a secret-bearing document is never reachable through the client-shared SystemState
+ * collection or the generic admin model service registered against it.
+ *
+ * This is a server-side only model. It has no provisions for client-side access, and deliberately
+ * has NO `firestore.rules` match block — the implicit default-deny is what denies every client, and
+ * a block here would only create an opportunity to grant access by accident.
+ */
+export declare const systemStatePrivateIdentity: import("@dereekb/firebase").RootFirestoreModelIdentity<"systemStatePrivate", "sysp">;
+export declare class SystemStatePrivateDocument<T extends SystemStateStoredData = SystemStateStoredData> extends AbstractFirestoreDocument<SystemState<T>, SystemStatePrivateDocument<T>, typeof systemStatePrivateIdentity> {
+    get modelIdentity(): import("@dereekb/firebase").RootFirestoreModelIdentity<"systemStatePrivate", "sysp">;
+}
+/**
+ * Returns the Firestore {@link CollectionReference} for {@link SystemStatePrivate} documents.
+ *
+ * @param context - The Firestore context to create the collection reference from.
+ * @returns The typed collection reference.
+ */
+export declare function systemStatePrivateCollectionReference(context: FirestoreContext): CollectionReference<SystemState>;
+export type SystemStatePrivateFirestoreCollection<T extends SystemStateStoredData = SystemStateStoredData> = FirestoreCollection<SystemState<T>, SystemStatePrivateDocument<T>>;
+/**
+ * Configuration for creating a {@link SystemStatePrivateFirestoreCollection}.
+ */
+export interface SystemStatePrivateFirestoreCollectionConfig {
+    readonly firestoreContext: FirestoreContext;
+    /**
+     * Server-only stored-data converters, keyed by SystemStateTypeIdentifier.
+     */
+    readonly converters: SystemStateStoredDataConverterMap;
+    /**
+     * Behavior when a document's type has no registered converter. Defaults to `error`.
+     *
+     * A private type that was not registered must never silently pass through — that would read a
+     * secret-bearing document without its field mapping, returning encrypted fields as raw ciphertext
+     * and dates as raw `Timestamp`s, with nothing to signal it.
+     */
+    readonly unknownTypeBehavior?: Maybe<SystemStateUnknownTypeBehavior>;
+}
+/**
+ * Creates a {@link SystemStatePrivateFirestoreCollection}.
+ *
+ * @param config - The Firestore context, converters, and unknown-type behavior.
+ * @returns The configured server-only SystemState collection.
+ */
+export declare function systemStatePrivateFirestoreCollection(config: SystemStatePrivateFirestoreCollectionConfig): SystemStatePrivateFirestoreCollection;

package/model/src/lib/system/system.private.module.d.ts

@@ -0,0 +1,70 @@
+import { type ModuleMetadata, type Provider } from '@nestjs/common';
+import { type Maybe } from '@dereekb/util';
+import { type FirestoreContext, type SystemStateStoredDataConverterMap, type SystemStateUnknownTypeBehavior } from '@dereekb/firebase';
+import { SystemStatePrivateFirestoreCollections } from './system.private';
+/**
+ * Configuration for the {@link SystemStatePrivateFirestoreCollections} provider.
+ */
+export declare abstract class SystemStatePrivateModuleConfig {
+    /**
+     * Server-only stored-data converters, keyed by SystemStateTypeIdentifier.
+     *
+     * Secret-bearing converters are built by the app, which owns its own `ConfigService`/env access —
+     * the framework never sees the secrets.
+     */
+    abstract readonly converters: SystemStateStoredDataConverterMap;
+    /**
+     * Behavior when a document's type has no registered converter. Defaults to `error`.
+     */
+    abstract readonly unknownTypeBehavior?: Maybe<SystemStateUnknownTypeBehavior>;
+}
+/**
+ * Creates the {@link SystemStatePrivateFirestoreCollections}.
+ *
+ * This is a bespoke provider rather than a `provideAppFirestoreCollections()` entry because that
+ * helper hard-codes a `(context: FirestoreContext) => T` factory and cannot carry the converters
+ * (and therefore the encryption secrets) this collection needs.
+ *
+ * @param firestoreContext - The Firestore context.
+ * @param config - The module configuration carrying the server-only converters.
+ * @returns The server-only collections.
+ */
+export declare function systemStatePrivateFirestoreCollectionsFactory(firestoreContext: FirestoreContext, config: SystemStatePrivateModuleConfig): SystemStatePrivateFirestoreCollections;
+/**
+ * Configuration for {@link appSystemStatePrivateModuleMetadata}.
+ */
+export interface ProvideAppSystemStatePrivateModuleMetadataConfig extends Pick<ModuleMetadata, 'imports' | 'exports' | 'providers'> {
+    /**
+     * Provider for {@link SystemStatePrivateModuleConfig}.
+     *
+     * The app declares this so it can inject its own `ConfigService`/env service and build each
+     * secret-bearing converter itself.
+     */
+    readonly configProvider: Provider;
+}
+/**
+ * Generates NestJS {@link ModuleMetadata} for an app's server-only SystemState module.
+ *
+ * IMPORTANT: do NOT add {@link SystemStatePrivateFirestoreCollections} to an app's shared
+ * `FirestoreCollections` class. Keeping it on its own provider is what stops the private collection
+ * from reaching client-shared code.
+ *
+ * @param config - The app's config provider plus optional additional module metadata.
+ * @returns Module metadata ready for the `@Module()` decorator.
+ *
+ * @example
+ * ```typescript
+ * @Module(
+ *   appSystemStatePrivateModuleMetadata({
+ *     configProvider: {
+ *       provide: SystemStatePrivateModuleConfig,
+ *       useFactory: myConfigFactory,
+ *       inject: [ConfigService, FirebaseServerEnvService]
+ *     },
+ *     imports: [ConfigModule]
+ *   })
+ * )
+ * export class AppSystemStatePrivateModule {}
+ * ```
+ */
+export declare function appSystemStatePrivateModuleMetadata(config: ProvideAppSystemStatePrivateModuleMetadataConfig): ModuleMetadata;

package/oidc/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/firebase-server/oidc",
-  "version": "13.33.0",
+  "version": "13.34.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.33.0",
-    "@dereekb/date": "13.33.0",
-    "@dereekb/firebase": "13.33.0",
-    "@dereekb/firebase-server": "13.33.0",
-    "@dereekb/model": "13.33.0",
-    "@dereekb/nestjs": "13.33.0",
-    "@dereekb/rxjs": "13.33.0",
-    "@dereekb/util": "13.33.0",
-    "@dereekb/zoho": "13.33.0",
+    "@dereekb/analytics": "13.34.0",
+    "@dereekb/date": "13.34.0",
+    "@dereekb/firebase": "13.34.0",
+    "@dereekb/firebase-server": "13.34.0",
+    "@dereekb/model": "13.34.0",
+    "@dereekb/nestjs": "13.34.0",
+    "@dereekb/rxjs": "13.34.0",
+    "@dereekb/util": "13.34.0",
+    "@dereekb/zoho": "13.34.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.33.0",
+  "version": "13.34.0",
   "sideEffects": false,
   "exports": {
     "./test": {
@@ -69,17 +69,17 @@
   "types": "./src/index.d.ts",
   "peerDependencies": {
     "@cantoo/pdf-lib": "^2.6.5",
-    "@dereekb/analytics": "13.33.0",
-    "@dereekb/calcom": "13.33.0",
-    "@dereekb/date": "13.33.0",
-    "@dereekb/dbx-core": "13.33.0",
-    "@dereekb/discord": "13.33.0",
-    "@dereekb/firebase": "13.33.0",
-    "@dereekb/model": "13.33.0",
-    "@dereekb/nestjs": "13.33.0",
-    "@dereekb/rxjs": "13.33.0",
-    "@dereekb/util": "13.33.0",
-    "@dereekb/zoho": "13.33.0",
+    "@dereekb/analytics": "13.34.0",
+    "@dereekb/calcom": "13.34.0",
+    "@dereekb/date": "13.34.0",
+    "@dereekb/dbx-core": "13.34.0",
+    "@dereekb/discord": "13.34.0",
+    "@dereekb/firebase": "13.34.0",
+    "@dereekb/model": "13.34.0",
+    "@dereekb/nestjs": "13.34.0",
+    "@dereekb/rxjs": "13.34.0",
+    "@dereekb/util": "13.34.0",
+    "@dereekb/zoho": "13.34.0",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.19.0",
     "@modelcontextprotocol/sdk": "1.29.0",

package/src/lib/firestore/snapshot/snapshot.field.encrypt.d.ts

@@ -14,6 +14,18 @@ export interface FirestoreEncryptedFieldConfig<T> {
      * Default value when the field is missing from Firestore.
      */
     readonly default: GetterOrValue<T>;
+    /**
+     * Called when a stored value is present but cannot be decrypted — a wrong or rotated key, a
+     * corrupt value, or data written before the field was encrypted. Its return value is used in
+     * place of the decrypted value.
+     *
+     * When omitted the decode throws, which is the correct behavior for a field of record: a
+     * credential that silently becomes `undefined` is far worse than a loud failure.
+     *
+     * Only supply this for data that can be regenerated — a cache. See the Zoho access token cache,
+     * where an undecryptable entry is a cache miss and the next call re-mints the token.
+     */
+    readonly onDecodeFailure?: Maybe<(error: unknown, data: string) => T>;
 }
 /**
  * Configuration for an optional encrypted Firestore field.
@@ -25,13 +37,20 @@ export interface OptionalFirestoreEncryptedFieldConfig<T> {
      * Secret source for the encryption key.
      */
     readonly secret: GetterOrValue<string>;
+    /**
+     * Called when a stored value is present but cannot be decrypted. See
+     * {@link FirestoreEncryptedFieldConfig.onDecodeFailure}. When omitted the decode throws.
+     */
+    readonly onDecodeFailure?: Maybe<(error: unknown, data: string) => Maybe<T>>;
 }
 /**
  * Creates a Firestore field mapping that encrypts/decrypts a JSON-serializable value
  * using AES-256-GCM. The value is stored in Firestore as a base64-encoded string.
  *
- * The encryption key is resolved from the configured secret source on each read/write,
- * allowing for key rotation via environment variable changes.
+ * IMPORTANT: there is NO key rotation. `resolveEncryptionKey()` reads and validates the secret once,
+ * here at construction, and closes over the resulting key — changing the secret afterwards orphans
+ * every value already written with the old one. Rotation is only survivable for fields that supply
+ * {@link FirestoreEncryptedFieldConfig.onDecodeFailure} and hold regenerable data.
  *
  * @param config - Encryption field configuration.
  * @returns A field mapping configuration for encrypted values.

package/test/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/firebase-server/test",
-  "version": "13.33.0",
+  "version": "13.34.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.33.0",
-    "@dereekb/date": "13.33.0",
-    "@dereekb/firebase": "13.33.0",
-    "@dereekb/firebase-server": "13.33.0",
-    "@dereekb/firebase-server/oidc": "13.33.0",
-    "@dereekb/model": "13.33.0",
-    "@dereekb/nestjs": "13.33.0",
-    "@dereekb/rxjs": "13.33.0",
-    "@dereekb/util": "13.33.0",
+    "@dereekb/analytics": "13.34.0",
+    "@dereekb/date": "13.34.0",
+    "@dereekb/firebase": "13.34.0",
+    "@dereekb/firebase-server": "13.34.0",
+    "@dereekb/firebase-server/oidc": "13.34.0",
+    "@dereekb/model": "13.34.0",
+    "@dereekb/nestjs": "13.34.0",
+    "@dereekb/rxjs": "13.34.0",
+    "@dereekb/util": "13.34.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.33.0"
+    "@dereekb/nestjs": "13.34.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/twilio/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@dereekb/firebase-server/twilio",
-  "version": "13.33.0",
+  "version": "13.34.0",
   "peerDependencies": {
-    "@dereekb/date": "13.33.0",
-    "@dereekb/firebase": "13.33.0",
-    "@dereekb/firebase-server": "13.33.0",
-    "@dereekb/model": "13.33.0",
-    "@dereekb/nestjs": "13.33.0",
-    "@dereekb/rxjs": "13.33.0",
-    "@dereekb/util": "13.33.0"
+    "@dereekb/date": "13.34.0",
+    "@dereekb/firebase": "13.34.0",
+    "@dereekb/firebase-server": "13.34.0",
+    "@dereekb/model": "13.34.0",
+    "@dereekb/nestjs": "13.34.0",
+    "@dereekb/rxjs": "13.34.0",
+    "@dereekb/util": "13.34.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/zoho/README.md

@@ -6,3 +6,33 @@ for the generic `UserExternalConnection` OAuth framework — a controller, servi
 mount a per-user Zoho connect flow at `/oauth/zoho`. The two are independent: the cache holds one
 token for the whole app, while the connect flow stores per-user credentials on the private
 connection document.
+
+## Access token cache: server-only, encrypted at rest
+
+The cached access token is a credential, so back the cache with a **server-only** collection —
+`systemStatePrivateFirestoreCollection()` from `@dereekb/firebase-server/model`, which stores at
+`/sysp` and has no `firestore.rules` match block:
+
+```ts
+const collections = systemStatePrivateFirestoreCollection({
+  firestoreContext,
+  converters: {
+    ...zohoAccessTokenSystemStatePrivateConverterEntry({ encryptionSecret })
+  }
+});
+
+const cacheService = firebaseZohoAccountsAccessTokenCacheService(collections);
+```
+
+Supply `encryptionSecret` from `ZOHO_ACCESS_TOKEN_ENCRYPTION_SECRET` (see
+`zohoAccessTokenEncryptionSecretFactory`). Only the `accessToken` string is encrypted — `expiresAt`
+and the other metadata stay plaintext so expired entries can be filtered without decrypting.
+
+**Do not** register `zohoAccessTokenSystemStateDataConverter` (now deprecated) in an app's
+client-shared `SystemStateStoredDataConverterMap`. That converter stores the token in plaintext, and
+importing it from client-shared code drags `@dereekb/firebase-server` — and therefore
+`firebase-admin`, `@nestjs/*` and Node builtins — into the browser bundle, which is a hard
+resolution error rather than something a bundler can tree-shake away.
+
+Rotating `ZOHO_ACCESS_TOKEN_ENCRYPTION_SECRET` is survivable: entries written under the old key
+degrade to a cache miss and the next Zoho call re-mints a token.