@elizaos/skills 2.0.0-alpha.10

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

@@ -0,0 +1,333 @@
+# Configuration Security Patterns
+
+Dangerous configuration patterns that enable security failures.
+
+## Zero/Empty/Null Semantics
+
+### The Lifetime Zero Problem
+
+```yaml
+# What does 0 mean?
+session_timeout: 0    # Infinite timeout? Immediate expiry? Disabled?
+token_lifetime: 0     # Never expires? Already expired? Use default?
+max_attempts: 0       # No attempts allowed? Unlimited attempts?
+```
+
+**Real-world failures:**
+- OTP libraries where `lifetime=0` means "accept any OTP regardless of age"
+- Rate limiters where `max_attempts=0` disables rate limiting
+- Session managers where `timeout=0` means "session never expires"
+
+**Detection**: Any numeric security parameter that accepts 0.
+
+**Fix**: Explicit constants, validation, or separate enable/disable flag.
+
+```python
+# BAD
+def verify_otp(code: str, lifetime: int = 300):
+    if lifetime <= 0:
+        return True  # What??
+
+# GOOD
+def verify_otp(code: str, lifetime: int = 300):
+    if lifetime <= 0:
+        raise ValueError("lifetime must be positive")
+```
+
+### Empty String Bypass
+
+```python
+# Passwords
+if user_password == stored_hash:  # What if stored_hash is ""?
+
+# API keys
+if api_key == config.api_key:  # What if config is empty?
+    grant_access()
+
+# The empty string equals the empty string
+"" == ""  # True - authentication bypassed
+```
+
+**Detection**: String comparisons for authentication without empty checks.
+
+### Null as "Skip"
+
+```javascript
+// DANGEROUS: null means "skip verification"
+function verifySignature(data, signature, publicKey) {
+    if (!publicKey) return true;  // No key = trust everything?
+    return crypto.verify(data, signature, publicKey);
+}
+
+// DANGEROUS: null means "any value"
+function checkRole(user, requiredRole) {
+    if (!requiredRole) return true;  // No requirement = allow all?
+    return user.roles.includes(requiredRole);
+}
+```
+
+## Boolean Traps
+
+### Security-Disabling Flags
+
+```yaml
+# Every one of these has caused real vulnerabilities
+verify_ssl: false
+validate_certificate: false
+check_signature: false
+require_auth: false
+enable_csrf_protection: false
+sanitize_input: false
+```
+
+**Pattern**: Any boolean that disables a security control.
+
+**The typo problem:**
+```yaml
+verify_ssl: fasle   # Typo - what does the parser do?
+verify_ssl: "false" # String "false" - truthy in many languages!
+verify_ssl: 0       # Integer 0 - falsy, but is it valid?
+```
+
+### Double Negatives
+
+```yaml
+# Confusing
+disable_auth: false      # Auth enabled? Let me re-read...
+skip_validation: false   # Validation runs? Think carefully...
+
+# Clear
+auth_enabled: true
+validate_input: true
+```
+
+## Magic Values
+
+### Sentinel Values in Security Parameters
+
+```yaml
+# What do these mean?
+max_retries: -1      # Infinite? Error? Use default?
+cache_ttl: -1        # Never expire? Disabled?
+timeout_seconds: -1  # Wait forever? Use system default?
+
+# Real vulnerability: connection pool with max_connections: -1
+# meant "unlimited" - enabled DoS via connection exhaustion
+```
+
+### Special String Values
+
+```yaml
+# Dangerous patterns
+allowed_origins: "*"       # CORS wildcard
+allowed_hosts: "any"       # Bypass host validation
+log_level: "none"          # Disable security logging
+password_policy: "disabled" # No password requirements
+```
+
+**Detection**: String configs that accept wildcards or "disable" keywords.
+
+## Combination Hazards
+
+### Conflicting Settings
+
+```yaml
+# Both true - which wins?
+require_authentication: true
+allow_anonymous_access: true
+
+# Both specified - conflict
+session_cookie_secure: true
+force_http: true  # HTTP can't use Secure cookies
+
+# Mutually exclusive
+encryption_key: "..."
+encryption_disabled: true
+```
+
+### Precedence Confusion
+
+```yaml
+# In config file
+verify_ssl: true
+
+# But overrideable by environment?
+VERIFY_SSL=false  # Which wins?
+
+# And command line?
+--no-verify-ssl   # Now there are three sources
+```
+
+**Fix**: Document precedence clearly; warn on conflicts; fail on contradictions.
+
+## Environment Variable Hazards
+
+### Sensitive Values in Environment
+
+```bash
+# Common but problematic
+export DATABASE_PASSWORD="secret"
+export API_KEY="sk_live_xxx"
+
+# Risks:
+# - Visible in process listings (ps aux)
+# - Inherited by child processes
+# - Logged in error dumps
+# - Visible in container inspection
+```
+
+### Override Attacks
+
+```python
+# Application trusts environment
+debug = os.environ.get("DEBUG", "false") == "true"
+
+# Attacker with environment access:
+export DEBUG=true  # Enables verbose logging of secrets
+```
+
+**Detection**: Security settings controllable via environment without validation.
+
+## Path Traversal via Config
+
+### Unrestricted Path Configuration
+
+```yaml
+# User-controlled paths
+log_file: "../../../etc/passwd"
+upload_dir: "/etc/nginx/conf.d/"
+template_dir: "../../../etc/shadow"
+
+# Even "read-only" paths can leak secrets
+config_include: "/etc/shadow"
+certificate_file: "/proc/self/environ"
+```
+
+**Fix**: Validate paths; restrict to allowed directories; resolve and check.
+
+## Unvalidated Constructor Parameters
+
+Configuration/parameter classes that accept security-relevant values without validation create "time bombs" - the insecure value is accepted silently at construction, then explodes later during use.
+
+### Algorithm Selection Without Allowlist
+
+```php
+// DANGEROUS: Accepts any string including weak algorithms
+readonly class ServerConfig {
+    public function __construct(
+        public string $hashAlgo = 'sha256',  // Accepts 'md5', 'crc32', 'adler32'
+        public string $cipher = 'aes-256-gcm', // Accepts 'des', 'rc4'
+    ) {}
+}
+
+// Caller can pass insecure values:
+new ServerConfig(hashAlgo: 'md5');  // Silently accepted!
+```
+
+**Detection**: Constructor parameters named `algo`, `algorithm`, `hash*`, `cipher`, `mode`, `*_type` that accept strings without validation.
+
+**Fix**: Validate against an explicit allowlist at construction:
+
+```php
+public function __construct(public string $hashAlgo = 'sha256') {
+    if (!in_array($hashAlgo, ['sha256', 'sha384', 'sha512'], true)) {
+        throw new InvalidArgumentException("Disallowed hash algorithm: $hashAlgo");
+    }
+}
+```
+
+### Timing Parameters Without Bounds
+
+```php
+// DANGEROUS: No minimum or maximum bounds
+readonly class AuthConfig {
+    public function __construct(
+        public int $otpLifetime = 120,     // Accepts 0 (immediate expiry? infinite?)
+        public int $sessionTimeout = 3600, // Accepts -1 (what does this mean?)
+        public int $maxRetries = 5,        // Accepts 0 (no retries? unlimited?)
+    ) {}
+}
+
+// All of these are silently accepted:
+new AuthConfig(otpLifetime: 0);      // OTP always expired or never expires?
+new AuthConfig(otpLifetime: 999999); // ~11 days - replay attacks!
+new AuthConfig(maxRetries: -1);      // Unlimited retries = brute force
+```
+
+**Detection**: Numeric constructor parameters for `*lifetime`, `*timeout`, `*ttl`, `*duration`, `max_*`, `min_*`, `*_seconds`, `*_attempts` without range validation.
+
+**Fix**: Enforce both minimum AND maximum bounds:
+
+```php
+public function __construct(public int $otpLifetime = 120) {
+    if ($otpLifetime < 2) {
+        throw new InvalidArgumentException("OTP lifetime too short (min: 2 seconds)");
+    }
+    if ($otpLifetime > 300) {
+        throw new InvalidArgumentException("OTP lifetime too long (max: 300 seconds)");
+    }
+}
+```
+
+### Hostname/URL Parameters Without Validation
+
+```php
+// DANGEROUS: No format validation
+readonly class NetworkConfig {
+    public function __construct(
+        public string $hostname = 'localhost',  // Accepts anything
+        public string $callbackUrl = '',        // Accepts malformed URLs
+    ) {}
+}
+
+// Silently accepted:
+new NetworkConfig(hostname: '../../../etc/passwd');
+new NetworkConfig(hostname: 'localhost; rm -rf /');
+new NetworkConfig(callbackUrl: 'javascript:alert(1)');
+```
+
+**Detection**: String constructor parameters named `host`, `hostname`, `domain`, `*_url`, `*_uri`, `endpoint`, `callback*` without validation.
+
+**Fix**: Validate format at construction:
+
+```php
+public function __construct(public string $hostname = 'localhost') {
+    if (!filter_var($hostname, FILTER_VALIDATE_DOMAIN, FILTER_FLAG_HOSTNAME)) {
+        throw new InvalidArgumentException("Invalid hostname: $hostname");
+    }
+}
+```
+
+### The "Sensible Default" Trap
+
+Having a secure default does NOT protect you - callers can override it:
+
+```php
+// Default is secure...
+public function __construct(
+    public string $hashAlgo = 'sha256'  // Good default!
+) {}
+
+// ...but callers can still shoot themselves
+$config = new Config(hashAlgo: 'md5');  // Oops
+```
+
+**The rule**: If a parameter affects security, validate it. Defaults only help developers who don't specify a value; validation protects everyone.
+
+## Configuration Validation Checklist
+
+For configuration schemas, verify:
+
+- [ ] **Zero/empty rejected**: Numeric security params require positive values
+- [ ] **No empty passwords/keys**: Empty string authentication forbidden
+- [ ] **No security-disabling booleans**: Or require confirmation/separate config
+- [ ] **No magic values**: -1 and wildcards have defined, safe meanings
+- [ ] **Conflict detection**: Contradictory settings produce errors
+- [ ] **Precedence documented**: Clear order when multiple sources exist
+- [ ] **Path validation**: User-provided paths restricted to safe directories
+- [ ] **Type strictness**: "false" string not silently converted to boolean
+- [ ] **Deprecation warnings**: Insecure legacy options warn loudly
+- [ ] **Algorithm allowlist**: Crypto algorithm params validated against safe options
+- [ ] **Timing bounds**: Lifetime/timeout params have both min AND max limits
+- [ ] **Hostname/URL validation**: Network addresses validated at construction
+- [ ] **Constructor validation**: All security params validated, not just defaulted

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