@learncard/lca-api-service 1.4.0 → 1.5.1

package/lambdaApp.ts

@@ -0,0 +1,146 @@
+import serverlessHttp from 'serverless-http';
+import type { Context, APIGatewayProxyResultV2, APIGatewayProxyEventV2 } from 'aws-lambda';
+import { awsLambdaRequestHandler } from '@trpc/server/adapters/aws-lambda';
+import * as Sentry from '@sentry/serverless';
+
+import app from './src/openapi';
+import didWebApp from './src/dids';
+import { appRouter, createContext } from './src/app';
+import { getEmptyLearnCard } from './src/helpers/learnCard.helpers';
+import { createOpenApiAwsLambdaHandler } from './src/helpers/shim';
+import {
+    handleTrpcError,
+    sentryBeforeSend,
+    getTracesSampleRate,
+} from './src/helpers/sentry.helpers';
+import { environment } from './src/config/environment';
+import { toServerlessApplication } from './src/helpers/serverlessApplication';
+import { ensureUserKeysIndexes, createEscrowHoldsIndexes } from './src/models';
+import { runEscrowHoldReminders } from './src/jobs/escrowHoldReminders';
+import { runEscrowBlobRewrap } from './src/jobs/escrowBlobRewrap';
+
+const startupPromise = Promise.all([
+    getEmptyLearnCard(), // Load WASM in for better cold starts
+    ensureUserKeysIndexes(),
+    createEscrowHoldsIndexes(),
+]);
+
+const isWarmupEvent = (event: APIGatewayProxyEventV2): boolean =>
+    'source' in event && event.source === 'serverless-plugin-warmup';
+
+Sentry.AWSLambda.init({
+    dsn: environment.SENTRY_DSN,
+    environment: environment.SENTRY_ENV,
+    enabled: Boolean(environment.SENTRY_DSN),
+    tracesSampleRate: getTracesSampleRate(),
+    beforeSend: sentryBeforeSend,
+    integrations: [
+        new Sentry.Integrations.Console(),
+        new Sentry.Integrations.Http({ tracing: true }),
+        new Sentry.Integrations.ContextLines(),
+        new Sentry.Integrations.Mongo(),
+    ],
+});
+
+export const swaggerUiHandler = serverlessHttp(toServerlessApplication(app), {
+    basePath: '/docs',
+});
+export const didWebHandler = serverlessHttp(toServerlessApplication(didWebApp));
+
+export const _openApiHandler = createOpenApiAwsLambdaHandler({
+    router: appRouter,
+    responseMeta: () => {
+        return {
+            headers: {
+                'Access-Control-Allow-Origin': '*',
+                'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
+                'Access-Control-Allow-Headers': 'Authorization, Content-Type',
+            },
+        };
+    },
+    createContext,
+    onError: handleTrpcError,
+});
+
+export const _trpcHandler = awsLambdaRequestHandler({
+    router: appRouter,
+    createContext,
+    onError: handleTrpcError,
+    responseMeta: () => {
+        return {
+            headers: {
+                'Access-Control-Allow-Origin': '*',
+                'Access-Control-Allow-Methods': '*',
+                'Access-Control-Allow-Headers': 'authorization',
+            },
+        };
+    },
+});
+
+export const openApiHandler = Sentry.AWSLambda.wrapHandler(
+    async (event: APIGatewayProxyEventV2, context: Context): Promise<APIGatewayProxyResultV2> => {
+        await startupPromise;
+
+        if (isWarmupEvent(event)) {
+            console.log('[Warmup] Initializing LearnCard...');
+            await getEmptyLearnCard();
+            console.log('[Warmup] Done!');
+            return 'All done! 😄';
+        }
+
+        if (event.requestContext.http.method === 'OPTIONS') {
+            return {
+                statusCode: 200,
+                headers: {
+                    'Access-Control-Allow-Origin': '*',
+                    'Access-Control-Allow-Headers': '*',
+                    'Access-Control-Allow-Methods': '*',
+                },
+            };
+        }
+
+        return _openApiHandler(event, context);
+    }
+);
+
+export const trpcHandler = Sentry.AWSLambda.wrapHandler(
+    async (event: APIGatewayProxyEventV2, context: Context): Promise<APIGatewayProxyResultV2> => {
+        await startupPromise;
+
+        if (isWarmupEvent(event)) {
+            console.log('[Warmup] Initializing LearnCard...');
+            await getEmptyLearnCard();
+            console.log('[Warmup] Done!');
+            return 'All done! 😄';
+        }
+
+        if (event.requestContext.http.method === 'OPTIONS') {
+            return {
+                statusCode: 200,
+                headers: {
+                    'Access-Control-Allow-Origin': '*',
+                    'Access-Control-Allow-Headers': '*',
+                    'Access-Control-Allow-Methods': '*',
+                },
+            };
+        }
+
+        return _trpcHandler(event, context);
+    }
+);
+
+// Scheduled (EventBridge) functions, not API-Gateway-triggered: they share
+// startupPromise with the handlers above; warmup/OPTIONS handling doesn't apply.
+export const escrowHoldRemindersHandler = Sentry.AWSLambda.wrapHandler(async (): Promise<void> => {
+    await startupPromise;
+    const counts = await runEscrowHoldReminders();
+    console.log('[escrow-hold-reminders] completed', counts);
+});
+
+// P9.3: migrates escrow blobs off a retiring enclave key for accounts that
+// never sign in again (P9.2 already covers accounts that do, on next login).
+export const escrowBlobRewrapHandler = Sentry.AWSLambda.wrapHandler(async (): Promise<void> => {
+    await startupPromise;
+    const counts = await runEscrowBlobRewrap();
+    console.log('[escrow-blob-rewrap] completed', counts);
+});

