Recover an identity

By the end of this page Alice has a recovery code, and with it gets her name, spaces and contacts back on a new laptop.

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.

Background

If every device is lost, the identity is lost with them, unless it has a recovery credential: a key kept outside every device. A recovery code is one such key, written as twelve words. Making it adds the key to the identity’s group as a member, the same way a device is added, so the key can admit a new device later.

Recovery goes through EDGE. The new device asks EDGE for a challenge, signs it with the key derived from the words, and EDGE checks the signature against the identity’s recovery credentials before it admits the device. The new device is a new member of the same identity, with the same DID, and syncs its spaces from EDGE and from anyone online.

HALO shows a recovery code once and keeps only its public half, and it will not revoke the last code you have: make the new one first. A passkey works the same way; see Passkey recovery.

Steps

1. Make a recovery code. Identity.createRecoveryCredential makes the key, adds it to the identity, and returns the words. Make a recovery code on the Recovery tab calls this.

   src/app/Recovery.tsx

   import * as Effect from 'effect/Effect';
   import React, { useState } from 'react';
   
   import { Identity } from '@dxos/halo';
   import { useCredentials, useHaloServices } from '@dxos/halo-react';
   
   import { Copyable } from './ui.tsx';
   
   /** Your recovery codes: make one, see the ones that work, and revoke one. */
   export const Recovery = () => {
     const services = useHaloServices();
     /** The recovery credentials that still work, re-rendering on each change. */
     const codes = useCredentials().flatMap(({ recovery, issuanceDate }) =>
       recovery && !recovery.revoked ? [{ ...recovery, issuanceDate }] : [],
     );
     const [created, setCreated] = useState<string>();
     const [error, setError] = useState<string>();
   
     /** Makes a recovery code, and shows it. HALO returns it only this once. */
     const handleCreate = () =>
       Effect.gen(function* () {
         const { recoveryCode } = yield* Identity.createRecoveryCredential();
         return recoveryCode;
       })
         .pipe(Effect.provide(services), Effect.runPromise)
         .then((code) => {
           setError(undefined);
           setCreated(code);
         });
   
   

2. List your codes. useCredentials returns the identity’s credentials and re-renders when one is written. It follows Identity.credentials. A recovery credential carries its kind, a label, the date it was made, a lookup key and whether it was revoked. The Recovery tab lists the ones still active.

   src/app/Recovery.tsx

   import { useCredentials, useHaloServices } from '@dxos/halo-react';
   
   import { Copyable } from './ui.tsx';
   
   /** Your recovery codes: make one, see the ones that work, and revoke one. */
   export const Recovery = () => {
     const services = useHaloServices();
     /** The recovery credentials that still work, re-rendering on each change. */
     const codes = useCredentials().flatMap(({ recovery, issuanceDate }) =>
       recovery && !recovery.revoked ? [{ ...recovery, issuanceDate }] : [],
     );
   
   

3. Revoke a code. Identity.revokeRecoveryCredential takes the lookup key. Revoke a code you think someone has seen.

   src/app/Recovery.tsx

   import * as Effect from 'effect/Effect';
   import React, { useState } from 'react';
   
   import { Identity } from '@dxos/halo';
   import { useCredentials, useHaloServices } from '@dxos/halo-react';
   
   import { Copyable } from './ui.tsx';
   
   /** Your recovery codes: make one, see the ones that work, and revoke one. */
   export const Recovery = () => {
     const services = useHaloServices();
     /** The recovery credentials that still work, re-rendering on each change. */
     const codes = useCredentials().flatMap(({ recovery, issuanceDate }) =>
       recovery && !recovery.revoked ? [{ ...recovery, issuanceDate }] : [],
     );
     const [created, setCreated] = useState<string>();
     const [error, setError] = useState<string>();
   
     /** Makes a recovery code, and shows it. HALO returns it only this once. */
     const handleCreate = () =>
       Effect.gen(function* () {
         const { recoveryCode } = yield* Identity.createRecoveryCredential();
         return recoveryCode;
       })
         .pipe(Effect.provide(services), Effect.runPromise)
         .then((code) => {
           setError(undefined);
           setCreated(code);
         });
   
     /** Revokes the recovery credential with `lookupKey`. */
     const handleRevoke = (lookupKey: string) =>
       Identity.revokeRecoveryCredential(lookupKey)
         .pipe(Effect.provide(services), Effect.runPromise)
         .then(
           () => setError(undefined),
           (error) =>
             setError(
               codes.length === 1
                 ? 'HALO will not revoke your last recovery code. Make another one first.'
                 : String(error),
             ),
         );
   
   

4. Recover on a new device. On a device with no identity, Identity.recover takes the words and gets the identity back. Recover with a code calls this.

   src/app/Welcome.tsx

   import * as Effect from 'effect/Effect';
   import React, { useState } from 'react';
   
   import { Identity } from '@dxos/halo';
   import { useHaloServices } from '@dxos/halo-react';
   
   import { type Stage, reached } from '../stage.ts';
   import { Guest } from './Invitations.tsx';
   import { Prompt } from './ui.tsx';
   
   /** The device before it has an identity: start one, join one from another device, or recover one. */
   export const Welcome = ({ stage }: { stage: Stage }) => {
     const services = useHaloServices();
     const [mode, setMode] = useState<'new' | 'device' | 'recover'>('new');
     // Focusing the first field on load would scroll the page to the embed.
     const [picked, setPicked] = useState(false);
     const pick = (next: typeof mode) => {
       setPicked(true);
       setMode(next);
     };
   
     /** Creates the identity, with this device as its first member. */
     const handleStart = (name: string) =>
       Identity.create({ displayName: name }).pipe(
         Effect.provide(services),
         Effect.runPromise,
       );
   
     /** Redeems the invitation `code` from your other device, and returns the flow. */
     const handleJoin = (code: string) =>
       Identity.join(code).pipe(Effect.provide(services), Effect.runPromise);
   
     /** Gets the identity back with `recoveryCode`. */
     const handleRecover = (recoveryCode: string) =>
       Identity.recover({ recoveryCode: recoveryCode.trim() }).pipe(
         Effect.provide(services),
         Effect.runPromise,
       );
   
   

Try it

Open Recovery on Alice’s laptop and make a code. Make a second one, then revoke the first. Try revoking the last one too, and HALO refuses.

Note

The devices on these pages run in your browser with no network, and recovering needs EDGE. To recover, fork the finished app on StackBlitz, which runs on the real network: make a code there, then open the project in a private window, choose Recover with a code and enter the words.

Fork on StackBlitz

What you can do now

You can make and revoke recovery codes, and recover an identity on a new device. That is the whole contact book. From here, Core concepts explains the model behind it, and the API pages cover the rest of @dxos/halo.