@learncard/lca-api-service 1.4.0 → 1.5.0

package/scripts/escrow-blob-mode-report.test.ts

@@ -0,0 +1,227 @@
+import { describe, expect, it, vi } from 'vitest';
+
+// Pure-logic test only: the script module (and, transitively, src/models/UserKey.ts)
+// imports the real Mongo connection module for the CLI's live-query path, which
+// requires a real Mongo global outside test-mode integration setup. Stub it so
+// importing the module here never needs one — same pattern as
+// src/models/UserKey.escrowPin.test.ts, but by relative path: `scripts/` sits
+// outside this package's tsconfig `include`, so path-alias mocks (`@mongo`)
+// resolved from here don't reliably match the alias-resolved import inside
+// src/models/UserKey.ts, even though both point at the same file.
+vi.mock('../src/mongo', () => ({ default: {} }));
+
+import {
+    buildCloudWatchMetricPayload,
+    buildReport,
+    activeModeFromEnv,
+    classifyEnclaveKeyIds,
+    CLOUDWATCH_NAMESPACE,
+    type RawEscrowCounts,
+} from './escrow-blob-mode-report';
+
+const emptyRaw: RawEscrowCounts = {
+    totalUserKeys: 0,
+    enclaveModeCounts: [],
+    enclaveKeyIdCounts: [],
+    escrowPinEnabledCount: 0,
+    optedOutCount: 0,
+    pendingHoldsByPolicy: [],
+};
+
+describe('activeModeFromEnv', () => {
+    it('maps remote to nitro', () => {
+        expect(activeModeFromEnv('remote')).toBe('nitro');
+    });
+
+    it('maps software, undefined, and anything else to software', () => {
+        expect(activeModeFromEnv('software')).toBe('software');
+        expect(activeModeFromEnv(undefined)).toBe('software');
+        expect(activeModeFromEnv('bogus')).toBe('software');
+    });
+});
+
+describe('buildReport', () => {
+    const now = new Date('2026-09-25T00:00:00.000Z');
+
+    it('reports zero counts for known modes/policies with no data', () => {
+        const report = buildReport(emptyRaw, 'nitro', now);
+
+        expect(report.generatedAt).toBe(now.toISOString());
+        expect(report.activeEnclaveMode).toBe('nitro');
+        expect(report.byEnclaveMode).toEqual({ software: 0, nitro: 0 });
+        expect(report.pendingHoldsByReleasePolicy).toEqual({ hold: 0, pin: 0 });
+        expect(report.totals).toEqual({
+            userKeys: 0,
+            escrowBlobs: 0,
+            escrowPinEnabled: 0,
+            optedOut: 0,
+            pendingHolds: 0,
+        });
+        expect(report.reseal).toEqual({ activeCount: 0, staleCount: 0, staleRatePercent: 0 });
+    });
+
+    it('computes the re-seal split for a normal software/nitro mix', () => {
+        const raw: RawEscrowCounts = {
+            ...emptyRaw,
+            totalUserKeys: 20,
+            enclaveModeCounts: [
+                { mode: 'software', count: 7 },
+                { mode: 'nitro', count: 3 },
+            ],
+            escrowPinEnabledCount: 2,
+            optedOutCount: 1,
+        };
+
+        const report = buildReport(raw, 'nitro', now);
+
+        expect(report.byEnclaveMode).toEqual({ software: 7, nitro: 3 });
+        expect(report.totals.escrowBlobs).toBe(10);
+        expect(report.reseal).toEqual({ activeCount: 3, staleCount: 7, staleRatePercent: 70 });
+    });
+
+    it('surfaces an unknown enclaveMode value instead of dropping it, and counts it as stale', () => {
+        const raw: RawEscrowCounts = {
+            ...emptyRaw,
+            enclaveModeCounts: [
+                { mode: 'software', count: 1 },
+                { mode: 'nitro', count: 1 },
+                { mode: 'legacy-v0', count: 2 },
+            ],
+        };
+
+        const report = buildReport(raw, 'nitro', now);
+
+        expect(report.byEnclaveMode).toEqual({ software: 1, nitro: 1, 'legacy-v0': 2 });
+        expect(report.totals.escrowBlobs).toBe(4);
+        // activeCount only counts the active mode bucket; the unknown mode is stale too.
+        expect(report.reseal).toEqual({ activeCount: 1, staleCount: 3, staleRatePercent: 75 });
+    });
+
+    it('rounds the stale rate to 2 decimal places', () => {
+        const raw: RawEscrowCounts = {
+            ...emptyRaw,
+            enclaveModeCounts: [
+                { mode: 'software', count: 1 },
+                { mode: 'nitro', count: 2 },
+            ],
+        };
+
+        const report = buildReport(raw, 'nitro', now);
+
+        // stale = 1, total = 3 -> 33.333...% rounds to 33.33
+        expect(report.reseal.staleRatePercent).toBe(33.33);
+    });
+
+    it('passes through enclaveKeyId counts and an unknown release policy value', () => {
+        const raw: RawEscrowCounts = {
+            ...emptyRaw,
+            enclaveKeyIdCounts: [
+                { keyId: 'key-a', count: 4 },
+                { keyId: 'key-b', count: 1 },
+            ],
+            pendingHoldsByPolicy: [
+                { policy: 'hold', count: 3 },
+                { policy: 'weird-future-policy', count: 1 },
+            ],
+        };
+
+        const report = buildReport(raw, 'software', now);
+
+        expect(report.byEnclaveKeyId).toEqual({ 'key-a': 4, 'key-b': 1 });
+        expect(report.pendingHoldsByReleasePolicy).toEqual({
+            hold: 3,
+            pin: 0,
+            'weird-future-policy': 1,
+        });
+        expect(report.totals.pendingHolds).toBe(4);
+    });
+});
+
+describe('buildCloudWatchMetricPayload', () => {
+    it('emits EscrowBlobs per mode dimension plus a single EscrowBlobsStale datum', () => {
+        const report = buildReport(
+            {
+                ...emptyRaw,
+                enclaveModeCounts: [
+                    { mode: 'software', count: 5 },
+                    { mode: 'nitro', count: 2 },
+                ],
+            },
+            'nitro',
+            new Date('2026-09-25T00:00:00.000Z')
+        );
+
+        const payload = buildCloudWatchMetricPayload(report);
+
+        expect(payload.Namespace).toBe(CLOUDWATCH_NAMESPACE);
+        expect(payload.MetricData).toHaveLength(3);
+        expect(payload.MetricData).toEqual(
+            expect.arrayContaining([
+                {
+                    MetricName: 'EscrowBlobs',
+                    Value: 5,
+                    Unit: 'Count',
+                    Timestamp: report.generatedAt,
+                    Dimensions: [{ Name: 'EnclaveMode', Value: 'software' }],
+                },
+                {
+                    MetricName: 'EscrowBlobs',
+                    Value: 2,
+                    Unit: 'Count',
+                    Timestamp: report.generatedAt,
+                    Dimensions: [{ Name: 'EnclaveMode', Value: 'nitro' }],
+                },
+                {
+                    MetricName: 'EscrowBlobsStale',
+                    Value: 5,
+                    Unit: 'Count',
+                    Timestamp: report.generatedAt,
+                },
+            ])
+        );
+    });
+
+    it('still emits a zero-value EscrowBlobsStale datum when there is no data at all', () => {
+        const report = buildReport(emptyRaw, 'software', new Date('2026-09-25T00:00:00.000Z'));
+
+        const payload = buildCloudWatchMetricPayload(report);
+
+        const stale = payload.MetricData.find(datum => datum.MetricName === 'EscrowBlobsStale');
+        expect(stale?.Value).toBe(0);
+    });
+});
+
+describe('classifyEnclaveKeyIds (P9.3)', () => {
+    it('splits counts into current/previous/unknown, listing unknown keyIds sorted', () => {
+        const classification = classifyEnclaveKeyIds(
+            { 'key-2': 10, 'key-1': 4, 'key-0': 1, unknown: 1 },
+            'key-2',
+            ['key-1', 'key-0']
+        );
+
+        expect(classification).toEqual({
+            current: 10,
+            previous: 5,
+            unknown: 1,
+            unknownKeyIds: ['unknown'],
+        });
+    });
+
+    it('reports zero previous/unknown when every blob is already on the current key', () => {
+        const classification = classifyEnclaveKeyIds({ 'key-2': 3 }, 'key-2', ['key-1']);
+
+        expect(classification).toEqual({ current: 3, previous: 0, unknown: 0, unknownKeyIds: [] });
+    });
+
+    it('treats an empty previous-key list as everything non-current being unknown', () => {
+        const classification = classifyEnclaveKeyIds(
+            { 'key-2': 2, 'retired-1': 1, 'retired-2': 1 },
+            'key-2',
+            []
+        );
+
+        expect(classification.previous).toBe(0);
+        expect(classification.unknown).toBe(2);
+        expect(classification.unknownKeyIds).toEqual(['retired-1', 'retired-2']);
+    });
+});

