pal-explorer-cli 0.4.0

package/LICENSE.md

@@ -0,0 +1,18 @@
+Copyright (c) 2015-2026 Palexplorer. All rights reserved.
+
+This software is provided under a proprietary license. You may use the
+compiled/installed version of this software for personal and commercial
+purposes. You may NOT:
+
+- Redistribute, sublicense, or sell copies of the source code
+- Modify the source code and distribute derivative works
+- Reverse engineer, decompile, or disassemble the software
+- Remove or alter any proprietary notices or labels
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,314 @@
+# Pal Explorer (`pe`)
+
+[![npm](https://img.shields.io/npm/v/pal-explorer-cli)](https://www.npmjs.com/package/pal-explorer-cli)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org/)
+
+> Peer-to-peer file sharing with end-to-end encryption. No cloud. No middleman.
+
+Pal Explorer lets you share files directly with friends using P2P protocols. Files are encrypted before leaving your device, transferred via WebTorrent, and only decryptable by intended recipients.
+
+## Features
+
+### File Sharing
+- Share files, folders, or entire drives via WebTorrent
+- Private shares with per-recipient E2EE (XChaCha20-Poly1305)
+- Public shares with global magnet links
+- Non-recursive folder sharing (top-level only)
+- Web share links with expiry and download limits
+- Share invites sent automatically via discovery server inbox
+
+### Groups
+- Create named groups and organize pals
+- Share with entire groups in one command (`--with-group`)
+- Broadcast messages to all group members
+- Pro limits on group count and member count
+
+### Comments
+- Per-share comment threads
+- Add, list, and delete comments on any share
+- Comments linked to author identity
+
+### Sync
+- Push/pull directory sync between pals
+- SHA-256 manifest-based delta sync
+- Watch mode for automatic sync on file changes
+- Conflict detection with `.sync-conflict` copies
+- Sync history tracking
+
+### File Explorer
+- Browse, search, and manage files with permission checks
+- Directory tree visualization
+- File info with share status
+- Copy, move, rename, delete operations
+- Audit log for all file operations
+
+### Remote Browsing
+- Browse pals' shares without downloading
+- List files in remote shares
+- Selective file download from remote shares
+- Server signature verification
+
+### Chat
+- Real-time encrypted messaging between pals
+- Chat history with conversation list
+- Fetch new messages from the server
+
+### Security
+- **Ed25519 identities** with private keys stored in OS credential manager (keytar)
+- **XChaCha20-Poly1305** authenticated encryption for all private shares
+- **Per-recipient key wrapping** -- each recipient gets a uniquely encrypted share key
+- **Key rotation on revocation** -- removing a recipient triggers re-encryption
+- **BIP-39 recovery** -- 24-word mnemonic phrase for identity backup
+- **Challenge-response registration** -- server never sees your private key
+- **Signed server responses** -- clients verify discovery server authenticity
+- **Encrypted messages** -- inbox payloads encrypted end-to-end
+- **Metadata protection** -- opaque filenames and encrypted manifests in torrents
+- **TOFU server key pinning** -- federated servers pinned on first contact
+- **Config integrity** -- HMAC-SHA256 signing for critical config sections
+- **PIN lock** -- protect the GUI with a PIN code
+
+### Pro Features
+- Multi-user profiles with role-based access (owner, admin, member)
+- Encrypted backup and restore
+- API keys for programmatic access
+- Web share links
+- Scheduled tasks (shares, downloads, auto-revokes)
+- Extended inbox and transfer analytics
+- Ad-free experience
+
+### Multi-User
+- Multiple identity profiles on one device
+- Owner/admin/member role hierarchy
+- Login switching between profiles
+- Profile promotion and demotion
+
+### Discovery & Presence
+- LAN peer discovery via mDNS (Bonjour)
+- Federated handle system (`alice@server.com`)
+- DHT-based decentralized fallback
+- Online/offline presence status for pals
+- Multi-device support with per-device registration
+
+## Quick Start
+
+```bash
+# Install CLI globally
+npm install -g pal-explorer-cli
+
+# Or clone and link for development
+# git clone https://github.com/hn2/palexplorer && cd palexplorer && npm install && npm link
+
+# Create your identity
+pe init "YourName"
+# Save the 24-word recovery phrase!
+
+# Share a folder with a friend
+pe share ~/Documents --visibility private --with Alice
+
+# Start seeding
+pe serve
+
+# Download from a peer
+pe download "magnet:?xt=urn:btih:..."
+```
+
+### Adding Friends
+
+```bash
+pe invite --qr              # Generate invite link + QR code
+pe pal add @alice            # Add by handle
+pe pal add pal://eyJ...     # Add by invite link
+pe nearby --add             # Auto-discover on LAN
+```
+
+## CLI Reference
+
+The `pe` CLI includes 100+ subcommands. See [docs/CLI.md](docs/CLI.md) for the complete reference.
+
+### Key Commands
+
+```bash
+pe init <name>                    # Create identity
+pe register <handle>              # Register on discovery network
+pe share <path> -v private -w bob # Share encrypted with a pal
+pe serve                          # Start seeding
+pe download <magnet>              # Download from magnet link
+pe pal add @alice                 # Add a pal by handle
+pe sync push ./project alice      # Push sync to a pal
+pe status                         # System health dashboard
+```
+
+### Global Flags
+
+| Flag | Description |
+|:---|:---|
+| `--json` | Output as JSON |
+| `--verbose` | Verbose logging |
+| `--quiet` | Suppress non-essential output |
+
+## GUI
+
+The Electron desktop app lives in the `gui/` directory:
+
+```bash
+cd gui
+npm install
+npm run electron
+```
+
+Features: setup wizard, splash screen with startup progress, dark/light themes, system tray, drag-and-drop sharing, P2P chat, PIN lock, media streaming, workspaces, extensions, file explorer with favorites, command palette, and sidebar grouped into Content/Social/System sections.
+
+## Web Dashboard
+
+Start the web dashboard alongside the seeder:
+
+```bash
+pe serve --web
+pe web                  # Opens in browser
+```
+
+REST API + WebSocket for real-time transfer monitoring, chat, and Pro/billing management.
+
+## Configuration
+
+| Key | Default | Description |
+|:---|:---|:---|
+| `port` | auto | Local seeder port |
+| `storage_path` | `./downloads` | Default download directory |
+| `max_connections` | `50` | Max P2P connections |
+| `bandwidth_cap` | `0` | Upload cap in KB/s (0 = unlimited) |
+| `discovery_servers` | `http://localhost:3000` | Discovery server URLs (comma-separated) |
+| `announce_interval` | -- | DHT announce interval in seconds |
+
+Config file location: `~/.config/palexplorer-cli/config.json`
+
+Override the discovery server URL with the `PAL_DISCOVERY_URL` environment variable.
+
+## Free vs Pro
+
+| Feature | Free | Pro |
+|:---|:---:|:---:|
+| File sharing, E2EE, chat | Yes | Yes |
+| Groups (max 3, 5 members each) | Yes | Unlimited |
+| Comments (max 10 per share) | Yes | Unlimited |
+| Share recipients (max 5) | Yes | Unlimited |
+| Ad-free experience | No | Yes |
+| Multi-user profiles | No | Yes |
+| Vanity handles | No | Yes |
+| Extended inbox (1000 msgs) | No | Yes |
+| Transfer analytics | No | Yes |
+| Encrypted backup/restore | No | Yes |
+| API keys | No | Yes |
+| Scheduled tasks | No | Yes |
+
+**Pricing:** Pro $2.99/mo | Pro Annual $29.99/yr | Enterprise $9.99/seat/mo
+
+See [docs/MONETIZATION.md](docs/MONETIZATION.md) for full comparison, enforcement architecture, and details.
+
+## Architecture
+
+```
++------------------+     +------------------+     +--------------------+
+|    CLI (pe)      |     |   Electron GUI   |     |   Web Dashboard    |
+|  bin/pal.js      |     |   gui/           |     |   web/             |
++--------+---------+     +--------+---------+     +--------+-----------+
+         |                        |                        |
+         +------------------------+------------------------+
+         |                Core Libraries                   |
+         |  lib/core/    - identity, shares, groups, sync  |
+         |  lib/crypto/  - E2EE, key exchange              |
+         |  lib/utils/   - config, logging                 |
+         +-------------------------+-----------------------+
+                                   |
+                    +--------------+--------------+
+                    |    Discovery Server          |
+                    |    palexplorer-server (repo)  |
+                    |    LevelDB + Express          |
+                    |   OAuth + Lemon Squeezy billing  |
+                    +------------------------------+
+```
+
+**CLI** -- 100+ subcommands, shell completion (bash/zsh), JSON output.
+
+**GUI** -- Electron desktop app with command palette, setup wizard, splash screen, dark/light themes, media streaming, extensions, workspaces, file explorer, P2P chat, PIN lock.
+
+**Web Dashboard** -- Browser-based node management. REST API + WebSocket, OAuth login, chat, billing.
+
+**Discovery Server** -- Separate repo: [palexplorer-server](../palexplorer-server). Identity resolution, message relay, OAuth, Lemon Squeezy billing, self-update server. Self-hostable via Docker.
+
+**PAL/1.0 Protocol** -- Proprietary control protocol on top of BitTorrent/DHT/mDNS. 27 message types, policy engine, smart routing.
+
+## Ecosystem
+
+| Project | Description |
+|:---|:---|
+| [palexplorer](.) | Desktop app (Electron + React + CLI) |
+| [palexplorer-server](../palexplorer-server) | Discovery server (Express 5 + LevelDB) |
+| [palexplorer-www](../palexplorer-www) | Web dashboard (React + Express) |
+| [palexplorer-mobile](../palexplorer-mobile) | Mobile app (React Native) |
+| [palexplorer-sdk](../palexplorer-sdk) | JavaScript SDK for integrations |
+
+## Repo Review
+
+A focused architecture and product review was added on 2026-03-23.
+
+Executive summary:
+- `palexplorer` is the core desktop product, not just a thin client.
+- Do not rename `palexplorer` to `palexplorer-client`.
+- Keep `palexplorer-mobile` as a separate app, but treat it as a companion surface with shared core packages.
+- Highest-priority fixes are packaged CLI installation, cross-platform packaging parity, startup page loading order, and stale GUI audit documentation.
+
+See:
+- [docs/REPO-REVIEW-2026-03-23.md](docs/REPO-REVIEW-2026-03-23.md)
+- [docs/REPO-REVIEW-ACTION-PLAN-2026-03-23.md](docs/REPO-REVIEW-ACTION-PLAN-2026-03-23.md)
+
+## Development
+
+```bash
+cd palexplorer
+npm install
+npm link
+
+# Run tests
+npm test
+
+# Start the discovery server (separate repo)
+cd ../palexplorer-server
+npm install
+npm start
+```
+
+### Project Structure
+
+```
+bin/              CLI entry point
+lib/commands/     One file per command group (63 files)
+lib/core/         Core logic (identity, shares, groups, sync, transfers, users, backup, extensions, billing, vfs, streaming)
+lib/crypto/       Encryption (stream cipher, share key wrapping)
+lib/protocol/     PAL/1.0 protocol (envelope, messages, policy, router, negotiation, sync, handler)
+lib/utils/        Config, logging, config integrity
+gui/              Electron desktop app (React + Vite)
+web/              Web dashboard (HTML/JS)
+extensions/       Bundled extensions (@palexplorer/vfs, explorer-integration, transfer-analytics, media-streaming)
+test/             Test suite (node:test, incl. stress tests)
+scripts/          Build and publish scripts
+docs/             Documentation
+```
+
+## Security
+
+For full details, see [SECURITY.md](docs/SECURITY.md).
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Write tests for new functionality
+4. Ensure `npm test` passes
+5. Submit a pull request
+
+## License
+
+MIT
+

package/bin/pal.js

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+
+// Enable V8 code caching for faster subsequent boots
+import 'v8-compile-cache-lib';
+
+import { program } from 'commander';
+import chalk from 'chalk';
+
+// Utility for lazy loading commands
+const lazy = (path) => async (program) => {
+  const mod = await import(path);
+  if (mod.default) mod.default(program);
+  else if (typeof mod === 'function') mod(program);
+};
+
+// --- Eagerly load ONLY what is needed for initial setup/parsing ---
+import logger from '../lib/utils/logger.js';
+import { installGlobalErrorHandler } from '../lib/core/analytics.js';
+installGlobalErrorHandler();
+
+globalThis.__palMode = 'cli';
+
+// --- Lazy load the big migration/core logic only if needed ---
+const runMigrations = async () => {
+  const { migrateShareKeys } = await import('../lib/core/shares.js');
+  const { migrateToMultiUser } = await import('../lib/core/users.js');
+  await migrateShareKeys();
+  migrateToMultiUser();
+};
+
+// Apply persisted log level from config before anything else
+import config from '../lib/utils/config.js';
+const settings = config.get('settings') || {};
+const configuredLevel = settings.logLevel;
+if (configuredLevel) logger.setLevel(configuredLevel);
+
+// Parse --log-level early (before Commander) so it works before subcommands
+const logLevelIdx = process.argv.indexOf('--log-level');
+if (logLevelIdx !== -1 && process.argv[logLevelIdx + 1]) {
+  const cliLevel = process.argv[logLevelIdx + 1];
+  if (logger.LEVELS.includes(cliLevel)) {
+    logger.setLevel(cliLevel);
+    process.argv.splice(logLevelIdx, 2);
+  }
+}
+
+logger.applyGlobalOverride();
+
+program
+  .name('pe')
+  .description('p2p file sharing for friends')
+  .version('0.4.0')
+  .option('--json', 'output in JSON format')
+  .option('--log-level <level>', 'set log level (debug, info, warn, error, silent)');
+
+// Register Commands LAZILY
+// Note: Commander requires commands to be defined upfront for help/autocompletion,
+// but the actual .js files containing the complex registration logic (with their own imports) 
+// are what we are lazy-loading here.
+const commands = [
+  ['init', '../lib/commands/init.js'],
+  ['whoami', '../lib/commands/whoami.js'],
+  ['register', '../lib/commands/register.js'],
+  ['recover', '../lib/commands/recover.js'],
+  ['share', '../lib/commands/share.js'],
+  ['download', '../lib/commands/download.js'],
+  ['list', '../lib/commands/list.js'],
+  ['revoke', '../lib/commands/revoke.js'],
+  ['serve', '../lib/commands/serve.js'],
+  ['pal', '../lib/commands/pal.js'],
+  ['invite', '../lib/commands/invite.js'],
+  ['nearby', '../lib/commands/nearby.js'],
+  ['group', '../lib/commands/group.js'],
+  ['sync', '../lib/commands/sync.js'],
+  ['transfers', '../lib/commands/transfers.js'],
+  ['config', '../lib/commands/config.js'],
+  ['device', '../lib/commands/device.js'],
+  ['server', '../lib/commands/server.js'],
+  ['explorer', '../lib/commands/explorer.js'],
+  ['status', '../lib/commands/status.js'],
+  ['log', '../lib/commands/log.js'],
+  ['completion', '../lib/commands/completion.js'],
+  ['web', '../lib/commands/web.js'],
+  ['gui-share', '../lib/commands/gui-share.js'],
+  ['vfs', '../lib/commands/vfs.js'],
+  ['file', '../lib/commands/file.js'],
+  ['remote', '../lib/commands/remote.js'],
+  ['user', '../lib/commands/user.js'],
+  ['schedule', '../lib/commands/schedule.js'],
+  ['chat', '../lib/commands/chat.js'],
+  ['backup', '../lib/commands/backup.js'],
+  ['api-keys', '../lib/commands/api-keys.js'],
+  ['share-link', '../lib/commands/share-link.js'],
+  ['comment', '../lib/commands/comment.js'],
+  ['update', '../lib/commands/update.js'],
+  ['auth', '../lib/commands/auth.js'],
+  ['network', '../lib/commands/network.js'],
+  ['search', '../lib/commands/search.js'],
+  ['connect', '../lib/commands/connect.js'],
+  ['protocol', '../lib/commands/protocol.js'],
+  ['workspace', '../lib/commands/workspace.js'],
+  ['favorite', '../lib/commands/favorite.js'],
+  ['pin', '../lib/commands/pin.js'],
+  ['stream', '../lib/commands/stream.js'],
+  ['uninstall', '../lib/commands/uninstall.js'],
+  ['extension', '../lib/commands/extension.js'],
+  ['ext', '../lib/commands/extension.js'],
+  ['billing', '../lib/commands/billing.js'],
+  ['permissions', '../lib/commands/permissions.js'],
+  ['org', '../lib/commands/org.js'],
+  ['su', '../lib/commands/su.js'],
+  ['federation', '../lib/commands/federation.js'],
+  ['analytics', '../lib/commands/analytics.js'],
+  ['webhook', '../lib/commands/webhook.js'],
+  ['relay', '../lib/commands/relay.js'],
+  ['compliance', '../lib/commands/compliance.js'],
+  ['sso', '../lib/commands/sso.js'],
+  ['rbac', '../lib/commands/rbac.js'],
+  ['scim', '../lib/commands/scim.js'],
+  ['audit', '../lib/commands/audit.js'],
+  ['scanner', '../lib/commands/scanner.js'],
+  ['notify', '../lib/commands/notify.js'],
+  ['cloud-backup', '../lib/commands/cloud-backup.js'],
+  ['dept', '../lib/commands/dept.js'],
+];
+
+// To keep it truly fast, we should only register the specific command being run.
+// Commander's parseAsync will handle the matching.
+const currentCmd = process.argv[2];
+const cmdMatch = commands.find(c => c[0] === currentCmd);
+
+// Commands that don't modify data — skip migrations for speed
+const readOnlyCommands = new Set([
+  'whoami', 'status', 'list', 'log', 'completion', 'nearby',
+  'protocol', 'pin', 'favorite', 'search', 'workspace',
+]);
+const isVersionOrHelp = !currentCmd || currentCmd === '--help' || currentCmd === '-h'
+  || currentCmd === '--version' || currentCmd === '-V';
+const needsMigrations = cmdMatch && !readOnlyCommands.has(cmdMatch[0]) && !isVersionOrHelp;
+
+if (cmdMatch) {
+  if (needsMigrations) await runMigrations();
+  const register = await lazy(cmdMatch[1]);
+  await register(program);
+} else if (isVersionOrHelp) {
+  // Help/version — load all commands for full help text, skip migrations
+  await Promise.all(commands.map(c => lazy(c[1])(program)));
+} else {
+  // Unknown command — load all for Commander to handle
+  await runMigrations();
+  await Promise.all(commands.map(c => lazy(c[1])(program)));
+}
+
+// Grouped help text
+program.addHelpText('after', `
+${chalk.cyan.bold('Command Groups:')}
+
+  ${chalk.yellow('Identity:')}     init, whoami, register, verify, recover
+  ${chalk.yellow('Users:')}        user list/add/remove/promote, login
+  ${chalk.yellow('Sharing:')}      share, list, revoke, serve, download, share-link, share-rename, permissions
+  ${chalk.yellow('Sync:')}         sync push/pull/status/watch/list/remove/diff
+  ${chalk.yellow('Files:')}        file ls/tree/info/copy/move/rename/mkdir/delete/search/open/reveal/audit
+  ${chalk.yellow('Remote:')}       remote browse/files/download
+  ${chalk.yellow('Social:')}       pal, invite, nearby, group, chat, comment
+  ${chalk.yellow('Search:')}       search (files, pals, groups)
+  ${chalk.yellow('Network:')}      network create/list/info/invite/join/members/groups/connect/disconnect
+  ${chalk.yellow('Workspace:')}    workspace list/create/delete/add/remove
+  ${chalk.yellow('Management:')}   transfers, config, device, server, explorer, vfs, web, schedule, favorite
+  ${chalk.yellow('Protocol:')}     protocol info/policy/route/envelope/keys
+  ${chalk.yellow('PIN:')}          pin set/remove/status
+  ${chalk.yellow('Billing:')}      billing status/plans/activate/deactivate/checkout
+  ${chalk.yellow('Pro:')}          backup, api-keys
+  ${chalk.yellow('Streaming:')}    stream local/remote/stop/status/broadcast/join/transport
+  ${chalk.yellow('Extensions:')}   ext list/install/remove/enable/disable/info/config/create
+  ${chalk.yellow('Orgs:')}         org create/list/info/invite/remove/subscribe/unsubscribe/billing
+  ${chalk.yellow('Utilities:')}    status, log, completion, gui-share, uninstall
+
+${chalk.gray('Aliases: pe connect → pe network connect, pe disconnect → pe network disconnect')}
+`);
+
+// Load extensions and emit lifecycle hooks
+let extensionsLoaded = false;
+if (!isVersionOrHelp) {
+  try {
+    const { loadAllExtensions, hooks, ensureDefaultExtensions } = await import('../lib/core/extensions.js');
+    ensureDefaultExtensions();
+    await loadAllExtensions();
+    extensionsLoaded = true;
+
+    // Clean stale transfers (0% for >24h)
+    const { cleanStaleTransfers } = await import('../lib/core/transfers.js');
+    const cleaned = cleanStaleTransfers(24);
+    if (cleaned > 0) console.log(`[transfers] Cleaned ${cleaned} stale transfer(s)`);
+
+    const identity = (await import('../lib/utils/config.js')).default.get('identity');
+    await hooks.emit('on:app:ready', {
+      version: program.version(),
+      identity: identity ? { handle: identity.handle, publicKey: identity.publicKey } : null,
+      mode: 'cli',
+    });
+
+    const shutdown = async () => {
+      await hooks.emit('on:app:shutdown', {});
+      process.exit(process.exitCode || 0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+  } catch (err) {
+    // Extension loading is non-fatal
+    logger.warn?.(`Extension loading failed: ${err.message}`) || console.warn(`[extensions] ${err.message}`);
+  }
+}
+
+if (!process.argv.slice(2).length) {
+  program.outputHelp();
+} else {
+  try {
+    await program.parseAsync(process.argv);
+  } catch (err) {
+    if (err.code !== 'commander.helpDisplayed' && err.code !== 'commander.unknownCommand') {
+      console.error(chalk.red(`Error: ${err.message}`));
+    }
+  }
+}
+
+// keytar's native D-Bus handles block the event loop on headless Linux
+const longRunning = new Set(['serve', 'nearby', 'stream']);
+if (!longRunning.has(currentCmd)) {
+  process.exit(process.exitCode || 0);
+}

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