@dereekb/firebase-server 13.12.2 → 13.12.4

package/oidc/index.esm.js

@@ -3,7 +3,7 @@ import { errors } from 'oidc-provider';
 import { SECONDS_IN_MINUTE, SECONDS_IN_DAY, cachedGetter, unixDateTimeSecondsNumberToDate, unixDateTimeSecondsNumberForNow, selectiveFieldEncryptor, filterUndefinedValues, websiteUrlFromPaths, firstValue, hasHttpPrefix } from '@dereekb/util';
 import { generateKeyPairSync, randomBytes } from 'node:crypto';
 import { resolveEncryptionKey, encryptValue, decryptValue, createAesStringEncryptionProvider, isValidAES256GCMEncryptionSecret } from '@dereekb/nestjs';
-import { where, iterateFirestoreDocumentSnapshotPairs, firestoreModelIdentity, snapshotConverterFunctions, optionalFirestoreDate, firestoreDate, firestoreEnum, firestorePassThroughField, AbstractFirestoreDocument, createOidcClientParamsType, deleteOidcClientParamsType, deleteOidcTokenParamsType, rotateOidcClientSecretParamsType, updateOidcClientParamsType, firestoreModelKey, oidcEntryIdentity, OIDC_ENTRY_CLIENT_TYPE, oidcEntriesByUserCodeQuery, oidcEntriesByUidQuery, oidcEntriesByGrantIdQuery, oidcEntryFirestoreCollection, callModelOidcScopeForCallType, CALL_MODEL_MISSING_OIDC_SCOPE_ERROR_CODE } from '@dereekb/firebase';
+import { where, iterateFirestoreDocumentSnapshotPairs, firestoreModelIdentity, snapshotConverterFunctions, optionalFirestoreDate, firestoreDate, firestoreEnum, firestorePassThroughField, AbstractFirestoreDocument, createOidcClientParamsType, deleteOidcClientParamsType, deleteOidcTokenParamsType, rotateOidcClientSecretParamsType, updateOidcClientParamsType, firestoreModelKey, oidcEntryIdentity, PUBLIC_PKCE_TOKEN_ENDPOINT_AUTH_METHOD, OIDC_ENTRY_CLIENT_TYPE, oidcEntriesByUserCodeQuery, oidcEntriesByUidQuery, oidcEntriesByGrantIdQuery, oidcEntryFirestoreCollection, callModelOidcScopeForCallType, CALL_MODEL_MISSING_OIDC_SCOPE_ERROR_CODE } from '@dereekb/firebase';
 import { firestoreEncryptedField, firebaseServerActionsContext, FirebaseServerEnvService, FIREBASE_FIRESTORE_CONTEXT_TOKEN, FirebaseServerFirestoreContextModule, forbiddenError } from '@dereekb/firebase-server';
 import { nanoid } from 'nanoid';
 import { safeToJsDate } from '@dereekb/date';
@@ -78,6 +78,31 @@ function _define_property$f(obj, key, value) {
     }
     return obj;
 }
+/**
+ * Default {@link OidcRenderErrorFunction} that emits a JSON body with `error` and
+ * `error_description` fields, with `Content-Type: application/json`.
+ *
+ * Wired by {@link oidcModuleMetadata} when {@link OidcModuleConfig.renderError} is
+ * not provided. API-focused OIDC providers (the common case in dbx-components apps)
+ * want JSON errors rather than the HTML page oidc-provider renders by default.
+ */ var OIDC_JSON_RENDER_ERROR_FUNCTION = function OIDC_JSON_RENDER_ERROR_FUNCTION(ctx, out) {
+    ctx.type = 'application/json';
+    ctx.body = JSON.stringify({
+        error: out.error,
+        error_description: out.error_description
+    });
+};
+/**
+ * Returns the space-delimited list of every scope declared on `providerConfig.claims`.
+ *
+ * Suitable as the `scope` value on an {@link OidcResourceServerInfo} when the
+ * resource server should accept any scope the provider issues.
+ *
+ * @param providerConfig - The OIDC provider configuration whose scopes to enumerate.
+ * @returns Space-delimited string of all scope names from `providerConfig.claims`.
+ */ function allOidcScopesStringForProviderConfig(providerConfig) {
+    return Object.keys(providerConfig.claims).join(' ');
+}
 /**
  * Default global ceiling for a client-requested login duration, in seconds. 90 days.
  */ var DEFAULT_MAX_REQUESTED_LOGIN_DURATION_SECONDS = 90 * SECONDS_IN_DAY;
