@tobq/boardclip 0.0.0-stage → 2.1.107

package/lib/cloud-accounts.js

@@ -0,0 +1,250 @@
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execFile } = require('child_process');
+const { probePath } = require('./fs-probe');
+const { promisify } = require('util');
+
+const execFileAsync = promisify(execFile);
+// Cloud mounts (DriveFS drive letters, ~/Library/CloudStorage, OneDrive) are
+// the one place discovery can HANG instead of failing, so every existence check
+// here carries a deadline. See lib/fs-probe.js for the incident this prevents.
+const MOUNT_PROBE_TIMEOUT_MS = 2000;
+const exists = target => probePath(target, { timeoutMs: MOUNT_PROBE_TIMEOUT_MS });
+const readdirBounded = async (dir) => {
+  if (!(await exists(dir))) return [];
+  try { return await fs.promises.readdir(dir); } catch { return []; }
+};
+
+const EMAIL_RE_SOURCE = '[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}';
+const EMAIL_RE = new RegExp(`^${EMAIL_RE_SOURCE}$`, 'i');
+
+function addAccount(accounts, seen, provider, label, basePath) {
+  const drivePath = path.join(basePath, 'clipboard-tray');
+  if (seen.has(drivePath)) return;
+  seen.add(drivePath);
+  accounts.push({ provider, label, email: label, path: drivePath });
+}
+
+function normalizeDriveLetter(value) {
+  const match = String(value || '').trim().match(/^([A-Z]):?\\?$/i);
+  return match ? match[1].toUpperCase() : null;
+}
+
+function setEmailByDriveLetter(map, letter, email) {
+  const normalizedLetter = normalizeDriveLetter(letter);
+  const normalizedEmail = String(email || '').trim();
+  if (!normalizedLetter || !EMAIL_RE.test(normalizedEmail)) return;
+  map.set(normalizedLetter, normalizedEmail);
+}
+
+function mergeMissingDriveEmails(target, source) {
+  for (const [letter, email] of source) {
+    if (!target.has(letter)) target.set(letter, email);
+  }
+}
+
+function driveFsBaseDir() {
+  const localAppData = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+  return path.join(localAppData, 'Google', 'DriveFS');
+}
+
+function getDriveEmailsFromPreferenceCache() {
+  const emails = new Map();
+  const baseDir = driveFsBaseDir();
+  const googleDriveNameRe = new RegExp(
+    `(?:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})?` +
+    `(${EMAIL_RE_SOURCE}) - Google(?: Drive|\\.\\.\\.).{0,16}?([A-Z]):\\\\`,
+    'gi'
+  );
+
+  for (const name of ['root_preference_sqlite.db', 'root_preference_sqlite.db-wal']) {
+    try {
+      const text = fs.readFileSync(path.join(baseDir, name)).toString('latin1');
+      for (const match of text.matchAll(googleDriveNameRe)) {
+        setEmailByDriveLetter(emails, match[2], match[1]);
+      }
+    } catch {}
+  }
+
+  return emails;
+}
+
+function getDriveEmailsFromRecentLogs() {
+  const emails = new Map();
+  const logDir = path.join(driveFsBaseDir(), 'Logs');
+  let files = [];
+  try {
+    files = fs.readdirSync(logDir)
+      .filter(name => /^drive_fs(?:_\d+)?\.txt$/i.test(name))
+      .map(name => {
+        const filePath = path.join(logDir, name);
+        return { filePath, mtimeMs: fs.statSync(filePath).mtimeMs };
+      })
+      .sort((a, b) => a.mtimeMs - b.mtimeMs)
+      .slice(-8);
+  } catch {
+    return emails;
+  }
+
+  const logMountRe = new RegExp(
+    `name:\\s*(${EMAIL_RE_SOURCE}) - Google(?: Drive|\\.\\.\\.).*?mount_point(?:\\(raw\\))?:\\s*"?([A-Z]):\\\\`,
+    'gi'
+  );
+
+  for (const { filePath } of files) {
+    try {
+      const buf = fs.readFileSync(filePath);
+      const tail = buf.length > 2 * 1024 * 1024 ? buf.subarray(buf.length - 2 * 1024 * 1024) : buf;
+      const text = tail.toString('utf-8');
+      for (const match of text.matchAll(logMountRe)) {
+        setEmailByDriveLetter(emails, match[2], match[1]);
+      }
+    } catch {}
+  }
+
+  return emails;
+}
+
+async function getWindowsMountLetters() {
+  const letters = new Set();
+
+  try {
+    const { stdout } = await execFileAsync(
+      'reg.exe',
+      ['query', 'HKCU\\Software\\Google\\DriveFS', '/v', 'PerAccountPreferences'],
+      { windowsHide: true, timeout: 3000 }
+    );
+    const match = stdout.match(/REG_\w+\s+(.+)/);
+    if (match) {
+      const prefs = JSON.parse(match[1].trim());
+      for (const acct of prefs.per_account_preferences || []) {
+        const letter = normalizeDriveLetter(acct.value && acct.value.mount_point_path);
+        if (letter) letters.add(letter);
+      }
+    }
+  } catch {}
+
+  // Probed in PARALLEL, each with a deadline: a wedged letter costs 2 s once
+  // instead of blocking the main thread for ever.
+  const probedLetters = await Promise.all([...'GHIJKLMNOPQRSTUVWXYZ'].map(
+    async letter => (await exists(`${letter}:\\My Drive`) ? letter : null)
+  ));
+  for (const letter of probedLetters) {
+    if (letter) letters.add(letter);
+  }
+
+  return letters;
+}
+
+async function getPsDriveInfo() {
+  const letters = new Set();
+  const emails = new Map();
+
+  try {
+    const { stdout } = await execFileAsync(
+      'powershell.exe',
+      [
+        '-NoProfile',
+        '-Command',
+        'Get-PSDrive -PSProvider FileSystem | ForEach-Object { "$($_.Name)|$($_.Description)" }',
+      ],
+      { windowsHide: true, timeout: 5000 }
+    );
+    for (const line of stdout.split(/\r?\n/)) {
+      const [name, desc] = line.split('|');
+      const letter = normalizeDriveLetter(name);
+      if (!letter) continue;
+      letters.add(letter);
+
+      const emailMatch = String(desc || '').match(new RegExp(`(${EMAIL_RE_SOURCE})`, 'i'));
+      if (emailMatch) setEmailByDriveLetter(emails, name, emailMatch[1]);
+    }
+  } catch {}
+
+  return { letters, emails };
+}
+
+async function getMacAccounts(accounts, seen) {
+  const cloudBase = path.join(os.homedir(), 'Library', 'CloudStorage');
+  try {
+    for (const entry of await readdirBounded(cloudBase)) {
+      if (entry === 'GoogleDrive') {
+        const myDrive = path.join(cloudBase, entry, 'My Drive');
+        if (await exists(myDrive)) addAccount(accounts, seen, 'google', 'Google Drive', myDrive);
+      } else if (entry.startsWith('GoogleDrive-')) {
+        const myDrive = path.join(cloudBase, entry, 'My Drive');
+        if (await exists(myDrive)) {
+          addAccount(accounts, seen, 'google', entry.replace('GoogleDrive-', '').replace(/_/g, '.'), myDrive);
+        }
+      } else if (entry === 'OneDrive' || entry.startsWith('OneDrive-')) {
+        const label = entry === 'OneDrive' ? 'OneDrive' : entry.replace('OneDrive-', 'OneDrive - ').replace(/_/g, '.');
+        addAccount(accounts, seen, 'onedrive', label, path.join(cloudBase, entry));
+      }
+    }
+  } catch {}
+
+  const iCloud = path.join(os.homedir(), 'Library', 'Mobile Documents', 'com~apple~CloudDocs');
+  if (await exists(iCloud)) addAccount(accounts, seen, 'icloud', 'iCloud Drive', iCloud);
+}
+
+async function addWindowsOneDriveAccounts(accounts, seen) {
+  const envCandidates = [
+    ['OneDrive Business', process.env.OneDriveCommercial],
+    ['OneDrive Personal', process.env.OneDriveConsumer],
+    ['OneDrive', process.env.OneDrive],
+  ];
+  for (const [name, dir] of envCandidates) {
+    if (dir && await exists(dir)) addAccount(accounts, seen, 'onedrive', name, dir);
+  }
+
+  try {
+    const oneDriveRoot = path.join(os.homedir(), 'OneDrive');
+    if (await exists(oneDriveRoot)) addAccount(accounts, seen, 'onedrive', 'OneDrive', oneDriveRoot);
+  } catch {}
+}
+
+async function addWindowsICloudAccounts(accounts, seen) {
+  for (const dir of [
+    path.join(os.homedir(), 'iCloudDrive'),
+    path.join(os.homedir(), 'iCloud Drive'),
+  ]) {
+    if (await exists(dir)) addAccount(accounts, seen, 'icloud', 'iCloud Drive', dir);
+  }
+}
+
+async function getWindowsAccounts(accounts, seen) {
+  const letters = await getWindowsMountLetters();
+  const psDrive = await getPsDriveInfo();
+  const emailByLetter = psDrive.emails;
+
+  mergeMissingDriveEmails(emailByLetter, getDriveEmailsFromPreferenceCache());
+  mergeMissingDriveEmails(emailByLetter, getDriveEmailsFromRecentLogs());
+
+  for (const letter of emailByLetter.keys()) {
+    if (psDrive.letters.has(letter)) letters.add(letter);
+  }
+
+  for (const letter of [...letters].sort()) {
+    const myDrive = `${letter}:\\My Drive`;
+    addAccount(accounts, seen, 'google', emailByLetter.get(letter) || `Google Drive (${letter}:)`, myDrive);
+  }
+
+  await addWindowsOneDriveAccounts(accounts, seen);
+  await addWindowsICloudAccounts(accounts, seen);
+}
+
+async function getCloudAccounts() {
+  const accounts = [];
+  const seen = new Set();
+
+  if (process.platform === 'darwin') {
+    await getMacAccounts(accounts, seen);
+  } else if (process.platform === 'win32') {
+    await getWindowsAccounts(accounts, seen);
+  }
+
+  return accounts;
+}
+
+module.exports = getCloudAccounts;

