@dereekb/firebase-server 13.32.0 → 13.34.0

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;

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

@@ -0,0 +1,157 @@
+import { type FactoryWithRequiredInput, type Maybe, type Milliseconds } from '@dereekb/util';
+import { type FirebaseAuthUserId, type FirebaseAuthUserIdRef, type UserExternalConnectionErrorCode, type UserExternalConnectionProviderType } from '@dereekb/firebase';
+import { type UserExternalConnectionAccessor, type UserExternalConnectionForProvider, type UserExternalConnectionReadParams } from './userexternalconnection.accessor.service';
+import { type UserExternalConnectionCredentials } from './userexternalconnection.private';
+import { type UserExternalConnectionCredentialsRefresher } from './userexternalconnection.refresh.service';
+import { type UserExternalConnectionCredentialsAndFailureWriter } from './userexternalconnection.action.server';
+/**
+ * How long before its stated expiration a set of credentials is treated as already expired.
+ *
+ * A token that expires mid-flight is indistinguishable from one that was never valid, so the check
+ * needs headroom. One minute matches the `tokenExpirationBuffer` default that the Cal.com and Zoho
+ * token factories already use, so a credential this reader hands out is one those factories would also
+ * consider live.
+ */
+export declare const DEFAULT_USER_EXTERNAL_CONNECTION_CREDENTIALS_EXPIRATION_BUFFER: Milliseconds;
+/**
+ * The error code recorded when a refresh attempt fails.
+ *
+ * `expired` rather than `revoked`: a failed refresh is nearly always `invalid_grant`, which does not
+ * distinguish a revoked grant from a refresh token that was already spent, and claiming the user
+ * revoked access when they did not would send the UI down the wrong path.
+ */
+export declare const DEFAULT_USER_EXTERNAL_CONNECTION_REFRESH_FAILURE_ERROR_CODE: UserExternalConnectionErrorCode;
+/**
+ * Configuration for {@link userExternalConnectionReader}.
+ */
+export interface UserExternalConnectionReaderConfig {
+    /**
+     * The paired read surface this reader adds policy on top of.
+     */
+    readonly accessor: UserExternalConnectionAccessor;
+    /**
+     * Used to persist a refresh and to record a failure. Both go through the paired write.
+     *
+     * Narrowed to those two writes: a full `UserExternalConnectionServerActions` satisfies it, and
+     * a caller wiring a reader over something else does not have to implement writes it never reaches.
+     */
+    readonly actions: UserExternalConnectionCredentialsAndFailureWriter;
+    /**
+     * Optional. Without one, expired credentials cannot be renewed and
+     * {@link UserExternalConnectionReaderProviderInstance.readUsableUserExternalConnectionCredentials}
+     * throws instead.
+     */
+    readonly refresher?: Maybe<UserExternalConnectionCredentialsRefresher>;
+    /**
+     * How long before its stated expiration a credential is treated as expired. Defaults to
+     * {@link DEFAULT_USER_EXTERNAL_CONNECTION_CREDENTIALS_EXPIRATION_BUFFER}.
+     */
+    readonly expirationBuffer?: Maybe<Milliseconds>;
+}
+/**
+ * Why a provider rejected a user's credentials.
+ */
+export interface UserExternalConnectionReportFailureInput {
+    /**
+     * Why the credentials were rejected. Defaults to `unauthorized`, the code for the 401 this is
+     * almost always called in response to.
+     */
+    readonly error?: Maybe<UserExternalConnectionErrorCode>;
+}
+/**
+ * Parameters for reporting that a provider rejected a user's credentials.
+ */
+export interface UserExternalConnectionReportFailureParams extends UserExternalConnectionReadParams, UserExternalConnectionReportFailureInput {
+}
+/**
+ * Input identifying the user a {@link UserExternalConnectionReaderUserInstance} reads for.
+ */
+export interface UserExternalConnectionReaderUserInput extends FirebaseAuthUserIdRef {
+}
+/**
+ * A {@link UserExternalConnectionReader} narrowed to ONE user and ONE provider.
+ *
+ * The reader's entire read surface, with `{ uid, providerType }` already applied — so a consumer acting
+ * as one user against one provider, the normal case for code making provider API calls, states that
+ * pair once instead of at every call and cannot accidentally mix two providers up.
+ */
+export interface UserExternalConnectionReaderProviderInstance {
+    readonly uid: FirebaseAuthUserId;
+    readonly providerType: UserExternalConnectionProviderType;
+    /**
+     * Loads both halves of the pair, applying no policy. Never throws for an absent or unusable
+     * connection.
+     */
+    readUserExternalConnectionForProvider(): Promise<UserExternalConnectionForProvider>;
+    /**
+     * Loads the stored credentials as-is, applying no policy. They may be expired.
+     */
+    readUserExternalConnectionCredentials(): Promise<Maybe<UserExternalConnectionCredentials>>;
+    /**
+     * Returns credentials that are safe to attempt a provider call with, renewing them first if needed.
+     *
+     * @throws When the user is not connected to the provider, or the credentials have expired and could
+     *   not be renewed.
+     */
+    readUsableUserExternalConnectionCredentials(): Promise<UserExternalConnectionCredentials>;
+    /**
+     * Records that the provider rejected these credentials, moving the entry to the `error` status.
+     *
+     * Exists so a caller that gets a 401 mid-call can report it without reaching for the write surface.
+     * Never throws — a failure to record a failure is logged and swallowed, because the caller is already
+     * handling an error and losing that error to this one would be worse.
+     *
+     * @param input - Why the credentials were rejected. Defaults to `unauthorized`.
+     */
+    reportUserExternalConnectionFailure(input?: Maybe<UserExternalConnectionReportFailureInput>): Promise<void>;
+}
+/**
+ * A {@link UserExternalConnectionReader} narrowed to one user, awaiting the provider to target.
+ *
+ * The second of the reader's two factory levels. Splitting them this way is what lets ONE reader — the
+ * app has a single provider-agnostic instance — be narrowed to a user once and then used against any
+ * number of that user's providers.
+ */
+export type UserExternalConnectionReaderUserInstance = FactoryWithRequiredInput<UserExternalConnectionReaderProviderInstance, UserExternalConnectionProviderType>;
+/**
+ * Reads a user's third-party credentials for a specific provider, and keeps them usable.
+ *
+ * The read surface a consumer should reach for. It wraps a {@link UserExternalConnectionAccessor} and
+ * adds the policy that would otherwise be re-implemented at every call site: whether the connection is
+ * usable, whether the credentials are near enough to expiring to renew, renewing them, persisting the
+ * result, and recording a failure.
+ *
+ * A consumer that has this does not need `UserExternalConnectionServerActions` at all, which is
+ * the point — that class is the write surface.
+ */
+export declare abstract class UserExternalConnectionReader {
+    /**
+     * Narrows this reader to one user, returning a factory that narrows it further to one provider.
+     *
+     * The reader's only entry point. Every read and the failure report live on the narrowed instance, so
+     * a caller states the user and provider it is acting for once instead of threading that pair through
+     * each call:
+     *
+     * ```ts
+     * const connections = reader.readerForUser({ uid });
+     * const credentials = await connections(CALCOM).readUsableUserExternalConnectionCredentials();
+     * ```
+     *
+     * @param input - The user to read for.
+     * @returns A factory producing a reader for whichever of that user's providers is needed.
+     */
+    abstract readerForUser(input: UserExternalConnectionReaderUserInput): UserExternalConnectionReaderUserInstance;
+}
+/**
+ * Reference to a {@link UserExternalConnectionReader} instance.
+ */
+export interface UserExternalConnectionReaderRef {
+    readonly userExternalConnectionReader: UserExternalConnectionReader;
+}
+/**
+ * Creates a {@link UserExternalConnectionReader}.
+ *
+ * @param config - The accessor and actions to build over, plus the optional refresher.
+ * @returns A concrete UserExternalConnectionReader implementation.
+ */
+export declare function userExternalConnectionReader(config: UserExternalConnectionReaderConfig): UserExternalConnectionReader;

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

