@dereekb/firebase-server 13.32.0 → 13.34.0

package/zoho/package.json

@@ -1,15 +1,19 @@
 {
   "name": "@dereekb/firebase-server/zoho",
-  "version": "13.32.0",
+  "version": "13.34.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.32.0",
-    "@dereekb/date": "13.32.0",
-    "@dereekb/model": "13.32.0",
-    "@dereekb/nestjs": "13.32.0",
-    "@dereekb/rxjs": "13.32.0",
-    "@dereekb/firebase": "13.32.0",
-    "@dereekb/util": "13.32.0",
-    "@dereekb/zoho": "13.32.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.json": "./package.json",

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

@@ -1,2 +1,8 @@
 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';
+export * from './zoho.oauth.connection.controller';
+export * from './zoho.oauth.connection.module';
+export * from './zoho.oauth.connection.service';

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

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

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

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

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

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

package/zoho/src/lib/zoho.oauth.connection.cache.d.ts

@@ -0,0 +1,45 @@
+import { type ZohoAccessToken, type ZohoAccessTokenCache } from '@dereekb/zoho';
+import { type FirebaseAuthUserId } from '@dereekb/firebase';
+import { type UserExternalConnectionAccessor, type UserExternalConnectionCredentials, type UserExternalConnectionCredentialsWriter } from '@dereekb/firebase-server/model';
+import { type Maybe } from '@dereekb/util';
+/**
+ * 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.
+ */
+export declare function zohoAccessTokenFromUserExternalConnectionCredentials(credentials: Maybe<UserExternalConnectionCredentials>): Maybe<ZohoAccessToken>;
+/**
+ * Configuration for {@link userExternalConnectionZohoAccessTokenCache}.
+ */
+export interface UserExternalConnectionZohoAccessTokenCacheConfig {
+    /**
+     * Used to read the user's currently stored Zoho credentials.
+     *
+     * The accessor rather than `UserExternalConnectionReader`: the contract below is explicitly that an
+     * EXPIRED token may be returned, so a surface that could refresh would be the wrong tool — see
+     * `loadCachedToken`.
+     */
+    readonly accessor: UserExternalConnectionAccessor;
+    /**
+     * Used to persist a renewed token back onto the connection pair, and to record a cleared one.
+     */
+    readonly actions: UserExternalConnectionCredentialsWriter;
+    readonly uid: FirebaseAuthUserId;
+}
+/**
+ * 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.
+ */
+export declare function userExternalConnectionZohoAccessTokenCache(config: UserExternalConnectionZohoAccessTokenCacheConfig): ZohoAccessTokenCache;

package/zoho/src/lib/zoho.oauth.connection.config.d.ts

@@ -0,0 +1,80 @@
+import { type ZohoAccountsConfigApiUrlInput, type ZohoOAuthScope } from '@dereekb/zoho';
+import { type FirebaseServerEnvService } from '@dereekb/firebase-server';
+import { UserExternalConnectionOAuthServiceConfig } from '@dereekb/firebase-server/model';
+import { type Maybe } from '@dereekb/util';
+/**
+ * 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.
+ */
+export declare const ZOHO_USER_EXTERNAL_CONNECTION_OAUTH_CONTROLLER_PATH: string;
+/**
+ * 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`.
+ */
+export declare const ZOHO_USER_EXTERNAL_CONNECTION_OAUTH_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE: string[];
+/**
+ * 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.
+ */
+export declare const DEFAULT_ZOHO_OAUTH_SCOPES: readonly ZohoOAuthScope[];
+/**
+ * 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.
+ */
+export declare abstract class ZohoUserExternalConnectionOAuthServiceConfig extends UserExternalConnectionOAuthServiceConfig {
+    readonly scopes: readonly ZohoOAuthScope[];
+    /**
+     * Datacenter to authorize against. Defaults to the api's configured one.
+     */
+    readonly accountsApiUrl?: Maybe<ZohoAccountsConfigApiUrlInput>;
+}
+export interface ZohoUserExternalConnectionOAuthServiceConfigFactoryConfig {
+    readonly envService: FirebaseServerEnvService;
+    /**
+     * Path on the app URL the user is returned to after connecting, e.g. `/app/settings`.
+     */
+    readonly successPath: string;
+    /**
+     * Path on the app URL the user is returned to after a failed connect. Defaults to `successPath`.
+     */
+    readonly failurePath?: Maybe<string>;
+    /**
+     * The scopes to request. Defaults to {@link DEFAULT_ZOHO_OAUTH_SCOPES}.
+     */
+    readonly scopes?: Maybe<readonly ZohoOAuthScope[]>;
+    /**
+     * Datacenter to authorize against. Defaults to the api's configured one.
+     */
+    readonly accountsApiUrl?: Maybe<ZohoAccountsConfigApiUrlInput>;
+}
+/**
+ * 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.
+ */
+export declare function zohoUserExternalConnectionOAuthServiceConfigFactory(config: ZohoUserExternalConnectionOAuthServiceConfigFactoryConfig): ZohoUserExternalConnectionOAuthServiceConfig;

package/zoho/src/lib/zoho.oauth.connection.controller.d.ts

@@ -0,0 +1,18 @@
+import { AbstractUserExternalConnectionOAuthController } from '@dereekb/firebase-server/model';
+import { ZohoUserExternalConnectionOAuthService } from './zoho.oauth.connection.service';
+/**
+ * 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.
+ */
+export declare class ZohoUserExternalConnectionOAuthController extends AbstractUserExternalConnectionOAuthController {
+    readonly oauthService: ZohoUserExternalConnectionOAuthService;
+    constructor(oauthService: ZohoUserExternalConnectionOAuthService);
+}

package/zoho/src/lib/zoho.oauth.connection.module.d.ts

@@ -0,0 +1,43 @@
+import { type ModuleMetadata } from '@nestjs/common';
+import { type ZohoAccountsConfigApiUrlInput, type ZohoOAuthScope } from '@dereekb/zoho';
+import { type Maybe } from '@dereekb/util';
+export interface ProvideAppZohoUserExternalConnectionOAuthMetadataConfig extends Pick<ModuleMetadata, 'imports' | 'exports' | 'providers'> {
+    /**
+     * This module requires the following dependencies in order to initialize properly:
+     * - ZohoAccountsOAuthApi
+     *
+     * This module declaration makes it easier to import a module that exports that dependency.
+     */
+    readonly dependencyModule?: Maybe<Required<ModuleMetadata>['imports']['0']>;
+    /**
+     * Path on the app URL the user is returned to after connecting, e.g. `/app/settings`.
+     */
+    readonly successPath: string;
+    /**
+     * Path on the app URL the user is returned to after a failed connect. Defaults to `successPath`.
+     */
+    readonly failurePath?: Maybe<string>;
+    /**
+     * The scopes to request. Defaults to `DEFAULT_ZOHO_OAUTH_SCOPES`.
+     */
+    readonly scopes?: Maybe<readonly ZohoOAuthScope[]>;
+    /**
+     * Datacenter to authorize against. Defaults to the api's configured one.
+     */
+    readonly accountsApiUrl?: Maybe<ZohoAccountsConfigApiUrlInput>;
+}
+/**
+ * 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.
+ */
+export declare function appZohoUserExternalConnectionOAuthModuleMetadata(config: ProvideAppZohoUserExternalConnectionOAuthMetadataConfig): ModuleMetadata;

package/zoho/src/lib/zoho.oauth.connection.service.d.ts

@@ -0,0 +1,107 @@
+import { type ZohoAccountsApiUrl, type ZohoAccountsAuthorizeUrlFactory, type ZohoAccountsRefreshTokenFromAuthorizationCodeResponse, type ZohoAccountsUserInfoResponse } from '@dereekb/zoho';
+import { ZohoAccountsOAuthApi } from '@dereekb/zoho/nestjs';
+import { AbstractUserExternalConnectionOAuthService, UserExternalConnectionAccessor, UserExternalConnectionServerActions, UserExternalConnectionStateCoder, type UserExternalConnectionCredentials, type UserExternalConnectionOAuthCallbackQueryValues, type UserExternalConnectionOAuthExchangeInput, type UserExternalConnectionOAuthRefreshCredentialsInput, type UserExternalConnectionOAuthState } from '@dereekb/firebase-server/model';
+import { type Maybe, type WebsiteUrl } from '@dereekb/util';
+import { ZohoUserExternalConnectionOAuthServiceConfig } from './zoho.oauth.connection.config';
+/**
+ * The callback parameter naming the datacenter whose accounts server issued the code.
+ */
+export declare const ZOHO_OAUTH_CALLBACK_ACCOUNTS_SERVER_PARAM = "accounts-server";
+/**
+ * The callback parameter naming the datacenter's short location code, e.g. `us`.
+ */
+export declare const 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.
+ */
+export declare const ZOHO_EXTRA_API_DOMAIN_KEY = "apiDomain";
+/**
+ * `extra` key holding the accounts host a later refresh must be sent to.
+ */
+export declare const ZOHO_EXTRA_ACCOUNTS_SERVER_KEY = "accountsServer";
+/**
+ * `extra` key holding Zoho's short location code for the datacenter.
+ */
+export declare const ZOHO_EXTRA_LOCATION_KEY = "location";
+export interface ZohoUserExternalConnectionCredentialsInput {
+    /**
+     * The token response the exchange returned.
+     */
+    readonly response: ZohoAccountsRefreshTokenFromAuthorizationCodeResponse;
+    /**
+     * The accounts host the code was exchanged against.
+     */
+    readonly accountsApiUrl: ZohoAccountsApiUrl;
+    /**
+     * Zoho's short location code for that datacenter, when the callback carried one.
+     */
+    readonly location?: Maybe<string>;
+    /**
+     * The Zoho account the token belongs to, when one could be read.
+     *
+     * Optional because the identity call is best-effort: a connection is fully usable unlabeled.
+     */
+    readonly userInfo?: Maybe<ZohoAccountsUserInfoResponse>;
+}
+/**
+ * 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.
+ */
+export declare function zohoUserExternalConnectionCredentials(input: ZohoUserExternalConnectionCredentialsInput): UserExternalConnectionCredentials;
+/**
+ * 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.
+ */
+export declare class ZohoUserExternalConnectionOAuthService extends AbstractUserExternalConnectionOAuthService {
+    readonly config: ZohoUserExternalConnectionOAuthServiceConfig;
+    readonly stateCoder: UserExternalConnectionStateCoder;
+    readonly userExternalConnectionActions: UserExternalConnectionServerActions;
+    readonly userExternalConnectionAccessor: UserExternalConnectionAccessor;
+    readonly oauthApi: ZohoAccountsOAuthApi;
+    readonly authorizeUrlFactory: ZohoAccountsAuthorizeUrlFactory;
+    /**
+     * The accounts host this app authorizes against, and the fallback for an exchange whose callback
+     * named no usable one.
+     */
+    readonly accountsApiUrl: ZohoAccountsApiUrl;
+    constructor(config: ZohoUserExternalConnectionOAuthServiceConfig, stateCoder: UserExternalConnectionStateCoder, userExternalConnectionActions: UserExternalConnectionServerActions, userExternalConnectionAccessor: UserExternalConnectionAccessor, oauthApi: ZohoAccountsOAuthApi);
+    protected authorizeUrlForState(state: UserExternalConnectionOAuthState): WebsiteUrl;
+    protected credentialsForAuthorizationCode(input: UserExternalConnectionOAuthExchangeInput): Promise<UserExternalConnectionCredentials>;
+    refreshCredentials(input: UserExternalConnectionOAuthRefreshCredentialsInput): Promise<UserExternalConnectionCredentials>;
+    /**
+     * 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.
+     */
+    protected accountsApiUrlForCallbackQuery(query: Maybe<UserExternalConnectionOAuthCallbackQueryValues>): Maybe<ZohoAccountsApiUrl>;
+    /**
+     * 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.
+     */
+    protected allowlistedAccountsApiUrl(accountsServer: Maybe<string>): Maybe<ZohoAccountsApiUrl>;
+}