pal-protocol

PAL/1.2 baseline with PAL/2.0 extensions — Proprietary application-layer protocol for Palexplorer. Built on BitTorrent, Ed25519, and XChaCha20-Poly1305.

What is PAL?

PAL is the control plane for Palexplorer's P2P file sharing. BitTorrent moves the bytes — PAL decides what, when, and to whom.

PAL handles: identity, share negotiation, transfer authorization, sync, chat, routing, presence, streaming signaling, and machine browsing. All messages are signed (Ed25519) and optionally encrypted (crypto_box_seal).

Protocol Stack

┌──────────────────────────────────────────────┐
│            PAL/2.0 Extensions                │  Forward secrecy, ratchet,
│                                              │  onion relay, group keys, ACK
├──────────────────────────────────────────────┤
│            PAL/1.2 (baseline)                │  Control plane
├──────────┬──────────┬───────────────────────┤
│ Signaling│  Sync    │  Policy Engine         │  Sub-protocols
├──────────┴──────────┴───────────────────────┤
│         PAL Envelope                         │  Message framing
├──────────────────────────────────────────────┤
│  Ed25519 / X25519 / XChaCha20-Poly1305       │  Cryptography
├──────────┬──────────┬───────────────────────┤
│WebTorrent│   DHT    │  mDNS                  │  Transport
├──────────┴──────────┴───────────────────────┤
│          TCP / UDP / WebRTC                   │  Network
└──────────────────────────────────────────────┘

Modules

Core (PAL/1.2)

| Module | File | Description | |--------|------|-------------| | Envelope | lib/envelope.js | Create, sign, verify, encrypt/decrypt PAL envelopes | | Messages | lib/messages.js | Message type definitions and builders | | Handler | lib/handler.js | Incoming envelope dispatcher (event-based) | | Negotiation | lib/negotiation.js | Share offer → accept → key delivery flow | | Policy | lib/policy.js | Share access policies (expiry, limits, IP, schedule) | | Router | lib/router.js | Smart route selection (LAN → direct → relay) | | Sync | lib/sync.js | 3-way manifest sync with delta support | | Rate Limit | lib/rateLimit.js | Per-key rate limiting |

Extensions (PAL/2.0)

| Module | File | Capability | Status | |--------|------|------------|--------| | Forward Secrecy | lib/session.js | pfs | Implemented — promote to core | | Double Ratchet | lib/ratchet.js | ratchet | Implemented | | Noise Signaling | lib/noise.js | noise | Implemented — under review | | Onion Relay | lib/onion.js | onion | Implemented | | Group Keys | lib/groupKeys.js | sender-keys | Implemented | | Message ACK | lib/ack.js | ack | Implemented — promote to core | | Attestation | lib/attestation.js | cap-attest | Implemented — deferred | | Certificate Transparency | lib/ct.js | ct-log | Implemented — deferred |

Usage

import { create, verify, decrypt, createEncrypted } from 'pal-protocol';

// Create a signed envelope
const envelope = create('share.offer', myKeyPair, recipientPK, {
  shareId: 'uuid',
  name: 'vacation-photos',
  totalSize: 1073741824,
});

// Verify an incoming envelope
const result = verify(envelope, { localPublicKey: myPK });
if (result.valid) {
  const payload = decrypt(envelope, myKeyPair);
}

Specs

• PAL/1.2 Specification — Active baseline
• PAL/2.0 Extensions — Draft extensions

Consumers

| Project | Role | |---------|------| | palexplorer | Desktop app — full protocol implementation | | palexplorer-server | Discovery server — envelope relay and validation | | palexplorer-mobile | Mobile app — P2P on mobile | | palexplorer-sdk | SDK for third-party developers |

Requirements

• Node.js 20+
• ES modules
• sodium-native (libsodium bindings for Ed25519, XChaCha20, X25519)

License

Proprietary. See LICENSE.md.