javascript-obfuscator 5.4.1 → 5.4.2

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 Change Log
 
+v5.4.2
+---
+* Fixed obfuscated code hanging in Bun when `selfDefending` is enabled. Fixes https://github.com/javascript-obfuscator/javascript-obfuscator/issues/1404
+
 v5.4.1
 ---
 * Fixed `Utils.nodeRequire` causing `ReferenceError: require is not defined` in browser build by making it lazy-evaluated

package/README.md

@@ -15,13 +15,25 @@ Huge thanks to all supporters!
 
 ---
 
-### :rocket: Obfuscator.io with VM Obfuscation is out!
+### :rocket: Obfuscator.io with VM Obfuscation
 
-**Obfuscator.io** features **VM-based bytecode obfuscation** — the most advanced code protection available. Your JavaScript functions are transformed into custom bytecode running on an embedded virtual machine, making reverse engineering extremely difficult.
+**Obfuscator.io** adds **VM-based bytecode obfuscation** to this package - your JavaScript functions are compiled to custom bytecode that runs on an embedded virtual machine. Each build produces unique opcodes and VM structure, making reverse engineering and automated deobfuscation dramatically harder.
 
-[Try it at obfuscator.io](https://obfuscator.io)
+| Protection goal | Free (this package)                                                               | [obfuscator.io](https://obfuscator.io)                                                                                                                                                                        |
+| --- |-----------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Rename identifiers | ✅ variable/function renaming                                                      | ✅ + VM-local symbols never exposed as JavaScript                                                                                                                                                              |
+| Obscure strings | ✅ string array + base64/rc4 | ✅ + strings embedded in bytecode constants                                                                                                                                                                    |
+| Obscure control flow | ✅ control flow flattening | ✅ full bytecode virtualization, [`vmJumpsEncoding`](#vmjumpsencoding) (runtime-computed jump targets), [`vmDeadCodeInjection`](#vmdeadcodeinjection) (fake bytecode sequences)                                |
+| Resist decompilation | ⚠️ output is still JavaScript | ✅ custom opcodes, [`vmStatefulOpcodes`](#vmstatefulopcodes) (position-dependent opcode mapping), [`vmMacroOps`](#vmmacroops) (fused instructions), [`vmDecoyOpcodes`](#vmdecoyopcodes) (fake opcode handlers) |
+| Resist automated LLM-based analysis | ❌ fully vulnerable (no LLM-specific defenses) | ✅ bytecode encryption + anti-LLM defenses in [`vmSelfDefending`](#vmselfdefending) and [`vmDebugProtection`](#vmdebugProtection)                                                                              |
+| Encryption | ✅ [`stringArrayEncoding`](#stringarrayencoding) (base64/rc4 on extracted strings) | ✅ [`vmBytecodeEncoding`](#vmbytecodeencoding) (per-instruction encoding), [`vmBytecodeArrayEncoding`](#vmbytecodeArrayEncoding) (whole bytecode array as single block)                                        |
+| Anti-debugging | ✅ `debugProtection` (freezes browser DevTools) | ✅ [`vmDebugProtection`](#vmdebugProtection) (multi-layered anti-debugging and anti-analysis defenses)                                                                                                         |
+| Tamper detection | ✅ `selfDefending` (breaks if beautified) | ✅ [`vmSelfDefending`](#vmselfdefending) (multi-layered tamper detection, anti-hooking, anti-reverse-engineering protection)                                                                                   |
+| Runs offline, no network | ✅ | ❌ uses obfuscator.io API (requires token)                                                                                                                                                                     |
 
-This package provides access to Obfuscator.io Pro API via CLI and Node.js API.
+[Visit Obfuscator.io](https://obfuscator.io) · [Pro API methods](#shield-pro-api-methods-vm-obfuscation)
+
+This package provides access to Obfuscator.io API via CLI and Node.js API.
 
 ---
 
@@ -51,6 +63,7 @@ The example of obfuscated code: [github.com](https://github.com/javascript-obfus
 * Malta: [malta-js-obfuscator](https://github.com/fedeghe/malta-js-obfuscator)
 * Netlify plugin: [netlify-plugin-js-obfuscator](https://www.npmjs.com/package/netlify-plugin-js-obfuscator)
 * Snowpack plugin: [snowpack-javascript-obfuscator](https://www.npmjs.com/package/snowpack-javascript-obfuscator)
+* Vite plugin: [vite-plugin-bundle-obfuscator](https://github.com/z0ffy/vite-plugin-bundle-obfuscator)
 
 [![npm version](https://badge.fury.io/js/javascript-obfuscator.svg)](https://badge.fury.io/js/javascript-obfuscator)
 [![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fjavascript-obfuscator%2Fjavascript-obfuscator.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Fjavascript-obfuscator%2Fjavascript-obfuscator?ref=badge_shield)
@@ -513,6 +526,8 @@ When using CLI this prefix will be added automatically.
 
 ## JavaScript Obfuscator Options
 
+> :shield: **Looking for VM obfuscation?** Options like `vmObfuscation`, `parseHtml`, and every `vm*` option are Pro-only and require an API token from [obfuscator.io](https://obfuscator.io). Use them via the [`obfuscatePro()`](#shield-pro-api-methods-vm-obfuscation) method, or the `--pro-api-token` CLI flag — see [Pro API Methods](#shield-pro-api-methods-vm-obfuscation).
+
 Following options are available for the JS Obfuscator:
 
 #### options:
@@ -1870,8 +1885,8 @@ Specify exactly which root-level functions should get VM protection by name.
 **Example:**
 ```javascript
 {
-    vmObfuscation: true,
-    vmTargetFunctions: ['someFunctionName']
+  vmObfuscation: true,
+  vmTargetFunctions: ['someFunctionName']
 }
 ```
 
@@ -1885,8 +1900,8 @@ Specify root-level functions that should never get VM protection. Takes preceden
 **Example:**
 ```javascript
 {
-    vmObfuscation: true,
-    vmExcludeFunctions: ['someFunctionName']
+  vmObfuscation: true,
+  vmExcludeFunctions: ['someFunctionName']
 }
 ```
 
@@ -1906,28 +1921,28 @@ Controls how functions/methods are selected for VM obfuscation.
 ```javascript
 // Source code
 function regularFunction() {
-    return 'not virtualized';
+  return 'not virtualized';
 }
 
 /* javascript-obfuscator:vm */
 function sensitiveFunction() {
-    return 'this will be VM-protected';
+  return 'this will be VM-protected';
 }
 
 function outer() {
-    /* javascript-obfuscator:vm */
-    function nestedSensitive() {
-        return 'nested but still VM-protected';
-    }
-    return nestedSensitive();
+  /* javascript-obfuscator:vm */
+  function nestedSensitive() {
+    return 'nested but still VM-protected';
+  }
+  return nestedSensitive();
 }
 ```
 
 ```javascript
 // Obfuscator options
 {
-    vmObfuscation: true,
-    vmTargetFunctionsMode: 'comment'
+  vmObfuscation: true,
+  vmTargetFunctionsMode: 'comment'
 }
 ```
 
@@ -2020,10 +2035,10 @@ vmBytecodeArrayEncodingKeyGetter: "window.config.encryption.key"
 ```ts
 // Build time
 JavaScriptObfuscator.obfuscate(code, {
-    vmObfuscation: true,
-    vmBytecodeArrayEncoding: true,
-    vmBytecodeArrayEncodingKey: 'mySecretKey123',
-    vmBytecodeArrayEncodingKeyGetter: 'window.__VM_KEY__'
+  vmObfuscation: true,
+  vmBytecodeArrayEncoding: true,
+  vmBytecodeArrayEncodingKey: 'mySecretKey123',
+  vmBytecodeArrayEncodingKeyGetter: 'window.__VM_KEY__'
 });
 
 // Runtime - key must be set before obfuscated code runs
@@ -2045,26 +2060,24 @@ Type: `boolean` Default: `false`
 
 Injects fake bytecode sequences that are never executed. These look like real instructions but are skipped during runtime, confusing analysis tools that process them.
 
-### `vmCompactDispatcher`
+### `vmMacroOps`
 Type: `boolean` Default: `false`
 
-Uses a single unified dispatcher (generator-based) for both sync and async/generator code execution. By default (`false`), the VM generates two separate dispatchers: a non-generator version for sync code (faster) and a generator version for async/generator code. When enabled, only the generator-based dispatcher is used for all execution.
+Combines common instruction sequences into single "macro" opcodes. For example, `LOAD + ADD + STORE` might become a single `MACRO_ADD_TO_VAR` instruction. This breaks pattern recognition and can improve performance.
 
-**Trade-offs:**
-- `false` (default): Larger code size due to dual dispatchers, but faster sync execution (no generator overhead)
-- `true`: Smaller code size with single dispatcher, but sync code has generator protocol overhead
+### `vmDebugProtection`
+Type: `boolean` Default: `false`
 
-Use this when code size is more important than sync execution speed.
+Adds multi-layered anti-debugging, anti-analysis, and anti-LLM defenses to the VM runtime. For best results, allow `unsafe-eval` in your Content Security Policy. Works best with `browser`/`browser-no-eval` targets.
 
-### `vmMacroOps`
+### `vmSelfDefending`
 Type: `boolean` Default: `false`
 
-Combines common instruction sequences into single "macro" opcodes. For example, `LOAD + ADD + STORE` might become a single `MACRO_ADD_TO_VAR` instruction. This breaks pattern recognition and can improve performance.
+Adds multi-layered tamper detection, anti-hooking, and anti-reverse-engineering protection to the VM runtime.
 
-### `vmDebugProtection`
-Type: `boolean` Default: `false`
+> :warning: This option force-enables [`vmBytecodeArrayEncoding`](#vmbytecodeArrayEncoding).
 
-Adds anti-debugging measures to the VM runtime. Detects debugger presence and alters behavior when debugging is detected.
+Strongly recommended to use together with [`vmDebugProtection`](#vmDebugProtection), [`vmBytecodeArrayEncodingKey`](#vmbytecodeArrayEncodingKey), and [`vmBytecodeArrayEncodingKeyGetter`](#vmbytecodeArrayEncodingKeyGetter).
 
 ### `vmStatefulOpcodes`
 Type: `boolean` Default: `false`
@@ -2078,6 +2091,26 @@ Encrypts values on the VM stack during execution. Values are encoded when pushed
 
 This option heavily affects performance.
 
+### `vmCompactDispatcher`
+Type: `boolean` Default: `false`
+
+Uses a single VM executor instead of dual executors (sync + generator). Reduces obfuscated code size but adds ~20% performance overhead on recursion-heavy code.
+
+- `false` (default): dual executors — optimal performance, larger output
+- `true`: single executor — smaller output, slightly slower
+
+### `vmStringArrayBytecodeOnly`
+Type: `boolean` Default: `false`
+
+When enabled, the string array will **only** extract strings from bytecode data — no other strings in the code are transformed. This force-enables `stringArray` even if it's not explicitly set.
+
+**Why use this:** Extracting all VM runtime strings to a string array is slow. This option targets only bytecode content for string array extraction, improving performance while still protecting bytecode constants.
+
+- When `vmBytecodeArrayEncoding: false` — strings inside bytecode constant pools (`c` arrays) are extracted
+- When `vmBytecodeArrayEncoding: true` — top-level base64 encoded bytecode strings are extracted
+- `stringArrayThreshold` still controls what percentage of those bytecode strings are extracted
+
+
 ### `strictMode`
 Type: `boolean | null` Default: `null`