credential-daemon.ts

#!/usr/bin/env node
// node-only entry point — credential daemon (Unix socket, net, os, fs)
/**
 * credential-daemon.ts - Secure Private Key Server
 *
 * DEXBot credential daemon for multi-bot private key management.
 * Enables bot processes to request pre-decrypted keys via Unix socket.
 * Keeps the derived vault secret in RAM so key updates remain visible while the daemon runs.
 *
 * ===============================================================================
 * DAEMON OPERATION
 * ===============================================================================
 *
 * STARTUP:
 * 1. Prompts for master password ONCE at startup
 * 2. Authenticates with profiles/keys.json
 * 3. Re-wraps the decrypted account cache with a random session secret
 * 4. Keeps the derived vault secret and session cache in RAM during operation
 * 5. Listens on Unix socket for credential requests
 * 6. Services private key requests from bot processes
 *
 * COMMUNICATION:
 * - Socket: profiles/run/dexbot-cred-daemon.sock (or $DEXBOT_CRED_RUNTIME_DIR, or $XDG_RUNTIME_DIR/dexbot2/)
 * - Ready file: profiles/run/dexbot-cred-daemon.ready (or $DEXBOT_CRED_RUNTIME_DIR, or $XDG_RUNTIME_DIR/dexbot2/)
 * - Startup timeout: 60 seconds (DAEMON_STARTUP_TIMEOUT_MS)
 * - Linux only (Unix socket)
 *
 * REQUEST FORMAT:
 *   {"type": "ping", "accountName": "account-name"}
 *   {"type": "probe-account", "accountName": "account-name"}
 *   {"type": "broadcast-operation", "sessionId": "...", "accountName": "account-name", "operation": {...}}
 *   {"type": "execute-operations", "sessionId": "...", "accountName": "account-name", "operations": [...]}
 *
 * RESPONSE FORMAT:
 *   Success:  {"success": true, ...}
 *   Failure:  {"success": false, "error": "Error message"}
 *
 * ===============================================================================
 * SECURITY BENEFITS
 * ===============================================================================
 *
 * - Master password prompt only once (at daemon startup)
 * - Individual bot processes have no access to the derived vault secret
 * - No persisted raw password in environment variables or config files
 * - Private keys never written to disk unencrypted
 * - Centralized key management
 * - Unix socket provides process-level isolation
 *
 * ===============================================================================
 * USAGE
 * ===============================================================================
 *
 * Direct:
 *   tsx credential-daemon.ts
 *
 * Via PM2 (recommended):
 *   npm run unlock
 *   or: node unlock
 *
 * Bot processes then access keys automatically via socket connection.
 *
 * ===============================================================================
 */

const { setUmask } = require('./modules/config');
setUmask(0o077);

const net = require('net');
const fs = require('fs');
const { path } = require('./modules/path_api');
const os = require('os');
const { randomBytes } = require('./modules/crypto/sync');
const chainKeys = require('./modules/chain_keys');
const { TIMING, NODE_MANAGEMENT, DAEMON_ERRORS, DAEMON_CODES } = require('./modules/constants');
const { readGeneralSettings } = require('./modules/general_settings');
const { orderNodesForSettings } = require('./modules/node_health_cache');
const credentialPolicy = require('./modules/credential_policy');
const { getStorage } = require('./modules/storage');
const storage = getStorage();
let _nativeChainClient: any = null;
let _nativeNodeList: any[] = [];

const native = require('./modules/bitshares-native');
_nativeChainClient = native.createChainClient({ rpcTimeoutMs: TIMING.CONNECTION_TIMEOUT_MS, connectTimeoutMs: TIMING.CONNECTION_TIMEOUT_MS });

// Register asset-ref resolver so the credential policy can resolve symbol
// names (e.g. "BTS" -> "1.3.0") using the native chain client instead of
// the legacy global BitShares object (which is not initialised in daemon
// context).
const assetResolver = async (assetRef: string): Promise<string | null> => {
    try {
        if (_nativeChainClient.getStatus() !== 'connected') {
            _nativeChainClient.setNodes(_nativeNodeList.length > 0 ? _nativeNodeList : NODE_MANAGEMENT.DEFAULT_NODES);
            await _nativeChainClient.connect();
        }
        const result = await _nativeChainClient.db.lookup_asset_symbols([assetRef]);
        const asset = Array.isArray(result) ? result[0] : null;
        return asset?.id ? String(asset.id) : null;
    } catch (_: any) {
        return null;
    }
};
credentialPolicy.setExternalAssetResolver(assetResolver);

_nativeNodeList = [];
const {
    assertPrivatePathSecurity,
    ensureCredentialRuntimeDirSync,
    getCredentialReadyFilePath,
    getCredentialRuntimeDir,
    getCredentialSocketPath,
} = require('./modules/credential_runtime');
const {
    buildSessionAccountCache,
    loadDaemonPrivateKey,
} = require('./modules/credential_session_cache');
const { fetchBootstrapPassword } = require('./modules/launcher/credential_bootstrap');
const { normalizeBootstrapCredential } = require('./modules/launcher/credential_secret');
const Logger = require('./modules/logger');
const { ensureDir, safeUnlink } = require('./modules/utils/fs_utils');
const { Config } = require('./modules/config');
const daemonLogger = new Logger('credential-daemon');

