js-audit

JavaScript Code Audit Skill

Perform comprehensive security, correctness, and quality audits on Hull JavaScript stdlib code.

Target: $ARGUMENTS (default: all stdlib/js/hull/*.js files)

Usage

/js-audit                               # Audit all JS stdlib modules
/js-audit stdlib/js/hull/template.js    # Audit a specific module
/js-audit --fix                         # Audit and apply fixes

Hull JS Context

Hull JS code runs inside a sandboxed QuickJS (ES2023) interpreter:

• Removed globals: eval() disabled at C level
• Not loaded: std, os modules
• Memory limit: 64 MB (JS_SetMemoryLimit)
• Stack limit: 1 MB (JS_SetMaxStackSize)
• Gas metering: Instruction-count interrupt handler
• Module system: Only hull:* modules available via import
• C capabilities: db, crypto, time, env, fs, http — accessed through hull module imports

Audit Categories

1. Sandbox Safety (Critical)

Hull-specific: The template engine's _template.compile() uses JS_Eval via C bridge — this is the ONLY allowed code compilation path. Verify no JS-level code compilation exists.

2. Input Validation & Injection

SQL safety check:

// BAD: template literal interpolation
db.query(`SELECT * FROM users WHERE id = ${id}`);

// BAD: string concatenation
db.query("SELECT * FROM users WHERE id = " + id);

// GOOD: parameterized
db.query("SELECT * FROM users WHERE id = ?", [id]);

Template safety check:

// BAD: raw output of user data
template.renderString("{{{ user_input }}}", data);

// GOOD: auto-escaped output
template.renderString("{{ user_input }}", data);

3. Error Handling

Patterns to check:

// BAD: unchecked
const result = db.query("SELECT * FROM users WHERE id = ?", [id]);
const name = result[0].name;  // crashes if result is empty

// GOOD: null-safe
const result = db.query("SELECT * FROM users WHERE id = ?", [id]);
if (!result || result.length === 0) return null;
const name = result[0].name;

4. Type Safety

JS-specific pitfalls:

// BAD: loose equality
if (value == null)  // matches both null and undefined

// GOOD: explicit
if (value === null || value === undefined)

// BAD: implicit coercion
const total = count + "items"  // "5items" not "5 items"

// GOOD: explicit
const total = `${count} items`

5. Resource Management

Performance patterns:

// BAD: O(n^2) string building
let s = "";
for (const item of items) {
    s += item;  // copies entire string each iteration
}

// GOOD: array join
const parts = [];
for (const item of items) {
    parts.push(item);
}
const s = parts.join("");

6. Crypto & Auth Safety

Constant-time comparison:

// BAD: early-exit comparison
if (token === expected) { ... }

// GOOD: use crypto.verifyPassword or HMAC-then-compare
// Hull's jwt.verify and csrf.verify use constant-time internally

7. API Consistency (JS vs Lua parity)

8. Template Engine Specific

9. QuickJS-Specific Issues

10. Dead Code & Style

Audit Procedure

When /js-audit is invoked:

1. Locate Files

   stdlib/js/hull/*.js                     # All JS stdlib modules
   examples/*/app.js                       # Example apps (reference patterns)
   tests/fixtures/*/app.js                 # Test fixture apps
   

2. Scan for Critical Issues

   • Search for eval(, Function(, new Function( — sandbox escapes
   • Search for template literal SQL: db.query(`...${` or db.query("..." + — SQL injection
   • Search for {{{ in template strings — raw output of user data
   • Search for === comparison of secrets, tokens, hashes
   • Search for hardcoded secret strings
   • Search for globalThis. or globalThis[ — global pollution
   • Search for __proto__, constructor.prototype — prototype pollution

3. Review Each Module

   • Check public API functions for input validation
   • Check error handling (null/undefined checks, try/catch)
   • Check resource cleanup (cache sizes, collection growth)
   • Verify API parity with Lua equivalent

4. Check Template Engine

   • Verify codegen never interpolates user data into generated source
   • Verify HTML escaping covers & < > " '
   • Verify null-safe dot paths (optional chaining)
   • Verify circular extends detection
   • Verify include depth limit

5. Generate Report Format as markdown table with findings, severity, file:line, and suggested fix.

Report Format

## JS Audit Report: Hull

**Date:** YYYY-MM-DD
**Files Scanned:** N
**Issues Found:** N (Critical: N, High: N, Medium: N, Low: N)

### Critical Issues

| # | File:Line | Issue | Current Code | Suggested Fix |
|---|-----------|-------|--------------|---------------|
| C1 | stdlib/js/hull/auth.js:42 | SQL injection | `` db.query(`...${id}`) `` | `db.query("...?", [id])` |

### High Issues
...

### Medium Issues
...

### Low Issues
...

### Recommendations
1. ...

Fix Mode (--fix)

When --fix is specified:

1. Generate the audit report first
2. For each fixable issue, apply the transformation
3. Rebuild (make)
4. Re-run tests (make test && make e2e-templates)
5. Report any test failures

Auto-fixable Issues:

• SQL string interpolation -> parameterized queries
• == -> === (strict equality)
• Unused variables -> remove or prefix with _
• s += x in loops -> array.push + .join("") pattern
• Missing null checks -> add guard clause
• Commented-out code blocks -> remove

NOT Auto-fixable (require manual review):

• Logic errors
• Crypto/auth design flaws
• API parity mismatches (may require Lua changes too)
• Template codegen injection paths
• Prototype pollution vectors
• Resource leak in complex control flow