@dereekb/firebase-server 13.31.0 → 13.33.0

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

@@ -0,0 +1,68 @@
+import { type Request, type Response } from 'express';
+import { type Maybe } from '@dereekb/util';
+import { type AbstractUserExternalConnectionOAuthService, type UserExternalConnectionOAuthCallbackQueryValues, type UserExternalConnectionOAuthState } from './userexternalconnection.oauth.service';
+/**
+ * HTTP status used for the handoff redirects.
+ *
+ * A 302 keeps the redirect non-cacheable, which matters because each authorize URL carries a
+ * single-use `state`.
+ */
+export declare const USER_EXTERNAL_CONNECTION_OAUTH_REDIRECT_STATUS = 302;
+/**
+ * Query parameters a provider sends to the redirect URI.
+ *
+ * Snake-cased because these are the wire names — `error_description` is what RFC 6749 4.1.2.1
+ * specifies, so it is read as-is rather than renamed at the boundary.
+ */
+export interface UserExternalConnectionOAuthCallbackQuery extends UserExternalConnectionOAuthCallbackQueryValues {
+    readonly code?: Maybe<string>;
+    readonly state?: Maybe<UserExternalConnectionOAuthState>;
+    readonly error?: Maybe<string>;
+    readonly error_description?: Maybe<string>;
+}
+/**
+ * The two endpoints of an external-connection authorization-code handoff.
+ *
+ * A provider ships its own controller so it keeps full control of its route surface; extending this
+ * means it declares only the mount point and its constructor:
+ *
+ * ```ts
+ * @Controller(CALCOM_USER_EXTERNAL_CONNECTION_OAUTH_CONTROLLER_PATH)
+ * export class CalcomUserExternalConnectionOAuthController extends AbstractUserExternalConnectionOAuthController {
+ *   constructor(@Inject(CalcomUserExternalConnectionOAuthService) readonly oauthService: CalcomUserExternalConnectionOAuthService) {
+ *     super();
+ *   }
+ * }
+ * ```
+ *
+ * Mount at {@link userExternalConnectionOAuthControllerPath}, and exclude those routes from any
+ * global API route prefix with {@link userExternalConnectionOAuthRoutesForGlobalRouteExclude} — the
+ * redirect URI registered with a provider must match byte-for-byte, so a prefix silently breaks it.
+ */
+export declare abstract class AbstractUserExternalConnectionOAuthController {
+    abstract readonly oauthService: AbstractUserExternalConnectionOAuthService;
+    /**
+     * Begins the handoff by redirecting the user's browser to the provider's consent screen.
+     *
+     * Carries the `state` resolved for the request; a request without one is bounced to the failure
+     * URL rather than sent to the provider.
+     *
+     * @param request - The incoming authorize request, which the state is read from.
+     * @param response - The response to issue the redirect on.
+     */
+    authorize(request: Request, response: Response): void;
+    /**
+     * Completes the handoff: verifies the returned `state`, exchanges the authorization code, and
+     * redirects to the configured success or failure URL.
+     *
+     * On refusal a provider sends `error` / `error_description` in place of a `code` (RFC 6749
+     * 4.1.2.1), so both are read and passed through — otherwise a rejected scope or a denied consent
+     * is indistinguishable from a missing code.
+     *
+     * @param query - The callback query parameters: `code` + `state` on approval, or `error` +
+     *   `error_description` on refusal. Passed through whole, so a provider adapter can read the
+     *   extras its exchange needs.
+     * @param response - The response to issue the redirect on.
+     */
+    callback(query: UserExternalConnectionOAuthCallbackQuery, response: Response): Promise<void>;
+}

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

@@ -0,0 +1,29 @@
+import { type UserExternalConnectionErrorCode } from '@dereekb/firebase';
+import { type Maybe } from '@dereekb/util';
+/**
+ * An error a provider reported on the redirect back, rather than one thrown on our side.
+ *
+ * Per RFC 6749 4.1.2.1 the authorization server redirects to the `redirect_uri` with these instead
+ * of a `code` when it refuses the request. Reading them is what keeps a declined consent or a
+ * rejected scope from being misreported as a missing authorization code.
+ */
+export interface UserExternalConnectionOAuthProviderError {
+    /**
+     * The OAuth error code, e.g. `invalid_request`, `invalid_scope`, `access_denied`.
+     */
+    readonly error: string;
+    /**
+     * The provider's human-readable explanation, when it sent one.
+     */
+    readonly errorDescription?: Maybe<string>;
+}
+/**
+ * Maps an OAuth refusal reported by a provider to the connection entry's error code.
+ *
+ * The codes are the standard OAuth 2.0 ones, so this mapping is the same for every provider. A
+ * failure thrown on our own side has no provider error and stays `provider_error`.
+ *
+ * @param providerError - The error the provider reported on the redirect, when it reported one.
+ * @returns The error code to record on the connection entry.
+ */
+export declare function userExternalConnectionErrorCodeForOAuthProviderError(providerError: Maybe<UserExternalConnectionOAuthProviderError>): UserExternalConnectionErrorCode;

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

