add readme to declare lint macro

Author: oslfmt

lints/type_cosplay/src/lib.rs

@@ -19,21 +19,37 @@ use solana_lints::{paths, utils::visit_expr_no_bodies};
 use if_chain::if_chain;
 
 dylint_linting::impl_late_lint! {
-    /// **What it does:**
-    /// 
-    /// **Why is this bad?**
-    ///
-    /// **Known problems:** When only one enum is serialized, may miss certain edge cases.
+    /// **What it does:** Checks that all deserialized types have a proper discriminant so that
+    /// all types are guaranteed to deserialize differently.
+
+    /// Instead of searching for equivalent types and checking to make sure those specific
+    /// types have a discriminant, this lint takes a more strict approach and instead enforces
+    /// all deserialized types it collects, to have a discriminant, regardless of whether the
+    /// types are equivalent or not.
+
+    /// We define a proper discriminant as an enum with as many variants as there are struct
+    /// types in the program. Further, the discriminant should be the first field of every
+    /// struct in order to avoid overwrite by arbitrary length fields, like vectors.
+
+    /// A second case of a proper discriminant is when a single enum contains as variants all the struct
+    /// types that will be deserialized. This "umbrella" enum essentially has a built-in
+    /// discriminant. If it is the only type that is deserialized, then all struct types
+    /// are guaranteed to be unique since the program will have to match a specific variant.
     ///
-    /// **Example:**
+    /// **Why is this bad?**
+    /// The type cosplay issue is when one account type can be substituted for another account type.
+    /// This occurs when a type deserializes exactly the same as another type, such that you can't
+    /// tell the difference between deserialized type `X` and deserialized type `Y`. This allows a
+    /// malicious user to substitute `X` for `Y` or vice versa, and the code may perform unauthorized
+    /// actions with the bytes.
     ///
-    /// ```rust
-    /// // example code where a warning is issued
-    /// ```
-    /// Use instead:
-    /// ```rust
-    /// // example code that does not raise a warning
-    /// ```
+    /// **Known problems:** In the case when only one enum is deserialized, this lint by default
+    /// regards that as secure. However, this is not always the case. For example, if the program
+    /// defines another enum and serializes, but never deserializes it, a user could create this enum,
+    /// and, if it deserializes the same as the first enum, then this may be a possible vulnerability.
+
+    /// Furthermore, one may have alternative definitions of a discriminant, such as using a bool,
+    /// or u8, and not an enum. This will flag a false positive.
     pub TYPE_COSPLAY,
     Warn,
     "type is equivalent to another type",

lints/type_cosplay/ui/secure-2/src/lib.rs

@@ -23,16 +23,15 @@ pub mod type_cosplay_secure {
                 }
                 msg!("GM {}", user.authority);
                 Ok(())
-            },
+            }
             AccountDiscriminant::Metadata(metadata) => {
                 if ctx.accounts.user.owner != ctx.program_id {
                     return Err(ProgramError::IllegalOwner);
                 }
                 msg!("GM {}", metadata.account);
                 Ok(())
-            },
+            }
         }
-
     }
 }