> ## Documentation Index
> Fetch the complete documentation index at: https://docs.socket.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# SocketFi Account Recovery for Lost Passkeys and Devices

> Guide to SocketFi account recovery — what is preserved, the 6-step recovery flow, identity verification requirements, and UX best practices.

Account recovery lets a user regain access to their wallet after they can no longer use their original passkey. The most common reasons are a lost or damaged phone, a passkey deleted during a device reset, or a failed migration to a new authenticator. Recovery does not create a new wallet and does not move assets — it replaces the authentication credential so the user can sign in again with a new passkey while accessing the exact same wallet they had before.

<Warning>
  Recovery is a high-privilege operation. A successful recovery permanently replaces the credential that controls a wallet. You **must** implement robust identity verification before authorising a recovery request. Weak verification is the primary attack surface for account takeover.
</Warning>

## What recovery is and is not

SocketFi recovery replaces the **authentication credential**, not the wallet. Think of it as re-issuing a lost key to an existing lock — the lock (wallet), its contents (assets), and its address on the blockchain stay exactly the same.

| What changes                        | What is preserved           |
| ----------------------------------- | --------------------------- |
| Authentication credential (passkey) | Wallet address              |
|                                     | All token balances and NFTs |
|                                     | Full transaction history    |
|                                     | Active DeFi positions       |
|                                     | Governance votes            |
|                                     | Wallet policies             |

After recovery completes, the user authenticates normally with their new passkey and lands in the same wallet as before.

## When users need recovery

Recovery is the right flow when the user **cannot access their current passkey**:

* Lost, stolen, or destroyed phone
* Passkey deleted during a factory reset or OS reinstall
* Failed device migration (old device disposed before credential was transferred)
* Authenticator app uninstalled or reset

If the user **still has access** to their current passkey but wants to move to a new device, use [Credential Rotation](/guides/credential-rotation) instead. Rotation is simpler, faster, and does not require identity verification because the user can prove ownership directly with their existing credential.

## The recovery flow

<Steps>
  ### User initiates recovery

  The user arrives at your app without a valid session — either they cannot authenticate, or their device no longer has the passkey enrolled. Your login screen should surface a clearly labelled **"Can't sign in? Recover your account"** link.

  Display a brief explanation of what recovery does before the user proceeds:

  ```text theme={null}
  Your wallet, assets, and transaction history are safe.
  Recovery replaces your passkey so you can sign in again
  on this device. Your wallet address will not change.
  ```

  Collect the minimum information needed to identify the account — typically the wallet address or a verified email address associated with the account.

  ### Verify the user's identity

  This is the most critical step. SocketFi requires identity verification before issuing a recovery authorization. The specific method is up to you and depends on your security requirements and regulatory context. Common approaches include:

  * Email one-time code sent to the address on file
  * SMS OTP to the registered phone number
  * Knowledge-based verification (security questions set during onboarding)
  * Government ID verification via a KYC provider
  * Video call with a support agent for high-value accounts

  Your backend must perform this verification and only proceed to the next step after it succeeds.

  <Warning>
    Do not skip or weaken identity verification in development builds. A test environment with bypassed verification creates a security habit that can slip into production. Build the full verification flow from the start.
  </Warning>

  Show the user clear progress so they understand where they are in the process:

  ```text theme={null}
  Step 1 of 3: Verify your identity ← (current)
  Step 2 of 3: Create a new passkey
  Step 3 of 3: Restore wallet access
  ```

  ### Generate a recovery authorization

  After your backend confirms the user's identity, request a recovery authorization from SocketFi. This authorization is a time-limited token that permits exactly one credential replacement for the specified wallet.

  ```typescript src/server/routes/recovery.ts theme={null}
  import { Router } from "express";
  import { createRecoveryAuthorization } from "@socketfi/server";
  import { verifyUserIdentity } from "../services/identity";

  const router = Router();

  router.post("/recovery/authorize", async (req, res) => {
    const { walletAddress, verificationCode, verificationMethod } = req.body;

    // Step 1: verify the user's identity on your backend
    const verified = await verifyUserIdentity({
      walletAddress,
      code: verificationCode,
      method: verificationMethod,
    });

    if (!verified) {
      return res.status(403).json({
        error: "Identity verification failed. Please check your code and try again.",
      });
    }

    // Step 2: create a time-limited recovery authorization
    const authorization = await createRecoveryAuthorization({ walletAddress });

    // Return only the token — do not expose internal details
    res.json({ recoveryToken: authorization.token });
  });

  export default router;
  ```

  <Note>
    Recovery authorization tokens are short-lived. Instruct users to complete the next steps promptly after receiving the authorization.
  </Note>

  ### Create a new passkey on the new device

  With the recovery token in hand, the user enrolls a fresh passkey on their current device. The SocketFi SDK handles the WebAuthn / platform authenticator interaction:

  ```typescript src/services/recovery.ts theme={null}
  import { socketfi } from "../socketfi/client";

  export async function initiateRecovery(recoveryToken: string): Promise<void> {
    await socketfi.recoverAccount({ token: recoveryToken });
    // The SDK registers a new passkey and submits the recovery transaction
  }
  ```

  Walk the user through the device prompt with clear copy:

  ```text theme={null}
  Your device will ask you to create a new passkey.
  This is how you'll sign in going forward.
  When prompted, use Face ID, Touch ID, or your PIN.
  ```

  ### SDK executes the on-chain credential replacement

  The SocketFi SDK submits a recovery transaction to the Stellar network on the user's behalf. The smart wallet contract verifies:

  1. The recovery authorization is valid and unexpired
  2. The new passkey credential proof is genuine
  3. The wallet policies permit the credential change

  All three checks must pass before the credential is replaced. If any check fails, the transaction is rejected and the user must restart from Step 2.

  Your UI should display an in-progress state during this step:

  ```typescript src/components/RecoveryProgress.tsx theme={null}
  type RecoveryStep = "verifying" | "creating-passkey" | "updating-wallet" | "complete" | "failed";

  export function RecoveryProgress({ step }: { step: RecoveryStep }) {
    const steps = [
      { id: "verifying", label: "Verifying your identity" },
      { id: "creating-passkey", label: "Creating new passkey" },
      { id: "updating-wallet", label: "Updating wallet access" },
      { id: "complete", label: "Access restored" },
    ];

    return (
      <ol>
        {steps.map((s) => (
          <li key={s.id} aria-current={step === s.id ? "step" : undefined}>
            {s.label}
            {step === s.id && " ← in progress"}
            {steps.findIndex((x) => x.id === step) > steps.findIndex((x) => x.id === s.id) && " ✓"}
          </li>
        ))}
      </ol>
    );
  }
  ```

  ### User authenticates with the new passkey

  Once the on-chain recovery transaction is confirmed, the user can sign in normally using their new passkey. Their wallet address, assets, history, and DeFi positions are all intact.

  ```typescript src/screens/RecoverySuccessScreen.tsx theme={null}
  import { useAuth } from "../auth/context";

  export function RecoverySuccessScreen() {
    const { login } = useAuth();

    return (
      <div>
        <h2>Your account has been recovered</h2>
        <p>
          Your wallet and all your assets are exactly as you left them.
          Sign in now to continue.
        </p>
        <button onClick={login}>Sign In with New Passkey</button>
      </div>
    );
  }
  ```
