@corpus-core/colibri-tor 1.1.22

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

@@ -0,0 +1,195 @@
+import type { TorStorage } from '#wasm';
+import { getNodeDeps } from './node-deps.js';
+
+/** Storage interface without locking — just the CRUD methods. */
+export type TorStorageSimple = Omit<TorStorage, 'tryLock' | 'unlock'>;
+
+function isNodeError(err: unknown): err is NodeJS.ErrnoException {
+  return err instanceof Error && 'code' in err;
+}
+
+/**
+ * Wrap a simple storage with platform-detected locking.
+ *
+ * - Browser: Web Locks API (`navigator.locks`)
+ * - Node.js: lock file at `~/.local/share/${name}/.lock`
+ *
+ * If the real lock can't be acquired (another tab/process holds it),
+ * the wrapper degrades gracefully: reads fall through to the inner storage,
+ * writes go to an in-memory overlay, and `tryLock()` still returns `true`.
+ */
+export function addLocking(inner: TorStorageSimple, name: string): TorStorage {
+  let hasRealLock = false;
+  let overlay: Map<string, string | null> | null = null;
+
+  // Web Locks state
+  let releaseLock: (() => void) | undefined;
+  let lockRequestDone: Promise<unknown> | undefined;
+
+  // Filesystem lock state
+  let lockPath: string | null = null;
+  let exitHandler: (() => void) | null = null;
+  let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+
+  const STALE_MS = 30_000;
+  const HEARTBEAT_MS = 10_000;
+
+  async function tryAcquireReal(): Promise<boolean> {
+    // Browser
+    if (typeof navigator !== 'undefined' && navigator.locks) {
+      let resolveAcquired!: (v: boolean) => void;
+      const acquired = new Promise<boolean>(r => { resolveAcquired = r; });
+
+      lockRequestDone = navigator.locks.request(
+        `tor-js:${name}`,
+        { ifAvailable: true },
+        (lock) => {
+          if (lock) {
+            resolveAcquired(true);
+            return new Promise<void>(r => { releaseLock = r; });
+          }
+          resolveAcquired(false);
+        },
+      );
+
+      return acquired;
+    }
+
+    // Node.js
+    if (typeof process !== 'undefined' && process.versions?.node) {
+      try {
+        const { fs, fsSync, path, os } = await getNodeDeps();
+        const dir = path.join(os.homedir(), '.local', 'share', name);
+        await fs.mkdir(dir, { recursive: true });
+        const lp = path.join(dir, '.lock');
+
+        // Try exclusive create
+        try {
+          await fs.writeFile(lp, `${process.pid}`, { flag: 'wx' });
+        } catch (err) {
+          if (!isNodeError(err) || err.code !== 'EEXIST') throw err;
+          // Check if the existing lock is stale (mtime older than STALE_MS)
+          const stat = await fs.stat(lp);
+          if (Date.now() - stat.mtimeMs < STALE_MS) return false;
+          // Stale — take over
+          await fs.writeFile(lp, `${process.pid}`);
+        }
+
+        lockPath = lp;
+
+        // Heartbeat: touch the lock file periodically so others know we're alive
+        heartbeatTimer = setInterval(async () => {
+          try {
+            const now = new Date();
+            await fs.utimes(lp, now, now);
+          } catch {}
+        }, HEARTBEAT_MS);
+        if (heartbeatTimer.unref) heartbeatTimer.unref();
+
+        exitHandler = () => {
+          try { fsSync.unlinkSync(lp); } catch {}
+        };
+        process.on('exit', exitHandler);
+
+        return true;
+      } catch (err) {
+        return false;
+      }
+    }
+
+    throw new Error("Failed to detect suitable locking mechanism");
+  }
+
+  async function releaseReal(): Promise<void> {
+    // Web Locks — resolve the held promise, then wait for the browser
+    // to actually free the lock before returning.
+    if (releaseLock) {
+      releaseLock();
+      releaseLock = undefined;
+      await lockRequestDone;
+      lockRequestDone = undefined;
+    }
+
+    // Filesystem
+    if (heartbeatTimer) {
+      clearInterval(heartbeatTimer);
+      heartbeatTimer = null;
+    }
+    if (lockPath) {
+      const { fs } = await getNodeDeps();
+      try {
+        await fs.unlink(lockPath);
+      } catch (err) {
+        if (!isNodeError(err) || err.code !== 'ENOENT') throw err;
+      }
+      lockPath = null;
+    }
+    if (exitHandler) {
+      process.removeListener('exit', exitHandler);
+      exitHandler = null;
+    }
+  }
+
+  return {
+    async get(key: string): Promise<string | null> {
+      if (overlay?.has(key)) return overlay.get(key)!;
+      return inner.get(key);
+    },
+
+    async set(key: string, value: string): Promise<void> {
+      if (overlay) {
+        overlay.set(key, value);
+        return;
+      }
+      return inner.set(key, value);
+    },
+
+    async delete(key: string): Promise<void> {
+      if (overlay) {
+        overlay.set(key, null);
+        return;
+      }
+      return inner.delete(key);
+    },
+
+    async keys(prefix: string): Promise<string[]> {
+      const base = await inner.keys(prefix);
+      if (!overlay) return base;
+      const result = new Set(base);
+      for (const [k, v] of overlay) {
+        if (!k.startsWith(prefix)) continue;
+        if (v !== null) result.add(k);
+        else result.delete(k);
+      }
+      return [...result].sort();
+    },
+
+    async getAll(prefix: string): Promise<[string, string][]> {
+      const base = await inner.getAll(prefix);
+      if (!overlay) return base;
+      const merged = new Map<string, string>(base);
+      for (const [k, v] of overlay) {
+        if (!k.startsWith(prefix)) continue;
+        if (v !== null) merged.set(k, v);
+        else merged.delete(k);
+      }
+      return [...merged.entries()];
+    },
+
+    async tryLock(): Promise<boolean> {
+      if (hasRealLock) return false;
+
+      const acquired = await tryAcquireReal();
+      hasRealLock = acquired;
+      overlay = acquired ? null : (overlay ?? new Map());
+
+      return true;
+    },
+
+    async unlock(): Promise<void> {
+      await releaseReal();
+      hasRealLock = false;
+      overlay = null;
+    },
+  };
+}

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

