How mercuryworkshop/scramjet works
Scramjet is an experimental browser-based web proxy for sandboxing and rewriting remote sites to bypass browser restrictions and censorship. The principal flow is bootstrap registration and setup, followed by controller-managed service-worker interception, proxy fetching, response rewriting, and execution in a sandboxed client. The repository also includes a Rust/JavaScript rewriter implementation and browser-management plugins. The README documents the overall interception, rewriting, and sandboxing design; several internal links below are therefore documented at subsystem level rather than verified from sampled runtime calls.
Main entry points: fetch.ts Proxy fetch handler · index.ts Controller and frames · rewriters Content rewriters · client.ts Sandbox client
Components 25
Bootstrap and setup
- Bootstrap client
packages/bootstrap/src/client.ts - Service worker setup
packages/bootstrap/src/clientcommon.ts - Bootstrap server
packages/bootstrap/src/server.ts
Proxy runtime
- Controller and frames
packages/controller/src/index.ts - RPC helpers
packages/rpc/index.ts - Proxy fetch handler
packages/core/src/fetch/fetch.ts - Fetch parsing
packages/core/src/fetch/parse.ts - Proxy transport
- HTTP headers
packages/core/src/fetch/headers.ts
Rewriting and sandbox
- Content rewriters
packages/core/src/shared/rewriters - HTML rewriting
packages/core/src/shared/rewriters/html.ts - JavaScript rewriting
packages/core/src/shared/rewriters/js.ts - Wasm rewriting
packages/core/src/shared/rewriters/wasm.ts - Native rewriter
packages/core/rewriter/native/src/rewriter.rs - Coverage analysis
packages/core/rewriter/coverage-macro/src/analyze.rs - Sandbox client
packages/core/src/client/client.ts - Client entry
packages/core/src/client/entry.ts - DOM emulation
packages/core/src/client/dom - Browser API interception
packages/core/src/client/shared - Source maps
packages/core/src/client/shared/sourcemaps.ts
Browser extensions
- Event handler plugin
packages/utils/src/event-handler-plugin.ts - Late event listeners
packages/utils/src/alwaysLastBubble.ts - Link handler plugin
packages/utils/src/link-handler-plugin.ts
Other components
- Site visitor
- Remote website
Connections 21
- Site visitor → Bootstrap client: starts proxy
- Bootstrap client → Service worker setup: registers worker
packages/bootstrap/src/client.ts - Bootstrap client → Controller and frames: creates controller
packages/bootstrap/src/client.ts - Bootstrap server → Bootstrap client: serves bootstrap
packages/bootstrap/src/server.ts - Controller and frames → Proxy fetch handler: creates handler
packages/controller/src/index.ts - Controller and frames → Proxy transport: configures transport
packages/controller/src/index.ts - Controller and frames → RPC helpers: uses RPC
packages/controller/src/index.ts - Proxy fetch handler → Fetch parsing: uses parsing
- Proxy fetch handler → HTTP headers: handles headers
- Proxy fetch handler → Remote website: fetches remote content
- Proxy fetch handler → Content rewriters: rewrites responses
- Content rewriters → HTML rewriting: includes
- Content rewriters → JavaScript rewriting: includes
- Content rewriters → Wasm rewriting: includes
- Native rewriter → Coverage analysis: analyzes coverage
- Client entry → Sandbox client: initializes
packages/core/src/client/client.ts - Sandbox client → DOM emulation: emulates DOM
- Sandbox client → Browser API interception: intercepts APIs
packages/core/src/client/client.ts - Sandbox client → Source maps: uses source maps
packages/core/src/client/singletonbox.ts - Event handler plugin → Late event listeners: sets up listeners
packages/utils/src/event-handler-plugin.ts - Link handler plugin → Event handler plugin: registers click handlers
packages/utils/src/link-handler-plugin.ts