Add provider-independent NetherNet signalling and local connection checks

[ziaxzulu]

NetherNet servers can use a signalling provider chosen by their operator. A server registers, publishes its connection details, and sends heartbeats. When a client connects, the server checks a token in the first packet without asking the provider to approve that individual connection.

This proposal defines NetherNet External Signalling (NXS) and implements it in Network's external-signalling module. It builds on Cloudburst Network, Kas-tle's NetherNet work, and RTM's HTTP signalling and native transport. The NXS spec and local connection checks are our contributions.

Where the work comes from

Origin	Contribution	Source and commit in this proposal
CloudburstMC/Network	The Network foundation. Production RakNet and both codec trees are preserved.	develop at 508ed83c
Kas-tle/NetworkCompatible	Initial NetherNet transport, discovery, Xbox JSON-RPC signalling, and SDP fixes.	Source 9f3c0b7e, including 77489fb0 and dcea2bab; imported as 04ac4abb.
rtm516/NetworkCompatible	HTTP signalling and the libdatachannel backend.	Source 8d1c989e, including 37f82650 and f4ba1e7b; imported as b96f3094.
Zulu / teamziax	Open NXS spec, registration, recovery, heartbeats, and optional extensions.	Work through 01df7a0b, consolidated as fc7dcc35.
Zulu / teamziax	Check the first packet locally, create the native peer, and manage its lifetime.	Work through 01df7a0b, consolidated as 9bf6674c.
This consolidation	Build the maintained native forks together, record their versions, and explain the spec in plain English.	4ac17d6d, eeab76ad.
Zulu / teamziax	Move packet handling into native code; validate each pending connection asynchronously in Java.	c41512bb.
Zulu / teamziax	Publish and refresh multiple IPv4/IPv6 endpoints for one native host identity.	a6e73dfa.

The contribution record gives the full commit mapping and attribution. Three existing upstream test lines are repaired to match the current APIs and test assumptions; production RakNet code is unchanged. Kas-tle's broader RakNet compatibility and performance changes are deferred to separate proposals, including ACK coalescing and split-packet reassembly.

What we add

The NXS specification defines registration, heartbeats, connection settings, key management, and outcome reports. Its protocol requirements are separate from the supplied Java/native implementation, so other languages and libraries can implement NXS. A restart recovers the same registration IDs and keys. Registration completion starts the generation; heartbeat carries health, profile updates, installed key acknowledgements and desired/applied state. Connection outcomes use independent batches.

Geyser can request automatic registration with one opaque token and a metadata map. The provider selects account provisioning or fleet attachment from the credential's authority and binds the concrete mode into the challenge. Anonymous registration can only create a service. The client requires discovery support and rejects unresolved/unknown modes and anonymous attachment. Placement and tags remain bound to proof and completion.

The provider gives the client a short-lived connection token. Native code retains the first STUN request and sends its metadata to Java for token validation. Duplicate requests share that pending decision. After the token passes, native code checks STUN integrity before creating the peer. It then processes the retained request without waiting for a client retry. Established UDP traffic stays in native code; Java receives no per-packet admission callback.

During DTLS, the host checks the client certificate against the fingerprint in the token. Pending requests, used-token records and sessions have limits. Capacity is released after native cleanup finishes. A failed STUN integrity check releases the unused token reservation.

A host can publish several numeric IPv4/IPv6 addresses and ports under one identity. A background check-in can refresh the endpoint list as interfaces change. The first authenticated client address and port own the connection token; listing several host endpoints does not allow that token to create several sessions.

Optional metadata uses named extensions with limits on their number and size. Applications can interpret their own extensions, such as an account-claim link. Network does not require account or claim behavior or save this metadata with the registration.

Intended upstream PRs

Proposed PR	Dependency
Kas-tle's NetherNet transport	Cloudburst develop.
RTM's HTTP signalling and native backend	NetherNet transport and the Java binding.
NXS spec and provider client	The spec can be reviewed independently. The integrated client needs the preceding transport work.
Local token checks and native connection handling	NXS and the native libraries' asynchronous incoming-connection, certificate/ICE and cleanup APIs.
Multiple IPv4/IPv6 endpoints	The native provider transport. Preserve the existing single-endpoint API.

These PRs would target CloudburstMC/Network develop. Dependency pins and fork build configuration remain maintenance work. The build uses pinned libjuice, libdatachannel, and libdatachannel-java forks, so release does not depend on those projects accepting our changes. The imported native test probe retains its MPL-2.0 license.

Validation

Automatic-registration CI passes, with 37 NXS JVM tests plus native and transport checks. All four operator journeys exercise explicit and automatic registration; negative cases reject invalid selected modes before completion. Tests cover registration and recovery, native admission, and the NetherNet transport. The latest endpoint tests cover IPv4 and IPv6 STUN, both data channels from a mixed candidate list, endpoint refresh, and rejection of token reuse across address families.

The native regressions also cover a first STUN request sent once with a deliberately delayed decision, duplicate handling, invalid requests before peer allocation, capacity during cleanup, expiry, and incorrect DTLS fingerprints. The earlier consolidation passed the full Network build, including 88 RakNet tests, packages, Javadocs and protocol fixtures. Native fixtures do not establish stock-client gameplay or production capacity.

The current configuration delivery records the five-setting Geyser release. The earlier delivery record documents the asynchronous-admission release on zulubox with the existing production Warden control plane. It records signed readiness, installed/native checksums, preserved identity and live invalid-request rejection.

This is an internal draft from nxs-dev to upstream, which mirrors Cloudburst develop. Keep it unmerged so the mirror stays intact; future development PRs target nxs-dev. No upstream PR or repository transfer has been made.