docs(proto): ResolveLinkedAccount fail-closed on ambiguous identity (FailedPrecondition); comment-only, no regen (generated doc comments drift until next regen)

users.pb.go

@@ -1,7 +1,7 @@
 // Code generated by protoc-gen-go. DO NOT EDIT.
 // versions:
 // 	protoc-gen-go v1.36.11
-// 	protoc        v7.34.0
+// 	protoc        v7.34.2
 // source: users.proto
 
 package proto
@@ -711,6 +711,118 @@ func (x *GetLinkedAccountsResponse) GetAccounts() []*LinkedAccount {
 	return nil
 }
 
+type ResolveLinkedAccountRequest struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	Platform      string                 `protobuf:"bytes,1,opt,name=platform,proto3" json:"platform,omitempty"`
+	AccountId     string                 `protobuf:"bytes,2,opt,name=account_id,json=accountId,proto3" json:"account_id,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *ResolveLinkedAccountRequest) Reset() {
+	*x = ResolveLinkedAccountRequest{}
+	mi := &file_users_proto_msgTypes[12]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *ResolveLinkedAccountRequest) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*ResolveLinkedAccountRequest) ProtoMessage() {}
+
+func (x *ResolveLinkedAccountRequest) ProtoReflect() protoreflect.Message {
+	mi := &file_users_proto_msgTypes[12]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use ResolveLinkedAccountRequest.ProtoReflect.Descriptor instead.
+func (*ResolveLinkedAccountRequest) Descriptor() ([]byte, []int) {
+	return file_users_proto_rawDescGZIP(), []int{12}
+}
+
+func (x *ResolveLinkedAccountRequest) GetPlatform() string {
+	if x != nil {
+		return x.Platform
+	}
+	return ""
+}
+
+func (x *ResolveLinkedAccountRequest) GetAccountId() string {
+	if x != nil {
+		return x.AccountId
+	}
+	return ""
+}
+
+type ResolveLinkedAccountResponse struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	Linked        bool                   `protobuf:"varint,1,opt,name=linked,proto3" json:"linked,omitempty"`
+	GlobalUserId  int64                  `protobuf:"varint,2,opt,name=global_user_id,json=globalUserId,proto3" json:"global_user_id,omitempty"`
+	DisplayName   string                 `protobuf:"bytes,3,opt,name=display_name,json=displayName,proto3" json:"display_name,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *ResolveLinkedAccountResponse) Reset() {
+	*x = ResolveLinkedAccountResponse{}
+	mi := &file_users_proto_msgTypes[13]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *ResolveLinkedAccountResponse) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*ResolveLinkedAccountResponse) ProtoMessage() {}
+
+func (x *ResolveLinkedAccountResponse) ProtoReflect() protoreflect.Message {
+	mi := &file_users_proto_msgTypes[13]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use ResolveLinkedAccountResponse.ProtoReflect.Descriptor instead.
+func (*ResolveLinkedAccountResponse) Descriptor() ([]byte, []int) {
+	return file_users_proto_rawDescGZIP(), []int{13}
+}
+
+func (x *ResolveLinkedAccountResponse) GetLinked() bool {
+	if x != nil {
+		return x.Linked
+	}
+	return false
+}
+
+func (x *ResolveLinkedAccountResponse) GetGlobalUserId() int64 {
+	if x != nil {
+		return x.GlobalUserId
+	}
+	return 0
+}
+
+func (x *ResolveLinkedAccountResponse) GetDisplayName() string {
+	if x != nil {
+		return x.DisplayName
+	}
+	return ""
+}
+
 var File_users_proto protoreflect.FileDescriptor
 
 const file_users_proto_rawDesc = "" +
@@ -768,7 +880,15 @@ const file_users_proto_rawDesc = "" +
 	"\x0eglobal_user_id\x18\x01 \x01(\x03R\fglobalUserId\x12\x1a\n" +
 	"\bplatform\x18\x02 \x01(\tR\bplatform\"M\n" +
 	"\x19GetLinkedAccountsResponse\x120\n" +
-	"\baccounts\x18\x01 \x03(\v2\x14.users.LinkedAccountR\baccounts2\xe9\x05\n" +
+	"\baccounts\x18\x01 \x03(\v2\x14.users.LinkedAccountR\baccounts\"X\n" +
+	"\x1bResolveLinkedAccountRequest\x12\x1a\n" +
+	"\bplatform\x18\x01 \x01(\tR\bplatform\x12\x1d\n" +
+	"\n" +
+	"account_id\x18\x02 \x01(\tR\taccountId\"\x7f\n" +
+	"\x1cResolveLinkedAccountResponse\x12\x16\n" +
+	"\x06linked\x18\x01 \x01(\bR\x06linked\x12$\n" +
+	"\x0eglobal_user_id\x18\x02 \x01(\x03R\fglobalUserId\x12!\n" +
+	"\fdisplay_name\x18\x03 \x01(\tR\vdisplayName2\xca\x06\n" +
 	"\fUsersService\x12E\n" +
 	"\x10CreateGlobalUser\x12\x1e.users.CreateGlobalUserRequest\x1a\x11.users.GlobalUser\x12?\n" +
 	"\rGetGlobalUser\x12\x1b.users.GetGlobalUserRequest\x1a\x11.users.GlobalUser\x12M\n" +
@@ -778,7 +898,8 @@ const file_users_proto_rawDesc = "" +
 	"\rUnlinkAccount\x12\x1b.users.UnlinkAccountRequest\x1a\x16.google.protobuf.Empty\x12H\n" +
 	"\x10GetLinkedAccount\x12\x1e.users.GetLinkedAccountRequest\x1a\x14.users.LinkedAccount\x12j\n" +
 	"\x1bGetLinkedAccountsByPlatform\x12).users.GetLinkedAccountsByPlatformRequest\x1a .users.GetLinkedAccountsResponse\x12x\n" +
-	"\"GetLinkedAccountsByUserAndPlatform\x120.users.GetLinkedAccountsByUserAndPlatformRequest\x1a .users.GetLinkedAccountsResponseB,Z*git.be.kaien.ru/l-ai/l-ai-core-proto/protob\x06proto3"
+	"\"GetLinkedAccountsByUserAndPlatform\x120.users.GetLinkedAccountsByUserAndPlatformRequest\x1a .users.GetLinkedAccountsResponse\x12_\n" +
+	"\x14ResolveLinkedAccount\x12\".users.ResolveLinkedAccountRequest\x1a#.users.ResolveLinkedAccountResponseB,Z*git.be.kaien.ru/l-ai/l-ai-core-proto/protob\x06proto3"
 
 var (
 	file_users_proto_rawDescOnce sync.Once
@@ -792,7 +913,7 @@ func file_users_proto_rawDescGZIP() []byte {
 	return file_users_proto_rawDescData
 }
 
-var file_users_proto_msgTypes = make([]protoimpl.MessageInfo, 12)
+var file_users_proto_msgTypes = make([]protoimpl.MessageInfo, 14)
 var file_users_proto_goTypes = []any{
 	(*GlobalUser)(nil),                                // 0: users.GlobalUser
 	(*LinkedAccount)(nil),                             // 1: users.LinkedAccount
@@ -806,37 +927,41 @@ var file_users_proto_goTypes = []any{
 	(*GetLinkedAccountsByPlatformRequest)(nil),        // 9: users.GetLinkedAccountsByPlatformRequest
 	(*GetLinkedAccountsByUserAndPlatformRequest)(nil), // 10: users.GetLinkedAccountsByUserAndPlatformRequest
 	(*GetLinkedAccountsResponse)(nil),                 // 11: users.GetLinkedAccountsResponse
-	(*timestamppb.Timestamp)(nil),                     // 12: google.protobuf.Timestamp
+	(*ResolveLinkedAccountRequest)(nil),               // 12: users.ResolveLinkedAccountRequest
-	(*emptypb.Empty)(nil),                             // 13: google.protobuf.Empty
+	(*ResolveLinkedAccountResponse)(nil),              // 13: users.ResolveLinkedAccountResponse
+	(*timestamppb.Timestamp)(nil),                     // 14: google.protobuf.Timestamp
+	(*emptypb.Empty)(nil),                             // 15: google.protobuf.Empty
 }
 var file_users_proto_depIdxs = []int32{
-	12, // 0: users.GlobalUser.created_at:type_name -> google.protobuf.Timestamp
+	14, // 0: users.GlobalUser.created_at:type_name -> google.protobuf.Timestamp
-	12, // 1: users.GlobalUser.updated_at:type_name -> google.protobuf.Timestamp
+	14, // 1: users.GlobalUser.updated_at:type_name -> google.protobuf.Timestamp
 	1,  // 2: users.GlobalUser.linked_accounts:type_name -> users.LinkedAccount
-	12, // 3: users.LinkedAccount.linked_at:type_name -> google.protobuf.Timestamp
+	14, // 3: users.LinkedAccount.linked_at:type_name -> google.protobuf.Timestamp
-	12, // 4: users.LinkedAccount.updated_at:type_name -> google.protobuf.Timestamp
+	14, // 4: users.LinkedAccount.updated_at:type_name -> google.protobuf.Timestamp
 	0,  // 5: users.GetAllGlobalUsersResponse.users:type_name -> users.GlobalUser
 	1,  // 6: users.GetLinkedAccountsResponse.accounts:type_name -> users.LinkedAccount
 	2,  // 7: users.UsersService.CreateGlobalUser:input_type -> users.CreateGlobalUserRequest
 	3,  // 8: users.UsersService.GetGlobalUser:input_type -> users.GetGlobalUserRequest
-	13, // 9: users.UsersService.GetAllGlobalUsers:input_type -> google.protobuf.Empty
+	15, // 9: users.UsersService.GetAllGlobalUsers:input_type -> google.protobuf.Empty
 	5,  // 10: users.UsersService.UpdateDisplayName:input_type -> users.UpdateDisplayNameRequest
 	6,  // 11: users.UsersService.LinkAccount:input_type -> users.LinkAccountRequest
 	7,  // 12: users.UsersService.UnlinkAccount:input_type -> users.UnlinkAccountRequest
 	8,  // 13: users.UsersService.GetLinkedAccount:input_type -> users.GetLinkedAccountRequest
 	9,  // 14: users.UsersService.GetLinkedAccountsByPlatform:input_type -> users.GetLinkedAccountsByPlatformRequest
 	10, // 15: users.UsersService.GetLinkedAccountsByUserAndPlatform:input_type -> users.GetLinkedAccountsByUserAndPlatformRequest
-	0,  // 16: users.UsersService.CreateGlobalUser:output_type -> users.GlobalUser
+	12, // 16: users.UsersService.ResolveLinkedAccount:input_type -> users.ResolveLinkedAccountRequest
-	0,  // 17: users.UsersService.GetGlobalUser:output_type -> users.GlobalUser
+	0,  // 17: users.UsersService.CreateGlobalUser:output_type -> users.GlobalUser
-	4,  // 18: users.UsersService.GetAllGlobalUsers:output_type -> users.GetAllGlobalUsersResponse
+	0,  // 18: users.UsersService.GetGlobalUser:output_type -> users.GlobalUser
-	13, // 19: users.UsersService.UpdateDisplayName:output_type -> google.protobuf.Empty
+	4,  // 19: users.UsersService.GetAllGlobalUsers:output_type -> users.GetAllGlobalUsersResponse
-	1,  // 20: users.UsersService.LinkAccount:output_type -> users.LinkedAccount
+	15, // 20: users.UsersService.UpdateDisplayName:output_type -> google.protobuf.Empty
-	13, // 21: users.UsersService.UnlinkAccount:output_type -> google.protobuf.Empty
+	1,  // 21: users.UsersService.LinkAccount:output_type -> users.LinkedAccount
-	1,  // 22: users.UsersService.GetLinkedAccount:output_type -> users.LinkedAccount
+	15, // 22: users.UsersService.UnlinkAccount:output_type -> google.protobuf.Empty
-	11, // 23: users.UsersService.GetLinkedAccountsByPlatform:output_type -> users.GetLinkedAccountsResponse
+	1,  // 23: users.UsersService.GetLinkedAccount:output_type -> users.LinkedAccount
-	11, // 24: users.UsersService.GetLinkedAccountsByUserAndPlatform:output_type -> users.GetLinkedAccountsResponse
+	11, // 24: users.UsersService.GetLinkedAccountsByPlatform:output_type -> users.GetLinkedAccountsResponse
-	16, // [16:25] is the sub-list for method output_type
+	11, // 25: users.UsersService.GetLinkedAccountsByUserAndPlatform:output_type -> users.GetLinkedAccountsResponse
-	7,  // [7:16] is the sub-list for method input_type
+	13, // 26: users.UsersService.ResolveLinkedAccount:output_type -> users.ResolveLinkedAccountResponse
+	17, // [17:27] is the sub-list for method output_type
+	7,  // [7:17] is the sub-list for method input_type
 	7,  // [7:7] is the sub-list for extension type_name
 	7,  // [7:7] is the sub-list for extension extendee
 	0,  // [0:7] is the sub-list for field type_name
@@ -853,7 +978,7 @@ func file_users_proto_init() {
 			GoPackagePath: reflect.TypeOf(x{}).PkgPath(),
 			RawDescriptor: unsafe.Slice(unsafe.StringData(file_users_proto_rawDesc), len(file_users_proto_rawDesc)),
 			NumEnums:      0,
-			NumMessages:   12,
+			NumMessages:   14,
 			NumExtensions: 0,
 			NumServices:   1,
 		},

users.proto

@@ -19,6 +19,24 @@ service UsersService {
   rpc GetLinkedAccount(GetLinkedAccountRequest) returns (LinkedAccount);
   rpc GetLinkedAccountsByPlatform(GetLinkedAccountsByPlatformRequest) returns (GetLinkedAccountsResponse);
   rpc GetLinkedAccountsByUserAndPlatform(GetLinkedAccountsByUserAndPlatformRequest) returns (GetLinkedAccountsResponse);
+
+  // ResolveLinkedAccount resolves the global user owning a platform account
+  // (e.g. platform="telegram", account_id="<numeric Telegram user id>").
+  // This is a read-only, non-creating server-to-server identity lookup used
+  // by other services (e.g. l-ai-chat Telegram bridge) to map a transport
+  // identity to the stable global_user_id. It NEVER creates a global user or
+  // a linked account.
+  //
+  // Identity boundary invariant: (platform, account_id) -> at most one
+  // canonical global_user_id.
+  //   - no rows            -> linked=false (account not linked; nothing created)
+  //   - one distinct global user -> that user; if several legacy link rows
+  //     exist for the SAME user, the oldest (smallest linked_account id) wins,
+  //     deterministic across retries
+  //   - more than one distinct global user -> FAILS CLOSED with
+  //     FailedPrecondition (ambiguous identity); callers must not persist
+  //     anything under a guessed identity
+  rpc ResolveLinkedAccount(ResolveLinkedAccountRequest) returns (ResolveLinkedAccountResponse);
 }
 
 message GlobalUser {
@@ -88,3 +106,14 @@ message GetLinkedAccountsByUserAndPlatformRequest {
 message GetLinkedAccountsResponse {
   repeated LinkedAccount accounts = 1;
 }
+
+message ResolveLinkedAccountRequest {
+  string platform = 1;
+  string account_id = 2;
+}
+
+message ResolveLinkedAccountResponse {
+  bool linked = 1;
+  int64 global_user_id = 2;
+  string display_name = 3;
+}

users_grpc.pb.go

@@ -1,7 +1,7 @@
 // Code generated by protoc-gen-go-grpc. DO NOT EDIT.
 // versions:
 // - protoc-gen-go-grpc v1.6.1
-// - protoc             v7.34.0
+// - protoc             v7.34.2
 // source: users.proto
 
 package proto
@@ -29,6 +29,7 @@ const (
 	UsersService_GetLinkedAccount_FullMethodName                   = "/users.UsersService/GetLinkedAccount"
 	UsersService_GetLinkedAccountsByPlatform_FullMethodName        = "/users.UsersService/GetLinkedAccountsByPlatform"
 	UsersService_GetLinkedAccountsByUserAndPlatform_FullMethodName = "/users.UsersService/GetLinkedAccountsByUserAndPlatform"
+	UsersService_ResolveLinkedAccount_FullMethodName               = "/users.UsersService/ResolveLinkedAccount"
 )
 
 // UsersServiceClient is the client API for UsersService service.
@@ -46,6 +47,17 @@ type UsersServiceClient interface {
 	GetLinkedAccount(ctx context.Context, in *GetLinkedAccountRequest, opts ...grpc.CallOption) (*LinkedAccount, error)
 	GetLinkedAccountsByPlatform(ctx context.Context, in *GetLinkedAccountsByPlatformRequest, opts ...grpc.CallOption) (*GetLinkedAccountsResponse, error)
 	GetLinkedAccountsByUserAndPlatform(ctx context.Context, in *GetLinkedAccountsByUserAndPlatformRequest, opts ...grpc.CallOption) (*GetLinkedAccountsResponse, error)
+	// ResolveLinkedAccount resolves the global user owning a platform account
+	// (e.g. platform="telegram", account_id="<numeric Telegram user id>").
+	// This is a read-only, non-creating server-to-server identity lookup used
+	// by other services (e.g. l-ai-chat Telegram bridge) to map a transport
+	// identity to the stable global_user_id. It NEVER creates a global user or
+	// a linked account.
+	//
+	// linked=false means the account is not linked to any global user. When
+	// several links exist for the same account (legacy duplicates), the oldest
+	// (smallest linked_account id) wins — deterministic across retries.
+	ResolveLinkedAccount(ctx context.Context, in *ResolveLinkedAccountRequest, opts ...grpc.CallOption) (*ResolveLinkedAccountResponse, error)
 }
 
 type usersServiceClient struct {
@@ -146,6 +158,16 @@ func (c *usersServiceClient) GetLinkedAccountsByUserAndPlatform(ctx context.Cont
 	return out, nil
 }
 
+func (c *usersServiceClient) ResolveLinkedAccount(ctx context.Context, in *ResolveLinkedAccountRequest, opts ...grpc.CallOption) (*ResolveLinkedAccountResponse, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(ResolveLinkedAccountResponse)
+	err := c.cc.Invoke(ctx, UsersService_ResolveLinkedAccount_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
 // UsersServiceServer is the server API for UsersService service.
 // All implementations must embed UnimplementedUsersServiceServer
 // for forward compatibility.
@@ -161,6 +183,17 @@ type UsersServiceServer interface {
 	GetLinkedAccount(context.Context, *GetLinkedAccountRequest) (*LinkedAccount, error)
 	GetLinkedAccountsByPlatform(context.Context, *GetLinkedAccountsByPlatformRequest) (*GetLinkedAccountsResponse, error)
 	GetLinkedAccountsByUserAndPlatform(context.Context, *GetLinkedAccountsByUserAndPlatformRequest) (*GetLinkedAccountsResponse, error)
+	// ResolveLinkedAccount resolves the global user owning a platform account
+	// (e.g. platform="telegram", account_id="<numeric Telegram user id>").
+	// This is a read-only, non-creating server-to-server identity lookup used
+	// by other services (e.g. l-ai-chat Telegram bridge) to map a transport
+	// identity to the stable global_user_id. It NEVER creates a global user or
+	// a linked account.
+	//
+	// linked=false means the account is not linked to any global user. When
+	// several links exist for the same account (legacy duplicates), the oldest
+	// (smallest linked_account id) wins — deterministic across retries.
+	ResolveLinkedAccount(context.Context, *ResolveLinkedAccountRequest) (*ResolveLinkedAccountResponse, error)
 	mustEmbedUnimplementedUsersServiceServer()
 }
 
@@ -198,6 +231,9 @@ func (UnimplementedUsersServiceServer) GetLinkedAccountsByPlatform(context.Conte
 func (UnimplementedUsersServiceServer) GetLinkedAccountsByUserAndPlatform(context.Context, *GetLinkedAccountsByUserAndPlatformRequest) (*GetLinkedAccountsResponse, error) {
 	return nil, status.Error(codes.Unimplemented, "method GetLinkedAccountsByUserAndPlatform not implemented")
 }
+func (UnimplementedUsersServiceServer) ResolveLinkedAccount(context.Context, *ResolveLinkedAccountRequest) (*ResolveLinkedAccountResponse, error) {
+	return nil, status.Error(codes.Unimplemented, "method ResolveLinkedAccount not implemented")
+}
 func (UnimplementedUsersServiceServer) mustEmbedUnimplementedUsersServiceServer() {}
 func (UnimplementedUsersServiceServer) testEmbeddedByValue()                      {}
 
@@ -381,6 +417,24 @@ func _UsersService_GetLinkedAccountsByUserAndPlatform_Handler(srv interface{}, c
 	return interceptor(ctx, in, info, handler)
 }
 
+func _UsersService_ResolveLinkedAccount_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(ResolveLinkedAccountRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(UsersServiceServer).ResolveLinkedAccount(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: UsersService_ResolveLinkedAccount_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(UsersServiceServer).ResolveLinkedAccount(ctx, req.(*ResolveLinkedAccountRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
 // UsersService_ServiceDesc is the grpc.ServiceDesc for UsersService service.
 // It's only intended for direct use with grpc.RegisterService,
 // and not to be introspected or modified (even as a copy)
@@ -424,6 +478,10 @@ var UsersService_ServiceDesc = grpc.ServiceDesc{
 			MethodName: "GetLinkedAccountsByUserAndPlatform",
 			Handler:    _UsersService_GetLinkedAccountsByUserAndPlatform_Handler,
 		},
+		{
+			MethodName: "ResolveLinkedAccount",
+			Handler:    _UsersService_ResolveLinkedAccount_Handler,
+		},
 	},
 	Streams:  []grpc.StreamDesc{},
 	Metadata: "users.proto",