# 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