@nhic-lab/srv-wrapper 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nhic-lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# srv-wrapper
+
+A local daemon + CLI that lets AI coding agents run commands on your servers by an opaque **server-id** only — the agent never sees the real hostname, IP, port, username, or password/key. Everything an agent runs is visible live in a browser dashboard and permanently recorded in an audit log.
+
+## Why
+
+Giving an AI agent real SSH credentials means it can (accidentally or otherwise) leak them, and you lose visibility into what it actually did on the remote box. `srv-wrapper` sits between the agent and your servers: you register a server once via the dashboard, the agent only ever gets a short id like `srv-a1`, and the daemon resolves that id to the real connection internally.
+
+## How it works
+
+- **`srvd`** — a background daemon that holds the server registry (SQLite), stores secrets in the macOS Keychain, manages SSH connections, and exposes two local-only surfaces:
+  - a Unix domain socket for the CLI
+  - an Express + WebSocket dashboard, bound to `127.0.0.1` only
+- **`srv`** — the CLI an agent invokes. Supports one-shot commands and persistent interactive sessions.
+- **Dashboard** — register servers (single or bulk JSON import), watch a live feed of what every agent is running right now, and browse history.
+
+## Install
+
+```bash
+npm install -g @nhic-lab/srv-wrapper   # exposes `srv` and `srvd` globally
+```
+
+Or, from a clone of this repo:
+
+```bash
+npm install
+npm run build
+npm link              # exposes `srv` and `srvd` globally
+```
+
+Then, to have the daemon start automatically on login:
+
+```bash
+./scripts/install-launchd.sh
+```
+
+This installs a `launchd` agent (`~/Library/LaunchAgents/com.srv-wrapper.daemon.plist`) that runs the built daemon and restarts it if it crashes. Logs go to `~/.srv/daemon.log` and `~/.srv/daemon.error.log`.
+
+Alternatively, run it directly without installing anything permanent:
+
+```bash
+npm run dev:daemon
+```
+
+## Usage
+
+Open the dashboard at **http://127.0.0.1:4280** and register a server (id, host, port, username, auth method, password or key passphrase).
+
+Then, from anywhere:
+
+```bash
+# one-shot command
+srv exec srv-a1 "npm run build" --agent my-agent-label
+
+# persistent session (state — cwd, env vars — persists across calls)
+srv session start srv-a1 --agent my-agent-label   # prints a session id
+srv session send <session-id> "cd /var/www && ls"
+srv session send <session-id> "pwd"                # still /var/www
+srv session stop <session-id>
+```
+
+`--agent <label>` is required on every `exec` and `session start` call — it's how the dashboard's live view distinguishes multiple agents running at once.
+
+A Claude Code skill (`.claude/skills/srv-wrapper/SKILL.md`, also symlinked into `~/.claude/skills/`) documents this CLI so any Claude Code agent picks it up automatically.
+
+## Security model
+
+- Servers are referenced everywhere only by id — real connection details never reach the CLI process, its output, or the audit log (SSH errors are sanitized before being surfaced).
+- Secrets live in the macOS Keychain, scoped to the daemon binary via an ACL — not in the SQLite registry.
+- SSH host keys are pinned on first use (TOFU) and persisted across daemon restarts.
+- Private key files are restricted to paths resolving inside `~/.ssh`.
+- The dashboard has no authentication layer — it's a deliberate trade-off for a tool that only binds to `127.0.0.1` on your own machine, not a gap.
+
+## Development
+
+See `CLAUDE.md` for commands and architecture notes. Full design spec and implementation plan live under `docs/superpowers/`.

package/dist/cli/client.js

