Channel Extension

Rules that are not negotiable

Credentials — §B9. Encrypted at rest in Channel.credentials_encrypted, one JSON object for all of a channel's secrets. Write-only: an empty string clears the field, a value starting with • or * is an echoed mask and is ignored, anything else is stored. Clearing the last required secret switches the channel off. Storing requires the installation's encryption key (409 encryption_key_missing without it). Never log a credential, never return one, never put one in a URL. Every write is audited.

The customer's own application. Tel-Agent holds no shared platform app. Every credential comes from the customer's own developer account. If a platform only works through an application the vendor owns, it cannot be a Tel-Agent channel.

The door — for every channel that receives webhooks.

1. The address is a long random path (secrets.token_urlsafe(24)), unique per channel, stored in Channel.webhook_path. The route is /public/{kind}/{webhook_path}.
2. Verify the platform's signature over the raw body bytes, before parsing anything, with hmac.compare_digest. A JWT is verified against the issuer's published keys with cryptography, checking iss, aud, exp. No signature scheme, no channel.
3. One refusal for every reason. Unknown path, wrong signature, disabled channel, malformed body — all of them return the same 403 not_recognised. The door leaks nothing about what exists behind it.
4. Acknowledge first, answer after. Return the platform's expected 200 immediately; generate and deliver the reply in a scheduled task. Platforms retry slow webhooks and you will answer twice.
5. Dedup by the platform's own message id before storing. Retries are normal.
6. Signal, Matrix, Mattermost, IRC, iMessage and every other dial-out channel expose nothing. Prefer dial-out whenever the platform offers it; the LAN installation is the product's reason to exist.

Answering policy. A direct message is always answered. A group, room, channel or space message is answered only when the bot is addressed, and the mention is stripped before the text reaches the model. A message from the bot itself, or from another bot, is never answered.

Delivery before storage. respond() generates the whole reply, delivers it, and only then writes the agent line. If delivery raises, nothing is written — a transcript must never show an answer the customer did not receive. Human takeover is checked before generating and again before sending.

Reconnection. Dial-out loops reconnect with exponential backoff from 5 s to 300 s and report their state through api/channels/health.py so the health page can say "connected" or "reconnecting" truthfully.

Text limits. Every platform has one. Split on word boundaries at the platform's limit; never truncate silently.

Nothing new in pyproject.toml. If you believe a platform genuinely cannot be done without an SDK, stop and say so in the report instead of adding it.

The test file

tests/test_<kind>_channel.py, modelled on tests/test_discord_channel.py. A fake platform, not mocked functions:

class FakeLine:
    def __init__(self) -> None:
        self.sent: list[dict] = []
        self.refuse = False

    def handler(self, request: httpx.Request) -> httpx.Response: ...  # route by path
    def client(self) -> httpx.AsyncClient:
        return httpx.AsyncClient(
            base_url="https://line.test", transport=httpx.MockTransport(self.handler)
        )

The stage fixture builds a workspace, a channel row with credentials, three users at admin / reception / viewer, monkeypatches make_client, and starts the real app. Copy it.

Every channel's file has at least these, named for what they prove:

• a direct message is answered, and a message from a bot never is
• a group message is answered only when addressed, and the mention is stripped
• a repeated event is dropped by the platform's own id
• a taken-over thread gets no generated reply
• a refused send leaves no agent line in the record
• the secret goes in and only a mask comes out
• removing the secret switches the channel off with it
• a viewer reads and never writes
• the test button reports the platform's identity, and reports refusal
• door channels: a wrong signature, an unknown path and a disabled channel all get the same refusal; the platform's verification handshake succeeds
• dial-out channels: the loop starts a connection for an active channel and stops it when the channel is disabled

Run the suite for your file and the shared ones, then the gate:

pytest tests/test_<kind>_channel.py tests/test_channel_health.py tests/test_extensions.py -q
ruff check . && ruff format --check . && mypy .
npm --prefix web run lint && npx --prefix web tsc --noEmit

Before the commit

• No secret, no real phone number, no product other than the platform itself named.
• English only. Conventional commit: feat(channels): add <kind>.
• The card renders with no credentials saved, with a secret saved (mask shown), and after a test — check all three in the browser before calling it done.