owpengram-server/internal/app/bots/verifierbot.go

package bots

import (
	"context"
	"crypto/rand"
	"encoding/hex"
	"errors"
	"fmt"
	"strconv"
	"strings"
	"time"
	"unicode/utf8"

	"go.uber.org/zap"

	"telesrv/internal/branding"
	"telesrv/internal/domain"
)

// Built-in @verifierbot: the applicant front door for THIRD-PARTY verification
// (core.telegram.org/api/bots/verification).
//
// The difference from @verifybot is the whole reason this file exists, and it is
// the first thing every message here has to get across. The official checkmark is
// granted by the PLATFORM: an operator reviews the application @verifybot collected
// and flips the peer's verified flag. A third-party mark is granted by a VERIFIER
// BOT: the peer gets that bot's own icon before its name and that bot's line of
// description in its profile. Neither mechanism reads the other's state, and
// neither implies the other.
//
// This bot is the first verifier of a deployment -- the demo and the reference for
// the feature -- and its own verifier status (icon, company name, description
// permission) is granted by an operator in the admin panel, exactly like any other
// verifier's. That is the honesty constraint the dialog is built around: with no
// live, enabled BotVerifierSettings row this bot has no icon to put anywhere, so
// /start says so plainly and offers no apply button, instead of collecting
// paperwork nobody can act on.
//
// The dialog is button driven (inline keyboards) for every closed choice -- which
// peer, confirm/cancel, which mark to remove -- and text driven for the single
// free-form field (the justification). It owns no verification rule: verifier
// status, the per-verifier limit, the application status machine and the mark
// itself all live in app/botverification, and this file only renders the answers
// that service gives.
//
// Conversation state is domain.BotChatState (Command="verifier"), read and written
// under the per-user serviceBotReplyLock, so the Get->modify->Upsert round trip is
// atomic and replies stay ordered.

// customVerifications is the applicant-side surface of third-party verification
// used by this bot: app/botverification.Service satisfies it.
//
// It is declared as a narrow port rather than taken as a concrete service for the
// usual reason plus one specific to this feature: granting a mark is granting a
// badge, and the bot must not be able to reach past the service that owns the
// rules. Nothing here can write a mark, grant verifier status, decide an
// application or read another applicant's queue -- the operator's decision path is
// not on this interface at all.
//
// Once app/botverification lands, assert the contract in this package the way
// verifybot.go does for app/verification, so a signature change breaks the build
// instead of silently disabling the bot:
//
//	var _ customVerifications = (*botverificationapp.Service)(nil)
type customVerifications interface {
	// VerifierSettings reads this bot's own verifier status, or
	// domain.ErrVerifierNotFound when an operator has not granted it.
	VerifierSettings(ctx context.Context, botID int64) (domain.BotVerifierSettings, error)
	// CreateRequest files an application. A pending application on the same
	// (verifier, peer) pair reports domain.ErrCustomVerificationRequestExists.
	CreateRequest(ctx context.Context, req domain.CustomVerificationRequest) (domain.CustomVerificationRequest, error)
	// ApplicantRequests returns one applicant's own history, newest first.
	ApplicantRequests(ctx context.Context, applicantUserID int64, limit int) ([]domain.CustomVerificationRequest, error)
	// PendingRequest returns the live application for a (verifier, peer) pair, or
	// domain.ErrCustomVerificationRequestNotFound.
	PendingRequest(ctx context.Context, verifierBotID int64, peer domain.Peer) (domain.CustomVerificationRequest, error)
	// RevokeMark removes this verifier's mark from a peer. removed=false means there
	// was nothing to remove, which is what makes a repeated revoke a no-op.
	RevokeMark(ctx context.Context, verifierBotID int64, peer domain.Peer) (bool, error)
	// Marks lists granted marks. The bot only ever queries its own
	// (VerifierBotID, peer) pairs, so it can tell an applicant whether a mark is
	// actually live.
	Marks(ctx context.Context, filter domain.CustomVerificationFilter) ([]domain.CustomVerification, error)
}

// verifierBotTargets enumerates the peers an applicant may put forward: the bots
// they own, the channels and supergroups they created or administer, and their own
// account. app/verification.Service satisfies it as-is (EligibleTargets), which is
// why verificationApplications is accepted as a fallback source.
//
// Only the identity fields (Type, ID, Title, Username) are used here.
// VerificationTarget.Eligible and .Reason are deliberately IGNORED: they answer
// "may this peer be filed for the platform checkmark", which is a different bar
// belonging to a different mechanism -- a peer that is already officially verified,
// or has no public username, is a perfectly good third-party target. What the
// enumeration is trusted for is authorisation: it only ever contains peers the
// applicant owns or administers, which is why every button press re-resolves
// against it instead of trusting callback data.
type verifierBotTargets interface {
	EligibleTargets(ctx context.Context, applicantUserID int64) ([]domain.VerificationTarget, error)
}

// verifierBotApplicantNotifier mirrors app/botverification.ApplicantNotifier: the
// port that carries an operator's decision back to the applicant as an ordinary
// @verifierbot message. It is restated here so this package compiles the assertion
// below against its own copy of the contract; replace it with the real interface
// once that package exists.
type verifierBotApplicantNotifier interface {
	SendVerificationDecision(ctx context.Context, recipientUserID int64, req domain.CustomVerificationRequest) error
}

var _ verifierBotApplicantNotifier = (*Service)(nil)

const (
	// verifierBotCommand is the single BotChatState.Command of this dialog. There are
	// two flows (apply, revoke) and the step distinguishes them.
	verifierBotCommand = "verifier"

	verifierBotCmdVerify = "verify"
	verifierBotCmdStatus = "status"
	verifierBotCmdRevoke = "revoke"

	verifierStepIntro  = "intro"
	verifierStepTarget = "target"
	verifierStepReason = "reason"
	// verifierStepConfirm is the last button-only step of the apply flow.
	verifierStepConfirm = "confirm"
	// verifierStepDone is a terminal state that is deliberately *kept*: it is what
	// makes a second press of Confirm replay the same answer instead of filing a
	// second application or reporting an expired button.
	verifierStepDone          = "done"
	verifierStepRevokePick    = "revoke_pick"
	verifierStepRevokeConfirm = "revoke_confirm"

	verifierDraftTarget         = "tgt"
	verifierDraftTargetTitle    = "tgt_title"
	verifierDraftTargetUsername = "tgt_username"
	verifierDraftReason         = "reason"
	verifierDraftRequestID      = "req"
	// verifierDraftCorrelation is a per-attempt idempotency key handed to the
	// service. It is minted once when the summary is rendered and reused by every
	// repeat press of Confirm, so a double tap cannot become two applications even if
	// the dialog state is lost between them.
	verifierDraftCorrelation = "corr"
	// verifierDraftRevoked records the peer whose mark this dialog already removed
	// (and the label it was reported under), so a repeat press of the removal button
	// replays the same confirmation instead of reporting a second removal.
	verifierDraftRevoked      = "rev_done"
	verifierDraftRevokedLabel = "rev_done_label"
	verifierDraftGeneration   = "gen"
	// verifierDraftOptionPrefix namespaces the button token table inside the draft
	// map, so a token can never collide with a payload field.
	verifierDraftOptionPrefix = "opt:"

	// verifierCallbackDataPrefix tags this bot's own callback data. It carries no
	// information beyond "this is a @verifierbot button".
	verifierCallbackDataPrefix = "vfb:"
	// verifierOptionTokenBytes is the entropy behind one button token.
	verifierOptionTokenBytes = 6
	// verifierOptionTokenMaxLen bounds the token part of callback data before the
	// table is even consulted.
	verifierOptionTokenMaxLen = 32
	// verifierTokenGenerations is how many keyboard renders' worth of tokens stay
	// resolvable: the current render plus the two before it. Enough that pressing the
	// same button twice still resolves, while the table stays bounded.
	verifierTokenGenerations = 3

	// verifierMaxTargetButtons bounds one picker: an account can administer far more
	// peers than fit in an inline keyboard, and the token table is per-user durable
	// state, so the picker is truncated rather than unbounded.
	verifierMaxTargetButtons = 12
	// verifierStatusListLimit bounds the /status listing and the /revoke picker.
	verifierStatusListLimit = 10
	// verifierMinReasonLength is the floor on the justification. An operator has to
	// act on it, and "please verify me" is not something anyone can check.
	verifierMinReasonLength = 20
)

// Opaque button choices as stored in the per-user token table. These strings never
// travel over the wire: only the random token that maps to them does.
const (
	verifierChoiceApply       = "apply"
	verifierChoiceConfirm     = "confirm"
	verifierChoiceAbort       = "abort"
	verifierChoiceRevokeApply = "revoke"
	// The two peer-bearing choices carry the peer inside the token table entry, not
	// in the callback data. A confirmation button therefore names the peer it was
	// rendered for, so pressing a stale one cannot act on whatever peer the dialog
	// happens to be pointing at now.
	verifierChoiceTargetPrefix       = "tgt:"
	verifierChoiceRevokePrefix       = "rev:"
	verifierChoiceRevokeCommitPrefix = "revoke_commit:"
)

