That's utterly incorrect. It's absolutely a legal right, both statutorily and by customary international law. Don't mistake the fact that certain law is described as 'customary' or 'conventional' as meaning it's any less 'legal'. International and domestic courts absolutely recognize and base decisions on customary or conventional international law. Obviously not all CIL has crystallized in state practice and opinio juris to an equal extent, but the customary law around diplomatic immunity is as solid as it gets.
In the case of diplomatic immunities, though, you will find those various immunities spelled out in the 1961 Vienna Convention on Diplomatic Relations. Criminal immunity, for instance, is found in Article 31 of that treaty. Further, Canada has domestically codified it in the Foreign Missions and International Organizations Act, which imports the immunities sections of the VCDR into our own domestic law. It is typical for states party to international treaties to pass domestic laws giving those treaties effect.
Not criminally charging a accredited diplomatic agent is not a matter of prosecutorial discretion that is optional; it's just flat out prohibited - except for where the sending state waives immunity, which can and does happen occasionally.
However, the immunities attached to a foreign head of state for actions taken within their own country are a sovereign immunity matter, not a diplomatic immunity one. They're different immunities, distinct from each other.