Create and recover signers

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 user-based recovery. At a high-level, this setting modulates how the embedded signer's recovery share is encrypted and stored.

Automatic recovery: The recovery share is encrypted with a combination of project entropy and Openfort's entropy. When logging into a new device, users can immediately access their embedded signer.
User-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.

Automatic recovery#

It is worth noting that while automatic recovery makes for smooth user UX (without needing to set up a recovery system upfront when logging in), it comes with tradeoffs. Notably, the root of trust with is in 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 full encryption key can only be accessed if the decryption request includes the user's auth token.

When using automatic recovery, its very important to ensure that the encryption share should not be available from the client side of the application. An encryption session is requested every time configureEmbeddedSigner is called. The encryption session is only valid for a single use.

From your backend, you should have an endpoint that generates an encryption session for the user. This endpoint should be protected and only accessible by the user who is requesting the encryption session (i.e. the user who is logging in). For example, in a Next.js API route, you can create an endpoint like this:

protected-create-encryption-session.ts

openfortAdminConfig.ts

import openfort from './openfortAdminConfig';
export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
    const session = await openfort.registerRecoverySession('YOUR_SHIELD_PUBLISHABLE_KEY', 'YOUR_SHIELD_SECRET_KEY', 'YOUR_SHIELD_ENCRYPTION_SHARE')
    res.status(200).send({
        session: session,
    });
}

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

configure.tsx

encryptionSession.ts

openfortConfig.ts

import {ShieldAuthType, ShieldAuthentication} from '@openfort/openfort-js';
import openfort from "./openfortConfig"
import getEncryptionSession from "./encryptionSession"
async function authSetAutomaticRecoveryMethod(email:string, password:string) {
    const response = await openfort.signUpWithEmailPassword({email, password});
    const chainId = 80002;
    const shieldAuth: ShieldAuthentication = {
        auth: ShieldAuthType.OPENFORT,
        token: response.token,
        encryptionSession: await getEncryptionSession()
    };
    await openfort.configureEmbeddedSigner(chainId, shieldAuth);
}

User-based recovery#

Password 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. Therefore, if you're not planning to ever user the automatic recovery mode, you can use the encryption share in the client side of the application.

configure.tsx

openfortConfig.ts

import {ShieldAuthType, ShieldAuthentication} from '@openfort/openfort-js';
import openfort from "./openfortConfig"
async function authSetAutomaticRecoveryMethod(email:string, password:string, recoveryPassword:string) {
    const response = await openfort.signUpWithEmailPassword({email, password});
    const chainId = 80002;
    const shieldAuth: ShieldAuthentication = {
        auth: ShieldAuthType.OPENFORT,
        token: response.token
    };
    await openfort.configureEmbeddedSigner(chainId, shieldAuth, recoveryPassword);
}