181 lines
5.5 KiB
Markdown
181 lines
5.5 KiB
Markdown
# Yonexus.Server — Implementation Tasks
|
|
|
|
This document breaks the server-side work into actionable tasks.
|
|
|
|
## Phase 0 — Repository Skeleton
|
|
|
|
- [ ] Create required directories:
|
|
- [ ] `plugin/`
|
|
- [ ] `plugin/core/`
|
|
- [ ] `plugin/hooks/`
|
|
- [ ] `plugin/commands/`
|
|
- [ ] `plugin/tools/`
|
|
- [ ] `skills/`
|
|
- [ ] `servers/`
|
|
- [ ] `scripts/`
|
|
- [ ] Create required files:
|
|
- [ ] `plugin/index.ts`
|
|
- [ ] `plugin/openclaw.plugin.json`
|
|
- [ ] `scripts/install.mjs`
|
|
- [ ] Keep `protocol/` submodule intact and documented
|
|
|
|
## Phase 1 — Manifest and Entry Wiring
|
|
|
|
- [ ] Write initial `plugin/openclaw.plugin.json`
|
|
- [ ] Define server config defaults
|
|
- [ ] Add config validation for:
|
|
- [ ] `followerIdentifiers`
|
|
- [ ] `notifyBotToken`
|
|
- [ ] `adminUserId`
|
|
- [ ] `listenHost`
|
|
- [ ] `listenPort`
|
|
- [ ] `publicWsUrl`
|
|
- [ ] Implement `plugin/index.ts` as wiring-only entrypoint
|
|
- [ ] Register hooks / commands / tools from `plugin/index.ts`
|
|
|
|
## Phase 2 — Core Runtime Foundation
|
|
|
|
- [ ] Implement structured error definitions in `plugin/core/errors.ts`
|
|
- [ ] Implement config loader / validator
|
|
- [ ] Implement runtime container/bootstrap module
|
|
- [ ] Define shared server-side types:
|
|
- [ ] client record
|
|
- [ ] active session
|
|
- [ ] pairing state
|
|
- [ ] heartbeat status
|
|
|
|
## Phase 3 — WebSocket Service Layer
|
|
|
|
- [ ] Implement `servers/wsServer.ts`
|
|
- [ ] Bind WebSocket server to configured host/port
|
|
- [ ] Handle connection open/close lifecycle
|
|
- [ ] Parse inbound text frames
|
|
- [ ] Route raw inbound frames toward protocol/application dispatch
|
|
- [ ] Implement `servers/sessionManager.ts`
|
|
- [ ] Enforce one active session per identifier
|
|
- [ ] Replace old session on new authenticated connection
|
|
|
|
## Phase 4 — Registry and Persistence
|
|
|
|
- [ ] Implement `plugin/core/registry.ts`
|
|
- [ ] Add in-memory registry for active and known clients
|
|
- [ ] Add persistence model for durable trust state
|
|
- [ ] Implement load-on-start behavior
|
|
- [ ] Implement save-on-change behavior
|
|
- [ ] Decide initial persistence format (likely JSON)
|
|
- [ ] Ensure sensitive fields are not logged in plaintext
|
|
|
|
## Phase 5 — Builtin Protocol Routing
|
|
|
|
- [ ] Implement builtin message parser
|
|
- [ ] Implement builtin envelope validation
|
|
- [ ] Route by builtin `type`
|
|
- [ ] Support at minimum:
|
|
- [ ] `hello`
|
|
- [ ] `pair_confirm`
|
|
- [ ] `auth_request`
|
|
- [ ] `heartbeat`
|
|
- [ ] Return structured error responses for malformed payloads
|
|
|
|
## Phase 6 — Pairing Flow
|
|
|
|
- [ ] Implement pairing code generation
|
|
- [ ] Implement pairing TTL / expiry
|
|
- [ ] Store pending pairing state in registry
|
|
- [ ] Implement Discord DM notification path using `notifyBotToken`
|
|
- [ ] Include `identifier` and pairing code in DM
|
|
- [ ] Return `pair_request` to client without leaking pairing code
|
|
- [ ] Validate `pair_confirm`
|
|
- [ ] Implement `pair_success`
|
|
- [ ] Implement `pair_failed`
|
|
- [ ] Handle `admin_notification_failed`
|
|
|
|
## Phase 7 — Authentication Flow
|
|
|
|
- [ ] Implement proof verification logic in `plugin/core/auth.ts`
|
|
- [ ] Verify signature against stored public key
|
|
- [ ] Verify stored secret
|
|
- [ ] Verify timestamp freshness
|
|
- [ ] Implement nonce replay protection
|
|
- [ ] Implement handshake rate limiting
|
|
- [ ] Trigger `re_pair_required` on unsafe conditions
|
|
- [ ] Send `auth_success` on success
|
|
- [ ] Send `auth_failed` on failure
|
|
|
|
## Phase 8 — Heartbeat and Status
|
|
|
|
- [ ] Implement `plugin/core/heartbeat.ts`
|
|
- [ ] Update `lastHeartbeatAt` on valid heartbeat
|
|
- [ ] Start periodic sweep timer
|
|
- [ ] Mark clients `unstable` after 7 minutes
|
|
- [ ] Mark clients `offline` after 11 minutes
|
|
- [ ] Send `disconnect_notice` before forced close
|
|
- [ ] Close socket on offline transition
|
|
- [ ] Optionally send `heartbeat_ack`
|
|
|
|
## Phase 9 — Rule Dispatch and Messaging APIs
|
|
|
|
- [ ] Implement `plugin/core/dispatch.ts`
|
|
- [ ] Implement application message parse path
|
|
- [ ] Rewrite inbound client messages to include sender identifier
|
|
- [ ] Maintain rule registry
|
|
- [ ] Reject reserved rule `builtin`
|
|
- [ ] Reject duplicate rule registrations
|
|
- [ ] Implement `sendMessageToClient(identifier, message)`
|
|
- [ ] Fail cleanly when target client is offline
|
|
|
|
## Phase 10 — Hooks
|
|
|
|
- [ ] Implement `plugin/hooks/onGatewayStart.ts`
|
|
- [ ] Implement `plugin/hooks/onGatewayStop.ts`
|
|
- [ ] Ensure startup initializes runtime exactly once
|
|
- [ ] Ensure shutdown cleans up sockets/timers
|
|
|
|
## Phase 11 — Commands and Tools
|
|
|
|
### Commands
|
|
- [ ] `listClients`
|
|
- [ ] `showClient`
|
|
- [ ] `rePairClient`
|
|
|
|
### Tools
|
|
- [ ] `sendMessageToClient`
|
|
- [ ] `listClientStatus`
|
|
- [ ] `getPairingState`
|
|
|
|
## Phase 12 — Install Script
|
|
|
|
- [ ] Implement `scripts/install.mjs`
|
|
- [ ] Support `--install`
|
|
- [ ] Support `--uninstall`
|
|
- [ ] Support `--openclaw-profile-path <path>`
|
|
- [ ] Validate build output exists before install
|
|
- [ ] Copy runtime-ready files into plugin directory
|
|
|
|
## Phase 13 — Testing
|
|
|
|
- [ ] Unit tests for config validation
|
|
- [ ] Unit tests for builtin parsing
|
|
- [ ] Unit tests for pairing logic
|
|
- [ ] Unit tests for auth verification
|
|
- [ ] Unit tests for nonce/rate-limit protection
|
|
- [ ] Integration test: first-time pairing
|
|
- [ ] Integration test: reconnect auth
|
|
- [ ] Integration test: heartbeat timeout
|
|
- [ ] Integration test: offline disconnect
|
|
|
|
## Phase 14 — Hardening
|
|
|
|
- [ ] Redact secrets from logs
|
|
- [ ] Audit error messages for sensitive leakage
|
|
- [ ] Confirm persistence behavior across restart
|
|
- [ ] Review unsafe-condition handling
|
|
- [ ] Review operator-facing command/tool ergonomics
|
|
|
|
## Nice-to-Have / Later
|
|
|
|
- [ ] TLS listener support
|
|
- [ ] Better operator diagnostics
|
|
- [ ] Queued outbound delivery strategy
|
|
- [ ] Admin approve/deny workflow beyond code relay
|