@learncard/lca-api-service 1.5.0 → 1.5.2

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

@@ -0,0 +1,126 @@
+import { z } from 'zod';
+import {
+    encodeEscrowEnrollmentIntent,
+    ESCROW_ALGORITHM,
+    ESCROW_ENVELOPE_VERSION,
+} from '@learncard/sss-key-manager';
+
+export const safeInteger = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+const label = z
+    .string()
+    .min(1)
+    .max(128)
+    .regex(/^[A-Za-z0-9_-]+$/);
+export const AuthorityEnvelopeValidator = z
+    .object({
+        version: z.literal(ESCROW_ENVELOPE_VERSION),
+        algorithm: z.literal(ESCROW_ALGORITHM),
+        keyId: z.string().min(1).max(128),
+        ephemeralPublicKey: z.string().max(256),
+        salt: z.string().max(128),
+        iv: z.string().max(64),
+        ciphertext: z.string().max(16_384),
+    })
+    .strict();
+export const AuthorityRecordValidator = z
+    .object({
+        version: z.literal(1),
+        kind: z.enum(['proposal', 'commit', 'snapshot']),
+        keyId: z.string().min(1).max(128),
+        measurement: z.array(z.number().int().min(0).max(255)).length(32),
+        payload: z.string().min(1).max(49_152),
+        signature: z.string().length(88),
+    })
+    .strict();
+export const AuthorityCommitValidator = AuthorityRecordValidator.extend({
+    kind: z.literal('commit'),
+    payload: z.string().min(1).max(8192),
+});
+// Idempotent-retry attestation for confirm-hold / send-release-warning (see
+// `authority_hold_snapshot` in policy/authority.rs): a fresh call returns a
+// `commit`; a retry of an already-applied operation returns this instead,
+// signed over the hold's current fields rather than a new ledger transition.
+export const AuthorityHoldSnapshotValidator = AuthorityRecordValidator.extend({
+    kind: z.literal('snapshot'),
+});
+// confirm-hold and send-release-warning responses carry whichever shape the
+// enclave actually returned; callers must not assume `commit`.
+export const AuthorityHoldReceiptValidator = z.union([
+    AuthorityCommitValidator,
+    AuthorityHoldSnapshotValidator,
+]);
+export const SignedEnrollmentIntentValidator = z
+    .object({
+        intent: z
+            .object({
+                version: z.literal(2),
+                tenant: label,
+                did: z.string().length(56),
+                authorityGeneration: label,
+                expectedEnrollmentVersion: safeInteger,
+                action: z.enum(['enroll', 'replace', 'disable', 'carry']),
+                sourceBlobIdentity: z
+                    .string()
+                    .regex(/^[0-9a-f]{64}$/)
+                    .nullable(),
+                targetBlobIdentity: z
+                    .string()
+                    .regex(/^[0-9a-f]{64}$/)
+                    .nullable(),
+                pinAction: z.enum(['set', 'change', 'clear', 'keep']),
+                shareVersion: z.number().int().positive().max(0xffffffff),
+                enrollmentEpoch: safeInteger.positive(),
+                requestId: z.string().min(1).max(112),
+                allowRewrap: z.boolean(),
+                // P9.1 (attack C): shape only — `encodeEscrowEnrollmentIntent` below
+                // enforces normalization, the paired requirement, and the language
+                // allow-list; lca-api never re-derives or overrides these values.
+                recoveryEmail: z.string().min(3).max(254).nullable(),
+                recoveryLanguage: z.string().length(2).nullable(),
+            })
+            .strict()
+            .refine(intent => {
+                try {
+                    encodeEscrowEnrollmentIntent(intent);
+                    return true;
+                } catch {
+                    return false;
+                }
+            }, 'Invalid enrollment intent'),
+        signature: z.string().length(88),
+    })
+    .strict();
+export const AuthorityStateValidator = z
+    .object({
+        tenant: label,
+        authorityGeneration: label,
+        did: z.string().min(1).max(8192),
+        enrollmentVersion: safeInteger,
+        enrollmentEpoch: safeInteger,
+        status: z.enum(['empty', 'active', 'disabled']),
+        envelope: AuthorityEnvelopeValidator.nullable(),
+        shareVersion: z.number().int().positive().max(0xffffffff).nullable(),
+        hasPin: z.boolean(),
+        pinGeneration: safeInteger,
+        attemptsUsed: z.number().int().min(0).max(10),
+    })
+    .strict();
+export const AuthorityStateResponseValidator = z
+    .object({
+        state: AuthorityStateValidator,
+        proof: AuthorityRecordValidator.extend({ kind: z.literal('snapshot') }),
+    })
+    .strict();
+export const AuthorityMutationValidator = z
+    .object({
+        envelope: AuthorityEnvelopeValidator.nullable(),
+        receipt: AuthorityCommitValidator,
+        authorityGeneration: label,
+        enrollmentVersion: safeInteger.positive(),
+        enrollmentEpoch: safeInteger.positive(),
+    })
+    .strict();
+export type AuthorityRecord = z.infer<typeof AuthorityRecordValidator>;
+export type AuthorityHoldReceipt = z.infer<typeof AuthorityHoldReceiptValidator>;
+export type AuthorityMutationResult = z.infer<typeof AuthorityMutationValidator>;
+export type AuthorityStateResponse = z.infer<typeof AuthorityStateResponseValidator>;

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

