pal-explorer-cli 0.4.0

package/lib/protocol/messages.js

@@ -0,0 +1,247 @@
+import crypto from 'crypto';
+import sodium from 'sodium-native';
+import { create, createEncrypted } from './envelope.js';
+
+// ── Identity & Discovery ──
+
+export function identityAnnounce(keyPair, { handle, deviceId, deviceName, version, lanAddresses, capabilities }) {
+  return create('identity.announce', keyPair, null, {
+    handle,
+    deviceId,
+    deviceName,
+    capabilities: capabilities || ['share', 'sync', 'chat', 'relay'],
+    version,
+    addresses: {
+      lan: lanAddresses || [],
+      public: null,
+    },
+  });
+}
+
+export function identityResolve(keyPair, handle) {
+  return create('identity.resolve', keyPair, null, { handle });
+}
+
+export function identityResponse(keyPair, requesterPK, { handle, publicKey, deviceId, capabilities, lastSeen, source }) {
+  return create('identity.response', keyPair, requesterPK, {
+    handle,
+    publicKey,
+    deviceId: deviceId || null,
+    capabilities: capabilities || [],
+    lastSeen: lastSeen || new Date().toISOString(),
+    source: source || 'server',
+  });
+}
+
+export function heartbeat(keyPair, { handle, deviceId }) {
+  return create('heartbeat', keyPair, null, { handle, deviceId });
+}
+
+// ── Share Negotiation ──
+
+export function shareOffer(keyPair, recipientPK, { shareId, name, type, totalSize, fileCount, policy, preview }) {
+  return createEncrypted('share.offer', keyPair, recipientPK, {
+    shareId,
+    name,
+    type,
+    totalSize,
+    fileCount: fileCount || 0,
+    preview: preview || null,
+    policy: policy || {},
+    encryption: {
+      algorithm: 'xchacha20-poly1305',
+      chunkSize: 65536,
+      manifestEncrypted: true,
+    },
+  });
+}
+
+export function shareAccept(keyPair, sharerPK, { shareId }) {
+  const curve25519PK = Buffer.alloc(sodium.crypto_box_PUBLICKEYBYTES);
+  const edPK = Buffer.isBuffer(keyPair.publicKey) ? keyPair.publicKey : Buffer.from(keyPair.publicKey, 'hex');
+  sodium.crypto_sign_ed25519_pk_to_curve25519(curve25519PK, edPK);
+
+  return create('share.accept', keyPair, sharerPK, {
+    shareId,
+    recipientCurve25519PK: curve25519PK.toString('hex'),
+  });
+}
+
+export function shareKey(keyPair, recipientPK, { shareId, magnet, wrappedKey, manifestHash }) {
+  return createEncrypted('share.key', keyPair, recipientPK, {
+    shareId,
+    magnet,
+    wrappedKey,
+    manifestHash,
+  });
+}
+
+export function shareRevoke(keyPair, recipientPK, { shareId, reason, rotated }) {
+  return create('share.revoke', keyPair, recipientPK, {
+    shareId,
+    reason: reason || 'revoked',
+    rotated: rotated || false,
+  });
+}
+
+export function sharePolicyUpdate(keyPair, { shareId, policy }) {
+  return create('share.policy.update', keyPair, null, { shareId, policy });
+}
+
+// ── Transfer Control ──
+
+export function transferRequest(keyPair, seederPK, { shareId, requestedFiles, resumeFrom, clientVersion }) {
+  return create('transfer.request', keyPair, seederPK, {
+    shareId,
+    requestedFiles: requestedFiles || ['*'],
+    resumeFrom: resumeFrom || null,
+    clientVersion,
+  });
+}
+
+export function transferAuthorize(keyPair, downloaderPK, { shareId, magnet, wrappedKey, route, policy }) {
+  return createEncrypted('transfer.authorize', keyPair, downloaderPK, {
+    shareId,
+    magnet,
+    wrappedKey,
+    route: route || { preferred: 'direct', alternatives: [] },
+    policy: policy || {},
+  });
+}
+
+export function transferDeny(keyPair, downloaderPK, { shareId, reason, message }) {
+  return create('transfer.deny', keyPair, downloaderPK, {
+    shareId,
+    reason,
+    message,
+  });
+}
+
+export function transferProgress(keyPair, seederPK, { shareId, bytesTransferred, totalBytes, speed, percent }) {
+  return createEncrypted('transfer.progress', keyPair, seederPK, {
+    shareId,
+    bytesTransferred,
+    totalBytes,
+    speed: speed || 0,
+    percent: percent || 0,
+  });
+}
+
+export function transferComplete(keyPair, seederPK, { shareId, totalBytes, manifestHash }) {
+  return createEncrypted('transfer.complete', keyPair, seederPK, {
+    shareId,
+    totalBytes,
+    manifestHash: manifestHash || null,
+  });
+}
+
+export function transferReceipt(keyPair, downloaderPK, { shareId, downloadedBy, totalBytes, fileCount, manifestHash }) {
+  return createEncrypted('transfer.receipt', keyPair, downloaderPK, {
+    shareId,
+    downloadedBy,
+    completedAt: new Date().toISOString(),
+    totalBytes,
+    fileCount,
+    manifestHash,
+  });
+}
+
+// ── Sync ──
+
+export function syncManifest(keyPair, peerPK, { syncPairId, generation, entries, checksum }) {
+  return createEncrypted('sync.manifest', keyPair, peerPK, {
+    syncPairId,
+    generation,
+    entries,
+    checksum,
+  });
+}
+
+export function syncDiff(keyPair, peerPK, { syncPairId, files }) {
+  return createEncrypted('sync.diff', keyPair, peerPK, {
+    syncPairId,
+    files,
+  });
+}
+
+export function syncRequest(keyPair, peerPK, { syncPairId, files }) {
+  return createEncrypted('sync.request', keyPair, peerPK, {
+    syncPairId,
+    files,
+  });
+}
+
+export function syncConflict(keyPair, peerPK, { syncPairId, conflicts }) {
+  return createEncrypted('sync.conflict', keyPair, peerPK, {
+    syncPairId,
+    conflicts,
+  });
+}
+
+// ── Chat ──
+
+export function chatMessage(keyPair, recipientPK, { text, replyTo }) {
+  return createEncrypted('chat.message', keyPair, recipientPK, {
+    text,
+    replyTo: replyTo || null,
+  });
+}
+
+export function chatAck(keyPair, senderPK, { messageId }) {
+  return create('chat.ack', keyPair, senderPK, { messageId });
+}
+
+export function chatTyping(keyPair, recipientPK) {
+  return create('chat.typing', keyPair, recipientPK, {});
+}
+
+// ── Routing ──
+
+export function routeProbe(keyPair, peerPK, { shareId, lanAddresses, stunResult }) {
+  return create('route.probe', keyPair, peerPK, {
+    shareId,
+    probeId: crypto.randomUUID(),
+    lanAddresses: lanAddresses || [],
+    stunResult: stunResult || null,
+  });
+}
+
+export function routeProbeResponse(keyPair, peerPK, { probeId, reachable, latency, recommended }) {
+  return create('route.probe.response', keyPair, peerPK, {
+    probeId,
+    reachable,
+    latency,
+    recommended,
+  });
+}
+
+export function relayRequest(keyPair, { shareId, estimatedSize, tier }) {
+  return create('relay.request', keyPair, null, {
+    shareId,
+    estimatedSize,
+    tier: tier || 'free',
+  });
+}
+
+export function relayAllocated(keyPair, requesterPK, { urls, username, credential, ttl, bandwidthLimit, priority }) {
+  return createEncrypted('relay.allocated', keyPair, requesterPK, {
+    urls,
+    username,
+    credential,
+    ttl,
+    bandwidthLimit: bandwidthLimit || null,
+    priority: priority || 'normal',
+  });
+}
+
+// ── Server Gossip ──
+
+export function gossipServers(keyPair, peerPK, { servers }) {
+  return create('gossip.servers', keyPair, peerPK, {
+    servers: (servers || []).slice(0, 5).map(s => ({
+      url: s.url,
+      roles: s.roles || [],
+      publicKey: s.publicKey || null,
+    })),
+  });
+}

