kova-node-cli 0.1.0

package/README.md

@@ -0,0 +1,138 @@
+# Kova Node
+
+Provider node software for the Kova decentralized compute network. Share your spare computing resources and earn rewards.
+
+## Overview
+
+Kova is a decentralized marketplace for compute resources. By running this node software, you contribute idle computing power to the network and receive compensation for workloads executed on your machine.
+
+The platform enables anyone to become a compute provider, creating a distributed alternative to traditional cloud infrastructure.
+
+## Requirements
+
+- Docker (latest stable version)
+- Linux or macOS
+- Stable internet connection
+- Ethereum wallet address
+
+## Installation
+
+Install the node software globally via npm:
+
+```bash
+npm install -g @kovanetwork/node-cli
+```
+
+Or using yarn:
+
+```bash
+yarn global add @kovanetwork/node-cli
+```
+
+## Getting Started
+
+### 1. Obtain API Key
+
+Visit https://app.kovanetwork.com and authenticate with your wallet. Navigate to the Provider section to retrieve your API key.
+
+### 2. Start Your Node
+
+Launch the node with your API key:
+
+```bash
+kova-node start --api-key sk_live_your_key_here
+```
+
+The node will register with the network and begin accepting workloads based on your available resources.
+
+## Configuration
+
+By default, the node allocates all available system resources. You can configure resource limits using command-line flags:
+
+```bash
+kova-node start --api-key sk_live_your_key_here \
+  --max-cpu 4 \
+  --max-memory 8 \
+  --max-disk 100
+```
+
+### Available Options
+
+- `--max-cpu` - Maximum CPU cores to allocate (default: all available)
+- `--max-memory` - Maximum memory in GB (default: 80% of system total)
+- `--max-disk` - Maximum disk space in GB (default: 100)
+- `--port` - P2P network port (default: 4001)
+
+## Commands
+
+Check node status:
+
+```bash
+kova-node status
+```
+
+View earnings:
+
+```bash
+kova-node earnings
+```
+
+Stop the node:
+
+```bash
+kova-node stop
+```
+
+## Earnings
+
+Providers are compensated based on actual resource consumption. Payment rates are determined by:
+
+- CPU and memory utilization
+- Job execution duration
+- Network demand and pricing
+
+Earnings are credited to your connected wallet address. View accumulated earnings through the dashboard at https://app.kovanetwork.com or via the CLI.
+
+## Security
+
+Workloads execute within isolated Docker containers, providing process and filesystem separation from the host system. However, providers should understand the following:
+
+- Containers provide isolation but are not a complete security boundary
+- Providers have visibility into container contents and execution
+- Only run nodes on dedicated hardware or machines you control
+- Review the security documentation before accepting production workloads
+
+## Troubleshooting
+
+### Docker Not Found
+
+Ensure Docker is installed and the daemon is running. Verify with:
+
+```bash
+docker ps
+```
+
+### Node Fails to Start
+
+Check if the default port (4001) is available. Specify an alternative if needed:
+
+```bash
+kova-node start --api-key sk_live_your_key_here --port 4002
+```
+
+### No Jobs Assigned
+
+Network discovery typically takes 10-15 minutes for new nodes. Ensure your node maintains consistent uptime and competitive resource pricing.
+
+### Invalid API Key
+
+If authentication fails, log in to the dashboard and regenerate your API key from the Provider section.
+
+## Support
+
+- Documentation: https://docs.kovanetwork.com
+- GitHub Issues: https://github.com/Kovanetwork/node_cli/issues
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/cli.js';

package/dist/__tests__/auto-bidder.test.js

