pal-explorer-cli 0.4.6 → 0.4.8

package/lib/core/syncTransport.js

@@ -0,0 +1,203 @@
+import zlib from 'zlib';
+import { promisify } from 'util';
+import { sendAuthenticatedRequest } from './signalingServer.js';
+import { selectBestTransport, TRANSPORT } from './streamTransport.js';
+import { getNearbyPeers } from './mdnsService.js';
+import { getPrimaryServer } from './discoveryClient.js';
+import config from '../utils/config.js';
+import logger from '../utils/logger.js';
+
+const gzip = promisify(zlib.gzip);
+const gunzip = promisify(zlib.gunzip);
+
+// Base transport class — all sync transports implement send() and sendFile()
+class SyncTransportBase {
+  constructor(type) {
+    this.type = type;
+  }
+  async send(envelope) { throw new Error('Not implemented'); }
+  async sendFile(filePath, relativePath, opts) { throw new Error('Not implemented'); }
+  async sendChunk(data) { throw new Error('Not implemented'); }
+  close() {}
+}
+
+// LAN transport — send PAL/1.0 envelopes via signaling server TCP (port 7474)
+export class LanTransport extends SyncTransportBase {
+  constructor(peerAddress) {
+    super('lan');
+    const [host, port] = peerAddress.split(':');
+    this.host = host;
+    this.port = parseInt(port, 10) || 7474;
+  }
+
+  async send(envelope) {
+    const identity = config.get('identity');
+    if (!identity?.privateKey || !identity?.publicKey) {
+      throw new Error('Identity not configured');
+    }
+    const result = await sendAuthenticatedRequest(
+      this.host, this.port,
+      { type: 'message', envelope },
+      identity.privateKey, identity.publicKey, 10000
+    );
+    if (result.error) throw new Error(result.error);
+    return result;
+  }
+
+  async sendFile(readStream, relativePath, { onChunk } = {}) {
+    // File data is sent as sync.request response chunks via the same TCP protocol
+    // For LAN, we embed file data in the envelope payload (chunked for large files)
+    const chunks = [];
+    for await (const chunk of readStream) {
+      chunks.push(chunk);
+      if (onChunk) onChunk(chunk.length);
+    }
+    return Buffer.concat(chunks);
+  }
+}
+
+// WebRTC transport — send via WebRTC data channel (for internet peers)
+export class WebRTCTransport extends SyncTransportBase {
+  constructor(iceServers, localPK, remotePK) {
+    super('webrtc');
+    this.iceServers = iceServers;
+    this.localPK = localPK;
+    this.remotePK = remotePK;
+    this.dataChannel = null;
+  }
+
+  async send(envelope) {
+    if (!this.dataChannel) {
+      throw new Error('WebRTC data channel not established');
+    }
+    const data = JSON.stringify(envelope);
+    this.dataChannel.send(data);
+    return { received: true };
+  }
+
+  async sendChunk(data) {
+    if (!this.dataChannel) {
+      throw new Error('WebRTC data channel not established');
+    }
+    // 16KB chunks with backpressure
+    const CHUNK_SIZE = 16384;
+    for (let offset = 0; offset < data.length; offset += CHUNK_SIZE) {
+      const chunk = data.subarray(offset, offset + CHUNK_SIZE);
+      while (this.dataChannel.bufferedAmount > 1024 * 1024) {
+        await new Promise(r => setTimeout(r, 10));
+      }
+      this.dataChannel.send(chunk);
+    }
+  }
+
+  setDataChannel(dc) {
+    this.dataChannel = dc;
+  }
+
+  close() {
+    if (this.dataChannel) {
+      try { this.dataChannel.close(); } catch {}
+      this.dataChannel = null;
+    }
+  }
+}
+
+// Discovery transport — fallback to HTTP via discovery server (extension-only)
+export class DiscoveryTransport extends SyncTransportBase {
+  constructor(toHandle, fromHandle) {
+    super('discovery');
+    this.toHandle = toHandle;
+    this.fromHandle = fromHandle;
+  }
+
+  async send(envelope) {
+    const serverUrl = getPrimaryServer();
+    const res = await fetch(`${serverUrl}/messages`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        toHandle: this.toHandle,
+        fromHandle: this.fromHandle,
+        payload: envelope,
+      }),
+      signal: AbortSignal.timeout(15000),
+    });
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({}));
+      throw new Error(`Discovery server error: ${res.status} ${err.error || res.statusText}`);
+    }
+    return { received: true };
+  }
+}
+
+// Select the best available transport for a given peer
+export async function selectSyncTransport(peerPK, { peerHandle } = {}) {
+  const identity = config.get('identity');
+
+  // Try P2P transports first (LAN, then WebRTC)
+  try {
+    const best = await selectBestTransport(peerPK);
+    if (best) {
+      if (best.transport === TRANSPORT.LAN) {
+        return new LanTransport(best.address);
+      }
+      if (best.transport === TRANSPORT.P2P) {
+        return new WebRTCTransport(best.iceServers, identity?.publicKey, peerPK);
+      }
+    }
+  } catch (err) {
+    logger.debug(`P2P transport selection failed: ${err.message}`);
+  }
+
+  // Fallback to discovery server if peer has a handle
+  if (peerHandle && identity?.handle) {
+    return new DiscoveryTransport(peerHandle, identity.handle);
+  }
+
+  throw new Error('No available transport to reach peer. Ensure both peers are on the same LAN or have Pro for internet sync.');
+}
+
+// Find a peer's LAN address by public key (used for direct connection)
+export function findLanPeer(peerPK) {
+  const nearby = getNearbyPeers();
+  return nearby.find(p => p.publicKey === peerPK) || null;
+}
+
+// --- Compression helpers ---
+
+export async function compressData(data) {
+  return gzip(data);
+}
+
+export async function decompressData(data) {
+  return gunzip(data);
+}
+
+// --- Bandwidth throttle (token bucket) ---
+
+export class BandwidthThrottle {
+  constructor(kbps) {
+    this.bytesPerMs = (kbps * 1024) / 1000;
+    this.tokens = kbps * 1024; // start with 1 second of tokens
+    this.lastRefill = Date.now();
+  }
+
+  async throttle(bytes) {
+    if (this.bytesPerMs <= 0) return; // no limit
+
+    // Refill tokens
+    const now = Date.now();
+    const elapsed = now - this.lastRefill;
+    this.tokens = Math.min(this.bytesPerMs * 1000, this.tokens + elapsed * this.bytesPerMs);
+    this.lastRefill = now;
+
+    // Wait if we don't have enough tokens
+    if (this.tokens < bytes) {
+      const waitMs = Math.ceil((bytes - this.tokens) / this.bytesPerMs);
+      await new Promise(r => setTimeout(r, waitMs));
+      this.tokens = 0;
+    } else {
+      this.tokens -= bytes;
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pal-explorer-cli",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "description": "P2P encrypted file sharing CLI — share files directly with friends, not with the cloud",
   "main": "bin/pal.js",
   "bin": {
@@ -9,7 +9,8 @@
   "files": [
     "bin/",
     "lib/",
-    "extensions/",
+    "extensions/@palexplorer/*/extension.json",
+    "extensions/@palexplorer/*/index.js",
     "LICENSE.md"
   ],
   "scripts": {

package/extensions/@palexplorer/analytics/README.md

@@ -1,45 +0,0 @@
-# Analytics Extension
-
-Anonymous, opt-in usage analytics for Palexplorer via PostHog.
-
-## Privacy Guarantees
-
-- **Opt-in only** — disabled by default, must be explicitly enabled
-- **No PII** — device ID is a random UUID, not tied to identity
-- **No content** — never tracks file names, share names, peer identities, or message content
-- **No IP logging** — PostHog configured to anonymize IPs
-- **Transparent** — all tracked events listed below
-
-## Events Tracked
-
-| Event | Properties | When |
-|-------|-----------|------|
-| `app_open` | platform, version, arch | App starts |
-| `app_close` | sessionDurationSec | App closes |
-| `share_created` | visibility, recipientCount | Share created |
-| `share_revoked` | — | Share revoked |
-| `transfer_complete` | size, duration, speed | Download finishes |
-| `peer_connected` | — | Peer connects |
-| `peer_disconnected` | — | Peer disconnects |
-| `settings_changed` | key (setting name only) | Setting modified |
-
-## Configuration
-
-| Key | Type | Default | Description |
-|-----|------|---------|-------------|
-| `enabled` | boolean | `false` | Enable analytics (opt-in) |
-| `posthogKey` | string | (built-in) | PostHog project API key |
-| `posthogHost` | string | `https://us.i.posthog.com` | PostHog host |
-| `sessionTracking` | boolean | `true` | Track session duration |
-
-```bash
-pe ext config analytics enabled true
-pe ext config analytics sessionTracking false
-```
-
-## How to Opt Out
-
-```bash
-pe ext config analytics enabled false
-```
-Or toggle "Usage Analytics" in Settings > Privacy.

package/extensions/@palexplorer/analytics/docs/MONETIZATION.md

@@ -1,14 +0,0 @@
-# Analytics Extension — Monetization
-
-## Tier
-
-- [x] Free — available to all users
-
-## Rationale
-
-Analytics benefits us (product decisions, bug detection, growth tracking), not the user. It must be free and opt-in to maintain trust. Charging for analytics would be counterproductive — we want maximum opt-in rate.
-
-## Revenue Potential
-
-- No direct revenue
-- Indirect value: data-driven feature prioritization, retention insights, conversion tracking for Pro upsells

package/extensions/@palexplorer/analytics/docs/PLAN.md

@@ -1,23 +0,0 @@
-# Analytics Extension — Plan
-
-## Goal
-
-Move PostHog analytics out of core into an extension. Core should be pure P2P with no server dependencies. Analytics phones home to PostHog, so it must be an extension.
-
-## Design
-
-- Bundled extension (`@palexplorer/analytics`) — runs in-process, no sandbox
-- Listens to existing core hooks — no changes to core event emission needed
-- PostHog client initialized only when enabled (opt-in)
-- Device ID stored in extension's own store (not core config)
-- Offline queue with periodic flush — same pattern as before
-- Error reporting (`reportCrash`/`reportError`) stays in core as a safety feature
-
-## What Changed
-
-- Moved from: `lib/core/analytics.js` (PostHog + track functions)
-- Moved to: `extensions/@palexplorer/analytics/index.js`
-- Core `analytics.js` slimmed to error reporting only
-- `posthog-node` dependency moved from root to extension
-- Removed direct `track()` imports from `shares.js`, `transfers.js`, `billing.js`
-- Those events now flow through hooks → analytics extension

package/extensions/@palexplorer/analytics/docs/PRIVACY.md

@@ -1,38 +0,0 @@
-# Analytics Extension — Privacy
-
-## What We Collect
-
-- App open/close events with session duration
-- Feature usage counts (shares, transfers, peer connections)
-- Setting change events (key name only, not values)
-- Platform, app version, architecture
-
-## What We Never Collect
-
-- File names, paths, or content
-- Share names, IDs, or recipients
-- Peer identities, handles, or public keys
-- IP addresses (PostHog IP anonymization enabled)
-- Messages or chat content
-- Encryption keys or credentials
-- Browsing/usage patterns that could identify individuals
-
-## Device ID
-
-A random UUID generated on first use. Not derived from hardware, identity, or any personal data. Stored locally in the extension's store. Can be reset by disabling and re-enabling the extension.
-
-## Data Flow
-
-```
-App Events → Core Hooks → Analytics Extension → PostHog (US Cloud)
-```
-
-No data is sent to Palexplorer servers. Only PostHog receives analytics data.
-
-## User Control
-
-- Disabled by default (opt-in required)
-- Toggle in Settings > Privacy
-- First-launch setup wizard asks for consent
-- Can be disabled at any time via GUI or CLI
-- Disabling immediately stops all data collection

package/extensions/@palexplorer/analytics/test/analytics.test.js

@@ -1,82 +0,0 @@
-import { describe, it, beforeEach, afterEach, mock } from 'node:test';
-import assert from 'node:assert/strict';
-
-function createMockContext(overrides = {}) {
-  const config = { enabled: true, posthogKey: '', posthogHost: '', sessionTracking: true };
-  return {
-    hooks: { on: mock.fn() },
-    config: {
-      get: mock.fn((key) => config[key]),
-      set: mock.fn((key, val) => { config[key] = val; }),
-    },
-    store: {
-      get: mock.fn(() => undefined),
-      set: mock.fn(),
-      delete: mock.fn(),
-    },
-    logger: { info: mock.fn(), warn: mock.fn(), error: mock.fn() },
-    app: { version: '0.5.0', platform: 'linux', dataDir: '/tmp/test', appRoot: '/tmp/test' },
-    ...overrides,
-  };
-}
-
-describe('analytics extension', () => {
-  let ext;
-  let ctx;
-
-  beforeEach(async () => {
-    ext = await import('../index.js');
-    ctx = createMockContext();
-  });
-
-  afterEach(async () => {
-    await ext.deactivate();
-  });
-
-  it('should register all expected hooks when enabled', async () => {
-    await ext.activate(ctx);
-    const hookNames = ctx.hooks.on.mock.calls.map(c => c.arguments[0]);
-    assert.ok(hookNames.includes('on:app:ready'));
-    assert.ok(hookNames.includes('on:app:shutdown'));
-    assert.ok(hookNames.includes('after:share:create'));
-    assert.ok(hookNames.includes('after:download:complete'));
-    assert.ok(hookNames.includes('on:config:change'));
-  });
-
-  it('should still register hooks when disabled (for hot-enable support)', async () => {
-    ctx.config.get = mock.fn((key) => key === 'enabled' ? false : undefined);
-    await ext.activate(ctx);
-    // Hooks are always registered so analytics can be hot-enabled via config change
-    const hookNames = ctx.hooks.on.mock.calls.map(c => c.arguments[0]);
-    assert.ok(hookNames.includes('on:config:change'));
-    assert.ok(hookNames.includes('on:app:shutdown'));
-  });
-
-  it('should deactivate cleanly', async () => {
-    await ext.activate(ctx);
-    await ext.deactivate();
-  });
-
-  it('should generate and persist device ID', async () => {
-    await ext.activate(ctx);
-    // Device ID is generated on first track call — trigger via hook
-    // The store.set should be called with deviceId
-    const setCalls = ctx.store.set.mock.calls;
-    const deviceIdCall = setCalls.find(c => c.arguments[0] === 'deviceId');
-    if (deviceIdCall) {
-      assert.ok(deviceIdCall.arguments[1].length > 0);
-    }
-  });
-
-  it('should reuse existing device ID', async () => {
-    const existingId = 'test-uuid-1234';
-    ctx.store.get = mock.fn((key) => key === 'deviceId' ? existingId : undefined);
-    await ext.activate(ctx);
-  });
-
-  it('should queue events when offline', async () => {
-    await ext.activate(ctx);
-    ext.setOnline(false);
-    ext.setOnline(true);
-  });
-});