@@ -0,0 +1,135 @@
+import net from 'node:net';
+import { randomUUID } from 'node:crypto';
+import { encodeMessage, decodeMessages } from '../daemon/socket-protocol.js';
+export function execCommand(opts) {
+    return new Promise((resolve, reject) => {
+        const requestId = randomUUID();
+        const conn = net.createConnection(opts.socketPath);
+        let buffer = '';
+        conn.on('connect', () => {
+            conn.write(encodeMessage({
+                type: 'exec',
+                requestId,
+                serverId: opts.serverId,
+                agentLabel: opts.agentLabel,
+                command: opts.command,
+            }));
+        });
+        conn.on('data', (data) => {
+            buffer += data.toString();
+            const { messages, rest } = decodeMessages(buffer);
+            buffer = rest;
+            for (const msg of messages) {
+                if (msg.type === 'stream') {
+                    opts.onStream(msg.stream, msg.chunk);
+                }
+                else if (msg.type === 'done') {
+                    conn.end();
+                    if (msg.error)
+                        reject(new Error(msg.error));
+                    else
+                        resolve(msg.exitCode);
+                }
+            }
+        });
+        conn.on('error', reject);
+    });
+}
+export function sessionStart(opts) {
+    return new Promise((resolve, reject) => {
+        const requestId = randomUUID();
+        const conn = net.createConnection(opts.socketPath);
+        let buffer = '';
+        conn.on('connect', () => {
+            conn.write(encodeMessage({ type: 'session_start', requestId, serverId: opts.serverId, agentLabel: opts.agentLabel }));
+        });
+        conn.on('data', (data) => {
+            buffer += data.toString();
+            const { messages, rest } = decodeMessages(buffer);
+            buffer = rest;
+            for (const msg of messages) {
+                if (msg.type === 'session_started') {
+                    conn.end();
+                    resolve(msg.sessionId);
+                }
+                else if (msg.type === 'done' && msg.error) {
+                    conn.end();
+                    reject(new Error(msg.error));
+                }
+            }
+        });
+        conn.on('error', reject);
+    });
+}
+export function sessionSend(opts) {
+    return new Promise((resolve, reject) => {
+        const requestId = randomUUID();
+        const conn = net.createConnection(opts.socketPath);
+        let buffer = '';
+        conn.on('connect', () => {
+            conn.write(encodeMessage({ type: 'session_send', requestId, sessionId: opts.sessionId, command: opts.command }));
+        });
+        conn.on('data', (data) => {
+            buffer += data.toString();
+            const { messages, rest } = decodeMessages(buffer);
+            buffer = rest;
+            for (const msg of messages) {
+                if (msg.type === 'stream')
+                    opts.onStream(msg.stream, msg.chunk);
+                else if (msg.type === 'done') {
+                    conn.end();
+                    msg.error ? reject(new Error(msg.error)) : resolve();
+                }
+            }
+        });
+        conn.on('error', reject);
+    });
+}
+export function listServers(opts) {
+    return new Promise((resolve, reject) => {
+        const requestId = randomUUID();
+        const conn = net.createConnection(opts.socketPath);
+        let buffer = '';
+        conn.on('connect', () => {
+            conn.write(encodeMessage({ type: 'list', requestId }));
+        });
+        conn.on('data', (data) => {
+            buffer += data.toString();
+            const { messages, rest } = decodeMessages(buffer);
+            buffer = rest;
+            for (const msg of messages) {
+                if (msg.type === 'list_result') {
+                    conn.end();
+                    resolve(msg.serverIds);
+                }
+                else if (msg.type === 'done' && msg.error) {
+                    conn.end();
+                    reject(new Error(msg.error));
+                }
+            }
+        });
+        conn.on('error', reject);
+    });
+}
+export function sessionStop(opts) {
+    return new Promise((resolve, reject) => {
+        const requestId = randomUUID();
+        const conn = net.createConnection(opts.socketPath);
+        let buffer = '';
+        conn.on('connect', () => {
+            conn.write(encodeMessage({ type: 'session_stop', requestId, sessionId: opts.sessionId }));
+        });
+        conn.on('data', (data) => {
+            buffer += data.toString();
+            const { messages, rest } = decodeMessages(buffer);
+            buffer = rest;
+            for (const msg of messages) {
+                if (msg.type === 'done') {
+                    conn.end();
+                    msg.error ? reject(new Error(msg.error)) : resolve();
+                }
+            }
+        });
+        conn.on('error', reject);
+    });
+}

