@dereekb/firebase-server 14.5.0 → 14.6.0

package/mcp/package.json

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

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

@@ -313,6 +313,18 @@ export interface McpCliTokenMintResult {
      * SHA-256 of the artifact behind {@link downloadUrl}, so the caller can verify what it fetched.
      */
     readonly downloadSha256?: string;
+    /**
+     * Name of the CLI env the credential should be redeemed into, from `CliTokenApiModuleConfig.envName`.
+     *
+     * Load-bearing for the rendered `handoffCommand`, not decorative. `dbx-cli auth handoff` resolves
+     * the issuer to POST the claim to from the ACTIVE env — so on a machine with no active env the
+     * bare command fails `AUTH_HANDOFF_NO_ISSUER`, and on one active against a different env it aims
+     * the claim at the wrong issuer. A built-in env NAME is only a default template until something
+     * instantiates it, so it cannot be relied on to already exist. The deployment is the only party
+     * that knows which env it is; passing it through is what lets the tool render a command the target
+     * machine can run unmodified.
+     */
+    readonly envName?: string;
 }
 /**
  * Signature for the optional app-supplied CLI credential minter behind the `cli-token` MCP tool.

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

@@ -103,7 +103,56 @@ export interface McpManifestModelEntry {
         readonly exportName: string;
         readonly sourceFile: string;
     };
+    /**
+     * Declared `@dbxModelCompositeKey from=<ModelA>[,<ModelB>...] encoding=<two-way|one-way>` on the
+     * model interface — this model's document id is a flattened encoding of a source model's key
+     * (structural mirror of `@dereekb/dbx-cli`'s `CliModelCompositeKey`). Absent when the model omits
+     * the tag.
+     *
+     * Drives `model-decode`'s `derivedKeys` / `compositeSource` output and lets `model-get` accept a
+     * source model key in place of the flattened id.
+     */
+    readonly compositeKey?: McpManifestModelCompositeKey;
 }
+/**
+ * Flat-key encoding declared by a `@dbxModelCompositeKey` tag.
+ *
+ * - `one-way` — `flatFirestoreModelKey()`: slashes removed; the source key cannot be recovered.
+ * - `two-way` — `twoWayFlatFirestoreModelKey()`: slashes replaced with underscores; the source key
+ *   is recoverable with `inferKeyFromTwoWayFlatFirestoreModelKey()`.
+ */
+export type McpManifestModelCompositeKeyEncoding = 'one-way' | 'two-way';
+/**
+ * Composite-key declaration carried on a {@link McpManifestModelEntry}.
+ */
+export interface McpManifestModelCompositeKey {
+    /**
+     * `'*'` when any model's key may be the source, or the source model names as written in the tag
+     * — each an interface name, identity const, or modelType, resolved against the manifest.
+     */
+    readonly from: readonly string[] | '*';
+    readonly encoding: McpManifestModelCompositeKeyEncoding;
+}
+/**
+ * Resolves the manifest entries whose `compositeKey.from` names `source` — the models whose document
+ * id is derived from a `source` document's key. A wildcard `from=*` matches every model except
+ * `source` itself (a model's id is never derived from its own key).
+ *
+ * @param source - The manifest entry of the decoded key's leaf model.
+ * @param manifest - The full model manifest.
+ * @returns The composite-key entries derived from `source`, in manifest order.
+ */
+export declare function findCompositeKeyModelsDerivedFrom(source: McpManifestModelEntry, manifest: readonly McpManifestModelEntry[]): McpManifestModelEntry[];
+/**
+ * Whether `candidate` is a composite-key model whose document id is derived from a `source`
+ * document's key — `candidate.compositeKey.from` names `source` (by interface name, identity const,
+ * or modelType) or is the wildcard `*`. A model is never derived from its own key.
+ *
+ * @param source - The manifest entry of the source model.
+ * @param candidate - The manifest entry to test.
+ * @returns `true` when `candidate`'s id is a flattened `source` key.
+ */
+export declare function isCompositeKeyModelDerivedFrom(source: McpManifestModelEntry, candidate: McpManifestModelEntry): boolean;
 /**
  * One enum value with its persisted literal and the leading JSDoc paragraph.
  *

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

@@ -36,6 +36,10 @@ export interface CliTokenToolOutput {
     readonly cliName?: string;
     readonly downloadUrl?: string;
     readonly downloadSha256?: string;
+    /**
+     * Name of the CLI env the credential is redeemed into, when the app configured one.
+     */
+    readonly envName?: string;
     /**
      * The exact command to run once the CLI is on the machine.
      */

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

