@dereekb/firebase-server 13.12.2 → 13.12.4

package/mcp/package.json

@@ -1,20 +1,21 @@
 {
   "name": "@dereekb/firebase-server/mcp",
-  "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/firebase-server/oidc": "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/firebase-server/oidc": "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",
     "@modelcontextprotocol/sdk": "1.29.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/core": "^11.1.19",
+    "arktype": "^2.2.0",
     "express": "^5.2.1",
     "firebase-admin": "^13.8.0"
   },

package/mcp/src/lib/service/analytics/mcp.analytics.config.d.ts

@@ -3,7 +3,7 @@ import { type InjectionToken } from '@nestjs/common';
  * Default analytics event name used by {@link FirebaseServerMcpAnalyticsService} when
  * forwarding a completed MCP tool call to the downstream analytics pipeline.
  */
-export declare const DEFAULT_MCP_ANALYTICS_EVENT_NAME = "mcp-tool";
+export declare const DEFAULT_MCP_ANALYTICS_EVENT_NAME = "Mcp Tool Call";
 /**
  * Configuration for {@link FirebaseServerMcpAnalyticsService}.
  *
@@ -18,7 +18,9 @@ export interface FirebaseServerMcpAnalyticsConfig {
      */
     readonly eventName?: string;
     /**
-     * Whether to emit a per-call `Logger` line for each completed tool call. Defaults to `true`.
+     * Whether to emit a per-call `Logger` line for each completed tool call.
+     *
+     * Defaults to `true` on non-production environments.
      */
     readonly logEvents?: boolean;
 }
