zaygal/zaycomm

Purpose and Entry Surface

Zaycomm is a TypeScript reference implementation of a secure, decentralized, delay-tolerant mesh messaging protocol. It is protocol infrastructure rather than a web application: messages remain end-to-end encrypted while moving across untrusted relays and intermittent transports. No executable entry point is visible in the tree; the public integration surface is likely the exported modules under src/, with package behavior defined by package.json.

Identity and Cryptographic Sessions

Long-lived identity material, device identity operations, and verification live in src/identity/identity.ts and src/crypto/keys.ts. Session establishment and ongoing forward-secret messaging are separated into src/crypto/handshake.ts and src/crypto/ratchet.ts. This boundary is security-critical: endpoints own private keys and ratchet state; relays should only handle opaque envelopes.

Message Construction and Content Types

Application payloads are represented by src/message/message.ts, with file-oriented payload/chunk handling in src/message/file.ts. These feed encrypted session payloads and can support extensible types such as broadcast. src/broadcast/broadcast.ts is the distinct broadcast path, likely applying different dissemination semantics from ordinary destination-directed messages.

Envelope and Fragmentation Boundary

src/envelope/envelope.ts defines the transportable protocol unit: relay-visible routing/control metadata plus a sealed payload for the recipient. src/envelope/fragment.ts splits and reassembles envelopes for constrained links. This is the key boundary between routing/transport behavior and cryptographic confidentiality: relays validate, deduplicate, forward, or queue envelopes without decrypting content.

Routing and Store-Carry-Forward

src/routing/routing.ts selects forwarding behavior across direct, multi-hop, and disconnected contacts. It should use message identifiers, TTL/freshness, relay knowledge, and bounded replication to avoid loops and uncontrolled flooding. When no suitable next hop exists, control passes to src/storage/store.ts, which persists local state and encrypted relay queues until contact, expiry, acknowledgment, or eviction.

Transport Abstraction

src/transport/transport.ts is the pluggable link boundary. Transports discover reachable peers and exchange bounded opaque frames; higher layers should not depend on BLE, Wi-Fi, Internet, radio, or physical-carry specifics. This permits gateway/synchronization behavior without requiring central infrastructure and makes a new transport adapter an additive change rather than a protocol rewrite.

Primary Control Flow and Trust Boundaries

Outbound flow is: construct message (src/message/message.ts) → establish/use crypto session (src/crypto/handshake.ts, src/crypto/ratchet.ts) → seal into envelope (src/envelope/envelope.ts) → fragment if required (src/envelope/fragment.ts) → choose next hop (src/routing/routing.ts) → transmit (src/transport/transport.ts) or queue (src/storage/store.ts). At relay nodes, only envelope, routing, transport, and queued ciphertext are processed. At the destination, fragments are reassembled, the envelope is decrypted/authenticated through session state, and the payload is delivered to message or broadcast handling.

Runtime and External Dependencies

The codebase is Node/TypeScript-oriented, indicated by package.json and package-lock.json; no deployed service, database, browser runtime, or mandatory external infrastructure is present in the repository tree. Internet-connected peers are conceptually optional gateways, not protocol authorities. Shared low-level behavior is centralized in src/util.ts.