@learncard/lca-api-service 1.3.2 → 1.4.0

package/test/keys-recovery-rate-limit.spec.ts

@@ -0,0 +1,123 @@
+import { randomUUID } from 'crypto';
+
+import cache from '@cache';
+import { client } from '@mongo';
+import { getUserKeysCollection, type MongoUserKeyType } from '@models';
+import { checkRateLimit, clearRateLimit } from '@helpers/rateLimit.helpers';
+
+import { getClient } from './helpers/getClient';
+
+beforeAll(async () => {
+    process.env.IS_E2E_TEST = 'true';
+    await client.connect();
+});
+
+afterAll(async () => {
+    await client.close();
+});
+
+describe('LC-2207 recovery email rate limiting by auth provider', () => {
+    const uid = randomUUID();
+    const email = `login-${uid}@example.com`;
+    const recoveryEmail = `recovery-${uid}@example.com`;
+    const did = `did:key:z${uid}`;
+    const codeKey = `recovery_email_code:firebase:${uid}`;
+    const attemptKey = `recovery-verify-attempts:firebase:${uid}`;
+    const contactAttemptKey = `recovery-verify-attempts:email:${email}`;
+    const payload = Buffer.from(JSON.stringify({ sub: uid, email })).toString('base64url');
+    const input = { authToken: `header.${payload}.signature`, providerType: 'firebase' as const };
+    const caller = getClient({ did, isChallengeValid: true });
+
+    beforeEach(async () => {
+        const now = new Date();
+        const userKey: MongoUserKeyType = {
+            contactMethod: { type: 'email', value: email },
+            authProviders: [{ type: 'firebase', id: uid }],
+            primaryDid: did,
+            linkedDids: [],
+            keyProvider: 'sss',
+            authShare: { encryptedData: 'auth-share', encryptedDek: 'dek', iv: 'iv' },
+            shareVersion: 1,
+            shareUpdatedAt: now,
+            previousAuthShares: [],
+            securityLevel: 'basic',
+            recoveryMethods: [],
+            migratedFromWeb3Auth: false,
+            sssActivationState: 'active',
+            createdAt: now,
+            updatedAt: now,
+        };
+        await getUserKeysCollection().insertOne(userKey);
+        await cache.set(codeKey, JSON.stringify({ code: '123456', email: recoveryEmail }), 900);
+    });
+
+    afterEach(async () => {
+        await getUserKeysCollection().deleteMany({ 'authProviders.id': uid });
+        await cache.delete([codeKey]);
+        await clearRateLimit(attemptKey);
+        await clearRateLimit(contactAttemptKey);
+    });
+
+    it('locks out after five failures and deletes the pending code', async () => {
+        for (let attempt = 0; attempt < 5; attempt++) {
+            await expect(
+                caller.keys.verifyRecoveryEmail({ ...input, code: '000000' })
+            ).rejects.toMatchObject({
+                code: 'BAD_REQUEST',
+                message: 'Incorrect code. Please try again.',
+            });
+        }
+
+        await expect(
+            caller.keys.verifyRecoveryEmail({ ...input, code: '123456' })
+        ).rejects.toMatchObject({
+            code: 'TOO_MANY_REQUESTS',
+            message: 'Too many attempts. Please resend code.',
+        });
+        expect(await cache.get(codeKey)).toBeFalsy();
+        await clearRateLimit(attemptKey);
+        await expect(
+            caller.keys.verifyRecoveryEmail({ ...input, code: '123456' })
+        ).rejects.toMatchObject({ message: 'No pending verification. Please request a new code.' });
+    });
+
+    it('clears the provider counter on success without using a recycled contact counter', async () => {
+        await cache.set(`rate-limit:${contactAttemptKey}`, '99', 900);
+        await expect(
+            caller.keys.verifyRecoveryEmail({ ...input, code: '000000' })
+        ).rejects.toThrow();
+        expect(await cache.get(`rate-limit:${attemptKey}`)).toBe('1');
+        await expect(
+            caller.keys.verifyRecoveryEmail({ ...input, code: '123456' })
+        ).resolves.toMatchObject({ success: true });
+        expect(await cache.get(`rate-limit:${attemptKey}`)).toBeFalsy();
+        expect(await cache.get(`rate-limit:${contactAttemptKey}`)).toBe('99');
+        expect(await cache.get(codeKey)).toBeFalsy();
+        expect(await getUserKeysCollection().findOne({ 'authProviders.id': uid })).toMatchObject({
+            recoveryEmail,
+        });
+    });
+
+    it('clears the provider counter when resending and accepts the new code', async () => {
+        await cache.set(`rate-limit:${attemptKey}`, '6', 900);
+        await caller.keys.addRecoveryEmail({ ...input, email: recoveryEmail });
+        expect(await cache.get(`rate-limit:${attemptKey}`)).toBeFalsy();
+        const pending = JSON.parse((await cache.get(codeKey))!);
+        expect(pending.code).toMatch(/^\d{6}$/);
+        await expect(
+            caller.keys.verifyRecoveryEmail({ ...input, code: pending.code })
+        ).resolves.toMatchObject({ success: true });
+    });
+
+    it('preserves the QR Redis prefix in the shared helper', async () => {
+        const key = `create:${uid}`;
+        try {
+            expect(await checkRateLimit(key, 1, 60, 'qr-login:rate:')).toBe(true);
+            expect(await checkRateLimit(key, 1, 60, 'qr-login:rate:')).toBe(false);
+            expect(await cache.get(`qr-login:rate:${key}`)).toBe('2');
+            expect(await cache.get(`rate-limit:${key}`)).toBeFalsy();
+        } finally {
+            await clearRateLimit(key, 'qr-login:rate:');
+        }
+    });
+});

