Account recovery

If passkeys are your primary sign-in method, you still need a recovery path for users who lose access to them. Common examples include a new device that was never synced, a lost security key, or a wiped password manager.

Mailbox challenges give you an email-based recovery step: prove control of the mailbox on the account, then issue a short-lived recovery session that lets the user re-enrol passkeys or complete other recovery-only actions.

Caution

Keep account recovery separate from normal login. After the code is verified, begin a short-lived recovery session and guide the user into an account recovery flow. Don’t treat account recovery as a regular login.

Danger

Account recovery acts as a backdoor into an account. The benefits of passkeys are lost if you allow an attacker to bypass passkey authentication. You will need to employ additional controls to mitigate the risk, such as:

• SMS - Notify the user of the account recovery via SMS. Bear in mind that if a device is lost or stolen the attacker may also have access to messages.

• PIN verification - Prompt the user to enter a recovery PIN or passcode.

• Notify a second email - Prompt users to record an additional (unrelated) email e.g. work, friend or family member. During account recovery, send a notification to this second account.

• Reduced permissions - A recovered account should have limited permissions for a period of N days. This allows the account holder to raise concerns.

Start the recovery challenge

backend/recover-account.ts

import { Passlock, isChallengeRateLimitedError } from "@passlock/server";

const passlock = new Passlock({ ... });

// cpatured in a recover account form
const email = "...";

const user = await findUserByEmail(email);
if (!user) {
  throw new Error("Account not found");
}

const result = await passlock.createMailboxChallenge({
  email: user.email,
  userId: user.id,
  purpose: "account-recovery",
  // any pending challenges for this userId will be nuked
  invalidateOthers: true,
});

if (result.success) {
  const { challengeId, secret, message } = result.value.challenge;

  // save this in the user's session or a secure HTTP only cookie
  await savePendingChallenge({
    purpose: "account-recovery"
    challengeId,
    secret,
  });

    await emailCodeToUser({ email, message });
} else if (isChallengeRateLimitedError(result.error)) {
  return showRateLimit(result.error.retryAfterSeconds);
} else {
  throw new Error(result.error.message);
}

Verify the code and start recovery

backend/recover-account.ts

import { Passlock } from "@passlock/server";

const passlock = new Passlock({ ... });

// fetch from the user's session or secure cookie
const pendingChallenge = await loadPendingChallenge({ purpose: "account-recovery" });

const result = await passlock.verifyMailboxChallenge({
  challengeId: pendingChallenge.challengeId,
  secret: pendingChallenge.secret,
  code: form.code, // the user submitted this
});

if (result.success) {
  const { challenge } = result.value;

  // give the user 10 minutes to further verify
  // their identity and create a new passkey
  await createRecoverySession({
    userId: challenge.userId,
    expiresInMinutes: 10,
  });

  return redirectTo("/settings/account/recover");
} else {
  return showVerificationError(result.error);
}