Forge Bots

Forge playbook — Chat / messaging bots (Discord · Slack · Telegram)

A bot is an inbound-webhook + auth + secrets domain — it lives at the intersection of forge-integration (OAuth, secret hygiene, webhook auth, reader-side capability-split for untrusted inbound content) and event-driven delivery. Lead the auth/secret backbone through forge-integration; this file adds the platform-specific verification, ack, and anti-spam rules. Each platform has a different verification mechanism — never assume one algorithm carries to another. Never claim a bot is "live"/"verified" unless a signed event was actually accepted and a forged one rejected.

Hard rules (non-negotiable)

• Verify every inbound event — per platform, on the raw body, before acting.
  • Discord (Interactions endpoint): verify the Ed25519 signature from X-Signature-Ed25519 + X-Signature-Timestamp against the raw body using your app's public key; reply to the PING (type 1) with PONG. Discord rejects an endpoint that fails this — verification is not optional.
  • Slack: verify X-Slack-Signature (HMAC-SHA256 over v0:{timestamp}:{raw_body}) with the signing secret, and reject requests whose timestamp is older than ~5 minutes (replay window). Answer the url_verification challenge.
  • Telegram: Telegram does not sign payloads — set a secret_token on setWebhook and verify the X-Telegram-Bot-Api-Secret-Token header on every update (and/or a hard-to-guess webhook path). Treat an unverified update as hostile.
• Fast ack, background work. Ack inside the platform deadline (Slack ~3s, Discord interactions ~3s — use a deferred response for longer work) and do heavy processing in a background/idempotent path. A slow handler drops events and gets your endpoint disabled.
• Idempotent handling — dedupe on the platform id. Redelivered events are normal. Dedupe on interaction.id (Discord) / event_id (Slack) / update_id (Telegram) with a uniqueness guarantee so a retry never double-acts.
• Minimal scopes / intents / permissions. Request only what the bot uses: Slack minimal bot-token scopes (no broad admin/user scopes); Discord minimal permission integer and no privileged intents (MESSAGE_CONTENT, GUILD_MEMBERS, PRESENCE) unless truly needed and owner-approved; Telegram narrow allowed_updates.
• Retries + dead-letter on the send side. Outbound API calls respect rate limits (honor 429 + Retry-After on Discord/Telegram; Slack tiered limits), retry with bounded backoff, and route permanent failures to a dead-letter store — never a silent drop (dropped deliveries look like clean success).
• Safe logging — no token/PII leak. Never log the bot token, signing/secret token, or user PII/message content beyond what the task needs. Redact secrets in errors. Secrets live in env + .env.example placeholders, never in code, logs, or git.
• Outreach drafted only. No unsolicited DMs, mass-mentions, or channel broadcasts without explicit owner approval — anti-spam is a platform ToS gate, not a nicety (shared with forge-integration / forge-scraping).

Team (conditional)

Lead: integration-boss (a bot is an external-system/webhook integration; use build-boss if the bot is one slice of a larger app). Support: security-boss (signature/secret verification, minimal scopes, token hygiene — this is a real security trigger), test-boss (drive signed vs forged/replayed events, rate-limit + dedupe behavior), silent-failure-hunter (dropped deliveries / swallowed 429s look like success), typescript-reviewer / python-reviewer by stack. mcp-developer only if the bot is exposed as or consumes MCP tools. Optional advisors: security-reviewer, codex-reviewer on the verification + auth code.

Skills / commands / MCP

Defer the OAuth/secret/webhook backbone + the reader-side capability-split to forge-integration. Get the exact signature algorithm and API/version behavior from the platform SDK / vendor docs via Context7 (discord.js / discord-interactions, Slack Bolt / @slack/*, Telegram Bot API / grammY / python-telegram-bot) — never hand-roll the crypto; reuse the platform's official verification helper. systematic-debugging for delivery/ack failures. If the bot runs through n8n, defer webhook handling to forge-n8n. Opt-in: any Discord/Slack/Telegram MCP tools via ToolSearch only when present — not assumed.

Fan-out & flow

L1/L2 for a single-platform bot with a few commands; L3 for multi-platform or many interactions + background jobs. Serial: register app + minimal scopes/intents → raw-body signature/secret verification → fast ack + dedupe → command routing → background processing + outbound retries → dead-letter. Parallel: independent command handlers ∥ per-platform adapters (independent once the verified-event contract is fixed — the verified, deduped event is the contract).

Domain gates

• Every inbound webhook/interaction verifies the platform's auth on the raw body (Discord Ed25519 + PONG; Slack HMAC v0 + ≤5-min replay window; Telegram secret-token header); unsigned/expired/forged events are rejected.
• Ack returned within the platform deadline (Slack/Discord ~3s, Discord defers long work); heavy logic runs in the background.
• Redelivered events deduped on interaction.id / event_id / update_id with a uniqueness guarantee.
• Outbound calls honor rate limits (429 + Retry-After), retry with bounded backoff, and dead-letter permanent failures — no silent drop.
• Scopes/intents/permissions minimal; no privileged Discord intents or broad Slack scopes without justification + approval.
• No token / signing secret / PII in logs; secrets in env.
• No unsolicited DM / broadcast / mass-mention; any outreach is drafted-only until owner approves.

Ship-readiness (unique)

Signature/secret verification proven both ways — a forged or replayed event is rejected and a genuine one accepted (attach the evidence); fast-ack + background offload demonstrated; dedupe proven against a redelivered id; rate-limit backoff + dead-letter present; scopes/intents listed and minimal; secrets in env with logs redacted; no auto-outreach. Advisory checklist; optionally run security-reviewer / codex-reviewer on the verification + auth path — recommended, not a blocker. If a platform sandbox/test app wasn't available to exercise real events, say so (not-run), don't imply it passed.

Untrusted-content note

Message text, command arguments, and any embedded links/attachments in an inbound event are untrusted user input — validate/sanitize before use and never let them change which actions the bot runs (Plan-Then-Execute + reader-side capability-split, per forge-integration). Verifying the webhook signature authenticates the platform, not the user content it carries.