owpengram-server/docs/verification.md

# Official platform verification

Official verification is the platform badge shown next to the name of a bot,
public channel or public supergroup whose identity a human reviewer has
confirmed. In this server it is exactly one boolean on one peer record:
`users.verified` or `channels.verified`. Nothing else about the peer changes.

Applications are filed through the built-in `@verifybot`, decided in the admin
panel, and the decision commits together with the flag write. The protocol edge
then makes the new flag observable: it drops the cached peer projections and
pushes the ordinary peer-refresh update to online clients.

## What this is not

The badge here is the **platform** flag: `user#b1b8cc83 verified:flags.17` and
`channel#d49f34c6 verified:flags.7`.

Telegram also has a second, unrelated mechanism — **third-party bot
verification** — where an ordinary bot that a platform operator has appointed as
a "verifier" attaches its own custom icon and description to arbitrary peers.
That is `botVerification#f93cd45c`, `botVerifierSettings#b0cd6617`,
`bots.setCustomVerification#8b89dfbd`, `user.bot_verification_icon:flags2.14?long`,
`channel.bot_verification_icon:flags2.13?long` and
`channelFull.bot_verification:flags2.17?BotVerification`.

The two are deliberately kept apart:

- an approval in this flow never writes `bot_verification*`, and never issues
  `botVerifierSettings` to anybody;
- `bots.setCustomVerification` is routed and argument-checked at the RPC edge and
  then refused with `403 BOT_VERIFIER_FORBIDDEN`
  (`internal/rpc/bots_longtail.go`), because no bot on this deployment is a
  verifier;
- a client that renders `bot_verification_icon` renders it from data this flow
  never produces, so a third-party icon can neither stand in for the platform
  badge nor be shadowed by it.

## TL constructors and flags (Layer 228)

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

Platform verification:

| Constructor | Field |
| --- | --- |
| `user#b1b8cc83` | `verified:flags.17?true` |
| `channel#d49f34c6` | `verified:flags.7?true` |
| `chatInvite#5c9d3702` | `verified:flags.7?true`, `scam:flags.8?true`, `fake:flags.9?true` |

`chatInviteAlready#5a686d7c` carries a whole `Chat`, so a member's preview gets
the badge through `channel#d49f34c6` rather than through invite-level flags.

Third-party bot verification, for contrast — none of these are written by this
flow:

| Constructor / method | Field |
| --- | --- |
| `botVerification#f93cd45c` | `bot_id:long icon:long description:string` |
| `botVerifierSettings#b0cd6617` | `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` |
| `user#b1b8cc83` | `bot_verification_icon:flags2.14?long` |
| `channel#d49f34c6` | `bot_verification_icon:flags2.13?long` |
| `channelFull#a04e8d3a` | `bot_verification:flags2.17?BotVerification` |

`chatInvite#5c9d3702` also has `bot_verification:flags.13?BotVerification`; it is
never populated, for the same reason.

## End-to-end path

1. **`@verifybot`** (user id `1250000011`, seeded by migration `0152`) collects
   the application in a step-by-step dialog: subject, category, description,
   official website, optional social links, independent press links, optional
   note. Commands are `/new`, `/status`, `/cancel`, `/help`.
2. **Eligibility, first gate.** The subject must be a bot, public channel or
   public supergroup with a public `@username`, created or administered by the
   applicant, not a built-in system entity, not already verified, and not
   scam/fake/frozen/deleted. Per-applicant rate limits, an open-application cap
   and a post-rejection cooldown also apply.
3. **Submission** writes `verification_applications` (status `submitted`) and an
   immutable `verification_application_events` row.
4. **Admin panel** lists the queue and lets a reviewer claim, approve or reject.
   Panel BFF routes are under `/api/verification/...`; the Admin API routes are
   `GET /v1/verification/applications`, `.../{id}`, `.../counts`,
   `POST .../{id}/claim|approve|reject` and `POST /v1/verification/revoke`.
   Every decision also goes through the shared admin command journal, so it lands
   in `admin_commands` / `admin_audit_logs`.
