@learncard/lca-api-service 1.3.2 → 1.5.0

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

@@ -0,0 +1,34 @@
+/**
+ * Private CAs for enclave-host TLS, pinned per hostname. When a CA is pinned
+ * the remote-enclave transport trusts ONLY that CA (not the system roots), and
+ * nothing else in lca-api trusts it. Changing a trust anchor is a reviewed
+ * code change, never an environment edit.
+ *
+ * Each CA is name-constrained to its single hostname; see
+ * services/escrow-enclave-app/STAGING.md section 4a.
+ */
+const ENCLAVE_TRUST_ANCHORS: Readonly<Record<string, string>> = {
+    // Staging CA, valid until 2029-09-30. SHA-256 1BB676B1B969A916497AB7386A81AEBD
+    // 903469ED4B124685F43513B5FCB9E010; source: SSM
+    // /learncard/escrow-enclave/staging/ca-cert in account 217358003896.
+    'escrow-enclave.staging.internal': `-----BEGIN CERTIFICATE-----
+MIICgTCCAgigAwIBAgIUe/8u9Uy/Y9jD4Aw+cZCIeU/yap0wCgYIKoZIzj0EAwMw
+VDEkMCIGA1UECgwbTGVhcm5pbmcgRWNvbm9teSBGb3VuZGF0aW9uMSwwKgYDVQQD
+DCNMZWFybkNhcmQgRXNjcm93IEVuY2xhdmUgU3RhZ2luZyBDQTAeFw0yNjEwMDEy
+MTI1MDJaFw0yOTA5MzAyMTI1MDJaMFQxJDAiBgNVBAoMG0xlYXJuaW5nIEVjb25v
+bXkgRm91bmRhdGlvbjEsMCoGA1UEAwwjTGVhcm5DYXJkIEVzY3JvdyBFbmNsYXZl
+IFN0YWdpbmcgQ0EwdjAQBgcqhkjOPQIBBgUrgQQAIgNiAARSwi8GmnzoqYadKw9n
+gc7kOMMbimXjF5weA8YCOBhiaNHAxRcYJ0iz1nv74wYt/8x9lvwkFP4IK36i+bdH
+fiu6Oo34LXi3AHBbQvL5A2c2IELil6Cea+ClWtJLfWDu7OOjgZowgZcwHwYDVR0j
+BBgwFoAUybGIxOfLHqqbjDFJ1k28v4aKh4IwEgYDVR0TAQH/BAgwBgEB/wIBADAO
+BgNVHQ8BAf8EBAMCAQYwMQYDVR0eAQH/BCcwJaAjMCGCH2VzY3Jvdy1lbmNsYXZl
+LnN0YWdpbmcuaW50ZXJuYWwwHQYDVR0OBBYEFMmxiMTnyx6qm4wxSdZNvL+GioeC
+MAoGCCqGSM49BAMDA2cAMGQCMGp/wTQLmtB6/GK6hMFaFTA27gXZcxrgJ0Uy+8C0
+Ztl5uoRwN99inHNWv1cnKGdNQgIwSoQgKs8uMnBUcfiB9ZR6xb98z/9athp5pDIE
+/KUv6cNmJtuCgPOJxC+4fVKl8xC3
+-----END CERTIFICATE-----
+`,
+};
+
+export const pinnedEnclaveCa = (baseUrl: string): string | undefined =>
+    ENCLAVE_TRUST_ANCHORS[new URL(baseUrl).hostname];

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

