@corpus-core/colibri-tor 1.1.22

package/node_modules/tor-js/dist/wasm.d.ts

@@ -0,0 +1,31 @@
+import './polyfills.js';
+import { TorClient as WasmTorClient, TorClientOptions as WasmTorClientOptions } from '#wasm';
+export { WasmTorClient, WasmTorClientOptions };
+type WasmLogCallback = (level: string, target: string, message: string) => void;
+/**
+ * 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 declare function addLogListener(cb: WasmLogCallback, level?: string): () => void;
+/**
+ * Update the level for an existing listener and re-sync the WASM filter.
+ */
+export declare function setListenerLevel(cb: WasmLogCallback, level: string): void;
+type WasmSourceProvider = () => Promise<BufferSource | Uint8Array>;
+/**
+ * Override the WASM binary URL. Must be called before any TorClient is created.
+ */
+export declare function setWasmUrl(url: string | URL): void;
+/**
+ * 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 declare function setWasmSourceProvider(provider: WasmSourceProvider): void;
+/**
+ * Ensures the WASM module is loaded and initialized. Idempotent.
+ */
+export declare function ensureWasmInitialized(): Promise<void>;
+//# sourceMappingURL=wasm.d.ts.map

package/node_modules/tor-js/dist/wasm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wasm.d.ts","sourceRoot":"","sources":["../src/wasm.ts"],"names":[],"mappings":"AAAA,OAAO,gBAAgB,CAAC;AACxB,OAAiB,EAIf,SAAS,IAAI,aAAa,EAC1B,gBAAgB,IAAI,oBAAoB,EACzC,MAAM,OAAO,CAAC;AAEf,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,CAAC;AAM/C,KAAK,eAAe,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;AA2BhF;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,eAAe,EAAE,KAAK,GAAE,MAAgB,GAAG,MAAM,IAAI,CASvF;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAMzE;AAMD,KAAK,kBAAkB,GAAG,MAAM,OAAO,CAAC,YAAY,GAAG,UAAU,CAAC,CAAC;AAMnE;;GAEG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI,CAKlD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAKxE;AAED;;GAEG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAI3D"}

package/node_modules/tor-js/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "tor-js",
+  "version": "0.3.0",
+  "description": "TypeScript Tor client using arti via WASM",
+  "type": "module",
+  "main": "dist/entryPoints/wasm-cdn/index.js",
+  "types": "dist/entryPoints/wasm-cdn/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/entryPoints/wasm-cdn/index.d.ts",
+      "import": "./dist/entryPoints/wasm-cdn/index.js"
+    },
+    "./wasm-cdn": {
+      "types": "./dist/entryPoints/wasm-cdn/index.d.ts",
+      "import": "./dist/entryPoints/wasm-cdn/index.js"
+    },
+    "./wasm-file": {
+      "types": "./dist/entryPoints/wasm-file/index.d.ts",
+      "import": "./dist/entryPoints/wasm-file/index.js"
+    },
+    "./wasm-base64": {
+      "types": "./dist/entryPoints/wasm-base64/index.d.ts",
+      "import": "./dist/entryPoints/wasm-base64/index.js"
+    },
+    "./singleton": {
+      "types": "./dist/entryPoints/wasm-cdn/singleton.d.ts",
+      "import": "./dist/entryPoints/wasm-cdn/singleton.js"
+    },
+    "./wasm-cdn/singleton": {
+      "types": "./dist/entryPoints/wasm-cdn/singleton.d.ts",
+      "import": "./dist/entryPoints/wasm-cdn/singleton.js"
+    },
+    "./wasm-file/singleton": {
+      "types": "./dist/entryPoints/wasm-file/singleton.d.ts",
+      "import": "./dist/entryPoints/wasm-file/singleton.js"
+    },
+    "./wasm-base64/singleton": {
+      "types": "./dist/entryPoints/wasm-base64/singleton.d.ts",
+      "import": "./dist/entryPoints/wasm-base64/singleton.js"
+    }
+  },
+  "imports": {
+    "#wasm": "./dist/wasm-pkg/tor_js.js",
+    "#wasm-base64-data": "./dist/wasm-base64-data.js"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "node build.mjs",
+    "clean": "rm -rf dist src/wasm-pkg"
+  },
+  "author": "Andrew Morris",
+  "license": "MIT OR Apache-2.0",
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "tsup": "^8.3.5",
+    "typescript": "~5.7.3"
+  }
+}

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

