# Yonexus

Yonexus is a cross-instance communication system for OpenClaw built as **three separate repositories**:

| Repository | Role |
|---|---|
| `Yonexus` | Umbrella — architecture, planning, and coordination |
| `Yonexus.Server` | Central hub plugin — accepts client connections, handles pairing/authentication |
| `Yonexus.Client` | Client plugin — connects to server, manages local identity |
| `Yonexus.Protocol` | Shared protocol specification — referenced as a submodule by both Server and Client |

## Overview

### Yonexus.Server
Installed on the central OpenClaw instance.

Responsibilities:
- run the WebSocket server
- maintain the client registry
- handle pairing and authentication
- track heartbeat and liveness state
- relay messages to connected clients
- rewrite inbound client messages before rule dispatch
- notify a human administrator of pairing requests via Discord DM

### Yonexus.Client
Installed on follower OpenClaw instances.

Responsibilities:
- connect to `Yonexus.Server`
- manage local keypair and shared secret
- complete pairing with out-of-band pairing code
- authenticate on reconnect
- send periodic heartbeat
- send messages to server
- receive messages from server via rule dispatch

### Yonexus.Protocol
Shared protocol specification repository. Both `Yonexus.Server` and `Yonexus.Client` reference this as a submodule at `protocol/`.

---

## Repository Structure

```
Yonexus (umbrella)
├── Yonexus.Protocol  ← shared protocol submodule
├── Yonexus.Server    ← server plugin submodule
│   └── protocol/     ← points to Yonexus.Protocol
└── Yonexus.Client    ← client plugin submodule
    └── protocol/     ← points to Yonexus.Protocol
```

---

## Architecture

A Yonexus network contains:
- exactly one OpenClaw instance running `Yonexus.Server`
- one or more OpenClaw instances running `Yonexus.Client`

Topology rules:
- `Yonexus.Server` must be reachable via a stable address
- `Yonexus.Client` instances connect outbound to the server
- direct client-to-client sockets are not required in v1
- client-to-client communication, if needed, is relayed by the server

---

## Security Model

Pairing is intentionally **out-of-band**.

When a new client needs pairing:
- the server generates a pairing code
- the server sends that pairing code by Discord DM to a configured human admin
- the pairing code is **not** sent over the Yonexus WebSocket connection
- the human relays the code to the client side manually
- the client submits the code back through the protocol

After pairing:
- the server issues a shared secret
- the client stores its private key and secret locally
- reconnect authentication uses signed proof derived from `secret + nonce + timestamp`

---

## Current Repository Spec Files

### Umbrella (`Yonexus`)
- `PLAN.md` — project plan and architecture
- `ARCHITECTURE.md` — architecture overview and repository graph
- `FEAT.md` — implementation feature checklist

### Protocol (`Yonexus.Protocol`)
- `PROTOCOL.md` — shared communication protocol specification

### Server (`Yonexus.Server`)
- `PLAN.md` — server-specific implementation plan
- `protocol/` — submodule pointing to `Yonexus.Protocol`

### Client (`Yonexus.Client`)
- `PLAN.md` — client-specific implementation plan
- `protocol/` — submodule pointing to `Yonexus.Protocol`

---

## Planned TypeScript APIs

### Yonexus.Server
```ts
sendMessageToClient(identifier: string, message: string): Promise<void>
registerRule(rule: string, processor: (message: string) => unknown): void
```

### Yonexus.Client
```ts
sendMessageToServer(message: string): Promise<void>
registerRule(rule: string, processor: (message: string) => unknown): void
```

Message format:
```text
${rule_identifier}::${message_content}
```

Reserved rule: `builtin`

---

## Planned Server Config

```json
{
  "followerIdentifiers": ["client-a", "client-b"],
  "notifyBotToken": "<discord-bot-token>",
  "adminUserId": "123456789012345678",
  "listenHost": "0.0.0.0",
  "listenPort": 8787,
  "publicWsUrl": "wss://example.com/yonexus"
}
```

## Planned Client Config

```json
{
  "mainHost": "wss://example.com/yonexus",
  "identifier": "client-a",
  "notifyBotToken": "<discord-bot-token>",
  "adminUserId": "123456789012345678"
}
```

---

## Shared Terminology

To keep the umbrella repo, protocol repo, and both plugin repos aligned, Yonexus uses these terms consistently:

- `identifier`: the stable logical name of a follower/client instance, unique within one Yonexus network.
- `rule_identifier`: the exact-match application routing key used in `${rule_identifier}::${message_content}`.
- `builtin`: the reserved rule namespace for Yonexus protocol/control messages only.
- `pairingCode`: the short-lived out-of-band code generated by `Yonexus.Server` and delivered to a human admin by Discord DM.
- `secret`: the server-issued shared secret established after successful pairing and used in reconnect authentication proof construction.
- `publicKey` / `privateKey`: the client-owned signing keypair used for auth proof signing and verification.
- `nextAction`: the server decision returned in `hello_ack`, currently one of `pair_required`, `waiting_pair_confirm`, `auth_required`, or `rejected`.

## v1 Scope Boundaries

In scope for v1:
- WebSocket transport between one server and one or more clients
- out-of-band pairing via Discord DM to a human administrator
- signed reconnect authentication using `secret + nonce + timestamp`
- heartbeat/liveness tracking (`online | unstable | offline`)
- exact-match rule dispatch
- lightweight persistence for trust/state material
- optional `heartbeat_ack`
- exponential reconnect backoff on the client side

Explicitly out of scope for v1:
- multi-server topology
- direct client-to-client sockets
- offline message queues / delivery guarantees
- advanced rule matching (prefix/regex/wildcard)
- management UI
- distributed consensus / clustering
- automatic admin approve/deny workflows beyond human relay of the pairing code
- encryption-at-rest hardening beyond documenting local sensitive storage behavior

## Status

- umbrella/specification repo is aligned with the split architecture
- core implementation work is underway in `Yonexus.Server`, `Yonexus.Client`, and `Yonexus.Protocol`
- protocol/types/codec/test scaffolding already exists in `Yonexus.Protocol`
- runtime, transport, pairing, auth, heartbeat, rule dispatch, and test coverage are largely implemented in submodules; remaining work is focused on boundary cleanup and leftover failure-path coverage

---

## Repository URLs

- [Yonexus (umbrella)](https://git.hangman-lab.top/nav/Yonexus)
- [Yonexus.Server](https://git.hangman-lab.top/nav/Yonexus.Server)
- [Yonexus.Client](https://git.hangman-lab.top/nav/Yonexus.Client)
- [Yonexus.Protocol](https://git.hangman-lab.top/nav/Yonexus.Protocol)