Your Identity on Several Devices

One identity, every device the person owns. Added with a code or the recovery phrase; the private data follows by itself; removed from any of them.

From Flowsta Vault 1.6.0 a Flowsta identity is not tied to the device it was made on. The person adds a second Vault, and it becomes that identity as fully as the first: it signs in, approves, signs files and holds the private data. Nothing changes in the wire contract: an app still talks to the Vault on its own device, and a signature from any device is the person's. What changes is described below - first what the person does, then what an app sees.

How a device is added

There are two doors. Both end in the same state.

With a code, when the person has a device with the identity to hand:

1. On the new device, open Flowsta Vault and choose I already have an identity, then Use another device. It shows a code.
2. On a device that already has the identity, open Settings → Devices → Add a device and type the code. The Vault names the new device and asks before adding it.
3. Approve there. The new device starts, writes its own device record, and the private data arrives.

The code is shown on the new device and typed on the one the person already trusts, so the approval is always made on a device that is already theirs. The new device never approves itself.

With the recovery phrase, when no other device is to hand: on the new device choose I already have an identity, then Use my recovery phrase. The Vault looks for the identity's other devices and, when one answers, says so; the private data arrives from them. When none answers (the person lost their only device), the Vault offers Restore from an export file as a quiet link.

An identity made before 1.6.0 holds no handover keys on its first device yet. Adding its first device asks for the recovery phrase once, on the device that has the identity, as the first step of Add a device. That fills in what a new device needs and is not asked again.

What follows the identity

Within a round or two of a device starting (the Vault runs one every minute, a full one every five), it holds:

	Follows the identity
Keys	The identity's keys. Each device also has a key of its own (below).
Private records	Profile, picture, email, and every sealed record, resolved latest-wins.
Connections	Which apps the person has connected and what each may see, as consent. A Disconnect made on any device disconnects the app on every device.
Remembered sites	Sites the person chose to sign in to without being asked again.
App backups	Each device keeps a copy of the backups made on the other devices. An app can read the newest across them (below).
Activity	One feed across the devices, each line marked with the device it happened on.
Signatures	Made on any device, listed on all of them.

What stays per device, on purpose: an app's link (an app is a different install with its own key on each device, so it links again there - the dialog says "You already use this app on another of your devices"), the Vault's own settings, and the backups an app made on that device (the others hold copies).

The first minutes after opening. After a Vault starts, or the person switches identity, the status line reads Holochain - still starting and the devices chip says it is checking. The network's cells take a few minutes to answer on a device whose data has grown; meanwhile the Vault shows what it last knew. It is not stuck. The same is true of a device that has just joined: the Overview says the private data is on its way until it has all arrived.

Who can add devices

Each device has its own key, and the identity has an enrollment key, made from the recovery phrase. With the enrollment key in force, adding a device needs the recovery phrase or the approval of a device the person already has. Nobody who merely holds the identity's key - an old export file, a stolen device with its password - can add one.

• An identity created on 1.6.0 has its enrollment key in force from the start.
• An identity from before 1.6.0 gets one when the person enters the recovery phrase once (Settings → Devices → Who can add devices). Until then, anyone with the Vault password on one of the devices, or an export of it, can add a device - the same strength as a restore was before.
• A key registered after the fact takes effect after 7 days. The delay is a safety valve: someone who merely holds one of the devices cannot make their phrase the key before the person notices.

Removing a device

Settings → Devices → Remove, on any device the person still has. The removed device can no longer sign in or approve as the person, and it stops syncing. The next time it is on, it says it was removed and offers two things: add it back (with a code or the phrase) or erase what it holds. What it already holds stays on it until the person erases it - a removal is not a remote wipe.

The person's other devices are told that a device was added or removed, in Activity and with a system notification.

Locked, still syncing

A locked Vault keeps running its node, so the person's other devices keep receiving its changes and it keeps receiving theirs. The lock screen says Locked - still syncing. Lock and stop syncing stops the node too. Nothing is approved while locked: a request from an app waits for the unlock.

Exports

Export Data (format version 3.0) carries every key this device holds - identity, device and enrollment where it has them - and the copies it keeps of the other devices' app backups, under app_data.other_devices, by device. Data Portability has the shape.

What changes for an app

Nothing in the contract. What an app observes:

• The identity is the same on every device. agent_pub_key, the DID and the Permanent ID are the identity's, wherever the person is. Signatures made under a device's own key resolve to the person: Flowsta's verification and profile endpoints attribute them, and a removed device still attributes the signatures it made while it was one of the person's.
• Your app links on each device. Each install has its own agent key and links there, with its own approval. The link dialog tells the person they already use the app on another of their devices; a Disconnect on any device reaches your app's link on every device within a round, and /link-status on the device says linked: false from then on. Check it on launch and on focus, and drop the stored identity when the answer changes - never keep showing a name the Vault no longer vouches for.
• Scopes follow the identity. What the person allowed your app to see on one device is what it may see on the others.
• Backups can be read across devices. The person's devices each keep copies of what the others backed up. Your app asks for the newest with a label on any device with across: "devices"; without it, nothing changes.

Backups across devices

POST /backup/retrieve takes across: "devices" together with a label (required; 400 label_required without one). The Vault answers the newest backup under that label on any of the person's devices - this one included - and adds from_device: null when it was made here, otherwise an opaque id for the device that made it. The person's device names are not exposed to apps.

GET /backup/list adds other_devices when there are any: for each other device, the labels it holds for your app with created_at and data_size. Your own apps entry is unchanged and still lists only what was made on this device.

With @flowsta/holochain 3.7.0: retrieveFromVault({ clientId, label, across: 'devices' }) returns fromDevice, and listVaultBackups().otherDevices. Older Vaults ignore the option and answer as before.

Which labels to read across devices is your app's decision. The rule of thumb: things that belong to the person - a recovery label with the app's own keys, a document the person expects to find on every device - are read across devices; things that belong to the install - a per-device index, a cache - are not. A write always lands in this device's own slot; "newest wins" is a read-time rule. Replaying a backup into a fresh install, as a per-user-DHT app does on a reinstall, must be switched off when another device already holds the data: it would author every record again as new. The Your Own AI app is the reference for an app that syncs between the person's devices through this.

import { retrieveFromVault, listVaultBackups } from '@flowsta/holochain';

// The newest "recovery" label on any of the person's devices.
const recovery = await retrieveFromVault({ clientId, label: 'recovery', across: 'devices' });
if (recovery) {
  console.log(recovery.fromDevice ?? 'made on this device');
}

// What the other devices hold for this app.
const stats = await listVaultBackups();
for (const other of stats.otherDevices ?? []) {
  console.log(other.device, other.backups.map((b) => b.label));
}

Next steps

• Identity switching - several identities in one Vault
• IPC reference - every route on the local bridge
• @flowsta/holochain - the SDK