@turnkey/iframe-stamper/dist/index.d.ts

Iframe-based stamper for @turnkey/http

/// <reference lib="dom" />
export declare enum IframeEventType {
    PublicKeyReady = "PUBLIC_KEY_READY",
    InjectCredentialBundle = "INJECT_CREDENTIAL_BUNDLE",
    InjectKeyExportBundle = "INJECT_KEY_EXPORT_BUNDLE",
    InjectWalletExportBundle = "INJECT_WALLET_EXPORT_BUNDLE",
    InjectImportBundle = "INJECT_IMPORT_BUNDLE",
    ExtractWalletEncryptedBundle = "EXTRACT_WALLET_ENCRYPTED_BUNDLE",
    ExtractKeyEncryptedBundle = "EXTRACT_KEY_ENCRYPTED_BUNDLE",
    ApplySettings = "APPLY_SETTINGS",
    BundleInjected = "BUNDLE_INJECTED",
    EncryptedBundleExtracted = "ENCRYPTED_BUNDLE_EXTRACTED",
    SettingsApplied = "SETTINGS_APPLIED",
    TransactionSigned = "TRANSACTION_SIGNED",
    MessageSigned = "MESSAGE_SIGNED",
    EmbeddedPrivateKeyCleared = "EMBEDDED_PRIVATE_KEY_CLEARED",
    StampRequest = "STAMP_REQUEST",
    Stamp = "STAMP",
    TurnkeyInitMessageChannel = "TURNKEY_INIT_MESSAGE_CHANNEL",
    GetEmbeddedPublicKey = "GET_EMBEDDED_PUBLIC_KEY",
    ClearEmbeddedKey = "RESET_EMBEDDED_KEY",
    InitEmbeddedKey = "INIT_EMBEDDED_KEY",
    SignTransaction = "SIGN_TRANSACTION",
    SignMessage = "SIGN_MESSAGE",
    clearEmbeddedPrivateKey = "CLEAR_EMBEDDED_PRIVATE_KEY",
    SetEmbeddedKeyOverride = "SET_EMBEDDED_KEY_OVERRIDE",
    ResetToDefaultEmbeddedKey = "RESET_TO_DEFAULT_EMBEDDED_KEY",
    Error = "ERROR"
}
export declare enum KeyFormat {
    Hexadecimal = "HEXADECIMAL",
    Solana = "SOLANA",
    BitcoinMainNetWIF = "BITCOIN_MAINNET_WIF",
    BitcoinTestNetWIF = "BITCOIN_TESTNET_WIF",
    SuiBech32 = "SUI_BECH32"
}
type TStamp = {
    stampHeaderName: string;
    stampHeaderValue: string;
};
export type TIframeStamperConfig = {
    iframeUrl: string;
    iframeElementId: string;
    iframeContainer: HTMLElement | null | undefined;
    clearClipboardOnPaste?: boolean | undefined;
};
export type TIframeStyles = {
    padding?: string;
    margin?: string;
    borderWidth?: string;
    borderStyle?: string;
    borderColor?: string;
    borderRadius?: string;
    fontSize?: string;
    fontWeight?: string;
    fontFamily?: string;
    color?: string;
    labelColor?: string;
    backgroundColor?: string;
    width?: string;
    height?: string;
    maxWidth?: string;
    maxHeight?: string;
    lineHeight?: string;
    boxShadow?: string;
    textAlign?: string;
    overflowWrap?: string;
    wordWrap?: string;
    resize?: string;
};
export type TIframeSettings = {
    styles?: TIframeStyles;
    passphraseStyles?: TIframeStyles;
    enablePassphrase?: boolean;
};
export declare enum MessageType {
    Ethereum = "ETHEREUM",
    Solana = "SOLANA"
}
export type TSignableMessage = {
    message: string;
    type: MessageType;
};
export declare enum TransactionType {
    Ethereum = "ETHEREUM",
    Solana = "SOLANA"
}
export type TSignableTransaction = {
    transaction: string;
    type: TransactionType;
};
/**
 * Stamper to use with `@turnkey/http`'s `TurnkeyClient`
 * Creating a stamper inserts an iframe in the current page.
 */
