@mulmobridge/twilio-sms 0.1.0

package/README.md

@@ -0,0 +1,74 @@
+# @mulmobridge/twilio-sms
+
+> **Experimental** — please test and [report issues](https://github.com/receptron/mulmoclaude/issues/new).
+
+SMS bridge for [MulmoClaude](https://github.com/receptron/mulmoclaude) via [Twilio Programmable Messaging](https://www.twilio.com/messaging). Every phone on Earth can text your AI agent — no app install needed.
+
+**Public URL required** (Twilio posts a webhook every time an SMS arrives on your number).
+
+## Setup
+
+### 1. Get a Twilio number
+
+1. Sign up at [twilio.com](https://www.twilio.com/) (trial includes credits).
+2. **Phone Numbers → Buy a Number** → pick one with SMS capability.
+3. Note the **Account SID** + **Auth Token** (Twilio console top-right / Settings → General).
+
+### 2. Expose the bridge with a tunnel
+
+```bash
+ngrok http 3010
+# copy the https URL — e.g. https://abcd.ngrok-free.app
+```
+
+### 3. Configure the Twilio number
+
+In the Twilio console, open the number → **Messaging → A Message Comes In** → Webhook, method **HTTP POST** → URL `https://<your-tunnel>/sms`.
+
+### 4. Run the bridge
+
+```bash
+TWILIO_ACCOUNT_SID=AC... \
+TWILIO_AUTH_TOKEN=... \
+TWILIO_FROM_NUMBER=+15551234567 \
+TWILIO_PUBLIC_URL=https://abcd.ngrok-free.app \
+npx @mulmobridge/twilio-sms
+```
+
+Text the Twilio number — you'll get a reply.
+
+## Environment variables
+
+| Variable                 | Required    | Default | Description |
+|--------------------------|-------------|---------|-------------|
+| `TWILIO_ACCOUNT_SID`     | yes         | —       | Twilio Account SID |
+| `TWILIO_AUTH_TOKEN`      | yes         | —       | Twilio Auth Token (used for REST + signature verification) |
+| `TWILIO_FROM_NUMBER`     | yes         | —       | Your Twilio number in E.164, e.g. `+15551234567` |
+| `TWILIO_WEBHOOK_PORT`    | no          | `3010`  | HTTP port |
+| `TWILIO_PUBLIC_URL`      | yes (prod)  | —       | Full public URL the bridge is reachable at (e.g. `https://abcd.ngrok-free.app`, including any query string Twilio signs). Required to verify Twilio's `X-Twilio-Signature`. The bridge refuses to start without it unless `TWILIO_ALLOW_UNVERIFIED=1` is also set. |
+| `TWILIO_ALLOW_UNVERIFIED`| no          | —       | Set to `1` to skip signature verification (local testing only). Prints a loud warning and leaves `/sms` wide open. Do **not** set in production. |
+| `TWILIO_ALLOWED_NUMBERS` | no          | (all)   | CSV of sender E.164 numbers allowed (empty = accept every number) |
+| `MULMOCLAUDE_AUTH_TOKEN` | no          | auto    | MulmoClaude bearer token override |
+| `MULMOCLAUDE_API_URL`    | no          | `http://localhost:3001` | MulmoClaude server URL |
+
+## How it works
+
+1. Twilio posts form-encoded `From`, `To`, `Body`, `MessageSid` to `/sms` every time an SMS arrives.
+2. The bridge verifies `X-Twilio-Signature` (HMAC-SHA1 over the full URL — including query string — + sorted form params) using the auth token. `TWILIO_PUBLIC_URL` must match the URL Twilio sees (scheme + host + optional path prefix); the request's actual query string is read from `req.originalUrl`.
+3. We ACK `204` immediately so Twilio doesn't retry, then (asynchronously) forward the trimmed body to MulmoClaude keyed by the sender's number.
+4. The reply is sent back via `POST /2010-04-01/Accounts/{SID}/Messages.json` with Basic auth; long replies are chunked at 1 600 chars (Twilio's concatenated-SMS ceiling).
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| 401 at Twilio side | Signature verification failed | Verify `TWILIO_PUBLIC_URL` matches the URL Twilio actually hits (scheme + host + path, no trailing `/`) |
+| No reply delivered | `Messages.json` REST call failing | `docker logs` / `npx` output will show `[twilio-sms] send failed: …`. Common cause: trial account can only message verified numbers |
+| Duplicate replies | Twilio retried before ACK | Ensure reachable `https://` endpoint (not HTTP) and the bridge responds 2xx under 15 s |
+
+## Security notes
+
+- The auth token is equivalent to root credentials on your Twilio account. Rotate in the console if leaked.
+- `TWILIO_PUBLIC_URL` is strongly recommended — without it, anyone who finds your webhook can impersonate Twilio and converse with your agent.
+- Trial Twilio accounts can only SMS pre-verified numbers. Upgrade to production before real use.
+- SMS is plaintext — don't discuss secrets over it. Use Signal / WhatsApp / Matrix instead for sensitive content.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "dotenv/config";

package/dist/index.js

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+// @mulmobridge/twilio-sms — Twilio SMS bridge for MulmoClaude.
+//
+// Inbound: Twilio sends form-encoded POST to /sms when an SMS arrives
+// on your Twilio number. The bridge validates Twilio's HMAC-SHA1
+// X-Twilio-Signature, forwards the text to MulmoClaude, and replies
+// via the Twilio REST API. Outbound: Twilio REST API sends SMS.
+//
+// Required env vars:
+//   TWILIO_ACCOUNT_SID  — Account SID from the Twilio console
+//   TWILIO_AUTH_TOKEN   — Auth token (used for both REST auth and
+//                         X-Twilio-Signature verification)
+//   TWILIO_FROM_NUMBER  — Your Twilio number in E.164 form (+15551234567)
+//
+// Optional:
+//   TWILIO_WEBHOOK_PORT    — HTTP port (default 3010)
+//   TWILIO_PUBLIC_URL      — Full public URL of /sms, used for signature
+//                            verification. Required by default; the
+//                            bridge refuses to start without it unless
+//                            TWILIO_ALLOW_UNVERIFIED=1 is also set
+//                            (dev-only escape hatch).
+//   TWILIO_ALLOW_UNVERIFIED — When "1", skip signature verification.
+//                            Only for local testing — prints a loud
+//                            warning and leaves /sms wide open.
+//   TWILIO_ALLOWED_NUMBERS — CSV of sender numbers allowed (empty = all)
+import "dotenv/config";
+import crypto from "crypto";
+import express from "express";
+import { createBridgeClient, chunkText } from "@mulmobridge/client";
+const TRANSPORT_ID = "twilio-sms";
+const MAX_SMS_LEN = 1_600; // Twilio concatenates segments up to 1600 chars
+const FETCH_TIMEOUT_MS = 15_000;
+const PORT = Number(process.env.TWILIO_WEBHOOK_PORT) || 3010;
+const accountSid = process.env.TWILIO_ACCOUNT_SID;
+const authToken = process.env.TWILIO_AUTH_TOKEN;
+const fromNumber = process.env.TWILIO_FROM_NUMBER;
+if (!accountSid || !authToken || !fromNumber) {
+    console.error("TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, and TWILIO_FROM_NUMBER are required.\n" + "See README for setup instructions.");
+    process.exit(1);
+}
+const publicUrl = process.env.TWILIO_PUBLIC_URL?.replace(/\/$/, "");
+const allowUnverified = process.env.TWILIO_ALLOW_UNVERIFIED === "1";
+if (!publicUrl && !allowUnverified) {
+    console.error("TWILIO_PUBLIC_URL is required for X-Twilio-Signature verification.\n" +
+        "For local testing only, you can set TWILIO_ALLOW_UNVERIFIED=1 to skip\n" +
+        "verification — but never in production (open webhook).");
+    process.exit(1);
+}
+if (!publicUrl && allowUnverified) {
+    console.warn("[twilio-sms] ⚠ TWILIO_ALLOW_UNVERIFIED=1 — signature verification DISABLED. Use only in local testing.");
+}
+const allowedNumbers = new Set((process.env.TWILIO_ALLOWED_NUMBERS ?? "")
+    .split(",")
+    .map((num) => num.trim())
+    .filter(Boolean));
+const allowAll = allowedNumbers.size === 0;
+const mulmo = createBridgeClient({ transportId: TRANSPORT_ID });
+mulmo.onPush((pushEvent) => {
+    sendSms(pushEvent.chatId, pushEvent.message).catch((err) => console.error(`[twilio-sms] push send failed: ${err}`));
+});
+// ── Twilio signature validation ─────────────────────────────────
+function expectedSignature(url, params) {
+    // Twilio: sort params by key, concat key+value, prepend URL, sign with auth token.
+    const sortedKeys = Object.keys(params).sort();
+    const data = sortedKeys.reduce((acc, key) => acc + key + params[key], url);
+    const hmac = crypto.createHmac("sha1", authToken);
+    hmac.update(data);
+    return hmac.digest("base64");
+}
+function signatureValid(url, params, provided) {
+    const expected = expectedSignature(url, params);
+    if (expected.length !== provided.length)
+        return false;
+    try {
+        return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(provided));
+    }
+    catch {
+        return false;
+    }
+}
+// ── Twilio REST: send SMS ──────────────────────────────────────
+async function sendSms(toNumber, text) {
+    const auth = Buffer.from(`${accountSid}:${authToken}`).toString("base64");
+    const chunks = chunkText(text, MAX_SMS_LEN);
+    for (const chunk of chunks) {
+        const form = new URLSearchParams({ From: fromNumber, To: toNumber, Body: chunk });
+        let res;
+        try {
+            res = await fetch(`https://api.twilio.com/2010-04-01/Accounts/${accountSid}/Messages.json`, {
+                method: "POST",
+                headers: {
+                    Authorization: `Basic ${auth}`,
+                    "Content-Type": "application/x-www-form-urlencoded",
+                },
+                body: form.toString(),
+                signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+            });
+        }
+        catch (err) {
+            console.error(`[twilio-sms] network error: ${err}`);
+            continue;
+        }
+        if (!res.ok) {
+            const detail = await res.text().catch(() => "");
+            console.error(`[twilio-sms] send failed: ${res.status} ${detail.slice(0, 200)}`);
+        }
+    }
+}
+// ── HTTP server ────────────────────────────────────────────────
+const app = express();
+app.disable("x-powered-by");
+app.use(express.urlencoded({ extended: false }));
+app.get("/health", (__req, res) => {
+    res.json({ status: "ok", transport: TRANSPORT_ID });
+});
+function parseTwilioBody(body) {
+    if (!body || typeof body !== "object")
+        return null;
+    const record = body;
+    const from = typeof record.From === "string" ? record.From : "";
+    const toField = typeof record.To === "string" ? record.To : "";
+    const text = typeof record.Body === "string" ? record.Body : "";
+    const messageSid = typeof record.MessageSid === "string" ? record.MessageSid : "";
+    if (!from || !toField || !messageSid)
+        return null;
+    return { From: from, To: toField, Body: text, MessageSid: messageSid };
+}
+function stringifyParams(body) {
+    const out = {};
+    for (const [key, value] of Object.entries(body)) {
+        if (typeof value === "string")
+            out[key] = value;
+    }
+    return out;
+}
+app.post("/sms", async (req, res) => {
+    const parsed = parseTwilioBody(req.body);
+    if (!parsed) {
+        res.status(400).send("Bad Request");
+        return;
+    }
+    if (publicUrl) {
+        const sig = typeof req.headers["x-twilio-signature"] === "string" ? req.headers["x-twilio-signature"] : "";
+        const params = stringifyParams(req.body);
+        // Twilio signs the *full* URL it POSTed to — including query string.
+        // `req.originalUrl` keeps the querystring that Twilio saw, whereas
+        // `req.path` is just "/sms". Without this, any webhook URL with a
+        // query parameter (e.g. ?env=prod) would fail verification.
+        const fullUrl = `${publicUrl}${req.originalUrl}`;
+        if (!sig || !signatureValid(fullUrl, params, sig)) {
+            console.warn("[twilio-sms] AUTH_FAILED: X-Twilio-Signature mismatch");
+            res.status(401).send("Invalid signature");
+            return;
+        }
+    }
+    // ACK right away so Twilio doesn't retry; we'll send the reply asynchronously.
+    res.status(204).end();
+    if (!allowAll && !allowedNumbers.has(parsed.From)) {
+        console.log(`[twilio-sms] denied from=${parsed.From}`);
+        return;
+    }
+    const text = parsed.Body.trim();
+    if (!text)
+        return;
+    console.log(`[twilio-sms] message from=${parsed.From} len=${text.length}`);
+    try {
+        const ack = await mulmo.send(parsed.From, text);
+        if (ack.ok) {
+            await sendSms(parsed.From, ack.reply ?? "");
+        }
+        else {
+            const status = ack.status ? ` (${ack.status})` : "";
+            await sendSms(parsed.From, `Error${status}: ${ack.error ?? "unknown"}`);
+        }
+    }
+    catch (err) {
+        console.error(`[twilio-sms] message handling failed: ${err}`);
+    }
+});
+app.listen(PORT, () => {
+    console.log("MulmoClaude Twilio SMS bridge");
+    console.log(`Webhook listening on http://localhost:${PORT}/sms`);
+    console.log(`From number: ${fromNumber}`);
+    console.log(`Public URL: ${publicUrl ?? "(not set — signature verification OFF)"}`);
+    console.log(`Allowlist: ${allowAll ? "(all)" : [...allowedNumbers].join(", ")}`);
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@mulmobridge/twilio-sms",
+  "version": "0.1.0",
+  "description": "Twilio SMS bridge for MulmoBridge — inbound SMS via webhook, outbound via Twilio REST API",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "mulmobridge-twilio-sms": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepack": "yarn build",
+    "typecheck": "tsc --noEmit",
+    "test": "echo no tests yet"
+  },
+  "license": "MIT",
+  "author": "Receptron Team",
+  "dependencies": {
+    "@mulmobridge/client": "^0.1.0",
+    "@mulmobridge/protocol": "^0.1.0",
+    "dotenv": "^17.0.0",
+    "express": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/node": "^25.6.0",
+    "typescript": "^6.0.3"
+  }
+}