@@ -40,13 +40,13 @@ export const cancelHoldInEnclave = async (
         ) {
             throw new Error('Cancellation material unavailable');
         }
-        await getEscrowEnclave().cancelHold({
+        const result = await getEscrowEnclave().cancelHold({
             envelope,
             hold: hold.holdRecord,
             clientEphemeralPublicKey: hold.clientEphemeralPublicKey,
             expectedDid: hold.primaryDid,
         });
-        await confirmEscrowEnclaveCancellation(hold._id);
+        await confirmEscrowEnclaveCancellation(hold._id, result?.receipt);
         return true;
     } catch {
         // Policy/unknown/terminal errors are ambiguous, not proof of cancellation.

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

@@ -12,6 +12,35 @@ import {
 const baseUrl = 'https://enclave-host.internal';
 const token = 't'.repeat(32);
 const timeoutMs = 10_000;
+const receipt = {
+    version: 1 as const,
+    kind: 'commit' as const,
+    keyId: 'key-1',
+    measurement: Array(32).fill(0),
+    payload: 'AQ==',
+    signature: Buffer.alloc(64).toString('base64'),
+};
+
+// Real Rust shape for the idempotent-retry path (`authority_hold_snapshot`,
+// policy/authority.rs): a signed tuple, never an `AuthorityCommitValidator`.
+const snapshotReceipt = {
+    version: 1 as const,
+    kind: 'snapshot' as const,
+    keyId: 'key-1',
+    measurement: Array(32).fill(0),
+    payload: Buffer.from(
+        JSON.stringify([
+            'learncard-authority-hold-snapshot-v2',
+            'hold-1',
+            Array(32).fill(7),
+            'pending',
+            1700000000000,
+            1700086400000,
+            'g1',
+        ])
+    ).toString('base64'),
+    signature: Buffer.alloc(64).toString('base64'),
+};
 
 const envelope: EscrowEnvelope = {
     version: 1,
@@ -223,7 +252,14 @@ describe('createRemoteEnclave', () => {
     });
 
     it('rewraps an escrow blob sealed under a previous key onto the current key', async () => {
-        const post = vi.fn().mockResolvedValue(respond(200, { envelope }));
+        const authority = {
+            envelope,
+            receipt,
+            authorityGeneration: 'g1',
+            enrollmentVersion: 2,
+            enrollmentEpoch: 1,
+        };
+        const post = vi.fn().mockResolvedValue(respond(200, { result: authority }));
         const enclave = createRemoteEnclave({ baseUrl, token, timeoutMs, transport: { post } });
         const input = {
             envelope,
@@ -232,10 +268,10 @@ describe('createRemoteEnclave', () => {
             sourceEnrollmentEpoch: 1,
         };
 
-        await expect(enclave.rewrapEscrowBlob(input)).resolves.toEqual({ envelope });
+        await expect(enclave.rewrapEscrowBlob(input)).resolves.toEqual({ envelope, authority });
 
         expect(post).toHaveBeenCalledWith(
-            `${baseUrl}/v1/rewrap-escrow-blob`,
+            `${baseUrl}/v1/authority-rewrap`,
             {
                 envelope,
                 expectedDid: 'did:example:alice',
@@ -246,6 +282,183 @@ describe('createRemoteEnclave', () => {
         );
     });
 
+    it('preserves v2 cancellation receipts and stable release IDs, refusing absent commit evidence', async () => {
+        const v2 = {
+            ...hold,
+            hold: {
+                ...hold.hold,
+                policyVersion: 2,
+                signature: Buffer.from(JSON.stringify(receipt)).toString('base64'),
+            },
+        };
+        const post = vi.fn().mockResolvedValue(respond(200, { ok: true, receipt }));
+        const enclave = createRemoteEnclave({ baseUrl, token, timeoutMs, transport: { post } });
+        const input = {
+            envelope,
+            hold: v2,
+            expectedDid: v2.hold.did,
+            clientEphemeralPublicKey: v2.hold.clientEphemeralPublicKey,
+            requestId: 'stable-id',
+        };
+        await expect(enclave.cancelHold(input)).resolves.toEqual({ receipt });
+        post.mockResolvedValue(respond(200, { sealed: envelope, receipt }));
+        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);
+        post.mockResolvedValue(respond(200, { ok: true }));
+        await expect(enclave.cancelHold(input)).rejects.toBeInstanceOf(EscrowUnavailableError);
+    });
+
+    // [A] confirm-hold/send-release-warning: a fresh call returns a signed
+    // `commit`; an idempotent retry (lost response, hourly job re-run)
+    // returns a signed `snapshot` instead — both are real response shapes
+    // the enclave can return, never a stub that only ever returns `commit`.
+    const confirmInput = {
+        envelope,
+        hold,
+        clientEphemeralPublicKey: hold.hold.clientEphemeralPublicKey,
+        expectedDid: hold.hold.did,
+        code: '12345678',
+    };
+    it('confirmHold accepts a fresh commit receipt and returns the authoritative confirmation time', async () => {
+        const post = vi
+            .fn()
+            .mockResolvedValue(
+                respond(200, { confirmed: true, receipt, confirmedHiMs: 1700000000000 })
+            );
+        const enclave = createRemoteEnclave({ baseUrl, token, timeoutMs, transport: { post } });
+
+        await expect(enclave.confirmHold!(confirmInput)).resolves.toEqual({
+            receipt,
+            confirmedAtMs: 1700000000000,
+        });
+    });
+    it('confirmHold accepts a retry snapshot receipt (not a commit) and returns the SAME confirmation time', async () => {
+        const post = vi.fn().mockResolvedValue(
+            respond(200, {
+                confirmed: true,
+                receipt: snapshotReceipt,
+                confirmedHiMs: 1700000000000,
+            })
+        );
+        const enclave = createRemoteEnclave({ baseUrl, token, timeoutMs, transport: { post } });
+
+        await expect(enclave.confirmHold!(confirmInput)).resolves.toEqual({
+            receipt: snapshotReceipt,
+            confirmedAtMs: 1700000000000,
+        });
+    });
+    it('confirmHold fails closed when the receipt is neither a commit nor a snapshot', async () => {
+        const post = vi.fn().mockResolvedValue(
+            respond(200, {
+                confirmed: true,
+                receipt: { ...receipt, kind: 'proposal' },
+                confirmedHiMs: 1700000000000,
+            })
+        );
+        const enclave = createRemoteEnclave({ baseUrl, token, timeoutMs, transport: { post } });
+
+        await expect(enclave.confirmHold!(confirmInput)).rejects.toBeInstanceOf(
+            EscrowUnavailableError
+        );
+    });
+    it('confirmHold fails closed when confirmedHiMs is missing (pre-fix response shape)', async () => {
+        const post = vi.fn().mockResolvedValue(respond(200, { confirmed: true, receipt }));
+        const enclave = createRemoteEnclave({ baseUrl, token, timeoutMs, transport: { post } });
+
+        await expect(enclave.confirmHold!(confirmInput)).rejects.toBeInstanceOf(
+            EscrowUnavailableError
+        );
+    });
+
+    const warningInput = { holdId: hold.hold.holdId, expectedDid: hold.hold.did };
+    it('sendReleaseWarning accepts a fresh commit receipt and returns the authoritative send time', async () => {
+        const post = vi
+            .fn()
+            .mockResolvedValue(
+                respond(200, { sent: true, receipt, releaseWarningSentHiMs: 1700086400000 })
+            );
+        const enclave = createRemoteEnclave({ baseUrl, token, timeoutMs, transport: { post } });
+
+        await expect(enclave.sendReleaseWarning!(warningInput)).resolves.toEqual({
+            receipt,
+            releaseWarningSentAtMs: 1700086400000,
+        });
+    });
+    it('sendReleaseWarning accepts a retry snapshot receipt (not a commit) and returns the SAME send time', async () => {
+        const post = vi.fn().mockResolvedValue(
+            respond(200, {
+                sent: true,
+                receipt: snapshotReceipt,
+                releaseWarningSentHiMs: 1700086400000,
+            })
+        );
+        const enclave = createRemoteEnclave({ baseUrl, token, timeoutMs, transport: { post } });
+
+        await expect(enclave.sendReleaseWarning!(warningInput)).resolves.toEqual({
+            receipt: snapshotReceipt,
+            releaseWarningSentAtMs: 1700086400000,
+        });
+    });
+    it('sendReleaseWarning fails closed when releaseWarningSentHiMs is missing (pre-fix response shape)', async () => {
+        const post = vi.fn().mockResolvedValue(respond(200, { sent: true, receipt }));
+        const enclave = createRemoteEnclave({ baseUrl, token, timeoutMs, transport: { post } });
+
+        await expect(enclave.sendReleaseWarning!(warningInput)).rejects.toBeInstanceOf(
+            EscrowUnavailableError
+        );
+    });
+
+    it('forwards signed enrollment once and rejects a proposal or mismatched result generation', async () => {
+        const input = {
+            signedIntent: {
+                intent: {
+                    version: 2 as const,
+                    tenant: 'learncard',
+                    did: 'did:key:z6MktwupdmLXVVqTzCw4i46r4uGyosGXRnR3XjN4Zq7oMMsw',
+                    authorityGeneration: 'g1',
+                    expectedEnrollmentVersion: 0,
+                    action: 'enroll' as const,
+                    sourceBlobIdentity: null,
+                    targetBlobIdentity: 'ab'.repeat(32),
+                    pinAction: 'keep' as const,
+                    shareVersion: 1,
+                    enrollmentEpoch: 1,
+                    requestId: 'request',
+                    allowRewrap: true,
+                    recoveryEmail: 'owner@example.com',
+                    recoveryLanguage: 'en',
+                },
+                signature: Buffer.alloc(64).toString('base64'),
+            },
+            sourceEnvelope: null,
+            targetEnvelope: envelope,
+        };
+        const result = {
+            envelope,
+            receipt,
+            authorityGeneration: 'g1',
+            enrollmentVersion: 1,
+            enrollmentEpoch: 1,
+        };
+        const post = vi.fn().mockResolvedValue(respond(200, { result }));
+        const enclave = createRemoteEnclave({ baseUrl, token, timeoutMs, transport: { post } });
+        await expect(enclave.applyEnrollmentIntent!(input)).resolves.toEqual(result);
+        expect(post).toHaveBeenCalledTimes(1);
+        expect(post.mock.calls[0]?.slice(0, 2)).toEqual([`${baseUrl}/v1/apply-enrollment`, input]);
+        post.mockResolvedValue(respond(200, { result: { ...result, authorityGeneration: 'g2' } }));
+        await expect(enclave.applyEnrollmentIntent!(input)).rejects.toBeInstanceOf(
+            EscrowUnavailableError
+        );
+        post.mockResolvedValue(
+            respond(200, { result: { ...result, receipt: { ...receipt, kind: 'proposal' } } })
+        );
+        await expect(enclave.applyEnrollmentIntent!(input)).rejects.toBeInstanceOf(
+            EscrowUnavailableError
+        );
+    });
+
     it.each([
         ['policy', EscrowPolicyError],
         ['pinMismatch', EscrowPinMismatchError],

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

@@ -1,6 +1,13 @@
 import { Agent } from 'node:https';
 import axios from 'axios';
 import { z } from 'zod';
+import {
+    AuthorityCommitValidator,
+    AuthorityHoldReceiptValidator,
+    AuthorityMutationValidator,
+    AuthorityStateResponseValidator,
+    safeInteger,
+} from './authorityContract';
 import {
     ESCROW_ALGORITHM,
     ESCROW_ENVELOPE_VERSION,
@@ -12,11 +19,14 @@ import {
     EscrowPolicyError,
     EscrowUnavailableError,
     type CarryPinVerifierInput,
+    type ConfirmHoldRequest,
     type EnclaveAttestation,
     type EscrowEnclave,
     type ReleaseRequest,
     type ReleaseResult,
+    type ResendCodeRequest,
     type RewrapEscrowBlobInput,
+    type SendReleaseWarningRequest,
     type VerifyEscrowBlobInput,
     type VerifyEscrowBlobResult,
 } from './types';
@@ -58,7 +68,6 @@ const verifyBlobResponseValidator = z.union([
 ]);
 
 const carryPinVerifierResponseValidator = z.object({ envelope: envelopeValidator });
-const rewrapEscrowBlobResponseValidator = z.object({ envelope: envelopeValidator });
 
 // Opaque SignedHoldRecord JSON: validate shape while preserving signed extensions.
 const holdRecordValidator = z
@@ -74,8 +83,8 @@ const holdRecordValidator = z
                 clientEphemeralPublicKey: z.string().min(1),
                 createdLo: z.number().int().nonnegative(),
                 createdHi: z.number().int().nonnegative(),
-                policyVersion: z.number().int().positive(),
-                signature: z.string().min(1),
+                policyVersion: z.union([z.literal(1), z.literal(2)]),
+                signature: z.string().min(1).max(8192),
             })
             .passthrough(),
         holdDurationMs: z.number().int().nonnegative(),
@@ -84,9 +93,21 @@ const holdRecordValidator = z
     .passthrough();
 const validatedHold = (hold: ReleaseRequest['hold']): ReleaseRequest['hold'] => {
     if (!holdRecordValidator.safeParse(hold).success) throw new EscrowUnavailableError();
+    if (hold.hold.policyVersion === 2) {
+        try {
+            AuthorityCommitValidator.parse(
+                JSON.parse(Buffer.from(hold.hold.signature, 'base64').toString('utf8'))
+            );
+        } catch {
+            throw new EscrowUnavailableError();
+        }
+    }
     return hold;
 };
-const releaseResponseValidator = z.object({ sealed: envelopeValidator });
+const releaseResponseValidator = z.object({
+    sealed: envelopeValidator,
+    receipt: AuthorityCommitValidator.optional(),
+});
 
 const errorCodeValidator = z.enum([
     'policy',
@@ -181,6 +202,24 @@ export const createRemoteEnclave = (config: RemoteEnclaveConfig): EscrowEnclave
     };
 
     return {
+        getEnrollmentState: input =>
+            call('/v1/enrollment-state', input, AuthorityStateResponseValidator),
+        applyEnrollmentIntent: async input => {
+            const { result } = await call(
+                '/v1/apply-enrollment',
+                input,
+                z.object({ result: AuthorityMutationValidator }).strict()
+            );
+            if (
+                result.authorityGeneration !== input.signedIntent.intent.authorityGeneration ||
+                result.enrollmentVersion !==
+                    input.signedIntent.intent.expectedEnrollmentVersion + 1 ||
+                result.enrollmentEpoch !== input.signedIntent.intent.enrollmentEpoch ||
+                (result.envelope === null) !== (input.signedIntent.intent.action === 'disable')
+            )
+                throw new EscrowUnavailableError();
+            return result;
+        },
         getAttestation: (nonce?: Uint8Array): Promise<EnclaveAttestation> =>
             call('/v1/attest', { nonce: Array.from(nonce ?? []) }, attestResponseValidator),
         verifyEscrowBlob: (input: VerifyEscrowBlobInput): Promise<VerifyEscrowBlobResult> =>
@@ -207,47 +246,110 @@ export const createRemoteEnclave = (config: RemoteEnclaveConfig): EscrowEnclave
                 },
                 carryPinVerifierResponseValidator
             ),
-        rewrapEscrowBlob: (input: RewrapEscrowBlobInput): Promise<{ envelope: EscrowEnvelope }> =>
-            call(
-                '/v1/rewrap-escrow-blob',
+        rewrapEscrowBlob: async (input: RewrapEscrowBlobInput) => {
+            const { result } = await call(
+                '/v1/authority-rewrap',
                 {
                     envelope: input.envelope,
                     expectedDid: input.expectedDid,
                     expectedShareVersion: input.expectedShareVersion,
                     sourceEnrollmentEpoch: input.sourceEnrollmentEpoch,
                 },
-                rewrapEscrowBlobResponseValidator
-            ),
+                z.object({ result: AuthorityMutationValidator }).strict()
+            );
+            if (!result.envelope || result.enrollmentEpoch !== input.sourceEnrollmentEpoch)
+                throw new EscrowUnavailableError();
+            return { envelope: result.envelope, authority: result };
+        },
         createHold: async input => ({
-            holdRecord: await call(
-                '/v1/create-hold',
+            holdRecord: validatedHold(
+                await call(
+                    '/v1/create-hold',
+                    {
+                        envelope: input.envelope,
+                        holdId: input.holdId,
+                        expectedDid: input.expectedDid,
+                        expectedShareVersion: input.expectedShareVersion,
+                        enrollmentEpoch: input.enrollmentEpoch,
+                        releasePolicy: input.releasePolicy,
+                        clientEphemeralPublicKey: input.clientEphemeralPublicKey,
+                    },
+                    holdRecordValidator
+                )
+            ),
+        }),
+        cancelHold: async input => {
+            const result = await call(
+                '/v1/cancel-hold',
                 {
                     envelope: input.envelope,
-                    holdId: input.holdId,
+                    hold: validatedHold(input.hold),
+                    clientEphemeralPublicKey: input.clientEphemeralPublicKey,
                     expectedDid: input.expectedDid,
-                    expectedShareVersion: input.expectedShareVersion,
-                    enrollmentEpoch: input.enrollmentEpoch,
-                    releasePolicy: input.releasePolicy,
+                    ...(input.requestId ? { requestId: input.requestId } : {}),
+                },
+                z.object({ ok: z.literal(true), receipt: AuthorityCommitValidator.optional() })
+            );
+            if (input.hold.hold.policyVersion === 2 && !result.receipt)
+                throw new EscrowUnavailableError();
+            if (result.receipt) return { receipt: result.receipt };
+            return undefined;
+        },
+        confirmHold: async (input: ConfirmHoldRequest) => {
+            const result = await call(
+                '/v1/confirm-hold',
+                {
+                    envelope: input.envelope,
+                    hold: validatedHold(input.hold),
                     clientEphemeralPublicKey: input.clientEphemeralPublicKey,
+                    expectedDid: input.expectedDid,
+                    code: input.code,
+                    ...(input.requestId ? { requestId: input.requestId } : {}),
                 },
-                holdRecordValidator
-            ),
-        }),
-        cancelHold: async input => {
-            await call(
-                '/v1/cancel-hold',
+                z.object({
+                    confirmed: z.literal(true),
+                    receipt: AuthorityHoldReceiptValidator,
+                    confirmedHiMs: safeInteger,
+                })
+            );
+            return { receipt: result.receipt, confirmedAtMs: result.confirmedHiMs };
+        },
+        resendCode: async (input: ResendCodeRequest) => {
+            const result = await call(
+                '/v1/resend-code',
                 {
                     envelope: input.envelope,
                     hold: validatedHold(input.hold),
                     clientEphemeralPublicKey: input.clientEphemeralPublicKey,
                     expectedDid: input.expectedDid,
+                    ...(input.requestId ? { requestId: input.requestId } : {}),
+                },
+                z.object({ sent: z.literal(true), receipt: AuthorityCommitValidator })
+            );
+            return { receipt: result.receipt };
+        },
+        sendReleaseWarning: async (input: SendReleaseWarningRequest) => {
+            const result = await call(
+                '/v1/send-release-warning',
+                {
+                    holdId: input.holdId,
+                    expectedDid: input.expectedDid,
+                    ...(input.requestId ? { requestId: input.requestId } : {}),
                 },
-                z.object({ ok: z.literal(true) })
+                z.object({
+                    sent: z.literal(true),
+                    receipt: AuthorityHoldReceiptValidator,
+                    releaseWarningSentHiMs: safeInteger,
+                })
             );
+            return {
+                receipt: result.receipt,
+                releaseWarningSentAtMs: result.releaseWarningSentHiMs,
+            };
         },
         releaseEscrow: async (input: ReleaseRequest): Promise<ReleaseResult> => {
             validatedHold(input.hold);
-            return call(
+            const result = await call(
                 '/v1/release',
                 {
                     envelope: input.envelope,
@@ -255,9 +357,13 @@ export const createRemoteEnclave = (config: RemoteEnclaveConfig): EscrowEnclave
                     clientEphemeralPublicKey: input.clientEphemeralPublicKey,
                     expectedDid: input.expectedDid,
                     ...(input.pinProof !== undefined ? { pinProof: input.pinProof } : {}),
+                    ...(input.requestId ? { requestId: input.requestId } : {}),
                 },
                 releaseResponseValidator
             );
+            if (input.hold.hold.policyVersion === 2 && !result.receipt)
+                throw new EscrowUnavailableError();
+            return result;
         },
     };
 };