@learncard/lca-api-service 1.3.2 → 1.5.0

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

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+// Use Serverless's own YAML parser. An optional argument validates its packaged JSON template.
+const require = createRequire(import.meta.url);
+const serverlessRequire = createRequire(require.resolve('serverless/package.json'));
+const config = serverlessRequire('js-yaml').load(
+    readFileSync(fileURLToPath(new URL('../serverless.yml', import.meta.url)), 'utf8')
+);
+const packaged = process.argv[2] ? JSON.parse(readFileSync(process.argv[2], 'utf8')) : undefined;
+const resources = packaged?.Resources ?? config.resources.Resources;
+const key = resources.SigningAuthoritySeedKey;
+assert.equal(key.Type, 'AWS::KMS::Key');
+assert.equal(key.DeletionPolicy, 'Retain');
+assert.equal(key.UpdateReplacePolicy, 'Retain');
+assert.equal(key.Properties.KeySpec, 'SYMMETRIC_DEFAULT');
+assert.equal(key.Properties.KeyUsage, 'ENCRYPT_DECRYPT');
+assert.equal(key.Properties.EnableKeyRotation, true);
+
+const roleArn = { 'Fn::GetAtt': ['SigningAuthorityExecutionRole', 'Arn'] };
+const keyArn = { 'Fn::GetAtt': ['SigningAuthoritySeedKey', 'Arn'] };
+const purpose = { StringEquals: { 'kms:EncryptionContext:purpose': 'lca-signing-authority-seed' } };
+const statements = key.Properties.KeyPolicy.Statement;
+const use = statements.find(statement => statement.Sid === 'LcaApiSeedEncryption');
+assert.deepEqual(use.Principal, { AWS: roleArn });
+assert.deepEqual(use.Action, ['kms:GenerateDataKey', 'kms:Decrypt']);
+assert.deepEqual(use.Condition, purpose);
+const deny = statements.find(statement => statement.Sid === 'DenyOtherCryptographicPrincipals');
+assert.equal(deny.Effect, 'Deny');
+assert.equal(deny.Principal, '*');
+assert.deepEqual(deny.Condition, { ArnNotEquals: { 'aws:PrincipalArn': roleArn } });
+assert(deny.Action.includes('kms:Decrypt'));
+assert(deny.Action.includes('kms:ReEncrypt*'));
+const admin = statements.find(statement => statement.Sid === 'AccountKeyAdministration');
+assert(admin.Action.includes('kms:DeleteAlias'));
+assert(admin.Action.includes('kms:GetKeyPolicy'));
+assert(
+    !admin.Action.some(action =>
+        ['kms:*', 'kms:Decrypt', 'kms:CreateGrant', 'kms:ReEncrypt*'].includes(action)
+    )
+);
+const iam = resources.SigningAuthoritySeedKeyPolicy.Properties;
+assert.deepEqual(iam.Roles, [{ Ref: 'SigningAuthorityExecutionRole' }]);
+assert.deepEqual(iam.PolicyDocument.Statement, [
+    {
+        Effect: 'Allow',
+        Action: ['kms:GenerateDataKey', 'kms:Decrypt'],
+        Resource: keyArn,
+        Condition: purpose,
+    },
+]);
+
+const worker = config.functions.seedMigration;
+assert.equal(worker.timeout, 900);
+assert.equal(worker.reservedConcurrency, 1);
+assert.equal(worker.events, undefined);
+assert.equal(worker.url, undefined);
+assert.deepEqual(worker.vpc, config.functions.api.vpc);
+for (const name of ['api', 'trpc', 'seedMigration']) {
+    assert(config.functions[name].dependsOn.includes('SigningAuthoritySeedKeyPolicy'));
+    assert.equal(config.functions[name].role, 'SigningAuthorityExecutionRole');
+}
+for (const name of ['swagger', 'didWeb']) {
+    assert.equal(config.functions[name].role, undefined);
+}
+assert.equal(resources.SigningAuthorityExecutionRole.Type, 'AWS::IAM::Role');
+// 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);
+    assert.equal(lambda.Properties.ReservedConcurrentExecutions, 1);
+    assert.deepEqual(lambda.Properties.Role, roleArn);
+    assert.deepEqual(lambda.Properties.Environment.Variables.SA_SEED_KMS_KEY_ARN, keyArn);
+    for (const name of ['Api', 'Trpc']) {
+        assert.deepEqual(resources[`${name}LambdaFunction`].Properties.Role, roleArn);
+    }
+    for (const name of ['Swagger', 'DidWeb']) {
+        assert.deepEqual(resources[`${name}LambdaFunction`].Properties.Role, {
+            'Fn::GetAtt': ['IamRoleLambdaExecution', 'Arn'],
+        });
+    }
+    for (const resource of Object.values(resources)) {
+        if (resource.Type === 'AWS::Lambda::Permission' || resource.Type === 'AWS::Lambda::Url') {
+            assert(!JSON.stringify(resource).includes('SeedMigrationLambdaFunction'));
+        }
+    }
+}
+
+// Validate the entire dependency graph, including generated role/function resources when packaged.
+const references = value => {
+    const found = new Set();
+    const visit = node => {
+        if (!node || typeof node !== 'object') return;
+        if (typeof node.Ref === 'string') found.add(node.Ref);
+        const attribute = node['Fn::GetAtt'];
+        if (attribute) found.add(Array.isArray(attribute) ? attribute[0] : attribute.split('.')[0]);
+        const sub = node['Fn::Sub'];
+        const source = Array.isArray(sub) ? sub[0] : sub;
+        if (typeof source === 'string') {
+            for (const match of source.matchAll(/\$\{([^}.]+)(?:\.[^}]+)?\}/g)) found.add(match[1]);
+        }
+        for (const child of Object.values(node)) visit(child);
+    };
+    visit(value);
+    for (const name of [].concat(value.DependsOn ?? [])) found.add(name);
+    return [...found].filter(name => name in resources);
+};
+const finished = new Set();
+const visit = (name, active = new Set()) => {
+    assert(!active.has(name), `Circular CloudFormation dependency at ${name}`);
+    if (finished.has(name)) return;
+    const next = new Set(active).add(name);
+    for (const dependency of references(resources[name])) visit(dependency, next);
+    finished.add(name);
+};
+for (const name of Object.keys(resources)) visit(name);
+console.log(
+    `Seed encryption infrastructure checks passed (${packaged ? 'packaged template' : 'source config'}, ${finished.size} resources).`
+);

