Yonexus/FEAT.md

Yonexus — Feature Checklist

Project Direction

Yonexus is a two-plugin cross-instance communication system for OpenClaw:

• Yonexus.Server
• Yonexus.Client

This repository now targets the split-plugin architecture only.

---

Shared Terminology and v1 Scope

Canonical terms used across the project:

• identifier: unique logical client name
• rule_identifier: exact-match application route key
• builtin: reserved protocol/system route namespace
• pairingCode: short-lived out-of-band pairing code
• secret: shared secret issued after pairing
• publicKey / privateKey: client signing keypair

Locked v1 decisions:

• heartbeat_ack is optional
• client reconnect uses exponential backoff
• rule matching is exact-match only
• offline sends fail immediately instead of queueing
• mainHost is expected to be a full ws:// or wss:// URL

Explicit v1 non-goals:

• multi-server topology
• direct client-to-client sockets
• offline queueing guarantees
• advanced rule matching
• management UI
• admin approval control plane beyond human relay of pairing codes

---

1. Yonexus.Server Features

1.1 Server Runtime

• WebSocket server startup on OpenClaw gateway boot
• Configurable bind host / bind port
• Optional public WebSocket URL metadata
• Connection accept / close lifecycle handling
• One active authenticated connection per client identifier

1.2 Client Registry

• In-memory active client session registry
• Persistent client trust registry keyed by identifier
• Store client public key
• Store shared secret
• Store pairing state and expiry
• Store pairing notification metadata
• Store heartbeat timestamps
• Store recent security windows (nonce / handshake attempts)
• Store liveness state (online | unstable | offline)

1.3 Allowlist and Validation

• followerIdentifiers allowlist enforcement
• Reject unknown client identifiers
• Reject malformed builtin payloads
• Reject unsupported protocol versions

1.4 Pairing Flow

• Generate pairing code
• Generate pairing expiry / TTL
• Start pending pairing session
• Never send pairing code over Yonexus WebSocket
• Send pairing code to human admin via Discord DM using notifyBotToken
• Include target client identifier in pairing DM
• Accept client-submitted pairing code via builtin protocol
• Fail pairing on invalid code / expired code / notification failure
• Issue shared secret after successful pairing
• Persist paired trust material

1.5 Authentication

• Verify signed proof from client
• Validate stored secret
• Validate nonce format and uniqueness
• Validate timestamp drift < 10s
• Track recent handshake attempts
• Enforce >10 attempts / 10s unsafe threshold
• Trigger re-pair on unsafe condition
• Rotate or invalidate trust state when required

1.6 Heartbeat and Status

• Receive heartbeat from authenticated clients
• Update lastHeartbeatAt
• Mark client unstable after 7 minutes without heartbeat
• Mark client offline after 11 minutes without heartbeat
• Close socket when client becomes offline
• Optional heartbeat acknowledgement
• Periodic server-side status sweep timer

1.7 Messaging and Dispatch

• sendMessageToClient(identifier, message) API
• Rewrite inbound client messages to ${rule_identifier}::${sender_identifier}::${message_content}
• Builtin message routing
• Rule registry for application messages
• First-match rule dispatch
• Reject reserved rule builtin
• Reject duplicate rule registration by default

1.8 Operations and Safety

• Structured errors for pairing/auth/transport failures
• Redacted logging for sensitive values
• Restart-safe persistent storage for trust state
• Clear or safely rebuild rolling security windows on restart

---

2. Yonexus.Client Features

2.1 Client Runtime

• WebSocket client startup on OpenClaw gateway boot
• Connect to configured mainHost
• Disconnect / reconnect lifecycle handling
• Retry/backoff reconnect strategy

2.2 Local Identity and Trust Material

• Persist local identifier
• Generate public/private keypair on first run
• Persist private key locally
• Persist server-issued secret locally
• Load existing trust material on restart

2.3 Pairing Flow

