From f72a41e218903ec2dd9fb1880b1e17951041217f Mon Sep 17 00:00:00 2001 From: Taylor Dawson Date: Tue, 16 Jan 2024 15:53:49 -0800 Subject: [PATCH] Add stamper docs --- .../email-recovery-in-sub-organizations.md | 2 +- docs/sdk/api-key-stamper.mdx | 9 +- docs/sdk/iframe-stamper.mdx | 268 +++++++++++++++++- docs/sdk/webauthn-stamper.mdx | 90 ++++-- src/components/parameter.js | 19 +- 5 files changed, 357 insertions(+), 31 deletions(-) diff --git a/docs/integration-guides/email-recovery-in-sub-organizations.md b/docs/integration-guides/email-recovery-in-sub-organizations.md index b70c5bc..25b8ba4 100644 --- a/docs/integration-guides/email-recovery-in-sub-organizations.md +++ b/docs/integration-guides/email-recovery-in-sub-organizations.md @@ -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 diff --git a/docs/sdk/api-key-stamper.mdx b/docs/sdk/api-key-stamper.mdx index 7a47d6c..e27268c 100644 --- a/docs/sdk/api-key-stamper.mdx +++ b/docs/sdk/api-key-stamper.mdx @@ -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 - - + + + {`npm i @turnkey/iframe-stamper`} + + + + + {`pnpm i @turnkey/iframe-stamper`} + + + + + {`yarn add @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 + + + +An object containing configuration settings for the iframe stamper. + + + + + +The URL of the iframe to be used. + + + + + +The ID to assign to the iframe element. + + + + + +The container element in which the iframe will be inserted. + + + + +#### 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` + +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` + +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` that resolves to `true` if the bundle was successfully injected into the iframe, or `false` otherwise. + +#### Parameters + + + +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)). + + + +#### Example + +```ts +// .. Add imports and init iframeStamper + +// Pasted into the iFrame by the user +const credentialBundle = "" + +// Injects a new credential in the iframe +const injected = await iframeStamper.injectCredentialBundle(credentialBundle) +``` + +### `injectKeyExportBundle: (bundle: string) => Promise` + +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` which resolves to `true` if the bundle was successfully injected into the iframe, or `false` otherwise. + +#### Parameters + + + +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 + +```ts +// .. Add imports and init the IframeStamper + +// Pasted into the iFrame by the user +const keyExportBundle = "" + +// Injects a new wallet in the iframe +const injected = await iframeStamper.injectKeyExportBundle(keyExportBundle) + +``` + +### `injectWalletExportBundle: (bundle: string) => Promise` + +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` which resolves to `true` if the bundle is successfully injected into the iframe, or `false` otherwise. + +#### Parameters + + + +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 + +```ts +// .. Add imports and init the IframeStamper + +// Pasted into the iFrame by the user +const walletExportBundle = "" + +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() +``` \ No newline at end of file diff --git a/docs/sdk/webauthn-stamper.mdx b/docs/sdk/webauthn-stamper.mdx index ec260d1..5444c46 100644 --- a/docs/sdk/webauthn-stamper.mdx +++ b/docs/sdk/webauthn-stamper.mdx @@ -12,6 +12,13 @@ import Parameter from '@site/src/components/parameter' ## Introduction + +The [`@turnkey/webauthn-stamper`](https://www.npmjs.com/package/@turnkey/webauthn-stamper) +module is used for stamping requests made to Turnkey's API with WebAuthn credentials, but specifically for use with passkeys. + +For more information on passkeys and WebAuthn refer to [this section](../passkeys/introduction). + + ## Installing To get started install the [`@turnkey/webauthn-stamper`](https://www.npmjs.com/package/@turnkey/webauthn-stamper) client. @@ -39,7 +46,11 @@ To get started install the [`@turnkey/webauthn-stamper`](https://www.npmjs.com/p ## Initializing -### `constructor(config: TWebauthnStamperConfig)` +The `WebauthnStamper` class is a utility designed to facilitate the process of creating a digital stamp using WebAuthn credentials. +This stamp is essential for authenticating requests made to a web server or API that utilizes WebAuthn for secure, passwordless authentication. +You can initialize a new `WebauthnStamper` using the WebauthnStamper constructor: + +### `constructor(config: TWebauthnStamperConfig): WebauthnStamper` #### Parameters @@ -71,8 +82,8 @@ An object containing configuration settings for the stamper. > The RPID ("Relying Party ID") for your origin. -For an origin named "https://www.example.com", the RPID is typically "example.com". -If you're testing on localhost, the RPID should be "localhost". +For an origin named `https://www.example.com`, the RPID is typically `example.com`. +If you're testing on localhost, the RPID should be `localhost`. @@ -86,7 +97,7 @@ If you're testing on localhost, the RPID should be "localhost". }} > -Optional timeout value. Defaults to 5 minutes. +The time in milliseconds before the stamp request times out. Defaults to 300000 milliseconds (5 minutes) if not specified. @@ -96,12 +107,12 @@ Optional timeout value. Defaults to 5 minutes. name: 'userVerification', type: { name: 'UserVerificationRequirement', - link: 'https://github.com/tkhq/sdk/blob/main/packages/webauthn-stamper/src/index.ts#L9-L20' + link: 'https://github.com/microsoft/TypeScript/blob/d69757e3d39d48eaa798e6e542dd416f8aac2c93/src/lib/dom.generated.d.ts', } }} > -Optional override for UV flag. Defaults to "preferred". +Specifies the user verification requirements. Can be set to values like `required`, `preferred`, or `discouraged`. Defaults to `preferred` if not provided. @@ -111,12 +122,12 @@ Optional override for UV flag. Defaults to "preferred". name: 'allowCredentials', type: { name: 'PublicKeyCredentialDescriptor[]', - link: 'https://github.com/microsoft/TypeScript/blob/main/src/lib/dom.generated.d.ts#L1235-L1239' + link: 'https://github.com/microsoft/TypeScript/blob/d69757e3d39d48eaa798e6e542dd416f8aac2c93/src/lib/dom.generated.d.ts', } }} > -The list of credentials to pass. Defaults to empty. +An array of credential descriptors specifying the credentials to be allowed during authentication. This is optional and defaults to an empty array. @@ -133,26 +144,63 @@ type TWebauthnStamperConfig = { } ``` - - ##### `UserVerificationRequirement` -``` -type UserVerificationRequirement = "discouraged" | "preferred" | "required" -``` +DOM API type. See [lib/dom.generated.d.ts](https://github.com/microsoft/TypeScript/blob/d69757e3d39d48eaa798e6e542dd416f8aac2c93/src/lib/dom.generated.d.ts) for full type definition. + ##### `PublicKeyCredentialDescriptor` -``` -interface PublicKeyCredentialDescriptor { - id: BufferSource; - transports?: AuthenticatorTransport[]; - type: PublicKeyCredentialType; -} -``` +DOM API type. See [lib/dom.generated.d.ts](https://github.com/microsoft/TypeScript/blob/d69757e3d39d48eaa798e6e542dd416f8aac2c93/src/lib/dom.generated.d.ts) for full type definition. + #### Example +```ts +import { WebauthnStamper } from "@turnkey/webauthn-stamper"; +import { TurnkeyClient } from "@turnkey/http"; + +const stamper = new WebAuthnStamper({ + rpId: "example.com", +}); + +// New HTTP client able to sign with passkeys! +const httpClient = new TurnkeyClient( + { baseUrl: "https://api.turnkey.com" }, + stamper +); +``` + ## Methods -#### Types \ No newline at end of file +### `stamp: (input: string) => Promise` + +Creates a digital stamp, which includes the public key, signature scheme, and a signature based on WebAuthn credentials. +This generated stamp is used in the `X-Stamp` header of HTTP requests to authenticate. + +#### Parameters + + + +The payload should contain relevant data that needs to be authenticated, often related to the user's session or specific request. + + + +#### Types + +##### `TStamp` + +```ts +type TStamp = { + stampHeaderName: string; + stampHeaderValue: string; +} +``` \ No newline at end of file diff --git a/src/components/parameter.js b/src/components/parameter.js index 682744f..9810184 100644 --- a/src/components/parameter.js +++ b/src/components/parameter.js @@ -1,6 +1,12 @@ import React from "react" -export default function Parameter({ children, param, isRequired, style }) { +export default function Parameter({ + children, + param, + isRequired, + style, + note, +}) { return (
{param.type.name} )} + {isRequired && ( )} + {param?.type?.note && ( +
+ {param?.type?.note} +
+ )}