Yonexus.Server/README.md

Yonexus.Server

Yonexus.Server is the central hub plugin for a Yonexus network.

It runs on the main OpenClaw instance and is responsible for:

• accepting WebSocket connections from follower instances
• enforcing the followerIdentifiers allowlist
• driving pairing and authenticated reconnects
• tracking heartbeat/liveness state
• rewriting inbound client rule messages before dispatch
• sending pairing notifications to the human admin via Discord DM

Status

Current state: core runtime MVP with Discord DM transport wired via REST API

Implemented in this repository today:

• config validation
• runtime lifecycle wiring
• JSON persistence for durable trust records
• WebSocket transport and single-active-connection promotion model
• pairing session creation
• auth proof validation flow
• heartbeat receive + liveness sweep
• rule registry + send-to-client APIs
• Discord DM pairing notifications via Discord REST API (notifyBotToken + adminUserId)

Still pending before production use:

• broader lifecycle integration with real OpenClaw plugin hooks
• more operator-facing hardening / troubleshooting polish
• expanded edge-case and live-environment validation beyond the current automated suite

Install Layout

This repo expects the shared protocol repo to be available at:

protocol/

In the umbrella repo this is managed as a submodule.

Configuration

Required config shape:

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

Field notes

• followerIdentifiers: allowlisted client identifiers
• notifyBotToken: bot token used for pairing notifications
• adminUserId: Discord user that receives pairing DMs
• listenHost: optional bind host, defaults to local runtime handling
• listenPort: required WebSocket listen port
• publicWsUrl: optional public endpoint to document/share with clients

Runtime Overview

Startup flow:

1. validate config
2. load persisted trust records
3. ensure allowlisted identifiers have base records
4. start WebSocket transport
5. start liveness sweep timer

Connection flow:

1. unauthenticated socket connects
2. client sends hello
3. server decides pair_required, waiting_pair_confirm, or auth_required
4. if needed, server creates a pending pairing request and notifies admin out-of-band
5. client confirms pairing or authenticates with signed proof
6. authenticated connection is promoted to the active session for that identifier

Public API Surface

Exported runtime helpers currently include:

sendMessageToClient(identifier: string, message: string): Promise<boolean>
sendRuleMessageToClient(identifier: string, ruleIdentifier: string, content: string): Promise<boolean>
registerRule(rule: string, processor: (message: string) => unknown): void

Rules:

• builtin is reserved and cannot be registered
• server-side dispatch expects rewritten client-originated messages in the form:

${rule_identifier}::${sender_identifier}::${message_content}

Persistence

Durable state is stored as JSON and includes at least:

• identifier
• pairing status
• public key
• secret
• pairing metadata
• heartbeat / auth timestamps
• last known liveness status

Rolling nonce and handshake windows are intentionally rebuilt on restart in v1.

Development

Install dependencies and run type checks:

npm install
npm run check

Limitations

Current known limitations:

• DM delivery depends on Discord bot permissions and the target user's DM settings
• no offline message queueing
• no multi-server topology
• no management UI
• transport is covered mainly by automated tests rather than live Discord end-to-end validation

Related Repos

• Umbrella: ../
• Shared protocol: ../Yonexus.Protocol
• Client plugin: ../Yonexus.Client