SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsweb-js-env-patcher

web-js-env-patcher

Coding & development

View repository

Updated 10-16 06:24

About this skill

Web-side JS Node.js environment shimming

Capability boundaries

This Skill only handles the environment analysis, evidence collection, WebAPI implementation, and verification required to run web-side browser JavaScript in Node.js.

  • The goal is to run the original web JS, not to prioritize rewriting the algorithm.
  • It does not handle Native tasks such as App, Android, iOS, mini-programs, EXE, DLL, Frida, IDA, JADX, Ghidra, etc.
  • By default it does not proactively reverse JSVMP, opcode, or virtual machine interpreters; it only locates environment dependencies, request chains, and writers. When it is necessary to enter JSVMP source code, pause first and have the user explicitly change the scope.
  • TLS fingerprint compatibility is only used to verify browser network stack differences under authorization, and must not be used to bypass login, CAPTCHA, MFA, access control, or bulk access.

Working model

This Skill has three layers:

  1. SKILL.md Responsible for scope, decisions, hard rules, and the main workflow.
  2. references/ Responsible for scenario details, schemas, sampling methods, and acceptance criteria; read only when the corresponding scenario is triggered.
  3. scripts/ Responsible for deterministic collection and gating; script results cannot replace real browser evidence or engineering judgment.

Do not load all references at once. First determine the files to read based on the routing below.

References routing

Task confirmation and evidence collection

  • New case, missing information, or need to confirm the template: read references/intake-template.md、references/workflow.md、references/delivery-templates.md。
  • Choose ruyiPage, RuyiTrace, Camoufox, CloakBrowser, manual evidence collection, or AI decision: read references/browser-acquisition.md。
  • Use ruyiPage / RuyiTrace, installation detection, automatic capture, or import NDJSON: read references/ruyi-tooling.md。
  • Use Camoufox / camoufox-reverse-mcp: read references/camoufox-tooling.md。
  • Automatic click, drag, keyboard, scroll, or possible detection of isTrusted: read references/trusted-input-and-isTrusted.md。
  • CAPTCHA, challenge, WAF, or verify flow: read references/captcha-flow-and-verify-handoff.md。
  • Fix the same profile, seed, proxy, language, timezone, UA, screen, WebGL: read references/fingerprint-baseline-consistency.md。
  • Evaluate evidence credibility or choose implementation / replay / defer: read references/trust-matrix.md、references/case-patterns.md。

Request, resource, and entry-point localization

  • Parse requests, locate encryption entry points, XHR/fetch Hook, or sort out source → entry → builder → writer: read references/crypto-entry-location.md、references/hook-templates.md。
  • HTML, bundle, chunk, challenge JS, 403 pages may be expired: read references/dynamic-resource-freshness.md。
  • Cookie/token invalid or need to locate a non-login Cookie generation chain: read references/cookie-generation-analysis.md。
  • Final request order, Cookie jar, Session lifecycle: read references/session-request-chain.md。
  • UA, Client Hints, Header, TLS/HTTP2 aligned with browser baseline: read references/tls-request-validation.md。

Trace and environment implementation

  • Run target JS, Proxy probing, missing-environment localization: read references/env-debug-loop.md。
  • Trace first-round API inventory, coverage matrix, and reasons for unplanned additions: read references/trace-api-coverage.md。
  • Trace contract, audit-only/no-send, and runtime deep consistency: read references/trace-runtime-conformance.md。
  • Choose not to use a framework, isolated-vm,vm or jsEnv: read references/runtime-frameworks.md。
  • Use the bundled modified xbs isolated-vm: read references/xbs-isolated-vm-api.md。
  • addon.node or xbs ABI incompatible: read references/node-version-recovery.md。
  • addon new API, private API, native collection, plugins/mimeTypes: read references/addon-api.md。
  • Browser object inventory, constructors, prototype chain, descriptor and accessor: read references/env-object-model.md。
  • addon-first、toString、document.all, brand and native-like: read references/env-native-protection.md。
  • Node global object or host WebAPI leakage, silent failure: read references/node-leakage-and-silent-failure.md。
  • Level 1/2/3 module division: read references/env-module-levels.md。
  • Pure JS, addon and xbs all cannot express real behavior: read references/native-capability-gap.md。