@@ -0,0 +1,100 @@
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error';
+
+interface LogConstructorParams {
+  rawLog?: (level: LogLevel, ...args: unknown[]) => void;
+  parentStartTime?: number;
+  namePrefix?: string;
+}
+
+export class Log {
+  private rawLog: (level: LogLevel, ...args: unknown[]) => void;
+  private parentStartTime: number;
+  private namePrefix: string;
+
+  constructor(params: LogConstructorParams = {}) {
+    this.parentStartTime = params.parentStartTime ?? Date.now();
+    this.namePrefix = params.namePrefix ?? '';
+    this.rawLog = params.rawLog ?? this.defaultRawLog.bind(this);
+  }
+
+  child(name: string): Log {
+    const newPrefix = this.namePrefix ? `${this.namePrefix}.${name}` : name;
+    return new Log({
+      rawLog: this.rawLog,
+      parentStartTime: this.parentStartTime,
+      namePrefix: newPrefix,
+    });
+  }
+
+  trace(...args: unknown[]): void {
+    this.log('trace', ...args);
+  }
+
+  debug(...args: unknown[]): void {
+    this.log('debug', ...args);
+  }
+
+  info(...args: unknown[]): void {
+    this.log('info', ...args);
+  }
+
+  warn(...args: unknown[]): void {
+    this.log('warn', ...args);
+  }
+
+  error(...args: unknown[]): void {
+    this.log('error', ...args);
+  }
+
+  /** @internal Create a callback for WASM setLogCallback */
+  _makeWasmCallback(): (level: string, target: string, message: string) => void {
+    const levels: ReadonlySet<string> = new Set(['trace', 'debug', 'info', 'warn', 'error']);
+    return (level: string, target: string, message: string) => {
+      if (!levels.has(level)) {
+        this.log('error', `unexpected log level from WASM: ${JSON.stringify(level)}`);
+        level = 'debug';
+      }
+      this.child(target).log(level as LogLevel, message);
+    };
+  }
+
+  private log(level: LogLevel, ...args: unknown[]): void {
+    const elapsed = Date.now() - this.parentStartTime;
+    const timestamp = formatTimestamp(elapsed);
+    if (this.namePrefix) {
+      this.rawLog(level, `[${timestamp}]`, `[${this.namePrefix}]`, ...args);
+    } else {
+      this.rawLog(level, `[${timestamp}]`, ...args);
+    }
+  }
+
+  private defaultRawLog(level: LogLevel, ...args: unknown[]): void {
+    console[level](...args);
+  }
+}
+
+function formatTimestamp(elapsedMs: number): string {
+  const totalSeconds = Math.floor(elapsedMs / 1000);
+  const milliseconds = elapsedMs % 1000;
+  const ms = String(milliseconds).padStart(3, '0');
+
+  const days = Math.floor(totalSeconds / 86400);
+  const hours = Math.floor((totalSeconds % 86400) / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+
+  if (days > 0) {
+    return `${days}d ${p2(hours)}:${p2(minutes)}:${p2(seconds)}.${ms}`;
+  }
+  if (hours > 0) {
+    return `${p2(hours)}:${p2(minutes)}:${p2(seconds)}.${ms}`;
+  }
+  if (minutes > 0) {
+    return `${p2(minutes)}:${p2(seconds)}.${ms}`;
+  }
+  return `${p2(seconds)}.${ms}`;
+}
+
+function p2(n: number): string {
+  return String(n).padStart(2, '0');
+}

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

@@ -0,0 +1,134 @@
+import {
+  ensureWasmInitialized,
+  WasmTorClient,
+  WasmTorClientOptions,
+  addLogListener,
+  setListenerLevel,
+} from './wasm.js';
+import type { TorClientOptions, FetchInit, LogLevel } from './types.js';
+import { Log } from './Log.js';
+import { createAutoStorage } from './storage/index.js';
+import { ArtiSocketProvider } from './socketProvider.js';
+
+export class TorClient {
+  private log: Log;
+  private clientPromise: Promise<WasmTorClient>;
+  private removeLogListener: (() => void) | null = null;
+  private wasmCallback: ((level: string, target: string, message: string) => void) | null = null;
+  private closed = false;
+  private readyPromise: Promise<void> | null = null;
+  private socketProvider: ArtiSocketProvider | null = null;
+
+  constructor(options: TorClientOptions = {}) {
+    this.log = (options.log ?? new Log({ rawLog: () => {} }));
+    this.clientPromise = this.bootstrap(options);
+  }
+
+  private async bootstrap(options: TorClientOptions): Promise<WasmTorClient> {
+    await ensureWasmInitialized();
+
+    // Register log listener with per-client level filtering.
+    // The WASM subscriber auto-widens to the broadest level across all listeners.
+    this.wasmCallback = this.log._makeWasmCallback();
+    this.removeLogListener = addLogListener(this.wasmCallback, options.logLevel);
+
+    // ArtiSocketProvider handles relay connections. In browsers it needs a gateway
+    // URL for WebRTC/WebSocket proxying; in Node.js/Deno it connects via direct TCP.
+    this.socketProvider = options.socketProvider ?? new ArtiSocketProvider({ gateway: options.gateway });
+    const sp = this.socketProvider;
+
+    let wasmOptions = new WasmTorClientOptions(
+      (addr: string) => sp.connect(addr),
+    );
+
+    const storage = options.storage ?? createAutoStorage();
+    wasmOptions = wasmOptions.withStorage(storage);
+
+    // Auto-attempt fast bootstrap from gateway — only when a URL is available
+    if (options.gateway) {
+      const gatewayBase = options.gateway.replace(/\/+$/, '');
+      wasmOptions = wasmOptions.withFastBootstrap(async (): Promise<Uint8Array> => {
+        this.log.info('Fast bootstrap: fetching bootstrap.zip.br...');
+        const res = await fetch(`${gatewayBase}/bootstrap.zip.br`);
+        if (!res.ok) {
+          throw new Error(`Fast bootstrap fetch failed: ${res.status} ${res.statusText}`);
+        }
+        const bytes = new Uint8Array(await res.arrayBuffer());
+        this.log.info(`Fast bootstrap: received ${bytes.byteLength} bytes`);
+        return bytes;
+      });
+    }
+
+    // Create client (WASM constructor returns a Promise)
+    this.log.info('Bootstrapping...');
+    const client = await WasmTorClient.create(wasmOptions);
+    this.log.info('Bootstrap complete');
+    return client;
+  }
+
+  /**
+   * Make an HTTP fetch request through Tor.
+   * Returns a standard browser Response object.
+   */
+  async fetch(url: string, init?: FetchInit): Promise<Response> {
+    if (this.closed) throw new Error('TorClient is closed');
+    const client = await this.clientPromise;
+    await this.ready();
+    this.log.info(`Fetching ${url}`);
+    return client.fetch(url, init);
+  }
+
+  /**
+   * Wait for the Tor client to be ready for traffic
+   * (guard connected, usable consensus, and sufficient microdescs).
+   *
+   * Parallel callers share the same underlying promise — a single WS
+   * connection failure rejects all waiters. The cached promise is cleared
+   * on settle so the next call creates a fresh attempt.
+   */
+  async ready(): Promise<void> {
+    if (this.closed) throw new Error('TorClient is closed');
+    if (this.readyPromise) return this.readyPromise;
+
+    const p = (async () => {
+      const startTime = Date.now();
+      this.log.info('Waiting for client');
+      const client = await this.clientPromise;
+      this.log.info('Waiting for client to be ready');
+      await client.ready();
+      this.log.info(`Client ready in ${Date.now() - startTime}ms`);
+    })();
+
+    this.readyPromise = p;
+    p.finally(() => { this.readyPromise = null; });
+    return p;
+  }
+
+  /**
+   * Change the log level for this client's listener.
+   * Also re-syncs the global WASM filter to the broadest level across all clients.
+   */
+  setLogLevel(level: LogLevel): void {
+    if (this.wasmCallback) {
+      setListenerLevel(this.wasmCallback, level);
+    }
+  }
+
+  /**
+   * Close the TorClient and release resources.
+   */
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.removeLogListener?.();
+    this.removeLogListener = null;
+    this.wasmCallback = null;
+    this.socketProvider?.close();
+    this.socketProvider = null;
+    this.clientPromise.then(client => client.close()).catch(() => {});
+  }
+
+  [Symbol.dispose](): void {
+    this.close();
+  }
+}

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

