javascript-obfuscator 5.4.1 → 5.4.3

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 Change Log
 
+v5.4.3
+---
+* Fixed `controlFlowFlattening` occasionally dropping the `?.` short-circuit on `foo?.(arg)` calls, causing `TypeError: <X> is not a function`. Fixes https://github.com/javascript-obfuscator/javascript-obfuscator/issues/1408
+
+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/CLAUDE.md

@@ -42,7 +42,7 @@
 - **Parser**: Acorn 8.8.2 (ES3-ES2020 support)
 - **Code Generator**: @javascript-obfuscator/escodegen 2.3.0
 - **AST Traversal**: @javascript-obfuscator/estraverse 5.4.0
-- **DI Framework**: InversifyJS 6.0.1
+- **DI Framework**: InversifyJS 7.10.8
 - **Testing**: Mocha 10.4.0 + Chai 4.3.7
 - **Build System**: Webpack 5.75.0
 
@@ -210,7 +210,7 @@ The obfuscation process follows a multi-stage pipeline defined in `JavaScriptObf
 
 ### Dependency Injection Architecture
 
-The project uses **InversifyJS** for dependency injection, providing:
+The project uses **InversifyJS v7** for dependency injection, providing:
 
 - **Modularity**: Clean separation of concerns
 - **Testability**: Easy mocking and testing
@@ -219,6 +219,13 @@ The project uses **InversifyJS** for dependency injection, providing:
 
 All components are registered in container modules located in `src/container/modules/`.
 
+**Key Changes in InversifyJS v7:**
+- Container modules now use `ContainerModuleLoadOptions` instead of separate `bind`, `unbind`, etc. parameters
+- `getNamed`, `getTagged`, etc. are replaced by `get(serviceId, { name: ... })` or `get(serviceId, { tag: ... })`
+- `load()` and `unload()` are now async, with `loadSync()` and `unloadSync()` alternatives for synchronous operations
+- Types like `Context`, `Newable`, `Factory` are now directly exported instead of through `interfaces` namespace
+- Custom metadata and middleware features have been removed
+
 ## Key Components Deep Dive
 
 ### 1. JavaScriptObfuscator (Main Engine)

package/README.md

@@ -4,24 +4,53 @@
   Author: Timofei Kachalov
   -->
 
-#### You can support this project by donating:
-* (Github) https://github.com/sponsors/sanex3339
-
-Huge thanks to all supporters!
-
 # JavaScript obfuscator
 
 ![logo](https://raw.githubusercontent.com/javascript-obfuscator/javascript-obfuscator/master/images/logo.png)
 
 ---
 
-### :rocket: Obfuscator.io with VM Obfuscation is out!
+### Do you use JavaScript Obfuscator at your company?
+
+JavaScript Obfuscator has reached over **1 million npm downloads per week**. I am currently preparing an **EB-1 immigration case** and collecting independent evidence of the project’s real-world professional usage and impact.
+
+If you use JavaScript Obfuscator in a company project — especially at a well-known company, large organization, or widely used product — I would be very grateful if you could contact me.
+
+Helpful evidence may include a brief confirmation or, ideally, a 1–2 page reference letter describing:
+
+- how your team or company used JavaScript Obfuscator;
+- why you chose it;
+- what problem it helped solve;
+- whether it was used in production or an important internal workflow;
+- your role and how you are familiar with the usage.
+
+I can provide a simple draft/template to make this easy.
+
+Please contact me at: **referenceletter@obfuscator.io**
+
+Thank you for supporting the project.
+
+---
+
+### :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 +80,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 +543,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 +1902,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 +1917,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 +1938,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 +2052,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 +2077,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 +2108,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`