@@ -0,0 +1,24 @@
+import { type UserExternalConnectionCredentialsRefresher } from '../userexternalconnection.refresh.service';
+import { type UserExternalConnectionOAuthProviderRegistry } from './userexternalconnection.oauth.registry';
+/**
+ * Configuration for {@link userExternalConnectionOAuthRegistryCredentialsRefresher}.
+ */
+export interface UserExternalConnectionOAuthRegistryCredentialsRefresherConfig {
+    readonly registry: UserExternalConnectionOAuthProviderRegistry;
+}
+/**
+ * Creates a {@link UserExternalConnectionCredentialsRefresher} that renews credentials through the
+ * app's registered OAuth provider services.
+ *
+ * The bridge between the two layers: the reader knows it needs a refresh but nothing about providers,
+ * and each provider service knows how to refresh but nothing about who is asking. Dispatch is by
+ * provider type, so a provider the app never registered — or registered without a `refreshCredentials`
+ * implementation — resolves to null, which the reader reports as "cannot renew" rather than as a
+ * failure of the provider.
+ *
+ * @param config - The provider registry to dispatch through.
+ * @returns A refresher backed by the registry.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function userExternalConnectionOAuthRegistryCredentialsRefresher(config: UserExternalConnectionOAuthRegistryCredentialsRefresherConfig): UserExternalConnectionCredentialsRefresher;

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

@@ -0,0 +1,54 @@
+import { type InjectionToken, type Provider } from '@nestjs/common';
+import { type UserExternalConnectionProviderType } from '@dereekb/firebase';
+import { type Maybe } from '@dereekb/util';
+import { type AbstractUserExternalConnectionOAuthService } from './userexternalconnection.oauth.service';
+/**
+ * The providers an app has an OAuth authorize/callback flow mounted for.
+ *
+ * Built FROM the registered services rather than from a hand-maintained list, so it cannot disagree
+ * with which provider modules the app actually imported. A provider absent from it has no endpoint
+ * to send the user to, so minting a state for it would hand back something unusable.
+ */
+export declare abstract class UserExternalConnectionOAuthProviderRegistry {
+    abstract readonly providerTypes: ReadonlySet<UserExternalConnectionProviderType>;
+    /**
+     * Whether the app can begin an OAuth handoff for this provider.
+     */
+    abstract hasAuthorizeFlowForProviderType(providerType: UserExternalConnectionProviderType): boolean;
+    /**
+     * Throws when the app has no OAuth handoff for this provider.
+     *
+     * @throws A precondition-conflict HttpsError.
+     */
+    abstract assertHasAuthorizeFlowForProviderType(providerType: UserExternalConnectionProviderType): void;
+    /**
+     * The registered service for a provider, when there is one.
+     */
+    abstract serviceForProviderType(providerType: UserExternalConnectionProviderType): Maybe<AbstractUserExternalConnectionOAuthService>;
+}
+/**
+ * Creates the registry from the app's registered OAuth services.
+ *
+ * @param services - Every {@link AbstractUserExternalConnectionOAuthService} the app has mounted.
+ * @returns The registry.
+ * @throws {Error} When two services claim the same provider type.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function userExternalConnectionOAuthProviderRegistry(services: AbstractUserExternalConnectionOAuthService[]): UserExternalConnectionOAuthProviderRegistry;
+/**
+ * Creates the NestJS provider for the {@link UserExternalConnectionOAuthProviderRegistry}.
+ *
+ * Declared by the app rather than by the UserExternalConnection module, because each provider module
+ * imports that module for its actions and state coder — so the registry must live somewhere that can
+ * import the provider modules without a cycle.
+ *
+ * Registering a provider is then one module import plus one token here.
+ *
+ * @param oauthServiceTokens - Tokens of the registered `AbstractUserExternalConnectionOAuthService`
+ *   providers, whose modules must be imported by the declaring module.
+ * @returns The NestJS provider.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function userExternalConnectionOAuthProviderRegistryProvider(oauthServiceTokens: InjectionToken[]): Provider;

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;