package/dist/cli/index.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { execCommand, sessionStart, sessionSend, sessionStop, listServers } from './client.js';
+import { srvSocketPath } from '../shared/paths.js';
+const program = new Command();
+program
+    .name('srv')
+    .description('Run commands on registered servers by id, without ever seeing host/credentials');
+program
+    .command('exec <server-id> <command>')
+    .requiredOption('--agent <label>', 'label identifying the calling agent/session')
+    .action(async (serverId, command, options) => {
+    try {
+        const exitCode = await execCommand({
+            socketPath: srvSocketPath(),
+            serverId,
+            agentLabel: options.agent,
+            command,
+            onStream: (stream, chunk) => {
+                (stream === 'stdout' ? process.stdout : process.stderr).write(chunk);
+            },
+        });
+        process.exit(exitCode);
+    }
+    catch (err) {
+        process.stderr.write(`srv: ${err.message}\n`);
+        process.exit(1);
+    }
+});
+program
+    .command('list')
+    .description('List all registered server ids')
+    .action(async () => {
+    try {
+        const serverIds = await listServers({ socketPath: srvSocketPath() });
+        for (const id of serverIds)
+            process.stdout.write(id + '\n');
+    }
+    catch (err) {
+        process.stderr.write(`srv: ${err.message}\n`);
+        process.exit(1);
+    }
+});
+const session = program.command('session').description('Manage a persistent interactive session on a server');
+session
+    .command('start <server-id>')
+    .requiredOption('--agent <label>', 'label identifying the calling agent/session')
+    .action(async (serverId, options) => {
+    const sessionId = await sessionStart({ socketPath: srvSocketPath(), serverId, agentLabel: options.agent });
+    process.stdout.write(sessionId + '\n');
+});
+session
+    .command('send <session-id> <command>')
+    .action(async (sessionId, command) => {
+    await sessionSend({
+        socketPath: srvSocketPath(), sessionId, command: command + '\n',
+        onStream: (stream, chunk) => (stream === 'stdout' ? process.stdout : process.stderr).write(chunk),
+    });
+});
+session
+    .command('stop <session-id>')
+    .action(async (sessionId) => {
+    await sessionStop({ socketPath: srvSocketPath(), sessionId });
+});
+program.parseAsync(process.argv);

package/dist/daemon/dashboard-server.js

