edge-ai-client-ts 1.0.0

package/docs/INSTALLATION.md

@@ -0,0 +1,164 @@
+# Installation
+
+This guide covers installing `edge-ai-client-ts` on Linux, macOS, and
+Windows for **end users** (running the client) and for **contributors**
+(working on the package itself).
+
+---
+
+## End-user install
+
+### 1. Prerequisites
+
+- **Node.js >= 20** (we use `crypto.randomUUID`, native `fetch`, modern ESM).
+  Check with:
+  ```bash
+  node --version   # must print v20.x or newer
+  ```
+  If you need to install or upgrade Node, use [nvm](https://github.com/nvm-sh/nvm)
+  (Linux/macOS) or [fnm](https://github.com/Schniz/fnm) (cross-platform).
+
+- A **C/C++ toolchain** is only required if `node-pty` does not ship a
+  prebuilt binary for your platform. Most users on x86_64 / arm64 Linux,
+  x86_64 / arm64 macOS, and x86_64 Windows do **not** need it.
+
+### 2. Install via npm
+
+```bash
+npm install -g edge-ai-client-ts
+```
+
+Verify the binary is on `PATH`:
+
+```bash
+ec-ts --help
+```
+
+### 3. Configure secrets (NEVER commit them)
+
+Set the fleet shared secret and any optional pins via environment
+variables. **Do not paste these into shell history** — use a secrets
+manager or a `.env` file with restrictive permissions.
+
+```bash
+# Linux/macOS — current shell only
+export EDGE_AUTH_TOKEN="<your-fleet-shared-secret>"
+
+# Optional: pin the relay's TLS certificate (extract via the openssl
+# one-liner in the upstream docs)
+# export EDGE_RELAY_FINGERPRINT="<sha256:base64>"
+
+# Optional: enable offline buffer encryption (32 bytes = 64 hex chars)
+# export EDGE_BUFFER_KEY="<64 hex chars>"
+```
+
+Persist across shells by adding the exports to `~/.bashrc`,
+`~/.zshrc`, or `~/.config/fish/config.fish`.
+
+### 4. Enroll against your relay
+
+After creating an operator in the Edge AI Agent dashboard, copy the
+**per-operator API key** (format `opk_<base64>`) and enroll:
+
+```bash
+ec-ts enroll --key "<your-operator-api-key>"
+```
+
+This persists the credential to the **OS keychain** (Keychain on macOS,
+Credential Manager on Windows, libsecret/Secret Service on Linux). The
+plain key never touches a config file.
+
+### 5. Run the daemon
+
+Foreground (foreground is the default; useful for development):
+
+```bash
+ec-ts run
+```
+
+As a system service (auto-start on boot):
+
+```bash
+ec-ts run --install-service
+# Uninstall later with:
+ec-ts run --uninstall-service
+```
+
+The service manager installs:
+
+| OS | Service unit |
+|----|--------------|
+| Linux | `~/.config/systemd/user/ec-ts.service` |
+| macOS | `~/Library/LaunchAgents/com.edgeai.ec-ts.plist` |
+| Windows | `\LeastPrivilege` scheduled task |
+
+---
+
+## Contributor install
+
+### 1. Clone the monorepo
+
+```bash
+git clone https://github.com/baphuongna/edge-ai-agent.git
+cd edge-ai-agent/edge-client-ts
+```
+
+### 2. Install dependencies
+
+```bash
+npm install
+```
+
+### 3. Verify
+
+```bash
+npm run typecheck    # tsc --noEmit
+npm test             # vitest run
+npm run build        # compile to dist/
+```
+
+### 4. End-to-end smoke (optional)
+
+The smoke test connects a real daemon to a local `ws-service` and
+verifies register → heartbeat → ack → reconnect. See
+[`e2e-smoke/README.md`](../e2e-smoke/README.md).
+
+```bash
+npm run smoke
+```
+
+---
+
+## Upgrading
+
+```bash
+npm install -g edge-ai-client-ts@latest
+```
+
+Configuration and OS-keychain credentials are preserved across upgrades.
+To downgrade, pin the version:
+
+```bash
+npm install -g edge-ai-client-ts@1.0.0
+```
+
+---
+
+## Uninstall
+
+```bash
+# Remove the daemon + service
+ec-ts run --uninstall-service
+
+# Remove the package
+npm uninstall -g edge-ai-client-ts
+
+# Optional: wipe the per-user config directory
+rm -rf ~/.config/edge-ai-agent     # Linux
+rm -rf ~/Library/Application\ Support/edge-ai-agent   # macOS
+# Windows: %APPDATA%\edge-ai-agent
+```
+
+OS-keychain entries live in your platform's standard credential store and
+are removed with your platform's credential manager (do not forget to
+revoke the operator API key in the dashboard as well).

package/docs/PROTOCOL.md

@@ -0,0 +1,248 @@
+# Wire protocol reference
+
+`edge-ai-client-ts` speaks the **exact same wire protocol** as the
+Rust `edge-client` (`ec` binary). This document is the authoritative
+spec; both clients must conform.
+
+> If you find a discrepancy between the TS and Rust implementations,
+> that is a bug — open an issue.
+
+---
+
+## Transport
+
+- **WebSocket** to the relay's `/edge` path (text + binary frames).
+- **Subprotocol** header: `Sec-WebSocket-Protocol: edgeai-v2, <auth_token>[, device-secret=<value>]`.
+  - The `<auth_token>` is the **fleet shared secret** (`EDGE_AUTH_TOKEN`).
+  - `device-secret=<value>` is sent when the device has been issued a
+    per-machine secret (post-enrollment).
+- **TLS** (recommended for production):
+  - `wss://` only — `ws://` is refused when `EDGEAI_REQUIRE_TLS=1` or
+    `NODE_ENV=production`.
+  - Optional **SPKI fingerprint pin** (SHA-256 hex of the DER
+    `SubjectPublicKeyInfo`). Pin mismatch → handshake aborted.
+
+---
+
+## `/edge` JSON connection
+
+All messages are JSON, UTF-8 text frames.
+
+### Client → Server
+
+#### `register`
+
+First message after upgrade.
+
+```json
+{
+  "type": "register",
+  "machine_id": "<uuid-v4>",
+  "agent_id": "worker_default",
+  "platform": "linux",
+  "hostname": "<short-hostname>",
+  "agent_version": "0.1.0",
+  "operator_id": "op_<your-operator-id>"
+}
+```
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `machine_id` | yes | Stable per-machine UUID. The relay uses this as the device PK. |
+| `agent_id` | yes | Default agent id for dispatch when the dashboard does not pin one. |
+| `platform` | no | `linux` / `darwin` / `win32`. |
+| `hostname` | no | Display only; relay stores on `devices.display_name`. |
+| `agent_version` | no | Display only. |
+| `operator_id` | no | When set, the relay auto-claims ownership on first heartbeat. |
+
+#### `heartbeat`
+
+Every `heartbeat_interval_s` seconds (default 30).
+
+```json
+{
+  "type": "heartbeat",
+  "machine_id": "<uuid-v4>",
+  "operator_id": "op_<your-operator-id>",
+  "system": {
+    "cpu_cores": 8,
+    "cpu_usage_pct": 12.4,
+    "mem_total_mb": 16384,
+    "mem_available_mb": 9216,
+    "disk_total_gb": 512.0,
+    "disk_free_gb": 320.5,
+    "load_avg_1m": 0.42,
+    "process_count": 312
+  }
+}
+```
+
+#### `ack`
+
+Acknowledge receipt of a `stream` message from the relay.
+
+```json
+{ "type": "ack", "msg_id": "<relay-msg-id>" }
+```
+
+#### `stream` (rare)
+
+The TS client sends `stream` messages from the offline buffer drain —
+they have the same shape as relay → client `stream` messages.
+
+#### `execute_response` / `agent_list` / `browser_fetch_result`
+
+Server-originated RPC responses, forwarded back to the dashboard.
+
+### Server → Client
+
+#### `registered`
+
+Sent once on successful registration.
+
+```json
+{ "type": "registered", "machine_id": "<uuid-v4>", "agent_id": "worker_default" }
+```
+
+If the relay just minted a per-device secret, the next message is
+`device_secret_issued` (one-time).
+
+#### `device_secret_issued`
+
+```json
+{
+  "type": "device_secret_issued",
+  "secret": "<base64-32-bytes>",
+  "device_id": "<uuid-v4>"
+}
+```
+
+#### `stream`
+
+A message destined for the local agent.
+
+```json
+{
+  "type": "stream",
+  "msg_id": "<uuid-v4>",
+  "machine_id": "<uuid-v4>",
+  "agent_id": "worker_default",
+  "payload": { "...": "agent-specific JSON" },
+  "timestamp": 1721000000000
+}
+```
+
+The TS client forwards `payload` to the local `agent_id` Pi process and
+replies with `ack`.
+
+#### `set_config`
+
+Live config push from the relay.
+
+```json
+{
+  "type": "set_config",
+  "heartbeat_interval_s": 30,
+  "network_mode": "lan"
+}
+```
+
+#### `execute` / `list_agents` / `get_available_models` / `browser_fetch`
+
+RPC commands from the dashboard. The TS client spawns the relevant
+handler and replies via the buffer queue.
+
+---
+
+## `/shell-edge` binary channel
+
+After `/edge` registration succeeds, the TS client opens a second
+WebSocket to `/shell-edge`. This channel carries **binary frames** for
+shell sessions — byte-exact with the Rust client.
+
+### Frame layout
+
+```
++----------------+----------------+----------+----------------+
+| session_id     | FrameType      | payload_len (u32 BE) | payload     |
+| 16 bytes (UUID)| 1 byte         | 4 bytes              | N bytes     |
++----------------+----------------+----------------------+------------+
+```
+
+Total header size: **17 bytes** (UUID + FrameType + u32 BE length).
+
+### `FrameType` enum
+
+| Value | Name | Direction | Payload |
+|-------|------|-----------|---------|
+| 0x00 | `Data` | both | PTY output bytes |
+| 0x01 | `Resize` | client → server | `{ cols: u16 BE, rows: u16 BE }` |
+| 0x02 | `Close` | both | empty (graceful shutdown) |
+| 0x03 | `Ping` | both | empty (heartbeat) |
+| 0x04 | `Pong` | both | empty (heartbeat reply) |
+
+The first frame after upgrade MUST carry a `session_id` matching the
+one issued by the relay's `share_token` handshake. A mismatch is a
+fatal protocol error (close code 4403).
+
+---
+
+## Buffer dump encryption
+
+When the in-memory queue overflows, the daemon encrypts entries with
+AES-256-GCM and writes them to disk.
+
+### Envelope
+
+```
++----------------+----------+----------------------------+
+| KEY_VERSION=1  | nonce    | ciphertext + GCM tag       |
+| 1 byte         | 12 bytes | N bytes                   |
++----------------+----------+----------------------------+
+```
+
+- **KEY_VERSION**: always `0x01` in v1.x. A future major version may
+  introduce `0x02`.
+- **nonce**: 12 random bytes (NEVER reuse with the same key).
+- **key**: 32 bytes (256 bits), configured via `EDGE_BUFFER_KEY` (hex, 64 chars).
+- **tag**: 16 bytes (default GCM tag length).
+- **algorithm**: AES-256-GCM (RFC 5116).
+
+Key rotation is supported via `EDGE_BUFFER_KEY_PREVIOUS` — the daemon
+can decrypt entries written with the previous key and re-encrypt with
+the new one on next dump.
+
+---
+
+## TLS pinning
+
+When `relay.fingerprint` (or `EDGE_RELAY_FINGERPRINT`) is set, the
+client:
+
+1. Completes the standard TLS handshake against the Mozilla CA bundle.
+2. Extracts the leaf certificate's `SubjectPublicKeyInfo`.
+3. Hashes it with SHA-256.
+4. Compares in constant time against the configured pin.
+
+**Extract the pin for a relay cert:**
+
+```bash
+openssl s_client -connect <relay-host>:443 < /dev/null 2>/dev/null \
+  | openssl x509 -pubkey -noout \
+  | openssl pkey -pubin -outform DER \
+  | openssl dgst -sha256 -binary \
+  | xxd -p -c 64
+```
+
+> **Cert-renewal-safe.** The pin is over the **public key**, not the
+> full cert — operators do not need to repin on a cert rotation,
+> only on a keypair rotation.
+
+---
+
+## Versioning
+
+The wire protocol is versioned implicitly via the `Sec-WebSocket-Protocol`
+identifier (`edgeai-v2`). Future major versions will use `edgeai-v3`,
+etc. The TS client will refuse to connect if the relay advertises an
+unrecognized protocol version.

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,177 @@
+# Troubleshooting
+
+A field guide for the most common `edge-ai-client-ts` errors and how
+to fix them.
+
+> **Security note:** when filing an issue or asking for support, **never
+> share your `EDGE_AUTH_TOKEN`, `EDGE_BUFFER_KEY`, `EDGE_RELAY_FINGERPRINT`,
+> or operator API key.** Redact everything matching `<secret>=…` in logs
+> before pasting.
+
+---
+
+## Install / `npm install -g` fails
+
+### `EACCES: permission denied`
+
+You ran `npm install -g` without sudo. Either:
+
+- Re-run with `sudo`:
+  ```bash
+  sudo npm install -g edge-ai-client-ts
+  ```
+- Or fix npm's global prefix (recommended):
+  ```bash
+  mkdir -p ~/.npm-global
+  npm config set prefix '~/.npm-global'
+  export PATH="$HOME/.npm-global/bin:$PATH"
+  # Persist in ~/.bashrc / ~/.zshrc
+  npm install -g edge-ai-client-ts
+  ```
+
+### `node-pty` build fails (no prebuilt binary)
+
+Most platforms have a prebuilt `.node` artifact. If yours does not:
+
+- **Linux**: `apt install build-essential python3` (Debian/Ubuntu) or
+  `dnf install gcc-c++ make python3` (Fedora).
+- **macOS**: `xcode-select --install`.
+- **Windows**: install [windows-build-tools](https://github.com/felixrieseberg/windows-build-tools)
+  or use the Visual Studio Build Tools.
+
+### `ec-ts: command not found` after install
+
+The global `bin` dir is not on `PATH`. Find it with:
+
+```bash
+npm config get prefix
+# Add "$prefix/bin" to PATH.
+```
+
+---
+
+## Runtime / the daemon won't start
+
+### `WebSocket upgrade rejected (no detail)`
+
+The relay rejected the upgrade. Common causes:
+
+| Cause | Fix |
+|-------|-----|
+| Missing or wrong `EDGE_AUTH_TOKEN` | Re-export the env var, restart the daemon. |
+| TLS pin mismatch (`relay_fingerprint`) | Re-extract the SPKI hash with the `openssl` one-liner in the upstream docs. |
+| Relay is `wss://` but you configured `ws://` (or vice versa) | Match the scheme; set `EDGEAI_REQUIRE_TLS=1` to force `wss://`. |
+| Operator revoked in the dashboard | Re-enroll with a new key (`ec-ts enroll --key <new-key>`). |
+
+### `EAI_AGAIN` / `ENOTFOUND` (DNS resolution)
+
+The relay hostname does not resolve. Check:
+
+```bash
+# Replace "relay.example.com" with your ws_url host
+nslookup relay.example.com
+curl -v https://relay.example.com/health
+```
+
+If you are behind a corporate proxy, set `HTTPS_PROXY` (and `NO_PROXY`
+for the local relay) per Node's conventions.
+
+### `Buffer full: 16777276 bytes would exceed cap of 16777216 bytes`
+
+The in-memory queue hit `buffer.max_memory_mb`. Increase it, or speed up
+flushes:
+
+```toml
+[buffer]
+max_memory_mb = 64     # default 50; raise to 128+ on busy nodes
+flush_interval_ms = 50 # default 100; lower for faster drain
+```
+
+Also check that `EDGE_BUFFER_KEY` is set — without it, the daemon cannot
+dump the overflow to encrypted disk and starts dropping entries.
+
+---
+
+## Connection / WS flaps
+
+### Daemon connects, then immediately disconnects
+
+Look in the daemon log (`local_log_dir` from config). Two frequent
+patterns:
+
+- **`displaced by duplicate machine_id registration`** — another
+  daemon (TypeScript or Rust) is already registered with the same
+  `machine_id`. Kill the duplicate or set a unique `machine_id` per
+  daemon.
+- **`401 Unauthorized`** — fleet shared secret mismatch. Verify
+  `EDGE_AUTH_TOKEN` matches the relay's `RELAY_AUTH_TOKEN`.
+
+### `WebSocket protocol error: Handshake not finished`
+
+The relay closed the upgrade mid-handshake. Most common cause: an
+intermediating proxy (nginx, Cloudflare Tunnel) is stripping the
+`Sec-WebSocket-Protocol` subprotocol header. The `edgeai-v2` protocol
+identifier carries the auth token, so if the proxy strips it the relay
+sees an unauthenticated request.
+
+**Fix (Cloudflare Tunnel):** ensure the tunnel preserves headers. With
+`cloudflared` defaults the `Sec-WebSocket-Protocol` header IS forwarded
+to the upstream; double-check your `config.yml` `originRequest` block.
+
+---
+
+## `ec-ts enroll` problems
+
+### `keychain unavailable` on Linux
+
+`ec-ts` requires `libsecret` to store the per-operator API key. Install:
+
+```bash
+sudo apt install libsecret-1-0 libsecret-1-dev   # Debian/Ubuntu
+sudo dnf install libsecret libsecret-devel        # Fedora
+```
+
+Then make sure a Secret Service provider is running (GNOME Keyring,
+KDE Wallet, KeePassXC with Secret Service integration, etc.).
+
+### `enroll` succeeds but `run` still says "no operator"
+
+The keychain item may not be visible to the daemon process. Check:
+
+```bash
+# Linux
+secret-tool search service edge-ai-agent
+
+# macOS
+security find-generic-password -s edge-ai-agent
+```
+
+If the item is missing, re-enroll with the same key.
+
+---
+
+## Performance / memory
+
+- **`memory_max_mb`** is a SOFT cap. The daemon dumps to disk above it,
+  not OOM-kills.
+- **`tasks_max`** caps concurrent sessions + RPCs. Raise it on
+  machines running many parallel agents.
+- For long-lived nodes with intermittent connectivity, also raise
+  `buffer.max_memory_mb` and `buffer.max_retries`.
+
+---
+
+## Getting more help
+
+1. Run `ec-ts status --once` and capture the output (redact secrets).
+2. Tail the daemon log (`local_log_dir` from your config).
+3. File an issue at <https://github.com/baphuongna/edge-ai-agent/issues>
+   with:
+   - `ec-ts --version` and `node --version`
+   - OS / architecture
+   - Redacted `ec-ts whoami --verbose` output
+   - The relevant daemon log lines
+
+The maintainers will not ask for your `EDGE_AUTH_TOKEN` or operator API
+key — if you accidentally paste one, **rotate it immediately** in the
+dashboard.

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "edge-ai-client-ts",
+  "version": "1.0.0",
+  "description": "TypeScript edge-client for the Edge AI Agent fleet — pure-npm reimplementation of the Rust `ec` binary with byte-compatible wire protocol.",
+  "license": "MIT",
+  "author": {
+    "name": "Edge AI Agent Contributors",
+    "url": "https://github.com/baphuongna/edge-ai-agent"
+  },
+  "homepage": "https://github.com/baphuongna/edge-ai-agent/tree/main/edge-client-ts#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/baphuongna/edge-ai-agent.git",
+    "directory": "edge-client-ts"
+  },
+  "bugs": {
+    "url": "https://github.com/baphuongna/edge-ai-agent/issues"
+  },
+  "keywords": [
+    "edge",
+    "agent",
+    "ai",
+    "iot",
+    "telemetry",
+    "relay",
+    "websocket",
+    "fleet",
+    "daemon",
+    "typescript"
+  ],
+  "bin": {
+    "ec-ts": "./bin/ec-ts.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "bin/",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md",
+    "docs/"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && tsc-alias",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build",
+    "smoke:preflight": "node e2e-smoke/preflight.mjs",
+    "smoke": "npm run build && npm run smoke:preflight && node e2e-smoke/smoke.mjs"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "node-pty": "^1.0.0",
+    "smol-toml": "^1.3.1",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "@types/ws": "^8.5.12",
+    "tsc-alias": "^1.9.0",
+    "typescript": "^5.5.4",
+    "vitest": "^2.1.1"
+  }
+}