@dereekb/firebase-server 13.32.0 → 13.34.0

package/zoho/index.esm.js

@@ -1,48 +1,112 @@
-import { firestoreSubObject, firestoreDate, firestoreNumber, firestoreString, firestoreObjectArray } from '@dereekb/firebase';
-import { isPast, filterUniqueFunction } from '@dereekb/util';
+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';
 
 /**
  * {@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.
@@ -58,16 +122,38 @@ 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(arr, len) {
+function _array_like_to_array$1(arr, len) {
     if (len == null || len > arr.length) len = arr.length;
     for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
     return arr2;
 }
-function _array_without_holes(arr) {
-    if (Array.isArray(arr)) return _array_like_to_array(arr);
+function _array_without_holes$1(arr) {
+    if (Array.isArray(arr)) return _array_like_to_array$1(arr);
 }
-function asyncGeneratorStep(gen, resolve, reject, _next, _throw, key, arg) {
+function asyncGeneratorStep$2(gen, resolve, reject, _next, _throw, key, arg) {
     try {
         var info = gen[key](arg);
         var value = info.value;
@@ -81,22 +167,22 @@ function asyncGeneratorStep(gen, resolve, reject, _next, _throw, key, arg) {
         Promise.resolve(value).then(_next, _throw);
     }
 }
-function _async_to_generator(fn) {
+function _async_to_generator$2(fn) {
     return function() {
         var self = this, args = arguments;
         return new Promise(function(resolve, reject) {
             var gen = fn.apply(self, args);
             function _next(value) {
-                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "next", value);
+                asyncGeneratorStep$2(gen, resolve, reject, _next, _throw, "next", value);
             }
             function _throw(err) {
-                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "throw", err);
+                asyncGeneratorStep$2(gen, resolve, reject, _next, _throw, "throw", err);
             }
             _next(undefined);
         });
     };
 }
-function _define_property(obj, key, value) {
+function _define_property$5(obj, key, value) {
     if (key in obj) {
         Object.defineProperty(obj, key, {
             value: value,
@@ -109,13 +195,13 @@ function _define_property(obj, key, value) {
     }
     return obj;
 }
-function _iterable_to_array(iter) {
+function _iterable_to_array$1(iter) {
     if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
 }
-function _non_iterable_spread() {
+function _non_iterable_spread$1() {
     throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
 }
-function _object_spread(target) {
+function _object_spread$2(target) {
     for(var i = 1; i < arguments.length; i++){
         var source = arguments[i] != null ? arguments[i] : {};
         var ownKeys = Object.keys(source);
@@ -125,12 +211,12 @@ function _object_spread(target) {
             }));
         }
         ownKeys.forEach(function(key) {
-            _define_property(target, key, source[key]);
+            _define_property$5(target, key, source[key]);
         });
     }
     return target;
 }
-function ownKeys(object, enumerableOnly) {
+function ownKeys$2(object, enumerableOnly) {
     var keys = Object.keys(object);
     if (Object.getOwnPropertySymbols) {
         var symbols = Object.getOwnPropertySymbols(object);
@@ -138,29 +224,29 @@ function ownKeys(object, enumerableOnly) {
     }
     return keys;
 }
-function _object_spread_props(target, source) {
+function _object_spread_props$2(target, source) {
     source = source != null ? source : {};
     if (Object.getOwnPropertyDescriptors) {
         Object.defineProperties(target, Object.getOwnPropertyDescriptors(source));
     } else {
-        ownKeys(Object(source)).forEach(function(key) {
+        ownKeys$2(Object(source)).forEach(function(key) {
             Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key));
         });
     }
     return target;
 }
-function _to_consumable_array(arr) {
-    return _array_without_holes(arr) || _iterable_to_array(arr) || _unsupported_iterable_to_array(arr) || _non_iterable_spread();
+function _to_consumable_array$1(arr) {
+    return _array_without_holes$1(arr) || _iterable_to_array$1(arr) || _unsupported_iterable_to_array$1(arr) || _non_iterable_spread$1();
 }
-function _unsupported_iterable_to_array(o, minLen) {
+function _unsupported_iterable_to_array$1(o, minLen) {
     if (!o) return;
-    if (typeof o === "string") return _array_like_to_array(o, minLen);
+    if (typeof o === "string") return _array_like_to_array$1(o, minLen);
     var n = Object.prototype.toString.call(o).slice(8, -1);
     if (n === "Object" && o.constructor) n = o.constructor.name;
     if (n === "Map" || n === "Set") return Array.from(n);
-    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array(o, minLen);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$1(o, minLen);
 }
-function _ts_generator(thisArg, body) {
+function _ts_generator$2(thisArg, body) {
     var f, y, t, _ = {
         label: 0,
         sent: function() {
@@ -266,12 +352,19 @@ function _ts_generator(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();
  * ```
@@ -281,9 +374,9 @@ function _ts_generator(thisArg, body) {
         loadZohoAccessTokenCache: function loadZohoAccessTokenCache(serviceKey) {
             var cache = {
                 loadCachedToken: function loadCachedToken() {
-                    return _async_to_generator(function() {
+                    return _async_to_generator$2(function() {
                         var document, existingData, result, tokensArray;
-                        return _ts_generator(this, function(_state) {
+                        return _ts_generator$2(this, function(_state) {
                             switch(_state.label){
                                 case 0:
                                     document = loadZohoAccessTokenSystemState(systemStateDocumentAccessor);
@@ -309,17 +402,17 @@ function _ts_generator(thisArg, body) {
                     })();
                 },
                 updateCachedToken: function updateCachedToken(accessToken) {
-                    return _async_to_generator(function() {
-                        return _ts_generator(this, function(_state) {
+                    return _async_to_generator$2(function() {
+                        return _ts_generator$2(this, function(_state) {
                             switch(_state.label){
                                 case 0:
                                     // run in a transaction
                                     return [
                                         4,
                                         systemStateCollection.firestoreContext.runTransaction(function(transaction) {
-                                            return _async_to_generator(function() {
+                                            return _async_to_generator$2(function() {
                                                 var _ref, documentInTransaction, existingData, existingTokens, tokens, templateOrUpdate;
-                                                return _ts_generator(this, function(_state) {
+                                                return _ts_generator$2(this, function(_state) {
                                                     switch(_state.label){
                                                         case 0:
                                                             documentInTransaction = loadZohoAccessTokenSystemState(systemStateCollection.documentAccessorForTransaction(transaction));
@@ -331,11 +424,11 @@ function _ts_generator(thisArg, body) {
                                                             existingData = _state.sent();
                                                             existingTokens = (_ref = existingData === null || existingData === void 0 ? void 0 : existingData.data.tokens) !== null && _ref !== void 0 ? _ref : [];
                                                             tokens = // filter any potential old token for this service key
-                                                            _to_consumable_array(existingTokens.filter(function(x) {
+                                                            _to_consumable_array$1(existingTokens.filter(function(x) {
                                                                 return x.key !== serviceKey;
                                                             })).concat([
                                                                 // add the new token
-                                                                _object_spread_props(_object_spread({}, accessToken), {
+                                                                _object_spread_props$2(_object_spread$2({}, accessToken), {
                                                                     key: serviceKey
                                                                 })
                                                             ]);
@@ -386,16 +479,16 @@ function _ts_generator(thisArg, body) {
                     })();
                 },
                 clearCachedToken: function clearCachedToken() {
-                    return _async_to_generator(function() {
-                        return _ts_generator(this, function(_state) {
+                    return _async_to_generator$2(function() {
+                        return _ts_generator$2(this, function(_state) {
                             switch(_state.label){
                                 case 0:
                                     return [
                                         4,
                                         systemStateCollection.firestoreContext.runTransaction(function(transaction) {
-                                            return _async_to_generator(function() {
+                                            return _async_to_generator$2(function() {
                                                 var documentInTransaction, existingData, templateOrUpdate;
-                                                return _ts_generator(this, function(_state) {
+                                                return _ts_generator$2(this, function(_state) {
                                                     switch(_state.label){
                                                         case 0:
                                                             documentInTransaction = loadZohoAccessTokenSystemState(systemStateCollection.documentAccessorForTransaction(transaction));
@@ -447,4 +540,1245 @@ function _ts_generator(thisArg, body) {
     return service;
 }
 
-export { ZOHO_ACCESS_TOKEN_SYSTEM_STATE_TYPE, firebaseZohoAccountsAccessTokenCacheService, loadZohoAccessTokenSystemState, zohoAccessTokenSystemStateDataConverter, zohoAccessTokenSystemStateEmbeddedTokenConverter };
+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;
+}
+function __decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if ((typeof Reflect === "undefined" ? "undefined" : _type_of$3(Reflect)) === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+function __param(paramIndex, decorator) {
+    return function(target, key) {
+        decorator(target, key, paramIndex);
+    };
+}
+typeof SuppressedError === "function" ? SuppressedError : function(error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+};
+
+function _assert_this_initialized$2(self) {
+    if (self === void 0) {
+        throw new ReferenceError("this hasn't been initialised - super() hasn't been called");
+    }
+    return self;
+}
+function _call_super$2(_this, derived, args) {
+    derived = _get_prototype_of$2(derived);
+    return _possible_constructor_return$2(_this, _is_native_reflect_construct$2() ? Reflect.construct(derived, args || [], _get_prototype_of$2(_this).constructor) : derived.apply(_this, args));
+}
+function _class_call_check$2(instance, Constructor) {
+    if (!(instance instanceof Constructor)) {
+        throw new TypeError("Cannot call a class as a function");
+    }
+}
+function _define_property$3(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;
+}
+function _get_prototype_of$2(o) {
+    _get_prototype_of$2 = Object.setPrototypeOf ? Object.getPrototypeOf : function getPrototypeOf(o) {
+        return o.__proto__ || Object.getPrototypeOf(o);
+    };
+    return _get_prototype_of$2(o);
+}
+function _inherits$2(subClass, superClass) {
+    if (typeof superClass !== "function" && superClass !== null) {
+        throw new TypeError("Super expression must either be null or a function");
+    }
+    subClass.prototype = Object.create(superClass && superClass.prototype, {
+        constructor: {
+            value: subClass,
+            writable: true,
+            configurable: true
+        }
+    });
+    if (superClass) _set_prototype_of$2(subClass, superClass);
+}
+function _object_spread$1(target) {
+    for(var i = 1; i < arguments.length; i++){
+        var source = arguments[i] != null ? arguments[i] : {};
+        var ownKeys = Object.keys(source);
+        if (typeof Object.getOwnPropertySymbols === "function") {
+            ownKeys = ownKeys.concat(Object.getOwnPropertySymbols(source).filter(function(sym) {
+                return Object.getOwnPropertyDescriptor(source, sym).enumerable;
+            }));
+        }
+        ownKeys.forEach(function(key) {
+            _define_property$3(target, key, source[key]);
+        });
+    }
+    return target;
+}
+function ownKeys$1(object, enumerableOnly) {
+    var keys = Object.keys(object);
+    if (Object.getOwnPropertySymbols) {
+        var symbols = Object.getOwnPropertySymbols(object);
+        keys.push.apply(keys, symbols);
+    }
+    return keys;
+}
+function _object_spread_props$1(target, source) {
+    source = source != null ? source : {};
+    if (Object.getOwnPropertyDescriptors) {
+        Object.defineProperties(target, Object.getOwnPropertyDescriptors(source));
+    } else {
+        ownKeys$1(Object(source)).forEach(function(key) {
+            Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key));
+        });
+    }
+    return target;
+}
+function _possible_constructor_return$2(self, call) {
+    if (call && (_type_of$2(call) === "object" || typeof call === "function")) {
+        return call;
+    }
+    return _assert_this_initialized$2(self);
+}
+function _set_prototype_of$2(o, p) {
+    _set_prototype_of$2 = Object.setPrototypeOf || function setPrototypeOf(o, p) {
+        o.__proto__ = p;
+        return o;
+    };
+    return _set_prototype_of$2(o, p);
+}
+function _type_of$2(obj) {
+    "@swc/helpers - typeof";
+    return obj && typeof Symbol !== "undefined" && obj.constructor === Symbol ? "symbol" : typeof obj;
+}
+function _is_native_reflect_construct$2() {
+    try {
+        var result = !Boolean.prototype.valueOf.call(Reflect.construct(Boolean, [], function() {}));
+    } catch (_) {}
+    return (_is_native_reflect_construct$2 = function() {
+        return !!result;
+    })();
+}
+/**
+ * Controller path the Zoho external-connection OAuth endpoints are mounted at.
+ *
+ * Derived from the framework's path factory, the same expression the redirect URI and the
+ * global-prefix exclusion are built from, so the three cannot drift apart.
+ */ var ZOHO_USER_EXTERNAL_CONNECTION_OAUTH_CONTROLLER_PATH = userExternalConnectionOAuthControllerPath(ZOHO_USER_EXTERNAL_CONNECTION_PROVIDER_TYPE);
+/**
+ * Routes to exclude from an app's global API route prefix so the Zoho callback controller stays
+ * mounted at `/oauth/zoho/*`.
+ *
+ * Spread this into the `exclude` list of the app's `globalApiRoutePrefix` config, alongside
+ * `FIREBASE_SERVER_OIDC_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE`.
+ */ var ZOHO_USER_EXTERNAL_CONNECTION_OAUTH_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE = userExternalConnectionOAuthRoutesForGlobalRouteExclude(ZOHO_USER_EXTERNAL_CONNECTION_PROVIDER_TYPE);
+/**
+ * The scopes requested when an app does not declare its own.
+ *
+ * Declared in code, deliberately NOT read from the environment: the set to request follows from what
+ * the integration actually does, so it belongs where it is reviewable.
+ *
+ * Least privilege for a connect that proves the handoff and labels the connection: read the
+ * authorizing user's Zoho identity, and nothing else. No `ZohoCRM.*` / `ZohoRecruit.*` scope is
+ * requested because the default integration makes no product API call — requesting one would be
+ * privilege the code never uses, which is the same error as under-requesting, in the other
+ * direction. An app that actually calls a Zoho product declares its own set on the module metadata,
+ * in code.
+ *
+ * Unlike Cal.com, Zoho does not pre-register scopes on the OAuth client, so nothing has to be
+ * registered in the API console to request this.
+ */ var DEFAULT_ZOHO_OAUTH_SCOPES = [
+    ZOHO_ACCOUNTS_PROFILE_READ_SCOPE
+];
+/**
+ * Configuration for the {@link ZohoUserExternalConnectionOAuthService}.
+ *
+ * Extends the framework config with what is Zoho's own: which scopes to request, and which
+ * datacenter to authorize against.
+ */ var ZohoUserExternalConnectionOAuthServiceConfig = /*#__PURE__*/ function(UserExternalConnectionOAuthServiceConfig) {
+    _inherits$2(ZohoUserExternalConnectionOAuthServiceConfig, UserExternalConnectionOAuthServiceConfig);
+    function ZohoUserExternalConnectionOAuthServiceConfig() {
+        _class_call_check$2(this, ZohoUserExternalConnectionOAuthServiceConfig);
+        var _this;
+        _this = _call_super$2(this, ZohoUserExternalConnectionOAuthServiceConfig, arguments), _define_property$3(_this, "scopes", void 0), /**
+     * Datacenter to authorize against. Defaults to the api's configured one.
+     */ _define_property$3(_this, "accountsApiUrl", void 0);
+        return _this;
+    }
+    return ZohoUserExternalConnectionOAuthServiceConfig;
+}(UserExternalConnectionOAuthServiceConfig);
+/**
+ * Builds the Zoho connect flow's configuration from the app's configured origins.
+ *
+ * Nothing here is read from the environment as a value: the redirect URI is derived from the app's
+ * OAuth origin plus the mounted controller path, and the return URLs from the app URL plus
+ * code-declared paths. Registering Zoho therefore adds no deployment configuration beyond the client
+ * credentials the OAuth api already reads.
+ *
+ * @param config - The env service, the return paths, and the optional scope/datacenter overrides.
+ * @returns The validated service configuration.
+ */ function zohoUserExternalConnectionOAuthServiceConfigFactory(config) {
+    var envService = config.envService, successPath = config.successPath, failurePath = config.failurePath, scopes = config.scopes, accountsApiUrl = config.accountsApiUrl;
+    var baseConfig = userExternalConnectionOAuthServiceConfigFactory({
+        envService: envService,
+        providerType: ZOHO_USER_EXTERNAL_CONNECTION_PROVIDER_TYPE,
+        successPath: successPath,
+        failurePath: failurePath
+    });
+    return _object_spread_props$1(_object_spread$1({}, baseConfig), {
+        scopes: scopes !== null && scopes !== void 0 ? scopes : DEFAULT_ZOHO_OAUTH_SCOPES,
+        accountsApiUrl: accountsApiUrl
+    });
+}
+
+function _assert_this_initialized$1(self) {
+    if (self === void 0) {
+        throw new ReferenceError("this hasn't been initialised - super() hasn't been called");
+    }
+    return self;
+}
+function asyncGeneratorStep$1(gen, resolve, reject, _next, _throw, key, arg) {
+    try {
+        var info = gen[key](arg);
+        var value = info.value;
+    } catch (error) {
+        reject(error);
+        return;
+    }
+    if (info.done) {
+        resolve(value);
+    } else {
+        Promise.resolve(value).then(_next, _throw);
+    }
+}
+function _async_to_generator$1(fn) {
+    return function() {
+        var self = this, args = arguments;
+        return new Promise(function(resolve, reject) {
+            var gen = fn.apply(self, args);
+            function _next(value) {
+                asyncGeneratorStep$1(gen, resolve, reject, _next, _throw, "next", value);
+            }
+            function _throw(err) {
+                asyncGeneratorStep$1(gen, resolve, reject, _next, _throw, "throw", err);
+            }
+            _next(undefined);
+        });
+    };
+}
+function _call_super$1(_this, derived, args) {
+    derived = _get_prototype_of$1(derived);
+    return _possible_constructor_return$1(_this, _is_native_reflect_construct$1() ? Reflect.construct(derived, [], _get_prototype_of$1(_this).constructor) : derived.apply(_this, args));
+}
+function _class_call_check$1(instance, Constructor) {
+    if (!(instance instanceof Constructor)) {
+        throw new TypeError("Cannot call a class as a function");
+    }
+}
+function _defineProperties(target, props) {
+    for(var i = 0; i < props.length; i++){
+        var descriptor = props[i];
+        descriptor.enumerable = descriptor.enumerable || false;
+        descriptor.configurable = true;
+        if ("value" in descriptor) descriptor.writable = true;
+        Object.defineProperty(target, descriptor.key, descriptor);
+    }
+}
+function _create_class(Constructor, protoProps, staticProps) {
+    if (protoProps) _defineProperties(Constructor.prototype, protoProps);
+    return Constructor;
+}
+function _define_property$2(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;
+}
+function _get_prototype_of$1(o) {
+    _get_prototype_of$1 = Object.setPrototypeOf ? Object.getPrototypeOf : function getPrototypeOf(o) {
+        return o.__proto__ || Object.getPrototypeOf(o);
+    };
+    return _get_prototype_of$1(o);
+}
+function _inherits$1(subClass, superClass) {
+    if (typeof superClass !== "function" && superClass !== null) {
+        throw new TypeError("Super expression must either be null or a function");
+    }
+    subClass.prototype = Object.create(superClass && superClass.prototype, {
+        constructor: {
+            value: subClass,
+            writable: true,
+            configurable: true
+        }
+    });
+    if (superClass) _set_prototype_of$1(subClass, superClass);
+}
+function _possible_constructor_return$1(self, call) {
+    if (call && (_type_of$1(call) === "object" || typeof call === "function")) {
+        return call;
+    }
+    return _assert_this_initialized$1(self);
+}
+function _set_prototype_of$1(o, p) {
+    _set_prototype_of$1 = Object.setPrototypeOf || function setPrototypeOf(o, p) {
+        o.__proto__ = p;
+        return o;
+    };
+    return _set_prototype_of$1(o, p);
+}
+function _type_of$1(obj) {
+    "@swc/helpers - typeof";
+    return obj && typeof Symbol !== "undefined" && obj.constructor === Symbol ? "symbol" : typeof obj;
+}
+function _is_native_reflect_construct$1() {
+    try {
+        var result = !Boolean.prototype.valueOf.call(Reflect.construct(Boolean, [], function() {}));
+    } catch (_) {}
+    return (_is_native_reflect_construct$1 = function() {
+        return !!result;
+    })();
+}
+function _ts_generator$1(thisArg, body) {
+    var f, y, t, _ = {
+        label: 0,
+        sent: function() {
+            if (t[0] & 1) throw t[1];
+            return t[1];
+        },
+        trys: [],
+        ops: []
+    }, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype), d = Object.defineProperty;
+    return d(g, "next", {
+        value: verb(0)
+    }), d(g, "throw", {
+        value: verb(1)
+    }), d(g, "return", {
+        value: verb(2)
+    }), typeof Symbol === "function" && d(g, Symbol.iterator, {
+        value: function() {
+            return this;
+        }
+    }), g;
+    function verb(n) {
+        return function(v) {
+            return step([
+                n,
+                v
+            ]);
+        };
+    }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while(g && (g = 0, op[0] && (_ = 0)), _)try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [
+                op[0] & 2,
+                t.value
+            ];
+            switch(op[0]){
+                case 0:
+                case 1:
+                    t = op;
+                    break;
+                case 4:
+                    _.label++;
+                    return {
+                        value: op[1],
+                        done: false
+                    };
+                case 5:
+                    _.label++;
+                    y = op[1];
+                    op = [
+                        0
+                    ];
+                    continue;
+                case 7:
+                    op = _.ops.pop();
+                    _.trys.pop();
+                    continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) {
+                        _ = 0;
+                        continue;
+                    }
+                    if (op[0] === 3 && (!t || op[1] > t[0] && op[1] < t[3])) {
+                        _.label = op[1];
+                        break;
+                    }
+                    if (op[0] === 6 && _.label < t[1]) {
+                        _.label = t[1];
+                        t = op;
+                        break;
+                    }
+                    if (t && _.label < t[2]) {
+                        _.label = t[2];
+                        _.ops.push(op);
+                        break;
+                    }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop();
+                    continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) {
+            op = [
+                6,
+                e
+            ];
+            y = 0;
+        } finally{
+            f = t = 0;
+        }
+        if (op[0] & 5) throw op[1];
+        return {
+            value: op[0] ? op[1] : void 0,
+            done: true
+        };
+    }
+}
+/**
+ * The callback parameter naming the datacenter whose accounts server issued the code.
+ */ var ZOHO_OAUTH_CALLBACK_ACCOUNTS_SERVER_PARAM = 'accounts-server';
+/**
+ * The callback parameter naming the datacenter's short location code, e.g. `us`.
+ */ var ZOHO_OAUTH_CALLBACK_LOCATION_PARAM = 'location';
+/**
+ * `extra` key holding the api domain a Zoho access token is usable against.
+ *
+ * Named constants because these keys are written on connect and read back on refresh — a literal in
+ * one place and a typo in the other would silently send the refresh to the wrong datacenter.
+ */ var ZOHO_EXTRA_API_DOMAIN_KEY = 'apiDomain';
+/**
+ * `extra` key holding the accounts host a later refresh must be sent to.
+ */ var ZOHO_EXTRA_ACCOUNTS_SERVER_KEY = 'accountsServer';
+/**
+ * `extra` key holding Zoho's short location code for the datacenter.
+ */ var ZOHO_EXTRA_LOCATION_KEY = 'location';
+/**
+ * Maps an exchanged Zoho token response to the credentials stored on the private connection document.
+ *
+ * Two things differ from Cal.com's mapper. Zoho does not rotate its refresh token, so there is
+ * nothing to prefer over the token we already hold — and `refresh_token` can be ABSENT entirely on a
+ * re-consent, which is why it is passed through as `Maybe` rather than asserted (the framework's
+ * `credentialsRetainingStoredRefreshToken` is what keeps that from destroying a working token). And
+ * `api_domain` / `accountsServer` / `location` are retained in `extra`: a Zoho access token is only
+ * usable against the api domain it was issued for, and a later refresh must go back to the same
+ * datacenter's accounts server, so dropping them would leave the stored credentials unusable.
+ *
+ * @param input - The token response, the host it came from, and the identity when one was read.
+ * @returns The credentials to store.
+ */ function zohoUserExternalConnectionCredentials(input) {
+    var _ref, _ref1;
+    var response = input.response, accountsApiUrl = input.accountsApiUrl, location = input.location, userInfo = input.userInfo;
+    var access_token = response.access_token, refresh_token = response.refresh_token, expires_in = response.expires_in, scope = response.scope, api_domain = response.api_domain;
+    var now = Date.now();
+    var zuid = userInfo === null || userInfo === void 0 ? void 0 : userInfo.ZUID;
+    var _obj;
+    return {
+        accessToken: access_token,
+        // Maybe on purpose — absent on a re-consent that did not force the consent screen
+        refreshToken: refresh_token,
+        tokenType: 'Bearer',
+        issuedAt: new Date(now).toISOString(),
+        expiresAt: expires_in == null ? undefined : new Date(now + expires_in * MS_IN_SECOND).toISOString(),
+        scopes: zohoOAuthScopesFromScopeString(scope),
+        externalAccountId: zuid == null ? undefined : String(zuid),
+        label: (_ref = (_ref1 = userInfo === null || userInfo === void 0 ? void 0 : userInfo.Email) !== null && _ref1 !== void 0 ? _ref1 : userInfo === null || userInfo === void 0 ? void 0 : userInfo.Display_Name) !== null && _ref !== void 0 ? _ref : undefined,
+        extra: (_obj = {}, _define_property$2(_obj, ZOHO_EXTRA_API_DOMAIN_KEY, api_domain), _define_property$2(_obj, ZOHO_EXTRA_ACCOUNTS_SERVER_KEY, accountsApiUrl), _define_property$2(_obj, ZOHO_EXTRA_LOCATION_KEY, location), _obj)
+    };
+}
+/**
+ * Zoho's half of the external-connection authorization-code handoff.
+ *
+ * Everything else — resolving who is connecting, surfacing a refusal, retaining a refresh token the
+ * exchange did not return, persisting the credentials, choosing the redirect — is the framework's.
+ */ var ZohoUserExternalConnectionOAuthService = /*#__PURE__*/ function(AbstractUserExternalConnectionOAuthService) {
+    _inherits$1(ZohoUserExternalConnectionOAuthService, AbstractUserExternalConnectionOAuthService);
+    function ZohoUserExternalConnectionOAuthService(config, stateCoder, userExternalConnectionActions, userExternalConnectionAccessor, oauthApi) {
+        _class_call_check$1(this, ZohoUserExternalConnectionOAuthService);
+        var _this;
+        _this = _call_super$1(this, ZohoUserExternalConnectionOAuthService), _define_property$2(_this, "config", void 0), _define_property$2(_this, "stateCoder", void 0), _define_property$2(_this, "userExternalConnectionActions", void 0), _define_property$2(_this, "userExternalConnectionAccessor", void 0), _define_property$2(_this, "oauthApi", void 0), _define_property$2(_this, "authorizeUrlFactory", void 0), /**
+     * The accounts host this app authorizes against, and the fallback for an exchange whose callback
+     * named no usable one.
+     */ _define_property$2(_this, "accountsApiUrl", void 0);
+        _this.config = config;
+        _this.stateCoder = stateCoder;
+        _this.userExternalConnectionActions = userExternalConnectionActions;
+        _this.userExternalConnectionAccessor = userExternalConnectionAccessor;
+        _this.oauthApi = oauthApi;
+        var scopes = config.scopes, accountsApiUrl = config.accountsApiUrl, userExternalConnectionOAuth = config.userExternalConnectionOAuth;
+        // read through the api rather than injecting ZohoAccountsOAuthServiceConfig directly, which the
+        // OAuth module does not export to its dependents
+        _this.accountsApiUrl = accountsApiUrl == null ? oauthApi.apiUrl : zohoAccountsConfigApiUrl(accountsApiUrl);
+        _this.authorizeUrlFactory = zohoAccountsAuthorizeUrlFactory({
+            clientId: oauthApi.clientId,
+            redirectUri: userExternalConnectionOAuth.redirectUri,
+            scopes: scopes,
+            accountsApiUrl: _this.accountsApiUrl
+        });
+        return _this;
+    }
+    _create_class(ZohoUserExternalConnectionOAuthService, [
+        {
+            key: "authorizeUrlForState",
+            value: function authorizeUrlForState(state) {
+                return this.authorizeUrlFactory({
+                    state: state
+                });
+            }
+        },
+        {
+            key: "credentialsForAuthorizationCode",
+            value: function credentialsForAuthorizationCode(input) {
+                return _async_to_generator$1(function() {
+                    var _this_accountsApiUrlForCallbackQuery, code, redirectUri, query, accountsApiUrl, response, userInfo, e;
+                    return _ts_generator$1(this, function(_state) {
+                        switch(_state.label){
+                            case 0:
+                                code = input.code, redirectUri = input.redirectUri, query = input.query;
+                                accountsApiUrl = (_this_accountsApiUrlForCallbackQuery = this.accountsApiUrlForCallbackQuery(query)) !== null && _this_accountsApiUrlForCallbackQuery !== void 0 ? _this_accountsApiUrlForCallbackQuery : this.accountsApiUrl;
+                                return [
+                                    4,
+                                    this.oauthApi.exchangeAuthorizationCode({
+                                        code: code,
+                                        redirectUri: redirectUri,
+                                        accountsApiUrl: accountsApiUrl
+                                    })
+                                ];
+                            case 1:
+                                response = _state.sent();
+                                _state.label = 2;
+                            case 2:
+                                _state.trys.push([
+                                    2,
+                                    4,
+                                    ,
+                                    5
+                                ]);
+                                return [
+                                    4,
+                                    this.oauthApi.userInfo({
+                                        accessToken: response.access_token,
+                                        accountsApiUrl: accountsApiUrl
+                                    })
+                                ];
+                            case 3:
+                                userInfo = _state.sent();
+                                return [
+                                    3,
+                                    5
+                                ];
+                            case 4:
+                                e = _state.sent();
+                                this.logger.warn('Connected Zoho but could not read the identity to label the connection: ', e);
+                                return [
+                                    3,
+                                    5
+                                ];
+                            case 5:
+                                return [
+                                    2,
+                                    zohoUserExternalConnectionCredentials({
+                                        response: response,
+                                        accountsApiUrl: accountsApiUrl,
+                                        location: query === null || query === void 0 ? void 0 : query[ZOHO_OAUTH_CALLBACK_LOCATION_PARAM],
+                                        userInfo: userInfo
+                                    })
+                                ];
+                        }
+                    });
+                }).call(this);
+            }
+        },
+        {
+            key: "refreshCredentials",
+            value: function refreshCredentials(input) {
+                return _async_to_generator$1(function() {
+                    var _this_allowlistedAccountsApiUrl, credentials, refreshToken, extra, storedAccountsServer, accountsApiUrl, response, location;
+                    return _ts_generator$1(this, function(_state) {
+                        switch(_state.label){
+                            case 0:
+                                credentials = input.credentials;
+                                refreshToken = credentials.refreshToken, extra = credentials.extra;
+                                if (!refreshToken) {
+                                    throw new Error('ZohoUserExternalConnectionOAuthService.refreshCredentials: the stored credentials carry no refresh token.');
+                                }
+                                // the grant lives at ONE datacenter — a refresh token issued by `accounts.zoho.eu` is not honored
+                                // by `accounts.zoho.com` — so the stored accounts server is what the refresh must be sent to. It is
+                                // re-resolved through the allowlist rather than used verbatim: the value originally arrived on a
+                                // browser redirect, and it is the POST target the client secret travels to.
+                                storedAccountsServer = extra === null || extra === void 0 ? void 0 : extra[ZOHO_EXTRA_ACCOUNTS_SERVER_KEY];
+                                accountsApiUrl = (_this_allowlistedAccountsApiUrl = this.allowlistedAccountsApiUrl(storedAccountsServer == null ? undefined : String(storedAccountsServer))) !== null && _this_allowlistedAccountsApiUrl !== void 0 ? _this_allowlistedAccountsApiUrl : this.accountsApiUrl;
+                                return [
+                                    4,
+                                    this.oauthApi.refreshUserAccessToken({
+                                        refreshToken: refreshToken,
+                                        accountsApiUrl: accountsApiUrl
+                                    })
+                                ];
+                            case 1:
+                                response = _state.sent();
+                                // `location` is carried forward from the stored credentials rather than re-derived: it only ever
+                                // arrives on the callback, and the framework's merge would otherwise see an undefined value.
+                                location = extra === null || extra === void 0 ? void 0 : extra[ZOHO_EXTRA_LOCATION_KEY];
+                                // the response has no `refresh_token`, which the framework's merge retains — and `api_domain` may
+                                // legitimately differ from the one issued on connect, so it is taken from the response
+                                return [
+                                    2,
+                                    zohoUserExternalConnectionCredentials({
+                                        response: response,
+                                        accountsApiUrl: accountsApiUrl,
+                                        location: location == null ? undefined : String(location)
+                                    })
+                                ];
+                        }
+                    });
+                }).call(this);
+            }
+        },
+        {
+            /**
+     * The accounts host to exchange against, taken from Zoho's `accounts-server` callback parameter.
+     *
+     * @param query - The raw callback query.
+     * @returns The allowlisted accounts host the callback named, if any.
+     */ key: "accountsApiUrlForCallbackQuery",
+            value: function accountsApiUrlForCallbackQuery(query) {
+                return this.allowlistedAccountsApiUrl(query === null || query === void 0 ? void 0 : query[ZOHO_OAUTH_CALLBACK_ACCOUNTS_SERVER_PARAM]);
+            }
+        },
+        {
+            /**
+     * Resolves an untrusted accounts-host string back to one of the canonical Zoho hosts.
+     *
+     * Only an allowlisted Zoho host is honored. Every value passed here originated on a redirect an
+     * attacker can compose — either the live callback query or a value persisted from an earlier one —
+     * and it becomes the POST target the CLIENT SECRET is sent to, so an unchecked value would hand out
+     * the secret. Resolving through the allowlist rather than comparing to it also guarantees the host
+     * used is a canonical constant and never a caller-shaped variant of one. An unrecognized value is
+     * dropped (and logged) rather than trusted.
+     *
+     * @param accountsServer - The untrusted host string, if any.
+     * @returns The allowlisted accounts host, or null when there was none or it was not recognized.
+     */ key: "allowlistedAccountsApiUrl",
+            value: function allowlistedAccountsApiUrl(accountsServer) {
+                var result;
+                if (accountsServer) {
+                    var key = zohoAccountsApiUrlKeyForApiUrl(accountsServer);
+                    if (key == null) {
+                        this.logger.warn('Ignored an unrecognized Zoho accounts host of "'.concat(accountsServer, '"; using the configured host instead.'));
+                    } else {
+                        result = ZOHO_ACCOUNTS_API_URLS[key];
+                    }
+                }
+                return result;
+            }
+        }
+    ]);
+    return ZohoUserExternalConnectionOAuthService;
+}(AbstractUserExternalConnectionOAuthService);
+ZohoUserExternalConnectionOAuthService = __decorate([
+    Injectable(),
+    __param(0, Inject(ZohoUserExternalConnectionOAuthServiceConfig)),
+    __param(1, Inject(UserExternalConnectionStateCoder)),
+    __param(2, Inject(UserExternalConnectionServerActions)),
+    __param(3, Inject(UserExternalConnectionAccessor)),
+    __param(4, Inject(ZohoAccountsOAuthApi))
+], ZohoUserExternalConnectionOAuthService);
+
+function asyncGeneratorStep(gen, resolve, reject, _next, _throw, key, arg) {
+    try {
+        var info = gen[key](arg);
+        var value = info.value;
+    } catch (error) {
+        reject(error);
+        return;
+    }
+    if (info.done) {
+        resolve(value);
+    } else {
+        Promise.resolve(value).then(_next, _throw);
+    }
+}
+function _async_to_generator(fn) {
+    return function() {
+        var self = this, args = arguments;
+        return new Promise(function(resolve, reject) {
+            var gen = fn.apply(self, args);
+            function _next(value) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "next", value);
+            }
+            function _throw(err) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "throw", err);
+            }
+            _next(undefined);
+        });
+    };
+}
+function _define_property$1(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;
+}
+function _object_spread(target) {
+    for(var i = 1; i < arguments.length; i++){
+        var source = arguments[i] != null ? arguments[i] : {};
+        var ownKeys = Object.keys(source);
+        if (typeof Object.getOwnPropertySymbols === "function") {
+            ownKeys = ownKeys.concat(Object.getOwnPropertySymbols(source).filter(function(sym) {
+                return Object.getOwnPropertyDescriptor(source, sym).enumerable;
+            }));
+        }
+        ownKeys.forEach(function(key) {
+            _define_property$1(target, key, source[key]);
+        });
+    }
+    return target;
+}
+function ownKeys(object, enumerableOnly) {
+    var keys = Object.keys(object);
+    if (Object.getOwnPropertySymbols) {
+        var symbols = Object.getOwnPropertySymbols(object);
+        keys.push.apply(keys, symbols);
+    }
+    return keys;
+}
+function _object_spread_props(target, source) {
+    source = source != null ? source : {};
+    if (Object.getOwnPropertyDescriptors) {
+        Object.defineProperties(target, Object.getOwnPropertyDescriptors(source));
+    } else {
+        ownKeys(Object(source)).forEach(function(key) {
+            Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key));
+        });
+    }
+    return target;
+}
+function _ts_generator(thisArg, body) {
+    var f, y, t, _ = {
+        label: 0,
+        sent: function() {
+            if (t[0] & 1) throw t[1];
+            return t[1];
+        },
+        trys: [],
+        ops: []
+    }, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype), d = Object.defineProperty;
+    return d(g, "next", {
+        value: verb(0)
+    }), d(g, "throw", {
+        value: verb(1)
+    }), d(g, "return", {
+        value: verb(2)
+    }), typeof Symbol === "function" && d(g, Symbol.iterator, {
+        value: function() {
+            return this;
+        }
+    }), g;
+    function verb(n) {
+        return function(v) {
+            return step([
+                n,
+                v
+            ]);
+        };
+    }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while(g && (g = 0, op[0] && (_ = 0)), _)try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [
+                op[0] & 2,
+                t.value
+            ];
+            switch(op[0]){
+                case 0:
+                case 1:
+                    t = op;
+                    break;
+                case 4:
+                    _.label++;
+                    return {
+                        value: op[1],
+                        done: false
+                    };
+                case 5:
+                    _.label++;
+                    y = op[1];
+                    op = [
+                        0
+                    ];
+                    continue;
+                case 7:
+                    op = _.ops.pop();
+                    _.trys.pop();
+                    continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) {
+                        _ = 0;
+                        continue;
+                    }
+                    if (op[0] === 3 && (!t || op[1] > t[0] && op[1] < t[3])) {
+                        _.label = op[1];
+                        break;
+                    }
+                    if (op[0] === 6 && _.label < t[1]) {
+                        _.label = t[1];
+                        t = op;
+                        break;
+                    }
+                    if (t && _.label < t[2]) {
+                        _.label = t[2];
+                        _.ops.push(op);
+                        break;
+                    }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop();
+                    continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) {
+            op = [
+                6,
+                e
+            ];
+            y = 0;
+        } finally{
+            f = t = 0;
+        }
+        if (op[0] & 5) throw op[1];
+        return {
+            value: op[0] ? op[1] : void 0,
+            done: true
+        };
+    }
+}
+/**
+ * Maps stored connection credentials to a {@link ZohoAccessToken}.
+ *
+ * @param credentials - The credentials stored for the `zoho` provider.
+ * @returns The equivalent Zoho access token, or null when the credentials cannot form one.
+ */ function zohoAccessTokenFromUserExternalConnectionCredentials(credentials) {
+    var _credentials_extra;
+    var expiresAt = safeToJsDate(credentials === null || credentials === void 0 ? void 0 : credentials.expiresAt);
+    var apiDomain = credentials === null || credentials === void 0 ? void 0 : (_credentials_extra = credentials.extra) === null || _credentials_extra === void 0 ? void 0 : _credentials_extra[ZOHO_EXTRA_API_DOMAIN_KEY];
+    var result;
+    // the api domain is required, not incidental: a Zoho access token is only usable against the domain
+    // it was issued for, so a token synthesized without one would be sent to the wrong host
+    if (credentials != null && expiresAt != null && apiDomain != null) {
+        var _ref, _credentials_scopes;
+        var issuedAt = safeToJsDate(credentials.issuedAt);
+        var expiresIn = Math.round((expiresAt.getTime() - ((_ref = issuedAt === null || issuedAt === void 0 ? void 0 : issuedAt.getTime()) !== null && _ref !== void 0 ? _ref : Date.now())) / MS_IN_SECOND);
+        result = {
+            accessToken: credentials.accessToken,
+            // joined on the same delimiter `zohoOAuthScopesFromScopeString` split them with
+            scope: ((_credentials_scopes = credentials.scopes) !== null && _credentials_scopes !== void 0 ? _credentials_scopes : []).join(ZOHO_OAUTH_SCOPE_DELIMITER),
+            apiDomain: String(apiDomain),
+            expiresIn: expiresIn,
+            expiresAt: expiresAt
+        };
+    }
+    return result;
+}
+/**
+ * Creates a {@link ZohoAccessTokenCache} backed by a user's UserExternalConnection pair.
+ *
+ * The Zoho counterpart of `userExternalConnectionCalcomAccessTokenCache`, and the per-user counterpart
+ * of `firebaseZohoAccountsAccessTokenCacheService` — which caches the APP's token in a `SystemState`
+ * document and has no notion of a user.
+ *
+ * Zoho does not rotate refresh tokens, so unlike Cal.com there is no token here that is destroyed by
+ * being used. What this buys instead is that a renewed access token is shared: without it every Cloud
+ * Function instance holds its own in-memory token and refreshes independently, so a user's grant is
+ * exercised once per instance per hour rather than once per hour.
+ *
+ * @param config - The accessor, the actions, and the user the cache is for.
+ * @returns A ZohoAccessTokenCache reading and writing the user's connection pair.
+ */ function userExternalConnectionZohoAccessTokenCache(config) {
+    var accessor = config.accessor, actions = config.actions, uid = config.uid;
+    var providerType = ZOHO_USER_EXTERNAL_CONNECTION_PROVIDER_TYPE;
+    var connection = accessor.accessorForUser({
+        uid: uid
+    })(providerType);
+    function loadCachedToken() {
+        return _async_to_generator(function() {
+            var credentials;
+            return _ts_generator(this, function(_state) {
+                switch(_state.label){
+                    case 0:
+                        return [
+                            4,
+                            connection.readUserExternalConnectionCredentials()
+                        ];
+                    case 1:
+                        credentials = _state.sent();
+                        return [
+                            2,
+                            zohoAccessTokenFromUserExternalConnectionCredentials(credentials)
+                        ];
+                }
+            });
+        })();
+    }
+    function updateCachedToken(accessToken) {
+        return _async_to_generator(function() {
+            var previous, now, refreshed;
+            return _ts_generator(this, function(_state) {
+                switch(_state.label){
+                    case 0:
+                        return [
+                            4,
+                            connection.readUserExternalConnectionCredentials()
+                        ];
+                    case 1:
+                        previous = _state.sent();
+                        if (previous == null) {
+                            // nothing to merge onto, and a Zoho access token carries no refresh token — writing it alone
+                            // would store credentials that can never be renewed
+                            return [
+                                2
+                            ];
+                        }
+                        now = new Date();
+                        refreshed = _object_spread_props(_object_spread({}, previous), {
+                            accessToken: accessToken.accessToken,
+                            issuedAt: now.toISOString(),
+                            expiresAt: accessToken.expiresAt.toISOString(),
+                            extra: _object_spread_props(_object_spread({}, previous.extra), _define_property$1({}, ZOHO_EXTRA_API_DOMAIN_KEY, accessToken.apiDomain))
+                        });
+                        return [
+                            4,
+                            actions.refreshUserExternalConnectionCredentials({
+                                uid: uid,
+                                providerType: providerType,
+                                credentials: mergeRefreshedUserExternalConnectionCredentials({
+                                    previous: previous,
+                                    refreshed: refreshed
+                                })
+                            })
+                        ];
+                    case 2:
+                        _state.sent();
+                        return [
+                            2
+                        ];
+                }
+            });
+        })();
+    }
+    function clearCachedToken() {
+        return _async_to_generator(function() {
+            var previous;
+            return _ts_generator(this, function(_state) {
+                switch(_state.label){
+                    case 0:
+                        return [
+                            4,
+                            connection.readUserExternalConnectionCredentials()
+                        ];
+                    case 1:
+                        previous = _state.sent();
+                        if (previous == null) {
+                            return [
+                                2
+                            ];
+                        }
+                        // deliberately NOT a disconnect. Zoho's factory clears the cache to force its next call to refresh,
+                        // which is a statement about the ACCESS token only — dropping the refresh token here would turn a
+                        // routine cache invalidation into a connection the user has to re-authorize.
+                        return [
+                            4,
+                            actions.refreshUserExternalConnectionCredentials({
+                                uid: uid,
+                                providerType: providerType,
+                                credentials: _object_spread_props(_object_spread({}, previous), {
+                                    accessToken: '',
+                                    expiresAt: new Date(0).toISOString()
+                                })
+                            })
+                        ];
+                    case 2:
+                        _state.sent();
+                        return [
+                            2
+                        ];
+                }
+            });
+        })();
+    }
+    return {
+        loadCachedToken: loadCachedToken,
+        updateCachedToken: updateCachedToken,
+        clearCachedToken: clearCachedToken
+    };
+}
+
+function _assert_this_initialized(self) {
+    if (self === void 0) {
+        throw new ReferenceError("this hasn't been initialised - super() hasn't been called");
+    }
+    return self;
+}
+function _call_super(_this, derived, args) {
+    derived = _get_prototype_of(derived);
+    return _possible_constructor_return(_this, _is_native_reflect_construct() ? Reflect.construct(derived, [], _get_prototype_of(_this).constructor) : derived.apply(_this, args));
+}
+function _class_call_check(instance, Constructor) {
+    if (!(instance instanceof Constructor)) {
+        throw new TypeError("Cannot call a class as a function");
+    }
+}
+function _define_property(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;
+}
+function _get_prototype_of(o) {
+    _get_prototype_of = Object.setPrototypeOf ? Object.getPrototypeOf : function getPrototypeOf(o) {
+        return o.__proto__ || Object.getPrototypeOf(o);
+    };
+    return _get_prototype_of(o);
+}
+function _inherits(subClass, superClass) {
+    if (typeof superClass !== "function" && superClass !== null) {
+        throw new TypeError("Super expression must either be null or a function");
+    }
+    subClass.prototype = Object.create(superClass && superClass.prototype, {
+        constructor: {
+            value: subClass,
+            writable: true,
+            configurable: true
+        }
+    });
+    if (superClass) _set_prototype_of(subClass, superClass);
+}
+function _possible_constructor_return(self, call) {
+    if (call && (_type_of(call) === "object" || typeof call === "function")) {
+        return call;
+    }
+    return _assert_this_initialized(self);
+}
+function _set_prototype_of(o, p) {
+    _set_prototype_of = Object.setPrototypeOf || function setPrototypeOf(o, p) {
+        o.__proto__ = p;
+        return o;
+    };
+    return _set_prototype_of(o, p);
+}
+function _type_of(obj) {
+    "@swc/helpers - typeof";
+    return obj && typeof Symbol !== "undefined" && obj.constructor === Symbol ? "symbol" : typeof obj;
+}
+function _is_native_reflect_construct() {
+    try {
+        var result = !Boolean.prototype.valueOf.call(Reflect.construct(Boolean, [], function() {}));
+    } catch (_) {}
+    return (_is_native_reflect_construct = function() {
+        return !!result;
+    })();
+}
+/**
+ * Endpoints for the Zoho external-connection authorization-code handoff.
+ *
+ * Mounted at `/oauth/zoho`, matching the Angular registry's default authorize path of
+ * `/oauth/<providerType>/authorize`. Hosting rewrites do not strip the path, so this prefix is the
+ * public path — but an app with a global API route prefix must ALSO exclude these routes from it via
+ * {@link ZOHO_USER_EXTERNAL_CONNECTION_OAUTH_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE}, or they land under
+ * that prefix instead and no longer match the redirect URI registered with Zoho.
+ *
+ * The `authorize` and `callback` routes come from the base class, so this declares only where they
+ * mount and which service serves them.
+ */ var ZohoUserExternalConnectionOAuthController = /*#__PURE__*/ function(AbstractUserExternalConnectionOAuthController) {
+    _inherits(ZohoUserExternalConnectionOAuthController, AbstractUserExternalConnectionOAuthController);
+    function ZohoUserExternalConnectionOAuthController(oauthService) {
+        _class_call_check(this, ZohoUserExternalConnectionOAuthController);
+        var _this;
+        _this = _call_super(this, ZohoUserExternalConnectionOAuthController), _define_property(_this, "oauthService", void 0);
+        _this.oauthService = oauthService;
+        return _this;
+    }
+    return ZohoUserExternalConnectionOAuthController;
+}(AbstractUserExternalConnectionOAuthController);
+ZohoUserExternalConnectionOAuthController = __decorate([
+    Controller(ZOHO_USER_EXTERNAL_CONNECTION_OAUTH_CONTROLLER_PATH),
+    __param(0, Inject(ZohoUserExternalConnectionOAuthService))
+], ZohoUserExternalConnectionOAuthController);
+
+function _array_like_to_array(arr, len) {
+    if (len == null || len > arr.length) len = arr.length;
+    for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
+    return arr2;
+}
+function _array_without_holes(arr) {
+    if (Array.isArray(arr)) return _array_like_to_array(arr);
+}
+function _iterable_to_array(iter) {
+    if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter);
+}
+function _non_iterable_spread() {
+    throw new TypeError("Invalid attempt to spread non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+}
+function _to_consumable_array(arr) {
+    return _array_without_holes(arr) || _iterable_to_array(arr) || _unsupported_iterable_to_array(arr) || _non_iterable_spread();
+}
+function _unsupported_iterable_to_array(o, minLen) {
+    if (!o) return;
+    if (typeof o === "string") return _array_like_to_array(o, minLen);
+    var n = Object.prototype.toString.call(o).slice(8, -1);
+    if (n === "Object" && o.constructor) n = o.constructor.name;
+    if (n === "Map" || n === "Set") return Array.from(n);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array(o, minLen);
+}
+/**
+ * Convenience function used to generate ModuleMetadata for an app's Zoho external-connection OAuth
+ * module.
+ *
+ * Opt-in: importing the Zoho OAuth module alone never mounts HTTP routes, so an app that only makes
+ * outbound Zoho calls exposes no endpoints.
+ *
+ * The importing module must also supply `UserExternalConnectionServerActions` and
+ * `UserExternalConnectionStateCoder` — both exported by `appUserExternalConnectionModuleMetadata`,
+ * so pass that module in `imports`.
+ *
+ * @param config - The module metadata configuration.
+ * @returns NestJS ModuleMetadata mounting the Zoho connect endpoints.
+ */ function appZohoUserExternalConnectionOAuthModuleMetadata(config) {
+    var dependencyModule = config.dependencyModule, successPath = config.successPath, failurePath = config.failurePath, scopes = config.scopes, accountsApiUrl = config.accountsApiUrl, imports = config.imports, exports = config.exports, providers = config.providers;
+    var dependencyModuleImport = dependencyModule ? [
+        dependencyModule
+    ] : [];
+    return {
+        imports: [
+            ConfigModule
+        ].concat(_to_consumable_array(dependencyModuleImport), _to_consumable_array(imports !== null && imports !== void 0 ? imports : [])),
+        controllers: [
+            ZohoUserExternalConnectionOAuthController
+        ],
+        exports: [
+            ZohoUserExternalConnectionOAuthService
+        ].concat(_to_consumable_array(exports !== null && exports !== void 0 ? exports : [])),
+        providers: [
+            {
+                provide: ZohoUserExternalConnectionOAuthServiceConfig,
+                inject: [
+                    FirebaseServerEnvService
+                ],
+                useFactory: function useFactory(envService) {
+                    return zohoUserExternalConnectionOAuthServiceConfigFactory({
+                        envService: envService,
+                        successPath: successPath,
+                        failurePath: failurePath,
+                        scopes: scopes,
+                        accountsApiUrl: accountsApiUrl
+                    });
+                }
+            },
+            ZohoUserExternalConnectionOAuthService
+        ].concat(_to_consumable_array(providers !== null && providers !== void 0 ? providers : []))
+    };
+}
+
+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 };