:::::::..    ...    :::  :::.     .        :
;;;;``;;;;   ;;     ;;;  ;;`;;    ;;,.    ;;;
 [[[,/[[['  [['     [[[ ,[[ '[[,  [[[[, ,[[[[,
 $$$$$$c    $$      $$$c$$$cc$$$c $$$$$$$$"$$$
 888b "88bo,88    .d888 888   888,888 Y88" 888o
 MMMM   "W"  "YmmMMMM"" YMM   ""` MMM  M'  "MMM

Virtualization-Based (VM) JavaScript Obfuscator

Compiles JavaScript (JS) functions into custom bytecode executed by an embedded virtual machine.
Obfuscation does not guarantee secrecy or prevent reconstruction by an attacker who controls execution.

---

Quick Links

Installation ·  Quick Start ·  How It Works ·  Presets ·  API

The experimental offline regional compiler is available through explicit research APIs and ruam --regional-research. Its protection strength is unqualified; it does not replace the production VM. See the implementation and evidence and the selected design.

Most JavaScript obfuscators apply surface-level transformations — renaming variables, encoding strings, inserting dead code. A motivated attacker can undo these with off-the-shelf tools, logic analysis, or by patching functions at runtime.

Ruam compiles eligible JavaScript functions into a custom bytecode instruction set and embeds a virtual machine to execute them. Code outside the selected compilation scope can remain ordinary JavaScript. The artifact contains what it needs to run offline, so an attacker can inspect the interpreter, observe execution, and attempt to reconstruct equivalent logic.

Source JS → Transformed JS (still JS)

• Same language, same semantics
• AST-reversible transformations
• Automated deobfuscation tools exist

Source JS → Custom Bytecode + Embedded VM

• Selected function bodies become bytecode
• Attackers can analyze the VM or infer equivalent behavior
• Recovery resistance must be measured against concrete attacks

npm install ruam@npm:ruamvm
# or
bun add ruam@npm:ruamvm
# or
pnpm add ruam@npm:ruamvm
# or
yarn add ruam@npm:ruamvm

Requires Node.js >= 18. Ships as ESM only.

Ruam is published to npm under the name ruamvm (the registry rejects ruam as too similar to raf/rax/read). Installing via the ruam@npm:ruamvm alias keeps imports and CLI invocations as ruam everywhere. The CLI binary is also installed as ruamvm if you prefer.

# Obfuscate a file in-place
ruam app.js

# Obfuscate to a new file
ruam app.js -o app.obf.js

# Obfuscate a directory with medium preset
ruam dist/ --preset medium

# Maximum protection
ruam dist/ --preset max

# Interactive wizard (or just run `ruam` with no args)
ruam -I

import { obfuscateCode, obfuscateFile, runVmObfuscation } from "ruam";

// Synchronous — obfuscate a code string
const result = obfuscateCode('function hello() { return "world"; }');

// Async — obfuscate a file
await obfuscateFile("src/app.js", "dist/app.js");

// Async — obfuscate a directory with options
await runVmObfuscation("dist/", {
  include: ["**/*.js"],
  exclude: ["**/node_modules/**"],
  options: { preset: "max" },
});

Not every function needs virtualization. Use comment mode to protect only what matters:

/* ruam:vm */
function sensitiveLogic() {
  // → compiled to bytecode
}

function publicHelper() {
  // → untouched, no overhead
}

ruam app.js -m comment

Ruam applies multiple independent protection layers that compound the difficulty of reverse engineering. Each layer forces an attacker to solve a distinct problem before they can make progress on the next.

Additional hardening options include dead bytecode injection, stack value encryption, decoy opcode handlers, handler fragmentation, runtime opcode mutation, and polymorphic string decoding — all configurable independently or via presets.

Three built-in presets provide escalating protection. Explicit options always override preset values.

ruam dist/ --preset max

obfuscateCode(source, {
  preset: "medium",
  debugProtection: true,  // override: add debug protection to medium
});

Virtualization inherently adds overhead — this is the tradeoff for protection that surface-level transforms cannot provide. Ruam's multi-tier optimization pipeline minimizes the cost.

Typical overhead: ~38–45x native speed on compute-heavy benchmarks, competitive for a pure JS-in-JS interpreter.

Use selective obfuscation (-m comment) to protect only sensitive functions and leave hot paths running as native JS.

ruam <input> [options]

Presets:
  --preset <name>           Apply a preset: low, medium, max

Output:
  -o, --output <path>       Output file or directory (default: overwrite input)

Compilation:
  -m, --mode <mode>         Target mode: "root" (default) or "comment"
  -e, --encrypt             Enable bytecode encryption
  -p, --preprocess          Rename all identifiers before compilation

Security:
  -d, --debug-protection    Enable anti-debugger protection
  --no-debug-protection     Disable anti-debugger (overrides preset)
  --rolling-cipher          Enable instruction encryption
  --integrity-binding       Bind decryption to interpreter integrity
  --vm-shielding            Per-function isolated micro-interpreters

Hardening:
  --dynamic-opcodes         Filter unused opcodes from the interpreter
  --decoy-opcodes           Add fake opcode handlers
  --dead-code               Inject dead bytecode sequences
  --stack-encoding          Encrypt values on the VM stack
  --mba                     Arithmetic obfuscation (mixed boolean arithmetic)
  --handler-fragmentation   Split handler logic into interleaved fragments
  --string-atomization      Replace interpreter strings with encoded lookups
  --polymorphic-decoder     Per-build randomized string decoding chain
  --scattered-keys          Fragment key materials across closure scopes
  --block-permutation       Shuffle bytecode basic block order
  --opcode-mutation         Insert runtime handler table mutations

Environment:
  --target <env>            Target environment: node, browser (default), browser-extension

File Selection:
  --include <glob>          File glob for directory mode (default: "**/*.js")
  --exclude <glob>          Exclude glob (default: "**/node_modules/**")

Other:
  --debug-logging           Inject verbose VM trace logging
  -I, --interactive         Launch interactive configuration wizard
  -h, --help                Show help
  -v, --version             Show version

Synchronously obfuscates a JavaScript source string. Returns the obfuscated code as a string.

import { obfuscateCode } from "ruam";

const output = obfuscateCode(source, {
  preset: "medium",
  targetMode: "root",
});

Reads a file, obfuscates it, and writes the result. Returns a Promise<void>.

import { obfuscateFile } from "ruam";

await obfuscateFile("src/app.js", "dist/app.js", { preset: "max" });

Obfuscates all matching files in a directory. Returns a Promise<void>.

import { runVmObfuscation } from "ruam";

await runVmObfuscation("dist/", {
  include: ["**/*.js"],
  exclude: ["**/node_modules/**"],
  options: { preset: "medium" },
});

Ruam compiles the full range of modern JavaScript:

• Functions (declarations, expressions, arrows, generators, async, async generators)
• Classes (inheritance, constructors, methods, getters/setters, computed properties, static members, super)
• Control flow (if, for, for-in, for-of, while, do-while, switch, labeled statements)
• Exception handling (try/catch/finally, throw)
• Destructuring (array and object patterns, defaults, rest elements, nested)
• Spread/rest (...args in calls, arrays, and object literals)
• Closures and lexical scoping (let/const with proper TDZ, per-iteration bindings)
• Async/await, generators (yield, yield*), async generators
• Template literals, tagged templates, optional chaining, nullish coalescing
• Computed property names, shorthand properties/methods, symbol keys

Use --target to optimize output for your deployment environment:

ruam content-script.js --target browser-extension --preset max

• Node.js >= 18
• ESM ("type": "module")

LGPL-2.1