Boson WebGateway Client (HiggsNode)

The Java client library for the Boson WebGateway service — a light DHT node implementation (codename HiggsNode) that gives browser-based and other HTTP-only clients full access to the Boson DHT network through a super node's HTTP API.

---

Table of Contents

• Boson Node Types
• What Is WebGateway?
• How It Works
• Prerequisites
• Build
• Adding as a Dependency
• Usage
• Contributing
• License

---

Boson Node Types

The Boson network defines three node roles:

Node Type	DHT Participation	Service Access	Typical Use Case
Super Node	Full DHT node	Hosts layer-2 services	Server infrastructure
Regular Node	Full DHT node (UDP)	Consumes services	e.g.; Native desktop / mobile apps
Light Node	None — uses WebGateway	Consumes services	e.g.; Web apps running in a browser

A Light Node cannot run a full DHT implementation (for example, a browser cannot open UDP sockets), so it delegates all DHT operations to the WebGateway HTTP API exposed by a super node. HiggsNode is the Light Node implementation for Java.

---

What Is WebGateway?

WebGateway is a Boson layer-2 service that runs on a super node alongside the DHT. It wraps the DHT's UDP-based operations as authenticated HTTPS endpoints, enabling clients that cannot speak UDP to:

• Look up and announce peer service registrations (FIND_PEER / ANNOUNCE_PEER)
• Look up and store values in the DHT (FIND_VALUE / STORE_VALUE)
• Look up DHT nodes (FIND_NODE)

The service uses a custom Compact Web Token (CWT) for authentication — a CBOR-encoded, Ed25519-signed bearer token derived from the client's user or device key. Rate limiting and per-client access control are enforced by the gateway.

This repository contains the client side of WebGateway: the HiggsNode class, which implements the same Node interface as the full KadNode, making it a transparent drop-in replacement. Any Boson service or application written against the Node interface works without modification on top of HiggsNode.

---

How It Works

  Web App / Light Client
       │
       │  HTTPS (TLS 1.3)
       │  Bearer: Compact Web Token (CBOR + Ed25519 signature)
       ▼
 ┌─────────────────────────────────────┐
 │  WebGateway (super node service)    │  ← public HTTPS endpoint
 │  Rate limit · Auth · CORS           │
 └─────────────────────────────────────┘
       │  Internal calls
       ▼
 ┌─────────────────────────────────────┐
 │  KadNode (full DHT node)            │  ← UDP port 39001
 │  Boson Kademlia DHT                 │
 └─────────────────────────────────────┘

1. Identity — the client holds an Ed25519 key pair. Two modes are supported:
   • User key mode: the user's private key is held directly; the user ID is the public key. Suitable when the full key is available.
   • User ID + device key mode: only the user's public key (ID) and a device-specific private key are held. The access token identifies the user but is signed by the device key.
2. Access token — before each HTTP request, HiggsNode generates a short-lived CBOR token containing the issuer, audience (gateway node ID), subject (user ID), optional device ID, expiry, and a random nonce. The token is signed with the identity key and sent as an HTTP Authorization: Bearer header.
3. TLS trust — when connecting over HTTPS, HiggsNode uses a HybridTrustManager that validates the server's self-signed certificate against the expected gateway peer ID. No CA installation is required.
4. DHT operations — HiggsNode translates each Node interface call into the corresponding REST request and returns the same result types as KadNode.
5. Local data — values and peer records stored via HiggsNode are cached locally. Persistent entries are periodically reannounced to prevent DHT expiry.

---

Prerequisites

Requirement	Version
Java JDK	17 or later
Apache Maven	3.8 or later
Boson Core (boson-api)	same version or compatible
A running Boson super node with WebGateway	—

---

Build

git clone https://github.com/bosonnetwork/Boson.WebGateway.Client.git
cd Boson.WebGateway.Client
./mvnw clean package

