@learncard/lca-api-service 1.3.2 → 1.5.0

package/lambda.ts

@@ -1,123 +1,38 @@
-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 { bootstrapLambda } from '@learncard/service-config';
 
-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 { base, stages } from './src/config/stageConfig';
 
-const promise = getEmptyLearnCard(); // Load WASM in for better cold starts
+type LambdaApp = typeof import('./lambdaApp');
 
-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',
-            },
-        };
-    },
+const getApplication = bootstrapLambda<LambdaApp>({
+    base,
+    stages,
+    stage: process.env.AWS_LAMBDA_FUNCTION_NAME
+        ? process.env.LAMBDA_STAGE
+        : process.env.CONFIG_STAGE,
+    importApp: () => import('./lambdaApp'),
 });
 
-export const openApiHandler = Sentry.AWSLambda.wrapHandler(
-    async (event: APIGatewayProxyEventV2, context: Context): Promise<APIGatewayProxyResultV2> => {
-        await promise;
-
-        if (isWarmupEvent(event)) {
-            console.log('[Warmup] Initializing LearnCard...');
-            await getEmptyLearnCard();
-            console.log('[Warmup] Done!');
-            return 'All done! 😄';
-        }
+export const trpcHandler = async (...args: Parameters<LambdaApp['trpcHandler']>) =>
+    (await getApplication()).trpcHandler(...args);
 
-        if (event.requestContext.http.method === 'OPTIONS') {
-            return {
-                statusCode: 200,
-                headers: {
-                    'Access-Control-Allow-Origin': '*',
-                    'Access-Control-Allow-Headers': '*',
-                    'Access-Control-Allow-Methods': '*',
-                },
-            };
-        }
+export const openApiHandler = async (...args: Parameters<LambdaApp['openApiHandler']>) =>
+    (await getApplication()).openApiHandler(...args);
 
-        return _openApiHandler(event, context);
-    }
-);
+export const swaggerUiHandler = async (...args: Parameters<LambdaApp['swaggerUiHandler']>) =>
+    (await getApplication()).swaggerUiHandler(...args);
 
-export const trpcHandler = Sentry.AWSLambda.wrapHandler(
-    async (event: APIGatewayProxyEventV2, context: Context): Promise<APIGatewayProxyResultV2> => {
-        await promise;
+export const didWebHandler = async (...args: Parameters<LambdaApp['didWebHandler']>) =>
+    (await getApplication()).didWebHandler(...args);
 
-        if (isWarmupEvent(event)) {
-            console.log('[Warmup] Initializing LearnCard...');
-            await getEmptyLearnCard();
-            console.log('[Warmup] Done!');
-            return 'All done! 😄';
-        }
+// Preserve the local/offline handler name without importing the full API for OIDC.
+export { handler as oidcHandler } from './oidcLambda';
 
-        if (event.requestContext.http.method === 'OPTIONS') {
-            return {
-                statusCode: 200,
-                headers: {
-                    'Access-Control-Allow-Origin': '*',
-                    'Access-Control-Allow-Headers': '*',
-                    'Access-Control-Allow-Methods': '*',
-                },
-            };
-        }
+// Scheduled (EventBridge) escrow jobs share the API bootstrap: they need Mongo/Postmark from the bundle.
+export const escrowHoldRemindersHandler = async (
+    ...args: Parameters<LambdaApp['escrowHoldRemindersHandler']>
+) => (await getApplication()).escrowHoldRemindersHandler(...args);
 
-        return _trpcHandler(event, context);
-    }
-);
+export const escrowBlobRewrapHandler = async (
+    ...args: Parameters<LambdaApp['escrowBlobRewrapHandler']>
+) => (await getApplication()).escrowBlobRewrapHandler(...args);

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,14 +1,20 @@
 {
     "name": "@learncard/lca-api-service",
-    "version": "1.3.2",
+    "version": "1.5.0",
     "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",
@@ -22,8 +28,10 @@
         "start-p-5000": "PORT=5000 serverless offline --httpPort 5000 --websocketPort 5001 --lambdaPort 5002 --albPort 5003 --config serverless-local.yml",
         "dev": "bun --conditions=development --watch src/docker-entry.ts",
         "start:docker": "bun --conditions=development src/docker-entry.ts",
-        "serverless-deploy": "node ../../../scripts/prepare-didkit-native-layer.cjs && serverless deploy",
-        "serverless-deploy-scouts": "serverless deploy --config serverless-scouts.yml"
+        "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",
+        "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)",
@@ -45,34 +53,42 @@
         "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.36",
-        "@learncard/email-templates": "1.1.0",
-        "@learncard/did-web-plugin": "1.1.36",
-        "@learncard/didkit-plugin": "1.10.1",
-        "@learncard/didkit-plugin-node": "0.3.1",
-        "@learncard/init": "2.5.0",
-        "@learncard/helpers": "1.6.0",
-        "@learncard/types": "5.21.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.2",
+        "@learncard/service-config": "0.1.1",
+        "@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",
         "@types/lodash": "^4.14.191",
         "@types/node-forge": "^1.3.11",
         "axios": "^0.33.0",
-        "dotenv": "^16.0.3",
         "dag-jose-utils": "2.0.0",
         "did-jwt": "5.9.0",
+        "dotenv": "^16.0.3",
         "express": "^4.18.2",
         "fastify": "^5.8.5",
         "filestack-js": "^3.24.0",
         "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/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`.