@@ -156,8 +181,10 @@ function _define_property$f(obj, key, value) {
         /**
      * Custom error rendering function for the oidc-provider.
      *
-     * When not provided, defaults to a JSON error response with `error` and `error_description` fields.
-     * Set this to customize how OIDC errors are presented (e.g. redirect to an error page).
+     * When not provided, {@link OIDC_JSON_RENDER_ERROR_FUNCTION} is wired by
+     * {@link oidcModuleMetadata} so OIDC errors are returned as a JSON body with
+     * `error` and `error_description` fields. Set this to customize how OIDC
+     * errors are presented (e.g. redirect to an error page).
      *
      * The function signature matches oidc-provider's `renderError` configuration option.
      */ _define_property$f(this, "renderError", void 0);
@@ -203,6 +230,22 @@ function _define_property$f(obj, key, value) {
      * ```
      */ _define_property$f(this, "resourceServers", void 0);
         /**
+     * When `true`, {@link oidcModuleMetadata} automatically derives a resource-server
+     * entry from `envService.appMcpUrl` and the registered {@link OidcAccountService}'s
+     * provider config, then merges it into {@link resourceServers}. Any explicit entry
+     * supplied via {@link resourceServers} wins on key collisions.
+     *
+     * Required for OAuth-aware MCP clients (Claude, mcp-inspector) — they pass the
+     * MCP URL as the `resource` parameter on `/authorize` and `/token`, and oidc-provider
+     * rejects every such request with `invalid_target` unless that URL is registered.
+     *
+     * No effect when `envService.appMcpUrl` is unset.
+     *
+     * Defaults to `false`.
+     *
+     * @see buildFirebaseServerMcpResourceServer
+     */ _define_property$f(this, "configureMcpResourceServer", void 0);
+        /**
      * Absolute URL of the OAuth 2.0 Protected Resource Metadata document
      * (RFC 9728) for the resources guarded by {@link protectedPaths}.
      *
@@ -2201,14 +2244,19 @@ function _ts_generator$7(thisArg, body) {
             value: /**
      * Creates a new OIDC client through the oidc-provider.
      *
-     * Generates `client_id` and `client_secret` using the same defaults as oidc-provider's
-     * registration flow, validates via `Client.validate`, and persists through the adapter.
+     * Generates `client_id` (and, when the auth method requires one, a `client_secret`) using the
+     * same defaults as oidc-provider's registration flow, validates via `Client.validate`, and
+     * persists through the adapter.
+     *
+     * A secret is only generated when `ProviderClient.needsSecret()` returns `true`. The secret-less
+     * methods `private_key_jwt` and `'none'` (public PKCE client) therefore persist no secret and the
+     * returned `client_secret` is `undefined`.
      *
      * @param params - Client registration parameters.
      * @param validatedMetadata - Optional pre-validated metadata to merge into the client properties.
      *   Use this for server-side fields (e.g., inline `jwks`) that have already been validated
      *   and should not be exposed through the API params.
-     * @returns The generated client ID and secret (plaintext, returned only once).
+     * @returns The generated client ID and, for secret-based methods, the secret (plaintext, returned only once).
      */ function createClient(params, validatedMetadata) {
                 return _async_to_generator$7(function() {
                     var provider, ProviderClient, clientId, firestoreOwnerKey, properties, clientSecret, client, payload;
@@ -2370,9 +2418,12 @@ function _ts_generator$7(thisArg, body) {
      * Generates a new `client_secret`, re-validates via `Client.validate()`, and persists.
      * The new secret is returned in plaintext — this is the only time it is available.
      *
+     * Rejects public PKCE clients (`token_endpoint_auth_method === 'none'`): they have no secret,
+     * so there is nothing to rotate.
+     *
      * @param clientId - The client's document/adapter entry ID.
      * @returns The client ID and new secret (plaintext, returned only once).
-     * @throws {Error} When the client is not found.
+     * @throws {Error} When the client is not found, or is a public PKCE (`none`) client.
      */ function rotateClientSecret(clientId) {
                 return _async_to_generator$7(function() {
                     var provider, ProviderClient, existing, newSecret, updatedMetadata, client;
@@ -2395,6 +2446,9 @@ function _ts_generator$7(thisArg, body) {
                                 if (!existing) {
                                     throw new Error('Client not found.');
                                 }
+                                if (existing.token_endpoint_auth_method === PUBLIC_PKCE_TOKEN_ENDPOINT_AUTH_METHOD) {
+                                    throw new Error('Cannot rotate a client secret for a public PKCE client (token_endpoint_auth_method "none"). Public clients have no secret.');
+                                }
                                 newSecret = randomBytes(64).toString('base64url');
                                 updatedMetadata = _object_spread_props$2(_object_spread$5({}, existing), {
                                     client_secret: newSecret,
@@ -6573,6 +6627,40 @@ function _unsupported_iterable_to_array(o, minLen) {
     var trimmedPath = parsed.pathname.replace(/\/[^/]*\/?$/, '');
     return "".concat(parsed.origin).concat(trimmedPath, "/.well-known/oauth-protected-resource");
 }
+/**
+ * Builds a single-entry {@link OidcResourceServerInfo} map for the MCP endpoint
+ * declared on `envService.appMcpUrl`, with `scope` set to every scope declared
+ * on `providerConfig.claims` (so any scope the provider issues is valid on the
+ * resource server) and `audience` set to the MCP URL.
+ *
+ * Returns `undefined` when no `appMcpUrl` is configured.
+ *
+ * Used internally by {@link oidcModuleMetadata} when {@link OidcModuleConfig.configureMcpResourceServer}
+ * is enabled, and exported for apps that need to combine the MCP resource server
+ * with additional app-specific entries:
+ *
+ * @example
+ * ```ts
+ * resourceServers: {
+ *   ...(buildFirebaseServerMcpResourceServer({ envService, providerConfig: APP_PROVIDER_CONFIG }) ?? {}),
+ *   'https://api.example.com/extras': {
+ *     scope: 'openid profile',
+ *     audience: 'https://api.example.com/extras'
+ *   }
+ * }
+ * ```
+ */ function buildFirebaseServerMcpResourceServer(input) {
+    var envService = input.envService, providerConfig = input.providerConfig;
+    var mcpUrl = envService.appMcpUrl;
+    var result;
+    if (mcpUrl) {
+        result = _define_property({}, mcpUrl, {
+            scope: allOidcScopesStringForProviderConfig(providerConfig),
+            audience: mcpUrl
+        });
+    }
+    return result;
+}
 /**
  * Factory that creates {@link OidcServerFirestoreCollections} using the provided Firestore context
  * and JWKS encryption config from {@link OidcModuleConfig}.
@@ -6629,9 +6717,10 @@ function _unsupported_iterable_to_array(o, minLen) {
                 provide: OidcModuleConfig,
                 inject: [
                     ConfigService,
-                    FirebaseServerEnvService
+                    FirebaseServerEnvService,
+                    OidcAccountService
                 ],
-                useFactory: function useFactory(configService, envService) {
+                useFactory: function useFactory(configService, envService, oidcAccountService) {
                     var moduleConfig = oidcModuleConfigFactory(configService, envService);
                     var dynamicOverrides = configFactory ? configFactory(envService, configService) : undefined;
                     var merged = config || dynamicOverrides ? _object_spread({}, config, dynamicOverrides) : undefined;
@@ -6642,6 +6731,22 @@ function _unsupported_iterable_to_array(o, minLen) {
                             result.trustProxy = true;
                         }
                     }
+                    // Apply the default JSON error renderer when no custom renderError is configured.
+                    if (!result.renderError) {
+                        result.renderError = OIDC_JSON_RENDER_ERROR_FUNCTION;
+                    }
+                    // Auto-derive the MCP resource-server entry from envService.appMcpUrl and the
+                    // registered OidcAccountService's providerConfig. Any explicit resourceServers
+                    // entry from the consumer wins on key collisions.
+                    if (result.configureMcpResourceServer) {
+                        var mcpResourceServer = buildFirebaseServerMcpResourceServer({
+                            envService: envService,
+                            providerConfig: oidcAccountService.providerConfig
+                        });
+                        if (mcpResourceServer) {
+                            result.resourceServers = _object_spread({}, mcpResourceServer, result.resourceServers);
+                        }
+                    }
                     return result;
                 }
             },
@@ -6728,4 +6833,4 @@ function _unsupported_iterable_to_array(o, minLen) {
     return fn;
 }
 
-export { DEFAULT_APP_OAUTH_CONSENT_PATH_PART, DEFAULT_APP_OAUTH_INTERACTION_PATH, DEFAULT_APP_OAUTH_LOGIN_PATH_PART, DEFAULT_MAX_REQUESTED_LOGIN_DURATION_SECONDS, DEFAULT_MIN_REQUESTED_LOGIN_DURATION_SECONDS, DEFAULT_OIDC_CODE_CHALLENGE_METHODS, DEFAULT_OIDC_ID_TOKEN_SIGNING_ALG_VALUES, DEFAULT_OIDC_ISSUER_PATH, DEFAULT_OIDC_ROUTES, DEFAULT_OIDC_SUBJECT_TYPES, DEFAULT_OIDC_TOKEN_ENDPOINT_AUTH_METHODS, DEFAULT_OIDC_TOKEN_LIFETIMES, DEFAULT_ROTATED_KEY_MAX_AGE, FIREBASE_SERVER_OIDC_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE, GRANTABLE_MODEL_NAMES, JwksFirestoreCollections, JwksKeyDocument, JwksService, JwksServiceConfig, JwksServiceStorageConfig, OIDC_ENCRYPTED_PAYLOAD_FIELDS, OIDC_JWKS_ENCRYPTION_SECRET_ENV_KEY, OidcAccountService, OidcAccountServiceDelegate, OidcAccountServiceUserContext, OidcAuth, OidcAuthBearerTokenMiddleware, OidcAuthMiddlewareConfig, OidcClientService, OidcEncryptionService, OidcInteractionController, OidcInteractionService, OidcModelServerActions, OidcModuleConfig, OidcProviderConfigService, OidcProviderController, OidcServerFirestoreCollections, OidcService, OidcWellKnownController, activeJwksKeysQuery, appOidcModelModuleMetadata, applyOidcAuthMiddleware, applyOidcCorsMiddleware, buildBearerChallenge, createAdapterFactory, createOidcClientFactory, deleteOidcClientFactory, deleteOidcTokenFactory, deriveResourceMetadataUrlFromEnv, getOidcScopesFromRequest, jwksKeyCollectionReference, jwksKeyConverter, jwksKeyFirestoreCollection, jwksKeyIdentity, jwksKeysWithStatusQuery, nonRetiredJwksKeysQuery, oidcCallModelScopePreAssert, oidcFirestoreCollectionsFactory, oidcModelServerActions, oidcModelServerActionsFactory, oidcModuleConfigFactory, oidcModuleMetadata, resolveEffectiveSubset, rotateOidcClientSecretFactory, rotatedJwksKeysQuery, updateOidcClientFactory };
+export { DEFAULT_APP_OAUTH_CONSENT_PATH_PART, DEFAULT_APP_OAUTH_INTERACTION_PATH, DEFAULT_APP_OAUTH_LOGIN_PATH_PART, DEFAULT_MAX_REQUESTED_LOGIN_DURATION_SECONDS, DEFAULT_MIN_REQUESTED_LOGIN_DURATION_SECONDS, DEFAULT_OIDC_CODE_CHALLENGE_METHODS, DEFAULT_OIDC_ID_TOKEN_SIGNING_ALG_VALUES, DEFAULT_OIDC_ISSUER_PATH, DEFAULT_OIDC_ROUTES, DEFAULT_OIDC_SUBJECT_TYPES, DEFAULT_OIDC_TOKEN_ENDPOINT_AUTH_METHODS, DEFAULT_OIDC_TOKEN_LIFETIMES, DEFAULT_ROTATED_KEY_MAX_AGE, FIREBASE_SERVER_OIDC_ROUTES_FOR_GLOBAL_ROUTE_EXCLUDE, GRANTABLE_MODEL_NAMES, JwksFirestoreCollections, JwksKeyDocument, JwksService, JwksServiceConfig, JwksServiceStorageConfig, OIDC_ENCRYPTED_PAYLOAD_FIELDS, OIDC_JSON_RENDER_ERROR_FUNCTION, OIDC_JWKS_ENCRYPTION_SECRET_ENV_KEY, OidcAccountService, OidcAccountServiceDelegate, OidcAccountServiceUserContext, OidcAuth, OidcAuthBearerTokenMiddleware, OidcAuthMiddlewareConfig, OidcClientService, OidcEncryptionService, OidcInteractionController, OidcInteractionService, OidcModelServerActions, OidcModuleConfig, OidcProviderConfigService, OidcProviderController, OidcServerFirestoreCollections, OidcService, OidcWellKnownController, activeJwksKeysQuery, allOidcScopesStringForProviderConfig, appOidcModelModuleMetadata, applyOidcAuthMiddleware, applyOidcCorsMiddleware, buildBearerChallenge, buildFirebaseServerMcpResourceServer, createAdapterFactory, createOidcClientFactory, deleteOidcClientFactory, deleteOidcTokenFactory, deriveResourceMetadataUrlFromEnv, getOidcScopesFromRequest, jwksKeyCollectionReference, jwksKeyConverter, jwksKeyFirestoreCollection, jwksKeyIdentity, jwksKeysWithStatusQuery, nonRetiredJwksKeysQuery, oidcCallModelScopePreAssert, oidcFirestoreCollectionsFactory, oidcModelServerActions, oidcModelServerActionsFactory, oidcModuleConfigFactory, oidcModuleMetadata, resolveEffectiveSubset, rotateOidcClientSecretFactory, rotatedJwksKeysQuery, updateOidcClientFactory };

package/oidc/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/firebase-server/oidc",
-  "version": "13.12.2",
+  "version": "13.12.4",
   "peerDependencies": {
-    "@dereekb/analytics": "13.12.2",
-    "@dereekb/date": "13.12.2",
-    "@dereekb/firebase": "13.12.2",
-    "@dereekb/firebase-server": "13.12.2",
-    "@dereekb/model": "13.12.2",
-    "@dereekb/nestjs": "13.12.2",
-    "@dereekb/rxjs": "13.12.2",
-    "@dereekb/util": "13.12.2",
-    "@dereekb/zoho": "13.12.2",
+    "@dereekb/analytics": "13.12.4",
+    "@dereekb/date": "13.12.4",
+    "@dereekb/firebase": "13.12.4",
+    "@dereekb/firebase-server": "13.12.4",
+    "@dereekb/model": "13.12.4",
+    "@dereekb/nestjs": "13.12.4",
+    "@dereekb/rxjs": "13.12.4",
+    "@dereekb/util": "13.12.4",
+    "@dereekb/zoho": "13.12.4",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "express": "^5.2.1",

package/oidc/src/lib/oidc.config.d.ts

@@ -9,6 +9,15 @@ import { type JwksKeyConverterConfig } from './model';
  * Matches the `renderError` option from the oidc-provider `Configuration` type.
  */
 export type OidcRenderErrorFunction = Configuration['renderError'];
+/**
+ * Default {@link OidcRenderErrorFunction} that emits a JSON body with `error` and
+ * `error_description` fields, with `Content-Type: application/json`.
+ *
+ * Wired by {@link oidcModuleMetadata} when {@link OidcModuleConfig.renderError} is
+ * not provided. API-focused OIDC providers (the common case in dbx-components apps)
+ * want JSON errors rather than the HTML page oidc-provider renders by default.
+ */
+export declare const OIDC_JSON_RENDER_ERROR_FUNCTION: OidcRenderErrorFunction;
 /**
  * Per-resource configuration returned by `features.resourceIndicators.getResourceServerInfo`
  * to oidc-provider when a client requests an access token bound to a specific resource
@@ -78,6 +87,16 @@ export interface OidcProviderConfig<S extends OidcScope = OidcScope> {
      */
     readonly grantTypes: string[];
 }
+/**
+ * Returns the space-delimited list of every scope declared on `providerConfig.claims`.
+ *
+ * Suitable as the `scope` value on an {@link OidcResourceServerInfo} when the
+ * resource server should accept any scope the provider issues.
+ *
+ * @param providerConfig - The OIDC provider configuration whose scopes to enumerate.
+ * @returns Space-delimited string of all scope names from `providerConfig.claims`.
+ */
+export declare function allOidcScopesStringForProviderConfig<S extends OidcScope = OidcScope>(providerConfig: OidcProviderConfig<S>): string;
 /**
  * Configures the lifetime (in seconds) for each token type issued by the OIDC provider.
  *
@@ -197,8 +216,10 @@ export declare abstract class OidcModuleConfig {
     /**
      * Custom error rendering function for the oidc-provider.
      *
-     * When not provided, defaults to a JSON error response with `error` and `error_description` fields.
-     * Set this to customize how OIDC errors are presented (e.g. redirect to an error page).
+     * When not provided, {@link OIDC_JSON_RENDER_ERROR_FUNCTION} is wired by
+     * {@link oidcModuleMetadata} so OIDC errors are returned as a JSON body with
+     * `error` and `error_description` fields. Set this to customize how OIDC
+     * errors are presented (e.g. redirect to an error page).
      *
      * The function signature matches oidc-provider's `renderError` configuration option.
      */
@@ -247,6 +268,23 @@ export declare abstract class OidcModuleConfig {
      * ```
      */
     readonly resourceServers?: Readonly<Record<string, OidcResourceServerInfo>>;
+    /**
+     * When `true`, {@link oidcModuleMetadata} automatically derives a resource-server
+     * entry from `envService.appMcpUrl` and the registered {@link OidcAccountService}'s
+     * provider config, then merges it into {@link resourceServers}. Any explicit entry
+     * supplied via {@link resourceServers} wins on key collisions.
+     *
+     * Required for OAuth-aware MCP clients (Claude, mcp-inspector) — they pass the
+     * MCP URL as the `resource` parameter on `/authorize` and `/token`, and oidc-provider
+     * rejects every such request with `invalid_target` unless that URL is registered.
+     *
+     * No effect when `envService.appMcpUrl` is unset.
+     *
+     * Defaults to `false`.
+     *
+     * @see buildFirebaseServerMcpResourceServer
+     */
+    readonly configureMcpResourceServer?: boolean;
     /**
      * Absolute URL of the OAuth 2.0 Protected Resource Metadata document
      * (RFC 9728) for the resources guarded by {@link protectedPaths}.

package/oidc/src/lib/oidc.module.d.ts

@@ -1,6 +1,6 @@
 import { type ModuleMetadata } from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
-import { OidcModuleConfig } from './oidc.config';
+import { OidcModuleConfig, type OidcProviderConfig, type OidcResourceServerInfo } from './oidc.config';
 import { type FirestoreContext } from '@dereekb/firebase';
 import { FirebaseServerEnvService } from '@dereekb/firebase-server';
 import { OidcServerFirestoreCollections } from './model/model';
@@ -88,6 +88,43 @@ export declare function oidcModuleConfigFactory(configService: ConfigService, en
  * @returns The discovery URL, or `undefined` if `appMcpUrl` is not set.
  */
 export declare function deriveResourceMetadataUrlFromEnv(envService: FirebaseServerEnvService): string | undefined;
+/**
+ * Input for {@link buildFirebaseServerMcpResourceServer}.
+ */
+export interface BuildFirebaseServerMcpResourceServerInput {
+    /**
+     * The Firebase server environment service. The MCP URL is read from `envService.appMcpUrl`.
+     */
+    readonly envService: FirebaseServerEnvService;
+    /**
+     * The OIDC provider config whose scopes back the resource server's `scope` value.
+     */
+    readonly providerConfig: OidcProviderConfig;
+}
+/**
+ * Builds a single-entry {@link OidcResourceServerInfo} map for the MCP endpoint
+ * declared on `envService.appMcpUrl`, with `scope` set to every scope declared
+ * on `providerConfig.claims` (so any scope the provider issues is valid on the
+ * resource server) and `audience` set to the MCP URL.
+ *
+ * Returns `undefined` when no `appMcpUrl` is configured.
+ *
+ * Used internally by {@link oidcModuleMetadata} when {@link OidcModuleConfig.configureMcpResourceServer}
+ * is enabled, and exported for apps that need to combine the MCP resource server
+ * with additional app-specific entries:
+ *
+ * @example
+ * ```ts
+ * resourceServers: {
+ *   ...(buildFirebaseServerMcpResourceServer({ envService, providerConfig: APP_PROVIDER_CONFIG }) ?? {}),
+ *   'https://api.example.com/extras': {
+ *     scope: 'openid profile',
+ *     audience: 'https://api.example.com/extras'
+ *   }
+ * }
+ * ```
+ */
+export declare function buildFirebaseServerMcpResourceServer(input: BuildFirebaseServerMcpResourceServerInput): Record<string, OidcResourceServerInfo> | undefined;
 /**
  * Factory that creates {@link OidcServerFirestoreCollections} using the provided Firestore context
  * and JWKS encryption config from {@link OidcModuleConfig}.
@@ -101,7 +138,7 @@ export declare function oidcFirestoreCollectionsFactory(firestoreContext: Firest
  * Subset of {@link OidcModuleConfig} that consumers may override via
  * `oidcModuleMetadata`'s `config` or `configFactory`.
  */
-export type OidcModuleMetadataOverrides = Partial<Pick<OidcModuleConfig, 'issuer' | 'suppressBodyParserWarning' | 'renderError' | 'protectedPaths' | 'appOAuthInteractionPath' | 'appOAuthLoginUrlPart' | 'appOAuthConsentUrlPart' | 'tokenEndpointAuthMethods' | 'registrationEnabled' | 'trustProxy' | 'trustProxyInNonProduction' | 'tokenLifetimes' | 'maxRequestedLoginDuration' | 'minRequestedLoginDuration' | 'defaultRequestedLoginDuration' | 'resourceServers' | 'resourceMetadataUrl'>>;
+export type OidcModuleMetadataOverrides = Partial<Pick<OidcModuleConfig, 'issuer' | 'suppressBodyParserWarning' | 'renderError' | 'protectedPaths' | 'appOAuthInteractionPath' | 'appOAuthLoginUrlPart' | 'appOAuthConsentUrlPart' | 'tokenEndpointAuthMethods' | 'registrationEnabled' | 'trustProxy' | 'trustProxyInNonProduction' | 'tokenLifetimes' | 'maxRequestedLoginDuration' | 'minRequestedLoginDuration' | 'defaultRequestedLoginDuration' | 'resourceServers' | 'resourceMetadataUrl' | 'configureMcpResourceServer'>>;
 export interface ProvideAppOidcModuleMetadataConfig extends Pick<ModuleMetadata, 'imports' | 'exports' | 'providers'> {
     /**
      * Module that exports the required dependencies for this module.

package/oidc/src/lib/service/oidc.client.service.d.ts

@@ -13,14 +13,19 @@ export declare class OidcClientService {
     /**
      * Creates a new OIDC client through the oidc-provider.
      *
-     * Generates `client_id` and `client_secret` using the same defaults as oidc-provider's
-     * registration flow, validates via `Client.validate`, and persists through the adapter.
+     * Generates `client_id` (and, when the auth method requires one, a `client_secret`) using the
+     * same defaults as oidc-provider's registration flow, validates via `Client.validate`, and
+     * persists through the adapter.
+     *
+     * A secret is only generated when `ProviderClient.needsSecret()` returns `true`. The secret-less
+     * methods `private_key_jwt` and `'none'` (public PKCE client) therefore persist no secret and the
+     * returned `client_secret` is `undefined`.
      *
      * @param params - Client registration parameters.
      * @param validatedMetadata - Optional pre-validated metadata to merge into the client properties.
      *   Use this for server-side fields (e.g., inline `jwks`) that have already been validated
      *   and should not be exposed through the API params.
-     * @returns The generated client ID and secret (plaintext, returned only once).
+     * @returns The generated client ID and, for secret-based methods, the secret (plaintext, returned only once).
      */
     createClient(params: CreateOidcClientParams, validatedMetadata?: Partial<Pick<ClientMetadata, 'jwks'>>): Promise<CreateOidcClientResult>;
     /**
@@ -42,9 +47,12 @@ export declare class OidcClientService {
      * Generates a new `client_secret`, re-validates via `Client.validate()`, and persists.
      * The new secret is returned in plaintext — this is the only time it is available.
      *
+     * Rejects public PKCE clients (`token_endpoint_auth_method === 'none'`): they have no secret,
+     * so there is nothing to rotate.
+     *
      * @param clientId - The client's document/adapter entry ID.
      * @returns The client ID and new secret (plaintext, returned only once).
-     * @throws {Error} When the client is not found.
+     * @throws {Error} When the client is not found, or is a public PKCE (`none`) client.
      */
     rotateClientSecret(clientId: OidcEntryClientId): Promise<RotateOidcClientSecretResult>;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase-server",
-  "version": "13.12.2",
+  "version": "13.12.4",
   "sideEffects": false,
   "exports": {
     "./test": {
@@ -56,17 +56,19 @@
   "main": "./index.cjs.js",
   "types": "./src/index.d.ts",
   "peerDependencies": {
-    "@dereekb/analytics": "13.12.2",
-    "@dereekb/date": "13.12.2",
-    "@dereekb/dbx-core": "13.12.2",
-    "@dereekb/firebase": "13.12.2",
-    "@dereekb/model": "13.12.2",
-    "@dereekb/nestjs": "13.12.2",
-    "@dereekb/rxjs": "13.12.2",
-    "@dereekb/util": "13.12.2",
-    "@dereekb/zoho": "13.12.2",
+    "@cantoo/pdf-lib": "^2.6.5",
+    "@dereekb/analytics": "13.12.4",
+    "@dereekb/date": "13.12.4",
+    "@dereekb/dbx-core": "13.12.4",
+    "@dereekb/firebase": "13.12.4",
+    "@dereekb/model": "13.12.4",
+    "@dereekb/nestjs": "13.12.4",
+    "@dereekb/rxjs": "13.12.4",
+    "@dereekb/util": "13.12.4",
+    "@dereekb/zoho": "13.12.4",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.19.0",
+    "@modelcontextprotocol/sdk": "1.29.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "@nestjs/core": "^11.1.19",
@@ -84,6 +86,7 @@
     "nanoid": "^5.1.9",
     "oidc-provider": "^9.8.2",
     "rxjs": "^7.8.2",
+    "sharp": "0.34.5",
     "supertest": "^7.2.2",
     "ts-essentials": "^10.2.0"
   },

package/src/lib/auth/auth.service.d.ts

@@ -669,23 +669,82 @@ export interface FirebaseServerAuthPasswordResetSendContentConfig<D = unknown> {
      */
     readonly data?: Maybe<D>;
 }
+/**
+ * Opaque composite token returned to the user during a password reset. Encodes both
+ * the raw reset code and the target uid in a single value so the completion call does
+ * not need a separate uid argument (which a logged-out forgot-password flow cannot provide).
+ *
+ * The on-the-wire shape is `<code>-<uid>`. The raw code is the numeric string produced by
+ * {@link DEFAULT_FIREBASE_PASSWORD_NUMBER_GENERATOR}, so the first `-` cleanly splits the token.
+ * Do not split or mutate the token outside of {@link decodeFirebaseServerUserPasswordResetOobCode}.
+ */
+export type FirebaseServerUserPasswordResetOobCode = string & {
+    __firebaseServerUserPasswordResetOobCode: true;
+};
+/**
+ * Builds the composite oob code from a raw reset code (the numeric value stored in
+ * {@link FirebaseServerAuthResetUserPasswordClaims.resetPassword}) and the target user's uid.
+ *
+ * @param uid - The target user's UID.
+ * @param code - The raw reset code from the user's claims.
+ *
+ * @example
+ * ```typescript
+ * const oobCode = encodeFirebaseServerUserPasswordResetOobCode(user.uid, claims.resetPassword);
+ * // e.g. '482910-abcDEF123'
+ * ```
+ */
+export declare function encodeFirebaseServerUserPasswordResetOobCode(uid: FirebaseAuthUserId, code: string): FirebaseServerUserPasswordResetOobCode;
+/**
+ * Decodes a composite oob code back into its `{ uid, code }` parts. Returns `undefined`
+ * when the token is malformed (missing separator, non-numeric code, empty uid).
+ *
+ * @param token - The composite oob token, typically received from the password-reset email.
+ *
+ * @example
+ * ```typescript
+ * const decoded = decodeFirebaseServerUserPasswordResetOobCode('482910-abcDEF123');
+ * // decoded = { uid: 'abcDEF123', code: '482910' }
+ * ```
+ */
+export declare function decodeFirebaseServerUserPasswordResetOobCode(token: string): {
+    uid: FirebaseAuthUserId;
+    code: string;
+} | undefined;
 /**
  * Details about a user that is in the password reset phase, including their user context,
- * reset claims data, and the send configuration that was used.
+ * reset claims data, the encoded oob code intended for the user, and the send configuration that was used.
  */
 export interface FirebaseServerAuthPasswordResetDetails<U extends FirebaseServerAuthUserContext = FirebaseServerAuthUserContext, D = unknown> extends FirebaseServerAuthPasswordResetSendContentConfig<D> {
     readonly userContext: U;
     readonly claims: FirebaseAuthResetUserPasswordClaimsData;
+    /**
+     * The encoded oob code intended for the user (carries the raw reset code AND the target uid).
+     * Subclasses that send password-reset emails should embed this value, not `claims.resetPassword`.
+     */
+    readonly oobCode: FirebaseServerUserPasswordResetOobCode;
 }
 /**
- * Input for completing a password reset, containing the temporary reset code
- * and the desired new password.
+ * Result of {@link FirebaseServerUserPasswordResetService.beginPasswordReset}, exposing both the
+ * stored reset claims and the encoded composite oob code intended for the user.
+ */
+export interface FirebaseServerAuthBeginPasswordResetResult {
+    readonly claims: FirebaseServerAuthResetUserPasswordClaims;
+    /**
+     * The encoded oob code that should be delivered to the user (e.g. embedded in the reset email).
+     */
+    readonly oobCode: FirebaseServerUserPasswordResetOobCode;
+}
+/**
+ * Input for completing a password reset, containing the composite oob code from the recovery email
+ * (which encodes both the temporary reset code AND the target uid) and the desired new password.
  */
 export interface FirebaseServerAuthCompletePasswordResetInput {
     /**
-     * The temporary reset code from the reset email, to be verified against claims.
+     * The full oob token from the recovery email — encodes both the raw reset code AND the target uid.
+     * The service decodes this internally to resolve the user and verify the embedded code.
      */
-    readonly resetPassword: string;
+    readonly oobCode: FirebaseServerUserPasswordResetOobCode;
     /**
      * The new password to set after verification succeeds.
      */
@@ -700,9 +759,9 @@ export interface FirebaseServerAuthCompletePasswordResetInput {
  * @example
  * ```typescript
  * const resetSvc = authService.passwordReset();
- * const claims = await resetSvc.beginPasswordReset({ uid: 'some-uid', sendResetContent: true });
- * // Later, after user verifies identity:
- * await resetSvc.completePasswordReset('some-uid', { resetPassword: '123456', newPassword: 'newSecure' });
+ * const { oobCode } = await resetSvc.beginPasswordReset({ uid: 'some-uid', sendResetContent: true });
+ * // Later, after the user clicks the link in their reset email:
+ * await resetSvc.completePasswordReset({ oobCode, newPassword: 'newSecure' });
  * ```
  */
 export interface FirebaseServerUserPasswordResetService<D = unknown, U extends FirebaseServerAuthUserContext = FirebaseServerAuthUserContext> {
@@ -713,13 +772,16 @@ export interface FirebaseServerUserPasswordResetService<D = unknown, U extends F
      * When `sendResetContent` is true, this method delegates to {@link sendResetContent} and
      * may throw the same errors (throttle, send-once, no-config) depending on the configuration.
      *
+     * Returns both the stored reset claims and the encoded composite oob code that should be
+     * delivered to the user (the value the user will later submit to {@link completePasswordReset}).
+     *
      * @param input - Configuration for the reset, including user identification and send options.
      * @throws {Error} Throws if neither uid nor email is provided.
      * @throws {FirebaseServerAuthPasswordResetThrottleError} When send is throttled and `sendResetThrowErrors` is true.
      * @throws {FirebaseServerAuthPasswordResetSendOnceError} When already sent and `sendResetDetailsOnce` + `sendResetThrowErrors` are true.
      * @throws {FirebaseServerAuthPasswordResetNoResetConfigError} When no reset claims exist and `sendResetThrowErrors` is true.
      */
-    beginPasswordReset(input: FirebaseServerAuthInitiatePasswordReset<D>): Promise<FirebaseServerAuthResetUserPasswordClaims>;
+    beginPasswordReset(input: FirebaseServerAuthInitiatePasswordReset<D>): Promise<FirebaseServerAuthBeginPasswordResetResult>;
     /**
      * Sends reset content (e.g., a reset email) to the user.
      *
@@ -750,14 +812,19 @@ export interface FirebaseServerUserPasswordResetService<D = unknown, U extends F
      */
     loadResetDetailsForUserContext(userContext: U, config?: FirebaseServerAuthPasswordResetSendContentConfig<D>): Promise<Maybe<FirebaseServerAuthPasswordResetDetails<U, D>>>;
     /**
-     * Completes the password reset by verifying the temporary reset code against the user's
-     * claims and setting the new password. Clears reset claims on success.
+     * Completes the password reset by decoding the composite oob token, resolving the target user,
+     * verifying the embedded reset code against the user's claims, and setting the new password.
+     * Clears reset claims on success.
      *
-     * @param uid - The target user's UID.
-     * @param input - The reset code and new password.
-     * @throws {FirebaseServerAuthPasswordResetInvalidCodeError} When the reset code is invalid or no reset is active.
+     * The target uid is read from the encoded token — callers do not need to know it separately,
+     * which is what enables the logged-out "forgot password" flow.
+     *
+     * @param input - The encoded oob token and new password.
+     * @throws {FirebaseServerAuthPasswordResetInvalidCodeError} When the token is malformed, the
+     *   embedded uid does not own an active reset, the code is expired, or the code does not match.
+     *   The same opaque error is thrown for every failure mode.
      */
-    completePasswordReset(uid: FirebaseAuthUserId, input: FirebaseServerAuthCompletePasswordResetInput): Promise<admin.auth.UserRecord>;
+    completePasswordReset(input: FirebaseServerAuthCompletePasswordResetInput): Promise<admin.auth.UserRecord>;
 }
 /**
  * Default throttle duration (60 seconds) between reset content re-sends to prevent spam while
@@ -798,7 +865,7 @@ export declare abstract class AbstractFirebaseServerUserPasswordResetService<U e
     protected resetThrottleTime: Milliseconds;
     constructor(authService: FirebaseServerAuthService<U, C>);
     get authService(): FirebaseServerAuthService<U, C>;
-    beginPasswordReset(input: FirebaseServerAuthInitiatePasswordReset<D>): Promise<FirebaseServerAuthResetUserPasswordClaims>;
+    beginPasswordReset(input: FirebaseServerAuthInitiatePasswordReset<D>): Promise<FirebaseServerAuthBeginPasswordResetResult>;
     sendResetContent(uid: FirebaseAuthUserId, config?: FirebaseServerAuthPasswordResetSendContentConfig<D>): Promise<boolean>;
     loadResetDetails(uid: FirebaseAuthUserId, config?: FirebaseServerAuthPasswordResetSendContentConfig<D>): Promise<Maybe<FirebaseServerAuthPasswordResetDetails<U, D>>>;
     loadResetDetailsForUserContext(userContext: U, config?: FirebaseServerAuthPasswordResetSendContentConfig<D>): Promise<Maybe<FirebaseServerAuthPasswordResetDetails<U, D>>>;
@@ -808,7 +875,7 @@ export declare abstract class AbstractFirebaseServerUserPasswordResetService<U e
      * @param details - The user's reset details containing the user context.
      */
     protected updateResetContentSentTime(details: FirebaseServerAuthPasswordResetDetails<U, D>): Promise<void>;
-    completePasswordReset(uid: FirebaseAuthUserId, input: FirebaseServerAuthCompletePasswordResetInput): Promise<admin.auth.UserRecord>;
+    completePasswordReset(input: FirebaseServerAuthCompletePasswordResetInput): Promise<admin.auth.UserRecord>;
     /**
      * Delivers reset content (e.g., reset email, SMS) to the user.
      *

package/src/lib/env/env.service.d.ts

@@ -18,11 +18,11 @@ export declare abstract class FirebaseServerEnvService {
      */
     abstract readonly isTestingEnv: boolean;
     /**
-     * Whether the server is running in production.
+     * Whether the server is running in production mode. (This may be true in both prod or a staging running as production).
      */
     abstract readonly isProduction: boolean;
     /**
-     * Whether the server is running in a staging environment.
+     * Whether the server is running in a staging environment. isProduction is also typically true when this is true.
      */
     abstract readonly isStaging: boolean;
     /**