// verifierBotWhatText is the part of /start that is true whether or not an
// operator has activated this bot, so it is said first and unconditionally.
func verifierBotWhatText() string {
	return `I hand out THIRD-PARTY verification.

A third-party mark is a verifier's own icon, shown right before the name of a bot, a channel or an account, plus one line of description in its profile. It means "this verifier vouches for this peer" -- nothing more.

It is NOT the official ` + branding.ProductName + ` checkmark. The platform badge is granted by the platform itself (@verifybot collects those applications); a third-party mark is granted by the company running a verifier bot. The two are stored, shown and taken away separately, and neither one implies the other.`
}

func verifierBotHelpText() string {
	return `I am a verifier bot. I grant third-party marks: my icon before the name of your bot, channel or account, plus a description in its profile. This is not the official ` + branding.ProductName + ` checkmark.

/start - what a third-party mark is and who grants it
/verify - apply for the mark
/status - your applications and the marks you carry
/revoke - remove a mark from one of your peers
/cancel - drop the application I am collecting right now
/help - show this message

I do not decide anything: I collect the application, an operator grants or refuses the mark, and I message you here with the outcome.`
}

const (
	verifierBotIdleText = `I only hand out third-party verification marks. Send /verify to apply, /status to see where your applications stand, /revoke to remove a mark, or /help to see what I understand.`

	// verifierNotActivatedText is the honest answer when this bot has no live
	// verifier status. It never pretends an application is possible.
	verifierNotActivatedText = `I cannot accept applications yet.

I am the built-in verifier of this server, and verifier status is granted by hand: an operator has to give me an icon from the verification icon catalogue and a company name to vouch under (admin panel, bot verifiers), and keep that row enabled. Until it exists I have no icon to put on anything, so filing an application with me would only produce paperwork nobody can act on.

Send /start again once the operator tells you I am activated. /help lists the rest of my commands.`

	verifierUnavailableText = `Third-party verification is not available on this server right now.`

	verifierNoTargetSourceText = `I cannot look up your bots and channels right now, so I have nothing to offer you. Please try again in a moment.`

	verifierNoTargetsText = `I could not find anything of yours to mark. I can verify a bot you own, a channel or supergroup you created or administer, or your own account -- so get one of those first and come back with /verify.`

	verifierNoRequestsText = `You have not applied to me yet, and you carry none of my marks. Send /verify to apply.`

	verifierNothingToRevokeText = `You carry none of my marks, so there is nothing to remove. Send /status to see where your applications stand.`

	verifierNothingToCancelText = `There is nothing to cancel. Send /verify to apply for the mark.`

	verifierExpiredButtonText = `That button is no longer active. Send /verify to apply, or /status to see where your applications stand.`

	verifierPickButtonsText = `Please use the buttons in my message above.`

	verifierGoneTargetText = `That one is not yours to verify any more, so I dropped it. Send /verify to start again.`

	verifierApplyButtonText        = `Get verification`
	verifierConfirmButtonText      = `✅ Confirm`
	verifierCancelButtonText       = `❌ Cancel`
	verifierRevokeMenuButtonText   = `Remove a mark`
	verifierRevokeButtonText       = `✅ Remove the mark`
	verifierRevokeCancelButtonText = `❌ Keep the mark`
)

// verifierBotGlobalCommands are the commands honoured in every step, so an
// applicant is never trapped mid-dialog. Same contract as
// botFatherGlobalCommands.
var verifierBotGlobalCommands = map[string]bool{
	"start": true, "help": true, "cancel": true,
	verifierBotCmdVerify: true, verifierBotCmdStatus: true, verifierBotCmdRevoke: true,
}

// verifierOption is one inline button before its token is minted.
type verifierOption struct {
	text   string
	choice string
	style  domain.MarkupButtonStyle
}

// ---------------------------------------------------------------------------
// Message entry point
// ---------------------------------------------------------------------------

// respondAsVerifier generates and writes one @verifierbot reply. It is called from
// OnPrivateMessage's goroutine, serialised per user by serviceBotReplyLock, on a
// context detached from the user's already-answered RPC.
func (s *Service) respondAsVerifier(userID int64, msg domain.Message) {
	mu := s.serviceBotReplyLock(domain.VerifierBotUserID, userID)
	mu.Lock()
	defer mu.Unlock()

	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()
	if allowed, retryAfter := s.allowVerifierDialog(ctx, userID); !allowed {
		s.sendServiceBotReply(ctx, domain.VerifierBotUserID, userID, botReply{
			Text: verifierFloodText(retryAfter),
		})
		return
	}
	reply := s.handleVerifier(ctx, userID, msg.Body)
	s.sendServiceBotReply(ctx, domain.VerifierBotUserID, userID, reply)
}

// allowVerifierDialog bounds dialog traffic per applicant, keyed by this bot so it
// has its own budget rather than sharing @verifybot's. It is deliberately separate
// from any application limit inside the verification service: that one bounds how
// many applications exist, this one bounds how hard the state machine can be
// driven, so a script cannot burn writes without ever applying. A missing limiter
// means no bound, which is the pre-Redis behaviour.
func (s *Service) allowVerifierDialog(ctx context.Context, userID int64) (bool, int) {
	if s == nil || s.dialogLimiter == nil || s.dialogRateLimit <= 0 || s.dialogRateWindow <= 0 {
		return true, 0
	}
	key := fmt.Sprintf("bot-dialog:%d:%d", domain.VerifierBotUserID, userID)
	allowed, retryAfter, err := s.dialogLimiter.Allow(ctx, key, s.dialogRateLimit, s.dialogRateWindow)
	if err != nil {
		// A limiter outage must not silence the bot: fail open, log once.
		s.log.Warn("verifierbot: dialog rate limit check failed",
			zap.Int64("user_id", userID), zap.Error(err))
		return true, 0
	}
	return allowed, retryAfter
}

func verifierFloodText(retryAfter int) string {
	if retryAfter > 0 {
		return fmt.Sprintf("Too many requests. Please wait %d seconds and try again.", retryAfter)
	}
	return "Too many requests. Please wait a moment and try again."
}

func (s *Service) handleVerifier(ctx context.Context, userID int64, body string) botReply {
	text := strings.TrimSpace(body)
	state, found, err := s.bots.GetBotChatState(ctx, domain.VerifierBotUserID, userID)
	if err != nil {
		s.log.Error("verifierbot: get chat state", zap.Int64("user_id", userID), zap.Error(err))
		return internalReply()
	}
	if found && state.Command != verifierBotCommand {
		// Unreachable dirty state (an older dialog shape): drop it rather than trap the
		// applicant in a step no handler owns.
		s.deleteVerifierState(ctx, userID)
		state, found = domain.BotChatState{}, false
	}
	if cmd, ok := parseBotCommand(text); ok {
		if verifierBotGlobalCommands[cmd] {
			return s.handleVerifierCommand(ctx, userID, cmd, state, found)
		}
		return botReply{Text: "I do not know that command. Send /help for the list."}
	}
	if !found {
		if text == "" {
			// Stickers and captionless media with no active dialog: stay silent instead of
			// answering every non-text message.
			return botReply{}
		}
		return botReply{Text: verifierBotIdleText}
	}
	if text == "" {
		return s.verifierStepReminder(state)
	}
	switch state.Step {
	case verifierStepReason:
		return s.handleVerifierReason(ctx, state, text)
	case verifierStepIntro, verifierStepDone:
		return botReply{Text: verifierBotIdleText}
	case verifierStepTarget, verifierStepConfirm, verifierStepRevokePick, verifierStepRevokeConfirm:
		// Button-only steps. Answered deliberately without re-rendering the keyboard: a
		// fresh render mints a new token generation and would eventually expire the very
		// buttons the applicant is looking at.
		return botReply{Text: verifierPickButtonsText}
	default:
		s.deleteVerifierState(ctx, userID)
		return botReply{Text: "Something went wrong, I forgot what we were doing. Send /verify to start again."}
	}
}

func (s *Service) handleVerifierCommand(ctx context.Context, userID int64, cmd string, state domain.BotChatState, found bool) botReply {
	if cmd == "help" {
		return botReply{Text: verifierBotHelpText()}
	}
	if s.customVerification == nil {
		return botReply{Text: verifierUnavailableText}
	}
	switch cmd {
	case "start":
		return s.verifierIntro(ctx, userID, state, found)
	case verifierBotCmdVerify:
		if !found {
			state = verifierNewState(userID)
		}
		return s.startVerifierRequest(ctx, state)
	case verifierBotCmdStatus:
		return s.verifierStatusReply(ctx, userID)
	case verifierBotCmdRevoke:
		if !found {
			state = verifierNewState(userID)
		}
		return s.verifierRevokePrompt(ctx, state, "")
	case "cancel":
		return s.cancelVerifierDialog(ctx, userID, state, found)
	default:
		return botReply{Text: verifierBotHelpText()}
	}
}

