reverse-browser-runtime

name

reverse-browser-runtime

description

Reverse an authorized browser-side runtime, obfuscated JavaScript VM, request signer, anti-abuse token generator, or client-only algorithm into a local implementation. Use when Codex must inspect browser traffic/scripts, instrument a minified runtime, trace bytecode or VM execution, compare browser/VM outputs against a pure local implementation, and validate a replayed API workflow without relying on the original browser runtime.

Reverse Browser Runtime

Purpose

Use this skill to turn an authorized browser-only algorithm into a maintainable local implementation. It is especially useful for request signers, token builders, obfuscated bytecode VMs, and private web-client algorithms that a CLI must reproduce.

This skill complements website-to-cli: use website-to-cli for the product CLI shape and API replay, and this skill for the runtime/signing reverse engineering needed to remove browser or official-script dependencies.

Boundaries

Work only on systems the user is authorized to test. Do not help steal credentials, bypass access controls for unauthorized access, or evade detection on third-party systems. Keep captures, cookies, signed URLs, tokens, fixtures, and generated outputs private and out of commits.

Do not claim a pure implementation is complete until it passes local comparison and a real end-to-end request without falling back to the browser or official VM.

Workflow

1. Establish A Baseline

Start with git and a working replay path.

• Commit the current code before invasive reverse-engineering.
• Capture the browser workflow and identify the exact signed request.
• Build or reuse a VM/browser-backed signer as the oracle.
• Add a read-only comparison command, such as signer compare, that creates the signed request locally without submitting a state-changing API call.
• Save private fixtures outside the repo, with hashes and redacted metadata rather than secrets.

The first milestone is not pure JS. It is a stable oracle that can produce current outputs on demand.

2. Locate The Runtime

Find the smallest runtime surface responsible for the value.

• Search loaded scripts for token names, storage keys, request paths, and hook points.
• If names are absent, find fetch/XHR hooks, service worker hooks, or monkey-patched APIs.
• Map high-level call order: request wrapper -> canonicalization -> core function -> encoder.
• Record stable function or bytecode IDs, script versions, and input/output shapes.

Prefer instrumentation over reading minified code by eye. Minified code lies by omission; live traces show actual data flow.

3. Instrument Safely

Patch the local copy of the runtime, not production. Keep patches narrow and reversible.

Trace these layers:

• function factory calls and returns
• internal VM/bytecode calls that do not pass through public wrappers
• opcode program counters and small stack windows
• string table references and code lengths
• callsite arguments and return values with configurable value limits
• random/time inputs when they affect exact output

For bytecode VM details, read references/vm-bytecode-tracing.md.

4. Decompose The Algorithm

Work from the outer API boundary inward.

1. Identify canonical request input: URL, query string, body string, headers, storage values, user agent, screen fields, timestamps, random bytes.
2. Split the core function into named phases: hashing, environment collection, payload assembly, obfuscation, encryption, encoding.
3. Translate small helpers first and prove each helper against VM trace data.
4. Keep randomness injectable so deterministic tests can replay VM random sequences.
5. Preserve byte-level behavior. Avoid Unicode string assumptions unless the VM proves them.

Useful proof pattern:

VM input -> helper candidate -> byte-for-byte output comparison

Do not jump directly to the final token. A passing helper chain is easier to trust than a large opaque rewrite.

5. Implement The Pure Runtime

Move translated logic into a focused module, usually signer or *-algorithm.

Implementation rules:

• Keep browser/VM signer and pure signer separate.
• Keep algorithmSignCandidate free of fallback behavior.
• Put fallback only in a wrapper such as algorithmSignRequest({ fallback: true }).
• Return metadata that makes fallback obvious: algorithm.ok, algorithm.fallback, token lengths, and signer name.
• Keep exact token bytes private in command output.
• Treat random outputs carefully: compare structure, length, alphabet, and server acceptance when exact equality is impossible.

6. Validate In Gates

Use increasing-risk gates:

1. Syntax/type checks.
2. Helper-level trace comparisons.
3. Read-only signer comparison against oracle.
4. Read-only health command, such as doctor.
5. A real state-changing request only after the pure signer passes and the user has accepted side effects.
6. Status polling and output download.
7. Local file validation, such as file, media metadata, dimensions, duration, hashes, or JSON schema checks.

For a reusable validation checklist, read references/validation-gates.md.

7. Commit Milestones

Commit by learning milestone, not by time spent.

Good commit sequence:

• Add runtime trace command
• Improve bytecode callsite tracing
• Translate signer helper primitives
• Translate payload assembly
• Complete pure signer
• Document runtime reverse workflow

Do not commit private fixtures, auth stores, captured full URLs, generated outputs, or raw traces containing secrets.

Completion Criteria

A reverse-engineered runtime is complete only when:

• the pure implementation can sign without loading the browser, official runtime, or VM
• read-only comparison reports complete and no fallback
• a real workflow succeeds with the pure signer
• result polling/download works if the workflow is async
• final output is locally validated
• docs/skills accurately describe remaining limitations

If exact token equality is impossible because the official algorithm mixes randomness, document that clearly and compare deterministic structure plus real server acceptance.