# Networks & proxies

Source: https://tehoclient.dev/install/networks
SDK: 1.0.0

There are two supported ways to run Teho on a network. Pick one per network.

| | A · Backends only | B · Proxy plugin plus backends |
|---|---|---|
| Proxy | Nothing installed | `TehoAPI-Velocity.jar` or `TehoAPI-Bungee.jar` |
| Backends | `TehoAPI.jar` | `TehoAPI.jar` with `proxy.secret` set |
| Handshake | On every backend join | Once, with the proxy |
| Network features | None | Staff grants, rules, presence and anything set through `TehoApi` on the proxy |
| Good for | Per-server features only | Networks that want one session and shared staff tools |

## A · Backends only

Install `TehoAPI.jar` on each backend and nothing on the proxy. Each backend runs its own `HelloRequest` -> `Hello` -> `Welcome` when the player arrives. State from the previous backend is cleared by the new `Welcome`.

## B · Proxy plugin plus backends

Install the proxy plugin, then set the same secret everywhere:

```yaml
proxy:
  secret: "a long random string shared by the proxy and every backend"
```

| Where | File |
|---|---|
| Velocity | `plugins/tehoapi/config.yml` |
| BungeeCord, Waterfall | `plugins/TehoAPI/config.yml` |
| Paper, Spigot, Folia backends | `plugins/TehoAPI/config.yml` |
| Minestom backends | `TehoMinestom.builder().proxySecret(...)` |

Player-info forwarding is required: Velocity modern forwarding or BungeeCord `ip_forward`. Firewall your backends as usual.

### What happens on join

1. The client handshakes with the proxy. The proxy answers with a `Welcome` that carries the network's `server-name`.
2. When the player connects to a backend, the proxy sends that backend a **handoff** on the `teho:proxy` channel: the player's UUID, the negotiated protocol and capabilities, the client's `Hello` fields and the session id.
3. The backend creates the session from the handoff, fires `TehoPlayerReadyEvent` and applies its presets. The client does not handshake again.

### What happens on a server switch

- The proxy sends the client a `Reset`, which clears the old server's waypoints, HUD and rules.
- It then re-sends the network-level state it set itself, such as staff grants, network rules and anything set through `TehoApi` on the proxy.
- If a backend sends its own `Reset`, the proxy re-applies its state about 100 ms later.

### Client replies still reach backends

Client frames other than `Hello`, such as consent results, staff tool state, key presses and UI events, are handled on the proxy and also relayed to the current backend inside signed relays. `TehoConsentEvent`, `TehoStaffToolEvent` and `TehoClientEvent` therefore fire on both layers. Frames from a backend to the client pass through the proxy unchanged.

## How the proxy channel is secured

- Every `teho:proxy` message is signed with HMAC-SHA256 over a domain prefix plus the body, using your secret.
- Messages are bound to the player's UUID, valid for ±30 seconds and single-use, enforced with a nonce replay cache.
- Backends drop any message that fails a check and log the reason at most every 10 seconds.
- The proxy drops any `teho:proxy` frame a client tries to send, and ignores a `Hello` inside a relay, even a chunked one.


**Without a secret**

The proxy still handshakes and serves network features, but backends never see the player as a Teho player. Backend plugins will find `TehoApi.get().player(uuid)` empty.


## Pick one layer per feature

`ModuleRules` and `StaffGrant` are full replaces on the client. Let the proxy own network-wide staff tools and rules, and let backends own game features such as waypoints, HUD and notifications. If both layers set rules, the last frame the client received wins.


**Status**

The proxy adapters, handoff and relay are implemented and covered by the SDK's proxy tests. They have not yet been run end to end against a live Teho Client on Velocity or BungeeCord, so report anything odd you see on a real network.