pal-explorer-cli 0.4.0

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

@@ -0,0 +1,27 @@
+{
+  "name": "analytics",
+  "version": "1.0.0",
+  "description": "Anonymous usage analytics via PostHog — opt-in, no PII, privacy-safe",
+  "author": "Palexplorer Team",
+  "license": "MIT",
+  "main": "index.js",
+  "hooks": [
+    "on:app:ready",
+    "on:app:shutdown",
+    "after:share:create",
+    "after:share:revoke",
+    "after:download:complete",
+    "on:config:change",
+    "after:billing:upgrade",
+    "after:billing:downgrade"
+  ],
+  "permissions": ["config:read", "config:write", "net:http"],
+  "config": {
+    "enabled": { "type": "boolean", "default": false, "description": "Enable anonymous usage analytics (opt-in)" },
+    "posthogKey": { "type": "string", "default": "", "description": "PostHog project API key (leave empty for default)" },
+    "posthogHost": { "type": "string", "default": "https://us.i.posthog.com", "description": "PostHog ingestion host" },
+    "sessionTracking": { "type": "boolean", "default": true, "description": "Track session duration" }
+  },
+  "pro": false,
+  "minAppVersion": "0.4.0"
+}

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

@@ -0,0 +1,186 @@
+import crypto from 'crypto';
+import { createRequire } from 'module';
+
+const DEFAULT_POSTHOG_KEY = 'phc_PSslPgpRuFzQf6s5qbN9atXFGUDHzCvMlmpBTtdTkte';
+const FLUSH_INTERVAL = 30_000;
+const MAX_QUEUE = 100;
+
+let ctx = null;
+let posthog = null;
+let sessionStart = null;
+let queue = [];
+let flushTimer = null;
+let online = true;
+let initialized = false;
+
+function getDeviceId() {
+  let id = ctx.store.get('deviceId');
+  if (!id) {
+    id = crypto.randomUUID();
+    ctx.store.set('deviceId', id);
+  }
+  return id;
+}
+
+function isEnabled() {
+  return ctx.config.get('enabled') === true;
+}
+
+function baseProperties() {
+  return {
+    platform: process.platform,
+    version: ctx.app.version,
+    arch: process.arch,
+  };
+}
+
+async function initPostHog() {
+  if (posthog) return;
+  try {
+    // Resolve posthog-node from the app's node_modules (deployed extensions can't resolve from their own path)
+    let PostHog;
+    try {
+      const appRoot = ctx.app.appRoot || process.cwd();
+      const require = createRequire(appRoot + '/package.json');
+      PostHog = require('posthog-node').PostHog;
+    } catch {
+      PostHog = (await import('posthog-node')).PostHog;
+    }
+    const key = ctx.config.get('posthogKey') || DEFAULT_POSTHOG_KEY;
+    const host = ctx.config.get('posthogHost') || 'https://us.i.posthog.com';
+    posthog = new PostHog(key, { host, flushAt: 20, flushInterval: FLUSH_INTERVAL });
+  } catch (err) {
+    ctx.logger.warn('PostHog not available:', err.message);
+  }
+}
+
+function send(event, properties = {}) {
+  if (!isEnabled() || !posthog) return;
+
+  const props = { ...baseProperties(), ...properties };
+  const deviceId = getDeviceId();
+
+  posthog.capture({ distinctId: deviceId, event, properties: props });
+}
+
+function track(event, properties = {}) {
+  if (!isEnabled()) return;
+
+  if (!online) {
+    if (queue.length < MAX_QUEUE) {
+      queue.push({ event, properties });
+    }
+    return;
+  }
+
+  send(event, properties);
+}
+
+function flushQueue() {
+  while (queue.length > 0) {
+    const { event, properties } = queue.shift();
+    send(event, properties);
+  }
+}
+
+function startPeriodicFlush() {
+  if (flushTimer) return;
+  flushTimer = setInterval(() => {
+    if (online && queue.length > 0) flushQueue();
+  }, FLUSH_INTERVAL);
+  flushTimer.unref?.();
+}
+
+async function startTracking() {
+  if (initialized) return;
+  await initPostHog();
+  startPeriodicFlush();
+  sessionStart = Date.now();
+  initialized = true;
+  track('app_open');
+  ctx.logger.info('Analytics enabled — PostHog tracking started');
+}
+
+export async function activate(context) {
+  ctx = context;
+
+  // Register hooks regardless of enabled state — they check isEnabled() internally
+  context.hooks.on('on:app:ready', async () => {
+    context.logger.info('Analytics extension ready');
+  });
+
+  context.hooks.on('on:app:shutdown', async () => {
+    const duration = sessionStart ? Math.round((Date.now() - sessionStart) / 1000) : 0;
+    if (ctx.config.get('sessionTracking') !== false) {
+      track('app_close', { sessionDurationSec: duration });
+    }
+    if (posthog) {
+      try { await posthog.flush(); } catch {}
+    }
+  });
+
+  context.hooks.on('after:share:create', async ({ shareId, name, ...rest }) => {
+    track('share_created', {
+      visibility: rest.visibility,
+      recipientCount: rest.recipients?.length || 0,
+    });
+  });
+
+  context.hooks.on('after:share:revoke', async () => {
+    track('share_revoked');
+  });
+
+  context.hooks.on('after:download:complete', async ({ size, duration, speed }) => {
+    track('transfer_complete', {
+      size: size || 0,
+      duration: duration || 0,
+      speed: speed || 0,
+    });
+  });
+
+  context.hooks.on('on:config:change', async ({ key, value }) => {
+    // Hot-enable: if analytics was just turned on, initialize PostHog
+    if (key === 'ext.analytics' || key === 'enabled') {
+      if (isEnabled() && !initialized) {
+        await startTracking();
+      }
+    }
+    track('settings_changed', { key });
+  });
+
+  context.hooks.on('after:billing:upgrade', async ({ plan }) => {
+    track('pro_upgrade', { plan });
+  });
+
+  context.hooks.on('after:billing:downgrade', async ({ reason }) => {
+    track('pro_downgrade', { reason });
+  });
+
+  // If already enabled at startup, start immediately
+  if (isEnabled()) {
+    await startTracking();
+  } else {
+    context.logger.info('Analytics disabled (opt-in required) — will start when enabled');
+  }
+}
+
+export async function deactivate() {
+  if (flushTimer) {
+    clearInterval(flushTimer);
+    flushTimer = null;
+  }
+  if (posthog) {
+    try { await posthog.flush(); } catch {}
+    await posthog.shutdown();
+    posthog = null;
+  }
+  queue = [];
+  sessionStart = null;
+  initialized = false;
+  ctx = null;
+}
+
+export function setOnline(isOnline) {
+  online = isOnline;
+  if (isOnline && queue.length > 0) flushQueue();
+}

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/extensions/@palexplorer/audit/extension.json

