Merge pull-request #1200

Author: ethankonk

.changeset/proud-streets-exist.md

@@ -0,0 +1,5 @@
+---
+"@turnkey/iframe-stamper": minor
+---
+
+Added the ability to override the iframe's embedded key pair using a Turnkey P256 private key exported and encrypted to the iframe's embedded key pair.

examples/disaster-recovery/README.md

@@ -27,6 +27,7 @@ pnpm start
 ```
 
 The interactive CLI provides a menu-driven interface for all disaster recovery operations:
+
 - Generate test wallets for testing/PoC
 - Path 1: Import wallets and sweep funds
 - Path 2: Set up and recover from encryption escrow
@@ -67,11 +68,13 @@ pnpm run generate-test-wallet
 ```
 
 This will:
+
 1. Generate a random 12 or 24 word mnemonic, OR a raw private key
 2. Show the derived Ethereum address
 3. Optionally save to a JSON file for reference
 
 **Testing flow:**
+
 1. Generate a test wallet
 2. Fund it with Sepolia testnet ETH from a faucet:
    - https://sepoliafaucet.com
@@ -87,12 +90,12 @@ This will:
 
 ### Why This Approach
 
-| Benefit | Description |
-|---------|-------------|
-| Immediate Recovery | Keys are operational within Turnkey instantly—no decryption ceremonies |
-| Asset Agnostic | Single path for Bitcoin, Ethereum, Solana, and any SECP256k1/Ed25519 chains |
-| Fund Sweeping | SDK enables rapid fund movement without custom tooling |
-| Policy Controls | Full access to quorum policies, whitelisting, and transaction limits |
+| Benefit            | Description                                                                 |
+| ------------------ | --------------------------------------------------------------------------- |
+| Immediate Recovery | Keys are operational within Turnkey instantly—no decryption ceremonies      |
+| Asset Agnostic     | Single path for Bitcoin, Ethereum, Solana, and any SECP256k1/Ed25519 chains |
+| Fund Sweeping      | SDK enables rapid fund movement without custom tooling                      |
+| Policy Controls    | Full access to quorum policies, whitelisting, and transaction limits        |
 
 ### Import HD Wallet (Mnemonic)
 
@@ -103,6 +106,7 @@ pnpm run path1:import-wallet
 ```
 
 This will:
+
 1. Initialize an import bundle (temporary encryption key from Turnkey's enclave)
 2. Prompt for your mnemonic seed phrase
 3. Encrypt the mnemonic to Turnkey's ephemeral public key
@@ -117,6 +121,7 @@ pnpm run path1:import-key
 ```
 
 Supports:
+
 - Ethereum/EVM (SECP256K1)
 - Solana (ED25519)
 - Bitcoin (SECP256K1)
@@ -134,6 +139,7 @@ pnpm run path1:sweep-funds
 ```
 
 Features:
+
 - Network selection (Sepolia testnet or Mainnet)
 - Gas estimation and balance checking
 - Confirmation prompts for safety
@@ -183,6 +189,7 @@ pnpm run path2:setup
 ```
 
 This will:
+
 1. Create a P-256 encryption keypair in Turnkey (for encryption only, not on-chain)
 2. Prompt for your recovery material (mnemonic, credentials, or custom data)
 3. Encrypt the bundle with Turnkey's public key