5. **Eligibility, second gate.** At approval time the target is re-loaded and
   re-evaluated against a fresh snapshot, so a target that turned scam, lost its
   username, was frozen or got verified by another route between filing and
   review is refused. The review queue cannot launder a state the submission path
   forbids.
6. **Decision transaction.** The status transition, the audit event, the
   applicant-notification outbox row and the `verified` flag write on the peer
   commit in one transaction (`verification.PeerVerifier` is invoked with the
   store transaction taken from the context). "Approved" and "the peer carries
   the badge" can never disagree.
7. **Protocol edge.** After the commit the service calls
   `rpc.Router.NotifyPeerVerified(ctx, domain.Peer)`
   (`internal/rpc/verification_notify.go`), which:
   - drops the cached peer projections for the target
     (`invalidateRPCProjectionForUser` / `invalidateRPCProjectionForChannel`);
   - for a user or bot, reuses `NotifyUserModerationFlagsChanged` — the same
     audience-wide, non-PTS `updateUser` fan-out the scam/fake flags use. The
     audience is `ModerationFlagAudience` (accounts that already see the peer),
     filtered to the ones currently online; each recipient gets the peer
     re-projected for itself;
   - for a channel, reuses `NotifyChannelChanged` →
     `channelStateMutationUpdates` → `pushChannelStateToMembersWithLinkedMonoforum`,
     i.e. `updateChannel` plus the refreshed `channel#d49f34c6` object to the
     channel's members (and the linked monoforum when there is one);
   - reports a clear error instead of panicking when the peer cannot be resolved,
     and is a no-op on a nil receiver. A push failure never invalidates the
     committed decision; the caller logs it and moves on.
8. **Applicant notification.** `@verifybot` messages the applicant from a durable
   outbox drained by a retrying worker, never from inside the decision
   transaction. Kinds are `approved`, `rejected`, `revoked`.
9. **What the client sees.** An online client applies the flag from the pushed
   `User`/`Channel` object immediately: the badge appears in the dialog list,
   profile, search results and message headers without a restart. An offline
   client converges on reconnect — see below.

## Offline convergence

`updateUser` and `updateChannel` carry no `pts`, so they are not stored as
message-box events and are not replayed by `updates.getDifference`. Offline
sessions converge because `verified` is part of the peer's **base read model**,
whose version is bumped by the triggers shipped in `0001_init`:

- `users.verified` is listed in `telesrv_notify_user_base_read_model` (trigger
  `users_read_model_changed`), which bumps `user_base`, `contact_account` and the
  private dialog-light models, and in
  `telesrv_notify_user_channel_participants_read_model` (trigger
  `users_channel_participants_read_model_changed`), which bumps
  `channel_participants`;
- `channels` bumps `channel_base` on every row change (trigger
  `channels_read_model_changed`) and additionally fires
  `pg_notify('telesrv_channel_changed')`.

The `user_base` notification is consumed by the read-model listener
(`internal/store/postgres/read_model_listener.go`), which invalidates the RPC
projections **and** the shared Redis `user:base` row across instances. So any
later authoritative read — `users.getUsers`, `users.getFullUser`,
`channels.getChannels`, `channels.getFullChannel`, `messages.getDialogs`, or the
`users`/`chats` vectors attached to a `getDifference` answer — already carries the
new flag. No migration is needed for this, and none was added.

## Where the flag surfaces

`verified` is projected wherever a `User` or `Channel` object is projected, which
is every one of these:

| Surface | Method | Constructor |
| --- | --- | --- |
| Dialog list | `messages.getDialogs`, `messages.getPeerDialogs` | `user`, `channel` in `users`/`chats` |
| Search | `contacts.search`, `contacts.resolveUsername`, `messages.searchGlobal`, `channels.getAdminedPublicChannels` | `user`, `channel` |
| Profile | `users.getUsers`, `users.getFullUser` | `user` in `users.userFull.users` |
| Channel info | `channels.getChannels`, `channels.getFullChannel` | `channel` in `chats` |
| Message history | `messages.getHistory`, `messages.getMessages`, channel history | `user`, `channel` in `users`/`chats` |
| Invite preview | `messages.checkChatInvite` | `chatInvite` (`verified:flags.7`) or `chatInviteAlready.chat` |
| Live updates | pushed `updates` envelopes | `updateUser` / `updateChannel` plus the peer object |
| Difference | `updates.getDifference`, `updates.getChannelDifference` | `user`, `channel` in `users`/`chats` |

