@dereekb/firebase-server 13.12.3 → 13.12.5

package/model/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@dereekb/firebase-server/model",
-  "version": "13.12.3",
+  "version": "13.12.5",
   "peerDependencies": {
-    "@dereekb/analytics": "13.12.3",
-    "@dereekb/date": "13.12.3",
-    "@dereekb/firebase": "13.12.3",
-    "@dereekb/firebase-server": "13.12.3",
-    "@dereekb/model": "13.12.3",
-    "@dereekb/nestjs": "13.12.3",
-    "@dereekb/rxjs": "13.12.3",
-    "@dereekb/util": "13.12.3",
+    "@dereekb/analytics": "13.12.5",
+    "@dereekb/date": "13.12.5",
+    "@dereekb/firebase": "13.12.5",
+    "@dereekb/firebase-server": "13.12.5",
+    "@dereekb/model": "13.12.5",
+    "@dereekb/nestjs": "13.12.5",
+    "@dereekb/rxjs": "13.12.5",
+    "@dereekb/util": "13.12.5",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "archiver": "^7.0.1",

package/oidc/index.cjs.js

@@ -80,6 +80,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 * util.SECONDS_IN_DAY;
@@ -158,8 +183,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);
@@ -205,6 +232,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}.
      *
@@ -2203,14 +2246,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;
@@ -2372,9 +2420,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;
@@ -2397,6 +2448,9 @@ function _ts_generator$7(thisArg, body) {
                                 if (!existing) {
                                     throw new Error('Client not found.');
                                 }
+                                if (existing.token_endpoint_auth_method === firebase.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 = node_crypto.randomBytes(64).toString('base64url');
                                 updatedMetadata = _object_spread_props$2(_object_spread$5({}, existing), {
                                     client_secret: newSecret,
@@ -6575,6 +6629,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}.
@@ -6631,9 +6719,10 @@ function _unsupported_iterable_to_array(o, minLen) {
                 provide: OidcModuleConfig,
                 inject: [
                     config.ConfigService,
-                    firebaseServer.FirebaseServerEnvService
+                    firebaseServer.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$1 || dynamicOverrides ? _object_spread({}, config$1, dynamicOverrides) : undefined;
@@ -6644,6 +6733,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;
                 }
             },
@@ -6750,6 +6855,7 @@ exports.JwksKeyDocument = JwksKeyDocument;
 exports.JwksServiceConfig = JwksServiceConfig;
 exports.JwksServiceStorageConfig = JwksServiceStorageConfig;
 exports.OIDC_ENCRYPTED_PAYLOAD_FIELDS = OIDC_ENCRYPTED_PAYLOAD_FIELDS;
+exports.OIDC_JSON_RENDER_ERROR_FUNCTION = OIDC_JSON_RENDER_ERROR_FUNCTION;
 exports.OIDC_JWKS_ENCRYPTION_SECRET_ENV_KEY = OIDC_JWKS_ENCRYPTION_SECRET_ENV_KEY;
 exports.OidcAccountService = OidcAccountService;
 exports.OidcAccountServiceDelegate = OidcAccountServiceDelegate;
@@ -6761,10 +6867,12 @@ exports.OidcModelServerActions = OidcModelServerActions;
 exports.OidcModuleConfig = OidcModuleConfig;
 exports.OidcServerFirestoreCollections = OidcServerFirestoreCollections;
 exports.activeJwksKeysQuery = activeJwksKeysQuery;
+exports.allOidcScopesStringForProviderConfig = allOidcScopesStringForProviderConfig;
 exports.appOidcModelModuleMetadata = appOidcModelModuleMetadata;
 exports.applyOidcAuthMiddleware = applyOidcAuthMiddleware;
 exports.applyOidcCorsMiddleware = applyOidcCorsMiddleware;
 exports.buildBearerChallenge = buildBearerChallenge;
+exports.buildFirebaseServerMcpResourceServer = buildFirebaseServerMcpResourceServer;
 exports.createAdapterFactory = createAdapterFactory;
 exports.createOidcClientFactory = createOidcClientFactory;
 exports.deleteOidcClientFactory = deleteOidcClientFactory;

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.3",
+  "version": "13.12.5",
   "peerDependencies": {
-    "@dereekb/analytics": "13.12.3",
-    "@dereekb/date": "13.12.3",
-    "@dereekb/firebase": "13.12.3",
-    "@dereekb/firebase-server": "13.12.3",
-    "@dereekb/model": "13.12.3",
-    "@dereekb/nestjs": "13.12.3",
-    "@dereekb/rxjs": "13.12.3",
-    "@dereekb/util": "13.12.3",
-    "@dereekb/zoho": "13.12.3",
+    "@dereekb/analytics": "13.12.5",
+    "@dereekb/date": "13.12.5",
+    "@dereekb/firebase": "13.12.5",
+    "@dereekb/firebase-server": "13.12.5",
+    "@dereekb/model": "13.12.5",
+    "@dereekb/nestjs": "13.12.5",
+    "@dereekb/rxjs": "13.12.5",
+    "@dereekb/util": "13.12.5",
+    "@dereekb/zoho": "13.12.5",
     "@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>;
     /**