@@ -0,0 +1,283 @@
+import express from 'express';
+import { WebSocketServer } from 'ws';
+import { resolveJumpPath } from './jump-chain.js';
+import { sanitizeSshError } from './socket-server.js';
+function validateServerInput(input) {
+    if (!input.id || typeof input.id !== 'string' || !/^[a-zA-Z0-9._-]{1,64}$/.test(input.id))
+        return 'invalid or missing id';
+    if (!input.host || typeof input.host !== 'string')
+        return 'missing host';
+    if (!Number.isInteger(input.port) || input.port < 1 || input.port > 65535)
+        return 'port must be an integer between 1 and 65535';
+    if (!input.username || typeof input.username !== 'string')
+        return 'missing username';
+    if (input.authMethod !== 'password' && input.authMethod !== 'key')
+        return 'authMethod must be password or key';
+    if (input.authMethod === 'key' && !input.keyPath)
+        return 'keyPath is required when authMethod is key';
+    if (input.authMethod === 'password' && input.keyPath)
+        return 'keyPath must not be set when authMethod is password';
+    if (input.jumpChain !== undefined) {
+        if (!Array.isArray(input.jumpChain) || !input.jumpChain.every((id) => typeof id === 'string' && id.length > 0)) {
+            return 'jumpChain must be an array of server ids';
+        }
+    }
+    // Editing an existing server may omit the secret to keep the one already stored in Keychain.
+    // Key auth may omit it entirely: there the credential is the key file at
+    // keyPath, and the secret is only its (often absent) passphrase.
+    if (!input.secret && !input.isEdit && input.authMethod !== 'key')
+        return 'missing secret';
+    return null;
+}
+export function createDashboardApp(opts) {
+    const app = express();
+    app.use(express.json({ limit: '32kb' }));
+    const wsClients = new Set();
+    const broadcast = (event) => {
+        const payload = JSON.stringify(event);
+        for (const client of wsClients)
+            client.send(payload);
+    };
+    app.post('/api/servers', (req, res) => {
+        const input = req.body;
+        const error = validateServerInput(input);
+        if (error)
+            return res.status(400).json({ error });
+        const existing = opts.registry.get(input.id);
+        if (existing && !input.isEdit) {
+            return res.status(409).json({ error: `a server with id "${input.id}" already exists` });
+        }
+        if (!existing && input.isEdit) {
+            return res.status(404).json({ error: `no server with id "${input.id}" exists to edit` });
+        }
+        if (input.jumpChain && input.jumpChain.length > 0) {
+            try {
+                resolveJumpPath(input.id, input.jumpChain, (id) => opts.registry.get(id));
+            }
+            catch (err) {
+                return res.status(400).json({ error: err?.message ?? String(err) });
+            }
+        }
+        const record = opts.registry.upsert({
+            id: input.id, host: input.host, port: input.port, username: input.username,
+            authMethod: input.authMethod, keyPath: input.keyPath, jumpChain: input.jumpChain,
+        });
+        let priorSecret;
+        try {
+            priorSecret = existing ? opts.keychain.getSecret(input.id) : undefined;
+            // A passphrase-less private key legitimately has no secret to store.
+            const keyFallback = input.authMethod === 'key' ? '' : undefined;
+            const secretToStore = input.secret || priorSecret || keyFallback;
+            if (secretToStore === undefined)
+                throw new Error('missing secret');
+            opts.keychain.setSecret(input.id, secretToStore);
+        }
+        catch (err) {
+            if (existing) {
+                opts.registry.upsert({
+                    id: existing.id, host: existing.host, port: existing.port, username: existing.username,
+                    authMethod: existing.authMethod, keyPath: existing.keyPath, jumpChain: existing.jumpChain,
+                });
+                if (priorSecret !== undefined)
+                    opts.keychain.setSecret(existing.id, priorSecret);
+            }
+            else {
+                opts.registry.delete(input.id);
+            }
+            return res.status(500).json({ error: `failed to store secret: ${err?.message ?? err}` });
+        }
+        res.status(201).json(record);
+    });
+    app.post('/api/servers/bulk', (req, res) => {
+        if (!Array.isArray(req.body.servers)) {
+            return res.status(400).json({ error: 'servers must be an array' });
+        }
+        const servers = req.body.servers;
+        const seenIds = new Set();
+        const failed = [];
+        const valid = [];
+        for (const input of servers) {
+            const error = validateServerInput(input);
+            if (error) {
+                failed.push({ id: input.id, error });
+                continue;
+            }
+            if (seenIds.has(input.id)) {
+                failed.push({ id: input.id, error: 'duplicate id in batch' });
+                continue;
+            }
+            seenIds.add(input.id);
+            valid.push(input);
+        }
+        if (failed.length > 0) {
+            return res.json({ succeeded: [], failed });
+        }
+        const succeeded = [];
+        const committed = [];
+        try {
+            for (const input of valid) {
+                const priorRecord = opts.registry.get(input.id);
+                const priorSecret = priorRecord ? opts.keychain.getSecret(input.id) : undefined;
+                opts.registry.upsert({
+                    id: input.id, host: input.host, port: input.port, username: input.username,
+                    authMethod: input.authMethod, keyPath: input.keyPath,
+                });
+                committed.push({ id: input.id, priorRecord, priorSecret });
+                opts.keychain.setSecret(input.id, input.secret);
+                succeeded.push(input.id);
+            }
+        }
+        catch (err) {
+            for (const { id, priorRecord, priorSecret } of committed) {
+                if (priorRecord) {
+                    opts.registry.upsert({
+                        id: priorRecord.id, host: priorRecord.host, port: priorRecord.port, username: priorRecord.username,
+                        authMethod: priorRecord.authMethod, keyPath: priorRecord.keyPath,
+                    });
+                    if (priorSecret !== undefined)
+                        opts.keychain.setSecret(priorRecord.id, priorSecret);
+                }
+                else {
+                    opts.registry.delete(id);
+                    opts.keychain.deleteSecret(id);
+                }
+            }
+            return res.status(500).json({ error: `bulk import failed partway, rolled back: ${err?.message ?? err}`, succeeded: [], failed: [] });
+        }
+        res.json({ succeeded, failed: [] });
+    });
+    app.get('/api/servers', (_req, res) => {
+        res.json(opts.registry.list());
+    });
+    app.post('/api/servers/:id/test', async (req, res) => {
+        if (!opts.sshManager)
+            return res.status(501).json({ error: 'connection testing is not available' });
+        const server = opts.registry.get(req.params.id);
+        if (!server)
+            return res.status(404).json({ error: `unknown server: ${req.params.id}` });
+        try {
+            await opts.sshManager.testConnect(server);
+            opts.registry.setTestResult(server.id, true);
+            res.json({ ok: true });
+        }
+        catch (err) {
+            const safe = sanitizeSshError(err);
+            opts.registry.setTestResult(server.id, false, safe);
+            res.json({ ok: false, error: safe });
+        }
+    });
+    app.post('/api/servers/test', async (req, res) => {
+        if (!opts.sshManager)
+            return res.status(501).json({ error: 'connection testing is not available' });
+        const input = req.body;
+        const existing = input.id ? opts.registry.get(input.id) : undefined;
+        const error = validateServerInput({ ...input, isEdit: Boolean(existing && !input.secret) });
+        if (error)
+            return res.status(400).json({ error });
+        if (input.jumpChain && input.jumpChain.length > 0) {
+            try {
+                resolveJumpPath(input.id, input.jumpChain, (id) => opts.registry.get(id));
+            }
+            catch (err) {
+                return res.status(400).json({ error: err?.message ?? String(err) });
+            }
+        }
+        let secret;
+        try {
+            secret = input.secret || (existing ? opts.keychain.getSecret(input.id) : undefined);
+        }
+        catch {
+            // Keychain lookup can throw if the secret was never stored (or was deleted) —
+            // treat that the same as "no secret provided" rather than crashing the request.
+            secret = undefined;
+        }
+        if (secret === undefined && input.authMethod === 'key')
+            secret = '';
+        if (secret === undefined)
+            return res.status(400).json({ error: 'missing secret' });
+        const record = {
+            id: input.id, host: input.host, port: input.port, username: input.username,
+            authMethod: input.authMethod, keyPath: input.keyPath, jumpChain: input.jumpChain,
+            createdAt: 0, updatedAt: 0,
+        };
+        try {
+            await opts.sshManager.testConnect(record, secret);
+            res.json({ ok: true });
+        }
+        catch (err) {
+            res.json({ ok: false, error: sanitizeSshError(err) });
+        }
+    });
+    app.post('/api/servers/test-all', (_req, res) => {
+        if (!opts.sshManager)
+            return res.status(501).json({ error: 'connection testing is not available' });
+        const servers = opts.registry.list();
+        res.status(202).json({ count: servers.length });
+        for (const server of servers) {
+            opts.sshManager
+                .testConnect(server)
+                .then(() => {
+                opts.registry.setTestResult(server.id, true);
+                broadcast({ type: 'server_test_result', id: server.id, ok: true, at: Date.now() });
+            })
+                .catch((err) => {
+                const safe = sanitizeSshError(err);
+                opts.registry.setTestResult(server.id, false, safe);
+                broadcast({ type: 'server_test_result', id: server.id, ok: false, error: safe, at: Date.now() });
+            });
+        }
+    });
+    app.delete('/api/servers/:id', (req, res) => {
+        opts.registry.delete(req.params.id);
+        opts.keychain.deleteSecret(req.params.id);
+        res.status(204).end();
+    });
+    /**
+     * Run metadata only, newest first. Output is deliberately excluded: returning
+     * it for every run is what made this endpoint fail with "RangeError: Invalid
+     * string length" once stored output passed V8's string ceiling. The total row
+     * count rides along in X-Total-Count so the UI can say "showing N of M"
+     * without changing the array response shape.
+     */
+    app.get('/api/history', (req, res) => {
+        const { serverId, agentLabel } = req.query;
+        const limit = Number.parseInt(String(req.query.limit ?? ''), 10);
+        const offset = Number.parseInt(String(req.query.offset ?? ''), 10);
+        const runs = opts.logStore.list({
+            serverId,
+            agentLabel,
+            limit: Number.isFinite(limit) ? limit : undefined,
+            offset: Number.isFinite(offset) ? offset : undefined,
+        });
+        res.set('X-Total-Count', String(opts.logStore.count({ serverId, agentLabel })));
+        res.json(runs);
+    });
+    /** One run including its (already capped) output. */
+    app.get('/api/history/:id', (req, res) => {
+        const run = opts.logStore.get(req.params.id);
+        if (!run)
+            return res.status(404).json({ error: `unknown run: ${req.params.id}` });
+        res.json(run);
+    });
+    app.use(express.static(new URL('../../public', import.meta.url).pathname));
+    const ALLOWED_ORIGINS = new Set(['http://127.0.0.1:4280', 'http://localhost:4280']);
+    const attachWebSocket = (server) => {
+        const wss = new WebSocketServer({
+            server,
+            path: '/api/live',
+            verifyClient: (info, cb) => {
+                if (!info.origin || !ALLOWED_ORIGINS.has(info.origin)) {
+                    cb(false, 403, 'forbidden origin');
+                    return;
+                }
+                cb(true);
+            },
+        });
+        wss.on('connection', (ws) => {
+            wsClients.add(ws);
+            ws.on('close', () => wsClients.delete(ws));
+        });
+    };
+    app.attachWebSocket = attachWebSocket;
+    return { app, broadcast };
+}

