@floomhq/signaldash 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Floom
+
+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,120 @@
+# SignalDash
+
+Secure LinkedIn and WhatsApp access for AI agents.
+
+`@floomhq/signaldash` connects your own accounts through Unipile and exposes
+six account-scoped MCP tools. There is no email integration, CRM cockpit,
+signals engine, campaigns layer, sync database, or web UI in this package.
+
+## Connect
+
+SignalDash requires Node.js 20+ and a Unipile account. In the
+[Unipile dashboard](https://developer.unipile.com/docs/getting-started), copy
+your DSN and generate an Access Token. The API URL is your DSN followed by
+`/api/v1`.
+
+```bash
+export SIGNALDASH_UNIPILE_BASE="https://apiXXX.unipile.com:XXXXX/api/v1"
+export SIGNALDASH_UNIPILE_KEY="..."
+
+npx -y @floomhq/signaldash connect linkedin
+npx -y @floomhq/signaldash connect whatsapp
+```
+
+Each command creates a short-lived
+[Unipile hosted-auth](https://developer.unipile.com/docs/hosted-auth) URL.
+Open it to complete LinkedIn login or scan the live WhatsApp QR, then return
+to the terminal. SignalDash verifies the account through `GET /accounts` and
+stores its account ID.
+
+Without environment variables, run either command in a terminal. SignalDash
+prompts for the API URL and hides API-key input.
+
+Credentials live under `~/.signaldash` by default:
+
+- `device.key`: local 256-bit encryption key, mode `0600`
+- `secrets.enc`: AES-256-GCM credential envelope, mode `0600`
+- `config.json`: non-secret account references, mode `0600`
+
+The Unipile key is never written to config, printed, returned by an MCP tool,
+or passed to an MCP caller. Set `SIGNALDASH_HOME` to use another workspace.
+
+## MCP
+
+```bash
+npx -y @floomhq/signaldash mcp
+```
+
+The command starts a stdio MCP server. Its one-line registration hint is
+written to stderr so stdout remains valid JSON-RPC.
+
+Claude Code:
+
+```bash
+claude mcp add signaldash -- npx -y @floomhq/signaldash mcp
+```
+
+Cursor, `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "signaldash": {
+      "command": "npx",
+      "args": ["-y", "@floomhq/signaldash", "mcp"]
+    }
+  }
+}
+```
+
+The entire MCP surface is:
+
+- `li_list_chats`
+- `li_read_messages(chat)`
+- `li_send_message(chat, text)`
+- `wa_list_chats`
+- `wa_read_messages(chat)`
+- `wa_send_message(chat, text)`
+
+Every read and send verifies that the chat belongs to the configured account.
+List tools use chat-list endpoints only and never fetch profiles.
+
+## Safety is a feature
+
+The package includes
+[`skills/signaldash-safe-usage/SKILL.md`](skills/signaldash-safe-usage/SKILL.md).
+Install or give that skill to the agent using SignalDash.
+
+The runtime also enforces non-configurable safeguards:
+
+- LinkedIn: 18 send attempts per account per UTC day; 45 to 90 seconds
+  between sends.
+- WhatsApp: 30 send attempts per account per UTC day; 15 to 35 seconds
+  between sends.
+- The first send also receives randomized pre-send jitter.
+- Every send re-reads the recent thread and blocks an exact duplicate.
+- Provider warning headers, checkpoints, restrictions, HTTP 403, and HTTP 429
+  fail closed and persistently disable sends for that account.
+- A file lock serializes sends across concurrent MCP processes.
+
+LinkedIn invitation ceilings vary by account and often appear around 100 per
+week. SignalDash exposes no invitation tool. Keep invitation automation out
+of agent loops.
+
+Avoid bulk profile reads, copied message bursts, cold-account automation, and
+repeated retries after a checkpoint. Let the agent act slowly and human-like.
+On WhatsApp, use established accounts, keep the phone online, and avoid bulk
+or unsolicited messaging.
+
+After a provider warning, stop. Review the provider account manually and wait
+for it to return to good standing. The warning lock is recorded in
+`~/.signaldash/safety/send-state.json`; only a human may clear the relevant
+account entry after resolving the restriction.
+
+## Development
+
+```bash
+npm test
+npm run check
+npm pack --dry-run
+```

package/bin/sd.mjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// SignalDash thin client. Talks ONLY to the SignalDash backend (the gate) with a
+// bearer token. Never holds a Unipile key, never calls Unipile directly. The MCP
+// tools an agent uses all proxy through the backend, so agents access channels
+// THROUGH SignalDash, not around it.
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { createInterface } from "node:readline";
+
+const CFG_DIR = process.env.SIGNALDASH_HOME || `${homedir()}/.signaldash`;
+const CFG = `${CFG_DIR}/config.json`;
+const DEFAULT_BACKEND = process.env.SIGNALDASH_BACKEND || "https://signaldash-api.floom.dev";
+
+function loadCfg() { try { return JSON.parse(readFileSync(CFG, "utf8")); } catch { return {}; } }
+function saveCfg(c) { mkdirSync(CFG_DIR, { recursive: true }); writeFileSync(CFG, JSON.stringify(c, null, 2), { mode: 0o600 }); }
+
+async function api(path, body, { auth = true } = {}) {
+  const cfg = loadCfg();
+  const backend = cfg.backend || DEFAULT_BACKEND;
+  const r = await fetch(backend + path, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", ...(auth && cfg.token ? { Authorization: `Bearer ${cfg.token}` } : {}) },
+    body: JSON.stringify(body || {}),
+  });
+  return { status: r.status, json: await r.json().catch(() => ({})) };
+}
+
+async function cmdLogin(code, backend) {
+  const cfg = loadCfg();
+  cfg.backend = backend || cfg.backend || DEFAULT_BACKEND;
+  saveCfg(cfg);
+  const r = await api("/login", { code }, { auth: false });
+  if (r.status !== 200) { console.error("login failed:", r.json.error || r.status); process.exit(1); }
+  cfg.token = r.json.token; saveCfg(cfg);
+  console.log("Logged in to SignalDash. Token stored (no channel keys on your side).");
+}
+
+async function cmdConnect(provider) {
+  if (!["linkedin", "whatsapp"].includes(provider)) { console.error("usage: sd connect linkedin|whatsapp"); process.exit(1); }
+  const r = await api(`/connect/${provider}`, {});
+  if (r.status >= 300) { console.error("connect failed:", r.json.error || r.status); process.exit(1); }
+  console.log(`Open this to connect your ${provider}:\n\n  ${r.json.url}\n`);
+  console.log(`After authenticating, run:\n  sd connect ${provider} claim <account_id>`);
+}
+async function cmdClaim(provider, accountId) {
+  const r = await api(`/connect/${provider}/claim`, { account_id: accountId });
+  console.log(r.status === 200 ? `Connected ${provider}: ${r.json.name}` : `claim failed: ${r.json.error}`);
+}
+
+// ---- MCP (stdio). Every tool proxies through the backend with the token. ----
+const TOOLS = [
+  { name: "li_list_chats", ch: "li", action: "list_chats", description: "List your LinkedIn chats." },
+  { name: "li_read_messages", ch: "li", action: "read", description: "Read messages in a LinkedIn chat. args: chat_id" },
+  { name: "li_send_message", ch: "li", action: "send", description: "Send a LinkedIn message (rate-safe). args: chat_id, text" },
+  { name: "wa_list_chats", ch: "wa", action: "list_chats", description: "List your WhatsApp chats." },
+  { name: "wa_read_messages", ch: "wa", action: "read", description: "Read messages in a WhatsApp chat. args: chat_id" },
+  { name: "wa_send_message", ch: "wa", action: "send", description: "Send a WhatsApp message (rate-safe). args: chat_id, text" },
+];
+function mcpTool(name) {
+  return { name, description: TOOLS.find(t => t.name === name).description,
+    inputSchema: { type: "object", properties: { chat_id: { type: "string" }, text: { type: "string" }, limit: { type: "number" } } } };
+}
+async function runMcp() {
+  const rl = createInterface({ input: process.stdin });
+  const reply = (id, result, error) => process.stdout.write(JSON.stringify({ jsonrpc: "2.0", id, ...(error ? { error } : { result }) }) + "\n");
+  for await (const line of rl) {
+    let msg; try { msg = JSON.parse(line); } catch { continue; }
+    const { id, method, params } = msg;
+    if (method === "initialize") reply(id, { protocolVersion: "2024-11-05", capabilities: { tools: {} }, serverInfo: { name: "signaldash", version: "0.1.0" } });
+    else if (method === "tools/list") reply(id, { tools: TOOLS.map(t => mcpTool(t.name)) });
+    else if (method === "tools/call") {
+      const t = TOOLS.find(x => x.name === params.name);
+      if (!t) { reply(id, null, { code: -32601, message: "unknown tool" }); continue; }
+      const r = await api(`/${t.ch}/${t.action}`, params.arguments || {});
+      reply(id, { content: [{ type: "text", text: JSON.stringify(r.json) }], isError: r.status >= 300 });
+    } else if (id !== undefined) reply(id, {});
+  }
+}
+
+const [cmd, a, b, c] = process.argv.slice(2);
+if (cmd === "login") await cmdLogin(a, b === "--backend" ? c : undefined);
+else if (cmd === "connect" && b === "claim") await cmdClaim(a, c);
+else if (cmd === "connect") await cmdConnect(a);
+else if (cmd === "mcp") await runMcp();
+else console.log(`SignalDash — secure LinkedIn + WhatsApp access for your agent.\n\n  sd login <invite-code> [--backend URL]\n  sd connect linkedin|whatsapp\n  sd connect linkedin|whatsapp claim <account_id>\n  sd mcp\n\nThe agent reaches channels only through SignalDash. No keys on your machine.`);

package/bin/signaldash.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+import { main } from "../lib/cli.js";
+
+try {
+  await main(process.argv.slice(2));
+} catch (error) {
+  console.error(`SignalDash error: ${error.message}`);
+  process.exitCode = 1;
+}

package/lib/cli.js

@@ -0,0 +1,358 @@
+import { createInterface } from "node:readline/promises";
+import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { readSecrets, writeSecrets } from "./secrets.js";
+import { runMcp } from "./mcp.js";
+import { UnipileClient, accountIsReady } from "./unipile.js";
+
+const VERSION = "0.1.0";
+const CHANNELS = {
+  linkedin: { label: "LinkedIn", provider: "LINKEDIN" },
+  whatsapp: { label: "WhatsApp", provider: "WHATSAPP" },
+};
+
+function parseArgs(argv) {
+  const options = {};
+  const positional = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg.startsWith("--")) {
+      positional.push(arg);
+      continue;
+    }
+    const [key, inline] = arg.slice(2).split("=", 2);
+    if (inline !== undefined) {
+      options[key] = inline;
+    } else if (argv[index + 1] && !argv[index + 1].startsWith("--")) {
+      options[key] = argv[index + 1];
+      index += 1;
+    } else {
+      options[key] = true;
+    }
+  }
+  return { options, positional };
+}
+
+export function workspaceFor(options = {}) {
+  return path.resolve(
+    String(
+      options.workspace ||
+        process.env.SIGNALDASH_HOME ||
+        path.join(os.homedir(), ".signaldash"),
+    ),
+  );
+}
+
+async function ensureWorkspace(workspace) {
+  await mkdir(workspace, { recursive: true, mode: 0o700 });
+  await chmod(workspace, 0o700);
+}
+
+async function writeJsonPrivate(target, value) {
+  const temporary = `${target}.${process.pid}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, {
+    mode: 0o600,
+  });
+  await chmod(temporary, 0o600);
+  await rename(temporary, target);
+  await chmod(target, 0o600);
+}
+
+export async function readConfig(workspace, { optional = false } = {}) {
+  try {
+    return JSON.parse(
+      await readFile(path.join(workspace, "config.json"), "utf8"),
+    );
+  } catch (error) {
+    if (error.code === "ENOENT" && optional) {
+      return { version: 1, channels: {} };
+    }
+    if (error.code === "ENOENT") {
+      throw new Error(
+        "no connected accounts; run `signaldash connect linkedin` or `signaldash connect whatsapp`",
+      );
+    }
+    throw new Error(`cannot read SignalDash config: ${error.message}`);
+  }
+}
+
+function validateBase(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error("Unipile API URL must be an absolute HTTPS URL");
+  }
+  if (
+    url.protocol !== "https:" ||
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash ||
+    !url.hostname.endsWith(".unipile.com") ||
+    !url.pathname.replace(/\/+$/, "").endsWith("/api/v1")
+  ) {
+    throw new Error(
+      "Unipile API URL must be an https://*.unipile.com URL ending in /api/v1",
+    );
+  }
+  return url.toString().replace(/\/+$/, "");
+}
+
+function readHidden(prompt, stdin, stdout) {
+  if (!stdin.isTTY || !stdout.isTTY || typeof stdin.setRawMode !== "function") {
+    return Promise.resolve("");
+  }
+  return new Promise((resolve, reject) => {
+    let value = "";
+    const previousRaw = stdin.isRaw;
+    const finish = (error) => {
+      stdin.off("data", onData);
+      stdin.setRawMode(Boolean(previousRaw));
+      stdout.write("\n");
+      if (error) {
+        reject(error);
+      } else {
+        resolve(value);
+      }
+    };
+    const onData = (chunk) => {
+      for (const byte of chunk) {
+        if (byte === 3) {
+          finish(new Error("connection cancelled"));
+          return;
+        }
+        if (byte === 13 || byte === 10) {
+          finish();
+          return;
+        }
+        if (byte === 8 || byte === 127) {
+          value = value.slice(0, -1);
+        } else if (byte >= 32 && byte <= 126) {
+          value += String.fromCharCode(byte);
+        }
+      }
+    };
+    stdout.write(prompt);
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.on("data", onData);
+  });
+}
+
+async function credentials(workspace, options, io, environment) {
+  const stored = await readSecrets(workspace);
+  let base = String(
+    options.base ||
+      environment.SIGNALDASH_UNIPILE_BASE ||
+      stored.unipileBase ||
+      "",
+  ).trim();
+  let key = String(
+    environment.SIGNALDASH_UNIPILE_KEY || stored.unipileKey || "",
+  ).trim();
+  let prompt;
+  if ((!base || !key) && io.stdin.isTTY && io.stdout.isTTY) {
+    prompt = createInterface({ input: io.stdin, output: io.stdout });
+    if (!base) {
+      base = (
+        await prompt.question("Unipile API URL (ending in /api/v1): ")
+      ).trim();
+    }
+    if (!key) {
+      prompt.close();
+      prompt = undefined;
+      key = (await readHidden("Unipile API key (hidden): ", io.stdin, io.stdout)).trim();
+    }
+  }
+  prompt?.close();
+  if (!base || !key) {
+    throw new Error(
+      "set SIGNALDASH_UNIPILE_BASE and SIGNALDASH_UNIPILE_KEY, or run connect in a terminal",
+    );
+  }
+  return { base: validateBase(base), key };
+}
+
+function matchingAccounts(payload, provider) {
+  return (payload.items || []).filter(
+    (account) =>
+      String(account.type || "").toUpperCase() === provider &&
+      accountIsReady(account),
+  );
+}
+
+function selectAccount(accounts, requestedId) {
+  if (requestedId) {
+    const selected = accounts.find((account) => account.id === requestedId);
+    if (!selected) {
+      throw new Error(
+        `account ${requestedId} is not a connected account for this channel`,
+      );
+    }
+    return selected;
+  }
+  return accounts.length === 1 ? accounts[0] : null;
+}
+
+async function waitForHuman(label, io) {
+  if (!io.stdin.isTTY || !io.stdout.isTTY) {
+    return;
+  }
+  const prompt = createInterface({ input: io.stdin, output: io.stdout });
+  await prompt.question(
+    `Complete ${label} in the hosted page, then press Enter to verify: `,
+  );
+  prompt.close();
+}
+
+export async function connectCommand(channel, options, dependencies = {}) {
+  const definition = CHANNELS[channel];
+  if (!definition) {
+    throw new Error("channel must be linkedin or whatsapp");
+  }
+  const io = {
+    stdin: dependencies.stdin || process.stdin,
+    stdout: dependencies.stdout || process.stdout,
+  };
+  const workspace = workspaceFor(options);
+  await ensureWorkspace(workspace);
+  const secret = await credentials(
+    workspace,
+    options,
+    io,
+    dependencies.environment || process.env,
+  );
+  const createClient =
+    dependencies.createClient ||
+    ((base, key) => new UnipileClient({ base, key }));
+  const client = createClient(secret.base, secret.key);
+  const config = await readConfig(workspace, { optional: true });
+  const configuredId = config.channels?.[channel]?.accountId;
+
+  const before = await client.listAccounts();
+  const hostedUrl = await client.createHostedAuthLink(definition.provider);
+  io.stdout.write(`${definition.label} hosted auth: ${hostedUrl}\n`);
+
+  let available = matchingAccounts(before, definition.provider);
+  let selected = selectAccount(
+    available,
+    String(options["account-id"] || configuredId || "").trim(),
+  );
+  if (!selected && !options["no-wait"]) {
+    await waitForHuman(definition.label, io);
+    available = matchingAccounts(
+      await client.listAccounts(),
+      definition.provider,
+    );
+    selected = selectAccount(
+      available,
+      String(options["account-id"] || configuredId || "").trim(),
+    );
+  }
+
+  await writeSecrets(workspace, {
+    unipileBase: secret.base,
+    unipileKey: secret.key,
+  });
+
+  if (!selected) {
+    if (available.length > 1) {
+      const choices = available
+        .map((account) => `${account.id} (${account.name || definition.label})`)
+        .join(", ");
+      io.stdout.write(
+        `Multiple connected ${definition.label} accounts found: ${choices}\n`,
+      );
+      io.stdout.write(
+        `Re-run with --account-id <id> after completing hosted auth.\n`,
+      );
+    } else {
+      io.stdout.write(
+        `No connected ${definition.label} account detected yet. Complete hosted auth, then rerun this command.\n`,
+      );
+    }
+    return { connected: false, hostedUrl };
+  }
+
+  const nextConfig = {
+    version: 1,
+    channels: {
+      ...(config.channels || {}),
+      [channel]: {
+        accountId: selected.id,
+        name: selected.name || null,
+        connectedAt: new Date().toISOString(),
+      },
+    },
+  };
+  await writeJsonPrivate(path.join(workspace, "config.json"), nextConfig);
+  io.stdout.write(
+    `${definition.label} connected: ${selected.name || selected.id} (${selected.id})\n`,
+  );
+  io.stdout.write(`Credentials encrypted in ${workspace}\n`);
+  return { connected: true, account: selected, hostedUrl };
+}
+
+function registrationLine() {
+  return "Register: claude mcp add signaldash -- npx -y @floomhq/signaldash mcp | Cursor command: npx -y @floomhq/signaldash mcp";
+}
+
+export async function mcpCommand(options, dependencies = {}) {
+  const workspace = workspaceFor(options);
+  const config = await readConfig(workspace);
+  const secrets = await readSecrets(workspace);
+  if (!secrets.unipileBase || !secrets.unipileKey) {
+    throw new Error("encrypted Unipile credentials are missing; reconnect a channel");
+  }
+  const stderr = dependencies.stderr || process.stderr;
+  stderr.write(`${registrationLine()}\n`);
+  await runMcp({
+    workspace,
+    config,
+    secrets,
+    input: dependencies.stdin || process.stdin,
+    output: dependencies.stdout || process.stdout,
+    createClient: dependencies.createClient,
+    guard: dependencies.guard,
+  });
+}
+
+function help(output = process.stdout) {
+  output.write(`SignalDash ${VERSION}
+
+Secure LinkedIn + WhatsApp access for AI agents.
+
+Usage:
+  signaldash connect linkedin [--workspace PATH] [--account-id ID]
+  signaldash connect whatsapp [--workspace PATH] [--account-id ID]
+  signaldash mcp [--workspace PATH]
+
+Credentials:
+  Set SIGNALDASH_UNIPILE_BASE and SIGNALDASH_UNIPILE_KEY, or run connect
+  interactively. The API key is encrypted locally and never exposed over MCP.
+`);
+}
+
+export async function main(argv, dependencies = {}) {
+  const { options, positional } = parseArgs(argv);
+  const command = positional[0];
+  if (options.version || command === "version") {
+    (dependencies.stdout || process.stdout).write(`${VERSION}\n`);
+    return;
+  }
+  if (options.help || !command || command === "help") {
+    help(dependencies.stdout || process.stdout);
+    return;
+  }
+  if (command === "connect") {
+    await connectCommand(positional[1], options, dependencies);
+    return;
+  }
+  if (command === "mcp") {
+    await mcpCommand(options, dependencies);
+    return;
+  }
+  throw new Error(`unknown command: ${command}`);
+}