jso-protector — Python client

Python client for the JavaScript Obfuscator HTTP API. Mirrors the protect() surface of the npm jso-protector CLI so behavior stays in lockstep across runtimes.

Pure stdlib — uses urllib and json. No third-party dependency.

Install

pip install jso-protector

Quick start

from jso_protector import protect

result = protect(
    # Credentials default to JSO_API_KEY / JSO_API_PASSWORD env vars.
    files={"app.js": open("dist/app.js").read()},
    preset="balanced",
    label="ci-build-7f3a",   # tags the request with this release label
)

for name, code in result.files.items():
    with open(f"dist-protected/{name}", "w") as fh:
        fh.write(code)

print("BuildId:", result.build_id)
print("Fingerprint:", result.polymorphism_fingerprint)

Credentials

The client reads JSO_API_KEY / JSO_API_PASSWORD (or the long-form JAVASCRIPT_OBFUSCATOR_API_KEY / JAVASCRIPT_OBFUSCATOR_API_PASSWORD) from the environment before falling back to the api_key= / api_password= keyword arguments. Use env vars on shared / CI machines so the keys never appear in source.

Presets

For fine-grained control pass options={...} with the same Pascal-case keys the HTTP API documents — e.g. options={"LockDate": True, "LockDomain": True, "LockDomainList": "example.com"}. Explicit options override preset defaults.

Returned data

ProtectResult is a dataclass with five fields:

Error handling

from jso_protector import protect, ProtectError

try:
    result = protect(files={"app.js": code})
except ProtectError as e:
    # e.message is safe to log — API key / password are never interpolated.
    # e.type and e.error_code carry the API's Type / ErrorCode when present.
    print(f"JSO protection failed: {e}")

Watermarking — anti-piracy / dispute proof

The jso_protector.watermark module embeds an HMAC-SHA256-signed marker into source before it goes to the obfuscation API. The obfuscator's KeepComment option preserves the marker through every transform, so the watermark survives in the protected output. Holders of the secret can verify; everyone else sees an opaque comment block.

from jso_protector import protect, watermark

# Stamp during build:
source = open("dist/app.js").read()
stamped = watermark.inject_into(source, tag="release-2026-Q3", key=os.environ["JSO_WATERMARK_KEY"])
result = protect(files={"app.js": stamped}, preset="balanced",
                 options={"KeepComment": True})    # required so the marker survives

# Verify a protected artifact later:
r = watermark.verify(open("dist-protected/app.js").read(), key=os.environ["JSO_WATERMARK_KEY"])
if r.valid:
    print(f"Valid build, tag={r.tag}")
elif r.present:
    print(f"Watermark present (tag={r.tag}) but signature does NOT match the supplied key.")
else:
    print("No watermark in this file.")

Wire format is identical to the Node (packages/jso-protector/watermark.js) and .NET (JsoProtector.Watermark) clients — an artifact stamped by any of the three verifies under any of the others. Tests in tests/test_watermark.py include cross-language verification with the Node implementation (skipped when node isn't on PATH). Spec: https://javascriptobfuscator.com/docs/wireformat.aspx#watermark.

Lookup-only mode (no key supplied) extracts the embedded tag without validating — useful for forensic inspection of leaked artifacts where the secret shouldn't ship to the investigator. Constant-time HMAC compare via hmac.compare_digest.

Stack-trace symbolication

Persist result.report (or just result.report["GlobalIdentifierMap"] and result.report["MemberIdentifierMap"]) alongside the protected dist. When a production crash arrives, demangle locally with the jso-symbolicate npm package — or, for a Python-only pipeline, the identifier map is plain JSON that you can iterate over and substitute against the stack text yourself.

License

UNLICENSED. Provided as a free companion to the JSO service. An active JSO account is required to make API calls.