javascript-obfuscator 5.5.1 → 5.7.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 Change Log
 
+v5.7.0
+---
+* **New option:** `advertisement` allows to control the display of the JavaScript Obfuscator Pro advertisement message in the console. Fixed https://github.com/javascript-obfuscator/javascript-obfuscator/issues/1448
+
+v5.6.0
+---
+* Pro API: `obfuscatePro` now fall back to the basic local obfuscation API when no Pro feature (`vmObfuscation` or `parseHtml`) is enabled, instead of throwing an `ApiError`
+* Improved `stringArrayEncoding` runtime performance
+
 v5.5.1
 ---
 * Fixed leading whitespace of the source code being stripped without being reflected in the source map, shifting all `sourcesContent` and original position mappings. Fixes https://github.com/javascript-obfuscator/javascript-obfuscator/issues/1437

package/README.md

@@ -348,7 +348,7 @@ console.log(result.getObfuscatedCode());
 **Parameters:**
 
 * `sourceCode` (`string`) – source code to obfuscate
-* `options` (`Object`) – obfuscation options. **Must include at least one Pro feature: `vmObfuscation: true` or `parseHtml: true`**
+* `options` (`Object`) – obfuscation options. To use the Pro API, include at least one Pro feature: `vmObfuscation: true` or `parseHtml: true`. When no Pro feature is enabled, `obfuscatePro` falls back to the basic (local) obfuscation API.
 * `apiConfig` (`Object`) – Pro API configuration:
   * `apiToken` (`string`, required) – your API token from obfuscator.io
   * `timeout` (`number`, optional) – request timeout in ms (default: `300000` - 5 minutes)
@@ -357,8 +357,9 @@ console.log(result.getObfuscatedCode());
 
 **Returns:** `Promise<ObfuscationResult>`
 
+> **Note:** When no Pro feature (`vmObfuscation` or `parseHtml`) is enabled, the Pro API is not needed, so `obfuscatePro` falls back to the basic (local) obfuscation API and no API request is made.
+
 **Throws:** `ApiError` if:
-- No Pro features (`vmObfuscation` or `parseHtml`) are enabled in options
 - API token is invalid or expired
 - API request fails
 
