Pollen 🌿

Fully offline, zero-internet, peer-to-peer epidemic routing messenger.
Messages spread like a virus through human movement. No servers. No internet. Just people.

What is Pollen?

Pollen implements Epidemic Routing — a real concept from DTN (Delay-Tolerant Networking) research used by NASA for deep-space communication and deployed in disaster zones.

How it works:

1. You send a message → it stores on your device
2. Every Pollen user on your network silently receives a copy
3. When those users physically move to a new network, they unknowingly carry it
4. The message jumps network → network through human movement
5. The moment it reaches the destination device, it delivers — automatically and silently
6. An ACK travels back the same way

Zero internet used at any point. Only local WiFi or hotspot at each hop.

Prerequisites

node --version   # >= 18 required

Note: better-sqlite3 is a native addon that requires a C++ build toolchain.

• Windows: Install Visual Studio Build Tools and Python 3
• macOS: xcode-select --install
• Linux: sudo apt install build-essential python3

Install

cd pollen
npm install
npm link        # makes 'pollen' available globally

Usage

Start the daemon

pollen start

First run: prompts for a username, generates your identity (username@shortid) and RSA keypair.
Subsequent runs: starts instantly, detached in the background.

Stop the daemon

pollen stop

Scan for peers on your network

pollen scan

Send an encrypted message

pollen send raj@a3f2 "bhai notes bhej"

Returns a Message ID you can use to track delivery.

Check message delivery status

pollen status <messageId>

Returns: Undelivered / In Transit / Delivered

Manual sync

pollen sync

Forces an immediate epidemic bundle exchange with all known peers.

Send a file (Phase 5)

pollen file raj@a3f2 ./notes.pdf

Architecture

pollen/
├── bin/pollen.js              CLI entry point (Commander)
├── src/
│   ├── identity/index.js      Identity: username@shortID generation
│   ├── crypto/
│   │   ├── keys.js            RSA-2048 keypair generation
│   │   └── encrypt.js         Hybrid AES-256-GCM + RSA-OAEP encryption
│   ├── db/
│   │   ├── index.js           SQLite connection + schema
│   │   ├── messages.js        Message CRUD + peer table
│   │   └── cleanup.js         TTL expiry cleanup
│   ├── daemon/
│   │   ├── index.js           Daemon process (IPC server, PID, logging)
│   │   ├── network.js         IP polling / network change detection
│   │   ├── udp.js             UDP broadcast + peer discovery (Phase 2)
│   │   ├── tcp.js             TCP message transfer (Phase 2)
│   │   └── epidemic.js        Epidemic routing + ACK (Phase 4)
│   └── cli/
│       ├── ipc.js             CLI → Daemon IPC client
│       └── commands/          One file per pollen command

Key Design Decisions

| Decision | Reason | |---|---| | IPC via Unix socket / Windows named pipe | No port conflicts, no firewall issues | | Hybrid AES-256-GCM + RSA-OAEP | RSA alone has ~190 byte limit; hybrid has no limit | | Daemon spawned detached | CLI exits immediately; daemon lives independently | | windowsHide: true | No console window popup on Windows | | hop_count max 20 | Prevents infinite loops; message dies if unreachable | | TTL 7 days default | Prevents storage bloat on carrier devices |

Files & Data

Everything lives in ~/.pollen/:

| File | Purpose | |---|---| | identity.json | Your username and shortID | | keys/public.pem | Your RSA public key | | keys/private.pem | Your RSA private key (mode 0600) | | pollen.db | SQLite: messages + peer public keys | | daemon.pid | Running daemon PID | | daemon.log | Daemon logs |

Encryption Model

Relay nodes carry your messages but can never read them:

Sender                    Relay Node              Receiver
  │                           │                       │
  ├─ encrypt(msg, dest_pubkey)│                       │
  │  → AES key (random/msg)   │                       │
  │  → AES-GCM(plaintext)     │                       │
  │  → RSA-OAEP(AES key)      │                       │
  │                           │                       │
  ├────── encrypted blob ─────►│                       │
  │       (sees destination,  │                       │
  │        but NOT content)   ├──── encrypted blob ───►│
  │                           │                       │
  │                           │           decrypt(blob, private_key)
  │                           │                       │
  │◄─────────── ACK (epidemic path) ─────────────────-│

Development Phases

| Phase | Status | Feature | |---|---|---| | Phase 1 | ✅ Complete | Daemon, identity, crypto, IPC, SQLite | | Phase 2 | 🔜 Next | UDP discovery, LAN send/receive | | Phase 3 | 🔜 | Store-and-forward DTN | | Phase 4 | 🔜 | Full epidemic routing + ACK | | Phase 5 | 🔜 | File transfer |

License

MIT