Account Recovery

In case you lose your passkeys, ZKsync SSO will provide several methods to recover your account.

Multiple Devices with Passkey Synchronization

Users can synchronize their passkeys across multiple devices using services like iCloud Keychain for Apple devices or similar services on other platforms. This means if one device is lost, the passkeys are still accessible on other synchronized devices.

Account Recovery with Guardians

Recovering an account with a Guardian is a safety feature designed to help users regain access to their SSO accounts if their primary authentication method (such as a passkey) is lost.

Users can initiate the recovery process to update their passkey authentication, with the Guardian serving as both verifier and facilitator.

Guardian

A Guardian is a trusted entity designated to assist in recovering access to a smart account. It achieves this by signing to verify the legitimacy of the recovery process.

→ In other words, another account that acts as a guardian of the SSO account, protecting the owner from losing access to it due to the loss of the primary authentication method.

Key characteristics include:

• Can be another smart account with any valid blockchain address.
• Must be explicitly proposed by the SSO account owner.
• Must actively accept the Guardian role.
• Can verify recovery attempts but cannot directly control the account.
• Allows multiple guardians to be assigned to an account.

Main flows high-level description

Adding & Verifying a Guardian

This diagram illustrates the process of adding a new guardian to a user's SSO account.

The flow begins when a user decides to add a guardian and involves communication between the User, Auth Server, and SSO Account to generate and process a unique invitation that the designated guardian must accept.

Recovering an account

This diagram illustrates the step-by-step process of recovering an SSO account when a user has lost access to their primary authentication method.

The flow shows the interactions between the User, Auth Server, and Guardian during the recovery process, including the initial recovery request, passkey update, guardian verification, and completion of the recovery.

Stop malicious account recovery

This diagram illustrates how SSO account owners can detect and stop unauthorized recovery attempts initiated by a malicious guardian. The flow shows how users are alerted of pending recoveries during normal SSO login and can cancel suspicious recovery attempts before they are completed.

Module Implementation

The solution centers on a new erc7579 validator module called GuardianRecoveryValidator. This guide illustrates how to perform different guardian recovery actions with this module:

Adding & verifying a Guardian

To link a guardian to a smart account, the account owner must first propose the guardian, after which the guardian must verify and accept their role. This ensures mutual consent and secure onboarding.

Proposing a Guardian

The proposeGuardian method handles the initial registration of external accounts by:

1. Taking an external account address and storing it as a pending guardian.
2. Enabling addGuardian to confirm and activate this guardian.
3. Emits: GuardianProposed.

Verifying a Guardian

The addGuardian method handles the registration of external accounts by:

1. Verifying that the guardian was previously proposed by the account.
2. Marking the guardian as active and ready.
3. Recording the guardian-to-account relationship for future recovery and validation.
4. Emits: GuardianAdded.

Removing a Guardian

The removeGuardian method handles guardian removal by:

1. Accepting the guardian's address as input.
2. Removing the guardian from the account's list.
3. Cleaning up associated metadata (e.g., removing the account from the guardian's guarded list).
4. Emitting a GuardianRemoved event to log the change.

Recovery Process

The following section detail the technical implementation of initiating, completing, and canceling the recovery process.

Initiating Recovery

A verified guardian can initiate account recovery using the initRecovery method, which:

1. Verifies the caller is an active guardian of the account.
2. Verifies that account does not have non-expired pending recovery
3. Records a recovery request with:
   • Hashed credential ID
   • Raw public key
   • Timestamp
4. Emits a RecoveryInitiated event for auditability.
5. The contract enforces:
   1. Timelock: Recovery must be delayed by 24 hours before it can be executed.
   2. Expiration: Recovery must be completed within 72 hours, else it expires.

Completing Recovery

Account recovery is completed by submitting a specific transaction validated via validateTransaction, which:

1. Ensures the transaction calls WebAuthValidator.addValidationKey.
2. Confirm the credential ID and public key match the recovery request.
3. Verifies that 24 hours have passed since initiation and the request is within the 72-hour validity window.
4. Mark recovery as complete by calling finishRecovery
5. Emits: RecoveryFinished

Cancelling Recovery

A pending recovery can be discarded using discardRecovery, which:

1. Removes the recovery request from storage.
2. Emits a RecoveryDiscarded event for traceability.

More account recovery options are coming soon.