ConnectX — Decentralized P2P Mesh Networking Framework

Latest Build - 0.6.3-SNAPSHOT

ConnectX-0.6.3-20260925.215638-1.jar  ·  published 2026-09-25

Add to Your Project

Available via the Anvil Development Maven repository. Snapshots are enabled.

Prefer the JAR directly? See the download button above, or browse every published snapshot build in the repository.

What's Under the Hood

Human-Facing Applications on the Network

CXApps extend ConnectX beyond machine-to-machine messaging to serve users directly. A CXAppServer runs on the data-owning node. Fields annotated with @CXAppField and methods with @CXAppMethod are cached via reflection at registration. A CXAppClient runs on the user's local node and holds an HTML template. Field values travel over CX as signed events and are substituted into the template locally. No raw HTML ever crosses the wire. Field values from remote peers are HTML-escaped before substitution, so a compromised peer cannot inject markup or script.

Four operations are supported over the wire: READ (fetch current field values), WRITE (update a field), INVOKE (call a method), REFRESH (re-render with current permissions). All travel as APP_REQUEST / APP_RESPONSE events through the standard NodeMesh pipeline with full signing and verification at every hop. Field and method access is gated per-permission - REFRESH silently omits fields the caller lacks permission to read.

Official CXApps published by Anvil Development are distributed on the CXApps page.

How ConnectX Differs from Existing Solutions

Most P2P frameworks make a choice: either prioritize anonymity, or prioritize developer ergonomics, or provide raw messaging primitives. ConnectX is built around a different requirement: managed organizational networks where administrators need real governance tooling, cryptographic accountability at every layer, auditable state, and a human-facing application surface, without depending on a central server.

Cryptographic Identity as the Trust Primitive

ConnectX makes cryptographic identity the sole basis for trust at the protocol level. Every message, event, and state transition is signed or encrypted by the originating peer before it touches the wire. This is not defense-in-depth. It is exploit-class elimination.

Traditional exploit vectors like use-after-free, buffer overflows, or data races that corrupt in-memory state cannot escalate into protocol-level attacks. If memory corruption mangles a message in transit, it does not become a privilege escalation. It becomes an invalid signature. The data is either authentically from who it claims to be from, or it gets rejected. There is no middle ground.

The protocol enforces this through a three-layer signature and encryption system: transport-level signing on every hop (NetworkContainer), message-level signing by the original sender (NetworkEvent), and payload-level encryption for application data. Any tampering at any layer breaks the signature chain and the data is dropped.

Security hardening is enforced at every import path. Nodes are not added to the mesh until after all signature checks pass - no provisional state is written to disk before verification. Keys are loaded into a cert cache only and rolled back on failure. Power-loss and file-corruption events generate a scoped recovery file; the affected path is locked from further writes until recovery is confirmed and the file is cleared.

Peer identities are cosigned at provisioning time: a node's identity is attested by the NMI's key, creating a verifiable chain from the network's root to every participant. Peers cannot impersonate each other even on the same network segment. The network remains truly decentralized - cosigning is attestation, not control. The underlying blockchain is append-only; no party, including the NMI, can write over or alter committed state. Every event is permanent once confirmed.

Managed Decentralized Networks

ConnectX is built for networks that need real administration without a central server. The Network Master Identity (NMI) provisions nodes, assigns permissions through an embedded permissions framework, and issues Integration Keys (CXIK) to authorize network registration. CXIK binds a node's identity to its network membership at the cryptographic level before the node is permitted to participate. Nodes operate at equal authority within the permission model once admitted.

When the network is ready, the owner can activate Zero Trust mode. This is an irreversible decision that permanently locks the trust structure and removes even the NMI's ability to modify it. The network becomes fully decentralized by design, not by accident.

Networks can operate as open (anyone joins), whitelisted (registration required), or fully private (invitation-only, no public seed distribution). All configuration changes are recorded to the admin blockchain (c1), providing an immutable audit trail of every access policy change.

Typed, Signed Delivery

MESSAGE payloads are sent as CXMessage objects (text + timestamp, serialized as cxJSON1). Raw unsigned payloads are rejected at the receiver at the protocol level. There is no configuration option to disable this; a misbehaving peer cannot bypass it.

Delivery has two modes. Signed messages carry a cryptographic signature tied to the sender's PGP identity, so the recipient can verify exactly who sent it. E2E encrypted messages are encrypted to the recipient's key and signed by the sender. Both paths go through the same five-stage pipeline and produce the same guarantees about origin authenticity.

The network join API lets nodes discover and join non-CXNET networks without NMI-level bootstrap. joinNetworkFromPeers(networkID) sends a SEED_REQUEST to EPOCH first (authoritative), then to all HV peers. Seed.fetchOfficial() tries the peer network first, then falls back to the HTTPS bootstrap file. The public API also exposes getNetworks() and getNetworkIDs() for runtime inspection of a node's current network membership.

Cosigned Network Blobs

A network's definition travels as a cosigned blob: an inner signature by the network's own NMI, wrapped in an outer cosignature from EPOCH. Because both layers verify independently, the blob proves itself. The identity of whichever peer happened to forward it carries no weight, so any peer holding a stored copy can serve a join, the network's own NMI included but not required.

That property is what makes seeding work without a central distributor. A responder attaches its stored cosigned.cxnb to the seed response, and the receiver verifies both signature layers and rejects any blob whose network ID is not the one it asked for before registering anything.

