@corpus-core/colibri-tor 1.1.22

package/README.md

@@ -0,0 +1,90 @@
+<img src="c4_logo.png" alt="C4 Logo" width="300"/>
+
+# @corpus-core/colibri-tor
+
+Tor network transport for [Colibri Stateless](https://github.com/corpus-core/colibri-stateless). Routes all RPC requests through [Tor](https://www.torproject.org/) for enhanced network-level privacy.
+
+- **Browser**: Uses [Arti](https://gitlab.torproject.org/tpo/core/arti) compiled to WebAssembly via [tor-js](https://github.com/voltrevo/arti) -- no browser extension or external software needed.
+- **Node.js**: Connects to a locally running Tor SOCKS5 proxy -- zero dependencies, pure `node:net`/`node:tls` implementation.
+
+## Installation
+
+```sh
+npm install @corpus-core/colibri-tor @corpus-core/colibri-stateless
+```
+
+## Usage
+
+### Browser (Arti WASM)
+
+```typescript
+import Colibri from '@corpus-core/colibri-stateless';
+import { createBrowserFetch } from '@corpus-core/colibri-tor/browser';
+
+// Bootstrap starts immediately in the background (no await needed).
+// The first actual request will wait for bootstrap to complete.
+const client = new Colibri({
+  fetch: createBrowserFetch(),
+  prover: ['https://mainnet.colibri-proof.tech']
+});
+
+// This request will await Tor bootstrap if still in progress
+const balance = await client.request({
+  method: 'eth_getBalance',
+  params: ['0x...', 'latest']
+});
+```
+
+### Node.js (SOCKS5 Proxy)
+
+Start a Tor daemon first (e.g. `tor --SocksPort 9050` or via your system's package manager), then:
+
+```typescript
+import Colibri from '@corpus-core/colibri-stateless';
+import { createSocksFetch } from '@corpus-core/colibri-tor/node';
+
+const torFetch = await createSocksFetch({ socksPort: 9050 });
+
+const client = new Colibri({
+  fetch: torFetch,
+  prover: ['https://mainnet.colibri-proof.tech']
+});
+```
+
+## API
+
+### `createBrowserFetch(options?): typeof fetch`
+
+Creates a `fetch`-compatible function that routes requests through Tor via Arti WASM. Browser only. Returns synchronously -- Tor bootstrap starts immediately in the background and the first actual request awaits completion if needed.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `gateway` | `string` | `'https://tor-js-gateway.voltrevo.com'` | WebSocket/WebRTC gateway URL for Tor relay connections |
+| `onBootstrap` | `(ms: number) => void` | `undefined` | Callback when Tor bootstrap completes |
+| `logLevel` | `LogLevel` | `'warn'` | Arti log level (`'trace'` \| `'debug'` \| `'info'` \| `'warn'` \| `'error'`) |
+
+### `createSocksFetch(options?): Promise<typeof fetch>`
+
+Creates a `fetch`-compatible function that routes requests through a local Tor SOCKS5 proxy. Node.js only.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `socksHost` | `string` | `'127.0.0.1'` | SOCKS5 proxy hostname |
+| `socksPort` | `number` | `9050` | SOCKS5 proxy port |
+
+## Building tor-js from source
+
+Until `tor-js` is published on npm, the CI automatically builds the Arti WASM package from source and bundles it with `@corpus-core/colibri-tor` via `bundleDependencies`. Users installing the published package get `tor-js` included -- no extra steps needed.
+
+For local development, you can trigger the same build manually:
+
+```sh
+# Requires: Rust toolchain, wasm-pack, Node.js
+npm run build:arti
+```
+
+This clones [voltrevo/arti](https://github.com/voltrevo/arti), builds the WASM package, and installs the resulting `tor-js` ts-wrapper into `node_modules/`.
+
+## License
+
+MIT

package/dist/browser.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Copyright (c) 2025 corpus.core
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import type { ThorBrowserOptions } from './types.js';
+import { DEFAULT_GATEWAY } from './types.js';
+export type { ThorBrowserOptions };
+export { DEFAULT_GATEWAY };
+/**
+ * Create a `fetch`-compatible function that routes HTTP requests through the
+ * Tor network using Arti compiled to WebAssembly.  Browser only.
+ *
+ * Tor bootstrap starts immediately but does **not** block the returned
+ * function.  The first actual `fetch` call will await the bootstrap if it
+ * has not completed yet.  This allows the application to continue
+ * initializing while Tor connects in the background.
+ *
+ * ```typescript
+ * // Bootstrap starts immediately, returns without blocking
+ * const torFetch = createBrowserFetch();
+ * const client = new Colibri({ fetch: torFetch });
+ * // ... app continues initializing ...
+ * // First request will await bootstrap completion if still in progress
+ * await client.request({ method: 'eth_blockNumber' });
+ * ```
+ *
+ * @param options - Browser transport options (gateway URL, log level, etc.)
+ * @return A `fetch`-compatible function that routes through Tor
+ */
+export declare function createBrowserFetch(options?: ThorBrowserOptions): typeof globalThis.fetch;

package/dist/browser.js

@@ -0,0 +1,96 @@
+/**
+ * Copyright (c) 2025 corpus.core
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import { DEFAULT_GATEWAY } from './types.js';
+export { DEFAULT_GATEWAY };
+// tor-js is loaded dynamically so the import path can switch between vendored
+// artifacts (built from source via scripts/build-arti.sh) and the future npm
+// package without changing this file.
+let torJsImport = null;
+function getTorJs() {
+    if (!torJsImport) {
+        // Dynamic import -- resolved at runtime.  When tor-js is published on
+        // npm this will become `import('tor-js')`.  Until then, the vendored
+        // build (src/vendor/tor-js.js) is used via the package.json "imports"
+        // map or a direct relative path.
+        torJsImport = import('tor-js').catch(() => {
+            throw new Error('tor-js is not installed. Install it via npm (once published) ' +
+                'or run `npm run build:arti` to build from source.');
+        });
+    }
+    return torJsImport;
+}
+/**
+ * Create a `fetch`-compatible function that routes HTTP requests through the
+ * Tor network using Arti compiled to WebAssembly.  Browser only.
+ *
+ * Tor bootstrap starts immediately but does **not** block the returned
+ * function.  The first actual `fetch` call will await the bootstrap if it
+ * has not completed yet.  This allows the application to continue
+ * initializing while Tor connects in the background.
+ *
+ * ```typescript
+ * // Bootstrap starts immediately, returns without blocking
+ * const torFetch = createBrowserFetch();
+ * const client = new Colibri({ fetch: torFetch });
+ * // ... app continues initializing ...
+ * // First request will await bootstrap completion if still in progress
+ * await client.request({ method: 'eth_blockNumber' });
+ * ```
+ *
+ * @param options - Browser transport options (gateway URL, log level, etc.)
+ * @return A `fetch`-compatible function that routes through Tor
+ */
+export function createBrowserFetch(options = {}) {
+    const gateway = options.gateway ?? DEFAULT_GATEWAY;
+    // Kick off bootstrap eagerly -- the promise is shared across all requests.
+    const startTime = Date.now();
+    const clientReady = getTorJs().then(async ({ TorClient }) => {
+        const client = new TorClient({
+            gateway,
+            logLevel: options.logLevel ?? 'warn',
+        });
+        await client.ready();
+        options.onBootstrap?.(Date.now() - startTime);
+        return client;
+    });
+    const torFetch = async (input, init) => {
+        const client = await clientReady;
+        const url = typeof input === 'string'
+            ? input
+            : input instanceof URL
+                ? input.href
+                : input.url;
+        // tor-js TorClient.fetch() returns a Response-compatible object.
+        // We validate the essential properties to catch API mismatches early.
+        const response = await client.fetch(url, {
+            method: init?.method,
+            headers: init?.headers,
+            body: init?.body,
+        });
+        if (typeof response?.status !== 'number') {
+            throw new Error('tor-js returned an invalid response object (missing status)');
+        }
+        return response;
+    };
+    return torFetch;
+}

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Copyright (c) 2025 corpus.core
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
+ */
+export { createBrowserFetch, DEFAULT_GATEWAY } from './browser.js';
+export { createSocksFetch } from './node.js';
+export type { ThorBrowserOptions, ThorNodeOptions, LogLevel } from './types.js';

package/dist/index.js

@@ -0,0 +1,24 @@
+/**
+ * Copyright (c) 2025 corpus.core
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
+ */
+export { createBrowserFetch, DEFAULT_GATEWAY } from './browser.js';
+export { createSocksFetch } from './node.js';

package/dist/node.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Copyright (c) 2025 corpus.core
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
+ */
+import type { ThorNodeOptions } from './types.js';
+export type { ThorNodeOptions };
+/**
+ * Create a `fetch`-compatible function that routes HTTP requests through a
+ * locally running Tor SOCKS5 proxy.  Node.js only.
+ *
+ * The user must start the Tor daemon themselves (e.g. `tor --SocksPort 9050`).
+ *
+ * @param options - Node.js transport options (SOCKS host/port)
+ * @return A `fetch`-compatible function routing through the Tor SOCKS5 proxy
+ */
+export declare function createSocksFetch(options?: ThorNodeOptions): Promise<typeof globalThis.fetch>;

package/dist/node.js

@@ -0,0 +1,275 @@
+/**
+ * Copyright (c) 2025 corpus.core
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
+ */
+const SOCKS5_HANDSHAKE_TIMEOUT_MS = 30000;
+const HTTP_RESPONSE_TIMEOUT_MS = 60000;
+const MAX_RESPONSE_SIZE = 64 * 1024 * 1024; // 64 MiB
+/**
+ * Perform a SOCKS5 CONNECT handshake over an existing TCP socket.
+ *
+ * Implements RFC 1928 (no-auth) + CONNECT to a domain:port target.
+ * Uses buffered reads to handle TCP stream fragmentation correctly.
+ * The socket is left connected to the remote host on success.
+ */
+async function socks5Connect(socksHost, socksPort, targetHost, targetPort) {
+    const net = await import('node:net');
+    const hostBuf = Buffer.from(targetHost, 'utf-8');
+    if (hostBuf.length > 255) {
+        throw new Error(`SOCKS5: hostname too long (${hostBuf.length} bytes, max 255)`);
+    }
+    return new Promise((resolve, reject) => {
+        const socket = net.createConnection(socksPort, socksHost, () => {
+            socket.write(Buffer.from([0x05, 0x01, 0x00]));
+        });
+        socket.setTimeout(SOCKS5_HANDSHAKE_TIMEOUT_MS);
+        socket.once('timeout', () => {
+            socket.destroy();
+            reject(new Error('SOCKS5 handshake timeout'));
+        });
+        let phase = 'greeting';
+        let buffer = Buffer.alloc(0);
+        socket.once('error', (err) => {
+            socket.destroy();
+            reject(err);
+        });
+        socket.on('data', (chunk) => {
+            buffer = Buffer.concat([buffer, chunk]);
+            if (phase === 'greeting') {
+                if (buffer.length < 2)
+                    return;
+                if (buffer[0] !== 0x05 || buffer[1] !== 0x00) {
+                    socket.destroy();
+                    reject(new Error(`SOCKS5 handshake failed: server chose method ${buffer[1]}`));
+                    return;
+                }
+                buffer = buffer.subarray(2);
+                phase = 'connect';
+                const req = Buffer.alloc(4 + 1 + hostBuf.length + 2);
+                req[0] = 0x05; // VER
+                req[1] = 0x01; // CMD: CONNECT
+                req[2] = 0x00; // RSV
+                req[3] = 0x03; // ATYP: DOMAINNAME
+                req[4] = hostBuf.length;
+                hostBuf.copy(req, 5);
+                req.writeUInt16BE(targetPort, 5 + hostBuf.length);
+                socket.write(req);
+            }
+            if (phase === 'connect') {
+                // Minimum CONNECT response: VER(1) + REP(1) + RSV(1) + ATYP(1) + addr + port(2)
+                // For ATYP=1 (IPv4): 4+4+2 = 10 bytes total
+                if (buffer.length < 4)
+                    return;
+                let expectedLen;
+                switch (buffer[3]) {
+                    case 0x01:
+                        expectedLen = 10;
+                        break; // IPv4: 4 header + 4 addr + 2 port
+                    case 0x04:
+                        expectedLen = 22;
+                        break; // IPv6: 4 header + 16 addr + 2 port
+                    case 0x03: { // Domain: 4 header + 1 len + N + 2 port
+                        if (buffer.length < 5)
+                            return;
+                        expectedLen = 5 + buffer[4] + 2;
+                        break;
+                    }
+                    default:
+                        expectedLen = 10;
+                        break;
+                }
+                if (buffer.length < expectedLen)
+                    return;
+                if (buffer[0] !== 0x05) {
+                    socket.destroy();
+                    reject(new Error('SOCKS5 connect: unexpected version'));
+                    return;
+                }
+                if (buffer[1] !== 0x00) {
+                    socket.destroy();
+                    const codes = {
+                        0x01: 'general failure',
+                        0x02: 'connection not allowed',
+                        0x03: 'network unreachable',
+                        0x04: 'host unreachable',
+                        0x05: 'connection refused',
+                        0x06: 'TTL expired',
+                        0x07: 'command not supported',
+                        0x08: 'address type not supported',
+                    };
+                    reject(new Error(`SOCKS5 connect failed: ${codes[buffer[1]] || `code ${buffer[1]}`}`));
+                    return;
+                }
+                socket.setTimeout(0);
+                socket.removeAllListeners('data');
+                socket.removeAllListeners('error');
+                socket.removeAllListeners('timeout');
+                resolve(socket);
+            }
+        });
+    });
+}
+/**
+ * Perform an HTTP request through an established SOCKS5 tunnel.
+ *
+ * For HTTPS targets, wraps the raw socket in TLS using `node:tls`.
+ * Uses HTTP/1.0 to avoid chunked transfer-encoding complexity.
+ * Returns a standard Web API `Response` (Node 18+).
+ */
+async function httpOverSocks(socksHost, socksPort, url, init) {
+    const parsed = new URL(url);
+    const isHttps = parsed.protocol === 'https:';
+    const targetPort = parsed.port ? parseInt(parsed.port) : (isHttps ? 443 : 80);
+    let socket = await socks5Connect(socksHost, socksPort, parsed.hostname, targetPort);
+    if (isHttps) {
+        const tls = await import('node:tls');
+        const tlsSocket = tls.connect({
+            socket: socket,
+            servername: parsed.hostname,
+        });
+        await new Promise((resolve, reject) => {
+            tlsSocket.once('secureConnect', resolve);
+            tlsSocket.once('error', reject);
+        });
+        socket = tlsSocket;
+    }
+    const method = init?.method ?? 'GET';
+    if (!/^[A-Z]+$/.test(method)) {
+        socket.destroy();
+        throw new Error(`Invalid HTTP method: ${method}`);
+    }
+    const bodyStr = init?.body != null
+        ? (typeof init.body === 'string' ? init.body : new TextDecoder().decode(init.body))
+        : undefined;
+    const bodyBuf = bodyStr ? Buffer.from(bodyStr, 'utf-8') : undefined;
+    const headers = {
+        'Host': parsed.host,
+        'Connection': 'close',
+    };
+    if (init?.headers) {
+        const h = init.headers;
+        if (h instanceof Headers) {
+            h.forEach((v, k) => { headers[k] = v; });
+        }
+        else if (Array.isArray(h)) {
+            for (const [k, v] of h)
+                headers[k] = v;
+        }
+        else {
+            Object.assign(headers, h);
+        }
+    }
+    if (bodyBuf) {
+        headers['Content-Length'] = bodyBuf.length.toString();
+    }
+    // Validate headers against CRLF injection (CWE-113)
+    for (const [k, v] of Object.entries(headers)) {
+        if (/[\r\n]/.test(k) || /[\r\n]/.test(v)) {
+            socket.destroy();
+            throw new Error('Invalid header: CR/LF characters not allowed in header name or value');
+        }
+    }
+    // HTTP/1.0 avoids chunked transfer-encoding; Connection: close ensures
+    // the server closes the socket after the response.
+    const path = parsed.pathname + parsed.search;
+    let reqStr = `${method} ${path} HTTP/1.0\r\n`;
+    for (const [k, v] of Object.entries(headers)) {
+        reqStr += `${k}: ${v}\r\n`;
+    }
+    reqStr += '\r\n';
+    return new Promise((resolve, reject) => {
+        socket.setTimeout(HTTP_RESPONSE_TIMEOUT_MS);
+        socket.once('timeout', () => {
+            socket.destroy();
+            reject(new Error('HTTP response timeout'));
+        });
+        socket.once('error', (err) => {
+            socket.destroy();
+            reject(err);
+        });
+        let totalSize = 0;
+        const chunks = [];
+        socket.on('data', (chunk) => {
+            totalSize += chunk.length;
+            if (totalSize > MAX_RESPONSE_SIZE) {
+                socket.destroy();
+                reject(new Error(`Response too large (>${MAX_RESPONSE_SIZE} bytes)`));
+                return;
+            }
+            chunks.push(chunk);
+        });
+        socket.on('end', () => {
+            socket.destroy();
+            try {
+                const raw = Buffer.concat(chunks);
+                const headerEnd = raw.indexOf('\r\n\r\n');
+                if (headerEnd === -1) {
+                    reject(new Error('Malformed HTTP response: no header/body separator'));
+                    return;
+                }
+                const headerStr = raw.subarray(0, headerEnd).toString('utf-8');
+                const body = raw.subarray(headerEnd + 4);
+                const [statusLine, ...headerLines] = headerStr.split('\r\n');
+                const statusMatch = statusLine.match(/^HTTP\/[\d.]+ (\d+)/);
+                const status = statusMatch ? parseInt(statusMatch[1]) : 0;
+                const respHeaders = new Headers();
+                for (const line of headerLines) {
+                    const idx = line.indexOf(':');
+                    if (idx > 0) {
+                        respHeaders.append(line.substring(0, idx).trim(), line.substring(idx + 1).trim());
+                    }
+                }
+                resolve(new Response(body, { status, headers: respHeaders }));
+            }
+            catch (e) {
+                reject(e);
+            }
+        });
+        socket.write(reqStr);
+        if (bodyBuf)
+            socket.write(bodyBuf);
+    });
+}
+/**
+ * Create a `fetch`-compatible function that routes HTTP requests through a
+ * locally running Tor SOCKS5 proxy.  Node.js only.
+ *
+ * The user must start the Tor daemon themselves (e.g. `tor --SocksPort 9050`).
+ *
+ * @param options - Node.js transport options (SOCKS host/port)
+ * @return A `fetch`-compatible function routing through the Tor SOCKS5 proxy
+ */
+export async function createSocksFetch(options = {}) {
+    const host = options.socksHost ?? '127.0.0.1';
+    const port = options.socksPort ?? 9050;
+    if (port < 1 || port > 65535 || !Number.isInteger(port)) {
+        throw new Error(`Invalid SOCKS port: ${port} (must be 1-65535)`);
+    }
+    const socksFetch = async (input, init) => {
+        const url = typeof input === 'string'
+            ? input
+            : input instanceof URL
+                ? input.href
+                : input.url;
+        return httpOverSocks(host, port, url, init);
+    };
+    return socksFetch;
+}

package/dist/types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Copyright (c) 2025 corpus.core
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
+ */
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error';
+export declare const DEFAULT_GATEWAY = "https://tor-js-gateway.voltrevo.com";
+export interface ThorBrowserOptions {
+    /** WebSocket/WebRTC gateway URL for Tor relay connections.
+     *  Default: `'https://tor-js-gateway.voltrevo.com'`. */
+    gateway?: string;
+    /** Callback invoked when Tor bootstrap completes, with elapsed time in ms. */
+    onBootstrap?: (elapsedMs: number) => void;
+    /** Arti log level. Default: `'warn'`. */
+    logLevel?: LogLevel;
+}
+export interface ThorNodeOptions {
+    /** SOCKS5 proxy hostname. Default: `'127.0.0.1'`. */
+    socksHost?: string;
+    /** SOCKS5 proxy port. Default: `9050`. */
+    socksPort?: number;
+}

package/dist/types.js

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) 2025 corpus.core
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of
+ * this software and associated documentation files (the "Software"), to deal in
+ * the Software without restriction, including without limitation the rights to
+ * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ * the Software, and to permit persons to whom the Software is furnished to do so,
+ * subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
+ */
+export const DEFAULT_GATEWAY = 'https://tor-js-gateway.voltrevo.com';