deepdebug-local-agent 1.1.0 → 1.3.0

package/test/next-version.test.js

@@ -0,0 +1,48 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { classify, bumpFor, nextVersion } from '../scripts/next-version.mjs'
+
+test('fix and other non-feature types are a patch', () => {
+  for (const s of ['fix: handle empty body', 'fix(ci): x', 'chore: tidy', 'docs: readme', 'ci: workflow', 'perf: faster', 'refactor: split', 'Update thing']) {
+    assert.equal(classify(s), 'patch', s)
+  }
+})
+
+test('feat is a minor', () => {
+  assert.equal(classify('feat: add DLP masking'), 'minor')
+  assert.equal(classify('feat(ws): metadata only channel'), 'minor')
+})
+
+test('breaking changes are a major, by "!" or by footer', () => {
+  assert.equal(classify('feat!: drop node 18'), 'major')
+  assert.equal(classify('fix(api)!: rename endpoint'), 'major')
+  assert.equal(classify('fix: x\n\nBREAKING CHANGE: signature enforce is mandatory'), 'major')
+  assert.equal(classify('chore: y\n\nBREAKING-CHANGE: z'), 'major')
+})
+
+test('auto-bump and merge commits are ignored', () => {
+  assert.equal(classify('ci: auto bump to 1.1.0 [skip ci]'), null)
+  assert.equal(classify('Merge pull request #55 from x/y'), null)
+  assert.equal(classify(''), null)
+})
+
+test('the highest level wins', () => {
+  assert.equal(bumpFor(['fix: a', 'fix: b']), 'patch')
+  assert.equal(bumpFor(['fix: a', 'feat: b', 'chore: c']), 'minor')
+  assert.equal(bumpFor(['feat: a', 'fix!: b', 'fix: c']), 'major')
+  assert.equal(bumpFor([]), 'patch')
+  assert.equal(bumpFor(['ci: auto bump to 1.2.0 [skip ci]']), 'patch')
+})
+
+test('a footer that is not at the start of a line is not breaking', () => {
+  assert.equal(classify('fix: mention BREAKING CHANGE: in prose'), 'patch')
+})
+
+test('nextVersion resets the lower levels', () => {
+  assert.equal(nextVersion('1.1.0', 'patch'), '1.1.1')
+  assert.equal(nextVersion('1.1.7', 'minor'), '1.2.0')
+  assert.equal(nextVersion('1.9.4', 'major'), '2.0.0')
+  assert.equal(nextVersion('0.0.1', 'minor'), '0.1.0')
+  assert.throws(() => nextVersion('1.1', 'patch'))
+  assert.throws(() => nextVersion('1.x.0', 'patch'))
+})

package/test/ws-channel/allowlist.test.js

