Obscura.js

A JavaScript code protection library inspired by the obfuscation and anti-debugging techniques used in Google reCAPTCHA.

Features

| Category | Pass | Description | | ----------- | ----------------------- | ------------------------------------------------------------------------ | | Obfuscation | sequenceExpression | Flatten if blocks into comma-sequence expressions | | Obfuscation | mba | Expand arithmetic into Mixed Boolean Arithmetic (MBA) expressions | | Obfuscation | functionTable | Move function declarations into an indirect table, call by index | | Obfuscation | stringPool | Encrypt string literals and template literal quasis into an LCG-XOR pool | | Obfuscation | controlFlowFlattening | Transform function bodies into flat state machines | | Obfuscation | deadCode | Inject unreachable code blocks | | Anti-debug | nativeBinding | Pre-bind native methods to defend against prototype pollution | | Anti-debug | integrityTag | Attach Symbol-based integrity tags to detect object cloning/replace |

Input Format Support

Obscura.js auto-detects the module format of the input file (sourceType: "unambiguous") and handles all three variants:

| Format | Example | Notes | | ---------------- | ------------------------------ | ----------------------------------------------------------------- | | CommonJS (CJS) | require() / module.exports | require() paths are never encrypted to preserve static analysis | | ES Modules (ESM) | import / export | Module specifier strings are never encrypted | | JSX | <Component prop="value" /> | Attribute strings are wrapped in {} after encryption |

Per-pass ESM / CJS behaviour

Passes fall into two categories: format-aware (contain explicit logic for module syntax) and format-agnostic (operate purely on expressions/statements, no module knowledge required).

Format-aware passes

functionTable — avoids removing functions that are reachable from outside the module.

| Pattern | Example | Behaviour | | ------------------------------- | ------------------------------- | ------------------------------------------------------------------ | | ESM named export | export { foo } | foo is kept as a top-level declaration; not moved into the table | | ESM default export (identifier) | export default foo | same | | CJS module.exports | module.exports = foo | same | | CJS module.exports.x | module.exports.add = add | same | | CJS exports.x | exports.add = add | same | | CJS object shorthand | module.exports = { add, mul } | all referenced names are preserved |

stringPool — selectively skips strings whose values must be preserved for the module system or runtime.

| Pattern | Example | Behaviour | | -------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------- | | ESM import path | import x from "./mod" | skipped — bundlers need the literal path | | ESM re-export path | export { x } from "./mod" / export * from "./mod" | skipped | | Dynamic import path | import('./mod') | skipped — runtime module loader needs the literal | | CJS require path | require("./mod") | skipped | | CJS require.resolve path | require.resolve("./util") | skipped | | ES2022 string binding name | import { "foo" as bar } / export { x as "name" } | skipped — spec-mandated string syntax | | Tagged template | html`<b>${x}</b>` | skipped — tag receives a TemplateStringsArray, not a plain string | | All other strings | "hello", `hi ${name}`, { 'key': v } | encrypted |

Format-agnostic passes

These passes operate on expressions and statements only. They produce valid output for both CJS and ESM input without any module-specific logic.

| Pass | What it touches | | ----------------------- | --------------------------------------------------- | | sequenceExpression | if statement bodies | | mba | Binary arithmetic expressions (+, -, \|, ^) | | controlFlowFlattening | Function bodies | | deadCode | Top-level statement boundaries | | nativeBinding | Prepends const bindings for native methods | | integrityTag | Array and object literals |

What stringPool encrypts

| Syntax | Example | Behaviour | | ------------------------- | ----------------------- | ----------------------------------------------------------------------------- | | String literal | "hello" | Replaced with a pool decryption call | | Template literal | `hello ${x}` | Static quasis encrypted; expressions kept as-is; emitted as + concatenation | | Object / class string key | { 'key': v } | Key flipped to computed syntax { [pool()]: v } | | JSX attribute value | <div className="foo"> | Wrapped in {pool()} expression container | | export default "…" | export default 'msg' | Encrypted normally |

The following strings are never encrypted to avoid breaking the module system:

• import … from "path"
• require("path") / require.resolve("path")
• export { x } from "path"
• export * from "path"
• ES2022 string binding names — import { "name" as x }, export { x as "name" }
• Tagged template literals — html`…` (the tag function receives a TemplateStringsArray)

Installation

npm install obscura-js

Quick Start

CLI

# Protect a file (output: app.obscura.js)
npx obscura-js protect app.js

# Specify output path
npx obscura-js protect app.js -o app.protected.js

# Minify output
npx obscura-js protect app.js --minify

# Preserve original comments (stripped by default)
npx obscura-js protect app.js --keep-comments

API

import { protect } from "obscura-js";
import { readFileSync } from "fs";

const source = readFileSync("app.js", "utf-8");

const { code, appliedPasses } = protect(source);
// All 8 passes are enabled by default

console.log(appliedPasses);
// ['sequenceExpression', 'mba', 'functionTable', 'stringPool',
//  'controlFlowFlattening', 'deadCode', 'nativeBinding', 'integrityTag']

API Reference

protect(source, options?)

| Parameter | Type | Description | | --------- | ---------------- | --------------------------------- | | source | string | JavaScript source code to protect | | options | ObscuraOptions | Optional configuration |

Returns ProtectResult:

interface ProtectResult {
  code: string; // Protected source code
  appliedPasses: string[]; // Names of passes that were applied
}

ObscuraOptions

interface ObscuraOptions {
  obfuscation?: {
    sequenceExpression?: { probability?: number } | false;
    mba?: { rounds?: number } | false;
    functionTable?: { minFunctions?: number } | false;
    stringPool?: { seed?: number } | false;
    controlFlowFlattening?: {} | false;
    deadCode?: { targetLines?: number } | false;
  };
  antiDebug?: {
    nativeBinding?: { methods?: string[] } | false;
    integrityTag?: { tagDescription?: string } | false;
  };
  minify?: boolean; // Default: false
  stripComments?: boolean; // Default: true
}

Disable a specific pass by passing false:

protect(source, {
  obfuscation: { deadCode: false, mba: false },
});

Custom options example:

protect(source, {
  obfuscation: {
    mba: { rounds: 2 },
    stringPool: { seed: 1234 },
    deadCode: { targetLines: 100 },
  },
  antiDebug: {
    nativeBinding: { methods: ["Math.floor", "Object.defineProperty"] },
    integrityTag: { tagDescription: "myapp" },
  },
  minify: true,
  stripComments: false, // keep original comments
});

CLI Reference

obscura-js protect <input> [options]

| Option | Description | | --------------------- | ------------------------------------------------------ | | -o, --output <file> | Output file path (default: <input>.obscura.js) | | --no-seq | Disable sequenceExpression pass | | --no-mba | Disable mba pass | | --no-ft | Disable functionTable pass | | --no-sp | Disable stringPool pass | | --no-cff | Disable controlFlowFlattening pass | | --no-dead | Disable deadCode pass | | --no-native | Disable nativeBinding pass | | --no-tag | Disable integrityTag pass | | --sp-seed <number> | XOR seed for the string pool cipher | | --minify | Compact output (remove whitespace, shorten literals) | | --keep-comments | Preserve original source comments (default: strip all) |

Requirements

• Node.js ≥ 18

License

MIT