@@ -200,18 +207,19 @@ pnpm run path2:recovery
 ```
 
 This will:
+
 1. Generate a target keypair for receiving the exported key
 2. Export the encryption private key from Turnkey (may require quorum approval)
 3. Decrypt the export bundle to get the raw private key
 4. Load and decrypt your stored recovery bundle
 
 ### Security Properties
 
-| Scenario | Impact |
-|----------|--------|
-| Customer infrastructure breach | Attacker gets encrypted blobs but cannot decrypt without Turnkey authentication |
-| Turnkey user breach | Attacker could access the encryption keypair but doesn't have the encrypted bundles |
-| Both breached | Both parties must be compromised simultaneously for full recovery |
+| Scenario                       | Impact                                                                              |
+| ------------------------------ | ----------------------------------------------------------------------------------- |
+| Customer infrastructure breach | Attacker gets encrypted blobs but cannot decrypt without Turnkey authentication     |
+| Turnkey user breach            | Attacker could access the encryption keypair but doesn't have the encrypted bundles |
+| Both breached                  | Both parties must be compromised simultaneously for full recovery                   |
 
 ### Architecture
 
@@ -253,15 +261,15 @@ This will:
 
 ## Comparison: Path 1 vs Path 2
 
-| Factor | Path 1: Direct Import | Path 2: Encryption Escrow |
-|--------|----------------------|---------------------------|
-| Recovery Speed | Immediate—keys operational in Turnkey | Requires decryption ceremony |
-| Fund Sweeping | Built-in SDK support | Requires wallet tooling after decryption |
-| Key Storage | Turnkey holds wallet keys in enclave | Turnkey holds only encryption keys |
-| Material Location | Turnkey secure enclave | Your storage (encrypted) |
-| Complexity | Lower | Higher |
-| Best For | Enterprise DR, treasury backup | User recovery, compliance separation |
-| Security Model | Single party (authorized Turnkey users) | 2-of-2 (Turnkey auth + bundle access) |
+| Factor            | Path 1: Direct Import                   | Path 2: Encryption Escrow                |
+| ----------------- | --------------------------------------- | ---------------------------------------- |
+| Recovery Speed    | Immediate—keys operational in Turnkey   | Requires decryption ceremony             |
+| Fund Sweeping     | Built-in SDK support                    | Requires wallet tooling after decryption |
+| Key Storage       | Turnkey holds wallet keys in enclave    | Turnkey holds only encryption keys       |
+| Material Location | Turnkey secure enclave                  | Your storage (encrypted)                 |
+| Complexity        | Lower                                   | Higher                                   |
+| Best For          | Enterprise DR, treasury backup          | User recovery, compliance separation     |
+| Security Model    | Single party (authorized Turnkey users) | 2-of-2 (Turnkey auth + bundle access)    |
 
 ---
 
@@ -316,15 +324,19 @@ disaster-recovery/
 ## Troubleshooting
 
 ### "Missing required environment variable"
+
 Ensure all required variables are set in `.env.local`. Copy from `.env.local.example` and fill in your values.
 
 ### "Quorum approval required"
+
 Your Turnkey organization has policies requiring multiple approvers. Coordinate with other key holders.
 
 ### "Not enough ETH to sweep"
+
 The wallet balance is too low to cover gas costs. Fund the wallet or use a different network.
 
 ### Import fails with encryption error
+
 Ensure you're using a valid BIP-39 mnemonic (12 or 24 words) or correctly formatted private key.
 
 ---

examples/disaster-recovery/src/interactive.ts

@@ -100,7 +100,7 @@ function getTurnkeyClient(): Turnkey {
   if (!apiPublicKey || !apiPrivateKey || !organizationId) {
     throw new Error(
       "Missing required environment variables: API_PUBLIC_KEY, API_PRIVATE_KEY, ORGANIZATION_ID\n" +
-        "Please copy .env.local.example to .env.local and fill in your credentials."
+        "Please copy .env.local.example to .env.local and fill in your credentials.",
     );
   }
 
@@ -214,9 +214,15 @@ async function mainMenu(): Promise<void> {
       message: "Press Enter to continue...",
     });
     console.clear();
-    console.log("╔════════════════════════════════════════════════════════════╗");
-    console.log("║         TURNKEY DISASTER RECOVERY TOOLKIT                  ║");
-    console.log("╚════════════════════════════════════════════════════════════╝");
+    console.log(
+      "╔════════════════════════════════════════════════════════════╗",
+    );
+    console.log(
+      "║         TURNKEY DISASTER RECOVERY TOOLKIT                  ║",
+    );
+    console.log(
+      "╚════════════════════════════════════════════════════════════╝",
+    );
     console.log();
   }
 }
@@ -399,7 +405,7 @@ async function generateMnemonicWallet(): Promise<{
     const row = words
       .slice(i, i + columns)
       .map(
-        (word, idx) => `${String(i + idx + 1).padStart(2)}. ${word.padEnd(10)}`
+        (word, idx) => `${String(i + idx + 1).padStart(2)}. ${word.padEnd(10)}`,
       )
       .join("  ");
     console.log(`  ${row}`);
@@ -463,15 +469,15 @@ async function importHDWallet(): Promise<void> {
 
   if (!organizationId || !userId) {
     throw new Error(
-      "Missing required environment variables: ORGANIZATION_ID, USER_ID"
+      "Missing required environment variables: ORGANIZATION_ID, USER_ID",
     );
   }
 
   const turnkeyClient = getTurnkeyClient();
 
   console.log("Step 1: Initialize import bundle from Turnkey");
   console.log(
-    "This creates a temporary public key in Turnkey's enclave for encrypting your mnemonic."
+    "This creates a temporary public key in Turnkey's enclave for encrypting your mnemonic.",
   );
   console.log();
 
@@ -484,7 +490,7 @@ async function importHDWallet(): Promise<void> {
 
   console.log("Step 2: Encrypt wallet material");
   console.log(
-    "SECURITY WARNING: In production, perform this step on an air-gapped machine!"
+    "SECURITY WARNING: In production, perform this step on an air-gapped machine!",
   );
   console.log();
 
@@ -629,7 +635,7 @@ async function importPrivateKey(): Promise<void> {
 
   if (!organizationId || !userId) {
     throw new Error(
-      "Missing required environment variables: ORGANIZATION_ID, USER_ID"
+      "Missing required environment variables: ORGANIZATION_ID, USER_ID",
     );
   }
 
@@ -662,7 +668,7 @@ async function importPrivateKey(): Promise<void> {
 
   console.log("Step 2: Encrypt private key material");
   console.log(
-    "SECURITY WARNING: In production, perform this step on an air-gapped machine!"
+    "SECURITY WARNING: In production, perform this step on an air-gapped machine!",
   );
   console.log();
 
@@ -812,13 +818,13 @@ async function sweepFunds(): Promise<void> {
 
   if (!signWith) {
     throw new Error(
-      "Missing SIGN_WITH - set this to the imported wallet/key address in .env.local"
+      "Missing SIGN_WITH - set this to the imported wallet/key address in .env.local",
     );
   }
 
   if (!safeTreasury) {
     throw new Error(
-      "Missing SAFE_TREASURY_ADDRESS - set this to your safe destination address in .env.local"
+      "Missing SAFE_TREASURY_ADDRESS - set this to your safe destination address in .env.local",
     );
   }
 
@@ -933,7 +939,9 @@ async function sweepFunds(): Promise<void> {
   console.log();
 
   console.log("Waiting for transaction confirmation...");
-  const receipt = await publicClient.waitForTransactionReceipt({ hash: txHash });
+  const receipt = await publicClient.waitForTransactionReceipt({
+    hash: txHash,
+  });
 
   if (receipt.status === "success") {
     console.log();
@@ -976,7 +984,9 @@ async function escrowSetup(): Promise<void> {
   console.log("2. Encrypt your recovery material with Turnkey's public key");
   console.log("3. Save the encrypted bundle locally (you store this securely)");
   console.log();
-  console.log("Note: The encrypted bundle should be stored in YOUR infrastructure,");
+  console.log(
+    "Note: The encrypted bundle should be stored in YOUR infrastructure,",
+  );
   console.log("not on Turnkey. This creates a 2-of-2 security model.");
   console.log();
 
@@ -1069,7 +1079,11 @@ async function escrowSetup(): Promise<void> {
     let addMore = true;
     while (addMore) {
       const { service, apiKey } = await prompts([
-        { type: "text", name: "service", message: "Service name (e.g., AWS, Alchemy):" },
+        {
+          type: "text",
+          name: "service",
+          message: "Service name (e.g., AWS, Alchemy):",
+        },
         { type: "password", name: "apiKey", message: "API Key/Secret:" },
       ]);
 
@@ -1141,8 +1155,8 @@ async function escrowSetup(): Promise<void> {
         createdAt: new Date().toISOString(),
       },
       null,
-      2
-    )
+      2,
+    ),
   );
 
   console.log();
@@ -1162,7 +1176,7 @@ async function escrowSetup(): Promise<void> {
 }
 
 async function createNewEncryptionKey(
-  turnkeyClient: Turnkey
+  turnkeyClient: Turnkey,
 ): Promise<{ privateKeyId: string; publicKey: string }> {
   console.log();
   console.log("Step 1: Create encryption keypair in Turnkey");
@@ -1258,7 +1272,7 @@ async function escrowRecovery(): Promise<void> {
 
   const bundleContents = fs.readFileSync(
     path.resolve(process.cwd(), bundlePath),
-    "utf-8"
+    "utf-8",
   );
   const storedBundle: StoredBundle = JSON.parse(bundleContents);
 
@@ -1271,7 +1285,7 @@ async function escrowRecovery(): Promise<void> {
 
   if (!keyIdToUse) {
     throw new Error(
-      "No encryption key ID found in bundle or ENCRYPTION_KEY_ID environment variable"
+      "No encryption key ID found in bundle or ENCRYPTION_KEY_ID environment variable",
     );
   }
 
@@ -1323,7 +1337,7 @@ async function escrowRecovery(): Promise<void> {
 
     const decryptedRecoveryJson = await decryptWithPrivateKey(
       encryptionPrivateKey,
-      storedBundle.encryptedData
+      storedBundle.encryptedData,
     );
 
     const recoveryBundle: RecoveryBundle = JSON.parse(decryptedRecoveryJson);
@@ -1334,7 +1348,9 @@ async function escrowRecovery(): Promise<void> {
     console.log("═".repeat(60));
     console.log();
 
-    console.log("WARNING: Sensitive data displayed below. Clear your terminal after use.");
+    console.log(
+      "WARNING: Sensitive data displayed below. Clear your terminal after use.",
+    );
     console.log();
 
     const { showData } = await prompts({
@@ -1352,8 +1368,14 @@ async function escrowRecovery(): Promise<void> {
       console.log("Created at: ", recoveryBundle.createdAt);
 
       if (recoveryBundle.metadata) {
-        console.log("Description:", recoveryBundle.metadata.description || "N/A");
-        console.log("Organization:", recoveryBundle.metadata.organization || "N/A");
+        console.log(
+          "Description:",
+          recoveryBundle.metadata.description || "N/A",
+        );
+        console.log(
+          "Organization:",
+          recoveryBundle.metadata.organization || "N/A",
+        );
       }
 
       console.log();
@@ -1376,7 +1398,10 @@ async function escrowRecovery(): Promise<void> {
           console.log(`  ${cred.service}: ${cred.apiKey}`);
         }
         console.log();
-      } else if (recoveryBundle.type === "custom" && recoveryBundle.data.custom) {
+      } else if (
+        recoveryBundle.type === "custom" &&
+        recoveryBundle.data.custom
+      ) {
         console.log();
         console.log("CUSTOM DATA:");
         console.log(recoveryBundle.data.custom);
@@ -1420,8 +1445,12 @@ async function escrowRecovery(): Promise<void> {
       console.log("QUORUM APPROVAL REQUIRED");
       console.log("═".repeat(60));
       console.log();
-      console.log("This export requires additional approvals based on your policy.");
-      console.log("Please coordinate with other key holders to complete the export.");
+      console.log(
+        "This export requires additional approvals based on your policy.",
+      );
+      console.log(
+        "Please coordinate with other key holders to complete the export.",
+      );
       console.log();
     } else {
       throw error;