// ---------------------------------------------------------------------------
// Callback entry point
// ---------------------------------------------------------------------------

// onVerifierCallback answers one inline-button click on a @verifierbot message. It
// is reached from OnCallbackQuery (verifybot.go), which is the bots side of
// rpc.ServiceBotCallbacks.
func (s *Service) onVerifierCallback(ctx context.Context, query domain.BotCallbackQuery) (domain.BotCallbackAnswer, bool, error) {
	userID := query.UserID
	mu := s.serviceBotReplyLock(domain.VerifierBotUserID, userID)
	mu.Lock()
	defer mu.Unlock()

	if allowed, retryAfter := s.allowVerifierDialog(ctx, userID); !allowed {
		// Answering with an alert keeps the click from hanging for the whole callback
		// timeout, and the dialog state is left exactly as it was.
		return domain.BotCallbackAnswer{Message: verifierFloodText(retryAfter), Alert: true}, true, nil
	}

	state, found, err := s.bots.GetBotChatState(ctx, domain.VerifierBotUserID, userID)
	if err != nil {
		s.log.Error("verifierbot: get chat state for callback", zap.Int64("user_id", userID), zap.Error(err))
		return domain.BotCallbackAnswer{}, true, err
	}
	if !found || state.Command != verifierBotCommand {
		return verifierAlert(verifierExpiredButtonText), true, nil
	}
	choice, ok := verifierResolveOption(state, query.Data)
	if !ok {
		// The only way to reach this is callback data that is not in *this* user's own
		// token table: a button from an expired generation, or data that was replayed or
		// fabricated. All of them are refused identically and change nothing at all.
		return verifierAlert(verifierExpiredButtonText), true, nil
	}
	if s.customVerification == nil {
		return verifierAlert(verifierUnavailableText), true, nil
	}
	// The follow-up message is written on a context detached from the caller's RPC:
	// the answer unblocks the click, and the message must survive the client hanging
	// up immediately afterwards.
	sendCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 30*time.Second)
	defer cancel()
	reply, answer := s.applyVerifierChoice(sendCtx, state, choice)
	s.sendServiceBotReply(sendCtx, domain.VerifierBotUserID, userID, reply)
	return answer, true, nil
}

// applyVerifierChoice executes one resolved button choice.
func (s *Service) applyVerifierChoice(ctx context.Context, state domain.BotChatState, choice string) (botReply, domain.BotCallbackAnswer) {
	switch {
	case choice == verifierChoiceApply:
		return s.startVerifierRequest(ctx, state), domain.BotCallbackAnswer{}
	case choice == verifierChoiceAbort:
		return s.cancelVerifierDialog(ctx, state.UserID, state, true), domain.BotCallbackAnswer{}
	case choice == verifierChoiceConfirm:
		return s.submitVerifierRequest(ctx, state), domain.BotCallbackAnswer{}
	case choice == verifierChoiceRevokeApply:
		return s.verifierRevokePrompt(ctx, state, ""), domain.BotCallbackAnswer{}
	case strings.HasPrefix(choice, verifierChoiceRevokeCommitPrefix):
		return s.commitVerifierRevoke(ctx, state, strings.TrimPrefix(choice, verifierChoiceRevokeCommitPrefix)), domain.BotCallbackAnswer{}
	case strings.HasPrefix(choice, verifierChoiceTargetPrefix):
		return s.chooseVerifierTarget(ctx, state, strings.TrimPrefix(choice, verifierChoiceTargetPrefix)), domain.BotCallbackAnswer{}
	case strings.HasPrefix(choice, verifierChoiceRevokePrefix):
		return s.chooseVerifierRevokeTarget(ctx, state, strings.TrimPrefix(choice, verifierChoiceRevokePrefix)), domain.BotCallbackAnswer{}
	default:
		s.log.Warn("verifierbot: unknown button choice",
			zap.Int64("user_id", state.UserID), zap.String("choice", choice))
		return botReply{}, verifierAlert(verifierExpiredButtonText)
	}
}

// verifierAlert is a refusal shown as a modal on the clicking client. A refusal is
// deliberately an alert rather than a toast: it is the only feedback the applicant
// gets, because a refused click writes no message.
func verifierAlert(text string) domain.BotCallbackAnswer {
	return domain.BotCallbackAnswer{Alert: true, Message: verifierTruncate(text, domain.MaxBotCallbackAnswerLen)}
}

// ---------------------------------------------------------------------------
// Verifier status
// ---------------------------------------------------------------------------

// verifierSettings resolves this bot's own verifier status. The bool is the whole
// point of the function: false means an operator has not activated the bot, and the
// returned reply says exactly that instead of hiding it behind a generic failure.
func (s *Service) verifierSettings(ctx context.Context, userID int64) (domain.BotVerifierSettings, botReply, bool) {
	if s.customVerification == nil {
		return domain.BotVerifierSettings{}, botReply{Text: verifierUnavailableText}, false
	}
	settings, err := s.customVerification.VerifierSettings(ctx, domain.VerifierBotUserID)
	switch {
	case errors.Is(err, domain.ErrVerifierNotFound), errors.Is(err, domain.ErrVerifierForbidden):
		return domain.BotVerifierSettings{}, botReply{Text: verifierNotActivatedText}, false
	case err != nil:
		return domain.BotVerifierSettings{}, s.verifierErrorReply(userID, "read verifier settings", err), false
	}
	if !settings.Enabled {
		// The operator's kill switch. Existing marks stay, but nothing new can be
		// granted, so promising an application would be a lie.
		return domain.BotVerifierSettings{}, botReply{Text: verifierNotActivatedText}, false
	}
	if err := settings.Validate(); err != nil {
		// A half-written verifier row (no icon, no company) cannot mark anything either.
		// Report it as not activated, and log it: this one is an operator mistake.
		s.log.Warn("verifierbot: verifier settings do not validate", zap.Error(err))
		return domain.BotVerifierSettings{}, botReply{Text: verifierNotActivatedText}, false
	}
	return settings, botReply{}, true
}

// verifierMarkDescription is the description a mark granted now would carry. It is
// resolved through the domain rule rather than read off the settings struct, so
// this dialog and the RPC edge can never disagree about it.
func verifierMarkDescription(settings domain.BotVerifierSettings) string {
	description, err := settings.DescriptionFor("")
	if err != nil {
		return ""
	}
	return strings.TrimSpace(description)
}

func verifierDescriptionLine(settings domain.BotVerifierSettings) string {
	if description := verifierMarkDescription(settings); description != "" {
		return description
	}
	return "(no description -- only the icon is shown)"
}

// ---------------------------------------------------------------------------
// Flow: /start
// ---------------------------------------------------------------------------

// verifierIntro answers /start. The explanation of what a third-party mark is
// comes first and unconditionally; the apply button only exists when there is a
// live verifier status behind it.
func (s *Service) verifierIntro(ctx context.Context, userID int64, state domain.BotChatState, found bool) botReply {
	if !found {
		state = verifierNewState(userID)
	}
	settings, refusal, ok := s.verifierSettings(ctx, userID)
	if !ok {
		// No keyboard, no state write: there is nothing for the applicant to press.
		return botReply{Text: verifierJoin(verifierBotWhatText(), refusal.Text)}
	}
	state.Step = verifierStepIntro
	markup := s.verifierOptionKeyboard(&state, [][]verifierOption{{
		{text: verifierApplyButtonText, choice: verifierChoiceApply, style: domain.MarkupButtonStylePrimary},
	}})
	if !s.saveVerifierState(ctx, state) {
		return internalReply()
	}
	live := fmt.Sprintf("Verifier: %s\n\nThe mark I would put on your peer:\n%s\n\nTap the button below, or send /verify, to apply. An operator reads every application and decides; I only collect it. Send /help for the rest of my commands.",
		verifierTruncate(strings.TrimSpace(settings.CompanyName), domain.MaxVerifierCompanyLength),
		verifierDescriptionLine(settings))
	return botReply{Text: verifierJoin(verifierBotWhatText(), live), ReplyMarkup: markup}
}

// ---------------------------------------------------------------------------
// Flow: apply
// ---------------------------------------------------------------------------

// startVerifierRequest is /verify and the apply button: it starts a fresh
// application, so the leftovers of any previous one are cleared first.
func (s *Service) startVerifierRequest(ctx context.Context, state domain.BotChatState) botReply {
	settings, refusal, ok := s.verifierSettings(ctx, state.UserID)
	if !ok {
		return refusal
	}
	verifierEnsureDraft(&state)
	for _, key := range []string{
		verifierDraftTarget, verifierDraftTargetTitle, verifierDraftTargetUsername,
		verifierDraftReason, verifierDraftRequestID, verifierDraftCorrelation,
		verifierDraftRevoked, verifierDraftRevokedLabel,
	} {
		delete(state.Draft, key)
	}
	return s.verifierTargetPrompt(ctx, state, settings, "")
}