package/lib/conflict-model.js

@@ -0,0 +1,186 @@
+'use strict';
+
+const crypto = require('crypto');
+
+const CONFLICT_TOMBSTONE_MAX_AGE_MS = 30 * 86400 * 1000;
+
+function timestamp(value) {
+  const n = Number(value) || 0;
+  return Number.isFinite(n) ? n : 0;
+}
+
+function cleanTitle(value) {
+  return String(value == null ? '' : value).replace(/\s+/g, ' ').trim().slice(0, 240);
+}
+
+function cleanText(value) {
+  return String(value == null ? '' : value);
+}
+
+function uniqueId(parts) {
+  return crypto.createHash('sha256').update(parts.map(part => String(part == null ? '' : part)).join('\0'), 'utf8').digest('hex').slice(0, 24);
+}
+
+function normalizeSnapshot(snapshot) {
+  const raw = snapshot && typeof snapshot === 'object' ? snapshot : {};
+  const groups = Array.isArray(raw.groups)
+    ? [...new Set(raw.groups.map(group => String(group || '').trim()).filter(Boolean))]
+    : [];
+  return {
+    id: String(raw.id || ''),
+    type: raw.type === 'image' ? 'image' : 'text',
+    title: cleanTitle(raw.title),
+    text: cleanText(raw.text),
+    groups,
+    ts: timestamp(raw.ts),
+    updatedAt: timestamp(raw.updatedAt),
+    titleUpdatedAt: timestamp(raw.titleUpdatedAt),
+  };
+}
+
+function defaultResult(record) {
+  const right = normalizeSnapshot(record && record.right);
+  const left = normalizeSnapshot(record && record.left);
+  return {
+    title: right.title || left.title,
+    text: right.text || left.text,
+  };
+}
+
+function normalizeConflictRecord(record, now = Date.now()) {
+  if (!record || typeof record !== 'object') return null;
+  const kind = ['editor', 'title', 'merge'].includes(record.kind) ? record.kind : 'merge';
+  const createdAt = timestamp(record.createdAt) || timestamp(record.updatedAt) || now;
+  const updatedAt = timestamp(record.updatedAt) || createdAt;
+  const left = normalizeSnapshot(record.left);
+  const right = normalizeSnapshot(record.right);
+  const base = record.base ? normalizeSnapshot(record.base) : null;
+  const targetId = String(record.targetId || right.id || left.id || '');
+  const resultSource = record.result && typeof record.result === 'object' ? record.result : defaultResult({ left, right });
+  const id = String(record.id || `conf:${kind}:${uniqueId([targetId, left.id, left.title, left.text, right.id, right.title, right.text])}`);
+  return {
+    id,
+    kind,
+    status: record.status === 'resolved' ? 'resolved' : 'unresolved',
+    source: String(record.source || ''),
+    targetId,
+    createdAt,
+    updatedAt,
+    base,
+    left,
+    right,
+    result: {
+      title: cleanTitle(resultSource.title),
+      text: cleanText(resultSource.text),
+    },
+  };
+}
+
+function normalizeTombstones(list, now = Date.now()) {
+  const cutoff = now - CONFLICT_TOMBSTONE_MAX_AGE_MS;
+  const byId = new Map();
+  for (const tombstone of Array.isArray(list) ? list : []) {
+    if (!tombstone || !tombstone.id) continue;
+    const deletedAt = timestamp(tombstone.deletedAt);
+    if (deletedAt < cutoff) continue;
+    const existing = byId.get(tombstone.id);
+    if (!existing || deletedAt > existing.deletedAt) byId.set(tombstone.id, { id: String(tombstone.id), deletedAt });
+  }
+  return [...byId.values()];
+}
+
+function normalizeConflictState(state, now = Date.now()) {
+  const raw = state && typeof state === 'object' ? state : {};
+  const tombstones = normalizeTombstones(raw.tombstones, now);
+  const tombstoneById = new Map(tombstones.map(t => [t.id, t.deletedAt]));
+  const recordsById = new Map();
+  const records = Array.isArray(raw.records)
+    ? raw.records
+    : Array.isArray(raw.conflicts)
+      ? raw.conflicts
+      : [];
+  for (const rawRecord of records) {
+    const record = normalizeConflictRecord(rawRecord, now);
+    if (!record) continue;
+    const deletedAt = tombstoneById.get(record.id) || 0;
+    if (deletedAt) continue;
+    const existing = recordsById.get(record.id);
+    if (!existing || record.updatedAt >= existing.updatedAt) recordsById.set(record.id, record);
+  }
+  return {
+    version: 1,
+    records: [...recordsById.values()].sort((a, b) => b.updatedAt - a.updatedAt),
+    tombstones,
+  };
+}
+
+function mergeConflictStates(local, remote, now = Date.now()) {
+  const left = normalizeConflictState(local, now);
+  const right = normalizeConflictState(remote, now);
+  return normalizeConflictState({
+    version: 1,
+    records: [...left.records, ...right.records],
+    tombstones: [...left.tombstones, ...right.tombstones],
+  }, now);
+}
+
+function createConflictRecord(input, options = {}) {
+  const now = timestamp(options.now) || Date.now();
+  return normalizeConflictRecord({
+    ...(input || {}),
+    source: options.source || (input && input.source) || '',
+    createdAt: timestamp(input && input.createdAt) || now,
+    updatedAt: timestamp(input && input.updatedAt) || now,
+    status: 'unresolved',
+  }, now);
+}
+
+function upsertConflictRecord(state, record, now = Date.now()) {
+  if (!record) return normalizeConflictState(state, now);
+  const normalized = normalizeConflictState(state, now);
+  return normalizeConflictState({
+    ...normalized,
+    records: [...normalized.records, record],
+  }, now);
+}
+
+function removeConflictRecord(state, id, now = Date.now()) {
+  const normalized = normalizeConflictState(state, now);
+  const key = String(id || '');
+  if (!key) return normalized;
+  return normalizeConflictState({
+    version: 1,
+    records: normalized.records.filter(record => record.id !== key),
+    tombstones: [...normalized.tombstones, { id: key, deletedAt: now }],
+  }, now);
+}
+
+// What resolving a conflict writes back to the clip (main's
+// applyConflictResolution): accept_left / accept_right = that side verbatim
+// (its snapshot carries the title and groups); save and keep_both = the text
+// the view sends (keep_both's is the union of both sides, so it saves like
+// save); remove, or anything else, writes nothing and only drops the record.
+// Returns { snapshot, text, title } or null.
+function conflictResolutionWrite(record, payload) {
+  const p = payload && typeof payload === 'object' ? payload : {};
+  const action = p.action || 'save';
+  if (action === 'accept_left' || action === 'accept_right') {
+    const snapshot = record && (action === 'accept_left' ? record.left : record.right);
+    return snapshot ? { snapshot, text: String(snapshot.text || ''), title: snapshot.title } : null;
+  }
+  if (action === 'save' || action === 'keep_both') return { snapshot: null, text: String(p.text || ''), title: p.title };
+  return null;
+}
+
+module.exports = {
+  conflictResolutionWrite,
+  CONFLICT_TOMBSTONE_MAX_AGE_MS,
+  normalizeSnapshot,
+  normalizeConflictRecord,
+  normalizeTombstones,
+  normalizeConflictState,
+  mergeConflictStates,
+  createConflictRecord,
+  upsertConflictRecord,
+  removeConflictRecord,
+};

