add implementation task breakdown

TASKS.md

@@ -0,0 +1,180 @@
+# 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