// verifierTargetPrompt renders the peer picker.
func (s *Service) verifierTargetPrompt(ctx context.Context, state domain.BotChatState, settings domain.BotVerifierSettings, lead string) botReply {
	targets, reply, ok := s.verifierCandidates(ctx, state.UserID)
	if !ok {
		return botReply{Text: verifierJoin(lead, reply.Text)}
	}
	state.Step = verifierStepTarget
	rows := make([][]verifierOption, 0, len(targets)+1)
	for _, target := range targets {
		rows = append(rows, []verifierOption{{
			text:   verifierTargetButtonText(target),
			choice: verifierChoiceTargetPrefix + string(target.Type) + ":" + strconv.FormatInt(target.ID, 10),
		}})
	}
	rows = append(rows, []verifierOption{{
		text:   verifierCancelButtonText,
		choice: verifierChoiceAbort,
		style:  domain.MarkupButtonStyleDanger,
	}})
	markup := s.verifierOptionKeyboard(&state, rows)
	if !s.saveVerifierState(ctx, state) {
		return internalReply()
	}
	prompt := fmt.Sprintf("Which one should carry the %s mark? Pick it below.",
		verifierTruncate(strings.TrimSpace(settings.CompanyName), domain.MaxVerifierCompanyLength))
	return botReply{Text: verifierJoin(lead, prompt), ReplyMarkup: markup}
}

// verifierCandidates enumerates the applicant's own peers, bounded and filtered
// down to what a third-party mark can actually be attached to.
func (s *Service) verifierCandidates(ctx context.Context, userID int64) ([]domain.VerificationTarget, botReply, bool) {
	source := s.verifierTargetSource()
	if source == nil {
		return nil, botReply{Text: verifierNoTargetSourceText}, false
	}
	targets, err := source.EligibleTargets(ctx, userID)
	if err != nil {
		s.log.Warn("verifierbot: enumerate targets", zap.Int64("user_id", userID), zap.Error(err))
		return nil, botReply{Text: verifierNoTargetSourceText}, false
	}
	out := make([]domain.VerificationTarget, 0, len(targets))
	for _, target := range targets {
		if !verifierTargetVerifiable(target) {
			continue
		}
		out = append(out, target)
		if len(out) >= verifierMaxTargetButtons {
			break
		}
	}
	if len(out) == 0 {
		return nil, botReply{Text: verifierNoTargetsText}, false
	}
	return out, botReply{}, true
}

// verifierTargetVerifiable filters the enumeration down to peers a mark can exist
// on: the domain accepts user and channel peers only, and a built-in service
// account is never a third-party subject.
func verifierTargetVerifiable(target domain.VerificationTarget) bool {
	if target.ID <= 0 || !target.Type.Valid() {
		return false
	}
	peer := verifierTargetPeer(target)
	if peer.Type == domain.PeerTypeUser && domain.IsSystemUserID(peer.ID) {
		return false
	}
	return peer.Type == domain.PeerTypeUser || peer.Type == domain.PeerTypeChannel
}

func verifierTargetPeer(target domain.VerificationTarget) domain.Peer {
	return domain.Peer{Type: target.Type.PeerType(), ID: target.ID}
}

// chooseVerifierTarget opens the application for the picked peer.
//
// The kind and id come from the token table, i.e. from state this server wrote when
// it rendered the keyboard -- never from the callback data. They are then
// re-resolved against the applicant's own enumeration, which is what authorises the
// choice: a peer that is no longer theirs simply is not in the list any more.
func (s *Service) chooseVerifierTarget(ctx context.Context, state domain.BotChatState, payload string) botReply {
	kind, rawID, split := strings.Cut(payload, ":")
	targetID, err := strconv.ParseInt(rawID, 10, 64)
	targetType := domain.VerificationTargetType(kind)
	if !split || err != nil || targetID <= 0 || !targetType.Valid() {
		s.log.Warn("verifierbot: malformed target choice",
			zap.Int64("user_id", state.UserID), zap.String("payload", payload))
		return botReply{Text: verifierExpiredButtonText}
	}
	settings, refusal, ok := s.verifierSettings(ctx, state.UserID)
	if !ok {
		return refusal
	}
	targets, reply, ok := s.verifierCandidates(ctx, state.UserID)
	if !ok {
		return reply
	}
	var target domain.VerificationTarget
	for _, candidate := range targets {
		if candidate.Type == targetType && candidate.ID == targetID {
			target = candidate
		}
	}
	if target.ID == 0 {
		return botReply{Text: verifierGoneTargetText}
	}
	peer := verifierTargetPeer(target)
	label := verifierPeerLabel(target.Title, target.Username, peer)

	// Already applied for, or already marked: say so instead of filing a duplicate the
	// service would refuse anyway.
	if pending, found := s.verifierPendingRequest(ctx, peer); found {
		return botReply{Text: fmt.Sprintf("Application #%d for %s is already with the operator, so there is nothing to file. Send /status to see where it stands.",
			pending.ID, label)}
	}
	if mark, found := s.verifierMark(ctx, peer); found {
		text := fmt.Sprintf("%s already carries my mark, so there is nothing to apply for.", label)
		if description := strings.TrimSpace(mark.Description); description != "" {
			text += "\n\nIt reads: " + verifierTruncate(description, domain.MaxCustomVerificationDescriptionLength)
		}
		// The picker stays where it is (the dialog is still at the subject step): this
		// only offers the way out, which is removing the mark.
		markup := s.verifierOptionKeyboard(&state, [][]verifierOption{
			{{text: verifierRevokeMenuButtonText, choice: verifierChoiceRevokeApply, style: domain.MarkupButtonStyleDanger}},
		})
		if !s.saveVerifierState(ctx, state) {
			return internalReply()
		}
		return botReply{Text: text + "\n\nSend /revoke, or tap below, if you want it removed.", ReplyMarkup: markup}
	}

	verifierEnsureDraft(&state)
	state.Draft[verifierDraftTarget] = string(targetType) + ":" + strconv.FormatInt(targetID, 10)
	state.Draft[verifierDraftTargetTitle] = target.Title
	state.Draft[verifierDraftTargetUsername] = target.Username
	delete(state.Draft, verifierDraftCorrelation)
	return s.verifierAdvance(ctx, state, settings, verifierStepReason, "Subject: "+label+".")
}

func (s *Service) handleVerifierReason(ctx context.Context, state domain.BotChatState, text string) botReply {
	length := utf8.RuneCountInString(text)
	if length < verifierMinReasonLength {
		return botReply{Text: fmt.Sprintf("That is %d characters and I need at least %d. An operator has to be able to check what you say, so name who is behind it and what it is known for.",
			length, verifierMinReasonLength)}
	}
	if length > domain.MaxCustomVerificationReasonLength {
		return botReply{Text: fmt.Sprintf("That is %d characters and the limit is %d. Please shorten it.",
			length, domain.MaxCustomVerificationReasonLength)}
	}
	settings, refusal, ok := s.verifierSettings(ctx, state.UserID)
	if !ok {
		return refusal
	}
	verifierEnsureDraft(&state)
	state.Draft[verifierDraftReason] = text
	return s.verifierAdvance(ctx, state, settings, verifierStepConfirm, "Saved.")
}

