@dereekb/firebase-server 13.32.0 → 13.34.0

package/discord/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@dereekb/firebase-server/discord",
+  "version": "13.34.0",
+  "peerDependencies": {
+    "@dereekb/analytics": "13.34.0",
+    "@dereekb/date": "13.34.0",
+    "@dereekb/discord": "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",
+    "express": "^5.2.1"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "module": "./index.esm.js",
+      "types": "./index.d.ts",
+      "import": "./index.cjs.mjs",
+      "default": "./index.cjs.js"
+    }
+  },
+  "module": "./index.esm.js",
+  "main": "./index.cjs.js",
+  "types": "./index.d.ts"
+}

package/discord/src/index.d.ts

@@ -0,0 +1 @@
+export * from './lib';

package/discord/src/lib/discord.oauth.connection.config.d.ts

@@ -0,0 +1,69 @@
+import { type DiscordOAuthScope } from '@dereekb/discord';
+import { type FirebaseServerEnvService } from '@dereekb/firebase-server';
+import { UserExternalConnectionOAuthServiceConfig } from '@dereekb/firebase-server/model';
+import { type Maybe } from '@dereekb/util';
+/**
+ * Controller path the Discord external-connection OAuth endpoints are mounted at.
+ *
+ * Derived from the framework's path factory, the same expression the redirect URI and the
+ * global-prefix exclusion are built from, so the three cannot drift apart.
+ */
+export declare const DISCORD_USER_EXTERNAL_CONNECTION_OAUTH_CONTROLLER_PATH: string;
+/**
+ * Routes to exclude from an app's global API route prefix so the Discord callback controller stays
+ * mounted at `/oauth/discord/*`.
+ *
+ * Spread this into the `exclude` list of the app's `globalApiRoutePrefix` config, alongside
+ * `FIREBASE_SERVER_OIDC_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE`.
+ */
+export declare const DISCORD_USER_EXTERNAL_CONNECTION_OAUTH_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE: string[];
+/**
+ * The scopes requested when an app does not declare its own.
+ *
+ * Declared in code, deliberately NOT read from the environment: the set to request follows from what
+ * the integration actually does, so it is a property of the code rather than of a deployment.
+ *
+ * `identify` alone. It is the least-privilege scope that still makes a Discord connection meaningful
+ * — a token granted no scopes can do nothing — and it is what lets the connection be labeled with the
+ * account it belongs to. Excludes `email`, which is a real privilege escalation the label does not
+ * need, and `guilds` / `connections` / `bot`, which nothing here reads.
+ */
+export declare const DEFAULT_DISCORD_OAUTH_SCOPES: readonly DiscordOAuthScope[];
+/**
+ * Configuration for the {@link DiscordUserExternalConnectionOAuthService}.
+ *
+ * Extends the framework config with the one thing that is Discord's own — which scopes to request.
+ *
+ * The client credentials are NOT here: they belong to `DiscordOAuthServiceConfig` in
+ * `@dereekb/discord/nestjs`, and the service reads them through the injected `DiscordOAuthApi`.
+ */
+export declare abstract class DiscordUserExternalConnectionOAuthServiceConfig extends UserExternalConnectionOAuthServiceConfig {
+    readonly scopes: readonly DiscordOAuthScope[];
+}
+export interface DiscordUserExternalConnectionOAuthServiceConfigFactoryConfig {
+    readonly envService: FirebaseServerEnvService;
+    /**
+     * Path on the app URL the user is returned to after connecting, 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>;
+    /**
+     * The scopes to request. Defaults to {@link DEFAULT_DISCORD_OAUTH_SCOPES}.
+     */
+    readonly scopes?: Maybe<readonly DiscordOAuthScope[]>;
+}
+/**
+ * Builds the Discord connect flow's configuration from the app's configured origins.
+ *
+ * Nothing here is read from the environment as a value: the redirect URI is derived from the app's
+ * OAuth origin plus the mounted controller path, and the return URLs from the app URL plus
+ * code-declared paths. The client credentials are read by `discordOAuthServiceConfigFactory` in
+ * `@dereekb/discord/nestjs`, so registering Discord adds no deployment configuration here.
+ *
+ * @param config - The env service, the return paths, and the optional scope override.
+ * @returns The validated service configuration.
+ */
+export declare function discordUserExternalConnectionOAuthServiceConfigFactory(config: DiscordUserExternalConnectionOAuthServiceConfigFactoryConfig): DiscordUserExternalConnectionOAuthServiceConfig;

