-
Notifications
You must be signed in to change notification settings - Fork 180
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update docs for mpc core kit react native
- Loading branch information
1 parent
bcf618a
commit 27b631b
Showing
29 changed files
with
1,961 additions
and
127 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
241 changes: 241 additions & 0 deletions
241
docs/sdk/mpc-core-kit/mpc-core-kit-react-native/authentication.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,241 @@ | ||
| --- | ||
| title: "Web3Auth MPC Core Kit JS SDK - Authentication" | ||
| sidebar_label: "Authentication" | ||
| description: "Web3Auth MPC Core Kit JS SDK - Authentication | Documentation - Web3Auth" | ||
| --- | ||
|
|
||
| import TabItem from "@theme/TabItem"; | ||
| import Tabs from "@theme/Tabs"; | ||
|
|
||
| In the login process, in react native, the SDK expects you to have a JWT token from your own | ||
| authentication, via a service of your choice (like Auth0, Firebase, AWS Cognito, etc). This token is | ||
| then passed to the SDK to authenticate the user. | ||
|
|
||
| As a prerequisite, before triggering the login function, you need to create a verifier for your | ||
| login method on the [Web3Auth Dashboard](https://dashboard.web3auth.io). | ||
|
|
||
| ## Creating a Verifier | ||
|
|
||
| Since this is a Core Kit SDK, it does not provide any default authentication methods. You need to | ||
| create a custom verifier to use this SDK. This means that you need to authenticate users with your | ||
| own custom authentication service. | ||
|
|
||
| For example, while authenticating with Google, you have to use your own Google Client ID setup to | ||
| authenticate users directly or use auth provider services like Auth0, Firebase, AWS Cognito etc. | ||
| Additionally, you can make your own JWT token authentication system and pass over the ID Token to | ||
| Web3Auth. | ||
|
|
||
| [Learn how to create a verifier](/auth-provider-setup/verifiers). | ||
|
|
||
|  | ||
|
|
||
| ## Login | ||
|
|
||
| To authenticate users using your own id token, you can use the `loginWithJWT` method. This methods | ||
| takes the `JWTLoginParams` as a parameter, which is an object that contains the details of the | ||
| verifier, and additional authentication parameters like idToken, subVerifier, etc. | ||
|
|
||
| In JWT login flow, you'll have to manually get the idToken from the auth provider and pass it to the | ||
| login function. | ||
|
|
||
| ## Parameters | ||
|
|
||
| <Tabs | ||
| defaultValue="table" | ||
| values={[ | ||
| { label: "Table", value: "table" }, | ||
| { label: "Type", value: "type" }, | ||
| ]} | ||
| > | ||
|
|
||
| <TabItem value="table"> | ||
|
|
||
| | Parameter | Description | | ||
| | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | `verifier` | Name of the verifier created on Web3Auth Dashboard. In the case of Aggregate Verifier, the name of the top-level aggregate verifier. | | ||
| | `verifierId` | Unique Identifier for the User. The verifier identifier field is set for the verifier/sub verifier. E.g. "sub" field in your JWT ID Token. | | ||
| | `idToken` | The idToken received from the Auth Provider. | | ||
| | `subVerifier?` | Name of the sub verifier in case of aggregate verifier setup. This field is mandatory in the case of an aggregate verifier. | | ||
| | `extraVerifierParams?` | Extra verifier params in case of a WebAuthn verifier type. | | ||
| | `additionalParams?` | Any additional parameter (key-value pair) you'd like to pass to the login function. | | ||
| | `importTssKey?` | Key to import key into TSS during first time login. For secp256k1 curve, you need to pass the private key, and for ed25519 curve you need to pass the seed. The ed25519 seed is hashed to generate 64 bytes, where first 32 bytes are used to generate the public key, and last 32 bytes are used as private key. | | ||
| | `prefetchTssPublicKeys?` | Defines the number of TSS public keys to prefetch.The SDK by default starts with 2/2 flow, and this parameter should be used in the flow where you want to generate the recovery factor during first time login. The parameters helps you to reduce the operation time by pre-fetching the TSS public key and use it during generating new shares. For existing user you can set it to `0`. Default is `1`, maximum is `3` | | ||
|
|
||
| </TabItem> | ||
| <TabItem value="type"> | ||
|
|
||
| ```tsx | ||
| interface JWTLoginParams { | ||
| /** | ||
| * Name of the verifier created on Web3Auth Dashboard. In case of Aggregate Verifier, the name of the top level aggregate verifier. | ||
| */ | ||
| verifier: string; | ||
| /** | ||
| * Unique Identifier for the User. The verifier identifier field set for the verifier/ sub verifier. E.g. "sub" field in your on jwt id token. | ||
| */ | ||
| verifierId: string; | ||
| /** | ||
| * The idToken received from the Auth Provider. | ||
| */ | ||
| idToken: string; | ||
| /** | ||
| * Name of the sub verifier in case of aggregate verifier setup. This field should only be provided in case of an aggregate verifier. | ||
| */ | ||
| subVerifier?: string; | ||
| /** | ||
| * Extra verifier params in case of a WebAuthn verifier type. | ||
| */ | ||
| extraVerifierParams?: PasskeyExtraParams; | ||
| /** | ||
| * Any additional parameter (key value pair) you'd like to pass to the login function. | ||
| */ | ||
| additionalParams?: ExtraParams; | ||
| /** | ||
| * Key to import key into Tss during first time login. | ||
| */ | ||
| importTssKey?: string; | ||
| /** | ||
| * Number of TSS public keys to prefetch. For the best performance, set it to | ||
| * the number of factors you want to create. Set it to 0 for an existing user. | ||
| * Default is 1, maximum is 3. | ||
| */ | ||
| prefetchTssPublicKeys?: number; | ||
| } | ||
|
|
||
| export interface ExtraParams { | ||
| [key: string]: unknown; | ||
| } | ||
|
|
||
| export type WebAuthnExtraParams = { | ||
| signature?: string; | ||
| clientDataJSON?: string; | ||
| authenticatorData?: string; | ||
| publicKey?: string; | ||
| challenge?: string; | ||
| rpOrigin?: string; | ||
| credId?: string; | ||
| transports?: AuthenticatorTransport[]; | ||
| }; | ||
|
|
||
| type AuthenticatorTransport = "ble" | "hybrid" | "internal" | "nfc" | "usb"; | ||
| ``` | ||
|
|
||
| </TabItem> | ||
|
|
||
| </Tabs> | ||
|
|
||
| ## Usage | ||
|
|
||
| ### Single Verifier | ||
|
|
||
| To login with a single verifier, you will require to create a custom verifier in the Web3Auth | ||
| dashboard. If you haven't already created one, | ||
| [learn how to create a verifier](/docs/auth-provider-setup/byo-jwt-provider/#set-up-custom-jwt-verifier). | ||
|
|
||
| ```tsx | ||
| const jwtLoginParams: JWTLoginParams = { | ||
| verifier: "YOUR_VERIFIER_NAME", | ||
| verifierId: "USER'S_VERIFIER_ID", | ||
| idToken: "USER'S_ID_TOKEN", | ||
| }; | ||
|
|
||
| await coreKitInstance.loginWithJWT(jwtLoginParams); | ||
| ``` | ||
|
|
||
| ### Aggregate Verifier | ||
|
|
||
| To login with an aggregate verifier, you will require to create an aggregate verifier in the | ||
| Web3Auth dashboard. If you haven't already created one, | ||
| [learn how to create an aggregate verifier](/docs/auth-provider-setup/aggregate-verifier#set-up-an-aggregate-verifier). | ||
|
|
||
| ```tsx | ||
| const jwtLoginParams = { | ||
| verifier: "YOUR_AGGREGATE_VERIFIER_NAME" | ||
| subVerifier: "YOUR_SUB_VERIFIER_NAME", | ||
| verifierId: "USER'S_VERIFIER_ID", | ||
| idToken: "USER'S_ID_TOKEN", | ||
| } | ||
|
|
||
| await coreKitInstance.loginWithJWT(jwtLoginParams); | ||
| ``` | ||
|
|
||
| ## Importing an existing account. | ||
|
|
||
| During the first-time login with `Web3AuthMPCCoreKit`, you can import an existing account using the | ||
| `importTssKey` parameter. To import a secp256k1 chain account, be sure to provide the private key in | ||
| hex format. For an ed25519 chain account, you need to pass the seed. | ||
|
|
||
| By default, the ed25519 key is formatted in base58 and is 64 bytes long. This consists of the first | ||
| 32 bytes as the seed (also known as the private key) and the last 32 bytes as the public key. Ensure | ||
| that the first 32 bytes are provided in hexadecimal format when using the ed25519 seed. | ||
|
|
||
| ```tsx | ||
| const jwtLoginParams = { | ||
| verifier: "YOUR_VERIFIER_NAME", | ||
| verifierId: "USER'S_VERIFIER_ID", | ||
| idToken: "USER'S_ID_TOKEN", | ||
| // focus-next-line | ||
| importTssKey: "SECP256K1_PRIVATE_KEY_OR_ED25519_SEED", | ||
| }; | ||
|
|
||
| await coreKitInstance.loginWithJWT(jwtLoginParams); | ||
| ``` | ||
|
|
||
| ## Backend verification | ||
|
|
||
| To verify the user in the backend, you can retrieve the user's signature from frontend, and validate | ||
| it using the `SignatureValidator` from the | ||
| [@toruslabs/signature-validator](https://www.npmjs.com/package/@toruslabs/signature-validator) | ||
| package in the backend. | ||
|
|
||
| ### Retrieve user's signature | ||
|
|
||
| To retrieve user's signature you can use the `signatures` getter from `Web3AuthMPCCoreKit`. | ||
|
|
||
| ```tsx | ||
| const signatures = coreKitInstance.signatures; | ||
|
|
||
| // Send these signatures to backend through an API | ||
| ``` | ||
|
|
||
| ### Verify the signatures in backend | ||
|
|
||
| For verification you'll need to install couple of packages, | ||
| [@toruslabs/signature-validator](https://www.npmjs.com/package/@toruslabs/signature-validator) and | ||
| [@toruslabs/fnd-base](https://www.npmjs.com/package/@toruslabs/fnd-base), and use | ||
| `SignatureValidator` to validate the signatures. | ||
|
|
||
| ```js | ||
| const { fetchLocalConfig } = require("@toruslabs/fnd-base"); | ||
| const { SignatureValidator } = require("@toruslabs/signature-validator"); | ||
|
|
||
| // Here network can be "sapphire_mainnet" or "sapphire_testnet", since MPC doesn't support | ||
| // legacy networks. | ||
| const network = "sapphire_mainnet"; | ||
|
|
||
| // Fetch the node details | ||
| const nodeDetails = fetchLocalConfig(network, "secp256k1"); | ||
|
|
||
| const nodePubX = []; | ||
| const nodePubY = []; | ||
|
|
||
| nodeDetails.torusNodePub.forEach((key) => { | ||
| nodePubX.push(key.X); | ||
| nodePubY.push(key.Y); | ||
| }); | ||
|
|
||
| // Create the SignatureValidator object | ||
| const sigValidator = new SignatureValidator({ | ||
| nodePubKeyX: nodePubX.join(","), | ||
| nodePubKeyY: nodePubY.join(","), | ||
| }); | ||
|
|
||
| // Get the signatures from the frontend & validate the signatures | ||
| const result = sigValidator.authenticate(signatures, { skipExpValidation: false }); | ||
|
|
||
| if (!result) { | ||
| // Handle invalid singature | ||
| } | ||
|
|
||
| // Handle the valid signature | ||
| ``` |
11 changes: 11 additions & 0 deletions
11
docs/sdk/mpc-core-kit/mpc-core-kit-react-native/examples.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| --- | ||
| title: Examples - MPC Core Kot SDK | ||
| sidebar_label: Examples | ||
| description: "@web3auth/mpc-core-kit Examples | Documentation - Web3Auth" | ||
| hide_table_of_contents: true | ||
| --- | ||
|
|
||
| import Examples from "@site/src/components/Examples"; | ||
| import { coreKitMPCWebExamples, coreKitMPCReactNativeExamples } from "@site/src/common/maps"; | ||
|
|
||
| <Examples exampleMap={[...coreKitMPCReactNativeExamples]} /> |
Oops, something went wrong.