@elizaos/skills 2.0.0-alpha.3

package/skills/security-constant-time-analysis/skills/constant-time-analysis/references/javascript.md

@@ -0,0 +1,136 @@
+# Constant-Time Analysis: JavaScript and TypeScript
+
+Analysis guidance for JavaScript and TypeScript. Uses V8 bytecode output from Node.js to detect timing-unsafe operations.
+
+## Prerequisites
+
+- **Node.js** (v14+) - for JavaScript analysis
+- **TypeScript compiler** (tsc) - for TypeScript files (optional, uses npx fallback)
+
+## Running the Analyzer
+
+```bash
+# Analyze JavaScript
+uv run {baseDir}/ct_analyzer/analyzer.py crypto.js
+
+# Analyze TypeScript (transpiles first)
+uv run {baseDir}/ct_analyzer/analyzer.py crypto.ts
+
+# Include warning-level violations
+uv run {baseDir}/ct_analyzer/analyzer.py --warnings crypto.js
+
+# Filter to specific functions
+uv run {baseDir}/ct_analyzer/analyzer.py --func 'encrypt|sign' crypto.js
+
+# JSON output for CI
+uv run {baseDir}/ct_analyzer/analyzer.py --json crypto.js
+```
+
+## Dangerous Operations
+
+### Bytecodes (Errors)
+
+| Bytecode | Issue |
+|----------|-------|
+| Div | Variable-time execution based on operand values |
+| Mod | Variable-time execution based on operand values |
+| DivSmi | Division by small integer has variable-time execution |
+| ModSmi | Modulo by small integer has variable-time execution |
+
+### Functions (Errors)
+
+| Function | Issue | Safe Alternative |
+|----------|-------|------------------|
+| `Math.sqrt()` | Variable latency based on operand values | Avoid in crypto |
+| `Math.pow()` | Variable latency based on operand values | Avoid in crypto |
+| `Math.random()` | Predictable | `crypto.getRandomValues()` |
+| `eval()` | Unpredictable timing | Avoid entirely |
+
+### Functions (Warnings)
+
+| Function | Issue | Safe Alternative |
+|----------|-------|------------------|
+| `===` (strings) | Early-terminating | `crypto.timingSafeEqual()` |
+| `indexOf()` | Early-terminating | Constant-time search |
+| `includes()` | Early-terminating | Constant-time search |
+| `startsWith()` | Early-terminating | `crypto.timingSafeEqual()` on prefix |
+| `endsWith()` | Early-terminating | `crypto.timingSafeEqual()` on suffix |
+| `JSON.stringify()` | Variable-length output | Fixed-length padding |
+| `JSON.parse()` | Variable-time based on input | Fixed-length input |
+| `btoa()` / `atob()` | Variable-length output | Fixed-length padding |
+
+## Safe Patterns
+
+### String Comparison (Node.js)
+
+```javascript
+// VULNERABLE: Early exit on mismatch
+if (userToken === storedToken) { ... }
+
+// SAFE: Constant-time comparison (Node.js)
+const crypto = require('crypto');
+if (crypto.timingSafeEqual(Buffer.from(userToken), Buffer.from(storedToken))) { ... }
+```
+
+### Random Number Generation
+
+```javascript
+// VULNERABLE: Predictable
+const token = Math.random().toString(36);
+
+// SAFE: Cryptographically secure (Node.js)
+const crypto = require('crypto');
+const token = crypto.randomBytes(16).toString('hex');
+
+// SAFE: Browser
+const array = new Uint8Array(16);
+crypto.getRandomValues(array);
+```
+
+### Division Operations
+
+```javascript
+// VULNERABLE: Division has variable timing
+const quotient = secret / divisor;
+
+// SAFE: Use multiplication by inverse (if divisor is constant)
+// Precompute: inverse = 1/divisor as fixed-point
+const quotient = Math.floor(secret * inverse);
+```
+
+## TypeScript Notes
+
+The analyzer:
+1. Looks for `tsconfig.json` in parent directories
+2. Transpiles TypeScript to JavaScript in a temp directory
+3. Analyzes the transpiled JavaScript
+4. Reports violations against the original TypeScript file
+
+If tsc is not installed, the analyzer tries `npx tsc` as a fallback.
+
+## Limitations
+
+### V8 Bytecode Analysis
+
+The analyzer uses `node --print-bytecode` to get V8 bytecode. This has limitations:
+
+1. **JIT Compilation**: V8 may JIT-compile hot functions to native code with different timing characteristics
+2. **Function Inlining**: Inlined functions may not appear in bytecode
+3. **Deoptimization**: Code can be deoptimized back to bytecode
+
+### Source-Level Detection
+
+The analyzer also performs source-level pattern matching to detect:
+- Division (`/`) and modulo (`%`) operators
+- Dangerous function calls (`Math.random()`, etc.)
+
+This catches issues that bytecode analysis might miss due to parsing limitations.
+
+## Browser Considerations
+
+The analyzer targets Node.js V8 bytecode. Browser JavaScript engines (SpiderMonkey, JavaScriptCore) have different bytecode formats and timing characteristics.
+
+For browser-targeted code:
+- The V8 analysis is still valuable as a baseline
+- Consider additional testing in target browsers
+- Use Web Crypto API for cryptographic operations