package/oidcLambda.test.ts

@@ -0,0 +1,38 @@
+import type { APIGatewayProxyEventV2, Context } from 'aws-lambda';
+import { afterEach, beforeEach, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({ applyStage: vi.fn(), handler: vi.fn(), importApp: vi.fn() }));
+vi.mock('./src/config/stageConfig', () => ({ applyLcaApiStageConfig: mocks.applyStage }));
+
+beforeEach(() => {
+    vi.resetModules();
+    vi.clearAllMocks();
+    mocks.handler.mockResolvedValue({ statusCode: 200 });
+    vi.doMock('./oidcLambdaApp', () => {
+        mocks.importApp();
+        expect(mocks.applyStage).toHaveBeenCalledTimes(1);
+        return { oidcHandler: mocks.handler };
+    });
+});
+afterEach(() => vi.unstubAllEnvs());
+
+it.each([
+    ['lca-api-dev-oidc', 'dev'],
+    ['', 'local'],
+])(
+    'applies the appropriate stage before the isolated OIDC import (%s)',
+    async (functionName, expectedStage) => {
+        vi.stubEnv('AWS_LAMBDA_FUNCTION_NAME', functionName);
+        vi.stubEnv('LAMBDA_STAGE', 'dev');
+        vi.stubEnv('CONFIG_STAGE', 'local');
+        const { handler } = await import('./oidcLambda');
+        const event = {} as APIGatewayProxyEventV2;
+        const context = {} as Context;
+        const callback = vi.fn();
+        await Promise.all([handler(event, context, callback), handler(event, context, callback)]);
+        expect(mocks.applyStage).toHaveBeenCalledExactlyOnceWith(expectedStage);
+        expect(mocks.importApp).toHaveBeenCalledTimes(1);
+        expect(mocks.handler).toHaveBeenCalledTimes(2);
+        expect(mocks.handler).toHaveBeenLastCalledWith(event, context, callback);
+    }
+);

package/oidcLambda.ts