</Steps>

## Recovery security requirements

Before shipping your recovery flow to production, confirm:

* **Identity verification is mandatory** — there is no path through recovery that bypasses it
* **Recovery tokens are server-side only** — never expose the raw token in a URL or client-side log
* **Rate limiting is in place** — limit recovery attempts per wallet per time window to deter brute-force attacks
* **All recovery events are logged** — timestamp, wallet, outcome, IP, and verification method
* **Users are notified** — send a push notification or email when a recovery is initiated, approved, and completed

## UX recommendations

**Surface recovery prominently but not obtrusively.** Place a "Can't sign in?" link on your login screen, but don't make it more prominent than the normal sign-in button. You want it easy to find in a moment of stress, not so visible that it encourages casual misuse.

**Explain what recovery does before it starts.** Many users worry they will lose their assets. A single sentence — "Your wallet and assets are safe; we're just replacing your sign-in credential" — dramatically reduces support requests.

**Use step indicators.** Recovery takes multiple steps across multiple screens. Show a numbered progress indicator (e.g. "Step 2 of 3") so users know they are making progress and have not accidentally reached a dead end.

**Keep error messages actionable.** "Identity verification failed" is unhelpful. "The code you entered doesn't match. Please check your email and try again, or contact support." is clear and gives the user a next action.

**Test the complete flow before launch.** Recovery is rarely triggered, which means it is rarely tested. Walk through the entire flow on a staging environment before going live, and schedule a periodic test drill to catch regressions.

## Monitoring recovery events

Log and monitor every stage of the recovery lifecycle:

```typescript src/server/services/recoveryAudit.ts theme={null}
type RecoveryEvent = {
  timestamp: number;
  walletAddress: string;
  stage: "initiated" | "identity-verified" | "authorized" | "completed" | "failed";
  outcome: "success" | "failure";
  reason?: string;
  ipAddress?: string;
};

export async function logRecoveryEvent(event: RecoveryEvent) {
  // Write to your audit log / SIEM
  await auditLog.write(event);

  // Alert on unexpected patterns
  if (event.outcome === "failure") {
    await alerting.increment(`recovery.failures.${event.walletAddress}`);
  }
}
```

Repeated recovery failures for the same wallet — especially if they originate from different IP addresses — may indicate an account takeover attempt. Set up alerts for this pattern and have a response plan ready.