Stage 6: gateway edge (Connect/FlatBuffers over h2c, platform/email/guest auth, sessions, rate-limit, admin passthrough, live push bridge)

New public ingress and the first network edge. Framework + a vertical slice of
operations end-to-end; remaining ops reuse the same transcode pattern in Stage 7.

Contracts (new module scrabble/pkg):
- push.proto (backend->gateway gRPC server-stream) + scrabble.fbs (FlatBuffers
  edge payloads), committed generated Go; buf/flatc Makefiles (dev-time codegen).

Backend:
- REST handlers on the /api/v1 groups: internal session endpoints
  (telegram/guest/email login -> mint, resolve, revoke) and the user slice
  (profile, submit_play, state, lobby enqueue/poll, chat).
- internal/notify in-process Publisher hub + internal/pushgrpc gRPC server
  (BACKEND_GRPC_ADDR) streaming your_turn/opponent_moved/chat/nudge/match_found;
  emission in game.commit, social, matchmaker.
- migration 00005 accounts.is_guest; guests are durable rows excluded from stats;
  ProvisionGuest; email-as-login (RequestLoginCode/LoginWithCode).

Gateway (new module scrabble/gateway):
- Connect Gateway service over h2c (Execute + Subscribe), FlatBuffers<->JSON
  transcode registry, Telegram initData HMAC validator (seam), session cache,
  token-bucket rate limiter (3 classes), push fan-out hub, backend REST + push
  gRPC client, admin Basic-Auth reverse proxy.

go.work: use ./pkg, ./gateway + replace scrabble/pkg. CI: gateway/**, pkg/**
path filters; unit build/vet/test span all three modules. Docs (PLAN,
ARCHITECTURE, FUNCTIONAL+ru, TESTING, READMEs) updated; gateway/pkg unit tests +
guest/email-login integration tests.

backend/internal/server/handlers_user.go

@@ -0,0 +1,168 @@
+package server
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+
+	"scrabble/backend/internal/engine"
+)
+
+// The /api/v1/user/* endpoints require X-User-ID (RequireUserID middleware). The
+// backend treats that header as the sole identity input.
+
+// handleProfile returns the authenticated account's own profile.
+func (s *Server) handleProfile(c *gin.Context) {
+	uid, ok := userID(c)
+	if !ok {
+		abortBadRequest(c, "missing identity")
+		return
+	}
+	acc, err := s.accounts.GetByID(c.Request.Context(), uid)
+	if err != nil {
+		s.abortErr(c, err)
+		return
+	}
+	c.JSON(http.StatusOK, profileResponseFor(acc))
+}
+
+// submitPlayRequest places tiles in a direction on the player's turn.
+type submitPlayRequest struct {
+	Dir   string `json:"dir"`
+	Tiles []struct {
+		Row    int    `json:"row"`
+		Col    int    `json:"col"`
+		Letter string `json:"letter"`
+		Blank  bool   `json:"blank"`
+	} `json:"tiles"`
+}
+
+// handleSubmitPlay validates, scores and commits a placement.
+func (s *Server) handleSubmitPlay(c *gin.Context) {
+	uid, ok := userID(c)
+	if !ok {
+		abortBadRequest(c, "missing identity")
+		return
+	}
+	gameID, ok := gameIDParam(c)
+	if !ok {
+		abortBadRequest(c, "invalid game id")
+		return
+	}
+	var req submitPlayRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		abortBadRequest(c, "invalid request body")
+		return
+	}
+	dir, ok := parseDirection(req.Dir)
+	if !ok {
+		abortBadRequest(c, "dir must be H or V")
+		return
+	}
+	tiles := make([]engine.TileRecord, 0, len(req.Tiles))
+	for _, t := range req.Tiles {
+		tiles = append(tiles, engine.TileRecord{Row: t.Row, Col: t.Col, Letter: t.Letter, Blank: t.Blank})
+	}
+	res, err := s.games.SubmitPlay(c.Request.Context(), gameID, uid, dir, tiles)
+	if err != nil {
+		s.abortErr(c, err)
+		return
+	}
+	c.JSON(http.StatusOK, moveResultDTOFrom(res))
+}
+
+// handleGameState returns the player's view of a game.
+func (s *Server) handleGameState(c *gin.Context) {
+	uid, ok := userID(c)
+	if !ok {
+		abortBadRequest(c, "missing identity")
+		return
+	}
+	gameID, ok := gameIDParam(c)
+	if !ok {
+		abortBadRequest(c, "invalid game id")
+		return
+	}
+	view, err := s.games.GameState(c.Request.Context(), gameID, uid)
+	if err != nil {
+		s.abortErr(c, err)
+		return
+	}
+	c.JSON(http.StatusOK, stateDTOFrom(view))
+}
+
+// enqueueRequest joins the per-variant auto-match pool.
+type enqueueRequest struct {
+	Variant string `json:"variant"`
+}
+
+// handleEnqueue joins the auto-match pool for a variant.
+func (s *Server) handleEnqueue(c *gin.Context) {
+	uid, ok := userID(c)
+	if !ok {
+		abortBadRequest(c, "missing identity")
+		return
+	}
+	var req enqueueRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		abortBadRequest(c, "invalid request body")
+		return
+	}
+	variant, err := engine.ParseVariant(req.Variant)
+	if err != nil {
+		abortBadRequest(c, "unknown variant")
+		return
+	}
+	res, err := s.matchmaker.Enqueue(c.Request.Context(), uid, variant)
+	if err != nil {
+		s.abortErr(c, err)
+		return
+	}
+	c.JSON(http.StatusOK, matchDTOFrom(res))
+}
+
+// handlePoll reports whether the caller has been paired since queueing.
+func (s *Server) handlePoll(c *gin.Context) {
+	uid, ok := userID(c)
+	if !ok {
+		abortBadRequest(c, "missing identity")
+		return
+	}
+	res, err := s.matchmaker.Poll(c.Request.Context(), uid)
+	if err != nil {
+		s.abortErr(c, err)
+		return
+	}
+	c.JSON(http.StatusOK, matchDTOFrom(res))
+}
+
+// chatPostRequest posts a per-game chat message.
+type chatPostRequest struct {
+	Body string `json:"body"`
+}
+
+// handleChatPost stores a chat message from the authenticated player. The sender
+// IP is taken from the gateway-forwarded X-Forwarded-For header.
+func (s *Server) handleChatPost(c *gin.Context) {
+	uid, ok := userID(c)
+	if !ok {
+		abortBadRequest(c, "missing identity")
+		return
+	}
+	gameID, ok := gameIDParam(c)
+	if !ok {
+		abortBadRequest(c, "invalid game id")
+		return
+	}
+	var req chatPostRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		abortBadRequest(c, "invalid request body")
+		return
+	}
+	msg, err := s.social.PostMessage(c.Request.Context(), gameID, uid, req.Body, clientIP(c))
+	if err != nil {
+		s.abortErr(c, err)
+		return
+	}
+	c.JSON(http.StatusOK, chatDTOFrom(msg))
+}