The invite preview is the one that used to be missing: before, a non-member saw
an unbadged preview and the badge only appeared after joining. It is now set from
the persistent channel record in `internal/rpc/channels_invites.go`, through the
generated `Set*` helpers so the `flags` word and the struct field stay in step,
and left entirely unset for an unflagged peer.

## Migrations

- **`0153_verify_service_bot`** seeds `@verifybot` (id `1250000011`, fixed
  `access_hash` double-written with `domain.VerifyBotAccessHash`), its `bots` row
  and command list, and its `peer_usernames` registry entry. The handle is
  occupied from the moment the schema is current, so an ordinary user cannot claim
  `@verifybot` in the window before first use.
- **`0154_verification_applications`** creates
  `verification_applications` (the durable audit subject, never deleted, moved
  through `draft → submitted → in_review → approved|rejected|cancelled` under an
  optimistic-locking `version`), the append-only
  `verification_application_events` history, and
  `verification_notification_outbox` with
  `UNIQUE (application_id, kind)` so a repeated approve delivers one message.
  Partial unique indexes enforce one live application per target and one draft per
  applicant.

Neither migration touches the `verified` columns or the read-model triggers:
`users.verified` and `channels.verified` already existed and were already covered.

## Configuration

Verification (`internal/config/config.go`, `.env.example`):

| Key | Default | Meaning |
| --- | --- | --- |
| `TELESRV_VERIFICATION_ENABLED` | `true` | Master switch. When off every use case refuses explicitly; peers already badged keep the badge. |
| `TELESRV_VERIFICATION_ALLOW_USER_TARGETS` | `false` | Whether plain user accounts may be subjects. |
| `TELESRV_VERIFICATION_REJECT_COOLDOWN` | `720h` | Wait before re-filing the same target after a rejection, measured from the decision. `0` disables; max `8760h`. |
| `TELESRV_VERIFICATION_APPLY_RATE_LIMIT` | `3` | Applications one applicant may create per window. `0` disables. |
| `TELESRV_VERIFICATION_APPLY_RATE_WINDOW` | `24h` | That window. |
| `TELESRV_VERIFICATION_BOT_RATE_LIMIT` | `30` | `@verifybot` dialog rate per applicant, independent of applications created. `0` disables. |
| `TELESRV_VERIFICATION_BOT_RATE_WINDOW` | `1m` | That window. |
| `TELESRV_VERIFICATION_NOTIFY_INTERVAL` | `15s` | Applicant-notification worker cadence. Must be positive. |
| `TELESRV_VERIFICATION_NOTIFY_BATCH` | `50` | Rows per cycle, `1..500`. |
| `TELESRV_VERIFICATION_MAX_ACTIVE_PER_USER` | `3` | Open applications per applicant. `0` disables, max `50`. |

Reviewer access:

| Key | Default | Meaning |
| --- | --- | --- |
| `TELESRV_ADMIN_UI_PERMISSIONS` | `*` | Permissions of an Admin UI session. Reviewing needs `verification.review`; clearing an existing badge needs `verification.revoke` on top of it. |
| `TELESRV_ADMIN_SCOPED_TOKENS` | *(empty)* | `name:token:perm1,perm2` entries separated by `;`, for Admin API integrations that should get `verification.review` and nothing else. |

## Manual check with official Telegram Desktop

1. Log in to the deployment with official Telegram Desktop.
2. Open `@verifybot` — it resolves by username and its own profile already shows
   the badge (the seed row is `verified`).
