Category: Mirrorit

1. Executive Summary & The Problem of Minified Bundles

Modern production web applications built with Next.js, Vite, Remix, or Nuxt are delivered as deeply compressed, mangled, and tree-shaken JavaScript bundles. Function names become single characters (e(t, r)), module boundaries vanish into monolithic vendor chunks, and TypeScript type signatures are completely stripped away.

However, modern engineering teams frequently enable source maps in staging or inadvertently ship them to production for monitoring tools like Sentry, Datadog, or Bugsnag. When these assets are present, they contain a goldmine of architectural data: original source code, typed interfaces, and folder trees. Mirrorit is built to extract, decode, and reconstitute these assets into a clean, editor-ready repository located in _src/.

2. The Anatomy of Source Map v3 Specification

A Source Map v3 artifact is structured as a single JSON file with strict field semantics:

{
  "version": 3,
  "file": "main.8f4a21.js",
  "sources": [
    "webpack:///src/components/Navigation.tsx",
    "webpack:///src/hooks/useAuth.ts"
  ],
  "sourcesContent": [
    "export const Navigation = () => { ... }",
    "export function useAuth() { ... }"
  ],
  "names": ["Navigation", "useState", "useEffect"],
  "mappings": "AAAA,SAASA,QAAQC,KAAM..."
}

When the sourcesContent array is embedded directly inside the .map file, recovery is deterministic and instantaneous. Even when sourcesContent is omitted, Mirrorit parses the mappings string—an encoded sequence of Base64 Variable-Length Quantity (VLQ) segments—to cross-reference minified tokens against original source tokens.

3. Technical Comparison: Minified Bundles vs Reconstructed Source

The table below summarizes the technical differences between raw minified client code and the source artifacts recovered through Mirrorit’s deobfuscation engine:

4. The Base64 VLQ State Machine

Each segment in the mappings field contains 1, 4, or 5 variable-length values encoded in Base64:

1. Generated Column: The 0-based column offset in the generated file.
2. Sources Index: The 0-based index into the sources array indicating which file was the origin.
3. Original Line: The 0-based line number in the original source file.
4. Original Column: The 0-based column number in the original source file.
5. Names Index (Optional): The 0-based index into the names array identifying the original identifier.

Mirrorit implements a streaming VLQ decoder in memory that avoids intermediate string allocations, decoding tens of megabytes of sourcemaps in sub-second runtimes:

// High-performance VLQ segment consumer
export function decodeVLQSegment(str: string, index: number): [number[], number] {
  const result: number[] = [];
  let shift = 0;
  let value = 0;

  while (index < str.length) {
    const char = str.charCodeAt(index++);
    const integer = B64_LOOKUP[char];
    const hasContinuation = (integer & 32) !== 0;
    value += (integer & 31) << shift;

    if (hasContinuation) {
      shift += 5;
    } else {
      const isNegative = (value & 1) === 1;
      result.push(isNegative ? -(value >> 1) : value >> 1);
      value = 0;
      shift = 0;
      if (result.length === 5) break;
    }
  }

  return [result, index];
}

5. Path Traversal Defense & File System Normalization

A critical engineering hurdle when unpacking sourcemaps is path sanitization. Third-party bundlers frequently prefix source files with pseudo-schemes like webpack:///, vite:///, or arbitrary relative paths containing ../../../../etc/passwd.

Mirrorit enforces a strict path containment boundary:

• Strips custom protocols (webpack://, rollup://, ng://).
• Resolves all dot-dot segments (..) and verifies that the resolved path never escapes the target _src/ directory.
• Converts illegal Windows/Linux characters (colons, asterisks, question marks) into safe directory slugs.

6. Security Recommendations for Engineering Teams

If your organization does not intend to share proprietary algorithms or internal TypeScript models with the public:

• Configure your build tool (next.config.js or vite.config.ts) to set productionBrowserSourceMaps: false.
• Upload sourcemaps directly to your error monitoring backend (e.g. Sentry CLI) during CI/CD, and delete all .map files before deploying to CDN edges.
• Block public HTTP requests to *.map at your reverse proxy (Nginx, Cloudflare WAF, or Caddy).