0033. Telegram acts as the person through their delegation; the Mini App signs in with Telegram's signature
Status: accepted, 2026-10-21
Context
The owner decided on a Telegram control surface (a binding per person; deploy, rollback, restart, logs,
incident updates and flags behind a two-step confirmation and approvals) and a Telegram Mini App that is the
hub inside Telegram. The approvals design gave each person a linked Telegram identity and a delegation
confirmed with a passkey (ADR 0026), held by notify's bot. The Mini App runs in Telegram's web views: a frame
on Telegram's site in the web client, views shared by several accounts on one phone, no WebAuthn, no
third-party cookies. And Telegram keeps every chat on its servers.
Decision
- Every press acts as the presser, in private chats and groups alike: their linked identity, their own
delegation and their role, for reads too. From medium risk a press asks again (Confirm or Cancel, 90 seconds,
the same account), and the approvals policy for
telegram applies on top. Nothing critical is offered in
Telegram.
- One delegation for the Telegram surface. The bot and the Mini App act within the same delegation: the
Mini App's sessions take its ceiling and its end, and revoking it,
/lock or unlinking the account ends
both within minutes. There is no second delegation and no other standing credential.
- The Mini App signs in with Telegram's signed init data, verified by id with Telegram's published
Ed25519 key against the bot id notify registered, at most five minutes old and used once. It needs the
linked identity and an active delegation even to read. Nothing derived from the bot token authenticates
people, so a leaked bot token can't forge a sign-in.
- Mini App sessions are home's, without cookies and per launch: a bearer that works only at home, via
telegram, at most 12 hours and ended after an hour unused. Confirm-need approvals may be decided there
unless it was opened in a group; a passkey always means id's page in the system browser.
- Data stays off Telegram's servers by default. Notifications go there; log lines, build output, secrets,
values and error payloads open in the Mini App, which reads them from the instance. A person may let log
lines into their own private chat, never into a group.
Consequences
- id gains a token exchange for Telegram init data and refresh families bound to a delegation; home gains
sessions without cookies and the capabilities to make them and to decide confirm-need approvals for them.
- notify's bot registers its bot id at id, sets the chat menu button to the Mini App, and runs presses on a
worker pool through one action runner.
- A taken-over Telegram account reaches the bot and the Mini App within one ceiling; passkeys for high and
critical actions, the 90-day limit,
/lock and the warnings sent when an account is linked bound it.
- Extends ADR 0026 (a delegation also bounds another first-party service's sessions on the same surface) and
ADR 0006 (a sign-in path for the Mini App).
- Design:
superpowers/specs/2026-10-21-phone-hub-design.md in this repository.