Mimiclaw WebSocket Service

Single-file Node.js/TypeScript workforce communication service. Source code is in server.ts.

Features:

• WebSocket auth and role identity (boss / employee)
• Employee profile fields (name and tags[]) required at first registration
• Reconnect with identity recovery (id + key)
• Message routing between any connections
• Persistent storage with @seald-io/nedb for identities, connection events, and message logs
• HTTP admin APIs (list employees, connection status, ban/unban)
• pkg packaging support for single executable output

1) Install

cd websocket
npm install

Global install (after publish):

npm install -g mimiclaw-ws

When installed globally, postinstall will auto-create:

~/.mimiclaw-relay/

Global install from local folder:

cd websocket
npm install -g .

2) Build and run

npm run build
node dist/server.js --port 8787 --authkey your-secret

CLI mode (after npm install -g):

mimiclaw-ws 8787 your-secret

Equivalent flag form:

mimiclaw-ws --port 8787 --authkey your-secret

You can also pass auth key by env var:

MIMICLAW_AUTHKEY=your-secret mimiclaw-ws 8787

Optional args:

• --port: listening port, default 8787
• --host: listening host, default 0.0.0.0
• --ws-path: websocket path, default /ws
• --authkey: boss auth key (fallback to MIMICLAW_AUTHKEY)
• --data-dir: relay data dir (default ~/.mimiclaw-relay)
• positional args are also supported:
  • arg 1: port
  • arg 2: authkey
  • arg 3: data-dir

3) WebSocket auth protocol

First message after connect must be auth:

{
  "type": "auth",
  "role": "boss",
  "authkey": "your-secret"
}

First-time employee auth:

{
  "type": "auth",
  "role": "employee",
  "name": "Researcher-1",
  "tags": ["research", "solidity", "risk"]
}

name must be a non-empty string. tags must be a non-empty string array.

Reconnect with identity:

{
  "type": "auth",
  "role": "employee",
  "identity": {
    "id": "employee-xxxx",
    "key": "identity-key"
  }
}

Optional runtime health report message:

{
  "type": "health_report",
  "valid": true,
  "details": {
    "heartbeat": "ok"
  }
}

Server auth success response:

{
  "type": "auth_ok",
  "id": "employee-xxxx",
  "key": "identity-key",
  "role": "employee",
  "name": "Researcher-1",
  "tags": ["research", "solidity", "risk"],
  "reconnected": false,
  "timestamp": 1700000000000
}

4) Message envelope

Client send:

{
  "type": "message",
  "to": "employee-xxxx",
  "payload": {
    "task": "Analyze contract risk"
  }
}

to supports string or string array. Broadcast is supported with "*" or "all".

Server forwarded message always includes sender identity in top-level fields:

{
  "type": "message",
  "msg_id": "uuid",
  "from_id": "boss-xxxx",
  "from_role": "boss",
  "to": "employee-xxxx",
  "payload": {
    "task": "Analyze contract risk"
  },
  "timestamp": 1700000000000
}

Sender receives delivery ack:

{
  "type": "delivery_ack",
  "msg_id": "uuid",
  "delivered": ["employee-xxxx"],
  "failed": [],
  "timestamp": 1700000000000
}

5) HTTP admin APIs

Auth methods (write endpoints only):

• header: x-auth-key: your-secret
• query: ?authkey=your-secret

Endpoints:

• GET /health: health check (no auth required)
• GET /employees: list employees and online status (no auth required)
• GET /connections: list all identities (boss + employees) and statuses (no auth required)
• GET /admin/workforce: admin view with bosses, employees, tag grouping, and health details (no auth required)
• GET /admin/communications: admin comm logs for boss <-> employee messages (no auth required)
• POST /employees/:id/ban: ban employee (default banned=true)
• PUT /employees/:id/ban: ban/unban with body {"banned": true|false}
• DELETE /employees/:id/ban: unban employee

Examples:

curl "http://127.0.0.1:8787/employees"
curl "http://127.0.0.1:8787/connections"
curl "http://127.0.0.1:8787/admin/workforce"
curl "http://127.0.0.1:8787/admin/workforce?tag=research"
curl "http://127.0.0.1:8787/admin/communications?limit=100&offset=0"
curl "http://127.0.0.1:8787/admin/communications?boss_id=boss-xxx&employee_id=employee-yyy"
curl "http://127.0.0.1:8787/admin/communications?tag=solidity&since=1700000000000&until=1700009999999"
curl -X POST "http://127.0.0.1:8787/employees/employee-xxxx/ban?authkey=your-secret"
curl -X DELETE "http://127.0.0.1:8787/employees/employee-xxxx/ban?authkey=your-secret"

/admin/communications supports query filters:

• limit (default 50, max 500)
• offset (default 0)
• boss_id
• employee_id
• tag (matches employee tags)
• since / until (unix ms timestamp)

Persistent files in relay data dir:

• identities.db: identity records (id, role, name, tags, status, timestamps)
• connections.db: auth/reconnect/disconnect/ban event stream
• messages.db: routed message logs between nodes

6) Package with pkg

npm run build:pkg

Output folder: release/ with targets:

• node20-win-x64
• node20-linux-x64
• node20-macos-x64

7) Scripts

• npm run typecheck: type check only
• npm run build: compile to dist/
• npm run start: run compiled service
• npm run build:pkg: compile and package with pkg