@@ -0,0 +1,17 @@
+{
+  "name": "audit",
+  "version": "1.0.0",
+  "description": "Activity log and audit trail",
+  "author": "Palexplorer Team",
+  "license": "MIT",
+  "main": "index.js",
+  "hooks": ["on:app:ready"],
+  "permissions": ["audit:read"],
+  "contributes": {
+    "pages": [
+      { "id": "activity", "label": "activity", "icon": "Activity", "section": "system", "minLevel": "owner" }
+    ]
+  },
+  "config": { "enabled": { "type": "boolean", "default": false } },
+  "pro": false
+}

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

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

package/extensions/@palexplorer/auth-email/extension.json

@@ -0,0 +1,17 @@
+{
+  "name": "auth-email",
+  "version": "1.0.0",
+  "description": "Link your email to your Palexplorer handle for verification and recovery",
+  "author": "Palexplorer Team",
+  "license": "Proprietary",
+  "main": "index.js",
+  "hooks": ["on:app:ready"],
+  "permissions": ["identity:read", "identity:write", "config:read", "config:write", "net:http", "notifications"],
+  "config": {
+    "server": { "type": "string", "default": "https://discovery.palexplorer.com", "description": "Discovery server for email auth" },
+    "verifiedEmail": { "type": "string", "default": "", "description": "Currently verified email" },
+    "verifiedToken": { "type": "string", "default": "", "description": "Verified JWT token" }
+  },
+  "tier": "free",
+  "minAppVersion": "0.5.0"
+}

