@dereekb/firebase-server 13.33.0 → 13.34.0

package/zoho/src/lib/zoho.accounts.firebase.d.ts

@@ -1,4 +1,4 @@
-import { type SystemStateFirestoreCollection } from '@dereekb/firebase';
+import { type FirestoreDocument, type SystemState, type SystemStateFirestoreCollectionLike, type SystemStateStoredData } from '@dereekb/firebase';
 import { type ZohoAccountsAccessTokenCacheService } from '@dereekb/zoho/nestjs';
 /**
  * Creates a {@link ZohoAccountsAccessTokenCacheService} backed by Firestore {@link SystemState} documents.
@@ -7,14 +7,21 @@ import { type ZohoAccountsAccessTokenCacheService } from '@dereekb/zoho/nestjs';
  * Tokens are stored in a single {@link SystemState} document (type {@link ZOHO_ACCESS_TOKEN_SYSTEM_STATE_TYPE})
  * and token updates/clears use Firestore transactions for concurrency safety.
  *
+ * The access token is a credential, so pass a SERVER-ONLY collection — a
+ * `systemStatePrivateFirestoreCollection()` from `@dereekb/firebase-server/model`, whose converter
+ * map registers {@link zohoAccessTokenSystemStateDataConverterFactory} and encrypts the token at
+ * rest. Passing an app's client-shared `systemStateCollection` still type-checks (for backwards
+ * compatibility) but requires the converter to be registered in the client-shared map, which drags
+ * `@dereekb/firebase-server` into browser builds.
+ *
  * @param systemStateCollection - The Firestore collection for system state documents.
  * @returns A cache service backed by Firestore system state documents.
  *
  * @example
  * ```ts
- * const cacheService = firebaseZohoAccountsAccessTokenCacheService(systemStateCollection);
+ * const cacheService = firebaseZohoAccountsAccessTokenCacheService(systemStatePrivateCollection);
  * const cache = cacheService.loadZohoAccessTokenCache('my-zoho-service');
  * const token = await cache.loadCachedToken();
  * ```
  */
-export declare function firebaseZohoAccountsAccessTokenCacheService(systemStateCollection: SystemStateFirestoreCollection): ZohoAccountsAccessTokenCacheService;
+export declare function firebaseZohoAccountsAccessTokenCacheService<D extends FirestoreDocument<SystemState<SystemStateStoredData>>>(systemStateCollection: SystemStateFirestoreCollectionLike<SystemStateStoredData, D>): ZohoAccountsAccessTokenCacheService;

package/zoho/src/lib/zoho.accounts.firebase.module.d.ts

@@ -0,0 +1,51 @@
+import { type ConfigService } from '@nestjs/config';
+import { type SystemStateStoredDataConverterMap } from '@dereekb/firebase';
+import { type FirebaseServerEnvService } from '@dereekb/firebase-server';
+import { type AES256GCMEncryptionSecret } from '@dereekb/nestjs';
+import { type ZohoAccessTokenSystemStateDataConverterConfig } from './zoho.accounts.firebase.system';
+/**
+ * Environment variable name for the Zoho access token cache encryption secret
+ * (hex-encoded AES-256 key).
+ *
+ * There is NO key rotation — `firestoreEncryptedField` resolves and validates the key once at
+ * converter construction and closes over it. Unlike the `uecp` and `oidcJwksKey` secrets, however,
+ * rotating this one is SURVIVABLE: the Zoho converter supplies an `onDecodeFailure` handler, so
+ * every entry written under the old key simply degrades to a cache miss and the next Zoho call
+ * re-mints a token. Rotation costs one extra token request per service key, not an outage.
+ */
+export declare const ZOHO_ACCESS_TOKEN_ENCRYPTION_SECRET_ENV_KEY = "ZOHO_ACCESS_TOKEN_ENCRYPTION_SECRET";
+/**
+ * Deterministic secret used when running in a testing environment and no real secret is configured,
+ * so specs never need a live credential.
+ *
+ * Deliberately distinct from the OIDC JWKS and UserExternalConnection testing secrets so a leaked
+ * emulator blob is attributable. ("Zoho Access Token Cache Test Key", hex-encoded.)
+ */
+export declare const TESTING_ZOHO_ACCESS_TOKEN_ENCRYPTION_SECRET: AES256GCMEncryptionSecret;
+/**
+ * Reads the Zoho access token encryption secret from the environment.
+ *
+ * @param configService - The Nest config service used to read the encryption secret.
+ * @param envService - Used to detect a testing environment for the secret fallback.
+ * @returns The validated encryption secret.
+ * @throws {Error} When the configured secret is invalid outside a testing environment.
+ */
+export declare function zohoAccessTokenEncryptionSecretFactory(configService: ConfigService, envService: FirebaseServerEnvService): AES256GCMEncryptionSecret;
+/**
+ * Builds the converter map entry for the Zoho access token cache, for use in a SERVER-ONLY
+ * SystemState converter map.
+ *
+ * @param config - The encryption configuration.
+ * @returns A partial converter map containing only the Zoho access token entry.
+ *
+ * @example
+ * ```typescript
+ * const collections = systemStatePrivateFirestoreCollection({
+ *   firestoreContext,
+ *   converters: {
+ *     ...zohoAccessTokenSystemStatePrivateConverterEntry({ encryptionSecret })
+ *   }
+ * });
+ * ```
+ */
+export declare function zohoAccessTokenSystemStatePrivateConverterEntry(config: ZohoAccessTokenSystemStateDataConverterConfig): SystemStateStoredDataConverterMap;