package/test/keys-secret-leakage.spec.ts

@@ -0,0 +1,265 @@
+/**
+ * P0-4: Secret leakage — telemetry.
+ *
+ * Verifies that /keys/* routes never let share/token/recovery-key material
+ * reach Sentry: (1) the exported redaction helper strips every secret-shaped
+ * field from a realistic payload, and (2) exercising real /keys/* route
+ * handlers with sentinel values registers a Sentry scope event processor
+ * that redacts those sentinels from anything Sentry would capture.
+ */
+import * as Sentry from '@sentry/serverless';
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+
+import { redactSecretFields } from '@routes';
+import { getClient, getUser } from './helpers/getClient';
+
+import { client } from '@mongo';
+
+const SENTINEL_SHARE = 'SENTINEL_SHARE_XYZ';
+const SENTINEL_TOKEN = 'SENTINEL_TOKEN_XYZ';
+
+const makeMockToken = (email: string, uid: string): string => {
+    const payload = Buffer.from(JSON.stringify({ sub: uid, email })).toString('base64url');
+    return `header.${payload}.signature`;
+};
+
+beforeAll(async () => {
+    process.env.IS_E2E_TEST = 'true';
+    process.env.SEED ||= 'a'.repeat(64);
+
+    try {
+        await client.connect();
+    } catch (error) {
+        console.error(error);
+    }
+});
+
+afterAll(async () => {
+    try {
+        await client.close();
+    } catch (error) {
+        console.error(error);
+    }
+});
+
+describe('redactSecretFields', () => {
+    it('redacts every secret-shaped field from a realistic /keys/* payload', () => {
+        const payload = {
+            authToken: SENTINEL_TOKEN,
+            authShare: { encryptedData: SENTINEL_SHARE, encryptedDek: 'x', iv: 'iv' },
+            emailShare: SENTINEL_SHARE,
+            encryptedShare: { encryptedData: SENTINEL_SHARE, iv: 'iv' },
+            recoveryKey: SENTINEL_SHARE,
+            seed: SENTINEL_SHARE,
+            blob: SENTINEL_SHARE,
+            envelope: { ciphertext: SENTINEL_SHARE },
+            sealedShare: { ciphertext: SENTINEL_SHARE },
+            resumeToken: SENTINEL_TOKEN,
+            clientEphemeralPublicKey: SENTINEL_SHARE,
+            credentialId: 'not-a-secret-cred-id',
+            providerType: 'firebase',
+            type: 'passkey',
+        };
+
+        const redacted = redactSecretFields(payload) as Record<string, unknown>;
+
+        expect(redacted.authToken).toBe('[Redacted]');
+        expect(redacted.authShare).toBe('[Redacted]');
+        expect(redacted.emailShare).toBe('[Redacted]');
+        expect(redacted.encryptedShare).toBe('[Redacted]');
+        expect(redacted.recoveryKey).toBe('[Redacted]');
+        expect(redacted.seed).toBe('[Redacted]');
+        expect(redacted.blob).toBe('[Redacted]');
+        expect(redacted.envelope).toBe('[Redacted]');
+        expect(redacted.sealedShare).toBe('[Redacted]');
+        expect(redacted.resumeToken).toBe('[Redacted]');
+        expect(redacted.clientEphemeralPublicKey).toBe('[Redacted]');
+        // Non-secret fields survive untouched
+        expect(redacted.credentialId).toBe('not-a-secret-cred-id');
+        expect(redacted.providerType).toBe('firebase');
+        expect(redacted.type).toBe('passkey');
+
+        const serialized = JSON.stringify(redacted);
+        expect(serialized).not.toContain(SENTINEL_SHARE);
+        expect(serialized).not.toContain(SENTINEL_TOKEN);
+    });
+
+    it('redacts nested secret-shaped fields recursively', () => {
+        const payload = {
+            recoveryMethods: [
+                { type: 'backup', encryptedShare: { encryptedData: SENTINEL_SHARE, iv: 'iv' } },
+            ],
+        };
+
+        const redacted = redactSecretFields(payload) as {
+            recoveryMethods: { encryptedShare: unknown }[];
+        };
+
+        expect(redacted.recoveryMethods[0]!.encryptedShare).toBe('[Redacted]');
+    });
+
+    it('leaves keys that do not match the secret pattern alone', () => {
+        const payload = { credentialId: SENTINEL_TOKEN, providerType: 'firebase' };
+
+        const redacted = redactSecretFields(payload) as Record<string, unknown>;
+
+        expect(redacted.credentialId).toBe(SENTINEL_TOKEN);
+        expect(redacted.providerType).toBe('firebase');
+    });
+});
+
+// Use a real isolated scope while capturing processors, without touching the hub.
+const captureScope = (
+    processors: Array<(event: Record<string, unknown>) => unknown>
+): Sentry.Scope => {
+    const scope = new Sentry.Scope();
+    vi.spyOn(scope, 'addEventProcessor').mockImplementation(processor => {
+        processors.push(event => processor(event, {}));
+        return scope;
+    });
+    return scope;
+};
+
+describe('Sentry event processor for /keys/* routes', () => {
+    it('redacts escrow inputs and outputs on the separate escrow router namespace', async () => {
+        const processors: Array<(event: Record<string, unknown>) => unknown> = [];
+        const spy = vi.spyOn(Sentry, 'configureScope').mockImplementation(callback => {
+            callback(captureScope(processors));
+        });
+        try {
+            // Even a disabled or rejected request must register the defense-in-depth processor.
+            await getClient()
+                .escrow.startRecovery({
+                    authToken: SENTINEL_TOKEN,
+                    providerType: 'firebase',
+                    clientEphemeralPublicKey: SENTINEL_SHARE,
+                })
+                .catch(() => undefined);
+        } finally {
+            spy.mockRestore();
+        }
+        expect(processors).toHaveLength(1);
+        const payload = {
+            envelope: { ciphertext: SENTINEL_SHARE },
+            sealedShare: { ciphertext: SENTINEL_SHARE },
+            resumeToken: SENTINEL_TOKEN,
+            clientEphemeralPublicKey: SENTINEL_SHARE,
+        };
+        const event = {
+            contexts: { trpc: { input: payload } },
+            extra: { output: payload },
+            request: { data: payload },
+        };
+        const serialized = JSON.stringify(processors[0]!(event));
+        expect(serialized).not.toContain(SENTINEL_SHARE);
+        expect(serialized).not.toContain(SENTINEL_TOKEN);
+    });
+    it('registers a redacting event processor for every /keys/* call, using sentinel inputs', async () => {
+        const email = `p04-sentry-${Date.now()}@example.com`;
+        const token = makeMockToken(email, `p04-uid-${Date.now()}`);
+        const { learnCard } = await getUser(`b${'1'.repeat(63)}`);
+        const authedCaller = getClient({ did: learnCard.id.did(), isChallengeValid: true });
+
+        const registeredProcessors: Array<(event: Record<string, unknown>) => unknown> = [];
+
+        const configureScopeSpy = vi
+            .spyOn(Sentry, 'configureScope')
+            .mockImplementation(callback => {
+                callback(captureScope(registeredProcessors));
+            });
+
+        try {
+            // Exercise every /keys/* route that accepts share/token-shaped
+            // input, with sentinel values, exactly as a real client would.
+            await authedCaller.keys.storeAuthShare({
+                authToken: token,
+                providerType: 'firebase',
+                authShare: { encryptedData: SENTINEL_SHARE, encryptedDek: 'x', iv: 'iv' },
+                primaryDid: learnCard.id.did(),
+            });
+
+            await authedCaller.keys.addRecoveryMethod({
+                authToken: token,
+                providerType: 'firebase',
+                type: 'backup',
+                encryptedShare: { encryptedData: SENTINEL_SHARE, iv: 'iv' },
+            });
+
+            await getClient().keys.getAuthShare({ authToken: token, providerType: 'firebase' });
+            await getClient().keys.getRecoveryShare({
+                authToken: token,
+                providerType: 'firebase',
+                type: 'backup',
+            });
+            await expect(
+                authedCaller.keys.sendEmailBackup({
+                    authToken: token,
+                    providerType: 'firebase',
+                    relayPayload: {
+                        version: 1,
+                        algorithm: 'P-256-HKDF-SHA256-AES-256-GCM',
+                        keyId: 'sentry-test-key',
+                        ephemeralPublicKey: 'TESTEPHEMERAL',
+                        salt: 'TESTSALT',
+                        iv: 'TESTIV',
+                        ciphertext: SENTINEL_SHARE,
+                    },
+                    confirmationCode: '123456',
+                    email: 'recovery-target@example.com',
+                })
+            ).rejects.toMatchObject({ code: 'BAD_REQUEST' });
+        } finally {
+            configureScopeSpy.mockRestore();
+        }
+
+        // attachRpcInput is globally disabled (see routes/index.ts), so
+        // Sentry never received the raw input above in the first place.
+        // This proves the defense-in-depth layer independently: every one
+        // of the five /keys/* calls above registered a redacting processor.
+        expect(registeredProcessors.length).toBe(5);
+
+        const syntheticEvent = {
+            contexts: {
+                trpc: {
+                    procedure_type: 'mutation',
+                    input: {
+                        authToken: SENTINEL_TOKEN,
+                        authShare: { encryptedData: SENTINEL_SHARE, encryptedDek: 'x', iv: 'iv' },
+                        emailShare: SENTINEL_SHARE,
+                    },
+                },
+            },
+            extra: { recoveryKey: SENTINEL_SHARE, credentialId: 'safe-value' },
+        };
+
+        // Apply every registered processor, as the real Sentry client would.
+        let result: Record<string, unknown> = syntheticEvent;
+        for (const processor of registeredProcessors) {
+            result = (processor(result) as Record<string, unknown>) ?? result;
+        }
+
+        const serialized = JSON.stringify(result);
+        expect(serialized).not.toContain(SENTINEL_TOKEN);
+        expect(serialized).not.toContain(SENTINEL_SHARE);
+        // Confirms redaction is targeted, not a blanket event wipe
+        expect(serialized).toContain('safe-value');
+    });
+
+    it('does not register the redacting processor for non-/keys/* routes', async () => {
+        const registeredProcessors: Array<(event: Record<string, unknown>) => unknown> = [];
+
+        const configureScopeSpy = vi
+            .spyOn(Sentry, 'configureScope')
+            .mockImplementation(callback => {
+                callback(captureScope(registeredProcessors));
+            });
+
+        try {
+            await getClient().utilities.healthCheck();
+        } finally {
+            configureScopeSpy.mockRestore();
+        }
+
+        expect(registeredProcessors).toHaveLength(0);
+    });
+});

