320 lines
7.0 KiB
Markdown
320 lines
7.0 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
|
|
- protocol specification
|
|
- shared architectural decisions
|
|
- references to implementation repositories as git submodules
|
|
|
|
Yonexus is implemented as two separate plugins:
|
|
- `Yonexus.Server`
|
|
- `Yonexus.Client`
|
|
|
|
---
|
|
|
|
## 2. Repository Roles
|
|
|
|
## 2.1 `Yonexus` (umbrella repo)
|
|
|
|
Purpose:
|
|
- system-level planning
|
|
- architecture documents
|
|
- protocol definition
|
|
- shared design decisions
|
|
- cross-repo coordination
|
|
|
|
This repository should contain:
|
|
- top-level planning docs
|
|
- protocol docs
|
|
- feature checklists
|
|
- architecture overview
|
|
- cross-cutting decisions that apply to both server and client
|
|
|
|
This repository should **not** become the place where all implementation code lives.
|
|
|
|
## 2.2 `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
|
|
|
|
## 2.3 `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
|
|
|
|
---
|
|
|
|
## 3. 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:
|
|
|
|
```text
|
|
Yonexus.Client A --->
|
|
\
|
|
Yonexus.Client B ----> Yonexus.Server
|
|
/
|
|
Yonexus.Client C --->
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Shared vs Split Responsibilities
|
|
|
|
## 4.1 Shared System Concerns
|
|
|
|
These belong to the umbrella repo and apply to both plugins:
|
|
- protocol format
|
|
- builtin message types
|
|
- pairing security model
|
|
- nonce/timestamp validation rules
|
|
- heartbeat timing rules
|
|
- message rewrite rules
|
|
- reserved rule namespace (`builtin`)
|
|
- naming and terminology
|
|
|
|
These should live primarily in:
|
|
- `PLAN.md`
|
|
- `PROTOCOL.md`
|
|
- `FEAT.md`
|
|
- `ARCHITECTURE.md`
|
|
|
|
## 4.2 Server-Only Concerns
|
|
|
|
These belong in `Yonexus.Server` planning/implementation:
|
|
- 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
|
|
|
|
## 4.3 Client-Only Concerns
|
|
|
|
These belong in `Yonexus.Client` planning/implementation:
|
|
- 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
|
|
|
|
---
|
|
|
|
## 5. Communication Model
|
|
|
|
## 5.1 Transport
|
|
|
|
Transport is WebSocket.
|
|
|
|
- `Yonexus.Server` acts as server
|
|
- `Yonexus.Client` acts as client
|
|
|
|
## 5.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}
|
|
```
|
|
|
|
---
|
|
|
|
## 6. Security Architecture
|
|
|
|
## 6.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.
|
|
|
|
## 6.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
|
|
|
|
## 6.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
|
|
|
|
---
|
|
|
|
## 7. State Ownership
|
|
|
|
## 7.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
|
|
|
|
## 7.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
|
|
|
|
---
|
|
|
|
## 8. Plugin API Boundaries
|
|
|
|
## 8.1 Yonexus.Server API
|
|
|
|
Planned public API:
|
|
- `sendMessageToClient(identifier, message)`
|
|
- `registerRule(rule, processor)`
|
|
|
|
## 8.2 Yonexus.Client API
|
|
|
|
Planned public API:
|
|
- `sendMessageToServer(message)`
|
|
- `registerRule(rule, processor)`
|
|
|
|
The umbrella repo should define the semantics of these APIs, but implementation details belong in each submodule.
|
|
|
|
---
|
|
|
|
## 9. Documentation Ownership
|
|
|
|
## 9.1 Umbrella Repo Docs
|
|
|
|
Should contain:
|
|
- system architecture
|
|
- protocol spec
|
|
- cross-cutting feature list
|
|
- global design rationale
|
|
|
|
## 9.2 Server Repo Docs
|
|
|
|
Should contain:
|
|
- server setup
|
|
- server config reference
|
|
- server persistence model
|
|
- server operational behavior
|
|
- server implementation tasks
|
|
|
|
## 9.3 Client Repo Docs
|
|
|
|
Should contain:
|
|
- client setup
|
|
- client config reference
|
|
- client local storage model
|
|
- client reconnect/heartbeat behavior
|
|
- client implementation tasks
|
|
|
|
---
|
|
|
|
## 10. Development Flow
|
|
|
|
Recommended flow:
|
|
1. define cross-cutting behavior in `Yonexus`
|
|
2. split actionable work into `Yonexus.Server` and `Yonexus.Client`
|
|
3. implement server-side protocol handling in `Yonexus.Server`
|
|
4. implement client-side protocol handling in `Yonexus.Client`
|
|
5. keep protocol changes synchronized back into umbrella docs
|
|
|
|
---
|
|
|
|
## 11. Immediate Next Documents
|
|
|
|
After this architecture file, the next documents to maintain are:
|
|
- `Yonexus.Server/PLAN.md`
|
|
- `Yonexus.Client/PLAN.md`
|
|
- optionally later:
|
|
- `Yonexus.Server/README.md`
|
|
- `Yonexus.Client/README.md`
|
|
- server/client task breakdown docs
|
|
|
|
---
|
|
|
|
## 12. Non-Goals of the Umbrella Repo
|
|
|
|
The umbrella repo should avoid becoming:
|
|
- the only place where implementation changes happen
|
|
- a dumping ground for server-only details
|
|
- a dumping ground for client-only details
|
|
- a duplicate of submodule READMEs without system-level value
|
|
|
|
Its job is coordination, not code concentration.
|