package/dist/daemon/index.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import http from 'node:http';
+import fs from 'node:fs';
+import { Registry } from './registry.js';
+import { Keychain } from './keychain.js';
+import { LogStore } from './logstore.js';
+import { SshManager, RegistryHostKeyStore } from './ssh-manager.js';
+import { SocketServer } from './socket-server.js';
+import { createDashboardApp } from './dashboard-server.js';
+import { srvHome, srvSocketPath, srvRegistryDbPath, srvLogDbPath } from '../shared/paths.js';
+const DASHBOARD_PORT = 4280;
+process.on('uncaughtException', (err) => {
+    console.error('srvd: uncaught exception (daemon continuing):', err);
+});
+async function main() {
+    fs.mkdirSync(srvHome(), { recursive: true, mode: 0o700 });
+    const registry = new Registry(srvRegistryDbPath());
+    const logStore = new LogStore(srvLogDbPath());
+    // Trust is scoped to THIS script's real path, not the generic `node`
+    // binary (process.execPath) — trusting `node` itself would grant Keychain
+    // access to any script run via that Node install, not just this daemon.
+    // realpathSync keeps the identity stable even if dist/ is reached via a
+    // symlink. This path is only stable for the BUILT daemon (dist/daemon/
+    // index.js) invoked the same way every time (e.g. via the launchd plist)
+    // — dev-mode (tsx) invocations don't have a stable script path and will
+    // still prompt on every run.
+    const keychain = new Keychain(fs.realpathSync(process.argv[1]));
+    const sshManager = new SshManager((serverId) => keychain.getSecret(serverId), undefined, new RegistryHostKeyStore(registry), (serverId) => registry.get(serverId));
+    const { app, broadcast } = createDashboardApp({ registry, keychain, logStore, sshManager });
+    const httpServer = http.createServer(app);
+    app.attachWebSocket(httpServer);
+    httpServer.listen(DASHBOARD_PORT, '127.0.0.1', () => {
+        console.log(`Dashboard listening on http://127.0.0.1:${DASHBOARD_PORT}`);
+    });
+    const socketServer = new SocketServer({
+        socketPath: srvSocketPath(),
+        registry,
+        logStore,
+        sshManager,
+        onBroadcast: (event) => broadcast(event),
+    });
+    await socketServer.start();
+    console.log(`Socket server listening on ${srvSocketPath()}`);
+}
+main().catch((err) => {
+    console.error('srvd failed to start:', err);
+    process.exit(1);
+});

