edge-ai-client-ts 1.0.0

package/dist/session/shell.d.ts

@@ -0,0 +1,124 @@
+/**
+ * PTY session manager — mirrors `edge-client/src/session/shell.rs`.
+ *
+ * Owns PTY sessions keyed by `session_id` (UUID v4 string). Spawns the
+ * shell via `node-pty`, pumps PTY stdout → framed data frames → an outbound
+ * channel, writes browser keystrokes (data frames) into the PTY, handles
+ * resize/close, and emits `shellExited` lifecycle events.
+ *
+ * Security: the PTY shell runs as the edge-client's Standard User (per
+ * SPEC.md) — no privilege escalation. Shell is only active when
+ * `shell.enabled = true` in config (default false); enforced by the
+ * constructor gate.
+ *
+ * Frame codec: the 17-byte binary frame format (`[16-byte session_id |
+ * 1-byte frame_type | payload]`) is provided by `shell-frame.ts`. We use
+ * it directly via a thin `FrameCodec` adapter that converts UUID strings
+ * to/from raw bytes at the codec boundary — keeping the wire bytes
+ * EXACTLY byte-compatible with the Rust `portable-pty` + `portable-pty`
+ * implementation.
+ */
+import type { IPty } from 'node-pty';
+import { FrameType, type FrameTypeValue } from './shell-frame.js';
+export type { IPty } from 'node-pty';
+export { FrameType };
+export type { FrameTypeValue };
+/**
+ * Frame codec adapter — internally delegates to `shell-frame.ts`'s
+ * byte-exact codec, but exposes a string-keyed interface so this module
+ * can pass UUID strings around as the rest of `session/` does. Wire
+ * format is IDENTICAL to `shell-frame.ts` (no behavior drift possible).
+ */
+export interface FrameCodec {
+    encode(sessionId: string, frameType: FrameTypeValue, payload: Buffer): Buffer;
+    decode(data: Buffer): {
+        sessionId: string;
+        frameType: FrameTypeValue;
+        payload: Buffer;
+    } | undefined;
+}
+/** Default codec backed by `shell-frame.ts`'s byte-exact primitives. */
+export declare const inlineFrameCodec: FrameCodec;
+/** Options passed to the PTY spawn function. */
+export interface PtySpawnOptions {
+    readonly name: string;
+    readonly cols: number;
+    readonly rows: number;
+    readonly cwd: string;
+    readonly env: Record<string, string>;
+}
+/**
+ * Function that spawns a PTY. Production uses `node-pty`, tests inject mocks.
+ * Mirrors `pty.spawn(shell, args, opts)`. Returns IPty synchronously.
+ */
+export type PtyFactory = (program: string, args: string[], options: PtySpawnOptions) => IPty;
+export interface ShellManagerOptions {
+    /** Shell gate — if false, all open() calls throw. Mirrors Rust shell.enabled. */
+    readonly enabled: boolean;
+}
+export type DataHandler = (sessionId: string, frameType: FrameTypeValue, payload: Buffer) => void;
+export type ExitHandler = (sessionId: string, code: number) => void;
+export declare class ShellManager {
+    private readonly enabled;
+    private readonly sessions;
+    private readonly emitter;
+    private codec;
+    /** Injectable PTY factory — tests inject a mock, production uses defaultPtyFactory. */
+    private readonly ptyFactory;
+    constructor(opts: ShellManagerOptions, codec?: FrameCodec, ptyFactory?: PtyFactory);
+    /**
+     * Open a new PTY shell session. The caller provides a UUID session_id
+     * (assigned by the session manager).
+     *
+     * Mirrors Rust `ShellManager::open`.
+     */
+    open(sessionId: string, cols: number, rows: number, shell?: string): Promise<void>;
+    /**
+     * Write data to a session's PTY stdin (browser keystrokes).
+     * Mirrors Rust `FrameType::Data` handling in `handle_frame`.
+     */
+    write(sessionId: string, data: Buffer): void;
+    /**
+     * Resize a session's PTY.
+     * Mirrors Rust `FrameType::Resize` handling in `handle_frame`.
+     */
+    resize(sessionId: string, cols: number, rows: number): void;
+    /**
+     * Close a session's PTY (browser-initiated).
+     * Mirrors Rust `close_session`.
+     */
+    close(sessionId: string): void;
+    /**
+     * Handle an inbound binary frame from the browser (relayed by relay).
+     * Mirrors Rust `ShellManager::handle_frame`.
+     */
+    handleFrame(frameType: FrameTypeValue, sessionId: string, payload: Buffer): void;
+    /**
+     * Register a handler for PTY data frames (sessionId, frameType, payload).
+     * The handler receives the structured payload, not raw wire bytes.
+     */
+    onData(handler: DataHandler): void;
+    /**
+     * Register a handler for session exit events (sessionId, exitCode).
+     */
+    onExit(handler: ExitHandler): void;
+    /**
+     * Register a handler for raw wire frames (Buffer).
+     * The binary WS transport layer listens on this to send outbound frames.
+     */
+    onFrame(handler: (frame: Buffer) => void): void;
+    /** Number of active PTY sessions. For heartbeat metadata. */
+    activeCount(): number;
+    /**
+     * Close all sessions (edge shutdown). Mirrors Rust `close_all`.
+     */
+    closeAll(): void;
+}
+/** Build a data frame (FrameType::Data). */
+export declare function buildDataFrame(sessionId: string, payload: Buffer): Buffer;
+/**
+ * Build a resize frame (FrameType::Resize). payload = cols (u16 BE) + rows (u16 BE).
+ */
+export declare function buildResizeFrame(sessionId: string, cols: number, rows: number): Buffer;
+/** Build a close frame (FrameType::Close). No payload. */
+export declare function buildCloseFrame(sessionId: string): Buffer;

