ghostframe-borrow-feature

name	ghostframe-borrow-feature
description	Port a single feature from a reference stealth project into this fork's TypeScript code. Use when you've identified a needed mitigation in `vibheksoni/stealth-browser-mcp`, `nodriver`, or another reference repo and need to bring it across without copy-pasting unsafe patterns. Teaches the workflow; the seed examples are starting points, not a static port list.

Borrow a stealth feature

This skill teaches how to borrow, not what to borrow. Detection signals shift; the borrow targets that matter today differ from the ones that matter next quarter.

The reference repo most directly aligned with our scope is vibheksoni/stealth-browser-mcp (Python). Pin to commit 17311be7b0f6b879644c39ec5e8f0dc8a9dd920c when reading; the project moves fast and main may have diverged.

For why each layer matters, see docs/detection-signals.md.

Default scope

Operates on this fork's TypeScript source (src/...) and is effectively a code-borrow workflow with parity-verification steps. Out of scope for this curator role to actually edit src/; this skill is the operational guide an engineer or coding agent follows when the lead approves a port.

Workflow

1. Identify the target signal

Start from a failing detector row, a specific block response, or a diagnose-bot-block output. Map to a layer.

If you cannot name the layer in one sentence, stop. Don't borrow a feature whose purpose you can't articulate — porting unprincipled features adds entropy without removing detection.

2. Find the reference implementation

Search the reference repo for the target. Prefer:

• A Python file under src/ of vibheksoni/stealth-browser-mcp that addresses the layer in isolation.
• A nodriver README section that names the technique.
• A specific commit on Kaliiiiiiiiii-Vinyzu/patchright that introduces the polyfill or flag.

Read the source, not just the README. Read the commit message and any linked issue.

3. Classify the port

For each candidate, decide:

Classification	Meaning	Action
Port-as-is	TS-equivalent semantics, low integration risk	Translate Python → TypeScript line-by-line, preserve comments
Adapt-for-TS	Behavior identical but Python idiom doesn't map (dynamic types, exec, decorators)	Rewrite in idiomatic TS; cite the source for parity reference
Use upstream npm	Equivalent npm package exists	Use the package; do not re-implement
Don't port	Source has a footgun (see Negative examples)	Leave it. Document why in the port PR

4. Implement with parity in mind

When porting, capture for each function:

• The exact CDP method called (e.g. Network.setBlockedURLs, Page.addScriptToEvaluateOnNewDocument, Network.setExtraHTTPHeaders).
• The exact polyfill string injected, byte-for-byte if possible. Polyfills are detected by their shape; reformat carefully.
• The order of operations. Many stealth techniques are order-sensitive (e.g. addScriptToEvaluateOnNewDocument must run before any navigation).

5. Verify parity

Before the port lands, verify:

• Detector sweep passes the layer the borrow targets. Run ghostframe-detect-test before and after; confirm the row that was red is now green.
• The borrowed feature does not regress another layer. CreepJS lies count must not increase. UA coherence checks must still match.
• The behavior matches the source on a test page. If the reference repo ships a fixture, run against it.

6. Document the maintenance contract

Add to the port PR description:

• The reference commit hash (Python or upstream).
• The detection signal addressed.
• The expected lifetime — "Patchright shape, expect to revisit when Chrome changes the API."
• Detector-page observation: which detector row flipped from red to green.

Seed examples (high-value targets, not exhaustive)

From vibheksoni/stealth-browser-mcp at the pinned commit:

Feature	Source path	Layer addressed	Classification
Network.setBlockedURLs	src/network_interceptor.py:43-77	Network	Port-as-is
Network.setExtraHTTPHeaders	src/server.py:965-984	Fingerprint (header coherence)	Port-as-is
Page.addScriptToEvaluateOnNewDocument polyfill injection	src/server.py:2440-2461	DOM	Port-as-is, but treat each polyfill as a separate borrow with its own parity check
Authenticated-proxy forwarder	src/proxy_forwarder.py:1-439	Network (auth proxy support)	Use upstream npm — proxy-chain covers this without rewriting 400 lines

Negative examples

Do not port these. The reason they exist in the reference does not generalize to TS.

Source	Why not
dynamic_hook_ai_interface.py, hook_learning_system.py	AI-codegen executing exec() of LLM-generated Python. We are TypeScript; eval'd-string injection paths are a code-injection footgun without an equivalent runtime sandbox
--single-process container heuristic	The flag itself is detectable via crossOriginIsolated shape. Borrowing it adds detection signal
nodriver's default --disable-features=IsolateOrigins,site-per-process	Cloudflare BM Enterprise probes crossOriginIsolated; inheriting this default adds signal

Tips

• Borrow one feature per PR. Mixing two unrelated mitigations makes parity verification ambiguous.
• Capture the detector matrix before and after. The PR description should show the row that changed.
• Read the linked issue or commit message in the reference repo. Stealth code is full of "obvious-looking" patches that exist for non-obvious reasons.
• When the source is a polyfill string, preserve its exact whitespace and identifier names. Detectors fingerprint the polyfill source; reformatting changes the fingerprint.

What NOT to do

• Do not bulk-port "the stealth file" from the reference repo. Each feature has its own trade-off; borrow incrementally.
• Do not skip the negative-examples list. Two of those entries are more detectable than the inherited posture.
• Do not port a polyfill you don't understand. If you can't articulate which detector row it fixes, you can't tell when it stops working.