added encrypted bundle caching + escrow key injection by ethankonk · Pull Request #115 · tkhq/frames

ethankonk · 2026-02-12T00:41:04Z

Added the ability to store encrypted wallet account export bundles in the export-and-sign iframe's local storage, and decrypt + sign transactions & messages using an injected "escrow" private key export bundle.

General Flow:

Dedicated escrow private key is created with Turnkey

await httpClient?.createPrivateKeys({
  privateKeys: [
     {
      privateKeyName: "<PK_NAME>",
      curve: "CURVE_P256", // MUST BE A P256 KEY
      privateKeyTags: [], // optional
      addressFormats: [] // not needed
     }
  ]
})

Push wallet account export bundles to the iframe's persistent storage

The targetPublicKey you encrypt the export bundle to needs to be the public key of the escrow key we created earlier!!

const { exportBundle } =
  (await httpClient?.exportWalletAccount({
    address: account.address,
    targetPublicKey: privateKey.publicKey, // escrow PK public key
  })) || {};

Now we push the export bundle:

await iframeClient.storeEncryptedBundle(
    organizationId,
    exportBundle,
    KeyFormat.Solana, // or KeyFormat.Hexadecimal
    account.address // the address of the wallet account that we exported
);

Inject the escrow key!

Nab the iframe's embedded public key to encrypt the escrow bundle too:

const targetPublicKey = await iframeClient.getEmbeddedPublicKey();
if (!targetPublicKey) {
    throw new Error("Failed to retrieve target public key from iframe.");
}

const { exportBundle } =
    (await httpClient?.exportPrivateKey({
    privateKeyId: escrowPrivateKeyId,
    targetPublicKey,
    })) || {};

Inject the export bundle

iframeClient.injectDecryptionKeyBundle(organizationId, exportBundle);

Now all our encrypted bundles are safely stored encrypted in local storage but decrypted in memory! The escrow private key is never kept in persistent storage and must be re-injected whenever the iframe gets destroyed.

Additional helpers events include:

BURN_SESSION

Bulk clears in-memory decrypted bundles (injected escrow key + export bundles), does not wipe local storage

GET_STORED_WALLET_ADDRESSES

Lists all stored wallet addresses in local storage

CLEAR_STORED_BUNDLES

Clears specified addresses if the address parameter is passed, or all addresses in both local storage & in-memory

Sorta open questions:

Do we want to set an expiry on the keys stored in local storage? Should we enforce regular "clean outs"?
Do we want to be more technical with how we clear in-memory keys? Afaik even though we "clear" them normally, there are still ways to access that data due to how JavaScript's garbage collection works. Not quite sure how this would look like or if this is even something we need to consider

Quick Demo 🎉

https://www.loom.com/share/5b3c9d5427414629b42e81c9278e5df0

PS: the video shows keys that are "ready to sign" from a previous session on a different account. But you wouldn't actually be able to sign with those since that new sub-org I logged into wouldn't have the right decryption escrow key to decrypt the stored bundles with
The above has been fixed!

https://www.loom.com/share/3dca52882847484fa8df2738329fc997

This demo is irrelevant now, will update

Project doc: https://docs.google.com/document/d/16YXWrR75RnRmkM_gURLAzwrEG7FUzK_pF6Z-rQ5g0j8/edit?tab=t.0

Copilot

Pull request overview

Adds encrypted export-bundle caching in the export-and-sign iframe’s localStorage, plus an in-memory “escrow” decryption key injection flow to decrypt bundles and enable signing without persisting the escrow key.

Changes:

Added localStorage helpers for storing/removing encrypted bundles keyed by wallet address.
Added new iframe event handlers for storing encrypted bundles, injecting an escrow decryption bundle, listing stored addresses, clearing stored bundles, and burning the session.
Added comprehensive Jest coverage for the escrow storage/decryption/signing lifecycle and related helper APIs.

Reviewed changes

Copilot reviewed 4 out of 11 changed files in this pull request and generated 6 comments.

File	Description
shared/turnkey-core.js	Adds shared `localStorage` helpers to persist encrypted bundles.
export-and-sign/src/turnkey-core.js	Re-exports the new shared encrypted-bundle helper APIs through the iframe TKHQ facade.
export-and-sign/src/event-handlers.js	Implements new message handlers for encrypted bundle storage + escrow key injection + session/bundle management.
export-and-sign/index.test.js	Adds test coverage for new helper APIs and events (store/decrypt/sign/burn/clear/list).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

shared/turnkey-core.js

Copilot · 2026-02-12T00:56:10Z

shared/turnkey-core.js

+function setEncryptedBundle(address, bundleData) {
+  const bundles = getEncryptedBundles() || {};
+  bundles[address] = bundleData;
+  window.localStorage.setItem(
+    TURNKEY_ENCRYPTED_BUNDLES,
+    JSON.stringify(bundles)
+  );
+}


Using an untrusted address as an object key allows prototype pollution (e.g., "proto", "constructor", "prototype"), and bundles[address] = ... can mutate the object prototype. Since address ultimately comes from postMessage inputs, this is a concrete risk. Use a Map-like serialization (array of [address, bundleData] entries), or store into an object created via Object.create(null) and explicitly reject dangerous keys before setting/removing. Apply the same protection in removal paths.