@learncard/lca-api-service 1.3.2 → 1.4.0

package/test/keys-lifecycle-invariants.spec.ts

@@ -0,0 +1,785 @@
+import { client } from '@mongo';
+import { randomBytes, randomUUID } from 'crypto';
+import cache from '@cache';
+import {
+    consumeChallengeForDid,
+    DID_CHALLENGE_TTL_SECS,
+    getChallengeCacheKey,
+    setValidChallengeForDid,
+} from '@cache/challenges';
+import {
+    activateUserKeyByAuthProvider,
+    createUserKeysIndexes,
+    getUserKeysCollection,
+    PROVISIONAL_MIGRATION_TTL_MS,
+    upsertUserKeyByAuthProvider,
+    UserKeyVersionConflictError,
+    type MongoUserKeyType,
+} from '@models';
+
+import { getClient, getUser } from './helpers/getClient';
+
+const makeMockToken = (email: string, uid: string): string => {
+    const payload = Buffer.from(JSON.stringify({ sub: uid, email })).toString('base64url');
+
+    return `header.${payload}.signature`;
+};
+
+const makeUserKey = (
+    email: string,
+    uid: string,
+    primaryDid: string,
+    encryptedData = 'existing-auth-share'
+): MongoUserKeyType => {
+    const now = new Date();
+
+    return {
+        contactMethod: { type: 'email', value: email },
+        authProviders: [{ type: 'firebase', id: uid }],
+        primaryDid,
+        linkedDids: [],
+        keyProvider: 'sss',
+        authShare: { encryptedData, encryptedDek: 'dek', iv: 'iv' },
+        shareVersion: 1,
+        shareUpdatedAt: now,
+        previousAuthShares: [],
+        securityLevel: 'basic',
+        recoveryMethods: [],
+        migratedFromWeb3Auth: false,
+        createdAt: now,
+        updatedAt: now,
+    };
+};
+
+beforeAll(async () => {
+    process.env.IS_E2E_TEST = 'true';
+    process.env.SEED ||= 'a'.repeat(64);
+    await client.connect();
+    await createUserKeysIndexes();
+});
+
+afterAll(async () => {
+    await client.close();
+});
+
+describe('P0-6 immutable provider identity', () => {
+    it('does not return or mutate an old key when a new UID reuses its email', async () => {
+        const suffix = `${Date.now()}-${randomUUID()}`;
+        const email = `recycled-${suffix}@example.com`;
+        const oldUid = `old-${suffix}`;
+        const newUid = `new-${suffix}`;
+        const { learnCard } = await getUser('b'.repeat(64));
+        const collection = getUserKeysCollection();
+        const oldRecord = makeUserKey(email, oldUid, learnCard.id.did());
+
+        await collection.insertOne(oldRecord);
+
+        try {
+            const oldResult = await getClient().keys.getAuthShare({
+                authToken: makeMockToken(email, oldUid),
+                providerType: 'firebase',
+            });
+            const newResult = await getClient().keys.getAuthShare({
+                authToken: makeMockToken(email, newUid),
+                providerType: 'firebase',
+            });
+
+            expect(oldResult?.authShare?.encryptedData).toBe('existing-auth-share');
+            expect(newResult).toBeNull();
+
+            const unchanged = await collection.findOne({
+                authProviders: { $elemMatch: { type: 'firebase', id: oldUid } },
+            });
+
+            expect(unchanged?.authProviders).toEqual([{ type: 'firebase', id: oldUid }]);
+
+            await getClient({
+                did: learnCard.id.did(),
+                isChallengeValid: true,
+            }).keys.storeAuthShare({
+                authToken: makeMockToken(email, newUid),
+                providerType: 'firebase',
+                primaryDid: learnCard.id.did(),
+                authShare: { encryptedData: 'new-auth-share', encryptedDek: 'dek', iv: 'iv' },
+            });
+
+            const records = await collection.find({ 'contactMethod.value': email }).toArray();
+            const storedNewResult = await getClient().keys.getAuthShare({
+                authToken: makeMockToken(email, newUid),
+                providerType: 'firebase',
+            });
+
+            expect(records).toHaveLength(2);
+            expect(
+                records.find(record => record.authProviders[0]?.id === oldUid)?.authShare
+            ).toMatchObject({ encryptedData: 'existing-auth-share' });
+            expect(storedNewResult?.authShare?.encryptedData).toBe('new-auth-share');
+            expect(storedNewResult?.sssActivationState).toBe('provisional');
+        } finally {
+            await collection.deleteMany({ 'contactMethod.value': email });
+        }
+    });
+});
+
+describe('share version concurrency', () => {
+    it('enforces client versions, preserves acknowledged history against six stale writes, and supports legacy clients', async () => {
+        const uid = randomUUID();
+        const email = `cas-${uid}@example.com`;
+        const { learnCard } = await getUser('9'.repeat(64));
+        const caller = getClient({ did: learnCard.id.did(), isChallengeValid: true });
+        const auth = { authToken: makeMockToken(email, uid), providerType: 'firebase' as const };
+        const input = {
+            ...auth,
+            primaryDid: learnCard.id.did(),
+            authShare: { encryptedData: 'first', encryptedDek: '', iv: '' },
+        };
+        const collection = getUserKeysCollection();
+        try {
+            expect(await caller.keys.getAuthShare(auth)).toBeNull();
+            await expect(
+                caller.keys.storeAuthShare({ ...input, expectedShareVersion: 1 })
+            ).rejects.toMatchObject({ code: 'CONFLICT' });
+            expect(await collection.countDocuments({ 'authProviders.id': uid })).toBe(0);
+            expect(
+                await caller.keys.storeAuthShare({ ...input, expectedShareVersion: 0 })
+            ).toMatchObject({ shareVersion: 1, expectedShareVersionChecked: true });
+            const acknowledged = await caller.keys.storeAuthShare({
+                ...input,
+                authShare: { ...input.authShare, encryptedData: 'acknowledged' },
+                expectedShareVersion: 1,
+            });
+            expect(acknowledged).toMatchObject({
+                shareVersion: 2,
+                expectedShareVersionChecked: true,
+            });
+            for (let i = 0; i < 6; i++) {
+                await expect(
+                    caller.keys.storeAuthShare({ ...input, expectedShareVersion: 1 })
+                ).rejects.toMatchObject({
+                    code: 'CONFLICT',
+                    message: 'Key material changed; please retry',
+                });
+            }
+            expect(await caller.keys.getAuthShare(auth)).toMatchObject({
+                shareVersion: 2,
+                authShare: { encryptedData: 'acknowledged' },
+            });
+            const stored = await collection.findOne({ 'authProviders.id': uid });
+            expect(stored?.previousAuthShares.map(share => share.shareVersion)).toEqual([1]);
+            expect(await caller.keys.storeAuthShare(input)).toMatchObject({
+                shareVersion: 3,
+                expectedShareVersionChecked: false,
+            });
+        } finally {
+            await collection.deleteMany({ 'authProviders.id': uid });
+        }
+    });
+
+    it.each([false, true])(
+        'reports version zero for a record without auth material and atomically initializes it (BSON null=%s)',
+        async bsonNull => {
+            const uid = randomUUID();
+            const email = `empty-${uid}@example.com`;
+            const { learnCard } = await getUser('9'.repeat(64));
+            const caller = getClient({ did: learnCard.id.did(), isChallengeValid: true });
+            const auth = {
+                authToken: makeMockToken(email, uid),
+                providerType: 'firebase' as const,
+            };
+            const key = makeUserKey(email, uid, learnCard.id.did());
+            const collection = getUserKeysCollection();
+            await collection.insertOne(key);
+            await collection.updateOne(
+                { 'authProviders.id': uid },
+                bsonNull ? [{ $set: { authShare: null } }] : { $unset: { authShare: '' } }
+            );
+            try {
+                const stored = await collection.findOne({ 'authProviders.id': uid });
+                if (bsonNull) expect(stored?.authShare).toBeNull();
+                else expect(stored?.authShare).toBeUndefined();
+                expect(await caller.keys.getAuthShare(auth)).toMatchObject({
+                    shareVersion: 0,
+                    authShare: null,
+                });
+                expect(
+                    await caller.keys.storeAuthShare({
+                        ...auth,
+                        primaryDid: key.primaryDid,
+                        authShare: { encryptedData: 'initialized', encryptedDek: '', iv: '' },
+                        expectedShareVersion: 0,
+                    })
+                ).toMatchObject({ shareVersion: 2, expectedShareVersionChecked: true });
+                await expect(
+                    caller.keys.storeAuthShare({
+                        ...auth,
+                        primaryDid: key.primaryDid,
+                        authShare: { encryptedData: 'stale', encryptedDek: '', iv: '' },
+                        expectedShareVersion: 0,
+                    })
+                ).rejects.toMatchObject({ code: 'CONFLICT' });
+            } finally {
+                await collection.deleteMany({ 'authProviders.id': uid });
+            }
+        }
+    );
+
+    it('advances an auth-bearing legacy record without a counter from observable version one to two', async () => {
+        const uid = randomUUID();
+        const email = `legacy-${uid}@example.com`;
+        const { learnCard } = await getUser('9'.repeat(64));
+        const caller = getClient({ did: learnCard.id.did(), isChallengeValid: true });
+        const auth = { authToken: makeMockToken(email, uid), providerType: 'firebase' as const };
+        const collection = getUserKeysCollection();
+        await collection.insertOne(makeUserKey(email, uid, learnCard.id.did()));
+        await collection.updateOne({ 'authProviders.id': uid }, { $unset: { shareVersion: '' } });
+        try {
+            expect(await caller.keys.getAuthShare(auth)).toMatchObject({ shareVersion: 1 });
+            const input = {
+                ...auth,
+                primaryDid: learnCard.id.did(),
+                authShare: { encryptedData: 'next', encryptedDek: '', iv: '' },
+                expectedShareVersion: 1,
+            };
+            expect(await caller.keys.storeAuthShare(input)).toMatchObject({ shareVersion: 2 });
+            expect(await caller.keys.getAuthShare({ ...auth, shareVersion: 1 })).toMatchObject({
+                authShare: { encryptedData: 'existing-auth-share' },
+            });
+            await expect(caller.keys.storeAuthShare(input)).rejects.toMatchObject({
+                code: 'CONFLICT',
+            });
+        } finally {
+            await collection.deleteMany({ 'authProviders.id': uid });
+        }
+    });
+
+    it('recreates a missing provider index before concurrent first writes can succeed', async () => {
+        const uid = randomUUID();
+        const collection = getUserKeysCollection();
+        const provider = { type: 'firebase' as const, id: uid };
+        await collection.dropIndex('auth_provider_identity_unique');
+        try {
+            const results = await Promise.allSettled([
+                upsertUserKeyByAuthProvider(
+                    { type: 'email', value: `first-${uid}@example.com` },
+                    provider,
+                    { primaryDid: `did:example:first-${uid}` },
+                    0
+                ),
+                upsertUserKeyByAuthProvider(
+                    { type: 'email', value: `second-${uid}@example.com` },
+                    provider,
+                    { primaryDid: `did:example:second-${uid}` },
+                    0
+                ),
+            ]);
+            expect(results.filter(result => result.status === 'fulfilled')).toHaveLength(1);
+            const rejected = results.find(result => result.status === 'rejected');
+            expect(rejected?.status === 'rejected' && rejected.reason).toBeInstanceOf(
+                UserKeyVersionConflictError
+            );
+            expect(await collection.countDocuments({ 'authProviders.id': uid })).toBe(1);
+            const indexes = await collection.listIndexes().toArray();
+            expect(
+                indexes.some(
+                    index =>
+                        index.unique === true &&
+                        index.key?.['authProviders.type'] === 1 &&
+                        index.key?.['authProviders.id'] === 1
+                )
+            ).toBe(true);
+        } finally {
+            await collection.deleteMany({ 'authProviders.id': uid });
+            await createUserKeysIndexes();
+        }
+    });
+
+    it('fails first writes closed when legacy duplicate providers prevent index creation, but still updates existing records', async () => {
+        const suffix = randomUUID();
+        const duplicateUid = `duplicate-${suffix}`;
+        const newUid = `blocked-${suffix}`;
+        const collection = getUserKeysCollection();
+        const existing = makeUserKey(
+            `duplicate-a-${suffix}@example.com`,
+            duplicateUid,
+            `did:example:original-${suffix}`
+        );
+        const duplicate = makeUserKey(
+            `duplicate-b-${suffix}@example.com`,
+            duplicateUid,
+            `did:example:other-${suffix}`
+        );
+        await collection.dropIndex('auth_provider_identity_unique');
+        try {
+            await collection.insertMany([existing, duplicate]);
+            await expect(
+                upsertUserKeyByAuthProvider(
+                    { type: 'email', value: `blocked-${suffix}@example.com` },
+                    { type: 'firebase', id: newUid },
+                    { primaryDid: `did:example:new-${suffix}` },
+                    0
+                )
+            ).rejects.toBeInstanceOf(UserKeyVersionConflictError);
+            expect(await collection.countDocuments({ 'authProviders.id': newUid })).toBe(0);
+            expect(
+                (await collection.listIndexes().toArray()).some(
+                    index =>
+                        index.unique === true &&
+                        index.key?.['authProviders.type'] === 1 &&
+                        index.key?.['authProviders.id'] === 1
+                )
+            ).toBe(false);
+            const updated = await upsertUserKeyByAuthProvider(
+                existing.contactMethod,
+                { type: 'firebase', id: duplicateUid },
+                { authShare: { encryptedData: 'updated', encryptedDek: 'dek', iv: 'iv' } },
+                1
+            );
+            expect(updated.primaryDid).toBe(existing.primaryDid);
+            expect(updated.shareVersion).toBe(2);
+            expect(updated.previousAuthShares.map(share => share.shareVersion)).toEqual([1]);
+        } finally {
+            await collection.deleteMany({ 'authProviders.id': { $in: [duplicateUid, newUid] } });
+            await createUserKeysIndexes();
+        }
+    });
+
+    it('allows only one concurrent version-zero insert for an immutable provider identity', async () => {
+        const uid = randomUUID();
+        const email = `insert-${uid}@example.com`;
+        const { learnCard } = await getUser('9'.repeat(64));
+        const caller = getClient({ did: learnCard.id.did(), isChallengeValid: true });
+        const input = {
+            authToken: makeMockToken(email, uid),
+            providerType: 'firebase' as const,
+            primaryDid: learnCard.id.did(),
+            authShare: { encryptedData: 'new', encryptedDek: '', iv: '' },
+            expectedShareVersion: 0,
+        };
+        const collection = getUserKeysCollection();
+        try {
+            const results = await Promise.allSettled([
+                caller.keys.storeAuthShare(input),
+                caller.keys.storeAuthShare(input),
+            ]);
+            expect(results.filter(result => result.status === 'fulfilled')).toHaveLength(1);
+            const rejected = results.find(result => result.status === 'rejected');
+            expect(rejected?.status === 'rejected' && rejected.reason).toMatchObject({
+                code: 'CONFLICT',
+            });
+            expect(await collection.countDocuments({ 'authProviders.id': uid })).toBe(1);
+        } finally {
+            await collection.deleteMany({ 'authProviders.id': uid });
+        }
+    });
+
+    it('allows exactly one auth-share update from the same starting version', async () => {
+        const suffix = `${Date.now()}-${randomUUID()}`;
+        const email = `auth-share-cas-${suffix}@example.com`;
+        const uid = `uid-${suffix}`;
+        const { learnCard } = await getUser('9'.repeat(64));
+        const collection = getUserKeysCollection();
+        const authProvider = { type: 'firebase' as const, id: uid };
+        const key = makeUserKey(email, uid, learnCard.id.did());
+
+        await collection.insertOne(key);
+
+        try {
+            const updates = await Promise.allSettled([
+                upsertUserKeyByAuthProvider(
+                    key.contactMethod,
+                    authProvider,
+                    {
+                        authShare: { encryptedData: 'candidate-a', encryptedDek: 'dek', iv: 'iv' },
+                    },
+                    1
+                ),
+                upsertUserKeyByAuthProvider(
+                    key.contactMethod,
+                    authProvider,
+                    {
+                        authShare: { encryptedData: 'candidate-b', encryptedDek: 'dek', iv: 'iv' },
+                    },
+                    1
+                ),
+            ]);
+            const fulfilled = updates.filter(result => result.status === 'fulfilled');
+            const rejected = updates.filter(result => result.status === 'rejected');
+            const stored = await collection.findOne({
+                authProviders: { $elemMatch: authProvider },
+            });
+
+            expect(fulfilled).toHaveLength(1);
+            expect(rejected).toHaveLength(1);
+            expect((rejected[0] as PromiseRejectedResult).reason).toBeInstanceOf(
+                UserKeyVersionConflictError
+            );
+            expect(stored?.shareVersion).toBe(2);
+            expect(stored?.previousAuthShares.map(entry => entry.shareVersion)).toEqual([1]);
+            expect([
+                ...(stored?.previousAuthShares.map(entry => entry.shareVersion) ?? []),
+                stored?.shareVersion,
+            ]).toEqual([1, 2]);
+        } finally {
+            await collection.deleteMany({ 'contactMethod.value': email });
+        }
+    });
+
+    it('rejects activation from a stale version after a concurrent share rotation', async () => {
+        const suffix = `${Date.now()}-${randomUUID()}`;
+        const email = `activation-cas-${suffix}@example.com`;
+        const uid = `uid-${suffix}`;
+        const { learnCard } = await getUser('8'.repeat(64));
+        const collection = getUserKeysCollection();
+        const authProvider = { type: 'firebase' as const, id: uid };
+        const key = makeUserKey(email, uid, learnCard.id.did());
+
+        key.keyProvider = 'web3auth';
+        key.sssActivationState = 'provisional';
+        key.provisionalCreatedAt = new Date();
+        key.recoveryMethods = [
+            {
+                type: 'backup',
+                createdAt: new Date(),
+                confirmationStatus: 'confirmed',
+                confirmedAt: new Date(),
+                shareVersion: 1,
+            },
+        ];
+        await collection.insertOne(key);
+
+        try {
+            await upsertUserKeyByAuthProvider(
+                key.contactMethod,
+                authProvider,
+                {
+                    authShare: { encryptedData: 'rotated-share', encryptedDek: 'dek', iv: 'iv' },
+                },
+                1
+            );
+
+            await expect(activateUserKeyByAuthProvider(authProvider, 1, true)).resolves.toBe(false);
+
+            const stored = await collection.findOne({
+                authProviders: { $elemMatch: authProvider },
+            });
+
+            expect(stored?.shareVersion).toBe(2);
+            expect(stored?.previousAuthShares.map(entry => entry.shareVersion)).toEqual([1]);
+            expect(stored?.sssActivationState).toBe('provisional');
+            expect(stored?.keyProvider).toBe('web3auth');
+        } finally {
+            await collection.deleteMany({ 'contactMethod.value': email });
+        }
+    });
+});
+
+describe('P0-1 provisional SSS activation', () => {
+    it('rejects activation with no recovery method at the current share version', async () => {
+        const suffix = `${Date.now()}-${randomUUID()}`;
+        const email = `activation-empty-${suffix}@example.com`;
+        const uid = `uid-${suffix}`;
+        const token = makeMockToken(email, uid);
+        const { learnCard } = await getUser('e'.repeat(64));
+        const collection = getUserKeysCollection();
+        const key = makeUserKey(email, uid, learnCard.id.did());
+
+        key.keyProvider = 'web3auth';
+        key.sssActivationState = 'provisional';
+        key.provisionalCreatedAt = new Date();
+        await collection.insertOne(key);
+
+        try {
+            await expect(
+                getClient({ did: learnCard.id.did(), isChallengeValid: true }).keys.activate({
+                    authToken: token,
+                    providerType: 'firebase',
+                })
+            ).rejects.toMatchObject({ code: 'BAD_REQUEST' });
+
+            const unchanged = await collection.findOne({
+                authProviders: { $elemMatch: { type: 'firebase', id: uid } },
+            });
+
+            expect(unchanged?.sssActivationState).toBe('provisional');
+            expect(unchanged?.keyProvider).toBe('web3auth');
+            expect(unchanged?.migratedFromWeb3Auth).toBe(false);
+        } finally {
+            await collection.deleteMany({ 'contactMethod.value': email });
+        }
+    });
+
+    it('preserves legacy fallback when a migration without a prior record expires', async () => {
+        const suffix = `${Date.now()}-${randomUUID()}`;
+        const email = `legacy-no-record-${suffix}@example.com`;
+        const uid = `uid-${suffix}`;
+        const token = makeMockToken(email, uid);
+        const { learnCard } = await getUser('7'.repeat(64));
+        const collection = getUserKeysCollection();
+        const caller = getClient({ did: learnCard.id.did(), isChallengeValid: true });
+
+        try {
+            await caller.keys.storeAuthShare({
+                authToken: token,
+                providerType: 'firebase',
+                primaryDid: learnCard.id.did(),
+                authShare: { encryptedData: 'share', encryptedDek: '', iv: '' },
+            });
+
+            await expect(
+                caller.keys.markMigrated({ authToken: token, providerType: 'firebase' })
+            ).resolves.toEqual({ success: true });
+
+            const stored = await collection.findOne({
+                authProviders: { $elemMatch: { type: 'firebase', id: uid } },
+            });
+
+            expect(stored?.keyProvider).toBe('web3auth');
+            expect(stored?.sssActivationState).toBe('provisional');
+            expect(stored?.migratedFromWeb3Auth).toBe(false);
+            expect(stored?.provisionalCreatedAt).toBeInstanceOf(Date);
+
+            // Simulate abandoning recovery confirmation for more than 30 days.
+            const expiredAt = new Date(Date.now() - PROVISIONAL_MIGRATION_TTL_MS - 1_000);
+            await collection.updateOne(
+                { _id: stored!._id },
+                { $set: { provisionalCreatedAt: expiredAt } }
+            );
+            await caller.keys.markMigrated({ authToken: token, providerType: 'firebase' });
+            expect((await collection.findOne({ _id: stored!._id }))?.provisionalCreatedAt).toEqual(
+                expiredAt
+            );
+
+            // getAuthShare invokes the same lazy cleanup as for pre-existing Web3Auth records.
+            const result = await getClient().keys.getAuthShare({
+                authToken: token,
+                providerType: 'firebase',
+            });
+            const purged = await collection.findOne({ _id: stored!._id });
+            expect(result?.authShare).toBeNull();
+            expect(result?.keyProvider).toBe('web3auth');
+            expect(purged?.keyProvider).toBe('web3auth');
+            expect(purged?.authShare).toBeUndefined();
+            expect(purged?.sssActivationState).toBeUndefined();
+            expect(purged?.provisionalCreatedAt).toBeUndefined();
+            expect(purged?.recoveryMethods).toEqual([]);
+            expect(purged?.previousAuthShares).toEqual([]);
+        } finally {
+            await collection.deleteMany({ 'contactMethod.value': email });
+        }
+    });
+
+    it('atomically activates a migration with a confirmed version-matched recovery method', async () => {
+        const suffix = `${Date.now()}-${randomUUID()}`;
+        const email = `activation-ready-${suffix}@example.com`;
+        const uid = `uid-${suffix}`;
+        const token = makeMockToken(email, uid);
+        const { learnCard } = await getUser('6'.repeat(64));
+        const collection = getUserKeysCollection();
+        const key = makeUserKey(email, uid, learnCard.id.did());
+
+        key.keyProvider = 'web3auth';
+        key.sssActivationState = 'provisional';
+        key.provisionalCreatedAt = new Date();
+        key.recoveryMethods = [
+            {
+                type: 'backup',
+                createdAt: new Date(),
+                confirmationStatus: 'confirmed',
+                confirmedAt: new Date(),
+                shareVersion: 1,
+            },
+        ];
+        await collection.insertOne(key);
+
+        try {
+            await expect(
+                getClient({ did: learnCard.id.did(), isChallengeValid: true }).keys.activate({
+                    authToken: token,
+                    providerType: 'firebase',
+                })
+            ).resolves.toEqual({ success: true });
+
+            const activated = await collection.findOne({
+                authProviders: { $elemMatch: { type: 'firebase', id: uid } },
+            });
+
+            expect(activated?.sssActivationState).toBe('active');
+            expect(activated?.provisionalCreatedAt).toBeUndefined();
+            expect(activated?.keyProvider).toBe('sss');
+            expect(activated?.migratedFromWeb3Auth).toBe(true);
+            expect(activated?.migratedAt).toBeInstanceOf(Date);
+        } finally {
+            await collection.deleteMany({ 'contactMethod.value': email });
+        }
+    });
+
+    it('lazily purges only expired provisional migration shares', async () => {
+        const suffix = `${Date.now()}-${randomUUID()}`;
+        const migrationEmail = `expired-migration-${suffix}@example.com`;
+        const newUserEmail = `expired-new-user-${suffix}@example.com`;
+        const migrationUid = `migration-${suffix}`;
+        const newUserUid = `new-user-${suffix}`;
+        const migrationToken = makeMockToken(migrationEmail, migrationUid);
+        const { learnCard } = await getUser('1'.repeat(64));
+        const collection = getUserKeysCollection();
+        const expiredAt = new Date(Date.now() - PROVISIONAL_MIGRATION_TTL_MS - 1_000);
+        const migrationKey = makeUserKey(
+            migrationEmail,
+            migrationUid,
+            learnCard.id.did(),
+            'expired-migration-share'
+        );
+        const newUserKey = makeUserKey(
+            newUserEmail,
+            newUserUid,
+            learnCard.id.did(),
+            'new-user-share'
+        );
+
+        Object.assign(migrationKey, {
+            keyProvider: 'web3auth' as const,
+            sssActivationState: 'provisional' as const,
+            provisionalCreatedAt: expiredAt,
+            recoveryMethods: [{ type: 'backup' as const, createdAt: new Date(), shareVersion: 1 }],
+        });
+        Object.assign(newUserKey, {
+            keyProvider: 'sss' as const,
+            sssActivationState: 'provisional' as const,
+            provisionalCreatedAt: expiredAt,
+        });
+        await collection.insertMany([migrationKey, newUserKey]);
+
+        try {
+            const result = await getClient().keys.getAuthShare({
+                authToken: migrationToken,
+                providerType: 'firebase',
+            });
+            const purgedMigration = await collection.findOne({
+                authProviders: { $elemMatch: { type: 'firebase', id: migrationUid } },
+            });
+            const preservedNewUser = await collection.findOne({
+                authProviders: { $elemMatch: { type: 'firebase', id: newUserUid } },
+            });
+
+            expect(result?.authShare).toBeNull();
+            expect(purgedMigration?.authShare).toBeUndefined();
+            expect(purgedMigration?.sssActivationState).toBeUndefined();
+            expect(purgedMigration?.keyProvider).toBe('web3auth');
+            expect(purgedMigration?.recoveryMethods).toEqual([]);
+            expect(preservedNewUser?.authShare?.encryptedData).toBe('new-user-share');
+            expect(preservedNewUser?.sssActivationState).toBe('provisional');
+        } finally {
+            await collection.deleteMany({
+                'contactMethod.value': { $in: [migrationEmail, newUserEmail] },
+            });
+        }
+    });
+});
+
+describe('P0-6 fresh DID authorization', () => {
+    it('issues short-lived challenges that can only be consumed once', async () => {
+        const did = `did:key:${randomUUID()}`;
+        const challenge = randomBytes(32).toString('hex');
+
+        await setValidChallengeForDid(did, challenge);
+
+        const ttl = await cache.ttl(getChallengeCacheKey(did, challenge));
+
+        expect(ttl).toBeGreaterThan(0);
+        expect(ttl).toBeLessThanOrEqual(DID_CHALLENGE_TTL_SECS);
+        await expect(consumeChallengeForDid(did, challenge)).resolves.toBe(true);
+        await expect(consumeChallengeForDid(did, challenge)).resolves.toBe(false);
+    });
+
+    it.each([
+        ['no DID VP', getClient(), 'UNAUTHORIZED'],
+        ['stale DID challenge', undefined, 'UNAUTHORIZED'],
+        ['mismatched DID', undefined, 'FORBIDDEN'],
+    ] as const)(
+        '%s rejects every sensitive write without modifying the key record',
+        async (_name, providedCaller, expectedCode) => {
+            const suffix = `${Date.now()}-${randomUUID()}`;
+            const email = `challenge-${suffix}@example.com`;
+            const uid = `uid-${suffix}`;
+            const token = makeMockToken(email, uid);
+            const { learnCard } = await getUser('c'.repeat(64));
+            const { learnCard: otherLearnCard } = await getUser('d'.repeat(64));
+            const collection = getUserKeysCollection();
+            const key = makeUserKey(email, uid, learnCard.id.did());
+            const caller =
+                providedCaller ??
+                (_name === 'stale DID challenge'
+                    ? getClient({ did: learnCard.id.did() })
+                    : getClient({ did: otherLearnCard.id.did(), isChallengeValid: true }));
+
+            await collection.insertOne(key);
+
+            const actions = [
+                () =>
+                    caller.keys.storeAuthShare({
+                        authToken: token,
+                        providerType: 'firebase',
+                        primaryDid: learnCard.id.did(),
+                        authShare: { encryptedData: 'replacement', encryptedDek: 'dek', iv: 'iv' },
+                    }),
+                () =>
+                    caller.keys.addRecoveryMethod({
+                        authToken: token,
+                        providerType: 'firebase',
+                        type: 'backup',
+                        shareVersion: 1,
+                    }),
+                () =>
+                    caller.keys.deleteRecoveryMethod({
+                        authToken: token,
+                        providerType: 'firebase',
+                        type: 'backup',
+                    }),
+                () =>
+                    caller.keys.confirmRecoveryMethod({
+                        authToken: token,
+                        providerType: 'firebase',
+                        type: 'backup',
+                    }),
+                () => caller.keys.markMigrated({ authToken: token, providerType: 'firebase' }),
+                () => caller.keys.activate({ authToken: token, providerType: 'firebase' }),
+                () =>
+                    caller.keys.addRecoveryEmail({
+                        authToken: token,
+                        providerType: 'firebase',
+                        email: `recovery-${suffix}@example.com`,
+                    }),
+                () =>
+                    caller.keys.verifyRecoveryEmail({
+                        authToken: token,
+                        providerType: 'firebase',
+                        code: '000000',
+                    }),
+                () =>
+                    caller.keys.deleteUserKey({
+                        authToken: token,
+                        providerType: 'firebase',
+                        challenge: 'untrusted-challenge',
+                    }),
+            ];
+
+            try {
+                const before = await collection.findOne({
+                    authProviders: { $elemMatch: { type: 'firebase', id: uid } },
+                });
+
+                for (const action of actions) {
+                    await expect(action()).rejects.toMatchObject({ code: expectedCode });
+                }
+
+                const after = await collection.findOne({
+                    authProviders: { $elemMatch: { type: 'firebase', id: uid } },
+                });
+
+                expect(after).toEqual(before);
+            } finally {
+                await collection.deleteMany({ 'contactMethod.value': email });
+            }
+        }
+    );
+});