@@ -0,0 +1,42 @@
+import type { TorStorage } from '#wasm';
+
+export class MemoryStorage implements TorStorage {
+  private data = new Map<string, string>();
+  private locked = false;
+
+  async get(key: string): Promise<string | null> {
+    return this.data.get(key) ?? null;
+  }
+
+  async set(key: string, value: string): Promise<void> {
+    this.data.set(key, value);
+  }
+
+  async delete(key: string): Promise<void> {
+    this.data.delete(key);
+  }
+
+  async keys(prefix: string): Promise<string[]> {
+    return [...this.data.keys()].filter(k => k.startsWith(prefix)).sort();
+  }
+
+  async getAll(prefix: string): Promise<[string, string][]> {
+    const result: [string, string][] = [];
+    for (const [key, value] of this.data) {
+      if (key.startsWith(prefix)) {
+        result.push([key, value]);
+      }
+    }
+    return result;
+  }
+
+  async tryLock(): Promise<boolean> {
+    if (this.locked) return false;
+    this.locked = true;
+    return true;
+  }
+
+  async unlock(): Promise<void> {
+    this.locked = false;
+  }
+}

package/node_modules/tor-js/src/storage/node-deps.ts

@@ -0,0 +1,23 @@
+export type NodeDeps = {
+  fs: typeof import('node:fs/promises');
+  fsSync: typeof import('node:fs');
+  os: typeof import('node:os');
+  path: typeof import('node:path');
+};
+
+let promise: Promise<NodeDeps> | undefined;
+
+export function getNodeDeps(): Promise<NodeDeps> {
+  if (!promise) {
+    promise = (async () => {
+      const [fs, fsSync, os, path] = await Promise.all([
+        import('node:fs/promises').then(m => m.default ?? m),
+        import('node:fs').then(m => m.default ?? m),
+        import('node:os').then(m => m.default ?? m),
+        import('node:path').then(m => m.default ?? m),
+      ]);
+      return { fs, fsSync, os, path };
+    })();
+  }
+  return promise;
+}

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