package/lib/protocol/negotiation.js

@@ -0,0 +1,127 @@
+import sodium from 'sodium-native';
+import { shareOffer, shareAccept, shareKey, shareRevoke, transferAuthorize, transferDeny, transferReceipt } from './messages.js';
+import { enforcePolicy, validatePolicy } from './policy.js';
+import { probeRoutes, buildRouteInfo } from './router.js';
+import { verify, decrypt } from './envelope.js';
+import { getSharePolicy, incrementDownloadCount } from '../core/sharePolicy.js';
+import { isPro } from '../core/pro.js';
+
+export async function initiateShare(keyPair, recipientPK, share, policy) {
+  // Validate policy
+  if (policy) {
+    const validation = validatePolicy(policy);
+    if (!validation.valid) {
+      return { ok: false, errors: validation.errors };
+    }
+  }
+
+  const envelope = shareOffer(keyPair, recipientPK, {
+    shareId: share.id,
+    name: share.name || share.path?.split('/').pop() || 'share',
+    type: share.type,
+    totalSize: share.totalSize || 0,
+    fileCount: share.fileCount || 0,
+    policy: policy || {},
+  });
+
+  return { ok: true, envelope };
+}
+
+export function handleShareAccept(envelope, keyPair) {
+  const result = verify(envelope);
+  if (!result.valid) return { ok: false, errors: result.errors };
+
+  const payload = envelope.payload._enc ? decrypt(envelope, keyPair) : envelope.payload;
+  return {
+    ok: true,
+    shareId: payload.shareId,
+    recipientPK: envelope.from,
+    recipientCurve25519PK: payload.recipientCurve25519PK,
+  };
+}
+
+export function wrapShareKey(shareKeyHex, recipientCurve25519PK) {
+  const recipientPK = Buffer.from(recipientCurve25519PK, 'hex');
+  const shareKeyBuf = Buffer.from(shareKeyHex, 'hex');
+  const cipher = Buffer.alloc(shareKeyBuf.length + sodium.crypto_box_SEALBYTES);
+  sodium.crypto_box_seal(cipher, shareKeyBuf, recipientPK);
+  return cipher.toString('hex');
+}
+
+export function unwrapShareKey(wrappedKeyHex, keyPair) {
+  const cipher = Buffer.from(wrappedKeyHex, 'hex');
+  const curve25519PK = Buffer.alloc(sodium.crypto_box_PUBLICKEYBYTES);
+  const curve25519SK = Buffer.alloc(sodium.crypto_box_SECRETKEYBYTES);
+  sodium.crypto_sign_ed25519_pk_to_curve25519(curve25519PK, keyPair.publicKey);
+  sodium.crypto_sign_ed25519_sk_to_curve25519(curve25519SK, keyPair.privateKey);
+
+  const plaintext = Buffer.alloc(cipher.length - sodium.crypto_box_SEALBYTES);
+  const ok = sodium.crypto_box_seal_open(plaintext, cipher, curve25519PK, curve25519SK);
+  if (!ok) throw new Error('Failed to unwrap share key');
+  return plaintext.toString('hex');
+}
+
+export async function handleTransferRequest(envelope, keyPair, share) {
+  const result = verify(envelope);
+  if (!result.valid) {
+    return { ok: false, envelope: transferDeny(keyPair, envelope.from, {
+      shareId: envelope.payload.shareId,
+      reason: 'unauthorized',
+      message: result.errors.join(', '),
+    })};
+  }
+
+  const shareId = envelope.payload.shareId;
+
+  // Check policy
+  const policy = getSharePolicy(shareId);
+  const access = enforcePolicy(policy, { from: envelope.from });
+  if (!access.allowed) {
+    return { ok: false, envelope: transferDeny(keyPair, envelope.from, {
+      shareId,
+      reason: access.code,
+      message: access.message,
+    })};
+  }
+
+  // Probe routes for best path
+  const routes = await probeRoutes(envelope.from);
+  const routeInfo = buildRouteInfo(routes);
+
+  // Wrap share key for requester
+  let wrappedKey = null;
+  if (share.shareKey) {
+    const recipientEdPK = Buffer.from(envelope.from, 'hex');
+    const recipientCurve = Buffer.alloc(sodium.crypto_box_PUBLICKEYBYTES);
+    sodium.crypto_sign_ed25519_pk_to_curve25519(recipientCurve, recipientEdPK);
+    wrappedKey = wrapShareKey(share.shareKey, recipientCurve.toString('hex'));
+  }
+
+  // Increment download count
+  incrementDownloadCount(shareId);
+
+  return {
+    ok: true,
+    envelope: transferAuthorize(keyPair, envelope.from, {
+      shareId,
+      magnet: share.magnet,
+      wrappedKey,
+      route: routeInfo,
+      policy: {
+        expiresAt: policy?.expiresAt || null,
+        remainingDownloads: access.remainingDownloads,
+      },
+    }),
+  };
+}
+
+export function createReceipt(keyPair, downloaderPK, { shareId, totalBytes, fileCount, manifestHash }) {
+  if (!isPro()) return null; // receipts are Pro only
+  return transferReceipt(keyPair, downloaderPK, {
+    shareId,
+    downloadedBy: downloaderPK,
+    totalBytes,
+    fileCount,
+    manifestHash,
+  });
+}

