Security

Least privilege

A token is scoped to one bot, and every chat_id is checked against that bot. Bots cannot read arbitrary rooms or act as their owner.

Webhook safety

Only HTTPS endpoints on public IP addresses are accepted. Redirects, loopback, link-local, and private ranges are blocked to prevent SSRF.

Validation

Verify signatures before parsing JSON, reject stale timestamps, cap body size, and persist processed event ids. Store credentials in a secret manager.

Group isolation

Never forward background group traffic to bots. User-scoped callback results must not disclose private data to the rest of the room.

SDK practice

Accept webhooks only over HTTPS, verify the signature before JSON parsing, and cap the body size at the reverse proxy.

Never place a bot token in a PWA or mobile client. All official SDKs target trusted server-side environments.

import { verifyWebhook } from '@keychat/bots';

// Keep rawBody unchanged: verifyWebhook checks timestamp, HMAC and freshness.
const event = verifyWebhook(rawBody, request.headers, process.env.KEYCHAT_WEBHOOK_SECRET!);