Home

Recovering the embedded signer

Recovering the embedded signer is needed when a user logs into a new device or when the embedded signer is lost.

Openfort embedded signers have two core recovery modes: automatic recovery and password-based recovery. At a high-level, this setting modulates how the embedded signer's recovery share is encrypted and stored.

  • Automatic recovery: Openfort uses Shield to generate and store the key used to encrypt the recovery share of the embedded signer. When logging into a new device, users can immediately access their embedded signer.

  • Password-based recovery: the recovery share is encrypted by user-provided entropy. When logging into a new device, users must enter in their password to recover the embedded signer on the new device. Once the embedded signer has been recovered on a device, users will not need to enter their password on that devices again.

Initialization#

After installing the Openfort SDK in your project, you can initialize the SDK with your Openfort publishable key and Shield API key.

info

This guide shows you through using a hosted Shield instance. If you'd like to host your own Shield instance, please refer to the Advanced self-hosted documentation.

After your project is ready, grab your publishable_key, shield_api_key and shield_encryption_share from your Openfort dashboard.


_10
import Openfort from "@openfort/openfort-js";
_10
const openfort = Openfort('YOUR_OPENFORT_PUBLISHABLE_KEY', "YOUR_SHIELD_API_KEY", "YOUR_SHIELD_ENC_SHARE");

Password-based recovery#

Require that users set a password when the wallet is created, enforcing password-based recovery from the start

If encrypted by user-provided entropy, only the user can decrypt the recovery share. Openfort never sees or the user's password.

Using Openfort Auth#


_10
async function authSetAutomaticRecoveryMethod(email:string, password:string, recoveryPassword:string) {
_10
const response = await openfort.signUpWithEmailPassword(email, password);
_10
const chainId = 80002;
_10
const shieldAuth: ShieldAuthentication = {
_10
auth: AuthType.OPENFORT,
_10
token: response.token
_10
};
_10
await openfort.configureEmbeddedSignerRecovery(chainId, shieldAuth, recoveryPassword);
_10
}

Using Third-party Auth#

This example will showcase Firebase as the third-party auth provider. You can replace it with any other third-party auth provider supported by Openfort or with Custom Auth.


_11
async function authAndSetPassordRecoveryMethod(idToken: string, password: string) {
_11
await openfort.authenticateWithThirdPartyProvider("firebase", idToken, TokenType.idToken);
_11
const chainId = 80002;
_11
const shieldAuth: ShieldAuthentication = {
_11
auth: AuthType.OPENFORT,
_11
token: idToken,
_11
authProvider: "firebase",
_11
tokenType: "idToken",
_11
};
_11
await openfort.configureEmbeddedSignerRecovery(chainId, shieldAuth, password);
_11
}

Automatic recovery#

It is worth noting that Shield mode makes for smooth user UX (without needing to set up a recovery system upfront when logging in) but it comes with tradeoffs. Notably, the root of trust with Shield's automatic recovery is the user’s authentication token. This means access to the auth token grants access to the wallet. Accordingly, this token must be properly secured at all times.

When using automatic recovery, Shield generates a password that is used for the encryption of the recovery share. The encryption key can only be accessed if the decryption request includes the user's auth token.

We recommend enabling password-based recovery for users. This is especially important to enforce as the value of assets in a user's wallet grows.

Using Openfort Auth#


_10
async function authSetAutomaticRecoveryMethod(email:string, password:string) {
_10
const response = await openfort.signUpWithEmailPassword(email, password);
_10
const chainId = 80002;
_10
const shieldAuth: ShieldAuthentication = {
_10
auth: AuthType.OPENFORT,
_10
token: response.token
_10
};
_10
await openfort.configureEmbeddedSigner(chainId, shieldAuth);
_10
}

Using Third-party Auth#


_11
async function authSetAutomaticRecoveryMethod(idToken: string) {
_11
await openfort.authenticateWithThirdPartyProvider("firebase", idToken, TokenType.idToken);
_11
const chainId = 80002;
_11
const shieldAuth = {
_11
auth: AuthType.OPENFORT,
_11
token: idToken,
_11
authProvider: "firebase",
_11
tokenType: "idToken",
_11
};
_11
await openfort.configureEmbeddedSigner(chainId, shieldAuth);
_11
}

Resources#