Stage 11: account linking & merge (email + Telegram Login Widget)

Link an email (confirm-code) or Telegram (web Login Widget) to the current
account; if the identity already has its own account, merge the two into the
one in use (the current account is primary, except a guest initiator whose
durable counterpart wins). The merge runs in one transaction
(internal/accountmerge): stats + hint wallet summed, paid_account ORed,
identities/games/chat/complaints transferred, friends/blocks de-duplicated,
the secondary kept as a merged_into tombstone so a shared finished game's
no-cascade FKs hold; a shared active game blocks the merge.

- migration 00009: accounts.paid_account, merged_into, merged_at (+ jetgen)
- internal/link orchestrator; session.RevokeAllForAccount on merge
- connector ValidateLoginWidget RPC + loginwidget HMAC validator
- edge ops link.email.request/confirm/merge, link.telegram.confirm/merge;
  supersedes the Stage 8 email.bind.* surface (request never reveals 'taken'
  before the code is verified, so a probe cannot enumerate addresses)
- UI Profile link section + irreversible-merge dialog; Telegram web sign-in
- focused regression tests (merge core, guest inversion, active-game refusal,
  finished-shared-game kept), gateway transcode + connector + UI codec/e2e
- docs: PLAN, ARCHITECTURE 3/4/9, FUNCTIONAL(+ru), module READMEs

pkg/fbs/scrabble.fbs

@@ -272,18 +272,42 @@ table UpdateProfileRequest {
   notifications_in_app_only:bool = true;
 }
 
