docs/bot_verification.md

Rama main · réplica de lectura del repositorio original.

# Third-party bot verification

Third-party verification is an **attributed** mark: a bot that the operator
appointed as a *verifier* attaches its own custom-emoji icon and one line of
description to a peer. Official clients draw that icon **before** the peer's name
and show the description in the profile, together with the name of the company the
verifier vouches under.

Reference material:

- <https://core.telegram.org/api/bots/verification>
- <https://telegram.org/verify#third-party-verification>

Applications are collected by the built-in `@verifierbot`, decided in the admin
panel, and the decision commits together with the mark write. The protocol edge then
drops the cached peer projections and pushes the ordinary peer-refresh update, so an
online client shows the icon without a restart.

## What this is not

This is **not** the platform checkmark. That one is a single boolean on the peer
(`users.verified` / `channels.verified`), granted by the operator after platform
review, collected by `@verifybot`, and documented in [`verification.md`](verification.md).

The two mechanisms are deliberately disjoint:

| | Official verification | Third-party verification |
| --- | --- | --- |
| Stored as | `users.verified`, `channels.verified` (boolean) | `bot_verifier_settings`, `custom_verifications` (attributed rows) |
| Granted by | the platform operator | a verifier bot the operator appointed |
| Rendered as | the standard checkmark **after** the name | the verifier's custom emoji **before** the name, plus a profile description |
| Front door | `@verifybot` | `@verifierbot` (or `bots.setCustomVerification` directly) |
| Panel section | *Official verification* (`/verification`) | *Third-party verification* (`/bot-verification`) |
| Permissions | `verification.review`, `verification.revoke` | `botverification.review`, `botverification.manage` |

Neither reads the other's tables. Both can sit on one peer at the same time, an
approval on one side never writes the other side's state, and revoking one leaves
the other alone. The admin panel repeats that distinction in the section header and
on every decision page, because "verified" in a ticket almost always means the other
one.

## TL constructors and flags (Layer 228)

Checked against the schema snapshot the server is built for,
`/tmp/td/_schema/layers/layer-228.tl`.

| Constructor / method | Field |
| --- | --- |
| `botVerification#f93cd45c` | `bot_id:long icon:long description:string` |
| `botVerifierSettings#b0cd6617` | `can_modify_custom_description:flags.1?true icon:long company:string custom_description:flags.0?string` |
| `bots.setCustomVerification#8b89dfbd` | `enabled:flags.1?true bot:flags.0?InputUser peer:InputPeer custom_description:flags.2?string = Bool` |
| `user#b1b8cc83` | `bot_verification_icon:flags2.14?long` |
| `channel#d49f34c6` | `bot_verification_icon:flags2.13?long` |
| `userFull#6cbe645` | `bot_verification:flags2.12?BotVerification` |
| `channelFull#a04e8d3a` | `bot_verification:flags2.17?BotVerification` |
| `chatInvite#5c9d3702` | `bot_verification:flags.13?BotVerification` |
| `botInfo#4d8a0299` | `verifier_settings:flags.9?BotVerifierSettings` |

One fact — "verifier *B* marked peer *P* with icon *I* and description *D*" — is
spread over six unrelated constructors, and a client renders the badge only when the
exact bit is set. Every projection therefore goes through the generated `Set*`
helpers (`internal/rpc/bot_verification_projection.go`): a struct field assigned
without its flag bit encodes as an absent field, and the badge silently disappears.

Note the asymmetry inside `botVerifierSettings`: `custom_description:flags.0` is the
operator-configured *default* description, while
`can_modify_custom_description:flags.1` is the permission that lets the verifier
override it per peer. `botVerification.description` is the resolved text actually
shown on a marked peer.

## The icon is a custom emoji document

`botVerification.icon` and `botVerifierSettings.icon` are custom emoji **document
ids**. A client resolves them through `messages.getCustomEmojiDocuments` — exactly
the reader `files.Service.GetDocuments` answers from on this server.

Consequences that shape the whole feature:

- An id that names no fetchable document renders as **nothing at all**: the peer is
  marked in the database and the client draws an empty space. Nothing errors, nothing
  logs on the client, and the operator sees a granted mark that users cannot see.