// submitVerifierRequest files the application.
//
// Pressing Confirm twice is idempotent by construction: the first press moves the
// dialog to verifierStepDone, and a repeat press is answered from the id stored in
// the dialog instead of calling CreateRequest again.
func (s *Service) submitVerifierRequest(ctx context.Context, state domain.BotChatState) botReply {
	if state.Step == verifierStepDone {
		if id := verifierDraftInt(state, verifierDraftRequestID); id > 0 {
			return botReply{Text: verifierFiledText(id, verifierDraftTargetLabel(state))}
		}
		return botReply{Text: verifierBotIdleText}
	}
	settings, refusal, ok := s.verifierSettings(ctx, state.UserID)
	if !ok {
		return refusal
	}
	target, targetOK := verifierDraftTargetOf(state)
	reason := strings.TrimSpace(state.Draft[verifierDraftReason])
	if !targetOK {
		return s.startVerifierRequest(ctx, state)
	}
	if utf8.RuneCountInString(reason) < verifierMinReasonLength {
		return s.verifierAdvance(ctx, state, settings, verifierStepReason, "I still need the reason.")
	}
	peer := verifierTargetPeer(target)
	label := verifierDraftTargetLabel(state)
	verifierEnsureDraft(&state)
	correlation := state.Draft[verifierDraftCorrelation]
	if correlation == "" {
		correlation = s.verifierCorrelationID(state.UserID)
		state.Draft[verifierDraftCorrelation] = correlation
	}
	created, err := s.customVerification.CreateRequest(ctx, domain.CustomVerificationRequest{
		VerifierBotID:   domain.VerifierBotUserID,
		ApplicantUserID: state.UserID,
		Peer:            peer,
		PeerTitle:       state.Draft[verifierDraftTargetTitle],
		PeerUsername:    state.Draft[verifierDraftTargetUsername],
		Reason:          reason,
		// RequestedDescription is deliberately empty: the mark carries the verifier's
		// own description, resolved by domain.BotVerifierSettings.DescriptionFor when the
		// operator grants it. Freezing today's text into the application would let the
		// granted mark drift from what the verifier actually says.
		Status:        domain.CustomVerificationPending,
		CorrelationID: correlation,
	})
	if errors.Is(err, domain.ErrCustomVerificationRequestExists) {
		// Someone (another device, or this dialog after a lost reply) already filed it.
		// Adopt that application instead of reporting a refusal for something the
		// applicant actually got.
		if pending, found := s.verifierPendingRequest(ctx, peer); found {
			state.Step = verifierStepDone
			state.Draft[verifierDraftRequestID] = strconv.FormatInt(pending.ID, 10)
			if !s.saveVerifierState(ctx, state) {
				return internalReply()
			}
			return botReply{Text: verifierFiledText(pending.ID, label)}
		}
	}
	if err != nil {
		return s.verifierErrorReply(state.UserID, "create request", err)
	}
	state.Step = verifierStepDone
	state.Draft[verifierDraftRequestID] = strconv.FormatInt(created.ID, 10)
	if !s.saveVerifierState(ctx, state) {
		return internalReply()
	}
	return botReply{Text: verifierFiledText(created.ID, label)}
}

// cancelVerifierDialog drops the dialog. It cannot withdraw an application that is
// already with the operator, and says so rather than implying otherwise.
func (s *Service) cancelVerifierDialog(ctx context.Context, userID int64, state domain.BotChatState, found bool) botReply {
	if !found {
		return botReply{Text: verifierNothingToCancelText}
	}
	filed := verifierDraftInt(state, verifierDraftRequestID)
	s.deleteVerifierState(ctx, userID)
	if filed > 0 && state.Step == verifierStepDone {
		return botReply{Text: fmt.Sprintf("Dropped. Application #%d is already with the operator, so it stays in the queue -- send /status to follow it.", filed)}
	}
	return botReply{Text: "Dropped, nothing was filed. Send /verify when you want to apply."}
}

// ---------------------------------------------------------------------------
// Flow: /status
// ---------------------------------------------------------------------------

func (s *Service) verifierStatusReply(ctx context.Context, userID int64) botReply {
	requests, err := s.customVerification.ApplicantRequests(ctx, userID, verifierStatusListLimit)
	if err != nil {
		return s.verifierErrorReply(userID, "list requests", err)
	}
	if len(requests) == 0 {
		return botReply{Text: verifierNoRequestsText}
	}
	var b strings.Builder
	b.WriteString("Your third-party verification applications:")
	live := 0
	for _, req := range requests {
		label := verifierPeerLabel(req.PeerTitle, req.PeerUsername, req.Peer)
		b.WriteString("\n\n#")
		b.WriteString(strconv.FormatInt(req.ID, 10))
		b.WriteString(" - ")
		b.WriteString(label)
		b.WriteString("\nStatus: ")
		b.WriteString(verifierStatusLabel(req.Status))
		if date := verifierDateLabel(req); date != "" {
			b.WriteString(" (")
			b.WriteString(date)
			b.WriteString(")")
		}
		// Only DecisionReason is ever shown: it is the text written to be read by the
		// applicant. req.InternalNote is the operator's private note and must never
		// appear in a bot message.
		if req.Status == domain.CustomVerificationRejected || req.Status == domain.CustomVerificationRevoked {
			if reason := strings.TrimSpace(req.DecisionReason); reason != "" {
				b.WriteString("\nReason: ")
				b.WriteString(reason)
			}
		}
		if req.Status == domain.CustomVerificationApproved {
			// The application says "approved"; whether the mark is still on the peer is a
			// different fact, so it is read rather than inferred.
			if mark, found := s.verifierMark(ctx, req.Peer); found {
				live++
				b.WriteString("\nMark: live")
				if description := strings.TrimSpace(mark.Description); description != "" {
					b.WriteString(" -- ")
					b.WriteString(verifierTruncate(description, 200))
				}
			} else {
				b.WriteString("\nMark: not on the peer any more")
			}
		}
	}
	if live > 0 {
		b.WriteString("\n\nSend /revoke to remove a mark.")
	} else {
		b.WriteString("\n\nSend /verify to apply for another peer.")
	}
	return botReply{Text: b.String()}
}

// ---------------------------------------------------------------------------
// Flow: /revoke
// ---------------------------------------------------------------------------

// verifierRevokePrompt renders the picker of marks this applicant can remove.
//
// The list is built from the applicant's OWN approved applications, intersected
// with the marks that are actually live. That is what authorises the removal: a
// peer nobody filed under this account can never appear here, so the picker cannot
// be used to strip a mark off somebody else's channel.
func (s *Service) verifierRevokePrompt(ctx context.Context, state domain.BotChatState, lead string) botReply {
	marked, reply, ok := s.verifierRevocable(ctx, state.UserID)
	if !ok {
		return botReply{Text: verifierJoin(lead, reply.Text)}
	}
	state.Step = verifierStepRevokePick
	verifierEnsureDraft(&state)
	rows := make([][]verifierOption, 0, len(marked)+1)
	for _, req := range marked {
		rows = append(rows, []verifierOption{{
			text:   verifierTruncate(verifierPeerLabel(req.PeerTitle, req.PeerUsername, req.Peer), 64),
			choice: verifierChoiceRevokePrefix + verifierPeerKey(req.Peer),
		}})
	}
	rows = append(rows, []verifierOption{{
		text:   verifierCancelButtonText,
		choice: verifierChoiceAbort,
		style:  domain.MarkupButtonStyleDanger,
	}})
	markup := s.verifierOptionKeyboard(&state, rows)
	if !s.saveVerifierState(ctx, state) {
		return internalReply()
	}
	return botReply{
		Text:        verifierJoin(lead, "Which mark should I remove? The icon and the description disappear from the profile, and getting them back means applying again."),
		ReplyMarkup: markup,
	}
}

// verifierRevocable returns the applicant's approved applications whose mark is
// still live, one per peer.
func (s *Service) verifierRevocable(ctx context.Context, userID int64) ([]domain.CustomVerificationRequest, botReply, bool) {
	requests, err := s.customVerification.ApplicantRequests(ctx, userID, verifierStatusListLimit)
	if err != nil {
		return nil, s.verifierErrorReply(userID, "list requests for revoke", err), false
	}
	seen := make(map[domain.Peer]struct{}, len(requests))
	out := make([]domain.CustomVerificationRequest, 0, len(requests))
	for _, req := range requests {
		if req.Status != domain.CustomVerificationApproved {
			continue
		}
		if _, duplicate := seen[req.Peer]; duplicate {
			continue
		}
		if _, found := s.verifierMark(ctx, req.Peer); !found {
			continue
		}
		seen[req.Peer] = struct{}{}
		out = append(out, req)
		if len(out) >= verifierMaxTargetButtons {
			break
		}
	}
	if len(out) == 0 {
		return nil, botReply{Text: verifierNothingToRevokeText}, false
	}
	return out, botReply{}, true
}

// chooseVerifierRevokeTarget asks for confirmation before anything is removed.
func (s *Service) chooseVerifierRevokeTarget(ctx context.Context, state domain.BotChatState, payload string) botReply {
	peer, ok := verifierParsePeer(payload)
	if !ok {
		s.log.Warn("verifierbot: malformed revoke choice",
			zap.Int64("user_id", state.UserID), zap.String("payload", payload))
		return botReply{Text: verifierExpiredButtonText}
	}
	marked, reply, ok := s.verifierRevocable(ctx, state.UserID)
	if !ok {
		return reply
	}
	var chosen domain.CustomVerificationRequest
	for _, req := range marked {
		if req.Peer == peer {
			chosen = req
		}
	}
	if chosen.ID == 0 {
		return botReply{Text: verifierNothingToRevokeText}
	}
	verifierEnsureDraft(&state)
	state.Step = verifierStepRevokeConfirm
	markup := s.verifierOptionKeyboard(&state, [][]verifierOption{
		{{
			text:   verifierRevokeButtonText,
			choice: verifierChoiceRevokeCommitPrefix + verifierPeerKey(peer),
			style:  domain.MarkupButtonStyleDanger,
		}},
		{{text: verifierRevokeCancelButtonText, choice: verifierChoiceAbort}},
	})
	if !s.saveVerifierState(ctx, state) {
		return internalReply()
	}
	return botReply{
		Text: fmt.Sprintf("Remove my mark from %s?\n\nThe icon before the name and the description in the profile go away immediately. Application #%d stays in your history as revoked, and a new mark would need a new application.",
			verifierPeerLabel(chosen.PeerTitle, chosen.PeerUsername, peer), chosen.ID),
		ReplyMarkup: markup,
	}
}