@@ -554,6 +555,7 @@ Following options are available for the JS Obfuscator:
 
 ```javascript
 {
+    advertisement: true,
     compact: true,
     controlFlowFlattening: false,
     controlFlowFlatteningThreshold: 0.75,
@@ -617,6 +619,7 @@ Following options are available for the JS Obfuscator:
 
     -o, --output
 
+    --advertisement <boolean>
     --compact <boolean>
     --config <string>
     --control-flow-flattening <boolean>
@@ -634,6 +637,7 @@ Following options are available for the JS Obfuscator:
     --identifier-names-generator <string> [dictionary, hexadecimal, mangled, mangled-shuffled]
     --identifiers-dictionary '<list>' (comma separated)
     --identifiers-prefix <string>
+    --random-identifiers-prefix <boolean>
     --ignore-imports <boolean>
     --log <boolean>
     --numbers-to-expressions <boolean>
@@ -667,6 +671,7 @@ Following options are available for the JS Obfuscator:
     --string-array-wrappers-type <string> [variable, function]
     --string-array-threshold <number>
     --target <string> [browser, browser-no-eval, node]
+    --browser-environment <string> [http, https]
     --transform-object-keys <boolean>
     --unicode-escape-sequence <boolean>
     --pro-api-token <string>
@@ -678,6 +683,7 @@ Following options are available for the JS Obfuscator:
     --vm-target-functions '<list>' (comma separated)
     --vm-exclude-functions '<list>' (comma separated)
     --vm-target-functions-mode <string> [root, comment]
+    --vm-force-compile-dynamic-code <boolean>
     --vm-wrap-top-level-initializers <boolean>
     --vm-opcode-shuffle <boolean>
     --vm-bytecode-encoding <boolean>
@@ -691,12 +697,19 @@ Following options are available for the JS Obfuscator:
     --vm-split-dispatcher <boolean>
     --vm-macro-ops <boolean>
     --vm-debug-protection <boolean>
+    --vm-self-defending <boolean>
     --vm-runtime-opcode-derivation <boolean>
     --vm-stateful-opcodes <boolean>
+    --vm-async-executor <boolean>
+    --vm-call-context-opcodes <boolean>
     --vm-stack-encoding <boolean>
     --vm-randomize-keys <boolean>
     --vm-indirect-dispatch <boolean>
     --vm-compact-dispatcher <boolean>
+    --vm-register-based <boolean>
+    --vm-string-array-bytecode-only <boolean>
+    --vm-domain-lock '<list>' (comma separated)
+    --vm-domain-lock-redirect-url <string>
     --vm-bytecode-format <string> [binary, json]
     --parse-html <boolean>
     --strict-mode <boolean>
@@ -704,6 +717,13 @@ Following options are available for the JS Obfuscator:
 
 <!-- ##options-start## -->
 
+### `advertisement`
+Type: `boolean` Default: `true`
+
+Allows to control the display of the JavaScript Obfuscator Pro advertisement message in the console.
+
+The message is only shown when using the Node.js CLI in an interactive (TTY) terminal, is never shown in CI environments or in the browser, and is limited to a few displays. Set this option to `false` to disable the advertisement message completely.
+
 ### `compact`
 Type: `boolean` Default: `true`
 
@@ -1968,6 +1988,35 @@ function outer() {
 
 **When to use:** When you need surgical control over exactly which functions get VM protection, especially nested functions that contain sensitive logic. Unlike `vmTargetFunctions` which only works with root-level named functions, comment mode lets you protect any function anywhere in your code.
 
+### `vmForceCompileDynamicCode`
+Type: `boolean` Default: `false`
+
+Controls what VM obfuscation does with a function that contains a direct `eval`, `new Function(...)`, or `Function(...)` call.
+
+By default, such a function (and every function defined inside it) is skipped from VM bytecoding and a `VMDynamicCodeSkipped` warning is reported on `result.getWarnings()`. This is because the runtime-built source may reference identifiers from the surrounding scope chain — identifiers that the obfuscator has renamed.
+
+When set to `true`, the function is bytecoded anyway and the `VMDynamicCodeSkipped` warning is no longer emitted.
+
+The separate `DynamicCodeRenameRisk` warning continues to fire regardless of this option, because the rename risk it describes is independent of the VM skip — turning this option on does not make the underlying pattern any safer.
+
+```javascript
+// Source code
+function loadConfig(src) {
+    return eval(src);
+}
+loadConfig('1 + 2');
+```
+
+```javascript
+// Options
+{
+    vmObfuscation: true,
+    vmForceCompileDynamicCode: true
+}
+```
+
+With the option off (default), `loadConfig` is left as plain JavaScript. With the option on, `loadConfig` is compiled to VM bytecode like any other function. Use this when you have audited the call site and know the runtime-built code does not depend on closure-renamed identifiers.
+
 ### `vmWrapTopLevelInitializers`
 Type: `boolean` Default: `false`
 
@@ -2065,6 +2114,44 @@ JavaScriptObfuscator.obfuscate(code, {
 window.__VM_KEY__ = 'mySecretKey123';
 ```
 
