feat(telegram): chat-gate observability + grant on first registration

Two follow-ups from a contour test where a user joined the chat, then
registered, and got no write access — with silent logs.

Observability: log every chat_member update (chat id, configured id, user,
old->new status), the eligibility result and the grant outcome; plus a startup
self-check that warns loudly when the bot is not an administrator in the chat
with the restrict-members ("Ban users") right — the common misconfiguration,
previously invisible in the logs.

Grant on first registration: a user who joins the moderated chat BEFORE
registering is covered by no chat_member event, so the join-time grant never
fires for them. ProvisionTelegram now reports first contact, and the Telegram
auth handler emits chat_access_changed on it, so the gateway re-evaluates and
grants write access if the user is already in the chat.

backend/internal/account/account.go

@@ -151,14 +151,26 @@ func (s *Store) ProvisionRobot(ctx context.Context, externalID, displayName stri
 	return modelToAccount(row), nil
 }
 
-// ProvisionTelegram provisions (or finds) the account bound to a Telegram
-// identity. On first contact only, it seeds the new account's preferred language
-// from the Telegram client languageCode (when it maps to a supported language) and
-// its display name sanitized from firstName (falling back to username, then to a
-// generated placeholder when neither yields any letters); an already-existing
-// account is returned unchanged, so a later profile edit is never overwritten.
-func (s *Store) ProvisionTelegram(ctx context.Context, externalID, languageCode, username, firstName string) (Account, error) {
-	return s.provision(ctx, KindTelegram, externalID, telegramSeed(languageCode, username, firstName))
+// ProvisionTelegram provisions (or finds) the account bound to a Telegram identity,
+// reporting whether this call created it (first contact). On first contact only, it
+// seeds the new account's preferred language from the Telegram client languageCode
+// (when it maps to a supported language) and its display name sanitized from firstName
+// (falling back to username, then to a generated placeholder when neither yields any
+// letters); an already-existing account is returned unchanged, so a later profile edit
+// is never overwritten. The created flag lets the auth handler re-evaluate moderated-
+// chat write access on first registration — the path of a user who joined the chat
+// before registering, whom no chat_member event covers.
+func (s *Store) ProvisionTelegram(ctx context.Context, externalID, languageCode, username, firstName string) (Account, bool, error) {
+	// Pre-check whether the identity already exists so the caller can act on first
+	// contact. A race with a concurrent create only over- or under-reports created for
+	// that one call, which the idempotent chat-access re-evaluation tolerates.
+	_, err := s.findByIdentity(ctx, KindTelegram, externalID)
+	created := errors.Is(err, ErrNotFound)
+	if err != nil && !created {
+		return Account{}, false, err
+	}
+	acc, err := s.provision(ctx, KindTelegram, externalID, telegramSeed(languageCode, username, firstName))
+	return acc, created, err
 }
 
 // provision finds the account for (kind, externalID) or creates it with seed,

backend/internal/inttest/account_test.go

@@ -118,10 +118,13 @@ func TestProvisionTelegramSeedsNewAccountOnly(t *testing.T) {
 	store := account.NewStore(testDB)
 	ext := "tg-" + uuid.NewString()
 
-	acc, err := store.ProvisionTelegram(ctx, ext, "ru-RU", "thehandle", "Иван")
+	acc, created, err := store.ProvisionTelegram(ctx, ext, "ru-RU", "thehandle", "Иван")
 	if err != nil {
 		t.Fatalf("provision telegram: %v", err)
 	}
+	if !created {
+		t.Error("created = false on first contact, want true")
+	}
 	if acc.PreferredLanguage != "ru" {
 		t.Errorf("PreferredLanguage = %q, want ru", acc.PreferredLanguage)
 	}
@@ -133,10 +136,13 @@ func TestProvisionTelegramSeedsNewAccountOnly(t *testing.T) {
 	}
 
 	// A later login with different fields returns the same account, unchanged.
-	again, err := store.ProvisionTelegram(ctx, ext, "en", "other", "Other")
+	again, created, err := store.ProvisionTelegram(ctx, ext, "en", "other", "Other")
 	if err != nil {
 		t.Fatalf("re-provision telegram: %v", err)
 	}
+	if created {
+		t.Error("created = true on a repeat login, want false")
+	}
 	if again.ID != acc.ID {
 		t.Errorf("re-provision id = %s, want %s", again.ID, acc.ID)
 	}
@@ -150,7 +156,7 @@ func TestProvisionTelegramSeedsNewAccountOnly(t *testing.T) {
 // language CHECK.
 func TestProvisionTelegramUnknownLanguageDefaults(t *testing.T) {
 	ctx := context.Background()
-	acc, err := account.NewStore(testDB).ProvisionTelegram(ctx, "tg-"+uuid.NewString(), "fr", "", "")
+	acc, _, err := account.NewStore(testDB).ProvisionTelegram(ctx, "tg-"+uuid.NewString(), "fr", "", "")
 	if err != nil {
 		t.Fatalf("provision telegram: %v", err)
 	}
@@ -166,7 +172,7 @@ func TestProvisionTelegramUnknownLanguageDefaults(t *testing.T) {
 func TestHighRateFlagRoundTrip(t *testing.T) {
 	ctx := context.Background()
 	store := account.NewStore(testDB)
-	acc, err := store.ProvisionTelegram(ctx, "tg-"+uuid.NewString(), "en", "", "Player")
+	acc, _, err := store.ProvisionTelegram(ctx, "tg-"+uuid.NewString(), "en", "", "Player")
 	if err != nil {
 		t.Fatalf("provision telegram: %v", err)
 	}
@@ -222,7 +228,7 @@ func TestIdentityExternalID(t *testing.T) {
 	ctx := context.Background()
 	store := account.NewStore(testDB)
 	ext := "tg-" + uuid.NewString()
-	acc, err := store.ProvisionTelegram(ctx, ext, "en", "", "Tg User")
+	acc, _, err := store.ProvisionTelegram(ctx, ext, "en", "", "Tg User")
 	if err != nil {
 		t.Fatalf("provision telegram: %v", err)
 	}
@@ -247,7 +253,7 @@ func TestIdentityExternalID(t *testing.T) {
 func TestNotificationsInAppOnlyRoundTrip(t *testing.T) {
 	ctx := context.Background()
 	store := account.NewStore(testDB)
-	acc, err := store.ProvisionTelegram(ctx, "tg-"+uuid.NewString(), "en", "", "Player")
+	acc, _, err := store.ProvisionTelegram(ctx, "tg-"+uuid.NewString(), "en", "", "Player")
 	if err != nil {
 		t.Fatalf("provision telegram: %v", err)
 	}

backend/internal/inttest/admin_test.go

@@ -222,7 +222,7 @@ func TestConsoleGameDetailRobotSchedule(t *testing.T) {
 func TestConsoleThrottledViewAndFlagClear(t *testing.T) {
 	ctx := context.Background()
 	accounts := account.NewStore(testDB)
-	acc, err := accounts.ProvisionTelegram(ctx, "tg-"+uuid.NewString(), "en", "", "Throttled Player")
+	acc, _, err := accounts.ProvisionTelegram(ctx, "tg-"+uuid.NewString(), "en", "", "Throttled Player")
 	if err != nil {
 		t.Fatalf("provision: %v", err)
 	}

backend/internal/inttest/chat_access_test.go

@@ -18,6 +18,7 @@ import (
 	"scrabble/backend/internal/account"
 	"scrabble/backend/internal/notify"
 	"scrabble/backend/internal/server"
+	"scrabble/backend/internal/session"
 )
 
 // chatAccessBody mirrors the backend's /internal/chat-access JSON for the test.
@@ -54,7 +55,7 @@ func TestChatAccessResolver(t *testing.T) {
 	srv := server.New(":0", server.Deps{Logger: zaptest.NewLogger(t), DB: testDB, Accounts: accounts})
 
 	ext := "tg-" + uuid.NewString()
-	acc, err := accounts.ProvisionTelegram(ctx, ext, "en", "", "Chatter")
+	acc, _, err := accounts.ProvisionTelegram(ctx, ext, "en", "", "Chatter")
 	if err != nil {
 		t.Fatalf("provision: %v", err)
 	}
@@ -203,6 +204,48 @@ func TestChatAccessPublishedOnModeration(t *testing.T) {
 	}
 }
 
+// TestChatAccessPublishedOnFirstRegistration checks that a Telegram first contact
+// (the sessions/telegram endpoint creating the account) emits chat_access_changed —
+// the re-grant for a user who joined the moderated chat before registering — and that
+// a repeat login does not re-emit.
+func TestChatAccessPublishedOnFirstRegistration(t *testing.T) {
+	notifier := &captureNotifier{}
+	srv := server.New(":0", server.Deps{
+		Logger:   zaptest.NewLogger(t),
+		DB:       testDB,
+		Accounts: account.NewStore(testDB),
+		Sessions: session.NewService(session.NewStore(testDB), session.NewCache()),
+		Notifier: notifier,
+	})
+	h := srv.Handler()
+	ext := "tg-" + uuid.NewString()
+
+	post := func() {
+		rec := httptest.NewRecorder()
+		req := httptest.NewRequest(http.MethodPost, "/api/v1/internal/sessions/telegram",
+			strings.NewReader(`{"external_id":"`+ext+`","language_code":"en","first_name":"Reg"}`))
+		req.Header.Set("Content-Type", "application/json")
+		h.ServeHTTP(rec, req)
+		if rec.Code != http.StatusOK {
+			t.Fatalf("telegram auth = %d: %s", rec.Code, rec.Body.String())
+		}
+	}
+
+	post()
+	acc, err := account.NewStore(testDB).AccountByIdentity(context.Background(), account.KindTelegram, ext)
+	if err != nil {
+		t.Fatalf("lookup: %v", err)
+	}
+	if got := notifier.count(acc.ID, notify.KindChatAccessChanged); got != 1 {
+		t.Fatalf("first registration: chat_access_changed count = %d, want 1", got)
+	}
+	// A repeat login (the account already exists) must not re-emit.
+	post()
+	if got := notifier.count(acc.ID, notify.KindChatAccessChanged); got != 1 {
+		t.Fatalf("repeat login: chat_access_changed count = %d, want still 1", got)
+	}
+}
+
 // TestSuspensionsExpiredBetween checks the sweeper's window query: a non-lifted
 // temporary block whose expiry falls in the window is returned, while one outside the
 // window, a permanent block, and a lifted block are not.

backend/internal/inttest/suspension_gate_test.go

@@ -38,7 +38,7 @@ func TestSuspensionGate(t *testing.T) {
 		Accounts: accounts,
 	})
 
-	acc, err := accounts.ProvisionTelegram(ctx, "tg-"+uuid.NewString(), "ru", "", "Blocked")
+	acc, _, err := accounts.ProvisionTelegram(ctx, "tg-"+uuid.NewString(), "ru", "", "Blocked")
 	if err != nil {
 		t.Fatalf("provision: %v", err)
 	}

backend/internal/inttest/userlist_test.go

@@ -18,7 +18,7 @@ func TestUserListFilter(t *testing.T) {
 	st := account.NewStore(testDB)
 	uniq := uuid.NewString()
 
-	human, err := st.ProvisionTelegram(ctx, "tg-"+uniq, "en", "", "Zzqxhuman")
+	human, _, err := st.ProvisionTelegram(ctx, "tg-"+uniq, "en", "", "Zzqxhuman")
 	if err != nil {
 		t.Fatalf("provision human: %v", err)
 	}

backend/internal/server/handlers_auth.go

@@ -35,11 +35,17 @@ func (s *Server) handleTelegramAuth(c *gin.Context) {
 		abortBadRequest(c, "external_id is required")
 		return
 	}
-	acc, err := s.accounts.ProvisionTelegram(c.Request.Context(), req.ExternalID, req.LanguageCode, req.Username, req.FirstName)
+	acc, created, err := s.accounts.ProvisionTelegram(c.Request.Context(), req.ExternalID, req.LanguageCode, req.Username, req.FirstName)
 	if err != nil {
 		s.abortErr(c, err)
 		return
 	}
+	if created {
+		// First registration: re-evaluate moderated-chat write access, so a user who
+		// joined the chat before registering is granted on the spot (no chat_member
+		// event fires on registration).
+		s.publishChatAccessChange(acc.ID)
+	}
 	s.mintSession(c, acc)
 }