edge-ai-client-ts 1.0.0

package/dist/crypto/aes-gcm.js

@@ -0,0 +1,90 @@
+/**
+ * AES-256-GCM encrypt/decrypt matching the Rust `DiskDumper` envelope format.
+ *
+ * On-disk format (mirrors `edge-client/src/buffer/disk_dump.rs`):
+ * ```
+ * [KEY_VERSION: 1 byte][nonce: 12 bytes][ciphertext + GCM auth tag: 16 bytes appended]
+ * ```
+ *
+ * The Rust `aes-gcm` crate appends the 16-byte GCM tag to the ciphertext.
+ * Node's `crypto.createCipheriv('aes-256-gcm')` returns the tag separately via
+ * `getAuthTag()`, so we manually append it to match the Rust byte layout.
+ */
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+/** On-disk encrypted-blob format version (first byte of every dump file). */
+export const KEY_VERSION = 1;
+/** AES-256-GCM nonce length (bytes). */
+export const NONCE_LEN = 12;
+/** AES-256-GCM authentication tag length (bytes, appended to ciphertext). */
+export const GCM_TAG_LEN = 16;
+/** Minimum blob size: version(1) + nonce(12) + tag(16). */
+export const MIN_BLOB_LEN = 1 + NONCE_LEN + GCM_TAG_LEN;
+/**
+ * Encrypt `plaintext` with a 32-byte `key` using AES-256-GCM.
+ *
+ * Returns a Buffer in the DiskDumper format:
+ * `[KEY_VERSION][nonce:12][ciphertext][tag:16]`.
+ */
+export function encrypt(key, plaintext) {
+    const nonce = randomBytes(NONCE_LEN);
+    const cipher = createCipheriv('aes-256-gcm', Buffer.from(key), nonce, {
+        authTagLength: GCM_TAG_LEN,
+    });
+    const ciphertext = Buffer.concat([
+        cipher.update(plaintext, 'utf8'),
+        cipher.final(),
+    ]);
+    const tag = cipher.getAuthTag(); // 16 bytes
+    return Buffer.concat([Buffer.from([KEY_VERSION]), nonce, ciphertext, tag]);
+}
+/**
+ * Decrypt a DiskDumper-format blob. Tries `currentKey` first, then
+ * `previousKey` (rotation window). Throws on malformed data or auth failure.
+ */
+export function decrypt(data, currentKey, previousKey) {
+    if (data.length < MIN_BLOB_LEN) {
+        throw new Error('Invalid encrypted data: too short');
+    }
+    const version = data[0];
+    if (version !== KEY_VERSION) {
+        throw new Error(`Unsupported buffer-dump key version ${version} (expected ${KEY_VERSION})`);
+    }
+    const nonce = data.subarray(1, 1 + NONCE_LEN);
+    const ciphertextWithTag = data.subarray(1 + NONCE_LEN);
+    const ciphertextLen = ciphertextWithTag.length - GCM_TAG_LEN;
+    if (ciphertextLen < 0) {
+        throw new Error('Invalid encrypted data: ciphertext shorter than auth tag');
+    }
+    const ciphertext = ciphertextWithTag.subarray(0, ciphertextLen);
+    const tag = ciphertextWithTag.subarray(ciphertextLen);
+    // Trial decryption: current key first (common path), then previous.
+    const currentResult = tryDecrypt(currentKey, nonce, ciphertext, tag);
+    if (currentResult !== undefined) {
+        return { plaintext: currentResult, usedPrevious: false };
+    }
+    if (previousKey !== undefined) {
+        const prevResult = tryDecrypt(previousKey, nonce, ciphertext, tag);
+        if (prevResult !== undefined) {
+            return { plaintext: prevResult, usedPrevious: true };
+        }
+    }
+    throw new Error('Decryption failed: no matching key in keyring');
+}
+/**
+ * Attempt AES-256-GCM decryption → UTF-8 string, or `undefined` on failure
+ * (auth-tag mismatch / malformed). Used for trial decryption across the
+ * keyring so a wrong key is a benign `undefined` rather than a thrown error.
+ */
+function tryDecrypt(key, nonce, ciphertext, tag) {
+    try {
+        const decipher = createDecipheriv('aes-256-gcm', Buffer.from(key), nonce, {
+            authTagLength: GCM_TAG_LEN,
+        });
+        decipher.setAuthTag(tag);
+        const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+        return plaintext.toString('utf8');
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/crypto/hmac.d.ts

@@ -0,0 +1,31 @@
+/**
+ * HMAC-SHA256 + SHA-256 hex digest primitives.
+ *
+ * Mirrors the Rust `hmac` + `sha2` crate usage in the edge-client (used for
+ * TLS SPKI fingerprinting, message integrity, etc.).
+ */
+/**
+ * Compute HMAC-SHA256 of `message` using `key`.
+ * Returns the raw 32-byte digest as a `Buffer`.
+ */
+export declare function hmacSha256(key: Uint8Array, message: Uint8Array | string): Buffer;
+/**
+ * Compute HMAC-SHA256 and return the hex-encoded digest (64 hex chars).
+ */
+export declare function hmacSha256Hex(key: Uint8Array, message: Uint8Array | string): string;
+/**
+ * Compute SHA-256 of `data` and return the hex-encoded digest (64 hex chars).
+ */
+export declare function sha256Hex(data: Uint8Array | string): string;
+/**
+ * Compute SHA-256 of `data` and return the raw 32-byte digest as a `Buffer`.
+ */
+export declare function sha256(data: Uint8Array | string): Buffer;
+/**
+ * Constant-time comparison of two hex strings.
+ * Returns `true` if they are equal (case-insensitive hex, same length).
+ *
+ * Mirrors the Rust `fingerprint_matches` using a timing-safe compare.
+ * If lengths differ, returns `false` immediately (no timing leak of content).
+ */
+export declare function constantTimeHexEquals(a: string, b: string): boolean;

package/dist/crypto/hmac.js

@@ -0,0 +1,52 @@
+/**
+ * HMAC-SHA256 + SHA-256 hex digest primitives.
+ *
+ * Mirrors the Rust `hmac` + `sha2` crate usage in the edge-client (used for
+ * TLS SPKI fingerprinting, message integrity, etc.).
+ */
+import { createHmac, createHash, timingSafeEqual } from 'node:crypto';
+/**
+ * Compute HMAC-SHA256 of `message` using `key`.
+ * Returns the raw 32-byte digest as a `Buffer`.
+ */
+export function hmacSha256(key, message) {
+    const hmac = createHmac('sha256', Buffer.from(key));
+    hmac.update(message);
+    return hmac.digest();
+}
+/**
+ * Compute HMAC-SHA256 and return the hex-encoded digest (64 hex chars).
+ */
+export function hmacSha256Hex(key, message) {
+    return hmacSha256(key, message).toString('hex');
+}
+/**
+ * Compute SHA-256 of `data` and return the hex-encoded digest (64 hex chars).
+ */
+export function sha256Hex(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+/**
+ * Compute SHA-256 of `data` and return the raw 32-byte digest as a `Buffer`.
+ */
+export function sha256(data) {
+    return createHash('sha256').update(data).digest();
+}
+/**
+ * Constant-time comparison of two hex strings.
+ * Returns `true` if they are equal (case-insensitive hex, same length).
+ *
+ * Mirrors the Rust `fingerprint_matches` using a timing-safe compare.
+ * If lengths differ, returns `false` immediately (no timing leak of content).
+ */
+export function constantTimeHexEquals(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    const bufA = Buffer.from(a.toLowerCase(), 'hex');
+    const bufB = Buffer.from(b.toLowerCase(), 'hex');
+    if (bufA.length !== bufB.length || bufA.length === 0) {
+        return bufA.length === bufB.length;
+    }
+    return timingSafeEqual(bufA, bufB);
+}

package/dist/crypto/tls-guard.d.ts

@@ -0,0 +1,36 @@
+/**
+ * LAYER-1: TLS enforcement guard — pure decision logic.
+ *
+ * Mirrors `edge-client/src/network/tls_guard.rs`.
+ *
+ * Refuses to connect to a plaintext `ws://` URL when `NODE_ENV=production`
+ * (or `EDGEAI_REQUIRE_TLS=1`). Defense-in-depth: even if an operator
+ * misconfigures the deploy, a mis-pinned cert cannot silently downgrade
+ * to plaintext over the wire.
+ *
+ * Rules:
+ *   - `wss://`                              → Allow (TLS path)
+ *   - `ws://` + `NODE_ENV=production`        → Refuse (hard fail)
+ *   - `ws://` + `EDGEAI_REQUIRE_TLS=1`       → Refuse (operator forced TLS)
+ *   - `ws://` + dev/test                     → Allow (dev escape hatch)
+ */
+/** Decision for whether the configured URL is acceptable. */
+export type TlsGuardDecision = {
+    readonly kind: 'Allow';
+} | {
+    readonly kind: 'Refuse';
+    readonly reason: string;
+};
+/**
+ * Pure decision function. Takes explicit env values (not `process.env`)
+ * so it is race-free to unit-test.
+ *
+ * @param url        The relay WebSocket URL.
+ * @param nodeEnv    The `NODE_ENV` env value (undefined if unset).
+ * @param requireTls Whether `EDGEAI_REQUIRE_TLS=1` is set.
+ */
+export declare function decideTls(url: string, nodeEnv: string | undefined, requireTls: boolean): TlsGuardDecision;
+/**
+ * Convenience wrapper that reads `process.env`. Mirrors Rust `decide_tls(url)`.
+ */
+export declare function decideTlsFromEnv(url: string): TlsGuardDecision;

package/dist/crypto/tls-guard.js

@@ -0,0 +1,54 @@
+/**
+ * LAYER-1: TLS enforcement guard — pure decision logic.
+ *
+ * Mirrors `edge-client/src/network/tls_guard.rs`.
+ *
+ * Refuses to connect to a plaintext `ws://` URL when `NODE_ENV=production`
+ * (or `EDGEAI_REQUIRE_TLS=1`). Defense-in-depth: even if an operator
+ * misconfigures the deploy, a mis-pinned cert cannot silently downgrade
+ * to plaintext over the wire.
+ *
+ * Rules:
+ *   - `wss://`                              → Allow (TLS path)
+ *   - `ws://` + `NODE_ENV=production`        → Refuse (hard fail)
+ *   - `ws://` + `EDGEAI_REQUIRE_TLS=1`       → Refuse (operator forced TLS)
+ *   - `ws://` + dev/test                     → Allow (dev escape hatch)
+ */
+/**
+ * Pure decision function. Takes explicit env values (not `process.env`)
+ * so it is race-free to unit-test.
+ *
+ * @param url        The relay WebSocket URL.
+ * @param nodeEnv    The `NODE_ENV` env value (undefined if unset).
+ * @param requireTls Whether `EDGEAI_REQUIRE_TLS=1` is set.
+ */
+export function decideTls(url, nodeEnv, requireTls) {
+    if (url.startsWith('wss://')) {
+        return { kind: 'Allow' };
+    }
+    // Below this point: URL is ws:// (plaintext).
+    const isProduction = nodeEnv === 'production';
+    if (isProduction) {
+        return {
+            kind: 'Refuse',
+            reason: `NODE_ENV=production but relay URL uses plaintext ws:// (${url}). ` +
+                'Production deployments MUST use wss://. Set EDGEAI_REQUIRE_TLS=0 ' +
+                'only if you have an alternative transport-encryption layer ' +
+                '(e.g. a WireGuard tunnel to the relay host).',
+        };
+    }
+    if (requireTls) {
+        return {
+            kind: 'Refuse',
+            reason: `EDGEAI_REQUIRE_TLS=1 but relay URL uses plaintext ws:// (${url}). ` +
+                'Either change the URL to wss:// or unset EDGEAI_REQUIRE_TLS.',
+        };
+    }
+    return { kind: 'Allow' };
+}
+/**
+ * Convenience wrapper that reads `process.env`. Mirrors Rust `decide_tls(url)`.
+ */
+export function decideTlsFromEnv(url) {
+    return decideTls(url, process.env.NODE_ENV, process.env.EDGEAI_REQUIRE_TLS === '1');
+}

package/dist/daemon/manager.d.ts

@@ -0,0 +1,82 @@
+export type Platform = 'linux' | 'darwin' | 'win32' | 'freebsd' | 'other';
+export interface ServiceInstallOpts {
+    /** Directory where the binary lives (e.g. `$HOME/.local/bin`). */
+    installDir: string;
+    /** Directory where the config + secrets live. */
+    configDir: string;
+    /** Absolute path to the binary / shim to exec. */
+    binaryPath: string;
+    /** Optional env vars passed to the service (RELAY_URL, AGENT_ID, etc.). */
+    userEnv?: Record<string, string>;
+    /** Service name (default `edge-client-ts`). */
+    serviceName?: string;
+}
+export interface ServiceStatus {
+    installed: boolean;
+    running: boolean;
+    platform: Platform;
+    detail: string;
+}
+export declare class ServiceManager {
+    static detectPlatform(): Platform;
+    /** Default service name. */
+    static defaultServiceName(): string;
+    /** Default install dir per platform (user-scoped, no root). */
+    static defaultInstallDir(platform?: Platform): string;
+    /** Resolve the service-unit file path for the current platform. */
+    getServiceFilePath(platform: Platform, serviceName: string): string;
+    /** Linux systemd --user unit file contents. */
+    generateSystemdUnit(opts: ServiceInstallOpts, serviceName: string): string;
+    /** macOS LaunchAgent plist contents. */
+    generateLaunchdPlist(opts: ServiceInstallOpts, serviceName: string): string;
+    /** Windows Task Scheduler XML (no admin needed when created per-user). */
+    generateSchtasksXml(opts: ServiceInstallOpts, serviceName: string): string;
+    install(opts: ServiceInstallOpts): Promise<void>;
+    uninstall(opts: ServiceInstallOpts): Promise<void>;
+    start(serviceName?: string): Promise<void>;
+    stop(serviceName?: string): Promise<void>;
+    status(serviceName?: string): Promise<ServiceStatus>;
+    isInstalled(serviceName?: string): Promise<boolean>;
+}
+/** Expand `~` / `$HOME` / `%USERPROFILE%` placeholders. */
+export declare function expandUser(p: string): string;
+/**
+ * Validate a string is safe to interpolate into a systemd unit file.
+ * systemd's INI-like parser treats `[section]` at the start of a line
+ * as a section boundary and `Key=` as a directive. A newline in any
+ * interpolated value therefore lets an attacker close the current
+ * directive, start a new `[Service]` section, and inject `ExecStart=`,
+ * `Environment=`, etc. We reject anything containing ASCII control
+ * characters; legitimate values never need them.
+ */
+export declare function escapeSystemdValue(value: string, fieldName: string): string;
+/**
+ * XML-escape a string for use inside an attribute value or element
+ * text in plist/schtasks XML. The chars `<`, `>`, `&`, `"`, `'`
+ * MUST be escaped or an attacker can break out of the surrounding
+ * construct (`</string><key>ProgramArguments</key>...`) and inject
+ * arbitrary plist/schtasks directives. See C1 in security-review
+ * 2026-07-11.
+ */
+export declare function escapeXmlAttr(value: string): string;
+/**
+ * Validate that a service name is a valid systemd unit / plist label /
+ * schtasks task name. The charset is intentionally narrow:
+ *   - alphanumerics, dash, underscore, dot
+ *   - no path separators, no newlines, no leading dot
+ * Mirrors the constraints checked by `systemd-escape`, launchd
+ * `Label=`, and `schtasks` at registration time — failing here gives a
+ * clear "invalid serviceName" error instead of a confusing OS-level
+ * "unit name not valid" rejection at install.
+ */
+export declare function validateServiceName(name: string): void;
+/**
+ * Validate that an env var name is a portable POSIX identifier. systemd,
+ * launchd, and schtasks all follow the same rules:
+ *   - [A-Za-z_][A-Za-z0-9_]*
+ *   - no leading digit
+ *   - empty refused
+ * A name like `RELAY;ExecStart=/bin/sh` would otherwise inject
+ * additional directives.
+ */
+export declare function validateEnvName(name: string): void;