// Resolve project root — handles running from dist/ (compiled) vs source
const { PATHS } = require('./modules/paths');
const PROJECT_ROOT = PATHS.PROJECT_ROOT;

// Unix sockets are required; only Unix-like systems are supported

const RUNTIME_DIR = getCredentialRuntimeDir({ root: PATHS.PROJECT_ROOT });
const SOCKET_PATH = getCredentialSocketPath({ root: PATHS.PROJECT_ROOT, runtimeDir: RUNTIME_DIR });
const READY_FILE = getCredentialReadyFilePath({ root: PATHS.PROJECT_ROOT, runtimeDir: RUNTIME_DIR });

let vaultSecret: any = null;
let sessionSecret: any = null;
let sessionAccountKeys: Map<any, any> = new Map();
let server: any = null;
let daemonShuttingDown = false;

// Policy layer and session management
let policyConfig: any = null;
let activeSessions: Map<string, { accountName: string; createdAt: number }> = new Map();
let auditLogPath: any = null;
let auditLogQueue: Promise<void> = Promise.resolve();
// Policy-file watcher (cleared on shutdown so we don't leak the inotify FD
// or fire a debounced reload after secrets have been zeroed).
let policyWatcher: import('fs').FSWatcher | null = null;
let policyWatchDebounce: ReturnType<typeof setTimeout> | null = null;

function debugLog(message: string, err: any = null) {
    const suffix = err && err.message ? `: ${err.message}` : '';
    daemonLogger.error(`[credential-daemon][debug] ${message}${suffix}`);
}

function formatFatalReason(reason: any) {
    if (!reason) return 'unknown';
    if (reason instanceof Error) return reason.stack || reason.message;
    if (typeof reason === 'object') {
        try {
            return JSON.stringify(reason);
        } catch (_) {
            return String(reason);
        }
    }
    return String(reason);
}

function registerProcessDiagnostics() {
    process.on('uncaughtException', (err: any) => {
        daemonLogger.error(`[credential-daemon] Uncaught exception: ${formatFatalReason(err)}`);
        shutdown(1, 'uncaughtException');
    });

    process.on('unhandledRejection', (reason: any) => {
        daemonLogger.error(`[credential-daemon] Unhandled rejection: ${formatFatalReason(reason)}`);
        shutdown(1, 'unhandledRejection');
    });

    process.on('exit', (code: any) => {
        daemonLogger.log?.(`[credential-daemon] Process exiting with code ${code}`);
    });
}

/**
 * Policy and session management helpers
 */

function generateSessionId() {
    return randomBytes(16).toString('hex');
}

function purgeExpiredSessions() {
    const ttl = (policyConfig && policyConfig.sessionTtlMs) || 86400000;
    const now = Date.now();
    for (const [id, session] of activeSessions) {
        if (now - session.createdAt > ttl) {
            activeSessions.delete(id);
        }
    }
}

function checkSessionValid(accountName: any, sessionId: any) {
    purgeExpiredSessions();
    if (!sessionId) {
        return false;
    }
    const session = activeSessions.get(sessionId);
    return session && session.accountName === accountName;
}

function queueAuditLogWork(work: any) {
    auditLogQueue = auditLogQueue
        .then(() => Promise.resolve().then(work))
        .catch((err) => {
            debugLog('Audit log operation failed', err);
        });
    return auditLogQueue;
}

function performAuditLogPrune() {
    return new Promise<void>((resolve) => {
        if (!auditLogPath) {
            resolve();
            return;
        }

        try {
            const stat = storage.stat(auditLogPath);
            const perFileLimit = Math.floor(TIMING.AUDIT_LOG_MAX_SIZE / (TIMING.AUDIT_LOG_MAX_FILES + 1));
            if (stat.size >= perFileLimit) {
                for (let i = TIMING.AUDIT_LOG_MAX_FILES - 1; i >= 1; i--) {
                    const oldPath = auditLogPath + '.' + i;
                    const newPath = auditLogPath + '.' + (i + 1);
                    try { if (storage.exists(oldPath)) storage.rename(oldPath, newPath); } catch (err: any) { debugLog('Audit log rotation rename failed', err); }
                }
                try { if (storage.exists(auditLogPath)) storage.rename(auditLogPath, auditLogPath + '.1'); } catch (err: any) { debugLog('Audit log rotation rename failed', err); }
                resolve();
                return;
            }
        } catch (err: any) {
            debugLog('Audit log size check failed', err);
        }
        resolve();
    });
}

function pruneAuditLog() {
    return queueAuditLogWork(() => performAuditLogPrune());
}

function appendAuditLog(entry: any) {
    if (!auditLogPath) return;
    const line = JSON.stringify(entry) + '\n';
    return queueAuditLogWork(() => new Promise<void>((resolve) => {
        fs.appendFile(auditLogPath, line, (err: any) => {
            if (err) {
                debugLog('Audit log write failed', err);
            }
            resolve();
        });
    }));
}