@@ -0,0 +1,7 @@
+// Common exports shared by all entry points.
+
+export type { TorClientOptions, FetchInit, TorStorage } from './types.js';
+export { Log, type LogLevel } from './Log.js';
+export * as storage from './storage/index.js';
+export { setWasmUrl } from './wasm.js';
+export { ArtiSocketProvider, ArtiSocket, type ArtiSocketProviderOptions } from './socketProvider.js';

package/node_modules/tor-js/src/entryPoints/wasm-base64/index.ts

@@ -0,0 +1,17 @@
+// Entry point: tor-js/wasm-base64
+// Includes WASM as a base64-encoded string. Self-contained, no external file needed.
+
+import { setWasmSourceProvider } from '../../wasm.js';
+import { wasmBase64 } from '#wasm-base64-data';
+
+export { TorClient } from '../../TorClient.js';
+export * from '../../commonExports.js';
+
+setWasmSourceProvider(async () => {
+  const binaryString = atob(wasmBase64);
+  const bytes = new Uint8Array(binaryString.length);
+  for (let i = 0; i < binaryString.length; i++) {
+    bytes[i] = binaryString.charCodeAt(i);
+  }
+  return bytes;
+});

package/node_modules/tor-js/src/entryPoints/wasm-base64/singleton.ts

