feat(payments): trusted platform signal on the session

Record the execution platform (kind vk|telegram|direct + device subtype
ios|android|web) on each session, captured at creation and carried
gateway->backend as a trusted X-Platform header, so the upcoming
store-compliance gate has an unforgeable execution context.

- backend.sessions gains nullable platform_kind/platform_subtype columns
  (migration 00011, CHECK-constrained, jet regenerated); session.Platform
  captures them at mint, resolve returns them, middleware exposes platform(c).
  kind is derived from the establish endpoint, never a client field; the
  account-merge session mint inherits the caller's platform.
- gateway derives the platform (VK subtype from the signed vk_platform via
  vkauth, Telegram/direct best-effort from the client) and injects X-Platform
  on every authenticated backend call through the request context.
- ui submits a best-effort device subtype on the telegram/guest/email login
  requests (new FBS subtype field); VK is server-derived from the signed params.
- an unattributed session is untrusted (view-only); VK/TG self-heal on the next
  cold-start re-mint, direct/email on re-login.

Signal plumbing only, no user-visible change; X-Platform is inert until the
gate consumes it.

backend/internal/server/dto.go

@@ -28,10 +28,14 @@ type okResponse struct {
 }
 
 // resolveResponse maps a session token to its account. IsGuest lets the gateway
-// gate guest-forbidden operations without an extra round-trip.
+// gate guest-forbidden operations without an extra round-trip. PlatformKind and
+// PlatformSubtype carry the session's trusted execution platform so the gateway can
+// inject X-Platform; both are empty for an untrusted (pre-capture) session.
 type resolveResponse struct {
-	UserID  string `json:"user_id"`
-	IsGuest bool   `json:"is_guest"`
+	UserID          string `json:"user_id"`
+	IsGuest         bool   `json:"is_guest"`
+	PlatformKind    string `json:"platform_kind"`
+	PlatformSubtype string `json:"platform_subtype"`
 }
 
 // profileResponse is the authenticated account's own profile. AwayStart and AwayEnd

backend/internal/server/handlers_auth.go

@@ -10,6 +10,7 @@ import (
 
 	"scrabble/backend/internal/account"
 	"scrabble/backend/internal/notify"
+	"scrabble/backend/internal/session"
 )
 
 // The /api/v1/internal/sessions/* endpoints are gateway-only: the gateway has
@@ -23,7 +24,9 @@ import (
 // brand-new account's display name and language; BrowserTZ (the client's detected
 // "±HH:MM" UTC offset) seeds its time zone; StartParam is the validated launch
 // deep-link payload, which may seed the new account's variant preferences (first
-// contact only).
+// contact only). Subtype is the client-reported device family (ios/android/web);
+// Telegram's initData does not sign it, so it is recorded best-effort and the
+// payments gate never relies on it.
 type telegramAuthRequest struct {
 	ExternalID   string `json:"external_id"`
 	Username     string `json:"username"`
@@ -31,6 +34,7 @@ type telegramAuthRequest struct {
 	LanguageCode string `json:"language_code"`
 	BrowserTZ    string `json:"browser_tz"`
 	StartParam   string `json:"start_param"`
+	Subtype      string `json:"subtype"`
 }
 
 // handleTelegramAuth provisions (or finds) the account bound to a Telegram
@@ -63,19 +67,22 @@ func (s *Server) handleTelegramAuth(c *gin.Context) {
 			}
 		}
 	}
-	s.mintSession(c, acc)
+	s.mintSession(c, acc, session.Platform{Kind: session.PlatformKindTelegram, Subtype: session.NormalizeSubtype(req.Subtype)})
 }
 
 // vkAuthRequest carries the identity the gateway extracted from verified VK launch
 // params. LanguageCode (vk_language) and DisplayName (read client-side via
 // VKWebAppGetUserInfo, since VK omits the name from the signed params) seed a brand-new
 // account's language and display name; BrowserTZ (the client's detected "±HH:MM" UTC
-// offset) seeds its time zone. All seeds apply on first contact only.
+// offset) seeds its time zone. All seeds apply on first contact only. Subtype is the
+// device family the gateway derived from the signed vk_platform param — trusted,
+// since it rides inside the verified launch signature.
 type vkAuthRequest struct {
 	ExternalID   string `json:"external_id"`
 	LanguageCode string `json:"language_code"`
 	DisplayName  string `json:"display_name"`
 	BrowserTZ    string `json:"browser_tz"`
+	Subtype      string `json:"subtype"`
 }
 
 // handleVKAuth provisions (or finds) the account bound to a VK identity and mints a
@@ -94,7 +101,7 @@ func (s *Server) handleVKAuth(c *gin.Context) {
 		s.abortErr(c, err)
 		return
 	}
-	s.mintSession(c, acc)
+	s.mintSession(c, acc, session.Platform{Kind: session.PlatformKindVK, Subtype: session.NormalizeSubtype(req.Subtype)})
 }
 
 // pushTargetRequest asks for a user's out-of-app push routing data by account id.