@@ -0,0 +1,18 @@
+import { applyLcaApiStageConfig } from './src/config/stageConfig';
+
+type OidcApp = typeof import('./oidcLambdaApp');
+
+let application: Promise<OidcApp> | undefined;
+
+export const handler = async (...args: Parameters<OidcApp['oidcHandler']>) => {
+    if (!application) {
+        applyLcaApiStageConfig(
+            process.env.AWS_LAMBDA_FUNCTION_NAME
+                ? process.env.LAMBDA_STAGE
+                : process.env.CONFIG_STAGE
+        );
+        // This role cannot read the runtime bundle. Cache imports, including failures.
+        application = import('./oidcLambdaApp');
+    }
+    return (await application).oidcHandler(...args);
+};

package/oidcLambdaApp.ts

@@ -0,0 +1,11 @@
+import serverlessHttp from 'serverless-http';
+
+import { app as oidcApp } from './src/oidc';
+import { toServerlessApplication } from './src/helpers/serverlessApplication';
+
+/**
+ * Dedicated OIDC Lambda entrypoint. Unlike `lambdaApp.ts`, this imports only the
+ * Fastify OIDC surface and its focused environment, so the OIDC function boots
+ * without SEED/MONGO/Postmark/Firebase or a runtime-secrets bundle.
+ */
+export const oidcHandler = serverlessHttp(toServerlessApplication(oidcApp));

package/package.json

