Tg Canvas

This is a server skill. It includes a Node.js HTTP/WebSocket server (server.js), a CLI (bin/tg-canvas.js), and a Telegram Mini App frontend (miniapp/). It is not instruction-only.

Telegram Mini App Canvas renders agent-generated HTML or markdown inside a Telegram Mini App, with access limited to approved user IDs and authenticated via Telegram initData verification. It exposes a local push endpoint and a CLI command so agents can update the live canvas without manual UI steps.

Prerequisites

• Node.js 18+ (tested with Node 18/20/22)
• cloudflared for HTTPS tunnel (required by Telegram Mini Apps)
• Telegram bot token

Setup

1. Configure environment variables (see Configuration below) in your shell or a .env file.
2. Run the bot setup script to configure the menu button:

   BOT_TOKEN=... MINIAPP_URL=https://xxxx.trycloudflare.com node scripts/setup-bot.js
   

3. Start the server:

   node server.js
   

4. Start a Cloudflare tunnel to expose the Mini App over HTTPS:

   cloudflared tunnel --url http://localhost:3721
   

Pushing Content from the Agent

• CLI:

  tg-canvas push --html "<h1>Hello</h1>"
  tg-canvas push --markdown "# Hello"
  tg-canvas push --a2ui @./a2ui.json
  

• HTTP API:

  curl -X POST http://127.0.0.1:3721/push \
    -H 'Content-Type: application/json' \
    -d '{"html":"<h1>Hello</h1>"}'
  

Security

What the Cloudflare tunnel exposes publicly:

Loopback enforcement for /push, /clear, and /health is done at the TCP socket level (req.socket.remoteAddress), not via headers — so it cannot be spoofed via X-Forwarded-For or similar.

Recommendations:

• Set PUSH_TOKEN in your .env for defense-in-depth even though /push is already loopback-restricted.
• Use a strong random JWT_SECRET (32+ bytes).
• Keep BOT_TOKEN and JWT_SECRET secret; rotate if compromised.
• The Cloudflare tunnel exposes the Mini App publicly — the ALLOWED_USER_IDS check in /auth is the primary access control gate for the canvas.

Commands

• tg-canvas push — push HTML/markdown/text/A2UI
• tg-canvas clear — clear the canvas
• tg-canvas health — check server health

Configuration