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.

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#

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

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.

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

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#

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

Using Third-party Auth#

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

Resources#

Start your embedded signer