-// EmailBindRequest asks the backend to send a confirm-code binding email to the
-// caller's account.
-table EmailBindRequest {
+// --- account linking & merge (Stage 11, authenticated) ---
+
+// LinkEmailRequest mails a confirm-code to email for a later link or merge. The
+// code is always sent (no pre-send "taken" signal), so a probe cannot enumerate
+// registered addresses.
+table LinkEmailRequest {
   email:string;
 }
 
-// EmailConfirmRequest verifies the code and binds the email (returns Profile).
-table EmailConfirmRequest {
+// LinkEmailConfirm carries the email and its confirm code, for both the confirm
+// (preview) and the explicit merge step.
+table LinkEmailConfirm {
   email:string;
   code:string;
 }
 
+// LinkTelegramRequest carries Telegram Login Widget data (a URL query string) for
+// attaching a Telegram identity to the current account.
+table LinkTelegramRequest {
+  data:string;
+}
+
+// LinkResult is the unified result of a confirm or merge step. status is "linked"
+// (bound to the caller), "merge_required" (the identity belongs to another account —
+// the secondary_* fields summarise it for the irreversible confirmation), or
+// "merged" (done). session is present only when the active account switched (a guest
+// initiator whose durable counterpart won) — the client adopts it.
+table LinkResult {
+  status:string;
+  secondary_user_id:string;
+  secondary_display_name:string;
+  secondary_games:int;
+  secondary_friends:int;
+  session:Session;
+}
+
 // StatsView is a durable account's lifetime statistics (games-played and win-rate
 // are derived client-side).
 table StatsView {

pkg/fbs/scrabblefb/EmailConfirmRequest.go

@@ -1,71 +0,0 @@
-// Code generated by the FlatBuffers compiler. DO NOT EDIT.
-
-package scrabblefb
-
-import (
-	flatbuffers "github.com/google/flatbuffers/go"
-)
-
-type EmailConfirmRequest struct {
-	_tab flatbuffers.Table
-}
-
-func GetRootAsEmailConfirmRequest(buf []byte, offset flatbuffers.UOffsetT) *EmailConfirmRequest {
-	n := flatbuffers.GetUOffsetT(buf[offset:])
-	x := &EmailConfirmRequest{}
-	x.Init(buf, n+offset)
-	return x
-}
-
-func FinishEmailConfirmRequestBuffer(builder *flatbuffers.Builder, offset flatbuffers.UOffsetT) {
-	builder.Finish(offset)
-}
-
-func GetSizePrefixedRootAsEmailConfirmRequest(buf []byte, offset flatbuffers.UOffsetT) *EmailConfirmRequest {
-	n := flatbuffers.GetUOffsetT(buf[offset+flatbuffers.SizeUint32:])
-	x := &EmailConfirmRequest{}
-	x.Init(buf, n+offset+flatbuffers.SizeUint32)
-	return x
-}
-
-func FinishSizePrefixedEmailConfirmRequestBuffer(builder *flatbuffers.Builder, offset flatbuffers.UOffsetT) {
-	builder.FinishSizePrefixed(offset)
-}
-
-func (rcv *EmailConfirmRequest) Init(buf []byte, i flatbuffers.UOffsetT) {
-	rcv._tab.Bytes = buf
-	rcv._tab.Pos = i
-}
-
-func (rcv *EmailConfirmRequest) Table() flatbuffers.Table {
-	return rcv._tab
-}
-
-func (rcv *EmailConfirmRequest) Email() []byte {
-	o := flatbuffers.UOffsetT(rcv._tab.Offset(4))
-	if o != 0 {
-		return rcv._tab.ByteVector(o + rcv._tab.Pos)
-	}
-	return nil
-}
-
-func (rcv *EmailConfirmRequest) Code() []byte {
-	o := flatbuffers.UOffsetT(rcv._tab.Offset(6))
-	if o != 0 {
-		return rcv._tab.ByteVector(o + rcv._tab.Pos)
-	}
-	return nil
-}
-
-func EmailConfirmRequestStart(builder *flatbuffers.Builder) {
-	builder.StartObject(2)
-}
-func EmailConfirmRequestAddEmail(builder *flatbuffers.Builder, email flatbuffers.UOffsetT) {
-	builder.PrependUOffsetTSlot(0, flatbuffers.UOffsetT(email), 0)
-}
-func EmailConfirmRequestAddCode(builder *flatbuffers.Builder, code flatbuffers.UOffsetT) {
-	builder.PrependUOffsetTSlot(1, flatbuffers.UOffsetT(code), 0)
-}
-func EmailConfirmRequestEnd(builder *flatbuffers.Builder) flatbuffers.UOffsetT {
-	return builder.EndObject()
-}

pkg/fbs/scrabblefb/LinkEmailConfirm.go

@@ -0,0 +1,71 @@
+// Code generated by the FlatBuffers compiler. DO NOT EDIT.
+
+package scrabblefb
+
+import (
+	flatbuffers "github.com/google/flatbuffers/go"
+)
+
+type LinkEmailConfirm struct {
+	_tab flatbuffers.Table
+}
+
+func GetRootAsLinkEmailConfirm(buf []byte, offset flatbuffers.UOffsetT) *LinkEmailConfirm {
+	n := flatbuffers.GetUOffsetT(buf[offset:])
+	x := &LinkEmailConfirm{}
+	x.Init(buf, n+offset)
+	return x
+}
+
+func FinishLinkEmailConfirmBuffer(builder *flatbuffers.Builder, offset flatbuffers.UOffsetT) {
+	builder.Finish(offset)
+}
+
+func GetSizePrefixedRootAsLinkEmailConfirm(buf []byte, offset flatbuffers.UOffsetT) *LinkEmailConfirm {
+	n := flatbuffers.GetUOffsetT(buf[offset+flatbuffers.SizeUint32:])
+	x := &LinkEmailConfirm{}
+	x.Init(buf, n+offset+flatbuffers.SizeUint32)
+	return x
+}
+
+func FinishSizePrefixedLinkEmailConfirmBuffer(builder *flatbuffers.Builder, offset flatbuffers.UOffsetT) {
+	builder.FinishSizePrefixed(offset)
+}
+
+func (rcv *LinkEmailConfirm) Init(buf []byte, i flatbuffers.UOffsetT) {
+	rcv._tab.Bytes = buf
+	rcv._tab.Pos = i
+}
+
+func (rcv *LinkEmailConfirm) Table() flatbuffers.Table {
+	return rcv._tab
+}
+
+func (rcv *LinkEmailConfirm) Email() []byte {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(4))
+	if o != 0 {
+		return rcv._tab.ByteVector(o + rcv._tab.Pos)
+	}
+	return nil
+}
+
+func (rcv *LinkEmailConfirm) Code() []byte {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(6))
+	if o != 0 {
+		return rcv._tab.ByteVector(o + rcv._tab.Pos)
+	}
+	return nil
+}
+
+func LinkEmailConfirmStart(builder *flatbuffers.Builder) {
+	builder.StartObject(2)
+}
+func LinkEmailConfirmAddEmail(builder *flatbuffers.Builder, email flatbuffers.UOffsetT) {
+	builder.PrependUOffsetTSlot(0, flatbuffers.UOffsetT(email), 0)
+}
+func LinkEmailConfirmAddCode(builder *flatbuffers.Builder, code flatbuffers.UOffsetT) {
+	builder.PrependUOffsetTSlot(1, flatbuffers.UOffsetT(code), 0)
+}
+func LinkEmailConfirmEnd(builder *flatbuffers.Builder) flatbuffers.UOffsetT {
+	return builder.EndObject()
+}

pkg/fbs/scrabblefb/LinkEmailRequest.go

@@ -6,42 +6,42 @@ import (
 	flatbuffers "github.com/google/flatbuffers/go"
 )
 
-type EmailBindRequest struct {
+type LinkEmailRequest struct {
 	_tab flatbuffers.Table
 }
 
-func GetRootAsEmailBindRequest(buf []byte, offset flatbuffers.UOffsetT) *EmailBindRequest {
+func GetRootAsLinkEmailRequest(buf []byte, offset flatbuffers.UOffsetT) *LinkEmailRequest {
 	n := flatbuffers.GetUOffsetT(buf[offset:])
-	x := &EmailBindRequest{}
+	x := &LinkEmailRequest{}
 	x.Init(buf, n+offset)
 	return x
 }
 
-func FinishEmailBindRequestBuffer(builder *flatbuffers.Builder, offset flatbuffers.UOffsetT) {
+func FinishLinkEmailRequestBuffer(builder *flatbuffers.Builder, offset flatbuffers.UOffsetT) {
 	builder.Finish(offset)
 }
 
-func GetSizePrefixedRootAsEmailBindRequest(buf []byte, offset flatbuffers.UOffsetT) *EmailBindRequest {
+func GetSizePrefixedRootAsLinkEmailRequest(buf []byte, offset flatbuffers.UOffsetT) *LinkEmailRequest {
 	n := flatbuffers.GetUOffsetT(buf[offset+flatbuffers.SizeUint32:])
-	x := &EmailBindRequest{}
+	x := &LinkEmailRequest{}
 	x.Init(buf, n+offset+flatbuffers.SizeUint32)
 	return x
 }
 
-func FinishSizePrefixedEmailBindRequestBuffer(builder *flatbuffers.Builder, offset flatbuffers.UOffsetT) {
+func FinishSizePrefixedLinkEmailRequestBuffer(builder *flatbuffers.Builder, offset flatbuffers.UOffsetT) {
 	builder.FinishSizePrefixed(offset)
 }
 
-func (rcv *EmailBindRequest) Init(buf []byte, i flatbuffers.UOffsetT) {
+func (rcv *LinkEmailRequest) Init(buf []byte, i flatbuffers.UOffsetT) {
 	rcv._tab.Bytes = buf
 	rcv._tab.Pos = i
 }
 
-func (rcv *EmailBindRequest) Table() flatbuffers.Table {
+func (rcv *LinkEmailRequest) Table() flatbuffers.Table {
 	return rcv._tab
 }
 
-func (rcv *EmailBindRequest) Email() []byte {
+func (rcv *LinkEmailRequest) Email() []byte {
 	o := flatbuffers.UOffsetT(rcv._tab.Offset(4))
 	if o != 0 {
 		return rcv._tab.ByteVector(o + rcv._tab.Pos)
@@ -49,12 +49,12 @@ func (rcv *EmailBindRequest) Email() []byte {
 	return nil
 }
 
-func EmailBindRequestStart(builder *flatbuffers.Builder) {
+func LinkEmailRequestStart(builder *flatbuffers.Builder) {
 	builder.StartObject(1)
 }
-func EmailBindRequestAddEmail(builder *flatbuffers.Builder, email flatbuffers.UOffsetT) {
+func LinkEmailRequestAddEmail(builder *flatbuffers.Builder, email flatbuffers.UOffsetT) {
 	builder.PrependUOffsetTSlot(0, flatbuffers.UOffsetT(email), 0)
 }
-func EmailBindRequestEnd(builder *flatbuffers.Builder) flatbuffers.UOffsetT {
+func LinkEmailRequestEnd(builder *flatbuffers.Builder) flatbuffers.UOffsetT {
 	return builder.EndObject()
 }

pkg/fbs/scrabblefb/LinkResult.go

@@ -0,0 +1,128 @@
+// Code generated by the FlatBuffers compiler. DO NOT EDIT.
+
+package scrabblefb
+
+import (
+	flatbuffers "github.com/google/flatbuffers/go"
+)
+
+type LinkResult struct {
+	_tab flatbuffers.Table
+}
+
+func GetRootAsLinkResult(buf []byte, offset flatbuffers.UOffsetT) *LinkResult {
+	n := flatbuffers.GetUOffsetT(buf[offset:])
+	x := &LinkResult{}
+	x.Init(buf, n+offset)
+	return x
+}
+
+func FinishLinkResultBuffer(builder *flatbuffers.Builder, offset flatbuffers.UOffsetT) {
+	builder.Finish(offset)
+}
+
+func GetSizePrefixedRootAsLinkResult(buf []byte, offset flatbuffers.UOffsetT) *LinkResult {
+	n := flatbuffers.GetUOffsetT(buf[offset+flatbuffers.SizeUint32:])
+	x := &LinkResult{}
+	x.Init(buf, n+offset+flatbuffers.SizeUint32)
+	return x
+}
+
+func FinishSizePrefixedLinkResultBuffer(builder *flatbuffers.Builder, offset flatbuffers.UOffsetT) {
+	builder.FinishSizePrefixed(offset)
+}
+
+func (rcv *LinkResult) Init(buf []byte, i flatbuffers.UOffsetT) {
+	rcv._tab.Bytes = buf
+	rcv._tab.Pos = i
+}
+
+func (rcv *LinkResult) Table() flatbuffers.Table {
+	return rcv._tab
+}
+
+func (rcv *LinkResult) Status() []byte {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(4))
+	if o != 0 {
+		return rcv._tab.ByteVector(o + rcv._tab.Pos)
+	}
+	return nil
+}
+
+func (rcv *LinkResult) SecondaryUserId() []byte {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(6))
+	if o != 0 {
+		return rcv._tab.ByteVector(o + rcv._tab.Pos)
+	}
+	return nil
+}
+
+func (rcv *LinkResult) SecondaryDisplayName() []byte {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(8))
+	if o != 0 {
+		return rcv._tab.ByteVector(o + rcv._tab.Pos)
+	}
+	return nil
+}
+
+func (rcv *LinkResult) SecondaryGames() int32 {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(10))
+	if o != 0 {
+		return rcv._tab.GetInt32(o + rcv._tab.Pos)
+	}
+	return 0
+}
+
+func (rcv *LinkResult) MutateSecondaryGames(n int32) bool {
+	return rcv._tab.MutateInt32Slot(10, n)
+}
+
+func (rcv *LinkResult) SecondaryFriends() int32 {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(12))
+	if o != 0 {
+		return rcv._tab.GetInt32(o + rcv._tab.Pos)
+	}
+	return 0
+}
+
+func (rcv *LinkResult) MutateSecondaryFriends(n int32) bool {
+	return rcv._tab.MutateInt32Slot(12, n)
+}
+
+func (rcv *LinkResult) Session(obj *Session) *Session {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(14))
+	if o != 0 {
+		x := rcv._tab.Indirect(o + rcv._tab.Pos)
+		if obj == nil {
+			obj = new(Session)
+		}
+		obj.Init(rcv._tab.Bytes, x)
+		return obj
+	}
+	return nil
+}
+
+func LinkResultStart(builder *flatbuffers.Builder) {
+	builder.StartObject(6)
+}
+func LinkResultAddStatus(builder *flatbuffers.Builder, status flatbuffers.UOffsetT) {
+	builder.PrependUOffsetTSlot(0, flatbuffers.UOffsetT(status), 0)
+}
+func LinkResultAddSecondaryUserId(builder *flatbuffers.Builder, secondaryUserId flatbuffers.UOffsetT) {
+	builder.PrependUOffsetTSlot(1, flatbuffers.UOffsetT(secondaryUserId), 0)
+}
+func LinkResultAddSecondaryDisplayName(builder *flatbuffers.Builder, secondaryDisplayName flatbuffers.UOffsetT) {
+	builder.PrependUOffsetTSlot(2, flatbuffers.UOffsetT(secondaryDisplayName), 0)
+}
+func LinkResultAddSecondaryGames(builder *flatbuffers.Builder, secondaryGames int32) {
+	builder.PrependInt32Slot(3, secondaryGames, 0)
+}
+func LinkResultAddSecondaryFriends(builder *flatbuffers.Builder, secondaryFriends int32) {
+	builder.PrependInt32Slot(4, secondaryFriends, 0)
+}
+func LinkResultAddSession(builder *flatbuffers.Builder, session flatbuffers.UOffsetT) {
+	builder.PrependUOffsetTSlot(5, flatbuffers.UOffsetT(session), 0)
+}
+func LinkResultEnd(builder *flatbuffers.Builder) flatbuffers.UOffsetT {
+	return builder.EndObject()
+}

pkg/fbs/scrabblefb/LinkTelegramRequest.go

@@ -0,0 +1,60 @@
+// Code generated by the FlatBuffers compiler. DO NOT EDIT.
+
+package scrabblefb
+
+import (
+	flatbuffers "github.com/google/flatbuffers/go"
+)
+
+type LinkTelegramRequest struct {
+	_tab flatbuffers.Table
+}
+
+func GetRootAsLinkTelegramRequest(buf []byte, offset flatbuffers.UOffsetT) *LinkTelegramRequest {
+	n := flatbuffers.GetUOffsetT(buf[offset:])
+	x := &LinkTelegramRequest{}
+	x.Init(buf, n+offset)
+	return x
+}
+
+func FinishLinkTelegramRequestBuffer(builder *flatbuffers.Builder, offset flatbuffers.UOffsetT) {
+	builder.Finish(offset)
+}
+
+func GetSizePrefixedRootAsLinkTelegramRequest(buf []byte, offset flatbuffers.UOffsetT) *LinkTelegramRequest {
+	n := flatbuffers.GetUOffsetT(buf[offset+flatbuffers.SizeUint32:])
+	x := &LinkTelegramRequest{}
+	x.Init(buf, n+offset+flatbuffers.SizeUint32)
+	return x
+}
+
+func FinishSizePrefixedLinkTelegramRequestBuffer(builder *flatbuffers.Builder, offset flatbuffers.UOffsetT) {
+	builder.FinishSizePrefixed(offset)
+}
+
+func (rcv *LinkTelegramRequest) Init(buf []byte, i flatbuffers.UOffsetT) {
+	rcv._tab.Bytes = buf
+	rcv._tab.Pos = i
+}
+
+func (rcv *LinkTelegramRequest) Table() flatbuffers.Table {
+	return rcv._tab
+}
+
+func (rcv *LinkTelegramRequest) Data() []byte {
+	o := flatbuffers.UOffsetT(rcv._tab.Offset(4))
+	if o != 0 {
+		return rcv._tab.ByteVector(o + rcv._tab.Pos)
+	}
+	return nil
+}
+
+func LinkTelegramRequestStart(builder *flatbuffers.Builder) {
+	builder.StartObject(1)
+}
+func LinkTelegramRequestAddData(builder *flatbuffers.Builder, data flatbuffers.UOffsetT) {
+	builder.PrependUOffsetTSlot(0, flatbuffers.UOffsetT(data), 0)
+}
+func LinkTelegramRequestEnd(builder *flatbuffers.Builder) flatbuffers.UOffsetT {
+	return builder.EndObject()
+}