package/zoho/src/lib/zoho.accounts.firebase.system.d.ts

@@ -1,5 +1,6 @@
 import { type ZohoAccessToken, type ZohoServiceAccessTokenKey } from '@dereekb/zoho';
-import { type FirestoreDocumentAccessor, type SystemState, type SystemStateDocument, type SystemStateStoredData, type SystemStateStoredDataFieldConverterConfig } from '@dereekb/firebase';
+import { type FirestoreDocument, type FirestoreDocumentAccessor, type FirestoreModelFieldMapFunctionsConfig, type SystemState, type SystemStateDocument, type SystemStateStoredData, type SystemStateStoredDataFieldConverterConfig } from '@dereekb/firebase';
+import { type AES256GCMEncryptionSecretSource } from '@dereekb/nestjs';
 import { type Configurable } from '@dereekb/util';
 /**
  * {@link SystemState} type identifier for storing Zoho access tokens in Firestore.
@@ -15,7 +16,35 @@ export interface ZohoAccessTokenSystemStateEmbeddedToken extends Configurable<Zo
      */
     key: ZohoServiceAccessTokenKey;
 }
-export declare const zohoAccessTokenSystemStateEmbeddedTokenConverter: import("@dereekb/firebase").FirestoreSubObjectFieldMapFunctionsConfig<ZohoAccessTokenSystemStateEmbeddedToken, Partial<import("@dereekb/util").ReplaceType<ZohoAccessTokenSystemStateEmbeddedToken, import("@dereekb/util").MaybeMap<object>, any>>>;
+/**
+ * Configuration for the encrypted Zoho access token converters.
+ */
+export interface ZohoAccessTokenSystemStateDataConverterConfig {
+    /**
+     * Encryption secret source for the `accessToken` field.
+     */
+    readonly encryptionSecret: AES256GCMEncryptionSecretSource;
+}
+/**
+ * Creates the embedded-token converter, encrypting the `accessToken` at rest.
+ *
+ * This is a factory rather than a module-level const because `firestoreEncryptedField` resolves and
+ * validates the encryption key eagerly at construction — the secret must be known at runtime.
+ *
+ * ONLY `accessToken` is encrypted, deliberately. `firestoreEncryptedField` round-trips through
+ * `JSON.stringify`/`JSON.parse`, so anything placed inside the encrypted blob loses its type — and
+ * `expiresAt` is a `Date`. Encrypting the token string alone keeps every date outside the blob,
+ * which is what lets {@link zohoAccessTokenSystemStateDataConverterFactory} keep filtering expired
+ * entries without having to decrypt them first. Do not "improve" this by encrypting the whole
+ * token object or the `tokens` array.
+ *
+ * Accepted trade-off: `key`, `scope`, `apiDomain`, `expiresIn` and `expiresAt` remain plaintext at
+ * rest. None of them is a credential.
+ *
+ * @param config - The encryption configuration.
+ * @returns The embedded token field converter.
+ */
+export declare function zohoAccessTokenSystemStateEmbeddedTokenConverterFactory(config: ZohoAccessTokenSystemStateDataConverterConfig): FirestoreModelFieldMapFunctionsConfig<ZohoAccessTokenSystemStateEmbeddedToken, any>;
 /**
  * Data shape stored within a {@link SystemState} document for caching multiple Zoho access tokens.
  *
@@ -33,13 +62,17 @@ export interface ZohoAccessTokenSystemStateData extends SystemStateStoredData {
     lat: Date;
 }
 /**
- * Firestore field converter for {@link ZohoAccessTokenSystemStateData}.
+ * Creates the {@link ZohoAccessTokenSystemStateData} converter, encrypting each token's
+ * `accessToken` at rest.
+ *
+ * Register the result in a SERVER-ONLY converter map under {@link ZOHO_ACCESS_TOKEN_SYSTEM_STATE_TYPE} —
+ * see `systemStatePrivateFirestoreCollection()` in `@dereekb/firebase-server/model`. It must never be
+ * registered in an app's client-shared `SystemStateStoredDataConverterMap`.
  *
- * Automatically filters out expired tokens on read and enforces uniqueness by service key.
- * Must be registered in the app's {@link SystemStateStoredDataConverterMap} under
- * the {@link ZOHO_ACCESS_TOKEN_SYSTEM_STATE_TYPE} key.
+ * @param config - The encryption configuration.
+ * @returns The stored-data field converter.
  */