3. Send `/new`, pick the subject from the inline picker, and answer the steps:
   category, description, official website, social links (or *Skip*), at least the
   required number of independent press links, optional note. Press
   *Submit application*.
4. Send `/status`; the application is listed as submitted.
5. In the admin panel open the verification queue, claim the application and
   approve it. Confirm the audit entry appeared.
6. Within one notification-worker interval `@verifybot` messages the applicant
   with the decision.
7. Without restarting the client, check the badge on the approved subject:
   - **Profile** — open the peer's profile; the badge sits next to the title.
   - **Search** — type the `@username` in global search; the result row is badged.
   - **Dialog list** — the chat row in the main list is badged.
   - **Message header** — open the chat; the header title is badged.
   - **Invite preview** — from a *second* account that is **not** a member, open
     an invite link to the approved channel. The join-confirmation box is badged
     before joining. (This is the `chatInvite#5c9d3702 verified:flags.7` path.)
8. To check offline convergence, quit the client before approving, approve, then
   start it again: the badge is present on the first read, delivered by
   `getDifference` and the peer reads it triggers rather than by a live push.
9. Revoking from the panel takes the badge away by the same route.

## Limitations

- **Plain user accounts are off by default.** With
  `TELESRV_VERIFICATION_ALLOW_USER_TARGETS=false` (the shipped default) an
  application whose subject is an ordinary account is refused
  (`ErrVerificationUserTargetsDisabled`). Turning it on does not add any extra
  identity checks; it only stops refusing the target type.
- **Third-party bot verification is not part of this mechanism and is not
  implemented.** `bots.setCustomVerification` never succeeds: it validates its
  arguments and then refuses with `403 BOT_VERIFIER_FORBIDDEN`. No
  `botVerifierSettings` are issued, and
  `user.bot_verification_icon` / `channel.bot_verification_icon` /
  `channelFull.bot_verification` / `chatInvite.bot_verification` are never
  populated. A client asking for a custom verifier icon gets nothing.
- **The badge has no attributes.** It is a single boolean: no verifier company, no
  custom description, no per-peer icon, no expiry, no verification tier. There is
  nothing in the TL surface to carry them for the platform flag.
- **Built-in system entities cannot be applied for.** Service accounts are refused
  with `ErrVerificationTargetSystem`; their badge is set by the seed migrations.
- **A subject with no public `@username` is refused**
  (`ErrVerificationTargetNotPublic`), so private channels and usernameless bots
  cannot be verified at all — not even by an operator using the panel's revoke
  route in reverse.
- **Legacy basic groups (`chat#…`) have no `verified` field** in Layer 228, so a
  non-migrated basic group can never show a badge regardless of what is stored.
- **The live push only reaches online sessions.** `NotifyPeerVerified` filters the
  audience by the online index; everybody else converges on their next
  authoritative read. The user fan-out is additionally bounded (the moderation
  audience is capped, currently at 4096 accounts) and the channel fan-out is
  bounded by the online-member index, so on a very large peer some sessions get
  the flag from their next read rather than from a push.
- **`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 itself; it depends on the read-model bump. That is by design
  (a badge change is not a message), but it means the badge is not guaranteed to
  arrive as an *event* — only as *state*.
- **The live push can be one beat behind the shared base-user cache.** The
  decision writes the user row inside the verification transaction, bypassing the
  `users` service and therefore its Redis `user:base` refresh; that cache is
  dropped cross-instance by the asynchronous `user_base` read-model
  notification. `NotifyPeerVerified` runs synchronously right after commit, so in
  the small window before the listener processes the event the pushed `user`
  object can still carry the pre-decision flag. The persisted state is always
  correct, the projections are always invalidated, and the client repairs itself
  on the next read, so this shows up at worst as a badge that appears a moment
  late rather than instantly. The channel path is not affected: the
  transaction-scoped channel store is handed the channel row cache and drops it
  on the flag write.
- **Nothing re-checks a verified peer over time.** Once badged, a peer keeps the
  badge until an operator revokes it. There is no periodic re-validation, and
  losing the username or picking up a scam flag later does not clear it.