@elizaos/skills 2.0.0-alpha.10

package/skills/sharp-edges/skills/sharp-edges/references/auth-patterns.md

@@ -0,0 +1,252 @@
+# Authentication & Session Footguns
+
+Patterns that make authentication and session management error-prone.
+
+## Password Handling
+
+### Comparison Vulnerabilities
+
+```python
+# DANGEROUS: Short-circuit evaluation
+def check_password(user_input, stored):
+    return user_input == stored  # Timing attack
+
+# DANGEROUS: Empty password bypass
+def check_password(user_input, stored):
+    if not stored:
+        return True  # No password set = access granted?
+    return constant_time_compare(user_input, stored)
+
+# DANGEROUS: Null bypass
+def authenticate(username, password):
+    user = get_user(username)
+    if user is None:
+        return None  # No user = return None
+    if password == user.password:  # None == None if both None
+        return user
+```
+
+### Length Limits That Truncate
+
+```python
+# DANGEROUS: Password truncated before hashing
+def hash_password(password: str) -> str:
+    password = password[:72]  # bcrypt limit
+    return bcrypt.hash(password)
+
+# User sets: "password123" + 64 more characters + "IMPORTANT_ENTROPY"
+# Stored: hash of just "password123" + first 61 characters
+# Attacker only needs to brute force truncated version
+```
+
+**Fix**: Reject passwords over limit; don't silently truncate.
+
+### Validation Ordering
+
+```python
+# DANGEROUS: Username enumeration
+def login(username, password):
+    user = db.get_user(username)
+    if not user:
+        return "User not found"  # Reveals user doesn't exist
+    if not verify_password(password, user.password_hash):
+        return "Wrong password"  # Reveals user DOES exist
+    return create_session(user)
+
+# SECURE: Uniform error
+def login(username, password):
+    user = db.get_user(username)
+    if not user or not verify_password(password, user.password_hash):
+        return "Invalid credentials"
+    return create_session(user)
+```
+
+## Session Management
+
+### Session Fixation Enablers
+
+```python
+# DANGEROUS: Session ID accepted from request
+def login(request):
+    session_id = request.cookies.get("session") or generate_session_id()
+    # Attacker gives victim a known session ID before login
+    # After login, attacker knows victim's session
+    sessions[session_id] = user
+```
+
+**Fix**: Always generate new session ID on authentication state change.
+
+### Token Generation Weakness
+
+```python
+# DANGEROUS: Predictable tokens
+import time
+session_id = hashlib.md5(str(time.time()).encode()).hexdigest()
+# Attacker knows approximate login time = can guess session
+
+# DANGEROUS: Insufficient entropy
+session_id = ''.join(random.choice('abcdef') for _ in range(8))
+# Only 6^8 = 1.6M possibilities
+
+# SECURE: Cryptographic randomness
+session_id = secrets.token_urlsafe(32)
+```
+
+### Session Timeout Footguns
+
+```python
+# DANGEROUS: Timeout of 0 means "never"?
+class SessionConfig:
+    timeout_seconds: int = 3600  # 1 hour
+    # What if someone sets 0? Infinite session?
+
+# DANGEROUS: Negative timeout
+if current_time - session_created > timeout:
+    # If timeout is negative, this is always False
+    # Session never expires
+```
+
+## Token/OTP Handling
+
+### OTP Lifetime Issues
+
+```python
+# DANGEROUS: lifetime=0 accepts all
+def verify_otp(code, user, lifetime=300):
+    if lifetime == 0:
+        return True  # Skip expiry check entirely
+
+# DANGEROUS: Negative lifetime
+    if otp.created_at + lifetime > current_time:
+        return True
+    # If lifetime is negative, always expired? Or underflow?
+
+# DANGEROUS: No rate limiting
+def verify_otp(code, user):
+    return code == user.current_otp
+    # Attacker can try all 1,000,000 6-digit codes
+```
+
+### Token Reuse
+
+```python
+# DANGEROUS: OTP valid until next OTP generated
+def verify_otp(code, user):
+    return code == user.otp
+
+# DANGEROUS: Reset token valid forever
+def verify_reset_token(token):
+    return token in valid_tokens
+    # Never expires, never invalidated on use
+
+# SECURE: Single-use, time-limited
+def verify_reset_token(token):
+    record = db.get_token(token)
+    if not record:
+        return False
+    if record.used or record.expired:
+        return False
+    record.mark_used()  # Invalidate immediately
+    return True
+```
+
+## Authorization Footguns
+
+### Role/Permission Accumulation
+
+```python
+# DANGEROUS: String-based permissions
+user.permissions = "read,write"
+user.permissions += ",admin"  # Too easy
+
+# DANGEROUS: Any-match logic
+def has_permission(user, required):
+    return any(p in user.permissions for p in required.split(","))
+# has_permission(user, "admin,readonly") - matches if ANY is present
+
+# DANGEROUS: Substring matching
+if "admin" in user.role:
+    grant_admin_access()
+# "readonly_admin_viewer" contains "admin"
+```
+
+### Missing Authorization Checks
+
+```python
+# DANGEROUS: Auth check in one place, not others
+@require_login
+def list_documents(request):
+    return Document.objects.all()
+
+def get_document(request, doc_id):
+    # Developer forgot @require_login
+    return Document.objects.get(id=doc_id)
+
+def delete_document(request, doc_id):
+    # Developer also forgot authorization check
+    Document.objects.get(id=doc_id).delete()
+```
+
+**Fix**: Centralized authorization; deny-by-default.
+
+### IDOR Enablers
+
+```python
+# DANGEROUS: User ID from request
+def get_profile(request):
+    user_id = request.GET["user_id"]  # Attacker changes this
+    return User.objects.get(id=user_id)
+
+# DANGEROUS: Sequential IDs
+user = User.objects.create(...)  # Gets ID 12345
+# Attacker tries 12344, 12346, etc.
+```
+
+## Multi-Factor Authentication
+
+### Bypassable MFA
+
+```python
+# DANGEROUS: MFA check in frontend only
+# API directly accessible without MFA
+
+# DANGEROUS: "Remember this device" with weak token
+device_token = hashlib.md5(user_agent.encode()).hexdigest()
+# Attacker spoofs User-Agent to bypass MFA
+
+# DANGEROUS: MFA disabled by user preference
+if user.preferences.get("mfa_enabled", True):
+    require_mfa()
+# Preference stored in same session = attacker disables it
+```
+
+### Recovery Code Issues
+
+```python
+# DANGEROUS: Predictable recovery codes
+recovery_code = str(user.id).zfill(8)  # Just the user ID
+
+# DANGEROUS: Unlimited recovery attempts
+for _ in range(1000000):
+    try_recovery_code(guess)
+
+# DANGEROUS: Recovery codes don't invalidate
+if code in user.recovery_codes:
+    login(user)
+    # Code still valid for reuse
+```
+
+## Auth API Design Checklist
+
+For authentication APIs, verify:
+
+- [ ] **Constant-time comparison**: Password/token checks use constant-time compare
+- [ ] **Empty value rejection**: Empty passwords/tokens explicitly rejected
+- [ ] **Uniform errors**: No user enumeration via different error messages
+- [ ] **Session regeneration**: New session ID on auth state changes
+- [ ] **Cryptographic tokens**: secrets module, not random or time-based
+- [ ] **Positive timeouts**: Zero/negative values rejected or have safe meaning
+- [ ] **Single-use tokens**: OTPs/reset tokens invalidated on use
+- [ ] **Rate limiting**: Brute force protection on all auth endpoints
+- [ ] **Authorization centralized**: Not scattered across endpoints
+- [ ] **MFA in backend**: Not bypassable by skipping frontend

