Networking Design Self-Review and Follow-Ups

Status: Self-reviewed draft
Scope: review results for the split networking design set

Review Method

The original broad networking draft was split by responsibility and reviewed against these checks:

• one authoritative production MVP sync model
• no hidden trusted server role
• clear service separation
• clear transport/application identity boundary
• explicit membership and revocation semantics
• explicit anti-rollback persistence
• concrete online MVP defaults
• mailbox and storage phased after online sync
• no public unauthenticated stateful services in MVP defaults
• no placeholder requirements

Resolved Findings

Opaque snapshots competed with v2 sync

Resolution:

The production MVP is v2 record/resource sync. Opaque full-KDBX snapshots are now a future checkpoint, recovery, or availability layer. They must not bypass v2 tombstone, resource, membership, or anti-rollback rules.

Relay, mailbox, and storage responsibilities were too easy to blend

Resolution:

The split docs keep a hard rule:

Relay != Mailbox != Object Storage

Each role has explicit allowed and forbidden state.

Transport identity could be confused with vault authority

Resolution:

The identity design separates libp2p Peer ID from application device signing keys. Online sessions require a vault-level transcript signature by a current member key.

Mailbox and object storage scope was too large for MVP

Resolution:

Both are phased after online sync, membership, anti-rollback, and v2 compatibility hardening. Mailbox stores hints only. Object storage stores immutable encrypted objects only.

Public DHT, gossipsub, and proof-of-work defaults were risky

Resolution:

They are excluded from MVP defaults. The MVP uses local discovery, cached addresses, scoped rendezvous, direct dial, hole punching, and relay fallback.

Rollback behavior after local state loss was unclear

Resolution:

Lost anti-rollback state is now a recovery event. The client must restore trusted state, re-pair from a trusted device, or require user confirmation before accepting a new baseline.

Phase 1 depended on Phase 2 membership semantics

Resolution:

The online transport MVP now defines a phase-1 minimum signed membership artifact and an in-session membership bootstrap sequence. Phase 2 still owns the full membership lifecycle, revocation UX, epoch rotation UX, and lost-state recovery flow.

Merge semantics could reject valid concurrent edits

Resolution:

The revision protocol now distinguishes same-author equal-event mismatches from cross-author concurrent equal-version edits. Same record_id, author_device, author_sequence, version, and state with different content is corruption or equivocation. Different valid authors at the same record version route to conflict handling unless one candidate causally descends from the other.

Tombstone compaction was not operationalized

Resolution:

Tombstone retention now uses verifiable causal coverage. A tombstone can be compacted only when every accepted live head descends from the tombstone or from a later revision that carries the deletion forward. Signed member acknowledgements may help but are not required; time alone is not enough.

Device key replacement was missing

Resolution:

The identity design now defines signed device key replacement events, transition proofs when the old key is available, and acceptance rules that prevent old key bindings from reappearing after the replacement epoch.

Repo-secret rotation was implicit

Resolution:

The identity design now states that repo secrets are epoch-bound namespace material and should rotate on hard revocation, suspected repo-secret compromise, or future-alias unlinkability events.

Offline-service defaults were ranges instead of rollout profiles

Resolution:

Mailbox and object storage now define first post-MVP profile IDs with concrete baseline limits:

• mailbox-capability-v1
• object-storage-capability-v1

Subagent Questions

The following questions were delegated for focused review:

1. How should opaque KDBX snapshot sync relate to v2 record/resource sync?
2. What minimum identity, membership, key, revocation, and rollback rules are required before implementation?
3. Which mailbox, storage, discovery, proof-of-work, DHT/gossipsub, and relay defaults belong in the production MVP?
4. Do the split docs have security/protocol contradictions after the first revision?
5. Do the split docs have product-scope or roadmap contradictions after the first revision?

Subagent Results

v2 vs opaque snapshot boundary

Finding:

One review recommended keeping v2 records/resources as the local merge engine while exposing only opaque encrypted snapshot chunks at the network boundary.

Decision:

Do not use snapshot-only networking for the production MVP. Keep v2 record/resource sync as the network protocol and move opaque snapshots to a later checkpoint, recovery, or availability layer.

Rationale:

• It aligns with the current v2-only production direction.
• It directly exercises tombstones, resource transfer, attachments, custom icons, and typed fields across peers.
• It avoids dual authoritative sync paths during the MVP.
• It keeps large full-snapshot transfer and snapshot conflict UX out of the critical path.

Future follow-up:

If snapshot networking is later added, choose hard cutover or dual-stack migration before implementation.

Identity, membership, keys, revocation, and rollback

Finding:

The split design must define these rules before implementation, not leave them as recommendations:

• high-entropy repo secret and repo commitment
• signed versioned membership document
• stable device signing and encryption keys
• strict member and revoked-writer verification
• monotonic membership epochs
• key rotation on revocation
• persistent anti-rollback floors
• merge instead of last-write-wins