package/dist/session/shell.js

@@ -0,0 +1,300 @@
+/**
+ * PTY session manager — mirrors `edge-client/src/session/shell.rs`.
+ *
+ * Owns PTY sessions keyed by `session_id` (UUID v4 string). Spawns the
+ * shell via `node-pty`, pumps PTY stdout → framed data frames → an outbound
+ * channel, writes browser keystrokes (data frames) into the PTY, handles
+ * resize/close, and emits `shellExited` lifecycle events.
+ *
+ * Security: the PTY shell runs as the edge-client's Standard User (per
+ * SPEC.md) — no privilege escalation. Shell is only active when
+ * `shell.enabled = true` in config (default false); enforced by the
+ * constructor gate.
+ *
+ * Frame codec: the 17-byte binary frame format (`[16-byte session_id |
+ * 1-byte frame_type | payload]`) is provided by `shell-frame.ts`. We use
+ * it directly via a thin `FrameCodec` adapter that converts UUID strings
+ * to/from raw bytes at the codec boundary — keeping the wire bytes
+ * EXACTLY byte-compatible with the Rust `portable-pty` + `portable-pty`
+ * implementation.
+ */
+import * as os from 'node:os';
+import { EventEmitter } from 'node:events';
+import { FrameType, encodeFrame, decodeFrame, sessionIdFromString, sessionIdToString, } from './shell-frame.js';
+// Re-export the frame-type enum so consumers importing from `./shell.js`
+// (which they have historically done) keep working.
+export { FrameType };
+/** Default codec backed by `shell-frame.ts`'s byte-exact primitives. */
+export const inlineFrameCodec = {
+    encode(sessionId, frameType, payload) {
+        const sidBytes = sessionIdFromString(sessionId);
+        if (sidBytes === null) {
+            throw new RangeError(`shell.ts: invalid sessionId (not a valid UUID/hex): ${sessionId}`);
+        }
+        return encodeFrame({ sessionId: sidBytes, frameType, payload });
+    },
+    decode(data) {
+        const f = decodeFrame(data);
+        if (f === null)
+            return undefined;
+        const sidStr = sessionIdToString(f.sessionId);
+        if (sidStr === null)
+            return undefined;
+        return { sessionId: sidStr, frameType: f.frameType, payload: Buffer.from(f.payload) };
+    },
+};
+/* (Old hex-string codec + helpers removed; see `shell-frame.ts` for the
+ * authoritative byte-exact implementation. Keeping these here would have
+ * meant producing DIFFERENT wire bytes than the Rust side, since the
+ * Rust `ShellFrame` writes the 16 raw UUID bytes directly — not a hex
+ * encoding of them.) */
+// ---------------------------------------------------------------------------
+// Default shell selection (mirrors Rust `default_shell()`)
+// ---------------------------------------------------------------------------
+function defaultShell() {
+    if (process.platform === 'win32') {
+        return process.env.COMSPEC || 'cmd.exe';
+    }
+    // Unix: os.userInfo().shell, env SHELL, or /bin/sh
+    try {
+        const info = os.userInfo();
+        if (info.shell && info.shell.length > 0)
+            return info.shell;
+    }
+    catch {
+        // userInfo() can throw in certain container environments
+    }
+    if (process.env.SHELL && process.env.SHELL.length > 0) {
+        return process.env.SHELL;
+    }
+    return '/bin/sh';
+}
+/** Default PTY factory using node-pty (synchronous spawn). */
+function defaultPtyFactory(program, args, options) {
+    // node-pty is imported statically at the top level for production use.
+    // Tests inject a mock factory via the constructor.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const pty = require('node-pty');
+    return pty.spawn(program, args, options);
+}
+export class ShellManager {
+    enabled;
+    sessions = new Map();
+    emitter = new EventEmitter();
+    codec;
+    /** Injectable PTY factory — tests inject a mock, production uses defaultPtyFactory. */
+    ptyFactory;
+    constructor(opts, codec, ptyFactory) {
+        this.enabled = opts.enabled;
+        this.codec = codec ?? inlineFrameCodec;
+        this.ptyFactory = ptyFactory ?? defaultPtyFactory;
+    }
+    /**
+     * Open a new PTY shell session. The caller provides a UUID session_id
+     * (assigned by the session manager).
+     *
+     * Mirrors Rust `ShellManager::open`.
+     */
+    async open(sessionId, cols, rows, shell) {
+        if (!this.enabled) {
+            throw new Error('Shell is disabled (shell.enabled=false in config)');
+        }
+        if (this.sessions.has(sessionId)) {
+            // Guard against duplicate opens (mirrors Rust: "open for already-open session (ignored)")
+            return;
+        }
+        const shellCmd = shell ?? defaultShell();
+        const shellName = process.platform === 'win32' ? shellCmd : shellCmd;
+        const args = [];
+        const ptyInstance = this.ptyFactory(shellName, args, {
+            name: 'xterm-256color',
+            cols,
+            rows,
+            cwd: process.cwd(),
+            env: {
+                ...process.env,
+                TERM: 'xterm-256color',
+            },
+        });
+        const handle = {
+            pty: ptyInstance,
+            kill() {
+                try {
+                    ptyInstance.kill();
+                }
+                catch {
+                    // process may already be dead
+                }
+            },
+            resize(c, r) {
+                try {
+                    ptyInstance.resize(c, r);
+                }
+                catch {
+                    // session may have been closed
+                }
+            },
+            write(data) {
+                try {
+                    ptyInstance.write(data.toString('utf8'));
+                }
+                catch {
+                    // session may have been closed
+                }
+            },
+        };
+        this.sessions.set(sessionId, handle);
+        // Wire PTY stdout → frame emission.
+        // PTY data is a string (terminal output); we encode as UTF-8 Buffer.
+        ptyInstance.onData((data) => {
+            if (!this.sessions.has(sessionId))
+                return;
+            const payload = Buffer.from(data, 'utf8');
+            this.emitter.emit('data', sessionId, FrameType.Data, payload);
+            // Also emit raw wire bytes for the binary WS transport
+            const frame = this.codec.encode(sessionId, FrameType.Data, payload);
+            this.emitter.emit('frame', frame);
+        });
+        // Wire PTY exit → lifecycle event.
+        ptyInstance.onExit(({ exitCode }) => {
+            // Send a Close frame for this session (mirrors Rust reader thread EOF behavior).
+            const closePayload = Buffer.alloc(0);
+            this.emitter.emit('frame', this.codec.encode(sessionId, FrameType.Close, closePayload));
+            this.emitter.emit('exit', sessionId, exitCode);
+            // Remove the session (the PTY is dead).
+            this.sessions.delete(sessionId);
+        });
+    }
+    /**
+     * Write data to a session's PTY stdin (browser keystrokes).
+     * Mirrors Rust `FrameType::Data` handling in `handle_frame`.
+     */
+    write(sessionId, data) {
+        const handle = this.sessions.get(sessionId);
+        if (handle === undefined)
+            return;
+        handle.write(data);
+    }
+    /**
+     * Resize a session's PTY.
+     * Mirrors Rust `FrameType::Resize` handling in `handle_frame`.
+     */
+    resize(sessionId, cols, rows) {
+        const handle = this.sessions.get(sessionId);
+        if (handle === undefined)
+            return;
+        handle.resize(cols, rows);
+    }
+    /**
+     * Close a session's PTY (browser-initiated).
+     * Mirrors Rust `close_session`.
+     */
+    close(sessionId) {
+        const handle = this.sessions.get(sessionId);
+        if (handle === undefined)
+            return;
+        handle.kill();
+        this.sessions.delete(sessionId);
+    }
+    /**
+     * Handle an inbound binary frame from the browser (relayed by relay).
+     * Mirrors Rust `ShellManager::handle_frame`.
+     */
+    handleFrame(frameType, sessionId, payload) {
+        switch (frameType) {
+            case FrameType.Data:
+                this.write(sessionId, payload);
+                break;
+            case FrameType.Resize: {
+                // payload = cols (u16 BE) + rows (u16 BE) — 4 bytes
+                if (payload.length >= 4) {
+                    const cols = payload.readUInt16BE(0);
+                    const rows = payload.readUInt16BE(2);
+                    this.resize(sessionId, cols, rows);
+                }
+                break;
+            }
+            case FrameType.Close:
+                this.close(sessionId);
+                break;
+            case FrameType.OpenControl: {
+                // payload = JSON { cols, rows } — default 80x24
+                let cols = 80;
+                let rows = 24;
+                if (payload.length > 0) {
+                    try {
+                        const parsed = JSON.parse(payload.toString('utf8'));
+                        if (typeof parsed.cols === 'number' && parsed.cols > 0)
+                            cols = parsed.cols;
+                        if (typeof parsed.rows === 'number' && parsed.rows > 0)
+                            rows = parsed.rows;
+                    }
+                    catch {
+                        // use defaults
+                    }
+                }
+                void this.open(sessionId, cols, rows);
+                break;
+            }
+            case FrameType.CloseControl:
+                this.close(sessionId);
+                break;
+            // Sftp and SftpRoot are handled by the sftp forwarder, not here
+            default:
+                break;
+        }
+    }
+    /**
+     * Register a handler for PTY data frames (sessionId, frameType, payload).
+     * The handler receives the structured payload, not raw wire bytes.
+     */
+    onData(handler) {
+        this.emitter.on('data', handler);
+    }
+    /**
+     * Register a handler for session exit events (sessionId, exitCode).
+     */
+    onExit(handler) {
+        this.emitter.on('exit', handler);
+    }
+    /**
+     * Register a handler for raw wire frames (Buffer).
+     * The binary WS transport layer listens on this to send outbound frames.
+     */
+    onFrame(handler) {
+        this.emitter.on('frame', handler);
+    }
+    /** Number of active PTY sessions. For heartbeat metadata. */
+    activeCount() {
+        return this.sessions.size;
+    }
+    /**
+     * Close all sessions (edge shutdown). Mirrors Rust `close_all`.
+     */
+    closeAll() {
+        const ids = [...this.sessions.keys()];
+        for (const id of ids) {
+            this.close(id);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// ShellFrame helpers (mirrors Rust factory methods)
+// ---------------------------------------------------------------------------
+/** Build a data frame (FrameType::Data). */
+export function buildDataFrame(sessionId, payload) {
+    return inlineFrameCodec.encode(sessionId, FrameType.Data, payload);
+}
+/**
+ * Build a resize frame (FrameType::Resize). payload = cols (u16 BE) + rows (u16 BE).
+ */
+export function buildResizeFrame(sessionId, cols, rows) {
+    const payload = Buffer.alloc(4);
+    payload.writeUInt16BE(cols, 0);
+    payload.writeUInt16BE(rows, 2);
+    return inlineFrameCodec.encode(sessionId, FrameType.Resize, payload);
+}
+/** Build a close frame (FrameType::Close). No payload. */
+export function buildCloseFrame(sessionId) {
+    return inlineFrameCodec.encode(sessionId, FrameType.Close, Buffer.alloc(0));
+}

package/docs/CONFIGURATION.md

@@ -0,0 +1,169 @@
+# Configuration
+
+`edge-ai-client-ts` reads configuration from **two** sources,
+merged with this precedence (highest → lowest):
+
+1. **Environment variables** (preferred for secrets — never commit them).
+2. **`config.toml`** (or `config.json`) in the platform-specific config
+   directory.
+3. Built-in defaults.
+
+> **Precedence example:** if `EDGE_AUTH_TOKEN` is set in the environment
+> AND `relay.auth_token` is set in `config.toml`, the **environment
+> variable wins**.
+
+---
+
+## Config file location
+
+| OS | Path |
+|----|------|
+| 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 (TOML takes
+precedence if both exist).
+
+---
+
+## Full schema
+
+This schema is **identical** to the Rust `edge-client`'s `config.toml`.
+Both clients read the same fields; mismatches are a bug.
+
+```toml
+# A stable identifier for this machine. Auto-generated on first run if
+# omitted; do NOT change after enrolling (the relay binds your operator
+# to a specific machine_id).
+machine_id = "uuid-v4-or-fleet-name"
+
+# Optional: pre-bind this client to an operator (otherwise set via
+# `ec-ts enroll`).
+owner_operator_id = "op_<your-operator-id>"
+
+[server]
+# WebSocket URL of the relay's /edge endpoint.
+ws_url = "wss://relay.example.com/edge"
+
+# Optional mode-specific URLs (Batch 5 — live network-mode switching).
+# When the operator toggles network_mode='lan'/'wan' from the dashboard,
+# the daemon transparently reconnects to the matching URL.
+# ws_url_lan = "ws://192.168.1.10:3001/edge"
+# ws_url_wan = "wss://wan-relay.example.com/edge"
+
+[agent]
+# Default agent id used when the dashboard does not pin one.
+default_agent_id = "worker_default"
+
+[buffer]
+# Maximum in-memory queue size in MB before spill-to-disk is triggered.
+max_memory_mb = 50
+
+# How often (ms) the daemon flushes in-memory entries to the WS sender.
+flush_interval_ms = 100
+
+# How long (ms) an in-flight entry may wait for an ACK before being
+# re-sent.
+ack_timeout_ms = 5000
+
+# Number of re-send attempts before an entry is dumped to encrypted disk
+# (anti-data-loss — see docs/PROTOCOL.md).
+max_retries = 3
+
+# Buffer dump encryption key. Hex, 64 chars = 32 bytes.
+# PREFER the EDGE_BUFFER_KEY env var (do not commit to source).
+# key = "<64 hex chars>"
+
+[logging]
+# Log level: trace | debug | info | warn | error
+level = "info"
+
+# Local log directory (relative to config dir or absolute).
+local_log_dir = "logs"
+
+[shell]
+# Enable the /shell-edge binary channel. Default OFF — opt in per node.
+enabled = false
+
+# Default TTY size when the dashboard opens a fresh shell.
+default_cols = 80
+default_rows = 24
+
+[relay]
+# Fleet shared secret for WS auth. PREFER the EDGE_AUTH_TOKEN env var.
+# auth_token = "<your-fleet-shared-secret>"
+
+# Optional: TLS SPKI fingerprint pin (SHA-256 hex of the
+# SubjectPublicKeyInfo). Strongly recommended for production.
+fingerprint = "<sha256-hex>"
+
+[resources]
+# Soft memory cap (MB). The daemon dumps the buffer to disk above this.
+memory_max_mb = 2048
+
+# Soft CPU quota (%). The daemon sheds load above this percentage.
+cpu_quota_percent = 50
+
+# Maximum concurrent tasks (sessions + RPCs).
+tasks_max = 256
+
+[cmd_gate]
+# AGT-02 command gate mode. off | warn | block. Default: block.
+mode = "block"
+
+# Per-command timeout (seconds). Default: 60.
+timeout_s = 60
+```
+
+---
+
+## Environment variables
+
+> **Treat all `EDGE_*` env vars as secrets.** Never commit them. Use your
+> platform's secret manager (e.g. systemd `EnvironmentFile=` with mode
+> `0600`, macOS launchd `EnvironmentVariables`, Windows Credential
+> Manager, or a `.env` file with `chmod 600`).
+
+| Variable | Equivalent config | Notes |
+|----------|-------------------|-------|
+| `EDGE_AUTH_TOKEN` | `relay.auth_token` | Fleet shared secret. **Required** in production. |
+| `EDGE_BUFFER_KEY` | `buffer.key` | Hex, 64 chars. Required for offline buffer encryption. |
+| `EDGE_BUFFER_KEY_PREVIOUS` | — | Hex, 64 chars. Used during key rotation. |
+| `EDGE_RELAY_FINGERPRINT` | `relay.fingerprint` | Overrides config; recommended for prod. |
+| `EDGE_OWNER_OPERATOR_ID` | `owner_operator_id` | Overrides enrolled operator. |
+| `EDGEAI_REQUIRE_TLS` | — | `1` forces `wss://` outside production. |
+| `NODE_ENV=production` | — | Implicitly forces `wss://`. |
+| `EDGE_CMD_GATE_MODE` | `cmd_gate.mode` | `off` / `warn` / `block`. |
+| `EDGE_FAIL_FAST` | — | Fail-fast policy toggle (`0`/`1`). |
+
+---
+
+## Secret handling
+
+- **Never** paste tokens, API keys, or fingerprints into:
+  - `config.toml` in a git repository
+  - shell history (use a password manager or `read -s`)
+  - Slack / chat / issue trackers
+- **Always prefer env vars** for any value labeled "secret" or "token"
+  in the schema above.
+- **Rotate** the fleet shared secret via the dashboard; the daemon
+  reconnects within the next heartbeat interval (~30 s).
+- **Revoke** lost tokens in the dashboard immediately. The relay enforces
+  revocation on the next WS upgrade (no waiting for the daemon to
+  notice).
+
+---
+
+## Verifying your config
+
+```bash
+# Validate without running the daemon
+ec-ts status --once
+
+# Show effective config (with secrets redacted)
+ec-ts whoami --verbose
+```
+
+See [`docs/TROUBLESHOOTING.md`](TROUBLESHOOTING.md) for common
+configuration mistakes.