@@ -0,0 +1,174 @@
+import {
+    environment,
+    parseLcaApiEnvironment,
+    parseEscrowPrivateKeys,
+    type LcaApiEnvironment,
+} from '@environment';
+import type { EscrowBlobStaleReason } from '@learncard/types';
+import { SoftwareEnclave } from './softwareEnclave';
+import { createRemoteEnclave } from './remoteEnclave';
+import { pinnedEnclaveCa } from './enclaveTrustAnchors';
+import { EscrowUnavailableError, type EscrowEnclave } from './types';
+
+export * from './types';
+export * from './softwareEnclave';
+export * from './remoteEnclave';
+export * from './notifications';
+
+let enclave: EscrowEnclave | undefined;
+let config: LcaApiEnvironment = environment;
+
+// 'software' config validity is enforced at environment-parse time (see
+// config/environment.ts), so reaching that branch always means it's ready.
+// 'remote' config (URL/token) is deliberately NOT required at parse time, so
+// its readiness is checked here instead; missing it fails this closed rather
+// than crashing the whole service at boot.
+export const isEscrowEnabled = (): boolean => {
+    if (config.ESCROW_ENCLAVE_MODE === 'software') {
+        // Serverless injects the actual deploy stage; NODE_ENV often remains development
+        // in Lambda. Unknown deployed stages fail closed, regardless of offline flags.
+        const allowed = config.LAMBDA_STAGE
+            ? ['dev', 'development', 'staging', 'test', 'local'].includes(config.LAMBDA_STAGE)
+            : config.NODE_ENV !== 'production';
+        if (!allowed) console.error('[escrow] Software enclave disabled for this deploy stage');
+        return allowed;
+    }
+    if (config.ESCROW_ENCLAVE_MODE === 'remote') {
+        return Boolean(config.ESCROW_ENCLAVE_REMOTE_URL && config.ESCROW_ENCLAVE_REMOTE_TOKEN);
+    }
+    return false;
+};
+export const isEscrowRemoteMode = (): boolean => config.ESCROW_ENCLAVE_MODE === 'remote';
+// The client-facing attestation mode implied by the server's active backend
+// ('remote' mode always attests as 'nitro' — see remoteEnclave.ts).
+export const activeEscrowClientMode = (): 'software' | 'nitro' =>
+    isEscrowRemoteMode() ? 'nitro' : 'software';
+export const getEscrowHoldDurationMs = (): number => config.ESCROW_HOLD_DURATION_MS;
+export const getEscrowHoldRestartMinAgeMs = (): number => config.ESCROW_HOLD_RESTART_MIN_AGE_MS;
+export const getEscrowEnclave = (): EscrowEnclave => {
+    if (!isEscrowEnabled()) throw new EscrowUnavailableError();
+    if (enclave) return enclave;
+    if (config.ESCROW_ENCLAVE_MODE === 'software') {
+        enclave = new SoftwareEnclave({
+            privateKeys: parseEscrowPrivateKeys(
+                config.ESCROW_ENCLAVE_SOFTWARE_PRIVATE_KEYS_JSON ?? ''
+            ),
+            activeKeyId: config.ESCROW_ENCLAVE_ACTIVE_KEY_ID ?? '',
+            holdDurationMs: getEscrowHoldDurationMs(),
+        });
+        return enclave;
+    }
+    if (config.ESCROW_ENCLAVE_MODE === 'remote') {
+        const { ESCROW_ENCLAVE_REMOTE_URL: baseUrl, ESCROW_ENCLAVE_REMOTE_TOKEN: token } = config;
+        if (!baseUrl || !token) throw new EscrowUnavailableError();
+        enclave = createRemoteEnclave({
+            baseUrl,
+            token,
+            timeoutMs: config.ESCROW_ENCLAVE_REMOTE_TIMEOUT_MS,
+            caPem: pinnedEnclaveCa(baseUrl),
+        });
+        return enclave;
+    }
+    throw new EscrowUnavailableError();
+};
+
+export type { EscrowBlobStaleReason };
+
+interface EscrowAttestationIdentity {
+    keyId: string;
+    /** P9.1: retired keyIds the enclave still accepts for decrypt only. */
+    previousKeyIds: string[];
+    mode: 'software' | 'nitro';
+}
+interface EscrowAttestationCacheEntry extends EscrowAttestationIdentity {
+    fetchedAt: number;
+}
+
+// Keeps every login's status check off the enclave's critical path (a remote
+// nitro backend can be slow or briefly unreachable; a normal sign-in must
+// never wait on it). TTL and budget are process-local constants, not env
+// config, since neither is an operator-facing tuning knob.
+const ESCROW_ATTESTATION_CACHE_TTL_MS = 5 * 60 * 1000;
+const ESCROW_ATTESTATION_STATUS_BUDGET_MS = 250;
+
+let attestationCache: EscrowAttestationCacheEntry | undefined;
+let attestationRefreshInFlight: Promise<EscrowAttestationIdentity> | undefined;
+
+const isAttestationCacheFresh = (): boolean =>
+    !!attestationCache && Date.now() - attestationCache.fetchedAt < ESCROW_ATTESTATION_CACHE_TTL_MS;
+
+// Single-flight: any number of concurrent cold-cache callers (status checks
+// and release-enforcement checks alike) share one underlying getAttestation()
+// call and its outcome, so a cache-expiry moment never causes a call fan-out
+// to the enclave. Clears the in-flight marker on settle either way so the
+// next cold call starts a fresh fetch; only a successful fetch warms the cache.
+const refreshAttestationCache = (): Promise<EscrowAttestationIdentity> => {
+    attestationRefreshInFlight ??= (async () => {
+        try {
+            const attestation = await getEscrowEnclave().getAttestation();
+            const identity: EscrowAttestationIdentity = {
+                keyId: attestation.keyId,
+                previousKeyIds: attestation.previousKeyIds ?? [],
+                mode: attestation.mode,
+            };
+            attestationCache = { ...identity, fetchedAt: Date.now() };
+            return identity;
+        } finally {
+            attestationRefreshInFlight = undefined;
+        }
+    })();
+    return attestationRefreshInFlight;
+};
+
+/**
+ * Fail-closed identity lookup for release enforcement (startRecovery /
+ * completeRecovery): resolves instantly from a warm cache, otherwise awaits a
+ * real getAttestation() call (subject to the enclave's own normal timeout,
+ * e.g. `ESCROW_ENCLAVE_REMOTE_TIMEOUT_MS`) and lets a failure propagate — a
+ * caller here must never treat an unreachable enclave as "fresh".
+ */
+export const getEnclaveAttestationIdentity = (): Promise<EscrowAttestationIdentity> =>
+    isAttestationCacheFresh() ? Promise.resolve(attestationCache!) : refreshAttestationCache();
+
+// Best-effort status check (used for the client's read-only enrollment state
+// on every sign-in — see routes/keys.ts's getAuthShare — not for release
+// enforcement; see getEnclaveAttestationIdentity above for the fail-closed
+// version). Never awaits the enclave directly: a cold/failed cache still
+// returns "not stale" within ESCROW_ATTESTATION_STATUS_BUDGET_MS, while a
+// background refresh (already in flight, or started here) continues so a
+// later call can see a warm cache.
+export const getEscrowBlobStaleReason = async (blob: {
+    enclaveMode: 'software' | 'nitro';
+    enclaveKeyId: string;
+}): Promise<EscrowBlobStaleReason | undefined> => {
+    if (!isEscrowEnabled()) return undefined;
+    if (blob.enclaveMode !== activeEscrowClientMode()) return 'mode-mismatch';
+    if (isAttestationCacheFresh()) {
+        return blob.enclaveKeyId !== attestationCache!.keyId ? 'key-rotated' : undefined;
+    }
+    const identity = await Promise.race([
+        refreshAttestationCache().catch(() => undefined),
+        new Promise<undefined>(resolve => {
+            setTimeout(() => resolve(undefined), ESCROW_ATTESTATION_STATUS_BUDGET_MS);
+        }),
+    ]);
+    return identity && blob.enclaveKeyId !== identity.keyId ? 'key-rotated' : undefined;
+};
+
+/** Reset both singleton and environment snapshot after test environment changes. */
+export const __setEscrowEnclaveForTests = (replacement: EscrowEnclave | undefined): void => {
+    if (environment.NODE_ENV !== 'test') throw new EscrowUnavailableError();
+    config = parseLcaApiEnvironment(process.env);
+    enclave = replacement;
+    attestationCache = undefined;
+    attestationRefreshInFlight = undefined;
+};
+
+/** Invalidate the attestation cache without replacing the enclave singleton
+ * (e.g. to force the next freshness check to re-fetch against the same
+ * enclave, or to isolate tests from each other's cached state). */
+export const __resetEscrowAttestationCacheForTests = (): void => {
+    if (environment.NODE_ENV !== 'test') throw new EscrowUnavailableError();
+    attestationCache = undefined;
+    attestationRefreshInFlight = undefined;
+};

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