- Therefore the icon is never a free-form number. `verification_icons` is a
  catalogue, `botverification.Service.UpsertIcon` resolves the document before
  writing the row and refuses anything that is not a custom emoji
  (`domain.Document.IsCustomEmoji`), and a grant may only reference a catalogue entry
  that is `active` and either shared or reserved for that bot
  (`VerificationIcon.UsableBy`).
- The mark denormalises the icon at grant time (`custom_verifications.icon_document_id`),
  so a verifier changing its own icon later does not silently re-brand the peers it
  already marked.

The panel exposes the same rule: the icon catalogue tab is where document ids are
registered and named, and the grant form only offers active catalogue entries.

## End-to-end path

1. **Icon catalogue.** An operator adds a custom emoji document to
   `verification_icons` (panel: *Third-party verification → Icon catalogue*, or
   `POST /api/actions/upsert-verification-icon`). Entries can be shared or reserved
   for one bot, and retiring an entry (`set-verification-icon-active`) stops new
   grants without touching marks that already carry it.
2. **Verifier status.** The operator grants a bot verifier status — an icon from the
   catalogue, a company name, an optional default description and
   `can_modify_custom_description` (panel: *Verifiers*, or
   `POST /api/actions/grant-bot-verifier`). The row in `bot_verifier_settings` *is*
   verifier status: it is the only authority `bots.setCustomVerification` consults,
   and it is projected as `botInfo.verifier_settings`. Nothing seeds it — not even
   migration `0155` for the built-in bot — because seeding verifier status would ship
   a badge printer with the schema.
3. **Two ways to reach a mark.**
   - **Direct RPC.** The verifier bot (or the user who owns it) calls
     `bots.setCustomVerification`. `internal/rpc/bots_longtail.go` resolves the two
     TL branches — `bot:flags.0` unset means "the caller is the bot", set means "a
     user acting through a bot it owns" — validates shape, and hands a
     `domain.SetCustomVerificationRequest` to the service. A missing or disabled
     verifier row answers `403 BOT_VERIFIER_FORBIDDEN`, and the error deliberately
     does not distinguish "never was a verifier" from "switched off".
   - **Application queue.** A peer owner talks to `@verifierbot`
     (`/verify`, `/status`, `/revoke`, `/cancel`, `/help`), picks one of their own
     bots, channels or their own account, states a reason and optionally a wanted
     description. The bot writes `custom_verification_requests` with status
     `pending`; a partial unique index keeps one pending row per
     (verifier, peer) pair. `@verifierbot` decides nothing — it says so in `/start`.
4. **Review.** The panel lists the queue, the verifier roster, the icon catalogue and
   every granted mark. BFF routes are `GET /api/botverification/{verifiers,icons,marks,requests,counts}`,
   `GET /api/botverification/requests/{id}` and
   `POST /api/botverification/requests/{id}/{approve,reject,revoke}`; the manage-only
   mutations are the `/api/actions/...` commands listed above plus
   `set-bot-verifier-enabled`, `revoke-bot-verifier` and
   `revoke-custom-verification`. Every mutation goes through the shared admin command
   journal (reason → dry run → confirm), so it lands in `admin_commands` /
   `admin_audit_logs`.
5. **Second gate at approval.** `botverification.Service.Approve` re-loads a fresh
   snapshot: the verifier must still exist and be enabled, the peer must still
   resolve, and the per-verifier quota is spent only when the approval would create a
   mark rather than update one. A queue that sat for days cannot launder a state the
   RPC path would refuse. `version` is an optimistic lock — a stale panel gets a
   `409` and the page reloads instead of overwriting a fresher decision.
6. **Decision transaction.** The status transition and the mark write commit
   together: `DecideCustomVerificationRequest` runs the grant (or the revoke)
   through a callback whose context carries the decision's own transaction. "Approved"
   and "the peer carries the mark" can never disagree. The description is resolved by
   `BotVerifierSettings.DescriptionFor` — the applicant's wording only when
   `can_modify_custom_description` is set, otherwise the operator default — which is
   the single place that rule lives, so the RPC edge, the bot dialog and the panel
   preview cannot drift.