async function resolveVaultSecret() {
    // NOTE: The DAEMON_PASSWORD env-var path was removed.  No launcher in this
    // codebase ever sets it, and /proc/<pid>/environ retains deleted env values
    // in cleartext for the lifetime of the process — making it a high-value
    // extraction target for any local same-uid process.  All callers should use
    // the one-shot bootstrap socket (DEXBOT_CRED_BOOTSTRAP_PATH_FILE) instead.

    // Try the bootstrap path file first (stable path, no PM2 env leak).
    // The launcher writes the one-shot bootstrap socket path to this file
    // before starting the daemon.  We read it, connect, get the secret,
    // and delete the file.  Future restarts will not find the file and
    // will fall through to interactive auth.
    const bootstrapPathFile = Config.DEXBOT_CRED_BOOTSTRAP_PATH_FILE;
    if (bootstrapPathFile) {
        try {
            const bootstrapSocket = storage.readFile(bootstrapPathFile, 'utf-8').trim();
            if (bootstrapSocket) {
                // Uses delete on process.env directly (not Config) intentionally:
                // security cleanup — scrubs the one-shot path from the env block
                // so /proc/self/environ doesn't leak it to child processes.
                delete process.env.DEXBOT_CRED_BOOTSTRAP_PATH_FILE;
                safeUnlink(bootstrapPathFile)
                daemonLogger.log?.(`[credential-daemon] Resolving vault secret from bootstrap path file: ${bootstrapSocket}`);
                const secret = await fetchBootstrapPassword({ socketPath: bootstrapSocket, retries: 2 });
                daemonLogger.log?.('[credential-daemon] Bootstrap secret transfer completed');
                return normalizeBootstrapCredential(secret);
            }
        } catch (err: any) {
            // Bootstrap path file was consumed on a previous run (or never
            // written).  This is normal for a PM2 restart/resurrect — the
            // daemon is locked and needs re-authentication.
            safeUnlink(bootstrapPathFile)
            if (!process.stdin || !process.stdin.isTTY) {
                daemonLogger.log?.(
                    '[credential-daemon] Credential daemon is locked — no bootstrap path file and no TTY. ' +
                    'Run \'node pm2\' to unlock.'
                );
                // delete on process.env directly (not Config) — see note above
                delete process.env.DEXBOT_CRED_BOOTSTRAP_PATH_FILE;
                process.exit(0);
            }
            daemonLogger.log?.(
                `[credential-daemon] Bootstrap path file not available (${err.message}), falling back to interactive auth.`
            );
        }
        // delete on process.env directly (not Config) — see note above
        delete process.env.DEXBOT_CRED_BOOTSTRAP_PATH_FILE;
    }

    daemonLogger.log?.('[credential-daemon] Resolving vault secret from interactive authentication');
    return chainKeys.authenticate();
}

function removeSecureStaleFile(filePath: string, expectedType: any) {
    if (!storage.exists(filePath)) {
        return;
    }

    // Intentionally throws rather than silently cleaning up: if the path fails
    // the security check (wrong owner, wrong permissions, or a symlink) we must
    // not remove it — doing so could mask an attack. The caller is expected to
    // surface the error and abort daemon startup.
    assertPrivatePathSecurity(filePath, {
        expectedType,
        requiredMode: 0o600,
    });

    storage.unlink(filePath);
}

async function loadCurrentPrivateKey(accountName: any) {
    return loadDaemonPrivateKey(accountName, {
        vaultSecret,
        sessionAccountKeys,
        sessionSecret,
        chainClient: _nativeChainClient,
    });
}

async function executeOperationsWithClient(client: any, operations: any) {
    const ops = Array.isArray(operations) ? operations.filter(Boolean) : [];
    if (ops.length === 0) {
        return { success: true, operation_results: [], raw: null };
    }

    if (client.initPromise) {
        await client.initPromise;
    }

    if (typeof client.newTx !== 'function') {
        throw new Error('Signing client does not support newTx()');
    }

    const tx = client.newTx();
    for (const op of ops) {
        if (!op || !op.op_name || !op.op_data) {
            throw new Error('Each operation requires op_name and op_data');
        }
        if (typeof tx[op.op_name] !== 'function') {
            throw new Error(`Transaction builder does not support ${op.op_name}`);
        }
        tx[op.op_name](op.op_data);
    }

    const result = await tx.broadcast();
    const operationResults =
        (result && Array.isArray(result.operation_results) && result.operation_results.length > 0 && result.operation_results) ||
        (result && result.trx && Array.isArray(result.trx.operation_results) && result.trx.operation_results.length > 0 && result.trx.operation_results) ||
        (Array.isArray(result) && result[0] && result[0].trx && Array.isArray(result[0].trx.operation_results) && result[0].trx.operation_results.length > 0 && result[0].trx.operation_results) ||
        [];

    return {
        success: true,
        raw: result,
        operation_results: operationResults,
    };
}

