@hera-al/standardnode 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TGP / Hera Artificial Life
+
+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,241 @@
+# @hera-al/standardnode
+
+> **Part of [Hera Artificial Life](https://github.com/hera-artificial-life/hera-al)** — an opinionated AI assistant platform that runs locally on your machine. This package is the remote execution agent that connects your machines to the Hera gateway.
+
+Lightweight remote execution node that connects to a Hera gateway via WebSocket. Once paired, it can execute shell commands and proxy browser automation requests dispatched by the central server.
+
+## Features
+
+- **WebSocket connection** to Hera gateway (Nostromo) with automatic reconnect
+- **Signature-based pairing** — each node has a unique cryptographic identity, approved by an admin
+- **Shell execution** — run commands remotely with optional allowlist and timeout
+- **Browser proxy** — forward requests to a local [`@hera-al/browser-server`](https://www.npmjs.com/package/@hera-al/browser-server) instance (optional)
+- **Auto-detection** — discovers the gateway URL automatically when running inside the Hera project
+- **YAML configuration** — auto-generated on first run, CLI flags override and persist
+- **File logging** — append-only with automatic rotation at 10 MB
+- **Multi-platform** — macOS, Linux, Windows (Node.js ≥ 18)
+
+## Install
+
+```bash
+npm install @hera-al/standardnode
+```
+
+### With browser automation (optional)
+
+```bash
+npm install @hera-al/standardnode @hera-al/browser-server
+```
+
+## Quick start
+
+### CLI
+
+```bash
+npx hera-stdnode --ws ws://localhost:3001/nostromo/ws/nodes
+```
+
+All CLI flags:
+
+| Flag       | Default                | Description                          |
+| ---------- | ---------------------- | ------------------------------------ |
+| `--ws`     | *(auto-detected)*      | WebSocket URL of the Hera gateway    |
+| `--name`   | *(OS hostname)*        | Display name for this node           |
+| `--config` | `config.stdnode.yaml`  | Path to configuration file           |
+| `--init`   | —                      | Copy example config to current directory and exit |
+| `--help`   | —                      | Show help message                    |
+
+Values passed via CLI are persisted to the config file.
+
+### First run
+
+```bash
+# Option A: just launch — config is auto-generated with sensible defaults
+hera-stdnode --ws wss://yourserver:3001/nostromo/ws/nodes
+
+# Option B: generate a commented config first, edit it, then launch
+hera-stdnode --init
+# → creates config.stdnode.yaml in the current directory
+vi config.stdnode.yaml
+hera-stdnode
+```
+
+### From source
+
+```bash
+git clone <repo>
+cd standardnode
+npm install
+npm start -- --ws ws://localhost:3001/nostromo/ws/nodes
+```
+
+## WebSocket URL format
+
+```
+ws[s]://<hostname>:<port><basePath>/ws/nodes
+```
+
+| Segment      | Description                                     | Default      |
+| ------------ | ----------------------------------------------- | ------------ |
+| `<hostname>` | Server address or Tailscale DNS name            | `localhost`  |
+| `<port>`     | Nostromo UI port configured on the Hera server  | `3001`       |
+| `<basePath>` | Nostromo base path configured on the Hera server| `/nostromo`  |
+
+Use `wss://` when connecting through Tailscale Serve or any TLS-terminated proxy.
+
+## Configuration
+
+On first run a `config.stdnode.yaml` is created with a unique node ID and cryptographic signature. You can also copy the bundled `config.stdnode.example.yaml` as a starting point.
+
+### node
+
+| Key           | Type   | Default        | Description                          |
+| ------------- | ------ | -------------- | ------------------------------------ |
+| `id`          | string | *(generated)*  | Unique node identifier (UUID)        |
+| `displayName` | string | *(hostname)*   | Human-readable name shown in Nostromo|
+
+### gateway
+
+| Key           | Type    | Default                                | Description                      |
+| ------------- | ------- | -------------------------------------- | -------------------------------- |
+| `enabled`     | boolean | `true`                                 | Enable gateway connection        |
+| `url`         | string  | `ws://localhost:3001/nostromo/ws/nodes` | WebSocket endpoint               |
+| `token`       | string  | `""`                                   | Authentication token (reserved)  |
+| `signature`   | string  | *(generated)*                          | Node signature for pairing       |
+| `reconnectMs` | number  | `5000`                                 | Reconnect delay in milliseconds  |
+
+### commands.shell
+
+| Key         | Type     | Default | Description                                   |
+| ----------- | -------- | ------- | --------------------------------------------- |
+| `enabled`   | boolean  | `true`  | Enable shell command execution                |
+| `allowlist` | string[] | `[]`    | If non-empty, only these commands are allowed |
+| `timeout`   | number   | `30000` | Command timeout in milliseconds               |
+
+### browser
+
+| Key              | Type     | Default | Description                                    |
+| ---------------- | -------- | ------- | ---------------------------------------------- |
+| `enabled`        | boolean  | `false` | Enable browser automation proxy                |
+| `controlPort`    | number   | `3002`  | Port for the browser HTTP control server       |
+| `headless`       | boolean  | `false` | Run Chrome in headless mode                    |
+| `noSandbox`      | boolean  | `false` | Disable Chrome sandbox (CI/Docker)             |
+| `attachOnly`     | boolean  | `false` | Only attach to an already-running Chrome       |
+| `executablePath` | string   | —       | Custom Chrome/Brave/Edge executable path       |
+| `allowProfiles`  | string[] | `[]`    | If non-empty, only these profiles are allowed  |
+
+### logs
+
+| Key   | Type   | Default          | Description                    |
+| ----- | ------ | ---------------- | ------------------------------ |
+| `dir` | string | `./logs-stdnode` | Directory for log files        |
+
+Log files are written as `stdnode.log` with rotation at 10 MB (up to 9 rotated files).
+
+## Pairing flow
+
+```
+┌──────────┐         ┌──────────┐         ┌───────────┐
+│   Node   │──hello──▶│ Nostromo │         │   Admin   │
+│          │         │ (gateway)│◀─approve─│  (web UI) │
+│          │◀─status─│          │         │           │
+└──────────┘         └──────────┘         └───────────┘
+```
+
+1. Node connects and sends a `hello` message with ID, signature, and capabilities
+2. Nostromo shows the node as **pending** in the admin UI
+3. An admin approves (or revokes) the node
+4. Once approved, the node starts receiving and executing commands
+5. If the connection drops, the node reconnects automatically after `reconnectMs`
+
+## Supported commands
+
+| Command         | Description                                               |
+| --------------- | --------------------------------------------------------- |
+| `shell.run`     | Execute a shell command (`cmd` + `args` array)            |
+| `shell.which`   | Resolve a binary path                                     |
+| `browser.proxy` | Forward an HTTP request to the local browser-server       |
+
+### shell.run
+
+```json
+{
+  "cmd": "/usr/bin/ls",
+  "args": ["-la", "/tmp"],
+  "cwd": "/home/user",
+  "timeout": 10000,
+  "env": { "NODE_ENV": "production" }
+}
+```
+
+Returns `{ stdout, stderr, exitCode }`.
+
+> **Security:** Commands are spawned with `shell: false` — no shell injection possible. Use the `allowlist` to restrict which binaries can be executed.
+
+### browser.proxy
+
+Requires `@hera-al/browser-server` installed and `browser.enabled: true` in config.
+
+```json
+{
+  "method": "GET",
+  "path": "/snapshot",
+  "query": { "mode": "text" },
+  "profile": "default",
+  "timeoutMs": 30000
+}
+```
+
+Returns the browser-server response. File results (screenshots, PDFs) are automatically base64-encoded.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────┐
+│              Hera Gateway (Nostromo)             │
+└────────────────────┬────────────────────────────┘
+                     │ WebSocket
+          ┌──────────┴──────────┐
+          │    StandardNode     │
+          │  ┌────────────────┐ │
+          │  │  Gateway Link  │ │  ← connection, pairing, heartbeat
+          │  └───────┬────────┘ │
+          │    ┌─────┴─────┐    │
+          │    │           │    │
+          │  Shell    Browser   │
+          │  Runner   Proxy     │
+          │    │           │    │
+          │    ▼           ▼    │
+          │  spawn()   fetch()  │  ← local processes / browser-server
+          └─────────────────────┘
+```
+
+- **Gateway Link** — WebSocket client with reconnect, heartbeat (30s), and command dispatch
+- **Shell Runner** — secure process spawning with allowlist, timeout, env isolation
+- **Browser Proxy** — HTTP proxy to local `@hera-al/browser-server` with file detection and profile filtering
+
+## Auto-detection
+
+When running inside the Hera project directory (i.e. `standardnode/` is a subfolder), the node reads `../config.yaml` on first run and auto-configures the gateway URL from the Nostromo settings. The `--ws` flag always takes priority.
+
+## NPM scripts
+
+| Script          | Description                                  |
+| --------------- | -------------------------------------------- |
+| `npm start`     | Run via tsx (development, no build needed)    |
+| `npm run dev`   | Run with file watcher (hot reload)           |
+| `npm run build` | Compile TypeScript to `dist/`                |
+| `npm run node`  | Run the compiled build (`node dist/index.js`)|
+| `npm run help`  | Show CLI help                                |
+
+All scripts forward extra flags: `npm start -- --ws <url> --name <name>`.
+
+## Requirements
+
+- Node.js ≥ 18
+- macOS, Linux, or Windows
+- A running Hera gateway with Nostromo enabled
+
+## License
+
+[MIT](./LICENSE) — © 2026 TGP / Hera Artificial Life

package/config.stdnode.example.yaml

@@ -0,0 +1,44 @@
+# StandardNode configuration
+# Copy this file to config.stdnode.yaml and adjust as needed.
+
+node:
+  # Auto-generated on first run if left empty
+  id: ""
+  # Defaults to OS hostname if left empty
+  displayName: ""
+
+gateway:
+  enabled: true
+  # WebSocket URL of the Hera gateway (Nostromo)
+  url: ws://localhost:3001/nostromo/ws/nodes
+  token: ""
+  # Auto-generated on first run if left empty
+  signature: ""
+  reconnectMs: 5000
+
+logs:
+  # Directory for log files (created automatically)
+  dir: ./logs-stdnode
+
+commands:
+  shell:
+    enabled: true
+    # If non-empty, only these commands are allowed
+    allowlist: []
+    timeout: 30000
+
+# Browser automation via CDP (Chrome DevTools Protocol)
+browser:
+  enabled: false
+  # Port for the browser HTTP control server
+  controlPort: 3002
+  # Run Chrome in headless mode
+  headless: false
+  # Disable Chrome sandbox (needed in some Linux environments)
+  noSandbox: false
+  # Only attach to an already-running Chrome (don't launch one)
+  attachOnly: false
+  # Custom Chrome/Brave/Edge executable path
+  # executablePath: /usr/bin/google-chrome
+  # If non-empty, only these browser profiles are allowed
+  allowProfiles: []

package/dist/commands/browser-proxy.d.ts

@@ -0,0 +1,22 @@
+import type { Logger } from "../logger.js";
+export interface BrowserProxyParams {
+    method?: string;
+    path?: string;
+    query?: Record<string, string | number | boolean | null | undefined>;
+    body?: unknown;
+    timeoutMs?: number;
+    profile?: string;
+}
+export interface BrowserProxyFile {
+    path: string;
+    base64: string;
+    mimeType?: string;
+}
+export interface BrowserProxyResult {
+    result: unknown;
+    files?: BrowserProxyFile[];
+}
+export declare function createBrowserProxy(controlPort: number, allowProfiles: string[], log: Logger): {
+    handleProxy: (params: BrowserProxyParams) => Promise<BrowserProxyResult>;
+};
+//# sourceMappingURL=browser-proxy.d.ts.map

package/dist/commands/browser-proxy.js

@@ -0,0 +1,164 @@
+import { readFile, stat } from "node:fs/promises";
+import { extname } from "node:path";
+const TAG = "BrowserProxy";
+const MAX_FILE_BYTES = 10 * 1024 * 1024; // 10 MB
+// ---------- MIME detection (extension-based) ----------
+const MIME_MAP = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+    ".pdf": "application/pdf",
+    ".html": "text/html",
+    ".json": "application/json",
+    ".txt": "text/plain",
+    ".zip": "application/zip",
+    ".mp4": "video/mp4",
+    ".webm": "video/webm",
+};
+function detectMime(filePath) {
+    return MIME_MAP[extname(filePath).toLowerCase()] ?? "application/octet-stream";
+}
+// ---------- Helpers ----------
+/** Extract file paths from a browser response (path, imagePath, download.path) */
+function collectFilePaths(payload) {
+    const paths = new Set();
+    const obj = typeof payload === "object" && payload !== null
+        ? payload
+        : null;
+    if (!obj)
+        return [];
+    if (typeof obj.path === "string" && obj.path.trim()) {
+        paths.add(obj.path.trim());
+    }
+    if (typeof obj.imagePath === "string" && obj.imagePath.trim()) {
+        paths.add(obj.imagePath.trim());
+    }
+    const download = obj.download;
+    if (download && typeof download === "object") {
+        const dlPath = download.path;
+        if (typeof dlPath === "string" && dlPath.trim()) {
+            paths.add(dlPath.trim());
+        }
+    }
+    return [...paths];
+}
+/** Read a file from disk, check size, encode as base64 */
+async function readProxyFile(filePath) {
+    const st = await stat(filePath).catch(() => null);
+    if (!st || !st.isFile())
+        return null;
+    if (st.size > MAX_FILE_BYTES) {
+        throw new Error(`File exceeds ${Math.round(MAX_FILE_BYTES / (1024 * 1024))}MB: ${filePath}`);
+    }
+    const buffer = await readFile(filePath);
+    return {
+        path: filePath,
+        base64: buffer.toString("base64"),
+        mimeType: detectMime(filePath),
+    };
+}
+// ---------- Proxy handler ----------
+export function createBrowserProxy(controlPort, allowProfiles, log) {
+    const baseUrl = `http://127.0.0.1:${controlPort}`;
+    function isProfileAllowed(profile) {
+        if (allowProfiles.length === 0)
+            return true;
+        if (!profile)
+            return false;
+        return allowProfiles.includes(profile.trim());
+    }
+    async function handleProxy(params) {
+        const pathValue = typeof params.path === "string" ? params.path.trim() : "";
+        if (!pathValue) {
+            throw new Error("INVALID_REQUEST: path required");
+        }
+        const method = (typeof params.method === "string" ? params.method.toUpperCase() : "GET");
+        const path = pathValue.startsWith("/") ? pathValue : `/${pathValue}`;
+        const requestedProfile = typeof params.profile === "string" ? params.profile.trim() : "";
+        // Profile allowlist check
+        if (allowProfiles.length > 0 && path !== "/profiles") {
+            const profileToCheck = requestedProfile || "default";
+            if (!isProfileAllowed(profileToCheck)) {
+                throw new Error("INVALID_REQUEST: browser profile not allowed");
+            }
+        }
+        // Build URL with query params
+        const url = new URL(path, baseUrl);
+        if (requestedProfile) {
+            url.searchParams.set("profile", requestedProfile);
+        }
+        const rawQuery = params.query ?? {};
+        for (const [key, value] of Object.entries(rawQuery)) {
+            if (value === undefined || value === null)
+                continue;
+            url.searchParams.set(key, String(value));
+        }
+        log.info(TAG, `proxy: ${method} ${url.pathname}${url.search}`);
+        // HTTP fetch to local browser server
+        const fetchOpts = { method };
+        if (params.body !== undefined && method !== "GET") {
+            fetchOpts.headers = { "Content-Type": "application/json" };
+            fetchOpts.body = JSON.stringify(params.body);
+        }
+        const timeoutMs = Math.max(1000, Math.min(120_000, params.timeoutMs ?? 30_000));
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        fetchOpts.signal = controller.signal;
+        let response;
+        try {
+            response = await fetch(url.toString(), fetchOpts);
+        }
+        catch (err) {
+            throw new Error(`Browser server unreachable: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        let result;
+        const contentType = response.headers.get("content-type") ?? "";
+        if (contentType.includes("application/json")) {
+            result = await response.json();
+        }
+        else {
+            result = await response.text();
+        }
+        if (!response.ok) {
+            const message = result && typeof result === "object" && "error" in result
+                ? String(result.error)
+                : `HTTP ${response.status}`;
+            throw new Error(message);
+        }
+        // Filter profiles by allowlist if applicable
+        if (allowProfiles.length > 0 && path === "/profiles") {
+            const obj = typeof result === "object" && result !== null ? result : {};
+            const profiles = Array.isArray(obj.profiles) ? obj.profiles : [];
+            obj.profiles = profiles.filter((entry) => {
+                if (!entry || typeof entry !== "object")
+                    return false;
+                const name = entry.name;
+                return typeof name === "string" && allowProfiles.includes(name);
+            });
+        }
+        // Collect and read files (screenshots, PDFs, downloads)
+        let files;
+        const paths = collectFilePaths(result);
+        if (paths.length > 0) {
+            const loaded = await Promise.all(paths.map(async (p) => {
+                const file = await readProxyFile(p);
+                if (!file) {
+                    throw new Error(`Browser proxy file not found: ${p}`);
+                }
+                return file;
+            }));
+            if (loaded.length > 0) {
+                files = loaded;
+            }
+        }
+        return files ? { result, files } : { result };
+    }
+    return { handleProxy };
+}
+//# sourceMappingURL=browser-proxy.js.map

package/dist/commands/shell.d.ts

@@ -0,0 +1,25 @@
+import type { NodeConfig } from "../config.js";
+import type { Logger } from "../logger.js";
+export interface ShellRunParams {
+    cmd: string;
+    args?: string[];
+    cwd?: string;
+    timeout?: number;
+    env?: Record<string, string>;
+}
+export interface ShellRunResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+}
+export interface ShellWhichParams {
+    cmd: string;
+}
+export interface ShellWhichResult {
+    path: string | null;
+}
+export declare function createShellCommands(config: NodeConfig, log: Logger): {
+    shellRun: (params: ShellRunParams) => Promise<ShellRunResult>;
+    shellWhich: (params: ShellWhichParams) => Promise<ShellWhichResult>;
+};
+//# sourceMappingURL=shell.d.ts.map

package/dist/commands/shell.js

@@ -0,0 +1,62 @@
+import { spawn, execFile } from "node:child_process";
+const TAG = "Shell";
+export function createShellCommands(config, log) {
+    const shellConfig = config.commands.shell;
+    function validateCommand(cmd) {
+        if (!shellConfig.enabled) {
+            throw new Error("Shell commands are disabled");
+        }
+        if (shellConfig.allowlist.length > 0 && !shellConfig.allowlist.includes(cmd)) {
+            throw new Error(`Command "${cmd}" is not in the allowlist`);
+        }
+    }
+    async function shellRun(params) {
+        validateCommand(params.cmd);
+        log.info(TAG, `run: ${params.cmd} ${(params.args ?? []).join(" ")}`);
+        const timeout = params.timeout ?? shellConfig.timeout;
+        return new Promise((resolve) => {
+            const proc = spawn(params.cmd, params.args ?? [], {
+                cwd: params.cwd,
+                env: params.env ? { ...process.env, ...params.env } : undefined,
+                timeout,
+                shell: false,
+            });
+            const stdoutChunks = [];
+            const stderrChunks = [];
+            proc.stdout.on("data", (chunk) => stdoutChunks.push(chunk));
+            proc.stderr.on("data", (chunk) => stderrChunks.push(chunk));
+            proc.on("close", (code) => {
+                log.info(TAG, `run: ${params.cmd} exited with code ${code}`);
+                resolve({
+                    stdout: Buffer.concat(stdoutChunks).toString("utf-8"),
+                    stderr: Buffer.concat(stderrChunks).toString("utf-8"),
+                    exitCode: code,
+                });
+            });
+            proc.on("error", (err) => {
+                log.error(TAG, `run: ${params.cmd} error: ${err.message}`);
+                resolve({
+                    stdout: Buffer.concat(stdoutChunks).toString("utf-8"),
+                    stderr: err.message,
+                    exitCode: 1,
+                });
+            });
+        });
+    }
+    async function shellWhich(params) {
+        validateCommand(params.cmd);
+        log.debug(TAG, `which: ${params.cmd}`);
+        return new Promise((resolve) => {
+            execFile("which", [params.cmd], (err, stdout) => {
+                if (err) {
+                    resolve({ path: null });
+                }
+                else {
+                    resolve({ path: stdout.trim() });
+                }
+            });
+        });
+    }
+    return { shellRun, shellWhich };
+}
+//# sourceMappingURL=shell.js.map

package/dist/config.d.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+declare const ConfigSchema: z.ZodObject<{
+    node: z.ZodObject<{
+        id: z.ZodDefault<z.ZodString>;
+        displayName: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>;
+    gateway: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        url: z.ZodDefault<z.ZodString>;
+        token: z.ZodDefault<z.ZodString>;
+        signature: z.ZodDefault<z.ZodString>;
+        reconnectMs: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>;
+    logs: z.ZodDefault<z.ZodObject<{
+        dir: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+    commands: z.ZodObject<{
+        shell: z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            allowlist: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            timeout: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    browser: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        controlPort: z.ZodDefault<z.ZodNumber>;
+        headless: z.ZodDefault<z.ZodBoolean>;
+        noSandbox: z.ZodDefault<z.ZodBoolean>;
+        attachOnly: z.ZodDefault<z.ZodBoolean>;
+        executablePath: z.ZodOptional<z.ZodString>;
+        allowProfiles: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type NodeConfig = z.infer<typeof ConfigSchema>;
+export declare function loadConfig(opts?: {
+    configPath?: string;
+    ws?: string;
+    name?: string;
+}): NodeConfig;
+export {};
+//# sourceMappingURL=config.d.ts.map