@dereekb/firebase-server 13.31.0 → 13.33.0

package/zoho/package.json

@@ -1,15 +1,18 @@
 {
   "name": "@dereekb/firebase-server/zoho",
-  "version": "13.31.0",
+  "version": "13.33.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.31.0",
-    "@dereekb/date": "13.31.0",
-    "@dereekb/model": "13.31.0",
-    "@dereekb/nestjs": "13.31.0",
-    "@dereekb/rxjs": "13.31.0",
-    "@dereekb/firebase": "13.31.0",
-    "@dereekb/util": "13.31.0",
-    "@dereekb/zoho": "13.31.0"
+    "@dereekb/analytics": "13.33.0",
+    "@dereekb/date": "13.33.0",
+    "@dereekb/model": "13.33.0",
+    "@dereekb/nestjs": "13.33.0",
+    "@dereekb/rxjs": "13.33.0",
+    "@dereekb/firebase": "13.33.0",
+    "@dereekb/firebase-server": "13.33.0",
+    "@dereekb/util": "13.33.0",
+    "@dereekb/zoho": "13.33.0",
+    "@nestjs/common": "^11.1.19",
+    "express": "^5.2.1"
   },
   "exports": {
     "./package.json": "./package.json",

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

@@ -1,2 +1,7 @@
 export * from './zoho.accounts.firebase';
 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.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>;
+}