// commitVerifierRevoke removes the mark from the peer the pressed button was
// rendered for.
//
// A repeat press replays the same answer: the removed peer is recorded in the
// dialog together with the label it was reported under. A press whose peer is not
// the recorded one is not a replay and goes through the authorisation check again,
// so a stale confirmation can only ever be refused -- never applied to a peer the
// applicant did not confirm.
func (s *Service) commitVerifierRevoke(ctx context.Context, state domain.BotChatState, payload string) botReply {
	if state.Step == verifierStepDone && payload != "" && state.Draft[verifierDraftRevoked] == payload {
		return botReply{Text: verifierRevokedText(state.Draft[verifierDraftRevokedLabel])}
	}
	peer, ok := verifierParsePeer(payload)
	if !ok {
		s.log.Warn("verifierbot: malformed revoke commit",
			zap.Int64("user_id", state.UserID), zap.String("payload", payload))
		return botReply{Text: verifierExpiredButtonText}
	}
	// Re-authorise at the moment of the write: the picker's list is the only thing
	// that says this peer is the applicant's, and it was rendered some time ago.
	marked, reply, ok := s.verifierRevocable(ctx, state.UserID)
	if !ok {
		return reply
	}
	var chosen domain.CustomVerificationRequest
	for _, req := range marked {
		if req.Peer == peer {
			chosen = req
		}
	}
	if chosen.ID == 0 {
		return botReply{Text: verifierNothingToRevokeText}
	}
	label := verifierPeerLabel(chosen.PeerTitle, chosen.PeerUsername, peer)
	// The mark carries no revocation audit column, so the actor and the reason are
	// logged here rather than pretended into the store's signature.
	s.log.Info("verifierbot: applicant removed own mark",
		zap.Int64("user_id", state.UserID),
		zap.String("peer_type", string(peer.Type)),
		zap.Int64("peer_id", peer.ID))
	removed, err := s.customVerification.RevokeMark(ctx, domain.VerifierBotUserID, peer)
	if err != nil {
		return s.verifierErrorReply(state.UserID, "revoke mark", err)
	}
	if !removed {
		// The mark went away between the picker and this press. Nothing is recorded as
		// removed by this dialog, so a repeat press re-checks rather than replaying a
		// removal that never happened here.
		return botReply{Text: fmt.Sprintf("There was no mark left on %s, so nothing changed.", label)}
	}
	verifierEnsureDraft(&state)
	state.Step = verifierStepDone
	state.Draft[verifierDraftRevoked] = payload
	state.Draft[verifierDraftRevokedLabel] = label
	if !s.saveVerifierState(ctx, state) {
		return internalReply()
	}
	return botReply{Text: verifierRevokedText(label)}
}

func verifierRevokedText(label string) string {
	if strings.TrimSpace(label) == "" {
		label = "that peer"
	}
	return fmt.Sprintf("My mark is removed from %s: the icon and the description are gone from the profile. Send /verify if you ever want to apply again.", label)
}

// ---------------------------------------------------------------------------
// Step rendering
// ---------------------------------------------------------------------------

// verifierAdvance moves the dialog to step and renders that step's prompt. lead is
// an optional acknowledgement of what was just accepted.
func (s *Service) verifierAdvance(ctx context.Context, state domain.BotChatState, settings domain.BotVerifierSettings, step, lead string) botReply {
	state.Step = step
	verifierEnsureDraft(&state)
	var reply botReply
	switch step {
	case verifierStepTarget:
		return s.verifierTargetPrompt(ctx, state, settings, lead)
	case verifierStepReason:
		markup := s.verifierOptionKeyboard(&state, [][]verifierOption{{
			{text: verifierCancelButtonText, choice: verifierChoiceAbort, style: domain.MarkupButtonStyleDanger},
		}})
		reply = botReply{Text: verifierJoin(lead, verifierReasonPrompt(settings, verifierDraftTargetLabel(state))), ReplyMarkup: markup}
	case verifierStepConfirm:
		if state.Draft[verifierDraftCorrelation] == "" {
			state.Draft[verifierDraftCorrelation] = s.verifierCorrelationID(state.UserID)
		}
		markup := s.verifierOptionKeyboard(&state, [][]verifierOption{
			{{text: verifierConfirmButtonText, choice: verifierChoiceConfirm, style: domain.MarkupButtonStyleSuccess}},
			{{text: verifierCancelButtonText, choice: verifierChoiceAbort, style: domain.MarkupButtonStyleDanger}},
		})
		reply = botReply{Text: verifierJoin(lead, verifierSummaryText(state, settings)), ReplyMarkup: markup}
	default:
		s.log.Error("verifierbot: advance to unknown step",
			zap.Int64("user_id", state.UserID), zap.String("step", step))
		return internalReply()
	}
	if !s.saveVerifierState(ctx, state) {
		return internalReply()
	}
	return reply
}

func (s *Service) verifierStepReminder(state domain.BotChatState) botReply {
	switch state.Step {
	case verifierStepReason:
		return botReply{Text: fmt.Sprintf("I am waiting for the reason, in one message, between %d and %d characters.",
			verifierMinReasonLength, domain.MaxCustomVerificationReasonLength)}
	case verifierStepTarget, verifierStepConfirm, verifierStepRevokePick, verifierStepRevokeConfirm:
		return botReply{Text: verifierPickButtonsText}
	default:
		return botReply{Text: verifierBotIdleText}
	}
}

func verifierReasonPrompt(settings domain.BotVerifierSettings, label string) string {
	company := strings.TrimSpace(settings.CompanyName)
	if company == "" {
		company = "this verifier"
	}
	return fmt.Sprintf("Now tell me in one message why %s should vouch for %s: who is behind it, what it is publicly known for, and anything an operator can check. Between %d and %d characters.",
		company, label, verifierMinReasonLength, domain.MaxCustomVerificationReasonLength)
}

func verifierSummaryText(state domain.BotChatState, settings domain.BotVerifierSettings) string {
	var b strings.Builder
	b.WriteString("Here is what I will file. Nothing reaches the operator until you tap ")
	b.WriteString(verifierConfirmButtonText)
	b.WriteString(".\n\nVerifier: ")
	b.WriteString(strings.TrimSpace(settings.CompanyName))
	b.WriteString("\nSubject: ")
	b.WriteString(verifierDraftTargetLabel(state))
	b.WriteString("\nThe mark it would carry: ")
	b.WriteString(verifierDescriptionLine(settings))
	b.WriteString("\n\nWhy:\n")
	b.WriteString(state.Draft[verifierDraftReason])
	b.WriteString("\n\nThis is a third-party mark, not the official ")
	b.WriteString(branding.ProductName)
	b.WriteString(" checkmark, and I do not decide: an operator reads the application and either grants the mark or refuses it. I will message you here either way.")
	return b.String()
}

func verifierFiledText(requestID int64, label string) string {
	return fmt.Sprintf("Application #%d is filed for %s.\n\nAn operator reads it by hand -- I cannot grant my own mark. Send /status any time to see where it stands, and I will message you here as soon as it is decided.",
		requestID, label)
}

// ---------------------------------------------------------------------------
// Applicant notifications (botverification.ApplicantNotifier)
// ---------------------------------------------------------------------------

// SendVerificationDecision delivers one operator decision as an ordinary
// @verifierbot message, so it lands in the applicant's history and dialog list like
// any other message. Returning an error keeps the queued notification pending for
// the next cycle.
func (s *Service) SendVerificationDecision(ctx context.Context, recipientUserID int64, req domain.CustomVerificationRequest) error {
	if s == nil || s.messages == nil {
		return fmt.Errorf("custom verification decision: bots service is not configured")
	}
	if recipientUserID <= 0 {
		return fmt.Errorf("custom verification decision: recipient is empty")
	}
	text, ok := verifierDecisionText(req)
	if !ok {
		return fmt.Errorf("custom verification decision: nothing to report for request %d in status %q", req.ID, req.Status)
	}
	mu := s.serviceBotReplyLock(domain.VerifierBotUserID, recipientUserID)
	mu.Lock()
	defer mu.Unlock()
	if _, sent := s.sendServiceBotReplyResult(ctx, domain.VerifierBotUserID, recipientUserID, botReply{Text: text}); !sent {
		return fmt.Errorf("custom verification decision: deliver status %q for request %d", req.Status, req.ID)
	}
	return nil
}

