Skip to main content

Introduction

The @turnkey/iframe-stamper package, while sharing a similar purpose with the @turnkey/api-key-stamper, caters specifically to the unique context of iframes. This package is designed for stamping requests within an iframe, using credentials for Turnkey’s API, but operates distinctly from the API key stamper. Unlike the API key stamper, which has direct access to the API private key to compute signatures or stamps directly, the iframe stamper interacts with credentials in a more indirect manner. It leverages the postMessage communication mechanism to send and receive messages within the iframe, ensuring the credential does not leave its secure environment. This approach is particularly crucial in sensitive flows such as Email Auth, and Key or Wallet Export, where heightened security is required. The @turnkey/iframe-stamper works in tandem with @turnkey/http, facilitating secure and efficient communication in these specific use cases. By bridging the gap between the iframe’s isolated environment and Turnkey’s API, the iframe stamper plays a pivotal role in maintaining the integrity and security of the credential while ensuring seamless operation within the iframe context.

Installing

To start using the @turnkey/iframe-stamper client, install it as follows:
npm i @turnkey/iframe-stamper

Initializing

The IframeStamper class, part of the @turnkey/iframe-stamper package, is designed for stamping Turnkey requests through credentials in an iframe. It’s used with @turnkey/http for constructing various flows. The class can manage iframe interactions for credential insertion, wallet exports, and request stamping. Here’s how you can initialize an IframeStamper:

constructor(config: TIframeStamperConfig): IframeStamper

Parameters

iframeUrl
string
required
The URL of the iframe to be used.
iframeElementId
string
required
The ID to assign to the iframe element.
iframeContainer
HTMLElement | null | undefined
required
The container element in which the iframe will be inserted.
clearClipboardOnPaste
boolean
Whether to clear the clipboard on paste events.

Types

TIframeStamperConfig
type TIframeStamperConfig = {
  iframeUrl: string;
  iframeElementId: string;
  iframeContainer: HTMLElement | null | undefined;
  clearClipboardOnPaste?: boolean;
};

Example

For full example check out the email-auth example in our SDK repo. You should also read up Email Auth for more information on the technical details of how it works.

Methods

init: () => Promise<string>

Initializes the iframe stamper by inserting the iframe into the DOM and establishing communication with it. This method returns a promise that resolves to the iframe’s public key, which is used for subsequent operations like credential injection or request stamping.

Example

import { IframeStamper } from "@turnkey/iframe-stamper";
import { TurnkeyClient } from "@turnkey/http";

const TurnkeyIframeContainerId = "turnkey-iframe-container";
const TurnkeyIframeElementId = "turnkey-iframe";

const iframeStamper = new IframeStamper({
  iframeUrl: process.env.IFRAME_URL!,
  iframeContainer: document.getElementById(TurnkeyIframeContainerId),
  iframeElementId: TurnkeyIframeElementId,
});

// This inserts the iframe in the DOM and returns the public key
const publicKey = await iframeStamper.init();

injectCredentialBundle: (bundle: string) => Promise<boolean>

Injects a new credential bundle into the iframe, a process used in email authentication flows. The method requires an encrypted credential bundle, which should be encrypted to the iframe’s initial public key using HPKE (RFC 9180). Upon successful execution, it returns a Promise<boolean> that resolves to true if the bundle was successfully injected into the iframe, or false otherwise.

Parameters

bundle
string
required
The encrypted credential bundle that needs to be injected into the iframe. This bundle should be encrypted with the iframe’s initial public key using HPKE (RFC 9180).

Example

// .. Add imports and init iframeStamper

// Pasted into the iFrame by the user
const credentialBundle = "<your-encrypted-credentials-bundle>";

// Injects a new credential in the iframe
const injected = await iframeStamper.injectCredentialBundle(credentialBundle);

injectKeyExportBundle: (bundle: string) => Promise<boolean>

Injects an export bundle into the iframe. This method is used during key export flows. The bundle should be encrypted to the iframe’s initial public key using HPKE (RFC 9180). This method returns a Promise<boolean> which resolves to true if the bundle was successfully injected into the iframe, or false otherwise.

Parameters

bundle
string
required
The encrypted export bundle that needs to be injected into the iframe. This bundle should be encrypted with the iframe’s initial public key using HPKE (RFC 9180).

Example

// .. Add imports and init the IframeStamper

// Pasted into the iFrame by the user
const walletExportBundle = "<your-encrypted-wallet-export-bundle>";

const injected =
  await iframeStamper.injectWalletExportBundle(walletExportBundle);

injectWalletExportBundle: (bundle: string) => Promise<boolean>

Injects a wallet export bundle into the iframe. This method is typically used during wallet export flows. The bundle should be encrypted to the iframe’s initial public key using HPKE (RFC 9180). It returns a Promise<boolean> which resolves to true if the bundle is successfully injected into the iframe, or false otherwise.

Parameters

bundle
string
required
The encrypted wallet export bundle to be injected into the iframe. This bundle must be encrypted using the iframe’s initial public key according to HPKE (RFC 9180) standards.

Example

// .. Add imports and init the IframeStamper

// Pasted into the iFrame by the user
const walletExportBundle = "<your-encrypted-wallet-export-bundle>";

const injected =
  await iframeStamper.injectWalletExportBundle(walletExportBundle);

publicKey: () => string | null

Returns the public key of the iframe, or null if the underlying iframe isn’t properly initialized. This method is useful for retrieving the public key which is necessary for various operations like credential injection or request stamping.

Example

// .. Add imports and init the IframeStamper

const iframePublicKey = iframeStamper.publicKey();

clear: () => void

Removes the iframe from the DOM. This method is useful for cleaning up the iframe when it is no longer needed. It ensures that the iframe is properly disposed of, preventing potential memory leaks or other unintended side effects.

Example

// .. Add imports and init the IframeStamper

iframeStamper.clear();

Exporting & Importing Private Key Formats

There are five private key formats to choose from. All five are supported in both the export and import flows.

HEXADECIMAL

  • A 64-character hex string representation of the private key (with or without a 0x prefix). This is the format used by MetaMask, MyEtherWallet, Ledger, and Trezor for Ethereum and Tron keys.
  • Default if no format is specified.

SOLANA

  • A base58-encoded string concatenating the private key and the public key. This is the format used by Phantom and Solflare for Solana keys.
  • Exporting in this format requires the associated public key (passed as the address argument to injectKeyExportBundle).

BITCOIN_MAINNET_WIF

  • Bitcoin mainnet Wallet Import Format (base58check, version byte 0x80). Used by wallets like Electrum and Bitcoin Core.
  • Only compressed WIF keys are supported; uncompressed WIF keys are rejected.

BITCOIN_TESTNET_WIF

  • Bitcoin testnet Wallet Import Format (base58check, version byte 0xEF). Same compatibility and constraints as BITCOIN_MAINNET_WIF.

SUI_BECH32

  • A Bech32-encoded string with the human-readable part suiprivkey, used by Sui wallets.
  • Only the Ed25519 scheme (scheme flag 0) is supported.
These can be used when exporting or importing private keys to ensure compatibility with different blockchain ecosystems and tools by passing the desired format to the injectKeyExportBundle (export) and extractKeyEncryptedBundle (import) methods of the IframeStamper.