PENDING: feat(hermes-agent): add secure Telegram identity, chat, topic, and access-policy management #673

Parent epic: #668
Depends on: #670, #672
Related but separate: #646

Context

Hermes Telegram gateway supports numeric user allowlists, group/chat allowlists, topics, mention controls, command access controls, polling/webhook modes, and multiple profiles. AWCMS-Mini must govern desired bindings and show verified/unknown state without taking ownership of the Telegram bot runtime or conflating conversational agents with social publishing.

Objective

Add tenant-aware Telegram identity/chat/topic bindings and a default-deny desired access policy for each Hermes agent profile.

Scope

Tables

• awcms_mini_hermes_telegram_bindings
• awcms_mini_hermes_telegram_principals

Represent:

• one unique bot/profile binding per agent;
• masked bot username/identifier metadata, never bot token;
• numeric Telegram user IDs linked optionally to an AWCMS tenant user/profile;
• numeric group/supergroup chat IDs;
• optional topic/thread IDs;
• DM vs group scope;
• admin vs regular command role;
• allowed command list;
• require-mention, exclusive-bot-mention, guest-mode, and ignored-topic desired policy;
• polling/webhook mode metadata;
• verification state: unverified, operator_attested, telemetry_verified, mismatch;
• last verification time and safe mismatch codes.

API/UI support

• CRUD and soft-delete/restore for bindings/principals.
• Generate masked Hermes configuration guidance with placeholders only.
• Never mark a binding verified merely because an admin saved it.
• Show unverified when the documented Hermes API cannot prove gateway/allowlist state.
• Maintain a unique bot token requirement per concurrently running profile in documentation.
• Keep all tables, permissions, and secrets separate from social-publishing Telegram adapter feat(social-publishing): add Telegram channel publishing adapter #646.

Security requirements

• Use immutable numeric Telegram IDs, not usernames, as authorization identifiers.
• Default deny: empty allowlist authorizes nobody.
• No wildcard * in production unless a separately authorized override with warning and audit is implemented.
• Bot token and webhook secret live only in Hermes environment/secret manager.
• Group membership alone must not imply AWCMS role/tenant membership.
• Linking/unlinking identity is high-risk, idempotent, permission-gated, and audited.
• Do not ingest group chatter or conversation contents into AWCMS.

Acceptance criteria

• Tenant admin can manage desired user/chat/topic bindings without seeing bot secrets.
• Numeric-ID validation and uniqueness rules are enforced.
• Cross-tenant identity linking fails under RLS/ABAC tests.
• Empty policy is default deny.
• Verification state is honest and cannot be self-asserted as live verification.
• Config preview contains no raw token/webhook secret.
• feat(social-publishing): add Telegram channel publishing adapter #646 resources are not reused.
• OpenAPI, security/readiness docs, operator SOP, and tests are updated.
• A changeset is added.
• bun run check passes.

Out of scope

• Running the Telegram gateway inside AWCMS-Mini.
• BotFather automation.
• Telegram social publishing.
• Storing Telegram conversations or attachments.