// verifierDecisionText renders one decision for the applicant.
//
// req.InternalNote is NEVER rendered here, under any status: it is the operator's
// private note, kept for the audit trail and the admin panel only. The single field
// that reaches the applicant is req.DecisionReason, which exists precisely because
// it was written to be read by them.
func verifierDecisionText(req domain.CustomVerificationRequest) (string, bool) {
	label := verifierPeerLabel(req.PeerTitle, req.PeerUsername, req.Peer)
	switch req.Status {
	case domain.CustomVerificationApproved:
		return fmt.Sprintf("Application #%d is approved: %s now carries my mark -- my icon before the name and my description in the profile.\n\nThis is a third-party mark, not the official %s checkmark. Send /revoke if you ever want it removed.",
			req.ID, label, branding.ProductName), true
	case domain.CustomVerificationRejected:
		text := fmt.Sprintf("Application #%d for %s was not approved, so no mark was granted.", req.ID, label)
		if reason := strings.TrimSpace(req.DecisionReason); reason != "" {
			text += "\n\nReason: " + reason
		}
		return text + "\n\nYou can apply again with /verify once the reason no longer applies.", true
	case domain.CustomVerificationRevoked:
		text := fmt.Sprintf("My mark has been taken off %s (application #%d): the icon and the description are no longer shown.", label, req.ID)
		if reason := strings.TrimSpace(req.DecisionReason); reason != "" {
			text += "\n\nReason: " + reason
		}
		return text, true
	default:
		// Pending is not a decision, and an unmodelled status is not one either: report
		// it instead of delivering a message that says nothing.
		return "", false
	}
}

// ---------------------------------------------------------------------------
// Button tokens
// ---------------------------------------------------------------------------

// verifierOptionKeyboard renders one inline keyboard and records its buttons in the
// per-user token table.
//
// SECURITY: callback data never carries a peer id, a peer type, an application id
// or anything else the server would have to trust. Every button's data is
// verifierCallbackDataPrefix plus a freshly generated random token, and that token
// is meaningful only as a key into the token table of *this* applicant's own
// domain.BotChatState. A press is therefore incapable of naming a peer: the server
// resolves the choice from state it wrote itself when it rendered the keyboard, and
// then re-resolves that choice against the applicant's own peers before acting. A
// client that replays or fabricates callback data can at best hit a token absent
// from its own table, which is refused -- so forging a choice for somebody else's
// channel is impossible by construction, not by validation.
//
// Tokens are minted afresh on every render and kept for verifierTokenGenerations
// renders. That window is what makes a second press of the same button resolve to
// the same choice (the handlers are idempotent, so the reply repeats) while the
// table stays bounded.
func (s *Service) verifierOptionKeyboard(state *domain.BotChatState, rows [][]verifierOption) *domain.MessageReplyMarkup {
	if state == nil || len(rows) == 0 {
		return nil
	}
	verifierEnsureDraft(state)
	generation := verifierDraftInt(*state, verifierDraftGeneration) + 1
	state.Draft[verifierDraftGeneration] = strconv.FormatInt(generation, 10)
	verifierPruneOptions(state, generation)
	markup := &domain.MessageReplyMarkup{Type: domain.MessageReplyMarkupInline}
	for _, row := range rows {
		buttons := make([]domain.MarkupButton, 0, len(row))
		for _, option := range row {
			if option.text == "" || option.choice == "" {
				continue
			}
			token := s.verifierOptionToken()
			state.Draft[verifierDraftOptionPrefix+token] = strconv.FormatInt(generation, 10) + "|" + option.choice
			buttons = append(buttons, domain.MarkupButton{
				Type:  domain.MarkupButtonCallback,
				Text:  option.text,
				Style: option.style,
				Data:  []byte(verifierCallbackDataPrefix + token),
			})
		}
		if len(buttons) > 0 {
			markup.Inline = append(markup.Inline, buttons)
		}
	}
	if len(markup.Inline) == 0 {
		return nil
	}
	return markup
}

// verifierOptionToken mints one opaque button token.
func (s *Service) verifierOptionToken() string {
	var buf [verifierOptionTokenBytes]byte
	if _, err := rand.Read(buf[:]); err == nil {
		return hex.EncodeToString(buf[:])
	}
	// A crypto/rand failure must not brick the dialog. Unpredictability is defence in
	// depth here rather than the load-bearing property -- a token is only ever
	// resolved against the caller's own chat state, and the RPC edge additionally
	// requires the data to appear in a keyboard of a message in the caller's own box
	// -- so a monotonic fallback is safe.
	return strconv.FormatInt(s.now().UnixNano()+s.replySeq.Add(1), 36)
}

// verifierCorrelationID mints the per-attempt idempotency key handed to the
// service with an application.
func (s *Service) verifierCorrelationID(userID int64) string {
	return "verifierbot:" + strconv.FormatInt(userID, 10) + ":" + s.verifierOptionToken()
}

// verifierResolveOption maps callback data back onto the choice recorded for it.
// Anything that is not in this user's own table is refused.
func verifierResolveOption(state domain.BotChatState, data []byte) (string, bool) {
	raw := string(data)
	if !strings.HasPrefix(raw, verifierCallbackDataPrefix) {
		return "", false
	}
	token := raw[len(verifierCallbackDataPrefix):]
	if token == "" || len(token) > verifierOptionTokenMaxLen {
		return "", false
	}
	value, found := state.Draft[verifierDraftOptionPrefix+token]
	if !found {
		return "", false
	}
	_, choice, split := strings.Cut(value, "|")
	if !split || choice == "" {
		return "", false
	}
	return choice, true
}

// verifierPruneOptions drops tokens older than the retained window.
func verifierPruneOptions(state *domain.BotChatState, generation int64) {
	oldest := generation - verifierTokenGenerations + 1
	for key, value := range state.Draft {
		if !strings.HasPrefix(key, verifierDraftOptionPrefix) {
			continue
		}
		rawGen, _, _ := strings.Cut(value, "|")
		gen, err := strconv.ParseInt(rawGen, 10, 64)
		if err != nil || gen < oldest {
			delete(state.Draft, key)
		}
	}
}

// ---------------------------------------------------------------------------
// Service lookups
// ---------------------------------------------------------------------------

// verifierTargetSource resolves the peer enumeration. An explicitly injected
// source wins; otherwise the official verification service is used purely as a
// directory of the applicant's own peers (see verifierBotTargets on why its
// eligibility verdicts are ignored).
func (s *Service) verifierTargetSource() verifierBotTargets {
	if s == nil {
		return nil
	}
	if s.verifierTargets != nil {
		return s.verifierTargets
	}
	if s.verification != nil {
		return s.verification
	}
	return nil
}

// verifierPendingRequest reports the live application on a peer, if any.
func (s *Service) verifierPendingRequest(ctx context.Context, peer domain.Peer) (domain.CustomVerificationRequest, bool) {
	req, err := s.customVerification.PendingRequest(ctx, domain.VerifierBotUserID, peer)
	switch {
	case errors.Is(err, domain.ErrCustomVerificationRequestNotFound):
		return domain.CustomVerificationRequest{}, false
	case err != nil:
		s.log.Warn("verifierbot: read pending request",
			zap.String("peer_type", string(peer.Type)), zap.Int64("peer_id", peer.ID), zap.Error(err))
		return domain.CustomVerificationRequest{}, false
	}
	if req.ID <= 0 || req.Peer != peer || req.Status != domain.CustomVerificationPending {
		return domain.CustomVerificationRequest{}, false
	}
	return req, true
}

// verifierMark reports whether this verifier's mark is live on a peer. The filter
// result is re-checked rather than trusted, so a store that ignores a filter field
// cannot make the bot claim a mark on the wrong peer.
func (s *Service) verifierMark(ctx context.Context, peer domain.Peer) (domain.CustomVerification, bool) {
	marks, err := s.customVerification.Marks(ctx, domain.CustomVerificationFilter{
		VerifierBotID: domain.VerifierBotUserID,
		PeerType:      peer.Type,
		PeerID:        peer.ID,
		Limit:         1,
	})
	if err != nil {
		s.log.Warn("verifierbot: read mark",
			zap.String("peer_type", string(peer.Type)), zap.Int64("peer_id", peer.ID), zap.Error(err))
		return domain.CustomVerification{}, false
	}
	for _, mark := range marks {
		if mark.VerifierBotID == domain.VerifierBotUserID && mark.Peer == peer {
			return mark, true
		}
	}
	return domain.CustomVerification{}, false
}

// ---------------------------------------------------------------------------
// State helpers
// ---------------------------------------------------------------------------

func verifierNewState(userID int64) domain.BotChatState {
	return domain.BotChatState{
		BotUserID: domain.VerifierBotUserID,
		UserID:    userID,
		Command:   verifierBotCommand,
		Step:      verifierStepIntro,
		Draft:     map[string]string{},
	}
}

func verifierEnsureDraft(state *domain.BotChatState) {
	if state.Draft == nil {
		state.Draft = map[string]string{}
	}
	if state.BotUserID == 0 {
		state.BotUserID = domain.VerifierBotUserID
	}
	if state.Command == "" {
		state.Command = verifierBotCommand
	}
}