package/skills/sharp-edges/skills/sharp-edges/references/case-studies.md

@@ -0,0 +1,274 @@
+# Real-World Case Studies
+
+Analysis of sharp edges in widely-used libraries. These aren't implementation bugs—they're design decisions that make secure usage difficult.
+
+## GNU Multiple Precision Arithmetic Library (GMP)
+
+GMP is used extensively for cryptographic implementations (RSA, Paillier, ElGamal, etc.) despite being fundamentally unsuitable for cryptography.
+
+### Sharp Edge: Variable-Time Operations
+
+**The Problem**: GMP operations are not constant-time. Timing varies based on input values.
+
+```c
+// DANGEROUS: Timing leaks secret exponent bits
+mpz_powm(result, base, secret_exponent, modulus);
+
+// Each bit of secret_exponent affects timing differently
+// Attacker can recover secret_exponent via timing analysis
+```
+
+**Why This Matters**:
+- Paillier encryption uses `mpz_powm` with secret keys
+- RSA implementations using GMP leak private key bits
+- Even "blinded" implementations often have residual timing leaks
+
+**Detection Pattern**: Any use of GMP (`mpz_*` functions) with secret values:
+- `mpz_powm`, `mpz_powm_sec` (the "sec" version is still not fully constant-time)
+- `mpz_mul`, `mpz_mod` with secret operands
+- `mpz_cmp` for secret comparison
+
+**Real Vulnerabilities**:
+- CVE-2018-16152: Timing attack on strongSwan IKEv2
+- Numerous academic papers demonstrating key recovery from GMP-based crypto
+
+### Sharp Edge: Memory Not Securely Cleared
+
+```c
+mpz_t secret_key;
+mpz_init(secret_key);
+// ... use secret_key ...
+mpz_clear(secret_key);  // Memory NOT securely wiped
+// Secret data may persist in freed memory
+```
+
+**The Problem**: `mpz_clear` doesn't zero memory before freeing. Secrets persist.
+
+### Sharp Edge: Confusing Import/Export API
+
+```c
+// What does this do?
+mpz_export(buf, &count, order, size, endian, nails, op);
+
+// Parameters:
+// - order: 1 = most significant word first, -1 = least significant
+// - endian: 1 = big, -1 = little, 0 = native
+// - nails: bits to skip at top of each word (?!)
+```
+
+**The Problem**: Seven parameters, three of which control byte ordering in different ways. Easy to get wrong, hard to verify correctness.
+
+### Mitigation
+
+For cryptographic use, prefer:
+- **libsodium** for common operations
+- **OpenSSL BIGNUM** (has constant-time variants)
+- **libgmp with mpz_powm_sec** (partial mitigation, not complete)
+
+---
+
+## OpenSSL
+
+The canonical example of a powerful but footgun-laden cryptographic library.
+
+### Sharp Edge: SSL_CTX_set_verify Callback
+
+```c
+// DANGEROUS: Easy to write callback that always returns 1
+SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER, verify_callback);
+
+int verify_callback(int preverify_ok, X509_STORE_CTX *ctx) {
+    // Developer thinks: "I'll add logging here"
+    log_certificate(ctx);
+    return 1;  // OOPS: Always accepts, ignoring preverify_ok!
+}
+```
+
+**The Problem**: The callback's return value determines whether verification succeeds. Developers often:
+- Return 1 (success) unconditionally while "just adding logging"
+- Forget that returning non-zero bypasses all verification
+- Copy-paste examples that return 1 for "debugging"
+
+**Correct Pattern**:
+```c
+int verify_callback(int preverify_ok, X509_STORE_CTX *ctx) {
+    if (!preverify_ok) {
+        // Log failure details
+        log_verification_failure(ctx);
+    }
+    return preverify_ok;  // Preserve original decision
+}
+```
+
+### Sharp Edge: Error Handling via ERR_get_error
+
+```c
+// DANGEROUS: Error easily ignored
+EVP_EncryptFinal_ex(ctx, outbuf, &outlen);
+// Did it succeed? Who knows!
+
+// Correct but verbose:
+if (EVP_EncryptFinal_ex(ctx, outbuf, &outlen) != 1) {
+    unsigned long err = ERR_get_error();
+    char buf[256];
+    ERR_error_string_n(err, buf, sizeof(buf));
+    // Handle error...
+}
+```
+
+**The Problem**:
+- Functions return 1 for success (not 0!)
+- Errors accumulate in a thread-local queue
+- Easy to forget to check, easy to check wrong way
+- Error queue must be cleared or errors persist
+
+### Sharp Edge: RAND_bytes vs RAND_pseudo_bytes
+
+```c
+// These look almost identical:
+RAND_bytes(buf, len);        // Cryptographically secure
+RAND_pseudo_bytes(buf, len); // NOT guaranteed secure!
+
+// Worse: RAND_pseudo_bytes returns 1 even when insecure
+int rc = RAND_pseudo_bytes(buf, len);
+// rc == 1 means "success", not "cryptographically random"
+// rc == 0 means "success but not crypto-strength" (!!)
+// rc == -1 means "not supported"
+```
+
+**The Problem**: Function names differ by one word; return values are confusing; the insecure function is not clearly marked dangerous.
+
+### Sharp Edge: Memory Ownership Confusion
+
+```c
+// Who frees this?
+X509 *cert = SSL_get_peer_certificate(ssl);
+// Answer: YOU do (it's a copy)
+
+// Who frees this?
+X509 *cert = SSL_get0_peer_certificate(ssl);  // OpenSSL 3.0+
+// Answer: NOBODY (it's a reference)
+
+// The difference: "get" vs "get0"
+// This convention is NOT obvious or consistently applied
+```
+
+**The Problem**: Memory ownership indicated by subtle naming conventions that aren't documented together and aren't consistent across the API.
+
+### Sharp Edge: EVP_CIPHER_CTX Reuse
+
+```c
+EVP_CIPHER_CTX *ctx = EVP_CIPHER_CTX_new();
+EVP_EncryptInit_ex(ctx, EVP_aes_256_gcm(), NULL, key, iv);
+EVP_EncryptUpdate(ctx, out, &outlen, in, inlen);
+EVP_EncryptFinal_ex(ctx, out + outlen, &tmplen);
+
+// DANGEROUS: Reusing ctx without reset
+EVP_EncryptInit_ex(ctx, NULL, NULL, NULL, iv2);  // New IV only
+// Some state from previous encryption may persist!
+```
+
+**The Problem**: Context reuse rules are complex and vary by cipher mode.
+
+---
+
+## Python's `pickle`
+
+### Sharp Edge: Arbitrary Code Execution by Design
+
+```python
+import pickle
+
+# DANGEROUS: Deserializes arbitrary Python objects
+data = pickle.loads(untrusted_input)
+
+# Attacker sends:
+# b"cos\nsystem\n(S'rm -rf /'\ntR."
+# Result: Executes shell command
+```
+
+**The Problem**: `pickle` is not a data format—it's a code execution format. There is no safe way to unpickle untrusted data, but:
+- The function looks like a data parser
+- The name suggests food preservation, not danger
+- Many developers don't realize the risk
+
+**Mitigation**: Use `json` for data. If you need pickle, use `hmac` to authenticate before unpickling (but even then, prefer safer formats).
+
+---
+
+## YAML Libraries
+
+### Sharp Edge: Code Execution via Tags
+
+```python
+import yaml
+
+# DANGEROUS: yaml.load() executes arbitrary code
+data = yaml.load(untrusted_input)
+
+# Attacker sends:
+# !!python/object/apply:os.system ['rm -rf /']
+```
+
+**The Problem**: YAML's tag system allows arbitrary object instantiation. The "safe" loader is:
+```python
+data = yaml.safe_load(untrusted_input)  # Safe
+data = yaml.load(untrusted_input, Loader=yaml.SafeLoader)  # Also safe
+```
+
+But the dangerous version is the obvious one (`yaml.load()`).
+
+---
+
+## PHP's `strcmp` for Password Comparison
+
+### Sharp Edge: Type Juggling Bypass
+
+```php
+// DANGEROUS: Type juggling attack
+if (strcmp($_POST['password'], $stored_password) == 0) {
+    authenticate();
+}
+
+// Attacker sends: password[]=anything
+// strcmp(array, string) returns NULL
+// NULL == 0 is TRUE in PHP!
+```
+
+**The Problem**:
+- `strcmp` returns `NULL` on type error, not `-1` or `1`
+- PHP's `==` operator coerces `NULL` to `0`
+- `NULL == 0` evaluates to `TRUE`
+- Authentication bypassed
+
+**Fix**:
+```php
+if (hash_equals($stored_hash, hash('sha256', $_POST['password']))) {
+    // Use hash_equals for timing-safe comparison
+    // AND proper password hashing (not shown)
+}
+```
+
+---
+
+## Analysis Template
+
+When examining a library for sharp edges:
+
+### Input → Expected Output
+
+| Input | Expected | Actual | Vulnerability |
+|-------|----------|--------|---------------|
+| `verify_ssl=false` | Clear warning | Silent acceptance | Config cliff |
+| `password=""` | Rejection | Login success | Empty bypass |
+| `algorithm="none"` | Error | Signature skipped | Downgrade |
+| `timeout=-1` | Error | Infinite timeout | Magic value |
+
+### Library Comparison
+
+| Feature | Dangerous Library | Safer Alternative |
+|---------|------------------|-------------------|
+| Bignum crypto | GMP | libsodium, OpenSSL BIGNUM |
+| TLS | Raw OpenSSL | Higher-level wrappers |
+| Serialization | pickle, YAML | JSON, protobuf |
+| Password compare | strcmp | hash_equals, secrets.compare_digest |