@tatchi-xyz/sdk 0.20.0 → 0.31.0

package/dist/esm/core/WebAuthnManager/index.js

@@ -1,20 +1,25 @@
-import { init_accountIds, toAccountId } from "../types/accountIds.js";
-import { IndexedDBManager, init_IndexedDBManager } from "../IndexedDBManager/index.js";
+import { ensureEd25519Prefix } from "../../utils/validation.js";
+import { toAccountId } from "../types/accountIds.js";
+import { INTERNAL_WORKER_REQUEST_TYPE_SIGN_ADD_KEY_THRESHOLD_PUBLIC_KEY_NO_PROMPT, isSignAddKeyThresholdPublicKeyNoPromptSuccess } from "../types/signer-worker.js";
+import { buildThresholdEd25519Participants2pV1 } from "../../threshold/participants.js";
+import { IndexedDBManager } from "../IndexedDBManager/index.js";
+import { DEFAULT_WAIT_STATUS } from "../types/rpc.js";
+import { SignedTransaction } from "../NearClient.js";
 import { onEmbeddedBaseChange } from "../sdkPaths/base.js";
 import { resolveWorkerBaseOrigin } from "../sdkPaths/workers.js";
-import { TouchIdPrompt, init_touchIdPrompt } from "./touchIdPrompt.js";
-import { getLastLoggedInDeviceNumber, init_getDeviceNumber } from "./SignerWorkerManager/getDeviceNumber.js";
+import { TouchIdPrompt } from "./touchIdPrompt.js";
+import { hasAccessKey } from "../rpcCalls.js";
+import { getLastLoggedInDeviceNumber } from "./SignerWorkerManager/getDeviceNumber.js";
+import { collectAuthenticationCredentialForVrfChallenge } from "./collectAuthenticationCredentialForVrfChallenge.js";
 import { SignerWorkerManager } from "./SignerWorkerManager/index.js";
 import { VrfWorkerManager } from "./VrfWorkerManager/index.js";
 import userPreferences_default from "./userPreferences.js";
 import nonceManager_default from "../nonceManager.js";
 import { __isWalletIframeHostMode } from "../WalletIframe/host-mode.js";
+import { enrollThresholdEd25519KeyHandler } from "./threshold/enrollThresholdEd25519Key.js";
+import { rotateThresholdEd25519KeyPostRegistrationHandler } from "./threshold/rotateThresholdEd25519KeyPostRegistration.js";
 
 //#region src/core/WebAuthnManager/index.ts