package/extensions/@palexplorer/auth-email/index.js

@@ -0,0 +1,102 @@
+export function activate(ctx) {
+  const { hooks, config, logger, http } = ctx;
+
+  // Verification flow
+  ctx.auth = {
+    async requestVerificationCode(email) {
+      const server = config.get('server');
+      logger.info(`Requesting verification code for ${email} from ${server}`);
+      
+      try {
+        const res = await http(`${server}/api/v1/auth/email`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ email })
+        });
+        
+        if (!res.ok) {
+          const data = await res.json();
+          throw new Error(data.error || `Server returned ${res.status}`);
+        }
+        
+        return true;
+      } catch (err) {
+        logger.error(`Failed to request code: ${err.message}`);
+        throw err;
+      }
+    },
+
+    async confirmCode(email, code) {
+      const server = config.get('server');
+      logger.info(`Confirming code for ${email}`);
+      
+      try {
+        const res = await http(`${server}/api/v1/auth/email/verify`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ email, code })
+        });
+        
+        if (!res.ok) {
+          const data = await res.json();
+          throw new Error(data.error || `Server returned ${res.status}`);
+        }
+        
+        const data = await res.json();
+        config.set('verifiedEmail', email);
+        config.set('verifiedToken', data.token);
+        
+        return data;
+      } catch (err) {
+        logger.error(`Failed to confirm code: ${err.message}`);
+        throw err;
+      }
+    },
+
+    async linkIdentity() {
+      const token = config.get('verifiedToken');
+      const email = config.get('verifiedEmail');
+      const server = config.get('server');
+      
+      if (!token) throw new Error('Not logged in with email. Run verify first.');
+      
+      const identity = ctx.identity.get();
+      if (!identity) throw new Error('No local identity found.');
+      
+      logger.info(`Linking identity ${identity.publicKey} to ${email}`);
+      
+      try {
+        const res = await http(`${server}/api/v1/auth/link`, {
+          method: 'POST',
+          headers: { 
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${token}`
+          },
+          body: JSON.stringify({ publicKey: identity.publicKey })
+        });
+        
+        if (!res.ok) {
+          const data = await res.json();
+          throw new Error(data.error || `Server returned ${res.status}`);
+        }
+        
+        ctx.notify.show('Verification Success', `Your Palexplorer handle is now linked to ${email}.`);
+        return true;
+      } catch (err) {
+        logger.error(`Failed to link identity: ${err.message}`);
+        throw err;
+      }
+    }
+  };
+
+  hooks.on('on:app:ready', async ({ identity }) => {
+    const verifiedEmail = config.get('verifiedEmail');
+    if (verifiedEmail) {
+      logger.info(`Running as verified user: ${verifiedEmail}`);
+    }
+  });
+}
+
+export function deactivate() {
+  // Cleanup if needed
+}

package/extensions/@palexplorer/auth-oauth/extension.json

@@ -0,0 +1,16 @@
+{
+  "name": "auth-oauth",
+  "version": "1.0.0",
+  "description": "OAuth 2.0 social login with Google, GitHub, and Microsoft via PKCE flow",
+  "author": "Palexplorer Team",
+  "license": "Proprietary",
+  "main": "index.js",
+  "hooks": ["on:app:ready"],
+  "permissions": ["identity:read", "identity:write", "config:read", "config:write", "net:http"],
+  "config": {
+    "providers": { "type": "array", "default": ["google", "github", "microsoft"], "description": "Enabled OAuth providers" },
+    "autoLink": { "type": "boolean", "default": true, "description": "Automatically link OAuth identity to Palexplorer identity" }
+  },
+  "tier": "free",
+  "minAppVersion": "0.5.0"
+}

package/extensions/@palexplorer/auth-oauth/index.js

@@ -0,0 +1,199 @@
+import { randomBytes, createHash } from 'node:crypto';
+
+const PROVIDER_CONFIG = {
+  google: {
+    authUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+    tokenUrl: 'https://oauth2.googleapis.com/token',
+    userInfoUrl: 'https://www.googleapis.com/oauth2/v3/userinfo',
+    scopes: 'openid email profile',
+  },
+  github: {
+    authUrl: 'https://github.com/login/oauth/authorize',
+    tokenUrl: 'https://github.com/login/oauth/access_token',
+    userInfoUrl: 'https://api.github.com/user',
+    scopes: 'read:user user:email',
+  },
+  microsoft: {
+    authUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/authorize',
+    tokenUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
+    userInfoUrl: 'https://graph.microsoft.com/v1.0/me',
+    scopes: 'openid email profile',
+  },
+};
+
+let ctx = null;
+let pendingAuth = null;
+
+export function activate(context) {
+  ctx = context;
+  const { hooks, config, logger } = context;
+
+  context.oauth = {
+    getProviders() {
+      return config.get('providers') || [];
+    },
+
+    async initiateLogin(provider) {
+      return startOAuthFlow(provider, context);
+    },
+
+    async handleCallback(callbackUrl) {
+      return processCallback(callbackUrl, context);
+    },
+
+    getLinkedAccounts() {
+      return context.store.get('linkedAccounts') || [];
+    },
+
+    async unlinkAccount(provider) {
+      const accounts = context.store.get('linkedAccounts') || [];
+      const filtered = accounts.filter(a => a.provider !== provider);
+      context.store.set('linkedAccounts', filtered);
+      logger.info(`Unlinked ${provider} account`);
+    },
+  };
+
+  hooks.on('on:app:ready', async () => {
+    const accounts = context.store.get('linkedAccounts') || [];
+    if (accounts.length > 0) {
+      logger.info(`OAuth: ${accounts.length} linked account(s): ${accounts.map(a => a.provider).join(', ')}`);
+    }
+  });
+}
+
+export function deactivate() {
+  ctx = null;
+  pendingAuth = null;
+}
+
+function generatePKCE() {
+  const verifier = randomBytes(32).toString('base64url');
+  const challenge = createHash('sha256').update(verifier).digest('base64url');
+  return { verifier, challenge };
+}
+
+async function startOAuthFlow(provider, ctx) {
+  const providerCfg = PROVIDER_CONFIG[provider];
+  if (!providerCfg) throw new Error(`Unsupported OAuth provider: ${provider}`);
+
+  const enabled = ctx.config.get('providers') || [];
+  if (!enabled.includes(provider)) throw new Error(`Provider ${provider} is not enabled`);
+
+  const { verifier, challenge } = generatePKCE();
+  const state = randomBytes(16).toString('hex');
+
+  pendingAuth = { provider, verifier, state, startedAt: Date.now() };
+
+  const params = new URLSearchParams({
+    response_type: 'code',
+    scope: providerCfg.scopes,
+    redirect_uri: 'palexplorer://oauth/callback',
+    state,
+    code_challenge: challenge,
+    code_challenge_method: 'S256',
+  });
+
+  const authUrl = `${providerCfg.authUrl}?${params}`;
+  ctx.logger.info(`OAuth: opening browser for ${provider} login`);
+
+  return { url: authUrl, state, provider };
+}
+
+async function processCallback(callbackUrl, ctx) {
+  if (!pendingAuth) throw new Error('No pending OAuth flow');
+
+  const url = new URL(callbackUrl);
+  const code = url.searchParams.get('code');
+  const state = url.searchParams.get('state');
+  const error = url.searchParams.get('error');
+
+  if (error) {
+    pendingAuth = null;
+    throw new Error(`OAuth error: ${error}`);
+  }
+
+  if (state !== pendingAuth.state) {
+    pendingAuth = null;
+    throw new Error('OAuth state mismatch — possible CSRF attack');
+  }
+
+  const { provider, verifier } = pendingAuth;
+  const providerCfg = PROVIDER_CONFIG[provider];
+  pendingAuth = null;
+
+  // Exchange code for tokens
+  const tokenRes = await ctx.http(providerCfg.tokenUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+    body: new URLSearchParams({
+      grant_type: 'authorization_code',
+      code,
+      redirect_uri: 'palexplorer://oauth/callback',
+      code_verifier: verifier,
+    }).toString(),
+  });
+
+  if (!tokenRes.ok) throw new Error(`Token exchange failed: ${tokenRes.status}`);
+  const tokens = await tokenRes.json();
+
+  // Fetch user info
+  const userRes = await ctx.http(providerCfg.userInfoUrl, {
+    headers: { Authorization: `Bearer ${tokens.access_token}`, Accept: 'application/json' },
+  });
+
+  if (!userRes.ok) throw new Error(`Failed to fetch user info: ${userRes.status}`);
+  const userInfo = await userRes.json();
+
+  const profile = normalizeProfile(provider, userInfo);
+
+  // Link to local identity
+  if (ctx.config.get('autoLink')) {
+    await linkToIdentity(ctx, provider, profile);
+  }
+
+  return profile;
+}
+
+function normalizeProfile(provider, raw) {
+  switch (provider) {
+    case 'google':
+      return { provider, email: raw.email, name: raw.name, avatar: raw.picture };
+    case 'github':
+      return { provider, email: raw.email, name: raw.name || raw.login, avatar: raw.avatar_url };
+    case 'microsoft':
+      return { provider, email: raw.mail || raw.userPrincipalName, name: raw.displayName, avatar: null };
+    default:
+      return { provider, email: raw.email, name: raw.name, avatar: null };
+  }
+}
+
+async function linkToIdentity(ctx, provider, profile) {
+  const identity = ctx.identity?.get?.() || ctx.identity;
+  if (!identity?.publicKey) {
+    ctx.logger.warn('OAuth: no local identity to link');
+    return;
+  }
+
+  const accounts = ctx.store.get('linkedAccounts') || [];
+  const existing = accounts.findIndex(a => a.provider === provider);
+  const entry = {
+    provider,
+    email: profile.email,
+    name: profile.name,
+    publicKey: identity.publicKey,
+    linkedAt: new Date().toISOString(),
+  };
+
+  if (existing >= 0) {
+    accounts[existing] = entry;
+  } else {
+    accounts.push(entry);
+  }
+
+  ctx.store.set('linkedAccounts', accounts);
+  ctx.logger.info(`OAuth: linked ${provider} (${profile.email}) to identity ${identity.publicKey.slice(0, 16)}`);
+
+  if (ctx.notify?.show) {
+    ctx.notify.show('Account Linked', `${profile.name} (${provider}) linked to your Palexplorer identity.`);
+  }
+}

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

@@ -0,0 +1,17 @@
+{
+  "name": "chat",
+  "version": "1.0.0",
+  "description": "1:1 messaging with pals",
+  "author": "Palexplorer Team",
+  "license": "MIT",
+  "main": "index.js",
+  "hooks": ["on:app:ready"],
+  "permissions": [],
+  "contributes": {
+    "pages": [
+      { "id": "chat", "label": "chat", "icon": "MessagesSquare", "section": "social" }
+    ]
+  },
+  "config": { "enabled": { "type": "boolean", "default": true } },
+  "pro": false
+}

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

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