package/lib/control-client.js

@@ -0,0 +1,87 @@
+'use strict';
+
+// Local control channel - HELPER side (used by mcp/boardclip-mcp.js).
+//
+// Connects to the running app's named pipe / Unix socket, signs one request with
+// the shared secret from the discovery file, and awaits the single-line JSON
+// response. If the app is not running (no pipe), callers get a clean
+// `app_not_running` error so MCP tools can tell the user to open BoardClip.
+//
+// `timeoutMs` is the longest SILENCE tolerated, not a hard deadline: the app
+// pulses `{pending: true}` while it is still working (an approval prompt is
+// open and the user is reading it), and every pulse re-arms the timer. Pass
+// `keepalive: false` to get the old hard deadline.
+
+const net = require('net');
+const hmacAuth = require('./hmac-auth');
+const mcpPaths = require('./mcp-paths');
+
+const DEFAULT_TIMEOUT_MS = 60_000;
+
+class AppNotRunningError extends Error {
+  constructor(message = 'app_not_running') {
+    super(message);
+    this.code = 'app_not_running';
+  }
+}
+
+// Send a single request and resolve with the `result` field, or reject.
+function request(method, reqPath, payload, { discovery, timeoutMs = DEFAULT_TIMEOUT_MS, keepalive = true } = {}) {
+  const disco = discovery || mcpPaths.readDiscovery();
+  if (!disco || !disco.pipePath || !disco.secret) {
+    return Promise.reject(new AppNotRunningError());
+  }
+  const body = JSON.stringify(payload || {});
+  const ts = Date.now();
+  const sig = hmacAuth.sign(disco.secret, method, reqPath, ts, hmacAuth.bodyHash(Buffer.from(body)));
+  const wire = `${JSON.stringify({ id: ts, method, path: reqPath, ts, sig, body, keepalive: keepalive ? 1 : undefined })}\n`;
+
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let buffer = '';
+    let timer = null;
+    const conn = net.connect(disco.pipePath);
+    const done = (fn, arg) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try { conn.destroy(); } catch {}
+      fn(arg);
+    };
+    const arm = () => {
+      clearTimeout(timer);
+      timer = setTimeout(() => done(reject, new Error('control_timeout')), timeoutMs);
+    };
+    arm();
+
+    conn.setEncoding('utf8');
+    conn.on('connect', () => {
+      try { conn.write(wire); } catch (err) { done(reject, err); }
+    });
+    conn.on('data', chunk => {
+      buffer += chunk;
+      let index;
+      while ((index = buffer.indexOf('\n')) >= 0) {
+        const line = buffer.slice(0, index);
+        buffer = buffer.slice(index + 1);
+        let res;
+        try { res = JSON.parse(line); } catch { return done(reject, new Error('bad_response')); }
+        // Still working (e.g. the approval prompt is open): keep waiting.
+        if (res && res.pending) { arm(); continue; }
+        if (res && res.ok) return done(resolve, res.result);
+        const failure = new Error((res && res.error) || 'control_error');
+        if (res && typeof res.code === 'string') failure.code = res.code;
+        if (res && res.details && typeof res.details === 'object') failure.details = res.details;
+        return done(reject, failure);
+      }
+    });
+    conn.on('error', err => {
+      if (err && (err.code === 'ENOENT' || err.code === 'ECONNREFUSED')) {
+        return done(reject, new AppNotRunningError());
+      }
+      done(reject, err);
+    });
+  });
+}
+
+module.exports = { request, AppNotRunningError, DEFAULT_TIMEOUT_MS };

