Eccos handles credentials for the Meta WhatsApp Cloud API and verifies signed webhooks, so we take security seriously.
For a deeper, code-grounded write-up of assets, trust boundaries, attack surfaces, and residual
risks, see docs/threat-model.md. For what personal data Eccos stores,
for how long, and how an operator can inspect/export/delete it, see
docs/privacy.md.
Please do not open a public issue for security vulnerabilities.
Report privately through GitHub's private vulnerability reporting: go to the repository's Security tab → Report a vulnerability.
Please include a description, reproduction steps, and the impact you foresee. We aim to acknowledge reports within a few days and will keep you updated on the fix.
Eccos is pre-1.0. Security fixes are applied to the latest main. Pin a commit if you need
stability and watch the repository for advisories.
- Inbound webhooks are authenticated by verifying Meta's
X-Hub-Signature-256(HMAC-SHA256 over the raw body with yourMETA_APP_SECRET) using a constant-time comparison. Requests with a missing or invalid signature are rejected with401. - API routes (
/v1/*) require an account API key — a Bearer token /x-api-keyresolved to a hashed account key in the control plane — and verify WABA ownership before touching a data-plane object. The Bun target (src/) keeps its singleECCOS_API_KEYfor its single tenant. - Forwarded events are signed with
X-Eccos-Signature: sha256=<hex>usingSUBSCRIBER_SECRETso your subscriber can verify they came from Eccos. - Secrets live only in
.env(Bun target, gitignored), aswrangler secretvalues, or in control-plane storage for tenant Meta tokens. On the Workers target tenant Meta tokens are application-encrypted before they are stored: AES-256-GCM, with a key derived from theECCOS_TOKEN_ENCRYPTION_KEYWorker secret and bound to the account and WABA (apps/gateway/src/token-crypto.ts), on top of Cloudflare's encryption at rest. They are never returned by operator APIs, committed to the repository, or written to logs. Account API keys are stored only as SHA-256 hashes and are returned once at issue.
- Message content (inbound reply/echo text, outbound request bodies), API tokens, and other
secrets are not written to logs, on either target. The Workers target's structured JSON
logging (
apps/gateway/src/worker.ts,logEvent()) is restricted at the type level to ids, counts, booleans, and enum-like strings (LogMeta) — never bodies, phone numbers, or secret values; the Bun target logs only a boot message and delivery-loop errors. Seedocs/privacy.mdfor the full breakdown.
- Always set a strong, random
META_WEBHOOK_VERIFY_TOKEN,ECCOS_ADMIN_API_KEYandECCOS_TOKEN_ENCRYPTION_KEY(Workers), andSUBSCRIBER_SECRET(ECCOS_API_KEYon the Bun target). - Serve Eccos over HTTPS (the Workers target gives you a stable HTTPS URL for free).
- On Workers, per-account Meta tokens are stored in the control plane — rotate a WABA's token by re-registering the WABA if one is suspected exposed.
- If you use the provided
Dockerfile, the included.dockerignorekeeps.envand local data out of the image — keep it that way.