Secure ECMAScript
npm install @ukstv/sesSecure EcmaScript (SES) is a frozen environment for running EcmaScript
(Javascript) 'strict' mode programs with no ambient authority in their global
scope, and with the addition of a safe two-argument evaluator
(SES.confine(code, endowments)). By freezing everything accessible from the
global scope, it removes programs abilities to interfere with each other, and
thus enables isolated evaluation of arbitrary code.
It runs atop an ES6-compliant platform, enabling safe interaction of
mutually-suspicious code, using object-capability -style programming.
See https://github.com/Agoric/Jessie to see how SES fits into the various
flavors of confined EcmaScript execution. And visit
https://rawgit.com/Agoric/ses-shim/master/demo/ for a demo.
Derived from the Caja project, https://github.com/google/caja/wiki/SES.
Still under development: do not use for production systems yet, there are
known security holes that need to be closed.
``sh`
npm install ses
SES introduces the lockdown() function.lockdown()
Calling alters the surrounding execution enviornment, or
realm, such that no two programs running in the same realm can observe or
interfere with each other until they have been introduced.
To this end, lockdown() freezes all objects accessible to any program in theglobalThis
realm.
The set of accessible objects includes but is not limited to: ,[].__proto__, {}.__proto__, (() => {}).__proto__ (async () =>
{}).__proto__, and the properties of any accessible object.
The lockdown() function also tames some of those accessible objects
that have powers that would otherwise allow programs to observe or interfere
with one another like clocks, random number generators, and regular
expressions.
`js
import 'ses';
import 'my-vetted-shim';
lockdown();
console.log(Object.isFrozen([].__proto__));
// true
`
SES introduces the harden function.lockdown
After calling , the harden function ensures that every object inObject.freeze
the transitive closure over property and prototype access starting with that
object has been frozen by .
This means that the object can be passed among programs and none of those
programs will be able to tamper with the surface of that object graph.
They can only read the surface data and call the surface functions.
`js
import 'ses';
lockdown();
let counter = 0;
const capability = harden({
inc() {
counter++;
},
});
console.log(Object.isFrozen(capability));
// true
console.log(Object.isFrozen(capability.inc));
// true
`
Note that although the surface of the capability is frozen, the capability
still closes over the mutable counter.
Hardening an object graph makes the surface immutable, but does not make
methods pure.
SES introduces the Compartment constructor.globalThis
A compartment is an evaluation and execution environment with its own and wholly independent system of modules, but otherwise sharesArray
the same batch of intrinsics like with the surrounding compartment.
The concept of a compartment implies the existence of a "start compartment",
the initial execution environment of a realm.
In the following example, we create a compartment endowed with a print()globalThis
function on .
`js
import 'ses';
const c = new Compartment({
print: harden(console.log),
});
c.evaluate(
print('Hello! Hello?'););`
The new compartment has a different global object than the start compartment.
The global object is initially mutable.
Locking down the realm hardened the objects in global scope.
After lockdown, no compartment can tamper with these intrinsics and
undeniable objects.
Many of these are identical in the new compartment.
`js`
const c = new Compartment();
c.globalThis === globalThis; // false
c.globalThis.JSON === JSON; // true
Other pairs of compartments also share many identical intrinsics and undeniable
objects of the realm.
Each has a unique, initially mutable, global object.
`js`
const c1 = new Compartment();
const c2 = new Compartment();
c1.globalThis === c2.globalThis; // false
c1.globalThis.JSON === c2.globalThis.JSON; // true
Any code executed within a compartment shares a set of module instances.
For modules to work within a compartment, the creator must provide
a resolveHook and an importHook.resolveHook
The determines how the compartment will infer the full moduleimportHook
specifier for another module from a referrer module and the import specifier.
The accepts a full specifier and asynchronously returns aStaticModuleRecord for that module.
`js
import 'ses';
const c1 = new Compartment({}, {}, {
name: "first compartment",
resolveHook: (moduleSpecifier, moduleReferrer) => {
return resolve(moduleSpecifier, moduleReferrer);
},
importHook: async moduleSpecifier => {
const moduleLocation = locate(moduleSpecifier);
const moduleText = await retrieve(moduleLocation);
return new StaticModuleRecord(moduleText, moduleLocation);
},
});
`
A compartment can also link a module in another compartment.
Each compartment has a module function that accepts a module specifier
and returns the module exports namespace for that module.
The module exports namespace is not useful for inspecting the exports of the
module until that module has been imported, but it can be passed into the
module map of another Compartment, creating a link.
`js`
const c2 = new Compartment({}, {
'c1': c1.module('./main.js'),
}, {
name: "second compartment",
resolveHook,
importHook,
});
If a compartment imports a module specified as "./utility" but actually"./utility/index.js"
implemented by an alias like , the importHook mayimportHook
follow redirects, symbolic links, or search for candidates using its own logic
and return a module that has a different "response specifier" than the original
"request specifier".
The may return an "alias" objeect with record, compartment,module
and properties.
- record must be a StaticModuleRecord,compartment
- is optional, to be specified if the alias transits to aspecifier
different compartment, and
- is the full module specifier of the module in its compartment.
This defaults to the request specifier, which is only useful if the
compartment is different.
In the following example, the importHook searches for a file and returns an
alias.
`js${specifier}.js
const importHook = async specifier => {
const candidates = [specifier, , ${specifier}/index.js];Cannot find module ${specifier}
for (const candidate of candidates) {
const record = await wrappedImportHook(candidate).catch(_ => undefined);
if (record !== undefined) {
return { record, specifier };
}
}
throw new Error();
};
const compartment = new Compartment({}, {}, {
resolveHook,
importHook,
});
`
The module map above allows modules to be introduced to a compartment up-front.
Some modules cannot be known that early.
For example, in Node.js, a package might have a dependency that brings in an
entire subtree of modules.
Also, a pair of compartments with cyclic dependencies between modules they each
contain cannot use compartment.module to link the second compartmentCompartment
constructed to the first.
For these cases, the constructor accepts a moduleMapHook optionmoduleMap
that is like the dynamic version of the static argument.undefined
This is a function that accepts a module specifier and returns the module
namespace for that module specifier, or .moduleMapHook
If the returns undefined, the compartment proceeds to theimportHook to attempt to asynchronously obtain the module's source.
`js
const moduleMapHook = moduleSpecifier => {
if (moduleSpecifier === 'even') {
return even.module('./index.js');
} else if (moduleSpecifier === 'odd') {
return odd.module('./index.js');
}
};
const even = new Compartment({}, {}, {
resolveHook: nodeResolveHook,
importHook: makeImportHook('https://example.com/even'),
moduleMapHook,
});
const odd = new Compartment({}, {}, {
resolveHook: nodeResolveHook,
importHook: makeImportHook('https://example.com/odd'),
moduleMapHook,
});
`
To incorporate modules not implemented as ECMAScript modules, third-parties may
implement a StaticModuleRecord interface.imports
The record must have an array and an execute method.execute
The compartment will call with:
1. the proxied exports namespace object,resolvedImports
2. a object that maps import names (from imports) to theirresolveHook
corresponding resolved specifiers (through the compartment's ),compartment
and
3. the , such that importNow can obtain any of the module'simports
specified .
:warning: A future breaking version may allow the importNow and the execute`
method of third-party static module records to return promises, to support
top-level await.
Please help us practice coordinated security bug disclosure, by using the
instructions in
SECURITY.md
to report security-sensitive bugs privately.
For non-security bugs, please use the regular Issues
page.