package/test/models/escrow.spec.ts

@@ -0,0 +1,210 @@
+import { beforeAll, afterAll, beforeEach, describe, it, expect } from 'vitest';
+import { client } from '@mongo';
+import {
+    createUserKeysIndexes,
+    getUserKeysCollection,
+    upsertUserKeyByAuthProvider,
+    setEscrowBlobByAuthProvider,
+    clearEscrowByAuthProvider,
+    setEscrowOptInByAuthProvider,
+    removeRecoveryMethodFromUserKeyByAuthProvider,
+    findUserKeyByAuthProvider,
+    createEscrowHoldsIndexes,
+    getEscrowHoldsCollection,
+    createEscrowHold,
+    cancelEscrowHold,
+    completeEscrowHold,
+    expireStaleEscrowHolds,
+    ESCROW_HOLD_STALE_WINDOW_MS,
+    generateEscrowResumeToken,
+    hashEscrowResumeToken,
+    findPendingEscrowHoldByAuthProvider,
+    reserveEscrowPinAttempt,
+    refundEscrowPinAttempt,
+    type EscrowBlob,
+    type AuthProviderMapping,
+} from '@models';
+
+const provider: AuthProviderMapping = { type: 'firebase', id: 'escrow-model-test' };
+const blob: EscrowBlob = {
+    envelope: {
+        version: 1,
+        algorithm: 'P-256-HKDF-SHA256-AES-256-GCM',
+        keyId: 'test',
+        ephemeralPublicKey: 'key',
+        salt: 'salt',
+        iv: 'iv',
+        ciphertext: '$literal-data',
+    },
+    enclaveKeyId: 'test',
+    enclaveMode: 'software',
+    measurements: {},
+    shareVersion: 1,
+    createdAt: new Date(),
+};
+const createHold = (
+    releaseAfter = new Date(),
+    releasePolicy: 'hold' | 'pin' = 'hold'
+): ReturnType<typeof createEscrowHold> =>
+    createEscrowHold({
+        authProvider: provider,
+        primaryDid: 'did:key:test',
+        shareVersion: 1,
+        identityProofType: 'auth-token',
+        requestedAt: new Date(),
+        releaseAfter,
+        releasePolicy,
+        clientEphemeralPublicKey: 'public-key',
+        resumeTokenHash: hashEscrowResumeToken(generateEscrowResumeToken()),
+    });
+
+beforeAll(async () => {
+    process.env.IS_E2E_TEST = 'true';
+    process.env.SEED ||= 'a'.repeat(64);
+    await client.connect();
+    await createUserKeysIndexes();
+    await createEscrowHoldsIndexes();
+});
+beforeEach(async () => {
+    await getUserKeysCollection().deleteMany({ 'authProviders.id': provider.id });
+    await getEscrowHoldsCollection().deleteMany({ 'authProvider.id': provider.id });
+    await upsertUserKeyByAuthProvider({ type: 'email', value: 'escrow@example.com' }, provider, {
+        primaryDid: 'did:key:test',
+        authShare: { encryptedData: 'data', encryptedDek: 'dek', iv: 'iv' },
+    });
+});
+afterAll(async () => {
+    await client.close();
+});
+
+describe('escrow model invariants', () => {
+    it('migrates legacy pending holds before replacing the identity-only unique index', async () => {
+        const collection = getEscrowHoldsCollection();
+        await collection.createIndex(
+            { 'authProvider.type': 1, 'authProvider.id': 1 },
+            {
+                name: 'pending_escrow_identity_unique',
+                unique: true,
+                partialFilterExpression: { status: 'pending' },
+            }
+        );
+        const hold = await createHold();
+        await collection.updateOne({ _id: hold._id }, { $unset: { releasePolicy: '' } });
+        expect((await findPendingEscrowHoldByAuthProvider(provider, 'hold'))?._id).toBe(hold._id);
+        await createEscrowHoldsIndexes();
+        const indexes = await collection.listIndexes().toArray();
+        expect(indexes.some(index => index.name === 'pending_escrow_identity_unique')).toBe(false);
+        expect(
+            indexes.find(index => index.name === 'pending_escrow_identity_policy_unique')
+        ).toMatchObject({
+            key: { 'authProvider.type': 1, 'authProvider.id': 1, releasePolicy: 1 },
+            unique: true,
+            partialFilterExpression: { status: 'pending' },
+        });
+        expect((await findPendingEscrowHoldByAuthProvider(provider, 'hold'))?.releasePolicy).toBe(
+            'hold'
+        );
+        const pin = await createHold(new Date(), 'pin');
+        expect((await findPendingEscrowHoldByAuthProvider(provider, 'pin'))?._id).toBe(pin._id);
+        await expect(createHold()).rejects.toMatchObject({ code: 11000 });
+        await expect(createHold(new Date(), 'pin')).rejects.toMatchObject({ code: 11000 });
+    });
+
+    it('refunds only matching active reservations and never makes attempts negative', async () => {
+        await setEscrowBlobByAuthProvider(provider, blob, 1, {
+            salt: Buffer.alloc(16).toString('base64'),
+        });
+        await reserveEscrowPinAttempt(provider, 1, blob.envelope.ciphertext);
+        await refundEscrowPinAttempt(provider, 2, blob.envelope.ciphertext);
+        await refundEscrowPinAttempt(provider, 1, 'replacement');
+        expect(
+            (await findUserKeyByAuthProvider(provider.type, provider.id))?.escrowPin?.failedAttempts
+        ).toBe(1);
+        await refundEscrowPinAttempt(provider, 1, blob.envelope.ciphertext);
+        await refundEscrowPinAttempt(provider, 1, blob.envelope.ciphertext);
+        expect(
+            (await findUserKeyByAuthProvider(provider.type, provider.id))?.escrowPin?.failedAttempts
+        ).toBe(0);
+        await reserveEscrowPinAttempt(provider, 1, blob.envelope.ciphertext);
+        await getUserKeysCollection().updateOne(
+            { 'authProviders.id': provider.id },
+            { $set: { 'escrowPin.disabledAt': new Date() } }
+        );
+        await refundEscrowPinAttempt(provider, 1, blob.envelope.ciphertext);
+        expect(
+            (await findUserKeyByAuthProvider(provider.type, provider.id))?.escrowPin?.failedAttempts
+        ).toBe(1);
+    });
+    it('atomically replaces escrow without duplicate methods and preserves literal values', async () => {
+        await setEscrowBlobByAuthProvider(provider, blob, 1);
+        const result = await setEscrowBlobByAuthProvider(provider, blob, 1);
+        expect(result?.recoveryMethods).toHaveLength(1);
+        expect(result?.recoveryMethods[0]).toMatchObject({
+            type: 'escrow',
+            confirmationStatus: 'confirmed',
+            shareVersion: 1,
+        });
+        expect(result?.escrowBlob).toEqual(blob);
+        expect(
+            await setEscrowBlobByAuthProvider(provider, { ...blob, shareVersion: 2 }, 2)
+        ).toBeNull();
+    });
+    it('clears with and without opting out; explicit opt-in permits enrollment again', async () => {
+        await setEscrowBlobByAuthProvider(provider, blob, 1);
+        const cleared = await clearEscrowByAuthProvider(provider, { optOut: false });
+        expect(cleared?.escrowBlob).toBeUndefined();
+        expect(cleared?.escrowOptedOutAt).toBeUndefined();
+        expect(cleared?.recoveryMethods).toEqual([]);
+        await setEscrowBlobByAuthProvider(provider, blob, 1);
+        const optedOut = await clearEscrowByAuthProvider(provider, { optOut: true });
+        expect(optedOut?.escrowOptedOutAt).toBeInstanceOf(Date);
+        expect(await setEscrowBlobByAuthProvider(provider, blob, 1)).toBeNull();
+        await clearEscrowByAuthProvider(provider, { optOut: false });
+        expect(await setEscrowBlobByAuthProvider(provider, blob, 1)).toBeNull();
+        await setEscrowOptInByAuthProvider(provider);
+        expect(await setEscrowBlobByAuthProvider(provider, blob, 1)).not.toBeNull();
+    });
+    it('removes blobs on explicit method deletion and history pruning', async () => {
+        await setEscrowBlobByAuthProvider(provider, blob, 1);
+        await removeRecoveryMethodFromUserKeyByAuthProvider(provider, 'escrow');
+        expect(
+            (await findUserKeyByAuthProvider(provider.type, provider.id))?.escrowBlob
+        ).toBeUndefined();
+        await setEscrowBlobByAuthProvider(provider, blob, 1);
+        for (let i = 0; i < 6; i++) {
+            await upsertUserKeyByAuthProvider(
+                { type: 'email', value: 'escrow@example.com' },
+                provider,
+                { authShare: { encryptedData: 'next', encryptedDek: 'dek', iv: 'iv' } }
+            );
+        }
+        const result = await findUserKeyByAuthProvider(provider.type, provider.id);
+        expect(result?.escrowBlob).toBeUndefined();
+        expect(result?.recoveryMethods).toEqual([]);
+    });
+    it('allows only one pending hold and terminal transitions are conditional', async () => {
+        const hold = await createHold();
+        await expect(createHold()).rejects.toMatchObject({ code: 11000 });
+        expect((await cancelEscrowHold(hold._id, 'did'))?.status).toBe('cancelled');
+        expect(await cancelEscrowHold(hold._id, 'system')).toBeNull();
+        expect(await completeEscrowHold(hold._id)).toBeNull();
+        const next = await createHold();
+        expect((await completeEscrowHold(next._id))?.status).toBe('completed');
+        expect(await completeEscrowHold(next._id)).toBeNull();
+        expect(await cancelEscrowHold(next._id, 'did')).toBeNull();
+    });
+    it('expires only stale pending holds and creates random hashed resume tokens', async () => {
+        const now = new Date();
+        const hold = await createHold(new Date(now.getTime() - ESCROW_HOLD_STALE_WINDOW_MS - 1));
+        // Claiming must enforce expiry even before lazy cleanup has run.
+        expect(await completeEscrowHold(hold._id)).toBeNull();
+        expect(await expireStaleEscrowHolds(now)).toBe(1);
+        expect(await completeEscrowHold(hold._id)).toBeNull();
+        expect(await cancelEscrowHold(hold._id, 'did')).toBeNull();
+        const token = generateEscrowResumeToken();
+        expect(token).toMatch(/^[0-9a-f]{64}$/);
+        expect(generateEscrowResumeToken()).not.toBe(token);
+        expect(hashEscrowResumeToken(token)).toMatch(/^[0-9a-f]{64}$/);
+        expect(hashEscrowResumeToken(token)).not.toBe(token);
+    });
+});