TG Canvas Mini App

核心用法

tg-canvas 是一个 Telegram Mini App 服务器，用于将 Agent 生成的 HTML 或 Markdown 内容实时渲染到 Telegram 客户端中。它包含 Node.js 服务端、CLI 工具和前端 Mini App 三大部分。

主要功能：

• 内容推送：通过 CLI (tg-canvas push) 或 HTTP API (POST /push) 实时更新画布内容，支持 HTML、Markdown 和 A2UI JSON 格式
• 安全认证：基于 Telegram initData HMAC-SHA256 验证，配合 ALLOWED_USER_IDS 白名单实现访问控制
• 会话管理：JWT 签名会话令牌，支持 WebSocket 实时推送
• 代理功能：可选 /oc/* 路径代理到本地 OpenClaw 控制 UI

部署流程：
1. 配置环境变量（BOT_TOKEN、ALLOWED_USER_IDS、JWT_SECRET、PUSH_TOKEN 等）
2. 运行 setup-bot.js 配置 Telegram Bot 菜单按钮
3. 启动 Node.js 服务器
4. 使用 cloudflared 建立 HTTPS 隧道（Telegram Mini Apps 强制要求 HTTPS）

显著优点

• 原生 Telegram 集成：直接嵌入 Telegram 生态，用户无需离开聊天应用即可查看 AI 生成内容
• 多层安全防护：Telegram 原生认证 + JWT 会话 + PUSH_TOKEN 推送保护，形成纵深防御
• 实时更新：WebSocket 支持，内容推送后用户端即时刷新
• 灵活的输入格式：支持原始 HTML、Markdown 和结构化的 A2UI JSON
• 细粒度访问控制：基于 Telegram User ID 的白名单机制

潜在缺点与局限性

• 依赖外部隧道：必须使用 cloudflared 等工具暴露 HTTPS，增加了运维复杂度
• 网络暴露风险：Cloudflare 隧道会将所有请求源 IP 显示为 127.0.0.1，完全绕过了基于 IP 的回环检查，必须依赖 PUSH_TOKEN 进行认证
• Node.js 运行时依赖：需要维护 Node.js 18+ 环境
• Telegram 生态绑定：仅限 Telegram 用户使用，无法跨平台部署
• 配置门槛较高：需要同时管理 Bot Token、JWT Secret、Push Token 等多个密钥

适合人群

• 需要通过 Telegram 向特定用户展示 AI 生成内容的开发者和 Agent 构建者
• 希望为现有 Telegram Bot 增加富媒体展示能力的团队
• 注重访问控制、需要白名单机制的内容分发场景
• 熟悉 Node.js 和 DevOps 流程的技术用户

常规风险

| 风险类型 | 说明 | 缓解措施 |

|---------|------|---------|

| **密钥泄露** | BOT_TOKEN、JWT_SECRET、PUSH_TOKEN 任一泄露都可能导致未授权访问 | 使用强随机值（32+字节），定期轮换，避免提交到版本控制 |

| **Cloudflared 绕过** | 隧道将所有请求伪装为本地来源，IP 白名单失效 | **必须设置 PUSH_TOKEN**，不能单独依赖 loopback 检查 |

| **XSS 注入** | 推送的 HTML 内容若包含恶意脚本，将在用户浏览器执行 | 建议对输入内容进行过滤，或使用 CSP 策略（需自行配置） |

| **会话劫持** | JWT 令牌被盗后攻击者可伪造会话 | 使用长随机 JWT_SECRET，考虑设置合理的 token 过期时间 |

| **依赖供应链** | cloudflared、Node.js 依赖存在潜在漏洞 | 定期更新依赖，监控 CVE |

> ⚠️ 关键提醒：开发者必须理解 cloudflared 的工作机制——它通过出站 TCP 连接到本地端口，导致所有请求看似来自 127.0.0.1。文档明确警告不要将 loopback-only 端点作为唯一防线，PUSH_TOKEN 是强制要求且服务器会拒绝在未设置时启动。

核心用法

tg-canvas 是一个专为 Telegram 生态设计的 Mini App Canvas 服务器，主要功能是将 AI 代理生成的 HTML 或 Markdown 内容安全地渲染在 Telegram WebView 中。该技能采用 Node.js 构建，包含 HTTP/WebSocket 服务器、CLI 工具以及 Telegram Mini App 前端三大部分。

部署流程清晰：配置环境变量后启动服务器，通过 Cloudflare 隧道暴露 HTTPS 端点，即可在 Telegram 内访问。内容推送支持两种方式——本地 CLI 命令 tg-canvas push 或直接调用 /push HTTP API，实现代理与展示层的无缝衔接。

核心工作流为：用户通过 Telegram Bot 打开 Mini App → 完成 initData 身份验证获取 JWT → WebSocket 实时接收代理推送的内容更新 → 前端安全渲染 HTML/Markdown。整个链路经过多层认证关卡，确保只有白名单用户可查看内容。

显著优点

安全架构扎实：采用 Telegram 官方 initData HMAC-SHA256 签名验证作为第一道闸门，结合 ALLOWED_USER_IDS 白名单机制；会话层使用短时效 JWT（默认15分钟），配合内存速率限制和 initData 重放缓存，形成纵深防御。

部署友好：内置 Cloudflare 隧道支持，无需复杂域名配置即可快速上线；提供完整的 CLI 工具链，支持一键推送、清空、健康检查等操作，降低运维门槛。

生态整合度高：原生支持 OpenClaw 网关代理，可将本地 Control UI 安全暴露至 Telegram 环境，服务器端注入令牌机制避免浏览器暴露敏感凭证，对 AI 代理开发者尤为实用。

代码质量可靠：722 行核心代码结构清晰，注释充分，依赖极简（仅 ws@8.x），无已知 CVE 漏洞，通过静态分析与动态行为审计。

潜在缺点与局限性

HTML 渲染存在脚本重新注入风险：为绕过 Telegram WebView 对 innerHTML 中 script 标签的限制，代码实现了脚本提取再执行机制。虽受 PUSH_TOKEN 保护，但一旦服务器被攻破，可能成为代码注入通道。

路径遍历防护不够严谨：静态文件服务依赖正则表达式过滤 ../ 序列，存在被复杂路径序列绕过的可能，建议采用 path.resolve 白名单验证替代。

外部依赖不可控：Mini App 需从 Telegram 官方 CDN 加载 WebApp SDK，若 CDN 遭篡改可能影响安全性；同时硬编码了特定用户环境的 OpenClaw 配置路径，跨平台部署需手动调整。

数据保留策略未明确：Canvas 内容、JWT 日志等用户数据的保留期限和自动清理机制未在文档中说明，长期运行可能产生隐私合规隐患。

适合的目标群体

• Telegram Bot 开发者：需要将 AI 生成内容以富媒体形式呈现给特定用户群体
• AI 代理构建者：使用 OpenClaw 或类似框架，寻求安全的可视化输出通道
• 小团队协作场景：需快速搭建受限访问的内容展示面板，无需复杂权限系统
• 原型验证阶段：追求快速上线、低运维成本的 Mini App 解决方案

不适合完全开放的公共内容平台，或需要企业级审计日志、复杂角色权限管理的场景。

使用风险

隧道安全依赖 PUSH_TOKEN：Cloudflare 等本地隧道工具通过 TCP 连接转发远程请求，导致所有流量表现为 127.0.0.1 来源，传统 IP 白名单失效。必须设置强随机 PUSH_TOKEN，否则 /push 端点面临未授权访问风险。

WebSocket 连接稳定性：实时内容更新依赖 WebSocket，网络波动或 Telegram 客户端后台限制可能导致连接中断，需在前端实现重连机制。

Node.js 版本兼容性：测试覆盖 Node 18/20/22，更低版本可能存在兼容性问题；长期需关注 ws 依赖的安全更新。

Cloudflare 隧道临时性：免费隧道 URL 会变化，生产环境建议配置固定域名与 nginx 反向代理，避免 URL 变更导致 Bot 菜单失效。