add project plan
This commit is contained in:
root
416
PLAN.md
Normal file
416
PLAN.md
Normal file
@@ -0,0 +1,416 @@
|
||||
# Yonexus.Client — Project Plan
|
||||
|
||||
## 1. Goal
|
||||
|
||||
`Yonexus.Client` is the OpenClaw plugin that acts as a client in a Yonexus network.
|
||||
|
||||
It is responsible for:
|
||||
- connecting to `Yonexus.Server`
|
||||
- managing local keypair and secret
|
||||
- completing the out-of-band pairing confirmation
|
||||
- authenticating on each reconnect
|
||||
- sending periodic heartbeats
|
||||
- exposing a TypeScript API for client-side plugins and integrations
|
||||
- sending and receiving application messages through the server
|
||||
|
||||
---
|
||||
|
||||
## 2. Configuration
|
||||
|
||||
```ts
|
||||
interface YonexusClientConfig {
|
||||
mainHost: string;
|
||||
identifier: string;
|
||||
notifyBotToken: string;
|
||||
adminUserId: string;
|
||||
}
|
||||
```
|
||||
|
||||
Field semantics:
|
||||
- `mainHost`: WebSocket endpoint of `Yonexus.Server` (`ws://host:port/path` or `wss://`)
|
||||
- `identifier`: unique identity of this client within the Yonexus network
|
||||
- `notifyBotToken`: Discord bot token (kept for potential future client-side notification needs)
|
||||
- `adminUserId`: Discord user id of the human administrator (reference/shared with Yonexus system)
|
||||
|
||||
Validation:
|
||||
- missing required fields must fail plugin initialization
|
||||
- `mainHost` must be a valid WebSocket URL
|
||||
- `identifier` must be non-empty
|
||||
|
||||
---
|
||||
|
||||
## 3. Runtime Lifecycle
|
||||
|
||||
### 3.1 Startup
|
||||
|
||||
On OpenClaw gateway startup:
|
||||
1. load and validate config
|
||||
2. load local identity, keypair, and secret from persistent storage
|
||||
3. if no keypair exists, generate one
|
||||
4. connect to `mainHost`
|
||||
5. start pairing or authentication flow depending on local state
|
||||
6. after authentication, start heartbeat schedule
|
||||
7. handle incoming messages and rule dispatch
|
||||
|
||||
### 3.2 Reconnect
|
||||
|
||||
On disconnect:
|
||||
1. stop heartbeat
|
||||
2. enter `reconnecting` state
|
||||
3. attempt reconnect with backoff
|
||||
4. after reconnect, perform authentication or pairing again
|
||||
|
||||
---
|
||||
|
||||
## 4. Local Identity and Storage
|
||||
|
||||
### 4.1 Keypair
|
||||
|
||||
`Yonexus.Client` must generate a cryptographic keypair on first run.
|
||||
|
||||
Recommended algorithm: Ed25519
|
||||
- private key: never transmitted to server
|
||||
- public key: transmitted to server during pairing and optionally during auth
|
||||
|
||||
### 4.2 Local Persistence Model
|
||||
|
||||
```ts
|
||||
interface LocalClientState {
|
||||
identifier: string;
|
||||
privateKey: string; // encoded private key, stored locally
|
||||
publicKey: string; // encoded public key
|
||||
secret?: string; // shared secret issued by server after pairing
|
||||
pairingStatus: "unpaired" | "pending" | "paired" | "revoked";
|
||||
pairedAt?: number;
|
||||
lastConnectedAt?: number;
|
||||
}
|
||||
```
|
||||
|
||||
### 4.3 Security Notes
|
||||
|
||||
- private key must never leave the local instance
|
||||
- storage format should make encryption-at-rest a future option
|
||||
- initial implementation may use plaintext local file if documented as a limitation
|
||||
|
||||
---
|
||||
|
||||
## 5. Pairing Flow
|
||||
|
||||
### 5.1 Entry Condition
|
||||
|
||||
Pairing starts when:
|
||||
- the server responds to `hello` with `hello_ack(nextAction: "pair_required")`
|
||||
- OR the server sends `pair_request` builtin message
|
||||
|
||||
### 5.2 Step A — Receive Notification
|
||||
|
||||
Client receives `pair_request` from server via WebSocket.
|
||||
|
||||
This message contains:
|
||||
- `expiresAt`
|
||||
- `ttlSeconds`
|
||||
- `adminNotification`
|
||||
- `codeDelivery: "out_of_band"`
|
||||
|
||||
### 5.3 Step B — Human-Mediated Code Acquisition
|
||||
|
||||
The pairing code is delivered to a human administrator via Discord DM from the server.
|
||||
|
||||
The client operator must obtain this code from the human through some out-of-band trusted path.
|
||||
|
||||
This is intentionally not automated — a human must relay the code.
|
||||
|
||||
### 5.4 Step C — Submit Confirmation
|
||||
|
||||
Client sends `pair_confirm` builtin message to server:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "pair_confirm",
|
||||
"payload": {
|
||||
"identifier": "<this-client-identifier>",
|
||||
"pairingCode": "<human-provided-code>"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 5.5 Step D — Receive Secret
|
||||
|
||||
On success, server sends `pair_success` containing:
|
||||
- `identifier`
|
||||
- `secret`
|
||||
- `pairedAt`
|
||||
|
||||
Client must:
|
||||
- store `secret` locally
|
||||
- update `pairingStatus` to `paired`
|
||||
- store `pairedAt`
|
||||
|
||||
### 5.6 Failure Handling
|
||||
|
||||
If server responds with `pair_failed`:
|
||||
- log the reason
|
||||
- return to `pairing_required` state
|
||||
- wait for human to provide a new code and retry
|
||||
|
||||
---
|
||||
|
||||
## 6. Authentication
|
||||
|
||||
### 6.1 Entry Condition
|
||||
|
||||
Authentication starts when:
|
||||
- client connects and already has a stored `secret`
|
||||
- server responds to `hello` with `hello_ack(nextAction: "auth_required")`
|
||||
|
||||
### 6.2 Proof Construction
|
||||
|
||||
Client constructs a proof payload from:
|
||||
- `secret`: stored shared secret
|
||||
- `nonce`: exactly 24 random characters, generated fresh each attempt
|
||||
- `timestamp`: current UTC unix seconds
|
||||
|
||||
Logical concatenation:
|
||||
|
||||
```text
|
||||
secret + nonce + timestamp
|
||||
```
|
||||
|
||||
Implementation recommendation:
|
||||
- use a canonical serialized object, then sign its canonical bytes
|
||||
- avoid naive string concatenation in code
|
||||
|
||||
Example canonical JSON:
|
||||
|
||||
```json
|
||||
{
|
||||
"secret": "...",
|
||||
"nonce": "RANDOM24CHARACTERSTRINGX",
|
||||
"timestamp": 1711886500
|
||||
}
|
||||
```
|
||||
|
||||
### 6.3 Signing
|
||||
|
||||
Client signs the canonical proof bytes using its private key.
|
||||
|
||||
### 6.4 Sending Auth Request
|
||||
|
||||
Client sends `auth_request` builtin message:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "auth_request",
|
||||
"payload": {
|
||||
"identifier": "<this-client-identifier>",
|
||||
"nonce": "<24-char-nonce>",
|
||||
"proofTimestamp": 1711886500,
|
||||
"signature": "<base64-signature>"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 6.5 Response Handling
|
||||
|
||||
On `auth_success`:
|
||||
- record `lastAuthenticatedAt`
|
||||
- transition to `authenticated` state
|
||||
- start heartbeat loop
|
||||
|
||||
On `auth_failed`:
|
||||
- log the reason
|
||||
- handle according to reason:
|
||||
- `stale_timestamp` / `future_timestamp`: retry with fresh timestamp
|
||||
- `nonce_collision`: retry with fresh nonce
|
||||
- others: escalate to re-pairing if needed
|
||||
|
||||
On `re_pair_required`:
|
||||
- clear stored `secret` and public key trust
|
||||
- transition to `pairing_required`
|
||||
- begin pairing flow again
|
||||
|
||||
---
|
||||
|
||||
## 7. Heartbeat
|
||||
|
||||
### 7.1 Sending
|
||||
|
||||
After successful authentication, client starts a heartbeat loop.
|
||||
|
||||
Interval: every 5 minutes (300 seconds)
|
||||
|
||||
Message: `heartbeat` builtin message with `status: "alive"`.
|
||||
|
||||
### 7.2 Handling heartbeat_ack
|
||||
|
||||
If server responds with `heartbeat_ack`, client may:
|
||||
- update local connection metadata
|
||||
- optionally log
|
||||
|
||||
`heartbeat_ack` is optional on the server side; client should not fail if it is absent.
|
||||
|
||||
### 7.3 On Disconnect
|
||||
|
||||
When WebSocket connection is lost:
|
||||
- stop heartbeat loop immediately
|
||||
- enter `reconnecting` state
|
||||
- attempt reconnect with backoff
|
||||
|
||||
---
|
||||
|
||||
## 8. Messaging and Rule Dispatch
|
||||
|
||||
### 8.1 Outbound: sendMessageToServer
|
||||
|
||||
```ts
|
||||
async function sendMessageToServer(message: string): Promise<void>
|
||||
```
|
||||
|
||||
Constraints:
|
||||
- client must be authenticated / connected
|
||||
- message must already conform to `${rule_identifier}::${message_content}`
|
||||
|
||||
### 8.2 Inbound: Rule Dispatch
|
||||
|
||||
Client receives messages from server formatted as:
|
||||
|
||||
```
|
||||
${rule_identifier}::${message_content}
|
||||
```
|
||||
|
||||
Client maintains its own rule registry (separate from server's).
|
||||
|
||||
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 registerRule API
|
||||
|
||||
```ts
|
||||
function registerRule(rule: string, processor: (message: string) => unknown): void
|
||||
```
|
||||
|
||||
Validation:
|
||||
- must reject `builtin`
|
||||
- must reject duplicate rule unless explicit override mode is added later
|
||||
|
||||
---
|
||||
|
||||
## 9. WebSocket Client
|
||||
|
||||
### 9.1 Connection
|
||||
|
||||
Client connects to `mainHost` on startup and on each reconnect.
|
||||
|
||||
### 9.2 First Message: hello
|
||||
|
||||
Immediately after connection opens, client sends `hello`:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "hello",
|
||||
"payload": {
|
||||
"identifier": "<this-client-identifier>",
|
||||
"hasSecret": true,
|
||||
"hasKeyPair": true,
|
||||
"publicKey": "<current-public-key>",
|
||||
"protocolVersion": "1"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Fields:
|
||||
- `hasSecret`: whether a secret is stored locally
|
||||
- `hasKeyPair`: always `true` after first key generation
|
||||
- `publicKey`: current public key (required after keypair generation)
|
||||
|
||||
### 9.3 Reconnect Backoff Strategy
|
||||
|
||||
Recommended initial strategy:
|
||||
- first retry: 1 second
|
||||
- subsequent retries: multiply by 2, cap at 60 seconds
|
||||
- jitter: add random 0–1s to avoid thundering herd
|
||||
|
||||
---
|
||||
|
||||
## 10. Error Handling
|
||||
|
||||
Structured errors required for at minimum:
|
||||
- `INVALID_CONFIG` — missing required config fields
|
||||
- `CONNECTION_FAILED` — cannot connect to `mainHost`
|
||||
- `PAIRING_FAILED` — server rejected pairing
|
||||
- `AUTH_FAILED` — server rejected auth proof
|
||||
- `RE_PAIR_REQUIRED` — server demands re-pairing
|
||||
- `RULE_ALREADY_REGISTERED` — duplicate rule registration
|
||||
- `RESERVED_RULE` — attempted to register `builtin`
|
||||
- `MALFORMED_MESSAGE` — malformed builtin/application message received
|
||||
- `NOT_AUTHENTICATED` — attempted to send before auth
|
||||
|
||||
---
|
||||
|
||||
## 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 Client
|
||||
- WebSocket client connection
|
||||
- hello message
|
||||
- reconnect with backoff
|
||||
- connection close lifecycle
|
||||
|
||||
### Phase 2 — Local Identity
|
||||
- keypair generation (Ed25519)
|
||||
- local state persistence
|
||||
- state load on startup
|
||||
|
||||
### Phase 3 — Pairing
|
||||
- handle `pair_request`
|
||||
- accept human-provided pairing code
|
||||
- submit `pair_confirm`
|
||||
- store `secret` on `pair_success`
|
||||
- handle `pair_failed`
|
||||
|
||||
### Phase 4 — Authentication
|
||||
- proof construction
|
||||
- signing
|
||||
- send `auth_request`
|
||||
- handle `auth_success`
|
||||
- handle `auth_failed`
|
||||
- handle `re_pair_required`
|
||||
|
||||
### Phase 5 — Heartbeat
|
||||
- heartbeat loop (5 min interval)
|
||||
- heartbeat message construction
|
||||
- handle `heartbeat_ack`
|
||||
- stop loop on disconnect
|
||||
|
||||
### Phase 6 — Rule Dispatch and APIs
|
||||
- rule registry
|
||||
- inbound message dispatch
|
||||
- `registerRule` API
|
||||
- `sendMessageToServer` API
|
||||
|
||||
### Phase 7 — Hardening
|
||||
- structured error definitions
|
||||
- redacted logging for sensitive values
|
||||
- integration test coverage
|
||||
- failure-path coverage
|
||||
|
||||
---
|
||||
|
||||
## 12. Open Questions for Yonexus.Client
|
||||
|
||||
These should be resolved before or during implementation:
|
||||
|
||||
1. What cryptographic library will be used for Ed25519 keypair and signing?
|
||||
2. Should `notifyBotToken` and `adminUserId` be retained in client config, or are they purely server-side concerns?
|
||||
3. Should reconnect backoff be configurable or fixed?
|
||||
4. Should the client maintain a local log of recent sent/received messages for debugging?
|
||||
5. Should `sendMessageToServer` throw if called before authentication, or queue the message?
|
||||
Reference in New Issue
Block a user