diff --git a/.jules/scribe.md b/.jules/scribe.md index 48b090c..441acb0 100644 --- a/.jules/scribe.md +++ b/.jules/scribe.md @@ -12,3 +12,7 @@ **Gap:** The documentation stated the SWIM protocol period was 1000ms (1s), but the implementation uses 5000ms (5s) in both `src/config.zig` and `src/discovery/swim.zig`. **Learning:** The documentation likely reflected an early design decision or standard SWIM defaults, but the implementation settled on a more conservative 5s interval for WAN stability, and docs were not updated. **Prevention:** Add a CI check that grep's `docs/guide/configuration.md` for values that match constants exported in `src/config.zig`. +## 2024-03-22 - AppMessage Documentation Gap +**Gap:** The documentation (docs/concepts/wire-protocol.md) described an AppMessage protocol for end-to-end encrypted application-level messages, while the implementation (src/protocol/messages.zig) does not define it. +**Learning:** Documentation drifted because the initial design likely included an AppMessage protocol which was either not implemented or removed, but docs were not updated. +**Prevention:** Regularly audit messages.zig against documentation to ensure all documented message types are actually defined. diff --git a/docs/concepts/wire-protocol.md b/docs/concepts/wire-protocol.md index 2f7aaec..28009d1 100644 --- a/docs/concepts/wire-protocol.md +++ b/docs/concepts/wire-protocol.md @@ -33,7 +33,6 @@ SWIM messages use a **1-byte type tag**: | `0x41` | OrgAliasAnnounce | Org Trust | Gossip | | `0x42` | OrgCertRevoke | Org Trust | Gossip | | `0x43` | OrgTrustVouch | Org Trust | Gossip | -| `0x50` | AppMessage | App | A → B (relayed) | ## Ping @@ -150,21 +149,6 @@ Propagated via gossip. Org admin vouches for an external standalone node — all Total: **137 bytes**. Signature covers `vouched_pubkey ‖ lamport`. Revocable via OrgCertRevoke. -## AppMessage - -End-to-end encrypted application-level message, relayed through the mesh. - -``` -[0x50][32B dest_pubkey][32B sender_pubkey][12B nonce][N ciphertext][16B tag] -``` - -Minimum size: **93 bytes** (empty payload). Maximum payload: 1024 bytes. - -- **Key derivation**: X25519(sender_private, dest_wg_pubkey) → HKDF("meshguard-app-v1") → symmetric key -- **AD**: sender's Ed25519 public key -- **Routing**: intermediate peers forward the entire packet as-is (encrypted, opaque) to the destination by pubkey lookup -- **Delivery**: when `dest_pubkey` matches our own, the message is decrypted and delivered via callback - ## Endpoint Encoding All IPv4 endpoints are encoded as: