pal-explorer-cli 0.4.0

package/lib/crypto/streamEncryption.js

@@ -0,0 +1,189 @@
+import sodium from 'sodium-native';
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import config from '../utils/config.js';
+
+const CHUNK_SIZE = 65536;
+
+export function getEncryptedSeedDir(shareId) {
+  const baseDir = path.dirname(config.path);
+  return path.join(baseDir, 'encrypted-seeds', shareId);
+}
+
+export function getDecryptedDownloadDir(shareName) {
+  const baseDir = path.dirname(config.path);
+  return path.join(baseDir, 'decrypted-downloads', shareName);
+}
+
+function hashFileName(name, shareKey) {
+  const hmac = crypto.createHmac('sha256', shareKey);
+  hmac.update(name);
+  return hmac.digest('hex').slice(0, 32) + '.enc';
+}
+
+export function encryptFileStream(inputPath, outputPath, shareKey) {
+  const state = Buffer.alloc(sodium.crypto_secretstream_xchacha20poly1305_STATEBYTES);
+  const header = Buffer.alloc(sodium.crypto_secretstream_xchacha20poly1305_HEADERBYTES);
+  sodium.crypto_secretstream_xchacha20poly1305_init_push(state, header, shareKey);
+
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  const input = fs.openSync(inputPath, 'r');
+  const output = fs.openSync(outputPath, 'w');
+  fs.writeSync(output, header);
+
+  const plainBuf = Buffer.alloc(CHUNK_SIZE);
+  const fileSize = fs.fstatSync(input).size;
+  let totalRead = 0;
+
+  while (true) {
+    const bytesRead = fs.readSync(input, plainBuf, 0, CHUNK_SIZE, null);
+    if (bytesRead === 0) break;
+    totalRead += bytesRead;
+    const isLast = totalRead >= fileSize;
+    const plain = plainBuf.subarray(0, bytesRead);
+    const cipher = Buffer.alloc(bytesRead + sodium.crypto_secretstream_xchacha20poly1305_ABYTES);
+    const tag = isLast
+      ? sodium.crypto_secretstream_xchacha20poly1305_TAG_FINAL
+      : sodium.crypto_secretstream_xchacha20poly1305_TAG_MESSAGE;
+    sodium.crypto_secretstream_xchacha20poly1305_push(state, cipher, plain, null, tag);
+    const lenBuf = Buffer.alloc(4);
+    lenBuf.writeUInt32LE(cipher.length, 0);
+    fs.writeSync(output, lenBuf);
+    fs.writeSync(output, cipher);
+    if (isLast) break;
+  }
+
+  fs.closeSync(input);
+  fs.closeSync(output);
+}
+
+export function decryptFileStream(inputPath, outputPath, shareKey) {
+  const state = Buffer.alloc(sodium.crypto_secretstream_xchacha20poly1305_STATEBYTES);
+  const header = Buffer.alloc(sodium.crypto_secretstream_xchacha20poly1305_HEADERBYTES);
+
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  const input = fs.openSync(inputPath, 'r');
+  const tmpPath = outputPath + '.tmp';
+  const output = fs.openSync(tmpPath, 'w');
+
+  fs.readSync(input, header, 0, header.length, null);
+  sodium.crypto_secretstream_xchacha20poly1305_init_pull(state, header, shareKey);
+
+  const lenBuf = Buffer.alloc(4);
+  let fileOffset = header.length;
+
+  try {
+    while (true) {
+      const readLen = fs.readSync(input, lenBuf, 0, 4, fileOffset);
+      if (readLen < 4) break;
+      fileOffset += 4;
+      const chunkLen = lenBuf.readUInt32LE(0);
+      const maxChunk = CHUNK_SIZE + sodium.crypto_secretstream_xchacha20poly1305_ABYTES;
+      if (chunkLen === 0 || chunkLen > maxChunk) {
+        throw new Error('Corrupt ciphertext: invalid chunk length');
+      }
+      const cipher = Buffer.alloc(chunkLen);
+      fs.readSync(input, cipher, 0, chunkLen, fileOffset);
+      fileOffset += chunkLen;
+      const plain = Buffer.alloc(chunkLen - sodium.crypto_secretstream_xchacha20poly1305_ABYTES);
+      const tag = Buffer.alloc(1);
+      sodium.crypto_secretstream_xchacha20poly1305_pull(state, plain, tag, cipher, null);
+      fs.writeSync(output, plain);
+      if (tag[0] === sodium.crypto_secretstream_xchacha20poly1305_TAG_FINAL) break;
+    }
+  } catch {
+    fs.closeSync(input);
+    fs.closeSync(output);
+    try { fs.unlinkSync(tmpPath); } catch {}
+    throw new Error('Decryption failed — data corrupted or wrong key');
+  }
+
+  fs.closeSync(input);
+  fs.closeSync(output);
+  fs.renameSync(tmpPath, outputPath);
+}
+
+export function encryptForSeed(sourcePath, destDir, shareKey) {
+  const manifest = [];
+
+  function walk(dir, relBase) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      const rel = relBase ? path.join(relBase, entry.name) : entry.name;
+      if (entry.isDirectory()) {
+        walk(fullPath, rel);
+      } else if (entry.isFile()) {
+        const hashedName = hashFileName(rel, shareKey);
+        const encPath = path.join(destDir, hashedName);
+        encryptFileStream(fullPath, encPath, shareKey);
+        manifest.push({ hash: hashedName, path: rel });
+      }
+    }
+  }
+
+  fs.mkdirSync(destDir, { recursive: true });
+
+  if (fs.statSync(sourcePath).isDirectory()) {
+    walk(sourcePath, '');
+  } else {
+    const name = path.basename(sourcePath);
+    const hashedName = hashFileName(name, shareKey);
+    const encPath = path.join(destDir, hashedName);
+    encryptFileStream(sourcePath, encPath, shareKey);
+    manifest.push({ hash: hashedName, path: name });
+  }
+
+  // Derive a separate subkey for manifest encryption (key separation)
+  const manifestKey = Buffer.alloc(sodium.crypto_aead_xchacha20poly1305_ietf_KEYBYTES);
+  sodium.crypto_kdf_derive_from_key(manifestKey, 1, Buffer.from('manifest'), shareKey);
+
+  const manifestJson = JSON.stringify(manifest);
+  const manifestBuf = Buffer.from(manifestJson);
+  const nonce = Buffer.alloc(sodium.crypto_aead_xchacha20poly1305_ietf_NPUBBYTES);
+  sodium.randombytes_buf(nonce);
+  const ciphertext = Buffer.alloc(manifestBuf.length + sodium.crypto_aead_xchacha20poly1305_ietf_ABYTES);
+  sodium.crypto_aead_xchacha20poly1305_ietf_encrypt(ciphertext, manifestBuf, null, null, nonce, manifestKey);
+
+  const manifestPath = path.join(destDir, '.manifest.enc');
+  const manifestFile = Buffer.concat([nonce, ciphertext]);
+  fs.writeFileSync(manifestPath, manifestFile);
+
+  return manifest;
+}
+
+export function decryptFromDownload(encryptedDir, destDir, shareKey) {
+  const manifestPath = path.join(encryptedDir, '.manifest.enc');
+  if (!fs.existsSync(manifestPath)) {
+    throw new Error('No encrypted manifest found — cannot decrypt');
+  }
+
+  // Derive the same manifest subkey used during encryption
+  const manifestKey = Buffer.alloc(sodium.crypto_aead_xchacha20poly1305_ietf_KEYBYTES);
+  sodium.crypto_kdf_derive_from_key(manifestKey, 1, Buffer.from('manifest'), shareKey);
+
+  const manifestFile = fs.readFileSync(manifestPath);
+  const nonce = manifestFile.subarray(0, sodium.crypto_aead_xchacha20poly1305_ietf_NPUBBYTES);
+  const ciphertext = manifestFile.subarray(sodium.crypto_aead_xchacha20poly1305_ietf_NPUBBYTES);
+  const plaintext = Buffer.alloc(ciphertext.length - sodium.crypto_aead_xchacha20poly1305_ietf_ABYTES);
+  sodium.crypto_aead_xchacha20poly1305_ietf_decrypt(plaintext, null, ciphertext, null, nonce, manifestKey);
+
+  const manifest = JSON.parse(plaintext.toString());
+  fs.mkdirSync(destDir, { recursive: true });
+
+  for (const entry of manifest) {
+    const encPath = path.resolve(encryptedDir, entry.hash);
+    if (!encPath.startsWith(path.resolve(encryptedDir) + path.sep) && encPath !== path.resolve(encryptedDir)) {
+      throw new Error(`Path traversal detected in manifest hash: ${entry.hash}`);
+    }
+    if (!fs.existsSync(encPath)) continue;
+    const outPath = path.resolve(destDir, entry.path);
+    if (!outPath.startsWith(path.resolve(destDir))) {
+      throw new Error(`Path traversal detected in manifest: ${entry.path}`);
+    }
+    decryptFileStream(encPath, outPath, shareKey);
+  }
+
+  return manifest;
+}

