Skip to content
DXOS LogotypeDXOS LogotypeDXOS Documentation

Recovery and credentials

A recovery credential is a key outside every device that the identity has admitted as one of its members. It can admit a new device, so the user gets their identity back after losing all of them.

Model

Section titled “Model”

Recovery kinds.

Kind The key lives
recovery-code In a phrase of words HALO generates and the user writes down
passkey In the platform’s passkey store, behind the user’s biometrics or PIN
oauth Behind an account with an OAuth provider

The recovery key is a member. Creating a recovery credential is a delegation, like admitting a device: the identity’s group gains a member whose key the user holds outside every device. Revoking the credential removes that member.

The recovery challenge. Recovery runs through EDGE. The new device asks for a challenge with Identity.requestRecoveryChallenge, signs it with the recovery key, and sends the signature back with Identity.recover. For a recovery code, recover derives the key from the phrase and does the signing itself. EDGE checks the signature against the identity’s recovery credentials and admits the new device.

What comes back. The recovered device has the same identity and DID. It is a new device of that identity, so it syncs the personal space and the identity’s other spaces from EDGE and from any other members.

Credentials. An identity holds signed credentials: the statements that admit its devices, its recovery credentials, and service access credentials. Identity.credentials is a stream of them, with the current set first. A recovery credential carries its kind, its label, its lookup key and whether it has been revoked. grantServiceAccess writes a credential that lets the identity use an EDGE or Hub service, and createApiToken mints a token for a CLI or a server to act as the identity.

Behavior

Section titled “Behavior”
  • Creating a recovery code shows the phrase once. HALO keeps only the public half.
  • A revoked recovery credential no longer admits devices.
  • HALO refuses to revoke the last recovery credential that is still active. Make the new one first.
  • Recovery needs a network connection to EDGE.

Limits

Section titled “Limits”
  • A lost recovery code, with every device lost too, means the identity is gone. There is no reset.
  • Anyone who holds a recovery code can take over the identity. Revoke a code you think has leaked, then make a new one.