WebAPI, object shape and fingerprint

  • iframe, Worker, PerformanceTimeline, DOM/CSSOM, EventTarget, timer, writer branches: read references/webapi-env-detection-matrix.md。
  • Object ownKeys, descriptor, prototype walk or _ / __ private state leakage: read references/object-shape-private-state.md。
  • Real value sampling and replay for Canvas, WebGL, WebGPU, Audio, fonts, DOM geometry, etc.: read references/fingerprint-value-replay.md。
  • Browser and Node fixture comparison: read references/fixture-validation.md。
  • Worker, WASM, MessagePort, structuredClone: read references/wasm-worker-postmessage.md。
  • High-intensity browser integrity detection or complex behavior diff: read references/high-strength-browser-detection.md、references/high-intensity-env-diff.md。

XHR/fetch and final request

  • XHR/fetch/sendBeacon need to reuse the final TLS Session: read references/xhr-fetch-session-bridge.md。
  • Request headers, request body, actor, realm, lifecycle, status, responseURL, reload behavior comparison: read references/xhr-fetch-semantics-audit.md。

Engineering quality and delivery

  • Modify complex case or key source code: read references/code-change-memory.md。
  • Write or refactor final environment patching code: read references/code-style.md。
  • Chinese stage report: read references/stage-markdown-reports.md。
  • Final summary and environment / fingerprint API replay details: read references/final-project-summary.md。
  • Cleanup of temporary files and sensitive materials: read references/cleanup.md。
  • Regression scenarios and skill self-test: read references/validation.md。

