define split yonexus server/client architecture

FEAT.md

@@ -0,0 +1,268 @@
+# 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.
+
+---
+
+## 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
+- [x] Rewrite project direction
+- [x] Define split-plugin model
+- [x] Write protocol draft
+- [x] 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