@@ -0,0 +1,67 @@
+// Contract tests for the metadata-only outbound allowlist (T4-10).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { validateOutbound, projectResponse, OUTBOUND_SCHEMAS } from '../../src/ws-channel/allowlist.js';
+
+const H = 'a'.repeat(64);
+
+test('contract: every allowed message type validates with a golden example', () => {
+  const golden = [
+    { type: 'register', tenantId: 'tenant-1', port: 5055, workspaceHash: H },
+    { type: 'hello', agentVersion: '1.1.0', protocol: 2, signatureMode: 'enforce', metadataOnly: 'enforce' },
+    { type: 'status', state: 'idle', openWorkspaces: 2, queueDepth: 0, uptimeSeconds: 120 },
+    { type: 'cost', requestId: 'req-1', model: 'claude-sonnet-5-5', tokensIn: 10, tokensOut: 5, costMicros: 1200 },
+    { requestId: 'r1', command: 'health', ok: true, status: 'ok', openWorkspaces: 1 },
+    { requestId: 'r2', command: 'workspace.open', ok: false, errorCode: 'command_error' },
+  ];
+  for (const m of golden) assert.deepEqual(validateOutbound(m).ok, true, JSON.stringify(m));
+});
+
+test('contract: schema set is closed (changing it is a deliberate, reviewed edit)', () => {
+  assert.deepEqual(Object.keys(OUTBOUND_SCHEMAS).sort(), ['cost', 'hello', 'register', 'response', 'status']);
+});
+
+test('rejects unknown types, unknown fields and non-objects', () => {
+  assert.equal(validateOutbound({ type: 'file-content', content: 'x' }).reason, 'unknown-type');
+  assert.equal(validateOutbound({ type: 'status', state: 'idle', content: 'x' }).reason, 'unknown-field');
+  assert.equal(validateOutbound('ping').reason, 'not-an-object');
+  assert.equal(validateOutbound([]).reason, 'not-an-object');
+  assert.equal(validateOutbound({ type: '__proto__' }).reason, 'unknown-type');
+});
+
+test('rejects free text: code, diffs, paths, log lines and chat do not fit any string field', () => {
+  const leaks = ['const x = require("fs");', '--- a/x\n+++ b/x', '/Users/me/project/src/A.java', 'ERROR something failed', 'hello how are you', ''];
+  for (const v of leaks) {
+    assert.equal(validateOutbound({ type: 'register', tenantId: v, port: 1 }).ok, false, JSON.stringify(v));
+    assert.equal(validateOutbound({ type: 'cost', requestId: 'r', model: v }).ok, false);
+    assert.equal(validateOutbound({ requestId: 'r', command: v }).ok, false);
+  }
+  assert.equal(validateOutbound({ type: 'register', tenantId: 't', port: 1, workspaceHash: '/etc/passwd' }).field, 'workspaceHash');
+});
+
+test('rejects nested values, wrong numeric ranges and missing required fields', () => {
+  assert.equal(validateOutbound({ type: 'status', state: { a: 1 } }).ok, false);
+  assert.equal(validateOutbound({ type: 'status', openWorkspaces: -1 }).ok, false);
+  assert.equal(validateOutbound({ type: 'status', openWorkspaces: 1.5 }).ok, false);
+  assert.equal(validateOutbound({ type: 'register', port: 70000, tenantId: 't' }).ok, false);
+  assert.equal(validateOutbound({ type: 'register', port: 5055 }).reason, 'missing-field');
+  assert.equal(validateOutbound({ type: 'status', state: 'unknown-state' }).ok, false);
+});
+
+test('validation reports field names and codes, never the offending value', () => {
+  const secret = 'AKIA_SECRET_VALUE_123 /home/x';
+  const r = validateOutbound({ type: 'register', tenantId: secret, port: 1 });
+  assert.equal(JSON.stringify(r).includes('SECRET'), false);
+});
+
+test('projectResponse strips paths, turns free text into errorCode, rejects content fields', () => {
+  assert.deepEqual(projectResponse('r', 'health', { status: 'ok', workspace: '/home/u/p', openWorkspaces: 1 }).message,
+    { requestId: 'r', command: 'health', status: 'ok', openWorkspaces: 1 });
+  assert.deepEqual(projectResponse('r', 'workspace.open', { ok: true, root: '/home/u/p' }).message,
+    { requestId: 'r', command: 'workspace.open', ok: true });
+  assert.deepEqual(projectResponse('r', 'x', { error: 'ENOENT /home/u/secret.txt' }).message,
+    { requestId: 'r', command: 'x', ok: false, errorCode: 'command_error' });
+  const c = projectResponse('r', 'workspace.file-content', { content: 'code', found: true });
+  assert.equal(c.ok, false);
+  assert.equal(c.field, 'content');
+});

package/test/ws-channel/metadata-guard.test.js

