@dereekb/firebase-server 13.31.0 → 13.33.0

package/model/src/lib/userexternalconnection/userexternalconnection.action.server.d.ts

@@ -0,0 +1,172 @@
+import { type Maybe } from '@dereekb/util';
+import { type FirebaseAuthUserId, type FirestoreContextReference, type UserExternalConnectionDocument, type UserExternalConnectionEntryStatus, type UserExternalConnectionErrorCode, type UserExternalConnectionFirestoreCollections, type UserExternalConnectionProviderType } from '@dereekb/firebase';
+import { type UserExternalConnectionCredentials, type UserExternalConnectionServerFirestoreCollections } from './userexternalconnection.private';
+/**
+ * Context required by {@link userExternalConnectionServerActions}.
+ *
+ * Carries BOTH halves of the pair. Nothing else in the workspace should hold the private collection.
+ */
+export interface UserExternalConnectionServerActionsContext extends FirestoreContextReference, UserExternalConnectionFirestoreCollections, UserExternalConnectionServerFirestoreCollections {
+}
+/**
+ * Reference to a {@link UserExternalConnectionServerActions} instance.
+ */
+export interface UserExternalConnectionServerActionsRef {
+    readonly userExternalConnectionActions: UserExternalConnectionServerActions;
+}
+/**
+ * Parameters for connecting a user to a provider.
+ *
+ * NOTE what is absent: there is no parameter for `status`, `scopes`, `externalAccountId`,
+ * `expiresAt`, `connectedAt`, `updatedAt`, or the connected-provider array. Every one of those is
+ * derived from `credentials`, so a caller has no way to submit a summary that contradicts the
+ * credentials it summarizes. `label` rides on the credentials because it is a fact about the grant.
+ */
+export interface UserExternalConnectionConnectParams {
+    readonly uid: FirebaseAuthUserId;
+    readonly providerType: UserExternalConnectionProviderType;
+    readonly credentials: UserExternalConnectionCredentials;
+    /**
+     * Optional instant to apply the change at. Defaults to now.
+     */
+    readonly now?: Maybe<Date>;
+}
+/**
+ * Parameters for replacing a provider's credentials after a token refresh.
+ */
+export type UserExternalConnectionRefreshCredentialsParams = UserExternalConnectionConnectParams;
+/**
+ * Parameters for marking a provider's connection as errored.
+ *
+ * The stored credentials are retained so the connection can be repaired without a full reconnect.
+ */
+export interface UserExternalConnectionMarkErrorParams {
+    readonly uid: FirebaseAuthUserId;
+    readonly providerType: UserExternalConnectionProviderType;
+    readonly error?: Maybe<UserExternalConnectionErrorCode>;
+    readonly now?: Maybe<Date>;
+}
+/**
+ * Parameters for disconnecting a user from a provider.
+ */
+export interface UserExternalConnectionDisconnectParams {
+    readonly uid: FirebaseAuthUserId;
+    readonly providerType: UserExternalConnectionProviderType;
+    /**
+     * Whether to retain a `disconnected` history entry on the public document rather than removing the
+     * provider's key. The credentials are removed either way. Defaults to false.
+     */
+    readonly retainEntry?: Maybe<boolean>;
+    readonly now?: Maybe<Date>;
+}
+/**
+ * Parameters for creating a user's connection document.
+ */
+export interface UserExternalConnectionCreateParams {
+    readonly uid: FirebaseAuthUserId;
+    /**
+     * Optional instant to stamp the new document with. Defaults to now.
+     */
+    readonly now?: Maybe<Date>;
+}
+/**
+ * Parameters for deleting a user's entire connection pair.
+ */
+export interface UserExternalConnectionDeleteAllParams {
+    readonly uid: FirebaseAuthUserId;
+}
+/**
+ * Server-only actions for the UserExternalConnection document pair.
+ *
+ * This is the ENTIRE write surface, and ONLY the write surface. The two collections are never exposed
+ * for independent mutation, so there is no way for a caller to write one document without the other —
+ * and therefore no sync, reconciliation, or drift-detection process to maintain.
+ *
+ * Reading is `UserExternalConnectionAccessor` (raw) or `UserExternalConnectionReader` (the one a
+ * consumer wants). A read used to live here too, which meant every path that only needed to look at a
+ * user's credentials had to hold the write surface to do it.
+ */
+export declare abstract class UserExternalConnectionServerActions {
+    abstract createUserExternalConnection(params: UserExternalConnectionCreateParams): Promise<UserExternalConnectionDocument>;
+    abstract connectUserExternalConnection(params: UserExternalConnectionConnectParams): Promise<UserExternalConnectionDocument>;
+    abstract refreshUserExternalConnectionCredentials(params: UserExternalConnectionRefreshCredentialsParams): Promise<UserExternalConnectionDocument>;
+    abstract markUserExternalConnectionError(params: UserExternalConnectionMarkErrorParams): Promise<UserExternalConnectionDocument>;
+    abstract disconnectUserExternalConnection(params: UserExternalConnectionDisconnectParams): Promise<UserExternalConnectionDocument>;
+    abstract deleteAllUserExternalConnectionsForUser(params: UserExternalConnectionDeleteAllParams): Promise<void>;
+}
+/**
+ * The single write a per-user token cache needs: persisting credentials the provider just issued.
+ *
+ * Narrower than {@link UserExternalConnectionServerActions} on purpose. A token cache has no business
+ * connecting, disconnecting, or deleting anything, and the resolved document is of no use to it — hence
+ * the unconstrained result, which also means a caller can satisfy this without producing a document it
+ * would only throw away.
+ */
+export interface UserExternalConnectionCredentialsWriter {
+    refreshUserExternalConnectionCredentials(params: UserExternalConnectionRefreshCredentialsParams): Promise<unknown>;
+}
+/**
+ * The two writes a reader performs: persisting a refresh, and recording that a provider rejected the
+ * credentials.
+ *
+ * Also narrower than {@link UserExternalConnectionServerActions} on purpose — a read surface has no
+ * business creating or deleting a connection — and for the same reason unconstrained in its results.
+ */
+export interface UserExternalConnectionCredentialsAndFailureWriter extends UserExternalConnectionCredentialsWriter {
+    markUserExternalConnectionError(params: UserExternalConnectionMarkErrorParams): Promise<unknown>;
+}
+/**
+ * Creates a {@link UserExternalConnectionServerActions} bound to the given context.
+ *
+ * @param context - The context carrying both halves of the connection pair.
+ * @returns A concrete UserExternalConnectionServerActions implementation.
+ */
+export declare function userExternalConnectionServerActions(context: UserExternalConnectionServerActionsContext): UserExternalConnectionServerActions;
+/**
+ * Creates a function that creates a user's connection document.
+ *
+ * Only the public half is written: the private half exists to hold credentials, and the paired write
+ * creates it on the first connect. Creation runs in a transaction so two concurrent calls cannot both
+ * see an absent document and both write one.
+ *
+ * @param context - The context carrying both halves of the pair.
+ * @returns A function that creates the document for a uid, throwing if it already exists.
+ */
+export declare function createUserExternalConnectionFactory(context: UserExternalConnectionServerActionsContext): (params: UserExternalConnectionCreateParams) => Promise<UserExternalConnectionDocument>;
+/**
+ * Parameters for the paired write.
+ */
+export interface WriteUserExternalConnectionPairParams {
+    readonly uid: FirebaseAuthUserId;
+    readonly providerType: UserExternalConnectionProviderType;
+    /**
+     * The outcome the operation produced. Drives BOTH sides of the pair.
+     */
+    readonly outcome: UserExternalConnectionEntryStatus;
+    /**
+     * The credentials the outcome produced. Required for a `connected` outcome; ignored for a
+     * `disconnected` one (which always removes the stored credentials).
+     */
+    readonly credentials?: Maybe<UserExternalConnectionCredentials>;
+    readonly error?: Maybe<UserExternalConnectionErrorCode>;
+    readonly retainEntry?: Maybe<boolean>;
+    readonly now?: Maybe<Date>;
+}
+/**
+ * Creates the single function through which every mutation of the connection pair flows.
+ *
+ * Both documents are loaded from the same transaction, all reads happen before any write (a
+ * Firestore transaction requirement), and both are written with the COMPLETE next value derived from
+ * one input. A failure at any point leaves neither document changed.
+ *
+ * @param context - The context carrying both halves of the pair.
+ * @returns A function that applies one provider's outcome to both documents atomically.
+ */
+export declare function writeUserExternalConnectionPairInTransactionFactory(context: UserExternalConnectionServerActionsContext): (params: WriteUserExternalConnectionPairParams) => Promise<UserExternalConnectionDocument>;
+/**
+ * Creates a function that deletes a user's entire connection pair in one transaction.
+ *
+ * @param context - The context carrying both halves of the pair.
+ * @returns A function that removes both documents for a uid.
+ */
+export declare function deleteAllUserExternalConnectionsForUserFactory(context: UserExternalConnectionServerActionsContext): (params: UserExternalConnectionDeleteAllParams) => Promise<void>;

