npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@ukstv/ses

v0.10.3

Published

Secure ECMAScript

Downloads

11

Readme

Secure EcmaScript (SES)

Secure 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.

Install

npm install ses

Usage

Lockdown

SES introduces the lockdown() function. Calling lockdown() 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 the realm. The set of accessible objects includes but is not limited to: globalThis, [].__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.

import 'ses';
import 'my-vetted-shim';

lockdown();

console.log(Object.isFrozen([].__proto__));
// true

Harden

SES introduces the harden function. After calling lockdown, the harden function ensures that every object in the transitive closure over property and prototype access starting with that object has been frozen by Object.freeze. 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.

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.

Compartment

SES introduces the Compartment constructor. A compartment is an evaluation and execution environment with its own globalThis and wholly independent system of modules, but otherwise shares the same batch of intrinsics like Array 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() function on globalThis.

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.

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.

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. The resolveHook determines how the compartment will infer the full module specifier for another module from a referrer module and the import specifier. The importHook accepts a full specifier and asynchronously returns a StaticModuleRecord for that module.

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.

const c2 = new Compartment({}, {
  'c1': c1.module('./main.js'),
}, {
  name: "second compartment",
  resolveHook,
  importHook,
});

importHook aliases

If a compartment imports a module specified as "./utility" but actually implemented by an alias like "./utility/index.js", the importHook may 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 importHook may return an "alias" objeect with record, compartment, and module properties.

  • record must be a StaticModuleRecord,
  • compartment is optional, to be specified if the alias transits to a different compartment, and
  • specifier 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.

const importHook = async specifier => {
  const candidates = [specifier, `${specifier}.js`, `${specifier}/index.js`];
  for (const candidate of candidates) {
    const record = await wrappedImportHook(candidate).catch(_ => undefined);
    if (record !== undefined) {
      return { record, specifier };
    }
  }
  throw new Error(`Cannot find module ${specifier}`);
};

const compartment = new Compartment({}, {}, {
  resolveHook,
  importHook,
});

moduleMapHook

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 compartment constructed to the first. For these cases, the Compartment constructor accepts a moduleMapHook option that is like the dynamic version of the static moduleMap argument. This is a function that accepts a module specifier and returns the module namespace for that module specifier, or undefined. If the moduleMapHook returns undefined, the compartment proceeds to the importHook to attempt to asynchronously obtain the module's source.

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,
});

Third-party modules

To incorporate modules not implemented as ECMAScript modules, third-parties may implement a StaticModuleRecord interface. The record must have an imports array and an execute method. The compartment will call execute with:

  1. the proxied exports namespace object,
  2. a resolvedImports object that maps import names (from imports) to their corresponding resolved specifiers (through the compartment's resolveHook), and
  3. the compartment, such that importNow can obtain any of the module's specified imports.

: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.

Bug Disclosure

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.