Yonexus.Server/PLAN.md

# Yonexus.Server — Project Plan

## 1. Goal

`Yonexus.Server` is the OpenClaw plugin that acts as the central communication hub in a Yonexus network.

This repository references `Yonexus.Protocol` as a submodule at `protocol/`.

It is responsible for:
- accepting WebSocket connections from clients
- maintaining the client registry and trust state
- handling pairing initiation and Discord DM notification
- verifying client authentication proofs
- tracking client liveness via heartbeat
- routing and dispatching application messages
- exposing a TypeScript API for server-side plugins and integrations

---

## 2. Configuration

```ts
interface YonexusServerConfig {
  followerIdentifiers: string[];
  notifyBotToken: string;
  adminUserId: string;
  listenHost?: string;
  listenPort: number;
  publicWsUrl?: string;
}
```

Field semantics:
- `followerIdentifiers`: allowlist of identifiers permitted to pair/connect
- `notifyBotToken`: Discord bot token for sending pairing code DM to admin
- `adminUserId`: Discord user id of the human administrator
- `listenHost`: local bind address (default: `0.0.0.0`)
- `listenPort`: local bind port (required)
- `publicWsUrl`: optional canonical external WebSocket URL advertised to clients

Validation:
- missing required fields must fail plugin initialization
- identifiers not in `followerIdentifiers` must be rejected at connection time

---

## 3. Runtime Lifecycle

### 3.1 Startup

On OpenClaw gateway startup:
1. load and validate config
2. initialize persistent client registry
3. register builtin protocol handlers
4. register application rule registry
5. start WebSocket server on configured host/port
6. start heartbeat/status sweep timer

### 3.2 Shutdown

On shutdown:
1. close all client WebSocket connections gracefully
2. persist client registry state
3. stop sweep timers

---

## 4. Client Registry

### 4.1 Data Model

```ts
interface ClientRecord {
  identifier: string;
  publicKey?: string;
  secret?: string;
  pairingStatus: "unpaired" | "pending" | "paired" | "revoked";
  pairingCode?: string;
  pairingExpiresAt?: number;
  pairingNotifiedAt?: number;
  pairingNotifyStatus?: "pending" | "sent" | "failed";
  status: "online" | "offline" | "unstable";
  lastHeartbeatAt?: number;
  lastAuthenticatedAt?: number;
  recentNonces: Array<{ nonce: string; timestamp: number }>;
  recentHandshakeAttempts: number[];
  createdAt: number;
  updatedAt: number;
}
```

### 4.2 Persistence

Registry must survive server restarts:
- all trust-related fields must be persisted
- security rolling windows should be reset on restart or kept safely
- on-disk storage format should support future encryption-at-rest

---

## 5. Pairing Flow

### 5.1 Entry Condition

Pairing starts when a client connects and:
- its identifier is in `followerIdentifiers`
- it has no valid `secret` stored

### 5.2 Step A — Generate Pairing Code

Server generates:
- a random `pairingCode`
- `expiresAt` (UTC unix seconds)
- `ttlSeconds`

### 5.3 Step B — Discord DM to Admin

Server must use `notifyBotToken` to DM `adminUserId`.

DM body must contain:
- `identifier`
- `pairingCode`
- `expiresAt` or TTL

DM delivery must succeed before protocol continues.

### 5.4 Step C — Protocol Notification to Client

Server sends `hello_ack` with `nextAction: "pair_required"`.

Server then sends `pair_request` builtin message containing:
- `identifier`
- `expiresAt`
- `ttlSeconds`
- `adminNotification: "sent" | "failed"`
- `codeDelivery: "out_of_band"`

### 5.5 Step D — Accept Confirmation

Server accepts a `pair_confirm` builtin message from client containing the pairing code.

Validation:
- code must match stored pending code
- current time must be before `pairingExpiresAt`

### 5.6 Step E — Issue Secret

On successful confirmation:
- generate a random `secret`
- store `publicKey` and `secret`
- mark `pairingStatus` as `paired`
- send `pair_success` builtin message to client with the secret

On failure:
- send `pair_failed` builtin message
- optionally retry or leave for client to reconnect

---

## 6. Authentication

### 6.1 Entry Condition

Authentication starts when a connected client sends a `hello` with `hasSecret: true`.

### 6.2 Proof Validation

Client sends `auth_request` containing:
- `identifier`
- `nonce` (24 random characters)
- `proofTimestamp` (UTC unix seconds)
- `signature` (signed proof payload)
- optionally a new `publicKey` if rotating

Server validates:
1. identifier is allowlisted and paired
2. public key matches stored key (if not rotating)
3. signature verifies correctly
4. decrypted proof contains the correct `secret`
5. `abs(now - proofTimestamp) < 10`
6. nonce is not in recent nonce window
7. handshake attempts in last 10s ≤ 10

### 6.3 Nonce Window

Store last 10 nonces per client with their timestamps.

When a nonce is presented:
- if it matches any in the window, reject with `nonce_collision`
- add the new nonce to the window
- trim window to most recent 10 entries

### 6.4 Handshake Rate Limit

Track recent handshake attempt timestamps per client.

If >10 attempts appear in the last 10 seconds:
- reject with `rate_limited`
- trigger `re_pair_required`
- mark pairing status as `revoked`