-init_IndexedDBManager();
-init_touchIdPrompt();
-init_accountIds();
-init_getDeviceNumber();
 /**
 * WebAuthnManager - Main orchestrator for WebAuthn operations
 *
@@ -39,9 +44,8 @@ var WebAuthnManager = class {
 		this.nearClient = nearClient;
 		this.touchIdPrompt = new TouchIdPrompt(tatchiPasskeyConfigs.iframeWallet?.rpIdOverride, true);
 		this.userPreferencesManager = userPreferences_default;
-		try {
-			this.userPreferencesManager.configureWalletTheme?.(tatchiPasskeyConfigs.walletTheme);
-		} catch {}
+		this.userPreferencesManager.configureWalletTheme?.(tatchiPasskeyConfigs.walletTheme);
+		this.userPreferencesManager.configureDefaultSignerMode?.(tatchiPasskeyConfigs.signerMode);
 		this.nonceManager = nonceManager_default;
 		const { vrfWorkerConfigs } = tatchiPasskeyConfigs;
 		this.vrfWorkerManager = new VrfWorkerManager({
@@ -58,7 +62,7 @@ var WebAuthnManager = class {
 			rpIdOverride: this.touchIdPrompt.getRpId(),
 			nearExplorerUrl: tatchiPasskeyConfigs.nearExplorerUrl
 		});
-		this.signerWorkerManager = new SignerWorkerManager(this.vrfWorkerManager, nearClient, this.userPreferencesManager, this.nonceManager, tatchiPasskeyConfigs.iframeWallet?.rpIdOverride, true, tatchiPasskeyConfigs.nearExplorerUrl);
+		this.signerWorkerManager = new SignerWorkerManager(this.vrfWorkerManager, nearClient, this.userPreferencesManager, this.nonceManager, this.tatchiPasskeyConfigs.relayer.url, tatchiPasskeyConfigs.iframeWallet?.rpIdOverride, true, tatchiPasskeyConfigs.nearExplorerUrl);
 		this.workerBaseOrigin = resolveWorkerBaseOrigin() || (typeof window !== "undefined" ? window.location.origin : "");
 		this.signerWorkerManager.setWorkerBaseOrigin(this.workerBaseOrigin);
 		this.vrfWorkerManager.setWorkerBaseOrigin?.(this.workerBaseOrigin);
@@ -140,7 +144,7 @@ var WebAuthnManager = class {
 	}
 	async withSigningSession(args) {
 		if (typeof args.handler !== "function") throw new Error("withSigningSession requires a handler function");
-		const sessionId = (args.sessionId || "").trim() || (args.prefix ? this.generateSessionId(args.prefix) : "");
+		const sessionId = args.sessionId || (args.prefix ? this.generateSessionId(args.prefix) : "");
 		if (!sessionId) throw new Error("withSigningSession requires a sessionId or prefix");
 		return await this.withSigningSessionInternal({
 			sessionId,
@@ -154,6 +158,7 @@ var WebAuthnManager = class {
 		try {
 			if (args.options) await this.vrfWorkerManager.mintSessionKeysAndSendToSigner({
 				sessionId: args.sessionId,
+				wrapKeySalt: args.options.wrapKeySalt,
 				credential: args.options.credential
 			});
 			return await args.handler(args.sessionId);
@@ -191,15 +196,15 @@ var WebAuthnManager = class {
 		if (deviceNumber === null) throw new Error(`No deviceNumber found for account ${nearAccountId} (decrypt session)`);
 		const userForDevice = await IndexedDBManager.clientDB.getUserByDevice(nearAccountId, deviceNumber).catch(() => null);
 		const encryptedVrfKeypair = userForDevice?.encryptedVrfKeypair;
-		const encryptedKeyData = await IndexedDBManager.nearKeysDB.getEncryptedKey(nearAccountId, deviceNumber);
-		if (!encryptedKeyData) {
+		const keyMaterial = await IndexedDBManager.nearKeysDB.getLocalKeyMaterial(nearAccountId, deviceNumber);
+		if (!keyMaterial) {
 			console.error("WebAuthnManager: No encrypted key found for decrypt session", {
 				nearAccountId: String(nearAccountId),
 				deviceNumber
 			});
-			throw new Error(`No encrypted key found for account: ${nearAccountId}`);
+			throw new Error(`No key material found for account: ${nearAccountId}`);
 		}
-		const wrapKeySalt = encryptedKeyData.wrapKeySalt || "";
+		const wrapKeySalt = keyMaterial.wrapKeySalt;
 		if (!wrapKeySalt) {
 			console.error("WebAuthnManager: Missing wrapKeySalt in vault for decrypt session", {
 				nearAccountId: String(nearAccountId),
@@ -230,6 +235,16 @@ var WebAuthnManager = class {
 			allowCredentials
 		});
 	}
+	async collectAuthenticationCredentialForVrfChallenge(args) {
+		return collectAuthenticationCredentialForVrfChallenge({
+			indexedDB: IndexedDBManager,
+			touchIdPrompt: this.touchIdPrompt,
+			nearAccountId: args.nearAccountId,
+			vrfChallenge: args.vrfChallenge,
+			includeSecondPrfOutput: args.includeSecondPrfOutput,
+			onBeforePrompt: args.onBeforePrompt
+		});
+	}
 	/**
 	* Generate a VRF challenge bound to a specific signing/confirm session.
 	* The challenge will be cached in the VRF worker under this sessionId so
@@ -301,9 +316,9 @@ var WebAuthnManager = class {
 		const contractId = this.tatchiPasskeyConfigs.contractId;
 		try {
 			const sessionId = `device2-sign-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
-			const encryptedKeyData = await IndexedDBManager.nearKeysDB.getEncryptedKey(nearAccountId, deviceNumber);
-			if (!encryptedKeyData) throw new Error(`No encrypted key found for account ${nearAccountId} device ${deviceNumber}`);
-			const wrapKeySalt = encryptedKeyData.wrapKeySalt;
+			const keyMaterial = await IndexedDBManager.nearKeysDB.getLocalKeyMaterial(nearAccountId, deviceNumber);
+			if (!keyMaterial) throw new Error(`No key material found for account ${nearAccountId} device ${deviceNumber}`);
+			const wrapKeySalt = keyMaterial.wrapKeySalt;
 			if (!wrapKeySalt) throw new Error(`Missing wrapKeySalt for account ${nearAccountId} device ${deviceNumber}`);
 			const signerPort = await this.vrfWorkerManager.createSigningSessionChannel(sessionId);
 			await this.signerWorkerManager.reserveSignerWorkerSession(sessionId, { signerPort });
@@ -466,10 +481,28 @@ var WebAuthnManager = class {
 		const vrfStatus = await this.vrfWorkerManager.checkVrfStatus();
 		if (!vrfStatus.active) throw new Error("VRF keypair not active in memory. Please log in again.");
 		if (!vrfStatus.nearAccountId || String(vrfStatus.nearAccountId) !== String(nearAccountId)) throw new Error("VRF keypair active but bound to a different account. Please log in again.");
-		const deviceNumber = await getLastLoggedInDeviceNumber(nearAccountId, IndexedDBManager.clientDB);
-		const encryptedKeyData = await IndexedDBManager.nearKeysDB.getEncryptedKey(nearAccountId, deviceNumber);
-		if (!encryptedKeyData) throw new Error(`No encrypted key found for account ${nearAccountId} device ${deviceNumber}`);
-		const wrapKeySalt = encryptedKeyData.wrapKeySalt || "";
+		const credentialRawId = String(args.credential?.rawId || "").trim();
+		const authenticators = await this.getAuthenticatorsByUser(nearAccountId).catch(() => []);
+		let deviceNumber;
+		try {
+			deviceNumber = await getLastLoggedInDeviceNumber(nearAccountId, IndexedDBManager.clientDB);
+		} catch (err) {
+			if (credentialRawId) {
+				const matched = authenticators.find((a) => a.credentialId === credentialRawId);
+				const inferred = matched && typeof matched.deviceNumber === "number" && Number.isFinite(matched.deviceNumber) ? matched.deviceNumber : null;
+				if (inferred !== null) {
+					deviceNumber = inferred;
+					await this.setLastUser(nearAccountId, inferred).catch(() => void 0);
+				} else throw err;
+			} else throw err;
+		}
+		if (credentialRawId && authenticators.length > 1) {
+			const { wrongPasskeyError } = await IndexedDBManager.clientDB.ensureCurrentPasskey(nearAccountId, authenticators, credentialRawId);
+			if (wrongPasskeyError) throw new Error(wrongPasskeyError);
+		}
+		const keyMaterial = await IndexedDBManager.nearKeysDB.getLocalKeyMaterial(nearAccountId, deviceNumber);
+		if (!keyMaterial) throw new Error(`No key material found for account ${nearAccountId} device ${deviceNumber}`);
+		const wrapKeySalt = keyMaterial.wrapKeySalt;
 		if (!wrapKeySalt) throw new Error("Missing wrapKeySalt in vault; re-register to upgrade vault format.");
 		const { ttlMs, remainingUses } = this.resolveSigningSessionPolicy(args);
 		await this.vrfWorkerManager.mintSessionKeysAndSendToSigner({
@@ -674,14 +707,13 @@ var WebAuthnManager = class {
 	* @param onEvent: Optional callback for progress updates during signing
 	* @param onEvent - Optional callback for progress updates during signing
 	*/