@@ -0,0 +1,267 @@
+// tests for AutoBidder - order evaluation, bid pricing, deduplication
+jest.mock('../lib/logger.js', () => ({
+    logger: { info: jest.fn(), error: jest.fn(), warn: jest.fn(), debug: jest.fn() }
+}));
+import { AutoBidder } from '../services/auto-bidder';
+// mock fetch globally
+const mockFetch = jest.fn();
+global.fetch = mockFetch;
+// mock resource monitor
+const mockMonitor = {
+    getAvailableResources: jest.fn().mockResolvedValue({
+        cpu: { cores: 8, available: 6 },
+        memory: { total: 32, available: 24 },
+        disk: [{ path: '/', total: 500, available: 400 }],
+        network: { bandwidth: 100 },
+        gpu: []
+    }),
+    start: jest.fn(),
+    stop: jest.fn(),
+    getStats: jest.fn()
+};
+describe('AutoBidder', () => {
+    let bidder;
+    const config = {
+        nodeId: 'node-123',
+        providerId: 'provider-456',
+        orchestratorUrl: 'http://localhost:3000',
+        apiKey: 'sk_live_test123',
+        pricingStrategy: {
+            cpuPricePerCore: 0.01,
+            memoryPricePerGb: 0.005,
+            gpuPricePerUnit: 0.1,
+            margin: 1.2
+        }
+    };
+    // helper to make a fresh order id with recent timestamp
+    const makeOrderId = (suffix = '1') => {
+        return `user-abc-${Date.now()}-${suffix}`;
+    };
+    const makeOrder = (overrides = {}) => ({
+        id: makeOrderId(),
+        deploymentId: 'deploy-1',
+        resources: {
+            cpu: 2,
+            memory: '4Gi',
+            ...overrides.resources
+        },
+        placement: { pricing: {} },
+        maxPricePerBlock: 1.0,
+        ...overrides
+    });
+    // helper to wait for async operations to settle
+    const settle = (ms = 100) => new Promise(r => setTimeout(r, ms));
+    beforeEach(() => {
+        jest.clearAllMocks();
+        bidder = new AutoBidder(config, mockMonitor);
+    });
+    afterEach(() => {
+        bidder.stop();
+    });
+    // -- start/stop --
+    it('should start polling and run immediately', async () => {
+        mockFetch.mockResolvedValue({
+            ok: true,
+            json: async () => ({ orders: [] })
+        });
+        bidder.start(60000);
+        await settle();
+        expect(mockFetch).toHaveBeenCalledWith('http://localhost:3000/api/v1/provider/orders', expect.objectContaining({
+            headers: { 'Authorization': 'Bearer sk_live_test123' }
+        }));
+    });
+    it('should not start twice', async () => {
+        mockFetch.mockResolvedValue({ ok: true, json: async () => ({ orders: [] }) });
+        bidder.start(60000);
+        await settle();
+        const callCount = mockFetch.mock.calls.length;
+        bidder.start(60000);
+        await settle();
+        // shouldn't have made additional calls from second start
+        expect(mockFetch.mock.calls.length).toBe(callCount);
+    });
+    it('should stop cleanly', () => {
+        mockFetch.mockResolvedValue({ ok: true, json: async () => ({ orders: [] }) });
+        bidder.start(60000);
+        bidder.stop();
+        // no error thrown
+    });
+    // -- order evaluation --
+    it('should submit bid for affordable order with sufficient resources', async () => {
+        const order = makeOrder();
+        mockFetch
+            .mockResolvedValueOnce({ ok: true, json: async () => ({ orders: [order] }) })
+            .mockResolvedValueOnce({ ok: true, json: async () => ({ bid: { id: 'bid-1' } }) });
+        bidder.start(60000);
+        await settle(200);
+        const bidCall = mockFetch.mock.calls.find((c) => c[1]?.method === 'POST');
+        expect(bidCall).toBeDefined();
+        const body = JSON.parse(bidCall[1].body);
+        expect(body.orderId).toBe(order.id);
+        expect(body.nodeId).toBe('node-123');
+        expect(body.pricePerBlock).toBeGreaterThan(0);
+    });
+    it('should skip orders when resources are insufficient', async () => {
+        mockMonitor.getAvailableResources.mockResolvedValueOnce({
+            cpu: { cores: 8, available: 1 },
+            memory: { total: 32, available: 24 },
+            disk: [],
+            network: { bandwidth: 100 },
+            gpu: []
+        });
+        const order = makeOrder({ resources: { cpu: 4, memory: '8Gi' } });
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({ orders: [order] })
+        });
+        bidder.start(60000);
+        await settle(200);
+        const bidCalls = mockFetch.mock.calls.filter((c) => c[1]?.method === 'POST');
+        expect(bidCalls).toHaveLength(0);
+    });
+    it('should skip orders when our price exceeds maxPricePerBlock', async () => {
+        const order = makeOrder({ maxPricePerBlock: 0.0001 });
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({ orders: [order] })
+        });
+        bidder.start(60000);
+        await settle(200);
+        const bidCalls = mockFetch.mock.calls.filter((c) => c[1]?.method === 'POST');
+        expect(bidCalls).toHaveLength(0);
+    });
+    // -- bid price calculation --
+    it('should calculate price based on cpu and memory costs with margin', async () => {
+        // cpu: 2 cores * 0.01 = 0.02
+        // memory: 4gi * 0.005 = 0.02
+        // base: 0.04, with 1.2 margin = 0.048
+        const order = makeOrder({
+            resources: { cpu: 2, memory: '4Gi' },
+            maxPricePerBlock: 10
+        });
+        mockFetch
+            .mockResolvedValueOnce({ ok: true, json: async () => ({ orders: [order] }) })
+            .mockResolvedValueOnce({ ok: true, json: async () => ({ bid: { id: 'bid-1' } }) });
+        bidder.start(60000);
+        await settle(200);
+        const bidCall = mockFetch.mock.calls.find((c) => c[1]?.method === 'POST');
+        expect(bidCall).toBeDefined();
+        const body = JSON.parse(bidCall[1].body);
+        expect(body.pricePerBlock).toBe(0.048);
+    });
+    // -- deduplication --
+    it('should not bid on the same order twice', async () => {
+        const order = makeOrder();
+        mockFetch
+            .mockResolvedValueOnce({ ok: true, json: async () => ({ orders: [order] }) })
+            .mockResolvedValueOnce({ ok: true, json: async () => ({ bid: { id: 'bid-1' } }) });
+        bidder.start(500); // short interval for this test
+        await settle(200);
+        // second poll returns same order
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({ orders: [order] })
+        });
+        await settle(700);
+        // should only have 1 POST (bid submission)
+        const bidCalls = mockFetch.mock.calls.filter((c) => c[1]?.method === 'POST');
+        expect(bidCalls).toHaveLength(1);
+    });
+    it('should track "already bid" errors without retrying', async () => {
+        const order = makeOrder();
+        mockFetch
+            .mockResolvedValueOnce({ ok: true, json: async () => ({ orders: [order] }) })
+            .mockResolvedValueOnce({
+            ok: false,
+            json: async () => ({ message: 'already bid on this order' })
+        });
+        bidder.start(500);
+        await settle(200);
+        // next poll, same order should be skipped
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({ orders: [order] })
+        });
+        await settle(700);
+        // only 1 POST attempt total
+        const bidCalls = mockFetch.mock.calls.filter((c) => c[1]?.method === 'POST');
+        expect(bidCalls).toHaveLength(1);
+    });
+    // -- error handling --
+    it('should handle fetch errors gracefully', async () => {
+        mockFetch.mockRejectedValueOnce(new Error('network down'));
+        bidder.start(60000);
+        await settle(200);
+        // no crash, bidder still alive
+        expect(bidder).toBeDefined();
+    });
+    it('should handle non-ok response from orders endpoint', async () => {
+        mockFetch.mockResolvedValueOnce({
+            ok: false,
+            status: 500,
+            text: async () => 'internal error'
+        });
+        bidder.start(60000);
+        await settle(200);
+        // no crash
+        expect(bidder).toBeDefined();
+    });
+    it('should skip orders older than 7 days', async () => {
+        const oldTimestamp = Date.now() - 8 * 24 * 60 * 60 * 1000;
+        const order = makeOrder({
+            id: `user-abc-${oldTimestamp}-1`
+        });
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({ orders: [order] })
+        });
+        bidder.start(60000);
+        await settle(200);
+        const bidCalls = mockFetch.mock.calls.filter((c) => c[1]?.method === 'POST');
+        expect(bidCalls).toHaveLength(0);
+    });
+    it('should handle empty orders list', async () => {
+        mockFetch.mockResolvedValueOnce({
+            ok: true,
+            json: async () => ({ orders: [] })
+        });
+        bidder.start(60000);
+        await settle(200);
+        // just the one GET, no POSTs
+        const getCalls = mockFetch.mock.calls.filter((c) => !c[1]?.method || c[1]?.method === 'GET');
+        expect(getCalls.length).toBeGreaterThanOrEqual(1);
+        const bidCalls = mockFetch.mock.calls.filter((c) => c[1]?.method === 'POST');
+        expect(bidCalls).toHaveLength(0);
+    });
+    it('should include gpu cost in price when order requires gpu', async () => {
+        const order = makeOrder({
+            resources: {
+                cpu: 2,
+                memory: '4Gi',
+                gpu: { units: 2, attributes: {} }
+            },
+            maxPricePerBlock: 10
+        });
+        mockFetch
+            .mockResolvedValueOnce({ ok: true, json: async () => ({ orders: [order] }) })
+            .mockResolvedValueOnce({ ok: true, json: async () => ({ bid: { id: 'bid-2' } }) });
+        // provide gpu in available resources
+        mockMonitor.getAvailableResources.mockResolvedValueOnce({
+            cpu: { cores: 8, available: 6 },
+            memory: { total: 32, available: 24 },
+            disk: [],
+            network: { bandwidth: 100 },
+            gpu: [
+                { vendor: 'nvidia', model: 'a100', vram: 40 },
+                { vendor: 'nvidia', model: 'a100', vram: 40 }
+            ]
+        });
+        bidder.start(60000);
+        await settle(200);
+        const bidCall = mockFetch.mock.calls.find((c) => c[1]?.method === 'POST');
+        expect(bidCall).toBeDefined();
+        const body = JSON.parse(bidCall[1].body);
+        // cpu: 2*0.01=0.02, mem: 4*0.005=0.02, gpu: 2*0.1=0.2 => base 0.24, *1.2 margin = 0.288
+        expect(body.pricePerBlock).toBe(0.288);
+    });
+});

