From 2b5c355093835691d5c2fb56ccd88416f2e341c8 Mon Sep 17 00:00:00 2001 From: Taylor Dawson Date: Mon, 22 Jan 2024 17:23:48 -0800 Subject: [PATCH] Addresses PR review comments --- .gitignore | 2 +- docs/api-design/intro.md | 1 - docs/sdk/api-key-stamper.mdx | 30 +++++++++++------------------- docs/sdk/iframe-stamper.mdx | 21 +++++++++++++++------ docs/sdk/turnkey-client.mdx | 17 ++++++++++------- docs/sdk/webauthn-stamper.mdx | 34 ++++++++++++++++++++++------------ 6 files changed, 59 insertions(+), 46 deletions(-) diff --git a/.gitignore b/.gitignore index 95ec902..485cbde 100644 --- a/.gitignore +++ b/.gitignore @@ -4,4 +4,4 @@ build *.sw[a-z] .DS_Store .gitconfig -.vscode \ No newline at end of file +.vscode diff --git a/docs/api-design/intro.md b/docs/api-design/intro.md index 3b1b377..a7f22de 100644 --- a/docs/api-design/intro.md +++ b/docs/api-design/intro.md @@ -41,7 +41,6 @@ Every request made to Turnkey must include a signature inside a stamp header. Ou 1. Create a JSON-encoded string with the authenticator data, client data, credential ID, and signature. 2. Add the string to your request as a `X-Stamp-Webauthn` header -### If using a custom stamper In practice you should not have to worry about this step: our [JS SDK](https://github.com/tkhq/sdk) and [CLI](https://github.com/tkhq/tkcli) will take care of it for you. However, if you write an independent client, you will need to implement this yourself. For reference, check out our implementations: diff --git a/docs/sdk/api-key-stamper.mdx b/docs/sdk/api-key-stamper.mdx index e27268c..d771a9a 100644 --- a/docs/sdk/api-key-stamper.mdx +++ b/docs/sdk/api-key-stamper.mdx @@ -12,18 +12,9 @@ import Parameter from '@site/src/components/parameter' ## Introduction -The `@turnkey/api-key-stamper` module is an abstraction for stamping requests made to Turnkey's API using your public and private API keys. -For more information on API keys refer to [this section](../faq#why-do-you-require-a-public--private-key-pair-to-access-turnkey-api). - -The stamper can be used to initiate select requests on behalf of the end-user. -For instance, your app can create a new sub-organization on behalf of the end-user. See our integration guide -[Sub-Organizations as Wallets](../integration-guides/sub-organizations-as-wallets#step-1-create-a-sub-organization) for a complete example. - -:::note - -This module is intended to be used on the **server** as you would **_not_** want to expose your private API key to the client. - -::: +The @turnkey/api-key-stamper module simplifies the process of using your public/private API keys and passkeys to stamp and approve activity requests for Turnkey's API. +This stamping mechanism is central to the API's security, ensuring that each request is authenticated and authorized. +For an in-depth understanding of API keys see [this section](../faq#why-do-you-require-a-public--private-key-pair-to-access-turnkey-api). ## Installing @@ -52,8 +43,10 @@ To get started install the [`@turnkey/api-key-stamper`](https://www.npmjs.com/pa ## Initializing -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: + +The `ApiKeyStamper` class serving as a helper, that implements the `TStamper` interface used by the [TurnkeyClient](./turnkey-client.mdx) in the `@turnkey/http` module. +It encapsulates the logic necessary to sign activity requests and generate the appropriate HTTP headers for authentication. +To get started with an `ApiKeyStamper`, you can initialize it using its constructor: ### `constructor(config: TApiKeyStamperConfig): TStamper` @@ -65,7 +58,7 @@ Turnkey's API. This stamp is instrumental in authenticating requests with the @t name: 'config', type: { name: 'TApiKeyStamperConfig', - link: 'https://github.com/tkhq/sdk/blob/main/packages/api-key-stamper/src/index.ts#L8-L11' + link: 'https://github.com/tkhq/sdk/blob/a20922085f27537af70d61321fe2c3b82db71e17/packages/api-key-stamper/src/index.ts#L8-L11' } }} isRequired @@ -87,7 +80,7 @@ An object containing configuration settings for the stamper. isRequired > -Your Turnkey api private key. +Your Turnkey API private key. @@ -102,7 +95,7 @@ Your Turnkey api private key. isRequired > -Your Turnkey api public key. +Your Turnkey API public key. @@ -127,7 +120,7 @@ interface TStamper { #### Example -The example below shows how to initialze and use the `ApiKeyStamper` with the `TurnkeyClient` to make a request +The example below shows how to initialize and use the `ApiKeyStamper` with the `TurnkeyClient` to make a request to Turnkey's [`/public/v1/query/whoami`](https://docs.turnkey.com/api#tag/Sessions/operation/GetWhoami) endpoint: ```ts @@ -157,7 +150,6 @@ const whoami = await tk.getWhoami({ ### `stamp: (input: string) => Promise` Creates a digital stamp which includes the public key, signature scheme, and a signature. -This stamp is used in the `X-Stamp` header of HTTP requests to authenticate. #### Parameters diff --git a/docs/sdk/iframe-stamper.mdx b/docs/sdk/iframe-stamper.mdx index 268b918..f4df66e 100644 --- a/docs/sdk/iframe-stamper.mdx +++ b/docs/sdk/iframe-stamper.mdx @@ -12,12 +12,22 @@ import Parameter from '@site/src/components/parameter' ## Introduction -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. +The [`@turnkey/iframe-stamper`](https://www.npmjs.com/package/@turnkey/iframe-stamper) module, while sharing a similar purpose with the `@turnkey/api-key-stamper`, caters specifically to the unique context of iframes. +This module 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 [Recovery](../integration-guides/email-recovery-in-sub-organizations.md) / [Auth](../integration-guides/email-auth-for-sub-organizations.md), and [Key or Wallet Export](../integration-guides/export-wallets.md), 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`](https://www.npmjs.com/package/@turnkey/iframe-stamper) client, install it as follows: +To start using the `@turnkey/iframe-stamper` client, install it as follows: @@ -140,7 +150,6 @@ This method returns a promise that resolves to the iframe's public key, which is #### Example ```ts -// Assuming iframeStamper is an instance of IframeStamper import { IframeStamper } from "@turnkey/iframe-stamper" import { TurnkeyClient } from "@turnkey/http" @@ -193,7 +202,7 @@ 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. +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` which resolves to `true` if the bundle was successfully injected into the iframe, or `false` otherwise. #### Parameters @@ -207,7 +216,7 @@ Injects an export bundle into the iframe. This method is used during key export 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). +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)). diff --git a/docs/sdk/turnkey-client.mdx b/docs/sdk/turnkey-client.mdx index f01bb4b..5cbcdf8 100644 --- a/docs/sdk/turnkey-client.mdx +++ b/docs/sdk/turnkey-client.mdx @@ -12,6 +12,8 @@ import Parameter from '@site/src/components/parameter'; ## Introduction +The [`@turnkey/http`](https://www.npmjs.com/package/@turnkey/http) module is a fully-typed lower-level HTTP client for developers integrating with Turnkey's services. + ## Installing To get started install the [`@turnkey/http`](https://www.npmjs.com/package/@turnkey/http) client. @@ -39,7 +41,7 @@ To get started install the [`@turnkey/http`](https://www.npmjs.com/package/@turn ## Initializing -Create a new client for use in your JavaScript applications. +Create a new client for use in your JavaScript/Typescript applications. You can initialize a new **`TurnkeyClient`** using the **`TurnkeyClient`** constructor. The **`TurnkeyClient`** serves as your entry point to interact with the Turnkey ecosystem. @@ -51,7 +53,7 @@ You can initialize a new **`TurnkeyClient`** using the **`TurnkeyClient`** const name: 'config', type: { name: 'THttpConfig', - link: 'https://github.com/tkhq/sdk/blob/main/packages/http/src/base.ts#L257-L259' + link: 'https://github.com/tkhq/sdk/blob/a20922085f27537af70d61321fe2c3b82db71e17/packages/http/src/base.ts#L257-L259' } }} isRequired @@ -89,13 +91,14 @@ An object containing configuration settings for the client. isRequired > -An instance of a stamper class (e.g. [**`ApiKeyStamper`**](https://github.com/tkhq/sdk/blob/main/packages/api-key-stamper/src/index.ts#L33)) used to create signatures for authenticating API requests. +An instance of a stamper class (e.g. [**`ApiKeyStamper`**](./api-key-stamper.mdx)) used to create signatures for authenticating API requests. -Currently Turnkey provides 2 stampers: - - applications signing requests with Passkeys or webauthn devices should use [`@turnkey/webauthn-stamper`](https://www.npmjs.com/package/@turnkey/webauthn-stamper) - - applications signing requests with API keys should use [`@turnkey/api-key-stamper`](https://www.npmjs.com/package/@turnkey/api-key-stamper) +Currently Turnkey provides 3 stampers: + - applications signing requests with Passkeys or webauthn devices should use [`@turnkey/webauthn-stamper`](./webauthn-stamper.mdx) + - applications signing requests with API keys should use [`@turnkey/api-key-stamper`](./api-key-stamper.mdx) + - applications that need to sign requests within an iframe, particularly when handling sensitive operations like Recovery and Auth, or Key or Wallet Export, should use the [`@turnkey/iframe-stamper`](./iframe-stamper.mdx). -You can also implement the TStamper interface yourself. For more information checkout [Using a custom stamper](../api-introduction#if-using-a-custom-stamper). +You can also implement the TStamper interface yourself. For more information on implementing a custom stamper checkout the [API Design](./../api-design/intro.md) docs. diff --git a/docs/sdk/webauthn-stamper.mdx b/docs/sdk/webauthn-stamper.mdx index 5444c46..9b16ed0 100644 --- a/docs/sdk/webauthn-stamper.mdx +++ b/docs/sdk/webauthn-stamper.mdx @@ -73,7 +73,7 @@ An object containing configuration settings for the stamper. @@ -119,10 +119,10 @@ Specifies the user verification requirements. Can be set to values like `require @@ -146,12 +146,23 @@ type TWebauthnStamperConfig = { ##### `UserVerificationRequirement` -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. +```ts +type UserVerificationRequirement = "discouraged" | "preferred" | "required"; +``` +Refer to our guide on [using passkeys](https://docs.turnkey.com/passkeys/options#userverification) for more information on this type and its usage. ##### `PublicKeyCredentialDescriptor` -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. +```ts +interface PublicKeyCredentialDescriptor { + id: BufferSource; + transports?: AuthenticatorTransport[]; + type: PublicKeyCredentialType; +} +``` + +Refer to our guide on [using passkeys](https://docs.turnkey.com/passkeys/options#allowcredentials) for more information on this type and its usage. #### Example @@ -176,13 +187,12 @@ const httpClient = new TurnkeyClient( ### `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. +The Turnkey activity request, or query to be sent to Turnkey's API. @@ -203,4 +213,4 @@ type TStamp = { stampHeaderName: string; stampHeaderValue: string; } -``` \ No newline at end of file +```