# Yonexus

Yonexus is a cross-instance communication system for OpenClaw built as **two separate plugins**:

- `Yonexus.Server`
- `Yonexus.Client`

It is designed for scenarios where one OpenClaw instance acts as a central communication hub and multiple other OpenClaw instances connect to it as clients.

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

---

## 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 Spec Files

This repository currently contains planning/spec-first documents:

- `PLAN.md` — project plan and architecture
- `PROTOCOL.md` — builtin WebSocket protocol details
- `FEAT.md` — implementation feature checklist

---

## Planned Plugin Manifests

This repo is expected to define separate plugin manifests for:

- `plugin.server.json`
- `plugin.client.json`

These represent the initial config surface for `Yonexus.Server` and `Yonexus.Client`.

---

## Planned TypeScript APIs

### Yonexus.Server
- `sendMessageToClient(identifier: string, message: string)`
- `registerRule(rule: string, processor: (message: string) => unknown)`

### Yonexus.Client
- `sendMessageToServer(message: string)`
- `registerRule(rule: string, processor: (message: string) => unknown)`

Message format:

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

Reserved rule:

```text
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

Current repository status:
- planning/specification stage
- split-plugin architecture defined
- protocol draft defined
- implementation not started yet

---

## Next Steps

Recommended next deliverables:
- plugin manifests
- source tree scaffolds for server/client
- protocol model types
- transport skeleton
- pairing/auth flow implementation