@dereekb/firebase-server 13.33.0 → 13.34.0

package/zoho/index.cjs.js

@@ -1,57 +1,114 @@
 'use strict';
 
 var firebase = require('@dereekb/firebase');
+var firebaseServer = require('@dereekb/firebase-server');
 var util = require('@dereekb/util');
+var nestjs = require('@dereekb/nestjs');
 var zoho = require('@dereekb/zoho');
 var model = require('@dereekb/firebase-server/model');
 var date = require('@dereekb/date');
 var common = require('@nestjs/common');
-var nestjs = require('@dereekb/zoho/nestjs');
+var nestjs$1 = require('@dereekb/zoho/nestjs');
 var config = require('@nestjs/config');
-var firebaseServer = require('@dereekb/firebase-server');
 
 /**
  * {@link SystemState} type identifier for storing Zoho access tokens in Firestore.
  */ var ZOHO_ACCESS_TOKEN_SYSTEM_STATE_TYPE = 'zoho_access_token';
-var zohoAccessTokenSystemStateEmbeddedTokenConverter = firebase.firestoreSubObject({
-    objectField: {
-        fields: {
-            key: firebase.firestoreString(),
-            accessToken: firebase.firestoreString(),
-            scope: firebase.firestoreString(),
-            apiDomain: firebase.firestoreString(),
-            expiresIn: firebase.firestoreNumber({
-                default: 3600
-            }),
-            expiresAt: firebase.firestoreDate()
+/**
+ * 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.
+ */ function zohoAccessTokenSystemStateEmbeddedTokenConverterFactory(config) {
+    return firebase.firestoreSubObject({
+        objectField: {
+            fields: {
+                key: firebase.firestoreString(),
+                accessToken: firebaseServer.firestoreEncryptedField({
+                    secret: config.encryptionSecret,
+                    default: '',
+                    // This is a cache of ~1h tokens, so an undecryptable entry is a cache MISS, not an error.
+                    // The empty sentinel is dropped by the `tokens` filter, and the next Zoho call re-mints.
+                    // This is also what makes a rotated secret survivable here (unlike uecp/jwks).
+                    onDecodeFailure: function onDecodeFailure() {
+                        return '';
+                    }
+                }),
+                scope: firebase.firestoreString(),
+                apiDomain: firebase.firestoreString(),
+                expiresIn: firebase.firestoreNumber({
+                    default: 3600
+                }),
+                expiresAt: firebase.firestoreDate()
+            }
         }
-    }
-});
+    });
+}
 /**
  * Firestore field converter for {@link ZohoAccessTokenSystemStateData}.
  *
  * 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.
- */ var zohoAccessTokenSystemStateDataConverter = firebase.firestoreSubObject({
-    objectField: {
-        fields: {
-            tokens: firebase.firestoreObjectArray({
-                firestoreField: zohoAccessTokenSystemStateEmbeddedTokenConverter,
-                filterUnique: util.filterUniqueFunction(function(x) {
-                    return x.key;
+ */ /**
+ * Builds the {@link ZohoAccessTokenSystemStateData} converter around a given embedded-token converter.
+ *
+ * Shared by the encrypted factory and the deprecated plaintext const so the array's expiry filter and
+ * per-key dedup behavior can only ever be defined once.
+ *
+ * @param embeddedTokenConverter - The converter for each entry in the `tokens` array.
+ * @returns The stored-data field converter.
+ */ function zohoAccessTokenSystemStateDataConverterForEmbeddedTokenConverter(embeddedTokenConverter) {
+    return firebase.firestoreSubObject({
+        objectField: {
+            fields: {
+                tokens: firebase.firestoreObjectArray({
+                    firestoreField: embeddedTokenConverter,
+                    filterUnique: util.filterUniqueFunction(function(x) {
+                        return x.key;
+                    }),
+                    // `firestoreObjectArray` maps BEFORE it filters, so this runs on already-decoded entries.
+                    // The `accessToken` check is what drops an entry whose decryption failed (onDecodeFailure
+                    // leaves an empty string behind) — without it such an entry would surface as a token with
+                    // an empty secret rather than as a cache miss.
+                    filter: function filter(x) {
+                        return Boolean(x === null || x === void 0 ? void 0 : x.accessToken) && ((x === null || x === void 0 ? void 0 : x.expiresAt) ? !util.isPast(x.expiresAt) : true // filter out empty/expired values
+                        );
+                    }
                 }),
-                filter: function filter(x) {
-                    return (x === null || x === void 0 ? void 0 : x.expiresAt) ? !util.isPast(x.expiresAt) : true // filter out expired values or values that have no expiration
-                    ;
-                }
-            }),
-            lat: firebase.firestoreDate({
-                saveDefaultAsNow: true
-            })
+                lat: firebase.firestoreDate({
+                    saveDefaultAsNow: true
+                })
+            }
         }
-    }
-});
+    });
+}
+/**
+ * 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`.
+ *
+ * @param config - The encryption configuration.
+ * @returns The stored-data field converter.
+ */ function zohoAccessTokenSystemStateDataConverterFactory(config) {
+    return zohoAccessTokenSystemStateDataConverterForEmbeddedTokenConverter(zohoAccessTokenSystemStateEmbeddedTokenConverterFactory(config));
+}
 /**
  * Loads the {@link SystemStateDocument} that stores {@link ZohoAccessTokenSystemStateData},
  * using {@link ZOHO_ACCESS_TOKEN_SYSTEM_STATE_TYPE} as the document ID.
@@ -67,6 +124,28 @@ var zohoAccessTokenSystemStateEmbeddedTokenConverter = firebase.firestoreSubObje
  */ function loadZohoAccessTokenSystemState(accessor) {
     return accessor.loadDocumentForId(ZOHO_ACCESS_TOKEN_SYSTEM_STATE_TYPE);
 }
+// COMPAT: Deprecated aliases
+/**
+ * @deprecated stores the access token in PLAINTEXT. Use
+ * {@link zohoAccessTokenSystemStateEmbeddedTokenConverterFactory} instead, which encrypts it at rest.
+ */ var zohoAccessTokenSystemStateEmbeddedTokenConverter = firebase.firestoreSubObject({
+    objectField: {
+        fields: {
+            key: firebase.firestoreString(),
+            accessToken: firebase.firestoreString(),
+            scope: firebase.firestoreString(),
+            apiDomain: firebase.firestoreString(),
+            expiresIn: firebase.firestoreNumber({
+                default: 3600
+            }),
+            expiresAt: firebase.firestoreDate()
+        }
+    }
+});
+/**
+ * @deprecated stores access tokens in PLAINTEXT. Use {@link zohoAccessTokenSystemStateDataConverterFactory}
+ * instead, and register it on a server-only SystemStatePrivate collection.
+ */ var zohoAccessTokenSystemStateDataConverter = zohoAccessTokenSystemStateDataConverterForEmbeddedTokenConverter(zohoAccessTokenSystemStateEmbeddedTokenConverter);
 
 function _array_like_to_array$1(arr, len) {
     if (len == null || len > arr.length) len = arr.length;
@@ -105,7 +184,7 @@ function _async_to_generator$2(fn) {
         });
     };
 }
-function _define_property$4(obj, key, value) {
+function _define_property$5(obj, key, value) {
     if (key in obj) {
         Object.defineProperty(obj, key, {
             value: value,
@@ -134,7 +213,7 @@ function _object_spread$2(target) {
             }));
         }
         ownKeys.forEach(function(key) {
-            _define_property$4(target, key, source[key]);
+            _define_property$5(target, key, source[key]);
         });
     }
     return target;
@@ -275,12 +354,19 @@ function _ts_generator$2(thisArg, body) {
  * 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();
  * ```
@@ -456,6 +542,78 @@ function _ts_generator$2(thisArg, body) {
     return service;
 }
 
+function _define_property$4(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+// MARK: Environment Variable Keys
+/**
+ * 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.
+ */ var 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.)
+ */ var TESTING_ZOHO_ACCESS_TOKEN_ENCRYPTION_SECRET = '5a6f686f2041636365737320546f6b656e2043616368652054657374204b6579';
+// MARK: Config
+/**
+ * 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.
+ */ function zohoAccessTokenEncryptionSecretFactory(configService, envService) {
+    var _configService_get;
+    var encryptionSecret = (_configService_get = configService.get(ZOHO_ACCESS_TOKEN_ENCRYPTION_SECRET_ENV_KEY)) !== null && _configService_get !== void 0 ? _configService_get : '';
+    if (!nestjs.isValidAES256GCMEncryptionSecret(encryptionSecret)) {
+        if (envService.isTestingEnv) {
+            encryptionSecret = TESTING_ZOHO_ACCESS_TOKEN_ENCRYPTION_SECRET;
+        } else {
+            throw new Error("zohoAccessTokenEncryptionSecretFactory: The secret provided by ".concat(ZOHO_ACCESS_TOKEN_ENCRYPTION_SECRET_ENV_KEY, " is not valid. Expected a 64-character hexadecimal string."));
+        }
+    }
+    return encryptionSecret;
+}
+// MARK: Converter Map Entry
+/**
+ * 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 })
+ *   }
+ * });
+ * ```
+ */ function zohoAccessTokenSystemStatePrivateConverterEntry(config) {
+    return _define_property$4({}, ZOHO_ACCESS_TOKEN_SYSTEM_STATE_TYPE, zohoAccessTokenSystemStateDataConverterFactory(config));
+}
+
 function _type_of$3(obj) {
     "@swc/helpers - typeof";
     return obj && typeof Symbol !== "undefined" && obj.constructor === Symbol ? "symbol" : typeof obj;
@@ -1114,7 +1272,7 @@ exports.ZohoUserExternalConnectionOAuthService = __decorate([
     __param(1, common.Inject(model.UserExternalConnectionStateCoder)),
     __param(2, common.Inject(model.UserExternalConnectionServerActions)),
     __param(3, common.Inject(model.UserExternalConnectionAccessor)),
-    __param(4, common.Inject(nestjs.ZohoAccountsOAuthApi))
+    __param(4, common.Inject(nestjs$1.ZohoAccountsOAuthApi))
 ], exports.ZohoUserExternalConnectionOAuthService);
 
 function asyncGeneratorStep(gen, resolve, reject, _next, _throw, key, arg) {
@@ -1626,6 +1784,8 @@ function _unsupported_iterable_to_array(o, minLen) {
 }
 
 exports.DEFAULT_ZOHO_OAUTH_SCOPES = DEFAULT_ZOHO_OAUTH_SCOPES;
+exports.TESTING_ZOHO_ACCESS_TOKEN_ENCRYPTION_SECRET = TESTING_ZOHO_ACCESS_TOKEN_ENCRYPTION_SECRET;
+exports.ZOHO_ACCESS_TOKEN_ENCRYPTION_SECRET_ENV_KEY = ZOHO_ACCESS_TOKEN_ENCRYPTION_SECRET_ENV_KEY;
 exports.ZOHO_ACCESS_TOKEN_SYSTEM_STATE_TYPE = ZOHO_ACCESS_TOKEN_SYSTEM_STATE_TYPE;
 exports.ZOHO_EXTRA_ACCOUNTS_SERVER_KEY = ZOHO_EXTRA_ACCOUNTS_SERVER_KEY;
 exports.ZOHO_EXTRA_API_DOMAIN_KEY = ZOHO_EXTRA_API_DOMAIN_KEY;
@@ -1639,8 +1799,12 @@ exports.appZohoUserExternalConnectionOAuthModuleMetadata = appZohoUserExternalCo
 exports.firebaseZohoAccountsAccessTokenCacheService = firebaseZohoAccountsAccessTokenCacheService;
 exports.loadZohoAccessTokenSystemState = loadZohoAccessTokenSystemState;
 exports.userExternalConnectionZohoAccessTokenCache = userExternalConnectionZohoAccessTokenCache;
+exports.zohoAccessTokenEncryptionSecretFactory = zohoAccessTokenEncryptionSecretFactory;
 exports.zohoAccessTokenFromUserExternalConnectionCredentials = zohoAccessTokenFromUserExternalConnectionCredentials;
 exports.zohoAccessTokenSystemStateDataConverter = zohoAccessTokenSystemStateDataConverter;
+exports.zohoAccessTokenSystemStateDataConverterFactory = zohoAccessTokenSystemStateDataConverterFactory;
 exports.zohoAccessTokenSystemStateEmbeddedTokenConverter = zohoAccessTokenSystemStateEmbeddedTokenConverter;
+exports.zohoAccessTokenSystemStateEmbeddedTokenConverterFactory = zohoAccessTokenSystemStateEmbeddedTokenConverterFactory;
+exports.zohoAccessTokenSystemStatePrivateConverterEntry = zohoAccessTokenSystemStatePrivateConverterEntry;
 exports.zohoUserExternalConnectionCredentials = zohoUserExternalConnectionCredentials;
 exports.zohoUserExternalConnectionOAuthServiceConfigFactory = zohoUserExternalConnectionOAuthServiceConfigFactory;

package/zoho/index.esm.js

@@ -1,55 +1,112 @@
 import { firestoreSubObject, firestoreDate, firestoreNumber, firestoreString, firestoreObjectArray, ZOHO_USER_EXTERNAL_CONNECTION_PROVIDER_TYPE } from '@dereekb/firebase';
+import { firestoreEncryptedField, FirebaseServerEnvService } from '@dereekb/firebase-server';
 import { isPast, filterUniqueFunction, MS_IN_SECOND } from '@dereekb/util';
+import { isValidAES256GCMEncryptionSecret } from '@dereekb/nestjs';
 import { ZOHO_ACCOUNTS_PROFILE_READ_SCOPE, zohoAccountsConfigApiUrl, zohoAccountsAuthorizeUrlFactory, zohoOAuthScopesFromScopeString, zohoAccountsApiUrlKeyForApiUrl, ZOHO_ACCOUNTS_API_URLS, ZOHO_OAUTH_SCOPE_DELIMITER } from '@dereekb/zoho';
 import { userExternalConnectionOAuthControllerPath, userExternalConnectionOAuthRoutesForGlobalRouteExclude, userExternalConnectionOAuthServiceConfigFactory, UserExternalConnectionOAuthServiceConfig, UserExternalConnectionStateCoder, UserExternalConnectionServerActions, UserExternalConnectionAccessor, AbstractUserExternalConnectionOAuthService, mergeRefreshedUserExternalConnectionCredentials, AbstractUserExternalConnectionOAuthController } from '@dereekb/firebase-server/model';
 import { safeToJsDate } from '@dereekb/date';
 import { Injectable, Inject, Controller } from '@nestjs/common';
 import { ZohoAccountsOAuthApi } from '@dereekb/zoho/nestjs';
 import { ConfigModule } from '@nestjs/config';
-import { FirebaseServerEnvService } from '@dereekb/firebase-server';
 
 /**
  * {@link SystemState} type identifier for storing Zoho access tokens in Firestore.
  */ var ZOHO_ACCESS_TOKEN_SYSTEM_STATE_TYPE = 'zoho_access_token';
-var zohoAccessTokenSystemStateEmbeddedTokenConverter = firestoreSubObject({
-    objectField: {
-        fields: {
-            key: firestoreString(),
-            accessToken: firestoreString(),
-            scope: firestoreString(),
-            apiDomain: firestoreString(),
-            expiresIn: firestoreNumber({
-                default: 3600
-            }),
-            expiresAt: firestoreDate()
+/**
+ * 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.
+ */ function zohoAccessTokenSystemStateEmbeddedTokenConverterFactory(config) {
+    return firestoreSubObject({
+        objectField: {
+            fields: {
+                key: firestoreString(),
+                accessToken: firestoreEncryptedField({
+                    secret: config.encryptionSecret,
+                    default: '',
+                    // This is a cache of ~1h tokens, so an undecryptable entry is a cache MISS, not an error.
+                    // The empty sentinel is dropped by the `tokens` filter, and the next Zoho call re-mints.
+                    // This is also what makes a rotated secret survivable here (unlike uecp/jwks).
+                    onDecodeFailure: function onDecodeFailure() {
+                        return '';
+                    }
+                }),
+                scope: firestoreString(),
+                apiDomain: firestoreString(),
+                expiresIn: firestoreNumber({
+                    default: 3600
+                }),
+                expiresAt: firestoreDate()
+            }
         }
-    }
-});
+    });
+}
 /**
  * Firestore field converter for {@link ZohoAccessTokenSystemStateData}.
  *
  * 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.
- */ var zohoAccessTokenSystemStateDataConverter = firestoreSubObject({
-    objectField: {
-        fields: {
-            tokens: firestoreObjectArray({
-                firestoreField: zohoAccessTokenSystemStateEmbeddedTokenConverter,
-                filterUnique: filterUniqueFunction(function(x) {
-                    return x.key;
+ */ /**
+ * Builds the {@link ZohoAccessTokenSystemStateData} converter around a given embedded-token converter.
+ *
+ * Shared by the encrypted factory and the deprecated plaintext const so the array's expiry filter and
+ * per-key dedup behavior can only ever be defined once.
+ *
+ * @param embeddedTokenConverter - The converter for each entry in the `tokens` array.
+ * @returns The stored-data field converter.
+ */ function zohoAccessTokenSystemStateDataConverterForEmbeddedTokenConverter(embeddedTokenConverter) {
+    return firestoreSubObject({
+        objectField: {
+            fields: {
+                tokens: firestoreObjectArray({
+                    firestoreField: embeddedTokenConverter,
+                    filterUnique: filterUniqueFunction(function(x) {
+                        return x.key;
+                    }),
+                    // `firestoreObjectArray` maps BEFORE it filters, so this runs on already-decoded entries.
+                    // The `accessToken` check is what drops an entry whose decryption failed (onDecodeFailure
+                    // leaves an empty string behind) — without it such an entry would surface as a token with
+                    // an empty secret rather than as a cache miss.
+                    filter: function filter(x) {
+                        return Boolean(x === null || x === void 0 ? void 0 : x.accessToken) && ((x === null || x === void 0 ? void 0 : x.expiresAt) ? !isPast(x.expiresAt) : true // filter out empty/expired values
+                        );
+                    }
                 }),
-                filter: function filter(x) {
-                    return (x === null || x === void 0 ? void 0 : x.expiresAt) ? !isPast(x.expiresAt) : true // filter out expired values or values that have no expiration
-                    ;
-                }
-            }),
-            lat: firestoreDate({
-                saveDefaultAsNow: true
-            })
+                lat: firestoreDate({
+                    saveDefaultAsNow: true
+                })
+            }
         }
-    }
-});
+    });
+}
+/**
+ * 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`.
+ *
+ * @param config - The encryption configuration.
+ * @returns The stored-data field converter.
+ */ function zohoAccessTokenSystemStateDataConverterFactory(config) {
+    return zohoAccessTokenSystemStateDataConverterForEmbeddedTokenConverter(zohoAccessTokenSystemStateEmbeddedTokenConverterFactory(config));
+}
 /**
  * Loads the {@link SystemStateDocument} that stores {@link ZohoAccessTokenSystemStateData},
  * using {@link ZOHO_ACCESS_TOKEN_SYSTEM_STATE_TYPE} as the document ID.
@@ -65,6 +122,28 @@ var zohoAccessTokenSystemStateEmbeddedTokenConverter = firestoreSubObject({
  */ function loadZohoAccessTokenSystemState(accessor) {
     return accessor.loadDocumentForId(ZOHO_ACCESS_TOKEN_SYSTEM_STATE_TYPE);
 }
+// COMPAT: Deprecated aliases
+/**
+ * @deprecated stores the access token in PLAINTEXT. Use
+ * {@link zohoAccessTokenSystemStateEmbeddedTokenConverterFactory} instead, which encrypts it at rest.
+ */ var zohoAccessTokenSystemStateEmbeddedTokenConverter = firestoreSubObject({
+    objectField: {
+        fields: {
+            key: firestoreString(),
+            accessToken: firestoreString(),
+            scope: firestoreString(),
+            apiDomain: firestoreString(),
+            expiresIn: firestoreNumber({
+                default: 3600
+            }),
+            expiresAt: firestoreDate()
+        }
+    }
+});
+/**
+ * @deprecated stores access tokens in PLAINTEXT. Use {@link zohoAccessTokenSystemStateDataConverterFactory}
+ * instead, and register it on a server-only SystemStatePrivate collection.
+ */ var zohoAccessTokenSystemStateDataConverter = zohoAccessTokenSystemStateDataConverterForEmbeddedTokenConverter(zohoAccessTokenSystemStateEmbeddedTokenConverter);
 
 function _array_like_to_array$1(arr, len) {
     if (len == null || len > arr.length) len = arr.length;
@@ -103,7 +182,7 @@ function _async_to_generator$2(fn) {
         });
     };
 }
-function _define_property$4(obj, key, value) {
+function _define_property$5(obj, key, value) {
     if (key in obj) {
         Object.defineProperty(obj, key, {
             value: value,
@@ -132,7 +211,7 @@ function _object_spread$2(target) {
             }));
         }
         ownKeys.forEach(function(key) {
-            _define_property$4(target, key, source[key]);
+            _define_property$5(target, key, source[key]);
         });
     }
     return target;
@@ -273,12 +352,19 @@ function _ts_generator$2(thisArg, body) {
  * 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();
  * ```
@@ -454,6 +540,78 @@ function _ts_generator$2(thisArg, body) {
     return service;
 }
 
+function _define_property$4(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+// MARK: Environment Variable Keys
+/**
+ * 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.
+ */ var 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.)
+ */ var TESTING_ZOHO_ACCESS_TOKEN_ENCRYPTION_SECRET = '5a6f686f2041636365737320546f6b656e2043616368652054657374204b6579';
+// MARK: Config
+/**
+ * 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.
+ */ function zohoAccessTokenEncryptionSecretFactory(configService, envService) {
+    var _configService_get;
+    var encryptionSecret = (_configService_get = configService.get(ZOHO_ACCESS_TOKEN_ENCRYPTION_SECRET_ENV_KEY)) !== null && _configService_get !== void 0 ? _configService_get : '';
+    if (!isValidAES256GCMEncryptionSecret(encryptionSecret)) {
+        if (envService.isTestingEnv) {
+            encryptionSecret = TESTING_ZOHO_ACCESS_TOKEN_ENCRYPTION_SECRET;
+        } else {
+            throw new Error("zohoAccessTokenEncryptionSecretFactory: The secret provided by ".concat(ZOHO_ACCESS_TOKEN_ENCRYPTION_SECRET_ENV_KEY, " is not valid. Expected a 64-character hexadecimal string."));
+        }
+    }
+    return encryptionSecret;
+}
+// MARK: Converter Map Entry
+/**
+ * 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 })
+ *   }
+ * });
+ * ```
+ */ function zohoAccessTokenSystemStatePrivateConverterEntry(config) {
+    return _define_property$4({}, ZOHO_ACCESS_TOKEN_SYSTEM_STATE_TYPE, zohoAccessTokenSystemStateDataConverterFactory(config));
+}
+
 function _type_of$3(obj) {
     "@swc/helpers - typeof";
     return obj && typeof Symbol !== "undefined" && obj.constructor === Symbol ? "symbol" : typeof obj;
@@ -1623,4 +1781,4 @@ function _unsupported_iterable_to_array(o, minLen) {
     };
 }
 
-export { DEFAULT_ZOHO_OAUTH_SCOPES, ZOHO_ACCESS_TOKEN_SYSTEM_STATE_TYPE, ZOHO_EXTRA_ACCOUNTS_SERVER_KEY, ZOHO_EXTRA_API_DOMAIN_KEY, ZOHO_EXTRA_LOCATION_KEY, ZOHO_OAUTH_CALLBACK_ACCOUNTS_SERVER_PARAM, ZOHO_OAUTH_CALLBACK_LOCATION_PARAM, ZOHO_USER_EXTERNAL_CONNECTION_OAUTH_CONTROLLER_PATH, ZOHO_USER_EXTERNAL_CONNECTION_OAUTH_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE, ZohoUserExternalConnectionOAuthController, ZohoUserExternalConnectionOAuthService, ZohoUserExternalConnectionOAuthServiceConfig, appZohoUserExternalConnectionOAuthModuleMetadata, firebaseZohoAccountsAccessTokenCacheService, loadZohoAccessTokenSystemState, userExternalConnectionZohoAccessTokenCache, zohoAccessTokenFromUserExternalConnectionCredentials, zohoAccessTokenSystemStateDataConverter, zohoAccessTokenSystemStateEmbeddedTokenConverter, zohoUserExternalConnectionCredentials, zohoUserExternalConnectionOAuthServiceConfigFactory };
+export { DEFAULT_ZOHO_OAUTH_SCOPES, TESTING_ZOHO_ACCESS_TOKEN_ENCRYPTION_SECRET, ZOHO_ACCESS_TOKEN_ENCRYPTION_SECRET_ENV_KEY, ZOHO_ACCESS_TOKEN_SYSTEM_STATE_TYPE, ZOHO_EXTRA_ACCOUNTS_SERVER_KEY, ZOHO_EXTRA_API_DOMAIN_KEY, ZOHO_EXTRA_LOCATION_KEY, ZOHO_OAUTH_CALLBACK_ACCOUNTS_SERVER_PARAM, ZOHO_OAUTH_CALLBACK_LOCATION_PARAM, ZOHO_USER_EXTERNAL_CONNECTION_OAUTH_CONTROLLER_PATH, ZOHO_USER_EXTERNAL_CONNECTION_OAUTH_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE, ZohoUserExternalConnectionOAuthController, ZohoUserExternalConnectionOAuthService, ZohoUserExternalConnectionOAuthServiceConfig, appZohoUserExternalConnectionOAuthModuleMetadata, firebaseZohoAccountsAccessTokenCacheService, loadZohoAccessTokenSystemState, userExternalConnectionZohoAccessTokenCache, zohoAccessTokenEncryptionSecretFactory, zohoAccessTokenFromUserExternalConnectionCredentials, zohoAccessTokenSystemStateDataConverter, zohoAccessTokenSystemStateDataConverterFactory, zohoAccessTokenSystemStateEmbeddedTokenConverter, zohoAccessTokenSystemStateEmbeddedTokenConverterFactory, zohoAccessTokenSystemStatePrivateConverterEntry, zohoUserExternalConnectionCredentials, zohoUserExternalConnectionOAuthServiceConfigFactory };

package/zoho/package.json

@@ -1,17 +1,18 @@
 {
   "name": "@dereekb/firebase-server/zoho",
-  "version": "13.33.0",
+  "version": "13.34.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.33.0",
-    "@dereekb/date": "13.33.0",
-    "@dereekb/model": "13.33.0",
-    "@dereekb/nestjs": "13.33.0",
-    "@dereekb/rxjs": "13.33.0",
-    "@dereekb/firebase": "13.33.0",
-    "@dereekb/firebase-server": "13.33.0",
-    "@dereekb/util": "13.33.0",
-    "@dereekb/zoho": "13.33.0",
+    "@dereekb/analytics": "13.34.0",
+    "@dereekb/date": "13.34.0",
+    "@dereekb/model": "13.34.0",
+    "@dereekb/nestjs": "13.34.0",
+    "@dereekb/rxjs": "13.34.0",
+    "@dereekb/firebase": "13.34.0",
+    "@dereekb/firebase-server": "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"
   },
   "exports": {

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

@@ -1,4 +1,5 @@
 export * from './zoho.accounts.firebase';
+export * from './zoho.accounts.firebase.module';
 export * from './zoho.accounts.firebase.system';
 export * from './zoho.oauth.connection.cache';
 export * from './zoho.oauth.connection.config';