@elizaos/skills 2.0.0-alpha.3

package/skills/sharp-edges/skills/sharp-edges/references/crypto-apis.md

@@ -0,0 +1,190 @@
+# Cryptographic API Footguns
+
+Detailed patterns for identifying misuse-prone cryptographic interfaces.
+
+## Algorithm Selection Anti-Patterns
+
+### The "alg" Header Attack (JWT)
+
+The JSON Web Token standard allows the token itself to specify which algorithm to use for verification. This is catastrophically wrong.
+
+**Attack 1: "none" algorithm**
+```json
+{"alg": "none", "typ": "JWT"}
+```
+Many libraries accept this and skip signature verification entirely.
+
+**Attack 2: Algorithm confusion (RS256 → HS256)**
+- Server expects RSA signature, uses public key for verification
+- Attacker changes algorithm to HMAC, uses *public key* as HMAC secret
+- Public key is public, so attacker can forge valid signatures
+
+**Root cause**: Trusting untrusted input to select security mechanisms.
+
+**Fix**: Never let data dictate algorithm. Use one algorithm, hardcoded.
+
+### Cipher Mode Parameters
+
+```python
+# DANGEROUS: mode is selectable
+def encrypt(plaintext, key, mode="ECB"):  # ECB is never correct
+    ...
+
+# BAD: accepts any OpenSSL cipher string
+cipher = OpenSSL::Cipher.new(user_selected_cipher)
+
+# GOOD: no parameters
+def encrypt(plaintext, key):  # internally uses AES-256-GCM
+    ...
+```
+
+**Detection**: Parameters named `mode`, `cipher`, `algorithm`, `hash_type`
+
+### Hash Algorithm Downgrade
+
+```php
+// PHP's hash() accepts ANY algorithm
+hash("crc32", $password);  // Valid call, terrible security
+hash("md5", $password);    // Valid call, broken security
+hash("sha256", $password); // Valid call, still wrong for passwords
+
+// Password functions limit choices
+password_hash($password, PASSWORD_ARGON2ID);  // Better
+```
+
+**Pattern**: APIs that accept algorithm as string instead of restricting to safe subset.
+
+## Key/Nonce/IV Confusion
+
+### Indistinguishable Byte Arrays
+
+```go
+// All three are just []byte - easy to swap
+func Encrypt(plaintext, key, nonce []byte) []byte
+
+// Easy mistakes:
+Encrypt(plaintext, nonce, key)  // Swapped - compiles fine
+Encrypt(plaintext, key, key)    // Reused key as nonce - compiles fine
+```
+
+**Fix**: Distinct types
+
+```go
+type EncryptionKey [32]byte
+type Nonce [24]byte
+
+func Encrypt(plaintext []byte, key EncryptionKey, nonce Nonce) []byte
+// Now type system catches swaps
+```
+
+### Nonce Reuse
+
+```python
+# DANGEROUS: nonce parameter with no guidance
+def encrypt(plaintext, key, nonce):
+    ...
+
+# Developer "simplifies" by reusing:
+nonce = b'\x00' * 12
+encrypt(msg1, key, nonce)
+encrypt(msg2, key, nonce)  # Catastrophic with GCM/ChaCha
+```
+
+**Fix**: Generate nonces internally, return them with ciphertext.
+
+## Comparison Footguns
+
+### Timing-Safe vs. Regular Comparison
+
+```python
+# These look identical but have different security properties
+if computed_mac == expected_mac:  # VULNERABLE: timing attack
+if hmac.compare_digest(computed_mac, expected_mac):  # Safe
+```
+
+**The problem**: Developers don't know to use special comparison. Default string equality is vulnerable.
+
+**Detection**: Direct equality checks on MACs, signatures, hashes, tokens.
+
+### Boolean Confusion
+
+```python
+# Signature verification APIs
+result = verify(signature, message, key)
+
+# Some return True/False
+if verify(...):  # Must check return value
+
+# Some raise exceptions
+verify(...)  # Failure = exception, no return to check
+
+# Developers mixing these up = vulnerabilities
+```
+
+## Padding Oracle Enablers
+
+### Raw Decryption APIs
+
+```python
+# DANGEROUS: returns plaintext even if padding invalid
+def decrypt(ciphertext, key):
+    # ... decrypt ...
+    return unpad(plaintext)  # Throws on bad padding
+
+# Attacker can distinguish:
+# - Valid padding → success
+# - Invalid padding → exception
+
+# This distinction enables padding oracle attacks
+```
+
+**Fix**: Decrypt-then-MAC (or authenticated encryption). Never expose padding validity.
+
+### Error Message Differentiation
+
+```
+# DANGEROUS error messages
+"Invalid padding"           # Padding oracle signal
+"MAC verification failed"   # Different error = oracle
+"Decryption failed"         # Good: single error for all failures
+```
+
+## Key Derivation Footguns
+
+### Using Hashes Instead of KDFs
+
+```python
+# DANGEROUS: hash is not a KDF
+key = hashlib.sha256(password.encode()).digest()
+
+# Developer reasoning: "SHA-256 is secure"
+# Reality: Fast hash enables brute force
+
+# CORRECT: use actual KDF
+key = hashlib.scrypt(password.encode(), salt=salt, n=2**14, r=8, p=1)
+```
+
+### Password Storage Misuse
+
+```python
+# DANGEROUS: encryption is not password storage
+encrypted_password = encrypt(password, master_key)
+# Compromise of master_key = all passwords exposed
+
+# CORRECT: one-way hash with salt
+hashed_password = argon2.hash(password)
+# No key to steal; each password salted differently
+```
+
+## Safe API Design Checklist
+
+For cryptographic APIs, verify:
+
+- [ ] **No algorithm selection**: One safe algorithm, hardcoded
+- [ ] **No mode selection**: GCM/ChaCha20-Poly1305 only, no ECB/CBC
+- [ ] **Distinct types**: Keys, nonces, ciphertexts are different types
+- [ ] **Internal nonce generation**: Don't require developer to provide
+- [ ] **Authenticated encryption**: Encrypt-then-MAC or AEAD built in
+- [ ] **Constant-time comparison**: Default or only comparison method
+- [ ] **Uniform errors**: Same error for all decryption failures
+- [ ] **KDF for passwords**: Argon2/scrypt/bcrypt, not raw hashes

