@dereekb/firebase-server 13.32.0 → 13.33.0

package/model/src/lib/userexternalconnection/oauth/userexternalconnection.oauth.state.d.ts

@@ -0,0 +1,114 @@
+import { type ConfigService } from '@nestjs/config';
+import { type AES256GCMEncryptionSecret } from '@dereekb/nestjs';
+import { type FirebaseServerEnvService } from '@dereekb/firebase-server';
+import { type FirebaseAuthUserId, type UserExternalConnectionProviderType } from '@dereekb/firebase';
+import { type Maybe, type Milliseconds } from '@dereekb/util';
+/**
+ * Secret the external-connection OAuth `state` is encrypted with.
+ *
+ * Provider-agnostic on purpose: `state` is part of the OAuth 2.0 authorization-code flow itself
+ * (RFC 6749 4.1.1) and every provider echoes it back opaquely, so one secret serves the whole
+ * registry no matter how many providers are registered.
+ *
+ * Deliberately NOT the credentials secret. `USER_EXTERNAL_CONNECTION_ENCRYPTION_SECRET` is
+ * write-once — rotating it makes every stored `uecp` credential permanently undecryptable — whereas
+ * this one is freely rotatable, since a state lives for minutes and rotating it only invalidates
+ * handoffs that are mid-flight.
+ */
+export declare const USER_EXTERNAL_CONNECTION_STATE_SECRET_CONFIG_KEY = "USER_EXTERNAL_CONNECTION_STATE_SECRET";
+/**
+ * Deterministic secret used when running in a testing environment and no real secret is configured,
+ * so specs never need a live credential.
+ */
+export declare const TESTING_USER_EXTERNAL_CONNECTION_STATE_SECRET: AES256GCMEncryptionSecret;
+/**
+ * How long a minted `state` stays valid.
+ *
+ * Long enough for a user to work through a provider's consent screen, short enough that a leaked
+ * state is not reusable later.
+ */
+export declare const DEFAULT_USER_EXTERNAL_CONNECTION_STATE_EXPIRATION: Milliseconds;
+/**
+ * The payload carried inside an encrypted external-connection OAuth `state`.
+ */
+export interface UserExternalConnectionStatePayload {
+    /**
+     * The user the handoff belongs to.
+     */
+    readonly uid: FirebaseAuthUserId;
+    /**
+     * The provider the handoff was started for.
+     *
+     * Verified on the way back, so a state minted to connect one provider cannot be replayed against
+     * another provider's callback.
+     */
+    readonly providerType: UserExternalConnectionProviderType;
+    /**
+     * Epoch milliseconds after which the state is rejected.
+     */
+    readonly exp: number;
+}
+/**
+ * Who a verified state belongs to.
+ */
+export interface UserExternalConnectionStateActor {
+    readonly uid: FirebaseAuthUserId;
+}
+export interface MintUserExternalConnectionStateInput {
+    readonly uid: FirebaseAuthUserId;
+    readonly providerType: UserExternalConnectionProviderType;
+}
+export interface VerifyUserExternalConnectionStateInput {
+    readonly state: Maybe<string>;
+    /**
+     * The provider whose callback is verifying. A state minted for a different provider is rejected.
+     */
+    readonly providerType: UserExternalConnectionProviderType;
+}
+export interface UserExternalConnectionStateCoderConfig {
+    readonly secret: AES256GCMEncryptionSecret;
+    /**
+     * How long a minted state stays valid. Defaults to {@link DEFAULT_USER_EXTERNAL_CONNECTION_STATE_EXPIRATION}.
+     */
+    readonly expiresIn?: Maybe<Milliseconds>;
+}
+/**
+ * Mints and verifies the OAuth `state` for external-connection handoffs.
+ *
+ * Declared as an abstract class so it is its own injection token, matching
+ * `UserExternalConnectionModuleConfig`. One coder is shared by every registered provider.
+ */
+export declare abstract class UserExternalConnectionStateCoder {
+    /**
+     * Mints a short-lived state for a user's connect handoff with a provider.
+     */
+    abstract readonly mintState: (input: MintUserExternalConnectionStateInput) => string;
+    /**
+     * Resolves the user a state belongs to, or null when it is absent, tampered with, expired, or was
+     * minted for a different provider.
+     */
+    abstract readonly verifyState: (input: VerifyUserExternalConnectionStateInput) => Maybe<UserExternalConnectionStateActor>;
+}
+/**
+ * Creates the coder that mints and verifies the OAuth `state` for external-connection handoffs.
+ *
+ * The state is what lets a provider's redirect back to us be attributed to a user: the authorize
+ * request is a top-level browser navigation and carries no credentials of its own. Tamper-evidence
+ * is the requirement; AES-256-GCM is used because its auth tag provides that and additionally keeps
+ * the uid opaque to the browser.
+ *
+ * @param config - The encryption secret and optional expiration.
+ * @returns The state coder.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function userExternalConnectionStateCoder(config: UserExternalConnectionStateCoderConfig): UserExternalConnectionStateCoder;
+/**
+ * Builds the external-connection state coder from the environment.
+ *
+ * @param configService - The Nest config service used to read the state secret.
+ * @param envService - Used to detect a testing environment for the secret fallback.
+ * @returns The state coder.
+ * @throws {Error} When the configured secret is invalid outside a testing environment.
+ */
+export declare function userExternalConnectionStateCoderFactory(configService: ConfigService, envService: FirebaseServerEnvService): UserExternalConnectionStateCoder;

