SES: Hardened JavaScript for Secure Execution

Common errors

• TypeError: Cannot assign to read only property 'prototype' of object '#<Object>' (or similar 'Cannot assign to read only property' errors)

  cause `lockdown()` has frozen JavaScript intrinsics and objects to prevent prototype pollution and tampering with the global environment.
  fix Do not attempt to modify built-in objects or their prototypes after `lockdown()` has been called. If you need to introduce polyfills or shims, they must be applied *before* `lockdown()`.

• ReferenceError: fetch is not defined (or 'document is not defined', 'process is not defined')

  cause Code running inside a `Compartment` does not have access to ambient authority (global browser/Node.js APIs) by default, adhering to POLA.
  fix To grant access to specific host APIs, pass them explicitly into the `Compartment`'s `globals` option. For example: `new Compartment({ globals: { fetch: harden(globalThis.fetch) } })`. Ensure any granted capabilities are `harden()`ed.

• Error: Code evaluation is forbidden for `new Function(...)` (or `eval(...)`) after the compartment is locked down.

  cause `lockdown()` replaces the global `Function` constructor and `eval` with versions that throw errors when used to evaluate source code directly, as a security measure.
  fix Use the `Compartment.prototype.evaluate(code)` method to securely run code within a specific `Compartment`'s scope. For dynamic module loading, explore `Compartment.prototype.import()` or `Compartment`'s `moduleMapHook`.

Warnings

• breaking Version 2.0.0 includes a major fix for a NaN side-channel vulnerability in JavaScript. This change prevents the leakage of NaN bit encodings via shared TypedArray views of a common ArrayBuffer, which could potentially expose sensitive information. Users should upgrade to prevent this subtle information leak.
  Fix: Upgrade `ses` to version 2.0.0 or higher. Ensure your application architecture accounts for the strictness introduced by `lockdown()` regarding numeric representations.
• gotcha Calling `lockdown()` irreversibly modifies the global JavaScript environment. It freezes all intrinsic objects and functions, preventing any further prototype pollution or global tampering. It must be called once and as early as possible in the application's lifecycle, before any untrusted code or potentially harmful shims are loaded.
  Fix: Ensure `lockdown()` is the very first significant operation in your main entry point. Avoid calling it multiple times or after third-party libraries have initialized, as they might expect a mutable global environment.
• gotcha After `lockdown()` is invoked, the `Function` constructor and similar evaluators (e.g., `eval`, `setTimeout(string)`) become 'tamed' in the global realm, meaning they will throw an error when attempting to evaluate arbitrary source code. This is a critical security feature to prevent direct arbitrary code execution. Within a `Compartment`, its own `Function` constructor evaluates code only within that compartment's global scope.
  Fix: Do not rely on global `new Function()` or `eval()` after `lockdown()`. Instead, use `compartment.evaluate(code)` for code evaluation within an explicitly controlled, isolated environment. For dynamic module loading, use `compartment.import()` or `compartment.moduleMapHook`.
• gotcha Compartments operate under the Principle of Least Authority (POLA). By default, a `Compartment` receives no ambient authority, meaning it does not automatically have access to host-provided APIs like `fetch`, `localStorage`, `console`, or `process`.
  Fix: Explicitly pass any required ambient authority (e.g., `console.log`, `fetch`) into the `Compartment`'s `globals` or via its `importHook` and `moduleMap`. Use `harden()` on any objects passed into the `globals` to prevent the compartment from tampering with them.

Install

• npm install ses npm
• yarn add ses yarn
• pnpm add ses pnpm

Imports

• lockdown
  wrong:

  const lockdown = require('ses').lockdown;

  correct:

  import { lockdown } from 'ses';

  While CommonJS `require` works, ESM `import` is the recommended pattern. `lockdown()` is typically called once globally.
• Compartment
  wrong:

  const Compartment = require('ses').Compartment;

  correct:

  import { Compartment } from 'ses';

  The `Compartment` constructor is unavailable before `lockdown()` is called to ensure a hardened environment.
• harden
  wrong:

  const harden = require('ses').harden;

  correct:

  import { harden } from 'ses';

  Used to recursively freeze objects and their reachable properties, making them tamper-proof. It's automatically applied to many intrinsics by `lockdown()`.
• Global Lockdown
  wrong:

  require('ses'); // Only imports, does not automatically call lockdown

  correct:

  import 'ses'; // Immediately hardens the global environment
  lockdown(); // Explicitly calls the global lockdown function

  Importing 'ses' as a side effect calls `lockdown()` in some environments, but it's best practice to explicitly call `lockdown()` after import.

Quickstart

Demonstrates locking down the global environment and securely executing untrusted TypeScript code within an isolated Compartment, explicitly granting limited capabilities like logging and a custom greeting function. It also shows how attempts at prototype pollution or unauthorized global access are prevented.

import { lockdown, Compartment, harden } from 'ses';

// Step 1: Lock down the global environment to prevent tampering.
// This should be done as early as possible in your application's lifecycle.
lockdown();

console.log('Global environment locked down.');

// Step 2: Create a new Compartment for secure execution of untrusted code.
// Compartments are isolated and by default have no ambient authority (e.g., no `fetch`).
const untrustedCompartment = new Compartment({
  globals: {
    // Grant specific global capabilities to the compartment.
    log: harden(console.log),
    greet: harden((name: string) => `Hello, ${name} from compartment!\n`),
  },
});

// Step 3: Evaluate untrusted code within the compartment.
// The code only has access to its explicit globals and hardened intrinsics.
const untrustedCode = `
  try {
    log(greet('World'));
    // Attempting to access unauthorized globals will fail.
    // console.error('This should not be accessible.');
    // new Function('return this')().alert('Attempted to access window!');
    log('Attempting to modify Object.prototype...');
    Object.prototype.evil = 'muahaha'; // This will fail due to lockdown
  } catch (e: any) {
    log('Caught expected error: ' + e.message);
  }
  const func = new Function('return 1 + 1;'); // This will throw after lockdown
`;

try {
  untrustedCompartment.evaluate(untrustedCode);
} catch (e: any) {
  console.error('Error evaluating untrusted code:', e.message);
}

// Verify global prototype pollution did not occur in the main realm
if (Object.prototype.hasOwnProperty('evil')) {
  console.error('Prototype pollution detected in main realm!');
} else {
  console.log('Main realm is still secure.');
}