### 6.5 Success / Failure Responses

On success:
- send `auth_success` with `status: "online"`
- record `lastAuthenticatedAt`

On failure:
- send `auth_failed` with reason
- if reason is unsafe, also send `re_pair_required`

---

## 7. Heartbeat and Liveness

### 7.1 Heartbeat Reception

Clients send `heartbeat` builtin messages every 5 minutes.

On receiving a heartbeat:
- update `lastHeartbeatAt`
- if client was `offline` or `unstable`, transition to `online`

### 7.2 Status Sweep

Server runs a periodic sweep (recommended: every 30–60s).

For each registered client:
- if no heartbeat for 7 min → mark `unstable`
- if no heartbeat for 11 min → mark `offline`, close socket, send `disconnect_notice` first

### 7.3 Status Transitions

Allowed transitions:
- `online` → `unstable` (7 min timeout)
- `unstable` → `online` (heartbeat received)
- `unstable` → `offline` (11 min timeout)
- `offline` → (removed from active registry or marked offline permanently)

---

## 8. Messaging and Rule Dispatch

### 8.1 Message Rewrite

When server receives an application rule message from a client, before rule dispatch it rewrites:

```
${rule_identifier}::${message_content}
```

Into:

```
${rule_identifier}::${sender_identifier}::${message_content}
```

### 8.2 Rule Registry

Server maintains a registry of `(rule_identifier → processor)` pairs.

Dispatch algorithm:
1. parse first `::` segment as `rule_identifier`
2. if `rule_identifier === builtin`, route to builtin protocol handler
3. iterate registered rules in registration order
4. invoke first exact match
5. if no match, ignore or log as unhandled

### 8.3 Processor Function Signature

```ts
type RuleProcessor = (message: string) => unknown;
registerRule(rule: string, processor: RuleProcessor): void;
```

Validation:
- must reject `builtin`
- must reject duplicate rule unless explicit override mode is added later

### 8.4 API: sendMessageToClient

```ts
async function sendMessageToClient(identifier: string, message: string): Promise<void>
```

Constraints:
- identifier must be currently connected and authenticated
- message must already conform to `${rule_identifier}::${message_content}`
- throws if identifier is not online

---

## 9. WebSocket Server

### 9.1 Connection Accept

On new WebSocket connection:
1. read initial `hello` message
2. validate identifier is in allowlist
3. check if paired/authenticated or requires pairing
4. proceed accordingly

### 9.2 Connection Close

On client disconnect:
- mark client as offline immediately
- stop heartbeat tracking for that session
- keep persistent registry state intact

### 9.3 One Active Session Per Identifier

Recommended v1 policy:
- if a new authenticated connection appears for an already-authenticated identifier, terminate the old connection and accept the new one

---

## 10. Error Handling

Structured errors required for at minimum:
- `INVALID_CONFIG` — missing required config fields
- `IDENTIFIER_NOT_ALLOWED` — identifier not in allowlist
- `PAIRING_NOTIFICATION_FAILED` — Discord DM send failed
- `PAIRING_EXPIRED` — pairing code expired
- `AUTH_FAILED` — proof verification failed
- `NONCE_COLLISION` — replay detected
- `RATE_LIMITED` — unsafe handshake rate
- `RE_PAIR_REQUIRED` — trust must be reset
- `CLIENT_OFFLINE` — attempted to send to offline client
- `RULE_ALREADY_REGISTERED` — duplicate rule registration
- `RESERVED_RULE` — attempted to register `builtin`
- `MALFORMED_MESSAGE` — malformed builtin/application message

---

## 11. Implementation Phases

### Phase 0 — Skeleton
- plugin manifest and entry point
- config loading and validation
- basic OpenClaw hook registration
- minimal logging/error scaffolding

### Phase 1 — WebSocket Server
- WebSocket server startup
- connection accept / close lifecycle
- hello / hello_ack flow
- per-connection state tracking

### Phase 2 — Registry and Persistence
- in-memory client registry
- on-disk persistence (JSON or equivalent)
- restart recovery
- basic CRUD for client records

### Phase 3 — Pairing
- pairing code generation
- Discord DM via bot token
- pair_request / pair_confirm / pair_success / pair_failed
- pairing state transitions

### Phase 4 — Authentication
- auth_request verification
- signature verification
- nonce window tracking
- handshake rate limiting
- re_pair_required flow

### Phase 5 — Heartbeat and Status
- heartbeat receiver
- status sweep timer
- online / unstable / offline transitions
- disconnect_notice before socket close

### Phase 6 — Rule Dispatch and APIs
- rule registry
- message rewrite on inbound
- first-match dispatch
- `registerRule` API
- `sendMessageToClient` API

### Phase 7 — Hardening
- structured error definitions
- redacted logging for sensitive values
- integration test coverage
- failure-path coverage

---

## 12. Open Questions for Yonexus.Server

These should be resolved before or during implementation:

1. What Discord library/module will be used to send DM? (direct Discord API / discord.js / etc.)
2. Should the WebSocket server also expose an optional TLS listener?
3. Should the sweep timer interval be configurable or fixed?
4. What is the maximum supported number of concurrent connected clients?
5. Should server-side rule processors run in isolated contexts?
6. Should `sendMessageToClient` queue messages for briefly offline clients, or fail immediately?