package/discord/src/lib/discord.oauth.connection.controller.d.ts

@@ -0,0 +1,18 @@
+import { AbstractUserExternalConnectionOAuthController } from '@dereekb/firebase-server/model';
+import { DiscordUserExternalConnectionOAuthService } from './discord.oauth.connection.service';
+/**
+ * Endpoints for the Discord external-connection authorization-code handoff.
+ *
+ * Mounted at `/oauth/discord`, matching the Angular registry's default authorize path of
+ * `/oauth/<providerType>/authorize`. Hosting rewrites do not strip the path, so this prefix is the
+ * public path — but an app with a global API route prefix must ALSO exclude these routes from it via
+ * {@link DISCORD_USER_EXTERNAL_CONNECTION_OAUTH_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE}, or they land under
+ * that prefix instead and no longer match the redirect URI registered with Discord.
+ *
+ * The `authorize` and `callback` routes come from the base class, so this declares only where they
+ * mount and which service serves them.
+ */
+export declare class DiscordUserExternalConnectionOAuthController extends AbstractUserExternalConnectionOAuthController {
+    readonly oauthService: DiscordUserExternalConnectionOAuthService;
+    constructor(oauthService: DiscordUserExternalConnectionOAuthService);
+}

package/discord/src/lib/discord.oauth.connection.module.d.ts

@@ -0,0 +1,39 @@
+import { type ModuleMetadata } from '@nestjs/common';
+import { type DiscordOAuthScope } from '@dereekb/discord';
+import { type Maybe } from '@dereekb/util';
+export interface ProvideAppDiscordUserExternalConnectionOAuthMetadataConfig extends Pick<ModuleMetadata, 'imports' | 'exports' | 'providers'> {
+    /**
+     * This module requires the following dependencies in order to initialize properly:
+     * - DiscordOAuthApi
+     *
+     * This module declaration makes it easier to import a module that exports that dependency.
+     */
+    readonly dependencyModule?: Maybe<Required<ModuleMetadata>['imports']['0']>;
+    /**
+     * Path on the app URL the user is returned to after connecting, 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>;
+    /**
+     * The scopes to request. Defaults to `DEFAULT_DISCORD_OAUTH_SCOPES`.
+     */
+    readonly scopes?: Maybe<readonly DiscordOAuthScope[]>;
+}
+/**
+ * Convenience function used to generate ModuleMetadata for an app's Discord external-connection
+ * OAuth module.
+ *
+ * Opt-in, like the webhook module: importing the Discord OAuth module alone never mounts HTTP routes,
+ * so an app that only runs a Discord bot exposes no connect endpoints.
+ *
+ * The importing module must also supply `UserExternalConnectionServerActions` and
+ * `UserExternalConnectionStateCoder` — both exported by `appUserExternalConnectionModuleMetadata`,
+ * so pass that module in `imports`.
+ *
+ * @param config - The module metadata configuration.
+ * @returns NestJS ModuleMetadata mounting the Discord connect endpoints.
+ */
+export declare function appDiscordUserExternalConnectionOAuthModuleMetadata(config: ProvideAppDiscordUserExternalConnectionOAuthMetadataConfig): ModuleMetadata;

package/discord/src/lib/discord.oauth.connection.service.d.ts