package/scripts/escrow-blob-mode-report.ts

@@ -0,0 +1,465 @@
+#!/usr/bin/env bun
+/**
+ * P6.2 — Escrow blob mode report.
+ *
+ * Read-only report over the `userkeys` and `escrowholds` collections:
+ *   - escrow blob counts grouped by `escrowBlob.enclaveMode` and `escrowBlob.enclaveKeyId`
+ *   - count of users with an enabled `escrowPin` (present, not disabled, matching the
+ *     current `shareVersion` — same definition as `getEscrowPinStatus` in
+ *     `src/models/UserKey.ts`)
+ *   - pending `EscrowHold` counts grouped by `releasePolicy`
+ *   - count of users who have opted out of escrow (`escrowOptedOutAt` set)
+ *   - a "re-seal" breakdown: how many escrow blobs are sealed for the currently
+ *     configured active enclave mode vs. a different ("stale") one
+ *
+ * This script NEVER writes to the database and NEVER prints PII — no DIDs,
+ * emails, contact methods, or Mongo `_id`s, only counts.
+ *
+ * Usage:
+ *   bun scripts/escrow-blob-mode-report.ts [--json] [--publish-metrics]
+ *       [--current-key-id=<id>] [--previous-key-ids=<id1,id2,...>]
+ *
+ * Flags:
+ *   --json              Print a single JSON object instead of a human-readable table.
+ *   --publish-metrics   Print the CloudWatch `PutMetricData` payload (namespace
+ *                        `LearnCard/Escrow`, metrics `EscrowBlobs` dimensioned by
+ *                        `EnclaveMode` and `EscrowBlobsStale`) that a caller with AWS
+ *                        SDK access should forward to CloudWatch.
+ *   --current-key-id=<id>          (P9.3) Classifies `byEnclaveKeyId` into
+ *                                    current/previous/unknown buckets — how many
+ *                                    escrow blob copies remain under each previous
+ *                                    key, ready for the escrowBlobRewrap job/runbook.
+ *   --previous-key-ids=<a,b,c>      Required together with --current-key-id.
+ *
+ *   This script deliberately makes NO live enclave call (see "Known limitations"
+ *   below), so it cannot discover the current/previous key IDs itself — fetch
+ *   them once from `GET /keys/escrow/attestation` (`keyId`/`previousKeyIds`) and
+ *   pass them in explicitly:
+ *
+ *     bun scripts/escrow-blob-mode-report.ts --current-key-id=key-2 \
+ *       --previous-key-ids=key-1
+ *
+ *   Without these two flags, `byEnclaveKeyId` is still printed/returned as
+ *   before; only the extra classification section is omitted — compare it
+ *   manually against the enclave's own attestation response.
+ *
+ *                        lca-api does not depend on `@aws-sdk/client-cloudwatch`
+ *                        (only `services/learn-card-network/ai-agent` does in this
+ *                        monorepo), so this script does not publish metrics itself —
+ *                        see "CloudWatch metric emission" below.
+ *
+ * Environment:
+ *   Same as the lca-api server: `SEED`, `MONGO_URI`, `MONGO_DB_NAME` (see
+ *   `.env.example`). `SEED` is required by environment parsing even though this
+ *   script never uses it. Point `MONGO_URI` at the environment you want to report
+ *   on (e.g. a staging replica) before running.
+ *
+ * CloudWatch metric emission:
+ *   `--publish-metrics` never imports or requires an AWS SDK. It only prints the
+ *   exact `MetricData` payload. Forward it with the P7.1 monitor Lambda (which
+ *   already carries AWS SDK access) or any ops job that does, e.g.:
+ *
+ *     bun scripts/escrow-blob-mode-report.ts --json --publish-metrics \
+ *       | jq .metricsPayload \
+ *       | <your-cloudwatch-forwarder>
+ *
+ * Known limitations:
+ *   - "Stale" here means `escrowBlob.enclaveMode` does not match the currently
+ *     configured active mode (`ESCROW_ENCLAVE_MODE=remote` → `nitro`, otherwise
+ *     `software`) — the same comparison `assertFreshEscrowBlob` makes in
+ *     `src/routes/escrow.ts`. It does NOT detect `enclaveKeyId` (measurement)
+ *     rotation staleness, because that requires a live call to the enclave's
+ *     attestation endpoint (`getEscrowBlobStaleReason` in
+ *     `src/services/escrow-enclave/index.ts`), which this offline counts report
+ *     deliberately avoids depending on.
+ *   - `UserKey` has no tenant field, so a per-tenant breakdown of escrow blobs is
+ *     not possible and is intentionally not reported (see `byEnclaveMode` /
+ *     `byEnclaveKeyId` instead). `EscrowHold` does carry an optional `tenantId`,
+ *     but it was added after most holds existed and is not present on every
+ *     document, so it isn't reported here either — a "tenant breakdown" would
+ *     misleadingly undercount if only holds happened to be tenant-tagged.
+ */
+
+import type { Collection } from 'mongodb';
+
+import { getUserKeysCollection, type MongoUserKeyType } from '../src/models/UserKey';
+import { getEscrowHoldsCollection, type EscrowHold } from '../src/models/EscrowHold';
+import { environment } from '../src/config/environment';
+import { client as mongoClient } from '../src/mongo';
+
+export type ActiveEnclaveMode = 'software' | 'nitro';
+
+const KNOWN_ENCLAVE_MODES: readonly ActiveEnclaveMode[] = ['software', 'nitro'];
+const KNOWN_RELEASE_POLICIES: readonly EscrowHold['releasePolicy'][] = ['hold', 'pin'];
+
+/** Mirrors `activeEscrowClientMode()` in `src/services/escrow-enclave/index.ts`,
+ * re-derived directly from the env var so this script has no import-time
+ * dependency on that module (which is mid-edit as part of this same plan). */
+export const activeModeFromEnv = (mode: string | undefined): ActiveEnclaveMode =>
+    mode === 'remote' ? 'nitro' : 'software';
+
+export interface RawEscrowCounts {
+    totalUserKeys: number;
+    enclaveModeCounts: { mode: string; count: number }[];
+    enclaveKeyIdCounts: { keyId: string; count: number }[];
+    escrowPinEnabledCount: number;
+    optedOutCount: number;
+    pendingHoldsByPolicy: { policy: string; count: number }[];
+}
+
+export interface EscrowBlobModeReport {
+    generatedAt: string;
+    activeEnclaveMode: ActiveEnclaveMode;
+    totals: {
+        userKeys: number;
+        escrowBlobs: number;
+        escrowPinEnabled: number;
+        optedOut: number;
+        pendingHolds: number;
+    };
+    byEnclaveMode: Record<string, number>;
+    byEnclaveKeyId: Record<string, number>;
+    pendingHoldsByReleasePolicy: Record<string, number>;
+    reseal: {
+        activeCount: number;
+        staleCount: number;
+        /** Rounded to 2 decimal places; 0 when there are no escrow blobs at all. */
+        staleRatePercent: number;
+    };
+}
+
+/**
+ * Pure formatting/aggregation-shaping logic — no Mongo access. Takes the raw
+ * per-bucket counts from `queryEscrowCounts` and produces the final report,
+ * filling in zero counts for known enclave modes / release policies that had
+ * no matching documents, while still surfacing any unexpected ("unknown")
+ * values verbatim rather than silently dropping them.
+ */
+export const buildReport = (
+    raw: RawEscrowCounts,
+    activeEnclaveMode: ActiveEnclaveMode,
+    now: Date = new Date()
+): EscrowBlobModeReport => {
+    const byEnclaveMode: Record<string, number> = Object.fromEntries(
+        KNOWN_ENCLAVE_MODES.map(mode => [mode, 0])
+    );
+    for (const { mode, count } of raw.enclaveModeCounts) {
+        byEnclaveMode[mode] = (byEnclaveMode[mode] ?? 0) + count;
+    }
+
+    const byEnclaveKeyId: Record<string, number> = {};
+    for (const { keyId, count } of raw.enclaveKeyIdCounts) {
+        byEnclaveKeyId[keyId] = (byEnclaveKeyId[keyId] ?? 0) + count;
+    }
+
+    const pendingHoldsByReleasePolicy: Record<string, number> = Object.fromEntries(
+        KNOWN_RELEASE_POLICIES.map(policy => [policy, 0])
+    );
+    for (const { policy, count } of raw.pendingHoldsByPolicy) {
+        pendingHoldsByReleasePolicy[policy] = (pendingHoldsByReleasePolicy[policy] ?? 0) + count;
+    }
+
+    const escrowBlobs = Object.values(byEnclaveMode).reduce((sum, count) => sum + count, 0);
+    const activeCount = byEnclaveMode[activeEnclaveMode] ?? 0;
+    const staleCount = escrowBlobs - activeCount;
+    const staleRatePercent =
+        escrowBlobs === 0 ? 0 : Math.round((staleCount / escrowBlobs) * 10_000) / 100;
+    const pendingHolds = Object.values(pendingHoldsByReleasePolicy).reduce(
+        (sum, count) => sum + count,
+        0
+    );
+
+    return {
+        generatedAt: now.toISOString(),
+        activeEnclaveMode,
+        totals: {
+            userKeys: raw.totalUserKeys,
+            escrowBlobs,
+            escrowPinEnabled: raw.escrowPinEnabledCount,
+            optedOut: raw.optedOutCount,
+            pendingHolds,
+        },
+        byEnclaveMode,
+        byEnclaveKeyId,
+        pendingHoldsByReleasePolicy,
+        reseal: { activeCount, staleCount, staleRatePercent },
+    };
+};
+
+export interface CloudWatchMetricDatum {
+    MetricName: 'EscrowBlobs' | 'EscrowBlobsStale';
+    Value: number;
+    Unit: 'Count';
+    /** ISO-8601. The forwarder should parse this into whatever `Date`/timestamp
+     * shape its AWS SDK client expects — kept as a string here so this module
+     * has zero AWS SDK type dependency. */
+    Timestamp: string;
+    Dimensions?: { Name: 'EnclaveMode'; Value: string }[];
+}
+
+export interface CloudWatchMetricPayload {
+    Namespace: string;
+    MetricData: CloudWatchMetricDatum[];
+}
+
+export const CLOUDWATCH_NAMESPACE = 'LearnCard/Escrow';
+
+export interface EnclaveKeyIdClassification {
+    current: number;
+    previous: number;
+    unknown: number;
+    /** Sorted for stable output; empty when every counted keyId is current or previous. */
+    unknownKeyIds: string[];
+}
+
+/**
+ * Pure: classifies `byEnclaveKeyId` counts against an explicitly-provided
+ * current/previous key list (see script header "P9.3" flags — this script
+ * makes no live enclave call, so it cannot discover these itself). "Unknown"
+ * means neither current nor previous: a truly retired/lost key, never a
+ * candidate for `escrowBlobRewrap`, which only ever asks the enclave about
+ * keyIds in its OWN attestation's `previousKeyIds`.
+ */
+export const classifyEnclaveKeyIds = (
+    byEnclaveKeyId: Record<string, number>,
+    currentKeyId: string,
+    previousKeyIds: string[]
+): EnclaveKeyIdClassification => {
+    const previousSet = new Set(previousKeyIds);
+    let current = 0;
+    let previous = 0;
+    let unknown = 0;
+    const unknownKeyIds: string[] = [];
+    for (const [keyId, count] of Object.entries(byEnclaveKeyId)) {
+        if (keyId === currentKeyId) current += count;
+        else if (previousSet.has(keyId)) previous += count;
+        else {
+            unknown += count;
+            unknownKeyIds.push(keyId);
+        }
+    }
+    return { current, previous, unknown, unknownKeyIds: unknownKeyIds.sort() };
+};
+
+export const formatKeyIdClassification = (
+    classification: EnclaveKeyIdClassification,
+    currentKeyId: string,
+    previousKeyIds: string[]
+): string => {
+    const lines: string[] = [];
+    lines.push('');
+    lines.push(
+        `Enclave key classification (current=${currentKeyId}, previous=[${previousKeyIds.join(', ')}]):`
+    );
+    lines.push(`  Current:  ${classification.current}`);
+    lines.push(`  Previous: ${classification.previous}  (candidates for escrowBlobRewrap)`);
+    lines.push(
+        `  Unknown:  ${classification.unknown}` +
+            (classification.unknownKeyIds.length
+                ? ` [${classification.unknownKeyIds.join(', ')}] — retired/lost keys, never rewrapped`
+                : '')
+    );
+    return lines.join('\n');
+};
+
+/** Pure: shapes a report into a CloudWatch `PutMetricData` payload. Never
+ * imports an AWS SDK — see the script header's "CloudWatch metric emission". */
+export const buildCloudWatchMetricPayload = (
+    report: EscrowBlobModeReport
+): CloudWatchMetricPayload => {
+    const timestamp = report.generatedAt;
+    const MetricData: CloudWatchMetricDatum[] = Object.entries(report.byEnclaveMode).map(
+        ([mode, count]) => ({
+            MetricName: 'EscrowBlobs',
+            Value: count,
+            Unit: 'Count',
+            Timestamp: timestamp,
+            Dimensions: [{ Name: 'EnclaveMode', Value: mode }],
+        })
+    );
+    MetricData.push({
+        MetricName: 'EscrowBlobsStale',
+        Value: report.reseal.staleCount,
+        Unit: 'Count',
+        Timestamp: timestamp,
+    });
+    return { Namespace: CLOUDWATCH_NAMESPACE, MetricData };
+};
+
+const pad = (value: string, width: number): string => value.padEnd(width, ' ');
+
+export const formatReportTable = (report: EscrowBlobModeReport): string => {
+    const lines: string[] = [];
+    lines.push(`Escrow blob mode report — generated ${report.generatedAt}`);
+    lines.push(`Active enclave mode: ${report.activeEnclaveMode}`);
+    lines.push('');
+    lines.push('Totals:');
+    lines.push(`  UserKey documents:      ${report.totals.userKeys}`);
+    lines.push(`  Users with escrow blob: ${report.totals.escrowBlobs}`);
+    lines.push(`  Escrow PIN enabled:     ${report.totals.escrowPinEnabled}`);
+    lines.push(`  Opted out of escrow:    ${report.totals.optedOut}`);
+    lines.push(`  Pending holds:          ${report.totals.pendingHolds}`);
+    lines.push('');
+    lines.push('Escrow blobs by enclaveMode:');
+    for (const [mode, count] of Object.entries(report.byEnclaveMode)) {
+        lines.push(`  ${pad(mode, 14)} ${count}`);
+    }
+    lines.push('');
+    lines.push('Escrow blobs by enclaveKeyId:');
+    const keyIdEntries = Object.entries(report.byEnclaveKeyId);
+    if (keyIdEntries.length === 0) lines.push('  (none)');
+    for (const [keyId, count] of keyIdEntries) {
+        lines.push(`  ${pad(keyId, 28)} ${count}`);
+    }
+    lines.push('');
+    lines.push('Pending holds by releasePolicy:');
+    for (const [policy, count] of Object.entries(report.pendingHoldsByReleasePolicy)) {
+        lines.push(`  ${pad(policy, 14)} ${count}`);
+    }
+    lines.push('');
+    lines.push(
+        `Re-seal status: ${report.reseal.activeCount} on active mode (${report.activeEnclaveMode}), ` +
+            `${report.reseal.staleCount} stale (${report.reseal.staleRatePercent}%). ` +
+            `"Stale" = escrowBlob.enclaveMode !== active mode only; does not detect ` +
+            `enclaveKeyId rotation — see script header "Known limitations".`
+    );
+    lines.push('');
+    lines.push('Tenant breakdown: unavailable — UserKey has no tenant field.');
+    return lines.join('\n');
+};
+
+interface UserKeyFacetResult {
+    totalUserKeys: { count: number }[];
+    enclaveModeCounts: { _id: string | null; count: number }[];
+    enclaveKeyIdCounts: { _id: string | null; count: number }[];
+    escrowPinEnabled: { count: number }[];
+    optedOut: { count: number }[];
+}
+
+/**
+ * Impure: runs the counting queries. Never writes. Blob-related counts come
+ * from a single `$facet` aggregation over the UserKey collection; pending
+ * hold counts are a separate aggregation over the (distinct) EscrowHold
+ * collection.
+ */
+export const queryEscrowCounts = async (
+    userKeys: Collection<MongoUserKeyType>,
+    escrowHolds: Collection<EscrowHold>
+): Promise<RawEscrowCounts> => {
+    const [facetResult] = await userKeys
+        .aggregate<UserKeyFacetResult>([
+            {
+                $facet: {
+                    totalUserKeys: [{ $count: 'count' }],
+                    enclaveModeCounts: [
+                        { $match: { escrowBlob: { $exists: true } } },
+                        { $group: { _id: '$escrowBlob.enclaveMode', count: { $sum: 1 } } },
+                    ],
+                    enclaveKeyIdCounts: [
+                        { $match: { escrowBlob: { $exists: true } } },
+                        { $group: { _id: '$escrowBlob.enclaveKeyId', count: { $sum: 1 } } },
+                    ],
+                    // Same definition as getEscrowPinStatus() in src/models/UserKey.ts:
+                    // present, not disabled, and sealed for the current shareVersion.
+                    escrowPinEnabled: [
+                        {
+                            $match: {
+                                escrowPin: { $exists: true },
+                                'escrowPin.disabledAt': { $exists: false },
+                                $expr: { $eq: ['$escrowPin.shareVersion', '$shareVersion'] },
+                            },
+                        },
+                        { $count: 'count' },
+                    ],
+                    optedOut: [
+                        { $match: { escrowOptedOutAt: { $exists: true } } },
+                        { $count: 'count' },
+                    ],
+                },
+            },
+        ])
+        .toArray();
+
+    // Legacy rows predate the releasePolicy field and are treated as 'hold'
+    // everywhere else in the codebase (see EscrowHold.ts's own $or filters).
+    const pendingHoldsAgg = await escrowHolds
+        .aggregate<{ _id: string; count: number }>([
+            { $match: { status: 'pending' } },
+            { $group: { _id: { $ifNull: ['$releasePolicy', 'hold'] }, count: { $sum: 1 } } },
+        ])
+        .toArray();
+
+    return {
+        totalUserKeys: facetResult?.totalUserKeys[0]?.count ?? 0,
+        enclaveModeCounts: (facetResult?.enclaveModeCounts ?? []).map(({ _id, count }) => ({
+            mode: _id ?? 'unknown',
+            count,
+        })),
+        enclaveKeyIdCounts: (facetResult?.enclaveKeyIdCounts ?? []).map(({ _id, count }) => ({
+            keyId: _id ?? 'unknown',
+            count,
+        })),
+        escrowPinEnabledCount: facetResult?.escrowPinEnabled[0]?.count ?? 0,
+        optedOutCount: facetResult?.optedOut[0]?.count ?? 0,
+        pendingHoldsByPolicy: pendingHoldsAgg.map(({ _id, count }) => ({ policy: _id, count })),
+    };
+};
+
+const main = async (): Promise<void> => {
+    const argv = process.argv.slice(2);
+    const args = new Set(argv);
+    const jsonOutput = args.has('--json');
+    const publishMetrics = args.has('--publish-metrics');
+    const currentKeyId = argv
+        .find(arg => arg.startsWith('--current-key-id='))
+        ?.slice('--current-key-id='.length);
+    const previousKeyIds = (
+        argv
+            .find(arg => arg.startsWith('--previous-key-ids='))
+            ?.slice('--previous-key-ids='.length) ?? ''
+    )
+        .split(',')
+        .map(id => id.trim())
+        .filter(Boolean);
+
+    try {
+        const raw = await queryEscrowCounts(getUserKeysCollection(), getEscrowHoldsCollection());
+        const activeEnclaveMode = activeModeFromEnv(environment.ESCROW_ENCLAVE_MODE);
+        const report = buildReport(raw, activeEnclaveMode);
+        const metricsPayload = publishMetrics ? buildCloudWatchMetricPayload(report) : undefined;
+        const classification = currentKeyId
+            ? classifyEnclaveKeyIds(report.byEnclaveKeyId, currentKeyId, previousKeyIds)
+            : undefined;
+
+        if (jsonOutput) {
+            console.log(JSON.stringify({ report, metricsPayload, classification }, null, 2));
+        } else {
+            console.log(formatReportTable(report));
+            if (classification) {
+                console.log(
+                    formatKeyIdClassification(classification, currentKeyId, previousKeyIds)
+                );
+            }
+        }
+
+        if (publishMetrics && !jsonOutput) {
+            console.log('');
+            console.log(
+                'lca-api has no @aws-sdk/client-cloudwatch dependency (only ' +
+                    'services/learn-card-network/ai-agent does in this monorepo). ' +
+                    'Forward this payload to CloudWatch PutMetricData from the P7.1 ' +
+                    'monitor Lambda or an ops job that already has AWS SDK access:'
+            );
+            console.log(JSON.stringify(metricsPayload, null, 2));
+        }
+    } finally {
+        await mongoClient.close();
+    }
+};
+
+if (import.meta.main) {
+    main().catch(err => {
+        console.error('escrow-blob-mode-report failed:', err);
+        process.exit(1);
+    });
+}