edge-ai-client-ts 1.0.0

package/dist/config/settings.js

@@ -0,0 +1,627 @@
+/**
+ * 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 { randomUUID } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { parse as parseToml, stringify as stringifyToml } from 'smol-toml';
+import { defaultCmdGateConfig } from './cmd-gate.js';
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+function defaultShellConfig() {
+    return { enabled: false, default_cols: 80, default_rows: 24 };
+}
+function defaultResourcesConfig() {
+    return { memory_max_mb: 2048, cpu_quota_percent: 50, tasks_max: 256 };
+}
+/** Construct the default Settings (factory). Mirrors Rust `Settings::default()`. */
+export function defaultSettings() {
+    return {
+        server: {
+            ws_url: 'ws://localhost:3001/edge',
+        },
+        agent: {
+            default_agent_id: 'worker_default',
+        },
+        buffer: {
+            max_memory_mb: 50,
+            flush_interval_ms: 100,
+            ack_timeout_ms: 5000,
+            max_retries: 3,
+        },
+        logging: {
+            level: 'info',
+            local_log_dir: 'logs',
+        },
+        machine_id: '',
+        shell: defaultShellConfig(),
+        relay: {},
+        resources: defaultResourcesConfig(),
+        cmd_gate: defaultCmdGateConfig(),
+    };
+}
+// ---------------------------------------------------------------------------
+// Runtime guards (zero `any`)
+// ---------------------------------------------------------------------------
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function asString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function asNonEmptyString(value) {
+    if (typeof value === 'string' && value.length > 0) {
+        return value;
+    }
+    return undefined;
+}
+function asNumber(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return value;
+    }
+    // TOML integers may arrive as bigint via smol-toml
+    if (typeof value === 'bigint') {
+        return Number(value);
+    }
+    return undefined;
+}
+function asBoolean(value) {
+    return typeof value === 'boolean' ? value : undefined;
+}
+function asStringArray(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    return value.filter((v) => typeof v === 'string');
+}
+// ---------------------------------------------------------------------------
+// Config directory resolution
+// ---------------------------------------------------------------------------
+/**
+ * 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 function configDir() {
+    const home = os.homedir();
+    let base;
+    if (process.platform === 'win32') {
+        base = process.env.APPDATA ?? path.join(home, 'AppData', 'Roaming');
+    }
+    else if (process.platform === 'darwin') {
+        base = path.join(home, 'Library', 'Application Support');
+    }
+    else {
+        // Linux / other Unix — XDG
+        base = process.env.XDG_CONFIG_HOME ?? path.join(home, '.config');
+    }
+    const dir = path.join(base, 'edge-ai-agent');
+    fs.mkdirSync(dir, { recursive: true });
+    return dir;
+}
+/** Path to `config.toml`. */
+export function configPath() {
+    return path.join(configDir(), 'config.toml');
+}
+// ---------------------------------------------------------------------------
+// Atomic file writes
+// ---------------------------------------------------------------------------
+/**
+ * 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 function atomicWriteFile(filePath, data, options) {
+    const dir = path.dirname(filePath);
+    const name = path.basename(filePath);
+    const tmp = path.join(dir, `.${name}.tmp`);
+    const encoding = typeof data === 'string' ? 'utf8' : undefined;
+    // H2 — SECURITY FIX (security-review 2026-07-11): eliminate the
+    // writeFileSync → chmodSync TOCTOU window where the temp file would
+    // briefly exist world-readable (default mode 0644 on Linux) before
+    // the chmod tightens it. We open the temp file with the desired mode
+    // atomically, write via the fd, then close + rename — no other process
+    // sees a permissive-mode intermediate state. Mirrors the
+    // disk-queue.ts pattern (`fs.open(path, 'w', 0o600)`).
+    const mode = options?.mode ?? 0o644;
+    const fd = fs.openSync(tmp, 'w', mode);
+    try {
+        // fs.writeSync has separate overloads for string vs Buffer — branch on type
+        // so TypeScript picks the correct one. The `encoding` param is only used
+        // for the string branch (Buffer is always binary).
+        if (typeof data === 'string') {
+            fs.writeSync(fd, data, undefined, encoding);
+        }
+        else {
+            fs.writeSync(fd, data);
+        }
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    fs.renameSync(tmp, filePath);
+}
+// ---------------------------------------------------------------------------
+// machine_id — UUIDv4 persisted atomically (mirrors machine_id.rs)
+// ---------------------------------------------------------------------------
+/**
+ * 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 function generateMachineIdForDir(configDirPath) {
+    const idPath = path.join(configDirPath, 'machine_id');
+    // Persistence fast path
+    if (fs.existsSync(idPath)) {
+        try {
+            const content = fs.readFileSync(idPath, 'utf8');
+            const trimmed = content.trim();
+            if (trimmed.length > 0) {
+                return trimmed;
+            }
+        }
+        catch {
+            // fall through to generation
+        }
+    }
+    // Ensure config dir exists
+    fs.mkdirSync(configDirPath, { recursive: true });
+    const id = randomUUID();
+    atomicWriteFile(idPath, id);
+    return id;
+}
+/** Public entry point: resolve config dir and delegate. Mirrors `generate()`. */
+export function generateMachineId() {
+    return generateMachineIdForDir(configDir());
+}
+// ---------------------------------------------------------------------------
+// device_secret — per-device credential persistence (mirrors device_secret.rs)
+// ---------------------------------------------------------------------------
+/**
+ * Read the persisted device secret from `configDir`, or `undefined`.
+ * Pure inner helper.
+ */
+export function loadDeviceSecretForDir(configDirPath) {
+    const secretPath = path.join(configDirPath, 'device_secret');
+    try {
+        const content = fs.readFileSync(secretPath, 'utf8');
+        const trimmed = content.trim();
+        return trimmed.length > 0 ? trimmed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Read the persisted device secret from the real config dir, or `undefined`. */
+export function loadDeviceSecret() {
+    return loadDeviceSecretForDir(configDir());
+}
+/**
+ * Persist a device secret to `configDir` atomically. Overwrites existing.
+ * Pure inner helper.
+ */
+export function storeDeviceSecretForDir(configDirPath, secret) {
+    fs.mkdirSync(configDirPath, { recursive: true });
+    const secretPath = path.join(configDirPath, 'device_secret');
+    atomicWriteFile(secretPath, secret.trim(), { mode: 0o600 });
+}
+/** Persist a device secret to the real config dir (atomic write). */
+export function storeDeviceSecret(secret) {
+    storeDeviceSecretForDir(configDir(), secret);
+}
+/**
+ * Restrict the persisted secret file to owner-only (0600). Best-effort on
+ * Windows (no-op). Mirrors `restrict_perms`.
+ */
+export function restrictDeviceSecretPerms(configDirPath) {
+    if (process.platform === 'win32')
+        return;
+    const secretPath = path.join(configDirPath, 'device_secret');
+    if (fs.existsSync(secretPath)) {
+        try {
+            fs.chmodSync(secretPath, 0o600);
+        }
+        catch {
+            // best-effort
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Settings serialization (TOML / JSON)
+// ---------------------------------------------------------------------------
+/**
+ * Strip `device_secret` before serialization (mirrors Rust's
+ * `#[serde(skip_serializing)]`). Also strips any `undefined` optional fields.
+ */
+function settingsToSerializable(settings) {
+    const relayCopy = {};
+    if (settings.relay.auth_token !== undefined) {
+        relayCopy.auth_token = settings.relay.auth_token;
+    }
+    // device_secret intentionally omitted (skip_serializing)
+    if (settings.relay.fingerprint !== undefined) {
+        relayCopy.fingerprint = settings.relay.fingerprint;
+    }
+    const bufferCopy = {
+        max_memory_mb: settings.buffer.max_memory_mb,
+        flush_interval_ms: settings.buffer.flush_interval_ms,
+        ack_timeout_ms: settings.buffer.ack_timeout_ms,
+        max_retries: settings.buffer.max_retries,
+    };
+    if (settings.buffer.key !== undefined) {
+        bufferCopy.key = settings.buffer.key;
+    }
+    if (settings.buffer.dump_dir !== undefined) {
+        bufferCopy.dump_dir = settings.buffer.dump_dir;
+    }
+    const serverCopy = {
+        ws_url: settings.server.ws_url,
+    };
+    if (settings.server.ws_url_lan !== undefined) {
+        serverCopy.ws_url_lan = settings.server.ws_url_lan;
+    }
+    if (settings.server.ws_url_wan !== undefined) {
+        serverCopy.ws_url_wan = settings.server.ws_url_wan;
+    }
+    const result = {
+        server: serverCopy,
+        agent: settings.agent,
+        buffer: bufferCopy,
+        logging: settings.logging,
+        machine_id: settings.machine_id,
+        shell: settings.shell,
+        relay: relayCopy,
+        resources: settings.resources,
+        cmd_gate: settings.cmd_gate,
+    };
+    if (settings.owner_operator_id !== undefined) {
+        result.owner_operator_id = settings.owner_operator_id;
+    }
+    if (settings.pi_path !== undefined) {
+        result.pi_path = settings.pi_path;
+    }
+    return result;
+}
+/** Persist the current settings to `config.toml`. Mirrors Rust `save()`. */
+export function saveSettings(settings) {
+    const cfgPath = configPath();
+    const obj = settingsToSerializable(settings);
+    const content = stringifyToml(obj);
+    fs.writeFileSync(cfgPath, content, 'utf8');
+}
+// ---------------------------------------------------------------------------
+// Settings deserialization (TOML or JSON fallback)
+// ---------------------------------------------------------------------------
+/**
+ * Parse a TOML or JSON config string into a validated `Settings`.
+ * Missing fields fall back to defaults. Mirrors Rust `toml::from_str`.
+ */
+export function parseSettings(content) {
+    let raw;
+    const trimmed = content.trimStart();
+    if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+        raw = JSON.parse(content);
+    }
+    else {
+        raw = parseToml(content);
+    }
+    if (!isRecord(raw)) {
+        throw new Error('Config root is not an object');
+    }
+    return settingsFromRecord(raw);
+}
+function settingsFromRecord(raw) {
+    const d = defaultSettings();
+    const serverRaw = isRecord(raw['server']) ? raw['server'] : {};
+    const agentRaw = isRecord(raw['agent']) ? raw['agent'] : {};
+    const bufferRaw = isRecord(raw['buffer']) ? raw['buffer'] : {};
+    const loggingRaw = isRecord(raw['logging']) ? raw['logging'] : {};
+    const shellRaw = isRecord(raw['shell']) ? raw['shell'] : {};
+    const relayRaw = isRecord(raw['relay']) ? raw['relay'] : {};
+    const resourcesRaw = isRecord(raw['resources']) ? raw['resources'] : {};
+    const cmdGateRaw = isRecord(raw['cmd_gate']) ? raw['cmd_gate'] : {};
+    // Build ServerConfig with conditional optional fields
+    const server = {
+        ws_url: asNonEmptyString(serverRaw['ws_url']) ?? d.server.ws_url,
+    };
+    const wsUrlLan = asNonEmptyString(serverRaw['ws_url_lan']);
+    if (wsUrlLan !== undefined) {
+        server.ws_url_lan = wsUrlLan;
+    }
+    const wsUrlWan = asNonEmptyString(serverRaw['ws_url_wan']);
+    if (wsUrlWan !== undefined) {
+        server.ws_url_wan = wsUrlWan;
+    }
+    // BufferConfig
+    const buffer = {
+        max_memory_mb: asNumber(bufferRaw['max_memory_mb']) ?? d.buffer.max_memory_mb,
+        flush_interval_ms: asNumber(bufferRaw['flush_interval_ms']) ?? d.buffer.flush_interval_ms,
+        ack_timeout_ms: asNumber(bufferRaw['ack_timeout_ms']) ?? d.buffer.ack_timeout_ms,
+        max_retries: asNumber(bufferRaw['max_retries']) ?? d.buffer.max_retries,
+    };
+    const bufferKey = asNonEmptyString(bufferRaw['key']);
+    if (bufferKey !== undefined) {
+        buffer.key = bufferKey;
+    }
+    const dumpDir = asNonEmptyString(bufferRaw['dump_dir']);
+    if (dumpDir !== undefined) {
+        buffer.dump_dir = dumpDir;
+    }
+    // ShellConfig
+    const shell = {
+        enabled: asBoolean(shellRaw['enabled']) ?? d.shell.enabled,
+        default_cols: asNumber(shellRaw['default_cols']) ?? d.shell.default_cols,
+        default_rows: asNumber(shellRaw['default_rows']) ?? d.shell.default_rows,
+    };
+    // RelayConfig
+    const relay = {};
+    const authToken = asNonEmptyString(relayRaw['auth_token']);
+    if (authToken !== undefined) {
+        relay.auth_token = authToken;
+    }
+    const deviceSecret = asNonEmptyString(relayRaw['device_secret']);
+    if (deviceSecret !== undefined) {
+        relay.device_secret = deviceSecret;
+    }
+    const fingerprint = asNonEmptyString(relayRaw['fingerprint']);
+    if (fingerprint !== undefined) {
+        relay.fingerprint = fingerprint;
+    }
+    // ResourcesConfig
+    const resources = {
+        memory_max_mb: asNumber(resourcesRaw['memory_max_mb']) ?? d.resources.memory_max_mb,
+        cpu_quota_percent: asNumber(resourcesRaw['cpu_quota_percent']) ?? d.resources.cpu_quota_percent,
+        tasks_max: asNumber(resourcesRaw['tasks_max']) ?? d.resources.tasks_max,
+    };
+    // CmdGateConfig
+    const cmdGate = parseCmdGateRecord(cmdGateRaw, d.cmd_gate);
+    // Top-level fields
+    const machine_id = asString(raw['machine_id']) ?? '';
+    const owner_operator_id = asNonEmptyString(raw['owner_operator_id']);
+    const pi_path = asNonEmptyString(raw['pi_path']);
+    const settings = {
+        server,
+        agent: {
+            default_agent_id: asNonEmptyString(agentRaw['default_agent_id']) ?? d.agent.default_agent_id,
+        },
+        buffer,
+        logging: {
+            level: asNonEmptyString(loggingRaw['level']) ?? d.logging.level,
+            local_log_dir: asNonEmptyString(loggingRaw['local_log_dir']) ?? d.logging.local_log_dir,
+        },
+        machine_id,
+        shell,
+        relay,
+        resources,
+        cmd_gate: cmdGate,
+    };
+    if (owner_operator_id !== undefined) {
+        settings.owner_operator_id = owner_operator_id;
+    }
+    if (pi_path !== undefined) {
+        settings.pi_path = pi_path;
+    }
+    return settings;
+}
+function parseCmdGateRecord(raw, fallback) {
+    const modeRaw = asString(raw['mode']);
+    const mode = modeRaw === 'off' || modeRaw === 'warn' || modeRaw === 'block'
+        ? modeRaw
+        : fallback.mode;
+    const allowlist = asStringArray(raw['allowlist']) ?? [...fallback.allowlist];
+    const always_approve = asStringArray(raw['always_approve']) ?? [...fallback.always_approve];
+    const denylist = asStringArray(raw['denylist']) ?? [...fallback.denylist];
+    const timeout_s = asNumber(raw['timeout_s']) ?? fallback.timeout_s;
+    return { mode, allowlist, always_approve, denylist, timeout_s };
+}
+// ---------------------------------------------------------------------------
+// Settings.load()
+// ---------------------------------------------------------------------------
+/**
+ * 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 function loadSettings() {
+    const cfgPath = configPath();
+    if (!fs.existsSync(cfgPath)) {
+        // Also check for config.json fallback
+        const jsonPath = path.join(configDir(), 'config.json');
+        if (fs.existsSync(jsonPath)) {
+            const content = fs.readFileSync(jsonPath, 'utf8');
+            const settings = parseSettings(content);
+            applyEnvOverrides(settings);
+            ensureMachineId(settings);
+            return settings;
+        }
+        const defaults = defaultSettings();
+        defaults.machine_id = generateMachineId();
+        saveSettings(defaults);
+        return defaults;
+    }
+    const content = fs.readFileSync(cfgPath, 'utf8');
+    const settings = parseSettings(content);
+    applyEnvOverrides(settings);
+    ensureMachineId(settings);
+    return settings;
+}
+/** Apply `EDGE_OWNER_OPERATOR_ID` env override (env wins over config). */
+function applyEnvOverrides(settings) {
+    const envOwner = process.env.EDGE_OWNER_OPERATOR_ID;
+    if (envOwner !== undefined) {
+        const trimmed = envOwner.trim();
+        if (trimmed.length > 0) {
+            settings.owner_operator_id = trimmed;
+        }
+    }
+}
+/** Ensure machine_id is non-empty; generate + persist if missing. */
+function ensureMachineId(settings) {
+    if (settings.machine_id.trim().length === 0) {
+        settings.machine_id = generateMachineId();
+        saveSettings(settings);
+    }
+}
+// ---------------------------------------------------------------------------
+// Resource limit helpers (mirrors ResourcesConfig methods)
+// ---------------------------------------------------------------------------
+/** True if any resource limit is set (non-zero). */
+export function hasResourceLimits(config) {
+    return config.memory_max_mb > 0 || config.cpu_quota_percent > 0 || config.tasks_max > 0;
+}
+/** systemd `MemoryMax=` directive value, or undefined if unlimited. */
+export function memoryMaxDirective(config) {
+    return config.memory_max_mb > 0 ? `${config.memory_max_mb}M` : undefined;
+}
+/** systemd `CPUQuota=` directive value, or undefined if unlimited. */
+export function cpuQuotaDirective(config) {
+    return config.cpu_quota_percent > 0 ? `${config.cpu_quota_percent}%` : undefined;
+}
+/** systemd `TasksMax=` directive value, or undefined if unlimited. */
+export function tasksMaxDirective(config) {
+    return config.tasks_max > 0 ? String(config.tasks_max) : 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 function resolveResources(env, config) {
+    function parseEnv(key, fallback) {
+        const raw = env[key];
+        if (raw === undefined)
+            return fallback;
+        const parsed = Number.parseInt(raw.trim(), 10);
+        return Number.isFinite(parsed) ? parsed : fallback;
+    }
+    return {
+        memory_max_mb: parseEnv('EDGE_MEMORY_MAX_MB', config.memory_max_mb),
+        cpu_quota_percent: parseEnv('EDGE_CPU_QUOTA_PERCENT', config.cpu_quota_percent),
+        tasks_max: parseEnv('EDGE_TASKS_MAX', config.tasks_max),
+    };
+}
+// ---------------------------------------------------------------------------
+// Buffer encryption key (mirrors load_buffer_key + load_keyring)
+// ---------------------------------------------------------------------------
+/** Decode a hex-encoded 32-byte key. Throws on invalid hex or wrong length. */
+export function decodeHexKey(hex) {
+    const trimmed = hex.trim();
+    const bytes = Buffer.from(trimmed, 'hex');
+    if (bytes.length !== 32) {
+        throw new Error(`Buffer key must be 32 bytes (64 hex chars), got ${bytes.length} bytes`);
+    }
+    return new Uint8Array(bytes);
+}
+/**
+ * Resolve the buffer encryption key.
+ * Precedence: `EDGE_BUFFER_KEY` env > `config.toml` `buffer.key`.
+ * Throws if unconfigured (fail-closed).
+ */
+export function loadBufferKey(settings) {
+    const envHex = process.env.EDGE_BUFFER_KEY;
+    if (envHex !== undefined && envHex.trim().length > 0) {
+        return decodeHexKey(envHex);
+    }
+    if (settings.buffer.key !== undefined && settings.buffer.key.length > 0) {
+        return decodeHexKey(settings.buffer.key);
+    }
+    throw new Error('Buffer encryption key not configured. Set EDGE_BUFFER_KEY (hex-encoded 32 bytes / 64 hex chars) ' +
+        'or buffer.key in config.toml.');
+}
+/**
+ * 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 function loadKeyring(settings) {
+    const current = loadBufferKey(settings);
+    let previous;
+    const prevHex = process.env.EDGE_BUFFER_KEY_PREVIOUS;
+    if (prevHex !== undefined && prevHex.trim().length > 0) {
+        previous = decodeHexKey(prevHex);
+    }
+    return { current, ...(previous !== undefined ? { previous } : {}) };
+}
+// ---------------------------------------------------------------------------
+// Edge auth token (mirrors resolve_edge_auth_token + load_edge_auth_token)
+// ---------------------------------------------------------------------------
+/**
+ * Pure precedence resolver for the edge-auth token. Env wins; whitespace is
+ * trimmed and empty values treated as unset.
+ */
+export function resolveEdgeAuthToken(envValue, configValue) {
+    if (envValue !== undefined) {
+        const t = envValue.trim();
+        if (t.length > 0) {
+            return t;
+        }
+    }
+    if (configValue !== undefined) {
+        const t = configValue.trim();
+        if (t.length > 0) {
+            return t;
+        }
+    }
+    return undefined;
+}
+/**
+ * Resolve the edge-auth shared secret.
+ * Precedence: `EDGE_AUTH_TOKEN` env → `config.toml` `[relay] auth_token`.
+ * Returns `undefined` when unconfigured.
+ */
+export function loadEdgeAuthToken(settings) {
+    return resolveEdgeAuthToken(process.env.EDGE_AUTH_TOKEN, settings.relay.auth_token);
+}
+/**
+ * Edge-side mirror of the relay's auth-escape hatch.
+ * Active iff `AUTH_DISABLED=1` OR `ALLOW_AUTH_BYPASS=1`.
+ */
+export function edgeAuthEscapeHatchActive() {
+    return process.env.AUTH_DISABLED === '1' || process.env.ALLOW_AUTH_BYPASS === '1';
+}
+/**
+ * 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 function enforceHostnameOrToken(machineId) {
+    const trimmed = machineId.trim();
+    if (trimmed.length > 0) {
+        return undefined;
+    }
+    // No machine_id — check whether the operator supplied a manual token.
+    const token = process.env.EDGE_AUTH_TOKEN;
+    if (token !== undefined && token.trim().length > 0) {
+        return undefined;
+    }
+    return ('Refusing to start: machine_id is empty AND EDGE_AUTH_TOKEN is unset. ' +
+        'On macOS this typically means `hostname` returned a non-RFC1123 value. ' +
+        'Set machine_id in config.toml ([machine_id] section) or provide EDGE_AUTH_TOKEN ' +
+        'explicitly via the environment to override.');
+}

package/dist/crypto/aes-gcm.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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.
+ */
+/** On-disk encrypted-blob format version (first byte of every dump file). */
+export declare const KEY_VERSION = 1;
+/** AES-256-GCM nonce length (bytes). */
+export declare const NONCE_LEN = 12;
+/** AES-256-GCM authentication tag length (bytes, appended to ciphertext). */
+export declare const GCM_TAG_LEN = 16;
+/** Minimum blob size: version(1) + nonce(12) + tag(16). */
+export declare const MIN_BLOB_LEN: number;
+/**
+ * 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 declare function encrypt(key: Uint8Array, plaintext: string): Buffer;
+/** Result of {@link decrypt}: plaintext + whether the previous key was used. */
+export interface DecryptResult {
+    readonly plaintext: string;
+    /** `true` if the blob was decrypted with `previousKey` (pending rotation). */
+    readonly usedPrevious: boolean;
+}
+/**
+ * Decrypt a DiskDumper-format blob. Tries `currentKey` first, then
+ * `previousKey` (rotation window). Throws on malformed data or auth failure.
+ */
+export declare function decrypt(data: Buffer, currentKey: Uint8Array, previousKey?: Uint8Array): DecryptResult;