TypeScript-first JavaScript code protection for the Toil stack.

_{Typed ESM/CommonJS package with randomized control flow, literal protection, object packing, BigInt-backed VM bytecode, and hash-mesh bytecode unlock for browser and Node bundles.}

---

ToilDefender is Dacely's maintained TypeScript-authored JavaScript protection layer for the Toil technology stack. It started from the original defendjs project, but this fork is now maintained as its own typed package: @dacely/toildefender.

The goal is not to make client-side JavaScript impossible to analyze. That is not a real promise. The goal is to raise reverse-engineering cost by removing source-level structure, splitting logic across generated helpers, packing constants, and optionally compiling selected functions into randomized numeric VM programs.

npm install @dacely/toildefender

import { protect, type ToilDefenderOptions } from "@dacely/toildefender";

const source = `
function licenseGate(input) {
    return input.length > 8 && input.charCodeAt(0) === 84;
}

globalThis.__result = licenseGate("ToilDefender");
`;

const options: ToilDefenderOptions = {
    code: source,
    modulesCode: {},
    logLevel: "error",
    features: {
        dead_code: true,
        scope: true,
        control_flow: true,
        identifiers: true,
        numeric_vm: true,
        object_packing: true,
        literals: true,
        mangle: true,
        compress: true
    },
    protections: {
        virtualMachine: {
            enabled: true,
            mode: "aggressive",
            bigintBytecode: true,
            randomizedOpcodes: true,
            encodeConstants: true,
            perFunctionDialect: true,
            virtualize: "heuristic"
        },
        hashMesh: {
            enabled: true,
            mode: "aggressive",
            unlock: "per-function",
            deriveDialectFromMesh: true,
            bindToVmState: true,
            encodeChaff: true,
            chaffRatio: 0.55
        }
    }
};

const result = protect(options);

console.log(result.code);

Package Format

The public package is authored in TypeScript and built with Vite 8. Published artifacts are emitted into build/ as dual module targets:

Consumer	Entry
ESM	import toildefender, { protect, do, features } from "@dacely/toildefender"
CommonJS	Legacy compatibility through the package exports.require entry.
Types	import type { ToilDefenderOptions, ToilDefenderResult } from "@dacely/toildefender"
CLI	toildefender --help

protect(options) and do(options) are the same public function. The default export keeps the classic object shape: { protect, do, features }.

The package requires Node >=24.11.0. Type declarations are generated from the source and shipped through the package exports map, so TypeScript consumers do not need @types packages.

What It Does

Protection	Purpose
control_flow	Rewrites structured control flow into dispatcher-style execution.
scope	Flattens function/scope structure into generated runtime frames.
identifiers	Renames and rewrites identifiers, object references, and property access.
object_packing	Packs object literal keys into numeric schemas instead of readable key/value arrays.
literals	Encodes strings and numeric constants.
dead_code	Inserts unreachable or low-value code paths to add noise.
mangle	Shortens generated identifiers.
compress	Emits compact output.
numeric_vm	Virtualizes supported functions into BigInt-packed bytecode.

Virtual Machine Protection

Transform your JavaScript into randomized virtual-machine bytecode for maximum resistance against reverse engineering.

ToilDefender compiles protected functions into a private instruction set, packs the bytecode into encrypted BigInt streams, and executes it through a generated runtime VM. Instead of exposing readable JavaScript logic, your code becomes numeric program data consumed by a randomized virtual machine.

The compiler also fuses selected hot stack patterns into semantic superinstructions, so common operation boundaries such as constant-key property reads are not always emitted as separate primitive VM opcodes. Constants are wrapped in access-bound cells, so encoded strings and references are decoded lazily when bytecode reads them instead of during VM call setup.

Original logic disappears from the output bundle. Attackers no longer reverse plain JavaScript; they must recover the VM, decode the bytecode format, reconstruct the instruction set, and emulate the protected program.

import { protect, type ToilDefenderOptions } from "@dacely/toildefender";

const source = `
function validateLicense(input) {
    const total = input.length * 7;
    return input.charCodeAt(0) === 86 ? total + 13 : total - 5;
}

globalThis.__result = validateLicense("VM-Protected");
`;