-export declare const zohoAccessTokenSystemStateDataConverter: SystemStateStoredDataFieldConverterConfig<ZohoAccessTokenSystemStateData>;
+export declare function zohoAccessTokenSystemStateDataConverterFactory(config: ZohoAccessTokenSystemStateDataConverterConfig): SystemStateStoredDataFieldConverterConfig<ZohoAccessTokenSystemStateData>;
 /**
  * Loads the {@link SystemStateDocument} that stores {@link ZohoAccessTokenSystemStateData},
  * using {@link ZOHO_ACCESS_TOKEN_SYSTEM_STATE_TYPE} as the document ID.
@@ -53,4 +86,14 @@ export declare const zohoAccessTokenSystemStateDataConverter: SystemStateStoredD
  * const data = await doc.snapshotData();
  * ```
  */
-export declare function loadZohoAccessTokenSystemState(accessor: FirestoreDocumentAccessor<SystemState<SystemStateStoredData>, SystemStateDocument<SystemStateStoredData>>): SystemStateDocument<ZohoAccessTokenSystemStateData>;
+export declare function loadZohoAccessTokenSystemState<D extends FirestoreDocument<SystemState<SystemStateStoredData>>>(accessor: FirestoreDocumentAccessor<SystemState<SystemStateStoredData>, D>): SystemStateDocument<ZohoAccessTokenSystemStateData>;
+/**
+ * @deprecated stores the access token in PLAINTEXT. Use
+ * {@link zohoAccessTokenSystemStateEmbeddedTokenConverterFactory} instead, which encrypts it at rest.
+ */
+export declare const zohoAccessTokenSystemStateEmbeddedTokenConverter: import("@dereekb/firebase").FirestoreSubObjectFieldMapFunctionsConfig<ZohoAccessTokenSystemStateEmbeddedToken, Partial<import("@dereekb/util").ReplaceType<ZohoAccessTokenSystemStateEmbeddedToken, import("@dereekb/util").MaybeMap<object>, any>>>;
+/**
+ * @deprecated stores access tokens in PLAINTEXT. Use {@link zohoAccessTokenSystemStateDataConverterFactory}
+ * instead, and register it on a server-only SystemStatePrivate collection.
+ */
+export declare const zohoAccessTokenSystemStateDataConverter: SystemStateStoredDataFieldConverterConfig<ZohoAccessTokenSystemStateData>;