Skip to main content

IframeStamper

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 Recovery / 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​

configTIframeStamperConfigrequired

An object containing configuration settings for the iframe stamper.

.iframeUrlstringrequired

The URL of the iframe to be used.

.iframeElementIdstringrequired

The ID to assign to the iframe element.

.iframeContainerHTMLElement | null | undefinedrequired

The container element in which the iframe will be inserted.

Types​

TIframeStamperConfig​
type TIframeStamperConfig = {
  iframeUrl: string;
  iframeElementId: string;
  iframeContainer: HTMLElement | null | undefined;
};

Example​

For full example check out the email-recovery example in our SDK repo. You should also read up on Email Recovery and 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 recovery and 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​

bundlestringrequired

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​

bundlestringrequired

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 keyExportBundle = "<your-encrypted-key-export-bundle>";

// Injects a new wallet in the iframe
const injected = await iframeStamper.injectKeyExportBundle(keyExportBundle);

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​

bundlestringrequired

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();