Skip to main content
ast-guard can transform validated code for safe execution. Transformations wrap dangerous operations with safe runtime proxies that enforce limits and provide isolation.

Basic Usage

Transformation Output

Transformation Options

Main Wrapper

The main wrapper enables top-level await and provides an entry point:
The runtime calls __ag_main() to execute the script.

Safe callTool

The callTool transformation proxies all tool calls through the runtime:
The __safe_callTool proxy:
  • Counts tool calls against maxToolCalls limit
  • Routes calls through the configured toolHandler
  • Sanitizes arguments and return values

Safe Loops

Loop transformations enforce iteration limits:
while and do...while loops get the same counter and check. Two things keep a script from switching the limit off:
  • The counter has a name the script does not mention anywhere: the transformer never hands out a counter name that appears in the script.
  • The limit is a number in the loop’s own code when maxIterations is given, as @enclave-vm/core does. Without maxIterations the check compares with the runtime’s __maxIterations; that name is reserved, and a script that uses it fails the transform.

Safe Console

Console methods are proxied for rate limiting:
The __safe_console proxy:
  • Counts calls against maxConsoleCalls
  • Tracks output bytes against maxConsoleOutputBytes
  • Hands each line to the enclave’s consoleHandler, or to the host console at PERMISSIVE

Reserved Prefixes

The transformation reserves these prefixes that user code cannot use:
  • __ag_ - AgentScript internal identifiers
  • __safe_ - Safe runtime proxies
Any attempt to declare identifiers with these prefixes is blocked by the ReservedPrefixRule.

Other Transforms

The package exports the transforms @enclave-vm/core applies after validation. Each one changes an AST in place: The validator’s own transform option (validate(code, { transform: { enabled: true, ... } })) can prefix identifiers and rewrite computed keys. A computed key it rewrites is printed as one string literal, whatever characters the key holds.

rewriteImports

  • Only allowed packages can be imported: the ones in allowedPackages when it is given, otherwise the keys of packageVersions. An import of another package throws. This holds for import declarations, re-exports and dynamic import().
  • A dynamic import('react') of an allowed package is rewritten. One whose specifier is not written as a string cannot be checked and throws.
  • A version is a version number, range or tag without path or URL characters; cdnBaseUrl is an HTTPS URL without credentials, query or fragment. Anything else throws.
  • The allowlist is the configuration’s. Where the configuration comes from the same party as the code, the rewrite restricts nothing.

Integration with enclave-vm

enclave-vm automatically applies transformations when transform: true (default):

Transformation Without Validation

You can transform code independently of validation: