Networking Principles and Scope
Status: Self-reviewed draft
Audience: protocol, product security, implementation, and operations reviewers
Applies to: all Lattice PM network sync modes
Problem
Section titled “Problem”The local-network sync model is not enough for normal multi-device use. Users need devices to synchronize when they are on different networks, behind NATs, temporarily offline, or dependent on optional self-hosted or hosted infrastructure.
The design must support that without turning any server into a trusted vault authority.
Core Constraint
Section titled “Core Constraint”No protocol can prevent a relay, mailbox, discovery node, or storage server from saving bytes it receives.
The system therefore assumes:
Any server that sees ciphertext may retain it forever.The design goal is not to make servers forget. The design goal is to make retained bytes useless and make incorrect server behavior detectable by clients.
- Sync paired devices across different networks.
- Prefer direct peer-to-peer paths and use relays only as fallback.
- Keep basic sync functional without a mailbox or durable storage service.
- Allow optional mailbox and object storage services for better offline catch-up.
- Treat infrastructure as untrusted for confidentiality and correctness.
- Keep application authority on paired devices.
- Detect forged revisions, stale heads, rollback attempts, and membership rollback.
- Bound relay, mailbox, and storage abuse with quotas and rate limits.
- Support self-hosted, community-hosted, and hosted deployment models.
Non-Goals
Section titled “Non-Goals”- Anonymous networking.
- Full metadata hiding.
- Preventing denial of service, deletion, or withholding by a malicious server.
- Guaranteed offline catch-up when no reachable peer or storage provider has the needed data.
- Public unauthenticated durable storage.
- Making relays responsible for delivery acknowledgement or canonical state.
- Replacing KDBX encryption.
- Making every future sync mode part of the production MVP.
Service Roles
Section titled “Service Roles”User Device
Section titled “User Device”A user device is an authoritative participant in a vault sync group.
Responsibilities:
- Watch or manage the local vault.
- Produce v2 record/resource changes from local KDBX state.
- Sign revision heads and protocol messages with an application device key.
- Verify remote signatures, manifests, content hashes, epochs, and membership.
- Persist anti-rollback state.
- Fetch and serve encrypted protocol resources to authorized paired devices.
- Detect conflicts and drive local merge workflows.
A relay is a stateless libp2p transport helper.
Allowed:
- Accept bounded relay reservations.
- Forward encrypted libp2p streams.
- Enforce connection, bandwidth, and lifetime limits.
Forbidden:
- Store mailbox envelopes.
- Store vault objects.
- Store canonical heads.
- Perform delivery acknowledgement.
- Enforce vault membership at the application layer.
Discovery Node
Section titled “Discovery Node”A discovery node helps paired devices find network addresses.
Allowed mechanisms:
- local mDNS
- cached peer addresses
- private or scoped rendezvous
- bootstrap peers
- peer exchange between already paired devices
Public DHT/provider records and gossipsub announcements are not MVP defaults because they increase metadata leakage and abuse surface.
Mailbox Server
Section titled “Mailbox Server”A mailbox server stores short-lived encrypted hints for recipient devices.
It may store:
- blinded mailbox identifiers
- encrypted envelopes
- expiry times
- admission and quota metadata
It must not store:
- KDBX snapshots
- attachment-sized payloads
- durable revision history
- canonical latest-head state
Object Storage Server
Section titled “Object Storage Server”An object storage server stores durable immutable encrypted objects.
It may store:
- encrypted resource chunks
- encrypted full-snapshot objects in a future snapshot mode
- signed manifests or pointers as advisory data
- retention and quota metadata
It must not be trusted to tell the truth about latest state. Clients verify all fetched data.
Service Separation
Section titled “Service Separation”The protocol separates service roles even when one physical process provides several services.
Relay != Mailbox != Object Storage| Service | State | Stores vault data? | MVP default | Main abuse risk |
|---|---|---|---|---|
| Relay | temporary | no | enabled as fallback | bandwidth exhaustion |
| Discovery | temporary or routing state | no | local/cached/scoped only | metadata leakage |
| Mailbox | short-lived hints | no full vaults | disabled | queue spam |
| Object storage | durable encrypted objects | yes, encrypted only | disabled | storage exhaustion |
| Peer fetch | peer-local | yes, encrypted protocol data | enabled | unauthorized fetch attempts |
Availability Rule
Section titled “Availability Rule”Serverless sync cannot create availability from nothing.
If no online peer, helper peer, mailbox, or object store can provide evidence of a newer revision, another device cannot fetch it.
The baseline guarantee is:
Devices converge once at least one authorized peer or storage provider holding the needed revision becomes reachable.Mailbox and object storage improve availability but do not change the trust model.
Security Posture
Section titled “Security Posture”Servers may:
- retain ciphertext forever
- delete data
- withhold data
- serve stale data
- observe timing, size, address, and provider metadata
Servers must not be able to:
- decrypt vault contents
- forge accepted revisions
- modify accepted revisions undetected
- silently roll a device back
- turn relay reservations into durable storage
- consume unbounded resources
The rest of the design documents define the rules that make those guarantees concrete.