@dereekb/firebase-server 13.32.0 → 13.34.0

package/model/package.json

@@ -1,19 +1,20 @@
 {
   "name": "@dereekb/firebase-server/model",
-  "version": "13.32.0",
+  "version": "13.34.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.32.0",
-    "@dereekb/date": "13.32.0",
-    "@dereekb/firebase": "13.32.0",
-    "@dereekb/firebase-server": "13.32.0",
-    "@dereekb/model": "13.32.0",
-    "@dereekb/nestjs": "13.32.0",
-    "@dereekb/rxjs": "13.32.0",
-    "@dereekb/util": "13.32.0",
+    "@dereekb/analytics": "13.34.0",
+    "@dereekb/date": "13.34.0",
+    "@dereekb/firebase": "13.34.0",
+    "@dereekb/firebase-server": "13.34.0",
+    "@dereekb/model": "13.34.0",
+    "@dereekb/nestjs": "13.34.0",
+    "@dereekb/rxjs": "13.34.0",
+    "@dereekb/util": "13.34.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "archiver": "^7.0.1",
     "date-fns": "^4.1.0",
+    "express": "^5.2.1",
     "firebase-functions": "^7.2.5",
     "make-error": "^1.3.6",
     "@cantoo/pdf-lib": "^2.6.5",

package/model/src/lib/index.d.ts

@@ -1,3 +1,5 @@
 export * from './mailgun';
 export * from './notification';
 export * from './storagefile';
+export * from './system';
+export * from './userexternalconnection';

package/model/src/lib/system/index.d.ts

@@ -0,0 +1,2 @@
+export * from './system.private';
+export * from './system.private.module';

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

@@ -0,0 +1,63 @@
+import { type Maybe } from '@dereekb/util';
+import { AbstractFirestoreDocument, type CollectionReference, type FirestoreCollection, type FirestoreContext, type SystemState, type SystemStateStoredData, type SystemStateStoredDataConverterMap, type SystemStateUnknownTypeBehavior } from '@dereekb/firebase';
+/**
+ * Provides access to the {@link SystemStatePrivate} collection.
+ *
+ * Provided ONLY by a server module. 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 secrets a private
+ * converter needs — so the private collection structurally cannot leak into the client-shared
+ * collection set.
+ */
+export declare abstract class SystemStatePrivateFirestoreCollections {
+    abstract readonly systemStatePrivateCollection: SystemStatePrivateFirestoreCollection;
+}
+/**
+ * Firestore model identity for {@link SystemStatePrivate} documents.
+ *
+ * The server-only counterpart of `systemStateIdentity` from `@dereekb/firebase`. Same document
+ * shape, same "document id is the type identifier" singleton convention — but a separate `sysp`
+ * collection, so a secret-bearing document is never reachable through the client-shared SystemState
+ * collection or the generic admin model service registered against it.
+ *
+ * This is a server-side only model. It has no provisions for client-side access, and deliberately
+ * has NO `firestore.rules` match block — the implicit default-deny is what denies every client, and
+ * a block here would only create an opportunity to grant access by accident.
+ */
+export declare const systemStatePrivateIdentity: import("@dereekb/firebase").RootFirestoreModelIdentity<"systemStatePrivate", "sysp">;
+export declare class SystemStatePrivateDocument<T extends SystemStateStoredData = SystemStateStoredData> extends AbstractFirestoreDocument<SystemState<T>, SystemStatePrivateDocument<T>, typeof systemStatePrivateIdentity> {
+    get modelIdentity(): import("@dereekb/firebase").RootFirestoreModelIdentity<"systemStatePrivate", "sysp">;
+}
+/**
+ * Returns the Firestore {@link CollectionReference} for {@link SystemStatePrivate} documents.
+ *
+ * @param context - The Firestore context to create the collection reference from.
+ * @returns The typed collection reference.
+ */
+export declare function systemStatePrivateCollectionReference(context: FirestoreContext): CollectionReference<SystemState>;
+export type SystemStatePrivateFirestoreCollection<T extends SystemStateStoredData = SystemStateStoredData> = FirestoreCollection<SystemState<T>, SystemStatePrivateDocument<T>>;
+/**
+ * Configuration for creating a {@link SystemStatePrivateFirestoreCollection}.
+ */
+export interface SystemStatePrivateFirestoreCollectionConfig {
+    readonly firestoreContext: FirestoreContext;
+    /**
+     * Server-only stored-data converters, keyed by SystemStateTypeIdentifier.
+     */
+    readonly converters: SystemStateStoredDataConverterMap;
+    /**
+     * Behavior when a document's type has no registered converter. Defaults to `error`.
+     *
+     * A private type that was not registered must never silently pass through — that would read a
+     * secret-bearing document without its field mapping, returning encrypted fields as raw ciphertext
+     * and dates as raw `Timestamp`s, with nothing to signal it.
+     */
+    readonly unknownTypeBehavior?: Maybe<SystemStateUnknownTypeBehavior>;
+}
+/**
+ * Creates a {@link SystemStatePrivateFirestoreCollection}.
+ *
+ * @param config - The Firestore context, converters, and unknown-type behavior.
+ * @returns The configured server-only SystemState collection.
+ */
+export declare function systemStatePrivateFirestoreCollection(config: SystemStatePrivateFirestoreCollectionConfig): SystemStatePrivateFirestoreCollection;

package/model/src/lib/system/system.private.module.d.ts

@@ -0,0 +1,70 @@
+import { type ModuleMetadata, type Provider } from '@nestjs/common';
+import { type Maybe } from '@dereekb/util';
+import { type FirestoreContext, type SystemStateStoredDataConverterMap, type SystemStateUnknownTypeBehavior } from '@dereekb/firebase';
+import { SystemStatePrivateFirestoreCollections } from './system.private';
+/**
+ * Configuration for the {@link SystemStatePrivateFirestoreCollections} provider.
+ */
+export declare abstract class SystemStatePrivateModuleConfig {
+    /**
+     * Server-only stored-data converters, keyed by SystemStateTypeIdentifier.
+     *
+     * Secret-bearing converters are built by the app, which owns its own `ConfigService`/env access —
+     * the framework never sees the secrets.
+     */
+    abstract readonly converters: SystemStateStoredDataConverterMap;
+    /**
+     * Behavior when a document's type has no registered converter. Defaults to `error`.
+     */
+    abstract readonly unknownTypeBehavior?: Maybe<SystemStateUnknownTypeBehavior>;
+}
+/**
+ * Creates the {@link SystemStatePrivateFirestoreCollections}.
+ *
+ * This is a bespoke provider rather than a `provideAppFirestoreCollections()` entry because that
+ * helper hard-codes a `(context: FirestoreContext) => T` factory and cannot carry the converters
+ * (and therefore the encryption secrets) this collection needs.
+ *
+ * @param firestoreContext - The Firestore context.
+ * @param config - The module configuration carrying the server-only converters.
+ * @returns The server-only collections.
+ */
+export declare function systemStatePrivateFirestoreCollectionsFactory(firestoreContext: FirestoreContext, config: SystemStatePrivateModuleConfig): SystemStatePrivateFirestoreCollections;
+/**
+ * Configuration for {@link appSystemStatePrivateModuleMetadata}.
+ */
+export interface ProvideAppSystemStatePrivateModuleMetadataConfig extends Pick<ModuleMetadata, 'imports' | 'exports' | 'providers'> {
+    /**
+     * Provider for {@link SystemStatePrivateModuleConfig}.
+     *
+     * The app declares this so it can inject its own `ConfigService`/env service and build each
+     * secret-bearing converter itself.
+     */
+    readonly configProvider: Provider;
+}
+/**
+ * Generates NestJS {@link ModuleMetadata} for an app's server-only SystemState module.
+ *
+ * IMPORTANT: do NOT add {@link SystemStatePrivateFirestoreCollections} to an app's shared
+ * `FirestoreCollections` class. Keeping it on its own provider is what stops the private collection
+ * from reaching client-shared code.
+ *
+ * @param config - The app's config provider plus optional additional module metadata.
+ * @returns Module metadata ready for the `@Module()` decorator.
+ *
+ * @example
+ * ```typescript
+ * @Module(
+ *   appSystemStatePrivateModuleMetadata({
+ *     configProvider: {
+ *       provide: SystemStatePrivateModuleConfig,
+ *       useFactory: myConfigFactory,
+ *       inject: [ConfigService, FirebaseServerEnvService]
+ *     },
+ *     imports: [ConfigModule]
+ *   })
+ * )
+ * export class AppSystemStatePrivateModule {}
+ * ```
+ */
+export declare function appSystemStatePrivateModuleMetadata(config: ProvideAppSystemStatePrivateModuleMetadataConfig): ModuleMetadata;

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

@@ -0,0 +1,8 @@
+export * from './oauth';
+export * from './userexternalconnection.private';
+export * from './userexternalconnection.accessor.service';
+export * from './userexternalconnection.action.server';
+export * from './userexternalconnection.error';
+export * from './userexternalconnection.module';
+export * from './userexternalconnection.reader.service';
+export * from './userexternalconnection.refresh.service';

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

@@ -0,0 +1,7 @@
+export * from './userexternalconnection.oauth.config';
+export * from './userexternalconnection.oauth.controller';
+export * from './userexternalconnection.oauth.error';
+export * from './userexternalconnection.oauth.refresh';
+export * from './userexternalconnection.oauth.registry';
+export * from './userexternalconnection.oauth.service';
+export * from './userexternalconnection.oauth.state';

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

@@ -0,0 +1,110 @@
+import { type UserExternalConnectionProviderType } from '@dereekb/firebase';
+import { type FirebaseServerEnvService } from '@dereekb/firebase-server';
+import { type Maybe, type WebsiteUrl } from '@dereekb/util';
+/**
+ * Controller path a provider's external-connection OAuth endpoints are mounted at.
+ *
+ * Matches the Angular registry's `DEFAULT_EXTERNAL_CONNECTION_AUTHORIZE_PATH_FACTORY`, which builds
+ * `/oauth/<providerType>/authorize`.
+ *
+ * @param providerType - The provider to build a controller path for.
+ * @returns The controller path, without a leading slash.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function userExternalConnectionOAuthControllerPath(providerType: UserExternalConnectionProviderType): string;
+/**
+ * Routes to exclude from an app's global API route prefix so a provider's callback controller stays
+ * mounted at `/oauth/<providerType>/*`.
+ *
+ * Spread the result into the `exclude` list of the app's `globalApiRoutePrefix` config, alongside
+ * `FIREBASE_SERVER_OIDC_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE`. Without it an `/api` prefix moves the
+ * routes to `/api/oauth/<providerType>/*`, which no longer matches the redirect URI registered with
+ * the provider — and providers require a byte-identical match, so this is not something they
+ * tolerate.
+ *
+ * @param providerType - The provider whose routes should be excluded.
+ * @returns The route patterns to exclude.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function userExternalConnectionOAuthRoutesForGlobalRouteExclude(providerType: UserExternalConnectionProviderType): string[];
+export interface UserExternalConnectionOAuthRedirectUriInput {
+    /**
+     * The origin the OAuth endpoints are reachable at, e.g. `https://example.com`.
+     */
+    readonly origin: WebsiteUrl;
+    readonly providerType: UserExternalConnectionProviderType;
+}
+/**
+ * Builds the redirect URI to register with a provider.
+ *
+ * Derived from {@link userExternalConnectionOAuthControllerPath}, the same expression the controller
+ * mounts on, so the registered URI cannot drift from the route that serves it.
+ *
+ * @param input - The origin and the provider.
+ * @returns The redirect URI.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function userExternalConnectionOAuthRedirectUri(input: UserExternalConnectionOAuthRedirectUriInput): WebsiteUrl;
+export interface UserExternalConnectionOAuthApiConfig {
+    /**
+     * The provider this flow connects.
+     */
+    readonly providerType: UserExternalConnectionProviderType;
+    /**
+     * The redirect URI registered on the provider's OAuth client.
+     *
+     * Must match the registered value byte-for-byte, including the port, since it is sent on both the
+     * authorize redirect and the token exchange.
+     */
+    readonly redirectUri: WebsiteUrl;
+    /**
+     * Where the user is sent after a connection succeeds.
+     */
+    readonly successUrl: WebsiteUrl;
+    /**
+     * Where the user is sent after a connection fails. Defaults to the `successUrl`.
+     */
+    readonly failureUrl?: Maybe<WebsiteUrl>;
+}
+/**
+ * Configuration for an {@link AbstractUserExternalConnectionOAuthService}.
+ *
+ * Provided privately by each provider's module, so two registered providers never collide on this
+ * token.
+ */
+export declare abstract class UserExternalConnectionOAuthServiceConfig {
+    readonly userExternalConnectionOAuth: UserExternalConnectionOAuthApiConfig;
+    static assertValidConfig(config: UserExternalConnectionOAuthServiceConfig): void;
+}
+export interface UserExternalConnectionOAuthServiceConfigFactoryConfig {
+    /**
+     * Used to resolve the OAuth origin and the app URL. No part of this configuration is read from the
+     * environment as a value — only the origins the app is already configured with.
+     */
+    readonly envService: FirebaseServerEnvService;
+    readonly providerType: UserExternalConnectionProviderType;
+    /**
+     * Path on the app URL the user is returned to after a successful connect, e.g. `/app/settings`.
+     */
+    readonly successPath: string;
+    /**
+     * Path on the app URL the user is returned to after a failed connect. Defaults to `successPath`.
+     */
+    readonly failurePath?: Maybe<string>;
+}
+/**
+ * Builds a provider's OAuth configuration from the app's configured origins plus code-declared
+ * return paths.
+ *
+ * The redirect URI is derived rather than configured: it is the app's OAuth origin joined to the
+ * same controller path the callback mounts on. Registering a provider therefore requires no
+ * deployment configuration of its own.
+ *
+ * @param config - The env service, the provider, and the return paths.
+ * @returns The validated service configuration.
+ * @throws {Error} When no app URL is configured, or the derived URIs are inconsistent.
+ */
+export declare function userExternalConnectionOAuthServiceConfigFactory(config: UserExternalConnectionOAuthServiceConfigFactoryConfig): UserExternalConnectionOAuthServiceConfig;

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;