REstringer

All modules in REstringer must follow the match/transform pattern to separate concerns and ensure predictable orchestration. This pattern consists of three parts:

1. Match function: moduleNameMatch(arb, candidateFilter = () => true) identifies target nodes within the Abstract Representation (arb).
2. Transform function: moduleNameTransform(arb, node) modifies the matched nodes. Crucially, this function must explicitly return the arb object.
3. Main function: Orchestrates the process by calling the match function, iterating through matches, and capturing the returned arb from each transformation.

Key Requirement: The main function must use arb = moduleNameTransform(arb, matches[i]) to capture the returned state.

// Match function - identifies target nodes
export function moduleNameMatch(arb, candidateFilter = () => true) {
  const matches = [];
  const candidates = arb.ast[0].typeMap.TargetNodeType
                        .concat(arb.ast[0].typeMap.AnotherTargetNodeType);
  
  for (let i = 0; i < candidates.length; i++) {
    const node = candidates[i];
    if (matchesCriteria(node) && candidateFilter(node)) {
      matches.push(node);
    }
  }
  return matches;
}

// Transform function - modifies matched nodes
export function moduleNameTransform(arb, node) {
  // Apply transformations
  performTransformation(node);
  return arb; // Must explicitly return arb
}

// Main function - orchestrates match and transform
export default function moduleName(arb, candidateFilter = () => true) {
  let currentArb = moduleNameMatch(arb, candidateFilter);
  
  for (let i = 0; i < currentArb.length; i++) {
    arb = moduleNameTransform(arb, currentArb[i]); // Capture returned arb
  }
  return arb;
}

Processors do not use a default export function. Instead, they must export preprocessors and postprocessors arrays containing transformation functions. This allows the engine to run multiple stages of preparation or cleanup.

While modules may internally separate logic into match and transform functions for organization, the processor itself can be a single function or a complex structure. The core requirement is the exported arrays.

// Main processor logic
function myProcessorLogic(arb, candidateFilter = () => true) {
  const candidates = arb.ast[0].typeMap.TargetNodeType
                        .concat(arb.ast[0].typeMap.AnotherTargetNodeType);
  
  for (let i = 0; i < candidates.length; i++) {
    const node = candidates[i];
    if (matchesCriteria(node) && candidateFilter(node)) {
      // Apply transformation directly
      performTransformation(node);
    }
  }
  return arb;
}

// Processors MUST export arrays of functions
export const preprocessors = [myProcessorLogic];
export const postprocessors = [];

You can intercept and replace built-in methods by accessing the unsafeMethods array on the REstringer instance. This is useful for adding limits (like execution counts) or custom logic to existing deobfuscators.

import fs from 'node:fs';
import {REstringer} from 'restringer';

const code = fs.readFileSync('obfuscated.js', 'utf-8');
const restringer = new REstringer(code);

// Find and replace a specific method
const targetMethod = restringer.unsafeMethods.find(m => 
  m.name === 'resolveLocalCalls'
);

if (targetMethod) {
  let processedCount = 0;
  const maxProcessing = 5;
  
  // Custom implementation with limits
  const customMethod = function limitedResolveLocalCalls(arb) {
    return targetMethod(arb, () => processedCount++ < maxProcessing);
  };
  
  // Replace the method in the array
  const index = restringer.unsafeMethods.indexOf(targetMethod);
  restringer.unsafeMethods[index] = customMethod;
}

restringer.deobfuscate();

const targetMethod = restringer.unsafeMethods.find(m => m.name === 'resolveLocalCalls');
if (targetMethod) {
  const index = restringer.unsafeMethods.indexOf(targetMethod);
  restringer.unsafeMethods[index] = customMethod;
}
restringer.deobfuscate();

REstringer requires high-performance code. Follow these optimization guidelines:

Loop Optimization

• Prefer traditional for (let i = 0; i < length; i++) loops over for..of or for..in.
• Use i as the iteration variable.

Memory & Allocation

• Static Extraction: Move static arrays or sets outside of functions to avoid re-allocation on every call.
• Array Operations: Use .concat() for concatenation and .slice() for copying.
• Object Cloning: Use the spread operator { ...obj } for AST node cloning.
• Data Structures:
  • Use Arrays for small collections (≤10 elements).
  • Use Sets for large collections to achieve O(1) lookup performance.

Performance Anti-pattern Example

// ❌ Bad - recreated every call
function someFunction() {
    const types = ['Type1', 'Type2'];
    const relevantNodes = [...(arb.ast[0].typeMap.NodeType || [])];
    // ...
}

// ✅ Good - static extraction and direct access
const ALLOWED_TYPES = ['Type1', 'Type2'];
function someFunction() {
    const relevantNodes = arb.ast[0].typeMap.NodeType;
    // ...
}