+### `vmAsyncExecutor`
+Type: `boolean` Default: `false`
+
+Enables the asynchronous VM executor, which lets [`vmBytecodeArrayEncodingKeyGetter`](#vmbytecodearrayencodingkeygetter) return a `Promise` (an **asynchronous** key getter) — so the decryption key can be fetched at runtime (network request, IndexedDB, etc.) instead of having to be available synchronously when the code loads.
+
+**Heavily recommended for fully async codebases.** In this mode only `async` functions are virtualized — a synchronous function can't be made async without turning its return value into a `Promise` and breaking its callers — so code that is `async` throughout gets the most coverage. It still works when the root is synchronous (e.g. a sync IIFE / UMD wrapper): the outermost `async` functions inside are protected, and the sync parts are left as-is.
+
+**What gets transformed:** every **outermost** `async` function, wherever it appears (including nested inside sync wrappers). The outermost async in each chain is the protected unit — everything inside it, sync and async, is compiled in. Synchronous functions and plain generators are left unobfuscated.
+```js
+function foo() {              // sync — left as-is
+    function bar() {}         // sync — left as-is
+
+    async function baz() {    // transformed
+        // any code here, including calls to other async or sync functions
+    }
+
+    async function bark() {   // transformed
+        // any code here, including calls to other async or sync functions
+    }
+}
+```
+
+**Skips and warnings.** Async generators are also left unobfuscated when an asynchronous key getter is active (an async generator must return its iterator synchronously and can't wait for the key). In the default `vmTargetFunctionsMode: 'root'` skips are silent (selection is automatic); in `comment` [mode](#vmtargetfunctionsmode) a warning is emitted through `ObfuscationResult.getWarnings()` whenever a function you explicitly marked can't be virtualized — it turned out synchronous, or it's an async generator under an async key getter.
+
+The asynchronous key getter additionally requires `vmBytecodeArrayEncoding` with a `vmBytecodeArrayEncodingKeyGetter`.
+
+**Usage example:**
+```ts
+JavaScriptObfuscator.obfuscate(code, {
+    vmObfuscation: true,
+    vmAsyncExecutor: true,
+    vmBytecodeArrayEncoding: true,
+    vmBytecodeArrayEncodingKey: 'mySecretKey123',
+    // the key getter may now return a Promise
+    vmBytecodeArrayEncodingKeyGetter: 'fetch("/vm-key").then((res) => res.text())'
+});
+```
+
 ### `vmJumpsEncoding`
 Type: `boolean` Default: `false`
 
@@ -2099,11 +2186,137 @@ Adds multi-layered tamper detection, anti-hooking, and anti-reverse-engineering
 
 Strongly recommended to use together with [`vmDebugProtection`](#vmDebugProtection), [`vmBytecodeArrayEncodingKey`](#vmbytecodeArrayEncodingKey), and [`vmBytecodeArrayEncodingKeyGetter`](#vmbytecodeArrayEncodingKeyGetter).
 
+### `vmDefenseHook`
+Type: `{ name: string, aliases?: object }` Default: `''`
+
+`vmDefenseHook` takes an object with two keys: **`name`** (required) and **`aliases`** (optional).
+
+`name` is a **global function your host page defines** that a VM defense (`vmDebugProtection` / `vmSelfDefending`) calls with a signal object when it detects a hostile signal — a debugger or inspector, a headless / automation browser, an AI-coding-agent process, a disallowed domain, and so on. Use it to report the event to your backend (e.g. `navigator.sendBeacon`). The hook is a **pure telemetry sink**: its return value is ignored, and a missing or throwing hook is a silent no-op that can never disable a defense. To change what a defense *does* on detection, use [`vmDefenseReaction`](#vmdefensereaction).
+
+`aliases` optionally renames the fields of that signal object — covered under *Renaming the signal fields* below.
+
+**The signal object.** The hook receives a single `signal`:
+
+- `source` — the specific detector that fired (see the table).
+- `category` — the group it reports under: `automation` (non-human browsers), `debugger` (a debugger/inspector is active), `sandbox` (instrumented/fake host), `domain` (domain-lock violation), `tamper` (built-ins patched at runtime), or `integrity` (the VM's own code was altered).
+- `score` / `threshold` — how strongly the detector fired and the value it had to reach; the hook fires only once `score >= threshold`. Most checks are all-or-nothing (a single decisive signal); `headless` sums several browser-shape signals, so its `score` is typically higher than its `threshold`.
+
+| `source` | detects                                                                          | `category` |
+|---|----------------------------------------------------------------------------------|---|
+| `integrity` | the obfuscated VM code itself has been modified                                  | `integrity` |
+| `node` | browser-targeted code running under Node.js                                      | `debugger` |
+| `debugger` | an attached or active debugger or inspector session, or a debug environment      | `debugger` |
+| `headless` | a headless browser is used to run the code                                       | `automation` |
+| `agent` | an AI coding-agent running the code                                              | `automation` |
+| `timing` | an execution pause suggesting a breakpoint or a stepping debugger                | `debugger` |
+| `sandbox` | the code runs in a sandbox or a faked host environment                           | `sandbox` |
+| `domain` | the page origin is not in the [`vmDomainLock`](#vmdomainlock) allow-list          | `domain` |
+| `nativeHook` | a native built-in function has been replaced or hooked                            | `tamper` |
+
+**Registering the hook.** Define it as a plain global **before** the obfuscated bundle loads — the VM runtime and its defenses run before your (protected) program, so many detections fire during startup:
+
+```js
+// in your page, before the obfuscated script:
+window.__vmDetection = function (signal) { navigator.sendBeacon('/vm-defense', JSON.stringify(signal)); };
+```
+```js
+// obfuscation option:
+vmDefenseHook: { name: '__vmDetection' }
+```
+
+> A hook defined *inside* the obfuscated source is registered too late to catch startup-time detections, and if it gets VM-compiled it can't be reached until your program runs. It's kept safe either way (a missing hook no-ops, and a re-entrancy guard prevents any runaway), but for complete coverage register it up front. To still protect your reporting logic, keep the registered hook a one-line buffer (`(window.__vmDet = window.__vmDet || []).push(signal)`) and read/send that buffer from your obfuscated code.
+
+**Renaming the signal fields (`aliases`).** The default `source`/`category` values are descriptive names, so anyone instrumenting the callback (or reading the output) can recognise the protection and which detector fired. `aliases` renames signal fields to opaque tokens of your choice, applied inside the VM *before* the signal is emitted, so those names never appear in the output or reach the callback. Your app knows its own mapping and forwards the tokens to your backend.
+
+Aliases are per field, keeping key and value renames separate: each field takes a `key` (the property name the callback receives); the string name-fields `source` and `category` also take a `values` map, while `score`/`threshold` are numbers and take only a `key`. The names you can map (anything else is rejected at build time):
+
+- **field keys** — `source`, `category`, `score`, `threshold`
+- **`source` values** — `headless`, `agent`, `node`, `debugger`, `timing`, `sandbox`, `domain`, `nativeHook`, `integrity`
+- **`category` values** — `automation`, `debugger`, `sandbox`, `domain`, `tamper`, `integrity`
+
+```js
+vmDefenseHook: {
+    name: '__vmDetection',
+    aliases: {
+        source:    { key: 'a8Qm', values: { headless: 'xP4m9Q' } },
+        category:  { key: 'p3Tx', values: { automation: 'bQ7s1M' } },
+        score:     { key: 's1' },
+        threshold: { key: 't1' }
+    }
+    // the callback now receives e.g. { a8Qm: 'xP4m9Q', p3Tx: 'bQ7s1M', s1: <score>, t1: <threshold> }
+}
+```
+
+This is fingerprint avoidance, not secrecy — the mapping can still be inferred by repeated testing — so its only benefit is not exposing stable, self-explanatory names. Unset entries keep their default names.
+
+> A bare string (`vmDefenseHook: '__vmDetection'`) is accepted as shorthand for `{ name: '__vmDetection' }` but is **deprecated** — prefer the object form.
+
+### `vmDefenseReaction`
+Type: `object` Default: `{ automation: 'break', debugger: 'decoy', sandbox: 'decoy', domain: 'break', tamper: 'break', integrity: 'break' }`
+
+Configures how each detection category reacts. It does **not** enable anything — the defenses themselves are turned on by [`vmSelfDefending`](#vmselfdefending), [`vmDebugProtection`](#vmdebugprotection), and [`vmDomainLock`](#vmdomainlock); this option only selects *how* an enabled defense reacts. The **category is the unit of control** — every detector in a category enacts that category's reaction.
+
+Each **category** groups the detectors that watch for one kind of hostile condition. A category only reacts when the option that emits its detectors is enabled:
+
+| Category | Enabled by | Reacts when |
+|---|---|---|
+| `automation` | `vmSelfDefending` or `vmDebugProtection` | The code is being driven by software instead of a person: a headless or automated browser, a scraping / testing framework, or an AI coding-agent stepping the page. |
+| `debugger` | `vmDebugProtection` or `vmSelfDefending` | Someone has a debugger or the browser's developer-tools inspector open and is stepping through the running code to understand it. |
+| `sandbox` | `vmDebugProtection` | The code is not running in a real browser at all — it has been lifted into an emulated or scripted JavaScript environment to be executed and studied offline. |
+| `domain` | `vmDomainLock` | The code is running on a site you did not authorize: a host not in your [`vmDomainLock`](#vmdomainlock) allow-list (for example, your bundle copied onto someone else's domain). |
+| `tamper` | `vmSelfDefending` | The JavaScript environment around the VM has been modified to watch or hijack it, such as native browser built-ins swapped out for instrumented versions. |
+| `integrity` | `vmSelfDefending` | The protected bundle's own code has been edited or patched since you generated it. |
+
+Every category maps to one or more of [`vmSelfDefending`](#vmselfdefending), [`vmDebugProtection`](#vmdebugprotection), and [`vmDomainLock`](#vmdomainlock); there is no category outside those three options, and a reaction set for a category whose option is off simply has no effect.
+
+Keys are these six category names, or `default` (a fallback for unspecified categories). Values are:
+
+- `break` — break immediately
+- `decoy` — keep running on poisoned state, silently producing wrong results
+- `none` — do nothing locally (telemetry only)
+
+The per-category defaults are shown above; a category you don't set (or set to its default value) uses that default. `default` reaches **every** category, including the correct-by-construction ones (`integrity`, `tamper`), so `{ default: 'none' }` is a genuinely non-breaking, telemetry-only build:
+
+```js
+vmDefenseReaction: { default: 'none' }              // never break — pair with vmDefenseHook
+vmDefenseReaction: { automation: 'none', domain: 'break' }   // tolerate automation FPs, still break on a bad domain
+```
+
+### `browserEnvironment`
+Type: `object` Default: `{}`
+
+Declares facts about the environment your production build is served in, so the protected code can bind itself to them. Only takes effect together with [`vmSelfDefending`](#vmselfdefending), and only for `browser` / `browser-no-eval` / `service-worker` targets — it is rejected for `node`, `userscript`, and `bytenode`.
+
+Currently one field:
+
+- **`transport`** — the scheme your production serves the bundle over: `'http'` or `'https'`. With `'https'`, the build ties its integrity to being served over HTTPS, so a copy an analyst lifts and serves over plain HTTP (a common local reverse-engineering setup) will not run correctly. `'http'` or an unset field adds no binding.
+
+```js
+browserEnvironment: { transport: 'https' }
+```
+
+> :warning: A build declared `transport: 'https'` runs correctly **only** where it is actually served over `https:`. Every other scheme corrupts it, so declare it only when every context that loads your production build is HTTPS. That excludes: plain `http://` (including `http://localhost` in development), `file://` (Electron / Cordova / packaged apps), and `blob:` / `about:` embeddings (a bundle running inside an `about:blank` or `srcdoc` iframe). A client-side HTTP→HTTPS redirect still renders the HTTP page first, so the bundle must not run before the redirect completes.
+
 ### `vmStatefulOpcodes`
 Type: `boolean` Default: `false`
 
 Makes opcode meanings depend on position in the bytecode. Each position has a different opcode-to-handler mapping derived from a seed, so the same opcode number performs different operations at different positions.
 
+### `vmCallContextOpcodes`
+Type: `boolean` Default: `false`
+
+Makes a protected function depend on where it's called from, so it can't be lifted out of the code and run or analyzed on its own — it only behaves correctly when invoked through its real call sites in the program. This option affects runtime performance.
+
+Currently only the following constructions are supported:
+
+- function declarations (`function f() {}`);
+- function expressions and arrow functions assigned to a variable (`const f = () => {}`);
+- instance private methods (`this.#m()`).
+
+In every case the function must always be reached through a direct call (`f()`, `this.#m()`). If it is stored in another variable, passed as an argument, or otherwise used as a value, it is left unprotected. Async functions are supported; generators are not.
+
+This option is experimental and may break your code, so test the output thoroughly before using it.
+
 ### `vmStackEncoding`
 Type: `boolean` Default: `false`
 
@@ -2119,6 +2332,17 @@ Uses a single VM executor instead of dual executors (sync + generator). Reduces
 - `false` (default): dual executors — optimal performance, larger output
 - `true`: single executor — smaller output, slightly slower
 
+### `vmRegisterBased`
+Type: `boolean` Default: `false`
+
+Switches the VM from the default stack-based bytecode to a register-based execution model, which improves VM runtime performance in some cases by ~15-20%, but slightly increases obfuscated code size.
+
+Because it emits a structurally different bytecode and executor, it also gives the VM a more unique fingerprint than the default stack-based one — use it when you want to vary the VM's shape so it is less recognizable to generic analysis.
+
+Under the hood this isn't a native register-based compiler — the regular stack-based compiler still generates the bytecode, which a separate transformation stage then rewrites into register-based form.
+
+This option is experimental - test that your code runs well when `vmRegisterBased` is enabled.
+
 ### `vmStringArrayBytecodeOnly`
 Type: `boolean` Default: `false`
 
@@ -2131,6 +2355,25 @@ When enabled, the string array will **only** extract strings from bytecode data
 - `stringArrayThreshold` still controls what percentage of those bytecode strings are extracted
 
 
+### `vmDomainLock`
+Type: `string[]` Default: `[]`
+
+##### :warning: This option does not work with `target: 'node'`, `target: 'service-worker'` or `target: 'bytenode'`
+
+Restricts the obfuscated code to specific domains and/or sub-domains, and is much harder to locate and strip than `domainLock`.
+
+If the source code isn't run on the domains specified by this option, the browser will be redirected to the URL passed to [`vmDomainLockRedirectUrl`](#vmdomainlockredirecturl), and further protected calls will return incorrect results even if the redirect is suppressed.
+
+##### Multiple domains and sub-domains
+It's possible to lock your code to more than one domain or sub-domain. For instance, to lock it so the code only runs on **www.example.com** add `www.example.com`. To make it work on the root domain including any sub-domains (`example.com`, `sub.example.com`), use `.example.com`.
+
+### `vmDomainLockRedirectUrl`
+Type: `string` Default: `about:blank`
+
+##### :warning: This option does not work with `target: 'node'`, `target: 'service-worker'` or `target: 'bytenode'`
+
+Allows the browser to be redirected to a passed URL if the source code isn't run on the domains specified by [`vmDomainLock`](#vmdomainlock).
+
 ### `strictMode`
 Type: `boolean | null` Default: `null`
 
@@ -2197,6 +2440,15 @@ JavaScriptObfuscator.obfuscate(html, {
 // output: HTML with only the marked script obfuscated
 ```
 
+### `randomIdentifiersPrefix`
+Type: `boolean` Default: `false`
+
+Appends a seeded random prefix (6 alphanumeric characters) to all global identifiers. Use this option to avoid collisions between separately obfuscated bundles that are loaded into the same global scope — it removes the need to pick a unique `identifiersPrefix` per bundle manually.
+
+- The random value is derived from the `seed` option and the source code hash, so reproducible builds with the same seed produce the same prefix.
+- When combined with `identifiersPrefix`, the random characters are appended to the user-provided prefix (e.g. `myApp` + random `aBc123` → `myAppaBc123`).
+- When combined with `vmObfuscation`, the random value replaces the default `vm` prefix — randomness already guarantees uniqueness.
+
 ## Frequently Asked Questions
 
 ### What javascript versions are supported?