edge-ai-client-ts 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog
+
+All notable changes to `edge-ai-client-ts` are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/) and the
+project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+- (placeholder for next iteration)
+
+## [1.0.0] - 2026-07-13
+
+**First public release** of `edge-ai-client-ts` on npm. The package
+ships a complete, byte-compatible TypeScript re-implementation of the Rust
+`ec` binary — same wire protocol, same security model, same CLI surface,
+shipped via `npm install -g`.
+
+### Added
+- Full TypeScript (Model 1) parallel client mirroring the Rust
+  `edge-client` byte-for-byte on the wire protocol. See
+  `docs/PROTOCOL.md` for the full spec and `e2e-smoke/README.md` for the
+  end-to-end smoke test.
+- 17-byte binary shell frame codec (`session/shell-frame.ts`) — byte-exact
+  with Rust `ShellFrame::encode/decode`.
+- AES-256-GCM disk-backed offline buffer queue (`buffer/disk-queue.ts`).
+- AGT-02 fail-fast policy (`session/fail-fast.ts`).
+- Disk-backed session persistence (`session/persistence.ts`).
+- `EdgeWsClient` with register / heartbeat / ACK / `get_config` RPC /
+  reconnect supervisor.
+- All six CLI subcommands (`run`, `enroll`, `whoami`, `status`, `devices`,
+  `messages`) with commander `exitOverride()` for embeddability.
+- `ServiceManager` for per-OS service install: systemd --user (Linux),
+  LaunchAgent (macOS), schtasks / LeastPrivilege (Windows).
+- TLS SPKI fingerprint pinning via the Node built-in `tls` module.
+- Comprehensive documentation under `docs/`:
+  - `INSTALLATION.md`
+  - `CONFIGURATION.md`
+  - `TROUBLESHOOTING.md`
+  - `PROTOCOL.md`
+- GitHub Actions workflow for CI + automated npm publish.
+
+### Fixed
+- Subprotocol header is now a 2-element array `["edgeai-v2", "<token>"]`
+  (was a single comma-containing string that `ws@8` rejects).
+- `socket.on('error')` defensive null-error handler (was propagating
+  `null` → `Error("null")`).
+- `session/shell.ts` stub `FrameCodec` replaced with the byte-exact real
+  codec from `session/shell-frame.ts` (was producing DIFFERENT wire bytes
+  than the Rust side via a hex-string interpretation).
+
+### Changed
+- Renamed the package version series from the pre-publish `7.0.0` line to
+  `1.0.0` to mark the first public npm release (no API/semantic break —
+  internal only).
+- Removed duplicate `FrameType` / `FrameCodec` stub from
+  `session/shell.ts` in favor of `session/shell-frame.ts` as the single
+  source of truth.
+
+### Security
+- `prepublishOnly` runs `typecheck`, `test`, and `build` to prevent
+  shipping a broken / unverified package.
+- No secrets are stored in source. All credentials are loaded from
+  environment variables (`EDGE_AUTH_TOKEN`, `EDGE_BUFFER_KEY`,
+  `EDGE_RELAY_FINGERPRINT`, …) — see `docs/CONFIGURATION.md`.
+
+### Known issues
+- See `docs/TROUBLESHOOTING.md` for a curated list of operator-facing
+  workarounds (no known critical issues at v1.0.0).
+
+[Unreleased]: https://github.com/baphuongna/edge-ai-agent/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/baphuongna/edge-ai-agent/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Edge AI Agent Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+# edge-ai-client-ts
+
+[![npm version](https://img.shields.io/npm/v/edge-ai-client-ts.svg)](https://www.npmjs.com/package/edge-ai-client-ts)
+[![npm downloads](https://img.shields.io/npm/dm/edge-ai-client-ts.svg)](https://www.npmjs.com/package/edge-ai-client-ts)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%E2%89%A520-green.svg)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.5-blue.svg)](https://www.typescriptlang.org/)
+
+**TypeScript edge-client** for the [Edge AI Agent](https://github.com/baphuongna/edge-ai-agent) fleet — a pure-npm re-implementation of the Rust `ec` binary with a **byte-compatible wire protocol**.
+
+A TypeScript edge-client and a Rust edge-client can connect to the **same relay** interchangeably, making `ec-ts` the perfect choice when:
+
+- You want a one-line `npm install -g` install (no Rust toolchain required).
+- You are running the edge node on an architecture without a prebuilt `ec` binary.
+- You need to embed the client into a Node.js application or a custom daemon.
+
+---
+
+## 🚀 Quick start
+
+```bash
+# 1. Install (requires Node.js >= 20)
+npm install -g edge-ai-client-ts
+
+# 2. Enroll against your relay (uses the per-operator API key from your dashboard)
+ec-ts enroll --key <your-operator-api-key>
+
+# 3. Start the daemon (foreground)
+ec-ts run
+
+# Or install it as a system service (auto-start on boot)
+ec-ts run --install-service
+```
+
+That's it — the daemon will open a WebSocket to the relay, register, and start sending heartbeats.
+
+---
+
+## 📦 What you get
+
+| Command | Purpose |
+|---------|---------|
+| `ec-ts run` | Start the daemon (foreground or `--install-service` for systemd/LaunchAgent/schtasks). |
+| `ec-ts enroll --key <key>` | Persist a per-operator credential to the OS keychain. |
+| `ec-ts whoami` | Print the current operator + relay identity. |
+| `ec-ts status` | One-shot health snapshot (WS state, queue depth, last heartbeat). |
+| `ec-ts devices` | List devices owned by the current operator. |
+| `ec-ts messages` | Tail the message buffer. |
+
+> **Binary name:** `ec-ts` (not `ec`) so you can run both the TypeScript and the Rust clients side-by-side if you want to compare them.
+
+---
+
+## ✅ Protocol parity with the Rust `ec`
+
+The TypeScript client implements the **exact same wire formats** as the Rust client:
+
+- **`/edge` JSON connection** — `register`, `stream`, `ack`, `heartbeat`, `get_config`, `list_agents`, `browser_fetch` message types with identical field names (`machine_id`, `agent_id`, `msg_id`, `type`, `payload`, `timestamp`).
+- **`/shell-edge` binary frames** — 17-byte header = 16-byte `session_id` (UUID bytes) + 1-byte `FrameType` + payload. `FrameType` enum values are identical (`Data=0`, `Resize=1`, `Close=2`, …).
+- **Buffer dump encryption** — `[KEY_VERSION=1][nonce:12][ciphertext+tag]` AES-256-GCM envelope with keyring rotation.
+- **TLS SPKI pinning** — SHA-256 of the DER `SubjectPublicKeyInfo`.
+- **`Sec-WebSocket-Protocol`** — `edgeai-v2, <token>[, device-secret=...]`.
+
+A TS edge-client and a Rust edge-client produce **byte-compatible** frames and JSON.
+
+---
+
+## 📋 Requirements
+
+- **Node.js >= 20** (uses `crypto.randomUUID`, native `fetch`, modern ESM).
+- A C++ toolchain for `node-pty` — Microsoft `node-pty` ships **prebuilt `.node` binaries** for common platforms (Linux x64/arm64, macOS x64/arm64, Windows x64), so a toolchain is only needed on unusual architectures.
+- The relay server must be reachable via WebSocket (`ws://` for dev, `wss://` for production).
+
+---
+
+## ⚙️ Configuration
+
+Config lives at:
+
+- **Linux:** `~/.config/edge-ai-agent/config.toml`
+- **macOS:** `~/Library/Application Support/edge-ai-agent/config.toml`
+- **Windows:** `%APPDATA%\edge-ai-agent\config.toml`
+
+A JSON `config.json` is also accepted as a fallback. The schema is identical to the Rust `config.toml` — see [`docs/CONFIGURATION.md`](docs/CONFIGURATION.md) for the full reference.
+
+### Environment variables (preferred for secrets)
+
+> **Never commit credentials to source.** Use environment variables for tokens, API keys, and encryption keys.
+
+| Variable | Purpose |
+|----------|---------|
+| `EDGE_AUTH_TOKEN` | Fleet shared secret for WS auth (preferred over `config.toml`). |
+| `EDGE_BUFFER_KEY` | Buffer-dump AES-256-GCM key (hex, 64 chars = 32 bytes). |
+| `EDGE_BUFFER_KEY_PREVIOUS` | Previous key for rotation (hex, 64 chars). |
+| `EDGE_RELAY_FINGERPRINT` | Pinned TLS SPKI fingerprint (overrides config). |
+| `EDGE_OWNER_OPERATOR_ID` | Override the enrolled operator id. |
+| `EDGEAI_REQUIRE_TLS` | `1` forces `wss://` even outside production. |
+| `NODE_ENV=production` | Forces `wss://`. |
+| `EDGE_CMD_GATE_MODE` | `off` / `warn` / `block`. |
+| `EDGE_FAIL_FAST` | Fail-fast policy toggle. |
+
+See [`docs/CONFIGURATION.md`](docs/CONFIGURATION.md) for the full env-var reference and precedence rules.
+
+---
+
+## 🛠️ Development
+
+```bash
+git clone https://github.com/baphuongna/edge-ai-agent.git
+cd edge-ai-agent/edge-client-ts
+npm install
+npm run typecheck   # tsc --noEmit
+npm test            # vitest run
+npm run build       # compile to dist/
+```
+
+Pre-publish sanity check (mirrors CI):
+
+```bash
+npm run prepublishOnly   # typecheck + test + build
+```
+
+End-to-end smoke test against a live `ws-service`:
+
+```bash
+npm run smoke
+```
+
+See [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md) for common install/run issues.
+
+---
+
+## 🧱 Architecture (module mapping)
+
+Every module in this package corresponds 1:1 with a Rust module — see
+[`docs/PROTOCOL.md`](docs/PROTOCOL.md) for the byte-exact wire spec.
+
+| Rust file                          | TS file                          |
+|------------------------------------|----------------------------------|
+| `config/settings.rs`               | `src/config/settings.ts`         |
+| `config/machine_id.rs`             | `src/config/settings.ts`         |
+| `config/device_secret.rs`          | `src/config/settings.ts`         |
+| `session/cmd_gate.rs` (config)     | `src/config/cmd-gate.ts`         |
+| `network/tls_guard.rs`             | `src/crypto/tls-guard.ts`        |
+| `crypto/aes_gcm.rs`                | `src/crypto/aes-gcm.ts`          |
+| `logging/file_logger.rs`           | `src/logging/file-logger.ts`     |
+| `network/ws_client.rs`             | `src/network/ws-client.ts`       |
+| `session/manager.rs`               | `src/session/manager.ts`         |
+| `session/shell.rs`                 | `src/session/shell.ts`           |
+| `session/shell_frame.rs`           | `src/session/shell-frame.ts`     |
+| `session/fail_fast.rs`             | `src/session/fail-fast.ts`       |
+| `session/pi_rpc.rs`                | `src/session/pi-rpc.ts`          |
+| `session/persistence.rs`           | `src/session/persistence.ts`     |
+| `session/sftp.rs`                  | `src/session/sftp.ts`            |
+| `buffer/disk_queue.rs`             | `src/buffer/disk-queue.ts`       |
+| `cli/mod.rs`                       | `src/cli/index.ts`               |
+| `daemon/manager.rs`                | `src/daemon/manager.ts`          |
+
+---
+
+## 📚 Documentation
+
+- [`docs/INSTALLATION.md`](docs/INSTALLATION.md) — Detailed install guide (Linux / macOS / Windows, dev / prod).
+- [`docs/CONFIGURATION.md`](docs/CONFIGURATION.md) — Full config schema + env-var precedence.
+- [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md) — Common errors and fixes.
+- [`docs/PROTOCOL.md`](docs/PROTOCOL.md) — Wire-protocol reference (frames, JSON messages, TLS pinning).
+
+---
+
+## 📄 License
+
+MIT — see [`LICENSE`](LICENSE).
+
+This package is part of the Edge AI Agent monorepo. The full system is documented at <https://github.com/baphuongna/edge-ai-agent>.

package/bin/ec-ts.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * ec-ts — TypeScript (Model 1) parallel edge-client binary shim.
+ *
+ * Loader that forwards argv to the CLI dispatch in the compiled dist/index.js.
+ * Install globally via `npm i -g edge-ai-client-ts` and run `ec-ts`.
+ *
+ * Requires Node.js >= 20.
+ */
+import('../dist/cli/index.js')
+  .then(async ({ dispatch }) => {
+    const code = await dispatch(process.argv.slice(2));
+    process.exit(code);
+  })
+  .catch((err) => {
+    console.error('ec-ts: failed to load CLI dispatch:', err);
+    process.exit(1);
+  });

package/dist/buffer/disk-queue.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Disk-backed offline buffer queue — TypeScript parallel of
+ * `edge-client/src/buffer/queue.rs` (in-memory queue with the disk-persist
+ * half) and `edge-client/src/buffer/disk_dump.rs` (AES-256-GCM envelope).
+ *
+ * This is the OFFLINE RESILIENCE LAYER: when the WS connection is down,
+ * stream frames are durably written to disk; on reconnect they replay in
+ * order; no frames lost on crash.
+ *
+ * ## On-disk format (mirrors Rust `DiskDumper`)
+ *
+ *   [KEY_VERSION: 1 byte][AES-256-GCM nonce: 12 bytes][ciphertext + auth tag: 16 bytes]
+ *
+ * The plaintext is a JSON-encoded array of {@link QueueEntry} objects
+ * (`{ msg_id, timestamp, bytes }`), where `bytes` is base64-encoded.
+ *
+ * ## Atomic-write invariant (the project's hardest-won guarantee)
+ *
+ *   1. Serialize entries → encrypt → write to `<dir>/.buffer.queue.enc.tmp`
+ *   2. `fsync` the temp file
+ *   3. `rename` tmp → `<dir>/buffer.queue.enc`
+ *
+ * Crash safety: a tmp file left on disk after a crash is half-written; we
+ * delete it on next lazy-load. The main file is either fully written or
+ * absent (the rename is atomic on POSIX and on Windows since Node 14+).
+ *
+ * ## Concurrency
+ *
+ * In-process serialization via a Promise-chain mutex. Cross-process locking
+ * is intentionally NOT implemented (would require `proper-lockfile` or
+ * similar; omitted to keep the dependency surface minimal — the in-process
+ * case is the common path).
+ *
+ * ## Dedup
+ *
+ * `append` silently skips when an entry with the same `msg_id` is already
+ * buffered. The Rust `BufferQueue::push` does not dedup, but the disk queue
+ * MUST dedup to avoid sending the same `msg_id` twice to the relay on
+ * reconnect (relay-side ACKs would otherwise race).
+ */
+import { KEY_VERSION } from '../crypto/aes-gcm.js';
+/** One queued message awaiting replay. */
+export interface QueueEntry {
+    /** Stable identifier used for dedup. */
+    msg_id: string;
+    /** Unix epoch milliseconds (sender-side ordering hint). */
+    timestamp: number;
+    /** Wire payload — encrypted at rest in the on-disk file. */
+    bytes: Uint8Array;
+}
+export interface DiskBufferQueueOptions {
+    /** Directory where the encrypted queue file lives. Created if missing. */
+    readonly dir: string;
+    /** 32-byte AES-256-GCM key (typically from `loadBufferKey(settings)`). */
+    readonly key: Uint8Array;
+    /**
+     * Soft cap on the serialized JSON envelope (plaintext bytes).
+     * Mirrors Rust `BufferConfig.max_memory_mb` (default 50 MiB).
+     */
+    readonly maxBytes?: number;
+}
+/** Default cap — 50 MiB. Matches Rust `BufferConfig::default().max_memory_mb`. */
+export declare const DEFAULT_MAX_BYTES: number;
+/** Filename of the encrypted queue blob (relative to `dir`). */
+export declare const QUEUE_FILE_NAME = "buffer.queue.enc";
+/** Filename of the atomic-write temp file (relative to `dir`). */
+export declare const QUEUE_TMP_NAME = ".buffer.queue.enc.tmp";
+/** Thrown by {@link DiskBufferQueue.append} when the cap would be exceeded. */
+export declare class BufferFullError extends Error {
+    readonly currentBytes: number;
+    readonly maxBytes: number;
+    constructor(currentBytes: number, maxBytes: number);
+}
+/**
+ * Single-file, AES-256-GCM-encrypted, FIFO buffer queue.
+ *
+ * Append-only on the hot path. `drain()` consumes every entry in FIFO order,
+ * hands each to a handler, and deletes the on-disk file when the handler
+ * completes successfully. `peek()` and `size()` are non-mutating.
+ */
+export declare class DiskBufferQueue {
+    private readonly dir;
+    private readonly filePath;
+    private readonly tmpPath;
+    private readonly key;
+    private readonly maxBytes;
+    /** In-memory cache. Loaded lazily on first op. */
+    private entries;
+    private loaded;
+    /** Promise-chain mutex for in-process serialization. */
+    private mutex;
+    constructor(opts: DiskBufferQueueOptions);
+    /**
+     * Append an entry to the queue. Skips silently when `entry.msg_id` is
+     * already buffered (dedup invariant). Throws {@link BufferFullError} when
+     * the serialized envelope would exceed `maxBytes`.
+     */
+    append(entry: QueueEntry): Promise<void>;
+    /**
+     * Return up to `limit` entries (FIFO order) without removing them.
+     * Defensive copy — callers may freely mutate the returned bytes.
+     */
+    peek(limit: number): Promise<QueueEntry[]>;
+    /** Return the number of entries currently buffered. */
+    size(): Promise<number>;
+    /**
+     * Delete all entries and the on-disk file. Idempotent — succeeds whether
+     * the file exists or not.
+     */
+    clear(): Promise<void>;
+    /**
+     * Invoke `handler(entry)` for every entry in FIFO order, then delete the
+     * on-disk file. Returns the number of entries processed. If the handler
+     * throws, the entries remain on disk for a future `drain()` retry
+     * (at-least-once semantics — matches the Rust offline-queue contract).
+     */
+    drain(handler: (entry: QueueEntry) => Promise<void> | void): Promise<number>;
+    /**
+     * Lazily create the dir, recover from a prior crash (delete tmp), and
+     * load existing entries. Runs at most once per queue instance.
+     */
+    private ensureLoaded;
+    /**
+     * Encrypt + atomic-write the in-memory entry list to disk.
+     *
+     * Sequence (mirrors Rust `atomic_write` in `disk_dump.rs:159-186`):
+     *   1. encrypt(plaintext) → `[version][nonce][ciphertext][tag]`
+     *   2. open tmp with mode 0600 (defense in depth — encryption protects
+     *      contents either way)
+     *   3. write blob + fsync the file (force kernel buffers to disk)
+     *   4. rename tmp → final path (atomic on POSIX, atomic on Win since Node 14+)
+     */
+    private persist;
+    private projectedBytesAfterAppend;
+    /** Serialize operations via a Promise chain (in-process mutex). */
+    private withLock;
+    private assertValidEntry;
+    private unlinkIfExists;
+}
+export { KEY_VERSION };