@dereekb/firebase-server 13.18.0 → 13.20.0

package/mailgun/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@dereekb/firebase-server/mailgun",
-  "version": "13.18.0",
+  "version": "13.20.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.18.0",
-    "@dereekb/firebase": "13.18.0",
-    "@dereekb/firebase-server": "13.18.0",
-    "@dereekb/date": "13.18.0",
-    "@dereekb/nestjs": "13.18.0",
-    "@dereekb/model": "13.18.0",
-    "@dereekb/rxjs": "13.18.0",
-    "@dereekb/util": "13.18.0"
+    "@dereekb/analytics": "13.20.0",
+    "@dereekb/firebase": "13.20.0",
+    "@dereekb/firebase-server": "13.20.0",
+    "@dereekb/date": "13.20.0",
+    "@dereekb/nestjs": "13.20.0",
+    "@dereekb/model": "13.20.0",
+    "@dereekb/rxjs": "13.20.0",
+    "@dereekb/util": "13.20.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/mcp/index.cjs.js

@@ -487,7 +487,7 @@ function _unsupported_iterable_to_array$9(o, minLen) {
  * Version stamp embedded in `route.manifest.json`. Runtime loaders refuse
  * manifests whose `version` does not match. Mirror in `@dereekb/dbx-cli`'s
  * `ROUTE_MANIFEST_VERSION` — bump both together.
- */ var ROUTE_MANIFEST_VERSION = 1;
+ */ var ROUTE_MANIFEST_VERSION = 2;
 /**
  * Extracts the normalized pathname from a full URL or a bare path. Strips the
  * scheme/host/port, query string, and hash; collapses an empty path to `/` and
@@ -3572,12 +3572,12 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  */ function createWhoamiTool(deps) {
     var _ref;
     var _deps_auth_app;
-    var handler = function handler(_args, ctx) {
-        return Promise.resolve(whoamiToolHandler(ctx, deps));
+    var handler = function handler(args, ctx) {
+        return Promise.resolve(whoamiToolHandler(args, ctx, deps));
     };
     var name = WHOAMI_TOOL_NAME;
     var appLabel = (_ref = (_deps_auth_app = deps.auth.app) === null || _deps_auth_app === void 0 ? void 0 : _deps_auth_app.app) !== null && _ref !== void 0 ? _ref : 'this server';
-    var description = "Reports the authenticated caller's uid, raw custom claims, and decoded role set for `".concat(appLabel, "`. Returns `authenticated: false` for anonymous callers. Claim descriptions are drawn from the build-time auth manifest; only keys actually present on the live token are detailed.");
+    var description = "Reports the authenticated caller's identity and decoded role set for `".concat(appLabel, '`. Returns `authenticated: false` for anonymous callers. Defaults to a concise summary (uid + roles only); pass `detail: "claims"` to also include the raw claims object, or `detail: "full"` to additionally include per-claim descriptions (drawn from the build-time auth manifest) and any unknown claim keys.');
     return buildStaticToolDefinition({
         name: name,
         description: description,
@@ -3593,24 +3593,20 @@ function _unsupported_iterable_to_array$5(o, minLen) {
     });
 }
 // MARK: Handler
-function whoamiToolHandler(ctx, deps) {
+function whoamiToolHandler(args, ctx, deps) {
     var _auth_token;
     var _deps_auth_app;
     var auth = ctx.auth;
     if ((auth === null || auth === void 0 ? void 0 : auth.uid) == null) {
-        var output = {
-            authenticated: false,
-            claims: {},
-            roles: [],
-            claimDetails: [],
-            unknownClaimKeys: []
-        };
-        return buildResult(output, '# whoami\n\nUnauthenticated.');
+        return buildResult({
+            authenticated: false
+        }, '# whoami\n\nNot authenticated (anonymous caller).');
     }
+    var detail = parseDetailLevel(args);
     var token = (_auth_token = auth.token) !== null && _auth_token !== void 0 ? _auth_token : {};
-    var presentKeys = Object.entries(token).filter(function(param) {
-        var _param = _sliced_to_array$3(param, 2), value = _param[1];
-        return value !== undefined;
+    var claimKeys = Object.entries(token).filter(function(param) {
+        var _param = _sliced_to_array$3(param, 2), key = _param[0], value = _param[1];
+        return value !== undefined && key !== 'email' && key !== 'email_verified';
     }).map(function(param) {
         var _param = _sliced_to_array$3(param, 1), key = _param[0];
         return key;
@@ -3644,11 +3640,8 @@ function whoamiToolHandler(ctx, deps) {
     var unknownClaimKeys = [];
     var _iteratorNormalCompletion1 = true, _didIteratorError1 = false, _iteratorError1 = undefined;
     try {
-        for(var _iterator1 = presentKeys[Symbol.iterator](), _step1; !(_iteratorNormalCompletion1 = (_step1 = _iterator1.next()).done); _iteratorNormalCompletion1 = true){
+        for(var _iterator1 = claimKeys[Symbol.iterator](), _step1; !(_iteratorNormalCompletion1 = (_step1 = _iterator1.next()).done); _iteratorNormalCompletion1 = true){
             var key = _step1.value;
-            if (key === 'email' || key === 'email_verified') {
-                continue;
-            }
             var claim1 = claimsByKey.get(key);
             if (claim1 == null) {
                 unknownClaimKeys.push(key);
@@ -3678,22 +3671,30 @@ function whoamiToolHandler(ctx, deps) {
             }
         }
     }
-    var output1 = _object_spread$2({
+    var output = _object_spread$2({
         authenticated: true,
         uid: auth.uid,
-        claims: _object_spread$2({}, token),
         roles: roles,
-        claimDetails: claimDetails,
-        unknownClaimKeys: unknownClaimKeys
+        claimCount: claimKeys.length
     }, ((_deps_auth_app = deps.auth.app) === null || _deps_auth_app === void 0 ? void 0 : _deps_auth_app.app) == null ? {} : {
         app: deps.auth.app.app
     }, token.email == null ? {} : {
         email: token.email
     }, token.email_verified == null ? {} : {
         emailVerified: token.email_verified
-    });
-    var text = renderText(output1);
-    return buildResult(output1, text);
+    }, detail === 'summary' ? {} : {
+        claims: _object_spread$2({}, token)
+    }, detail === 'full' ? {
+        claimDetails: claimDetails,
+        unknownClaimKeys: unknownClaimKeys
+    } : {});
+    var text = renderText(output, detail);
+    return buildResult(output, text);
+}
+// Coerces the `detail` input into a WhoamiDetailLevel, defaulting unknown or absent values to `summary`.
+function parseDetailLevel(args) {
+    var value = args.detail;
+    return value === 'claims' || value === 'full' ? value : 'summary';
 }
 function buildResult(output, text) {
     return {
@@ -3706,34 +3707,51 @@ function buildResult(output, text) {
         structuredContent: output
     };
 }
-function renderText(output) {
+function renderText(output, detail) {
     var lines = [
         '# whoami',
         ''
     ];
     appendHeaderLines(lines, output);
-    appendClaimDetailLines(lines, output.claimDetails);
-    appendUnknownClaimLines(lines, output.unknownClaimKeys);
+    if (detail === 'full') {
+        var _output_claimDetails, _output_unknownClaimKeys;
+        appendClaimDetailLines(lines, (_output_claimDetails = output.claimDetails) !== null && _output_claimDetails !== void 0 ? _output_claimDetails : []);
+        appendUnknownClaimLines(lines, (_output_unknownClaimKeys = output.unknownClaimKeys) !== null && _output_unknownClaimKeys !== void 0 ? _output_unknownClaimKeys : []);
+    }
+    if (detail !== 'summary') {
+        var _output_claims;
+        appendRawClaimsLines(lines, (_output_claims = output.claims) !== null && _output_claims !== void 0 ? _output_claims : {});
+    }
+    appendDetailHint(lines, detail);
     return lines.join('\n');
 }
 function appendHeaderLines(lines, output) {
-    if (output.uid != null) {
-        lines.push("- **uid:** `".concat(output.uid, "`"));
-    }
-    if (output.app != null) {
-        lines.push("- **app:** `".concat(output.app, "`"));
-    }
+    var _output_roles, _output_claimCount;
+    var appPart = output.app == null ? '' : " on `".concat(output.app, "`");
+    lines.push("Authenticated as `".concat(output.uid, "`").concat(appPart, "."), '');
     if (output.email != null) {
-        lines.push("- **email:** `".concat(output.email, "`"));
+        lines.push("- **email:** `".concat(output.email, "`").concat(formatEmailVerified(output.emailVerified)));
     }
-    if (output.roles.length > 0) {
-        var rolesText = output.roles.map(function(role) {
+    var roles = (_output_roles = output.roles) !== null && _output_roles !== void 0 ? _output_roles : [];
+    if (roles.length > 0) {
+        var rolesText = roles.map(function(role) {
             return "`".concat(role, "`");
         }).join(', ');
         lines.push("- **roles:** ".concat(rolesText));
     } else {
         lines.push('- **roles:** _(none)_');
     }
+    lines.push("- **claims:** ".concat((_output_claimCount = output.claimCount) !== null && _output_claimCount !== void 0 ? _output_claimCount : 0, " present"));
+}
+// Renders the parenthetical verification suffix for the email line, or an empty string when the token carries no `email_verified` claim.
+function formatEmailVerified(emailVerified) {
+    if (emailVerified === true) {
+        return ' (verified)';
+    }
+    if (emailVerified === false) {
+        return ' (unverified)';
+    }
+    return '';
 }
 function appendClaimDetailLines(lines, claimDetails) {
     if (claimDetails.length === 0) {
@@ -3795,22 +3813,40 @@ function appendUnknownClaimLines(lines, unknownClaimKeys) {
         }
     }
 }
+// Renders the raw claims object as a fenced JSON block — the one place the tool emits raw JSON, since claims are an arbitrary key → value bag.
+function appendRawClaimsLines(lines, claims) {
+    lines.push('', '## Raw claims', '```json', JSON.stringify(claims, null, 2), '```');
+}
+// Appends a hint pointing at the next, more detailed level. Omitted at `full`, which is already the most detailed level.
+function appendDetailHint(lines, detail) {
+    if (detail === 'summary') {
+        lines.push('', '_Call again with `detail: "claims"` for the raw claim values, or `detail: "full"` for values plus per-claim descriptions._');
+    } else if (detail === 'claims') {
+        lines.push('', '_Call again with `detail: "full"` for per-claim descriptions and unknown claim keys._');
+    }
+}
 // MARK: Schemas
 var WHOAMI_INPUT_SCHEMA = {
     type: 'object',
-    properties: {},
+    properties: {
+        detail: {
+            type: 'string',
+            enum: [
+                'summary',
+                'claims',
+                'full'
+            ],
+            description: 'Level of detail. "summary" (default): identity + decoded roles only. "claims": adds the raw claims object (key → value). "full": adds per-claim descriptions, granted/revoked roles, tags, and unknown claim keys.'
+        }
+    },
     additionalProperties: false
 };
 var WHOAMI_OUTPUT_SCHEMA = {
     type: 'object',
     required: [
-        'authenticated',
-        'claims',
-        'roles',
-        'claimDetails',
-        'unknownClaimKeys'
+        'authenticated'
     ],
-    description: 'Caller identity, raw token claims, decoded role set, and per-claim descriptions for every key present on the live token.',
+    description: 'Caller identity and decoded role set. Claim-bearing fields (claims, claimDetails, unknownClaimKeys) are present only at the detail level that requests them via the `detail` input.',
     properties: {
         authenticated: {
             type: 'boolean'
@@ -3827,16 +3863,19 @@ var WHOAMI_OUTPUT_SCHEMA = {
         app: {
             type: 'string'
         },
-        claims: {
-            type: 'object',
-            additionalProperties: true
-        },
         roles: {
             type: 'array',
             items: {
                 type: 'string'
             }
         },
+        claimCount: {
+            type: 'integer'
+        },
+        claims: {
+            type: 'object',
+            additionalProperties: true
+        },
         claimDetails: {
             type: 'array',
             items: {
@@ -4132,6 +4171,11 @@ function _ts_generator$4(thisArg, body) {
 /**
  * Placeholder segment standing for the caller's authenticated uid.
  */ var AUTH_UID_PLACEHOLDER = '{authUid}';
+/**
+ * Matches a `{flatKey:<param>}` key template, capturing the route param whose
+ * URL value is a whole two-way-flat FirestoreModelKey. Mirror of the build-time
+ * `FLAT_KEY_TOKEN_RE` in `@dereekb/dbx-cli`'s route-model-tag parser.
+ */ var FLAT_KEY_TEMPLATE_RE = RegExp("^\\{flatKey:([a-zA-Z_][a-zA-Z0-9_]*)\\}$", "u");
 // MARK: Factory
 /**
  * Builds the built-in `url-models` MCP tool definition.
@@ -4410,6 +4454,8 @@ function resolveModelEntry(input) {
         result = base;
     } else if (entry.kind === 'id') {
         result = _object_spread$1({}, base, resolveIdKey(input));
+    } else if (entry.kind === 'flatKey') {
+        result = _object_spread$1({}, base, resolveFlatKey(input));
     } else {
         result = _object_spread$1({}, base, resolveFullKey(input));
     }
@@ -4448,6 +4494,57 @@ function resolveIdKey(input) {
     }
     return result;
 }
+function resolveFlatKey(input) {
+    var _entry_keyTemplate;
+    var entry = input.entry, params = input.params;
+    var match = FLAT_KEY_TEMPLATE_RE.exec((_entry_keyTemplate = entry.keyTemplate) !== null && _entry_keyTemplate !== void 0 ? _entry_keyTemplate : '');
+    var result;
+    if (match === null) {
+        var _entry_keyTemplate1;
+        // Defensive: a flatKey entry whose template is not `{flatKey:<param>}` (a malformed manifest).
+        result = {
+            unresolved: {
+                reason: 'invalid-flat-key',
+                message: "Model `".concat(entry.modelType, "` is a flatKey binding but its key template `").concat((_entry_keyTemplate1 = entry.keyTemplate) !== null && _entry_keyTemplate1 !== void 0 ? _entry_keyTemplate1 : '', "` is not `{flatKey:<param>}`.")
+            }
+        };
+    } else {
+        var paramName = match[1];
+        var value = params[paramName];
+        if (value === undefined || value.length === 0) {
+            result = {
+                unresolved: {
+                    reason: 'missing-param',
+                    message: "Route param `:".concat(paramName, "` (the flattened model key) was not captured from the URL.")
+                }
+            };
+        } else {
+            // The param value IS a two-way-flat key (`r_<id>_cs_<id>`); un-flatten it back to `r/<id>/cs/<id>`.
+            var key = firebase.inferKeyFromTwoWayFlatFirestoreModelKey(value);
+            result = isEvenSegmentKey(key) ? {
+                key: key
+            } : {
+                unresolved: {
+                    reason: 'invalid-flat-key',
+                    message: "Route param `:".concat(paramName, "` did not decode to a valid FirestoreModelKey (got `").concat(key, "`).")
+                }
+            };
+        }
+    }
+    return result;
+}
+/**
+ * Whether a decoded key has the shape of a FirestoreModelKey: a non-empty,
+ * even number of `/`-separated segments (collection/id pairs).
+ *
+ * @param key - The decoded (un-flattened) key.
+ * @returns True when the key has an even, non-zero segment count.
+ */ function isEvenSegmentKey(key) {
+    var segments = key.split('/').filter(function(s) {
+        return s.length > 0;
+    });
+    return segments.length >= 2 && segments.length % 2 === 0;
+}
 function resolveFullKey(input) {
     var _entry_keyTemplate;
     var entry = input.entry, params = input.params, uid = input.uid;

package/mcp/index.esm.js

@@ -7,7 +7,7 @@ import { makeValuesGroupMap, performAsyncTasks, authRolesSetHasRoles } from '@de
 import { ModelApiCallModelDispatchService, ModelApiGetService, FirebaseServerStorageService, FirebaseServerEnvService, FirebaseServerAnalyticsService } from '@dereekb/firebase-server';
 import { inspect } from 'node:util';
 import { arktypeToJsonSchemaForExport } from '@dereekb/model';
-import { callModelOidcScopeForCallType } from '@dereekb/firebase';
+import { callModelOidcScopeForCallType, inferKeyFromTwoWayFlatFirestoreModelKey } from '@dereekb/firebase';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 
 function _class_call_check$5(instance, Constructor) {
@@ -485,7 +485,7 @@ function _unsupported_iterable_to_array$9(o, minLen) {
  * Version stamp embedded in `route.manifest.json`. Runtime loaders refuse
  * manifests whose `version` does not match. Mirror in `@dereekb/dbx-cli`'s
  * `ROUTE_MANIFEST_VERSION` — bump both together.
- */ var ROUTE_MANIFEST_VERSION = 1;
+ */ var ROUTE_MANIFEST_VERSION = 2;
 /**
  * Extracts the normalized pathname from a full URL or a bare path. Strips the
  * scheme/host/port, query string, and hash; collapses an empty path to `/` and
@@ -3570,12 +3570,12 @@ function _unsupported_iterable_to_array$5(o, minLen) {
  */ function createWhoamiTool(deps) {
     var _ref;
     var _deps_auth_app;
-    var handler = function handler(_args, ctx) {
-        return Promise.resolve(whoamiToolHandler(ctx, deps));
+    var handler = function handler(args, ctx) {
+        return Promise.resolve(whoamiToolHandler(args, ctx, deps));
     };
     var name = WHOAMI_TOOL_NAME;
     var appLabel = (_ref = (_deps_auth_app = deps.auth.app) === null || _deps_auth_app === void 0 ? void 0 : _deps_auth_app.app) !== null && _ref !== void 0 ? _ref : 'this server';
-    var description = "Reports the authenticated caller's uid, raw custom claims, and decoded role set for `".concat(appLabel, "`. Returns `authenticated: false` for anonymous callers. Claim descriptions are drawn from the build-time auth manifest; only keys actually present on the live token are detailed.");
+    var description = "Reports the authenticated caller's identity and decoded role set for `".concat(appLabel, '`. Returns `authenticated: false` for anonymous callers. Defaults to a concise summary (uid + roles only); pass `detail: "claims"` to also include the raw claims object, or `detail: "full"` to additionally include per-claim descriptions (drawn from the build-time auth manifest) and any unknown claim keys.');
     return buildStaticToolDefinition({
         name: name,
         description: description,
@@ -3591,24 +3591,20 @@ function _unsupported_iterable_to_array$5(o, minLen) {
     });
 }
 // MARK: Handler
-function whoamiToolHandler(ctx, deps) {
+function whoamiToolHandler(args, ctx, deps) {
     var _auth_token;
     var _deps_auth_app;
     var auth = ctx.auth;
     if ((auth === null || auth === void 0 ? void 0 : auth.uid) == null) {
-        var output = {
-            authenticated: false,
-            claims: {},
-            roles: [],
-            claimDetails: [],
-            unknownClaimKeys: []
-        };
-        return buildResult(output, '# whoami\n\nUnauthenticated.');
+        return buildResult({
+            authenticated: false
+        }, '# whoami\n\nNot authenticated (anonymous caller).');
     }
+    var detail = parseDetailLevel(args);
     var token = (_auth_token = auth.token) !== null && _auth_token !== void 0 ? _auth_token : {};
-    var presentKeys = Object.entries(token).filter(function(param) {
-        var _param = _sliced_to_array$3(param, 2), value = _param[1];
-        return value !== undefined;
+    var claimKeys = Object.entries(token).filter(function(param) {
+        var _param = _sliced_to_array$3(param, 2), key = _param[0], value = _param[1];
+        return value !== undefined && key !== 'email' && key !== 'email_verified';
     }).map(function(param) {
         var _param = _sliced_to_array$3(param, 1), key = _param[0];
         return key;
@@ -3642,11 +3638,8 @@ function whoamiToolHandler(ctx, deps) {
     var unknownClaimKeys = [];
     var _iteratorNormalCompletion1 = true, _didIteratorError1 = false, _iteratorError1 = undefined;
     try {
-        for(var _iterator1 = presentKeys[Symbol.iterator](), _step1; !(_iteratorNormalCompletion1 = (_step1 = _iterator1.next()).done); _iteratorNormalCompletion1 = true){
+        for(var _iterator1 = claimKeys[Symbol.iterator](), _step1; !(_iteratorNormalCompletion1 = (_step1 = _iterator1.next()).done); _iteratorNormalCompletion1 = true){
             var key = _step1.value;
-            if (key === 'email' || key === 'email_verified') {
-                continue;
-            }
             var claim1 = claimsByKey.get(key);
             if (claim1 == null) {
                 unknownClaimKeys.push(key);
@@ -3676,22 +3669,30 @@ function whoamiToolHandler(ctx, deps) {
             }
         }
     }
-    var output1 = _object_spread$2({
+    var output = _object_spread$2({
         authenticated: true,
         uid: auth.uid,
-        claims: _object_spread$2({}, token),
         roles: roles,
-        claimDetails: claimDetails,
-        unknownClaimKeys: unknownClaimKeys
+        claimCount: claimKeys.length
     }, ((_deps_auth_app = deps.auth.app) === null || _deps_auth_app === void 0 ? void 0 : _deps_auth_app.app) == null ? {} : {
         app: deps.auth.app.app
     }, token.email == null ? {} : {
         email: token.email
     }, token.email_verified == null ? {} : {
         emailVerified: token.email_verified
-    });
-    var text = renderText(output1);
-    return buildResult(output1, text);
+    }, detail === 'summary' ? {} : {
+        claims: _object_spread$2({}, token)
+    }, detail === 'full' ? {
+        claimDetails: claimDetails,
+        unknownClaimKeys: unknownClaimKeys
+    } : {});
+    var text = renderText(output, detail);
+    return buildResult(output, text);
+}
+// Coerces the `detail` input into a WhoamiDetailLevel, defaulting unknown or absent values to `summary`.
+function parseDetailLevel(args) {
+    var value = args.detail;
+    return value === 'claims' || value === 'full' ? value : 'summary';
 }
 function buildResult(output, text) {
     return {
@@ -3704,34 +3705,51 @@ function buildResult(output, text) {
         structuredContent: output
     };
 }
-function renderText(output) {
+function renderText(output, detail) {
     var lines = [
         '# whoami',
         ''
     ];
     appendHeaderLines(lines, output);
-    appendClaimDetailLines(lines, output.claimDetails);
-    appendUnknownClaimLines(lines, output.unknownClaimKeys);
+    if (detail === 'full') {
+        var _output_claimDetails, _output_unknownClaimKeys;
+        appendClaimDetailLines(lines, (_output_claimDetails = output.claimDetails) !== null && _output_claimDetails !== void 0 ? _output_claimDetails : []);
+        appendUnknownClaimLines(lines, (_output_unknownClaimKeys = output.unknownClaimKeys) !== null && _output_unknownClaimKeys !== void 0 ? _output_unknownClaimKeys : []);
+    }
+    if (detail !== 'summary') {
+        var _output_claims;
+        appendRawClaimsLines(lines, (_output_claims = output.claims) !== null && _output_claims !== void 0 ? _output_claims : {});
+    }
+    appendDetailHint(lines, detail);
     return lines.join('\n');
 }
 function appendHeaderLines(lines, output) {
-    if (output.uid != null) {
-        lines.push("- **uid:** `".concat(output.uid, "`"));
-    }
-    if (output.app != null) {
-        lines.push("- **app:** `".concat(output.app, "`"));
-    }
+    var _output_roles, _output_claimCount;
+    var appPart = output.app == null ? '' : " on `".concat(output.app, "`");
+    lines.push("Authenticated as `".concat(output.uid, "`").concat(appPart, "."), '');
     if (output.email != null) {
-        lines.push("- **email:** `".concat(output.email, "`"));
+        lines.push("- **email:** `".concat(output.email, "`").concat(formatEmailVerified(output.emailVerified)));
     }
-    if (output.roles.length > 0) {
-        var rolesText = output.roles.map(function(role) {
+    var roles = (_output_roles = output.roles) !== null && _output_roles !== void 0 ? _output_roles : [];
+    if (roles.length > 0) {
+        var rolesText = roles.map(function(role) {
             return "`".concat(role, "`");
         }).join(', ');
         lines.push("- **roles:** ".concat(rolesText));
     } else {
         lines.push('- **roles:** _(none)_');
     }
+    lines.push("- **claims:** ".concat((_output_claimCount = output.claimCount) !== null && _output_claimCount !== void 0 ? _output_claimCount : 0, " present"));
+}
+// Renders the parenthetical verification suffix for the email line, or an empty string when the token carries no `email_verified` claim.
+function formatEmailVerified(emailVerified) {
+    if (emailVerified === true) {
+        return ' (verified)';
+    }
+    if (emailVerified === false) {
+        return ' (unverified)';
+    }
+    return '';
 }
 function appendClaimDetailLines(lines, claimDetails) {
     if (claimDetails.length === 0) {
@@ -3793,22 +3811,40 @@ function appendUnknownClaimLines(lines, unknownClaimKeys) {
         }
     }
 }
+// Renders the raw claims object as a fenced JSON block — the one place the tool emits raw JSON, since claims are an arbitrary key → value bag.
+function appendRawClaimsLines(lines, claims) {
+    lines.push('', '## Raw claims', '```json', JSON.stringify(claims, null, 2), '```');
+}
+// Appends a hint pointing at the next, more detailed level. Omitted at `full`, which is already the most detailed level.
+function appendDetailHint(lines, detail) {
+    if (detail === 'summary') {
+        lines.push('', '_Call again with `detail: "claims"` for the raw claim values, or `detail: "full"` for values plus per-claim descriptions._');
+    } else if (detail === 'claims') {
+        lines.push('', '_Call again with `detail: "full"` for per-claim descriptions and unknown claim keys._');
+    }
+}
 // MARK: Schemas
 var WHOAMI_INPUT_SCHEMA = {
     type: 'object',
-    properties: {},
+    properties: {
+        detail: {
+            type: 'string',
+            enum: [
+                'summary',
+                'claims',
+                'full'
+            ],
+            description: 'Level of detail. "summary" (default): identity + decoded roles only. "claims": adds the raw claims object (key → value). "full": adds per-claim descriptions, granted/revoked roles, tags, and unknown claim keys.'
+        }
+    },
     additionalProperties: false
 };
 var WHOAMI_OUTPUT_SCHEMA = {
     type: 'object',
     required: [
-        'authenticated',
-        'claims',
-        'roles',
-        'claimDetails',
-        'unknownClaimKeys'
+        'authenticated'
     ],
-    description: 'Caller identity, raw token claims, decoded role set, and per-claim descriptions for every key present on the live token.',
+    description: 'Caller identity and decoded role set. Claim-bearing fields (claims, claimDetails, unknownClaimKeys) are present only at the detail level that requests them via the `detail` input.',
     properties: {
         authenticated: {
             type: 'boolean'
@@ -3825,16 +3861,19 @@ var WHOAMI_OUTPUT_SCHEMA = {
         app: {
             type: 'string'
         },
-        claims: {
-            type: 'object',
-            additionalProperties: true
-        },
         roles: {
             type: 'array',
             items: {
                 type: 'string'
             }
         },
+        claimCount: {
+            type: 'integer'
+        },
+        claims: {
+            type: 'object',
+            additionalProperties: true
+        },
         claimDetails: {
             type: 'array',
             items: {
@@ -4130,6 +4169,11 @@ function _ts_generator$4(thisArg, body) {
 /**
  * Placeholder segment standing for the caller's authenticated uid.
  */ var AUTH_UID_PLACEHOLDER = '{authUid}';
+/**
+ * Matches a `{flatKey:<param>}` key template, capturing the route param whose
+ * URL value is a whole two-way-flat FirestoreModelKey. Mirror of the build-time
+ * `FLAT_KEY_TOKEN_RE` in `@dereekb/dbx-cli`'s route-model-tag parser.
+ */ var FLAT_KEY_TEMPLATE_RE = RegExp("^\\{flatKey:([a-zA-Z_][a-zA-Z0-9_]*)\\}$", "u");
 // MARK: Factory
 /**
  * Builds the built-in `url-models` MCP tool definition.
@@ -4408,6 +4452,8 @@ function resolveModelEntry(input) {
         result = base;
     } else if (entry.kind === 'id') {
         result = _object_spread$1({}, base, resolveIdKey(input));
+    } else if (entry.kind === 'flatKey') {
+        result = _object_spread$1({}, base, resolveFlatKey(input));
     } else {
         result = _object_spread$1({}, base, resolveFullKey(input));
     }
@@ -4446,6 +4492,57 @@ function resolveIdKey(input) {
     }
     return result;
 }
+function resolveFlatKey(input) {
+    var _entry_keyTemplate;
+    var entry = input.entry, params = input.params;
+    var match = FLAT_KEY_TEMPLATE_RE.exec((_entry_keyTemplate = entry.keyTemplate) !== null && _entry_keyTemplate !== void 0 ? _entry_keyTemplate : '');
+    var result;
+    if (match === null) {
+        var _entry_keyTemplate1;
+        // Defensive: a flatKey entry whose template is not `{flatKey:<param>}` (a malformed manifest).
+        result = {
+            unresolved: {
+                reason: 'invalid-flat-key',
+                message: "Model `".concat(entry.modelType, "` is a flatKey binding but its key template `").concat((_entry_keyTemplate1 = entry.keyTemplate) !== null && _entry_keyTemplate1 !== void 0 ? _entry_keyTemplate1 : '', "` is not `{flatKey:<param>}`.")
+            }
+        };
+    } else {
+        var paramName = match[1];
+        var value = params[paramName];
+        if (value === undefined || value.length === 0) {
+            result = {
+                unresolved: {
+                    reason: 'missing-param',
+                    message: "Route param `:".concat(paramName, "` (the flattened model key) was not captured from the URL.")
+                }
+            };
+        } else {
+            // The param value IS a two-way-flat key (`r_<id>_cs_<id>`); un-flatten it back to `r/<id>/cs/<id>`.
+            var key = inferKeyFromTwoWayFlatFirestoreModelKey(value);
+            result = isEvenSegmentKey(key) ? {
+                key: key
+            } : {
+                unresolved: {
+                    reason: 'invalid-flat-key',
+                    message: "Route param `:".concat(paramName, "` did not decode to a valid FirestoreModelKey (got `").concat(key, "`).")
+                }
+            };
+        }
+    }
+    return result;
+}
+/**
+ * Whether a decoded key has the shape of a FirestoreModelKey: a non-empty,
+ * even number of `/`-separated segments (collection/id pairs).
+ *
+ * @param key - The decoded (un-flattened) key.
+ * @returns True when the key has an even, non-zero segment count.
+ */ function isEvenSegmentKey(key) {
+    var segments = key.split('/').filter(function(s) {
+        return s.length > 0;
+    });
+    return segments.length >= 2 && segments.length % 2 === 0;
+}
 function resolveFullKey(input) {
     var _entry_keyTemplate;
     var entry = input.entry, params = input.params, uid = input.uid;

package/mcp/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@dereekb/firebase-server/mcp",
-  "version": "13.18.0",
+  "version": "13.20.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.18.0",
-    "@dereekb/date": "13.18.0",
-    "@dereekb/firebase": "13.18.0",
-    "@dereekb/firebase-server": "13.18.0",
-    "@dereekb/firebase-server/oidc": "13.18.0",
-    "@dereekb/model": "13.18.0",
-    "@dereekb/nestjs": "13.18.0",
-    "@dereekb/rxjs": "13.18.0",
-    "@dereekb/util": "13.18.0",
-    "@dereekb/zoho": "13.18.0",
+    "@dereekb/analytics": "13.20.0",
+    "@dereekb/date": "13.20.0",
+    "@dereekb/firebase": "13.20.0",
+    "@dereekb/firebase-server": "13.20.0",
+    "@dereekb/firebase-server/oidc": "13.20.0",
+    "@dereekb/model": "13.20.0",
+    "@dereekb/nestjs": "13.20.0",
+    "@dereekb/rxjs": "13.20.0",
+    "@dereekb/util": "13.20.0",
+    "@dereekb/zoho": "13.20.0",
     "@modelcontextprotocol/sdk": "1.29.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/core": "^11.1.19",

package/mcp/src/index.d.ts

@@ -1 +1,19 @@
+/**
+ * Public entry for `@dereekb/firebase-server/mcp`.
+ *
+ * Packaging note: the published `exports["./mcp"]` maps the `import` condition to
+ * the real ESM build (`./mcp/index.esm.js`), NOT the `.cjs.mjs` CJS re-export
+ * shim, so a downstream `import { matchRouteManifestUrl, ROUTE_MANIFEST_VERSION }
+ * from '@dereekb/firebase-server/mcp'` exposes statically-analyzable named
+ * exports under vitest. The shim (`export * from './index.cjs.js'`) resolved to
+ * `undefined` for this subpath under vitest's externalized SSR resolution, while
+ * plain Node and the root `@dereekb/firebase-server` entry were unaffected.
+ * `require` / the `default` condition still resolves to the CJS build for CJS
+ * consumers (the NestJS server runtime).
+ *
+ * Fallback: if a downstream still sees undefined named imports (e.g. consuming a
+ * build that predates this fix), inline the package in its vitest config so Vite
+ * transforms it through the `module` (ESM) condition:
+ * `test: { server: { deps: { inline: [/@dereekb\/firebase-server/] } } }`.
+ */
 export * from './lib';

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

@@ -12,12 +12,13 @@
  * manifests whose `version` does not match. Mirror in `@dereekb/dbx-cli`'s
  * `ROUTE_MANIFEST_VERSION` — bump both together.
  */
-export declare const ROUTE_MANIFEST_VERSION: 1;
+export declare const ROUTE_MANIFEST_VERSION: 2;
 /**
- * Whether a route-model entry resolves to a promoted id, a full key, or a
- * keyless list. Mirror of `@dereekb/dbx-cli`'s `RouteModelKind`.
+ * Whether a route-model entry resolves to a promoted id, a full key, a
+ * single-param flattened key, or a keyless list. Mirror of `@dereekb/dbx-cli`'s
+ * `RouteModelKind`.
  */
-export type RouteModelKind = 'id' | 'key' | 'list';
+export type RouteModelKind = 'id' | 'key' | 'flatKey' | 'list';
 /**
  * One model an app page renders. Structural mirror of `@dereekb/dbx-cli`'s
  * `RouteManifestModelEntry`.

package/mcp/src/lib/service/tools/mcp.tool.url-models.d.ts

@@ -19,7 +19,7 @@ export declare const URL_MODELS_DISPATCH_MODEL_TYPE = "route";
 /**
  * Why a model binding could not be resolved into a concrete key.
  */
-export type UrlModelUnresolvedReason = 'missing-param' | 'subcollection-requires-key-template' | 'unknown-model-type' | 'auth-required';
+export type UrlModelUnresolvedReason = 'missing-param' | 'subcollection-requires-key-template' | 'unknown-model-type' | 'auth-required' | 'invalid-flat-key';
 /**
  * One resolved model binding for a matched page.
  */

package/mcp/src/lib/service/tools/mcp.tool.whoami.d.ts

@@ -45,7 +45,17 @@ export interface WhoamiClaimDetail {
     readonly tags: readonly string[];
 }
 /**
- * Output payload for the `whoami` tool.
+ * Requested verbosity for the `whoami` tool, set via the `detail` input.
+ *
+ * - `summary` (default) — identity + decoded roles + a claim count. No claims.
+ * - `claims` — adds the raw claims object (key → value).
+ * - `full` — adds per-claim descriptions, granted/revoked roles, tags, and unknown claim keys.
+ */
+export type WhoamiDetailLevel = 'summary' | 'claims' | 'full';
+/**
+ * Output payload for the `whoami` tool. The claim-bearing fields are populated
+ * only at the detail level that requests them, so the structured payload scales
+ * with the `detail` input the same way the rendered text does.
  */
 export interface WhoamiToolOutput {
     readonly authenticated: boolean;
@@ -53,10 +63,30 @@ export interface WhoamiToolOutput {
     readonly email?: string;
     readonly emailVerified?: boolean;
     readonly app?: string;
-    readonly claims: Readonly<Record<string, unknown>>;
-    readonly roles: readonly string[];
-    readonly claimDetails: readonly WhoamiClaimDetail[];
-    readonly unknownClaimKeys: readonly string[];
+    /**
+     * Decoded role set. Present for authenticated callers (empty when no role
+     * reader is configured); omitted for anonymous callers.
+     */
+    readonly roles?: readonly string[];
+    /**
+     * Count of custom claim keys present on the live token, excluding the reserved
+     * `email` / `email_verified` keys. Present for authenticated callers.
+     */
+    readonly claimCount?: number;
+    /**
+     * Raw claims object copied from the live token. Included when `detail` is
+     * `claims` or `full`.
+     */
+    readonly claims?: Readonly<Record<string, unknown>>;
+    /**
+     * Per-claim descriptions for every manifest-known key present on the token.
+     * Included when `detail` is `full`.
+     */
+    readonly claimDetails?: readonly WhoamiClaimDetail[];
+    /**
+     * Token claim keys with no matching manifest entry. Included when `detail` is `full`.
+     */
+    readonly unknownClaimKeys?: readonly string[];
 }
 /**
  * Builds the built-in `whoami` MCP tool definition. Returns the calling

package/model/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@dereekb/firebase-server/model",
-  "version": "13.18.0",
+  "version": "13.20.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.18.0",
-    "@dereekb/date": "13.18.0",
-    "@dereekb/firebase": "13.18.0",
-    "@dereekb/firebase-server": "13.18.0",
-    "@dereekb/model": "13.18.0",
-    "@dereekb/nestjs": "13.18.0",
-    "@dereekb/rxjs": "13.18.0",
-    "@dereekb/util": "13.18.0",
+    "@dereekb/analytics": "13.20.0",
+    "@dereekb/date": "13.20.0",
+    "@dereekb/firebase": "13.20.0",
+    "@dereekb/firebase-server": "13.20.0",
+    "@dereekb/model": "13.20.0",
+    "@dereekb/nestjs": "13.20.0",
+    "@dereekb/rxjs": "13.20.0",
+    "@dereekb/util": "13.20.0",
     "@nestjs/common": "^11.1.19",
     "@nestjs/config": "^4.0.4",
     "archiver": "^7.0.1",
@@ -17,7 +17,7 @@
     "firebase-functions": "^7.2.5",
     "make-error": "^1.3.6",
     "@cantoo/pdf-lib": "^2.6.5",
-    "sharp": "0.34.5"
+    "sharp": "0.35.2"
   },
   "exports": {
     "./package.json": "./package.json",

package/oidc/package.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase-server",
-  "version": "13.18.0",
+  "version": "13.20.0",
   "sideEffects": false,
   "exports": {
     "./test": {
@@ -42,7 +42,7 @@
     "./mcp": {
       "module": "./mcp/index.esm.js",
       "types": "./mcp/index.d.ts",
-      "import": "./mcp/index.cjs.mjs",
+      "import": "./mcp/index.esm.js",
       "default": "./mcp/index.cjs.js"
     },
     "./package.json": "./package.json",
@@ -57,15 +57,15 @@
   "types": "./src/index.d.ts",
   "peerDependencies": {
     "@cantoo/pdf-lib": "^2.6.5",
-    "@dereekb/analytics": "13.18.0",
-    "@dereekb/date": "13.18.0",
-    "@dereekb/dbx-core": "13.18.0",
-    "@dereekb/firebase": "13.18.0",
-    "@dereekb/model": "13.18.0",
-    "@dereekb/nestjs": "13.18.0",
-    "@dereekb/rxjs": "13.18.0",
-    "@dereekb/util": "13.18.0",
-    "@dereekb/zoho": "13.18.0",
+    "@dereekb/analytics": "13.20.0",
+    "@dereekb/date": "13.20.0",
+    "@dereekb/dbx-core": "13.20.0",
+    "@dereekb/firebase": "13.20.0",
+    "@dereekb/model": "13.20.0",
+    "@dereekb/nestjs": "13.20.0",
+    "@dereekb/rxjs": "13.20.0",
+    "@dereekb/util": "13.20.0",
+    "@dereekb/zoho": "13.20.0",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.19.0",
     "@modelcontextprotocol/sdk": "1.29.0",
@@ -86,7 +86,7 @@
     "nanoid": "^5.1.9",
     "oidc-provider": "^9.8.2",
     "rxjs": "^7.8.2",
-    "sharp": "0.34.5",
+    "sharp": "0.35.2",
     "supertest": "^7.2.2",
     "ts-essentials": "^10.2.0"
   },

package/test/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/firebase-server/test",
-  "version": "13.18.0",
+  "version": "13.20.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.18.0",
-    "@dereekb/date": "13.18.0",
-    "@dereekb/firebase": "13.18.0",
-    "@dereekb/firebase-server": "13.18.0",
-    "@dereekb/firebase-server/oidc": "13.18.0",
-    "@dereekb/model": "13.18.0",
-    "@dereekb/nestjs": "13.18.0",
-    "@dereekb/rxjs": "13.18.0",
-    "@dereekb/util": "13.18.0",
+    "@dereekb/analytics": "13.20.0",
+    "@dereekb/date": "13.20.0",
+    "@dereekb/firebase": "13.20.0",
+    "@dereekb/firebase-server": "13.20.0",
+    "@dereekb/firebase-server/oidc": "13.20.0",
+    "@dereekb/model": "13.20.0",
+    "@dereekb/nestjs": "13.20.0",
+    "@dereekb/rxjs": "13.20.0",
+    "@dereekb/util": "13.20.0",
     "@google-cloud/firestore": "^7.11.6",
     "@google-cloud/storage": "^7.19.0",
     "@nestjs/common": "^11.1.19",
@@ -23,7 +23,7 @@
     "supertest": "^7.2.2"
   },
   "devDependencies": {
-    "@dereekb/nestjs": "13.18.0"
+    "@dereekb/nestjs": "13.20.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/twilio/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@dereekb/firebase-server/twilio",
-  "version": "13.18.0",
+  "version": "13.20.0",
   "peerDependencies": {
-    "@dereekb/date": "13.18.0",
-    "@dereekb/firebase": "13.18.0",
-    "@dereekb/firebase-server": "13.18.0",
-    "@dereekb/model": "13.18.0",
-    "@dereekb/nestjs": "13.18.0",
-    "@dereekb/rxjs": "13.18.0",
-    "@dereekb/util": "13.18.0"
+    "@dereekb/date": "13.20.0",
+    "@dereekb/firebase": "13.20.0",
+    "@dereekb/firebase-server": "13.20.0",
+    "@dereekb/model": "13.20.0",
+    "@dereekb/nestjs": "13.20.0",
+    "@dereekb/rxjs": "13.20.0",
+    "@dereekb/util": "13.20.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/zoho/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@dereekb/firebase-server/zoho",
-  "version": "13.18.0",
+  "version": "13.20.0",
   "peerDependencies": {
-    "@dereekb/analytics": "13.18.0",
-    "@dereekb/date": "13.18.0",
-    "@dereekb/model": "13.18.0",
-    "@dereekb/nestjs": "13.18.0",
-    "@dereekb/rxjs": "13.18.0",
-    "@dereekb/firebase": "13.18.0",
-    "@dereekb/util": "13.18.0",
-    "@dereekb/zoho": "13.18.0"
+    "@dereekb/analytics": "13.20.0",
+    "@dereekb/date": "13.20.0",
+    "@dereekb/model": "13.20.0",
+    "@dereekb/nestjs": "13.20.0",
+    "@dereekb/rxjs": "13.20.0",
+    "@dereekb/firebase": "13.20.0",
+    "@dereekb/util": "13.20.0",
+    "@dereekb/zoho": "13.20.0"
   },
   "exports": {
     "./package.json": "./package.json",