• Send hello after connect
• Enter pairing mode when server requires pairing
• Receive pairing metadata without receiving code itself
• Accept human-provided pairing code on client side
• Send pairing confirmation to server
• Store secret after pair_success

2.4 Authentication

• Build proof from secret + nonce + timestamp
• Prefer canonical serialized payload for signing
• Sign proof with local private key
• Send builtin auth_request
• Handle auth_success
• Handle auth_failed
• Handle re_pair_required

2.5 Heartbeat

• Start heartbeat loop after authentication
• Send heartbeat every 5 minutes
• Stop heartbeat when disconnected / unauthenticated
• Handle optional heartbeat acknowledgement

2.6 Messaging and Dispatch

• sendMessageToServer(message) API
• Builtin message routing
• Rule registry for application messages
• First-match rule dispatch
• Reject reserved rule builtin
• Reject duplicate rule registration by default

---

3. Shared Protocol Features

3.1 Builtin Wire Format

• builtin::{json} message format
• Standard builtin envelope with type, requestId, timestamp, payload
• UTC unix seconds as protocol timestamp unit

3.2 Builtin Types

• hello
• hello_ack
• pair_request
• pair_confirm
• pair_success
• pair_failed
• auth_request
• auth_success
• auth_failed
• re_pair_required
• heartbeat
• heartbeat_ack
• status_update
• disconnect_notice
• error

3.3 Security Constraints

• Pairing code must be delivered out-of-band only
• Pairing code must not travel over Yonexus WebSocket
• Nonce length fixed at 24 random characters
• Nonce replay detection window
• Timestamp freshness validation
• Rate-limit / unsafe reconnect detection

3.4 Rule Message Format

• Application messages use ${rule_identifier}::${message_content}
• Server rewrites inbound client messages before dispatch
• Rule matching is exact-match in v1

---

4. Configuration Features

4.1 Yonexus.Server Config

• followerIdentifiers: string[]
• notifyBotToken: string
• adminUserId: string
• listenHost?: string
• listenPort: number
• publicWsUrl?: string

4.2 Yonexus.Client Config

• mainHost: string
• identifier: string
• notifyBotToken: string
• adminUserId: string

4.3 Validation

• Fail startup on missing required fields
• Fail startup on invalid config shape
• Validate required split-plugin semantics per side

---

5. Docs and Deliverables

Required Planning / Spec Docs

• PLAN.md
• PROTOCOL.md
• FEAT.md

Next Implementation Deliverables

• server plugin manifest
• client plugin manifest
• README for dual-plugin architecture
• implementation task breakdown
• protocol test cases
• pairing/auth failure-path test matrix

---

6. Suggested Delivery Order

Phase 0 — Planning

• Rewrite project direction
• Define split-plugin model
• Write protocol draft
• Write feature checklist

Phase 1 — Skeleton

• Create Yonexus.Server plugin scaffold
• Create Yonexus.Client plugin scaffold
• Add config schema / manifests
• Add minimal startup hooks

Phase 2 — Transport

• Implement WebSocket server
• Implement WebSocket client
• Implement hello / hello_ack flow
• Implement reconnect baseline

Phase 3 — Pairing and Auth

• Implement keypair generation
• Implement pairing creation
• Implement Discord DM notification
• Implement pairing confirmation
• Implement secret issuance
• Implement signed auth proof validation
• Implement nonce and rate-limit protection

Phase 4 — Heartbeat and Messaging

• Implement heartbeat loop
• Implement server status sweep
• Implement sendMessageToServer
• Implement sendMessageToClient
• Implement rule registry and dispatch

Phase 5 — Hardening

• Add persistence
• Add restart recovery behavior
• Add structured errors
• Add logging/redaction
• Add integration tests
• Add operator docs

---

7. Non-Goals

Not in initial scope unless explicitly added later:

• direct client-to-client sockets
• multi-server topology
• distributed consensus
• queueing guarantees for offline clients
• management UI
• advanced pattern matching for rules