-	async signTransactionsWithActions({ transactions, rpcCall, confirmationConfigOverride, title, body, onEvent }) {
-		if (transactions.length === 0) throw new Error("No payloads provided for signing");
-		const activeSessionId = this.getOrCreateActiveSigningSessionId(toAccountId(rpcCall.nearAccountId));
+	async signTransactionsWithActions({ transactions, rpcCall, signerMode, confirmationConfigOverride, title, body, onEvent }) {
 		return this.withSigningSession({
-			sessionId: activeSessionId,
+			sessionId: this.getOrCreateActiveSigningSessionId(toAccountId(rpcCall.nearAccountId)),
 			handler: (sessionId) => this.signerWorkerManager.signTransactionsWithActions({
 				transactions,
 				rpcCall,
+				signerMode,
 				confirmationConfigOverride,
 				title,
 				body,
@@ -690,7 +722,74 @@ var WebAuthnManager = class {
 			})
 		});
 	}
-	async signDelegateAction({ delegate, rpcCall, confirmationConfigOverride, title, body, onEvent }) {
+	/**
+	* Sign AddKey(thresholdPublicKey) for `receiverId === nearAccountId` without running confirmTxFlow.
+	*
+	* This is a narrowly-scoped, internal-only helper for post-registration activation flows where
+	* the caller already has a PRF-bearing credential in memory (e.g., immediately after registration)
+	* and wants to avoid an extra TouchID/WebAuthn prompt.
+	*/
+	async signAddKeyThresholdPublicKeyNoPrompt(args) {
+		const nearAccountId = toAccountId(args.nearAccountId);
+		const wrapKeySalt = args.wrapKeySalt;
+		if (!wrapKeySalt) throw new Error("Missing wrapKeySalt for AddKey(thresholdPublicKey) signing");
+		if (!args.credential) throw new Error("Missing credential for AddKey(thresholdPublicKey) signing");
+		if (!args.transactionContext) throw new Error("Missing transactionContext for no-prompt signing");
+		const thresholdPublicKey = ensureEd25519Prefix(args.thresholdPublicKey);
+		if (!thresholdPublicKey) throw new Error("Missing thresholdPublicKey for AddKey(thresholdPublicKey) signing");
+		const relayerVerifyingShareB64u = args.relayerVerifyingShareB64u;
+		if (!relayerVerifyingShareB64u) throw new Error("Missing relayerVerifyingShareB64u for AddKey(thresholdPublicKey) signing");
+		const deviceNumber = Number(args.deviceNumber);
+		const resolvedDeviceNumber = Number.isSafeInteger(deviceNumber) && deviceNumber >= 1 ? deviceNumber : await getLastLoggedInDeviceNumber(nearAccountId, IndexedDBManager.clientDB).catch(() => 1);
+		const localKeyMaterial = await IndexedDBManager.nearKeysDB.getLocalKeyMaterial(nearAccountId, resolvedDeviceNumber);
+		if (!localKeyMaterial) throw new Error(`No local key material found for account ${nearAccountId} device ${resolvedDeviceNumber}`);
+		if (localKeyMaterial.wrapKeySalt !== wrapKeySalt) throw new Error("wrapKeySalt mismatch for AddKey(thresholdPublicKey) signing");
+		return await this.withSigningSession({
+			prefix: "no-prompt-add-threshold-key",
+			options: {
+				credential: args.credential,
+				wrapKeySalt
+			},
+			handler: async (sessionId) => {
+				const response = await this.signerWorkerManager.getContext().sendMessage({
+					sessionId,
+					message: {
+						type: INTERNAL_WORKER_REQUEST_TYPE_SIGN_ADD_KEY_THRESHOLD_PUBLIC_KEY_NO_PROMPT,
+						payload: {
+							createdAt: Date.now(),
+							decryption: {
+								encryptedPrivateKeyData: localKeyMaterial.encryptedSk,
+								encryptedPrivateKeyChacha20NonceB64u: localKeyMaterial.chacha20NonceB64u
+							},
+							transactionContext: args.transactionContext,
+							nearAccountId,
+							thresholdPublicKey,
+							relayerVerifyingShareB64u,
+							clientParticipantId: typeof args.clientParticipantId === "number" ? args.clientParticipantId : void 0,
+							relayerParticipantId: typeof args.relayerParticipantId === "number" ? args.relayerParticipantId : void 0
+						}
+					},
+					onEvent: args.onEvent
+				});
+				if (!isSignAddKeyThresholdPublicKeyNoPromptSuccess(response)) throw new Error("AddKey(thresholdPublicKey) signing failed");
+				if (!response.payload.success) throw new Error(response.payload.error || "AddKey(thresholdPublicKey) signing failed");
+				const signedTransactions = response.payload.signedTransactions || [];
+				if (signedTransactions.length !== 1) throw new Error(`Expected 1 signed transaction but received ${signedTransactions.length}`);
+				const signedTx = signedTransactions[0];
+				if (!signedTx || !signedTx.transaction || !signedTx.signature) throw new Error("Incomplete signed transaction data received for AddKey(thresholdPublicKey)");
+				return {
+					signedTransaction: new SignedTransaction({
+						transaction: signedTx.transaction,
+						signature: signedTx.signature,
+						borsh_bytes: Array.from(signedTx.borshBytes || [])
+					}),
+					nearAccountId: String(nearAccountId),
+					logs: response.payload.logs || []
+				};
+			}
+		});
+	}
+	async signDelegateAction({ delegate, rpcCall, signerMode, confirmationConfigOverride, title, body, onEvent }) {
 		const nearAccountId = toAccountId(rpcCall.nearAccountId || delegate.senderId);
 		const normalizedRpcCall = {
 			contractId: rpcCall.contractId || this.tatchiPasskeyConfigs.contractId,
@@ -706,6 +805,7 @@ var WebAuthnManager = class {
 					return this.signerWorkerManager.signDelegateAction({
 						delegate,
 						rpcCall: normalizedRpcCall,
+						signerMode,
 						confirmationConfigOverride,
 						title,
 						body,
@@ -752,29 +852,6 @@ var WebAuthnManager = class {
 	async extractCosePublicKey(attestationObjectBase64url) {
 		return await this.signerWorkerManager.extractCosePublicKey(attestationObjectBase64url);
 	}
-	/**
-	* Helper to ensure the local `lastUser` pointer is consistent with the latest DB updates.
-	* This fixes issues where a recovery or registration might have updated the user record
-	* but failed to update the `lastUser` pointer (e.g. due to previous bugs or interruptions),
-	* preventing the strict `ensureCurrentPasskey` check from passing.
-	*/
-	async autoHealLastUserPointer(nearAccountId) {
-		try {
-			const lastUser = await this.getLastUser();
-			if (lastUser && lastUser.nearAccountId === nearAccountId) {
-				const freshest = await IndexedDBManager.clientDB.getLastDBUpdatedUser(nearAccountId);
-				if (freshest && freshest.deviceNumber !== lastUser.deviceNumber) {
-					console.log(`[WebAuthnManager] Auto-healing lastUser pointer from device ${lastUser.deviceNumber} to ${freshest.deviceNumber}`);
-					await this.setLastUser(nearAccountId, freshest.deviceNumber);
-				}
-			} else {
-				const freshest = await IndexedDBManager.clientDB.getLastDBUpdatedUser(nearAccountId);
-				if (freshest) await this.setLastUser(nearAccountId, freshest.deviceNumber);
-			}
-		} catch (e) {
-			console.warn("[WebAuthnManager] Auto-heal pointer failed (non-fatal):", e);
-		}
-	}
 	/** Worker-driven export: two-phase V2 (collect PRF → decrypt → show UI) */
 	async exportNearKeypairWithUIWorkerDriven(nearAccountId, options) {
 		await this.withSigningSession({
@@ -799,7 +876,7 @@ var WebAuthnManager = class {
 		if (!userData || userData.nearAccountId !== nearAccountId) userData = await IndexedDBManager.clientDB.getLastDBUpdatedUser(nearAccountId);
 		return {
 			accountId: String(nearAccountId),
-			publicKey: String(userData?.clientNearPublicKey || ""),
+			publicKey: userData?.clientNearPublicKey ?? "",
 			privateKey: ""
 		};
 	}
@@ -872,6 +949,232 @@ var WebAuthnManager = class {
 			actions
 		});
 	}
+	/**
+	* Derive the deterministic threshold client verifying share (2-of-2 ed25519) from WrapKeySeed.
+	* This is safe to call during registration because it only requires the PRF-bearing credential
+	* (no on-chain verification needed) and returns public material only.
+	*/
+	async deriveThresholdEd25519ClientVerifyingShareFromCredential(args) {
+		const nearAccountId = toAccountId(args.nearAccountId);
+		try {
+			return await this.withSigningSession({
+				prefix: "threshold-client-share",
+				options: {
+					credential: args.credential,
+					wrapKeySalt: args.wrapKeySalt
+				},
+				handler: (sessionId) => this.signerWorkerManager.deriveThresholdEd25519ClientVerifyingShare({
+					sessionId,
+					nearAccountId
+				})
+			});
+		} catch (error) {
+			const message = String(error?.message ?? error);
+			return {
+				success: false,
+				nearAccountId,
+				clientVerifyingShareB64u: "",
+				wrapKeySalt: "",
+				error: message
+			};
+		}
+	}
+	/**
+	* Threshold key enrollment (post-registration):
+	* prompts for a dual-PRF WebAuthn authentication to obtain PRF.first/second,
+	* then runs the `/threshold-ed25519/keygen` enrollment flow.
+	*
+	* This is intended to be called only after the passkey is registered on-chain.
+	*/
+	async enrollThresholdEd25519KeyPostRegistration(args) {
+		const nearAccountId = toAccountId(args.nearAccountId);
+		try {
+			const rpId = this.touchIdPrompt.getRpId();
+			if (!rpId) throw new Error("Missing rpId for WebAuthn VRF challenge");
+			const block = await this.nearClient.viewBlock({ finality: "final" });
+			const blockHeight = String(block?.header?.height ?? "");
+			const blockHash = String(block?.header?.hash ?? "");
+			if (!blockHeight || !blockHash) throw new Error("Failed to fetch NEAR block context for VRF challenge");
+			const vrfChallenge = await this.vrfWorkerManager.generateVrfChallengeOnce({
+				userId: nearAccountId,
+				rpId,
+				blockHeight,
+				blockHash
+			});
+			const authenticators = await this.getAuthenticatorsByUser(nearAccountId);
+			if (!authenticators.length) throw new Error(`No passkey authenticators found for account ${nearAccountId}`);
+			const authCredential = await this.collectAuthenticationCredentialForVrfChallenge({
+				nearAccountId,
+				vrfChallenge,
+				includeSecondPrfOutput: true
+			});
+			return await this.enrollThresholdEd25519Key({
+				credential: authCredential,
+				nearAccountId,
+				deviceNumber: args.deviceNumber
+			});
+		} catch (error) {
+			const message = String(error?.message ?? error);
+			return {
+				success: false,
+				publicKey: "",
+				relayerKeyId: "",
+				wrapKeySalt: "",
+				error: message
+			};
+		}
+	}
+	/**
+	* Threshold key rotation (post-registration):
+	* - keygen (new relayerKeyId + publicKey)
+	* - AddKey(new threshold publicKey)
+	* - DeleteKey(old threshold publicKey)
+	*
+	* Uses the local signer key for AddKey/DeleteKey, and requires the account to already
+	* have a stored `threshold_ed25519_2p_v1` key material entry for the target device.
+	*/
+	async rotateThresholdEd25519KeyPostRegistration(args) {
+		const nearAccountId = toAccountId(args.nearAccountId);
+		let oldPublicKey = "";
+		let oldRelayerKeyId = "";
+		try {
+			const deviceNumber = Number(args.deviceNumber);
+			const resolvedDeviceNumber = Number.isSafeInteger(deviceNumber) && deviceNumber >= 1 ? deviceNumber : await getLastLoggedInDeviceNumber(nearAccountId, IndexedDBManager.clientDB).catch(() => 1);
+			const existing = await IndexedDBManager.nearKeysDB.getThresholdKeyMaterial(nearAccountId, resolvedDeviceNumber);
+			if (!existing) throw new Error(`No threshold key material found for account ${nearAccountId} device ${resolvedDeviceNumber}. Call enrollThresholdEd25519Key() first.`);
+			oldPublicKey = existing.publicKey;
+			oldRelayerKeyId = existing.relayerKeyId;
+			const enrollment = await this.enrollThresholdEd25519KeyPostRegistration({
+				nearAccountId,
+				deviceNumber: resolvedDeviceNumber
+			});
+			if (!enrollment.success) throw new Error(enrollment.error || "Threshold keygen/enrollment failed");
+			return await rotateThresholdEd25519KeyPostRegistrationHandler({
+				nearClient: this.nearClient,
+				contractId: this.tatchiPasskeyConfigs.contractId,
+				nearRpcUrl: this.tatchiPasskeyConfigs.nearRpcUrl,
+				signTransactionsWithActions: (params) => this.signTransactionsWithActions(params)
+			}, {
+				nearAccountId,
+				deviceNumber: resolvedDeviceNumber,
+				oldPublicKey,
+				oldRelayerKeyId,
+				newPublicKey: enrollment.publicKey,
+				newRelayerKeyId: enrollment.relayerKeyId,
+				wrapKeySalt: enrollment.wrapKeySalt
+			});
+		} catch (error) {
+			const message = String(error?.message ?? error);
+			return {
+				success: false,
+				oldPublicKey,
+				oldRelayerKeyId,
+				publicKey: "",
+				relayerKeyId: "",
+				wrapKeySalt: "",
+				deleteOldKeyAttempted: false,
+				deleteOldKeySuccess: false,
+				error: message
+			};
+		}
+	}
+	/**
+	* Threshold key enrollment (2-of-2): deterministically derive the client verifying share
+	* from WrapKeySeed and register the corresponding relayer share via `/threshold-ed25519/keygen`.
+	*
+	* Stores a v3 vault entry of kind `threshold_ed25519_2p_v1` (breaking; no migration).
+	*/
+	async enrollThresholdEd25519Key(args) {
+		const nearAccountId = toAccountId(args.nearAccountId);
+		const relayerUrl = this.tatchiPasskeyConfigs.relayer.url;
+		try {
+			if (!relayerUrl) throw new Error("Missing relayer url (configs.relayer.url)");
+			if (!args.credential) throw new Error("Missing credential");
+			const deviceNumber = Number(args.deviceNumber);
+			const resolvedDeviceNumber = Number.isSafeInteger(deviceNumber) && deviceNumber >= 1 ? deviceNumber : await getLastLoggedInDeviceNumber(nearAccountId, IndexedDBManager.clientDB).catch(() => 1);
+			const keygen = await this.withSigningSession({
+				prefix: "threshold-keygen",
+				options: { credential: args.credential },
+				handler: (sessionId) => enrollThresholdEd25519KeyHandler({
+					nearClient: this.nearClient,
+					vrfWorkerManager: this.vrfWorkerManager,
+					signerWorkerManager: this.signerWorkerManager,
+					touchIdPrompt: this.touchIdPrompt,
+					relayerUrl
+				}, {
+					sessionId,
+					nearAccountId
+				})
+			});
+			if (!keygen.success) throw new Error(keygen.error || "Threshold keygen failed");
+			const publicKey = keygen.publicKey;
+			const clientVerifyingShareB64u = keygen.clientVerifyingShareB64u;
+			const relayerKeyId = keygen.relayerKeyId;
+			const relayerVerifyingShareB64u = keygen.relayerVerifyingShareB64u;
+			if (!clientVerifyingShareB64u) throw new Error("Threshold keygen returned empty clientVerifyingShareB64u");
+			const localKeyMaterial = await IndexedDBManager.nearKeysDB.getLocalKeyMaterial(nearAccountId, resolvedDeviceNumber);
+			if (!localKeyMaterial) throw new Error(`No local key material found for account ${nearAccountId} device ${resolvedDeviceNumber}`);
+			const alreadyActive = await hasAccessKey(this.nearClient, nearAccountId, publicKey, {
+				attempts: 1,
+				delayMs: 0
+			});
+			if (!alreadyActive) {
+				this.nonceManager.initializeUser(nearAccountId, localKeyMaterial.publicKey);
+				const txContext = await this.nonceManager.getNonceBlockHashAndHeight(this.nearClient, { force: true });
+				const signed = await this.signAddKeyThresholdPublicKeyNoPrompt({
+					nearAccountId,
+					credential: args.credential,
+					wrapKeySalt: localKeyMaterial.wrapKeySalt,
+					transactionContext: txContext,
+					thresholdPublicKey: publicKey,
+					relayerVerifyingShareB64u,
+					clientParticipantId: keygen.clientParticipantId,
+					relayerParticipantId: keygen.relayerParticipantId,
+					deviceNumber: resolvedDeviceNumber
+				});
+				const signedTx = signed?.signedTransaction;
+				if (!signedTx) throw new Error("Failed to sign AddKey(thresholdPublicKey) transaction");
+				await this.nearClient.sendTransaction(signedTx, DEFAULT_WAIT_STATUS.thresholdAddKey);
+				const activated = await hasAccessKey(this.nearClient, nearAccountId, publicKey);
+				if (!activated) throw new Error("Threshold access key not found on-chain after AddKey");
+			}
+			const keyMaterial = {
+				kind: "threshold_ed25519_2p_v1",
+				nearAccountId,
+				deviceNumber: resolvedDeviceNumber,
+				publicKey,
+				wrapKeySalt: keygen.wrapKeySalt,
+				relayerKeyId,
+				clientShareDerivation: "prf_first_v1",
+				participants: buildThresholdEd25519Participants2pV1({
+					clientParticipantId: keygen.clientParticipantId,
+					relayerParticipantId: keygen.relayerParticipantId,
+					relayerKeyId,
+					relayerUrl,
+					clientVerifyingShareB64u,
+					relayerVerifyingShareB64u,
+					clientShareDerivation: "prf_first_v1"
+				}),
+				timestamp: Date.now()
+			};
+			await IndexedDBManager.nearKeysDB.storeKeyMaterial(keyMaterial);
+			return {
+				success: true,
+				publicKey,
+				relayerKeyId,
+				wrapKeySalt: keygen.wrapKeySalt
+			};
+		} catch (error) {
+			const message = String(error?.message ?? error);
+			return {
+				success: false,
+				publicKey: "",
+				relayerKeyId: "",
+				wrapKeySalt: "",
+				error: message
+			};
+		}
+	}
 	/** * Get user preferences manager */
 	getUserPreferences() {
 		return this.userPreferencesManager;