352 lines
8.1 KiB
Markdown
352 lines
8.1 KiB
Markdown
# Yonexus — Architecture Overview
|
|
|
|
## 1. Purpose
|
|
|
|
Yonexus is a cross-instance communication system for OpenClaw.
|
|
|
|
The repository `Yonexus` is the **umbrella/specification repository** for the system. It contains:
|
|
- high-level planning
|
|
- architecture documents
|
|
- references to implementation repositories as git submodules
|
|
|
|
Yonexus is implemented as three repositories:
|
|
- `Yonexus.Server` — central hub plugin
|
|
- `Yonexus.Client` — client plugin
|
|
- `Yonexus.Protocol` — shared protocol specification, referenced as a submodule by both
|
|
|
|
---
|
|
|
|
## 2. Repository Roles
|
|
|
|
## 2.1 `Yonexus` (umbrella repo)
|
|
|
|
Purpose:
|
|
- system-level planning
|
|
- architecture documents
|
|
- cross-cutting decisions that apply to both server and client
|
|
- coordination of sub-repositories via git submodules
|
|
|
|
This repository should contain:
|
|
- top-level planning docs
|
|
- architecture overview
|
|
- feature checklists
|
|
- cross-cutting design rationale
|
|
|
|
It references:
|
|
- `Yonexus.Server` (submodule)
|
|
- `Yonexus.Client` (submodule)
|
|
- `Yonexus.Protocol` (submodule)
|
|
|
|
## 2.2 `Yonexus.Protocol`
|
|
|
|
Purpose:
|
|
- protocol specification (PROTOCOL.md)
|
|
- canonical JSON shape references
|
|
- shared type definitions (planned)
|
|
|
|
Referenced as a submodule by:
|
|
- `Yonexus.Server/protocol`
|
|
- `Yonexus.Client/protocol`
|
|
|
|
This is the **single source of truth** for the Yonexus protocol. Both server and client implementations must conform to the protocol defined here.
|
|
|
|
## 2.3 `Yonexus.Server`
|
|
|
|
Purpose:
|
|
- implementation of the central hub/server plugin
|
|
- server-side connection management
|
|
- server-side pairing/authentication/state tracking
|
|
- server-side dispatch and routing behavior
|
|
|
|
Contains:
|
|
- `protocol/` — submodule pointing to `Yonexus.Protocol`
|
|
- `PLAN.md`
|
|
- implementation code
|
|
|
|
## 2.4 `Yonexus.Client`
|
|
|
|
Purpose:
|
|
- implementation of the client plugin
|
|
- outbound connection to `Yonexus.Server`
|
|
- local identity/keypair/secret management
|
|
- client-side pairing confirmation and authenticated reconnect
|
|
- client-side heartbeat and message sending
|
|
|
|
Contains:
|
|
- `protocol/` — submodule pointing to `Yonexus.Protocol`
|
|
- `PLAN.md`
|
|
- implementation code
|
|
|
|
---
|
|
|
|
## 3. Repository Graph
|
|
|
|
```
|
|
Yonexus (umbrella)
|
|
├── Yonexus.Protocol (submodule)
|
|
├── Yonexus.Server (submodule)
|
|
│ └── protocol/ (nested submodule -> Yonexus.Protocol)
|
|
└── Yonexus.Client (submodule)
|
|
└── protocol/ (nested submodule -> Yonexus.Protocol)
|
|
```
|
|
|
|
Policy:
|
|
- protocol changes are always committed to `Yonexus.Protocol` first
|
|
- `Yonexus.Server` and `Yonexus.Client` update their `protocol/` submodule ref after protocol version is stable
|
|
- umbrella `Yonexus` updates its submodule refs after server/client have stable versions
|
|
|
|
---
|
|
|
|
## 4. System Topology
|
|
|
|
A Yonexus deployment contains:
|
|
- exactly one `Yonexus.Server` instance
|
|
- one or more `Yonexus.Client` instances
|
|
|
|
Topology assumptions:
|
|
- `Yonexus.Server` runs on an OpenClaw instance reachable at a stable address
|
|
- each `Yonexus.Client` connects outbound to the server
|
|
- clients do not directly connect to each other in v1
|
|
- cross-client coordination is relayed through the server
|
|
|
|
Visual model:
|
|
|
|
```
|
|
Yonexus.Client A --->
|
|
\
|
|
Yonexus.Client B ----> Yonexus.Server
|
|
/
|
|
Yonexus.Client C --->
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Shared vs Split Responsibilities
|
|
|
|
## 5.1 Yonexus.Protocol — Shared
|
|
|
|
These belong to the protocol repo and apply to both plugins:
|
|
- protocol format and message categories
|
|
- builtin message types and their semantics
|
|
- pairing security model
|
|
- nonce/timestamp validation rules
|
|
- heartbeat timing rules
|
|
- message rewrite rules
|
|
- reserved rule namespace (`builtin`)
|
|
- canonical JSON shapes
|
|
- naming and terminology
|
|
|
|
## 5.2 Server-Only Concerns (Yonexus.Server)
|
|
|
|
These belong in `Yonexus.Server`:
|
|
- WebSocket server startup
|
|
- listen host/port config
|
|
- client registry persistence
|
|
- public key / secret storage
|
|
- pairing code generation
|
|
- Discord DM notification to admin
|
|
- auth proof verification
|
|
- liveness status tracking
|
|
- client message rewriting and dispatch on server side
|
|
- sending messages to connected clients
|
|
|
|
## 5.3 Client-Only Concerns (Yonexus.Client)
|
|
|
|
These belong in `Yonexus.Client`:
|
|
- WebSocket client connection management
|
|
- reconnect/backoff logic
|
|
- local keypair generation
|
|
- local secret persistence
|
|
- pairing code submission
|
|
- auth proof construction/signing
|
|
- heartbeat sending
|
|
- sending messages to server
|
|
- receiving server messages and local dispatch
|
|
|
|
---
|
|
|
|
## 6. Communication Model
|
|
|
|
## 6.1 Transport
|
|
|
|
Transport is WebSocket.
|
|
|
|
- `Yonexus.Server` acts as server
|
|
- `Yonexus.Client` acts as client
|
|
|
|
## 6.2 Message Categories
|
|
|
|
Two message categories exist on the same transport:
|
|
|
|
### Builtin protocol messages
|
|
Used for:
|
|
- hello/session setup
|
|
- pairing
|
|
- authentication
|
|
- heartbeat
|
|
- lifecycle/status
|
|
- protocol errors
|
|
|
|
Format:
|
|
|
|
```text
|
|
builtin::{json}
|
|
```
|
|
|
|
### Application rule messages
|
|
Used for higher-level cross-instance communication.
|
|
|
|
Format:
|
|
|
|
```text
|
|
${rule_identifier}::${message_content}
|
|
```
|
|
|
|
Server rewrite rule:
|
|
|
|
When server receives a message from a client, before dispatch it rewrites:
|
|
|
|
```text
|
|
${rule_identifier}::${sender_identifier}::${message_content}
|
|
```
|
|
|
|
---
|
|
|
|
## 7. Security Architecture
|
|
|
|
## 7.1 Pairing Model
|
|
|
|
Pairing is intentionally out-of-band.
|
|
|
|
When a new client needs pairing:
|
|
- server generates a pairing code
|
|
- server sends that code to a human administrator via Discord DM
|
|
- server does **not** send the code over the Yonexus WebSocket channel
|
|
- human relays the code to the client side manually
|
|
- client submits the code back to the server
|
|
|
|
This preserves a basic human-mediated trust step.
|
|
|
|
## 7.2 Post-Pairing Authentication
|
|
|
|
After pairing:
|
|
- server issues a shared secret
|
|
- client stores secret locally
|
|
- client already has a private key
|
|
- reconnect auth uses signed proof derived from:
|
|
- secret
|
|
- nonce
|
|
- timestamp
|
|
|
|
## 7.3 Replay Protection
|
|
|
|
Server enforces:
|
|
- timestamp freshness (`< 10s` drift)
|
|
- nonce collision detection
|
|
- handshake rate threshold (`>10 attempts in 10s` is unsafe)
|
|
- re-pair requirement after unsafe conditions
|
|
|
|
---
|
|
|
|
## 8. State Ownership
|
|
|
|
## 8.1 Server-Owned State
|
|
|
|
Canonical server-owned state includes:
|
|
- allowed client identifiers
|
|
- trust state for each client
|
|
- client public key
|
|
- client secret
|
|
- pairing state
|
|
- pairing notification state
|
|
- recent nonce window
|
|
- recent handshake attempt window
|
|
- client liveness state
|
|
|
|
## 8.2 Client-Owned State
|
|
|
|
Canonical client-owned state includes:
|
|
- client identifier
|
|
- client private key
|
|
- client public key
|
|
- current shared secret
|
|
- last successful local trust metadata if needed
|
|
|
|
---
|
|
|
|
## 9. Plugin API Boundaries
|
|
|
|
## 9.1 Yonexus.Server API
|
|
|
|
Planned public API:
|
|
- `sendMessageToClient(identifier, message)`
|
|
- `registerRule(rule, processor)`
|
|
|
|
## 9.2 Yonexus.Client API
|
|
|
|
Planned public API:
|
|
- `sendMessageToServer(message)`
|
|
- `registerRule(rule, processor)`
|
|
|
|
The protocol defines semantics; implementation details belong in each submodule.
|
|
|
|
---
|
|
|
|
## 10. Documentation Ownership
|
|
|
|
## 10.1 Umbrella Repo Docs
|
|
|
|
Should contain:
|
|
- system architecture
|
|
- cross-cutting feature list
|
|
- global design rationale
|
|
- cross-repo coordination notes
|
|
|
|
## 10.2 Protocol Repo Docs
|
|
|
|
Must contain:
|
|
- protocol specification (PROTOCOL.md)
|
|
- canonical message shapes
|
|
- protocol versioning notes
|
|
|
|
## 10.3 Server Repo Docs
|
|
|
|
Should contain:
|
|
- server setup
|
|
- server config reference
|
|
- server persistence model
|
|
- server operational behavior
|
|
- implementation tasks
|
|
|
|
## 10.4 Client Repo Docs
|
|
|
|
Should contain:
|
|
- client setup
|
|
- client config reference
|
|
- client local storage model
|
|
- client reconnect/heartbeat behavior
|
|
- implementation tasks
|
|
|
|
---
|
|
|
|
## 11. Development Flow
|
|
|
|
Recommended flow:
|
|
1. define cross-cutting behavior in `Yonexus` umbrella
|
|
2. finalize protocol in `Yonexus.Protocol`
|
|
3. update submodule refs in `Yonexus.Server` and `Yonexus.Client`
|
|
4. implement server-side protocol handling in `Yonexus.Server`
|
|
5. implement client-side protocol handling in `Yonexus.Client`
|
|
6. keep protocol changes synchronized back into umbrella docs
|
|
|
|
---
|
|
|
|
## 12. Non-Goals of the Umbrella Repo
|
|
|
|
The umbrella repo should avoid becoming:
|
|
- the place where all implementation code lives
|
|
- a dumping ground for server-only or client-only details
|
|
- a duplicate of submodule READMEs without system-level value
|
|
|
|
Its job is coordination, not code concentration.
|