Skip to content

Commit

Permalink
Add stamper docs
Browse files Browse the repository at this point in the history
  • Loading branch information
taylorjdawson committed Jan 16, 2024
1 parent d80e574 commit f72a41e
Show file tree
Hide file tree
Showing 5 changed files with 357 additions and 31 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ Let's review these steps in detail:
5. User copies and pastes their recovery code into your app. Remember: this code is an encrypted credential which can only be decrypted within the iframe.
6. Your app injects the recovery code into the iframe for decryption:
```js
await iframeStamper.injectRecoveryBundle(code);
await iframeStamper.injectCredentialBundle(code);
```
7. Your app prompts the user to create a new passkey (using our SDK functionality):
```js
Expand Down
9 changes: 2 additions & 7 deletions docs/sdk/api-key-stamper.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -52,18 +52,13 @@ To get started install the [`@turnkey/api-key-stamper`](https://www.npmjs.com/pa


## Initializing
The **`ApiKeyStamper`** class is a helper, which abstracts away the required stamp headers when making request to Turnkey's API.
You can initialize a new **`ApiKeyStamper`** using the **`ApiKeyStamper`** constructor:
The `ApiKeyStamper` class, serving as a helper, is designed to create a digital stamp using API keys and abstracts away the required stamp headers for requests made to
Turnkey's API. This stamp is instrumental in authenticating requests with the @turnkey/http's `TurnkeyClient`. You can easily initialize a new `ApiKeyStamper` using its constructor:

### `constructor(config: TApiKeyStamperConfig): TStamper`

The `ApiKeyStamper` class is responsible for creating a digital stamp using API keys.
This stamp is used for authenticating requests made with the `@turnkey/http`'s `TurnkeyClient`.

#### Parameters



<Parameter
style={{ borderBottom: "none", paddingBottom: "none"}}
param={{
Expand Down
268 changes: 267 additions & 1 deletion docs/sdk/iframe-stamper.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -12,4 +12,270 @@ import Parameter from '@site/src/components/parameter'

## Introduction

## Installing
The [`@turnkey/iframe-stamper`](https://www.npmjs.com/package/@turnkey/iframe-stamper) module is designed for stamping requests within an iframe using credentials for Turnkey's API.
It works alongside [`@turnkey/http`](https://www.npmjs.com/package/@turnkey/http) to facilitate various flows, such as Recovery and Auth, and Key or Wallet Export.

## Installing

To start using the [`@turnkey/iframe-stamper`](https://www.npmjs.com/package/@turnkey/iframe-stamper) client, install it as follows:

<Tabs>
<TabItem value="npm" label="npm" default>
<CodeBlock
language="bash">
{`npm i @turnkey/iframe-stamper`}
</CodeBlock>
</TabItem>
<TabItem value="pnpm" label="pnpm">
<CodeBlock
language="bash">
{`pnpm i @turnkey/iframe-stamper`}
</CodeBlock>
</TabItem>
<TabItem value="yarn" label="yarn">
<CodeBlock
language="bash">
{`yarn add @turnkey/iframe-stamper`}
</CodeBlock>
</TabItem>
</Tabs>

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

<Parameter
style={{ borderBottom: "none", paddingBottom: "none"}}
param={{
name: 'config',
type: {
name: 'TIframeStamperConfig',
link: 'https://github.com/tkhq/sdk/blob/1b20d5767a913e56174337cbadc7c439c0d400e7/packages/iframe-stamper/src/index.ts#L39-L43'
}
}}
isRequired
>

An object containing configuration settings for the iframe stamper.

</Parameter>

<Parameter
style={{ paddingTop: '0', paddingLeft: "12px"}}
param={{
name: '.iframeUrl',
type: {
name: 'string',
}
}}
isRequired
>

The URL of the iframe to be used.

</Parameter>

<Parameter
style={{ paddingLeft: "12px"}}
param={{
name: '.iframeElementId',
type: {
name: 'string',
}
}}
isRequired
>

The ID to assign to the iframe element.

</Parameter>

<Parameter
style={{ paddingLeft: "12px"}}
param={{
name: '.iframeContainer',
type: {
name: 'HTMLElement | null | undefined',
}
}}
isRequired
>

The container element in which the iframe will be inserted.

</Parameter>


#### Types

##### `TIframeStamperConfig`

```ts
type TIframeStamperConfig = {
iframeUrl: string
iframeElementId: string
iframeContainer: HTMLElement | null | undefined
}
```
#### Example
For full example check out the [email-recovery](https://github.com/tkhq/sdk/tree/main/examples/email-recovery) example in our sdk repo. You should also
read up on [Email Recovery](../getting-started/email-recovery) and [Email Auth](../getting-started/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
```ts
// Assuming iframeStamper is an instance of IframeStamper
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 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

<Parameter
param={{
name: 'bundle',
type: {
name: 'string',
}
}}
isRequired
>

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)).

</Parameter>

#### Example

```ts
// .. 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

<Parameter
param={{
name: 'bundle',
type: {
name: 'string',
}
}}
isRequired
>

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).

</Parameter>

#### Example

```ts
// .. 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

<Parameter
param={{
name: 'bundle',
type: {
name: 'string',
}
}}
isRequired
>

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.

</Parameter>

#### Example

```ts
// .. 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

```ts
// .. 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

```ts
// .. Add imports and init the IframeStamper

iframeStamper.clear()
```
Loading

0 comments on commit f72a41e

Please sign in to comment.