package/scripts/check-signing-authority-redis.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Redis from 'ioredis';
+
+const LEGACY_SEED_PATTERN = 'sa|*';
+
+/** Read key names only. SCAN can repeat keys, so only a zero count proves absence. */
+export const countLegacySigningAuthorityKeys = async redis => {
+    let cursor = '0';
+    let matches = 0;
+    const deadline = Date.now() + 60_000;
+    do {
+        if (Date.now() >= deadline) throw new Error('Redis audit timed out.');
+        const [nextCursor, keys] = await redis.scan(
+            cursor,
+            'MATCH',
+            LEGACY_SEED_PATTERN,
+            'COUNT',
+            500
+        );
+        matches += keys.length;
+        cursor = nextCursor;
+    } while (cursor !== '0');
+    return matches;
+};
+
+/** Require an explicit real endpoint; never fall back to an empty in-memory cache. */
+export const getAuditRedisOptions = (env = process.env) => {
+    const port = Number(env.REDIS_PORT);
+    const db = Number(env.REDIS_DB ?? '0');
+    if (
+        !env.REDIS_HOST?.trim() ||
+        !Number.isInteger(port) ||
+        port < 1 ||
+        port > 65535 ||
+        !Number.isInteger(db) ||
+        db < 0 ||
+        (env.REDIS_TLS !== undefined && !['true', 'false'].includes(env.REDIS_TLS))
+    ) {
+        throw new Error(
+            'Set REDIS_HOST and REDIS_PORT; REDIS_DB defaults to 0 and REDIS_TLS accepts true or false.'
+        );
+    }
+    return {
+        host: env.REDIS_HOST,
+        port,
+        db,
+        username: env.REDIS_USERNAME,
+        password: env.REDIS_PASSWORD,
+        ...(env.REDIS_TLS === 'true' ? { tls: {} } : {}),
+        lazyConnect: true,
+        connectTimeout: 2_000,
+        commandTimeout: 5_000,
+        maxRetriesPerRequest: 0,
+        retryStrategy: () => null,
+    };
+};
+
+const main = async () => {
+    let redis;
+    try {
+        const options = getAuditRedisOptions();
+        redis = new Redis(options);
+        // Driver errors can include endpoint/auth details; report only the sanitized failure below.
+        redis.on('error', () => undefined);
+        await redis.connect();
+        const legacyKeyMatches = await countLegacySigningAuthorityKeys(redis);
+        console.log(
+            JSON.stringify({
+                database: options.db,
+                pattern: LEGACY_SEED_PATTERN,
+                legacyKeyMatches,
+                auditedAt: new Date().toISOString(),
+            })
+        );
+        if (legacyKeyMatches > 0) {
+            console.error(
+                'Legacy signing-authority cache keys remain. Follow the seed-encryption runbook before completing rollout.'
+            );
+            process.exitCode = 1;
+        }
+    } catch {
+        console.error(
+            'Redis audit failed. Check REDIS_HOST, REDIS_PORT, optional REDIS_DB/TLS/auth settings, and private network access. No clean result was established.'
+        );
+        process.exitCode = 1;
+    } finally {
+        redis?.disconnect();
+    }
+};
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await main();

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