package/model/src/lib/userexternalconnection/userexternalconnection.accessor.service.d.ts

@@ -0,0 +1,111 @@
+import { type FactoryWithRequiredInput, type Maybe } from '@dereekb/util';
+import { type FirebaseAuthUserId, type FirebaseAuthUserIdRef, type UserExternalConnectionEntry, type UserExternalConnectionFirestoreCollections, type UserExternalConnectionProviderType } from '@dereekb/firebase';
+import { type UserExternalConnectionCredentials, type UserExternalConnectionServerFirestoreCollections } from './userexternalconnection.private';
+/**
+ * Context required by {@link userExternalConnectionAccessor}.
+ *
+ * Carries both halves of the pair, the same as the server actions context. Unlike that context there
+ * is no `FirestoreContextReference` here: every read is a plain document read, so nothing in this
+ * file needs to start a transaction.
+ */
+export interface UserExternalConnectionAccessorContext extends UserExternalConnectionFirestoreCollections, UserExternalConnectionServerFirestoreCollections {
+}
+/**
+ * Identifies the one provider entry a read is about.
+ */
+export interface UserExternalConnectionReadParams {
+    readonly uid: FirebaseAuthUserId;
+    readonly providerType: UserExternalConnectionProviderType;
+}
+/**
+ * Both halves of a user's connection state for a single provider.
+ *
+ * The public entry and the private credentials are returned together because a caller deciding
+ * whether it can act as this user needs both: the credentials alone cannot say whether the
+ * connection is `connected` or `error`, and the entry alone cannot be used to call anything.
+ *
+ * Either side may be null. A user with no connection document at all reads as both null.
+ */
+export interface UserExternalConnectionForProvider {
+    readonly uid: FirebaseAuthUserId;
+    readonly providerType: UserExternalConnectionProviderType;
+    /**
+     * The provider's entry on the client-readable document, when the user has one.
+     */
+    readonly entry: Maybe<UserExternalConnectionEntry>;
+    /**
+     * The provider's stored credentials in plaintext, when the user has any.
+     */
+    readonly credentials: Maybe<UserExternalConnectionCredentials>;
+}
+/**
+ * Input identifying the user a {@link UserExternalConnectionAccessorUserInstance} reads for.
+ */
+export interface UserExternalConnectionAccessorUserInput extends FirebaseAuthUserIdRef {
+}
+/**
+ * A {@link UserExternalConnectionAccessor} narrowed to ONE user and ONE provider.
+ *
+ * The accessor's entire read surface with `{ uid, providerType }` already applied.
+ */
+export interface UserExternalConnectionAccessorProviderInstance {
+    readonly uid: FirebaseAuthUserId;
+    readonly providerType: UserExternalConnectionProviderType;
+    /**
+     * Loads both halves of the pair.
+     */
+    readUserExternalConnectionForProvider(): Promise<UserExternalConnectionForProvider>;
+    /**
+     * Loads only the stored credentials.
+     */
+    readUserExternalConnectionCredentials(): Promise<Maybe<UserExternalConnectionCredentials>>;
+}
+/**
+ * A {@link UserExternalConnectionAccessor} narrowed to one user, awaiting the provider to target.
+ */
+export type UserExternalConnectionAccessorUserInstance = FactoryWithRequiredInput<UserExternalConnectionAccessorProviderInstance, UserExternalConnectionProviderType>;
+/**
+ * Server-only read surface for the UserExternalConnection document pair.
+ *
+ * Deliberately the whole read surface and nothing more: no expiration policy, no refresh, no
+ * assertions. That keeps this usable by the OAuth provider services themselves — they need to read
+ * the credentials they are about to replace, and a tier that could refresh would have to know about
+ * the provider registry those services are registered in.
+ *
+ * {@link UserExternalConnectionReader} wraps this and adds the policy.
+ */
+export declare abstract class UserExternalConnectionAccessor {
+    /**
+     * Narrows this accessor to one user, returning a factory that narrows it further to one provider.
+     *
+     * The accessor's only entry point, and the same two levels
+     * {@link UserExternalConnectionReader.readerForUser} has, so a caller holding either states the user
+     * and provider it is reading for once:
+     *
+     * ```ts
+     * const credentials = await accessor.accessorForUser({ uid })(CALCOM).readUserExternalConnectionCredentials();
+     * ```
+     *
+     * @param input - The user to read for.
+     * @returns A factory producing an accessor for whichever of that user's providers is needed.
+     */
+    abstract accessorForUser(input: UserExternalConnectionAccessorUserInput): UserExternalConnectionAccessorUserInstance;
+}
+/**
+ * Reference to a {@link UserExternalConnectionAccessor} instance.
+ */
+export interface UserExternalConnectionAccessorRef {
+    readonly userExternalConnectionAccessor: UserExternalConnectionAccessor;
+}
+/**
+ * Creates a {@link UserExternalConnectionAccessor} bound to the given context.
+ *
+ * Reads are NOT paired the way writes are. The pairing is a write invariant — the two documents are
+ * only ever written together, so a read of one cannot observe a state the other contradicts, and
+ * reading them in a transaction would buy nothing. Server paths load both halves; the client can only
+ * ever load the public one.
+ *
+ * @param context - The context carrying both halves of the pair.
+ * @returns A concrete UserExternalConnectionAccessor implementation.
+ */
+export declare function userExternalConnectionAccessor(context: UserExternalConnectionAccessorContext): UserExternalConnectionAccessor;

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;