7. **Protocol edge.** After the commit the service calls
   `rpc.Router.NotifyPeerBotVerification(ctx, domain.Peer)`
   (`internal/rpc/bot_verification_notify.go`), which:
   - drops the cached peer projections for the peer, and for a channel also the
     `channelFull` bot-info cache that carries `botInfo.verifier_settings`;
   - for a user or bot, reuses `NotifyUserModerationFlagsChanged` — the audience-wide,
     non-PTS `updateUser` fan-out the scam/fake flags use, filtered to online
     sessions, with the peer re-projected per recipient;
   - for a channel, reuses `NotifyChannelChanged` → `updateChannel` plus the refreshed
     `channel#d49f34c6` object to members (and a linked monoforum when there is one);
   - is a no-op on a nil receiver and reports an error rather than panicking. A push
     failure never invalidates the committed decision.
8. **Applicant notification.** `@verifierbot` messages the applicant with the
   outcome (`SendVerificationDecision`). `internal_note` is never rendered there
   under any status — only `decision_reason` reaches the applicant.
9. **What the client sees.** The icon appears before the name in the dialog list,
   search results, message headers and the profile, and the description appears in the
   profile. `bots.setCustomVerification` returns `BoolTrue` for every successful
   application, including an idempotent re-apply or revoke; official clients
   treat `BoolFalse` as failure.

## Where the mark surfaces

| Surface | Method | Field |
| --- | --- | --- |
| Dialog list, search, history, difference | `messages.getDialogs`, `contacts.search`, `contacts.resolveUsername`, `messages.getHistory`, `updates.getDifference`, … | `user.bot_verification_icon`, `channel.bot_verification_icon` |
| User profile | `users.getFullUser` | `userFull.bot_verification` |
| Channel / supergroup info | `channels.getFullChannel` | `channelFull.bot_verification` |
| Invite preview (non-member) | `messages.checkChatInvite` | `chatInvite.bot_verification` |
| Verifier bot's own profile | `users.getFullUser`, `channels.getFullChannel` bot list | `botInfo.verifier_settings` |
| Live updates | pushed `updates` envelopes | `updateUser` / `updateChannel` plus the peer object |

The icon overlay runs at the **response boundary**, not inside `tgUser`/`tgChannel`:
`applyPeerReadModels` (`internal/rpc/story_peer_projection.go`) is the single hook
every handler funnels through, so all ~40 call sites get the field with one batched
read per response instead of an N+1 per peer. The `userFull` / `channelFull` /
`chatInvite` variants are post-cache overlays for the same reason — a cached full
object is still stamped with the current mark. A nil service or any read error leaves
every flag unset, which is byte-identical to the pre-feature wire shape.

## Migrations

- **`0155_bot_verification`** creates the four tables:
  - `verification_icons` — the catalogue. `document_id` is unique and positive,
    `owner_bot_id = 0` means shared, `active` retires an entry without deleting it.
  - `bot_verifier_settings` — verifier status, keyed by `bot_id` with an optimistic
    `version`, `enabled` as the per-verifier kill switch, and the operator's
    `granted_by` / `grant_reason` for the audit trail.
  - `custom_verifications` — granted marks. `UNIQUE (peer_type, peer_id)`
    matches the single `BotVerification` value on the wire: a different verifier
    replaces the current mark rather than leaving hidden fallback rows. It also has
    `peer_type IN ('user','channel')`,
    `icon_document_id` denormalised from the verifier, `ON DELETE CASCADE` from the
    verifier row.
  - `custom_verification_requests` — the review queue. `status IN ('pending','approved','rejected','revoked')`,
    a partial unique index for one `pending` row per (verifier, peer), and check
    constraints that pair each stamp with its status
    (`(status = 'approved') = (approved_at IS NOT NULL)`) and refuse a rejection
    without a reason.
- **`0156_verifier_service_bot`** seeds `@verifierbot` (id `1250000013`, fixed
  `access_hash` double-written with `domain.VerifierBotAccessHash`), its `bots` row
  and command list, and its `peer_usernames` registry entry, so the handle is occupied
  from the moment the schema is current. `verified = false` on purpose: a third-party
  verifier wearing the platform checkmark would blur the exact distinction it has to
  explain to every applicant. The seed grants **no** verifier status — an operator
  does that by hand in the panel.

Neither migration adds read-model triggers: the marks are read live at the response
boundary rather than cached in a peer read model.

## Configuration

Third-party verification (`internal/config/config.go`, `.env.example`):