async function broadcastWithRetry(accountName: any, privateKey: any, broadcastFn: any) {
    // The inner deadline caps the TOTAL time spent across BOTH retry attempts
    // so we always reply to the bot well before its outer socket timer
    // (CREDENTIAL_BROADCAST_TIMEOUT_MS) fires. If we don't reply in time, the
    // bot raises BroadcastUncertainError and enters the recovery path.
    // See: modules/dexbot_credential_client.ts BroadcastUncertainError.
    const innerDeadlineMs = Number.isFinite(Number(TIMING?.CREDENTIAL_DAEMON_INNER_DEADLINE_MS))
        ? Number(TIMING.CREDENTIAL_DAEMON_INNER_DEADLINE_MS)
        : 20000;
    const startedAt = Date.now();
    let deadlineTimer: any = null;
    const deadlinePromise = new Promise((_, reject) => {
        deadlineTimer = setTimeout(() => {
            const err: any = new Error(
                `${DAEMON_CODES.BROADCAST_DEADLINE}:inner broadcast deadline ${innerDeadlineMs}ms exceeded`
            );
            err.code = DAEMON_CODES.BROADCAST_DEADLINE;
            err.uncertain = true;
            err.accountName = accountName;
            err.startedAt = startedAt;
            err.ageMs = Date.now() - startedAt;
            reject(err);
        }, innerDeadlineMs);
    });

    const work = (async () => {
        for (let attempt = 1; attempt <= 2; attempt++) {
            try {
                if (_nativeChainClient.getStatus() !== 'connected') {
                    _nativeChainClient.setNodes(_nativeNodeList.length > 0 ? _nativeNodeList : NODE_MANAGEMENT.DEFAULT_NODES);
                    await _nativeChainClient.connect();
                }
                const { createSigningClient } = require('./modules/bitshares-native');
                const signingClient = createSigningClient(_nativeChainClient, accountName, privateKey);
                const client = signingClient.client;
                await client.initPromise;
                return await broadcastFn(client);
            } catch (err: any) {
                if (attempt === 2) throw err;
                debugLog(`Broadcast failed (attempt ${attempt}), reconnecting: ${err.message}`);
                try { _nativeChainClient.disconnect(); } catch (_) {}
            }
        }
    })();

    try {
        return await Promise.race([work, deadlinePromise]);
    } finally {
        if (deadlineTimer) clearTimeout(deadlineTimer);
    }
}

/**
 * Refresh the BitShares node list from the health cache.
 * Ensures the daemon isn't stuck on stale nodes if they fail during long uptime.
 */
function refreshNodeList() {
    const settings = readGeneralSettings({ fallback: null });
    const nodeSettings = settings?.NODES;
    const nodeManagerEnabled = nodeSettings?.enabled ?? NODE_MANAGEMENT.DEFAULT_ENABLED;

    if (nodeManagerEnabled) {
        try {
            const bestNodes = orderNodesForSettings(settings);
            if (bestNodes && bestNodes.length > 0) {
                _nativeNodeList = bestNodes;
                _nativeChainClient.setNodes(bestNodes);
                daemonLogger.log?.(`[credential-daemon] Node list refreshed: using best ${bestNodes.length} nodes from cache.`);
            }
        } catch (err: any) {
            daemonLogger.warn?.(`[credential-daemon] Failed to refresh node list: ${err.message}`);
        }
    }
}

function getCredentialDaemonNodeRefreshIntervalMs(settings: any) {
    const configured = settings?.NODES?.credentialDaemonRefreshIntervalMs
        ?? settings?.NODES?.CREDENTIAL_DAEMON_NODE_REFRESH_INTERVAL_MS
        ?? NODE_MANAGEMENT.CREDENTIAL_DAEMON_NODE_REFRESH_INTERVAL_MS;
    return Number.isFinite(configured) && configured > 0
        ? configured
        : NODE_MANAGEMENT.CREDENTIAL_DAEMON_NODE_REFRESH_INTERVAL_MS;
}

/**
 * Initialize daemon: authenticate and start listening
 */