@@ -0,0 +1,7 @@
+// Entry point: tor-js/wasm-base64/singleton
+// Singleton with WASM as a base64-encoded string. Self-contained, no external file needed.
+
+import './index.js'; // side effect: registers base64 WASM source provider
+
+export { tor } from '../../singleton.js';
+export * from '../../commonExports.js';

package/node_modules/tor-js/src/entryPoints/wasm-cdn/index.ts

@@ -0,0 +1,155 @@
+// Entry point: tor-js (default), tor-js/wasm-cdn
+// Downloads WASM from CDN with SHA256 hash verification.
+// Caches the downloaded WASM using createAutoStorage for faster subsequent loads.
+// The GitHub CDN source stores AES-256-GCM encrypted files keyed by the WASM hash,
+// with filenames derived from hash(hash) so the key isn't revealed by the URL.
+
+import { setWasmSourceProvider } from '../../wasm.js';
+import { createAutoStorage } from '../../storage/index.js';
+
+export { TorClient } from '../../TorClient.js';
+export * from '../../commonExports.js';
+
+const CACHE_KEY = 'wasm';
+
+function hexToBytes(hex: string): Uint8Array {
+  const bytes = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < hex.length; i += 2) {
+    bytes[i / 2] = parseInt(hex.slice(i, i + 2), 16);
+  }
+  return bytes;
+}
+
+function bytesToBase64(bytes: Uint8Array): string {
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(bytes).toString('base64');
+  }
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+
+function base64ToBytes(base64: string): Uint8Array {
+  if (typeof Buffer !== 'undefined') {
+    return new Uint8Array(Buffer.from(base64, 'base64'));
+  }
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+
+async function sha256hex(bytes: ArrayBuffer | Uint8Array): Promise<string> {
+  if (typeof crypto !== 'undefined' && crypto.subtle) {
+    const buf = bytes instanceof Uint8Array ? bytes.buffer as ArrayBuffer : bytes;
+    const hashBuf = await crypto.subtle.digest('SHA-256', buf);
+    return [...new Uint8Array(hashBuf)].map(b => b.toString(16).padStart(2, '0')).join('');
+  }
+  // Node.js fallback
+  const { createHash } = await import('node:crypto');
+  return createHash('sha256').update(new Uint8Array(bytes)).digest('hex');
+}
+
+async function decryptAesGcm(encrypted: ArrayBuffer, keyBytes: Uint8Array): Promise<ArrayBuffer> {
+  const iv = keyBytes.slice(0, 12);
+
+  if (typeof crypto !== 'undefined' && crypto.subtle) {
+    const key = await crypto.subtle.importKey('raw', keyBytes.buffer as ArrayBuffer, 'AES-GCM', false, ['decrypt']);
+    return crypto.subtle.decrypt({ name: 'AES-GCM', iv }, key, encrypted);
+  }
+
+  // Node.js fallback — crypto.subtle output is ciphertext || 16-byte auth tag
+  const { createDecipheriv } = await import('node:crypto');
+  const data = new Uint8Array(encrypted);
+  const authTag = data.slice(-16);
+  const ciphertext = data.slice(0, -16);
+  const decipher = createDecipheriv('aes-256-gcm', keyBytes, iv);
+  decipher.setAuthTag(authTag);
+  const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+  return decrypted.buffer.slice(decrypted.byteOffset, decrypted.byteOffset + decrypted.byteLength);
+}
+
+setWasmSourceProvider(async () => {
+  let cache: ReturnType<typeof createAutoStorage> | undefined;
+  try {
+    cache = createAutoStorage('tor-js-wasm');
+  } catch {
+    // No persistent storage available — proceed without caching
+  }
+
+  // Try loading from cache
+  if (cache) {
+    try {
+      const cached = await cache.get(CACHE_KEY);
+      if (cached) {
+        const bytes = base64ToBytes(cached);
+        const hash = await sha256hex(bytes);
+        if (hash === __WASM_SHA256__) {
+          return bytes;
+        }
+        // Hash mismatch — stale cache, delete it
+        await cache.delete(CACHE_KEY);
+      }
+    } catch {
+      // Cache read failed — proceed to download
+    }
+  }
+
+  // Download from CDN
+  const hashBytes = hexToBytes(__WASM_SHA256__);
+  const hashHash = await sha256hex(hashBytes);
+  const hashHashPrefix = hashHash.slice(0, 2);
+
+  const githubBase = `https://raw.githubusercontent.com/voltrevo/arti/hash-artifacts/`;
+
+  type Source = { urls: string[], encrypted: boolean };
+
+  const sources: Source[] = [
+    { urls: [`https://cdn.jsdelivr.net/npm/tor-js@${__PACKAGE_VERSION__}/dist/tor_js_bg.wasm`], encrypted: false },
+    { urls: [`https://unpkg.com/tor-js@${__PACKAGE_VERSION__}/dist/tor_js_bg.wasm`], encrypted: false },
+    { urls: [`${githubBase}${hashHashPrefix}/${hashHash}`, `${githubBase}tmp/${hashHash}`], encrypted: true },
+  ];
+
+  // Shuffle sources for load balancing
+  for (let i = sources.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [sources[i], sources[j]] = [sources[j], sources[i]];
+  }
+
+  const errors: string[] = [];
+  for (const source of sources) {
+    for (const url of source.urls) {
+      try {
+        const resp = await fetch(url);
+        if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
+        let bytes = await resp.arrayBuffer();
+
+        if (source.encrypted) {
+          bytes = await decryptAesGcm(bytes, hashBytes);
+        }
+
+        const hash = await sha256hex(bytes);
+        if (hash !== __WASM_SHA256__) {
+          throw new Error(`SHA256 mismatch: expected ${__WASM_SHA256__}, got ${hash}`);
+        }
+
+        const result = new Uint8Array(bytes);
+
+        // Cache for next time (fire and forget)
+        if (cache) {
+          cache.set(CACHE_KEY, bytesToBase64(result)).catch(() => {});
+        }
+
+        return result;
+      } catch (err) {
+        errors.push(`${url}: ${err instanceof Error ? err.message : err}`);
+      }
+    }
+  }
+
+  throw new Error(`Failed to load WASM from any CDN:\n  ${errors.join('\n  ')}`);
+});

package/node_modules/tor-js/src/entryPoints/wasm-cdn/singleton.ts

@@ -0,0 +1,7 @@
+// Entry point: tor-js/wasm-cdn/singleton
+// Singleton that downloads WASM from CDN with SHA256 hash verification.
+
+import './index.js'; // side effect: registers CDN WASM source provider
+
+export { tor } from '../../singleton.js';
+export * from '../../commonExports.js';

package/node_modules/tor-js/src/entryPoints/wasm-file/index.ts

@@ -0,0 +1,19 @@
+// Entry point: tor-js/wasm-file
+// Loads WASM from a file alongside the JS module (Node.js filesystem or browser URL).
+
+import { setWasmSourceProvider } from '../../wasm.js';
+
+export { TorClient } from '../../TorClient.js';
+export * from '../../commonExports.js';
+
+setWasmSourceProvider(async () => {
+  if (typeof process !== 'undefined' && process.versions?.node) {
+    const { readFile } = await import('node:fs/promises');
+    const { fileURLToPath } = await import('node:url');
+    const wasmPath = fileURLToPath(new URL('./tor_js_bg.wasm', import.meta.url));
+    return readFile(wasmPath);
+  }
+  const resp = await fetch(new URL('./tor_js_bg.wasm', import.meta.url));
+  if (!resp.ok) throw new Error(`Failed to fetch WASM: HTTP ${resp.status}`);
+  return new Uint8Array(await resp.arrayBuffer());
+});

package/node_modules/tor-js/src/entryPoints/wasm-file/singleton.ts

@@ -0,0 +1,7 @@
+// Entry point: tor-js/wasm-file/singleton
+// Singleton that loads WASM from a file alongside the JS module.
+
+import './index.js'; // side effect: registers file WASM source provider
+
+export { tor } from '../../singleton.js';
+export * from '../../commonExports.js';

package/node_modules/tor-js/src/globals.d.ts

@@ -0,0 +1,2 @@
+declare const __WASM_SHA256__: string;
+declare const __PACKAGE_VERSION__: string;

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

@@ -0,0 +1,20 @@
+/**
+ * Compile-time exhaustiveness check. Accepts only `never`, so TypeScript
+ * emits an error if the value could still be a valid type (i.e., a case
+ * was not handled).
+ */
+export function never(value: never): never {
+  throw new Error(`Unexpected value: ${safeToString(value)}`);
+}
+
+function safeToString(value: unknown) {
+  try {
+    return JSON.stringify(value);
+  } catch {}
+
+  try {
+    return `${value}`;
+  } catch {}
+
+  return '(string conversion failed)';
+}

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

@@ -0,0 +1,4 @@
+// Polyfill Symbol.dispose for runtimes that don't support it yet
+// (e.g. Node < 20, older browsers). Must be imported before wasm-pkg
+// code runs, since wasm-bindgen uses `if (Symbol.dispose)` at load time.
+(Symbol as any).dispose ??= Symbol('Symbol.dispose');

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

@@ -0,0 +1,54 @@
+import { TorClient } from './TorClient.js';
+import type { TorClientOptions, FetchInit } from './types.js';
+
+let client: TorClient | undefined;
+
+let config: TorClientOptions = {
+  gateway: 'https://tor-js-gateway.voltrevo.com',
+};
+
+export const tor = {
+  /**
+   * Make an HTTP fetch request through Tor.
+   * Automatically opens the TorClient on first use.
+   */
+  async fetch(url: string, init?: FetchInit): Promise<Response> {
+    if (!client) {
+      this.open();
+    }
+    return client!.fetch(url, init);
+  },
+
+  /**
+   * Configure the singleton TorClient.
+   * If already open, closes and reopens with the new config.
+   */
+  configure(options: TorClientOptions): void {
+    config = options;
+    if (client) {
+      client.close();
+      client = undefined;
+      this.open();
+    }
+  },
+
+  /**
+   * Open the singleton TorClient.
+   * Optional — fetch() calls this automatically.
+   * Call this early if you know you'll need Tor, to start bootstrapping sooner.
+   */
+  open(): void {
+    if (client) return;
+    client = new TorClient(config);
+  },
+
+  /**
+   * Close the singleton TorClient and release resources.
+   */
+  close(): void {
+    if (client) {
+      client.close();
+      client = undefined;
+    }
+  },
+};