package/skills/sharp-edges/skills/sharp-edges/references/lang-c.md

@@ -0,0 +1,205 @@
+# C/C++ Sharp Edges
+
+## Integer Overflow is Undefined Behavior
+
+```c
+// DANGEROUS: Signed overflow is UB, compiler can optimize away checks
+int x = INT_MAX;
+if (x + 1 > x) {  // Compiler may assume always true (UB)
+    // Overflow check optimized away!
+}
+
+// DANGEROUS: Size calculations
+size_t size = user_count * sizeof(struct User);
+// If user_count * sizeof overflows, allocates tiny buffer
+void *buf = malloc(size);
+```
+
+**The Problem**: Signed integer overflow is undefined behavior. Compilers assume it never happens and optimize accordingly—including removing overflow checks.
+
+**Detection**: Look for arithmetic on signed integers, especially in size calculations, loop bounds, and allocation sizes.
+
+## Buffer Handling
+
+```c
+// DANGEROUS: No bounds checking
+char buf[64];
+strcpy(buf, user_input);       // Classic overflow
+sprintf(buf, "Hello %s", name); // Format + overflow
+gets(buf);                      // Never use, removed in C11
+
+// DANGEROUS: Off-by-one
+char buf[64];
+strncpy(buf, src, 64);         // NOT null-terminated if src >= 64!
+buf[63] = '\0';                // Must do manually
+
+// DANGEROUS: snprintf return value
+int ret = snprintf(buf, sizeof(buf), "%s", long_string);
+// ret is length that WOULD be written, not actual length
+// If ret >= sizeof(buf), output was truncated
+```
+
+**Safe Alternatives**:
+- `strlcpy`, `strlcat` (BSD, not standard)
+- `snprintf` with proper return value checking
+- C11 Annex K `strcpy_s`, `sprintf_s` (limited support)
+
+## Format Strings
+
+```c
+// DANGEROUS: User controls format
+printf(user_input);            // Format string attack
+syslog(LOG_INFO, user_input);  // Same problem
+fprintf(stderr, user_input);   // Same problem
+
+// Attacker input: "%x%x%x%x" → leaks stack
+// Attacker input: "%n" → writes to memory
+
+// SAFE: Format as literal
+printf("%s", user_input);
+```
+
+**Detection**: Any `*printf` family function where the format argument is not a string literal.
+
+## Memory Cleanup
+
+```c
+// DANGEROUS: Compiler may optimize away
+char password[64];
+// ... use password ...
+memset(password, 0, sizeof(password));  // May be removed!
+
+// The compiler sees: "writes to password, then password goes out of scope"
+// Optimization: "dead store elimination" removes the memset
+```
+
+**Safe Alternatives**:
+```c
+// Option 1: explicit_bzero (BSD, glibc 2.25+)
+explicit_bzero(password, sizeof(password));
+
+// Option 2: SecureZeroMemory (Windows)
+SecureZeroMemory(password, sizeof(password));
+
+// Option 3: Volatile function pointer trick
+static void *(*const volatile memset_ptr)(void *, int, size_t) = memset;
+memset_ptr(password, 0, sizeof(password));
+
+// Option 4: C11 memset_s (limited support)
+memset_s(password, sizeof(password), 0, sizeof(password));
+```
+
+## Uninitialized Variables
+
+```c
+// DANGEROUS: Uninitialized stack variables
+int result;
+if (condition) {
+    result = compute();
+}
+return result;  // Uninitialized if !condition
+
+// DANGEROUS: Uninitialized struct padding
+struct {
+    char a;      // 1 byte
+    // 3 bytes padding (uninitialized)
+    int b;       // 4 bytes
+} s;
+s.a = 'x';
+s.b = 42;
+send(sock, &s, sizeof(s), 0);  // Leaks 3 bytes of stack
+```
+
+**Fix**: Use `= {0}` initialization or `memset`.
+
+## Double Free and Use-After-Free
+
+```c
+// DANGEROUS: Double free
+free(ptr);
+// ... later ...
+free(ptr);  // Heap corruption
+
+// DANGEROUS: Use after free
+free(ptr);
+ptr->value = 42;  // Writing to freed memory
+
+// DANGEROUS: Returning pointer to local
+char *get_greeting() {
+    char buf[64] = "hello";
+    return buf;  // Stack pointer invalid after return
+}
+```
+
+**Mitigations**:
+- Set pointer to NULL after free: `free(ptr); ptr = NULL;`
+- Use static analysis (Coverity, cppcheck)
+- Use AddressSanitizer in testing
+
+## Signal Handler Issues
+
+```c
+// DANGEROUS: Non-async-signal-safe functions in handler
+void handler(int sig) {
+    printf("Got signal\n");  // NOT async-signal-safe
+    malloc(100);             // NOT async-signal-safe
+    free(ptr);               // NOT async-signal-safe
+}
+
+// Async-signal-safe: write(), _exit(), signal()
+// Most functions including printf, malloc, free are NOT safe
+```
+
+## Time-of-Check to Time-of-Use (TOCTOU)
+
+```c
+// DANGEROUS: File state can change between check and use
+if (access(filename, W_OK) == 0) {
+    // Attacker replaces file with symlink here
+    fd = open(filename, O_WRONLY);  // Opens different file
+}
+```
+
+**Fix**: Open first, then check permissions on the file descriptor.
+
+## Variadic Function Pitfalls
+
+```c
+// DANGEROUS: Wrong format specifier
+printf("%d", (long long)value);  // %d expects int, not long long
+printf("%s", 42);                // Interprets 42 as pointer
+
+// DANGEROUS: Missing sentinel
+execl("/bin/ls", "ls", "-l", NULL);  // NULL required!
+execl("/bin/ls", "ls", "-l");        // Missing NULL = UB
+```
+
+## Macro Pitfalls
+
+```c
+// DANGEROUS: Macro arguments evaluated multiple times
+#define SQUARE(x) ((x) * (x))
+int a = 5;
+SQUARE(a++);  // Expands to ((a++) * (a++)) - increments twice!
+
+// DANGEROUS: Operator precedence
+#define ADD(a, b) a + b
+int x = ADD(1, 2) * 3;  // Expands to 1 + 2 * 3 = 7, not 9
+
+// SAFER: Fully parenthesize
+#define ADD(a, b) ((a) + (b))
+```
+
+## Detection Patterns
+
+Search for these patterns in C/C++ code:
+
+| Pattern | Risk |
+|---------|------|
+| `strcpy`, `strcat`, `gets`, `sprintf` | Buffer overflow |
+| `printf(var)` where var is not literal | Format string |
+| `memset` before variable goes out of scope | Dead store elimination |
+| `free(ptr)` without `ptr = NULL` | Double free risk |
+| `malloc` without overflow check on size | Integer overflow |
+| Arithmetic on `int` near INT_MAX | Signed overflow UB |
+| `strncpy` without explicit null termination | Missing terminator |