Hard rules

  1. Confirm information first: At minimum confirm the target page, target API, method, encrypted parameter name and location, successful request sample, known JS, forensics mode, final TLS client, or "do not send real requests". When information is insufficient, only output the known information, missing items and next steps; do not start forensics, download JS, run old code or write env.

  2. Forensics mode before forensics actions: Before opening web pages, packet capture, Hook, breakpoints, screenshots, downloading resources or collecting Trace, first confirm ruyiPage + RuyiTrace, ruyiPage only, Camoufox + MCP, Camoufox only, CloakBrowser, manual forensics, or AI decision. Do not first fail with ordinary Playwright / Puppeteer / system browser and then switch.

  3. Fix fingerprint baseline: After the first successful forensics, generate case/notes/fingerprint-baseline.json and baselineId. Subsequent network, Trace, Hook, fingerprint and Node audit must use the same profile / seed / proxy / language / timezone / UA / Client Hints / screen / WebGL. Before switching tools or baseline, must pause and confirm.

  4. Pre-confirmation for captcha and login: Before any forensics, first determine whether it is a captcha, risk-control verification, challenge or WAF interface. When login is required, do not ask for account, password, captcha or MFA; let the user complete it in the confirmed tool and reply success. Captcha Trace must cover trigger, display, interaction, submission and verify return.

  5. Request sample is not equal to final baseline: cURL/HAR only provides URL, method, structure, parameter location and business field clues. If the sample browser family conflicts with the forensics baseline, by default use the forensics baseline's UA, Client Hints, Header, TLS/HTTP2, Cookie and fingerprint as the standard, and record the conflict.

  6. Confirm parameters and links first: List all suspicious dynamic parameters in Query, Header, Body, and Cookie, and have the user confirm the current scope; entry-point localization must output source → entry → builder → writer. When a non-login Cookie becomes invalid, first analyze the generation/refresh chain; do not ask for a new Cookie by default.

  7. Dynamic resources must not be frozen: HTML, bundles, chunks, challenge JS, 403 pages, and inline seeds are by default only analysis snapshots. Record resource freshness; when they affect final parameters, they must be refreshed at runtime within the same Session.

  8. Trace hits must be planned in the first round: When RuyiTrace, Node trace, Hook environment logs, or missing-env.json exist, generate trace-api-inventory.json and env-coverage-matrix.mdbefore the first version of the env/signer probe. P0/P1 must be implemented in the first round, sampled against the same baseline, and explicitly marked as not yet mounted or as entering a native gap; do not wait for an error or a writer branch failure before adding them.missed-from-trace must be recorded as a process defect.

  9. Trace must form an executable closure: After the first round of env, each environment modification, dynamic resource refresh, or baseline change, regenerate the v3 Trace runtime contract, and have the current final entry point output Node audit in audit-only/no-send mode. You must compare realm, receiver, descriptor, brand, prototype, ownKeys, results/exceptions, and the raw state timeline; do not infer order from grouped observations. When multiple Traces are automatically discovered, explicitly select the current baseline; silently merging across historical collections is prohibited. Handwritten matched, same-name targets, evidence text, keywords, or Top API lists do not count as observations; P0/P1 mismatches or network access will block.

  10. The framework is decided by the user: Before formally supplementing the environment, confirm that no framework is used (default), xbs isolated-vm, Node vm , or jsEnv. Trace complexity only determines risk and priority; it does not automatically select a framework. isolated-vm must verify the bundled binary, Node ABI,window.xbs , and xbs.dom.createDocument; when jsEnv does not provide a real project and documentation, APIs must not be fabricated.

  11. Node leakage and native capabilities upfront: Before running the target JS, isolate process、Buffer、require、module、global、Node navigator, Storage, performance, and host network/messaging WebAPIs. Environment supplementation initialization detects addon.node or xbs; when available, functions, accessors, constructors, collection objects, plugins/mimeTypes,document.all , etc. must be native-first. If the ABI is incompatible, first handle it according to the version recovery process; only after the user refuses or recovery fails is a documented fallback allowed.

  12. The real browser object model is enabled by default: Key WebAPIs must handle descriptor, getter/setter, construction behavior, prototype,instanceof, toString, brand, and illegal receivers from the first version; do not paper over them with plain objects or simple functions. iframe/Worker must have an independent global, constructor graph, exposed objects, and lifecycle; only underlying same-origin state with browser evidence may be shared, and the main Realm wrapper must not be reused. Probe Proxy may only be used for diagnosis; the final deliverable should solidify real objects.

  13. Browser object private state must not leak: Objects visible to the target JS must not store internal state through _、__ or custom Symbol own properties. Prefer addon/xbs private APIs, then module-level WeakMap. Object shape must be compared field by field against the browser baseline and Node audit; do not only check property prefixes or target names.

  14. Fingerprint values must have real evidence: Prefer Trace values from the same baseline that are not truncated; when Trace is missing, close to the 4000/4096 truncation limit, of unknown length, or has a baseline conflict, supplement collection with confirmed browser tools. AI-guessed values, random values, default values, mocks, jsdom, node-canvas, and headless-gl cannot be used as final replay values. For long values, record the full length, hash, shards, and source.

  15. XHR/fetch must satisfy both semantics and Session: For real requests, XHR/fetch/sendBeacon must go through the same TLS Session bridge; they must not directly use the Node host network, nor return a default 200 or a fixture pretending to be a success. Python curl_cffi scenarios are handled by final.py holding the sole Session and serving Node IPC. Before a real request, generate the complete network-transcript/v3 and complete the no-send diff; if any of URL, Header actual value/masked hash, body/response hash, responseURL, response headers, actor/realm/epoch, global event order, reload cleanup, Session, or extra requests is missing, it is blocked, and if both sides are missing the same field it does not count as matched.

  16. Code quality and native gaps must not be bypassed: signer, probe, runner, and diagnostic only do orchestration; the WebAPI main body must be split into src/env/ or src/node-runtime/env/; isolated-vm must not use large blocks of String.raw to aggregate source code. Before a real request, the code quality and addon-first gates must be passed. When pure JS, addon, and xbs all cannot reliably implement it, output the native capability gap, suggested API, minimal browser/native test, and pass criteria; do not fake success.

  17. Unified master gate before real requests: Whenever a case's Trace, stage report, notes, fixtures, transcript, or runtime shows browser environment/XHR/fetch signals, check_environment_closure.js --before-real-requestmust be executed. The master gate actively aggregates Trace-runtime, object shape, WebAPI/Realm/message/DOM behavior matrix, XHR/fetch no-send, same Session, code quality, and addon-first; if any fails, no real request may be sent and no delivery may be made.

  18. Final project and cleanup: The final project may have only one directly runnable entry point, result/final.js or result/final.py, which internally completes environment installation, Session creation, dynamic resource refresh, parameter generation, optional requests, and finally destruction. It must not contain browser automation, temporary server/bridge, Trace, HAR, Hook, screenshots, Profile, or test cache. Clean up temporary artifacts promptly at each stage; before deleting sensitive materials such as login state and Cookies, confirm the user's intent.