export declare class IframeStamper {
    container: HTMLElement;
    iframe: HTMLIFrameElement;
    iframeOrigin: string;
    iframePublicKey: string | null;
    messageChannel: MessageChannel;
    private pendingRequests;
    /**
     * Creates a new iframe stamper. This function _does not_ insert the iframe in the DOM.
     * Call `.init()` to insert the iframe element in the DOM.
     * @param {TIframeStamperConfig} config - Configuration object for the iframe stamper
     * @throws {Error} When running in non-browser environment
     * @throws {Error} When MessageChannel is not supported
     * @throws {Error} When iframeContainer is not provided
     * @throws {Error} When iframe element with the same ID already exists
     */
    constructor(config: TIframeStamperConfig);
    /**
     * Handles incoming messages from the iframe via MessageChannel
     * @param {MessageEvent} event - Message event from the iframe
     * @returns {void}
     */
    onMessageHandler(event: MessageEvent): void;
    /**
     * Inserts the iframe on the page and returns a promise resolving to the iframe's public key
     * @param {number} [dangerouslyOverrideIframeKeyTtl] - Optional TTL override for the iframe's embedded key (default 48 hours). Only use this if you are intentional about the security implications.
     * @returns {Promise<string>} The iframe's public key
     * @throws {Error} When contentWindow or contentWindow.postMessage does not exist
     */
    init(dangerouslyOverrideIframeKeyTtl?: number | undefined): Promise<string>;
    /**
     * Removes the iframe from the DOM and cleans up all resources
     * @returns {void}
     */
    clear(): void;
    /**
     * Returns the public key, or `null` if the underlying iframe isn't properly initialized.
     * @returns {string | null} The iframe's public key or null
     */
    publicKey(): string | null;
    /**
     * Returns the public key, or `null` if the underlying iframe isn't properly initialized.
     * This differs from the above in that it reaches out to the live iframe to see if an embedded key exists.
     * @returns {Promise<string | null>} The embedded public key or null
     */
    getEmbeddedPublicKey(): Promise<string | null>;
    /**
     * Clears the embedded key within an iframe.
     * @returns {Promise<null>} Returns null on success
     */
    clearEmbeddedKey(): Promise<null>;
    /**
     * Creates a new embedded key within an iframe. If an embedded key already exists, this will return it.
     * This is primarily to be used in conjunction with `clearEmbeddedKey()`: after an embedded key is cleared,
     * this can be used to create a new one.
     * @returns {Promise<string | null>} The newly created embedded public key
     */
    initEmbeddedKey(): Promise<string | null>;
    /**
     * Generic function to abstract away request creation
     * @template T
     * @param {IframeEventType} type - The type of iframe event to send
     * @param {any} [payload={}] - Optional payload data to send with the request
     * @returns {Promise<T>} Promise resolving to the expected response shape
     */
    private createRequest;
    /**
     * Function to inject a new credential into the iframe
     * The bundle should be encrypted to the iframe's initial public key
     * Encryption should be performed with HPKE (RFC 9180).
     * This is used during recovery and auth flows.
     * @param {string} bundle - The encrypted credential bundle to inject
     * @returns {Promise<boolean>} Returns true on successful injection
     */
    injectCredentialBundle(bundle: string): Promise<boolean>;
    /**
     * Function to inject an export bundle into the iframe
     * The bundle should be encrypted to the iframe's initial public key
     * Encryption should be performed with HPKE (RFC 9180).
     * The key format to encode the private key in after it's exported and decrypted: HEXADECIMAL or SOLANA. Defaults to HEXADECIMAL.
     * This is used during the private key export flow.
     * @param {string} bundle - The encrypted export bundle to inject
     * @param {string} organizationId - The organization ID
     * @param {KeyFormat} keyFormat - [Optional] The key format (HEXADECIMAL or SOLANA). Defaults to HEXADECIMAL
     * @param {string} address - [Optional] Address corresponding to the key bundle (case sensitive)
     * @returns {Promise<boolean>} Returns true on successful injection
     */
    injectKeyExportBundle(bundle: string, organizationId: string, keyFormat?: KeyFormat, address?: string): Promise<boolean>;
    /**
     * Function to inject an export bundle into the iframe
     * The bundle should be encrypted to the iframe's initial public key
     * Encryption should be performed with HPKE (RFC 9180).
     * This is used during the wallet export flow.
     * @param {string} bundle - The encrypted wallet export bundle to inject
     * @param {string} organizationId - The organization ID
     * @returns {Promise<boolean>} Returns true on successful injection
     */
    injectWalletExportBundle(bundle: string, organizationId: string): Promise<boolean>;
    /**
     * Function to inject an import bundle into the iframe
     * This is used to initiate either the wallet import flow or the private key import flow.
     * @param {string} bundle - The import bundle to inject
     * @param {string} organizationId - The organization ID
     * @param {string} userId - The user ID
     * @returns {Promise<boolean>} Returns true on successful injection
     */
    injectImportBundle(bundle: string, organizationId: string, userId: string): Promise<boolean>;
    /**
     * Function to extract an encrypted bundle from the iframe
     * The bundle should be encrypted to Turnkey's Signer enclave's initial public key
     * Encryption should be performed with HPKE (RFC 9180).
     * This is used during the wallet import flow.
     * @returns {Promise<string>} The encrypted wallet bundle
     */
    extractWalletEncryptedBundle(): Promise<string>;
    /**
     * Function to extract an encrypted bundle from the iframe
     * The bundle should be encrypted to Turnkey's Signer enclave's initial public key
     * Encryption should be performed with HPKE (RFC 9180).
     * The key format to encode the private key in before it's encrypted and imported: HEXADECIMAL or SOLANA. Defaults to HEXADECIMAL.
     * This is used during the private key import flow.
     * @param {KeyFormat} [keyFormat] - The key format (HEXADECIMAL or SOLANA). Defaults to HEXADECIMAL
     * @returns {Promise<string>} The encrypted key bundle
     */
    extractKeyEncryptedBundle(keyFormat?: KeyFormat): Promise<string>;
    /**
     * Function to apply settings on allowed parameters in the iframe
     * This is used to style the HTML element used for plaintext in wallet and private key import.
     * @param {TIframeSettings} settings - The settings object containing styles to apply
     * @returns {Promise<boolean>} Returns true on successful application
     */
    applySettings(settings: TIframeSettings): Promise<boolean>;
    /**
     * Function to sign a payload with the underlying iframe
     * @param {string} payload - The payload to sign
     * @returns {Promise<TStamp>} Object containing stamp header name and value
     * @throws {Error} When iframe public key is null (init() not called/awaited)
     */
    stamp(payload: string): Promise<TStamp>;
    /**
     * Function to sign a message using an embedded private key in-memory within an iframe
     * Returns the signed message string
     * @param {TSignableMessage} message - The message to sign with type (Ethereum or Solana)
     * @param {string} address - [Optional] Address to sign with
     * @returns {Promise<string>} The signed message string
     */
    signMessage(message: TSignableMessage, address?: string): Promise<string>;
    /**
     * Function to sign a transaction using an embedded private key in-memory within an iframe
     * Returns the signed, serialized transaction payload
     * @param {TSignableTransaction} transaction - The transaction to sign with type (Ethereum or Solana)
     * @param {string} address - [Optional] Address to sign with
     * @returns {Promise<string>} The signed, serialized transaction payload
     */
    signTransaction(transaction: TSignableTransaction, address?: string): Promise<string>;
    /**
     * Function to clear the iframe's in-memory embedded private key. For now, we assume that there will be only one private key at most.
     * @returns {Promise<boolean>} Returns true on successful clearing
     */
    clearEmbeddedPrivateKey(): Promise<boolean>;
    setEmbeddedKeyOverride(organizationId: string, bundle: string): Promise<boolean>;
    resetToDefaultEmbeddedKey(): Promise<boolean>;
}
export {};
//# sourceMappingURL=index.d.ts.map