package/dist/daemon/jump-chain.js

@@ -0,0 +1,35 @@
+/**
+ * Given a target server id and its proposed (not-yet-persisted) jumpChain,
+ * resolves the fully-expanded ordered hop path — recursively following each
+ * hop's own stored jumpChain — and returns it as an array of server ids
+ * ordered first-hop-to-connect-to first, target last.
+ *
+ * Throws if:
+ *  - any referenced id doesn't exist in the registry (via `lookup`)
+ *  - the target's own id, or any id, appears more than once in the fully
+ *    expanded path (including the trivial case of a server referencing
+ *    itself, directly or indirectly)
+ */
+export function resolveJumpPath(targetId, proposedChain, lookup) {
+    const path = [];
+    const seen = new Set([targetId]);
+    const expandHop = (id) => {
+        if (seen.has(id)) {
+            throw new Error(`jump chain cycle detected: "${id}" would be reached more than once`);
+        }
+        seen.add(id);
+        const record = lookup(id);
+        if (!record) {
+            throw new Error(`jump chain references unknown server id "${id}"`);
+        }
+        for (const subHopId of record.jumpChain ?? []) {
+            expandHop(subHopId);
+        }
+        path.push(id);
+    };
+    for (const hopId of proposedChain) {
+        expandHop(hopId);
+    }
+    path.push(targetId);
+    return path;
+}