fix possible type confusion in PyClassGuardMut::as_super (#6104)

* fix possible type confusion in `PyClassGuardMut::as_super`

* Update src/pyclass/guard.rs

---------

Co-authored-by: David Hewitt <mail@davidhewitt.dev>

Author: Icxolu

newsfragments/6104.added.md

@@ -0,0 +1 @@
+added `PyClassGuardMapSuper`

newsfragments/6104.fixed.md

@@ -0,0 +1 @@
+fixed soundness issue caused by exposing a mutable reference from `PyClassGuardMut::as_super` by moving into `PyClassGuardMutSuper`

src/pyclass.rs

@@ -11,6 +11,7 @@ pub(crate) use self::create_type_object::{create_type_object, PyClassTypeObject}
 pub use self::gc::{PyTraverseError, PyVisit};
 pub use self::guard::{
     PyClassGuard, PyClassGuardError, PyClassGuardMap, PyClassGuardMut, PyClassGuardMutError,
+    PyClassGuardMutSuper,
 };
 
 /// Types that can be used as Python classes.

src/pyclass/guard.rs

@@ -701,9 +701,15 @@ where
     /// super-superclass (and so on).
     ///
     /// See [`PyClassGuard::as_super`] for more.
-    pub fn as_super(&mut self) -> &mut PyClassGuardMut<'a, T::BaseType> {
-        // SAFETY: `PyClassGuardMut<T>` and `PyClassGuardMut<U>` have the same layout
-        unsafe { NonNull::from(self).cast().as_mut() }
+    ///
+    /// # Note
+    ///
+    /// The mutable reference to the base type is not exposed directly, but through [`PyClassGuardMutSuper`].
+    pub fn as_super(&mut self) -> PyClassGuardMutSuper<'_, 'a, T::BaseType> {
+        PyClassGuardMutSuper {
+            // SAFETY: `PyClassGuardMut<T>` and `PyClassGuardMut<U>` have the same layout
+            guard: unsafe { NonNull::from(self).cast().as_mut() },
+        }
     }
 
     /// Gets a `PyClassGuardMut<T::BaseType>`.
@@ -842,6 +848,59 @@ impl From<PyClassGuardMutError<'_, '_>> for PyErr {
     }
 }
 
+/// Wraps a borrowed mutable reference to the base class `T::BaseType` of a PyClass `T`
+///
+/// See [`PyClassGuardMut::as_super`]
+#[repr(transparent)]
+pub struct PyClassGuardMutSuper<'a, 'g, T: PyClass<Frozen = False>> {
+    // NOTE: Exposing this directly from `PyClassGuardMut::as_super` would allow swapping this
+    // `guard` with another guard of the same basetype but different subtype. That is unsound as the
+    // original `PyClassGuardMut` allows access to the `T` stored inside. By wrapping the guard in a
+    // new type which does not expose a mutable reference to the guard directly we ensure that this
+    // swap is impossible.
+    guard: &'a mut PyClassGuardMut<'g, T>,
+}
+
+impl<'a, 'g, T> PyClassGuardMutSuper<'a, 'g, T>
+where
+    T: PyClass<Frozen = False>,
+    T::BaseType: PyClass<Frozen = False>,
+{
+    /// Borrows a mutable reference to `PyClassGuardMut<T::BaseType>`.
+    ///
+    /// See [`PyClassGuardMut::as_super`] for more.
+    pub fn as_super(&mut self) -> PyClassGuardMutSuper<'a, 'g, T::BaseType> {
+        PyClassGuardMutSuper {
+            // SAFETY: `PyClassGuardMut<T>` and `PyClassGuardMut<U>` have the same layout
+            guard: unsafe { NonNull::from(&mut *self.guard).cast().as_mut() },
+        }
+    }
+}
+
+impl<T> Deref for PyClassGuardMutSuper<'_, '_, T>
+where
+    T: PyClass<Frozen = False>,
+{
+    type Target = T;
+
+    fn deref(&self) -> &T {
+        // SAFETY: `PyClassObject<T>` contains a valid `T`, by construction no
+        // alias is enforced
+        unsafe { &*self.guard.as_class_object().get_ptr().cast_const() }
+    }
+}
+
+impl<T> DerefMut for PyClassGuardMutSuper<'_, '_, T>
+where
+    T: PyClass<Frozen = False>,
+{
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        // SAFETY: `PyClassObject<T>` contains a valid `T`, by construction no
+        // alias is enforced
+        unsafe { &mut *self.guard.as_class_object().get_ptr() }
+    }
+}
+
 /// Wraps a borrowed mutable reference `U` to a value stored inside of a pyclass `T`
 ///
 /// See [`PyClassGuardMut::map`]