async function initialize() {
    try {
        // Check if profiles/keys.json exists
        const keysPath = path.join(PATHS.PROJECT_ROOT, 'profiles', 'keys.json');
        if (!storage.exists(keysPath)) {
            throw new Error('profiles/keys.json not found. Please run: tsx dexbot.ts keys');
        }

        // Accept a one-shot bootstrap secret when launched by a wrapper,
        // otherwise prompt once interactively.
        vaultSecret = await resolveVaultSecret();
        const accountsData = chainKeys.loadAccounts();
        const sessionState = buildSessionAccountCache(accountsData, vaultSecret, {
            onDecryptError: (accountName: any, err: any) => {
                debugLog(`Skipping account '${accountName}' — decryption failed: ${err.message}`);
            },
        });
        sessionAccountKeys = sessionState.cache;
        sessionSecret = sessionState.sessionSecret;
        if (accountsData && typeof accountsData === 'object') {
            accountsData.accounts = null;
        }

        // Load policy config — auto-remediate legacy 0o644 permissions first
        const policyConfigPath = PATHS.PROFILES.DAEMON_POLICIES_JSON;
        credentialPolicy.checkPolicyFileSecurity(policyConfigPath);
        policyConfig = credentialPolicy.loadRequiredPolicyConfig(policyConfigPath);

        // Set audit log path
        const auditLogDir = PATHS.LOGS_DIR;
        if (!storage.exists(auditLogDir)) {
            try {
                ensureDir(auditLogDir, { mode: 0o700 });
            } catch (err: any) {
                debugLog(`Failed to create audit log directory ${auditLogDir}: ${err.message}`);
            }
        }
        auditLogPath = path.join(auditLogDir, 'daemon-audit.jsonl');

        // Apply configured node list so the daemon uses the same
        // nodes as bot processes (when node management is enabled),
        // without instantiating NodeManager (which was crashing the
        // daemon ~80s after startup).  Mirror the enabled check from
        // bitshares_client.ts so both stay aligned.
        const settings = readGeneralSettings({ fallback: null });
        refreshNodeList();

        // Fire-and-forget connect so the asset resolver works on first request
        _nativeChainClient.setNodes(_nativeNodeList.length > 0 ? _nativeNodeList : NODE_MANAGEMENT.DEFAULT_NODES);
        _nativeChainClient.connect().catch(() => {});

        // Lightweight node list refresh from the health cache. This is separate
        // from updater schedules and does not run active node probes.
        const nodeRefreshInterval = setInterval(refreshNodeList, getCredentialDaemonNodeRefreshIntervalMs(settings));
        if (typeof nodeRefreshInterval.unref === 'function') {
            nodeRefreshInterval.unref();
        }

        // Audit log prune on a timer (M5): replaces inline pruning on every
        // append, which caused read+rewrite of the entire file on each signed
        // operation.  Hourly prune is sufficient for the 7-day retention window.
        const AUDIT_LOG_PRUNE_INTERVAL_MS = 60 * 60 * 1000;
        const auditPruneInterval = setInterval(() => { pruneAuditLog(); }, AUDIT_LOG_PRUNE_INTERVAL_MS);
        if (typeof auditPruneInterval.unref === 'function') {
            auditPruneInterval.unref();
        }

        // Register SIGHUP handler for policy and node list reload.
        // PM2 may forward SIGHUP on terminal disconnect, but we treat it
        // as a trigger to refresh configuration.
        process.on('SIGHUP', () => {
            daemonLogger.log?.('[credential-daemon] SIGHUP received: refreshing configuration and node list...');

            // Strict reload: fail closed if the operator just wrote an
            // invalid policy.  The try/catch wraps shutdown() so a
            // successful reload falls through to refreshNodeList().
            try {
                policyConfig = credentialPolicy.reloadPolicyFromDisk(policyConfigPath, { strict: true });
                debugLog('Policy config reloaded');
            } catch (err: any) {
                daemonLogger.error?.(`[credential-daemon] SIGHUP policy reload failed: ${err.message}`);
                shutdown(1, 'invalid policy reload');
                return;
            }

            // Reload node list
            refreshNodeList();
        });

        // Watch policy config file for external changes (e.g. auto-provision
        // of botHmacSecret by a bot process).  fs.watch fires multiple events
        // per atomic rename, so debounce with a 500ms settle window.
        // This is the safety net that makes C2 fixes work end-to-end: the bot
        // writes a new secret, sends SIGHUP, and even if SIGHUP is lost or
        // delayed, the daemon picks up the change within 500ms.
        try {
            policyWatcher = fs.watch(policyConfigPath, { persistent: false }, (eventType: string) => {
                if (policyWatchDebounce) clearTimeout(policyWatchDebounce);
                policyWatchDebounce = setTimeout(() => {
                    policyWatchDebounce = null;
                    const newConfig = credentialPolicy.reloadPolicyFromDisk(policyConfigPath);
                    if (newConfig) {
                        policyConfig = newConfig;
                        debugLog(`Policy config reloaded via fs.watch (${eventType})`);
                    }
                    // On non-strict failure, reloadPolicyFromDisk already logs
                    // a warn; the existing in-memory config is kept.  This is
                    // intentionally distinct from SIGHUP's fail-closed policy.
                }, 500);
            });
        } catch (watchErr: any) {
            // fs.watch can fail on exotic filesystems (network FS, FUSE).
            // Log at WARN (not debug): without the watch AND without a
            // successful SIGHUP from the bot, the daemon keeps the stale
            // botHmacSecret until restart.  Operators need to see this.
            daemonLogger.warn?.(`[credential-daemon] Could not watch policy config file ${policyConfigPath}: ${watchErr.message}. SIGHUP from bot process is now the only reload path.`);
        }

        ensureCredentialRuntimeDirSync({ root: PATHS.PROJECT_ROOT, runtimeDir: RUNTIME_DIR, socketPath: SOCKET_PATH, readyFilePath: READY_FILE });
        daemonLogger.log?.(`[credential-daemon] Runtime socket path: ${SOCKET_PATH}`);
        daemonLogger.log?.(`[credential-daemon] Ready file path: ${READY_FILE}`);

        // Clean up old socket if it exists
        try {
            removeSecureStaleFile(SOCKET_PATH, 'socket');
            removeSecureStaleFile(READY_FILE, 'file');
        } catch (err: any) {
            throw new Error(`Insecure credential runtime path detected: ${err.message}`);
        }

        // Create server
        server = net.createServer(handleConnection);
        server.listen(SOCKET_PATH, () => {
            try {
                storage.chmod(SOCKET_PATH, 0o600);
                assertPrivatePathSecurity(SOCKET_PATH, { expectedType: 'socket', requiredMode: 0o600 });
            } catch (err: any) {
                daemonLogger.error?.(`[credential-daemon] FATAL: Insecure socket permissions on ${SOCKET_PATH}: ${err.message}`);
                shutdown(1, 'insecure socket permissions');
                return;
            }
            // Create ready file to signal startup completion.
            // Open with explicit 0o600 mode to avoid the TOCTOU window between
            // writeFileSync and chmodSync (the file is never world-readable).
            // Write JSON with pid so callers can send SIGHUP to trigger policy reload.
            try {
                const readyPayload = JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() });
                storage.writeFile(READY_FILE, readyPayload, { mode: 0o600 });
                assertPrivatePathSecurity(READY_FILE, { expectedType: 'file', requiredMode: 0o600 });
                daemonLogger.log?.(`[credential-daemon] Ready: listening on ${SOCKET_PATH}`);
            } catch (err: any) {
                daemonLogger.error?.(`[credential-daemon] FATAL: Insecure ready-file permissions on ${READY_FILE}: ${err.message}`);
                shutdown(1, 'insecure ready-file permissions');
                return;
            }
        });

        server.on('error', (error: any) => {
            daemonLogger.error(`Server error: ${error.message}`);
            process.exit(1);
        });

        // Handle graceful shutdown.
        // SIGTERM is sent by PM2 when stopping the daemon — honour it.
        // SIGINT is from stray Ctrl-C in the parent terminal; under PM2
        // management we ignore it so the daemon stays alive.  When running
        // interactively (not via PM2), SIGINT still works because the
        // process group leader is the shell.
        process.on('SIGTERM', () => shutdown(0, 'SIGTERM'));
        process.on('SIGINT', () => {
            daemonLogger.log?.(
                '[credential-daemon] SIGINT ignored (daemon is managed by PM2; use `pm2 stop dexbot-cred` to shut down).'
            );
        });

    } catch (error: any) {
        daemonLogger.error(`[credential-daemon] Startup failed: ${error.stack || error.message}`);
        shutdown(1, 'startup failure');
    }
}