func (s *Service) saveVerifierState(ctx context.Context, state domain.BotChatState) bool {
	verifierEnsureDraft(&state)
	state.BotUserID = domain.VerifierBotUserID
	clone := domain.BotChatState{
		BotUserID: state.BotUserID,
		UserID:    state.UserID,
		Command:   state.Command,
		Step:      state.Step,
		Draft:     make(map[string]string, len(state.Draft)),
	}
	for key, value := range state.Draft {
		clone.Draft[key] = value
	}
	if err := s.bots.UpsertBotChatState(ctx, clone); err != nil {
		s.log.Error("verifierbot: save chat state", zap.Int64("user_id", state.UserID), zap.Error(err))
		return false
	}
	return true
}

func (s *Service) deleteVerifierState(ctx context.Context, userID int64) {
	if err := s.bots.DeleteBotChatState(ctx, domain.VerifierBotUserID, userID); err != nil {
		s.log.Error("verifierbot: delete chat state", zap.Int64("user_id", userID), zap.Error(err))
	}
}

func verifierDraftInt(state domain.BotChatState, key string) int64 {
	value, err := strconv.ParseInt(strings.TrimSpace(state.Draft[key]), 10, 64)
	if err != nil {
		return 0
	}
	return value
}

// verifierDraftTargetOf reads back the chosen subject. The stored form is the
// verification target kind plus its id, so the peer namespace is derived by the
// domain rather than remembered separately.
func verifierDraftTargetOf(state domain.BotChatState) (domain.VerificationTarget, bool) {
	kind, rawID, split := strings.Cut(state.Draft[verifierDraftTarget], ":")
	if !split {
		return domain.VerificationTarget{}, false
	}
	id, err := strconv.ParseInt(rawID, 10, 64)
	targetType := domain.VerificationTargetType(kind)
	if err != nil || id <= 0 || !targetType.Valid() {
		return domain.VerificationTarget{}, false
	}
	return domain.VerificationTarget{
		Type:     targetType,
		ID:       id,
		Title:    state.Draft[verifierDraftTargetTitle],
		Username: state.Draft[verifierDraftTargetUsername],
	}, true
}

func verifierDraftTargetLabel(state domain.BotChatState) string {
	target, ok := verifierDraftTargetOf(state)
	if !ok {
		return "the selected subject"
	}
	return verifierPeerLabel(target.Title, target.Username, verifierTargetPeer(target))
}

// verifierPeerKey renders a peer for the token table: the two peer namespaces a
// mark can live in, and an id. It never reaches a client -- only the random token
// standing for it does.
func verifierPeerKey(peer domain.Peer) string {
	return string(peer.Type) + ":" + strconv.FormatInt(peer.ID, 10)
}

// verifierParsePeer reads a verifierPeerKey back. It accepts only the two peer
// namespaces a mark can live in.
func verifierParsePeer(payload string) (domain.Peer, bool) {
	kind, rawID, split := strings.Cut(payload, ":")
	if !split {
		return domain.Peer{}, false
	}
	id, err := strconv.ParseInt(rawID, 10, 64)
	if err != nil || id <= 0 {
		return domain.Peer{}, false
	}
	peerType := domain.PeerType(kind)
	if peerType != domain.PeerTypeUser && peerType != domain.PeerTypeChannel {
		return domain.Peer{}, false
	}
	return domain.Peer{Type: peerType, ID: id}, true
}

// ---------------------------------------------------------------------------
// Rendering helpers
// ---------------------------------------------------------------------------

// verifierPeerLabel renders a subject for humans. The username is the identity
// that matters, the title is the context, and the peer is the last resort so a
// message never says "the selected peer" when it can name one.
func verifierPeerLabel(title, username string, peer domain.Peer) string {
	title = strings.TrimSpace(title)
	username = strings.TrimSpace(username)
	switch {
	case username != "" && title != "":
		return verifierTruncate(title, 64) + " (@" + username + ")"
	case username != "":
		return "@" + username
	case title != "":
		return verifierTruncate(title, 64)
	case peer.Type == domain.PeerTypeChannel && peer.ID > 0:
		return "channel " + strconv.FormatInt(peer.ID, 10)
	case peer.Type == domain.PeerTypeUser && peer.ID > 0:
		return "account " + strconv.FormatInt(peer.ID, 10)
	default:
		return "the selected peer"
	}
}

func verifierTargetButtonText(target domain.VerificationTarget) string {
	label := strings.TrimSpace(target.Username)
	if label != "" {
		label = "@" + label
	} else {
		label = strings.TrimSpace(target.Title)
	}
	if label == "" {
		label = "id " + strconv.FormatInt(target.ID, 10)
	}
	return verifierTargetKindLabel(target.Type) + ": " + verifierTruncate(label, 64)
}

func verifierTargetKindLabel(kind domain.VerificationTargetType) string {
	switch kind {
	case domain.VerificationTargetBot:
		return "Bot"
	case domain.VerificationTargetChannel:
		return "Channel"
	case domain.VerificationTargetSupergroup:
		return "Group"
	case domain.VerificationTargetUser:
		return "Account"
	default:
		return "Subject"
	}
}

func verifierStatusLabel(status domain.CustomVerificationRequestStatus) string {
	switch status {
	case domain.CustomVerificationPending:
		return "waiting for an operator"
	case domain.CustomVerificationApproved:
		return "approved, the mark was granted"
	case domain.CustomVerificationRejected:
		return "not approved"
	case domain.CustomVerificationRevoked:
		return "the mark was taken away"
	default:
		return string(status)
	}
}

func verifierDateLabel(req domain.CustomVerificationRequest) string {
	switch {
	case !req.ApprovedAt.IsZero():
		return "granted " + req.ApprovedAt.UTC().Format("2006-01-02")
	case !req.RejectedAt.IsZero():
		return "decided " + req.RejectedAt.UTC().Format("2006-01-02")
	case !req.CreatedAt.IsZero():
		return "filed " + req.CreatedAt.UTC().Format("2006-01-02")
	default:
		return ""
	}
}

func verifierJoin(lead, body string) string {
	lead = strings.TrimSpace(lead)
	if lead == "" {
		return body
	}
	if strings.TrimSpace(body) == "" {
		return lead
	}
	return lead + "\n\n" + body
}

func verifierTruncate(value string, max int) string {
	if max <= 0 || utf8.RuneCountInString(value) <= max {
		return value
	}
	runes := []rune(value)
	return string(runes[:max])
}

// ---------------------------------------------------------------------------
// Error mapping
// ---------------------------------------------------------------------------

func (s *Service) verifierErrorReply(userID int64, operation string, err error) botReply {
	if text, ok := verifierPolicyText(err); ok {
		return botReply{Text: text}
	}
	s.log.Error("verifierbot: "+operation, zap.Int64("user_id", userID), zap.Error(err))
	return internalReply()
}

// verifierPolicyText turns a policy refusal into a sentence the applicant can act
// on. Anything that is not a policy error is an internal fault and is logged
// instead of being narrated.
func verifierPolicyText(err error) (string, bool) {
	switch {
	case err == nil:
		return "", false
	case errors.Is(err, domain.ErrVerifierNotFound), errors.Is(err, domain.ErrVerifierForbidden),
		errors.Is(err, domain.ErrVerifierSettingsInvalid):
		return verifierNotActivatedText, true
	case errors.Is(err, domain.ErrVerificationIconNotFound), errors.Is(err, domain.ErrVerificationIconInactive),
		errors.Is(err, domain.ErrVerificationIconInvalid):
		return "My icon is not usable right now, so I cannot mark anything. The operator has to fix that before I can take applications.", true
	case errors.Is(err, domain.ErrCustomVerificationLimit):
		return "I have marked as many peers as I am allowed to, so I cannot take another application until the operator raises the limit.", true
	case errors.Is(err, domain.ErrCustomVerificationRequestExists):
		return "There is already an application waiting for that one. Send /status to see it.", true
	case errors.Is(err, domain.ErrCustomVerificationTargetInvalid):
		return "That one cannot carry my mark. I can verify a bot, a channel or supergroup, or an account.", true
	case errors.Is(err, domain.ErrCustomVerificationNotFound):
		return "There is no mark of mine on that one, so there is nothing to remove.", true
	case errors.Is(err, domain.ErrCustomVerificationRequestNotFound):
		return "I cannot find that application any more. Send /verify to file a fresh one.", true
	case errors.Is(err, domain.ErrCustomVerificationRequestInvalid):
		return "I could not accept that. Send /help to see what an application needs.", true
	case errors.Is(err, domain.ErrCustomVerificationVersionConflict):
		return "That application just changed somewhere else. Send /status to see where it stands now.", true
	case errors.Is(err, domain.ErrVerifierDescriptionForbidden):
		return "I may only apply my own description, so I cannot take a custom one for your peer.", true
	default:
		return "", false
	}
}