repository·main·Indexed 19 days ago
https://github.com/mercuryworkshop/scramjetAn experimental interception-based web proxy designed to bypass censorship, circumvent CORS restrictions, and sandbox web content. Scramjet enables browser-based instrumentation and debugging of arbitrary websites through rewriting and sandboxing techniques. It includes a Controller for managing frames and plugins, a bootstrap system for service worker registration, and support for multiple transport layers including epoxy and libcurl.
Scramjet is an experimental interception-based web proxy designed to evade internet censorship and bypass arbitrary browser restrictions. It enables users to:
It achieves these capabilities through a combination of interception, rewriting, and sandboxing techniques.
To run the Scramjet development server, execute the following command from the repository root. The demo page will be available at http://localhost:4141 and will automatically rebuild when files change (note: the rewriter is excluded from automatic rebuilds).
pnpm devTo build Scramjet from the repository, ensure you have the necessary dependencies installed, then follow these steps:
git clone --recursive https://github.com/MercuryWorkshop/scramjetpnpm:
pnpm icd packages/corepnpm rewriter:buildpnpm buildgit clone --recursive https://github.com/MercuryWorkshop/scramjet
pnpm i
cd packages/core
pnpm rewriter:build
pnpm buildScramjet uses Rspack to generate several different build targets depending on the consumer's environment. The build system produces both IIFE (Immediately Invoked Function Expression) bundles for global script injection and ESM (ES Modules) for modern module-based environments.
Key build variations include:
self.$scramjet). These can be either unbundled (requiring external assets) or bundled (including the WASM rewriter as a Base64 string).libraryTarget: 'module' for standard imports. These can also be unbundled or bundled with WASM.create-proxy-app are configured as Node.js executables with a shebang banner.When tapping into a hook, you can provide a TapOrder object to control when your callback executes relative to other plugins. This is useful for ensuring dependencies are met or that transformations happen in a specific sequence.
before: An array of plugin names. Your callback will run before these plugins.after: An array of plugin names. Your callback will run after these plugins.If no order is provided to the .tap() method, the plugin's own tapOrder (defined in its constructor) is used.
const plugin = new Plugin("my-plugin", {
before: ["auth-plugin"]
});
// This specific tap will run after 'logger-plugin'
plugin.tap(hooks.someHook, callback, { after: ["logger-plugin"] });The ExternalStubPlugin is used to facilitate a pattern where consumers can import Scramjet via ESM (e.g., import { ... } from 'scramjet') while the actual implementation is provided by a global variable (e.g., self.$scramjet).
When this plugin is applied, it automatically discovers the exports in the primary bundle and generates a thin .mjs stub file. This stub simply destructures the required members from the global object, ensuring that consumers pay zero additional source size for the import.
// Example of what the generated stub looks like:
// AUTO-GENERATED by ExternalStubPlugin — do not edit.
// Re-exports of globalThis.$scramjet (set by the IIFE bundle).
const __external = /** @type {any} */ (globalThis).$scramjet;
export const {
exportName1,
exportName2,
} = __external;The Tap system is a plugin architecture used to intercept and modify behavior via hooks.
Tap.create()) that holds a collection of callbacks.Plugin instance provides a namespace and a default tapOrder. Plugins use the .tap() method to register callbacks to specific hooks.Tap.dispatch(), all registered callbacks are executed in an order determined by their TapOrder requirements.before and after arrays, which reference other plugin names. This allows you to ensure your plugin runs specifically before or after a known plugin.// 1. Define the hook structure
interface MyHooks extends Record<string, { context?: object; props?: object }> {
onData: { context?: object; props?: object };
}
// 2. Create the Tap instance
const hooks = Tap.create<MyHooks>();
// 3. Register a plugin
const myPlugin = new Plugin("my-plugin");
myPlugin.tap(hooks.onData, (context, props) => {
console.log("Intercepted!", context);
}, { before: ["other-plugin"] });
// 4. Dispatch the hook
await Tap.dispatch(hooks.onData, { some: "context" }, { some: "props" });The RpcHelper uses a specific JSON-compatible object structure for communication, namespaced by the id provided during construction.
Sent via call(). Used to trigger a method on the remote side.
{
"[id]": {
"$type": "request",
"$method": "methodName",
"$args": { ... },
"$token": 123
}
}Sent by the receiver after a method execution. It includes either the result or an error.
{
"[id]": {
"$type": "response",
"$token": 123,
"$data": "resultValue",
"$error": "Error message if applicable"
}
}Note: $token is used to match responses back to the original call promise.
Scramjet frames support a plugin system via the plugins array passed to createFrame. Common plugins available via the $scramjetUtils global object include:
$scramjetUtils.HttpCachePlugin: Enables HTTP caching for the proxied session.$scramjetUtils.UrlWatcherPlugin(callback): Executes a callback whenever the URL in the frame changes. The callback receives the new URL.$scramjetUtils.CatchEscapedLinksPlugin(callback): Intercepts links within the proxied content. The callback receives the original URL and should return a new URL (e.g., a rewritten link) to be used instead.const urlWatcher = new $scramjetUtils.UrlWatcherPlugin((url) => {
console.log("The frame navigated to:", url);
});
const catchEscapedLinks = new $scramjetUtils.CatchEscapedLinksPlugin(
(url) => new URL(`/?goto=${encodeURIComponent(url.href)}`, location.origin)
);
// Apply them during frame creation
const frame = controller.createFrame(frameElement, {
plugins: [urlWatcher, catchEscapedLinks],
});Scramjet synchronizes cookies between the main page, the Controller, and the Service Worker to maintain session state across sandboxed environments.
Controller uses IndexedDB (under the name __scramjet_controller) to persist the CookieJar state.fetch request within a Frame modifies cookies, the Frame calls sendSetCookie on the controller. The controller then updates its local CookieJar, persists the state to IndexedDB, and propagates the change to the Service Worker via RPC.BroadcastChannel (__scramjet_controller_channel) is used to notify other tabs/contexts when the cookie state has been updated, triggering a reload of the persisted state.Scramjet supports different transport mechanisms via the transport option in BootstrapOptions. Currently, the following are supported:
epoxy: Uses the EpoxyClient. Requires epoxyClientPath to be provided in the configuration.libcurl: Uses the LibcurlClient. Requires libcurlClientPath to be provided in the configuration.bare: Not yet implemented; attempting to use this will throw an error.When using epoxy or libcurl, the client is initialized with a wisp URL constructed from the wispPath provided in the config and the current window's protocol and host.
The ScramjetFetchParsed interface provides enriched metadata about a request after it has been processed by Scramjet. This is used by hooks to make decisions based on the request's context.
Key fields:
url: The parsed _URL of the request.destination: The request destination (can be overridden by $dest).fetchSiteState: Tracks the worst-case Sec-Fetch-Site classification ("same-origin" | "same-site" | "cross-site") through redirects.isIframe: Indicates if the request was made by a Scramjet-defined iframe.meta: Contains URLMeta for advanced URL analysis.fetchCredentialsInclude: Boolean indicating if credentials=include was used.