@@ -1,18 +1,20 @@
 {
     "name": "@learncard/lca-api-service",
-    "version": "1.4.0",
+    "version": "1.5.1",
     "description": "",
     "engines": {
         "node": ">=24.12 <25"
     },
-    "packageManager": "bun@1.3.14",
+    "packageManager": "bun@1.4.2",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
     "scripts": {
         "migrate:sa-seeds:local": "bash scripts/migrate-signing-authority-seeds-local.sh",
         "migrate:sa-seeds": "node scripts/migrate-signing-authority-seeds.mjs",
         "check:sa-infra": "node scripts/check-seed-encryption-infrastructure.mjs",
+        "sa-seed:flags": "bun --conditions=development scripts/print-seed-rollout-flags.ts",
         "check:sa-redis": "node scripts/check-signing-authority-redis.mjs",
+        "provision:keycloak": "bun --conditions=development scripts/provision-keycloak-users.ts",
         "test": "vitest run --config vitest.config.ts",
         "test:watch": "vitest --config vitest.config.ts",
         "test:coverage": "vitest run --coverage --config vitest.config.ts",
@@ -27,7 +29,9 @@
         "dev": "bun --conditions=development --watch src/docker-entry.ts",
         "start:docker": "bun --conditions=development src/docker-entry.ts",
         "serverless-deploy": "node scripts/check-seed-encryption-infrastructure.mjs && node ../../../scripts/prepare-didkit-native-layer.cjs && serverless deploy",
-        "serverless-deploy-scouts": "serverless deploy --config serverless-scouts.yml"
+        "serverless-deploy-scouts": "serverless deploy --config serverless-scouts.yml",
+        "test:oidc:e2e": "node test/oidc-e2e/run.mjs",
+        "typecheck:oidc:e2e": "tsc --noEmit -p test/oidc-e2e/tsconfig.json"
     },
     "keywords": [],
     "author": "WeLibrary, LLC (www.welibrary.io)",
@@ -49,21 +53,25 @@
         "serverless-http": "3.2.0",
         "serverless-offline": "^14.4.0",
         "serverless-prune-plugin": "^2.1.0",
-        "shx": "^0.3.4"
+        "shx": "^0.3.4",
+        "@playwright/test": "^1.42.0"
     },
     "dependencies": {
         "@aws-sdk/client-kms": "^3.1139.0",
+        "@aws-sdk/client-secrets-manager": "^3.1139.0",
         "@fastify/cors": "^11.2.0",
+        "@fastify/formbody": "^8.0.2",
+        "@fastify/rate-limit": "^10.2.0",
         "@fastify/static": "^10.1.1",
-        "@learncard/core": "9.4.37",
-        "@learncard/did-web-plugin": "1.1.37",
-        "@learncard/didkit-plugin": "1.10.2",
-        "@learncard/didkit-plugin-node": "0.3.2",
-        "@learncard/email-templates": "1.2.0",
-        "@learncard/helpers": "1.6.1",
-        "@learncard/init": "2.5.1",
-        "@learncard/types": "5.22.0",
-        "@learncard/sss-key-manager": "0.2.0",
+        "@learncard/core": "9.4.38",
+        "@learncard/did-web-plugin": "1.1.38",
+        "@learncard/didkit-plugin": "1.10.3",
+        "@learncard/didkit-plugin-node": "0.3.3",
+        "@learncard/email-templates": "1.2.1",
+        "@learncard/helpers": "1.6.2",
+        "@learncard/init": "2.5.3",
+        "@learncard/types": "5.23.0",
+        "@learncard/sss-key-manager": "0.2.1",
         "@sentry/serverless": "^7.61.0",
         "@trpc/server": "11.8.0",
         "@types/jsonwebtoken": "^9.0.8",
@@ -79,6 +87,7 @@
         "firebase-admin": "13.4.0",
         "ioredis": "^5.2.2",
         "ioredis-mock": "^8.2.2",
+        "jose": "^6.2.12",
         "jsonwebtoken": "^9.0.2",
         "jwt-decode": "^3.1.2",
         "libsodium-wrappers": "^0.7.11",

package/project.json

@@ -14,7 +14,14 @@
     "targets": {
         "build": {
             "executor": "nx:run-script",
-            "inputs": ["source"],
+            "inputs": [
+                "source",
+                "{projectRoot}/bundle.mjs",
+                "{projectRoot}/esbuildPlugins.cjs",
+                "{projectRoot}/package.json",
+                "{projectRoot}/tsconfig*.json",
+                "{workspaceRoot}/packages/service-config/src/**/*"
+            ],
             "options": {
                 "script": "build"
             }

package/scripts/README.md

@@ -0,0 +1,88 @@
+# lca-api scripts
+
+Operational scripts run directly with `bun scripts/<name>.ts` from
+`services/learn-card-network/lca-api/`. These are not part of the deployed
+service and are not built by `bun run build`; they import `src/` files by
+relative path (not the `@alias` path mappings used inside `src/`, since
+`scripts/` is intentionally outside this package's `tsconfig.json` `include`
+and those aliases don't resolve from here — see `escrow-blob-mode-report.ts`
+if you need the full explanation).
+
+## `strip-email.ts`
+
+Removes the email attribute from a Firebase user by UID, via the Identity
+Toolkit REST API (the Admin SDK can't clear an email, only replace it).
+
+```bash
+bun scripts/strip-email.ts <uid>
+```
+
+Requires `GOOGLE_APPLICATION_CREDENTIAL`.
+
+## `escrow-blob-mode-report.ts` (P6.2)
+
+Read-only counts report over the `userkeys` and `escrowholds` collections:
+escrow blob counts by `enclaveMode` / `enclaveKeyId`, enabled-PIN count,
+pending-hold counts by `releasePolicy`, opted-out count, and a software→nitro
+"re-seal" breakdown. Never writes to the database and never prints PII (counts
+only — no DIDs, emails, or Mongo `_id`s).
+
+```bash
+# Human-readable table
+bun scripts/escrow-blob-mode-report.ts
+
+# Machine-readable JSON
+bun scripts/escrow-blob-mode-report.ts --json
+
+# Also print the CloudWatch PutMetricData payload for the counts
+bun scripts/escrow-blob-mode-report.ts --json --publish-metrics
+```
+
+Requires the same env as the lca-api server: `SEED`, `MONGO_URI`,
+`MONGO_DB_NAME` (point `MONGO_URI` at whichever environment you want to report
+on). Full flag/limitation reference lives in the script's own header comment.
+
+**CloudWatch:** `--publish-metrics` does not call AWS itself — lca-api has no
+`@aws-sdk/client-cloudwatch` dependency (only
+`services/learn-card-network/ai-agent` does elsewhere in this monorepo, and it
+isn't shared with lca-api). The flag prints the exact `MetricData` payload
+(namespace `LearnCard/Escrow`, metrics `EscrowBlobs` per `EnclaveMode`
+dimension and `EscrowBlobsStale`) for the P7.1 monitor Lambda or an ops job
+that already has AWS SDK access to forward.
+
+### Running it locally against a throwaway Mongo
+
+There's no persistent local Mongo fixture for scripts (unlike `test/*.spec.ts`,
+which get one via `vitest-setup.ts`'s `mongodb-memory-server` global setup).
+To try the report against real data without touching a real environment, spin
+up your own `mongodb-memory-server` instance and point the script at it:
+
+```ts
+// tmp-run-report.mjs (delete after use — do not commit)
+import { MongoMemoryServer } from 'mongodb-memory-server';
+import { spawnSync } from 'node:child_process';
+
+const mongod = await MongoMemoryServer.create();
+// ...seed `userkeys` / `escrowholds` via a MongoClient here...
+
+spawnSync('bun', ['scripts/escrow-blob-mode-report.ts', '--json'], {
+    env: {
+        ...process.env,
+        NODE_ENV: 'development',
+        SEED: 'a'.repeat(64),
+        MONGO_URI: mongod.getUri(),
+        MONGO_DB_NAME: 'report-harness',
+    },
+    stdio: 'inherit',
+});
+
+await mongod.stop();
+```
+
+### Testing
+
+`escrow-blob-mode-report.test.ts` covers the pure aggregation → report
+formatting logic (zero-count modes, an unknown `enclaveMode`/`releasePolicy`
+value, the CloudWatch payload shape) without touching Mongo. It's picked up by
+the same `bun run test` as `src/**/*.test.ts` — `vitest.config.ts`'s `include`
+was extended to also match `scripts/**/*.test.ts`.

package/scripts/check-seed-encryption-infrastructure.mjs

@@ -67,8 +67,24 @@ for (const name of ['swagger', 'didWeb']) {
     assert.equal(config.functions[name].role, undefined);
 }
 assert.equal(resources.SigningAuthorityExecutionRole.Type, 'AWS::IAM::Role');
-assert.deepEqual(config.provider.environment.SA_SEED_KMS_KEY_ARN, keyArn);
-assert.equal(config.provider.environment.SA_SEED_LOCAL_KEK, undefined);
+// provider.environment is a Serverless file variable; resolve it like Serverless does, in
+// both runtime-secrets modes, so the KMS ARN and the no-local-KEK invariant are still checked.
+assert.equal(config.provider.environment, '${file(./serverless.function-env.cjs):provider}');
+const functionEnv = require('../serverless.function-env.cjs');
+const savedEnv = { ...process.env };
+try {
+    for (const bundle of ['', 'lca-api/dev/runtime-secrets']) {
+        process.env.RUNTIME_SECRETS_ID = bundle;
+        process.env.SA_SEED_LOCAL_KEK = 'must-not-reach-lambda';
+        const provider = functionEnv.provider({ options: { stage: 'dev' } });
+        assert.deepEqual(provider.SA_SEED_KMS_KEY_ARN, keyArn);
+        // Deployed functions use KMS only; the local KEK is for offline development.
+        for (const env of [provider, functionEnv.api(), functionEnv.escrow()])
+            assert.equal(env.SA_SEED_LOCAL_KEK, undefined);
+    }
+} finally {
+    process.env = savedEnv;
+}
 if (packaged) {
     const lambda = resources.SeedMigrationLambdaFunction;
     assert.equal(lambda.Properties.Timeout, 900);

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']);
+    });
+});