@endo/evasive-transform

@endo/evasive-transform

Source transforms for evading censorship in SES-enabled applications

This package provides a function which transforms source code which would otherwise be rejected outright by SES. The transform is meaning-preserving.

It covers sequences resembling HTML comments and dynamic import inside of:

• comments
• strings
• template strings (but not tagged template strings)
• regular expression literals

and additionally covers sequences resembling HTML comments inside of code itself (e.g., if (a-->b)).

Usage

Options

Both evadeCensor and evadeCensorSync accept a source string as the first argument and an options object as the second argument:

Option	Type	Description
sourceUrl	string	The URL or filename of the source file. Used for source map generation and error messages.
sourceMap	string | object	Optional. An existing source map (as JSON string or object) to be updated with the transform's mappings.
sourceType	'script' | 'module'	Optional. Specifies whether the source is a CommonJS script ('script') or an ES module ('module'). When provided, it helps the parser handle the code correctly.
elideComments	boolean	Optional. If true, removes comment contents while preserving newlines. Defaults to false.
onlyComments	boolean	Optional. If true, limits transformation to comment contents only, leaving code unchanged. Defaults to false.

Example

See example below, or see the second test in packages/compartment-mapper/test/evasive-transform.test.js for a demonstration of its usage in compartment-mapper.

// ESM example
import { evadeCensor } from '@endo/evasive-transform';
import fs from 'node:fs/promises';

/**
 * Imagine this file contains a comment like `@property {import('foo').Bar} bar`. SES will refuse to run this code.
 */
const source = await fs.readFile('./dist/index.js', 'utf8');
const sourceMap = await fs.readFile('./dist/index.js.map', 'utf8');
const sourceUrl = 'index.js'; // assuming the source map references index.js
// sourceType can be "script" (CJS) or "module" (ESM)
const sourceType = 'script';

const { code, map } = await evadeCensor(source, {
  sourceMap,
  sourceUrl,
  // always provide a sourceType, if known!
  sourceType,
  elideComments: true,
  onlyComments: true,
});

/**
 * The resulting file will now contain `@property {IMPORT('foo').Bar} bar`, which SES will allow (and TypeScript no longer understands, but that should be fine for the use-case). 
 * 
 * Note that this could be avoided entirely by stripping comments during, say, a bundling phase.
 */
await fs.writeFile('./dist/index.ses.js', code);
await fs.writeFile('./dist/index.ses.js.map', JSON.stringify(map));

License

Apache-2.0