0.6.2 removed the peer-count vote from the join path. A network previously could not be joined unless three distinct peers answered the seed request, which meant a small network could never be joined at all: the tally sat below threshold indefinitely with no timeout. Since a cosigned blob is self-proving, a verified response is now applied on sight. Consensus is unchanged and still handles every response that fails verification or arrives without a blob. Nothing is trusted that was not trusted before; the vote is skipped only where the signature chain is the stronger guarantee.

EventType has declared ttlMs, maxPayloadBytes and maxRetries for some time, but the retry queue ignored them in favour of a flat 50-attempt ceiling with exponential backoff, so a request could be retransmitted for hours after it stopped being relevant. Retry bundles now resolve their type's real limits once at construction and expire on TTL as well as attempt count. A SEED_REQUEST honours its 60-second TTL and drops in about a minute, letting the join logic issue a fresh one instead of the mesh carrying a stale broadcast.

CXApp Dispatcher, Security Hardening & Administrative Authorization

Handler dispatch off the EventProcessor. CXAppServer.handle() previously ran inline on the single mesh thread, so a slow app handler could delay other event processing on the node. CXAppDispatcher adds a bounded pool with one lane per appID: apps run concurrently, while each app's own requests stay ordered. Parsing and app lookup stay on the EventProcessor; only the handler call moved.

Error codes and enumeration defence. Refusal responses have been consolidated to a single FORBIDDEN code rather than distinguishing unknown field, unreadable, unwritable, and denied cases, closing off a way to infer an app's structure by comparing replies. .debug re-opens detail without granting access.

Field value encoding. stringify used String.valueOf while coerce read cxJSON1, so a Map went out as {a=b} and came back as an unparseable success. The client had no cxJSON1 branch at all and silently applied null. Both are fixed and consolidated into CXAppCodec so they cannot drift apart again.

In-process calling API. CXApps could previously only be reached from a browser. ConnectX.sendAppRequest plus read/write/invoke/refresh now return CompletableFuture, completed on a dispatcher lane so caller callbacks never land on the EventProcessor. ttlMs added to both annotations.

Inherited members and arity. buildCache only saw the concrete class, so a shared base app's members were missed. It now walks the class hierarchy. INVOKE requires exact arity instead of null-padding.

Audit findings addressed

• NodeMeshPeer verification result handling tightened so unsigned blobs can no longer be stored, including cases involving already-known identities.
• NodeMeshUnsolicited APP_RESPONSE handling is now guarded on sid + app + origin before it can update client state.
• IOThreadFixed a double-invocation path in doAfter that could produce contradictory outcomes.
• NodeMeshReplaced an assert-based null check with a real runtime check, since asserts are disabled by default.
• CXAppClientescapeHtml is now context-aware, closing an attribute-injection gap.
• HTTPBridgeProviderAdded bounds on body read size and session map growth.
• JacksonProviderRestored the us.anvildevelopment. allowlist wildcard alongside its narrower entries.

Also corrected: registerPeerHint now writes as intended (a validation check had been silently blocking it); confirmed escapeAttr correctly escapes quotes.

Administrative authorization

The six c1 admin handlers (GRANT_PERMISSION, BLOCK_NODE, UNBLOCK_NODE, REGISTER_NODE, and related paths) now go through an explicit authorization check before applying changes, closing a gap where these actions could previously be processed without one.

CXNetwork.checkAdministrativeAuthority now requires the target network's NMI, backend set, or the action's permission - never CXNET's. Zero Trust activation fully demotes the NMI. Permission already declared BlockNode/UnblockNode/RegisterNode, and enforcement is now wired up to match.

All six handlers now authorize strictly on verified origin (oCXID), removing a transmitter-based fallback that didn't require direct authorship of the event. ZERO_TRUST_ACTIVATION - an irreversible operation - now checks the correct authority field.

Bidirectional Encrypted Channels

CXStreamPlugin provides full bidirectional stream sessions between peers. Open a session with openStream(targetCxID, localHost), accept with acceptStream(session), write with session.write(data), and close with session.close(cx). Sessions run over the same cryptographic pipeline as all other ConnectX traffic.

Transport is negotiated automatically. TCP mux is the default: stream frames are multiplexed on the existing P2P port via a CXST header, so no additional port is needed. When both peers have a working HTTP bridge, the receiver probes its own health endpoint and verifies the response identity matches its own node ID before advertising WebSocket. If the external URL routes to a different server, it falls back to TCP. The initiator follows whatever transport the receiver advertises in ACCEPT. NodeConfig.streamBridgeOnly = true disables TCP for nodes behind reverse proxies where exposing a direct IP defeats the point.

Network Topology

Threading Model: Five-Stage Pipeline

ConnectX distributes I/O and cryptographic work across five dedicated stages. Ingress and egress each run independent thread pools so neither direction can stall the other. State transitions are serialized through a single-threaded processor. No locks required for correctness.

CPU-heavy cryptographic operations scale across cores in stages 2 and 4. The single EventProcessor in stage 3 guarantees atomic state without synchronization overhead. No single slow operation blocks a parallel path.

Test Coverage

Baseline report from 2026-03-24. Coverage has grown since - stream sessions, CXApps (19 unit tests), CXIK, and a full JUnit 5 MultiPeerTest suite (E2E encryption, permission enforcement, spoofed-sender rejection, signed/unsigned delivery) were all added after this snapshot. Core networking, cryptography, and threading paths are fully exercised. Subsystems not yet implemented are at 0% by design.