@@ -27,7 +29,7 @@ export interface FirebaseServerMcpAnalyticsConfig {
  *
  * @example
  * ```typescript
- * @Module(appMcpAnalyticsModuleMetadata({ mcpAnalyticsConfig: { eventName: 'mcp-tool', logEvents: true } }))
+ * @Module(appMcpAnalyticsModuleMetadata({ mcpAnalyticsConfig: { eventName: 'Mcp Tool Call', logEvents: true } }))
  * export class AppMcpAnalyticsModule {}
  * ```
  */

package/mcp/src/lib/service/analytics/mcp.analytics.service.d.ts

@@ -1,4 +1,4 @@
-import { FirebaseServerAnalyticsService } from '@dereekb/firebase-server';
+import { FirebaseServerAnalyticsService, FirebaseServerEnvService } from '@dereekb/firebase-server';
 import { McpAnalyticsService, type McpAnalyticsEvent } from './mcp.analytics.handler';
 import { type FirebaseServerMcpAnalyticsConfig } from './mcp.analytics.config';
 /**
@@ -11,10 +11,11 @@ import { type FirebaseServerMcpAnalyticsConfig } from './mcp.analytics.config';
  * no-op aside from the optional log line.
  */
 export declare class FirebaseServerMcpAnalyticsService extends McpAnalyticsService {
+    private readonly firebaseServerEnvService;
     private readonly analyticsService?;
     private readonly _logger;
     private readonly _eventName;
     private readonly _logEvents;
-    constructor(analyticsService?: FirebaseServerAnalyticsService | undefined, config?: FirebaseServerMcpAnalyticsConfig);
+    constructor(firebaseServerEnvService: FirebaseServerEnvService, analyticsService?: FirebaseServerAnalyticsService | undefined, config?: FirebaseServerMcpAnalyticsConfig);
     handleMcpAnalyticsEvent(event: McpAnalyticsEvent): void;
 }

package/mcp/src/lib/service/tools/mcp.tool.model-info.d.ts

@@ -14,6 +14,15 @@ export declare const MODEL_INFO_DISPATCH_CALL = "info";
  * apps avoiding collisions should not register a real model literally named "model".
  */
 export declare const MODEL_INFO_DISPATCH_MODEL_TYPE = "model";
+/**
+ * Group label applied to manifest entries that declare no `modelGroup`. Keeps the `groups` mode
+ * total reconcilable with the catalog size (sum of group counts always equals `totalModels`).
+ */
+export declare const MODEL_INFO_UNGROUPED_LABEL = "(ungrouped)";
+/**
+ * Hint string surfaced alongside the default `groups` response so callers know how to drill in.
+ */
+export declare const MODEL_INFO_GROUPS_HINT = "Pass `model` for one/many models, `modelGroup` for a group, or `all:true` for the full catalog.";
 /**
  * Constructor dependencies for {@link createModelInfoTool}.
  */
@@ -25,13 +34,43 @@ export interface CreateModelInfoToolDeps {
     readonly manifest: readonly McpManifestModelEntry[];
 }
 /**
- * Shape of the `model-info` tool input. Omit `model` to list every model in the manifest.
+ * Public shape of the `model-info` tool input. Every field is optional; the combination selects
+ * the response mode (see {@link createModelInfoTool}).
  */
 export interface ModelInfoToolInput {
-    readonly model?: string;
+    /**
+     * One model (string) or many (string array), each matched by `modelType`, `identityConst`, or
+     * `collectionPrefix`. A string yields `mode: 'single'`; an array yields `mode: 'multiple'`.
+     */
+    readonly model?: string | ReadonlyArray<string>;
+    /**
+     * Returns the summary list of models in this group (`mode: 'list'`). Matched case-insensitively.
+     */
+    readonly modelGroup?: string;
+    /**
+     * Opt in to the full catalog summary (every model). Never the default.
+     */
+    readonly all?: boolean;
+    /**
+     * Forces (`true`) or suppresses (`false`) full persisted-field detail in `list` / `multiple`
+     * modes. Defaults to summary rows for `list`, full entries for `single` / `multiple`.
+     */
+    readonly fields?: boolean;
 }
 /**
- * Summary row returned in list mode.
+ * Normalized form of {@link ModelInfoToolInput} produced by {@link parseModelInfoInput}. The
+ * `model` arg is collapsed to a query array plus a flag recording whether it arrived as an array
+ * (which drives `single` vs `multiple` mode).
+ */
+export interface ParsedModelInfoInput {
+    readonly modelQueries?: ReadonlyArray<string>;
+    readonly modelIsArray: boolean;
+    readonly modelGroup?: string;
+    readonly all: boolean;
+    readonly fields?: boolean;
+}
+/**
+ * Summary row returned in list/group modes and (when `fields: false`) in single/multiple modes.
  */
 export interface ModelInfoSummaryRow {
     readonly modelType: string;
@@ -47,22 +86,63 @@ export interface ModelInfoSummaryRow {
     readonly serviceFactoryExport?: string;
 }
 /**
- * Output payload for the `model-info` tool. `mode === 'list'` carries `models[]`;
- * `mode === 'single'` carries the full `model` entry.
+ * One row in a model-bearing response: either a compact {@link ModelInfoSummaryRow} or the full
+ * {@link McpManifestModelEntry} (including persisted `fields`). The `fields` toggle and the active
+ * mode decide which form is emitted.
+ */
+export type ModelInfoModelRow = ModelInfoSummaryRow | McpManifestModelEntry;
+/**
+ * One model group and the number of models it contains. Returned in the default `groups` mode.
+ */
+export interface ModelInfoGroupCount {
+    readonly modelGroup: string;
+    readonly modelCount: number;
+}
+/**
+ * A model query that matched nothing. Mirrors `model-get`'s per-key `{ key, message }` error shape
+ * with `query` standing in for `key`.
+ */
+export interface ModelInfoNotFound {
+    readonly query: string;
+    readonly message: string;
+}
+/**
+ * Output payload for the `model-info` tool. The `mode` field discriminates the variant:
+ * - `groups`: model groups + counts (the default, no-arg response).
+ * - `list`: a summary (or, with `fields: true`, full) list — used by `modelGroup` and `all`.
+ * - `single`: full detail for one `model` string.
+ * - `multiple`: full detail per match for a `model` array, with misses in `notFound`.
  */
 export type ModelInfoToolOutput = {
+    readonly mode: 'groups';
+    readonly groups: ReadonlyArray<ModelInfoGroupCount>;
+    readonly totalModels: number;
+    readonly hint: string;
+} | {
     readonly mode: 'list';
-    readonly models: ReadonlyArray<ModelInfoSummaryRow>;
+    readonly models: ReadonlyArray<ModelInfoModelRow>;
+    readonly modelGroup?: string;
 } | {
     readonly mode: 'single';
-    readonly model: McpManifestModelEntry;
+    readonly model: ModelInfoModelRow;
+} | {
+    readonly mode: 'multiple';
+    readonly models: ReadonlyArray<ModelInfoModelRow>;
+    readonly notFound?: ReadonlyArray<ModelInfoNotFound>;
 };
 /**
  * Builds the built-in `model-info` MCP tool definition.
  *
- * Mirrors dbx-cli's `model-info [model]` command:
- * - Without a `model` arg: returns a summary list (modelType, modelName, prefix, group, identity, field count).
- * - With a `model` arg: matches by `modelType`, `identityConst`, or `collectionPrefix` and returns the full entry.
+ * Modes (selected by input):
+ * - No args: returns model groups + counts (`mode: 'groups'`) — the cheap default for browsing.
+ * - `model` (string): returns the full entry for one model (`mode: 'single'`).
+ * - `model` (string array): returns full detail per match (`mode: 'multiple'`); misses land in `notFound`.
+ * - `modelGroup`: returns the summary list of that group's models (`mode: 'list'`).
+ * - `all: true`: returns the full catalog summary (`mode: 'list'`).
+ * - `fields`: forces (`true`) or suppresses (`false`) full persisted-field detail in list/multiple modes.
+ *
+ * Each `model` query matches by `modelType`, `identityConst`, or `collectionPrefix`. When several
+ * params are supplied, precedence is `model` > `modelGroup` > `all` > the default `groups` view.
  *
  * Output is delivered as both stringified JSON in `content[0].text` and `structuredContent`
  * so MCP clients can consume either form.

package/model/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@dereekb/firebase-server/model",
-  "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/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",
     "@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;