@@ -0,0 +1,377 @@
+import { describe, it, expect, vi } from 'vitest';
+import * as Sentry from '@sentry/serverless';
+
+import type { EscrowHold, MongoUserKeyType, RecoveryMethod } from '@models';
+import type { TemplateNotification } from '../delivery';
+import {
+    notifyEscrowHoldEvent,
+    ESCROW_NOTIFICATION_TIMEOUT_MS,
+    type EscrowHoldNotifierDeps,
+    type EscrowHoldEventKind,
+} from './notifications';
+
+const baseUserKey = (overrides: Partial<MongoUserKeyType> = {}): MongoUserKeyType => {
+    const now = new Date();
+    return {
+        contactMethod: { type: 'email', value: 'owner@example.com' },
+        authProviders: [{ type: 'firebase', id: 'user-1' }],
+        primaryDid: 'did:key:owner',
+        linkedDids: [],
+        keyProvider: 'sss',
+        shareVersion: 1,
+        previousAuthShares: [],
+        securityLevel: 'basic',
+        recoveryMethods: [],
+        migratedFromWeb3Auth: false,
+        createdAt: now,
+        updatedAt: now,
+        ...overrides,
+    };
+};
+
+const baseHold = (overrides: Partial<EscrowHold> = {}): EscrowHold => {
+    const now = new Date();
+    return {
+        holdRecord: {
+            hold: {
+                holdId: 'hold-1',
+                did: 'did:key:owner',
+                shareVersion: 1,
+                blobHash: 'ab'.repeat(32),
+                enrollmentEpoch: 1,
+                releasePolicy: 'hold',
+                clientEphemeralPublicKey: 'public-key',
+                createdLo: 0,
+                createdHi: 0,
+                policyVersion: 1,
+                signature: 'test-signature',
+            },
+            holdDurationMs: 0,
+            ledgerSeq: 0,
+        },
+        _id: 'hold-1',
+        authProvider: { type: 'firebase', id: 'user-1' },
+        primaryDid: 'did:key:owner',
+        shareVersion: 1,
+        status: 'pending',
+        identityProofType: 'auth-token',
+        requestedAt: now,
+        releaseAfter: now,
+        releasePolicy: 'hold',
+        clientEphemeralPublicKey: 'client-pub',
+        resumeTokenHash: 'a'.repeat(64),
+        notifications: [],
+        createdAt: now,
+        updatedAt: now,
+        ...overrides,
+    };
+};
+
+const confirmedRecoveryMethod = (confirmationEmail: string): RecoveryMethod => ({
+    type: 'email',
+    createdAt: new Date(),
+    confirmationStatus: 'confirmed',
+    confirmedAt: new Date(),
+    confirmationEmail,
+});
+
+const pendingRecoveryMethod = (confirmationEmail: string): RecoveryMethod => ({
+    type: 'email',
+    createdAt: new Date(),
+    confirmationStatus: 'pending',
+    confirmationEmail,
+});
+
+const makeDeps = (overrides: Partial<EscrowHoldNotifierDeps> = {}) => {
+    const sent: TemplateNotification[] = [];
+    const pushCalls: unknown[] = [];
+    const recorded: { holdId: string; kind: EscrowHoldEventKind }[] = [];
+    const deps: EscrowHoldNotifierDeps = {
+        send: async notification => {
+            sent.push(notification as TemplateNotification);
+        },
+        sendPush: async (notification): ReturnType<EscrowHoldNotifierDeps['sendPush']> => {
+            pushCalls.push(notification);
+            return { successCount: 1, failureCount: 0, failedTokens: [] };
+        },
+        now: () => new Date('2026-01-01T00:00:00.000Z'),
+        rotateCancelToken: async () => 'b'.repeat(64),
+        recordNotification: async (holdId, kind) => {
+            recorded.push({ holdId, kind });
+        },
+        ...overrides,
+    };
+    return { deps, sent, pushCalls, recorded };
+};
+
+describe('notifyEscrowHoldEvent', () => {
+    it('emails every verified address deduped case-insensitively, excluding unconfirmed methods', async () => {
+        const userKey = baseUserKey({
+            contactMethod: { type: 'email', value: 'Owner@Example.com' },
+            recoveryEmail: 'owner@example.com',
+            recoveryEmailVerifiedAt: new Date(),
+            recoveryMethods: [
+                confirmedRecoveryMethod('secondary@example.com'),
+                pendingRecoveryMethod('attacker@example.com'),
+            ],
+        });
+        const hold = baseHold({ completedAt: new Date() });
+        const { deps, sent } = makeDeps();
+
+        await notifyEscrowHoldEvent({ kind: 'completed', hold, userKey }, deps);
+
+        const recipients = sent.map(n => n.to).sort();
+        expect(recipients).toEqual(['owner@example.com', 'secondary@example.com']);
+    });
+
+    it('excludes a recoveryEmail that lacks recoveryEmailVerifiedAt', async () => {
+        const userKey = baseUserKey({
+            contactMethod: { type: 'phone', value: '+15555550100' },
+            recoveryEmail: 'unverified@example.com',
+        });
+        const hold = baseHold({ completedAt: new Date() });
+        const { deps, sent } = makeDeps();
+
+        await notifyEscrowHoldEvent({ kind: 'completed', hold, userKey }, deps);
+
+        expect(sent).toHaveLength(0);
+    });
+
+    it('sends the started email with a cancel link built from the plaintext cancelToken, never rotating', async () => {
+        const userKey = baseUserKey();
+        const hold = baseHold();
+        const rotateCancelToken = vi.fn(async () => {
+            throw new Error('must not rotate for started');
+        });
+        const { deps, sent } = makeDeps({ rotateCancelToken });
+        const cancelToken = 'a'.repeat(64);
+
+        await notifyEscrowHoldEvent({ kind: 'started', hold, userKey, cancelToken }, deps);
+
+        expect(rotateCancelToken).not.toHaveBeenCalled();
+        expect(sent).toHaveLength(1);
+        expect(sent[0]!.templateAlias).toBe('escrow-hold-started');
+        expect(sent[0]!.templateModel.cancelUrl).toContain(cancelToken);
+        expect(sent[0]!.templateModel.cancelUrl).toContain(hold._id);
+    });
+
+    it('rotates a fresh cancel token for reminder emails', async () => {
+        const userKey = baseUserKey();
+        const hold = baseHold();
+        const rotateCancelToken = vi.fn(async () => 'c'.repeat(64));
+        const { deps, sent } = makeDeps({ rotateCancelToken });
+
+        await notifyEscrowHoldEvent({ kind: 'reminder', hold, userKey }, deps);
+
+        expect(rotateCancelToken).toHaveBeenCalledWith(hold._id);
+        expect(sent[0]!.templateAlias).toBe('escrow-hold-reminder');
+        expect(sent[0]!.templateModel.cancelUrl).toContain('c'.repeat(64));
+    });
+
+    it('pin-locked with an active waiting-period hold rotates that hold (not the PIN hold) and links to it', async () => {
+        const userKey = baseUserKey();
+        // The PIN hold itself is already terminal by the time 'pin-locked' fires.
+        const hold = baseHold({
+            _id: 'pin-hold',
+            releasePolicy: 'pin',
+            status: 'cancelled',
+            cancelledBy: 'system',
+            cancelReason: 'pin-locked',
+        });
+        const activeHold = baseHold({
+            _id: 'active-hold',
+            releasePolicy: 'hold',
+            status: 'pending',
+        });
+        const rotateCancelToken = vi.fn(async () => 'd'.repeat(64));
+        const { deps, sent } = makeDeps({ rotateCancelToken });
+
+        await notifyEscrowHoldEvent({ kind: 'pin-locked', hold, userKey, activeHold }, deps);
+
+        expect(rotateCancelToken).toHaveBeenCalledExactlyOnceWith(activeHold._id);
+        expect(sent[0]!.templateAlias).toBe('escrow-pin-locked');
+        expect(sent[0]!.templateModel.cancelUrl).toContain('d'.repeat(64));
+        expect(sent[0]!.templateModel.cancelUrl).toContain(activeHold._id);
+        expect(sent[0]!.templateModel.releaseAfter).toBe(activeHold.releaseAfter.toISOString());
+    });
+
+    it('pin-locked without an active hold sends no cancelUrl/releaseAfter and never rotates the PIN hold', async () => {
+        const userKey = baseUserKey();
+        const hold = baseHold({
+            _id: 'pin-hold',
+            releasePolicy: 'pin',
+            status: 'cancelled',
+            cancelledBy: 'system',
+            cancelReason: 'pin-locked',
+        });
+        const rotateCancelToken = vi.fn(async () => 'e'.repeat(64));
+        const { deps, sent } = makeDeps({ rotateCancelToken });
+
+        await notifyEscrowHoldEvent({ kind: 'pin-locked', hold, userKey }, deps);
+
+        expect(rotateCancelToken).not.toHaveBeenCalled();
+        expect(sent[0]!.templateAlias).toBe('escrow-pin-locked');
+        expect(sent[0]!.templateModel).not.toHaveProperty('cancelUrl');
+        expect(sent[0]!.templateModel).not.toHaveProperty('releaseAfter');
+    });
+
+    it('pin-locked treats a non-pending activeHold the same as no active hold', async () => {
+        const userKey = baseUserKey();
+        const hold = baseHold({ _id: 'pin-hold', releasePolicy: 'pin', status: 'cancelled' });
+        const activeHold = baseHold({ _id: 'stale-hold', status: 'completed' });
+        const rotateCancelToken = vi.fn(async () => 'f'.repeat(64));
+        const { deps, sent } = makeDeps({ rotateCancelToken });
+
+        await notifyEscrowHoldEvent({ kind: 'pin-locked', hold, userKey, activeHold }, deps);
+
+        expect(rotateCancelToken).not.toHaveBeenCalled();
+        expect(sent[0]!.templateModel).not.toHaveProperty('cancelUrl');
+    });
+
+    it('skips the reminder email entirely when a fresh token cannot be issued', async () => {
+        const userKey = baseUserKey();
+        const hold = baseHold();
+        const { deps, sent } = makeDeps({ rotateCancelToken: async () => null });
+
+        await notifyEscrowHoldEvent({ kind: 'reminder', hold, userKey }, deps);
+
+        expect(sent).toHaveLength(0);
+    });
+
+    it('sends a push notification to the account DID for every kind', async () => {
+        const userKey = baseUserKey({ contactMethod: { type: 'phone', value: '+15555550100' } });
+        const hold = baseHold();
+        const { deps, sent, pushCalls } = makeDeps();
+
+        await notifyEscrowHoldEvent(
+            { kind: 'started', hold, userKey, cancelToken: 'a'.repeat(64) },
+            deps
+        );
+
+        expect(sent).toHaveLength(0);
+        expect(pushCalls).toEqual([
+            expect.objectContaining({ type: 'APP_NOTIFICATION', to: { did: userKey.primaryDid } }),
+        ]);
+    });
+
+    it('keeps the security email pending even when push succeeds and logs only safe metadata', async () => {
+        const userKey = baseUserKey();
+        const hold = baseHold();
+        const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+        const sentrySpy = vi.spyOn(Sentry, 'captureException').mockImplementation(() => 'event-id');
+        const { deps, recorded } = makeDeps({
+            send: async () => {
+                throw new Error('Postmark rejected owner@example.com');
+            },
+        });
+
+        await notifyEscrowHoldEvent(
+            { kind: 'started', hold, userKey, cancelToken: 'a'.repeat(64) },
+            deps
+        );
+
+        expect(recorded).toEqual([]);
+        expect(errorSpy).toHaveBeenCalled();
+        expect(sentrySpy).toHaveBeenCalled();
+
+        const loggedText = JSON.stringify([...errorSpy.mock.calls, ...sentrySpy.mock.calls]);
+        expect(loggedText).not.toContain('owner@example.com');
+        expect(loggedText).not.toContain(userKey.primaryDid);
+        expect(loggedText).not.toContain('a'.repeat(64));
+
+        errorSpy.mockRestore();
+        sentrySpy.mockRestore();
+    });
+
+    it('never throws and records nothing when every channel fails', async () => {
+        const userKey = baseUserKey();
+        const hold = baseHold();
+        vi.spyOn(console, 'error').mockImplementation(() => {});
+        vi.spyOn(Sentry, 'captureException').mockImplementation(() => 'event-id');
+        const { deps, recorded } = makeDeps({
+            send: async () => {
+                throw new Error('email down');
+            },
+            sendPush: async () => {
+                throw new Error('push down');
+            },
+        });
+
+        await expect(
+            notifyEscrowHoldEvent(
+                { kind: 'started', hold, userKey, cancelToken: 'a'.repeat(64) },
+                deps
+            )
+        ).resolves.toBe(false);
+        expect(recorded).toHaveLength(0);
+
+        vi.restoreAllMocks();
+    });
+
+    it('contains template token and persistence rejections', async () => {
+        for (const overrides of [
+            {
+                rotateCancelToken: async () => {
+                    throw new Error('token DB failed');
+                },
+            },
+            {
+                recordNotification: async () => {
+                    throw new Error('record DB failed');
+                },
+            },
+        ]) {
+            const { deps } = makeDeps(overrides);
+            await expect(
+                notifyEscrowHoldEvent(
+                    { kind: 'reminder', hold: baseHold(), userKey: baseUserKey() },
+                    deps
+                )
+            ).resolves.toBe(false);
+        }
+    });
+
+    it.each(['started', 'reminder'] as const)(
+        'retries %s when only one verified inbox receives its email',
+        async kind => {
+            const { deps, recorded } = makeDeps({
+                send: async notification => {
+                    if (notification.to === 'recovery@example.com')
+                        throw new Error('delivery failed');
+                },
+            });
+            const userKey = baseUserKey({
+                recoveryEmail: 'recovery@example.com',
+                recoveryEmailVerifiedAt: new Date(),
+            });
+            expect(await notifyEscrowHoldEvent({ kind, hold: baseHold(), userKey }, deps)).toBe(
+                false
+            );
+            expect(recorded).toEqual([]);
+        }
+    );
+
+    it('bounds hanging delivery and consumes its late rejection', async () => {
+        vi.useFakeTimers();
+        try {
+            let rejectSend!: (error: Error) => void;
+            const { deps, recorded } = makeDeps({
+                send: () =>
+                    new Promise((_, reject) => {
+                        rejectSend = reject;
+                    }),
+            });
+            const pending = notifyEscrowHoldEvent(
+                { kind: 'reminder', hold: baseHold(), userKey: baseUserKey() },
+                deps
+            );
+            await vi.advanceTimersByTimeAsync(ESCROW_NOTIFICATION_TIMEOUT_MS);
+            expect(await pending).toBe(false);
+            rejectSend(new Error('late failure'));
+            await vi.runAllTimersAsync();
+            expect(recorded).toEqual([]);
+        } finally {
+            vi.useRealTimers();
+        }
+    });
+});