@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.- with
InvalidSourceError, for a source that is not a string or is empty; - with a
TypeError, for apreScanoption 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).
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)
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.createStrictPreset, createSecurePreset, createStandardPreset, createPermissivePreset, createPreset(level, options?)
The other presets, also available asPresets.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 theBabel 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.config of new PreScanner({ preset, config }), not in the place of the options.
normalizeToolNamespaces(spec, options?)
Validates atoolNamespaces 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 codeDISALLOWED_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.maxIterations a loop check compares its counter with the runtime’s __maxIterations, and a script that uses that name is refused.
Example:
transformConcatenation, rewriteImports, …).
Custom Rules
Creating a Custom Rule
Using Custom Rules
context.report(). An exception it throws instead ends the validation: validate() rejects with it, and there is no result.
Complete Example
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.
Related
- Overview - Feature overview
- AgentScript Preset - Preset details
- Custom Rules - Writing rules