@@ -0,0 +1,43 @@
+import { type DiscordAccessToken, type DiscordOAuthAuthorizeUrlFactory, type DiscordOAuthCurrentUser } from '@dereekb/discord';
+import { DiscordOAuthApi } from '@dereekb/discord/nestjs';
+import { AbstractUserExternalConnectionOAuthService, UserExternalConnectionAccessor, UserExternalConnectionServerActions, UserExternalConnectionStateCoder, type UserExternalConnectionCredentials, type UserExternalConnectionOAuthExchangeInput, type UserExternalConnectionOAuthRefreshCredentialsInput, type UserExternalConnectionOAuthState } from '@dereekb/firebase-server/model';
+import { type Maybe, type WebsiteUrl } from '@dereekb/util';
+import { DiscordUserExternalConnectionOAuthServiceConfig } from './discord.oauth.connection.config';
+export interface DiscordUserExternalConnectionCredentialsInput {
+    readonly accessToken: DiscordAccessToken;
+    /**
+     * The Discord account the token belongs to, when one could be read.
+     *
+     * Optional because the identity call is best-effort: a connection is fully usable unlabeled.
+     */
+    readonly currentUser?: Maybe<DiscordOAuthCurrentUser>;
+}
+/**
+ * Maps an exchanged Discord token, plus the identity it belongs to, to the credentials stored on the
+ * private connection document.
+ *
+ * The `refreshToken` written here is the one the exchange returned. Discord's refresh responses carry
+ * a refresh token of their own, so persisting whatever came back is correct whether or not it rotated.
+ *
+ * @param input - The exchanged token and the resolved Discord user, when one could be read.
+ * @returns The credentials to store.
+ */
+export declare function discordUserExternalConnectionCredentials(input: DiscordUserExternalConnectionCredentialsInput): UserExternalConnectionCredentials;
+/**
+ * Discord's half of the external-connection authorization-code handoff.
+ *
+ * Everything else — resolving who is connecting, surfacing a refusal, persisting the credentials,
+ * choosing the redirect — is the framework's.
+ */
+export declare class DiscordUserExternalConnectionOAuthService extends AbstractUserExternalConnectionOAuthService {
+    readonly config: DiscordUserExternalConnectionOAuthServiceConfig;
+    readonly stateCoder: UserExternalConnectionStateCoder;
+    readonly userExternalConnectionActions: UserExternalConnectionServerActions;
+    readonly userExternalConnectionAccessor: UserExternalConnectionAccessor;
+    readonly oauthApi: DiscordOAuthApi;
+    readonly authorizeUrlFactory: DiscordOAuthAuthorizeUrlFactory;
+    constructor(config: DiscordUserExternalConnectionOAuthServiceConfig, stateCoder: UserExternalConnectionStateCoder, userExternalConnectionActions: UserExternalConnectionServerActions, userExternalConnectionAccessor: UserExternalConnectionAccessor, oauthApi: DiscordOAuthApi);
+    protected authorizeUrlForState(state: UserExternalConnectionOAuthState): WebsiteUrl;
+    protected credentialsForAuthorizationCode(input: UserExternalConnectionOAuthExchangeInput): Promise<UserExternalConnectionCredentials>;
+    refreshCredentials(input: UserExternalConnectionOAuthRefreshCredentialsInput): Promise<UserExternalConnectionCredentials>;
+}

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

@@ -0,0 +1,4 @@
+export * from './discord.oauth.connection.config';
+export * from './discord.oauth.connection.controller';
+export * from './discord.oauth.connection.module';
+export * from './discord.oauth.connection.service';

package/index.cjs.js

@@ -4517,8 +4517,10 @@ var _obj;
  * Creates a Firestore field mapping that encrypts/decrypts a JSON-serializable value
  * using AES-256-GCM. The value is stored in Firestore as a base64-encoded string.
  *
- * The encryption key is resolved from the configured secret source on each read/write,
- * allowing for key rotation via environment variable changes.
+ * IMPORTANT: there is NO key rotation. `resolveEncryptionKey()` reads and validates the secret once,
+ * here at construction, and closes over the resulting key — changing the secret afterwards orphans
+ * every value already written with the old one. Rotation is only survivable for fields that supply
+ * {@link FirestoreEncryptedFieldConfig.onDecodeFailure} and hold regenerable data.
  *
  * @param config - Encryption field configuration.
  * @returns A field mapping configuration for encrypted values.