@@ -0,0 +1,104 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createWsMetadataGuard } from '../../src/ws-channel/metadata-guard.js';
+import { resolveWsMetadataConfig } from '../../src/ws-channel/config.js';
+import { createTransitGuard } from '../../src/ws-channel/transit-guard.js';
+
+const capture = () => { const lines = []; return { lines, warn: (m) => lines.push(String(m)), log: (m) => lines.push(String(m)) }; };
+const enforce = { mode: 'enforce' };
+
+test('flag config: default off, enforce, and unrecognised values fail closed', () => {
+  const warn = () => {};
+  assert.equal(resolveWsMetadataConfig({}, warn).mode, 'off');
+  assert.equal(resolveWsMetadataConfig({ LOCAL_AGENT_WS_METADATA_ONLY: '' }, warn).mode, 'off');
+  assert.equal(resolveWsMetadataConfig({ LOCAL_AGENT_WS_METADATA_ONLY: 'off' }, warn).mode, 'off');
+  assert.equal(resolveWsMetadataConfig({ LOCAL_AGENT_WS_METADATA_ONLY: ' ENFORCE ' }, warn).mode, 'enforce');
+  assert.equal(resolveWsMetadataConfig({ LOCAL_AGENT_WS_METADATA_ONLY: 'enfroce' }, warn).mode, 'enforce');
+});
+
+test('flag off: no guard is created and no socket is opened', () => {
+  let socketsOpened = 0;
+  const openSocket = () => { socketsOpened++; };
+  const guard = createWsMetadataGuard({ config: resolveWsMetadataConfig({}) });
+  assert.equal(guard, null);
+  if (guard) openSocket(); // the conditional start point: only reached when the guard exists
+  assert.equal(socketsOpened, 0);
+});
+
+test('legacy content commands are refused before execution, with a metadata-only error', () => {
+  const log = capture();
+  const g = createWsMetadataGuard({ config: enforce, logger: log });
+  for (const cmd of ['workspace.file-content', 'workspace.diff', 'workspace.safe-patch', 'mcp.read-file', 'mcp.execute-command', 'mcp.apply-patch']) {
+    const a = g.admitCommand('req-1', cmd);
+    assert.equal(a.ok, false, cmd);
+    assert.deepEqual(JSON.parse(a.errorFrame), { requestId: 'req-1', command: cmd, ok: false, errorCode: 'blocked_metadata_only' });
+  }
+});
+
+test('health reply carries only metadata (workspace path dropped)', () => {
+  const g = createWsMetadataGuard({ config: enforce, logger: capture() });
+  assert.equal(g.admitCommand('r1', 'health').ok, true);
+  const out = JSON.parse(g.frameResponse('r1', 'health', { status: 'ok', workspace: '/Users/x/client-repo', openWorkspaces: 2 }));
+  assert.deepEqual(out, { requestId: 'r1', command: 'health', status: 'ok', openWorkspaces: 2 });
+});
+
+test('content in a reply is blocked, replaced by an error, and never logged', () => {
+  const log = capture();
+  const g = createWsMetadataGuard({ config: enforce, logger: log });
+  g.admitCommand('r2', 'health');
+  const secret = 'SUPER_SECRET_SOURCE_CODE_LINE';
+  const out = JSON.parse(g.frameResponse('r2', 'health', { status: 'ok', diff: secret }));
+  assert.deepEqual(out, { requestId: 'r2', command: 'health', ok: false, errorCode: 'blocked_metadata_only' });
+  assert.ok(log.lines.some((l) => l.includes('BLOCKED') && l.includes('unknown-field') && l.includes('diff')));
+  assert.equal(log.lines.join('\n').includes(secret), false, 'payload must never be logged');
+  assert.equal(JSON.stringify(out).includes(secret), false);
+});
+
+test('free-text error messages become an errorCode and are not sent', () => {
+  const g = createWsMetadataGuard({ config: enforce, logger: capture() });
+  g.admitCommand('r3', 'workspace.open');
+  const out = JSON.parse(g.frameResponse('r3', 'workspace.open', { error: 'ENOENT: /home/u/secret/file.js' }));
+  assert.deepEqual(out, { requestId: 'r3', command: 'workspace.open', ok: false, errorCode: 'command_error' });
+});
+
+test('spontaneous messages are validated; violations return null (dropped, not queued)', () => {
+  const log = capture();
+  const g = createWsMetadataGuard({ config: enforce, logger: log });
+  assert.ok(g.frameMessage({ type: 'status', state: 'idle', openWorkspaces: 1 }));
+  assert.equal(g.frameMessage({ type: 'chat', text: 'hi' }), null);
+  assert.equal(g.frameMessage({ type: 'register', tenantId: 't', port: 1, workspacePath: '/x' }), null);
+  assert.equal(g.stats.blocked, 2);
+});
+
+test('D17 TTL: reply to an unknown, expired or already-answered request is dropped', () => {
+  let t = 1_000;
+  const transit = createTransitGuard({ now: () => t, limits: { requestTtlMs: 1000 } });
+  const g = createWsMetadataGuard({ config: enforce, transit, logger: capture() });
+  assert.equal(g.frameResponse('never', 'health', { status: 'ok' }), null);
+  g.admitCommand('a', 'health');
+  assert.ok(g.frameResponse('a', 'health', { status: 'ok' }));
+  assert.equal(g.frameResponse('a', 'health', { status: 'ok' }), null, 'single use');
+  g.admitCommand('b', 'health');
+  t += 1500;
+  assert.equal(g.frameResponse('b', 'health', { status: 'ok' }), null, 'expired');
+});
+
+test('D17 limits: message size, rate and in-flight bound', () => {
+  const transit = createTransitGuard({ limits: { rateMax: 2, maxInFlight: 2, maxMessageBytes: 60 } });
+  const g = createWsMetadataGuard({ config: enforce, transit, logger: capture() });
+  assert.equal(g.frameMessage({ type: 'cost', requestId: 'r', model: 'm'.repeat(100) }), null, 'oversize');
+  assert.ok(g.frameMessage({ type: 'status', state: 'idle' }));
+  assert.ok(g.frameMessage({ type: 'status', state: 'busy' }));
+  assert.equal(g.frameMessage({ type: 'status', state: 'idle' }), null, 'rate limited');
+  assert.equal(g.admitCommand('x1', 'health').ok, true);
+  assert.equal(g.admitCommand('x2', 'health').ok, true);
+  assert.equal(g.admitCommand('x3', 'health').ok, false, 'in-flight cap');
+});
+
+test('D17: the guard persists nothing (no fs/network usage in the module)', async () => {
+  const { readFile } = await import('node:fs/promises');
+  for (const f of ['metadata-guard', 'transit-guard', 'allowlist']) {
+    const src = await readFile(new URL(`../../src/ws-channel/${f}.js`, import.meta.url), 'utf8');
+    assert.equal(/node:fs|from "fs"|appendFile|writeFile|node:net|node:http/.test(src), false, f);
+  }
+});

