pal-explorer-cli 0.4.10 → 0.4.12

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

@@ -0,0 +1,45 @@
+# 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

@@ -0,0 +1,14 @@
+# 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

@@ -0,0 +1,23 @@
+# 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

@@ -0,0 +1,38 @@
+# 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

@@ -0,0 +1,82 @@
+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);
+  });
+});

package/lib/commands/sync.js

@@ -114,7 +114,7 @@ async function biSync(dirPath, palName, opts) {
   try {
     absolutePath = validateDir(dirPath);
     pal = findPal(palName);
-    identity = getIdentity();
+    identity = await getIdentity();
     keyPair = getKeyPair();
   } catch (err) {
     console.log(chalk.red(err.message));
@@ -201,7 +201,7 @@ async function pushSync(dirPath, palName, opts) {
   try {
     absolutePath = validateDir(dirPath);
     pal = findPal(palName);
-    identity = getIdentity();
+    identity = await getIdentity();
     keyPair = getKeyPair();
   } catch (err) {
     console.log(chalk.red(err.message));
@@ -305,7 +305,7 @@ async function pullSync(dirPath, palName, opts) {
   try {
     absolutePath = validateDir(dirPath);
     pal = findPal(palName);
-    identity = getIdentity();
+    identity = await getIdentity();
     keyPair = getKeyPair();
   } catch (err) {
     console.log(chalk.red(err.message));

package/lib/commands/web-login.js

@@ -14,7 +14,7 @@ Examples:
 `)
     .action(async (code, opts) => {
       try {
-        const identity = getIdentity();
+        const identity = await getIdentity();
         if (!identity) {
           console.log(chalk.red('No identity found. Run: pe init'));
           return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pal-explorer-cli",
-  "version": "0.4.10",
+  "version": "0.4.12",
   "description": "P2P encrypted file sharing CLI — share files directly with friends, not with the cloud",
   "main": "bin/pal.js",
   "bin": {
@@ -9,8 +9,17 @@
   "files": [
     "bin/",
     "lib/",
-    "extensions/@palexplorer/*/extension.json",
-    "extensions/@palexplorer/*/index.js",
+    "extensions/@palexplorer/analytics/",
+    "extensions/@palexplorer/audit/",
+    "extensions/@palexplorer/auth-email/",
+    "extensions/@palexplorer/auth-oauth/",
+    "extensions/@palexplorer/chat/",
+    "extensions/@palexplorer/discovery/",
+    "extensions/@palexplorer/email-notifications/",
+    "extensions/@palexplorer/groups/",
+    "extensions/@palexplorer/share-links/",
+    "extensions/@palexplorer/sync/",
+    "extensions/@palexplorer/user-mgmt/",
     "LICENSE.md"
   ],
   "scripts": {

package/extensions/@palexplorer/explorer-integration/extension.json

@@ -1,13 +0,0 @@
-{
-  "name": "explorer-integration",
-  "version": "1.0.0",
-  "description": "Add 'Share with Pal' to your file manager context menu (Explorer, Finder, Nautilus)",
-  "author": "Palexplorer Team",
-  "license": "MIT",
-  "main": "index.js",
-  "hooks": [],
-  "permissions": ["fs:write"],
-  "config": {},
-  "tier": "pro",
-  "minAppVersion": "0.5.0"
-}

package/extensions/@palexplorer/explorer-integration/index.js

@@ -1,122 +0,0 @@
-import fs from 'fs';
-import path from 'path';
-import { exec } from 'child_process';
-
-let ctx = null;
-
-function isHeadless() {
-  return process.platform === 'linux' && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY;
-}
-
-export function activate(context) {
-  ctx = context;
-  if (!isHeadless()) {
-    ctx.logger.info('Explorer integration loaded. Use `pe explorer install` to set up.');
-  }
-}
-
-export function deactivate() {}
-
-export async function install() {
-  const p = process.platform;
-  if (p === 'win32') return installWindows();
-  if (p === 'darwin') return installFinder();
-  if (p === 'linux') return installNautilus();
-  throw new Error(`No file manager integration for ${p}`);
-}
-
-export async function uninstall() {
-  const p = process.platform;
-  if (p === 'win32') return uninstallWindows();
-  if (p === 'darwin') return uninstallFinder();
-  if (p === 'linux') return uninstallNautilus();
-  throw new Error(`No file manager integration for ${p}`);
-}
-
-async function installWindows() {
-  // Delegates to existing Windows explorer util
-  const { installExplorerContextMenu } = await import('../../../lib/utils/explorer.js');
-  await installExplorerContextMenu();
-}
-
-async function uninstallWindows() {
-  const { uninstallExplorerContextMenu } = await import('../../../lib/utils/explorer.js');
-  await uninstallExplorerContextMenu();
-}
-
-async function installFinder() {
-  const workflowDir = path.join(
-    process.env.HOME,
-    'Library/Services/Share with Pal.workflow/Contents'
-  );
-
-  fs.mkdirSync(workflowDir, { recursive: true });
-
-  fs.writeFileSync(path.join(workflowDir, 'Info.plist'), `<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-    <key>NSServices</key>
-    <array>
-        <dict>
-            <key>NSMenuItem</key>
-            <dict>
-                <key>default</key>
-                <string>Share with Pal</string>
-            </dict>
-            <key>NSMessage</key>
-            <string>runWorkflowAsService</string>
-            <key>NSSendFileTypes</key>
-            <array>
-                <string>public.item</string>
-            </array>
-        </dict>
-    </array>
-</dict>
-</plist>
-`);
-
-  fs.writeFileSync(path.join(workflowDir, 'share-with-pal.sh'), `#!/bin/bash
-for f in "$@"; do
-  pe share "$f"
-done
-`, { mode: 0o755 });
-
-  ctx?.logger.info(`Finder Quick Action created at ${workflowDir}`);
-}
-
-async function uninstallFinder() {
-  const dir = path.join(process.env.HOME, 'Library/Services/Share with Pal.workflow');
-  if (fs.existsSync(dir)) fs.rmSync(dir, { recursive: true });
-}
-
-async function installNautilus() {
-  const scriptDir = path.join(process.env.HOME, '.local/share/nautilus/scripts');
-  fs.mkdirSync(scriptDir, { recursive: true });
-
-  fs.writeFileSync(path.join(scriptDir, 'Share with Pal'), `#!/bin/bash
-IFS=$'\\n'
-for f in $NAUTILUS_SCRIPT_SELECTED_FILE_PATHS; do
-  pe share "$f"
-done
-`, { mode: 0o755 });
-
-  const actionsDir = path.join(process.env.HOME, '.local/share/file-manager/actions');
-  fs.mkdirSync(actionsDir, { recursive: true });
-
-  fs.writeFileSync(path.join(actionsDir, 'palexplorer-share.desktop'), `[Desktop Action]
-Name=Share with Pal
-Icon=palexplorer
-Exec=pe share %f
-MimeType=inode/directory;application/octet-stream;
-`);
-
-  ctx?.logger.info('Nautilus script installed');
-}
-
-async function uninstallNautilus() {
-  const script = path.join(process.env.HOME, '.local/share/nautilus/scripts/Share with Pal');
-  const action = path.join(process.env.HOME, '.local/share/file-manager/actions/palexplorer-share.desktop');
-  if (fs.existsSync(script)) fs.unlinkSync(script);
-  if (fs.existsSync(action)) fs.unlinkSync(action);
-}

package/extensions/@palexplorer/networks/extension.json

@@ -1,17 +0,0 @@
-{
-  "name": "networks",
-  "version": "1.0.0",
-  "description": "Private overlay networks for organizations",
-  "author": "Palexplorer Team",
-  "license": "MIT",
-  "main": "index.js",
-  "hooks": ["on:app:ready"],
-  "permissions": [],
-  "contributes": {
-    "pages": [
-      { "id": "networks", "label": "networks", "icon": "Globe", "section": "system" }
-    ]
-  },
-  "config": { "enabled": { "type": "boolean", "default": false } },
-  "tier": "enterprise"
-}

package/extensions/@palexplorer/networks/index.js

@@ -1,2 +0,0 @@
-export function activate(context) {}
-export function deactivate() {}

package/extensions/@palexplorer/vfs/extension.json

@@ -1,17 +0,0 @@
-{
-  "name": "vfs",
-  "version": "1.0.0",
-  "description": "Mount Palexplorer shares as a virtual drive (WebDAV)",
-  "author": "Palexplorer Team",
-  "license": "MIT",
-  "main": "index.js",
-  "hooks": ["on:app:ready", "on:app:shutdown", "after:share:create", "after:share:revoke"],
-  "permissions": ["shares:read", "config:read", "config:write"],
-  "config": {
-    "port": { "type": "number", "default": 1900, "description": "WebDAV server port" },
-    "driveLetter": { "type": "string", "default": "P", "description": "Windows drive letter" },
-    "autoMount": { "type": "boolean", "default": true, "description": "Auto-mount on startup" }
-  },
-  "tier": "pro",
-  "minAppVersion": "0.5.0"
-}

package/extensions/@palexplorer/vfs/index.js

@@ -1,167 +0,0 @@
-import { v2 as webdav } from 'webdav-server';
-import { exec } from 'child_process';
-import crypto from 'crypto';
-import path from 'path';
-import fs from 'fs';
-
-let server = null;
-let token = null;
-let mounted = false;
-let shares = new Map();
-let ctx = null;
-
-export function activate(context) {
-  ctx = context;
-
-  context.hooks.on('on:app:ready', async () => {
-    const port = context.config.get('port') || 1900;
-    const autoMount = context.config.get('autoMount') !== false;
-    try {
-      await startServer(port);
-      await syncShares(context);
-      if (autoMount) {
-        const letter = context.config.get('driveLetter') || 'P';
-        await mount(letter, port);
-      }
-    } catch (err) {
-      context.logger.error('VFS startup failed:', err.message);
-    }
-  });
-
-  context.hooks.on('after:share:create', async () => {
-    if (server) await syncShares(context);
-  });
-
-  context.hooks.on('after:share:revoke', async () => {
-    if (server) await syncShares(context);
-  });
-
-  context.hooks.on('on:app:shutdown', async () => {
-    await stop();
-  });
-}
-
-export function deactivate() {
-  return stop();
-}
-
-export function getStatus() {
-  return {
-    running: !!server,
-    mounted,
-    shareCount: shares.size,
-    shares: Array.from(shares.entries()).map(([name, localPath]) => ({ name, localPath })),
-  };
-}
-
-async function startServer(port = 1900) {
-  if (server) return;
-  token = crypto.randomBytes(32).toString('hex');
-
-  const userManager = new webdav.SimpleUserManager();
-  const user = userManager.addUser('pal', token, false);
-  const privilegeManager = new webdav.SimplePathPrivilegeManager();
-  privilegeManager.setRights(user, '/', ['all']);
-
-  server = new webdav.WebDAVServer({
-    port,
-    hostname: '127.0.0.1',
-    requireAuthentification: true,
-    httpAuthentication: new webdav.HTTPBasicAuthentication(userManager, 'Palexplorer VFS'),
-    privilegeManager,
-  });
-
-  return new Promise((resolve, reject) => {
-    server.start((s) => {
-      if (s instanceof Error) return reject(s);
-      ctx?.logger.info(`WebDAV server on http://127.0.0.1:${port}`);
-      resolve();
-    });
-  });
-}
-
-async function stop() {
-  if (mounted) {
-    try { await unmount(); } catch {}
-  }
-  if (server) {
-    return new Promise((resolve) => {
-      server.stop(() => { server = null; token = null; resolve(); });
-    });
-  }
-}
-
-async function syncShares(context) {
-  const configShares = context.shares?.list() || [];
-  const activeNames = new Set();
-
-  for (const share of configShares) {
-    if (share.status !== 'active') continue;
-    const name = path.basename(share.path);
-    activeNames.add(name);
-    if (!shares.has(name)) {
-      try {
-        await new Promise((resolve, reject) => {
-          server.setFileSystem(`/${name}`, new webdav.PhysicalFileSystem(share.path), (ok) => {
-            if (ok) { shares.set(name, share.path); resolve(); }
-            else reject(new Error(`Failed to add: ${name}`));
-          });
-        });
-      } catch {}
-    }
-  }
-
-  for (const [name] of shares) {
-    if (!activeNames.has(name)) {
-      server.removeFileSystem(`/${name}`, () => { shares.delete(name); });
-    }
-  }
-}
-
-async function mount(driveLetter = 'P', port = 1900) {
-  const p = process.platform;
-  if (p === 'win32') {
-    const cmd = `net use ${driveLetter}: http://127.0.0.1:${port} /user:pal ${token} /persistent:yes`;
-    return new Promise((resolve) => {
-      exec(cmd, (err, stdout, stderr) => {
-        if (err && stderr?.includes('67')) {
-          ctx?.logger.warn('WebClient service not running, drive skipped.');
-          return resolve();
-        }
-        mounted = !err || stderr?.includes('85');
-        if (mounted) ctx?.logger.info(`Mounted at ${driveLetter}:`);
-        resolve();
-      });
-    });
-  }
-  if (p === 'darwin') {
-    const mp = '/Volumes/Palexplorer';
-    return new Promise((resolve) => {
-      exec(`mkdir -p "${mp}" && mount_webdav -s -S http://127.0.0.1:${port} "${mp}"`, (err) => {
-        mounted = !err;
-        if (mounted) ctx?.logger.info(`Mounted at ${mp}`);
-        resolve();
-      });
-    });
-  }
-  if (p === 'linux') {
-    const mp = `${process.env.HOME}/Palexplorer`;
-    return new Promise((resolve) => {
-      exec(`mkdir -p "${mp}" && mount -t davfs http://127.0.0.1:${port} "${mp}"`, (err) => {
-        mounted = !err;
-        if (mounted) ctx?.logger.info(`Mounted at ${mp}`);
-        resolve();
-      });
-    });
-  }
-}
-
-async function unmount() {
-  const p = process.platform;
-  const cmd = p === 'win32' ? `net use P: /delete /yes`
-    : p === 'darwin' ? `umount /Volumes/Palexplorer`
-    : `umount ${process.env.HOME}/Palexplorer`;
-  return new Promise((resolve) => {
-    exec(cmd, () => { mounted = false; resolve(); });
-  });
-}