# 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"
}
```

---

## Status

- planning/specification stage
- split-plugin architecture defined
- protocol draft defined in `Yonexus.Protocol`
- implementation not started yet

---

## 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)