package/dist/__tests__/container-manager.test.js

@@ -0,0 +1,189 @@
+// tests for ContainerManager - container lifecycle, exec, file ops, health
+jest.mock('../lib/logger.js', () => ({
+    logger: { info: jest.fn(), error: jest.fn(), warn: jest.fn(), debug: jest.fn() }
+}));
+const mockDocker = {
+    checkDocker: jest.fn().mockResolvedValue(true),
+    pullImage: jest.fn().mockResolvedValue(undefined),
+    createContainer: jest.fn().mockResolvedValue({
+        id: 'container-123',
+        // never resolve wait() so the container stays "running" in the map
+        wait: jest.fn().mockReturnValue(new Promise(() => { }))
+    }),
+    getContainerStats: jest.fn().mockResolvedValue({ memory: 100, cpu: 5, network: { rx: 0, tx: 0 } }),
+    cleanupContainer: jest.fn().mockResolvedValue(undefined),
+    execCommand: jest.fn().mockResolvedValue({ stdout: 'ok', stderr: '', exitCode: 0 }),
+    getContainerLogs: jest.fn().mockResolvedValue('log output'),
+    streamContainerLogs: jest.fn().mockResolvedValue(() => { })
+};
+jest.mock('../lib/docker.js', () => ({
+    DockerManager: jest.fn().mockImplementation(() => mockDocker)
+}));
+import { ContainerManager } from '../services/container-manager';
+describe('ContainerManager', () => {
+    let cm;
+    const testJob = {
+        id: 'job-001',
+        userId: 'user-1',
+        image: 'alpine:latest',
+        resources: { cpu: 2, memory: 4, disk: 10 },
+        env: { FOO: 'bar' },
+        duration: 0
+    };
+    beforeEach(() => {
+        jest.clearAllMocks();
+        cm = new ContainerManager();
+    });
+    afterEach(async () => {
+        // cleanup intervals
+        await cm.stop();
+    });
+    // -- start --
+    it('should check docker availability on start', async () => {
+        await cm.start();
+        expect(mockDocker.checkDocker).toHaveBeenCalled();
+    });
+    it('should throw if docker is not available', async () => {
+        mockDocker.checkDocker.mockResolvedValueOnce(false);
+        await expect(cm.start()).rejects.toThrow('docker not available');
+    });
+    // -- runJob --
+    it('should pull image and create container', async () => {
+        const containerId = await cm.runJob(testJob);
+        expect(containerId).toBe('container-123');
+        expect(mockDocker.pullImage).toHaveBeenCalledWith('alpine:latest');
+        expect(mockDocker.createContainer).toHaveBeenCalledWith(expect.objectContaining({
+            jobId: 'job-001',
+            image: 'alpine:latest',
+            cpus: 2,
+            memory: 4096 // 4gb * 1024
+        }));
+    });
+    it('should emit container-started event on successful run', async () => {
+        const events = [];
+        cm.on('container-started', (data) => events.push(data));
+        await cm.runJob(testJob);
+        expect(events).toHaveLength(1);
+        expect(events[0].jobId).toBe('job-001');
+        expect(events[0].containerId).toBe('container-123');
+    });
+    it('should track running jobs after run', async () => {
+        await cm.runJob(testJob);
+        expect(cm.getRunningJobs()).toContain('job-001');
+    });
+    it('should emit container-failed on error', async () => {
+        mockDocker.pullImage.mockRejectedValueOnce(new Error('pull failed'));
+        const events = [];
+        cm.on('container-failed', (data) => events.push(data));
+        await expect(cm.runJob(testJob)).rejects.toThrow('pull failed');
+        expect(events).toHaveLength(1);
+        expect(events[0].jobId).toBe('job-001');
+    });
+    // -- stopContainer --
+    it('should stop and remove tracked container', async () => {
+        await cm.runJob(testJob);
+        const events = [];
+        cm.on('container-stopped', (data) => events.push(data));
+        await cm.stopContainer('job-001');
+        expect(mockDocker.cleanupContainer).toHaveBeenCalledWith('container-123');
+        expect(cm.getRunningJobs()).not.toContain('job-001');
+        expect(events).toHaveLength(1);
+    });
+    it('should silently no-op when stopping unknown job', async () => {
+        await cm.stopContainer('nonexistent');
+        // no throw
+    });
+    // -- execInContainer --
+    it('should exec command in running container', async () => {
+        await cm.runJob(testJob);
+        const result = await cm.execInContainer('job-001', 'whoami');
+        expect(mockDocker.execCommand).toHaveBeenCalledWith('container-123', 'whoami');
+        expect(result.stdout).toBe('ok');
+        expect(result.exitCode).toBe(0);
+    });
+    it('should throw when exec on unknown container', async () => {
+        await expect(cm.execInContainer('nope', 'ls')).rejects.toThrow('container not found');
+    });
+    it('should throw when exec on stopped container', async () => {
+        await cm.runJob(testJob);
+        await cm.stopContainer('job-001');
+        await expect(cm.execInContainer('job-001', 'ls')).rejects.toThrow('container not found');
+    });
+    // -- getContainerLogs --
+    it('should fetch logs from docker', async () => {
+        await cm.runJob(testJob);
+        const logs = await cm.getContainerLogs('job-001', 50);
+        expect(mockDocker.getContainerLogs).toHaveBeenCalledWith('container-123', 50);
+        expect(logs).toBe('log output');
+    });
+    it('should throw for logs on unknown container', async () => {
+        await expect(cm.getContainerLogs('nope')).rejects.toThrow('container not found');
+    });
+    // -- writeFile --
+    it('should base64 encode content and exec write command', async () => {
+        await cm.runJob(testJob);
+        await cm.writeFile('job-001', '/tmp/test.txt', 'hello world');
+        expect(mockDocker.execCommand).toHaveBeenCalled();
+        const call = mockDocker.execCommand.mock.calls[0];
+        expect(call[0]).toBe('container-123');
+        // command should contain base64 encoded content
+        const encoded = Buffer.from('hello world', 'utf8').toString('base64');
+        expect(call[1]).toContain(encoded);
+        expect(call[1]).toContain('/tmp/test.txt');
+    });
+    it('should reject path traversal in writeFile', async () => {
+        await cm.runJob(testJob);
+        await expect(cm.writeFile('job-001', '/tmp/../etc/passwd', 'bad'))
+            .rejects.toThrow('path traversal');
+    });
+    it('should reject relative paths in writeFile', async () => {
+        await cm.runJob(testJob);
+        await expect(cm.writeFile('job-001', 'relative/path.txt', 'bad'))
+            .rejects.toThrow('filepath must be absolute');
+    });
+    it('should reject shell metacharacters in filepath', async () => {
+        await cm.runJob(testJob);
+        await expect(cm.writeFile('job-001', '/tmp/test;rm -rf /', 'bad'))
+            .rejects.toThrow('invalid characters');
+    });
+    it('should reject system paths like /proc', async () => {
+        await cm.runJob(testJob);
+        await expect(cm.writeFile('job-001', '/proc/self/environ', 'bad'))
+            .rejects.toThrow('system paths not allowed');
+    });
+    // -- readFile --
+    it('should read file from container via exec', async () => {
+        await cm.runJob(testJob);
+        const content = await cm.readFile('job-001', '/tmp/data.txt');
+        expect(content).toBe('ok');
+        expect(mockDocker.execCommand).toHaveBeenCalledWith('container-123', expect.stringContaining('/tmp/data.txt'));
+    });
+    it('should reject path traversal in readFile', async () => {
+        await cm.runJob(testJob);
+        await expect(cm.readFile('job-001', '/dev/null/../etc/shadow'))
+            .rejects.toThrow('path traversal');
+    });
+    // -- getHealthStatus --
+    it('should return undefined for unknown job', () => {
+        expect(cm.getHealthStatus('nope')).toBeUndefined();
+    });
+    it('should return initial health status after run', async () => {
+        await cm.runJob(testJob);
+        const health = cm.getHealthStatus('job-001');
+        expect(health).toBeDefined();
+        expect(health.status).toBe('unknown');
+        expect(health.failures).toBe(0);
+    });
+    // -- getRunningJobs --
+    it('should return empty array with no jobs', () => {
+        expect(cm.getRunningJobs()).toEqual([]);
+    });
+    it('should list multiple running jobs', async () => {
+        await cm.runJob(testJob);
+        await cm.runJob({ ...testJob, id: 'job-002' });
+        const jobs = cm.getRunningJobs();
+        expect(jobs).toHaveLength(2);
+        expect(jobs).toContain('job-001');
+        expect(jobs).toContain('job-002');
+    });
+});