@@ -1,4 +1,4 @@
-import { type McpManifestModelEntry } from '../mcp.manifest';
+import { type McpManifestModelCompositeKeyEncoding, type McpManifestModelEntry } from '../mcp.manifest';
 import { type McpToolDefinition } from '../mcp.tool-generator';
 /**
  * Reserved tool name for the built-in `model-decode` static tool.
@@ -46,14 +46,46 @@ export interface DecodedKeySegment {
     readonly sourceFile?: string;
 }
 /**
- * Output payload for the `model-decode` tool.
+ * Segments of a decoded Firestore key — the leaf, its ancestor chain, and any prefixes the manifest
+ * could not resolve.
  */
-export interface ModelDecodeToolOutput {
+export interface DecodedKeySegments {
     readonly key: string;
     readonly leaf: DecodedKeySegment;
     readonly ancestors: ReadonlyArray<DecodedKeySegment>;
     readonly unresolvedPrefixes: ReadonlyArray<string>;
 }
+/**
+ * A composite-key model whose document id is derived from the decoded key, with that document's
+ * ready-to-use key. Published so a caller never has to hand-build a flattened id (e.g. decoding a
+ * `District` key also yields the `jobDistrict` key `jd/<flattened district key>`).
+ */
+export interface DerivedCompositeKey {
+    /**
+     * The derived document's full key (`<collectionPrefix>/<flattened source key>`).
+     */
+    readonly key: string;
+    readonly modelType: string;
+    readonly modelName: string;
+    readonly collectionPrefix: string;
+    readonly encoding: McpManifestModelCompositeKeyEncoding;
+}
+/**
+ * Output payload for the `model-decode` tool.
+ */
+export interface ModelDecodeToolOutput extends DecodedKeySegments {
+    /**
+     * Composite-key models derived from this key (see {@link DerivedCompositeKey}). Empty when the leaf
+     * prefix is unresolved or no model declares this leaf as a composite-key source.
+     */
+    readonly derivedKeys: ReadonlyArray<DerivedCompositeKey>;
+    /**
+     * When the leaf is itself a `two-way` composite-key model, the source key recovered from its id
+     * (`inferKeyFromTwoWayFlatFirestoreModelKey`), decoded. Absent for `one-way` models (the source is
+     * not recoverable) and when the id does not parse as a flattened key.
+     */
+    readonly compositeSource?: DecodedKeySegments;
+}
 /**
  * Builds the built-in `model-decode` MCP tool definition.
  *
@@ -72,16 +104,30 @@ export interface ModelDecodeToolOutput {
 export declare function createModelDecodeTool(deps: CreateModelDecodeToolDeps): McpToolDefinition;
 /**
  * Splits `rawKey` on `/`, resolves each `[prefix, id]` pair against the manifest, and
- * returns the leaf segment + ancestor chain.
+ * returns the leaf segment + ancestor chain, plus the composite-key relationships declared
+ * on the manifest: the keys of models derived from this key (`derivedKeys`) and, for a
+ * two-way composite-key leaf, the recovered source key (`compositeSource`).
  *
  * Mirrors the dbx-cli `decodeFirestoreModelKey` helper structurally; both implementations
- * must stay in lockstep on segment count and resolution order.
+ * must stay in lockstep on segment count, resolution order, and composite-key output.
  *
  * @param rawKey - The Firestore key string.
  * @param manifest - The model manifest.
- * @returns The decoded key with leaf, ancestors, and any unresolved prefixes.
+ * @returns The decoded key with leaf, ancestors, unresolved prefixes, and composite-key relationships.
  * @throws {Error} When `rawKey` is empty or does not parse into an even number of `prefix/id` segments.
  *
  * @__NO_SIDE_EFFECTS__
  */
 export declare function decodeFirestoreModelKey(rawKey: string, manifest: ReadonlyArray<McpManifestModelEntry>): ModelDecodeToolOutput;
+/**
+ * Splits `rawKey` on `/` and resolves each `[prefix, id]` pair against the manifest — the segment
+ * walk shared by {@link decodeFirestoreModelKey} and the two-way composite-source decode.
+ *
+ * @param rawKey - The Firestore key string.
+ * @param manifest - The model manifest.
+ * @returns The decoded key with leaf, ancestors, and any unresolved prefixes.
+ * @throws {Error} When `rawKey` is empty or does not parse into an even number of `prefix/id` segments.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function decodeFirestoreModelKeySegments(rawKey: string, manifest: ReadonlyArray<McpManifestModelEntry>): DecodedKeySegments;

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

@@ -1,6 +1,7 @@
 import { type Maybe } from '@dereekb/util';
 import { type FirestoreModelIdentity, type FirestoreModelKey, type FirestoreModelType } from '@dereekb/firebase';
 import { type ModelAccessMultiReadResult, type FirebaseServerAuthData } from '@dereekb/firebase-server';
+import { type McpManifestModelEntry } from '../mcp.manifest';
 import { type McpToolDefinition } from '../mcp.tool-generator';
 /**
  * Reserved tool name for the built-in `model-get` static tool.
@@ -51,6 +52,13 @@ export interface CreateModelGetToolDeps {
      * `prefix/id` keys.
      */
     readonly resolveIdentity: McpModelGetResolveIdentity;
+    /**
+     * Frozen model catalog. When present, a key whose leaf model is a declared composite-key source of
+     * the requested root model (`@dbxModelCompositeKey from=…`) is flattened into that model's id
+     * instead of being passed verbatim — e.g. `model-get jobDistrict` accepts a `District` key
+     * `rc/…/rcsrd/<id>` and reads `jd/<flattened district key>`. Omit to disable the rewrite.
+     */
+    readonly manifest?: readonly McpManifestModelEntry[];
 }
 /**
  * Shape of the `model-get` tool input.
@@ -66,6 +74,8 @@ export interface ModelGetToolInput {
  * - Accepts an array of keys; values containing `/` are treated as full keys and passed verbatim
  *   while bare ids are promoted to `${collectionName}/${id}` for root models.
  * - Nested (subcollection) models reject bare ids since a parent path is required.
+ * - When a manifest is supplied, a root composite-key model also accepts its declared source
+ *   model's key and flattens it into the document id (see {@link CreateModelGetToolDeps.manifest}).
  * - Auto-chunks at {@link MCP_MODEL_GET_BATCH_SIZE} keys per backend call, mirroring
  *   `getMultipleModelsOverHttpChunked` on the CLI side.
  *

package/model/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@dereekb/firebase-server/model",
-  "version": "14.5.0",
+  "version": "14.6.0",
   "sideEffects": false,
   "type": "module",
   "peerDependencies": {
     "@cantoo/pdf-lib": ">=2.6.5 <2.11.0",
-    "@dereekb/analytics": "14.5.0",
-    "@dereekb/date": "14.5.0",
-    "@dereekb/firebase": "14.5.0",
-    "@dereekb/firebase-server": "14.5.0",
-    "@dereekb/model": "14.5.0",
-    "@dereekb/nestjs": "14.5.0",
-    "@dereekb/rxjs": "14.5.0",
-    "@dereekb/util": "14.5.0",
+    "@dereekb/analytics": "14.6.0",
+    "@dereekb/date": "14.6.0",
+    "@dereekb/firebase": "14.6.0",
+    "@dereekb/firebase-server": "14.6.0",
+    "@dereekb/model": "14.6.0",
+    "@dereekb/nestjs": "14.6.0",
+    "@dereekb/rxjs": "14.6.0",
+    "@dereekb/util": "14.6.0",
     "@nestjs/common": "^12.0.1",
     "@nestjs/config": "^12.0.0",
     "archiver": "^8.0.0",

package/oidc/index.esm.js

@@ -6504,7 +6504,7 @@ var CLI_TOKEN_CLAIM_INVALID_MESSAGE = 'The claim code is invalid, expired, or ha
      * @throws {HttpsError} `401` with no uid, `403` when a gate rejects the caller, `400` when minting is disabled.
      */ function mintCliToken(auth, params, context) {
                 return _async_to_generator$7(function() {
-                    var _parentGrantId, _this_config, _this_config1, _this_config2, _this_config3, _this_config4, _this_config5, uid, isAllowed, _tmp, configuredScope, callerScopes, cliClientId, provider, client, scopeString, ttlSeconds, grantInit, grant, grantId, refreshToken, refreshTokenValue, nowMs, expiresAt, claimExpiresAt, claimCode;
+                    var _parentGrantId, _this_config, _this_config1, _this_config2, _this_config3, _this_config4, _this_config5, _this_config6, uid, isAllowed, _tmp, configuredScope, callerScopes, cliClientId, provider, client, scopeString, ttlSeconds, grantInit, grant, grantId, refreshToken, refreshTokenValue, nowMs, expiresAt, claimExpiresAt, claimCode;
                     return _ts_generator$7(this, function(_state) {
                         switch(_state.label){
                             case 0:
@@ -6652,14 +6652,18 @@ var CLI_TOKEN_CLAIM_INVALID_MESSAGE = 'The claim code is invalid, expired, or ha
                             case 9:
                                 _state.sent();
                                 this._logger.log("Minted CLI credential: minter=".concat(uid, " parentGrant=").concat((_parentGrantId = parentGrantId(auth)) !== null && _parentGrantId !== void 0 ? _parentGrantId : 'unknown', " childGrant=").concat(grantId, " client=").concat(cliClientId, ' scope="').concat(scopeString, '" expiresAt=').concat(expiresAt));
+                                // `envName` is returned as well as stored on the claim: the stored copy configures the env AFTER a
+                                // successful redeem, but the caller needs the name to BUILD the redeem command in the first place.
                                 return [
                                     2,
-                                    {
+                                    _object_spread$4({
                                         claimCode: claimCode,
                                         claimExpiresAt: claimExpiresAt.toISOString(),
                                         expiresAt: expiresAt,
                                         scope: scopeString
-                                    }
+                                    }, ((_this_config6 = this.config) === null || _this_config6 === void 0 ? void 0 : _this_config6.envName) ? {
+                                        envName: this.config.envName
+                                    } : undefined)
                                 ];
                         }
                     });

package/oidc/package.json

@@ -1,19 +1,19 @@
 {
   "name": "@dereekb/firebase-server/oidc",
-  "version": "14.5.0",
+  "version": "14.6.0",
   "sideEffects": false,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/analytics": "14.5.0",
-    "@dereekb/date": "14.5.0",
-    "@dereekb/firebase": "14.5.0",
-    "@dereekb/firebase-server": "14.5.0",
-    "@dereekb/model": "14.5.0",
-    "@dereekb/nestjs": "14.5.0",
-    "@dereekb/oauth-resource": "14.5.0",
-    "@dereekb/rxjs": "14.5.0",
-    "@dereekb/util": "14.5.0",
-    "@dereekb/zoho": "14.5.0",
+    "@dereekb/analytics": "14.6.0",
+    "@dereekb/date": "14.6.0",
+    "@dereekb/firebase": "14.6.0",
+    "@dereekb/firebase-server": "14.6.0",
+    "@dereekb/model": "14.6.0",
+    "@dereekb/nestjs": "14.6.0",
+    "@dereekb/oauth-resource": "14.6.0",
+    "@dereekb/rxjs": "14.6.0",
+    "@dereekb/util": "14.6.0",
+    "@dereekb/zoho": "14.6.0",
     "@nestjs/common": "^12.0.1",
     "@nestjs/config": "^12.0.0",
     "express": "^5.2.1",

package/oidc/src/lib/controller/oidc.cli-token.config.d.ts

@@ -220,6 +220,18 @@ export interface CliTokenMintResult {
      * The space-delimited scopes the minted credential carries.
      */
     readonly scope: string;
+    /**
+     * Name of the CLI env the credential should be redeemed into, echoed from
+     * {@link CliTokenApiModuleConfig.envName}.
+     *
+     * Returned at MINT time, not only stored in the claim payload, because the redeeming machine needs
+     * it BEFORE it can redeem — this is the "information the redeeming machine needs before it can
+     * redeem" the {@link CliTokenMintResult.claimCode} note anticipates, supplied alongside the code
+     * rather than encoded into it. `dbx-cli auth handoff` takes the issuer it POSTs the claim to from
+     * the ACTIVE env, so without a name to pass as `--env` a bare machine fails
+     * `AUTH_HANDOFF_NO_ISSUER` and a machine pointed elsewhere sends the claim to the wrong issuer.
+     */
+    readonly envName?: string;
 }
 /**
  * The credential bundle handed back by `POST /oidc/cli-token/claim`. Everything a bare machine needs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase-server",
-  "version": "14.5.0",
+  "version": "14.6.0",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -58,18 +58,18 @@
   },
   "peerDependencies": {
     "@cantoo/pdf-lib": ">=2.6.5 <2.11.0",
-    "@dereekb/analytics": "14.5.0",
-    "@dereekb/calcom": "14.5.0",
-    "@dereekb/date": "14.5.0",
-    "@dereekb/dbx-core": "14.5.0",
-    "@dereekb/discord": "14.5.0",
-    "@dereekb/firebase": "14.5.0",
-    "@dereekb/model": "14.5.0",
-    "@dereekb/nestjs": "14.5.0",
-    "@dereekb/oauth-resource": "14.5.0",
-    "@dereekb/rxjs": "14.5.0",
-    "@dereekb/util": "14.5.0",
-    "@dereekb/zoho": "14.5.0",
+    "@dereekb/analytics": "14.6.0",
+    "@dereekb/calcom": "14.6.0",
+    "@dereekb/date": "14.6.0",
+    "@dereekb/dbx-core": "14.6.0",
+    "@dereekb/discord": "14.6.0",
+    "@dereekb/firebase": "14.6.0",
+    "@dereekb/model": "14.6.0",
+    "@dereekb/nestjs": "14.6.0",
+    "@dereekb/oauth-resource": "14.6.0",
+    "@dereekb/rxjs": "14.6.0",
+    "@dereekb/util": "14.6.0",
+    "@dereekb/zoho": "14.6.0",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.22.0",
     "@modelcontextprotocol/node": "2.0.0",

package/test/package.json

@@ -1,19 +1,19 @@
 {
   "name": "@dereekb/firebase-server/test",
-  "version": "14.5.0",
+  "version": "14.6.0",
   "sideEffects": false,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/analytics": "14.5.0",
-    "@dereekb/date": "14.5.0",
-    "@dereekb/firebase": "14.5.0",
-    "@dereekb/firebase-server": "14.5.0",
-    "@dereekb/firebase-server/oidc": "14.5.0",
-    "@dereekb/model": "14.5.0",
-    "@dereekb/nestjs": "14.5.0",
-    "@dereekb/oauth-resource": "14.5.0",
-    "@dereekb/rxjs": "14.5.0",
-    "@dereekb/util": "14.5.0",
+    "@dereekb/analytics": "14.6.0",
+    "@dereekb/date": "14.6.0",
+    "@dereekb/firebase": "14.6.0",
+    "@dereekb/firebase-server": "14.6.0",
+    "@dereekb/firebase-server/oidc": "14.6.0",
+    "@dereekb/model": "14.6.0",
+    "@dereekb/nestjs": "14.6.0",
+    "@dereekb/oauth-resource": "14.6.0",
+    "@dereekb/rxjs": "14.6.0",
+    "@dereekb/util": "14.6.0",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.22.0",
     "@nestjs/common": "^12.0.1",
@@ -26,7 +26,7 @@
     "supertest": "^7.2.2"
   },
   "devDependencies": {
-    "@dereekb/nestjs": "14.5.0"
+    "@dereekb/nestjs": "14.6.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/twilio/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/firebase-server/twilio",
-  "version": "14.5.0",
+  "version": "14.6.0",
   "sideEffects": false,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/date": "14.5.0",
-    "@dereekb/firebase": "14.5.0",
-    "@dereekb/firebase-server": "14.5.0",
-    "@dereekb/model": "14.5.0",
-    "@dereekb/nestjs": "14.5.0",
-    "@dereekb/rxjs": "14.5.0",
-    "@dereekb/util": "14.5.0"
+    "@dereekb/date": "14.6.0",
+    "@dereekb/firebase": "14.6.0",
+    "@dereekb/firebase-server": "14.6.0",
+    "@dereekb/model": "14.6.0",
+    "@dereekb/nestjs": "14.6.0",
+    "@dereekb/rxjs": "14.6.0",
+    "@dereekb/util": "14.6.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/zoho/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@dereekb/firebase-server/zoho",
-  "version": "14.5.0",
+  "version": "14.6.0",
   "sideEffects": false,
   "type": "module",
   "peerDependencies": {
-    "@dereekb/analytics": "14.5.0",
-    "@dereekb/date": "14.5.0",
-    "@dereekb/firebase": "14.5.0",
-    "@dereekb/firebase-server": "14.5.0",
-    "@dereekb/model": "14.5.0",
-    "@dereekb/nestjs": "14.5.0",
-    "@dereekb/rxjs": "14.5.0",
-    "@dereekb/util": "14.5.0",
-    "@dereekb/zoho": "14.5.0",
+    "@dereekb/analytics": "14.6.0",
+    "@dereekb/date": "14.6.0",
+    "@dereekb/firebase": "14.6.0",
+    "@dereekb/firebase-server": "14.6.0",
+    "@dereekb/model": "14.6.0",
+    "@dereekb/nestjs": "14.6.0",
+    "@dereekb/rxjs": "14.6.0",
+    "@dereekb/util": "14.6.0",
+    "@dereekb/zoho": "14.6.0",
     "@nestjs/common": "^12.0.1",
     "@nestjs/config": "^12.0.0",
     "express": "^5.2.1"