@learncard/lca-api-service 1.3.1 → 1.4.0

package/src/models/UserKey.ts

@@ -1,4 +1,7 @@
 import { z } from 'zod';
+import type { Filter } from 'mongodb';
+import { ESCROW_PIN_MAX_ATTEMPTS } from '@learncard/sss-key-manager';
+import { EscrowPinStatusValidator as SharedEscrowPinStatusValidator } from '@learncard/types';
 
 import mongodb from '@mongo';
 import { pruneOrphanedRecoveryMethods } from './pruneOrphanedRecoveryMethods';
@@ -28,11 +31,17 @@ export const EncryptedShareValidator = z.object({
 });
 
 export const RecoveryMethodValidator = z.object({
-    type: z.enum(['passkey', 'backup', 'phrase', 'email']),
+    type: z.enum(['passkey', 'backup', 'phrase', 'email', 'escrow']),
     createdAt: z.date(),
+    confirmationStatus: z.enum(['pending', 'confirmed']).optional(),
+    confirmedAt: z.date().optional(),
     credentialId: z.string().optional(),
     encryptedShare: EncryptedShareValidator.optional(),
     shareVersion: z.number().optional(),
+    confirmationCodeHash: z.string().optional(),
+    confirmationCodeExpiresAt: z.date().optional(),
+    confirmationAttempts: z.number().int().nonnegative().optional(),
+    confirmationEmail: z.string().email().optional(),
 });
 
 export const PreviousAuthShareValidator = z.object({
@@ -41,7 +50,78 @@ export const PreviousAuthShareValidator = z.object({
     createdAt: z.date(),
 });
 
-export const MongoUserKeyValidator = z.object({
+export const EscrowEnvelopeValidator = z
+    .object({
+        version: z.literal(1),
+        algorithm: z.literal('P-256-HKDF-SHA256-AES-256-GCM'),
+        keyId: z.string().regex(/^[A-Za-z0-9._-]{1,128}$/),
+        ephemeralPublicKey: z.string().min(1).max(256),
+        salt: z.string().min(1).max(128),
+        iv: z.string().min(1).max(64),
+        ciphertext: z.string().min(1).max(16_384),
+    })
+    .strict();
+
+export const EscrowBlobValidator = z.object({
+    envelope: EscrowEnvelopeValidator,
+    enclaveKeyId: z.string().regex(/^[A-Za-z0-9._-]{1,128}$/),
+    enclaveMode: z.enum(['software', 'nitro']),
+    measurements: z.object({
+        imageSha384: z.string().optional(),
+        pcr0: z.string().optional(),
+        pcr1: z.string().optional(),
+        pcr2: z.string().optional(),
+    }),
+    shareVersion: z.number().int().positive(),
+    createdAt: z.date(),
+});
+export type EscrowBlob = z.infer<typeof EscrowBlobValidator>;
+
+export const EscrowPinSaltValidator = z
+    .string()
+    .length(24)
+    .refine(
+        salt =>
+            Buffer.from(salt, 'base64').length === 16 &&
+            Buffer.from(salt, 'base64').toString('base64') === salt,
+        'Expected a base64-encoded 16-byte salt.'
+    );
+export const EscrowPinValidator = z.object({
+    salt: EscrowPinSaltValidator,
+    // Legacy name: charged lifetime budget, including unresolved reservations.
+    failedAttempts: z.number().int().nonnegative(),
+    verifiedFailedAttempts: z.number().int().nonnegative().optional(),
+    enabledAt: z.date(),
+    disabledAt: z.date().optional(),
+    shareVersion: z.number().int().positive(),
+});
+export const EscrowPinStatusValidator = SharedEscrowPinStatusValidator.extend({
+    salt: EscrowPinSaltValidator.optional(),
+});
+
+export const getEscrowPinStatus = (
+    userKey: MongoUserKeyType
+): z.infer<typeof EscrowPinStatusValidator> => {
+    const pin = userKey.escrowPin;
+    const enabled = !!pin && !pin.disabledAt && pin.shareVersion === userKey.shareVersion;
+    return {
+        state: !pin
+            ? 'none'
+            : pin.disabledAt
+              ? 'locked'
+              : pin.shareVersion !== userKey.shareVersion
+                ? 'stale'
+                : 'enabled',
+        enabled,
+        attemptsRemaining: pin ? Math.max(0, ESCROW_PIN_MAX_ATTEMPTS - pin.failedAttempts) : 0,
+        ...(enabled ? { salt: pin.salt } : {}),
+    };
+};
+
+const MongoUserKeyBaseValidator = z.object({
+    escrowBlob: EscrowBlobValidator.optional(),
+    escrowPin: EscrowPinValidator.optional(),
+    escrowOptedOutAt: z.date().optional(),
     _id: z.string().optional(),
 
     contactMethod: ContactMethodValidator,
@@ -78,11 +158,16 @@ export const MongoUserKeyValidator = z.object({
     migratedFromWeb3Auth: z.boolean().default(false),
     migratedAt: z.date().optional(),
 
+    sssActivationState: z.enum(['provisional', 'active']).optional(),
+    provisionalCreatedAt: z.date().optional(),
+
     createdAt: z.date(),
     updatedAt: z.date(),
 });
 
-export type MongoUserKeyType = z.infer<typeof MongoUserKeyValidator>;
+export const MongoUserKeyValidator = MongoUserKeyBaseValidator.passthrough();
+
+export type MongoUserKeyType = z.infer<typeof MongoUserKeyBaseValidator>;
 export type ContactMethod = z.infer<typeof ContactMethodValidator>;
 export type AuthProviderMapping = z.infer<typeof AuthProviderMappingValidator>;
 export type ServerEncryptedShare = z.infer<typeof ServerEncryptedShareValidator>;
@@ -91,6 +176,40 @@ export type RecoveryMethod = z.infer<typeof RecoveryMethodValidator>;
 export type PreviousAuthShare = z.infer<typeof PreviousAuthShareValidator>;
 
 export const MAX_PREVIOUS_AUTH_SHARES = 5;
+export const PROVISIONAL_MIGRATION_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+
+export class UserKeyVersionConflictError extends Error {
+    constructor() {
+        super('User key share version changed during update');
+        this.name = 'UserKeyVersionConflictError';
+    }
+}
+
+/**
+ * Records created before activation state tracking are grandfathered as active.
+ * This preserves existing SSS users while new writes use the explicit state machine.
+ */
+export const getSssActivationState = (userKey: MongoUserKeyType): 'provisional' | 'active' =>
+    userKey.sssActivationState ?? 'active';
+
+/** New methods are pending until receipt is proved. Methods without confirmation
+ * metadata on already-active records predate this protocol and are grandfathered. */
+export const isRecoveryMethodConfirmed = (
+    userKey: MongoUserKeyType,
+    method: RecoveryMethod
+): boolean => {
+    if (method.confirmedAt) return true;
+    if (method.confirmationStatus) return false;
+
+    return getSssActivationState(userKey) === 'active';
+};
+
+export const hasActivatableRecoveryMethod = (userKey: MongoUserKeyType): boolean =>
+    (userKey.recoveryMethods ?? []).some(
+        method =>
+            method.shareVersion === (userKey.shareVersion ?? 1) &&
+            isRecoveryMethodConfirmed(userKey, method)
+    );
 
 export { pruneOrphanedRecoveryMethods };
 
@@ -98,19 +217,172 @@ export const getUserKeysCollection = () => {
     return mongodb.collection<MongoUserKeyType>(USER_KEYS_COLLECTION);
 };
 
-export const createUserKeysIndexes = async () => {
+const getMongoErrorCode = (error: unknown): number | undefined => {
+    if (typeof error !== 'object' || error === null || !('code' in error)) return undefined;
+
+    return typeof error.code === 'number' ? error.code : undefined;
+};
+
+const runIndexMigrationOperation = async (
+    operationName: string,
+    operation: () => Promise<unknown>,
+    options: { duplicateRequiresManualDedupe?: boolean } = {}
+): Promise<void> => {
+    try {
+        await operation();
+    } catch (error) {
+        const code = getMongoErrorCode(error);
+
+        if (code === 11000) {
+            if (options.duplicateRequiresManualDedupe) {
+                console.error(
+                    `[UserKey indexes] ${operationName} found duplicate provider identities; ` +
+                        'manual dedupe is required before the unique index can be created.',
+                    { code }
+                );
+            } else {
+                console.error(
+                    `[UserKey indexes] ${operationName} encountered duplicate data; continuing startup.`,
+                    { code }
+                );
+            }
+
+            return;
+        }
+
+        // IndexNotFound and index option/spec conflicts are expected when cold starts race.
+        if (code === 27 || code === 85 || code === 86) {
+            console.warn(
+                `[UserKey indexes] ${operationName} raced another index migration; continuing startup.`,
+                { code }
+            );
+            return;
+        }
+
+        throw error;
+    }
+};
+
+export const createUserKeysIndexes = async (): Promise<void> => {
     const collection = getUserKeysCollection();
 
-    await collection.createIndex(
-        { 'contactMethod.type': 1, 'contactMethod.value': 1 },
-        { unique: true }
+    const indexes = await collection
+        .listIndexes()
+        .toArray()
+        .catch((error: unknown) => {
+            const code = getMongoErrorCode(error);
+
+            if (code === 26) return [];
+            throw error;
+        });
+
+    const contactIndex = indexes.find(
+        index => index.key?.['contactMethod.type'] === 1 && index.key?.['contactMethod.value'] === 1
+    );
+
+    // Contact methods are mutable and can be recycled. They remain searchable,
+    // but are deliberately non-unique and never serve as account identity.
+    if (contactIndex?.unique && contactIndex.name) {
+        await runIndexMigrationOperation('drop unique contact-method index', () =>
+            collection.dropIndex(contactIndex.name!)
+        );
+    }
+
+    if (!contactIndex || contactIndex.unique) {
+        await runIndexMigrationOperation('create contact-method lookup index', () =>
+            collection.createIndex(
+                { 'contactMethod.type': 1, 'contactMethod.value': 1 },
+                { name: 'contact_method_lookup' }
+            )
+        );
+    }
+
+    const providerIndex = indexes.find(
+        index => index.key?.['authProviders.type'] === 1 && index.key?.['authProviders.id'] === 1
     );
 
-    await collection.createIndex(
-        { 'authProviders.type': 1, 'authProviders.id': 1 }
+    if (providerIndex && !providerIndex.unique && providerIndex.name) {
+        await runIndexMigrationOperation('drop non-unique provider identity index', () =>
+            collection.dropIndex(providerIndex.name!)
+        );
+    }
+
+    if (!providerIndex || !providerIndex.unique) {
+        await runIndexMigrationOperation(
+            'create unique provider identity index',
+            () =>
+                collection.createIndex(
+                    { 'authProviders.type': 1, 'authProviders.id': 1 },
+                    { name: 'auth_provider_identity_unique', unique: true }
+                ),
+            { duplicateRequiresManualDedupe: true }
+        );
+    }
+
+    await runIndexMigrationOperation('create primary DID index', () =>
+        collection.createIndex({ primaryDid: 1 })
+    );
+    await runIndexMigrationOperation('create verified recovery email index', () =>
+        collection.createIndex(
+            { recoveryEmail: 1, recoveryEmailVerifiedAt: 1 },
+            { name: 'verified_recovery_email_lookup' }
+        )
     );
+};
 
-    await collection.createIndex({ primaryDid: 1 });
+/** First writes require database-enforced provider uniqueness, not a process-local check. */
+const ensureProviderIdentityUniqueForInsert = async (): Promise<void> => {
+    const hasUniqueIndex = async (): Promise<boolean> => {
+        const indexes = await getUserKeysCollection()
+            .listIndexes()
+            .toArray()
+            .catch((error: unknown) => {
+                if (getMongoErrorCode(error) === 26) return [];
+                throw error;
+            });
+
+        return indexes.some(index => {
+            const keys = Object.keys(index.key ?? {});
+            return (
+                index.unique === true &&
+                !index.sparse &&
+                !index.partialFilterExpression &&
+                keys.length === 2 &&
+                index.key?.['authProviders.type'] === 1 &&
+                index.key?.['authProviders.id'] === 1
+            );
+        });
+    };
+
+    try {
+        if (await hasUniqueIndex()) return;
+
+        // The migration drops a legacy non-unique index before creating the unique one.
+        // It logs and tolerates legacy duplicates, so verify the index actually exists.
+        await createUserKeysIndexes();
+        if (await hasUniqueIndex()) return;
+    } catch (error) {
+        console.error('[UserKey indexes] provider uniqueness unavailable for first write.', error);
+    }
+
+    throw new UserKeyVersionConflictError();
+};
+
+let userKeysIndexesPromise: Promise<void> | undefined;
+
+/** Runs the production index migration at most once per warm process. */
+export const ensureUserKeysIndexes = (): Promise<void> => {
+    // Never let an index-migration failure take the API down: log it, and clear the
+    // memo so the next request/boot retries instead of failing on a poisoned promise.
+    userKeysIndexesPromise ??= createUserKeysIndexes().catch((error: unknown) => {
+        console.error(
+            '[UserKey indexes] migration failed; requests will proceed and the migration will retry.',
+            error
+        );
+        userKeysIndexesPromise = undefined;
+    });
+
+    return userKeysIndexesPromise;
 };
 
 export const findUserKeyByContactMethod = async (
@@ -145,6 +417,22 @@ export const findUserKeyByDid = async (did: string): Promise<MongoUserKeyType |
     });
 };
 
+/** Recovery email is a proof channel, never account identity. Ambiguous matches are rejected. */
+export const findUniqueUserKeyByVerifiedRecoveryEmail = async (
+    email: string
+): Promise<MongoUserKeyType | null> => {
+    const escapedEmail = email.trim().replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const matches = await getUserKeysCollection()
+        .find({
+            recoveryEmail: { $regex: `^${escapedEmail}$`, $options: 'i' },
+            recoveryEmailVerifiedAt: { $exists: true },
+        })
+        .limit(2)
+        .toArray();
+
+    return matches.length === 1 ? matches[0]! : null;
+};
+
 /**
  * Look up a specific auth share version from the current or previous shares.
  * Returns the matching auth share, or null if the version is not found.
@@ -212,10 +500,19 @@ export const upsertUserKey = async (
             const prunedMethods = pruneOrphanedRecoveryMethods(
                 existing.recoveryMethods ?? [],
                 newCurrentVersion,
-                survivingVersions,
+                survivingVersions
             );
 
             (updateOps.$set as Record<string, unknown>).recoveryMethods = prunedMethods;
+            if (!prunedMethods.some(method => method.type === 'escrow')) {
+                delete (updateOps.$set as Record<string, unknown>).escrowBlob;
+                delete (updateOps.$set as Record<string, unknown>).escrowPin;
+                updateOps.$unset = {
+                    ...((updateOps.$unset as Record<string, unknown> | undefined) ?? {}),
+                    escrowBlob: '',
+                    escrowPin: '',
+                };
+            }
         } else if (data.authShare) {
             // First auth share — no history to push
             updateOps.$inc = { shareVersion: 1 };
@@ -248,6 +545,8 @@ export const upsertUserKey = async (
             previousAuthShares: [],
             migratedFromWeb3Auth: data.migratedFromWeb3Auth ?? false,
             migratedAt: data.migratedAt,
+            sssActivationState: data.sssActivationState,
+            provisionalCreatedAt: data.provisionalCreatedAt,
             createdAt: now,
             updatedAt: now,
         };
@@ -258,6 +557,143 @@ export const upsertUserKey = async (
     }
 };
 
+/**
+ * Create or update a UserKey by immutable provider identity. A contact-method
+ * collision intentionally creates a separate record; linking identities is an
+ * explicit authenticated flow and never a side effect of lookup.
+ */
+export const upsertUserKeyByAuthProvider = async (
+    contactMethod: ContactMethod,
+    authProvider: AuthProviderMapping,
+    data: Partial<Omit<MongoUserKeyType, '_id' | 'contactMethod' | 'createdAt' | 'authProviders'>>,
+    expectedVersion?: number
+): Promise<MongoUserKeyType> => {
+    const collection = getUserKeysCollection();
+    const now = new Date();
+    const providerFilter: Filter<MongoUserKeyType> = {
+        authProviders: { $elemMatch: authProvider },
+    };
+    const existing = await collection.findOne(providerFilter);
+
+    if (existing) {
+        const currentVersion = existing.authShare ? (existing.shareVersion ?? 1) : 0;
+
+        if (expectedVersion != null && expectedVersion !== currentVersion) {
+            throw new UserKeyVersionConflictError();
+        }
+        if (data.primaryDid !== undefined && data.primaryDid !== existing.primaryDid) {
+            throw new UserKeyVersionConflictError();
+        }
+
+        const updateOps: Record<string, unknown> = {
+            $set: {
+                ...data,
+                updatedAt: now,
+            },
+        };
+
+        if (data.authShare && existing.authShare) {
+            (updateOps.$set as Record<string, unknown>).shareVersion =
+                (existing.shareVersion ?? 1) + 1;
+            (updateOps.$set as Record<string, unknown>).shareUpdatedAt = now;
+
+            const oldEntry: PreviousAuthShare = {
+                authShare: existing.authShare,
+                shareVersion: existing.shareVersion ?? 1,
+                createdAt: existing.shareUpdatedAt ?? existing.updatedAt ?? now,
+            };
+            const history = [...(existing.previousAuthShares ?? []), oldEntry];
+            const trimmedHistory = history.slice(-MAX_PREVIOUS_AUTH_SHARES);
+            (updateOps.$set as Record<string, unknown>).previousAuthShares = trimmedHistory;
+
+            const newCurrentVersion = (existing.shareVersion ?? 1) + 1;
+            const survivingVersions = trimmedHistory.map(previous => previous.shareVersion);
+            const prunedMethods = pruneOrphanedRecoveryMethods(
+                existing.recoveryMethods ?? [],
+                newCurrentVersion,
+                survivingVersions
+            );
+            (updateOps.$set as Record<string, unknown>).recoveryMethods = prunedMethods;
+            if (!prunedMethods.some(method => method.type === 'escrow')) {
+                delete (updateOps.$set as Record<string, unknown>).escrowBlob;
+                delete (updateOps.$set as Record<string, unknown>).escrowPin;
+                updateOps.$unset = {
+                    ...((updateOps.$unset as Record<string, unknown> | undefined) ?? {}),
+                    escrowBlob: '',
+                    escrowPin: '',
+                };
+            }
+        } else if (data.authShare) {
+            (updateOps.$set as Record<string, unknown>).shareVersion =
+                (existing.shareVersion ?? 1) + 1;
+            (updateOps.$set as Record<string, unknown>).shareUpdatedAt = now;
+        }
+
+        const result = await collection.findOneAndUpdate(
+            {
+                ...providerFilter,
+                primaryDid: existing.primaryDid,
+                shareVersion: existing.shareVersion ?? null,
+                // Version 0 is a public sentinel, not necessarily the stored counter.
+                ...(existing.authShare
+                    ? { authShare: existing.authShare }
+                    : {
+                          $or: [
+                              { authShare: { $exists: false } },
+                              { authShare: { $type: 'null' } },
+                          ],
+                      }),
+            },
+            updateOps,
+            {
+                returnDocument: 'after',
+            }
+        );
+
+        if (!result) throw new UserKeyVersionConflictError();
+
+        return result;
+    }
+
+    if (expectedVersion !== undefined && expectedVersion !== 0) {
+        throw new UserKeyVersionConflictError();
+    }
+    await ensureProviderIdentityUniqueForInsert();
+    const newDoc: MongoUserKeyType = {
+        contactMethod,
+        authProviders: [authProvider],
+        primaryDid: data.primaryDid ?? '',
+        linkedDids: data.linkedDids ?? [],
+        keyProvider: data.keyProvider ?? 'sss',
+        authShare: data.authShare,
+        shareVersion: 1,
+        shareUpdatedAt: data.authShare ? now : undefined,
+        securityLevel: data.securityLevel ?? 'basic',
+        recoveryMethods: data.recoveryMethods ?? [],
+        previousAuthShares: [],
+        recoveryEmail: data.recoveryEmail,
+        recoveryEmailVerifiedAt: data.recoveryEmailVerifiedAt,
+        migratedFromWeb3Auth: data.migratedFromWeb3Auth ?? false,
+        migratedAt: data.migratedAt,
+        sssActivationState: data.sssActivationState,
+        provisionalCreatedAt: data.provisionalCreatedAt,
+        createdAt: now,
+        updatedAt: now,
+    };
+
+    try {
+        // auth_provider_identity_unique arbitrates concurrent first writes.
+        await collection.insertOne(newDoc);
+    } catch (error) {
+        if (error && typeof error === 'object' && 'code' in error && error.code === 11000) {
+            throw new UserKeyVersionConflictError();
+        }
+        throw error;
+    }
+
+    return newDoc;
+};
+
 export const addAuthProviderToUserKey = async (
     contactMethod: ContactMethod,
     authProvider: AuthProviderMapping
@@ -280,47 +716,359 @@ export const addRecoveryMethodToUserKey = async (
     contactMethod: ContactMethod,
     recoveryMethod: RecoveryMethod
 ): Promise<void> => {
-    const collection = getUserKeysCollection();
-    const now = new Date();
+    await addRecoveryMethodWithFilter(
+        {
+            'contactMethod.type': contactMethod.type,
+            'contactMethod.value': contactMethod.value,
+        },
+        recoveryMethod
+    );
+};
 
-    // Atomic: pull any existing method of the same type, then push the new one.
-    // Uses bulkWrite so both ops execute in a single server round-trip / batch,
-    // preventing a crash between $pull and $push from losing the method.
-    //
-    // For passkeys, scope the $pull by credentialId so multiple passkeys
-    // (each with a unique credentialId) can coexist. For other types
-    // (backup, phrase, email) there is at most one per type.
-    const pullFilter: Record<string, unknown> = { type: recoveryMethod.type };
+const getAuthProviderFilter = (authProvider: AuthProviderMapping): Filter<MongoUserKeyType> => ({
+    authProviders: { $elemMatch: authProvider },
+});
 
-    if (recoveryMethod.type === 'passkey') {
-        pullFilter.credentialId = recoveryMethod.credentialId ?? null;
+/** Persist verified escrow and its confirmed descriptor atomically. */
+export const setEscrowBlobByAuthProvider = async (
+    authProvider: AuthProviderMapping,
+    blob: EscrowBlob,
+    expectedShareVersion: number,
+    pin?: { salt: string },
+    carryFrom?: { blob: EscrowBlob; pin: NonNullable<MongoUserKeyType['escrowPin']> }
+): Promise<MongoUserKeyType | null> => {
+    const now = new Date();
+    const parsed = EscrowBlobValidator.safeParse(blob);
+    if (!parsed.success) throw new Error('Invalid escrow payload');
+    const validated = parsed.data;
+    if (
+        validated.shareVersion !== expectedShareVersion ||
+        validated.enclaveKeyId !== validated.envelope.keyId
+    ) {
+        return null;
     }
-
-    await collection.bulkWrite([
+    return getUserKeysCollection().findOneAndUpdate(
         {
-            updateOne: {
-                filter: {
-                    'contactMethod.type': contactMethod.type,
-                    'contactMethod.value': contactMethod.value,
+            ...getAuthProviderFilter(authProvider),
+            shareVersion: expectedShareVersion,
+            escrowOptedOutAt: { $exists: false },
+            ...(carryFrom ? { escrowBlob: carryFrom.blob, escrowPin: carryFrom.pin } : {}),
+        },
+        [
+            {
+                $set: {
+                    escrowBlob: { $literal: validated },
+                    escrowPin: carryFrom
+                        ? { $literal: { ...carryFrom.pin, shareVersion: expectedShareVersion } }
+                        : pin
+                          ? {
+                                $literal: EscrowPinValidator.parse({
+                                    salt: pin.salt,
+                                    failedAttempts: 0,
+                                    enabledAt: now,
+                                    shareVersion: expectedShareVersion,
+                                }),
+                            }
+                          : '$$REMOVE',
+                    updatedAt: now,
+                    recoveryMethods: {
+                        $concatArrays: [
+                            {
+                                $filter: {
+                                    input: { $ifNull: ['$recoveryMethods', []] },
+                                    as: 'm',
+                                    cond: { $ne: ['$$m.type', 'escrow'] },
+                                },
+                            },
+                            [
+                                {
+                                    type: 'escrow',
+                                    createdAt: now,
+                                    confirmationStatus: 'confirmed',
+                                    confirmedAt: now,
+                                    shareVersion: expectedShareVersion,
+                                },
+                            ],
+                        ],
+                    },
                 },
-                update: {
-                    $pull: { recoveryMethods: pullFilter },
+            },
+        ],
+        { returnDocument: 'after' }
+    );
+};
+
+export const clearEscrowByAuthProvider = async (
+    authProvider: AuthProviderMapping,
+    { optOut }: { optOut: boolean }
+): Promise<MongoUserKeyType | null> => {
+    const now = new Date();
+    return getUserKeysCollection().findOneAndUpdate(
+        getAuthProviderFilter(authProvider),
+        {
+            $unset: { escrowBlob: '', escrowPin: '' },
+            $pull: { recoveryMethods: { type: 'escrow' } },
+            $set: { updatedAt: now, ...(optOut ? { escrowOptedOutAt: now } : {}) },
+        },
+        { returnDocument: 'after' }
+    );
+};
+
+export const setEscrowOptInByAuthProvider = async (
+    authProvider: AuthProviderMapping
+): Promise<MongoUserKeyType | null> =>
+    getUserKeysCollection().findOneAndUpdate(
+        getAuthProviderFilter(authProvider),
+        { $unset: { escrowOptedOutAt: '' }, $set: { updatedAt: new Date() } },
+        { returnDocument: 'after' }
+    );
+
+/** Reserve before claiming a hold or invoking the enclave; never read-then-increment. */
+export const reserveEscrowPinAttempt = async (
+    authProvider: AuthProviderMapping,
+    shareVersion: number,
+    expectedCiphertext?: string
+): Promise<MongoUserKeyType | null> =>
+    getUserKeysCollection().findOneAndUpdate(
+        {
+            ...getAuthProviderFilter(authProvider),
+            shareVersion,
+            'escrowPin.shareVersion': shareVersion,
+            'escrowPin.failedAttempts': { $lt: ESCROW_PIN_MAX_ATTEMPTS },
+            'escrowPin.disabledAt': { $exists: false },
+            ...(expectedCiphertext === undefined
+                ? {}
+                : { 'escrowBlob.envelope.ciphertext': expectedCiphertext }),
+        },
+        [
+            {
+                $set: {
+                    // Legacy charged history may include unresolved reservations. Keep
+                    // its budget, but never infer verified mismatches from it.
+                    'escrowPin.verifiedFailedAttempts': {
+                        $ifNull: ['$escrowPin.verifiedFailedAttempts', 0],
+                    },
+                    'escrowPin.failedAttempts': { $add: ['$escrowPin.failedAttempts', 1] },
+                    updatedAt: new Date(),
                 },
             },
+        ],
+        { returnDocument: 'after' }
+    );
+
+/** Refund infrastructure/claim failures without modifying a replacement PIN enrollment. */
+export const refundEscrowPinAttempt = async (
+    authProvider: AuthProviderMapping,
+    shareVersion: number,
+    expectedCiphertext: string
+): Promise<void> => {
+    await getUserKeysCollection().updateOne(
+        {
+            ...getAuthProviderFilter(authProvider),
+            shareVersion,
+            'escrowPin.shareVersion': shareVersion,
+            'escrowPin.failedAttempts': { $gt: 0 },
+            'escrowPin.disabledAt': { $exists: false },
+            'escrowBlob.envelope.ciphertext': expectedCiphertext,
         },
+        { $inc: { 'escrowPin.failedAttempts': -1 }, $set: { updatedAt: new Date() } }
+    );
+};
+
+/** Only an enclave mismatch can advance verified failures and atomically disable a PIN. */
+export const recordEscrowPinFailure = async (
+    authProvider: AuthProviderMapping,
+    shareVersion: number,
+    expectedCiphertext: string
+): Promise<MongoUserKeyType | null> =>
+    getUserKeysCollection().findOneAndUpdate(
         {
-            updateOne: {
-                filter: {
-                    'contactMethod.type': contactMethod.type,
-                    'contactMethod.value': contactMethod.value,
+            ...getAuthProviderFilter(authProvider),
+            shareVersion,
+            'escrowPin.shareVersion': shareVersion,
+            'escrowBlob.envelope.ciphertext': expectedCiphertext,
+            'escrowPin.disabledAt': { $exists: false },
+        },
+        [
+            {
+                $set: {
+                    'escrowPin.verifiedFailedAttempts': {
+                        $add: ['$escrowPin.verifiedFailedAttempts', 1],
+                    },
+                    updatedAt: new Date(),
                 },
-                update: {
-                    $push: { recoveryMethods: recoveryMethod },
-                    $set: { updatedAt: now },
+            },
+            {
+                $set: {
+                    'escrowPin.disabledAt': {
+                        $cond: [
+                            {
+                                $gte: [
+                                    '$escrowPin.verifiedFailedAttempts',
+                                    ESCROW_PIN_MAX_ATTEMPTS,
+                                ],
+                            },
+                            '$$NOW',
+                            '$$REMOVE',
+                        ],
+                    },
                 },
             },
+        ],
+        { returnDocument: 'after' }
+    );
+
+export const disableEscrowPin = async (
+    authProvider: AuthProviderMapping,
+    shareVersion?: number,
+    expectedCiphertext?: string
+): Promise<boolean> => {
+    const result = await getUserKeysCollection().updateOne(
+        {
+            ...getAuthProviderFilter(authProvider),
+            escrowPin: { $exists: true },
+            'escrowPin.verifiedFailedAttempts': { $gte: ESCROW_PIN_MAX_ATTEMPTS },
+            ...(shareVersion === undefined ? {} : { 'escrowPin.shareVersion': shareVersion }),
+            ...(expectedCiphertext === undefined
+                ? {}
+                : { 'escrowBlob.envelope.ciphertext': expectedCiphertext }),
         },
-    ], { ordered: true });
+        { $set: { 'escrowPin.disabledAt': new Date(), updatedAt: new Date() } }
+    );
+    return result.matchedCount === 1;
+};
+
+const addRecoveryMethodWithFilter = async (
+    filter: Filter<MongoUserKeyType>,
+    recoveryMethod: RecoveryMethod
+): Promise<void> => {
+    const collection = getUserKeysCollection();
+    const now = new Date();
+
+    // For passkeys, scope the $pull by credentialId so multiple passkeys
+    // (each with a unique credentialId) can coexist. For other types
+    // (backup, phrase, email) there is at most one per type.
+    const keepExistingMethod =
+        recoveryMethod.type === 'passkey'
+            ? {
+                  $or: [
+                      { $ne: ['$$method.type', recoveryMethod.type] },
+                      {
+                          $ne: [
+                              { $ifNull: ['$$method.credentialId', null] },
+                              recoveryMethod.credentialId ?? null,
+                          ],
+                      },
+                  ],
+              }
+            : { $ne: ['$$method.type', recoveryMethod.type] };
+
+    await collection.updateOne(filter, [
+        {
+            $set: {
+                recoveryMethods: {
+                    $concatArrays: [
+                        {
+                            $filter: {
+                                input: { $ifNull: ['$recoveryMethods', []] },
+                                as: 'method',
+                                cond: keepExistingMethod,
+                            },
+                        },
+                        [{ $literal: recoveryMethod }],
+                    ],
+                },
+                updatedAt: now,
+            },
+        },
+    ]);
+};
+
+export const addRecoveryMethodToUserKeyByAuthProvider = async (
+    authProvider: AuthProviderMapping,
+    recoveryMethod: RecoveryMethod
+): Promise<void> => {
+    await addRecoveryMethodWithFilter(getAuthProviderFilter(authProvider), recoveryMethod);
+};
+
+export const removeRecoveryMethodFromUserKeyByAuthProvider = async (
+    authProvider: AuthProviderMapping,
+    type: RecoveryMethod['type'],
+    credentialId?: string
+): Promise<void> => {
+    const pullFilter: Record<string, unknown> = { type };
+
+    if (type === 'passkey' && credentialId) pullFilter.credentialId = credentialId;
+
+    await getUserKeysCollection().updateOne(getAuthProviderFilter(authProvider), {
+        $pull: { recoveryMethods: pullFilter },
+        ...(type === 'escrow'
+            ? { $unset: { escrowBlob: '' as const, escrowPin: '' as const } }
+            : {}),
+        $set: { updatedAt: new Date() },
+    });
+};
+
+const getRecoveryMethodSelector = (
+    type: RecoveryMethod['type'],
+    shareVersion: number,
+    credentialId?: string
+): Record<string, unknown> => ({
+    type,
+    shareVersion,
+    confirmationStatus: 'pending',
+    ...(type === 'passkey' && credentialId ? { credentialId } : {}),
+});
+
+export const incrementRecoveryConfirmationAttemptsByAuthProvider = async (
+    authProvider: AuthProviderMapping,
+    shareVersion: number
+): Promise<boolean> => {
+    const result = await getUserKeysCollection().updateOne(
+        {
+            ...getAuthProviderFilter(authProvider),
+            recoveryMethods: {
+                $elemMatch: getRecoveryMethodSelector('email', shareVersion),
+            },
+        },
+        {
+            $inc: { 'recoveryMethods.$.confirmationAttempts': 1 },
+            $set: { updatedAt: new Date() },
+        }
+    );
+
+    return result.modifiedCount === 1;
+};
+
+export const confirmRecoveryMethodByAuthProvider = async (
+    authProvider: AuthProviderMapping,
+    type: RecoveryMethod['type'],
+    shareVersion: number,
+    credentialId?: string
+): Promise<boolean> => {
+    const selector = getRecoveryMethodSelector(type, shareVersion, credentialId);
+    const now = new Date();
+    const result = await getUserKeysCollection().updateOne(
+        {
+            ...getAuthProviderFilter(authProvider),
+            recoveryMethods: { $elemMatch: selector },
+        },
+        {
+            $set: {
+                'recoveryMethods.$.confirmationStatus': 'confirmed',
+                'recoveryMethods.$.confirmedAt': now,
+                updatedAt: now,
+            },
+            $unset: {
+                'recoveryMethods.$.confirmationCodeHash': '',
+                'recoveryMethods.$.confirmationCodeExpiresAt': '',
+                'recoveryMethods.$.confirmationAttempts': '',
+                'recoveryMethods.$.confirmationEmail': '',
+            },
+        }
+    );
+
+    return result.modifiedCount === 1;
 };
 
 export const markUserKeyMigrated = async (contactMethod: ContactMethod): Promise<void> => {
@@ -342,6 +1090,114 @@ export const markUserKeyMigrated = async (contactMethod: ContactMethod): Promise
     );
 };
 
+export const markUserKeyMigratedByAuthProvider = async (
+    authProvider: AuthProviderMapping
+): Promise<void> => {
+    await getUserKeysCollection().updateOne(getAuthProviderFilter(authProvider), {
+        $set: {
+            migratedFromWeb3Auth: true,
+            migratedAt: new Date(),
+            keyProvider: 'sss',
+            updatedAt: new Date(),
+        },
+    });
+};
+
+export const markUserKeyMigrationProvisionalByAuthProvider = async (
+    authProvider: AuthProviderMapping,
+    provisionalCreatedAt: Date
+): Promise<boolean> => {
+    const result = await getUserKeysCollection().updateOne(
+        {
+            ...getAuthProviderFilter(authProvider),
+            $or: [
+                { keyProvider: 'web3auth' },
+                { keyProvider: 'sss', sssActivationState: 'provisional' },
+            ],
+        },
+        {
+            $set: {
+                // Preserve legacy fallback until recovery enrollment activates SSS.
+                keyProvider: 'web3auth',
+                sssActivationState: 'provisional',
+                provisionalCreatedAt,
+                updatedAt: new Date(),
+            },
+        }
+    );
+
+    return result.modifiedCount > 0 || result.matchedCount > 0;
+};
+
+/**
+ * Commit activation in one document update. The recovery-method predicate is
+ * included in the update filter so a concurrent removal cannot violate the
+ * activation invariant between validation and commit.
+ */
+export const activateUserKeyByAuthProvider = async (
+    authProvider: AuthProviderMapping,
+    shareVersion: number,
+    isMigration: boolean
+): Promise<boolean> => {
+    const now = new Date();
+    const migrationFields = isMigration ? { migratedFromWeb3Auth: true, migratedAt: now } : {};
+    const result = await getUserKeysCollection().updateOne(
+        {
+            ...getAuthProviderFilter(authProvider),
+            shareVersion,
+            sssActivationState: 'provisional',
+            recoveryMethods: { $elemMatch: { shareVersion, confirmedAt: { $exists: true } } },
+        },
+        {
+            $set: {
+                sssActivationState: 'active',
+                keyProvider: 'sss',
+                ...migrationFields,
+                updatedAt: now,
+            },
+            $unset: { provisionalCreatedAt: '' },
+        }
+    );
+
+    return result.modifiedCount === 1;
+};
+
+/**
+ * Lazily discard abandoned migration shares after the P0-1 TTL. New-user
+ * provisional records are excluded because their keyProvider is already SSS.
+ */
+export const purgeExpiredProvisionalMigrationByAuthProvider = async (
+    authProvider: AuthProviderMapping,
+    now = new Date()
+): Promise<boolean> => {
+    const cutoff = new Date(now.getTime() - PROVISIONAL_MIGRATION_TTL_MS);
+    const result = await getUserKeysCollection().updateOne(
+        {
+            ...getAuthProviderFilter(authProvider),
+            keyProvider: 'web3auth',
+            sssActivationState: 'provisional',
+            provisionalCreatedAt: { $lte: cutoff },
+        },
+        {
+            $set: {
+                recoveryMethods: [],
+                previousAuthShares: [],
+                updatedAt: now,
+            },
+            $unset: {
+                authShare: '',
+                escrowBlob: '',
+                escrowPin: '',
+                shareUpdatedAt: '',
+                sssActivationState: '',
+                provisionalCreatedAt: '',
+            },
+        }
+    );
+
+    return result.modifiedCount === 1;
+};
+
 export const setRecoveryEmail = async (
     contactMethod: ContactMethod,
     email: string
@@ -355,7 +1211,7 @@ export const setRecoveryEmail = async (
         },
         {
             $set: {
-                recoveryEmail: email,
+                recoveryEmail: email.trim().toLowerCase(),
                 recoveryEmailVerifiedAt: new Date(),
                 updatedAt: new Date(),
             },
@@ -363,6 +1219,19 @@ export const setRecoveryEmail = async (
     );
 };
 
+export const setRecoveryEmailByAuthProvider = async (
+    authProvider: AuthProviderMapping,
+    email: string
+): Promise<void> => {
+    await getUserKeysCollection().updateOne(getAuthProviderFilter(authProvider), {
+        $set: {
+            recoveryEmail: email.trim().toLowerCase(),
+            recoveryEmailVerifiedAt: new Date(),
+            updatedAt: new Date(),
+        },
+    });
+};
+
 export const upgradeContactMethod = async (
     oldContactMethod: ContactMethod,
     newContactMethod: ContactMethod
@@ -395,6 +1264,28 @@ export const upgradeContactMethod = async (
     return result.modifiedCount > 0;
 };
 
+export const upgradeContactMethodByAuthProvider = async (
+    authProvider: AuthProviderMapping,
+    expectedOldContactMethod: ContactMethod,
+    newContactMethod: ContactMethod
+): Promise<boolean> => {
+    const result = await getUserKeysCollection().updateOne(
+        {
+            ...getAuthProviderFilter(authProvider),
+            'contactMethod.type': expectedOldContactMethod.type,
+            'contactMethod.value': expectedOldContactMethod.value,
+        },
+        {
+            $set: {
+                contactMethod: newContactMethod,
+                updatedAt: new Date(),
+            },
+        }
+    );
+
+    return result.modifiedCount > 0;
+};
+
 export const deleteUserKey = async (contactMethod: ContactMethod): Promise<void> => {
     const collection = getUserKeysCollection();
 
@@ -403,3 +1294,96 @@ export const deleteUserKey = async (contactMethod: ContactMethod): Promise<void>
         'contactMethod.value': contactMethod.value,
     });
 };
+
+export const deleteUserKeyByAuthProvider = async (
+    authProvider: AuthProviderMapping
+): Promise<void> => {
+    await getUserKeysCollection().deleteOne(getAuthProviderFilter(authProvider));
+};
+
+export interface CompleteIdentityRebindInput {
+    oldAuthProvider: AuthProviderMapping;
+    newAuthProvider: AuthProviderMapping;
+    newContactMethod: ContactMethod;
+    primaryDid: string;
+    authShare: ServerEncryptedShare;
+}
+
+/**
+ * Atomically bind a replacement login identity and commit a security rotation.
+ * Historical auth shares are purged. Existing recovery methods are retained only
+ * as unconfirmed descriptors because their external shares belong to the old split.
+ */
+export const completeIdentityRebind = async (
+    input: CompleteIdentityRebindInput
+): Promise<{
+    shareVersion: number;
+    methodsRequiringConfirmation: RecoveryMethod['type'][];
+} | null> => {
+    const collection = getUserKeysCollection();
+    const existing = await collection.findOne({
+        ...getAuthProviderFilter(input.oldAuthProvider),
+        primaryDid: input.primaryDid,
+    });
+
+    if (!existing) return null;
+
+    const providerConflict = await collection.findOne({
+        ...getAuthProviderFilter(input.newAuthProvider),
+        ...(existing._id ? { _id: { $ne: existing._id } } : {}),
+    });
+
+    if (providerConflict) return null;
+
+    const now = new Date();
+    const shareVersion = (existing.shareVersion ?? 1) + 1;
+    const remainingAuthProviders = (existing.authProviders ?? []).filter(
+        provider =>
+            provider.type !== input.oldAuthProvider.type || provider.id !== input.oldAuthProvider.id
+    );
+    const authProviders = remainingAuthProviders.some(
+        provider =>
+            provider.type === input.newAuthProvider.type && provider.id === input.newAuthProvider.id
+    )
+        ? remainingAuthProviders
+        : [...remainingAuthProviders, input.newAuthProvider];
+    const recoveryMethods = (existing.recoveryMethods ?? []).map(method => ({
+        type: method.type,
+        createdAt: now,
+        confirmationStatus: 'pending' as const,
+        credentialId: method.credentialId,
+        shareVersion,
+    }));
+    const result = await collection.findOneAndUpdate(
+        {
+            ...getAuthProviderFilter(input.oldAuthProvider),
+            primaryDid: input.primaryDid,
+            shareVersion: existing.shareVersion ?? 1,
+        },
+        {
+            $set: {
+                authProviders,
+                contactMethod: input.newContactMethod,
+                authShare: input.authShare,
+                shareVersion,
+                shareUpdatedAt: now,
+                previousAuthShares: [],
+                recoveryMethods,
+                keyProvider: 'sss',
+                // The new split has no confirmed recovery method yet. SSS records
+                // are excluded from provisional migration cleanup (Web3Auth only).
+                sssActivationState: 'provisional',
+                updatedAt: now,
+            },
+            $unset: { provisionalCreatedAt: '', escrowBlob: '', escrowPin: '' },
+        },
+        { returnDocument: 'after' }
+    );
+
+    if (!result) return null;
+
+    return {
+        shareVersion,
+        methodsRequiringConfirmation: recoveryMethods.map(method => method.type),
+    };
+};