Guides for protecting production JavaScript

Five-minute proof run

For a real evaluation, do not rely on screenshots. Protect one small marked function, keep the source-free report with the build, and confirm the shipped file no longer contains the original function body.

# 1. Mark one cold sensitive function with @virtualize.
# 2. Enable UseVMProtection in the protection request or config.
# 3. Save both the manifest and the full API report.
npx jso-protector --config jso.config.json \
  --manifest dist-protected/jso-manifest.json \
  --report   dist-protected/jso-report.json

# 4. Verify the protected files still match the manifest.
npx jso-protector --verify-manifest dist-protected/jso-manifest.json \
  --audit-source-maps

# 5. Verify the source-free report proves VM protection ran.
npx jso-protector --verify-vm-proof dist-protected/jso-report.json \
  --min-vm-functions 1

# 6. Generate the reviewer handoff packet.
npx jso-protector --vm-proof-pack dist-protected/jso-report.json \
  --vm-proof-output reports/vm-proof-pack.md \
  --min-vm-functions 1

The pass condition is practical: the application smoke test still passes, --verify-vm-proof passes, the report shows UseVMProtection=true, the virtualized count is above zero, the generated --vm-proof-pack handoff has a passing checklist, a review decision, compatibility guidance, and hot-path guidance, and the protected file does not contain the readable source body of the marked function.

What a reviewer should look for

Sample selected function

A good VM candidate is short, valuable, synchronous, and rarely called. This is the kind of function a reviewer should expect to see marked:

// @virtualize
function validateLicense(userId, licenseKey) {
    let hash = 2166136261;

    for (let i = 0; i < licenseKey.length; i++) {
        hash ^= licenseKey.charCodeAt(i);
        hash = Math.imul(hash, 16777619);
    }

    return (hash >> 0) === expectedLicenseHash(userId);
}

The function does not use async, closures, this, classes, destructured parameters, template literals, or var. That keeps the VM pass focused on the part of the application where stronger protection is worth the runtime cost.

Representative protected output shape

The exact output changes by build. A reviewer should not expect this literal text; they should expect the same shape: generated VM bootstrap, encoded bytecode, and a replacement function that dispatches through the VM.

var __jsoVm=(function(){
  var seed=492817, tape="61,08,4d,3f,...";
  var ops=decodeTape(tape, seed);
  function run(slot,args){
    var pc=0, stack=[], locals=args.slice(0);
    while(pc<ops.length){
      switch(nextOpcode(ops,pc++)){
        case 17: stack.push(locals[nextOperand(ops,pc++)]); break;
        case 42: stack.push(Math.imul(stack.pop(), nextOperand(ops,pc++))); break;
        case 91: return stack.pop();
      }
    }
  }
  return { call: run };
})();

function validateLicense(userId, licenseKey) {
  return __jsoVm.call(0, arguments);
}

This is the useful review signal: the original source-level body is no longer present in the shipped file. An attacker can still observe runtime behavior, but static recovery is a different and harder job.

Compatibility table

Performance planning

The generated --vm-proof-pack Markdown and JSON output repeats this hot-path guidance and the compatibility limits above, then adds a review decision such as ready-for-manual-review when the required VM proof checks passed but the release owner still needs to confirm function scope and smoke-test results. It also includes a source-free VM Proof Review Assistant for BYO AI or internal reviewers, with prompts for failed proof checks, VM warnings, cold sensitive function scope, hot-path exclusion, build identity, and protected-build smoke evidence. The assistant boundary is explicit: do not include source code, protected output, VM bytecode, source maps, provider keys, customer data, or secrets. Reviewers should ask for an application smoke test, not a synthetic slowdown ratio. The right question is whether the selected function is rare enough that the extra protection is worth the added runtime work.

Release evidence example

JSO release reports are source-free. They can be stored with build artifacts to show which protections were requested and what the engine actually applied:

{
  "BuildID": "2026-06-06-main-8f43b7c",
  "EnabledOptions": ["EncryptStrings", "FlatTransform", "UseVMProtection"],
  "UseVMProtection": true,
  "VMProtectionApplied": true,
  "VMProtectionVirtualizedCount": 1,
  "VMProtectionWarnings": [],
  "CompatibilitySummary": {
    "Risk": "Low",
    "Warnings": []
  },
  "RuntimeDefenseSummary": {
    "BeaconCallback": true,
    "SelfDefending": true
  },
  "RecoverySymbolPackJson": "{ ... source-free symbolication metadata ... }"
}

If the count is zero, reviewers should check VMProtectionWarnings, confirm the account is enabled for the beta, and confirm the marker is directly above a supported function declaration. Accepted marker forms are // @virtualize, /* @virtualize */, and /** @virtualize */.

Evidence checklist

Security review handoff

For an internal review, keep this evidence together with the protected release:

• The source-free release report for the protected build.
• The jso-protector --vm-proof-pack Markdown or JSON output for that report.
• The VM Proof Review Assistant section from that packet when a BYO AI key or internal reviewer will help turn proof gaps into owner actions.
• The jso-protector --verify-vm-proof output when CI needs a compact pass/fail gate.
• The list of functions selected for VM protection and why each one is sensitive.
• Any skip warnings and the decision made for those functions.
• Protected-build smoke-test results for login, checkout, license validation, and other affected flows.
• Runtime-defense beacon configuration when tamper events need to reach the dashboard, Slack, Discord, Splunk, Elasticsearch, or a signed webhook.

Boundary statement

VM protection is a stronger static-analysis barrier, not a promise that client-side code becomes secret forever. Determined attackers can still run the code, observe behavior, instrument the browser, and spend time reconstructing logic. The practical value is that the shipped file no longer exposes the original function body, and repeated releases do not need to expose the same VM shape.