@@ -0,0 +1,48 @@
+import type { Log } from './Log.js';
+import type { TorStorage } from '#wasm';
+import type { ArtiSocketProvider } from './socketProvider.js';
+
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error';
+
+/**
+ * Options for creating a TorClient.
+ *
+ * In browsers, provide a gateway URL for WebSocket/WebRTC relay connections
+ * and fast bootstrap. In Node.js/Deno, the gateway connects via direct TCP
+ * without a URL; providing one enables fast bootstrap from that server.
+ */
+export type TorClientOptions = {
+  /** Gateway URL (e.g., `"https://tor-js-gateway.voltrevo.com"`). Required in browsers for relay connections; optional in Node.js/Deno (enables fast bootstrap). */
+  gateway?: string;
+
+  /**
+   * Optional logger instance.
+   * Note: WASM logging is global, so all TorClient instances receive all WASM
+   * log events, not just their own. This is because wasm-bindgen generates a
+   * single module-level instance (`let wasm;`), so all Rust global state
+   * (including the tracing subscriber) is shared.
+   */
+  log?: Log;
+
+  /** Optional storage for persistent state (implements TorStorage). */
+  storage?: TorStorage;
+
+  /**
+   * Minimum log level for this client's log listener. Defaults to 'debug'.
+   * Can be changed at runtime via `TorClient.setLogLevel()`.
+   * The WASM subscriber auto-widens to the broadest level across all clients.
+   */
+  logLevel?: LogLevel;
+
+  /** Optional custom socket provider. When set, overrides the default ArtiSocketProvider created from the gateway URL. */
+  socketProvider?: ArtiSocketProvider;
+};
+
+export type { TorStorage } from '#wasm';
+
+export interface FetchInit {
+  method?: string;
+  headers?: Record<string, string>;
+  body?: string | Uint8Array | ArrayBuffer;
+  signal?: AbortSignal;
+}

package/node_modules/tor-js/src/wasm-base64-data.d.ts

@@ -0,0 +1,3 @@
+declare module '#wasm-base64-data' {
+  export const wasmBase64: string;
+}

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

