The device model
SyncBins is single-user, but multi-device. A device is any browser, CLI, or agent that has completed pairing and holds a session token plus a device keypair.
What a device is
Section titled “What a device is”Each device has:
| Field | Stored where | Purpose |
|---|---|---|
| Device ID | Server (ULID) | Identity in API and wrapped-key bundles |
| Name + glyph | Server (plaintext) | Settings UI, feed attribution |
| Public key | Server (base64) | Other devices wrap item keys to it |
| Private key | Client only, sealed to master key | Unwrap item keys |
| Session token | Client (localStorage) | Authorization: Bearer … on REST/WS |
| Master key | Client memory while unlocked | Pairing/recovery; not sent to server |
There is no shared “account password.” Access is device session + crypto keys, with the 12-word recovery phrase as the ultimate backup.
Pairing = trusting a new keyholder
Section titled “Pairing = trusting a new keyholder”Pairing gives a new device:
- A session token (30-day TTL on the server; no auto-renewal yet).
- The master key, wrapped to that device’s fresh Curve25519 public key.
- A path to historical items via background re-wrap from devices that can still decrypt them.
The QR (or six-word) code is the out-of-band secret that lets the new device prove it isn’t an impostor on the network, and a 6-digit verification code shown on both devices — which you approve on the existing one — binds the master-key transfer to the device you actually scanned. See Pairing more devices for the UI flow and How encryption works for the message sequence.
Revocation = evicting a keyholder
Section titled “Revocation = evicting a keyholder”Settings → Devices → Revoke on any other device:
- Invalidates that device’s bearer token immediately.
- Closes its WebSocket connections.
- Stops including its public key in new item wrapped-key bundles.
- Triggers a pubkey refresh on remaining devices so they re-wrap without the revoked key.
Revocation is forward-looking. Anything the revoked device already decrypted stays on that machine until you wipe it locally.
Recovery phrase vs device loss
Section titled “Recovery phrase vs device loss”| Situation | Recovery phrase needed? | Pair code needed? |
|---|---|---|
| Lost one device, others remain | No | No — revoke the lost device |
| Cleared browser, others remain | No | Yes — six words from Settings → Devices |
| All devices gone, phrase saved | Yes — restore path | No |
| All devices gone, phrase lost | Unrecoverable | — |
The phrase derives the master key. Devices are disposable entry points; the phrase is not.
MCP counts as a device
Section titled “MCP counts as a device”@syncbins/mcp pairs through the same handshake and appears in Settings → Devices like a laptop. Revoke it when you stop trusting an agent process.
Session lifetime
Section titled “Session lifetime”Bearer tokens expire after 30 days (SESSION_TTL_MS). There is no silent refresh yet — if a device goes idle past expiry, re-pair or restore with the recovery phrase.