@floomhq/signaldash 0.1.0

package/lib/mcp.js

@@ -0,0 +1,332 @@
+import { createInterface } from "node:readline";
+import { SendRateGuard } from "./rate-guard.js";
+import { UnipileClient, UnipileWarningError } from "./unipile.js";
+
+const PROTOCOL_VERSION = "2024-11-05";
+const CHANNELS = {
+  li: { configKey: "linkedin", provider: "LINKEDIN" },
+  wa: { configKey: "whatsapp", provider: "WHATSAPP" },
+};
+
+function tool(channel, action) {
+  const prefix = channel === "li" ? "LinkedIn" : "WhatsApp";
+  const name =
+    action === "list"
+      ? `${channel}_list_chats`
+      : action === "read"
+        ? `${channel}_read_messages`
+        : `${channel}_send_message`;
+  if (action === "list") {
+    return {
+      name,
+      description: `List ${prefix} chats without fetching individual profiles.`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          limit: {
+            type: "integer",
+            minimum: 1,
+            maximum: 50,
+            default: 20,
+          },
+        },
+        additionalProperties: false,
+      },
+    };
+  }
+  if (action === "read") {
+    return {
+      name,
+      description: `Read recent messages from one account-scoped ${prefix} chat.`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          chat: { type: "string", minLength: 1 },
+          limit: {
+            type: "integer",
+            minimum: 1,
+            maximum: 50,
+            default: 20,
+          },
+        },
+        required: ["chat"],
+        additionalProperties: false,
+      },
+    };
+  }
+  return {
+    name,
+    description: `Send one ${prefix} message. Enforces thread re-read, duplicate detection, pacing, a daily account cap, and stop-on-warning.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        chat: { type: "string", minLength: 1 },
+        text: { type: "string", minLength: 1, maxLength: 5000 },
+      },
+      required: ["chat", "text"],
+      additionalProperties: false,
+    },
+  };
+}
+
+export const TOOLS = [
+  tool("li", "list"),
+  tool("li", "read"),
+  tool("li", "send"),
+  tool("wa", "list"),
+  tool("wa", "read"),
+  tool("wa", "send"),
+];
+
+function boundedInteger(value, fallback) {
+  if (value === undefined) {
+    return fallback;
+  }
+  if (!Number.isInteger(value) || value < 1 || value > 50) {
+    throw new Error("limit must be an integer from 1 to 50");
+  }
+  return value;
+}
+
+function requiredText(value, name, maximum = Infinity) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`${name} is required`);
+  }
+  const text = value.trim();
+  if (text.length > maximum) {
+    throw new Error(`${name} exceeds ${maximum} characters`);
+  }
+  return text;
+}
+
+function configuredChannel(config, shortName) {
+  const definition = CHANNELS[shortName];
+  const account = config.channels?.[definition.configKey];
+  if (!account?.accountId) {
+    throw new Error(
+      `${definition.configKey} is not connected; run signaldash connect ${definition.configKey}`,
+    );
+  }
+  return { ...definition, accountId: account.accountId };
+}
+
+function cleanChat(chat) {
+  return {
+    id: chat.id,
+    name: chat.name ?? null,
+    type: chat.type ?? null,
+    timestamp: chat.timestamp ?? null,
+    unread_count: chat.unread_count ?? 0,
+    archived: chat.archived ?? 0,
+    read_only: chat.read_only ?? 0,
+  };
+}
+
+function cleanMessage(message) {
+  return {
+    id: message.id ?? message.provider_id ?? null,
+    text: message.text ?? null,
+    timestamp: message.timestamp ?? null,
+    is_sender: Boolean(message.is_sender),
+    sender_id: message.sender_id ?? null,
+    attachments: (message.attachments || []).map((attachment) => ({
+      id: attachment.id ?? null,
+      file_name: attachment.file_name ?? null,
+      mimetype: attachment.mimetype ?? null,
+      file_size: attachment.file_size ?? null,
+      type: attachment.type ?? null,
+      unavailable: Boolean(attachment.unavailable),
+    })),
+  };
+}
+
+function itemList(payload) {
+  return Array.isArray(payload?.items)
+    ? payload.items
+    : Array.isArray(payload?.messages)
+      ? payload.messages
+      : [];
+}
+
+async function assertChat(client, channel, chatId) {
+  const chat = await client.getChat(chatId);
+  if (chat.account_id !== channel.accountId) {
+    throw new Error("chat does not belong to the configured account");
+  }
+  const accountType = String(chat.account_type || "").toUpperCase();
+  if (accountType && !accountType.includes(channel.provider)) {
+    throw new Error("chat provider does not match the requested channel");
+  }
+  return chat;
+}
+
+function parseToolName(name) {
+  const match = /^(li|wa)_(list_chats|read_messages|send_message)$/.exec(
+    String(name || ""),
+  );
+  if (!match) {
+    throw new Error(`unknown tool: ${name}`);
+  }
+  return { shortName: match[1], action: match[2] };
+}
+
+async function executeTool({ name, args, config, client, guard }) {
+  const { shortName, action } = parseToolName(name);
+  const channel = configuredChannel(config, shortName);
+
+  try {
+    if (action === "list_chats") {
+      const limit = boundedInteger(args.limit, 20);
+      const payload = await client.listChats(channel.accountId, limit);
+      return {
+        items: itemList(payload)
+          .filter((chat) => chat.account_id === channel.accountId)
+          .map(cleanChat),
+        cursor: payload.cursor ?? null,
+      };
+    }
+
+    const chatId = requiredText(args.chat, "chat", 500);
+    if (action === "read_messages") {
+      await assertChat(client, channel, chatId);
+      const limit = boundedInteger(args.limit, 20);
+      const payload = await client.listMessages(chatId, limit);
+      return {
+        chat: chatId,
+        items: itemList(payload).map(cleanMessage),
+        cursor: payload.cursor ?? null,
+      };
+    }
+
+    const text = requiredText(args.text, "text", 5000);
+    const sent = await guard.executeSend({
+      channel: channel.configKey,
+      accountId: channel.accountId,
+      action: async () => {
+        await assertChat(client, channel, chatId);
+        const recent = itemList(await client.listMessages(chatId, 20));
+        const duplicate = recent.find(
+          (message) =>
+            message.is_sender &&
+            typeof message.text === "string" &&
+            message.text.trim() === text,
+        );
+        if (duplicate) {
+          throw new Error(
+            `duplicate blocked: the same outbound text already exists in recent history (${duplicate.id || "message id unavailable"})`,
+          );
+        }
+        return client.sendMessage(chatId, text);
+      },
+    });
+    return {
+      sent: true,
+      chat: chatId,
+      message_id:
+        sent.result.message_id ??
+        sent.result.messageId ??
+        sent.result.id ??
+        null,
+      safety: sent.safety,
+    };
+  } catch (error) {
+    if (error instanceof UnipileWarningError) {
+      await guard.block(channel.accountId, error.message);
+    }
+    throw error;
+  }
+}
+
+function result(id, value) {
+  return { jsonrpc: "2.0", id, result: value };
+}
+
+function errorResult(id, code, message) {
+  return { jsonrpc: "2.0", id, error: { code, message } };
+}
+
+function toolResult(id, value, isError = false) {
+  return result(id, {
+    content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+    ...(isError ? { isError: true } : {}),
+  });
+}
+
+export async function runMcp({
+  workspace,
+  config,
+  secrets,
+  input = process.stdin,
+  output = process.stdout,
+  createClient,
+  guard,
+}) {
+  const client = createClient
+    ? createClient(secrets.unipileBase, secrets.unipileKey)
+    : new UnipileClient({
+        base: secrets.unipileBase,
+        key: secrets.unipileKey,
+      });
+  const sendGuard = guard || new SendRateGuard(workspace);
+  const lines = createInterface({ input, crlfDelay: Infinity });
+
+  for await (const line of lines) {
+    if (!line.trim()) {
+      continue;
+    }
+    let request;
+    try {
+      request = JSON.parse(line);
+    } catch {
+      output.write(`${JSON.stringify(errorResult(null, -32700, "parse error"))}\n`);
+      continue;
+    }
+    if (request.method === "notifications/initialized") {
+      continue;
+    }
+    if (request.method === "initialize") {
+      output.write(
+        `${JSON.stringify(
+          result(request.id, {
+            protocolVersion: PROTOCOL_VERSION,
+            capabilities: { tools: {} },
+            serverInfo: { name: "signaldash", version: "0.1.0" },
+          }),
+        )}\n`,
+      );
+      continue;
+    }
+    if (request.method === "tools/list") {
+      output.write(
+        `${JSON.stringify(result(request.id, { tools: TOOLS }))}\n`,
+      );
+      continue;
+    }
+    if (request.method === "tools/call") {
+      try {
+        const value = await executeTool({
+          name: request.params?.name,
+          args: request.params?.arguments || {},
+          config,
+          client,
+          guard: sendGuard,
+        });
+        output.write(`${JSON.stringify(toolResult(request.id, value))}\n`);
+      } catch (error) {
+        output.write(
+          `${JSON.stringify(
+            toolResult(request.id, { error: error.message }, true),
+          )}\n`,
+        );
+      }
+      continue;
+    }
+    if (request.id !== undefined) {
+      output.write(
+        `${JSON.stringify(
+          errorResult(request.id, -32601, `method not found: ${request.method}`),
+        )}\n`,
+      );
+    }
+  }
+}

package/lib/rate-guard.js

@@ -0,0 +1,219 @@
+import {
+  chmod,
+  mkdir,
+  open,
+  readFile,
+  rename,
+  stat,
+  unlink,
+  writeFile,
+} from "node:fs/promises";
+import path from "node:path";
+import { UnipileWarningError } from "./unipile.js";
+
+export const SEND_SAFETY = Object.freeze({
+  linkedin: {
+    dailyCap: 18,
+    firstDelayMs: [5_000, 15_000],
+    intervalMs: [45_000, 90_000],
+  },
+  whatsapp: {
+    dailyCap: 30,
+    firstDelayMs: [2_000, 6_000],
+    intervalMs: [15_000, 35_000],
+  },
+});
+
+const sleep = (milliseconds) =>
+  new Promise((resolve) => setTimeout(resolve, milliseconds));
+
+function utcDay(date) {
+  return date.toISOString().slice(0, 10);
+}
+
+function randomBetween([minimum, maximum], random) {
+  return Math.floor(minimum + random() * (maximum - minimum + 1));
+}
+
+export class SendRateGuard {
+  constructor(
+    workspace,
+    {
+      clock = () => new Date(),
+      random = Math.random,
+      wait = sleep,
+      safety = SEND_SAFETY,
+    } = {},
+  ) {
+    this.directory = path.join(workspace, "safety");
+    this.statePath = path.join(this.directory, "send-state.json");
+    this.lockPath = path.join(this.directory, "send-state.lock");
+    this.clock = clock;
+    this.random = random;
+    this.wait = wait;
+    this.safety = safety;
+  }
+
+  async initialize() {
+    await mkdir(this.directory, { recursive: true, mode: 0o700 });
+    await chmod(this.directory, 0o700);
+  }
+
+  async acquireLock() {
+    await this.initialize();
+    for (let attempt = 0; attempt < 100; attempt += 1) {
+      try {
+        return await open(this.lockPath, "wx", 0o600);
+      } catch (error) {
+        if (error.code !== "EEXIST") {
+          throw error;
+        }
+        try {
+          const details = await stat(this.lockPath);
+          if (Date.now() - details.mtimeMs > 600_000) {
+            await unlink(this.lockPath);
+            continue;
+          }
+        } catch (statError) {
+          if (statError.code !== "ENOENT") {
+            throw statError;
+          }
+        }
+        await this.wait(100);
+      }
+    }
+    throw new Error("SignalDash send guard is busy; retry later");
+  }
+
+  async releaseLock(handle) {
+    await handle.close();
+    try {
+      await unlink(this.lockPath);
+    } catch (error) {
+      if (error.code !== "ENOENT") {
+        throw error;
+      }
+    }
+  }
+
+  async readState() {
+    try {
+      return JSON.parse(await readFile(this.statePath, "utf8"));
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return { version: 1, days: {}, blocked: {} };
+      }
+      throw new Error(`cannot read send safety state: ${error.message}`);
+    }
+  }
+
+  async writeState(state) {
+    const days = Object.keys(state.days || {}).sort().slice(-14);
+    state.days = Object.fromEntries(days.map((day) => [day, state.days[day]]));
+    const temporary = `${this.statePath}.${process.pid}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(state, null, 2)}\n`, {
+      mode: 0o600,
+    });
+    await chmod(temporary, 0o600);
+    await rename(temporary, this.statePath);
+    await chmod(this.statePath, 0o600);
+  }
+
+  async block(accountId, reason) {
+    const handle = await this.acquireLock();
+    try {
+      const state = await this.readState();
+      state.blocked ||= {};
+      state.blocked[accountId] = {
+        at: this.clock().toISOString(),
+        reason: String(reason).slice(0, 500),
+      };
+      await this.writeState(state);
+    } finally {
+      await this.releaseLock(handle);
+    }
+  }
+
+  async executeSend({ channel, accountId, action }) {
+    const policy = this.safety[channel];
+    if (!policy) {
+      throw new Error(`unsupported send channel: ${channel}`);
+    }
+    const handle = await this.acquireLock();
+    try {
+      const state = await this.readState();
+      const blocked = state.blocked?.[accountId];
+      if (blocked) {
+        throw new Error(
+          `sending is disabled for this account after a provider warning at ${blocked.at}: ${blocked.reason}`,
+        );
+      }
+      const now = this.clock();
+      const day = utcDay(now);
+      state.days ||= {};
+      state.days[day] ||= {};
+      const accountKey = `${channel}:${accountId}`;
+      const usage = state.days[day][accountKey] || {
+        sent: 0,
+        lastSentAt: null,
+      };
+      if (usage.sent >= policy.dailyCap) {
+        throw new Error(
+          `${channel} daily send cap reached (${policy.dailyCap} per account, UTC day)`,
+        );
+      }
+
+      const delay = usage.lastSentAt
+        ? Math.max(
+            0,
+            new Date(usage.lastSentAt).getTime() +
+              randomBetween(policy.intervalMs, this.random) -
+              now.getTime(),
+          )
+        : randomBetween(policy.firstDelayMs, this.random);
+      const reservedAt = now.toISOString();
+      state.days[day][accountKey] = {
+        sent: usage.sent + 1,
+        lastSentAt: reservedAt,
+      };
+      await this.writeState(state);
+      if (delay > 0) {
+        await this.wait(delay);
+      }
+
+      let result;
+      try {
+        result = await action();
+      } catch (error) {
+        if (error instanceof UnipileWarningError) {
+          state.blocked ||= {};
+          state.blocked[accountId] = {
+            at: this.clock().toISOString(),
+            reason: error.message.slice(0, 500),
+          };
+          await this.writeState(state);
+        }
+        throw error;
+      }
+
+      const sentAt = this.clock().toISOString();
+      state.days[day][accountKey] = {
+        sent: usage.sent + 1,
+        lastSentAt: sentAt,
+      };
+      await this.writeState(state);
+      return {
+        result,
+        safety: {
+          channel,
+          dailyCap: policy.dailyCap,
+          sentToday: usage.sent + 1,
+          remainingToday: policy.dailyCap - usage.sent - 1,
+          sentAt,
+        },
+      };
+    } finally {
+      await this.releaseLock(handle);
+    }
+  }
+}

package/lib/secrets.js

@@ -0,0 +1,96 @@
+import {
+  createCipheriv,
+  createDecipheriv,
+  randomBytes,
+} from "node:crypto";
+import {
+  chmod,
+  mkdir,
+  readFile,
+  rename,
+  writeFile,
+} from "node:fs/promises";
+import path from "node:path";
+
+const KEY_BYTES = 32;
+
+async function keyFor(workspace) {
+  const keyPath = path.join(workspace, "device.key");
+  try {
+    const key = await readFile(keyPath);
+    if (key.length !== KEY_BYTES) {
+      throw new Error(`invalid encryption key at ${keyPath}`);
+    }
+    return key;
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+    const key = randomBytes(KEY_BYTES);
+    await mkdir(workspace, { recursive: true, mode: 0o700 });
+    try {
+      await writeFile(keyPath, key, { mode: 0o600, flag: "wx" });
+    } catch (writeError) {
+      if (writeError.code === "EEXIST") {
+        return keyFor(workspace);
+      }
+      throw writeError;
+    }
+    await chmod(keyPath, 0o600);
+    return key;
+  }
+}
+
+export async function writeSecrets(workspace, value) {
+  const key = await keyFor(workspace);
+  const iv = randomBytes(12);
+  const cipher = createCipheriv("aes-256-gcm", key, iv);
+  const encrypted = Buffer.concat([
+    cipher.update(JSON.stringify(value), "utf8"),
+    cipher.final(),
+  ]);
+  const envelope = {
+    version: 1,
+    algorithm: "aes-256-gcm",
+    iv: iv.toString("base64"),
+    tag: cipher.getAuthTag().toString("base64"),
+    ciphertext: encrypted.toString("base64"),
+  };
+  const target = path.join(workspace, "secrets.enc");
+  const temporary = `${target}.${process.pid}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(envelope)}\n`, { mode: 0o600 });
+  await chmod(temporary, 0o600);
+  await rename(temporary, target);
+  await chmod(target, 0o600);
+}
+
+export async function readSecrets(workspace) {
+  const key = await keyFor(workspace);
+  const target = path.join(workspace, "secrets.enc");
+  let envelope;
+  try {
+    envelope = JSON.parse(await readFile(target, "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return {};
+    }
+    throw new Error(`cannot read encrypted credentials: ${error.message}`);
+  }
+  if (
+    envelope.version !== 1 ||
+    envelope.algorithm !== "aes-256-gcm"
+  ) {
+    throw new Error("unsupported credential envelope");
+  }
+  const decipher = createDecipheriv(
+    "aes-256-gcm",
+    key,
+    Buffer.from(envelope.iv, "base64"),
+  );
+  decipher.setAuthTag(Buffer.from(envelope.tag, "base64"));
+  const cleartext = Buffer.concat([
+    decipher.update(Buffer.from(envelope.ciphertext, "base64")),
+    decipher.final(),
+  ]);
+  return JSON.parse(cleartext.toString("utf8"));
+}