/**
 * Handle incoming client connection to daemon.
 * Reads newline-delimited JSON requests and processes credential requests.
 * 
 * @param {net.Socket} socket - Connected client socket
 */
function handleConnection(socket: any) {
    let buffer = '';

    socket.on('data', (data: any) => {
        try {
            buffer += data.toString();

            // Look for newline-delimited JSON
            const lines = buffer.split('\n');
            buffer = lines.pop() || ''; // Keep incomplete line in buffer

            for (const line of lines) {
                if (line.trim()) {
                    processRequest(line.trim(), socket);
                }
            }
        } catch (error) {
            sendError(socket, 'Invalid request');
        }
    });

    socket.on('end', () => {
        // Connection closed
    });

    socket.on('error', (_error: any) => {
        // Client disconnected or error
    });
}

/**
 * Process incoming credential request from client.
 * Validates request format and retrieves private key if valid.
 * Sends success or error response back to client.
 * 
 * @param {string} requestStr - JSON string with {type, accountName}
 * @param {net.Socket} socket - Client socket to send response
 */
function processRequest(requestStr: string, socket: any) {
    // The outer try/catch handles JSON parse errors and any synchronous throws.
    // Each async branch manages its own errors via .catch() → sendError(), so
    // the outer catch is not expected to fire for async operation failures.
    try {
        const request = JSON.parse(requestStr);
        const { type, accountName } = request;

        if (!type) {
            return sendError(socket, 'Missing "type" field');
        }

        if (!accountName) {
            return sendError(socket, 'Missing "accountName" field');
        }

        if (type === 'ping') {
            // Lightweight health check — no session created, no audit log entry.
            // Used by the credential daemon watchdog and pre-write probes where
            // we only need to verify the daemon is alive, not establish a session.
            sendSuccess(socket, { pong: true });
            return;
        }

        if (type === 'probe-account') {
            loadCurrentPrivateKey(accountName)
                .then(() => {
                    // Session registration
                    const sessionId = generateSessionId();
                    activeSessions.set(sessionId, {
                        accountName,
                        createdAt: Date.now(),
                    });
                    appendAuditLog({
                        event: 'session_created',
                        accountName,
                        sessionId,
                        timestamp: new Date().toISOString(),
                    });
                    sendSuccess(socket, { sessionId });
                })
                .catch((error: any) => sendError(socket, error.message));
            return;
        }

        if (type === 'broadcast-operation') {
            const operation = request.operation;
            if (!operation || typeof operation !== 'object') {
                return sendError(socket, 'Missing "operation" field');
            }

            const sessionId = request.sessionId || null;

            // Session validation
            if (!checkSessionValid(accountName, sessionId)) {
                const reason = DAEMON_ERRORS.SESSION_EXPIRED;
                appendAuditLog({
                    event: 'sign_denied',
                    accountName,
                    sessionId,
                    reason: 'session: ' + reason,
                    timestamp: new Date().toISOString(),
                });
                return sendError(socket, credentialPolicy.POLICY_DENIED_PREFIX + reason);
            }

            // Source authentication (HMAC verification)
            // For broadcast-operation, we verify HMAC over [operation] (single-element array)
            const hmacResult = credentialPolicy.verifySourceHmac(
                { ...request, operations: [operation] },
                policyConfig
            );
            if (!hmacResult.valid) {
                appendAuditLog({
                    event: 'sign_denied',
                    accountName,
                    sessionId,
                    reason: 'source: ' + hmacResult.reason,
                    timestamp: new Date().toISOString(),
                });
                return sendError(socket, credentialPolicy.POLICY_DENIED_PREFIX + DAEMON_ERRORS.SOURCE_AUTH_DENIED);
            }
            if (hmacResult.skipped) {
                debugLog(`[warn] no botHmacSecret configured for ${accountName} — source authentication skipped`);
            }

            // Policy evaluation — treat as single-operation batch
            const policy = credentialPolicy.resolveAccountPolicy(policyConfig, accountName);
            const context = credentialPolicy.buildPolicyContext({
                ...request,
                operations: [operation],
            });

            credentialPolicy.evaluatePolicy(policy, context)
                .then(async (result: any) => {
                    if (!result.allow) {
                        appendAuditLog({
                            event: 'sign_denied',
                            accountName,
                            sessionId,
                            policyId: result.policyId,
                            reason: result.reason,
                            opCount: 1,
                            opTypes: [operation && operation.op_name].filter(Boolean),
                            timestamp: new Date().toISOString(),
                        });
                        sendError(socket, credentialPolicy.POLICY_DENIED_PREFIX + result.reason);
                        return;
                    }

                    const privateKey = await loadCurrentPrivateKey(accountName);
                    let signResult: any;
                    try {
                        signResult = await broadcastWithRetry(
                            accountName, privateKey,
                            (client: any) => client.broadcast(operation)
                        );
                    } catch (broadcastErr: any) {
                        if (broadcastErr && broadcastErr.code === DAEMON_CODES.BROADCAST_DEADLINE) {
                            appendAuditLog({
                                event: 'sign_timeout',
                                accountName,
                                sessionId,
                                opCount: 1,
                                opTypes: [operation && operation.op_name].filter(Boolean),
                                ageMs: broadcastErr.ageMs,
                                startedAt: broadcastErr.startedAt
                                    ? new Date(broadcastErr.startedAt).toISOString()
                                    : null,
                                timestamp: new Date().toISOString(),
                            });
                            // Tell the bot the chain state is uncertain so it
                            // can run the recovery path (read chain, match by
                            // fingerprint, adopt or discard).
                            return sendError(
                                socket,
                                'chain status uncertain after inner deadline',
                                DAEMON_CODES.BROADCAST_DEADLINE
                            );
                        }
                        throw broadcastErr;
                    }

                    appendAuditLog({
                        event: 'sign_allowed',
                        accountName,
                        sessionId,
                        opCount: 1,
                        opTypes: [operation && operation.op_name].filter(Boolean),
                        timestamp: new Date().toISOString(),
                    });
                    sendSuccess(socket, signResult);
                })
                .catch((error: any) => sendError(socket, error.message));
            return;
        }

        if (type === 'execute-operations') {
            const operations = request.operations;
            if (!Array.isArray(operations)) {
                return sendError(socket, 'Missing "operations" field');
            }

            const sessionId = request.sessionId || null;

            // Session validation
            if (!checkSessionValid(accountName, sessionId)) {
                const reason = DAEMON_ERRORS.SESSION_EXPIRED;
                appendAuditLog({
                    event: 'sign_denied',
                    accountName,
                    sessionId,
                    reason: 'session: ' + reason,
                    timestamp: new Date().toISOString(),
                });
                return sendError(socket, credentialPolicy.POLICY_DENIED_PREFIX + reason);
            }

            // Source authentication (HMAC verification)
            const hmacResult = credentialPolicy.verifySourceHmac(request, policyConfig);
            if (!hmacResult.valid) {
                appendAuditLog({
                    event: 'sign_denied',
                    accountName,
                    sessionId,
                    reason: 'source: ' + hmacResult.reason,
                    timestamp: new Date().toISOString(),
                });
                return sendError(socket, credentialPolicy.POLICY_DENIED_PREFIX + DAEMON_ERRORS.SOURCE_AUTH_DENIED);
            }
            if (hmacResult.skipped) {
                debugLog(`[warn] no botHmacSecret configured for ${accountName} — source authentication skipped`);
            }

            // Policy evaluation — before any key material is touched
            const policy = credentialPolicy.resolveAccountPolicy(policyConfig, accountName);
            const context = credentialPolicy.buildPolicyContext(request);

            credentialPolicy.evaluatePolicy(policy, context)
                .then(async (result: any) => {
                    if (!result.allow) {
                        appendAuditLog({
                            event: 'sign_denied',
                            accountName,
                            sessionId,
                            policyId: result.policyId,
                            reason: result.reason,
                            opCount: operations.length,
                            opTypes: operations.map((o: any) => o && o.op_name).filter(Boolean),
                            timestamp: new Date().toISOString(),
                        });
                        sendError(socket, credentialPolicy.POLICY_DENIED_PREFIX + result.reason);
                        return;
                    }

                    const privateKey = await loadCurrentPrivateKey(accountName);
                    let signResult: any;
                    try {
                        signResult = await broadcastWithRetry(
                            accountName, privateKey,
                            (client: any) => executeOperationsWithClient(client, operations)
                        );
                    } catch (broadcastErr: any) {
                        if (broadcastErr && broadcastErr.code === DAEMON_CODES.BROADCAST_DEADLINE) {
                            appendAuditLog({
                                event: 'sign_timeout',
                                accountName,
                                sessionId,
                                opCount: operations.length,
                                opTypes: operations.map((o: any) => o && o.op_name).filter(Boolean),
                                ageMs: broadcastErr.ageMs,
                                startedAt: broadcastErr.startedAt
                                    ? new Date(broadcastErr.startedAt).toISOString()
                                    : null,
                                timestamp: new Date().toISOString(),
                            });
                            return sendError(
                                socket,
                                'chain status uncertain after inner deadline',
                                DAEMON_CODES.BROADCAST_DEADLINE
                            );
                        }
                        throw broadcastErr;
                    }

                    appendAuditLog({
                        event: 'sign_allowed',
                        accountName,
                        sessionId,
                        opCount: operations.length,
                        opTypes: operations.map((o: any) => o && o.op_name).filter(Boolean),
                        timestamp: new Date().toISOString(),
                    });
                    sendSuccess(socket, signResult);
                })
                .catch((error: any) => sendError(socket, error.message));
            return;
        }

        return sendError(socket, `Unknown credential type: ${type}`);
    } catch (error: any) {
        sendError(socket, error.message);
    }
}

