Draft: experiment with Twilio SMS/RCS channel backend

[bglusman]

Summary

Experimental channel work for Twilio SMS/RCS and current WhatsApp capability limits.

• Adds sms_provider = "twilio" alongside the existing Linq-backed kind = "sms" channel.
• Implements Twilio inbound webhook parsing with signature validation, allowed-number gating, button payload handling, and basic media markers.
• Implements Twilio outbound sends through the Programmable Messaging Message resource, with either MessagingServiceSid or From.
• Documents why the embedded WhatsApp Web backend remains text-fallback-only for native choice UI today, and distinguishes it from official WhatsApp Business/Cloud API or Baileys-style experiments.

Scope Notes

This is deliberately an experiment branch. It does not merge Matrix E2EE work, does not change the docs-public-copy branch, and does not claim full RCS native suggested-reply rendering yet.

Known follow-ups if we like this direction:

• Add outbound native RCS suggested reply/action rendering for Calciforge typed choices.
• Convert Twilio media URLs into authenticated artifact downloads instead of text markers.
• Decide whether a provider-backed WhatsApp Business/Cloud API adapter is worthwhile separately from the embedded WhatsApp Web transport.
• Consider whether Baileys is worth a JS sidecar experiment, with clear warnings that it is unofficial.

Validation

• cargo fmt --check
• cargo test -p calciforge twilio -- --nocapture
• cargo test -p calciforge channels::sms:: -- --nocapture
• cargo test -p calciforge test_channel_docs_sms_toml_blocks_valid -- --nocapture
• ruby scripts/check-docs-site.rb
• git diff --check
• Pre-push gate passed: fmt, clippy, workspace unit tests, e2e tests, doctests, and loom tests.

[Copilot]

Pull request overview

This PR experiments with adding a Twilio-backed provider option for Calciforge’s existing kind = "sms" channel, alongside the current Linq integration, including webhook ingestion, signature validation, outbound sends, and supporting documentation/config validation.

Changes:

• Adds sms_provider = "twilio" support to the SMS channel, including Twilio inbound form parsing + signature verification and outbound sends via Twilio’s Message resource.
• Extends config schema + validation (and tests) to cover Twilio credentials, sender configuration, and webhook public URL requirements.
• Updates channel documentation to describe provider differences (SMS + WhatsApp capability notes) and adds the sha1 dependency for Twilio HMAC verification.

Reviewed changes

Copilot reviewed 8 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
docs/index.md	Updates the channel list description to mention Twilio as an SMS/RCS webhook option.
docs/channels/whatsapp.md	Documents WhatsApp backend limitations vs official provider APIs and Baileys-style experiments.
docs/channels/sms.md	Adds provider-oriented docs and a Twilio configuration + webhook verification section.
crates/calciforge/src/main.rs	Updates startup log messaging for the SMS channel.
crates/calciforge/src/config/validator.rs	Validates sms_provider and required Twilio/Linq fields; adds focused tests.
crates/calciforge/src/config.rs	Extends ChannelConfig with Twilio-specific fields and adds a parsing test.
crates/calciforge/src/channels/sms.rs	Implements Twilio transport, webhook handler, signature verification, and outbound send logic.
crates/calciforge/Cargo.toml	Adds sha1 dependency for Twilio HMAC-SHA1 signature verification.
Cargo.lock	Locks the new sha1 dependency.

Comments suppressed due to low confidence (1)

crates/calciforge/src/channels/sms.rs:851

• read_secret_file hardcodes the prefix "Text/iMessage" in its error context. With the new Twilio backend, failures reading sms_twilio_* secrets will report as "Text/iMessage", which is misleading. Consider switching this prefix to something provider-neutral like "SMS"/"SMS channel" (or including the provider name) so Twilio configuration errors are clearer.

fn read_secret_file(path: &str, label: &str) -> Result<String> {
    Ok(std::fs::read_to_string(expand_tilde(path))
        .with_context(|| format!("Text/iMessage: failed to read {label} '{path}'"))?
        .trim()
        .to_string())