package/model/src/lib/userexternalconnection/userexternalconnection.error.d.ts

@@ -0,0 +1,44 @@
+import { type FirebaseAuthUserId, type UserExternalConnectionProviderType } from '@dereekb/firebase';
+export declare const USER_EXTERNAL_CONNECTION_PROVIDER_NOT_CONNECTED_ERROR_CODE = "USER_EXTERNAL_CONNECTION_PROVIDER_NOT_CONNECTED";
+export declare const USER_EXTERNAL_CONNECTION_PROVIDER_NOT_ALLOWED_ERROR_CODE = "USER_EXTERNAL_CONNECTION_PROVIDER_NOT_ALLOWED";
+export declare const USER_EXTERNAL_CONNECTION_ALREADY_EXISTS_ERROR_CODE = "USER_EXTERNAL_CONNECTION_ALREADY_EXISTS";
+export declare const USER_EXTERNAL_CONNECTION_CREDENTIALS_EXPIRED_ERROR_CODE = "USER_EXTERNAL_CONNECTION_CREDENTIALS_EXPIRED";
+/**
+ * Creates an error indicating the user already has a connection document.
+ *
+ * There is exactly one per user, so creating a second is a caller mistake rather than a conflict to
+ * resolve. Clients that create on page load are expected to skip the call when the document is
+ * already loaded, and to treat this code as success when two of them race.
+ *
+ * @param uid - The user whose document already exists.
+ * @returns A precondition-conflict HttpsError.
+ */
+export declare function userExternalConnectionAlreadyExistsError(uid: FirebaseAuthUserId): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating the user has no connection to the requested provider.
+ *
+ * @param providerType - The provider that was requested.
+ * @returns A precondition-conflict HttpsError.
+ */
+export declare function userExternalConnectionProviderNotConnectedError(providerType: UserExternalConnectionProviderType): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating the user's credentials for a provider have expired and could not be
+ * renewed.
+ *
+ * Distinct from {@link userExternalConnectionProviderNotConnectedError}: the user IS connected and the
+ * credentials are still stored, they just cannot be used right now. Either no refresher was configured,
+ * the provider has no refresh path, or the refresh itself failed. The remedy for the last of those is a
+ * reconnect; for the first two it is a configuration change, so the code is deliberately the same and
+ * the distinction is left to the server logs.
+ *
+ * @param providerType - The provider whose credentials expired.
+ * @returns A precondition-conflict HttpsError.
+ */
+export declare function userExternalConnectionCredentialsExpiredError(providerType: UserExternalConnectionProviderType): import("firebase-functions/https").HttpsError;
+/**
+ * Creates an error indicating the requested provider is not one this app allows connecting to.
+ *
+ * @param providerType - The provider that was requested.
+ * @returns A precondition-conflict HttpsError.
+ */
+export declare function userExternalConnectionProviderNotAllowedError(providerType: UserExternalConnectionProviderType): import("firebase-functions/https").HttpsError;

