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:
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
The URL of the iframe to be used.
The ID to assign to the iframe element.
The container element in which the iframe will be inserted.
Whether to clear the clipboard on paste events.
Types
TIframeStamperConfig
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
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
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
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
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
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
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
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
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
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
0xprefix). 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
addressargument toinjectKeyExportBundle).
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 asBITCOIN_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.
injectKeyExportBundle (export) and
extractKeyEncryptedBundle (import) methods of the IframeStamper.