@learncard/lca-api-service 1.5.2 → 1.6.0

package/src/routes/ai.ts

@@ -1,10 +1,11 @@
 import { environment } from '@environment';
 import OpenAI from 'openai';
-import { zodResponseFormat } from 'openai/helpers/zod';
+import { createBedrockClient, generateStructuredOutput } from '@helpers/bedrockGeneration';
+import { generateStoredImage } from '@helpers/imageGeneration';
 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';
@@ -79,7 +80,7 @@ const IconMapValidator = z.record(
     z.string().min(1).max(8)
 );
 
-// LLM output schema: object-wrapped list to satisfy response_format type 'object'
+// Required-function output schema: object-wrapped list.
 // We'll convert this into the IconMapValidator shape before returning
 const IconListContainerValidator = z.object({
     items: z.array(
@@ -94,6 +95,10 @@ const openai = environment.OPENAI_API_KEY
     ? new OpenAI({ apiKey: environment.OPENAI_API_KEY })
     : undefined;
 
+let generationClient: OpenAI | undefined;
+const getGenerationClient = (): OpenAI =>
+    (generationClient ??= createBedrockClient(environment.BEDROCK_BASE_URL));
+
 export const aiRouter = t.router({
     generateBoostInfo: didAndChallengeRoute
         .meta({
@@ -109,41 +114,19 @@ export const aiRouter = t.router({
         })
         .input(z.object({ description: z.string().nonempty(), locale: z.string().optional() }))
         .output(AIResponseValidator)
-        .query(async ({ input, ctx }) => {
-            const {
-                user: { did },
-            } = ctx;
-            if (!openai) {
-                throw new TRPCError({
-                    code: 'INTERNAL_SERVER_ERROR',
-                    message: 'No OpenAI Key Set',
-                });
-            }
-
+        .query(async ({ input }) => {
             const { description } = input;
 
-            const completion = await openai.chat.completions.create({
-                model: 'gpt-4o-2024-08-06',
-                messages: [
-                    {
-                        role: 'system',
-                        content:
-                            `Generate a title ${aiTitleCharsetRule(
-                                input.locale
-                            )} with a maximum length of 24 characters and separate words with spaces if there is more than one, description, category, type, and narrative for a boost based on an arbitrary description. The narrative is no longer than 300 characters and answers the question "How do you earn this boost?"\n\nStrict constraints:\n- category MUST be EXACTLY one of: "Social Badge", "Achievement", "Course", "ID", "Work History", "Learning History", "Accomplishment", "Accommodation". Use exact casing and spelling; do NOT invent other categories.\n- type MUST be EXACTLY one of: "Certificate", "Badge", "ID". Use exact casing and spelling; do NOT invent other types.\n\nOutput requirements:\n- Return ONLY a JSON object with the keys "title", "description", "category", "type", and optional "narrative".\n- Do not include explanations, markdown, or extra fields.\n- Ensure the JSON parses without code fences.` +
-                            aiLocaleInstruction(input.locale),
-                    },
-                    { role: 'user', content: description },
-                ],
-                // response_format: zodResponseFormat(AIResponseValidator, 'info'),
-                response_format: { type: 'json_object' },
-                user: did,
+            return generateStructuredOutput(getGenerationClient(), {
+                task: 'reasoning',
+                instructions:
+                    `Generate a title ${aiTitleCharsetRule(
+                        input.locale
+                    )} with a maximum length of 24 characters and separate words with spaces if there is more than one, description, category, type, and narrative for a boost based on an arbitrary description. The narrative is no longer than 300 characters and answers the question "How do you earn this boost?"\n\nStrict constraints:\n- category MUST be EXACTLY one of: "Social Badge", "Achievement", "Course", "ID", "Work History", "Learning History", "Accomplishment", "Accommodation". Use exact casing and spelling; do NOT invent other categories.\n- type MUST be EXACTLY one of: "Certificate", "Badge", "ID". Use exact casing and spelling; do NOT invent other types.\n\nOutput requirements:\n- Return ONLY a JSON object with the keys "title", "description", "category", "type", and "narrative".\n- Do not include explanations, markdown, or extra fields.\n- Ensure the JSON parses without code fences.` +
+                    aiLocaleInstruction(input.locale),
+                input: description,
+                schema: AIResponseValidator,
             });
-
-            const content = completion.choices[0]?.message.content ?? '';
-            const response = JSON.parse(content);
-
-            return AIResponseValidator.parseAsync(response);
         }),
 
     generateBoostSkills: didAndChallengeRoute
@@ -159,36 +142,15 @@ export const aiRouter = t.router({
         })
         .input(z.object({ description: z.string().nonempty() }))
         .output(z.array(BoostSkillsValidator))
-        .query(async ({ input, ctx }) => {
-            const {
-                user: { did },
-            } = ctx;
-            if (!openai) {
-                throw new TRPCError({
-                    code: 'INTERNAL_SERVER_ERROR',
-                    message: 'No OpenAI Key Set',
-                });
-            }
-
+        .query(async ({ input }) => {
             const { description } = input;
 
-            const completion = await openai.chat.completions.create({
-                model: 'gpt-4o-2024-08-06',
-                messages: [
-                    {
-                        role: 'system',
-                        content: `Generate *NO MORE THAN 3* skills for the provided description about a boost that matches the given skills hierarchy. ${aiSkillsHierarchyRule}`,
-                    },
-                    { role: 'user', content: description },
-                ],
-                response_format: zodResponseFormat(BoostSkillHierarchyValidator, 'skills'),
-                user: did,
+            const parsedResponse = await generateStructuredOutput(getGenerationClient(), {
+                task: 'reasoning',
+                instructions: `Generate *NO MORE THAN 3* skills for the provided description about a boost that matches the given skills hierarchy. ${aiSkillsHierarchyRule}`,
+                input: description,
+                schema: BoostSkillHierarchyValidator,
             });
-
-            const response = JSON.parse(completion.choices[0]?.message.content ?? '');
-
-            const parsedResponse = await BoostSkillHierarchyValidator.parseAsync(response);
-
             return transformLLMResultToOutputShape(parsedResponse);
         }),
 
@@ -204,20 +166,9 @@ 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 {
-                user: { did },
-            } = ctx;
-
-            if (!openai) {
-                throw new TRPCError({
-                    code: 'INTERNAL_SERVER_ERROR',
-                    message: 'No OpenAI Key Set',
-                });
-            }
-
+        .query(async ({ input }) => {
             const { names } = input;
 
             const systemPrompt = `You are assigning a single, standard Unicode emoji to represent each skill name.
@@ -233,42 +184,12 @@ Rules:
                     '\n'
                 )}\n\nReturn a JSON object of the form { items: [{ name, icon }] } for these names.`;
 
-            // TODO switch to gpt 5 and use responses API
-            // will have to bump the openai package
-            let completion: any;
-            try {
-                completion = await openai.chat.completions.create({
-                    model: 'gpt-4o-2024-08-06',
-                    messages: [
-                        {
-                            role: 'system',
-                            content: systemPrompt,
-                        },
-                        { role: 'user', content: userContent },
-                    ],
-                    // Use the object-wrapped list schema for structured outputs
-                    //   currently breaks because response is wrapped in a code fence (```json ... ```)
-                    //   likely would need to to bump openai package version
-                    // response_format: zodResponseFormat(IconListContainerValidator, 'icons'),
-                    response_format: { type: 'json_object' },
-                    user: did,
-                });
-            } catch (error) {
-                console.error('🔥🔥🔥🔥🔥🔥🔥🔥🔥');
-                console.error('error:', error);
-            }
-
-            const content = completion.choices[0]?.message.content ?? '';
-
-            const response = JSON.parse(content);
-            // First, validate the model output with the object-wrapped list schema
-            const parsed = await IconListContainerValidator.parseAsync(response);
-            if (!parsed) {
-                throw new TRPCError({
-                    code: 'INTERNAL_SERVER_ERROR',
-                    message: 'No parsed structured output returned.',
-                });
-            }
+            const parsed = await generateStructuredOutput(getGenerationClient(), {
+                task: 'formatting',
+                instructions: systemPrompt,
+                input: userContent,
+                schema: IconListContainerValidator,
+            });
 
             // Transform into a record mapping input names to icons
             const record: Record<string, string> = {};
@@ -306,39 +227,7 @@ Rules:
             const {
                 user: { did },
             } = ctx;
-            if (!openai) {
-                throw new TRPCError({
-                    code: 'INTERNAL_SERVER_ERROR',
-                    message: 'No OpenAI Key Set',
-                });
-            }
-
-            const { prompt } = input;
-            const res = await openai.images.generate({
-                prompt,
-                model: 'dall-e-3',
-                size: '1024x1024',
-                user: did,
-            });
-
-            if (!res.data || !res.data[0]?.url) {
-                throw new TRPCError({
-                    code: 'INTERNAL_SERVER_ERROR',
-                    message: 'No image URL returned from OpenAI',
-                });
-            }
-
-            const filestackRes = (await client.storeURL(res?.data[0]?.url)) as any;
-            if (!filestackRes || !filestackRes.url) {
-                throw new TRPCError({
-                    code: 'INTERNAL_SERVER_ERROR',
-                    message: 'Failed to store image URL',
-                });
-            }
-
-            return {
-                url: filestackRes.url,
-            };
+            return generateStoredImage(input.prompt, did, environment, openai, client);
         }),
 });
 

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/routes/keys.ts

@@ -643,6 +643,13 @@ export const keysRouter = t.router({
                     escrowOptedOut: z.boolean(),
                     escrowPin: EscrowPinStatusValidator,
                     escrowStale: z.enum(['mode-mismatch', 'key-rotated']).optional(),
+                    /**
+                     * The account has an escrow recovery method (any confirmation state)
+                     * but none confirmed at the current share version, e.g. `pending`
+                     * after an identity-recovery rebind. A hint only; the client still
+                     * proves prior enrollment against the signed escrow authority.
+                     */
+                    priorEscrowEnrollment: z.boolean(),
                     sssActivationState: z.enum(['provisional', 'active']),
                 })
                 .nullable()
@@ -702,6 +709,10 @@ export const keysRouter = t.router({
                           }
                         : {}),
                 }));
+            const currentVersion = userKey.shareVersion ?? 1;
+            const escrowMethods = (userKey.recoveryMethods ?? []).filter(
+                rm => rm?.type === 'escrow'
+            );
 
             return {
                 authShare,
@@ -720,6 +731,13 @@ export const keysRouter = t.router({
                 escrowStale: userKey.escrowBlob
                     ? await getEscrowBlobStaleReason(userKey.escrowBlob)
                     : undefined,
+                priorEscrowEnrollment:
+                    escrowMethods.length > 0 &&
+                    !escrowMethods.some(
+                        rm =>
+                            rm.shareVersion === currentVersion &&
+                            isRecoveryMethodConfirmed(userKey, rm)
+                    ),
             };
         }),
 

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

@@ -27,6 +27,25 @@ MAoGCCqGSM49BAMDA2cAMGQCMGp/wTQLmtB6/GK6hMFaFTA27gXZcxrgJ0Uy+8C0
 Ztl5uoRwN99inHNWv1cnKGdNQgIwSoQgKs8uMnBUcfiB9ZR6xb98z/9athp5pDIE
 /KUv6cNmJtuCgPOJxC+4fVKl8xC3
 -----END CERTIFICATE-----
+`,
+    // Production CA, valid until 2029-10-26. SHA-256 C017B1482D96679D6F725F8A46A52DAC
+    // CE9921AB47B4FEDFDB4C814B38584859; source: SSM
+    // /learncard/escrow-enclave/production/ca-cert in account 934654685669.
+    'escrow-enclave.production.internal': `-----BEGIN CERTIFICATE-----
+MIICaDCCAe6gAwIBAgIUCMYQNgdrxBILfOeoVNOWuZBiG1cwCgYIKoZIzj0EAwMw
+VzEkMCIGA1UECgwbTGVhcm5pbmcgRWNvbm9teSBGb3VuZGF0aW9uMS8wLQYDVQQD
+DCZMZWFybkNhcmQgRXNjcm93IEVuY2xhdmUgUHJvZHVjdGlvbiBDQTAeFw0yNjEw
+MjcxOTE5MzBaFw0yOTEwMjYxOTE5MzBaMFcxJDAiBgNVBAoMG0xlYXJuaW5nIEVj
+b25vbXkgRm91bmRhdGlvbjEvMC0GA1UEAwwmTGVhcm5DYXJkIEVzY3JvdyBFbmNs
+YXZlIFByb2R1Y3Rpb24gQ0EwdjAQBgcqhkjOPQIBBgUrgQQAIgNiAARE/z2wlD3g
+oj5XyHZEJOjdffpvXHav9802AHod0h7QQP4NCLpw4Aofhx6+Qrx/le8KUGdu63V7
+948yzbrvW08XL20lmd2kFkb/23589kOzaTPeE1Ngs2y08n5cAkCdxWOjezB5MBIG
+A1UdEwEB/wQIMAYBAf8CAQAwDgYDVR0PAQH/BAQDAgEGMDQGA1UdHgEB/wQqMCig
+JjAkgiJlc2Nyb3ctZW5jbGF2ZS5wcm9kdWN0aW9uLmludGVybmFsMB0GA1UdDgQW
+BBTHUF7Yd+mLuA2XOthizgvTc8WW3zAKBggqhkjOPQQDAwNoADBlAjEAiFXqrpcc
+nR6ttLI4EEZ5qLMMGTksNypiTa+WyiUmJCtW3o6Luj9o/wlFXsFParINAjA8zeDx
+b1+05o+sCl0kQzEq1b2pN9/Xco5NQpMDfG2/BvKuSOVLhOQ1tdkZLo+uTgk=
+-----END CERTIFICATE-----
 `,
 };
 

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

@@ -0,0 +1,72 @@
+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 log = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+        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',
+        });
+        const metric = JSON.parse(String(log.mock.calls[0]?.[0]));
+        expect(metric).toMatchObject({ Reason: 'invalid_hold', EnclaveFailure: 1 });
+        expect(metric._aws.CloudWatchMetrics[0]).toMatchObject({
+            Namespace: 'LearnCard/Escrow',
+            Dimensions: [['Reason']],
+        });
+        expect(JSON.stringify(log.mock.calls)).not.toContain('private hold contents');
+    });
+    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,46 @@
+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 });
+    // One EMF event alongside the existing warning; no error text, request or identity fields.
+    console.log(
+        JSON.stringify({
+            _aws: {
+                Timestamp: Date.now(),
+                CloudWatchMetrics: [
+                    {
+                        Namespace: 'LearnCard/Escrow',
+                        Dimensions: [['Reason']],
+                        Metrics: [{ Name: 'EnclaveFailure', Unit: 'Count' }],
+                    },
+                ],
+            },
+            Reason: reason,
+            EnclaveFailure: 1,
+        })
+    );
+};

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();