| Key | Default | Meaning |
| --- | --- | --- |
| `TELESRV_BOT_VERIFICATION_ENABLED` | `true` | Master switch. When off, every third-party mutation is refused (grants, revocations, applications, catalogue edits) while marks already granted keep rendering — blanking one verifier's badges is what its per-verifier kill switch is for. |
| `TELESRV_BOT_VERIFICATION_MAX_PER_VERIFIER` | `10000` | Peers one verifier may mark. `0` disables the service bound and leaves only the storage bound (`domain.MaxCustomVerificationsPerVerifier`), which is also the maximum this key accepts. |
| `TELESRV_BOT_VERIFICATION_REQUEST_RATE_LIMIT` | `5` | Applications one applicant may file per window, across all verifier bots. `0` disables the budget. Looser than the official `3` on purpose: a deployment can run several verifier companies, and filing with a second one is not a retry of the first. |
| `TELESRV_BOT_VERIFICATION_REQUEST_RATE_WINDOW` | `24h` | That window. A positive limit requires a positive window. |

Operator access:

| Key | Default | Meaning |
| --- | --- | --- |
| `TELESRV_ADMIN_UI_PERMISSIONS` | `*` | Permissions of an Admin UI session. Reading the section and deciding applications needs `botverification.review`; the verifier roster, the icon catalogue and stripping a granted mark need `botverification.manage`. |
| `TELESRV_ADMIN_SCOPED_TOKENS` | *(empty)* | `name:token:perm1,perm2` entries separated by `;`, for integrations that should get `botverification.review` and nothing else. |

The two rights are independent of the official ones: a reviewer may hold
`verification.review` without `botverification.review`, and vice versa. The panel
hides the nav entry, gates the route and hides the manage-only buttons accordingly;
every route is checked again server-side.

## Manual check

### Telegram Desktop

1. In the panel, open *Third-party verification → Icon catalogue* and add a custom
   emoji document id. The *Emoji* section lists the documents this deployment holds
   with their ids; pick one that a client can actually fetch.
2. Open *Verifiers*, grant `@verifierbot` verifier status with that icon, a company
   name (say `Acme Verification Ltd`), a default description
   (`Verified by Acme`) and `can_modify_custom_description` off for the first pass.
   Confirm the audit entry appeared.
3. Log in to the deployment with official Telegram Desktop and open `@verifierbot`.
   Its profile now carries a **"verified by" block** built from
   `botInfo.verifier_settings` — the company and the icon — while its name has **no**
   platform checkmark. That contrast is the point.
4. Send `/verify`, pick one of your channels from the inline picker, state a reason,
   confirm. `/status` lists the application as pending.
5. In the panel open the queue, open the application, read the *Description the mark
   would carry* preview (with `can_modify_custom_description` off it shows the
   verifier default, not what you asked for), and approve.
6. Within a moment `@verifierbot` messages you the decision.
7. Without restarting the client, check the icon on the approved channel:
   - **Profile** — the icon sits immediately **before** the title, and the
     description line ("Verified by Acme") appears in the profile body
     (`channelFull.bot_verification`).
   - **Dialog list** — the chat row shows the icon before the title.
   - **Message header** — open the chat; the header title carries the icon.
   - **Search** — type the `@username` in global search; the result row carries it.
   - **Invite preview** — from a second account that is **not** a member, open an
     invite link to that channel: the join box carries the icon
     (`chatInvite.bot_verification`).
8. If the peer also holds the platform checkmark, both are visible at once: the
   custom icon before the name, the checkmark after it.
9. In the panel, revoke from the application's danger zone (or *Granted marks →
   Remove mark*). The icon disappears from all of those surfaces on the next push or
   read, and the platform checkmark stays untouched.
10. To check the invisible-badge failure mode on purpose, retire the icon and grant
    a verifier a catalogue entry whose document was deleted: the peer is marked in
    the database and the client draws nothing. That is why the catalogue validates
    documents up front.

### Telegram Android

1. Log in with the official Android client, force-close it and reopen it after the
   grant so the profile cache is cold.
2. `@verifierbot` profile: the verifier block ("verified by *company*" with the
   icon) is rendered under the bot's info, and the bot's name has no checkmark.
3. Approve an application for a **user account** (your own) and open that account's
   profile from a second device: the icon is drawn before the name in the profile
   header and in the chat header, and the description is a line in the profile
   (`userFull.bot_verification`).