@@ -4535,12 +4537,22 @@ var _obj;
  *
  * @__NO_SIDE_EFFECTS__
  */ function firestoreEncryptedField(config) {
-    var secret = config.secret, defaultValue = config.default;
+    var secret = config.secret, defaultValue = config.default, onDecodeFailure = config.onDecodeFailure;
     var getKey = nestjs.resolveEncryptionKey(secret);
     return firebase.firestoreField({
         default: defaultValue,
         fromData: function fromData(data) {
-            return nestjs.decryptValue(data, getKey());
+            var result;
+            if (onDecodeFailure == null) {
+                result = nestjs.decryptValue(data, getKey());
+            } else {
+                try {
+                    result = nestjs.decryptValue(data, getKey());
+                } catch (e) {
+                    result = onDecodeFailure(e, data);
+                }
+            }
+            return result;
         },
         toData: function toData(value) {
             return nestjs.encryptValue(value, getKey());
@@ -4567,11 +4579,21 @@ var _obj;
  *
  * @__NO_SIDE_EFFECTS__
  */ function optionalFirestoreEncryptedField(config) {
-    var secret = config.secret;
+    var secret = config.secret, onDecodeFailure = config.onDecodeFailure;
     var getKey = nestjs.resolveEncryptionKey(secret);
     return firebase.optionalFirestoreField({
         transformFromData: function transformFromData(data) {
-            return nestjs.decryptValue(data, getKey());
+            var result;
+            if (onDecodeFailure == null) {
+                result = nestjs.decryptValue(data, getKey());
+            } else {
+                try {
+                    result = nestjs.decryptValue(data, getKey());
+                } catch (e) {
+                    result = onDecodeFailure(e, data);
+                }
+            }
+            return result;
         },
         transformToData: function transformToData(value) {
             return nestjs.encryptValue(value, getKey());
@@ -7728,14 +7750,19 @@ function _ts_generator$9(thisArg, body) {
 }
 /**
  * Derives a fallback read-error message from a resolved error code, distinguishing not-found from
- * permission-denied. Accepts both the server-error form (`NOT_FOUND` / `PERMISSION_DENIED` /
- * `FORBIDDEN`) and the Firebase HttpsError form (`not-found` / `permission-denied`).
+ * permission-denied. Accepts both the server-error form (`NOT_FOUND` / `MODEL_NOT_AVAILABLE` /
+ * `PERMISSION_DENIED` / `FORBIDDEN`) and the Firebase HttpsError form (`not-found` /
+ * `permission-denied`).
+ *
+ * `MODEL_NOT_AVAILABLE` is the code a missing document actually produces on this path — the
+ * per-key existence check throws {@link nestFirebaseDoesNotExistError}, i.e. `modelNotAvailableError()`
+ * — so it must map to not-found rather than falling through to the generic message.
  *
  * @param code - The resolved error code (`serverErrorCode ?? firebaseErrorCode`), if any.
  * @returns `'not found'`, `'permission denied'`, or a generic `'unknown error'` fallback.
  */ function modelAccessReadErrorMessageFromCode(code) {
     var message;
-    if (code === firebase.NOT_FOUND_ERROR_CODE || code === 'not-found') {
+    if (code === firebase.NOT_FOUND_ERROR_CODE || code === firebase.MODEL_NOT_AVAILABLE_ERROR_CODE || code === 'not-found') {
         message = 'not found';
     } else if (code === firebase.PERMISSION_DENIED_ERROR_CODE || code === firebase.FORBIDDEN_ERROR_CODE || code === 'permission-denied') {
         message = 'permission denied';
@@ -9418,6 +9445,12 @@ function _is_native_reflect_construct$1() {
                 return this.env.appMcpUrl;
             }
         },
+        {
+            key: "appOAuthUrl",
+            get: function get() {
+                return this.env.appOAuthUrl;
+            }
+        },
         {
             key: "appWebhookUrl",
             get: function get() {

package/index.esm.js

@@ -4515,8 +4515,10 @@ var _obj;
  * Creates a Firestore field mapping that encrypts/decrypts a JSON-serializable value
  * using AES-256-GCM. The value is stored in Firestore as a base64-encoded string.
  *
- * The encryption key is resolved from the configured secret source on each read/write,
- * allowing for key rotation via environment variable changes.
+ * IMPORTANT: there is NO key rotation. `resolveEncryptionKey()` reads and validates the secret once,
+ * here at construction, and closes over the resulting key — changing the secret afterwards orphans
+ * every value already written with the old one. Rotation is only survivable for fields that supply
+ * {@link FirestoreEncryptedFieldConfig.onDecodeFailure} and hold regenerable data.
  *
  * @param config - Encryption field configuration.
  * @returns A field mapping configuration for encrypted values.
@@ -4533,12 +4535,22 @@ var _obj;
  *
  * @__NO_SIDE_EFFECTS__
  */ function firestoreEncryptedField(config) {
-    var secret = config.secret, defaultValue = config.default;
+    var secret = config.secret, defaultValue = config.default, onDecodeFailure = config.onDecodeFailure;
     var getKey = resolveEncryptionKey(secret);
     return firestoreField({
         default: defaultValue,
         fromData: function fromData(data) {
-            return decryptValue(data, getKey());
+            var result;
+            if (onDecodeFailure == null) {
+                result = decryptValue(data, getKey());
+            } else {
+                try {
+                    result = decryptValue(data, getKey());
+                } catch (e) {
+                    result = onDecodeFailure(e, data);
+                }
+            }
+            return result;
         },
         toData: function toData(value) {
             return encryptValue(value, getKey());
@@ -4565,11 +4577,21 @@ var _obj;
  *
  * @__NO_SIDE_EFFECTS__
  */ function optionalFirestoreEncryptedField(config) {
-    var secret = config.secret;
+    var secret = config.secret, onDecodeFailure = config.onDecodeFailure;
     var getKey = resolveEncryptionKey(secret);
     return optionalFirestoreField({
         transformFromData: function transformFromData(data) {
-            return decryptValue(data, getKey());
+            var result;
+            if (onDecodeFailure == null) {
+                result = decryptValue(data, getKey());
+            } else {
+                try {
+                    result = decryptValue(data, getKey());
+                } catch (e) {
+                    result = onDecodeFailure(e, data);
+                }
+            }
+            return result;
         },
         transformToData: function transformToData(value) {
             return encryptValue(value, getKey());
@@ -7726,14 +7748,19 @@ function _ts_generator$9(thisArg, body) {
 }
 /**
  * Derives a fallback read-error message from a resolved error code, distinguishing not-found from
- * permission-denied. Accepts both the server-error form (`NOT_FOUND` / `PERMISSION_DENIED` /
- * `FORBIDDEN`) and the Firebase HttpsError form (`not-found` / `permission-denied`).
+ * permission-denied. Accepts both the server-error form (`NOT_FOUND` / `MODEL_NOT_AVAILABLE` /
+ * `PERMISSION_DENIED` / `FORBIDDEN`) and the Firebase HttpsError form (`not-found` /
+ * `permission-denied`).
+ *
+ * `MODEL_NOT_AVAILABLE` is the code a missing document actually produces on this path — the
+ * per-key existence check throws {@link nestFirebaseDoesNotExistError}, i.e. `modelNotAvailableError()`
+ * — so it must map to not-found rather than falling through to the generic message.
  *
  * @param code - The resolved error code (`serverErrorCode ?? firebaseErrorCode`), if any.
  * @returns `'not found'`, `'permission denied'`, or a generic `'unknown error'` fallback.
  */ function modelAccessReadErrorMessageFromCode(code) {
     var message;
-    if (code === NOT_FOUND_ERROR_CODE || code === 'not-found') {
+    if (code === NOT_FOUND_ERROR_CODE || code === MODEL_NOT_AVAILABLE_ERROR_CODE || code === 'not-found') {
         message = 'not found';
     } else if (code === PERMISSION_DENIED_ERROR_CODE || code === FORBIDDEN_ERROR_CODE || code === 'permission-denied') {
         message = 'permission denied';
@@ -9416,6 +9443,12 @@ function _is_native_reflect_construct$1() {
                 return this.env.appMcpUrl;
             }
         },
+        {
+            key: "appOAuthUrl",
+            get: function get() {
+                return this.env.appOAuthUrl;
+            }
+        },
         {
             key: "appWebhookUrl",
             get: function get() {

package/mailgun/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@dereekb/firebase-server/mailgun",
-  "version": "13.32.0",
+  "version": "13.34.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.32.0",
-    "@dereekb/firebase": "13.32.0",
-    "@dereekb/firebase-server": "13.32.0",
-    "@dereekb/date": "13.32.0",
-    "@dereekb/nestjs": "13.32.0",
-    "@dereekb/model": "13.32.0",
-    "@dereekb/rxjs": "13.32.0",
-    "@dereekb/util": "13.32.0"
+    "@dereekb/analytics": "13.34.0",
+    "@dereekb/firebase": "13.34.0",
+    "@dereekb/firebase-server": "13.34.0",
+    "@dereekb/date": "13.34.0",
+    "@dereekb/nestjs": "13.34.0",
+    "@dereekb/model": "13.34.0",
+    "@dereekb/rxjs": "13.34.0",
+    "@dereekb/util": "13.34.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/mcp/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@dereekb/firebase-server/mcp",
-  "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/firebase-server/oidc": "13.32.0",
-    "@dereekb/model": "13.32.0",
-    "@dereekb/nestjs": "13.32.0",
-    "@dereekb/rxjs": "13.32.0",
-    "@dereekb/util": "13.32.0",
-    "@dereekb/zoho": "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/firebase-server/oidc": "13.34.0",
+    "@dereekb/model": "13.34.0",
+    "@dereekb/nestjs": "13.34.0",
+    "@dereekb/rxjs": "13.34.0",
+    "@dereekb/util": "13.34.0",
+    "@dereekb/zoho": "13.34.0",
     "@modelcontextprotocol/sdk": "1.29.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/core": "^11.1.19",