Passkey recovery

A passkey can be an identity’s recovery credential. The user then gets their identity back on a new device with a fingerprint or a PIN, with no recovery code to keep. @dxos/halo writes and checks the credential; the WebAuthn ceremony that creates and uses the passkey runs in the app, because only the app knows its site and its UI.

This guide uses the browser’s WebAuthn API. Recovery goes through EDGE, so the client needs a network connection.

Caution

Recovery needs a DXOS account. EDGE stores recovery credentials only for identities linked to an account, and for now you can create an account only through Composer.

Register a passkey

navigator.credentials.create makes the passkey. Put a random lookup key in its user handle: the browser returns the handle when the passkey signs, and HALO finds the credential by it. Then pass the passkey’s public key, the lookup key and the algorithm to Identity.createRecoveryCredential as externalKey. The identity’s group gains the passkey as a member.

import * as Effect from 'effect/Effect';
import * as Option from 'effect/Option';
import { Identity } from '@dxos/halo';
import { PublicKey } from '@dxos/keys';

const registerPasskey = Effect.gen(function* () {
  const identity = Option.getOrThrow(yield* Identity.getSnapshot);

  // The lookup key names the passkey. It goes in the user handle, so the
  // assertion returns it.
  const lookupKey = PublicKey.random();

  const credential = yield* Effect.promise(() =>
    navigator.credentials.create({
      publicKey: {
        challenge: new Uint8Array(32),
        rp: { id: rpId, name: 'Contact book' },
        user: {
          id: new Uint8Array(lookupKey.asUint8Array()),
          name: identity.did,
          displayName: identity.displayName ?? '',
        },
        pubKeyCredParams: [
          { type: 'public-key', alg: -8 }, // Ed25519
          { type: 'public-key', alg: -7 }, // ES256
        ],
        authenticatorSelection: { residentKey: 'required' },
      },
    }),
  );
  if (
    !(credential instanceof PublicKeyCredential) ||
    !(credential.response instanceof AuthenticatorAttestationResponse)
  ) {
    return yield* Effect.die('No passkey was created.');
  }

  const response = credential.response;
  const publicKey = response.getPublicKey();
  if (!publicKey) {
    return yield* Effect.die('The authenticator returned no public key.');
  }

  yield* Identity.createRecoveryCredential({
    externalKey: {
      recoveryKey: PublicKey.from(new Uint8Array(publicKey)).toHex(),
      lookupKey: lookupKey.toHex(),
      algorithm: response.getPublicKeyAlgorithm() === -7 ? 'ES256' : 'ED25519',
      label: 'Passkey',
      kind: 'passkey',
    },
  });
});

The passkey must be a resident key (residentKey: 'required'), so a new device can find it without being told which one to use.

Recover on a new device

On the new device, before any identity exists:

1. Identity.requestRecoveryChallenge gets a challenge from EDGE for this device.
2. navigator.credentials.get asks the user to sign it with the passkey.
3. Identity.recover sends the signature, the challenge and the lookup key from the user handle. EDGE checks them against the identity’s recovery credentials and admits the device.

import * as Effect from 'effect/Effect';
import { Identity } from '@dxos/halo';
import { PublicKey } from '@dxos/keys';

const fromBase64 = (value: string) =>
  Uint8Array.from(atob(value), (char) => char.charCodeAt(0));

const recoverWithPasskey = Effect.gen(function* () {
  const challenge = yield* Identity.requestRecoveryChallenge;

  const credential = yield* Effect.promise(() =>
    navigator.credentials.get({
      publicKey: {
        challenge: fromBase64(challenge.challenge),
        rpId,
        userVerification: 'required',
      },
    }),
  );
  if (
    !(credential instanceof PublicKeyCredential) ||
    !(credential.response instanceof AuthenticatorAssertionResponse)
  ) {
    return yield* Effect.die('No passkey assertion was returned.');
  }

  const response = credential.response;
  // The user handle carries the lookup key the passkey was registered with.
  const userHandle = response.userHandle;
  if (!userHandle) {
    return yield* Effect.die('The passkey has no user handle.');
  }

  return yield* Identity.recover({
    passkey: {
      challenge,
      lookupKey: PublicKey.from(new Uint8Array(userHandle)).toHex(),
      signature: new Uint8Array(response.signature),
      clientDataJson: new Uint8Array(response.clientDataJSON),
      authenticatorData: new Uint8Array(response.authenticatorData),
    },
  });
});

recover returns the identity. The device then syncs the identity’s spaces, as any new device does.

Revoke a passkey

Identity.credentials lists the recovery credentials, each with its kind and lookup key. revokeRecoveryCredential removes one. HALO refuses to revoke the last active recovery credential, so register the replacement first.

import * as Effect from 'effect/Effect';
import * as Stream from 'effect/Stream';
import { Identity } from '@dxos/halo';

const revokePasskeys = Effect.gen(function* () {
  const [credentials] = yield* Identity.credentials.pipe(
    Stream.take(1),
    Stream.runCollect,
  );
  for (const { recovery } of credentials) {
    if (
      recovery?.kind === 'passkey' &&
      !recovery.revoked &&
      recovery.lookupKey
    ) {
      yield* Identity.revokeRecoveryCredential(recovery.lookupKey);
    }
  }
});

Related

• Recovery and credentials
• Recover an identity, which uses a recovery code.
• Identity