Skip to main content
API reference for the @enclave-vm/ast package.

Installation

JSAstValidator Class

Main AST validation class. It is built from an array of rules; a preset function returns such an array.

Constructor

Methods

validate(source, config?)

Validate JavaScript source against the rules.
The promise rejects in three cases:
  • with InvalidSourceError, for a source that is not a string or is empty;
  • with a TypeError, for a preScan option that names no preset or holds an invalid setting;
  • with whatever a rule throws. The validator does not turn the exception of a rule into an issue, so a validation with rules of your own belongs in a try/catch (see Using Custom Rules).
Every other outcome is in the result: a failed pre-scan, a parse error, the issues the rules report and a failed transform.
A validation result is bounded: at the cap of maxIssues the validation stops as soon as an error is on the list, and a validation that stopped early is never valid. An UNKNOWN_GLOBAL issue states the list of allowed globals once per validation. Example:

registerRule(rule), unregisterRule(name), getRules(), getRule(name), getStats(result, durationMs)

Manage the rules of a validator, and count the issues of a result by severity.

PreScanner Class

Checks on the source text before it is parsed.

Constructor

preset is 'agentscript', 'strict', 'secure', 'standard' (the default) or 'permissive'; config overrides single settings of it. PreScanner.forAgentScript(overrides?), forStrict, forSecure, forStandard and forPermissive do the same.

Methods

scan(source)

Example:
JSAstValidator.validate() runs a pre-scan itself, with the standard preset unless preScan.preset says otherwise. See Pre-Scanner.

Factory Functions

createAgentScriptPreset(options?)

Create the rules of the AgentScript preset.
Options:
Example:

createStrictPreset, createSecurePreset, createStandardPreset, createPermissivePreset, createPreset(level, options?)

The other presets, also available as Presets.strict, Presets.secure, Presets.standard, Presets.permissive and Presets.create. Each returns an array of rules. They are filters on source text: passing one does not make code safe to run.

createBabelPreset(options?), getBabelConfig(level?)

The AgentScript preset with the Babel global, and the Babel limits of a security level. See Babel Preset.

createPreScannerConfig(preset, overrides?)

The configuration object of a pre-scanner preset, merged with overrides and clamped to the mandatory maxima.
PreScannerConfig:
Pass the result as config of new PreScanner({ preset, config }), not in the place of the options.

normalizeToolNamespaces(spec, options?)

Validates a toolNamespaces specification ({ mail: ['list', 'send'] } or { users: { get: 'users:get' } }) and returns it as plain data. It throws a TypeError whose message starts with Invalid toolNamespaces: for a name no runtime may bind, among them the names the language calls on an object by itself: then, toString, valueOf, toLocaleString and toJSON, as a method name and as a namespace name.

ValidationRule

Built-in Rules

See Security Rules for the options.

AllowedSyntaxRule

A syntax allowlist: every node of the parsed script must have a type the rule was given, and any other construct is reported with the code DISALLOWED_SYNTAX. The AgentScript preset uses it with AGENTSCRIPT_ALLOWED_NODE_TYPES, so a construct no other rule names (this, classes, new.target, debugger, generators) is refused rather than passed.
AGENTSCRIPT_ALLOWED_NODE_TYPES is the list for AgentScript v1 as the transformer produces it (a script wrapped in async function __ag_main(), loops rewritten). A tagged template is a call that is not a CallExpression: a rule that checks how a function is called has to look at TaggedTemplateExpression as well.

Code Transformation

transformAgentScript(code, config?)

Transform code for safe execution.
Options:
Without maxIterations a loop check compares its counter with the runtime’s __maxIterations, and a script that uses that name is refused. Example:
See Code Transformation for the other transforms (transformConcatenation, rewriteImports, …).

Custom Rules

Creating a Custom Rule

Using Custom Rules

A rule reports a finding with context.report(). An exception it throws instead ends the validation: validate() rejects with it, and there is no result.

Complete Example

The pre-scan comes first because transformAgentScript() parses the whole script and has no size limit of its own. The pre-scan that validate() runs by default would only see the transformed script, after that parse: a recipe that takes scripts from outside bounds the script as written, as step 1 does. A script that passes is accepted by the filter. To run it, use @enclave-vm/core, which does these steps itself and then runs the script in a sandbox.