@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