package/test/ws-channel/policy-offline.test.js

@@ -0,0 +1,99 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createConnectionState } from '../../src/ws-channel/connection-state.js';
+import { createOfflinePolicyGuard, requiresPolicyGate, decideOffline } from '../../src/ws-channel/policy-offline.js';
+import { decideExec } from '../../src/utils/exec-policy.js';
+
+test('connection state: online only while open and fresh', () => {
+  let t = 0;
+  const c = createConnectionState({ now: () => t, staleAfterMs: 90_000 });
+  assert.equal(c.isOnline(), false);
+  c.markOpen();
+  assert.equal(c.isOnline(), true);
+  t = 60_000; c.markSeen();
+  t = 120_000;
+  assert.equal(c.isOnline(), true);
+  t = 200_000;
+  assert.equal(c.isOnline(), false, 'stale = offline');
+  c.markSeen(); // ignored while stale? still open, refreshes
+  assert.equal(c.isOnline(), true);
+  c.markClosed();
+  assert.equal(c.isOnline(), false);
+  c.markSeen();
+  assert.equal(c.isOnline(), false, 'a message on a closed socket does not revive it');
+});
+
+test('D19 classification: only PolicyGate-backed decisions need the gate', () => {
+  assert.equal(requiresPolicyGate('platform-tool:git_push'), true);
+  assert.equal(requiresPolicyGate('human-approval:ana'), true);
+  assert.equal(requiresPolicyGate('allowlist:git'), false);
+  assert.equal(requiresPolicyGate('policy-off'), false);
+  assert.deepEqual(decideOffline({ gated: true, online: false }).decision, 'DENY');
+  assert.deepEqual(decideOffline({ gated: true, online: true }).decision, 'ALLOW');
+  assert.deepEqual(decideOffline({ gated: false, online: false }).decision, 'ALLOW');
+});
+
+test('D19 guard: offline DENY for gated allows, allowlisted local commands unaffected', () => {
+  const state = { online: false };
+  const denied = [];
+  const guard = createOfflinePolicyGuard({ connection: { isOnline: () => state.online }, onDeny: (d) => denied.push(d) });
+  const gated = { allow: true, via: 'platform-tool:git_push' };
+  const local = { allow: true, via: 'allowlist:git' };
+
+  const d = guard(gated);
+  assert.equal(d.allow, false);
+  assert.equal(d.status, 403);
+  assert.equal(d.via, 'policy-gate-offline');
+  assert.deepEqual(denied, [{ via: 'platform-tool' }]);
+  assert.equal(guard(local), local);
+  assert.deepEqual(guard({ allow: false, via: 'rejected' }), { allow: false, via: 'rejected' });
+
+  state.online = true;
+  assert.equal(guard(gated), gated, 'online: PolicyGate path unchanged');
+});
+
+test('D19 via decideExec: a signed platform tool is denied offline, allowed online; flag off = unchanged', () => {
+  const input = {
+    command: 'git push origin feat/x', root: process.cwd(), headers: {},
+    body: { commandOrigin: 'platform', tool: 'git_push' }, vhSignature: { verified: true },
+  };
+  const base = { mode: 'enforce' };
+  assert.equal(decideExec(input, base).allow, true, 'flag off (no guard): unchanged');
+  let online = false;
+  const cfg = { mode: 'enforce', offlineGuard: createOfflinePolicyGuard({ connection: { isOnline: () => online } }) };
+  const off = decideExec(input, cfg);
+  assert.equal(off.allow, false);
+  assert.equal(off.via, 'policy-gate-offline');
+  online = true;
+  assert.equal(decideExec(input, cfg).allow, true);
+});
+
+test('D19 on the MCP bridge: /mcp/execute-command denies a platform tool offline, allows it online', async () => {
+  const net = await import('node:net');
+  const { startMCPHttpServer } = await import('../../src/mcp-http-server.js');
+  const { internalSignatureHeaders } = await import('../../src/utils/request-signing.js');
+  const port = await new Promise((resolve) => {
+    const s = net.createServer().listen(0, '127.0.0.1', () => { const p = s.address().port; s.close(() => resolve(p)); });
+  });
+  let online = false;
+  const execPolicy = { mode: 'enforce', offlineGuard: createOfflinePolicyGuard({ connection: { isOnline: () => online } }) };
+  const app = startMCPHttpServer({ resolveRoot: () => process.cwd(), count: 0, list: () => [] }, port, execPolicy);
+  await new Promise((r) => (app.locals.server.listening ? r() : app.locals.server.once('listening', r)));
+  try {
+    const call = () => fetch(`http://127.0.0.1:${port}/mcp/execute-command`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', ...internalSignatureHeaders() },
+      body: JSON.stringify({ workspaceId: 'w', command: 'git --version', commandOrigin: 'platform', tool: 'current_branch' }),
+    });
+    const off = await call();
+    const offBody = await off.json();
+    assert.equal(off.status, 403);
+    assert.equal(offBody.ok, false);
+    assert.match(String(offBody.reason), /control plane|offline|policy/i);
+    online = true;
+    const on = await call();
+    assert.notEqual(on.status, 403, 'online: PolicyGate path unchanged');
+  } finally {
+    app.locals.server.close();
+  }
+});