/**
 * Send successful credential response to client.
 * 
 * @param {net.Socket} socket - Client socket
 * @param {Object} data - Response data
 */
function sendSuccess(socket: any, data: any) {
    const response = JSON.stringify({
        success: true,
        ...data
    });
    socket.write(response + '\n');
}

/**
 * Send error response to client.
 * 
 * @param {net.Socket} socket - Client socket
 * @param {string} message - Error message
 * @param {number} code - Error code
 */
function sendError(socket: any, message: string, code: string | null = null) {
    const response = JSON.stringify({
        success: false,
        error: message,
        ...(code ? { code } : {})
    });
    socket.write(response + '\n');
}

/**
 * Gracefully shutdown daemon.
 * Clears the derived vault secret from memory and closes server.
 * @param {number} [exitCode=0] - Process exit code
 * @param {string} [reason='shutdown'] - Reason for shutdown (for logging)
 */
function shutdown(exitCode = 0, reason = 'shutdown') {
    if (daemonShuttingDown) return;
    daemonShuttingDown = true;
    daemonLogger.log?.(`[credential-daemon] Shutdown requested (${reason}, exitCode=${exitCode})`);

    // Clear derived vault secret from memory.  Vault and session secrets are
    // plain objects ({ kind, version, vaultKeyHex }) — not Buffers — so we
    // iterate their properties, zero any Buffer values, and null everything.
    // Hex-string properties (vaultKeyHex, sessionSaltHex) are immutable in V8
    // and cannot be zeroed in place; they will be reclaimed by GC after the
    // object reference is dropped.
    if (vaultSecret) {
        if (Buffer.isBuffer(vaultSecret)) {
            vaultSecret.fill(0);
        } else if (typeof vaultSecret === 'object') {
            for (const key of Object.keys(vaultSecret)) {
                if (Buffer.isBuffer(vaultSecret[key])) vaultSecret[key].fill(0);
                vaultSecret[key] = null;
            }
        }
        vaultSecret = null;
    }
    if (sessionSecret) {
        if (Buffer.isBuffer(sessionSecret)) {
            sessionSecret.fill(0);
        } else if (typeof sessionSecret === 'object') {
            for (const key of Object.keys(sessionSecret)) {
                if (Buffer.isBuffer(sessionSecret[key])) sessionSecret[key].fill(0);
                sessionSecret[key] = null;
            }
        }
        sessionSecret = null;
    }
    if (sessionAccountKeys) {
        for (const [key, val] of sessionAccountKeys) {
            if (Buffer.isBuffer(val)) {
                val.fill(0);
            }
        }
        sessionAccountKeys.clear();
    }

    // Close server — don't wait for active connections, process.exit will
    // tear everything down.  A hanging server.close() would prevent PM2 from
    // stopping the daemon, causing a SIGKILL after 1.6s.
    if (server) {
        try { server.close(); } catch (_) {}
    }

    // Cancel any pending policy-watch debounce and close the inotify handle.
    // If we don't, a reload could fire AFTER secrets have been zeroed, or
    // the watcher could keep the event loop alive briefly during shutdown.
    if (policyWatchDebounce) {
        clearTimeout(policyWatchDebounce);
        policyWatchDebounce = null;
    }
    if (policyWatcher) {
        try { policyWatcher.close(); } catch (_) {}
        policyWatcher = null;
    }

    daemonLogger.log?.('[credential-daemon] Server closed');
    daemonLogger.flush().finally(() => process.exit(exitCode));
}

// Start daemon
registerProcessDiagnostics();
initialize().catch(error => {
    daemonLogger.error(`[credential-daemon] Startup failed: ${error.stack || error.message}`);
    shutdown(1, 'startup failure');
});
export {};