@@ -150,6 +157,9 @@ func (s *Server) handlePushTarget(c *gin.Context) {
 // time zone, so robot timing is anchored to the player's zone from the first game.
 type guestAuthRequest struct {
 	BrowserTZ string `json:"browser_tz"`
+	// Subtype is the client-reported device family (ios/android/web) of this direct
+	// (web/native) session; there is no external signer, so it is recorded best-effort.
+	Subtype string `json:"subtype"`
 }
 
 // handleGuestAuth provisions a fresh ephemeral guest account and mints a session,
@@ -164,7 +174,7 @@ func (s *Server) handleGuestAuth(c *gin.Context) {
 		s.abortErr(c, err)
 		return
 	}
-	s.mintSession(c, acc)
+	s.mintSession(c, acc, session.Platform{Kind: session.PlatformKindDirect, Subtype: session.NormalizeSubtype(req.Subtype)})
 }
 
 // emailRequest is an email-login code request. BrowserTZ (the client's detected
@@ -196,10 +206,12 @@ func (s *Server) handleEmailRequest(c *gin.Context) {
 	c.JSON(http.StatusOK, okResponse{OK: true})
 }
 
-// emailLoginRequest verifies an email login code.
+// emailLoginRequest verifies an email login code. Subtype is the client-reported
+// device family (ios/android/web) of this direct session; recorded best-effort.
 type emailLoginRequest struct {
-	Email string `json:"email"`
-	Code  string `json:"code"`
+	Email   string `json:"email"`
+	Code    string `json:"code"`
+	Subtype string `json:"subtype"`
 }
 
 // handleEmailLogin verifies the code and mints a session for the owning account.
@@ -214,7 +226,7 @@ func (s *Server) handleEmailLogin(c *gin.Context) {
 		s.abortErr(c, err)
 		return
 	}
-	s.mintSession(c, acc)
+	s.mintSession(c, acc, session.Platform{Kind: session.PlatformKindDirect, Subtype: session.NormalizeSubtype(req.Subtype)})
 }
 
 // confirmLinkResponse is the outcome of a one-tap deeplink confirmation. For a login,
@@ -248,7 +260,8 @@ func (s *Server) handleEmailConfirmLink(c *gin.Context) {
 			s.abortErr(c, err)
 			return
 		}
-		token, _, err := s.sessions.Create(c.Request.Context(), acc.ID)
+		// A magic-link login always opens in a browser, so its session is direct/web.
+		token, _, err := s.sessions.Create(c.Request.Context(), acc.ID, session.Platform{Kind: session.PlatformKindDirect, Subtype: session.SubtypeWeb})
 		if err != nil {
 			s.abortErr(c, err)
 			return
@@ -288,7 +301,11 @@ func (s *Server) handleResolveSession(c *gin.Context) {
 	// is_guest is best-effort: a transient account read must not fail an otherwise
 	// valid resolve (the auth hot path), so a read error falls back to false; the
 	// per-operation backend gate remains the authoritative guest check.
-	resp := resolveResponse{UserID: sess.AccountID.String()}
+	resp := resolveResponse{
+		UserID:          sess.AccountID.String(),
+		PlatformKind:    sess.Platform.Kind,
+		PlatformSubtype: sess.Platform.Subtype,
+	}
 	if acc, err := s.accounts.GetByID(c.Request.Context(), sess.AccountID); err == nil {
 		resp.IsGuest = acc.IsGuest
 	}
@@ -309,9 +326,10 @@ func (s *Server) handleRevokeSession(c *gin.Context) {
 	c.JSON(http.StatusOK, okResponse{OK: true})
 }
 
-// mintSession creates a session for acc and writes the credential response.
-func (s *Server) mintSession(c *gin.Context, acc account.Account) {
-	token, _, err := s.sessions.Create(c.Request.Context(), acc.ID)
+// mintSession creates a session for acc carrying the captured platform and writes
+// the credential response.
+func (s *Server) mintSession(c *gin.Context, acc account.Account, platform session.Platform) {
+	token, _, err := s.sessions.Create(c.Request.Context(), acc.ID, platform)
 	if err != nil {
 		s.abortErr(c, err)
 		return

backend/internal/server/middleware.go

@@ -4,9 +4,12 @@ import (
 	"context"
 	"net/http"
 	"net/url"
+	"strings"
 
 	"github.com/gin-gonic/gin"
 	"github.com/google/uuid"
+
+	"scrabble/backend/internal/session"
 )
 
 // headerUserID is the identity header the gateway injects after resolving a
@@ -41,6 +44,46 @@ func UserIDFromContext(ctx context.Context) (uuid.UUID, bool) {
 	return id, ok
 }
 
+// headerPlatform is the trusted execution-platform header the gateway injects after
+// resolving a session's platform. Its value is "<kind>/<subtype>" (e.g. "vk/ios");
+// it is omitted for an untrusted session, in which case platform(c) reports the
+// zero Platform. Like X-User-ID, the value is the gateway's — never a client body.
+const headerPlatform = "X-Platform"
+
+// platformContext returns middleware that parses the gateway-injected X-Platform
+// header into the request context, so handlers (and the link/merge session mint)
+// read the caller's trusted platform. An absent or malformed header leaves the
+// context without a platform (untrusted) and never rejects the request — X-Platform
+// is a capability signal, not an identity gate.
+func platformContext() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if p, ok := parsePlatformHeader(c.GetHeader(headerPlatform)); ok {
+			c.Request = c.Request.WithContext(session.WithPlatform(c.Request.Context(), p))
+		}
+		c.Next()
+	}
+}
+
+// parsePlatformHeader splits a "<kind>/<subtype>" X-Platform value into a Platform.
+// A blank value or blank kind yields no platform (an untrusted session).
+func parsePlatformHeader(h string) (session.Platform, bool) {
+	if h == "" {
+		return session.Platform{}, false
+	}
+	kind, subtype, _ := strings.Cut(h, "/")
+	if kind == "" {
+		return session.Platform{}, false
+	}
+	return session.Platform{Kind: kind, Subtype: subtype}, true
+}
+
+// platform returns the caller's trusted execution platform, or the zero Platform
+// and false when the session was not attributed to one — an untrusted, view-only
+// context for the payments gate.
+func platform(c *gin.Context) (session.Platform, bool) {
+	return session.PlatformFromContext(c.Request.Context())
+}
+
 // requireSameOrigin guards the admin console's state-changing requests: it rejects
 // a non-safe request whose Origin (or, failing that, Referer) host does not match
 // the request Host. The gateway authenticates the operator with Basic-Auth in front

backend/internal/server/middleware_test.go

@@ -7,6 +7,8 @@ import (
 
 	"github.com/gin-gonic/gin"
 	"github.com/google/uuid"
+
+	"scrabble/backend/internal/session"
 )
 
 // TestRequireUserID checks that the middleware accepts a valid X-User-ID,
@@ -58,3 +60,51 @@ func TestRequireUserID(t *testing.T) {
 		}
 	})
 }