Main flow

A. Intake and forensic confirmation

  1. Confirm that the task belongs to web-side JS Node.js environment supplementation; otherwise explain the boundary and stop.
  2. Run the information completeness check, listing known information, missing items, and all suspicious parameters.
  3. Confirm the forensic mode, the final TLS client or no request, the final Session mode, and the timing for choosing the environment supplementation framework.
  4. Write case/阶段报告/01-需求信息确认.md; record an exemption only when the user explicitly requests that no report be generated.
  5. Once the information is complete, first confirm the CAPTCHA / login / permission interaction, then begin forensics.
  6. Parse cURL/HAR and the browser family, recording conflicts with the fingerprint baseline.

B. Evidence and first-round environment plan

  1. Use confirmed tools to collect evidence starting from the first page open, fix baselineId, and collect successful requests, related JS, and dynamic resource freshness.
  2. Locate source → entry → builder → writer, and confirm the location where the target parameter is actually written into the request.
  3. When a Trace is available, first import it and generate the API inventory, coverage matrix, and complexity summary; complexity does not determine the framework.
  4. Complete all Trace P0/P1 decisions before the first env version; when real-value APIs lack samples, mark them for sampling rather than attaching empty shells.
  5. Immediately after the first env version, generate the runtime contract, run the audit-only/no-send Node audit and a deep diff.
  6. When iframe, Worker, MessagePort, Performance, DOM CRUD/CSSOM, EventTarget, timer, writer, object shape, or network behavior is triggered, use the same probe suite to separately generate a browser baseline and a Node audit containing actual observations; evidence paths and manual status cannot replace results.

C. Implementation and Iteration

  1. Initialize the runtime according to the user's choice, perform Node leak blocking, load addon/xbs capabilities, and record fallbacks.
  2. Implement according to Level 1 basic runtime layer, Level 2 fingerprint authenticity layer, and Level 3 target SDK layer; site logic must not pollute the general env.
  3. All browser objects use modularization, native-first, authenticity protection, and private state isolation; maintain case/notes/代码变更记忆.md。
  4. Fingerprint APIs only replay real browser values from the same baseline; when missing or truncated, collect additional samples.
  5. For XHR/fetch, first implement browser semantics and the no-send transcript, then connect to the confirmed TLS Session bridge.
  6. After each modification to env, baseline, dynamic resources, or network bridging, rerun the affected runtime audit and matrix; do not wait for new errors before patching the environment.