package/skills/security-constant-time-analysis/skills/constant-time-analysis/references/kotlin.md

@@ -0,0 +1,252 @@
+# Constant-Time Analysis: Kotlin
+
+Analysis guidance for Kotlin targeting Android and JVM platforms. Kotlin compiles to JVM bytecode, sharing the same runtime characteristics as Java.
+
+## Understanding Kotlin Compilation
+
+Kotlin compiles to JVM bytecode that runs on the same virtual machine as Java:
+
+```text
+Source Code (.kt/.kts)
+        |
+        v
+    kotlinc (Kotlin Compiler)
+        |
+        v
+Bytecode (.class files)
+        |
+        v
+    JIT Compiler (HotSpot/ART)
+        |
+        v
+   Native Code (at runtime)
+```
+
+**Key implications for Android:**
+
+1. **Android Runtime (ART)** - Android uses ART instead of HotSpot JVM
+2. **AOT compilation** - ART compiles bytecode to native code at install time
+3. **Same bytecode vulnerabilities** - Division/branch timing issues persist regardless of runtime
+
+## Running the Analyzer
+
+```bash
+# Analyze Kotlin source
+uv run {baseDir}/ct_analyzer/analyzer.py CryptoUtils.kt
+
+# Include conditional branch warnings
+uv run {baseDir}/ct_analyzer/analyzer.py --warnings CryptoUtils.kt
+
+# Filter to specific functions
+uv run {baseDir}/ct_analyzer/analyzer.py --func 'sign|verify' CryptoUtils.kt
+
+# CI-friendly JSON output
+uv run {baseDir}/ct_analyzer/analyzer.py --json CryptoUtils.kt
+```
+
+Note: The `--arch` and `--opt-level` flags do not apply to Kotlin as it compiles to JVM bytecode.
+
+## Dangerous Bytecode Instructions
+
+Kotlin compiles to the same JVM bytecode as Java:
+
+| Category | Instructions | Risk |
+|----------|--------------|------|
+| Integer Division | `idiv`, `ldiv`, `irem`, `lrem` | Variable-time based on operand values |
+| Floating Division | `fdiv`, `ddiv`, `frem`, `drem` | Variable latency |
+| Conditional Branches | `ifeq`, `ifne`, `iflt`, `ifge`, `ifgt`, `ifle`, `if_icmp*` | Timing leak if condition depends on secrets |
+| Table Lookups | `*aload`, `*astore`, `tableswitch`, `lookupswitch` | Cache timing if index depends on secrets |
+
+## Constant-Time Patterns
+
+### Replace Division
+
+```kotlin
+// VULNERABLE: Division instruction emitted
+val q = secretValue / divisor
+
+// SAFE: Barrett reduction (for fixed divisor)
+// Precompute: mu = (1L shl 32) / divisor
+val mu = (1L shl 32) / divisor
+val q = ((secretValue.toLong() * mu) ushr 32).toInt()
+```
+
+### Replace Branches
+
+```kotlin
+// VULNERABLE: Branch timing reveals secret
+val result = if (secret != 0) a else b
+
+// SAFE: Constant-time selection using bitwise ops
+val mask = -(if (secret != 0) 1 else 0)
+// Better: compute mask without branch
+val mask = (secret or -secret) shr 31  // -1 if secret != 0, else 0
+val result = (a and mask) or (b and mask.inv())
+```
+
+### Replace Comparisons
+
+```kotlin
+// VULNERABLE: contentEquals() may early-terminate
+if (computed.contentEquals(expected)) { ... }
+
+// SAFE: Use MessageDigest.isEqual() for constant-time comparison
+import java.security.MessageDigest
+if (MessageDigest.isEqual(computed, expected)) { ... }
+```
+
+### Secure Random
+
+```kotlin
+// VULNERABLE: kotlin.random.Random is predictable
+import kotlin.random.Random
+val value = Random.nextInt()
+
+// SAFE: Cryptographically secure
+import java.security.SecureRandom
+val secureRand = SecureRandom()
+val value = secureRand.nextInt()
+
+// Or use Kotlin's secure wrapper (requires kotlin-stdlib-jdk8)
+import kotlin.random.asKotlinRandom
+val secureKotlinRandom = SecureRandom().asKotlinRandom()
+```
+
+## Android-Specific Considerations
+
+### Keystore Operations
+
+```kotlin
+// Use Android Keystore for cryptographic key storage
+import android.security.keystore.KeyGenParameterSpec
+import android.security.keystore.KeyProperties
+
+val keyGenerator = KeyGenerator.getInstance(
+    KeyProperties.KEY_ALGORITHM_AES,
+    "AndroidKeyStore"
+)
+keyGenerator.init(
+    KeyGenParameterSpec.Builder(
+        "my_key",
+        KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT
+    )
+    .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
+    .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
+    .build()
+)
+```
+
+### Constant-Time Comparison on Android
+
+```kotlin
+// Android provides MessageDigest.isEqual()
+import java.security.MessageDigest
+
+fun constantTimeEquals(a: ByteArray, b: ByteArray): Boolean {
+    return MessageDigest.isEqual(a, b)
+}
+```
+
+### Secure Random on Android
+
+```kotlin
+// SecureRandom works the same on Android
+import java.security.SecureRandom
+
+fun generateSecureToken(length: Int): ByteArray {
+    val random = SecureRandom()
+    val token = ByteArray(length)
+    random.nextBytes(token)
+    return token
+}
+```
+
+## Kotlin-Specific Pitfalls
+
+### Extension Functions on Primitives
+
+```kotlin
+// DANGEROUS: Division in extension function
+fun Int.divideBy(divisor: Int) = this / divisor  // Emits IDIV
+
+// The inline modifier doesn't change bytecode behavior
+inline fun Int.divideByInline(divisor: Int) = this / divisor  // Still IDIV
+```
+
+### When Expressions
+
+```kotlin
+// VULNERABLE: when compiles to tableswitch/lookupswitch
+when (secretValue) {
+    0 -> handleZero()
+    1 -> handleOne()
+    else -> handleOther()
+}
+
+// Consider constant-time alternatives for secret-dependent dispatch
+```
+
+### Null Safety Checks
+
+```kotlin
+// Nullable operations may introduce branches
+val result = secretNullable?.process()  // Introduces null check branch
+
+// Be aware of null-check timing when handling secrets
+```
+
+## Setup Requirements
+
+### Kotlin Compiler
+
+**macOS:**
+```bash
+brew install kotlin
+```
+
+**Ubuntu/Debian:**
+```bash
+sudo snap install kotlin --classic
+```
+
+**Windows:**
+```bash
+scoop install kotlin
+# or
+choco install kotlinc
+```
+
+### Android Development
+
+For Android projects, the Kotlin compiler is typically bundled with Android Studio. Ensure your project's Kotlin version is up to date in `build.gradle.kts`:
+
+```kotlin
+plugins {
+    kotlin("jvm") version "1.9.0"
+}
+```
+
+### Verification
+
+```bash
+kotlinc -version  # Should show: kotlinc-jvm X.X.X
+javap -version    # Required for bytecode disassembly
+```
+
+## Common Mistakes
+
+1. **Using kotlin.random.Random** - The default Random is not cryptographically secure; use `java.security.SecureRandom`
+
+2. **Relying on == for byte arrays** - `==` compares references in Kotlin; use `contentEquals()` for value comparison, but neither is constant-time
+
+3. **Infix functions for crypto** - Custom operators don't change timing characteristics of underlying operations
+
+4. **Coroutines timing** - Suspending functions add scheduling overhead that may mask or introduce timing variations
+
+5. **Sealed classes for dispatch** - Pattern matching on sealed classes compiles to switches that may leak timing
+
+## Further Reading
+
+- [Kotlin/JVM Interoperability](https://kotlinlang.org/docs/java-interop.html)
+- [Android Keystore System](https://developer.android.com/training/articles/keystore)
+- [Bouncy Castle for Kotlin](https://www.bouncycastle.org/java.html) - Constant-time crypto primitives

package/skills/security-constant-time-analysis/skills/constant-time-analysis/references/php.md

@@ -0,0 +1,172 @@
+# Constant-Time Analysis: PHP
+
+Analysis guidance for PHP scripts. Uses the VLD extension or OPcache debug output to analyze Zend opcodes.
+
+## Prerequisites
+
+### Installing VLD Extension
+
+The VLD (Vulcan Logic Dumper) extension is required for detailed opcode analysis. OPcache fallback is available but provides less detail.
+
+**Option 1: PECL Install (Recommended)**
+
+```bash
+# Query latest version from PECL
+VLD_VERSION=$(curl -s https://pecl.php.net/package/vld | grep -oP 'vld-\K[0-9.]+(?=\.tgz)' | head -1)
+echo "Latest VLD version: $VLD_VERSION"
+
+# Install via PECL channel URL (avoids version detection issues)
+pecl install channel://pecl.php.net/vld-${VLD_VERSION}
+
+# Or if above fails, install with explicit channel:
+pecl install https://pecl.php.net/get/vld-${VLD_VERSION}.tgz
+```
+
+**Option 2: Build from Source**
+
+```bash
+# Clone and build from GitHub
+git clone https://github.com/derickr/vld.git
+cd vld
+phpize
+./configure
+make
+sudo make install
+
+# Add to php.ini
+echo "extension=vld.so" | sudo tee -a $(php --ini | grep "Loaded Configuration" | cut -d: -f2 | tr -d ' ')
+```
+
+**Verify Installation**
+
+```bash
+php -m | grep -i vld
+# Should output: vld
+```
+
+### macOS with Homebrew PHP
+
+```bash
+# Homebrew PHP may need manual extension directory setup
+PHP_EXT_DIR=$(php -i | grep extension_dir | awk '{print $3}')
+echo "PHP extension directory: $PHP_EXT_DIR"
+
+# After building VLD, copy the extension
+sudo cp modules/vld.so "$PHP_EXT_DIR/"
+```
+
+## Running the Analyzer
+
+```bash
+# Analyze PHP file
+uv run {baseDir}/ct_analyzer/analyzer.py crypto.php
+
+# Include warning-level violations
+uv run {baseDir}/ct_analyzer/analyzer.py --warnings crypto.php
+
+# Filter to specific functions
+uv run {baseDir}/ct_analyzer/analyzer.py --func 'encrypt|decrypt' crypto.php
+
+# JSON output for CI
+uv run {baseDir}/ct_analyzer/analyzer.py --json crypto.php
+```
+
+## Dangerous Operations
+
+### Opcodes (Errors)
+
+| Opcode | Issue |
+|--------|-------|
+| DIV | Variable-time execution based on operand values |
+| MOD | Variable-time execution based on operand values |
+| POW | Variable-time execution |
+
+### Functions (Errors)
+
+| Function | Issue | Safe Alternative |
+|----------|-------|------------------|
+| `chr()` | Table lookup indexed by secret data | `pack('C', $int)` |
+| `ord()` | Table lookup indexed by secret data | `unpack('C', $char)[1]` |
+| `bin2hex()` | Table lookups indexed on secret data | Custom constant-time implementation |
+| `hex2bin()` | Table lookups indexed on secret data | Custom constant-time implementation |
+| `base64_encode()` | Table lookups indexed on secret data | Custom constant-time implementation |
+| `base64_decode()` | Table lookups indexed on secret data | Custom constant-time implementation |
+| `rand()` | Predictable | `random_int()` |
+| `mt_rand()` | Predictable | `random_int()` |
+| `array_rand()` | Uses mt_rand internally | `random_int()` |
+| `uniqid()` | Predictable | `random_bytes()` |
+| `shuffle()` | Uses mt_rand internally | Fisher-Yates with `random_int()` |
+
+### Functions (Warnings)
+
+| Function | Issue | Safe Alternative |
+|----------|-------|------------------|
+| `strcmp()` | Variable-time | `hash_equals()` |
+| `strcasecmp()` | Variable-time | `hash_equals()` |
+| `strncmp()` | Variable-time | `hash_equals()` |
+| `substr_compare()` | Variable-time | `hash_equals()` |
+| `serialize()` | Variable-length output | Fixed-length output |
+| `json_encode()` | Variable-length output | Fixed-length output |
+
+## Safe Patterns
+
+### String Comparison
+
+```php
+// VULNERABLE: Early exit on mismatch
+if ($user_token === $stored_token) { ... }
+
+// SAFE: Constant-time comparison
+if (hash_equals($stored_token, $user_token)) { ... }
+```
+
+### Random Number Generation
+
+```php
+// VULNERABLE: Predictable
+$token = bin2hex(random_bytes(16));  // OK - random_bytes is secure
+$index = mt_rand(0, count($array) - 1);  // VULNERABLE
+
+// SAFE: Cryptographically secure
+$token = bin2hex(random_bytes(16));
+$index = random_int(0, count($array) - 1);
+```
+
+### Character Operations
+
+```php
+// VULNERABLE: Table lookup timing
+$byte = ord($secret_char);
+$char = chr($secret_byte);
+
+// SAFE: No table lookup
+$byte = unpack('C', $secret_char)[1];
+$char = pack('C', $secret_byte);
+```
+
+## Troubleshooting
+
+### VLD Not Loading
+
+```bash
+# Check if extension is enabled
+php -i | grep vld
+
+# Check for loading errors
+php -d display_errors=1 -d vld.active=1 -r "echo 'test';" 2>&1
+
+# Common issue: wrong extension directory
+php -i | grep extension_dir
+ls $(php -r "echo ini_get('extension_dir');") | grep vld
+```
+
+### OPcache Fallback
+
+If VLD is unavailable, the analyzer falls back to OPcache debug output:
+
+```bash
+# Manually test OPcache output
+php -d opcache.enable_cli=1 -d opcache.opt_debug_level=0x10000 crypto.php 2>&1
+```
+
+OPcache provides less detailed output than VLD but still detects division/modulo opcodes.