@corpus-core/colibri-tor 1.1.22

package/node_modules/tor-js/src/socketProvider.ts

@@ -0,0 +1,405 @@
+/**
+ * Socket provider for connecting to Tor relays via direct TCP, WebSocket,
+ * or WebRTC.
+ *
+ * ArtiSocketProvider auto-detects available strategies based on environment:
+ * - Node.js/Deno: tries direct TCP first, then WebSocket/WebRTC if a gateway URL is set
+ * - Browsers: tries WebRTC first (if available), then WebSocket (requires gateway URL)
+ *
+ * Each `connect(target)` call returns an {@link ArtiSocket} — a uniform
+ * bidirectional byte pipe regardless of transport.
+ */
+
+// ---------------------------------------------------------------------------
+// Environment detection
+// ---------------------------------------------------------------------------
+
+const HAS_DENO = typeof (globalThis as any).Deno !== 'undefined';
+const HAS_NODE = typeof (globalThis as any).process?.versions?.node !== 'undefined';
+const HAS_RTC = typeof (globalThis as any).RTCPeerConnection !== 'undefined';
+const HAS_WS =
+  typeof (globalThis as any).WebSocket !== 'undefined' || HAS_DENO || HAS_NODE;
+
+function defaultStrategies(hasUrl: boolean): string[] {
+  const s: string[] = [];
+  if (HAS_DENO || HAS_NODE) s.push('direct');
+  if (hasUrl && HAS_RTC) s.push('webrtc');
+  if (hasUrl && HAS_WS) s.push('websocket');
+  return s;
+}
+
+// ---------------------------------------------------------------------------
+// ArtiSocket — uniform bidirectional byte pipe
+// ---------------------------------------------------------------------------
+
+/**
+ * A bidirectional byte pipe to a Tor relay.
+ *
+ * Assign `onmessage` and `onclose` after creation.
+ * Call `send(data)` with Uint8Array and `close()` when done.
+ */
+export class ArtiSocket {
+  #send: (data: Uint8Array) => void;
+  #close: () => void;
+  #closed = false;
+  #onclose: (() => void) | null = null;
+
+  /** Set by transport on error, before onclose fires. */
+  _error: string | null = null;
+
+  /** Receive callback — transport fires this with each incoming chunk. */
+  onmessage: ((data: Uint8Array) => void) | null = null;
+
+  constructor(
+    send: (data: Uint8Array) => void,
+    close: () => void,
+  ) {
+    this.#send = send;
+    this.#close = close;
+  }
+
+  /** Setter that fires immediately if close already happened. */
+  set onclose(fn: (() => void) | null) {
+    this.#onclose = fn;
+    if (this.#closed && fn) queueMicrotask(() => fn());
+  }
+  get onclose(): (() => void) | null { return this.#onclose; }
+
+  /** @internal — called by transport wrappers when the underlying connection closes. */
+  _notifyClose(): void {
+    if (this.#closed) return;
+    this.#closed = true;
+    this.#onclose?.();
+  }
+
+  send(data: Uint8Array): void {
+    this.#send(data);
+  }
+
+  close(): void {
+    this.#close();
+  }
+
+  // -- Transport factories --------------------------------------------------
+
+  /** Wrap a browser WebSocket (already open). */
+  static fromWebSocket(ws: WebSocket): ArtiSocket {
+    const sock = new ArtiSocket(
+      (data) => ws.send(data),
+      () => ws.close(),
+    );
+    ws.onmessage = (ev) => sock.onmessage?.(new Uint8Array(ev.data));
+    ws.onclose = () => sock._notifyClose();
+    return sock;
+  }
+
+  /** Wrap a WebRTC data channel (already open). */
+  static fromDataChannel(dc: RTCDataChannel): ArtiSocket {
+    const sock = new ArtiSocket(
+      (data) => dc.send(data),
+      () => dc.close(),
+    );
+    dc.onmessage = (ev) => sock.onmessage?.(new Uint8Array(ev.data));
+    dc.onclose = () => sock._notifyClose();
+    return sock;
+  }
+
+  /** Wrap a Node.js net.Socket (already connected). */
+  static fromNodeSocket(socket: any): ArtiSocket {
+    const sock = new ArtiSocket(
+      (data) => socket.write(data),
+      () => socket.destroy(),
+    );
+    socket.on('data', (buf: Buffer) => sock.onmessage?.(new Uint8Array(buf)));
+    socket.on('close', () => sock._notifyClose());
+    socket.on('error', () => {});
+    return sock;
+  }
+
+  /** Wrap a Deno TCP connection. */
+  static fromDenoConn(conn: any): ArtiSocket {
+    const sock = new ArtiSocket(
+      (data) => {
+        const writer = conn.writable.getWriter();
+        writer.write(data).then(() => writer.releaseLock());
+      },
+      () => conn.close(),
+    );
+    (async () => {
+      try {
+        for await (const chunk of conn.readable) {
+          sock.onmessage?.(new Uint8Array(chunk));
+        }
+      } catch {}
+      sock._notifyClose();
+    })();
+    return sock;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ArtiSocketProvider — multi-strategy connection manager
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for creating an ArtiSocketProvider.
+ */
+export interface ArtiSocketProviderOptions {
+  /**
+   * Gateway URL (e.g., `"https://tor-js-gateway.example.com"`).
+   * Required in browsers for WebRTC/WebSocket relay connections.
+   * Optional in Node.js/Deno (enables fast bootstrap when provided).
+   */
+  gateway?: string;
+
+  /**
+   * Ordered list of strategies to try: `"direct"`, `"webrtc"`, `"websocket"`.
+   * Defaults based on environment and whether a gateway URL is provided.
+   */
+  strategies?: string[];
+}
+
+interface TrackedEntry {
+  dc: RTCDataChannel;
+  sock: ArtiSocket | null;
+  reject: ((err: Error) => void) | null;
+}
+
+/**
+ * Opens sockets to Tor relays via configurable strategies (direct TCP,
+ * WebRTC data channels, WebSocket) with automatic fallback.
+ *
+ * The gateway URL is optional — without it, only the `direct` strategy is
+ * available (Node.js/Deno native TCP). With a gateway URL, WebRTC and
+ * WebSocket strategies become available for browser environments.
+ */
+export class ArtiSocketProvider {
+  #url: string | null;
+  #strategies: string[];
+
+  // WebRTC state (lazily created, reused across connect() calls)
+  #rtcPc: RTCPeerConnection | null = null;
+  #rtcAlive = false;
+  #signalChannel: RTCDataChannel | null = null;
+  // Tracked data channels: before open has reject, after open has sock.
+  #tracked: TrackedEntry[] = [];
+
+  constructor(options: ArtiSocketProviderOptions = {}) {
+    this.#url = options.gateway ? options.gateway.replace(/\/+$/, '') : null;
+    this.#strategies = options.strategies ?? defaultStrategies(!!this.#url);
+  }
+
+  /**
+   * Open a relay socket to the given target (e.g. "198.51.100.1:9001").
+   * Tries each configured strategy in order until one succeeds.
+   */
+  async connect(target: string): Promise<ArtiSocket> {
+    const errors: string[] = [];
+
+    for (const strategy of this.#strategies) {
+      try {
+        switch (strategy) {
+          case 'direct':
+            return await this.#connectDirect(target);
+          case 'webrtc':
+            return await this.#connectWebRTC(target);
+          case 'websocket':
+            return await this.#connectWebSocket(target);
+          default:
+            throw new Error(`unknown strategy: ${strategy}`);
+        }
+      } catch (e: any) {
+        errors.push(`${strategy}: ${e.message}`);
+      }
+    }
+
+    throw new Error(`all strategies failed for ${target}: ${errors.join('; ')}`);
+  }
+
+  /** Close WebRTC peer connection and release resources. */
+  close(): void {
+    if (this.#rtcPc) {
+      this.#rtcPc.close();
+      this.#rtcPc = null;
+      this.#rtcAlive = false;
+      this.#signalChannel = null;
+    }
+  }
+
+  // -- Direct TCP strategy (Node.js / Deno) ---------------------------------
+
+  async #connectDirect(target: string): Promise<ArtiSocket> {
+    const [host, portStr] = target.split(':');
+    const port = parseInt(portStr, 10);
+
+    if (HAS_DENO) {
+      const conn = await (globalThis as any).Deno.connect({ hostname: host, port });
+      return ArtiSocket.fromDenoConn(conn);
+    }
+
+    if (HAS_NODE) {
+      const net = await import('node:net');
+      const socket = net.createConnection({ host, port });
+      await new Promise<void>((resolve, reject) => {
+        socket.once('connect', resolve);
+        socket.once('error', reject);
+      });
+      return ArtiSocket.fromNodeSocket(socket);
+    }
+
+    throw new Error('direct TCP not available in this environment');
+  }
+
+  // -- WebSocket strategy ---------------------------------------------------
+
+  async #connectWebSocket(target: string): Promise<ArtiSocket> {
+    if (!this.#url) throw new Error('websocket strategy requires a gateway URL');
+    const wsUrl = `${this.#url.replace(/^http/, 'ws')}/socket/${target}`;
+    const ws = new WebSocket(wsUrl);
+    ws.binaryType = 'arraybuffer';
+
+    await new Promise<void>((resolve, reject) => {
+      ws.onopen = () => resolve();
+      ws.onerror = () => reject(new Error('websocket connection failed'));
+    });
+
+    return ArtiSocket.fromWebSocket(ws);
+  }
+
+  // -- WebRTC strategy ------------------------------------------------------
+
+  async #connectWebRTC(target: string): Promise<ArtiSocket> {
+    if (!this.#url) throw new Error('webrtc strategy requires a gateway URL');
+    if (typeof RTCPeerConnection === 'undefined') {
+      throw new Error('RTCPeerConnection not available');
+    }
+
+    // Create or reuse peer connection
+    if (!this.#rtcAlive) {
+      if (this.#rtcPc) this.#rtcPc.close();
+      await this.#setupRtcPeerConnection();
+    }
+
+    const dc = this.#rtcPc!.createDataChannel(target);
+    dc.binaryType = 'arraybuffer';
+
+    const entry = { dc, sock: null as ArtiSocket | null, reject: null as ((err: Error) => void) | null };
+    this.#tracked.push(entry);
+
+    // Race: channel opens vs server rejects via _signal
+    await new Promise<void>((resolve, reject) => {
+      entry.reject = reject;
+      dc.onopen = () => resolve();
+      dc.onerror = (e: any) => {
+        this.#removeTracked(entry);
+        reject(new Error(`data channel error: ${e.error?.message || e}`));
+      };
+    });
+
+    // Channel is open — dc.id now available
+    entry.reject = null;
+    const sock = ArtiSocket.fromDataChannel(dc);
+    entry.sock = sock;
+    dc.onclose = () => {
+      this.#removeTracked(entry);
+      sock._notifyClose();
+    };
+    return sock;
+  }
+
+  async #setupRtcPeerConnection(): Promise<void> {
+    const pc = new RTCPeerConnection();
+
+    // Signal channel for control messages (hello, ping/pong, rejections)
+    const signal = pc.createDataChannel('_signal');
+    signal.onmessage = (ev) => this.#handleSignalMessage(ev.data);
+
+    const offer = await pc.createOffer();
+    await pc.setLocalDescription(offer);
+
+    // Wait for ICE gathering to complete
+    await new Promise<void>((resolve) => {
+      if (pc.iceGatheringState === 'complete') return resolve();
+      pc.addEventListener('icegatheringstatechange', () => {
+        if (pc.iceGatheringState === 'complete') resolve();
+      });
+    });
+
+    const res = await fetch(`${this.#url}/rtc/connect`, {
+      method: 'POST',
+      body: JSON.stringify(pc.localDescription),
+    });
+
+    if (!res.ok) {
+      pc.close();
+      throw new Error(`rtc signaling failed: ${res.status} ${await res.text()}`);
+    }
+
+    const answer = await res.json();
+    await pc.setRemoteDescription(answer);
+
+    // Wait for connection
+    await new Promise<void>((resolve, reject) => {
+      if (pc.connectionState === 'connected') return resolve();
+      pc.addEventListener('connectionstatechange', () => {
+        if (pc.connectionState === 'connected') resolve();
+        if (pc.connectionState === 'failed') reject(new Error('WebRTC connection failed'));
+      });
+    });
+
+    this.#rtcPc = pc;
+    this.#rtcAlive = true;
+    this.#signalChannel = signal;
+
+    pc.addEventListener('connectionstatechange', () => {
+      const s = pc.connectionState;
+      if (s === 'disconnected' || s === 'closed' || s === 'failed') {
+        this.#rtcAlive = false;
+        this.#signalChannel = null;
+      }
+    });
+  }
+
+  #findTracked(sctpId: number | null, label: string) {
+    return this.#tracked.find(e => e.dc.id != null && e.dc.id === sctpId)
+      ?? this.#tracked.find(e => e.dc.label === label);
+  }
+
+  #removeTracked(entry: TrackedEntry): void {
+    const i = this.#tracked.indexOf(entry);
+    if (i !== -1) this.#tracked.splice(i, 1);
+  }
+
+  #handleSignalMessage(data: string): void {
+    try {
+      const msg = JSON.parse(data);
+      switch (msg.type) {
+        case 'rejected': {
+          const entry = this.#findTracked(msg.sctp_id, msg.channel);
+          if (entry) {
+            this.#removeTracked(entry);
+            if (entry.reject) {
+              entry.reject(new Error(`rejected: ${msg.reason}`));
+            } else if (entry.sock) {
+              entry.sock._error = msg.reason;
+              entry.sock.close();
+              entry.sock._notifyClose();
+            }
+          }
+          break;
+        }
+        case 'closed': {
+          const entry = this.#findTracked(msg.sctp_id, msg.channel);
+          if (entry) {
+            this.#removeTracked(entry);
+            if (entry.sock) {
+              entry.sock.close();
+              entry.sock._notifyClose();
+            }
+          }
+          break;
+        }
+      }
+    } catch { /* ignore malformed signal messages */ }
+  }
+}

package/node_modules/tor-js/src/storage/filesystem.ts

@@ -0,0 +1,171 @@
+import type { TorStorageSimple } from './locking.js';
+import { getNodeDeps } from './node-deps.js';
+
+function isNodeError(err: unknown): err is NodeJS.ErrnoException {
+  return err instanceof Error && 'code' in err;
+}
+
+/**
+ * Encode a storage key into a filesystem-safe filename.
+ * Alphanumeric characters pass through; everything else becomes _XX_ or _XXXX_.
+ */
+function mangleKey(key: string): string {
+  let result = '';
+  for (let i = 0; i < key.length; i++) {
+    const code = key.charCodeAt(i);
+    if (
+      (code >= 97 && code <= 122) || // a-z
+      (code >= 65 && code <= 90)  || // A-Z
+      (code >= 48 && code <= 57)     // 0-9
+    ) {
+      result += key[i];
+    } else if (code <= 0xff) {
+      result += '_' + code.toString(16).padStart(2, '0') + '_';
+    } else {
+      result += '_' + code.toString(16).padStart(4, '0') + '_';
+    }
+  }
+  return result;
+}
+
+/**
+ * Decode a mangled filename back to the original key.
+ */
+function unmangleKey(filename: string): string {
+  let result = '';
+  let i = 0;
+  while (i < filename.length) {
+    if (filename[i] === '_') {
+      // Try _XXXX_ (4-digit)
+      if (i + 5 < filename.length && filename[i + 5] === '_') {
+        const hex = filename.slice(i + 1, i + 5);
+        if (/^[0-9a-f]{4}$/i.test(hex)) {
+          result += String.fromCharCode(parseInt(hex, 16));
+          i += 6;
+          continue;
+        }
+      }
+      // Try _XX_ (2-digit)
+      if (i + 3 < filename.length && filename[i + 3] === '_') {
+        const hex = filename.slice(i + 1, i + 3);
+        if (/^[0-9a-f]{2}$/i.test(hex)) {
+          result += String.fromCharCode(parseInt(hex, 16));
+          i += 4;
+          continue;
+        }
+      }
+      result += '_';
+      i++;
+    } else {
+      result += filename[i];
+      i++;
+    }
+  }
+  return result;
+}
+
+export class FilesystemStorage implements TorStorageSimple {
+  private dirPath: string | null;
+  private name: string | null;
+  private resolvedDirPath: string | null = null;
+  private initialized = false;
+
+  constructor(dirPath: string) {
+    this.dirPath = dirPath;
+    this.name = null;
+  }
+
+  static localShare(name: string): FilesystemStorage {
+    const s = new FilesystemStorage('');
+    s.dirPath = null;
+    s.name = name;
+    return s;
+  }
+
+  private async resolvedDir(): Promise<string> {
+    if (!this.resolvedDirPath) {
+      if (this.dirPath) {
+        this.resolvedDirPath = this.dirPath;
+      } else {
+        const { os, path } = await getNodeDeps();
+        this.resolvedDirPath = path.join(os.homedir(), '.local', 'share', this.name!);
+      }
+    }
+    return this.resolvedDirPath!;
+  }
+
+  private async ensureDir(): Promise<void> {
+    if (!this.initialized) {
+      const { fs } = await getNodeDeps();
+      await fs.mkdir(await this.resolvedDir(), { recursive: true });
+      this.initialized = true;
+    }
+  }
+
+  private async filePath(key: string): Promise<string> {
+    const { path } = await getNodeDeps();
+    return path.join(await this.resolvedDir(), mangleKey(key));
+  }
+
+  async get(key: string): Promise<string | null> {
+    const { fs } = await getNodeDeps();
+    await this.ensureDir();
+    try {
+      return await fs.readFile(await this.filePath(key), 'utf-8');
+    } catch (err) {
+      if (isNodeError(err) && err.code === 'ENOENT') return null;
+      throw err;
+    }
+  }
+
+  async set(key: string, value: string): Promise<void> {
+    const { fs } = await getNodeDeps();
+    await this.ensureDir();
+    await fs.writeFile(await this.filePath(key), value, 'utf-8');
+  }
+
+  async delete(key: string): Promise<void> {
+    const { fs } = await getNodeDeps();
+    await this.ensureDir();
+    try {
+      await fs.unlink(await this.filePath(key));
+    } catch (err) {
+      if (isNodeError(err) && err.code === 'ENOENT') return;
+      throw err;
+    }
+  }
+
+  async keys(prefix: string): Promise<string[]> {
+    const { fs } = await getNodeDeps();
+    await this.ensureDir();
+    try {
+      const files = await fs.readdir(await this.resolvedDir());
+      return files
+        .map(unmangleKey)
+        .filter(k => k.startsWith(prefix))
+        .sort();
+    } catch (err) {
+      if (isNodeError(err) && err.code === 'ENOENT') return [];
+      throw err;
+    }
+  }
+
+  async getAll(prefix: string): Promise<[string, string][]> {
+    const { fs } = await getNodeDeps();
+    await this.ensureDir();
+    try {
+      const files = await fs.readdir(await this.resolvedDir());
+      const keys = files.map(unmangleKey).filter(k => k.startsWith(prefix));
+      const entries = await Promise.all(
+        keys.map(async (key): Promise<[string, string] | null> => {
+          const value = await this.get(key);
+          return value !== null ? [key, value] : null;
+        })
+      );
+      return entries.filter((e): e is [string, string] => e !== null);
+    } catch (err) {
+      if (isNodeError(err) && err.code === 'ENOENT') return [];
+      throw err;
+    }
+  }
+}

package/node_modules/tor-js/src/storage/index.ts

@@ -0,0 +1,21 @@
+export { MemoryStorage } from './memory.js';
+export { IndexedDBStorage } from './indexeddb.js';
+export { FilesystemStorage } from './filesystem.js';
+export { addLocking, type TorStorageSimple } from './locking.js';
+
+import type { TorStorage } from '#wasm';
+import { IndexedDBStorage } from './indexeddb.js';
+import { FilesystemStorage } from './filesystem.js';
+import { addLocking } from './locking.js';
+
+export function createAutoStorage(name: string = 'tor-js'): TorStorage {
+  if (typeof globalThis !== 'undefined' && typeof globalThis.indexedDB !== 'undefined') {
+    return addLocking(new IndexedDBStorage(name), name);
+  }
+  if (typeof process !== 'undefined' && process.versions?.node) {
+    return addLocking(FilesystemStorage.localShare(name), name);
+  }
+  throw new Error(
+    'No persistent storage available: need IndexedDB (browser) or filesystem (Node.js)',
+  );
+}

package/node_modules/tor-js/src/storage/indexeddb.ts

@@ -0,0 +1,99 @@
+import type { TorStorageSimple } from './locking.js';
+
+export class IndexedDBStorage implements TorStorageSimple {
+  private dbName: string;
+  private storeName = 'keyvalue';
+  private dbPromise: Promise<IDBDatabase> | null = null;
+
+  constructor(name: string = 'tor-js') {
+    this.dbName = name;
+  }
+
+  private getDB(): Promise<IDBDatabase> {
+    if (!this.dbPromise) {
+      this.dbPromise = new Promise((resolve, reject) => {
+        const request = indexedDB.open(this.dbName, 1);
+        request.onerror = () => reject(request.error);
+        request.onsuccess = () => resolve(request.result);
+        request.onupgradeneeded = (event) => {
+          const db = (event.target as IDBOpenDBRequest).result;
+          if (!db.objectStoreNames.contains(this.storeName)) {
+            db.createObjectStore(this.storeName);
+          }
+        };
+      });
+    }
+    return this.dbPromise;
+  }
+
+  async get(key: string): Promise<string | null> {
+    const db = await this.getDB();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(this.storeName, 'readonly');
+      const store = tx.objectStore(this.storeName);
+      const request = store.get(key);
+      request.onerror = () => reject(request.error);
+      request.onsuccess = () => {
+        resolve(request.result === undefined ? null : request.result);
+      };
+    });
+  }
+
+  async set(key: string, value: string): Promise<void> {
+    const db = await this.getDB();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(this.storeName, 'readwrite');
+      const store = tx.objectStore(this.storeName);
+      const request = store.put(value, key);
+      request.onerror = () => reject(request.error);
+      request.onsuccess = () => resolve();
+    });
+  }
+
+  async delete(key: string): Promise<void> {
+    const db = await this.getDB();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(this.storeName, 'readwrite');
+      const store = tx.objectStore(this.storeName);
+      const request = store.delete(key);
+      request.onerror = () => reject(request.error);
+      request.onsuccess = () => resolve();
+    });
+  }
+
+  async keys(prefix: string): Promise<string[]> {
+    const db = await this.getDB();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(this.storeName, 'readonly');
+      const store = tx.objectStore(this.storeName);
+      const request = store.getAllKeys();
+      request.onerror = () => reject(request.error);
+      request.onsuccess = () => {
+        const allKeys = request.result as string[];
+        resolve(allKeys.filter(k => k.startsWith(prefix)).sort());
+      };
+    });
+  }
+
+  async getAll(prefix: string): Promise<[string, string][]> {
+    const db = await this.getDB();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(this.storeName, 'readonly');
+      const store = tx.objectStore(this.storeName);
+      const keysReq = store.getAllKeys();
+      const valsReq = store.getAll();
+      tx.onerror = () => reject(tx.error);
+      tx.oncomplete = () => {
+        const keys = keysReq.result as string[];
+        const vals = valsReq.result as string[];
+        const result: [string, string][] = [];
+        for (let i = 0; i < keys.length; i++) {
+          if (keys[i].startsWith(prefix)) {
+            result.push([keys[i], vals[i]]);
+          }
+        }
+        resolve(result);
+      };
+    });
+  }
+}