D. Verification, Requests, and Delivery

  1. Use fixtures to compare key outputs between the browser and Node; "no errors" does not count as completion, and a standalone OPTIONS preflight does not count as a successful target request.
  2. When parameters or requests are inconsistent, first investigate baseline, resource freshness, Cookie/Storage, request order, Header/TLS/Session, Trace truncation, and automation exposure, then modify the env.
  3. Execute a unified environment closure before real requests; in real mode add --require-live and actual --tls-client。
  4. Only after the closure passes, use the single entry point to perform a small number of authorized verifications with the same Session.
  5. Generate the phase report and result/最终项目总结.md, recording hashes, mismatch counts, matrix, replay sources, Session chain, risks, and cleanup results.
  6. Run the final artifact check, fix all blocking items, clean up temporary files, and then deliver.

Unified Command Entry

The following commands are the main entry points; use finer command parameters according to the corresponding reference.

# Intake
node scripts/check_intake.js --input task.md --markdown

# 真实请求前统一环境闭环
node scripts/check_environment_closure.js --case-dir case --before-real-request --markdown
node scripts/check_environment_closure.js --case-dir case --before-real-request --require-live --tls-client curl_cffi --markdown

# 阶段报告与最终产物
node scripts/check_stage_reports.js --case-dir case --require-dynamic-fields --markdown
node scripts/check_final_artifact.js --case-dir case --markdown

Minimal closed loop for the Trace scenario:

node scripts/build_trace_runtime_contract.js --case-dir case --baseline-id <baselineId> --markdown
node scripts/run_trace_runtime_audit.js --case-dir case --entry case/result/final.js --markdown
node scripts/check_trace_api_coverage.js --case-dir case --require-runtime-closure --markdown

Minimal closed loop for the XHR/fetch scenario:

node scripts/check_xhr_fetch_semantics.js --case-dir case --require --require-no-send --out case/tmp/xhr-fetch-semantics-audit.json --markdown
node scripts/check_xhr_fetch_session_bridge.js --case-dir case --require-live --tls-client curl_cffi --markdown

Required Evidence

Generate according to the triggered scenario; do not manually fill in matched in place of machine observation:

  • Baseline:case/notes/fingerprint-baseline.json and unified baselineId。
  • Trace：trace-api-inventory.json、env-coverage-matrix.md、trace-runtime-contract.json、node-trace-runtime-audit.json。
  • WebAPI: same probeSuiteVersion/probeSourceFile/probeSourceHash and containing actual observation browser-env-detection-baseline.json、node-env-detection-audit.json、webapi-env-detection-matrix.md。
  • Object shape:browser-object-shape-baseline.json、node-object-shape-audit.json、object-shape-audit.md。
  • Network: browser / Node network transcript,xhr-fetch-semantics-audit.json、xhr-fetch-session-bridge-audit/v2。
  • Fingerprint: real source,baselineId, full length, SHA-256, truncation status, and replay key.
  • Engineering: phase report, code change memory, final summary, single entry point, and final check results.

The phase report and final summary must at least record:

  • traceSourceHash、contractHash、runtimeSourceHash、baselineId、probe version。
  • Trace P0/P1 matched/mismatch, network mismatch, extra Node requests, and audit-only network attempt counts.
  • XHR/fetch Session holder, TLS client, round trip, and same-session proof.
  • WebAPI / trigger categories, blocking items, real value sources, and native fallback for the object shape matrix.
  • In-plan WebAPI for this phase, out-of-plan new addition reasons, features, bugs, fingerprints, tests, risks, and cleanup.

Delivery constraints

  • The final entry point must dynamically generate parameters and must not hardcode encrypted values from cURL, fixtures, or historical requests.
  • The final request must reuse the UA, Client Hints, Header, TLS/HTTP2, proxy, Cookie jar, and Session corresponding to the forensic baseline.
  • Automation tools are only used for pre-forensics and must not enter result/。
  • When the user chooses not to send a real request, output only local parameters and clearly state that no network verification was performed.
  • When any gate fails, fix and retest first; do not deliver after merely declaring the risk in the summary.