4. Chat list and global search rows carry the icon before the name
   (`user.bot_verification_icon`).
5. Custom emoji rendering follows the client's animated-emoji setting: with animated
   emoji disabled the icon shows as a static frame, and while the document is still
   being fetched the slot is briefly empty. Neither is a server-side problem.
6. Revoke from the panel and pull-to-refresh the profile: the icon is gone.

## Limitations

- **A verifier can mark a peer that never asked.** `bots.setCustomVerification`
  authorises the *caller* (the bot itself, or a user who owns it) and the *verifier
  status*, not the target's consent. Verifier status is the trust boundary; that is
  why granting it is an operator-only action, why it has a kill switch, and why
  `TELESRV_BOT_VERIFICATION_MAX_PER_VERIFIER` bounds it. A peer cannot refuse or
  remove a mark itself — only the verifier (`/revoke` in the bot dialog, or the RPC
  with `enabled` unset) or an operator can.
- **No per-application event history.** Unlike official verification, there is no
  `*_events` table: an application keeps only `decided_by`, `decision_reason`,
  `internal_note` and its stamps. The full trail lives in the shared
  `admin_commands` / `admin_audit_logs` journal, so the panel's decision page shows a
  decision, not a timeline.
- **A revocation clears `approved_at`.** `0155` pairs each stamp with its status, so
  leaving the approved state nulls the approval stamp. After a revoke, "when was this
  approved?" can only be answered from the audit journal.
- **Applicant notifications are best-effort.** They are sent directly by
  `@verifierbot` after the decision commits, not through a durable outbox like the
  official flow's `verification_notification_outbox`. A delivery failure is logged
  and swallowed (`notifyApplicant`); the decision itself stands, and nothing retries
  the message, so an applicant can end up with a decided application they were never
  told about.
- **Only users and channels can be marked.** `peer_type` is constrained to
  `user`/`channel`, matching the TL surface: legacy basic groups (`chat#…`) have no
  `bot_verification` field in Layer 228, so a non-migrated basic group can never
  show a mark.
- **Only bots can be verifiers, and system bots cannot** — except the built-in
  `@verifierbot`. `botInfo.verifier_settings` exists only on a bot, so a user account
  granted verifier status would carry a status no client can see; seeded service
  accounts are refused outright (`@verifybot` in particular, which owns the *other*
  mechanism).
- **One icon per verifier, one mark per peer.** A verifier cannot vary
  its icon per peer, there are no verification tiers, and no expiry: a mark lives
  until somebody removes it. Nothing re-validates a marked peer over time — losing
  its username or picking up a scam flag later does not clear the mark.
- **A new verifier replaces the current peer mark.** `user.bot_verification_icon`
  and `channel.bot_verification_icon` are single `long` fields, so the database
  stores one matching mark. Replacing it cannot leave an older hidden mark that
  unexpectedly reappears after a revoke or kill-switch change.
- **A retired icon keeps rendering on existing marks.** Retiring a catalogue entry
  only blocks new grants, because the mark copied the document id at grant time.
  Blanking an already-granted icon means revoking the marks (or the verifier).
- **An unresolvable document is an invisible badge.** The catalogue validates the
  document when the entry is written, not continuously. A document deleted afterwards
  leaves marks that render as nothing, and the server has no way to notice.
- **The live push only reaches online sessions**, and the user fan-out is bounded by
  the same capped moderation audience the scam/fake flags use. Everybody else
  converges on their next authoritative read, which is always correct: the icon is an
  overlay read live at the response boundary rather than a cached read-model column.
- **`updateUser` / `updateChannel` carry no `pts`.** They are not persisted as
  message-box events, so a session that was offline during the decision never replays
  the push; it picks the mark up as *state* on its next read, not as an *event*.
- **`channelFull`'s bot-info cache is per process.** `NotifyPeerBotVerification`
  drops it on the instance that handled the decision. On other instances a cached
  `channelFull.bot_info` can still carry a stale `verifier_settings` block (the
  company/icon *of the verifier bot*, not the peer's mark) until that entry expires.
  The peer's own `bot_verification` fields are overlaid post-cache and are not
  affected.
- **`TELESRV_BOT_VERIFICATION_ENABLED=false` is not a badge switch.** It refuses new
  mutations; the marks already granted keep being projected. Use the per-verifier kill
  switch, or revoke, to actually clear badges.