> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turnkey.com/llms.txt
> Use this file to discover all available pages before exploring further.

# IframeStamper

## Introduction

The [`@turnkey/iframe-stamper`](https://www.npmjs.com/package/@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](/authentication/email), and [Key or Wallet Export](/wallets/export-wallets), 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:

<CodeGroup>
  ```bash npm theme={"system"}
  npm i @turnkey/iframe-stamper
  ```

  ```bash pnpm theme={"system"}
  pnpm i @turnkey/iframe-stamper
  ```

  ```bash yarn theme={"system"}
  yarn add @turnkey/iframe-stamper
  ```
</CodeGroup>

## 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

<ParamField body="config" type="TIframeStamperConfig" required>
  An object containing configuration settings for the iframe stamper.
</ParamField>

<ParamField body="iframeUrl" type="string" required>
  The URL of the iframe to be used.
</ParamField>

<ParamField body="iframeElementId" type="string" required>
  The ID to assign to the iframe element.
</ParamField>

<ParamField body="iframeContainer" type="HTMLElement | null | undefined" required>
  The container element in which the iframe will be inserted.
</ParamField>

#### Types

##### `TIframeStamperConfig`

```js theme={"system"}
type TIframeStamperConfig = {
  iframeUrl: string;
  iframeElementId: string;
  iframeContainer: HTMLElement | null | undefined;
};
```

#### Example

For full example check out the [email-auth](https://github.com/tkhq/sdk/tree/main/examples/email-auth) example in our SDK repo. You should also read up [Email Auth](/authentication/email) 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

```js theme={"system"}
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](https://www.rfc-editor.org/rfc/rfc9180.html)). 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

<ParamField body="bundle" type="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](https://www.rfc-editor.org/rfc/rfc9180.html)).
</ParamField>

#### 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](https://www.rfc-editor.org/rfc/rfc9180.html)). This method returns a `Promise<boolean>` which resolves to `true` if the bundle was successfully injected into the iframe, or `false` otherwise.

#### Parameters

<ParamField body="bundle" type="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](https://www.rfc-editor.org/rfc/rfc9180.html)).
</ParamField>

#### Example

```js theme={"system"}
// .. 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

<ParamField body="bundle" type="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.
</ParamField>

#### Example

```js theme={"system"}
// .. 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

```js theme={"system"}
// .. 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

```js theme={"system"}
// .. Add imports and init the IframeStamper

iframeStamper.clear();
```