const options: ToilDefenderOptions = {
    code: source,
    modulesCode: {},
    features: {
        numeric_vm: true
    },
    protections: {
        virtualMachine: {
            enabled: true,
            mode: "aggressive",
            bigintBytecode: true,
            randomizedOpcodes: true,
            encodeConstants: true,
            perFunctionDialect: true,
            virtualize: "marked",
            minFunctionSize: 1,
            maxFunctionSize: 120,
            seed: "build-seed"
        }
    }
};

const result = protect(options);

Selection modes:

virtualize	Meaning
marked	Virtualize functions marked by supported annotations or compiler selection.
all-supported	Virtualize every function that fits the supported syntax subset.
heuristic	Virtualize functions selected by size and compiler suitability.

Supported VM syntax currently targets practical protection work: literals, locals, arguments, return, assignment, arithmetic, comparisons, logical expressions, if / else, while, calls, member reads, arrays, and object literals. Unsupported syntax remains native or is skipped by selection.

All-Modes Output Demo

Input:

const demoSource = `
function licenseGate(input) {
    const total = input.length * 7;
    return input.charCodeAt(0) === 86
        ? { ok: true, total: total + 13 }
        : { ok: false, total: total - 5 };
}

globalThis.__result = licenseGate("ToilDefender");
`;

The demo artifact is generated with every major protection enabled and compression disabled so the runtime stays readable:

import { protect, type ToilDefenderOptions } from "@dacely/toildefender";

const demoOptions: ToilDefenderOptions = {
    code: demoSource,
    modulesCode: {},
    features: {
        dead_code: true,
        scope: true,
        control_flow: true,
        identifiers: true,
        numeric_vm: true,
        object_packing: true,
        literals: true,
        mangle: true,
        compress: false
    },
    protections: {
        virtualMachine: {
            enabled: true,
            mode: "aggressive",
            bigintBytecode: true,
            randomizedOpcodes: true,
            encodeConstants: true,
            perFunctionDialect: true,
            virtualize: "all-supported",
            seed: "readme-all-modes-demo"
        },
        hashMesh: {
            enabled: true,
            mode: "aggressive",
            unlock: "per-function",
            deriveDialectFromMesh: true,
            bindToVmState: true,
            encodeChaff: true,
            chaffRatio: 0.55
        }
    }
};

const demoResult = protect(demoOptions);

The complete beautified generated output is committed at docs/all-modes-output.demo.js. It is a real 1019-line artifact from the current generator and executes to:

Output excerpt:

(function () {
  function a(f, k) {
    var b = new Array(109);
    ;
    var c = arguments;
    var i;
    while (true) try {
      switch (f) {
        case 24210:
          b[11] = c[11];
          b[12] = c[10];
          b[13] = c[9];
          b[14] = c[8];
          b[15] = c[7];
          b[16] = c[6];
          b[17] = c[5];
          b[18] = c[4];
          b[19] = c[3];
          b[20] = c[2];
          b[21] = e(a, 16503, b, c[1]);
          b[22] = e(a, 16827, b, c[1]);
          b[23] = e(a, 28881, b, c[1]);
          b[24] = e(a, 27718, b, c[1]);
          b[25] = e(a, 26046, b, c[1]);
          b[26] = e(a, 11984, b, c[1]);
          b[27] = e(a, 10989, b, c[1]);
          b[28] = e(a, 10700, b, c[1]);
          b[29] = e(a, 18606, b, c[1]);
          b[30] = e(a, 22347, b, c[1]);
          b[31] = e(a, 28683, b, c[1]);
          b[32] = e(a, 11069, b, c[1]);
          b[33] = e(a, 8443, b, c[1]);
          b[34] = e(a, 27840, b, c[1]);
          b[35] = e(a, 21656, b, c[1]);
          b[36] = BigInt(b[19]);
          b[37] = [1n];
          b[38] = c[1][10][1];
          b[39] = c[1][10][1];
          if (b[11]) {
            b[38] = c[1][4](b[11], b[19], b[18], b[17], b[16], b[12]);
            b[39] = b[11][c[1][10][24]] >>> c[1][10][1];
          }
          b[40] = c[1][10][1];
          b[41] = b[17] >>> c[1][10][1];
          while (b[40] < b[18]) {
            b[42] = b[33](b[40]);
            b[41] = b[34](b[41], b[42], b[40]);
            b[40] += c[1][10][5];
          }
          if (b[41] >>> c[1][10][1] !== b[16] >>> c[1][10][1]) throw new Error(c[1][10][29]);
          b[43] = c[1][10][1];
          b[44] = b[17] >>> c[1][10][1];
          b[45] = b[17] & c[1][10][5];
          b[46] = b[45] ? c[1][10][30] : [];
          b[47] = b[45] ? c[1][10][30] : [];
          b[48] = b[45] ? g([
            /* encoded layout keys */
          ], [
            [],
            Object[c[1][10][36]](c[1][10][30])
          ]) : c[1][10][30];

          /* 900+ more generated lines:
             dispatcher cases, encoded literals, streaming VM token reads,
             lazy constant cells, seed-selected stack/local storage, BigInt program blobs,
             semantic superinstructions, randomized opcode tables,
             and Hash-Mesh unwrap */

        case 27718:
          if (c[1][50] < c[2][10][1] || c[1][50] >= c[1][18]) throw new Error(c[2][10][46]);
          b[1] = c[1][31](c[1][50]);
          c[1][50] += c[2][10][5];
          return b[1];
        case 30063:
          b[1] = '';
          b[1] += d(86, 101, 105);
          b[1] += d(108, 109);
          b[1] += d(97, 114, 107);
          return b[1];
      }
    } catch (a) {
      i = null;
      switch (f) {
        default:
          throw a;
      }
    }
  }
  a(20498, {});
})();