package/lib/package.json

@@ -0,0 +1 @@
+{ "type": "module" }

package/lib/protocol/envelope.js

@@ -0,0 +1,271 @@
+import sodium from 'sodium-native';
+import crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+export const PROTOCOL_VERSION = 1;
+const CLOCK_SKEW_MS = 5 * 60 * 1000; // ±5 minutes
+
+const seenIds = new Map(); // id → expiry timestamp
+const DEDUP_WINDOW_MS = 60 * 60 * 1000; // 1 hour
+
+const REPLAY_CACHE_DIR = path.join(os.homedir(), '.config', 'pal-explorer-cli');
+const REPLAY_CACHE_PATH = path.join(REPLAY_CACHE_DIR, 'replay-cache.json');
+
+function loadReplayCache() {
+  try {
+    if (fs.existsSync(REPLAY_CACHE_PATH)) {
+      const data = JSON.parse(fs.readFileSync(REPLAY_CACHE_PATH, 'utf8'));
+      const now = Date.now();
+      for (const [id, expiry] of Object.entries(data)) {
+        if (expiry > now) seenIds.set(id, expiry);
+      }
+    }
+  } catch {}
+}
+
+export function saveReplayCache() {
+  try {
+    if (!fs.existsSync(REPLAY_CACHE_DIR)) {
+      fs.mkdirSync(REPLAY_CACHE_DIR, { recursive: true });
+    }
+    const obj = Object.fromEntries(seenIds);
+    fs.writeFileSync(REPLAY_CACHE_PATH, JSON.stringify(obj), 'utf8');
+  } catch {}
+}
+
+loadReplayCache();
+if (typeof process !== 'undefined') {
+  process.on('exit', saveReplayCache);
+  process.on('SIGINT', () => { saveReplayCache(); process.exit(0); });
+  process.on('SIGTERM', () => { saveReplayCache(); process.exit(0); });
+}
+
+// Error codes (Appendix B)
+export const ErrorCodes = {
+  E_UNAUTHORIZED: 'E_UNAUTHORIZED',
+  E_EXPIRED: 'E_EXPIRED',
+  E_POLICY_VIOLATION: 'E_POLICY_VIOLATION',
+  E_REVOKED: 'E_REVOKED',
+  E_NOT_FOUND: 'E_NOT_FOUND',
+  E_RATE_LIMITED: 'E_RATE_LIMITED',
+  E_QUOTA_EXCEEDED: 'E_QUOTA_EXCEEDED',
+  E_VERSION_MISMATCH: 'E_VERSION_MISMATCH',
+  E_CLOCK_SKEW: 'E_CLOCK_SKEW',
+  E_REPLAY: 'E_REPLAY',
+  E_CAPABILITY: 'E_CAPABILITY',
+};
+
+// All known message types
+const KNOWN_TYPES = new Set([
+  'identity.announce', 'identity.resolve', 'identity.response', 'heartbeat',
+  'share.offer', 'share.accept', 'share.key', 'share.revoke', 'share.policy.update',
+  'transfer.request', 'transfer.authorize', 'transfer.deny', 'transfer.progress',
+  'transfer.complete', 'transfer.receipt',
+  'sync.manifest', 'sync.diff', 'sync.request', 'sync.conflict',
+  'chat.message', 'chat.ack', 'chat.typing',
+  'route.probe', 'route.probe.response',
+  'relay.request', 'relay.allocated',
+]);
+
+// All known capabilities
+export const CAPABILITIES = {
+  SHARE: 'share',
+  SYNC: 'sync',
+  CHAT: 'chat',
+  RELAY: 'relay',
+  DELTA_SYNC: 'delta-sync',
+  RECEIPTS: 'receipts',
+};
+
+// Capability requirements per message type
+const CAPABILITY_REQUIREMENTS = {
+  'share.offer': CAPABILITIES.SHARE,
+  'share.accept': CAPABILITIES.SHARE,
+  'share.key': CAPABILITIES.SHARE,
+  'share.revoke': CAPABILITIES.SHARE,
+  'sync.manifest': CAPABILITIES.SYNC,
+  'sync.diff': CAPABILITIES.SYNC,
+  'sync.request': CAPABILITIES.SYNC,
+  'sync.conflict': CAPABILITIES.SYNC,
+  'chat.message': CAPABILITIES.CHAT,
+  'chat.ack': CAPABILITIES.CHAT,
+  'chat.typing': CAPABILITIES.CHAT,
+  'relay.request': CAPABILITIES.RELAY,
+  'share.policy.update': CAPABILITIES.SHARE,
+  'gossip.servers': CAPABILITIES.RELAY,
+};
+
+function sortKeys(value) {
+  if (value === null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map(sortKeys);
+  const sorted = {};
+  for (const key of Object.keys(value).sort()) {
+    sorted[key] = sortKeys(value[key]);
+  }
+  return sorted;
+}
+
+function canonicalize(obj) {
+  return JSON.stringify(sortKeys(obj));
+}
+
+function hashPayload(envelope) {
+  const { sig, ...rest } = envelope;
+  return crypto.createHash('sha256').update(canonicalize(rest)).digest();
+}
+
+export function create(type, fromKeyPair, to, payload) {
+  const envelope = {
+    v: PROTOCOL_VERSION,
+    type,
+    from: fromKeyPair.publicKey.toString('hex'),
+    to: to ? (Buffer.isBuffer(to) ? to.toString('hex') : to) : null,
+    id: crypto.randomUUID(),
+    ts: new Date().toISOString(),
+    payload,
+  };
+
+  const message = hashPayload(envelope);
+  const sig = Buffer.alloc(sodium.crypto_sign_BYTES);
+  sodium.crypto_sign_detached(sig, message, fromKeyPair.privateKey);
+  envelope.sig = sig.toString('hex');
+
+  return envelope;
+}
+
+export function createEncrypted(type, fromKeyPair, recipientPK, payload) {
+  const recipientPKBuf = Buffer.isBuffer(recipientPK) ? recipientPK : Buffer.from(recipientPK, 'hex');
+
+  // Convert Ed25519 PK to Curve25519 for encryption
+  const curve25519PK = Buffer.alloc(sodium.crypto_box_PUBLICKEYBYTES);
+  sodium.crypto_sign_ed25519_pk_to_curve25519(curve25519PK, recipientPKBuf);
+
+  const plaintext = Buffer.from(JSON.stringify(payload));
+  const cipher = Buffer.alloc(plaintext.length + sodium.crypto_box_SEALBYTES);
+  sodium.crypto_box_seal(cipher, plaintext, curve25519PK);
+
+  return create(type, fromKeyPair, recipientPKBuf, {
+    _enc: true,
+    _cipher: cipher.toString('hex'),
+  });
+}
+
+export function verify(envelope, { localPublicKey, peerCapabilities } = {}) {
+  const errors = [];
+
+  if (envelope.v !== PROTOCOL_VERSION) {
+    errors.push(`${ErrorCodes.E_VERSION_MISMATCH}: expected ${PROTOCOL_VERSION}, got ${envelope.v}`);
+  }
+
+  if (!envelope.type || typeof envelope.type !== 'string') {
+    errors.push('E_INVALID: missing type');
+  }
+
+  if (!envelope.from || envelope.from.length !== 64) {
+    errors.push('E_INVALID: missing or invalid from');
+  }
+
+  if (!envelope.id) {
+    errors.push('E_INVALID: missing id');
+  }
+
+  if (!envelope.ts) {
+    errors.push('E_INVALID: missing timestamp');
+  }
+
+  // Clock skew check
+  if (envelope.ts) {
+    const msgTime = new Date(envelope.ts).getTime();
+    const now = Date.now();
+    if (Math.abs(now - msgTime) > CLOCK_SKEW_MS) {
+      errors.push(`${ErrorCodes.E_CLOCK_SKEW}: timestamp outside ±5 min window`);
+    }
+  }
+
+  // Replay check
+  if (envelope.id) {
+    if (seenIds.has(envelope.id)) {
+      errors.push(`${ErrorCodes.E_REPLAY}: duplicate message ID`);
+    }
+  }
+
+  // Recipient check — if `to` is set, it must match local public key
+  if (envelope.to && localPublicKey) {
+    const localPK = Buffer.isBuffer(localPublicKey) ? localPublicKey.toString('hex') : localPublicKey;
+    if (envelope.to !== localPK) {
+      errors.push(`${ErrorCodes.E_UNAUTHORIZED}: message not addressed to this node`);
+    }
+  }
+
+  // Capability check — does sender have required capability?
+  if (envelope.type && peerCapabilities) {
+    const required = CAPABILITY_REQUIREMENTS[envelope.type];
+    if (required && !peerCapabilities.includes(required)) {
+      errors.push(`${ErrorCodes.E_CAPABILITY}: peer lacks required capability '${required}'`);
+    }
+  }
+
+  // Signature check
+  if (envelope.sig && envelope.from) {
+    try {
+      const pk = Buffer.from(envelope.from, 'hex');
+      const sig = Buffer.from(envelope.sig, 'hex');
+      const message = hashPayload(envelope);
+      const valid = sodium.crypto_sign_verify_detached(sig, message, pk);
+      if (!valid) errors.push(`${ErrorCodes.E_UNAUTHORIZED}: invalid signature`);
+    } catch (e) {
+      errors.push(`${ErrorCodes.E_UNAUTHORIZED}: signature verification failed: ${e.message}`);
+    }
+  }
+
+  if (errors.length > 0) return { valid: false, errors };
+
+  // Mark as seen
+  seenIds.set(envelope.id, Date.now() + DEDUP_WINDOW_MS);
+  // Cap seenIds to prevent memory exhaustion
+  if (seenIds.size > 10000) {
+    pruneSeenIds();
+    if (seenIds.size > 10000) {
+      const entries = [...seenIds.entries()].sort((a, b) => a[1] - b[1]);
+      while (seenIds.size > 5000) {
+        seenIds.delete(entries.shift()[0]);
+      }
+    }
+  }
+
+  return { valid: true, errors: [] };
+}
+
+export function decrypt(envelope, recipientKeyPair) {
+  if (!envelope.payload?._enc) return envelope.payload;
+
+  const cipher = Buffer.from(envelope.payload._cipher, 'hex');
+
+  // Convert Ed25519 keys to Curve25519
+  const curve25519PK = Buffer.alloc(sodium.crypto_box_PUBLICKEYBYTES);
+  const curve25519SK = Buffer.alloc(sodium.crypto_box_SECRETKEYBYTES);
+  sodium.crypto_sign_ed25519_pk_to_curve25519(curve25519PK, recipientKeyPair.publicKey);
+  sodium.crypto_sign_ed25519_sk_to_curve25519(curve25519SK, recipientKeyPair.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(`${ErrorCodes.E_UNAUTHORIZED}: decryption failed`);
+
+  return JSON.parse(plaintext.toString());
+}
+
+export function isKnownType(type) {
+  return KNOWN_TYPES.has(type) || type.startsWith('x-');
+}
+
+export function pruneSeenIds() {
+  const now = Date.now();
+  for (const [id, expiry] of seenIds) {
+    if (expiry < now) seenIds.delete(id);
+  }
+}
+
+// Run cleanup every 10 minutes
+setInterval(pruneSeenIds, 10 * 60 * 1000).unref();

package/lib/protocol/handler.js

@@ -0,0 +1,191 @@
+import { verify, decrypt, isKnownType } from './envelope.js';
+import { handleTransferRequest } from './negotiation.js';
+
+const listeners = new Map();
+
+export function on(type, callback) {
+  if (!listeners.has(type)) listeners.set(type, []);
+  listeners.get(type).push(callback);
+}
+
+export function off(type, callback) {
+  const cbs = listeners.get(type);
+  if (!cbs) return;
+  const idx = cbs.indexOf(callback);
+  if (idx !== -1) cbs.splice(idx, 1);
+}
+
+function emit(type, data) {
+  const cbs = listeners.get(type) || [];
+  for (const cb of cbs) {
+    try { cb(data); } catch (e) { console.error(`[pal-protocol] handler error for ${type}:`, e.message); }
+  }
+  const wildcards = listeners.get('*') || [];
+  for (const cb of wildcards) {
+    try { cb({ type, ...data }); } catch {}
+  }
+}
+
+export async function handleIncoming(envelope, keyPair, context = {}) {
+  const verifyOpts = {};
+  if (keyPair?.publicKey) {
+    verifyOpts.localPublicKey = keyPair.publicKey;
+  }
+  if (context.peerCapabilities) {
+    verifyOpts.peerCapabilities = context.peerCapabilities;
+  }
+
+  const result = verify(envelope, verifyOpts);
+  if (!result.valid) {
+    emit('error', { envelope, errors: result.errors });
+    return { handled: false, errors: result.errors };
+  }
+
+  // Decrypt if needed
+  let payload;
+  try {
+    payload = envelope.payload?._enc ? decrypt(envelope, keyPair) : envelope.payload;
+  } catch (e) {
+    emit('error', { envelope, errors: [e.message] });
+    return { handled: false, errors: [e.message] };
+  }
+
+  const data = { from: envelope.from, id: envelope.id, ts: envelope.ts, ...payload };
+
+  switch (envelope.type) {
+    // ── Identity & Discovery ──
+    case 'identity.announce':
+      emit('identity.announce', data);
+      return { handled: true, action: 'identity_announced' };
+
+    case 'identity.resolve':
+      emit('identity.resolve', data);
+      return { handled: true, action: 'identity_resolve_requested' };
+
+    case 'identity.response':
+      emit('identity.response', data);
+      return { handled: true, action: 'identity_resolved' };
+
+    case 'heartbeat':
+      emit('heartbeat', data);
+      return { handled: true, action: 'heartbeat_received' };
+
+    // ── Share Negotiation ──
+    case 'share.offer':
+      emit('share.offer', data);
+      return { handled: true, action: 'share_offered' };
+
+    case 'share.accept':
+      emit('share.accept', data);
+      return { handled: true, action: 'share_accepted' };
+
+    case 'share.key':
+      emit('share.key', data);
+      return { handled: true, action: 'share_key_received' };
+
+    case 'share.revoke':
+      emit('share.revoke', data);
+      return { handled: true, action: 'share_revoked' };
+
+    case 'share.policy.update':
+      emit('share.policy.update', data);
+      return { handled: true, action: 'policy_updated' };
+
+    // ── Transfer Control ──
+    case 'transfer.request': {
+      if (context.share && keyPair) {
+        const response = await handleTransferRequest(envelope, keyPair, context.share);
+        emit('transfer.request', { ...data, response });
+        return { handled: true, action: response.ok ? 'transfer_authorized' : 'transfer_denied', envelope: response.envelope };
+      }
+      emit('transfer.request', data);
+      return { handled: true, action: 'transfer_requested' };
+    }
+
+    case 'transfer.authorize':
+      emit('transfer.authorize', data);
+      return { handled: true, action: 'transfer_authorized' };
+
+    case 'transfer.deny':
+      emit('transfer.deny', data);
+      return { handled: true, action: 'transfer_denied' };
+
+    case 'transfer.progress':
+      emit('transfer.progress', data);
+      return { handled: true, action: 'transfer_progress' };
+
+    case 'transfer.complete':
+      emit('transfer.complete', data);
+      return { handled: true, action: 'transfer_completed' };
+
+    case 'transfer.receipt':
+      emit('transfer.receipt', data);
+      return { handled: true, action: 'receipt_received' };
+
+    // ── Sync ──
+    case 'sync.manifest':
+      emit('sync.manifest', data);
+      return { handled: true, action: 'manifest_received' };
+
+    case 'sync.diff':
+      emit('sync.diff', data);
+      return { handled: true, action: 'diff_received' };
+
+    case 'sync.request':
+      emit('sync.request', data);
+      return { handled: true, action: 'sync_requested' };
+
+    case 'sync.conflict':
+      emit('sync.conflict', data);
+      return { handled: true, action: 'conflict_detected' };
+
+    // ── Chat ──
+    case 'chat.message':
+      emit('chat.message', data);
+      return { handled: true, action: 'chat_received' };
+
+    case 'chat.ack':
+      emit('chat.ack', data);
+      return { handled: true, action: 'chat_acked' };
+
+    case 'chat.typing':
+      emit('chat.typing', data);
+      return { handled: true, action: 'typing_indicator' };
+
+    // ── Routing ──
+    case 'route.probe':
+      emit('route.probe', data);
+      return { handled: true, action: 'probe_received' };
+
+    case 'route.probe.response':
+      emit('route.probe.response', data);
+      return { handled: true, action: 'probe_response' };
+
+    case 'relay.request':
+      emit('relay.request', data);
+      return { handled: true, action: 'relay_requested' };
+
+    case 'relay.allocated':
+      emit('relay.allocated', data);
+      return { handled: true, action: 'relay_allocated' };
+
+    // ── Server Gossip ──
+    case 'gossip.servers':
+      emit('gossip.servers', data);
+      return { handled: true, action: 'gossip_received' };
+
+    default:
+      // Custom x- types (extensibility §13.1)
+      if (envelope.type.startsWith('x-')) {
+        emit(envelope.type, data);
+        return { handled: true, action: 'custom' };
+      }
+      // Forward compatibility — unknown types are silently ignored (§13.2)
+      if (!isKnownType(envelope.type)) {
+        emit('unknown', { type: envelope.type, ...data });
+        return { handled: false, errors: [] }; // not an error, just unknown
+      }
+      emit('unknown', { type: envelope.type, ...data });
+      return { handled: false, errors: ['Unknown message type'] };
+  }
+}

package/lib/protocol/index.js

@@ -0,0 +1,27 @@
+// PAL/1.0 Protocol — Palexplorer proprietary control protocol
+// Built on: BitTorrent (transport), Ed25519/XChaCha20 (crypto), HTTP/DHT/mDNS (discovery)
+
+export { create, createEncrypted, verify, decrypt, isKnownType, ErrorCodes, CAPABILITIES, PROTOCOL_VERSION } from './envelope.js';
+export * as messages from './messages.js';
+export { validatePolicy, enforcePolicy, FREE_POLICY_LIMITS, PRO_POLICY_LIMITS } from './policy.js';
+export { probeRoutes, selectRoute, buildRouteInfo, getRelayLimits, ROUTE_PRIORITY } from './router.js';
+export {
+  initiateShare,
+  handleShareAccept,
+  handleTransferRequest,
+  wrapShareKey,
+  unwrapShareKey,
+  createReceipt,
+} from './negotiation.js';
+export {
+  buildProtocolManifest,
+  createManifestEnvelope,
+  computeDelta,
+  computeBlockHashes,
+  findChangedBlocks,
+  createSyncRequest,
+  createConflictNotification,
+} from './sync.js';
+export { handleIncoming, on, off } from './handler.js';
+
+export const PROTOCOL_NAME = 'PAL/1.0';