package/lib/protocol/policy.js

@@ -0,0 +1,142 @@
+import { isPro } from '../core/pro.js';
+
+export const FREE_POLICY_LIMITS = {
+  maxDownloads: null,
+  maxExpiry: 24 * 60 * 60 * 1000, // 24 hours
+  allowScheduleWindow: false,
+  allowIPRestriction: false,
+  allowBandwidthLimit: false,
+  allowReceipts: false,
+};
+
+export const PRO_POLICY_LIMITS = {
+  maxDownloads: null,
+  maxExpiry: null,
+  allowScheduleWindow: true,
+  allowIPRestriction: true,
+  allowBandwidthLimit: true,
+  allowReceipts: true,
+};
+
+function getLimits() {
+  return isPro() ? PRO_POLICY_LIMITS : FREE_POLICY_LIMITS;
+}
+
+export function validatePolicy(policy) {
+  const limits = getLimits();
+  const errors = [];
+
+  if (policy.expiresAt) {
+    const ttl = new Date(policy.expiresAt).getTime() - Date.now();
+    if (ttl <= 0) {
+      errors.push('Policy expiresAt is in the past');
+    }
+    if (limits.maxExpiry && ttl > limits.maxExpiry) {
+      errors.push(`Free tier: max expiry is ${limits.maxExpiry / 3600000}h. Upgrade to Pro for custom expiry.`);
+    }
+  }
+
+  if (policy.scheduleWindow && !limits.allowScheduleWindow) {
+    errors.push('Schedule windows require Pro. Upgrade to Pro for transfer scheduling.');
+  }
+
+  if (policy.allowedIPs && policy.allowedIPs.length > 0 && !limits.allowIPRestriction) {
+    errors.push('IP restrictions require Pro. Upgrade to Pro for IP-based access control.');
+  }
+
+  if (policy.bandwidthLimit && !limits.allowBandwidthLimit) {
+    errors.push('Bandwidth limits require Pro.');
+  }
+
+  if (policy.requireReceipt && !limits.allowReceipts) {
+    errors.push('Download receipts require Pro.');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+export function enforcePolicy(policy, request) {
+  if (!policy) return { allowed: true };
+
+  // Expiry check
+  if (policy.expiresAt && new Date(policy.expiresAt) < new Date()) {
+    return { allowed: false, code: 'E_EXPIRED', message: `Share expired on ${policy.expiresAt}` };
+  }
+
+  // Download limit
+  if (policy.maxDownloads != null && (policy.downloadCount || 0) >= policy.maxDownloads) {
+    return {
+      allowed: false,
+      code: 'E_POLICY_VIOLATION',
+      message: `Download limit reached (${policy.maxDownloads})`,
+    };
+  }
+
+  // Recipient check
+  if (policy.allowedRecipients && policy.allowedRecipients.length > 0) {
+    if (!request?.from || !policy.allowedRecipients.includes(request.from)) {
+      return { allowed: false, code: 'E_UNAUTHORIZED', message: 'Not an authorized recipient' };
+    }
+  }
+
+  // IP check
+  if (policy.allowedIPs && policy.allowedIPs.length > 0) {
+    if (!request?.ip || !matchIP(request.ip, policy.allowedIPs)) {
+      return { allowed: false, code: 'E_POLICY_VIOLATION', message: 'IP not in allowed list' };
+    }
+  }
+
+  // Schedule window
+  if (policy.scheduleWindow) {
+    if (!isWithinWindow(policy.scheduleWindow)) {
+      return {
+        allowed: false,
+        code: 'E_POLICY_VIOLATION',
+        message: `Transfers allowed ${policy.scheduleWindow.start}-${policy.scheduleWindow.end} ${policy.scheduleWindow.timezone || 'UTC'}`,
+      };
+    }
+  }
+
+  return {
+    allowed: true,
+    remainingDownloads: policy.maxDownloads != null ? policy.maxDownloads - (policy.downloadCount || 0) : null,
+  };
+}
+
+function matchIP(ip, allowedIPs) {
+  for (const allowed of allowedIPs) {
+    if (allowed.includes('/')) {
+      if (isInSubnet(ip, allowed)) return true;
+    } else {
+      if (ip === allowed) return true;
+    }
+  }
+  return false;
+}
+
+function isInSubnet(ip, cidr) {
+  const [subnet, bits] = cidr.split('/');
+  const mask = ~((1 << (32 - parseInt(bits))) - 1) >>> 0;
+  const ipNum = ipToNum(ip);
+  const subnetNum = ipToNum(subnet);
+  return (ipNum & mask) === (subnetNum & mask);
+}
+
+function ipToNum(ip) {
+  return ip.split('.').reduce((acc, octet) => (acc << 8) + parseInt(octet), 0) >>> 0;
+}
+
+function isWithinWindow(window) {
+  const now = new Date();
+  const [startH, startM] = window.start.split(':').map(Number);
+  const [endH, endM] = window.end.split(':').map(Number);
+  const currentMinutes = now.getUTCHours() * 60 + now.getUTCMinutes();
+  const startMinutes = startH * 60 + startM;
+  const endMinutes = endH * 60 + endM;
+
+  if (startMinutes <= endMinutes) {
+    return currentMinutes >= startMinutes && currentMinutes < endMinutes;
+  }
+  // Overnight window (e.g. 22:00 - 06:00)
+  return currentMinutes >= startMinutes || currentMinutes < endMinutes;
+}

package/lib/protocol/router.js

@@ -0,0 +1,86 @@
+import { getNearbyPeers } from '../core/mdnsService.js';
+import { fetchTurnCredentials } from '../core/discoveryClient.js';
+import { isPro } from '../core/pro.js';
+import { sendRequest } from '../core/signalingServer.js';
+
+export const ROUTE_PRIORITY = ['lan', 'direct', 'relay'];
+
+const RELAY_LIMITS = {
+  free: { bandwidth: 5 * 1024 * 1024, sessionDuration: 3600, concurrent: 1 },
+  pro: { bandwidth: null, sessionDuration: 86400, concurrent: 10 },
+};
+
+export function getRelayLimits() {
+  return isPro() ? RELAY_LIMITS.pro : RELAY_LIMITS.free;
+}
+
+export async function probeRoutes(targetPK, { lanAddresses } = {}) {
+  const results = { lan: null, direct: null, relay: null };
+
+  // LAN probe — check if target is on local network via mDNS (pure TCP)
+  try {
+    const nearby = getNearbyPeers();
+    const lanPeer = nearby.find(p => p.publicKey === targetPK);
+    if (lanPeer) {
+      const start = Date.now();
+      const resp = await sendRequest(lanPeer.ip, 7474, { type: 'status' }, 2000);
+      if (resp.ok) {
+        results.lan = { reachable: true, latency: Date.now() - start, address: `${lanPeer.ip}:7474` };
+      }
+    }
+  } catch {
+    results.lan = { reachable: false };
+  }
+
+  // Direct probe — try known addresses (pure TCP)
+  if (lanAddresses?.length) {
+    for (const addr of lanAddresses) {
+      try {
+        const [host, port] = addr.includes(':') ? addr.split(':') : [addr, 7474];
+        const start = Date.now();
+        const resp = await sendRequest(host, parseInt(port, 10), { type: 'status' }, 3000);
+        if (resp.ok) {
+          results.direct = { reachable: true, latency: Date.now() - start, address: addr };
+          break;
+        }
+      } catch {}
+    }
+  }
+  if (!results.direct) results.direct = { reachable: false };
+
+  // Relay is always available (via TURN)
+  try {
+    const creds = await fetchTurnCredentials();
+    if (creds) {
+      results.relay = { reachable: true, latency: null, credentials: creds };
+    } else {
+      results.relay = { reachable: false };
+    }
+  } catch {
+    results.relay = { reachable: false };
+  }
+
+  return results;
+}
+
+export function selectRoute(probeResults) {
+  for (const route of ROUTE_PRIORITY) {
+    if (probeResults[route]?.reachable) {
+      return {
+        type: route,
+        ...probeResults[route],
+      };
+    }
+  }
+  return null;
+}
+
+export function buildRouteInfo(probeResults) {
+  const selected = selectRoute(probeResults);
+  return {
+    preferred: selected?.type || null,
+    alternatives: ROUTE_PRIORITY.filter(r => r !== selected?.type && probeResults[r]?.reachable),
+    lanAddress: probeResults.lan?.address || null,
+    relayToken: probeResults.relay?.credentials || null,
+  };
+}