{ "ok": true, "total": 69 }

That output contains the full stacked mess: flattened dispatcher runtime, identifier rewriting, packed literals, object packing, VM bytecode execution, BigInt program blobs, randomized opcode tables, and Hash-Mesh unlock material.

Hash-Mesh Unlock

Hash-Mesh Unlock derives VM bytecode keys from runtime integrity data. If protected code, constants, VM helpers, or execution state are modified, the next bytecode chunk decrypts incorrectly instead of exposing runnable logic.

This turns integrity checks into decryption requirements instead of patchable boolean branches.

import { protect, type ToilDefenderOptions } from "@dacely/toildefender";

const source = `
function licenseGate(input) {
    const total = input.length * 7;
    return input.charCodeAt(0) === 86 ? total + 13 : total - 5;
}

globalThis.__result = licenseGate("Hash-Mesh");
`;

const options: ToilDefenderOptions = {
    code: source,
    modulesCode: {},
    features: {
        numeric_vm: true
    },
    protections: {
        virtualMachine: {
            enabled: true,
            mode: "aggressive",
            virtualize: "all-supported"
        },
        hashMesh: {
            enabled: true,
            mode: "aggressive",
            unlock: "per-function",
            deriveDialectFromMesh: true,
            bindToVmState: true,
            encodeChaff: true,
            chaffRatio: 0.55,
            serverBound: false
        }
    }
};

const result = protect(options);

Hash-Mesh is an obfuscation and tamper-resistance layer. It is not a cryptographic secrecy guarantee for code running on an attacker-controlled machine.

CLI

Install globally or run through npx:

npm install -g @dacely/toildefender
toildefender --help

toildefender \
  --input ./src \
  --output ./dist-protected \
  --features scope,control_flow,identifiers,literals,mangle,compress

For multi-entry projects, declare entry files in package.json:

{
    "toildefender": {
        "mainFiles": ["index.js", "worker.js"]
    }
}

The old defendjs.mainFiles field is still read as a compatibility fallback, but new projects should use toildefender.

API And Types

ESM and TypeScript:

import toildefender, {
    protect,
    type FeatureConfig,
    type ToilDefenderOptions,
    type ToilDefenderResult
} from "@dacely/toildefender";

const features: Partial<FeatureConfig> = {
    dead_code: false,
    scope: true,
    control_flow: true,
    identifiers: true,
    numeric_vm: false,
    object_packing: true,
    literals: true,
    mangle: true,
    compress: true
};

const options: ToilDefenderOptions = {
    code: "function add(a,b){ return a + b } globalThis.x = add(1,2)",
    modulesCode: {},
    logLevel: "warn",
    features
};

const result: ToilDefenderResult = protect(options);

console.log(result.code);
console.log(toildefender.features.control_flow.default);

