edge-ai-client-ts 1.0.0

package/dist/config/settings.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Edge-client configuration — mirrors `edge-client/src/config/settings.rs`,
+ * `machine_id.rs`, `device_secret.rs`, and `mod.rs`.
+ *
+ * All field names EXACTLY match the Rust struct fields (snake_case), so a
+ * `config.toml` written by the Rust client round-trips through the TS client
+ * and vice versa.
+ *
+ * Security invariants preserved from Rust:
+ *  - `machine_id`: UUIDv4, generated once, persisted atomically.
+ *  - `device_secret`: atomic write, chmod 600 on Unix.
+ *  - `relay.device_secret`: `skip_serializing` — never written to config.toml.
+ *  - `enforceHostnameOrToken`: refuse to start with empty machine_id + no token.
+ *  - Buffer key + edge-auth-token resolution: env var wins over config.
+ */
+import type { CmdGateConfig } from './cmd-gate.js';
+export interface ServerConfig {
+    ws_url: string;
+    /** Relay URL for `network_mode='lan'`. */
+    ws_url_lan?: string;
+    /** Relay URL for `network_mode='wan'`. */
+    ws_url_wan?: string;
+}
+export interface AgentConfig {
+    default_agent_id: string;
+}
+export interface BufferConfig {
+    max_memory_mb: number;
+    flush_interval_ms: number;
+    ack_timeout_ms: number;
+    max_retries: number;
+    /** AES-256-GCM key for buffer-dump encryption (hex, 64 chars = 32 bytes). */
+    key?: string;
+    /** Directory for encrypted overflow buffer dumps. */
+    dump_dir?: string;
+}
+export interface LoggingConfig {
+    level: string;
+    local_log_dir: string;
+}
+export interface ShellConfig {
+    /** Master on/off. Default false. */
+    enabled: boolean;
+    default_cols: number;
+    default_rows: number;
+}
+export interface ResourcesConfig {
+    /** Hard RAM cap in MB (0 = unlimited/legacy). Default 2048. */
+    memory_max_mb: number;
+    /** CPU quota in percent (200 = 2 cores, 0 = unlimited). Default 50. */
+    cpu_quota_percent: number;
+    /** Max tasks/processes (0 = unlimited). Default 256. */
+    tasks_max: number;
+}
+export interface RelayConfig {
+    /** Per-edge shared secret (`EDGE_AUTH_TOKEN`). */
+    auth_token?: string;
+    /**
+     * Per-device credential issued by relay at enrollment. Unique per machine.
+     * `skip_serializing` in Rust — NEVER written to config.toml.
+     */
+    device_secret?: string;
+    /** Pinned TLS SPKI fingerprint (SHA-256 hex, 64 chars). */
+    fingerprint?: string;
+}
+export interface Settings {
+    server: ServerConfig;
+    agent: AgentConfig;
+    buffer: BufferConfig;
+    logging: LoggingConfig;
+    machine_id: string;
+    /** Operator who owns this machine (set by `enroll`). */
+    owner_operator_id?: string;
+    /** Path to the `pi` binary (default "pi"; Windows often "pi.cmd"). */
+    pi_path?: string;
+    shell: ShellConfig;
+    relay: RelayConfig;
+    resources: ResourcesConfig;
+    cmd_gate: CmdGateConfig;
+}
+/**
+ * Versioned keyring for buffer-dump encryption (A4 key rotation).
+ * `current` encrypts every new dump; `previous` decrypts dumps written
+ * before a rotation (then lazily re-encrypted with `current`).
+ */
+export interface Keyring {
+    current: Uint8Array;
+    previous?: Uint8Array;
+}
+/** Construct the default Settings (factory). Mirrors Rust `Settings::default()`. */
+export declare function defaultSettings(): Settings;
+/**
+ * The edge-ai-agent config directory. Mirrors Rust's `dirs::config_dir()`:
+ *   - Linux:   `$XDG_CONFIG_HOME/edge-ai-agent` or `~/.config/edge-ai-agent`
+ *   - macOS:   `~/Library/Application Support/edge-ai-agent`
+ *   - Windows: `%APPDATA%\edge-ai-agent`
+ *
+ * Creates the directory if missing.
+ */
+export declare function configDir(): string;
+/** Path to `config.toml`. */
+export declare function configPath(): string;
+/**
+ * Write `data` to `filePath` atomically: write a sibling `.tmp` file then
+ * rename over the destination. Prevents torn writes. Mirrors the Rust
+ * `atomic_write` pattern in `disk_dump.rs` / `persistence.rs`.
+ *
+ * On Unix, optionally restricts the file to owner-only (0600).
+ */
+export declare function atomicWriteFile(filePath: string, data: string | Buffer, options?: {
+    readonly mode?: number;
+}): void;
+/**
+ * Read-or-create the persisted machine_id inside `configDir`.
+ *
+ * 1. If `<configDir>/machine_id` exists and is non-empty after trim → return it.
+ * 2. Otherwise: create `configDir`, mint a fresh UUIDv4, atomically persist.
+ *
+ * Pure inner helper (takes explicit dir) for unit-testability.
+ */
+export declare function generateMachineIdForDir(configDirPath: string): string;
+/** Public entry point: resolve config dir and delegate. Mirrors `generate()`. */
+export declare function generateMachineId(): string;
+/**
+ * Read the persisted device secret from `configDir`, or `undefined`.
+ * Pure inner helper.
+ */
+export declare function loadDeviceSecretForDir(configDirPath: string): string | undefined;
+/** Read the persisted device secret from the real config dir, or `undefined`. */
+export declare function loadDeviceSecret(): string | undefined;
+/**
+ * Persist a device secret to `configDir` atomically. Overwrites existing.
+ * Pure inner helper.
+ */
+export declare function storeDeviceSecretForDir(configDirPath: string, secret: string): void;
+/** Persist a device secret to the real config dir (atomic write). */
+export declare function storeDeviceSecret(secret: string): void;
+/**
+ * Restrict the persisted secret file to owner-only (0600). Best-effort on
+ * Windows (no-op). Mirrors `restrict_perms`.
+ */
+export declare function restrictDeviceSecretPerms(configDirPath: string): void;
+/** Persist the current settings to `config.toml`. Mirrors Rust `save()`. */
+export declare function saveSettings(settings: Settings): void;
+/**
+ * Parse a TOML or JSON config string into a validated `Settings`.
+ * Missing fields fall back to defaults. Mirrors Rust `toml::from_str`.
+ */
+export declare function parseSettings(content: string): Settings;
+/**
+ * Load settings from `config.toml` (or `config.json`).
+ *
+ * - If the config file doesn't exist → write defaults and return them.
+ * - Applies the `EDGE_OWNER_OPERATOR_ID` env override (env wins over config).
+ * - If `machine_id` is empty → generate a UUIDv4, persist, and save.
+ *
+ * Mirrors Rust `Settings::load()`.
+ */
+export declare function loadSettings(): Settings;
+/** True if any resource limit is set (non-zero). */
+export declare function hasResourceLimits(config: ResourcesConfig): boolean;
+/** systemd `MemoryMax=` directive value, or undefined if unlimited. */
+export declare function memoryMaxDirective(config: ResourcesConfig): string | undefined;
+/** systemd `CPUQuota=` directive value, or undefined if unlimited. */
+export declare function cpuQuotaDirective(config: ResourcesConfig): string | undefined;
+/** systemd `TasksMax=` directive value, or undefined if unlimited. */
+export declare function tasksMaxDirective(config: ResourcesConfig): string | undefined;
+/**
+ * Resolve resource limits from env overrides. Env wins over config.
+ * Env names: `EDGE_MEMORY_MAX_MB`, `EDGE_CPU_QUOTA_PERCENT`, `EDGE_TASKS_MAX`.
+ */
+export declare function resolveResources(env: Record<string, string | undefined>, config: ResourcesConfig): ResourcesConfig;
+/** Decode a hex-encoded 32-byte key. Throws on invalid hex or wrong length. */
+export declare function decodeHexKey(hex: string): Uint8Array;
+/**
+ * Resolve the buffer encryption key.
+ * Precedence: `EDGE_BUFFER_KEY` env > `config.toml` `buffer.key`.
+ * Throws if unconfigured (fail-closed).
+ */
+export declare function loadBufferKey(settings: Settings): Uint8Array;
+/**
+ * Resolve the buffer-encryption keyring (A4 key rotation).
+ * `current` follows the same precedence as `loadBufferKey`.
+ * `previous` is `EDGE_BUFFER_KEY_PREVIOUS` env (optional, rotation window only).
+ */
+export declare function loadKeyring(settings: Settings): Keyring;
+/**
+ * Pure precedence resolver for the edge-auth token. Env wins; whitespace is
+ * trimmed and empty values treated as unset.
+ */
+export declare function resolveEdgeAuthToken(envValue: string | undefined, configValue: string | undefined): string | undefined;
+/**
+ * Resolve the edge-auth shared secret.
+ * Precedence: `EDGE_AUTH_TOKEN` env → `config.toml` `[relay] auth_token`.
+ * Returns `undefined` when unconfigured.
+ */
+export declare function loadEdgeAuthToken(settings: Settings): string | undefined;
+/**
+ * Edge-side mirror of the relay's auth-escape hatch.
+ * Active iff `AUTH_DISABLED=1` OR `ALLOW_AUTH_BYPASS=1`.
+ */
+export declare function edgeAuthEscapeHatchActive(): boolean;
+/**
+ * Refuse to start with an empty `machine_id` when there is no manual token.
+ * Mirrors `enforce_hostname_or_token`.
+ *
+ * Returns `undefined` on success or an error `string` on refusal.
+ */
+export declare function enforceHostnameOrToken(machineId: string): string | undefined;