@dereekb/firebase-server 14.4.0 → 14.5.1

package/mcp/package.json

@@ -1,20 +1,20 @@
 {
   "name": "@dereekb/firebase-server/mcp",
-  "version": "14.4.0",
+  "version": "14.5.1",
   "sideEffects": false,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/analytics": "14.4.0",
-    "@dereekb/date": "14.4.0",
-    "@dereekb/firebase": "14.4.0",
-    "@dereekb/firebase-server": "14.4.0",
-    "@dereekb/firebase-server/oidc": "14.4.0",
-    "@dereekb/model": "14.4.0",
-    "@dereekb/nestjs": "14.4.0",
-    "@dereekb/oauth-resource": "14.4.0",
-    "@dereekb/rxjs": "14.4.0",
-    "@dereekb/util": "14.4.0",
-    "@dereekb/zoho": "14.4.0",
+    "@dereekb/analytics": "14.5.1",
+    "@dereekb/date": "14.5.1",
+    "@dereekb/firebase": "14.5.1",
+    "@dereekb/firebase-server": "14.5.1",
+    "@dereekb/firebase-server/oidc": "14.5.1",
+    "@dereekb/model": "14.5.1",
+    "@dereekb/nestjs": "14.5.1",
+    "@dereekb/oauth-resource": "14.5.1",
+    "@dereekb/rxjs": "14.5.1",
+    "@dereekb/util": "14.5.1",
+    "@dereekb/zoho": "14.5.1",
     "@modelcontextprotocol/node": "2.0.0",
     "@modelcontextprotocol/server": "2.0.0",
     "@nestjs/common": "^12.0.1",

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

@@ -132,9 +132,11 @@ export declare abstract class McpModuleConfig {
      * injected {@link OidcProviderConfigService.clientRequestableScopesSupported}, so
      * the MCP resource advertises the scopes the issuer grants an arbitrary client
      * without the app restating them. Scopes only an admin-assigned provider profile
-     * unlocks are already excluded — requesting one is fatal at the consent unlock
-     * gate. Provide this only to narrow the set further; it returns the subset to
-     * advertise. When unset, the whole base list is advertised.
+     * unlocks are excluded from that base list, since an unassigned client can never
+     * be granted one. Provide this to narrow the set further — or to add such a gated
+     * scope back deliberately, which is safe: the consent URL builder withholds it
+     * from any client whose profiles do not unlock it, so that client's flow completes
+     * without it rather than failing. When unset, the whole base list is advertised.
      *
      * Advertising these matters because dynamic-registration MCP clients (the Claude
      * Code CLI) read `scopes_supported` to decide which scopes to request on the
@@ -259,3 +261,71 @@ export type McpModelRolesTargetUidPredicate = (auth: Maybe<FirebaseServerAuthDat
  * NestJS injection token for the optional {@link McpModelRolesTargetUidPredicate} provider.
  */
 export declare const MCP_MODEL_ROLES_TARGET_UID_PREDICATE = "MCP_MODEL_ROLES_TARGET_UID_PREDICATE";
+/**
+ * Input handed to an {@link McpCliTokenMinter}.
+ */
+export interface McpCliTokenMintInput {
+    /**
+     * The calling request's auth data — the identity the minted credential belongs to.
+     */
+    readonly auth: Maybe<FirebaseServerAuthData>;
+    /**
+     * An optional subset of the caller's own scopes to grant. May only narrow.
+     */
+    readonly scopes?: Maybe<readonly string[]>;
+    /**
+     * An optional requested lifetime in seconds, clamped by the minter.
+     */
+    readonly ttlSeconds?: Maybe<number>;
+    /**
+     * When true, ask the minter to also produce a signed, self-authenticating download URL for the
+     * CLI binary so a bare machine can fetch it before redeeming the claim code.
+     */
+    readonly includeDownloadUrl?: boolean;
+    /**
+     * The calling MCP session's client address, resolved from the tool call's raw request.
+     *
+     * Forwarded so a mint through the MCP surface records the same address an HTTP mint does. Without
+     * it an app that binds a claim code to its minting address would silently apply that binding on one
+     * path and not the other — a gate that looks enabled while doing nothing is worse than none.
+     */
+    readonly requestIp?: Maybe<string>;
+}
+/**
+ * What an {@link McpCliTokenMinter} returns. Carries the one-time claim code and NEVER the refresh
+ * token — the tool's output reaches an MCP transcript, and a refresh token must not.
+ */
+export interface McpCliTokenMintResult {
+    readonly claimCode: string;
+    readonly claimExpiresAt: string;
+    readonly expiresAt: string;
+    readonly scope: string;
+    /**
+     * The CLI's binary name, used to render the exact `<cli> auth handoff <code>` command.
+     */
+    readonly cliName?: string;
+    /**
+     * A signed download URL for the CLI binary, when one was requested and the app wired the
+     * download path.
+     */
+    readonly downloadUrl?: string;
+    /**
+     * SHA-256 of the artifact behind {@link downloadUrl}, so the caller can verify what it fetched.
+     */
+    readonly downloadSha256?: string;
+}
+/**
+ * Signature for the optional app-supplied CLI credential minter behind the `cli-token` MCP tool.
+ *
+ * Minting needs `OidcService.getProvider()`, which lives in `@dereekb/firebase-server/oidc`. Routing
+ * it through an app-supplied injection token — the same shape as
+ * {@link McpModelRolesTargetUidPredicate} — keeps `@dereekb/firebase-server/mcp` app-agnostic and
+ * free of a dependency on the oidc package.
+ *
+ * When no minter is provided the `cli-token` tool is not registered at all.
+ */
+export type McpCliTokenMinter = (input: McpCliTokenMintInput) => PromiseOrValue<McpCliTokenMintResult>;
+/**
+ * NestJS injection token for the optional {@link McpCliTokenMinter} provider.
+ */
+export declare const MCP_CLI_TOKEN_MINTER = "MCP_CLI_TOKEN_MINTER";

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

@@ -13,3 +13,4 @@ export * from './tools/mcp.tool.model-decode';
 export * from './tools/mcp.tool.enum-info';
 export * from './tools/mcp.tool.url-models';
 export * from './tools/mcp.tool.batch-execute';
+export * from './tools/mcp.tool.cli-token';

package/mcp/src/lib/service/mcp.server.factory.d.ts

@@ -1,7 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/server';
 import { type Request } from 'express';
 import { ModelApiCallModelDispatchService, ModelApiGetService, FirebaseServerStorageService, type FirebaseServerAuthData } from '@dereekb/firebase-server';
-import { McpModuleConfig, type McpAuthRoleReader, type McpModelRolesTargetUidPredicate } from '../mcp.config';
+import { McpModuleConfig, type McpAuthRoleReader, type McpCliTokenMinter, type McpModelRolesTargetUidPredicate } from '../mcp.config';
 import { type McpAnalyticsService } from './analytics/mcp.analytics.handler';
 /**
  * Optional per-request context passed when invoking the MCP server through a
@@ -29,6 +29,7 @@ export declare class McpServerFactoryService {
     private readonly roleReader?;
     private readonly storageService?;
     private readonly modelRolesTargetUidPredicate?;
+    private readonly cliTokenMinter?;
     private readonly _logger;
     private _cachedTools;
     private _cachedStaticTools;
@@ -43,7 +44,7 @@ export declare class McpServerFactoryService {
     private _warnedMissingRoleReader;
     private _resolvedReasonConfig?;
     private readonly _analyticsService;
-    constructor(mcpConfig: McpModuleConfig, dispatchService: ModelApiCallModelDispatchService, modelApiGetService?: ModelApiGetService | undefined, roleReader?: McpAuthRoleReader | undefined, analyticsService?: McpAnalyticsService, storageService?: FirebaseServerStorageService | undefined, modelRolesTargetUidPredicate?: McpModelRolesTargetUidPredicate | undefined);
+    constructor(mcpConfig: McpModuleConfig, dispatchService: ModelApiCallModelDispatchService, modelApiGetService?: ModelApiGetService | undefined, roleReader?: McpAuthRoleReader | undefined, analyticsService?: McpAnalyticsService, storageService?: FirebaseServerStorageService | undefined, modelRolesTargetUidPredicate?: McpModelRolesTargetUidPredicate | undefined, cliTokenMinter?: McpCliTokenMinter | undefined);
     /**
      * Builds a configured MCP server with tool listing + dispatch handlers wired up.
      *

package/mcp/src/lib/service/mcp.tool-generator.d.ts

@@ -281,6 +281,15 @@ export interface BuildStaticToolDefinitionInput {
      * Declarative visibility rule checked per request. Defaults to `{}` (always visible) when omitted.
      */
     readonly rule?: McpVisibilityRule;
+    /**
+     * OIDC scope TERMS an OIDC caller must satisfy to see AND to invoke this tool, evaluated by the
+     * same `oidcScopeTermsSatisfied` path the generated callModel tools use.
+     *
+     * Generated tools derive their terms from the dispatch call type; a built-in tool has no model
+     * verb to derive from, so a privileged one declares its own here (e.g. the CLI-token mint gates on
+     * `token.cli`). Omitted ⇒ no scope requirement, which is right for every read-only built-in.
+     */
+    readonly requiredScopeTerms?: readonly OidcScopeTerm[];
 }
 /**
  * Assembles a statically-registered {@link McpToolDefinition} with consistent MCP annotations.

package/mcp/src/lib/service/tools/mcp.tool.cli-token.d.ts

@@ -0,0 +1,62 @@
+import { type McpCliTokenMinter } from '../../mcp.config';
+import { type McpToolDefinition } from '../mcp.tool-generator';
+/**
+ * Reserved tool name for the built-in `cli-token` static tool.
+ */
+export declare const CLI_TOKEN_TOOL_NAME = "cli-token";
+/**
+ * Synthetic call type used in the tool's dispatch identity. `create` so the visibility classifier
+ * treats the tool as a write — minting a credential is not a read.
+ */
+export declare const CLI_TOKEN_DISPATCH_CALL = "create";
+/**
+ * Synthetic model type used in the tool's dispatch identity.
+ */
+export declare const CLI_TOKEN_DISPATCH_MODEL_TYPE = "auth";
+/**
+ * Constructor dependencies for {@link createCliTokenTool}.
+ */
+export interface CreateCliTokenToolDeps {
+    /**
+     * The app-supplied minter. The tool is only ever built when one is wired.
+     */
+    readonly minter: McpCliTokenMinter;
+}
+/**
+ * Output payload for the `cli-token` tool.
+ *
+ * Deliberately does NOT carry the refresh token: the claim code is a one-time, short-lived pointer
+ * at it, which is what makes the tool's output safe to leave in a transcript.
+ */
+export interface CliTokenToolOutput {
+    readonly claimCode: string;
+    readonly claimExpiresAt: string;
+    readonly expiresAt: string;
+    readonly scope: string;
+    readonly cliName?: string;
+    readonly downloadUrl?: string;
+    readonly downloadSha256?: string;
+    /**
+     * The exact command to run once the CLI is on the machine.
+     */
+    readonly handoffCommand: string;
+}
+/**
+ * Builds the built-in `cli-token` MCP tool definition — the agent-facing half of the CLI handoff.
+ *
+ * Mints a short-lived CLI login credential carrying no more privilege than the calling session and
+ * returns the one-time claim code that unwraps it, optionally alongside a signed download URL for
+ * the CLI binary so a bare machine can go from nothing to logged in without a human.
+ *
+ * Three independent gates apply before the handler ever runs:
+ *
+ * - `requiredScopeTerms: [token.cli]` — the tool is invisible to `tools/list` AND uncallable without
+ *   the scope, through the factory's existing scope filter.
+ * - `visibility.requiredRoles: [admin]` — the declarative role gate, which fails closed when the app
+ *   wires no `McpAuthRoleReader`.
+ * - The mint endpoint's own admin predicate, inside the minter.
+ *
+ * @param deps - The app-supplied minter.
+ * @returns A statically-registered {@link McpToolDefinition} to append to the MCP server factory's tool registry.
+ */
+export declare function createCliTokenTool(deps: CreateCliTokenToolDeps): McpToolDefinition;

package/model/package.json

@@ -1,17 +1,18 @@
 {
   "name": "@dereekb/firebase-server/model",
-  "version": "14.4.0",
+  "version": "14.5.1",
   "sideEffects": false,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/analytics": "14.4.0",
-    "@dereekb/date": "14.4.0",
-    "@dereekb/firebase": "14.4.0",
-    "@dereekb/firebase-server": "14.4.0",
-    "@dereekb/model": "14.4.0",
-    "@dereekb/nestjs": "14.4.0",
-    "@dereekb/rxjs": "14.4.0",
-    "@dereekb/util": "14.4.0",
+    "@cantoo/pdf-lib": ">=2.6.5 <2.11.0",
+    "@dereekb/analytics": "14.5.1",
+    "@dereekb/date": "14.5.1",
+    "@dereekb/firebase": "14.5.1",
+    "@dereekb/firebase-server": "14.5.1",
+    "@dereekb/model": "14.5.1",
+    "@dereekb/nestjs": "14.5.1",
+    "@dereekb/rxjs": "14.5.1",
+    "@dereekb/util": "14.5.1",
     "@nestjs/common": "^12.0.1",
     "@nestjs/config": "^12.0.0",
     "archiver": "^8.0.0",
@@ -19,9 +20,11 @@
     "express": "^5.2.1",
     "firebase-functions": "^7.3.2",
     "make-error": "^1.3.6",
-    "@cantoo/pdf-lib": ">=2.6.5 <2.11.0",
     "sharp": "0.35.4"
   },
+  "devDependencies": {
+    "firebase-admin": "^13.10.0"
+  },
   "exports": {
     "./package.json": "./package.json",
     ".": {