Named exports are available in ESM as protect, do, and features. The default export keeps the compatibility object with the same members. CommonJS callers remain supported through the package exports map, but new code should use the typed ESM API.

Exported TypeScript types:

Type	Purpose
ToilDefenderOptions	Full input configuration for protect / do.
ToilDefenderResult	Protected output object with code and optional map.
FeatureName, FeatureConfig, FeatureDescriptions	Feature switch and metadata types.
ProtectionOptions, NumericVmOptions, HashMeshOptions	VM and Hash-Mesh configuration.
ControlFlowOptions, ScopeOptions	Seed and ratio controls for those passes.
LogLevel, LogAdapter	Typed logging integration.

Main options:

Option	Meaning
code	Entry source code.
modulesCode	Map of dependency filename to source code.
features	Feature switches for the classic pipeline.
forceFeatures	Compatibility/testing override for feature selection after option merging; normal callers should use features.
babel	Defaults to false; set to true only when you want the optional Babel downlevel transform before protection.
babelPreserveAsync	Defaults to true; when babel: true, keeps async/generator syntax native so async-aware flattening can avoid Babel regenerator helper bloat. Set to false for legacy async lowering.
babelTarget	Babel target string used only when optional Babel lowering is enabled.
protections.virtualMachine	User-facing VM bytecode backend configuration.
protections.hashMesh	User-facing hash-mesh unlock configuration.
numericVm	Lower-level numeric VM configuration retained for internal callers.
controlFlow	Control-flow pass seed and ratio.
scope	Scope-flattening pass seed and ratio.
preprocessorVariables	Compile-time preprocessor constants.
runtimeHelpers	Controls whether generated runtime helpers are emitted.
simplify	Enables the post-generation simplify pass.
logLevel	error, warn, info, debug, or log.
logAdapter	Receives typed log callbacks when custom logging is needed.

The default path parses modern syntax directly and normalizes the constructs that older obfuscation passes cannot consume yet. The native AST path supports plain classes as native islands, class fields, private fields, arrows, for-of loops, async/generator functions, optional chaining, nullish coalescing, object rest/spread, and spread calls.

When babel: true and babelPreserveAsync is enabled, optional Babel packages installed by the caller can still downlevel syntax for legacy browser targets while leaving async and generator functions for ToilDefender's async/generator dispatchers. This avoids the large regenerator helper path for modern browser and Node bundles.

Toil Integration

ToilDefender is intended to sit behind Toil build tooling. Framework packages can call the API directly, then run normal syntax validation and browser tests against the protected artifact.

Recommended Toil stack pattern:

source bundle
-> Vite / framework build
-> ToilDefender pre-obfuscation and protection
-> syntax validation
-> browser smoke tests
-> publish/deploy artifact

For security-sensitive browser code, pair this with server-side validation. Client-side protection raises cost; it does not replace server authority.

Security Boundary

ToilDefender is code protection, not magic.

It helps against:

• quick static reading of shipped JavaScript
• simple string/signature extraction
• source-level control-flow recovery
• direct patching of obvious boolean integrity checks
• automated diffing across builds when seeds and dialects rotate

It does not guarantee:

• secrets stay secret in client-side code
• runtime tracing is impossible
• browser-controlled attackers cannot eventually emulate behavior
• server authorization can be moved into the browser

Put real authorization and durable decisions on the server.

Development

npm run build
npm run typecheck
npm run lint
npm test
npm run test:firefox
npm run pack:dry

Source lives under src/ as TypeScript. npm run build runs the Vite 8 library build for ESM and CommonJS, then emits declaration files with tsconfig.build.json.

Generated package artifacts live under build/ and are intentionally ignored in git. The root toildefender.js and defendjs.js shims load the built CLI and library output for package compatibility.

The regression suite covers modern syntax handling, object packing, VM bytecode execution, Hash-Mesh unlock, and tamper failure behavior.

Credit

ToilDefender began as a fork of defendjs, originally created by Alexander Horn and released under the GNU Affero General Public License v3.0.

Dacely maintains this fork for the Toil stack and has added the modern parser surface, VM bytecode backend, Hash-Mesh unlock layer, object key packing, branding cleanup, and current regression coverage.

See NOTICE.md for attribution details.

License

AGPL-3.0. See LICENSE.