package/lib/control-server.js

@@ -0,0 +1,149 @@
+'use strict';
+
+// Local control channel - APP side.
+//
+// A named pipe (Windows) / Unix domain socket (macOS/Linux) server, NOT an HTTP
+// server: no TCP port, no firewall prompt. The standalone MCP helper connects
+// here for the few actions that need the live app (approval modal, clipboard
+// write, race-free mutation). Every request is HMAC-authed with the shared
+// secret from the discovery file (defence-in-depth on top of the OS user-scoping
+// of the pipe).
+//
+// Pure transport + auth + framing. The actual action dispatch is injected as
+// `handleRequest(method, payload, { signal })` by main.js, so all mutation logic
+// stays in the app and is never duplicated here.
+//
+// Two liveness rules protect a request that waits on the user (approval modal):
+// - `signal` aborts when the caller's socket closes (it timed out or died), so
+//   the app can drop the prompt instead of running the action for nobody.
+// - A caller that sent `keepalive` in its envelope gets `{id, pending: true}`
+//   every keepaliveMs while the request runs; its inactivity timeout then waits
+//   for as long as the user deliberates. Older helpers that never set the flag
+//   see exactly one line, the response, as before.
+
+const net = require('net');
+const fs = require('fs');
+const hmacAuth = require('./hmac-auth');
+
+const MAX_LINE_BYTES = 4 * 1024 * 1024;
+
+class ControlServer {
+  constructor({ pipePath, secret, handleRequest, onError, windowMs, keepaliveMs }) {
+    this.pipePath = pipePath;
+    this.secret = secret;
+    this.handleRequest = handleRequest;
+    this.onError = onError || (() => {});
+    this.windowMs = windowMs || hmacAuth.DEFAULT_WINDOW_MS;
+    this.keepaliveMs = keepaliveMs || 10_000;
+    this.server = null;
+  }
+
+  start() {
+    return new Promise((resolve, reject) => {
+      // Clean up a stale unix socket from a previous run (Windows pipes don't
+      // leave a filesystem artifact, so this is a no-op there).
+      if (process.platform !== 'win32') {
+        try { fs.rmSync(this.pipePath, { force: true }); } catch {}
+      }
+      this.server = net.createServer(conn => this._onConnection(conn));
+      this.server.on('error', err => {
+        this.onError(err);
+        reject(err);
+      });
+      this.server.listen(this.pipePath, () => resolve(this.pipePath));
+    });
+  }
+
+  stop() {
+    return new Promise(resolve => {
+      if (!this.server) return resolve();
+      const server = this.server;
+      this.server = null;
+      try {
+        server.close(() => {
+          if (process.platform !== 'win32') {
+            try { fs.rmSync(this.pipePath, { force: true }); } catch {}
+          }
+          resolve();
+        });
+      } catch {
+        resolve();
+      }
+    });
+  }
+
+  _onConnection(conn) {
+    conn.setEncoding('utf8');
+    let buffer = '';
+    conn.on('error', () => {});
+    conn.on('data', chunk => {
+      buffer += chunk;
+      if (buffer.length > MAX_LINE_BYTES) {
+        this._respond(conn, null, { ok: false, error: 'request_too_large' });
+        conn.destroy();
+        return;
+      }
+      let index;
+      while ((index = buffer.indexOf('\n')) >= 0) {
+        const line = buffer.slice(0, index);
+        buffer = buffer.slice(index + 1);
+        if (line.trim()) this._handleLine(conn, line);
+      }
+    });
+  }
+
+  async _handleLine(conn, line) {
+    let req;
+    try {
+      req = JSON.parse(line);
+    } catch {
+      return this._respond(conn, null, { ok: false, error: 'bad_json' });
+    }
+    const { id, method, path: reqPath, ts, sig, body } = req || {};
+    const bodyStr = typeof body === 'string' ? body : '';
+    const authed = hmacAuth.verify(this.secret, {
+      method,
+      path: reqPath,
+      timestamp: ts,
+      signature: sig,
+      bodyHashHex: hmacAuth.bodyHash(Buffer.from(bodyStr)),
+      windowMs: this.windowMs,
+    });
+    if (!authed) {
+      return this._respond(conn, id, { ok: false, error: 'unauthorized' });
+    }
+    let payload = {};
+    try { payload = bodyStr ? JSON.parse(bodyStr) : {}; } catch { payload = {}; }
+    const ac = new AbortController();
+    const onClose = () => ac.abort();
+    conn.once('close', onClose);
+    let pulse = null;
+    if (req.keepalive) {
+      pulse = setInterval(() => {
+        if (ac.signal.aborted || conn.destroyed) return;
+        this._respond(conn, id, { pending: true });
+      }, this.keepaliveMs);
+    }
+    try {
+      const result = await this.handleRequest(reqPath || method, payload, { signal: ac.signal });
+      this._respond(conn, id, { ok: true, result });
+    } catch (err) {
+      const failure = { ok: false, error: (err && err.message) || 'error' };
+      // Structured errors (e.g. a RevisionConflict) keep their code + details.
+      if (err && typeof err.code === 'string') failure.code = err.code;
+      if (err && err.details && typeof err.details === 'object') failure.details = err.details;
+      this._respond(conn, id, failure);
+    } finally {
+      if (pulse) clearInterval(pulse);
+      conn.removeListener('close', onClose);
+    }
+  }
+
+  _respond(conn, id, payload) {
+    try {
+      conn.write(`${JSON.stringify({ id, ...payload })}\n`);
+    } catch {}
+  }
+}
+
+module.exports = { ControlServer };