package/skills/sharp-edges/skills/sharp-edges/references/lang-csharp.md

@@ -0,0 +1,285 @@
+# C# Sharp Edges
+
+## Nullable Reference Types
+
+```csharp
+// DANGEROUS: NRT is opt-in and warnings-only by default
+// Project must enable: <Nullable>enable</Nullable>
+
+string? nullable = null;
+string nonNull = nullable;  // Warning, but compiles!
+nonNull.Length;  // NullReferenceException at runtime
+
+// DANGEROUS: Suppression operator
+string value = possiblyNull!;  // Suppresses warning, doesn't fix bug
+
+// DANGEROUS: Default enabled doesn't mean enforced
+// Many legacy codebases have NRT enabled with thousands of warnings ignored
+```
+
+**Fix**: Enable NRT AND treat warnings as errors:
+```xml
+<Nullable>enable</Nullable>
+<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+```
+
+## Default Struct Values
+
+```csharp
+// DANGEROUS: Structs have default(T) that may be invalid
+struct Connection {
+    public string Host;  // Default: null
+    public int Port;     // Default: 0
+}
+
+var conn = default(Connection);
+// conn.Host is null, conn.Port is 0 - probably invalid state
+
+// DANGEROUS: Array of structs
+var connections = new Connection[10];
+// All 10 are default(Connection) - invalid state
+```
+
+**Fix**: Use constructors, or make structs readonly with init validation.
+
+## IDisposable Leaks
+
+```csharp
+// DANGEROUS: Resources not disposed on exception
+var conn = new SqlConnection(connectionString);
+conn.Open();
+// Exception here = connection never closed
+Process(conn);
+conn.Dispose();
+
+// DANGEROUS: Nested disposables
+var outer = new Outer();  // Creates inner disposable
+// Exception before outer.Dispose() = inner leaked
+```
+
+**Fix**: Use `using` statement or declaration:
+```csharp
+using var conn = new SqlConnection(connectionString);
+conn.Open();
+// Disposed even on exception
+
+using (var conn = new SqlConnection(...)) {
+    // Scoped disposal
+}
+```
+
+## Async/Await Pitfalls
+
+```csharp
+// DANGEROUS: async void - exceptions can't be caught
+async void FireAndForget() {
+    throw new Exception("Lost!");  // Crashes the process
+}
+
+// DANGEROUS: Deadlock with .Result
+async Task DoWork() {
+    await Task.Delay(100);
+}
+
+void Caller() {
+    DoWork().Result;  // Deadlock in UI/ASP.NET contexts!
+}
+
+// DANGEROUS: Forgetting to await
+async Task Process() {
+    DoWorkAsync();  // Not awaited - runs in background
+    // Exceptions lost, no completion guarantee
+}
+```
+
+**Fix**: Always return Task, use `ConfigureAwait(false)` in libraries:
+```csharp
+async Task DoWorkAsync() {
+    await Task.Delay(100).ConfigureAwait(false);
+}
+```
+
+## LINQ Deferred Execution
+
+```csharp
+// DANGEROUS: LINQ queries are lazy
+var query = items.Where(x => x.IsValid);
+// Nothing executed yet!
+
+items.Add(newItem);  // Added after query defined
+foreach (var item in query) {
+    // newItem IS included - query executes here
+}
+
+// DANGEROUS: Multiple enumeration
+var filtered = items.Where(x => ExpensiveCheck(x));
+var count = filtered.Count();    // Executes query
+var first = filtered.First();    // Executes query AGAIN
+```
+
+**Fix**: Materialize with `.ToList()` or `.ToArray()` when needed.
+
+## String Comparison
+
+```csharp
+// DANGEROUS: Culture-sensitive comparison by default
+"stra\u00dfe".Equals("strasse");  // Depends on culture!
+
+// DANGEROUS: Turkish-I problem
+"INFO".ToLower() == "info"  // FALSE in Turkish culture!
+// Turkish: I → ı (dotless i), İ → i
+
+// DANGEROUS: Ordinal vs linguistic
+string.Compare("a", "A");  // Culture-dependent
+```
+
+**Fix**: Use ordinal comparison for identifiers:
+```csharp
+string.Equals(a, b, StringComparison.Ordinal);
+string.Equals(a, b, StringComparison.OrdinalIgnoreCase);
+```
+
+## Boxing and Unboxing
+
+```csharp
+// DANGEROUS: Hidden boxing with value types
+int value = 42;
+object boxed = value;  // Boxing allocation
+int unboxed = (int)boxed;  // Unboxing
+
+// DANGEROUS: Interface boxing
+struct Point : IComparable<Point> { ... }
+IComparable<Point> comparable = point;  // Boxed!
+
+// DANGEROUS: LINQ with value types
+var ints = new[] { 1, 2, 3 };
+ints.Where(x => x > 1);  // Closure may box
+```
+
+## Equality Implementation
+
+```csharp
+// DANGEROUS: Incorrect equality implementation
+class MyClass {
+    public int Id;
+
+    public override bool Equals(object obj) {
+        return Id == ((MyClass)obj).Id;  // Throws if obj is null or wrong type
+    }
+
+    // DANGEROUS: Missing GetHashCode
+    // Objects that are Equal MUST have same hash code
+    // But: public override int GetHashCode() => ... // Missing!
+}
+```
+
+**Fix**: Implement correctly or use records (C# 9+):
+```csharp
+record MyRecord(int Id);  // Equality implemented correctly
+```
+
+## Lock Pitfalls
+
+```csharp
+// DANGEROUS: Locking on public object
+public object SyncRoot = new object();
+lock (SyncRoot) { }  // External code can deadlock
+
+// DANGEROUS: Locking on this
+lock (this) { }  // External code can lock same object
+
+// DANGEROUS: Locking on Type
+lock (typeof(MyClass)) { }  // Type objects are shared across AppDomains
+
+// DANGEROUS: Locking on string
+lock ("mylock") { }  // String interning makes this shared!
+```
+
+**Fix**: Lock on private readonly object:
+```csharp
+private readonly object _lock = new object();
+lock (_lock) { }
+```
+
+## Finalizers
+
+```csharp
+// DANGEROUS: Finalizer delays GC and can resurrect objects
+class Problematic {
+    ~Problematic() {
+        // This code runs on finalizer thread
+        // Can't access other managed objects safely
+        GlobalList.Add(this);  // Resurrection!
+    }
+}
+
+// DANGEROUS: Finalizer without dispose pattern
+// Object stays in memory longer (finalization queue)
+```
+
+**Fix**: Implement dispose pattern, avoid finalizers:
+```csharp
+class Proper : IDisposable {
+    private bool _disposed;
+
+    public void Dispose() {
+        Dispose(true);
+        GC.SuppressFinalize(this);
+    }
+
+    protected virtual void Dispose(bool disposing) {
+        if (_disposed) return;
+        if (disposing) { /* managed cleanup */ }
+        // unmanaged cleanup
+        _disposed = true;
+    }
+}
+```
+
+## Event Handler Memory Leaks
+
+```csharp
+// DANGEROUS: Event handlers keep objects alive
+class Publisher {
+    public event EventHandler Changed;
+}
+
+class Subscriber {
+    public Subscriber(Publisher pub) {
+        pub.Changed += OnChanged;  // Subscriber now rooted by Publisher
+        // Even if Subscriber should be collected, it won't be
+    }
+}
+```
+
+**Fix**: Unsubscribe in Dispose or use weak events.
+
+## Serialization
+
+```csharp
+// DANGEROUS: BinaryFormatter is insecure
+var formatter = new BinaryFormatter();
+formatter.Deserialize(untrustedStream);  // RCE vulnerability
+
+// Microsoft: "BinaryFormatter is dangerous and is not recommended"
+// Similar issues with NetDataContractSerializer, SoapFormatter
+```
+
+**Fix**: Use JSON, XML with known types, or protobuf.
+
+## Detection Patterns
+
+| Pattern | Risk |
+|---------|------|
+| `string? x = null; string y = x;` | NRT warning ignored |
+| `possiblyNull!` | Null suppression |
+| `new Connection[n]` for structs | Invalid default state |
+| `SqlConnection` without `using` | Resource leak |
+| `async void` | Unhandled exceptions |
+| `.Result` or `.Wait()` on Task | Deadlock |
+| Missing `await` before async call | Fire and forget |
+| `.Where()` without materialization | Multiple enumeration |
+| `string.Equals` without StringComparison | Culture bugs |
+| `lock (this)` or `lock (typeof(...))` | Deadlock risk |
+| `BinaryFormatter` | Deserialization RCE |
+| Event subscription without unsubscription | Memory leak |