@@ -0,0 +1,46 @@
+import { type Maybe } from '@dereekb/util';
+import { type FirebaseAuthUserId, type UserExternalConnectionProviderType } from '@dereekb/firebase';
+import { type UserExternalConnectionCredentials } from './userexternalconnection.private';
+/**
+ * Input for {@link UserExternalConnectionCredentialsRefresher.refreshUserExternalConnectionCredentials}.
+ */
+export interface UserExternalConnectionRefreshCredentialsInput {
+    readonly uid: FirebaseAuthUserId;
+    readonly providerType: UserExternalConnectionProviderType;
+    /**
+     * The credentials currently stored for this provider.
+     *
+     * Passed whole rather than as a bare refresh token because a refresh can need more than that:
+     * Zoho's refresh must be sent to the datacenter that issued the grant, which is only recorded on
+     * `extra`.
+     */
+    readonly credentials: UserExternalConnectionCredentials;
+}
+/**
+ * Exchanges a user's stored credentials for fresh ones.
+ *
+ * Declared here rather than beside the OAuth registry on purpose: {@link UserExternalConnectionReader}
+ * takes a refresher as OPTIONAL configuration, and if the reader could only be configured with a
+ * registry-backed one it would have to import the OAuth layer — whose provider services depend on the
+ * accessor the reader is built over. Keeping this an interface in the middle is what keeps that graph
+ * acyclic, and it also lets a caller supply a refresher that has nothing to do with OAuth.
+ *
+ * Implementations return the credentials the provider issued, and are NOT responsible for carrying
+ * forward values the provider's response omits — see `mergeRefreshedUserExternalConnectionCredentials`,
+ * which the reader applies to every result.
+ */
+export declare abstract class UserExternalConnectionCredentialsRefresher {
+    /**
+     * Refreshes one provider's credentials.
+     *
+     * @param input - The acting user, the provider, and the credentials currently stored.
+     * @returns The refreshed credentials, or null when this provider has no refresh path at all.
+     */
+    abstract refreshUserExternalConnectionCredentials(input: UserExternalConnectionRefreshCredentialsInput): Promise<Maybe<UserExternalConnectionCredentials>>;
+}
+/**
+ * Reference to a {@link UserExternalConnectionCredentialsRefresher} instance.
+ */
+export interface UserExternalConnectionCredentialsRefresherRef {
+    readonly userExternalConnectionCredentialsRefresher: UserExternalConnectionCredentialsRefresher;
+}