package/test/ws-channel/tunnel-e2e.test.js

@@ -0,0 +1,88 @@
+// End-to-end: boots the real agent against a fake control-plane WS server and
+// inspects what actually leaves the socket (T4-10).
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import net from 'node:net';
+import os from 'node:os';
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { WebSocketServer } from 'ws';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const SECRET = 'TOP_SECRET_SOURCE_MARKER_8841';
+
+const freePort = () => new Promise((res) => { const s = net.createServer().listen(0, '127.0.0.1', () => { const p = s.address().port; s.close(() => res(p)); }); });
+
+async function run({ flag, disableTunnel = false }) {
+  const ws = fs.mkdtempSync(path.join(os.tmpdir(), 'wsmeta-ws-'));
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'wsmeta-home-'));
+  fs.writeFileSync(path.join(ws, 'secret.txt'), SECRET);
+  const wss = new WebSocketServer({ port: 0, host: '127.0.0.1' });
+  await new Promise((r) => wss.on('listening', r));
+  const frames = [];
+  let connections = 0;
+  wss.on('connection', (sock) => {
+    connections++;
+    sock.on('message', (d) => {
+      const t = d.toString();
+      if (t === 'ping') return;
+      frames.push(JSON.parse(t));
+      if (frames[frames.length - 1].type === 'register') {
+        sock.send(JSON.stringify({ requestId: 'req-health', command: 'health', params: {} }));
+        sock.send(JSON.stringify({ requestId: 'req-file', command: 'workspace.file-content', params: { path: 'secret.txt', workspacePath: ws } }));
+      }
+    });
+  });
+  const env = { ...process.env, PORT: String(await freePort()), GATEWAY_URL: `http://127.0.0.1:${wss.address().port}`,
+    TENANT_ID: 'tenant-test', AUTH_TOKEN: 'test-token', WORKSPACE_ROOT: ws, HOME: home,
+    LOCAL_AGENT_SIGNATURE_MODE: 'off', ...(flag ? { LOCAL_AGENT_WS_METADATA_ONLY: flag } : {}),
+    ...(disableTunnel ? { DISABLE_WS_TUNNEL: 'true' } : {}) };
+  delete env.LOCAL_AGENT_TOKEN;
+  const child = spawn(process.execPath, ['src/server.js'], { cwd: ROOT, env, stdio: 'ignore' });
+  try {
+    const deadline = Date.now() + (disableTunnel ? 4000 : 20000);
+    while (Date.now() < deadline) {
+      if (frames.some((f) => f.requestId === 'req-file') && frames.some((f) => f.requestId === 'req-health')) break;
+      await new Promise((r) => setTimeout(r, 100));
+    }
+  } finally {
+    child.kill('SIGKILL');
+    for (const c of wss.clients) c.terminate();
+    await new Promise((r) => wss.close(r));
+    fs.rmSync(ws, { recursive: true, force: true });
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+  return { frames, connections };
+}
+
+test('flag off (default): legacy channel is unchanged', async () => {
+  const { frames } = await run({});
+  const reg = frames.find((f) => f.type === 'register');
+  assert.ok(reg && 'workspacePath' in reg, 'legacy register still carries workspacePath');
+  const file = frames.find((f) => f.requestId === 'req-file');
+  assert.equal(file.content, SECRET, 'legacy content command still works with the flag off');
+});
+
+test('enforce: nothing but allowlisted metadata leaves the socket, content never does', async () => {
+  const { frames } = await run({ flag: 'enforce' });
+  assert.ok(frames.length >= 3, 'register + 2 replies expected');
+  assert.equal(JSON.stringify(frames).includes(SECRET), false);
+  assert.equal(JSON.stringify(frames).includes('secret.txt'), false);
+  const reg = frames.find((f) => f.type === 'register');
+  assert.equal(reg.workspacePath, undefined);
+  assert.match(reg.workspaceHash, /^[a-f0-9]{64}$/);
+  assert.deepEqual(frames.find((f) => f.requestId === 'req-file'),
+    { requestId: 'req-file', command: 'workspace.file-content', ok: false, errorCode: 'blocked_metadata_only' });
+  const health = frames.find((f) => f.requestId === 'req-health');
+  assert.equal(health.status, 'ok');
+  assert.equal('workspace' in health, false);
+});
+
+test('DISABLE_WS_TUNNEL=true: no socket is opened, whatever the flag', async () => {
+  for (const flag of [undefined, 'enforce']) {
+    const { connections } = await run({ flag, disableTunnel: true });
+    assert.equal(connections, 0, `flag=${flag}`);
+  }
+});