@learncard/lca-api-service 1.5.2 → 1.5.3

package/dist/routes/ai.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/routes/escrow.d.ts

@@ -251,6 +251,25 @@ export declare const escrowRouter: import("@trpc/server").TRPCBuiltRouter<{
             } | undefined;
             requiresConfirmation?: boolean | undefined;
             pinSalt?: string | undefined;
+            codeSent?: boolean | undefined;
+            delivery?: {
+                codeSent: boolean;
+                proof: {
+                    version: 1;
+                    keyId: string;
+                    measurement: number[];
+                    signature: string;
+                    kind: "commit";
+                    payload: string;
+                } | {
+                    version: 1;
+                    keyId: string;
+                    measurement: number[];
+                    payload: string;
+                    signature: string;
+                    kind: "snapshot";
+                };
+            } | undefined;
         };
         meta: import("trpc-to-openapi").OpenApiMeta;
     }>;

package/dist/services/escrow-enclave/logFailure.d.ts

@@ -0,0 +1 @@
+export declare const logEscrowFailure: (error: unknown) => void;

package/dist/services/escrow-enclave/logFailure.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/escrow-enclave/types.d.ts

@@ -117,6 +117,17 @@ export interface EscrowEnclave {
     releaseEscrow(input: ReleaseRequest): Promise<ReleaseResult>;
     createHold(input: EnclaveCreateHoldInput): Promise<{
         holdRecord: EscrowHoldRecord;
+        delivery?: {
+            codeSent: boolean;
+            proof: AuthorityHoldReceipt;
+        };
+    }>;
+    getHoldState?(input: {
+        expectedDid: string;
+        hold: EscrowHoldRecord;
+        nonce: string;
+    }): Promise<{
+        proof: AuthorityRecord;
     }>;
     cancelHold(input: CancelHoldRequest): Promise<void | {
         receipt: AuthorityRecord;
@@ -136,6 +147,10 @@ export interface EscrowEnclave {
 export declare class EscrowPolicyError extends Error {
     constructor();
 }
+export declare class EscrowCodeError extends Error {
+    readonly reason: 'codeMismatch' | 'codeExpired' | 'codeLocked';
+    constructor(reason: 'codeMismatch' | 'codeExpired' | 'codeLocked');
+}
 export declare class EscrowPinMismatchError extends Error {
     constructor();
 }
@@ -143,5 +158,6 @@ export declare class EscrowBlobError extends Error {
     constructor();
 }
 export declare class EscrowUnavailableError extends Error {
-    constructor();
+    readonly reason: 'unavailable' | 'ledger' | 'time' | 'transport' | 'invalid_response' | 'invalid_hold' | 'http_refusal' | 'rate_limit';
+    constructor(reason?: 'unavailable' | 'ledger' | 'time' | 'transport' | 'invalid_response' | 'invalid_hold' | 'http_refusal' | 'rate_limit');
 }

package/esbuildPlugins.cjs

@@ -2,6 +2,7 @@ const path = require('node:path');
 const fs = require('node:fs');
 
 const { sentryEsbuildPlugin } = require('@sentry/esbuild-plugin');
+const { withSentryRateLimitRetry } = require('../../../scripts/sentry-rate-limit-retry.cjs');
 
 const forceCjsSodiumWrapperPlugin = {
     name: 'force-cjs-sodium-wrapper',
@@ -40,10 +41,12 @@ const copyDidkitWasmPlugin = {
 module.exports = [
     forceCjsSodiumWrapperPlugin,
     copyDidkitWasmPlugin,
-    sentryEsbuildPlugin({
-        telemetry: process.env.SENTRY_BUILD_TELEMETRY !== 'false',
-        authToken: process.env.SENTRY_AUTH_TOKEN,
-        org: process.env.SENTRY_ORG,
-        project: process.env.SENTRY_PROJECT,
-    }),
+    withSentryRateLimitRetry(
+        sentryEsbuildPlugin({
+            telemetry: process.env.SENTRY_BUILD_TELEMETRY !== 'false',
+            authToken: process.env.SENTRY_AUTH_TOKEN,
+            org: process.env.SENTRY_ORG,
+            project: process.env.SENTRY_PROJECT,
+        })
+    ),
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@learncard/lca-api-service",
-    "version": "1.5.2",
+    "version": "1.5.3",
     "description": "",
     "engines": {
         "node": ">=24.12 <25"
@@ -63,21 +63,21 @@
         "@fastify/formbody": "^8.0.2",
         "@fastify/rate-limit": "^10.2.0",
         "@fastify/static": "^10.1.1",
-        "@learncard/core": "9.4.39",
-        "@learncard/did-web-plugin": "1.1.39",
-        "@learncard/didkit-plugin": "1.10.4",
-        "@learncard/didkit-plugin-node": "0.3.4",
+        "@learncard/core": "9.4.40",
+        "@learncard/did-web-plugin": "1.1.40",
+        "@learncard/didkit-plugin": "1.10.5",
+        "@learncard/didkit-plugin-node": "0.3.5",
         "@learncard/email-templates": "1.2.1",
-        "@learncard/helpers": "1.6.3",
-        "@learncard/init": "2.5.4",
-        "@learncard/types": "5.23.1",
-        "@learncard/sss-key-manager": "0.2.2",
+        "@learncard/helpers": "1.7.0",
+        "@learncard/init": "2.5.5",
+        "@learncard/types": "5.23.2",
+        "@learncard/sss-key-manager": "0.2.3",
         "@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",
+        "axios": "^0.34.0",
         "dag-jose-utils": "2.0.0",
         "did-jwt": "5.9.0",
         "dotenv": "^16.0.3",

package/src/routes/ai.test.ts

@@ -0,0 +1,103 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+    SKILL_ICON_MAX_CHARACTERS_PER_REQUEST,
+    SKILL_ICON_MAX_NAMES_PER_REQUEST,
+} from '@learncard/types';
+
+const mocks = vi.hoisted(() => ({
+    create: vi.fn(),
+}));
+
+vi.mock('@environment', () => ({ environment: { OPENAI_API_KEY: 'test-key' } }));
+vi.mock('openai', () => ({
+    default: class {
+        chat = { completions: { create: mocks.create } };
+    },
+}));
+vi.mock('filestack-js', () => ({ init: () => ({}) }));
+vi.mock('@routes', async () => {
+    const { initTRPC } = await import('@trpc/server');
+    const t = initTRPC.create();
+    return { t, didAndChallengeRoute: t.procedure };
+});
+
+import { aiRouter } from './ai';
+
+const caller = aiRouter.createCaller({ user: { did: 'did:example:123' } } as never);
+
+const respondWithIcons = (): void => {
+    mocks.create.mockImplementation(async ({ messages }: { messages: { content: string }[] }) => {
+        const names = [...messages[1]!.content.matchAll(/^- (.*)$/gm)].map(match => match[1]);
+
+        return {
+            choices: [
+                {
+                    message: {
+                        content: JSON.stringify({
+                            items: names.map(name => ({ name, icon: '🎯' })),
+                        }),
+                    },
+                },
+            ],
+        };
+    });
+};
+
+describe('generateSkillIcons input validation', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        respondWithIcons();
+    });
+
+    it('accepts a batch at both limits', async () => {
+        const names = Array.from({ length: SKILL_ICON_MAX_NAMES_PER_REQUEST }, (_, i) =>
+            `${i}`.padStart(
+                SKILL_ICON_MAX_CHARACTERS_PER_REQUEST / SKILL_ICON_MAX_NAMES_PER_REQUEST,
+                'x'
+            )
+        );
+
+        const result = await caller.generateSkillIcons({ names });
+
+        expect(Object.keys(result)).toHaveLength(SKILL_ICON_MAX_NAMES_PER_REQUEST);
+        expect(mocks.create).toHaveBeenCalledTimes(1);
+    });
+
+    it('rejects too many names with BAD_REQUEST before calling the model', async () => {
+        const names = Array.from(
+            { length: SKILL_ICON_MAX_NAMES_PER_REQUEST + 1 },
+            (_, i) => `s${i}`
+        );
+
+        await expect(caller.generateSkillIcons({ names })).rejects.toMatchObject({
+            code: 'BAD_REQUEST',
+        });
+        expect(mocks.create).not.toHaveBeenCalled();
+    });
+
+    it('rejects names totalling more than the character limit with BAD_REQUEST', async () => {
+        const names = ['a'.repeat(SKILL_ICON_MAX_CHARACTERS_PER_REQUEST), 'b'];
+
+        await expect(caller.generateSkillIcons({ names })).rejects.toMatchObject({
+            code: 'BAD_REQUEST',
+        });
+        expect(mocks.create).not.toHaveBeenCalled();
+    });
+
+    it('rejects a single name over the character limit', async () => {
+        const names = ['a'.repeat(SKILL_ICON_MAX_CHARACTERS_PER_REQUEST + 1)];
+
+        await expect(caller.generateSkillIcons({ names })).rejects.toMatchObject({
+            code: 'BAD_REQUEST',
+        });
+    });
+
+    it('still rejects empty lists and empty names', async () => {
+        await expect(caller.generateSkillIcons({ names: [] })).rejects.toMatchObject({
+            code: 'BAD_REQUEST',
+        });
+        await expect(caller.generateSkillIcons({ names: [''] })).rejects.toMatchObject({
+            code: 'BAD_REQUEST',
+        });
+    });
+});

package/src/routes/ai.ts

@@ -5,6 +5,7 @@ import { z } from 'zod';
 
 import { t, didAndChallengeRoute } from '@routes';
 import { TRPCError } from '@trpc/server';
+import { GenerateSkillIconsInputValidator } from '@learncard/types';
 
 import * as filestack from 'filestack-js';
 import { BoostSkillHierarchy, BoostSkillHierarchyValidator } from 'types/skills';
@@ -204,7 +205,7 @@ export const aiRouter = t.router({
                     'Given a list of skill names, returns a mapping of each name to a single unicode emoji that best represents it. No skin tones, flags, or multi-character sequences.',
             },
         })
-        .input(z.object({ names: z.array(z.string().nonempty()).min(1) }))
+        .input(GenerateSkillIconsInputValidator)
         .output(IconMapValidator)
         .query(async ({ input, ctx }) => {
             const {

package/src/routes/escrow.ts

@@ -1,4 +1,5 @@
 import { timingSafeEqual, randomUUID, randomBytes } from 'crypto';
+import { logEscrowFailure } from '../services/escrow-enclave/logFailure';
 import {
     AuthorityCommitValidator,
     AuthorityHoldReceiptValidator,
@@ -79,6 +80,7 @@ import {
     getEnclaveAttestationIdentity,
     notifyEscrowHoldEvent,
     EscrowPolicyError,
+    EscrowCodeError,
     EscrowBlobError,
     EscrowUnavailableError,
     EscrowPinMismatchError,
@@ -247,6 +249,10 @@ const enclaveOperation = async <T>(
     try {
         return await operation();
     } catch (error) {
+        logEscrowFailure(error);
+        if (error instanceof EscrowCodeError) {
+            throw new TRPCError({ code: 'FORBIDDEN', message: error.reason });
+        }
         if (error instanceof EscrowUnavailableError) {
             throw new TRPCError({
                 code: 'PRECONDITION_FAILED',
@@ -760,6 +766,10 @@ export const escrowRouter = t.router({
                     status: z.literal('pending'),
                     resumeToken: z.string().nullable(),
                     pinSalt: EscrowPinSaltValidator.optional(),
+                    codeSent: z.boolean().optional(),
+                    delivery: z
+                        .object({ codeSent: z.boolean(), proof: AuthorityHoldReceiptValidator })
+                        .optional(),
                 })
         )
         .mutation(async ({ input, ctx }) => {
@@ -872,7 +882,7 @@ export const escrowRouter = t.router({
             // suppressed entirely rather than racing/duplicating it.
             const isAuthorityManagedHold =
                 input.releasePolicy === 'hold' && Boolean(getEscrowEnclave().confirmHold);
-            const { holdRecord } = await enclaveOperation(() =>
+            const { holdRecord, delivery } = await enclaveOperation(() =>
                 getEscrowEnclave().createHold({
                     envelope: userKey.escrowBlob!.envelope,
                     holdId: randomUUID(),
@@ -959,6 +969,7 @@ export const escrowRouter = t.router({
                 ...serializeHold(hold),
                 status: 'pending' as const,
                 resumeToken,
+                ...(delivery ? { delivery, codeSent: delivery.codeSent } : {}),
                 ...(input.releasePolicy === 'pin' ? { pinSalt: userKey.escrowPin!.salt } : {}),
             };
         }),
@@ -1302,8 +1313,10 @@ export const escrowRouter = t.router({
                     };
                 } catch (error) {
                     // Keep the typed mismatch inside the wrapper; never expose enclave internals.
-                    if (hold.releasePolicy === 'pin' && error instanceof EscrowPinMismatchError)
+                    if (hold.releasePolicy === 'pin' && error instanceof EscrowPinMismatchError) {
+                        logEscrowFailure(error);
                         return { mismatch: true as const };
+                    }
                     if (reserved && hold.holdRecord.hold.policyVersion !== 2)
                         await refundEscrowPinAttempt(
                             hold.authProvider,

package/src/services/escrow-enclave/logFailure.test.ts

@@ -0,0 +1,64 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createRemoteEnclave } from './remoteEnclave';
+import { logEscrowFailure } from './logFailure';
+import { EscrowUnavailableError } from './types';
+
+afterEach(() => vi.restoreAllMocks());
+
+describe('escrow failure reasons', () => {
+    it('logs invalid outbound holds without error details', () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+        const error = new EscrowUnavailableError('invalid_hold');
+        error.message = 'private hold contents';
+        logEscrowFailure(error);
+        expect(warn).toHaveBeenCalledExactlyOnceWith('[LCA escrow] enclave operation failed', {
+            reason: 'invalid_hold',
+        });
+    });
+    it.each([
+        [403, 'policy', 'policy'],
+        [403, 'pinMismatch', 'pin_mismatch'],
+        [403, 'codeMismatch', 'code_mismatch'],
+        [403, 'codeExpired', 'code_expired'],
+        [403, 'codeLocked', 'code_locked'],
+        [403, 'blob', 'blob'],
+        [503, 'ledger', 'ledger'],
+        [503, 'time', 'time'],
+        [412, 'unavailable', 'unavailable'],
+        [403, 'secret-unknown-code', 'http_refusal'],
+        [429, 'unknown', 'rate_limit'],
+        [200, 'unknown', 'invalid_response'],
+    ])('classifies HTTP %s / %s without logging payloads', async (status, code, reason) => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+        const enclave = createRemoteEnclave({
+            baseUrl: 'https://example.invalid',
+            token: 'secret-token',
+            timeoutMs: 100,
+            transport: {
+                post: async () => ({ status, data: { code, message: 'secret@example.com' } }),
+            },
+        });
+        await enclave.getAttestation().catch(logEscrowFailure);
+        expect(warn).toHaveBeenCalledExactlyOnceWith('[LCA escrow] enclave operation failed', {
+            reason,
+        });
+    });
+
+    it('drops transport error details', async () => {
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+        const enclave = createRemoteEnclave({
+            baseUrl: 'https://example.invalid',
+            token: 'secret-token',
+            timeoutMs: 100,
+            transport: {
+                post: async () => {
+                    throw new Error('secret-token');
+                },
+            },
+        });
+        await enclave.getAttestation().catch(logEscrowFailure);
+        expect(warn).toHaveBeenCalledExactlyOnceWith('[LCA escrow] enclave operation failed', {
+            reason: 'transport',
+        });
+    });
+});

package/src/services/escrow-enclave/logFailure.ts

@@ -0,0 +1,29 @@
+import {
+    EscrowBlobError,
+    EscrowCodeError,
+    EscrowPinMismatchError,
+    EscrowPolicyError,
+    EscrowUnavailableError,
+} from './types';
+
+/** Only allowlisted classifications reach logs; never serialize remote errors or payloads. */
+export const logEscrowFailure = (error: unknown): void => {
+    const reason =
+        error instanceof EscrowCodeError
+            ? {
+                  codeMismatch: 'code_mismatch',
+                  codeExpired: 'code_expired',
+                  codeLocked: 'code_locked',
+              }[error.reason]
+            : error instanceof EscrowUnavailableError
+              ? error.reason
+              : error instanceof EscrowPolicyError
+                ? 'policy'
+                : error instanceof EscrowPinMismatchError
+                  ? 'pin_mismatch'
+                  : error instanceof EscrowBlobError
+                    ? 'blob'
+                    : 'unexpected';
+    // lca-api uses structured console warnings rather than the browser logger.
+    console.warn('[LCA escrow] enclave operation failed', { reason });
+};

package/src/services/escrow-enclave/remoteEnclave.test.ts

@@ -3,6 +3,7 @@ import type { EscrowEnvelope } from '@learncard/sss-key-manager';
 import { createRemoteEnclave, type RemoteEnclaveTransportResponse } from './remoteEnclave';
 import {
     EscrowBlobError,
+    EscrowCodeError,
     EscrowPinMismatchError,
     EscrowPolicyError,
     EscrowUnavailableError,
@@ -114,6 +115,40 @@ describe('createRemoteEnclave', () => {
         );
     });
 
+    it.each(['codeMismatch', 'codeExpired', 'codeLocked'] as const)(
+        'maps %s without forwarding diagnostic text',
+        async code => {
+            const post = vi
+                .fn()
+                .mockResolvedValue(respond(403, { code, message: 'sensitive diagnostic' }));
+            const enclave = createRemoteEnclave({ baseUrl, token, timeoutMs, transport: { post } });
+            await expect(enclave.confirmHold!(confirmInput)).rejects.toEqual(
+                new EscrowCodeError(code)
+            );
+        }
+    );
+
+    it('separates delivery evidence from the signed hold before subsequent requests', async () => {
+        const delivery = { codeSent: false, proof: snapshotReceipt };
+        const post = vi.fn().mockResolvedValue(respond(200, { ...hold, delivery }));
+        const enclave = createRemoteEnclave({ baseUrl, token, timeoutMs, transport: { post } });
+        await expect(enclave.createHold(createInput)).resolves.toEqual({
+            holdRecord: hold,
+            delivery,
+        });
+    });
+
+    it('forwards fresh hold-state nonces under the existing bearer authentication', async () => {
+        const post = vi.fn().mockResolvedValue(respond(200, { proof: snapshotReceipt }));
+        const enclave = createRemoteEnclave({ baseUrl, token, timeoutMs, transport: { post } });
+        const input = { expectedDid: hold.hold.did, hold, nonce: 'ab'.repeat(32) };
+        await expect(enclave.getHoldState!(input)).resolves.toEqual({ proof: snapshotReceipt });
+        expect(post).toHaveBeenCalledWith(`${baseUrl}/v1/hold-state`, input, {
+            headers: { Authorization: `Bearer ${token}` },
+            timeout: timeoutMs,
+        });
+    });
+
     it('sends an empty nonce array when none is given', async () => {
         const post = vi.fn().mockResolvedValue(respond(200, attestationBody));
         const enclave = createRemoteEnclave({ baseUrl, token, timeoutMs, transport: { post } });
@@ -305,9 +340,69 @@ describe('createRemoteEnclave', () => {
         await expect(enclave.releaseEscrow(input)).resolves.toEqual({ sealed: envelope, receipt });
         expect(post.mock.calls.at(-1)?.[1]).toMatchObject({ requestId: 'stable-id' });
         post.mockResolvedValue(respond(200, { sealed: envelope }));
-        await expect(enclave.releaseEscrow(input)).rejects.toBeInstanceOf(EscrowUnavailableError);
+        await expect(enclave.releaseEscrow(input)).rejects.toMatchObject({
+            reason: 'invalid_response',
+        });
         post.mockResolvedValue(respond(200, { ok: true }));
-        await expect(enclave.cancelHold(input)).rejects.toBeInstanceOf(EscrowUnavailableError);
+        await expect(enclave.cancelHold(input)).rejects.toMatchObject({
+            reason: 'invalid_response',
+        });
+    });
+
+    it.each([
+        { ...hold, ledgerSeq: -1 },
+        { ...hold, hold: { ...hold.hold, policyVersion: 2, signature: 'invalid' } },
+    ])('distinguishes invalid outbound holds from invalid returned holds', async invalidHold => {
+        const post = vi.fn().mockResolvedValue(respond(200, invalidHold));
+        const enclave = createRemoteEnclave({ baseUrl, token, timeoutMs, transport: { post } });
+        const input = {
+            envelope,
+            hold: invalidHold,
+            expectedDid: hold.hold.did,
+            clientEphemeralPublicKey: hold.hold.clientEphemeralPublicKey,
+        };
+        await expect(enclave.releaseEscrow(input)).rejects.toMatchObject({
+            reason: 'invalid_hold',
+        });
+        await expect(enclave.cancelHold(input)).rejects.toMatchObject({ reason: 'invalid_hold' });
+        await expect(enclave.confirmHold!({ ...input, code: '12345678' })).rejects.toMatchObject({
+            reason: 'invalid_hold',
+        });
+        await expect(enclave.resendCode!(input)).rejects.toMatchObject({ reason: 'invalid_hold' });
+        expect(post).not.toHaveBeenCalled();
+        await expect(
+            enclave.createHold({
+                envelope,
+                ...hold.hold,
+                expectedDid: hold.hold.did,
+                expectedShareVersion: 1,
+            })
+        ).rejects.toMatchObject({ reason: 'invalid_response' });
+    });
+
+    it.each([
+        { envelope: null, enrollmentEpoch: 1 },
+        { envelope, enrollmentEpoch: 2 },
+    ])('classifies invalid rewrap envelope/epoch as a response failure', async result => {
+        const post = vi.fn().mockResolvedValue(
+            respond(200, {
+                result: {
+                    ...result,
+                    receipt,
+                    authorityGeneration: 'g1',
+                    enrollmentVersion: 2,
+                },
+            })
+        );
+        const enclave = createRemoteEnclave({ baseUrl, token, timeoutMs, transport: { post } });
+        await expect(
+            enclave.rewrapEscrowBlob({
+                envelope,
+                expectedDid: hold.hold.did,
+                expectedShareVersion: 1,
+                sourceEnrollmentEpoch: 1,
+            })
+        ).rejects.toMatchObject({ reason: 'invalid_response' });
     });
 
     // [A] confirm-hold/send-release-warning: a fresh call returns a signed
@@ -625,7 +720,10 @@ describe('createRemoteEnclave', () => {
         const created = await enclave.createHold(createInput);
         expect(created).toEqual({ holdRecord: opaque });
         const config = { headers: { Authorization: `Bearer ${token}` }, timeout: timeoutMs };
-        expect(post).toHaveBeenNthCalledWith(1, `${baseUrl}/v1/create-hold`, createInput, config);
+        expect(post).toHaveBeenNthCalledWith(1, `${baseUrl}/v1/create-hold`, createInput, {
+            ...config,
+            headers: { ...config.headers, 'X-Escrow-Delivery-Evidence': '1' },
+        });
         await expect(
             enclave.cancelHold({ ...cancelInput, hold: created.holdRecord })
         ).resolves.toBeUndefined();