@turnkey/iframe-stamper

This package contains functions to stamp a Turnkey request through credentials contained in an iframe. It is meant to be used with @turnkey/http to build flows. To stamp the request, use the Recovery and Auth flows to request and inject a credential bundle.

Usage:

Recovery and Auth

1import { IframeStamper } from "@turnkey/iframe-stamper";
2import { TurnkeyClient } from "@turnkey/http";
3
4const TurnkeyIframeContainerId = "turnkey-iframe-container";
5const TurnkeyIframeElementId = "turnkey-iframe";
6
7const iframeStamper = new IframeStamper({
8  iframeUrl: process.env.AUTH_IFRAME_URL!,
9  iframeContainer: document.getElementById(TurnkeyIframeContainerId),
10  iframeElementId: TurnkeyIframeElementId,
11});
12
13// This inserts the iframe in the DOM and returns the public key
14const publicKey = await iframeStamper.init();
15
16// Injects a new credential in the iframe
17const injected = await iframeStamper.injectCredentialBundle(credentialBundle);
18
19// New HTTP client able to sign with the credentials inside of the iframe
20const httpClient = new TurnkeyClient(
21  { baseUrl: "https://api.turnkey.com" },
22  iframeStamper,
23);

Key or Wallet Export

1import { IframeStamper } from "@turnkey/iframe-stamper";
2import { TurnkeyClient } from "@turnkey/http";
3
4const TurnkeyIframeContainerId = "turnkey-iframe-container";
5const TurnkeyIframeElementId = "turnkey-iframe";
6
7const iframeStamper = new IframeStamper({
8  iframeUrl: process.env.EXPORT_IFRAME_URL!,
9  iframeContainer: document.getElementById(TurnkeyIframeContainerId),
10  iframeElementId: TurnkeyIframeElementId,
11});
12
13// This inserts the iframe in the DOM and returns the public key
14const publicKey = await iframeStamper.init();
15
16// Injects a bundle containing the encrypted wallet seedphrase into the iframe
17// `exportBundle` is the response from requesting ACTIVITY_TYPE_EXPORT_WALLET
18const injected = await iframeStamper.injectWalletExportBundle(exportBundle);
19
20// If the bundle is successfully injected, the iframe is now displaying the
21// wallet seedphrase to the user
22if (injected !== true) {
23  throw new Error("unexpected error while injecting export bundle");
24}
25
26// Display the iframe to the user with their seedphrase.
27setIframeDisplay("block");

Key or Wallet Import

1import { IframeStamper } from "@turnkey/iframe-stamper";
2import { TurnkeyClient } from "@turnkey/http";
3
4const TurnkeyIframeContainerId = "turnkey-iframe-container";
5const TurnkeyIframeElementId = "turnkey-iframe";
6
7const iframeStamper = new IframeStamper({
8  iframeUrl: process.env.IMPORT_IFRAME_URL!,
9  iframeContainer: document.getElementById(TurnkeyIframeContainerId),
10  iframeElementId: TurnkeyIframeElementId,
11});
12
13// This inserts the iframe in the DOM
14await iframeStamper.init();
15
16// Injects a bundle containing the secure enclave's public key into the iframe's local storage
17// `importBundle` is the response from requesting ACTIVITY_TYPE_INIT_IMPORT_WALLET
18const injected = await iframeStamper.injectImportBundle(importBundle);
19
20if (injected !== true) {
21  throw new Error("unexpected error while injecting import bundle");
22}
23
24// Display the text input that the user can enter their seedphrase into
25setIframeDisplay("block");
26
27// Once the user has entered their seedphrase, trigger this call to the iframe that
28// 1) encrypts their seedphrase using the secure enclave's public key from the previous step
29// 2) sends this ciphertext and a public key generated by the client to your page
30const encryptedBundle = await iframeStamper.extractWalletEncryptedBundle();
31
32// Now you can pass this encryptedBundle as a request to ACTIVITY_TYPE_IMPORT_WALLET.