+
+// TestPlatformContext checks that the middleware parses the gateway-injected
+// X-Platform header into a trusted platform reachable via platform(c), treats an
+// absent or blank-kind header as untrusted, and never rejects the request.
+func TestPlatformContext(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	var seen session.Platform
+	var ok bool
+	r := gin.New()
+	r.Use(platformContext())
+	r.GET("/x", func(c *gin.Context) {
+		seen, ok = platform(c)
+		c.String(http.StatusOK, "ok")
+	})
+
+	for _, tc := range []struct {
+		name      string
+		header    string
+		setHeader bool
+		wantOK    bool
+		want      session.Platform
+	}{
+		{"vk-ios", "vk/ios", true, true, session.Platform{Kind: session.PlatformKindVK, Subtype: session.SubtypeIOS}},
+		{"telegram-no-subtype", "telegram", true, true, session.Platform{Kind: session.PlatformKindTelegram}},
+		{"direct-web", "direct/web", true, true, session.Platform{Kind: session.PlatformKindDirect, Subtype: session.SubtypeWeb}},
+		{"absent", "", false, false, session.Platform{}},
+		{"empty", "", true, false, session.Platform{}},
+		{"blank-kind", "/ios", true, false, session.Platform{}},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			seen, ok = session.Platform{}, false
+			req := httptest.NewRequest(http.MethodGet, "/x", nil)
+			if tc.setHeader {
+				req.Header.Set("X-Platform", tc.header)
+			}
+			rec := httptest.NewRecorder()
+			r.ServeHTTP(rec, req)
+
+			if rec.Code != http.StatusOK {
+				t.Fatalf("status = %d, want 200 (X-Platform never rejects)", rec.Code)
+			}
+			if ok != tc.wantOK || seen != tc.want {
+				t.Fatalf("platform = %+v (ok=%v), want %+v (ok=%v)", seen, ok, tc.want, tc.wantOK)
+			}
+		})
+	}
+}

backend/internal/server/server.go

@@ -238,6 +238,10 @@ func (s *Server) registerAPIGroups(engine *gin.Engine) {
 	s.public = v1.Group("/public")
 	s.user = v1.Group("/user")
 	s.user.Use(RequireUserID())
+	// Capture the gateway-injected trusted platform (X-Platform) into the request context,
+	// so the payments gate can read it via platform(c). Optional: an untrusted session simply
+	// carries no platform and is treated as view-only. Never rejects.
+	s.user.Use(platformContext())
 	// The suspension gate runs after identity is established: a blocked account is refused on
 	// every user route (except the block-status probe) so the UI can show the blocked screen.
 	s.user.Use(s.requireNotSuspended())