package/model/src/lib/userexternalconnection/userexternalconnection.module.d.ts

@@ -0,0 +1,129 @@
+import { type InjectionToken, type ModuleMetadata, type Provider } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { type Maybe, type Milliseconds } from '@dereekb/util';
+import { type FirestoreContext, type FirestoreContextReference, type UserExternalConnectionFirestoreCollections } from '@dereekb/firebase';
+import { FirebaseServerEnvService } from '@dereekb/firebase-server';
+import { type AES256GCMEncryptionSecret } from '@dereekb/nestjs';
+import { type UserExternalConnectionPrivateConverterConfig, UserExternalConnectionServerFirestoreCollections } from './userexternalconnection.private';
+import { type UserExternalConnectionServerActionsContext } from './userexternalconnection.action.server';
+/**
+ * Environment variable name for the external-connection credentials encryption secret
+ * (hex-encoded AES-256 key).
+ *
+ * IMPORTANT: there is NO key rotation. `firestoreEncryptedField` resolves and validates the key once
+ * at converter construction and closes over it, so changing this value makes every existing
+ * `uecp` document permanently undecryptable. Treat it as write-once per environment.
+ */
+export declare const USER_EXTERNAL_CONNECTION_ENCRYPTION_SECRET_ENV_KEY = "USER_EXTERNAL_CONNECTION_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 testing secret so a leaked emulator blob is attributable.
+ */
+export declare const TESTING_USER_EXTERNAL_CONNECTION_ENCRYPTION_SECRET: AES256GCMEncryptionSecret;
+/**
+ * Configuration for the UserExternalConnection server module.
+ */
+export declare abstract class UserExternalConnectionModuleConfig {
+    abstract readonly userExternalConnectionPrivateConverterConfig: UserExternalConnectionPrivateConverterConfig;
+}
+/**
+ * Builds the {@link UserExternalConnectionModuleConfig} 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 module configuration.
+ * @throws {Error} When the configured secret is invalid outside a testing environment.
+ */
+export declare function userExternalConnectionModuleConfigFactory(configService: ConfigService, envService: FirebaseServerEnvService): UserExternalConnectionModuleConfig;
+/**
+ * Creates the {@link UserExternalConnectionServerFirestoreCollections}.
+ *
+ * This is a bespoke provider rather than a `provideAppFirestoreCollections()` entry because that
+ * helper hard-codes a `(context: FirestoreContext) => T` factory and cannot carry the encryption
+ * secret this collection needs.
+ *
+ * @param firestoreContext - The Firestore context.
+ * @param config - The module configuration carrying the encryption secret.
+ * @returns The server-only collections.
+ */
+export declare function userExternalConnectionServerFirestoreCollectionsFactory(firestoreContext: FirestoreContext, config: UserExternalConnectionModuleConfig): UserExternalConnectionServerFirestoreCollections;
+/**
+ * Assembles the {@link UserExternalConnectionServerActionsContext} from the app-supplied public
+ * collections and the module-owned private collection.
+ *
+ * @param appCollections - The app's collections, carrying the public UserExternalConnection collection.
+ * @param serverCollections - The module-owned private collection.
+ * @returns The assembled server actions context.
+ */
+export declare function userExternalConnectionServerActionsContextFactory(appCollections: UserExternalConnectionFirestoreCollections & FirestoreContextReference, serverCollections: UserExternalConnectionServerFirestoreCollections): UserExternalConnectionServerActionsContext;
+/**
+ * NestJS injection token for the assembled {@link UserExternalConnectionServerActionsContext}.
+ */
+export declare const USER_EXTERNAL_CONNECTION_SERVER_ACTIONS_CONTEXT_TOKEN: InjectionToken;
+export interface ProvideAppUserExternalConnectionModuleMetadataConfig extends Pick<ModuleMetadata, 'imports' | 'exports' | 'providers'> {
+    /**
+     * Module that exports the app's collections token. When provided, it is automatically included in
+     * the generated `imports` array.
+     */
+    readonly dependencyModule?: Maybe<Required<ModuleMetadata>['imports']['0']>;
+    /**
+     * Token that resolves the app's collections — anything implementing both
+     * `UserExternalConnectionFirestoreCollections` and `FirestoreContextReference`.
+     *
+     * Taking this as a token is what keeps the package from ever naming an app's collections class.
+     */
+    readonly appCollectionsToken: InjectionToken;
+}
+/**
+ * Convenience function used to generate ModuleMetadata for an app's UserExternalConnectionModule.
+ *
+ * By default this module exports:
+ * - UserExternalConnectionServerActions
+ * - UserExternalConnectionAccessor
+ * - UserExternalConnectionServerFirestoreCollections
+ * - UserExternalConnectionModuleConfig
+ * - UserExternalConnectionStateCoder
+ *
+ * NOTE what is absent: `UserExternalConnectionReader`. The reader can be configured with a refresher,
+ * and the only refresher an app normally wants is backed by the OAuth provider registry — which this
+ * module cannot see without importing the provider modules that import it. Provide the reader with
+ * `userExternalConnectionReaderProvider()` from wherever the registry is declared.
+ *
+ * @param config - The module configuration.
+ * @returns The assembled {@link ModuleMetadata}.
+ */
+export declare function appUserExternalConnectionModuleMetadata(config: ProvideAppUserExternalConnectionModuleMetadataConfig): ModuleMetadata;
+/**
+ * Configuration for {@link userExternalConnectionReaderProvider}.
+ */
+export interface UserExternalConnectionReaderProviderConfig {
+    /**
+     * Whether to build the reader's refresher from the {@link UserExternalConnectionOAuthProviderRegistry}.
+     * Defaults to true.
+     *
+     * Set false for an app that registers no OAuth provider services — the registry token would not
+     * resolve, and a reader with no refresher is still useful for reading.
+     */
+    readonly refreshWithOAuthProviderRegistry?: Maybe<boolean>;
+    /**
+     * Overrides how long before its stated expiration a credential is treated as expired.
+     */
+    readonly expirationBuffer?: Maybe<Milliseconds>;
+}
+/**
+ * Creates the NestJS provider for the {@link UserExternalConnectionReader}.
+ *
+ * Declared by the app rather than by the UserExternalConnection module, for the same reason
+ * {@link userExternalConnectionOAuthProviderRegistryProvider} is: the reader refreshes through the
+ * registry, and the registry can only be assembled somewhere that is able to import the provider
+ * modules — each of which imports the UserExternalConnection module. Put this beside the registry
+ * provider.
+ *
+ * @param config - Optional configuration. By default the reader refreshes through the registry.
+ * @returns The NestJS provider.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function userExternalConnectionReaderProvider(config?: Maybe<UserExternalConnectionReaderProviderConfig>): Provider;

package/model/src/lib/userexternalconnection/userexternalconnection.private.d.ts

@@ -0,0 +1,192 @@
+import { type ISO8601DateString, type Maybe } from '@dereekb/util';
+import { AbstractFirestoreDocument, type CollectionReference, type FirebaseAuthUserId, type FirestoreCollection, type FirestoreContext, type UserExternalConnectionCapability, type UserExternalConnectionExternalAccountId, type UserExternalConnectionGrantSummary, type UserExternalConnectionProviderType, type UserRelated, type UserRelatedById } from '@dereekb/firebase';
+import { type AES256GCMEncryptionSecretSource } from '@dereekb/nestjs';
+/**
+ * Provides access to the {@link UserExternalConnectionPrivate} collection.
+ *
+ * Provided ONLY by the UserExternalConnectionModule. This is deliberately never declared on an
+ * app's shared `FirestoreCollections` class: `provideAppFirestoreCollections()` hard-codes a
+ * `(context: FirestoreContext) => T` factory, which cannot carry the encryption secret this
+ * collection's converter needs — so the private collection structurally cannot leak into the
+ * client-shared collection set.
+ */
+export declare abstract class UserExternalConnectionServerFirestoreCollections {
+    abstract readonly userExternalConnectionPrivateCollection: UserExternalConnectionPrivateFirestoreCollection;
+}
+/**
+ * Firestore model identity for {@link UserExternalConnectionPrivate} documents.
+ *
+ * This is a server-side only model. It has no provisions for client-side access, and deliberately
+ * has NO `firestore.rules` match block — the root catch-all `allow read, write: if false;` is what
+ * denies every client, and a block here would only create an opportunity to grant access by accident.
+ */
+export declare const userExternalConnectionPrivateIdentity: import("@dereekb/firebase").RootFirestoreModelIdentity<"userExternalConnectionPrivate", "uecp">;
+/**
+ * Credentials granted by a third-party provider for a single user.
+ *
+ * NOTE: every timestamp here is an {@link ISO8601DateString}, NOT a `Date`. The whole credentials
+ * map is JSON round-tripped through `encryptValue`/`decryptValue`, so a `Date` would silently come
+ * back as a string.
+ */
+export interface UserExternalConnectionCredentials {
+    readonly accessToken: string;
+    readonly refreshToken?: Maybe<string>;
+    readonly tokenType?: Maybe<string>;
+    readonly issuedAt: ISO8601DateString;
+    readonly expiresAt?: Maybe<ISO8601DateString>;
+    readonly scopes?: Maybe<UserExternalConnectionCapability[]>;
+    readonly externalAccountId?: Maybe<UserExternalConnectionExternalAccountId>;
+    readonly label?: Maybe<string>;
+    /**
+     * Any additional provider-specific values that must be retained to use the credentials.
+     */
+    readonly extra?: Maybe<Record<string, Maybe<string | number | boolean>>>;
+}
+/**
+ * Map of provider type to the credentials stored for that provider.
+ */
+export type UserExternalConnectionCredentialsMap = Record<UserExternalConnectionProviderType, UserExternalConnectionCredentials>;
+/**
+ * The server-only half of a user's third-party OAuth connection state.
+ *
+ * Shares its document id (the user's uid) with the client-readable `UserExternalConnection` in
+ * `@dereekb/firebase`, and is only ever written in the same transaction as it. See
+ * `writeUserExternalConnectionPairInTransactionFactory`.
+ */
+export interface UserExternalConnectionPrivate extends UserRelated, UserRelatedById {
+    /**
+     * Per-provider credentials. Stored as ONE encrypted string covering the whole map.
+     *
+     * A single encrypted field rather than a map of encrypted values: there is no server-side need to
+     * query inside credentials, and one field keeps the whole blob atomic with the paired write.
+     */
+    cr: UserExternalConnectionCredentialsMap;
+    /**
+     * Date this document was last updated at.
+     */
+    uat: Date;
+}
+export declare class UserExternalConnectionPrivateDocument extends AbstractFirestoreDocument<UserExternalConnectionPrivate, UserExternalConnectionPrivateDocument, typeof userExternalConnectionPrivateIdentity> {
+    get modelIdentity(): import("@dereekb/firebase").RootFirestoreModelIdentity<"userExternalConnectionPrivate", "uecp">;
+}
+/**
+ * Configuration for creating a {@link UserExternalConnectionPrivate} snapshot converter.
+ */
+export interface UserExternalConnectionPrivateConverterConfig {
+    /**
+     * Encryption secret source for the credentials field.
+     */
+    readonly encryptionSecret: AES256GCMEncryptionSecretSource;
+}
+/**
+ * Creates a snapshot converter for {@link UserExternalConnectionPrivate} documents.
+ *
+ * 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.
+ *
+ * @param config - Encryption configuration for the credentials field.
+ * @returns Snapshot converter functions for UserExternalConnectionPrivate documents.
+ */
+export declare function userExternalConnectionPrivateConverter(config: UserExternalConnectionPrivateConverterConfig): import("@dereekb/firebase").SnapshotConverterFunctions<UserExternalConnectionPrivate, Partial<import("@dereekb/util").ReplaceType<UserExternalConnectionPrivate, import("@dereekb/util").MaybeMap<object>, any>>>;
+/**
+ * Copies the document id into `uid` on write, so the stored uid can never drift from the document id.
+ */
+export declare const userExternalConnectionPrivateAccessorFactory: import("@dereekb/firebase").InterceptAccessorFactoryFunction<UserExternalConnectionPrivate, import("@dereekb/firebase").DocumentData>;
+/**
+ * Returns the Firestore {@link CollectionReference} for {@link UserExternalConnectionPrivate} documents.
+ *
+ * @param context - The Firestore context to create the collection reference from.
+ * @returns The typed collection reference.
+ */
+export declare function userExternalConnectionPrivateCollectionReference(context: FirestoreContext): CollectionReference<UserExternalConnectionPrivate>;
+export type UserExternalConnectionPrivateFirestoreCollection = FirestoreCollection<UserExternalConnectionPrivate, UserExternalConnectionPrivateDocument>;
+/**
+ * Configuration for creating a {@link UserExternalConnectionPrivateFirestoreCollection}.
+ */
+export interface UserExternalConnectionPrivateFirestoreCollectionConfig extends UserExternalConnectionPrivateConverterConfig {
+    readonly firestoreContext: FirestoreContext;
+}
+/**
+ * Creates a {@link UserExternalConnectionPrivateFirestoreCollection} with encrypted credentials support.
+ *
+ * @param config - Configuration including the Firestore context and encryption settings.
+ * @returns The configured collection.
+ */
+export declare function userExternalConnectionPrivateFirestoreCollection(config: UserExternalConnectionPrivateFirestoreCollectionConfig): UserExternalConnectionPrivateFirestoreCollection;
+/**
+ * Projects the client-readable facts out of a set of credentials.
+ *
+ * This is the ONLY bridge between the private and public halves of the pair. Because the summary
+ * entry is derived from this projection, the public document cannot describe scopes, an account, or
+ * an expiration that the credentials do not actually carry.
+ *
+ * @param credentials - The credentials to project.
+ * @returns The grant summary the public entry is derived from.
+ */
+export declare function userExternalConnectionGrantSummaryFromCredentials(credentials: UserExternalConnectionCredentials): UserExternalConnectionGrantSummary;
+/**
+ * Input for {@link mergeRefreshedUserExternalConnectionCredentials}.
+ */
+export interface MergeRefreshedUserExternalConnectionCredentialsInput {
+    /**
+     * The credentials that were stored before the refresh.
+     */
+    readonly previous: UserExternalConnectionCredentials;
+    /**
+     * The credentials a refresh produced.
+     */
+    readonly refreshed: UserExternalConnectionCredentials;
+}
+/**
+ * Merges refreshed credentials over the stored ones, retaining anything the refresh response omitted.
+ *
+ * Required because the paired write replaces a provider's credentials WHOLESALE (see
+ * {@link applyUserExternalConnectionCredentials}) — so persisting a refresh response verbatim erases
+ * every field the provider did not resend, while leaving the entry `connected`. Two of those are
+ * load-bearing:
+ *
+ * - `refreshToken`, which Zoho (and any provider that issues one only on first consent) omits on
+ *   refresh. Losing it yields a connection that can never be refreshed again and does not look broken.
+ * - `extra`, which carries the values needed to USE the credentials — Zoho's `apiDomain` and the
+ *   `accountsServer` datacenter a later refresh must be sent to. Dropping `accountsServer` breaks the
+ *   refresh AFTER this one, which is considerably harder to attribute.
+ *
+ * `extra` is merged key-by-key rather than replaced, so a refresh that resends only `apiDomain` still
+ * updates it without discarding the rest. Keys the refresh left UNDEFINED are dropped before merging,
+ * because an object literal built with an absent optional field carries the key with an undefined value
+ * and a plain spread would use it to erase the stored one. A refresh that means to CLEAR a key can
+ * still say so with an explicit null.
+ *
+ * The generalization of `AbstractUserExternalConnectionOAuthService.credentialsRetainingStoredRefreshToken`,
+ * which does the same thing for the authorization-code exchange.
+ *
+ * @param input - The stored credentials and the refreshed ones.
+ * @returns The credentials to persist.
+ */
+export declare function mergeRefreshedUserExternalConnectionCredentials(input: MergeRefreshedUserExternalConnectionCredentialsInput): UserExternalConnectionCredentials;
+/**
+ * Input for {@link applyUserExternalConnectionCredentials}.
+ */
+export interface ApplyUserExternalConnectionCredentialsInput {
+    /**
+     * The currently stored private document, when one exists.
+     */
+    readonly current?: Maybe<UserExternalConnectionPrivate>;
+    readonly uid: FirebaseAuthUserId;
+    readonly providerType: UserExternalConnectionProviderType;
+    /**
+     * The next credentials for this provider, or null to remove the provider's key entirely.
+     */
+    readonly credentials: Maybe<UserExternalConnectionCredentials>;
+    readonly now: Date;
+}
+/**
+ * Applies a single provider's credentials and returns the COMPLETE next private document.
+ *
+ * The counterpart of `applyUserExternalConnectionEntry()` — both are always called with the same
+ * provider and instant inside one transaction.
+ *
+ * @param input - The current document plus the credentials to apply.
+ * @returns The next UserExternalConnectionPrivate value to write.
+ */
+export declare function applyUserExternalConnectionCredentials(input: ApplyUserExternalConnectionCredentialsInput): UserExternalConnectionPrivate;