The compiled JAR is placed in target/lib/boson-higgs-<version>.jar.

To skip tests:

./mvnw clean package -DskipTests

---

Adding as a Dependency

Add the following to your Maven pom.xml:

<dependency>
    <groupId>io.bosonnetwork</groupId>
    <artifactId>boson-higgs</artifactId>
    <version>${boson.version}</version>
</dependency>

Native transport

This library carries no platform-specific native libraries, so it runs on Java NIO wherever it is deployed. To use Netty's native transport (epoll on Linux, kqueue on macOS), add the native jars for the platform the application runs on, and create the Vert.x instance the client runs on with new VertxOptions().setPreferNativeTransport(true). For Linux x86_64:

<dependency>
    <groupId>io.netty</groupId>
    <artifactId>netty-transport-native-epoll</artifactId>
    <classifier>linux-x86_64</classifier>
    <scope>runtime</scope>
</dependency>
<dependency>
    <groupId>io.netty</groupId>
    <artifactId>netty-transport-native-unix-common</artifactId>
    <classifier>linux-x86_64</classifier>
    <scope>runtime</scope>
</dependency>

The native jars must match the Netty version on the class path. See Native Transport for every platform, Maven profiles and Gradle.

---

Usage

User key mode

Use this when the application holds the full user private key (e.g., a trusted native client or server-side process).

// Gateway coordinates — obtain from the super node operator.
Id gatewayNodeId = Id.of("HZXXs9LTfNQjrDKvvexRhuMk8TTJhYCfrHwaj3jUzuhZ");
Id gatewayPeerId = Id.of("GbRwG3WgKgApSDBr9FGo5Y3RssSWxfWhanXMBdPCo5F2");
String gatewayUrl = "https://gateway.example.com:8443";

// Build the light node.
HiggsNode node = HiggsNode.builder()
    .userKey("<Base58-or-0x-hex-Ed25519-private-key>")
    .gatewayNodeId(gatewayNodeId)
    .gatewayPeerId(gatewayPeerId)
    .gatewayUrl(gatewayUrl)
    .build();

// Start — establishes the HTTPS connection and verifies the gateway version.
node.start().get();

// Use the Node interface exactly as you would with KadNode.
List<PeerInfo> peers = node.findPeer(serviceId, -1, 1, LookupOption.ARBITRARY).get();

node.stop().get();

User ID + device key mode

Use this when the full user private key should not be stored on the device. The device holds only its own private key; the user ID (public key) is stored separately.

Id userId    = Id.of("<Base58-user-public-key>");

HiggsNode node = HiggsNode.builder()
    .userId(userId)
    .deviceKey("<Base58-device-private-key>")
    .gatewayNodeId(gatewayNodeId)
    .gatewayPeerId(gatewayPeerId)
    .gatewayUrl(gatewayUrl)
    .build();

node.start().toCompletionStage().toCompletableFuture().get();

Providing an external Vert.x instance

Vertx vertx = Vertx.vertx();

HiggsNode node = HiggsNode.builder()
    .vertx(vertx)
    .userKey("<Base58-private-key>")
    .gatewayNodeId(gatewayNodeId)
    .gatewayPeerId(gatewayPeerId)
    .gatewayUrl(gatewayUrl)
    .build();

If no Vertx instance is provided, HiggsNode creates an internal one on start().

Using HiggsNode with Boson services

Because HiggsNode implements Node, it can be passed directly to any Boson service or client library that accepts a Node:

// Pass the light node to the messaging client — no code change needed.
MessagingClient client = MessagingClient.create(node, messagingConfig);

---

Contributing

We welcome contributions from the open-source community. To get started:

1. Fork this repository and create a feature branch.
2. Make your changes and add tests where applicable.
3. Ensure ./mvnw clean verify passes.
4. Open a pull request with a clear description of the change.

Please read our Code of Conduct before contributing.

---

License

This project is licensed under the MIT License.