Untwist is a JavaScript deobfuscator, unminifier and unbundler written in Rust on the oxc toolchain. It reads obfuscated, minified or bundled JavaScript and gives back readable source: string arrays decoded, control flow unflattened, minifier idioms undone, transpiler helpers turned back into native syntax, bundles split into modules and, on request, identifiers renamed.
It is a reimplementation of webcrack with two goals: speed, and deobfuscating hostile input without running it. Untwist never executes the program it is given. String decoders run inside a sandboxed, step-budgeted interpreter, and a decode is applied only where Untwist can show from the program text that it gives the same result the original would.
Try it in the browser at untwist.dev. The playground runs the same engine as WebAssembly, and your code never leaves the page.
- Deobfuscate. Finds javascript-obfuscator / obfuscator.io string arrays with their rotators,
decoders (base64, RC4) and wrapper functions, and replaces each decoder call with the string it
returns. It also removes the leftover machinery, inlines control-flow proxy objects, unflattens
switchdispatch loops, strips self-defending and debug-protection code, and folds constant expressions. - Unminify. Undoes minifier idioms:
!0becomestrue, comma sequences become statements, ternaries becomeif/else, Yoda conditions are flipped,void 0becomesundefined, and so on. - Untranspile. Turns TypeScript, Babel, SWC and esbuild helpers for spread, destructuring,
classes, generators and
asyncback into native syntax. - Unpack. Detects webpack 4/5 (including JSONP chunks), browserify, esbuild and Bun, rolldown
(also Vite 8), SystemJS, AMD, UMD, Parcel, Metro, Turbopack and Closure bundles, extracts their modules and rewrites
require/importspecifiers to relative paths. Rollup and Vite scope-hoisted bundles can be split on request. Several input files can be unpacked together. The unpacked tree is untrusted code: its file names and contents come from the bundle. Do not open it with an editor or tool that runs project configuration on its own. - Rename. Optional:
mangle(short names, compatible with webcrack's-m),simple(short names per function),unique(readable, program-wide names such asfn1,arr2,handler3) orsmart(names from evidence:i/jfor loop counters,item/indexandaccfor array callbacks,errincatch,fsforrequire("fs"),canvasfordocument.createElement("canvas"),ctx,data, destructured keys and the property a function is exported or stored under; also the property a value is read from or written to, constructors (socketfornew WebSocket,vector3,floats), element ids and storage keys (chatListforgetElementById("chatList")), event handlers and their events (onKeydown(keyEvent)), timer and frame callbacks,fetchresponses and bodies, setter values, export aliases,is*names for functions that return booleans, PascalCase for functions only used withnew, and a parameter's name when every call passes the same named value; a name is reused in sibling scopes and numbered only where it would clash, and human-written names are left alone; long hex tokens such asb475796ed633d5fd0485count as machine-made here and are renamed when evidence names them). - CommonJS wrappers. In every mode, the lazy
requireX()wrappers that@rollup/plugin-commonjswrites (if (hasRequiredX) return x; hasRequiredX = 1; ...), terser's inlined forms of them, rolldown's__commonJSMinfactories and the plugin's interop helpers (commonjsGlobal,getDefaultExportFromCjs,getAugmentedNamespace,commonjsRequire) get their names back when minification or obfuscation took them:requireModule3,hasRequiredModule3,module3, or the module's own name when one survives. Only names change; every wrapper still runs on its first call. Without--renameevery function keeps its name, the wrapper functions and interop helpers included; only the flag, holder and parameter bindings are renamed (rename.md, "CommonJS wrapper names").--disable name-commonjs-wrappersturns it off. - Libraries. Recognises core-js 3 (
internals/*andmodules/*, every minor 3.0 to 3.51), regenerator-runtime, tslib, Babel helpers (@babel/runtimeand inlined) and@swc/helpersby the exact shape of their functions, minified, mangled or obfuscated, and puts// core-js 3.38–3.51: internals/global-this.jsabove each matched module. With any--renamemode the matched bindings get the library's own names (requireGetBuiltIn,getBuiltIn,isCallable, ...); the report lists each library with its version range.--disable library-names,library-renameturns this off. - JSX. Rebuilds JSX from
React.createElementand the automaticjsx/jsxsruntime.
cargo install untwist-cliThis installs the untwist binary. It needs Rust 1.98 or newer.
cargo add untwistuse untwist::{Options, Pipeline};
let output = Pipeline::new(Options::default()).run("var a = !0;");
println!("{}", output.code());
output.write_to("out-dir")?;npm install untwistimport init, { run } from 'untwist';
await init();
const result = run(source, '--unsafe', false);
console.log(result.stdout);The package is the single-threaded WebAssembly build the playground uses; see its README for the full API and the flag format.
untwist input.js # print the result to stdout
untwist input.js -o out-dir # write deobfuscated.js (and modules, if a bundle is found)
untwist a.js b.js -o out-dir # unpack several files together
cat input.js | untwist # read from stdin
Common flags:
| Flag | What it does |
|---|---|
-o, --output DIR |
Write deobfuscated.js, and, when a bundle is found, bundle.json and one file per module. A .cjs or .mjs input keeps its extension (deobfuscated.cjs, deobfuscated.mjs), so node reads the file under the input's goal. With several inputs each is written as deobfuscated.<name>.js; when only some of them form the bundle (a chunk unpacked without its loader, or an entry whose chunks are not bundles), every input is written under its own relative name instead, so the tree runs as the inputs did, and no module takes one of those names. |
-f, --force |
Overwrite the files in DIR that this run writes and remove the ones a previous run left there. Input files are never overwritten. |
--unsafe |
Use the unsafe lane (see below). |
--modern BASELINE |
Opt-in: remove core-js polyfills of features that are native in BASELINE (see Modern mode). |
--types[=jsdoc|ts] |
Experimental, opt-in: annotate only types that hold for every value on every run, as JSDoc (the default) or TypeScript (see Proven types). |
--rename MODE |
none (default), mangle, simple, smart or unique. -m is short for --rename mangle. |
--no-deobfuscate, --no-unminify, --no-unpack, --no-jsx |
Skip a stage. |
--split-hoisted |
Also split Rollup/Vite scope-hoisted bundles, when the split provably keeps behaviour. |
--split-assume-modules |
With --split-hoisted: assume the split tree is ES modules for reading and for running in node, so document.currentScript, classic-script load timing and sloppy-mode top-level semantics are not preserved. Lifts the currentScript refusal, splits a bundle that sits inside an outer wrapper function, and makes every Rollup commonjs wrapper its own module while everything else stays in the entry. See known divergences. |
--single-file |
Write every unpacked module into one file, with a banner per module. |
--source-map [file|inline] |
Emit a source map from the output back to the input. file (default, needs -o) writes <file>.map next to every written file with a sourceMappingURL comment; inline embeds the map as a data URL. Unpacked modules get one map each. The code itself is the same with or without the flag. |
--input-source-map PATH|inline |
With --source-map: the input already has a source map (a file, or its inline data URL); map through it to the original sources. A source that is absolute, has a scheme or climbs out with .. is written as input-map:///<name>; the input map's sourceRoot is joined into each source first and not copied. |
--wasm-check off|on|auto |
Look for wasm modules embedded in the output. off (default) only prints a note when the output may hold one; auto finds a byte array or base64 text that holds a whole module with imports or exports, writes it to wasm/ and names its glue (feature-detect probes are left alone); on reparses every output to look, which can be slow on large files. |
--wasm-dir DIR, --wasm NAME=PATH |
Supply wasm modules the input loads from elsewhere, so their import and export names can name the glue. This works with every --wasm-check mode. |
--fetch-wasm, --wasm-base URL |
Download the wasm modules nobody supplied. Nothing is fetched without this flag. The URLs come from the input, so each one is printed before it is requested, and one run fetches at most 16 modules, 64 MiB and for 120 seconds. Redirects are followed three times at most. A host that resolves to a loopback, link-local or private address is refused, and no proxy from the environment is used. |
--fetch-wasm-local |
With --fetch-wasm, also fetch from loopback, link-local and private addresses, for input that loads its wasm from your own machine or network. |
--disable PASS |
Turn off individual passes; --list-passes prints them all. |
--report text|json |
Print what every stage and pass did. -v is short for --report text. |
-j, --jobs N |
Process up to N inputs in parallel. The output does not depend on N. |
--max-memory SIZE |
Memory the inputs being processed may use (the texts the run holds are not counted), such as 512MiB, 8G or unlimited (default 4GiB). At three quarters of it an input stops its passes and keeps the output so far, with the note budget-memory; at the full size that input is stopped and passed through unchanged, whatever its passes are doing. --report shows the budget and the peak. |
--timeout SECS |
Wall-clock seconds processing the inputs may take (default: no limit); writing the output and --fetch-wasm are not limited by it. At the limit every input stops its passes and keeps the output so far, with the note budget-time; an input still running a while later is passed through unchanged. |
--fuel N |
Interpreter steps a string-array decode may spend before giving up (default 50,000,000 plus 500,000 per distinct decoder call, at most 1,000,000,000; 1,000,000,000 with --unsafe). All decodes of one input share a pool of 32 times that per-decode figure or 2,000 steps per input byte, whichever is larger; once it is spent the remaining decodes are left encoded with a note. |
When an input stops its passes at a budget and keeps the output so far, that output still runs like the input: every rewrite in it was proven on its own.
untwist --help lists every flag.
untwist never runs or rewrites a wasm module; it reads only its import and export names (and its
name section, when it has one) to name the JS glue around it. Each name is taken only after a
check that every import key and export read in the glue exists in the module; a module that does
not match gives a warning and names nothing. Embedded modules are found with --wasm-check, and
modules loaded from elsewhere are supplied with --wasm-dir, --wasm or --fetch-wasm. An
embedded module is written to wasm/ and its literal stays in the code; only a data: URI passed
straight to fetch(...) is replaced by the path of the written file. In a classic script the
glue's top-level var and function names keep their names, because other scripts can reach
them, and so do a sloppy-mode block function and the var of the same name that it writes (or
code outside the block that reads the function's name). In a
webpack bundle the names reach the module files that import from or export to the wasm module,
and the same names are applied to the combined deobfuscated.js. That includes wasm-bindgen
glue (bundler target) in webpack 4 and 5 bundles that reaches the module through
import * as wasm, directly or handed over with __wbg_set_wasm: a wrapper that calls one
export, which no other function calls, takes that export's name. Glue and module given as
separate input files are not linked. For Emscripten glue whose
module has no name section, exports are named from Module._name wrappers and the export kind
(wasmMemory, wasmTable). Minified import names like a.a say nothing about the function
behind them, so an import is named only when its function has the shape of an Emscripten library
function (HEAPU8.copyWithin(dest, src, src + num) is _emscripten_memcpy_big) and the module's
import has that function's signature. Such a module must also have every import the glue
provides and no import the glue leaves out; otherwise nothing is named.
Exit codes: 0 success; 1 an error, a parse error (output is still produced) or a panic in a
pass; 2 a file this run would write already exists in the output directory (use -f); 3 an
input was too deep to process safely and was passed through unchanged.
On Unix the pipeline runs in a worker process, so an input that crashes it (a stack overflow or a failed allocation) is passed through and the rest of the run is kept. Windows has no worker: the memory and time limits still stop an input and pass it through, but a crash ends the whole run without output.
By default Untwist runs in the safe lane. A rewrite is made only when it can be proven from the program text. A string-array call is decoded only if nothing in the program can change what the decoder returns at that point: no patched built-in it relies on, no alias that reaches the array or decoder before the rotator runs, no code that is built at run time from strings. When the proof fails, the call stays in place and the report says why. The output behaves like the input.
The safe lane rests on a few stated premises about code it cannot see. One input file is a closed
program. Several classic scripts given in one run share one global scope, as scripts on one page
do: a top-level var, function, let, const or class of one is treated as read and written by
the others when another input names it (a free reference or a top-level declaration of its own) or
reaches globals through a computed key or code text, and is then not inlined away, removed or
renamed, in both lanes; a string array, decoder, decoder alias or protection named that way is kept
and nothing is decoded through it. A built-in name (eval, String, atob, ...) that another input declares at its top level, assigns as a bare name, sets as a property of the global object (this.X =, globalThis.X =, window["X"] =, a definer such as Object.defineProperty(globalThis, ...)), or declares or assigns in a code text it runs (eval, (0, eval), Function, a timer string) is not the built-in for any input, so no fold relies on it. A global-object write with a computed key, or a code text that is not a literal, counts for every name. In the default lane an input whose own built-in scan is not clean (it uses a built-in, the global object or a code runner outside the listed harmless shapes, or patches a built-in member) counts for every name too. The default lane also assumes no input hands code text to a DOM API that evaluates it (document.write, a javascript: URL, a script element's text, an event-handler attribute string). Renaming never renames a classic script's top-level bindings in the safe lane. Under --unsafe,
when two or more classic scripts are given or another input may observe the global object's
names, they keep their names too (--rename unique, whose counter is shared by every input,
still renames them when only other scripts are the reason), and no input's new top-level name is a
name another input binds at the top level, reads free or uses as a key. Inputs that share no names
come out as they would alone. A module (a file with import, export,
import.meta or top-level await) is closed apart from its exports. Code from outside the file
(require results, host functions, scripts not given to Untwist) writes no built-in. It also does not depend on
the names the obfuscator picked for the string array and its decoders, because that code was
written before those names existed. So when such code is handed a value that may hold the global
object, the machinery can still be removed. Outside code that prints that value still counts as
observing it (require("util").inspect(globalThis) keeps the machinery). A removal that relies
on this premise says so in the report (the machinery was dropped under the outside-code premise). Nor does any code give Object.prototype an accessor for a key the obfuscator
generated, so storing an object under such a key runs no code. Nor does any code give
Object.prototype a property, data or accessor, named like a module id, a chunk id or a require
request of a bundle whose runtime looks modules or chunks up in a plain object (webpack 4 and 5
and their chunks, browserify, Parcel, Turbopack): such a runtime would find that property in its
{} cache, module map or installed-chunk table instead of the module or chunk, while the written
files are loaded by node; unpacking does not check for such a write. Nor does any code replace Function.prototype.call, apply or bind:
those runtimes start their modules through .call (webpack 5 only where a module uses this as its
exports), which node's loader does not use for a written file. Nor does any code reach node's
module objects or loader through process taken as a value (var p = process; p.mainModule,
globalThis.process.mainModule): a module that names process.mainModule, process.getBuiltinModule, a
computed member of process, or requests the module or process built-in is not split, but an
alias is not followed, since most bundles pass process around. And
no value the program tests is document.all, so x != null ? x : y becomes x ?? y: the two
differ only for that object, which compares loosely equal to null without being nullish. Nor does any code read a function's caller through .caller, arguments.callee.caller or a stack frame (Error.prepareStackTrace call sites with getFunction() or getFunctionName()) to observe which function called it (the non-standard Function.prototype.caller; strict code cannot): inlining a control-flow object's call proxy removes the proxy's frame, so such a read would see the function that held the call instead of the proxy. The default lane also assumes obfuscator.io's self-defending check would pass on the input: removing the trap may make an input that would trap (for example one reformatted after obfuscation) run normally. Untwist also assumes no debugger or inspector session changes the program's values while it
runs; every lane and every proof rests on this.
docs/known-divergences/deobfuscate.md lists every
premise.
The safe lane never changes the name of a function or class unless you ask for renaming. Built-ins
and the host read name with no key in the program (Error.prototype.toString, WebCrypto
algorithm objects, DOM sinks), so whether a program reads names cannot be decided from its text:
every pass and every unpack rewrite keeps each function's and class's name, writing
(0, function () {}), { old: fn }.old or let renamed = class old {} where a value would
otherwise gain or lose one, and leaving the code as it was (or the bundle whole) where no such form
exists. With --rename (any mode), a function's or class's name, and anything derived from it
(Error.prototype.toString, host APIs reading name), may change: renaming the binding that gives
the name is what was asked for. The renamer still keeps, as a best effort, the name of a function or
class when it sees the file read name (.name, a computed key that is not a number, a numeric
loop counter or a literal naming another property, reflection, copies of own properties, code text),
but that is not a promise. The other passes keep names under --rename as they do without it, so a
function a pass moves keeps the name it had.
docs/known-divergences/rename.md has the details.
The unsafe lane (--unsafe) makes the assumptions webcrack makes: built-in objects are not
patched, even when the program visibly patches one, a direct eval reads and writes no local
variable (the lexical passes still refuse a program whose eval may), a built-in prototype that the
program reaches through a value it reads ([].__proto__, o[key], Reflect.getPrototypeOf(x))
is not patched through that value, no code observes a classic script's top-level var or
function through the global object or by its name other than in the ways the scan sees (so
renaming may rename them; the safe lane never does). The scan sees property reads off the global
object and code built from text: a literal text that names a top-level binding, a text that is
not a literal, or a text that may hand back a code runner (Function("return eval")()(s),
Function("return Reflect.set")(), a constructor, a timer) keeps every top-level binding's name, let, const and class
included, as does a read of the global object by a key the scan cannot resolve, and no new
top-level name is a word that a string of the file spells, also when the string is joined
through a constant binding (Function("return typeof a")). A value read by a key the scan
cannot resolve is not taken to be a code runner, so calls made with it are not judged as code
text (a runner read by name or by a key the scan resolves still is). No code observes or
replaces the obfuscator's machinery, protections or decoder aliases through the global object,
reflection or global code text (so a top-level string array, decoder, decoder alias,
self-defending or debug-protection binding of a classic script is removed, and calls through it
are decoded, even when the program enumerates or tests the global object's names, reads or writes
them by key, through Object.assign, Reflect.set, Object.defineProperty or a loop over keys,
or runs code text through any runner, (0, eval),
Function, a timer string, or a runner that code text hands back such as
Function("return eval")()(s)). No function declared in a block overwrites a decoder alias, a
decoder wrapper or a constant used as a decoder argument through Annex B hoisting (var d = dec; { function d() {} } d(1) is decoded as a call of dec). A few passes that rest on
heuristics are allowed to run. These are template-literals and JSX reconstruction (jsx, jsx-new).
dead-code, which deletes branches behind constant comparisons, runs in both lanes.
fold-pure-calls also folds calls to a pure helper that is passed around as a value or that the
program could rebind through a key it cannot resolve.
A Metro bundle whose file does not hold Metro's own __d/__r runtime is unpacked on the trust
that those names are Metro's.
A function's caller (.caller, arguments.callee.caller, a stack frame's getFunction()) is
the bundle's own function in the bundle and node's module wrapper in a written file. The safe lane
splits a bundle only when no code can see that frame: every function in the bundle's input is
strict code and every written module file is strict (an ES module, or a file that starts with
"use strict"), because V8 gives null for the caller of a function called from strict code and
undefined for getFunction() on strict frames. Bundles with sloppy code, which covers most
webpack 4 and CommonJS bundles, are kept whole in the safe lane. The unsafe lane assumes no read
of a function's caller or arguments reaches a bundled module's function and splits them anyway.
The unsafe lane also splits a bundle whose modules import files given beside it, on the premise
that the inputs given beside a bundle are the files its relative imports load and that the bundle's
input is not imported back by name; the safe lane keeps any bundle with a relative import(),
import or export … from whole. It assumes no code text (Function, indirect eval, a timer
string) reaches import(), node's module objects or loader, and that the program does not read its
own file name or the main module's path (import.meta.url, __filename, require.main,
process.argv); the safe lane refuses those. Both lanes assume no code reads file names out of a stack trace (new Error().stack).
An input is taken as an ES module, as node 22 takes it, when it is named .mjs, when its own text
(before any pass runs) does not parse as a script but parses as a module (import/export,
import.meta or a top-level await x, also in code a later pass removes), or when it declares
require, exports, module, __filename or __dirname with a top-level let, const or class,
which node's CommonJS wrapper does not allow. A .cjs input is always a script, as in node. Any
other .js input is a script or CommonJS, also one that parses only by calling a global named
await (await (x)). Untwist decides between script and module from the file extension and the
text only: it does not read the "type" field of the nearest package.json, so a .js file under
"type": "module" (or a .js file with module syntax under "type": "commonjs") is processed as
node would process it with no package.json; name such a file .mjs or .cjs. An input that
node 22 rejects with a SyntaxError is passed through unchanged with an error: an early error (a
legacy octal literal in strict code, an invalid regular expression pattern, a parenthesised
destructuring target), syntax node 22 does not read (using,
decorators, accessor, import defer/source, assert import attributes, regular expression
modifiers and repeated group names), and <!-- in module code. Only the checks that a corpus of
probes run against node 22 shows node also makes refuse an input, so for example a legacy octal
literal directly in a sloppy file's class body, which V8 accepts, is read. An input that node runs
but untwist's parser cannot read (a call as an assignment target, for (yield of ...)) is passed
through unchanged with an error that says so, and a function declared directly in an if beside a
same-named let, const or class is passed through unchanged because untwist's binder does not
model its scope. The module code of a
bundle in an ES module input is strict, so its written module files get "use strict" (or are ES
modules themselves), and when the passes remove the only module syntax of such an input, its
output ends with export {}; so that node still runs it as a module.
This decodes more on aggressively protected code. It is the right choice when you trust that the
input does not tamper with the runtime, and the wrong one for code written to fool analysis.
Every deliberate difference from webcrack is listed, with the reason, in
docs/known-divergences.md, where webcrack is called the reference
deobfuscator.
--modern BASELINE removes core-js polyfills when the code will only run on engines that have
the feature natively. It is off unless you ask for it, and --unsafe does not turn it on.
BASELINE is an ES year (es2017 to es2024), engines and versions (chrome 120, firefox 121, safari 17, node 20), or both; an engine named twice counts with its lower version.
| Year | Engines it stands for |
|---|---|
es2017 |
chrome 57, edge 15, firefox 52, safari 11, ios 11, node 8.0.0, opera 44, samsung 7.0 |
es2018 |
chrome 64, edge 79, firefox 78, safari 16.4, ios 16.4, node 10.0.0, opera 51, samsung 9.0 |
es2019 |
chrome 73, edge 79, firefox 78, safari 16.4, ios 16.4, node 12.0.0, opera 60, samsung 11.0 |
es2020 |
chrome 80, edge 80, firefox 80, safari 16.4, ios 16.4, node 14.0.0, opera 67, samsung 13.0 |
es2021 |
chrome 85, edge 85, firefox 80, safari 16.4, ios 16.4, node 15.0.0, opera 71, samsung 14.0 |
es2022 |
chrome 94, edge 94, firefox 93, safari 16.4, ios 16.4, node 16.11.0, opera 80, samsung 17.0 |
es2023 |
chrome 110, edge 110, firefox 115, safari 16.4, ios 16.4, node 20.0.0, opera 96, samsung 21.0 |
es2024 |
chrome 119, edge 119, firefox 145, safari 17.4, ios 17.4, node 22.0.0, opera 105, samsung 25.0 |
A year stands for the first engine versions that shipped all of its syntax and built-ins, even
with known bugs (from @mdn/browser-compat-data); core-js-compat then decides per engine
whether core-js still replaces a buggy native there. The table is generated by
cargo xtask modern-table from the versions pinned in tools/core-js-compat.
Only modules that the library fingerprints recognise exactly as core-js are touched. A
polyfill module (modules/es.*, modules/web.*) is removed when core-js-compat, for the
recognised core-js version, says no engine in the baseline needs it, which also covers the
engines where core-js replaces a buggy native. Proposals (esnext.*), modules core-js still
replaces in one of the engines, modules whose exports other code reads, and modules that call
code not recognised as core-js are kept. A module that runs a module that is kept is kept as
well, so a polyfill the baseline needs never loses the call that ran it. Helper modules
(internals/*) that nothing uses any more are removed after them. Only core-js code is
removed: the module wrappers, their own variables and the statements that run a removed
module; code around them is never touched. core-js-pure (whose path object holds the
polyfills instead of the global object) is detected and left as it is.
In the core-js code that stays, calls of exactly matched helpers become the native form where
it behaves the same in every baseline engine: wellKnownSymbol("iterator") becomes
Symbol.iterator, getBuiltIn("Reflect", "ownKeys") becomes Reflect.ownKeys, hasOwn(it, key)
becomes Object.hasOwn(it, key), an uncurried method stringSlice(s, 1) becomes
String.prototype.slice.call(s, 1) (only when core-js does not replace that method in the
baseline), and isCallable(it) becomes typeof it == "function" only when no browser is in the
baseline (in browsers core-js also accepts document.all). requireObjectCoercible is left as
it is, since no native form throws the same error. A call is rewritten only where it is used as
a value (not under delete), where the built-in's name is not shadowed, and where the helper's
variable is certainly set before the call runs.
The rewritten calls read the engine's built-ins when they run, where core-js read them once when
it loaded (hasOwn keeps the Object.hasOwn it saw then, an uncurried method keeps the method).
So the output assumes that the program does not replace built-ins after core-js loaded. Removing
a module can also move the first run of a helper module it used to run, which matters only to
code that changes built-ins between the two points.
The report lists every removed and kept module with the reason and every rewritten call kind, and says that the output assumes such an engine with its own built-ins; the output starts with a comment saying the same. These are informational notes: one summary line counts the removed and kept modules (the kept ones by reason), and the playground shows the per-module list in Details, grouped by reason, instead of in Diagnostics.
Modern mode is part of the CLI, the Rust library (cargo feature modern, on by default), the
WebAssembly build and the playground (Settings, Modern baseline), where the core-js table is
fetched only when the input holds core-js code.
Today this covers Rollup bundles built with @rollup/plugin-commonjs and strictRequires
(the lazy requireX() wrappers and the inline wrappers Rollup makes for modules required
once), in one program (with --split-hoisted every wrapper becomes its own module and they are
left as they are). Scope-hoisted Rollup output, webpack module maps, esbuild __commonJS
bundles and wrappers a minifier inlined into their caller are recognised but left as they are.
--types (or --types=jsdoc) keeps JavaScript and adds /** @type */, @param and @returns
comments; --types=ts writes the output as TypeScript (.ts, or .tsx when JSX is left). It is
experimental and off unless you ask for it. An annotation is written only when untwist proves
that every value the position can hold, on every run, has that type; everything else stays as it
was. number includes NaN and -0, a literal type is never NaN or -0, and no annotation is
ever any or unknown.
What it proves today is only what needs no premise about the rest of the realm: literals and the
closed set of values a local binding is written with, the results of operators, function returns
(an async function's as Promise<…>), and the parameters of a strict function (module code,
class code or code under "use strict") whose every call is visible. .caller, .arguments and
the stack-trace API never hand out a strict function, so no code outside the run can call one with
other values. A function is never treated that way when it is exported, reads arguments, is
called with a spread, or is reached any other way, and no function at all when any input or module
of the run can read a function's frame (.caller, .arguments, stack-trace functions, a with
statement, or code text that could). A sloppy function's parameters stay untyped, and so do the
results of built-ins such as Math.floor, parseInt or "".slice: both would rest on proving
that no code in the realm patches a built-in or reaches a frame, which this version does not try.
A direct eval (also through a local binding named eval) leaves untyped every binding it can
reach, and in sloppy code it also turns off the types that rest on global names it could shadow
(undefined, NaN, Infinity); a constant-string eval that only reads leaves out only the
names it reads. A with statement leaves the file untyped, and so does an object literal with a member whose
computed key is Symbol.<name> (tsc 7.0.2 reports the type errors around such an object only in
part, and differently from run to run, until a type is written); an operator result is typed only
when every operand is a proven primitive. Script-level vars, exported
bindings, objects, arrays, classes and the DOM get no types.
Every proven type is written, also when TypeScript would infer it anyway, unless writing it would
give the TypeScript checker a new error (for example a literal type compared with a value outside
it, which the checker narrows away), so the annotated file checks no worse than the untyped
output under strict with noImplicitAny off. --report counts the annotated positions, how
many of them TypeScript infers anyway, and the refused ones. The flag cannot be combined with
--source-map.
A file is written as .ts only when its TypeScript parse, stripped of the annotations, is the same
program as its JavaScript parse (a < b > (c) is a comparison in JavaScript and a generic call in
TypeScript) and it uses no name node's type stripping rejects (await, yield as identifiers);
otherwise it keeps its .js name and is written untyped. CommonJS files (free require,
module or exports) keep .js under --types=ts and stay untyped; --types (JSDoc) types them.
When split ES modules become .ts, the import, export … from, import() and require
specifiers that name them are rewritten to the new names, so the tree runs under node's type
stripping and checks with allowImportingTsExtensions. When a module loads another by a computed
name, or uses require other than as a call with one literal, or import.meta, every file keeps
its .js name and its untyped text. With --single-file, the joined file is TypeScript only when
every part is; otherwise every part is written untyped.
The types run after every other stage, on the final text, so they describe the program untwist
prints. The checks behind this live in crates/untwist-types/tests (one row per hazard), in the
node run of the fixtures with every annotation turned into a runtime check, and in
tools/types-check, which runs the pinned tsc over every annotated fixture output against the
same text without annotations and fails on any new diagnostic. It runs tsc three times on each
side (TYPES_CHECK_RUNS sets the count) and compares each annotated run with its own plain run,
so a new diagnostic in any one run fails the check, and more runs can only find more.
Known limitation: tsc 7.0.2 may report fewer diagnostics for unannotated code whose types carry
well-known-symbol keys ([Symbol.iterator], [Symbol.toPrimitive], ...), and which ones it drops
changes from run to run. A typed file can then show diagnostics that the plain file's run left out.
The annotations themselves are still true. A file with an object literal keyed by a literal
Symbol.<name> is left untyped to make this rarer, but an aliased Symbol or a copy of such an
object through a spread is not caught. See
docs/known-divergences/types.md. --against-js also compares each
.ts output with the untyped output as .js under checkJs; the diagnostics it reports come from
renaming JavaScript to .ts (in a .ts file every parameter is required, an object literal gets a
fixed shape, and so on), not from the annotations, so they do not touch the promise that every
written type holds. JSDoc mode keeps .js and has none of them, which is why a bare --types and
the playground's first choice are JSDoc.
untwist.dev runs Untwist in a Web Worker. Paste, drop or open a script and
press Run. You can browse and download the unpacked modules, compare input and output side by side,
read diagnostics and the run report, and edit the output with go to definition, find references
and rename. The output is byte for byte what the CLI gives for the same flags. The source is in
web/.
| Untwist | webcrack | |
|---|---|---|
| Language | Rust (oxc) | TypeScript (Babel) |
| Runs the input's code | Never; decoders run in a sandboxed, budgeted interpreter | Runs decoders in isolated-vm |
| Decoding under tampering | Refuses what it cannot prove, by default | Assumes built-ins are unpatched |
| Bundlers | webpack, browserify, esbuild/Bun, rolldown/Vite 8, SystemJS, AMD, UMD, Parcel, Metro, Turbopack, Closure, Rollup/Vite (opt-in) | webpack, browserify |
| Untranspile helpers | TypeScript, Babel, SWC, esbuild | No |
| Rename modes | mangle, simple, unique |
mangle |
Untwist's output is checked against webcrack's with differential harnesses (cargo xtask diff-unminify, diff-deobfuscate, diff-unpack, diff-mangle, diff-jsx), which run Untwist in
an internal comparison mode limited to the passes webcrack has. Decoded output is also checked by
running both the input and the output under Node and comparing what they print. cargo xtask obf-options runs javascript-obfuscator 5.9.1 output for every free option, pairs of the
high-impact ones and the four presets through both lanes and a pinned webcrack, and requires each
output to keep no obfuscator machinery and to print what the original program prints.
--suggest-expect <file> writes a whole replacement for its EXPECT. Each failure is named by its
cause, and each cause keeps the reason it already has in EXPECT.
cargo xtask obf-options --dir fixtures/obfuscator-versions runs the same checks on the version
matrix that tools/obfuscated/versions.mjs generates: twenty javascript-obfuscator releases from
0.10.2 to 5.9.1, each with its own string array options (encoding, rotate, shuffle, index shift,
wrappers, calls transform, threshold) and one extra transform, placed at the top level, in an IIFE,
in a webpack 4 module or around a whole webpack 4 bundle, then left as is or minified with
uglify-js or terser. The cells cover every version × encoding × container × minifier and every
pair of the other choices. Its EXPECT says for each cell whether the run is refused with a named
reason or MISSED (no string array found, or calls left with no note).
cargo xtask obf-fuzz --seed <n> --count <n> draws random programs from a grammar of those
features, obfuscates them with random option sets and rewires the decoder (aliases, wrappers, inert
statements, strict mode, a wrapping function), then judges both lanes the same way. A failure is
grouped by the cause key of its first blocking note and shrunk to a small repro. Only causes listed in
fixtures/fuzz/EXPECT (open gaps) or fixtures/obfuscator-io/SOUND_REFUSALS (refusals that are the
right answer, on programs with the named feature) are allowed.
cargo build --release -p untwist-cli # target/release/untwist
cargo test --workspaceThe workspace layout:
| Crate | Contents |
|---|---|
untwist |
The pipeline and the library API |
untwist-cli |
The untwist command-line tool |
untwist-core |
Parsing, printing and the pass framework |
untwist-eval |
Constant folding and the sandboxed interpreter |
untwist-deobfuscate |
String arrays, control flow and protections |
untwist-unminify |
Unminify and untranspile passes |
untwist-unpack |
Bundle detection and module extraction |
untwist-rename |
Identifier renaming |
untwist-jsx |
JSX reconstruction |
untwist-wasm |
The WebAssembly build (npm untwist) |
untwist-regress |
A fork of regress with a step-budgeted search |
Some tests read a large real-world sample at fixtures/real-world/game.js, which is not
distributed with the repository; they are skipped when it is absent. The cargo xtask diff-*
harnesses need a built webcrack clone in reference/ (or set UNTWIST_REFERENCE_DIR) and a CLI
built with cargo build --release -p untwist-cli --features test-hooks; cargo xtask obf-options --webcrack also needs npm ci --prefix tools/webcrack. Test inputs are described
in fixtures/README.md.
Licensed under either of Apache License 2.0 or MIT license at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
Untwist's behaviour follows webcrack, and the fixtures under fixtures/reference/ come from
webcrack (MIT, Copyright (c) 2023 j4k0xb, see fixtures/LICENSE-reference).
vendor/regress is a fork of regress by ridiculousfish (MIT OR Apache-2.0). See NOTICE.