@@ -0,0 +1,135 @@
+import './polyfills.js';
+import initWasm, {
+  init as wasmInit,
+  setLogCallback as wasmSetLogCallback,
+  setLogLevel as wasmSetLogLevel,
+  TorClient as WasmTorClient,
+  TorClientOptions as WasmTorClientOptions,
+} from '#wasm';
+
+export { WasmTorClient, WasmTorClientOptions };
+
+// ============================================================================
+// Log listener management
+// ============================================================================
+
+type WasmLogCallback = (level: string, target: string, message: string) => void;
+
+const LEVEL_ORDER = ['trace', 'debug', 'info', 'warn', 'error'] as const;
+
+function levelIndex(level: string): number {
+  const idx = LEVEL_ORDER.indexOf(level as typeof LEVEL_ORDER[number]);
+  return idx === -1 ? 1 : idx; // default to debug
+}
+
+interface LogListener {
+  callback: WasmLogCallback;
+  levelIdx: number;
+}
+
+const logListeners = new Map<WasmLogCallback, LogListener>();
+
+/** Recompute the broadest level across all listeners and update the WASM filter. */
+function syncWasmLogLevel(): void {
+  let broadestIdx = LEVEL_ORDER.length - 1; // start at narrowest (error)
+  for (const listener of logListeners.values()) {
+    if (listener.levelIdx < broadestIdx) {
+      broadestIdx = listener.levelIdx;
+    }
+  }
+  wasmSetLogLevel(LEVEL_ORDER[broadestIdx]);
+}
+
+/**
+ * Register a log callback at a given level. The WASM subscriber is
+ * automatically widened to the broadest level across all listeners.
+ * Each listener only receives events at or above its own level.
+ * Returns an unregister function.
+ */
+export function addLogListener(cb: WasmLogCallback, level: string = 'debug'): () => void {
+  logListeners.set(cb, { callback: cb, levelIdx: levelIndex(level) });
+  syncWasmLogLevel();
+  return () => {
+    logListeners.delete(cb);
+    if (logListeners.size > 0) {
+      syncWasmLogLevel();
+    }
+  };
+}
+
+/**
+ * Update the level for an existing listener and re-sync the WASM filter.
+ */
+export function setListenerLevel(cb: WasmLogCallback, level: string): void {
+  const listener = logListeners.get(cb);
+  if (listener) {
+    listener.levelIdx = levelIndex(level);
+    syncWasmLogLevel();
+  }
+}
+
+// ============================================================================
+// WASM initialization
+// ============================================================================
+
+type WasmSourceProvider = () => Promise<BufferSource | Uint8Array>;
+
+let initPromise: Promise<void> | null = null;
+let customWasmUrl: string | URL | undefined;
+let wasmSourceProvider: WasmSourceProvider | undefined;
+
+/**
+ * Override the WASM binary URL. Must be called before any TorClient is created.
+ */
+export function setWasmUrl(url: string | URL): void {
+  if (initPromise) {
+    throw new Error('setWasmUrl() must be called before any TorClient is created');
+  }
+  customWasmUrl = url;
+}
+
+/**
+ * Set a custom WASM source provider. Called by entry points to configure
+ * how the WASM binary is loaded (e.g. base64 decode, CDN fetch).
+ * Must be called before any TorClient is created.
+ */
+export function setWasmSourceProvider(provider: WasmSourceProvider): void {
+  if (initPromise) {
+    throw new Error('setWasmSourceProvider() must be called before any TorClient is created');
+  }
+  wasmSourceProvider = provider;
+}
+
+/**
+ * Ensures the WASM module is loaded and initialized. Idempotent.
+ */
+export async function ensureWasmInitialized(): Promise<void> {
+  if (initPromise) return initPromise;
+  initPromise = doInit();
+  return initPromise;
+}
+
+async function doInit(): Promise<void> {
+  if (customWasmUrl) {
+    await initWasm({ module_or_path: customWasmUrl });
+  } else if (wasmSourceProvider) {
+    await initWasm({ module_or_path: await wasmSourceProvider() });
+  } else {
+    throw new Error(
+      'No WASM source configured. Import from a specific entry point '
+      + '(tor-js/wasm-base64, tor-js/wasm-cdn, or tor-js/wasm-file) '
+      + 'or call setWasmUrl() before creating a TorClient.',
+    );
+  }
+  wasmInit();
+
+  // Install a single fan-out callback that dispatches to matching listeners
+  wasmSetLogCallback((level: string, target: string, message: string) => {
+    const lvl = levelIndex(level);
+    for (const listener of logListeners.values()) {
+      if (lvl >= listener.levelIdx) {
+        listener.callback(level, target, message);
+      }
+    }
+  });
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+    "name": "@corpus-core/colibri-tor",
+    "version": "1.1.22",
+    "description": "Tor network transport for Colibri Stateless. Routes RPC requests through Tor for enhanced privacy -- via Arti WASM in browsers, via SOCKS5 proxy in Node.js.",
+    "main": "dist/index.js",
+    "type": "module",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        },
+        "./browser": {
+            "types": "./dist/browser.d.ts",
+            "import": "./dist/browser.js"
+        },
+        "./node": {
+            "types": "./dist/node.d.ts",
+            "import": "./dist/node.js"
+        }
+    },
+    "files": [
+        "dist",
+        "README.md"
+    ],
+    "bundleDependencies": [
+        "tor-js"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "build:arti": "bash scripts/build-arti.sh",
+        "test": "node --test test/*.test.mjs"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/corpus-core/c4.git",
+        "directory": "bindings/emscripten/tor"
+    },
+    "keywords": [
+        "ethereum",
+        "tor",
+        "arti",
+        "privacy",
+        "socks5",
+        "colibri",
+        "stateless"
+    ],
+    "author": "Simon Jentzsch <simon@corpus.io>",
+    "license": "MIT",
+    "dependencies": {
+        "tor-js": "file:.arti-build/crates/tor-js/ts-wrapper"
+    },
+    "peerDependencies": {
+        "@corpus-core/colibri-stateless": ">=0.1.0"
+    },
+    "peerDependenciesMeta": {
+        "@corpus-core/colibri-stateless": {
+            "optional": true
+        }
+    },
+    "devDependencies": {
+        "typescript": "^5.5.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}