@dereekb/firebase-server 13.32.0 → 13.34.0

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

@@ -0,0 +1,216 @@
+import { Logger } from '@nestjs/common';
+import { type Request } from 'express';
+import { type FirebaseAuthUserId, type UserExternalConnectionProviderType } from '@dereekb/firebase';
+import { type Maybe, type WebsiteUrl } from '@dereekb/util';
+import { type UserExternalConnectionCredentials } from '../userexternalconnection.private';
+import { type UserExternalConnectionAccessor } from '../userexternalconnection.accessor.service';
+import { type UserExternalConnectionServerActions } from '../userexternalconnection.action.server';
+import { type UserExternalConnectionStateCoder } from './userexternalconnection.oauth.state';
+import { type UserExternalConnectionOAuthServiceConfig } from './userexternalconnection.oauth.config';
+/**
+ * The `state` value carried through the authorization-code handoff.
+ *
+ * Opaque to the provider: only {@link UserExternalConnectionStateCoder} can interpret it.
+ */
+export type UserExternalConnectionOAuthState = string;
+/**
+ * Identifies who a handoff belongs to, as resolved from a verified `state`.
+ */
+export interface UserExternalConnectionOAuthActor {
+    readonly uid: FirebaseAuthUserId;
+}
+/**
+ * The raw callback query, as the provider sent it.
+ *
+ * Kept open rather than narrowed to the four RFC 6749 parameters, because providers send more than
+ * those and some of the extras are load-bearing: Zoho's `accounts-server` names the datacenter that
+ * issued the code, and an exchange sent to the wrong one fails. Nest's keyless `@Query()` already
+ * receives every parameter — only the typed view was dropping them.
+ *
+ * Declared here rather than beside the controller's typed view so the service does not have to
+ * import from the controller that imports it.
+ */
+export type UserExternalConnectionOAuthCallbackQueryValues = Record<string, Maybe<string>>;
+export interface UserExternalConnectionOAuthExchangeInput {
+    /**
+     * The authorization code the provider issued.
+     */
+    readonly code: string;
+    /**
+     * The redirect URI the code was issued against. Sent on the exchange because providers require it
+     * to match the one used on the authorize request.
+     */
+    readonly redirectUri: WebsiteUrl;
+    /**
+     * The raw callback query, for a provider whose exchange needs a parameter beyond `code`.
+     *
+     * Optional, and most providers ignore it. Anything read from here arrived on a redirect the user's
+     * browser followed, so treat it as untrusted input — in particular, never use a value from here as
+     * a request target without checking it against an allowlist first.
+     */
+    readonly query?: Maybe<UserExternalConnectionOAuthCallbackQueryValues>;
+}
+export interface UserExternalConnectionOAuthHandleCallbackInput {
+    /**
+     * The authorization code, present when the provider approved the request.
+     */
+    readonly code?: Maybe<string>;
+    /**
+     * The state echoed back, identifying who is connecting.
+     */
+    readonly state?: Maybe<UserExternalConnectionOAuthState>;
+    /**
+     * The OAuth error code, present when the provider refused instead of issuing a code.
+     */
+    readonly error?: Maybe<string>;
+    /**
+     * The provider's explanation of the refusal.
+     */
+    readonly errorDescription?: Maybe<string>;
+    /**
+     * The raw callback query, passed through to the exchange unchanged.
+     */
+    readonly query?: Maybe<UserExternalConnectionOAuthCallbackQueryValues>;
+}
+/**
+ * Input for {@link AbstractUserExternalConnectionOAuthService.credentialsRetainingStoredRefreshToken}.
+ */
+export interface UserExternalConnectionOAuthRetainRefreshTokenInput {
+    readonly uid: FirebaseAuthUserId;
+    /**
+     * The credentials the exchange produced.
+     */
+    readonly credentials: UserExternalConnectionCredentials;
+}
+/**
+ * Input for {@link AbstractUserExternalConnectionOAuthService.refreshCredentials}.
+ *
+ * Carries no `providerType` — the service already knows its own, and taking one would create a
+ * parameter that could disagree with it.
+ */
+export interface UserExternalConnectionOAuthRefreshCredentialsInput {
+    readonly uid: FirebaseAuthUserId;
+    /**
+     * The credentials currently stored for this provider, carrying the refresh token and any
+     * provider-specific `extra` the exchange needs.
+     */
+    readonly credentials: UserExternalConnectionCredentials;
+}
+export interface UserExternalConnectionOAuthCallbackResult {
+    readonly success: boolean;
+    /**
+     * The URL the user should be redirected to.
+     */
+    readonly redirectUrl: WebsiteUrl;
+}
+/**
+ * Reads the `state` an authorize request should carry to the provider.
+ *
+ * A top-level browser navigation carries no credentials, so the state must have been minted by a
+ * prior authenticated `read:authorizeState` call and arrive here as the `state` query parameter.
+ *
+ * @param request - The incoming authorize request.
+ * @returns The state, when present.
+ */
+export declare function userExternalConnectionOAuthStateForRequest(request: Request): Maybe<UserExternalConnectionOAuthState>;
+/**
+ * Drives a provider's authorization-code handoff into a user's UserExternalConnection.
+ *
+ * Everything except the two abstract members is identical for every OAuth 2.0 provider: resolving
+ * who is connecting from the signed `state`, surfacing a provider-side refusal, persisting the
+ * credentials, recording the failure code, and choosing the redirect. A provider adapter extends
+ * this and supplies only the OAuth mechanics its service actually differs on.
+ *
+ * Subclasses expose `config`, `stateCoder`, `userExternalConnectionActions`, and
+ * `userExternalConnectionAccessor` as injected constructor properties.
+ */
+export declare abstract class AbstractUserExternalConnectionOAuthService {
+    abstract readonly config: UserExternalConnectionOAuthServiceConfig;
+    abstract readonly stateCoder: UserExternalConnectionStateCoder;
+    abstract readonly userExternalConnectionActions: UserExternalConnectionServerActions;
+    /**
+     * The read half of the pair.
+     *
+     * Deliberately the accessor rather than `UserExternalConnectionReader`: the reader can refresh, and
+     * it finds its refresh path through the registry these services are registered in — so depending on
+     * it here would be a cycle. This service needs only the raw read.
+     */
+    abstract readonly userExternalConnectionAccessor: UserExternalConnectionAccessor;
+    private readonly _logger;
+    protected get logger(): Logger;
+    get providerType(): UserExternalConnectionProviderType;
+    get redirectUri(): WebsiteUrl;
+    get successUrl(): WebsiteUrl;
+    get failureUrl(): WebsiteUrl;
+    /**
+     * PROVIDER: builds the provider's consent-screen URL carrying the minted state.
+     *
+     * @param state - The signed state to echo back on the callback.
+     * @returns The authorize URL to redirect the user's browser to.
+     */
+    protected abstract authorizeUrlForState(state: UserExternalConnectionOAuthState): WebsiteUrl;
+    /**
+     * PROVIDER: exchanges the authorization code and maps the token response to credentials.
+     *
+     * Both halves are the provider's own: token endpoints differ in body encoding and client
+     * authentication, and only the provider knows how its response maps onto
+     * {@link UserExternalConnectionCredentials}. When a provider rotates its refresh token, the
+     * rotated one must be the one returned here — the token the exchange started with is spent.
+     *
+     * @param input - The authorization code, the redirect URI it was issued against, and the raw
+     *   callback query.
+     * @returns The credentials to persist.
+     */
+    protected abstract credentialsForAuthorizationCode(input: UserExternalConnectionOAuthExchangeInput): Promise<UserExternalConnectionCredentials>;
+    /**
+     * PROVIDER (optional): exchanges the stored refresh token for new credentials.
+     *
+     * Optional because not every provider has a refresh path worth wiring — and because a provider that
+     * does not implement this stays correct rather than silently broken: `UserExternalConnectionReader`
+     * treats its absence as "cannot renew" and makes the user reconnect.
+     *
+     * PUBLIC, unlike the two abstract members above, because the reader reaches it through the provider
+     * registry rather than through a subclass.
+     *
+     * Implementations return what the provider issued and do NOT need to carry forward values the
+     * response omitted — the reader merges every result over the stored credentials.
+     *
+     * @param input - The acting user and the credentials currently stored.
+     * @returns The refreshed credentials.
+     */
+    refreshCredentials?(input: UserExternalConnectionOAuthRefreshCredentialsInput): Promise<UserExternalConnectionCredentials>;
+    /**
+     * Carries the stored refresh token forward when a provider's exchange returned none.
+     *
+     * The paired write replaces a provider's credentials wholesale, so persisting an exchange that
+     * omitted `refresh_token` would DESTROY a working one while leaving the entry `connected` — a
+     * connection that can never be refreshed again and does not look broken. Providers that do not
+     * rotate their refresh token (Zoho, and others that issue one only on first consent) hit this on
+     * every reconnect; a rotating provider never reaches the read.
+     *
+     * A read failure is deliberately allowed to propagate: failing the handoff loudly is strictly
+     * better than clobbering the stored token.
+     *
+     * @param input - The acting user and the credentials the exchange produced.
+     * @returns The credentials to persist, with a stored refresh token retained when the exchange
+     *   returned none.
+     */
+    protected credentialsRetainingStoredRefreshToken(input: UserExternalConnectionOAuthRetainRefreshTokenInput): Promise<UserExternalConnectionCredentials>;
+    /**
+     * Builds the authorize URL to redirect an incoming `/authorize` request to.
+     *
+     * @param request - The incoming authorize request, which the state is read from.
+     * @returns The authorize URL, or null when the request carried no state.
+     */
+    authorizeUrlForRequest(request: Request): Maybe<WebsiteUrl>;
+    /**
+     * Verifies the returned state, exchanges the authorization code, and persists the credentials.
+     *
+     * A refusal reported by the provider (`error` / `error_description`) is surfaced as the failure
+     * reason, so a rejected scope or a denied consent is not misreported as a missing code.
+     *
+     * @param input - The query parameters the provider redirected back with.
+     * @returns Where to redirect the user, and whether the handoff succeeded.
+     */
+    handleCallback(input: UserExternalConnectionOAuthHandleCallbackInput): Promise<UserExternalConnectionOAuthCallbackResult>;
+}

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;