Decision:

Incorporated in Identity, Membership, and Keys. The default authority is single-admin-v1; the implemented opt-in recovery-admin-v2 policy adds one constrained recovery Writer while retaining exactly one primary Admin. Threshold and all-member consensus policies remain future work.

Remaining follow-up:

Concrete AEAD, KDF, and key wrapping primitives still need to be selected in the implementation plan.

MVP service defaults

Finding:

Relay should be in the MVP default. Lightweight discovery should be in. Mailbox, object storage, public DHT, public gossipsub, and proof-of-work mailbox should be out of the MVP default.

Decision:

Incorporated in Online Transport MVP, Offline Services, and Product Modes and Roadmap.

Remaining follow-up:

No production MVP blocker remains. Public gossipsub and proof-of-work mailbox are future optional-mode decisions.

Second-pass product and roadmap review

Finding:

The MVP boundary was coherent, but Phase 1 needed a minimum membership contract and session bootstrap details so unauthorized fetch rejection could be implemented without depending on Phase 2. Optional offline modes also needed concrete default profiles rather than only limit ranges.

Decision:

Incorporated in Online Transport MVP, Offline Services, and Product Modes and Roadmap.

Second-pass security and protocol review

Finding:

No critical or high-confidence blocker remained, but the review found medium correctness gaps in merge version scope, symmetric session membership binding, tombstone compaction, key replacement, and repo-secret rotation.

Decision:

Incorporated in Online Transport MVP, Identity, Membership, and Keys, and Revision Protocol and Merge.

Current Follow-Up Items

Implemented Session And Resource Cryptography

Protocol 6 now selects HKDF-SHA256 and HMAC-SHA256 for application session authorization. The key schedule binds the complete signed handshake transcript and current epoch secret, uses distinct confirmation/request/response labels, and enforces exact request sequences with authenticated responses and NACKs. Stored resources now use a distinct HKDF-SHA256 context and versioned XChaCha20-Poly1305 envelopes bound to the vault, epoch, resource, and chunk descriptor. Legacy password-derived and retained older-epoch chunks migrate on verified writes. This resolves both implemented local contexts in the concrete-primitives follow-up. The shared epoch-secret design does not provide retrospective forward secrecy if an epoch secret and captured transcript or resource envelope are both compromised.

Implemented Pairing UX

The default product flow now transports the signed invite, join request, and acceptance through a 10-minute, one-use encrypted HTTP rendezvous session. The owner CLI renders a terminal QR code when space permits and always prints the same canonical LPM1-... capability for manual delivery. The joining CLI accepts that code through a hidden prompt or private --code-file. Once the joining device keys are known, both devices print a separate confirmation code that must be compared out of band before owner approval.

The rendezvous is blind to package plaintext and is not a membership authority. https://pair.latticepm.net is the client default; --server selects another HTTPS endpoint, including an operator-hosted loopback backend behind TLS. The original signed-file exchange remains an explicit fallback. Local-network pairing discovery remains optional future UX, not a blocker.

Implemented Offline Cryptographic Primitives

Session primitives are fixed as HKDF-SHA256 and HMAC-SHA256. Stored-resource and object-storage envelopes use separately labeled HKDF-SHA256 contexts and XChaCha20-Poly1305. Mailbox hints use ephemeral X25519 recipient encryption, HKDF-SHA256, and XChaCha20-Poly1305. Every envelope authenticates its protocol version and full vault, epoch, recipient/repository, object, and descriptor context before plaintext is accepted.

Minimum constraints:

• AEAD encryption for sync objects and mailbox envelopes
• signed manifests for every accepted revision
• explicit domain separation labels for every derived context
• no derivation from KeePass master password
• per-device key wrapping for epoch material

Conflict UX

The protocol does not use wall-clock last-write-wins. Concurrent entry state is represented deterministically through KeePass history or a conflict copy, while non-entry conflicts are retained in the encrypted conflict log. Encrypted offline bundles carry the signed historical records needed to reconstruct the same losing state on another device. A richer interactive conflict browser and explicit resolution workflow remain future product UX.

Tombstone Acknowledgement Proofs

The protocol no longer depends on acknowledgements for safe compaction, but signed acknowledgements may later reduce tombstone retention. If added, the acknowledgement format should name the member device, tombstone revision, and descendant head that covers the tombstone.

Snapshot Networking Migration

Snapshot networking is not part of the production MVP. If it is added later, choose one policy before implementation:

• hard cutover to snapshot networking with legacy v2-network peers blocked
• dual-stack compatibility until every paired device upgrades

The choice affects protocol negotiation, support burden, and recovery UX.

Completion Criteria

This design split is complete when:

• all subagent review results have been considered
• any valid subagent finding has been incorporated
• unresolved questions are captured in this document
• markdown links are valid
• placeholder scans find no unfinished markers
• the final review finds no known contradictions or unresolved blockers in the split docs