# EnclaveVM - Secure JavaScript Sandbox
# https://enclave.agentfront.dev
#
# This file provides context for LLMs and AI assistants about this project.
# For the llms-full.txt with attack vectors, see: /llms-full.txt

> EnclaveVM is a secure JavaScript sandbox that protects AI agents from code injection,
> prototype pollution, and sandbox escapes. It enables safe execution of AI-generated code.

## Quick Facts

- **Name**: EnclaveVM (enclave-vm)
- **Type**: JavaScript Sandbox / Security Runtime
- **Purpose**: Safe execution of AI-generated code
- **License**: MIT
- **GitHub**: https://github.com/agentfront/enclave
- **Playground**: https://enclave.agentfront.dev

## What is EnclaveVM?

EnclaveVM is a JavaScript sandbox designed specifically for AI agent code execution. When AI assistants generate code to help users, that code needs to run somewhere safe. EnclaveVM provides:

1. **Static Analysis**: Code is analyzed before execution to detect dangerous patterns
2. **Runtime Sandboxing**: Execution happens in an isolated environment
3. **Prototype Freezing**: JavaScript prototypes are frozen to prevent pollution
4. **Resource Limits**: CPU, memory, and time limits prevent resource exhaustion

## Key Features

- Blocks `eval()`, `Function()`, and dynamic code execution
- Prevents prototype pollution attacks
- Blocks access to `process`, `require`, `globalThis`
- Prevents infinite loops and resource exhaustion
- Supports async/await for tool calls
- TypeScript-first with full type definitions

## AgentScript Language

EnclaveVM executes "AgentScript" - a restricted JavaScript subset:

### Allowed
- `callTool()` for backend API calls
- `Math`, `JSON`, `Array`, `Object`, `String`, `Number`, `Date`
- `for...of` and bounded `for` loops
- Arrow functions, destructuring, spread operator
- Template literals, ternary operators

### Blocked
- `eval()`, `Function()`, `AsyncFunction`
- `process`, `require`, `module`, `globalThis`
- `Proxy`, `Reflect`, `Symbol`
- `while`, `do...while` (unbounded loops)
- Regular expressions (ReDoS prevention)

## Use Cases

1. **MCP Servers**: Safe execution of AI-orchestrated tool calls
2. **Chatbots**: Run user-provided code snippets safely
3. **Automation**: Execute dynamically generated scripts
4. **Data Processing**: Safe transformation of user data

## Integration Example

```javascript
import { Enclave } from 'enclave-vm';

const enclave = new Enclave({
  tools: {
    'users.list': async (args) => fetchUsers(args),
    'math.add': async ({ a, b }) => a + b,
  },
});

// Safe execution of AI-generated code
const result = await enclave.execute(`
  const users = await callTool('users.list', { limit: 10 });
  return users.map(u => u.name);
`);
```

## Related Projects

- **FrontMCP**: MCP server framework - https://github.com/agentfront/frontmcp
- **Enclave**: The sandbox library - https://github.com/agentfront/enclave

## Contact

- GitHub Issues: https://github.com/agentfront/enclave/issues
- Security: https://github.com/agentfront/enclave/security/advisories/new

## For Security Researchers

If you're testing the sandbox security, see /llms-full.txt for:
- Complete attack vector catalog
- Obfuscation techniques
- Example exploit attempts
- Valid code patterns

The playground at https://enclave.agentfront.dev lets you test attacks in real-time.