coucou

A peer-to-peer encrypted messaging application that works on local networks. Every node acts as both server and client, with all messages encrypted using a shared password.

Features

• Fully Decentralized: No central server required - every node is equal
• Automatic Discovery: Nodes automatically discover each other on the local network
• End-to-End Encryption: All messages are encrypted using Fernet (symmetric encryption)
• Cross-Platform GUI: Choose between CLI or GUI (auto-selects GTK4, Toga, or GTK3)
• Native Mobile Apps: Package as macOS or iOS apps with BeeWare/Toga
• Broadcast Messaging: Send messages to all peers at once
• Real-time Updates: See when peers join and leave the network
• Disconnection Detection: Automatic detection when peers go offline (15-second timeout)

Installation

Quick Install (pip)

Install the coucou CLI directly from the git repository — no need to clone:

pip install git+https://codeberg.org/dabrain34/coucou

Note: The git+ prefix is required so pip knows to build from the git repository. pip install https://codeberg.org/dabrain34/coucou (without it) will not work.

This installs the coucou command (CLI) along with its dependencies. Once installed, run it from anywhere:

coucou --password "test123"
coucou --version

To install a specific tag or branch, append @<ref>:

pip install "git+https://codeberg.org/dabrain34/coucou@v0.2.0"

With the graphical interface (Toga): add the [gui] extra to also pull in Toga and install the coucou-gui command (works on Windows, macOS, Linux):

pip install "papagayo[gui] @ git+https://codeberg.org/dabrain34/coucou"
coucou-gui --password "test123"

Linux prerequisites: on Linux, Toga uses the GTK backend, which builds PyGObject from source. Install the required system development packages first, otherwise the pip install will fail while building pygobject:

# Ubuntu/Debian
sudo apt install libgirepository-2.0-dev libcairo2-dev gcc \
 pkg-config python3-dev gir1.2-gtk-4.0
# Fedora
sudo dnf install gobject-introspection-devel cairo-gobject-devel gcc \
 pkg-config python3-devel gtk4

macOS and Windows need no extra system packages — Toga uses the native Cocoa / WinForms backends.

The distribution name is papagayo (hence papagayo[gui]), while the installed commands are coucou and coucou-gui.

Note: The bare install ships the CLI only, keeping it lightweight. The [gui] extra adds the cross-platform Toga GUI. The GTK4 GUI is not available via pip (it needs system PyGObject/GTK4 packages) — install from source as described below for GTK4.

From Source

1. Create and activate a virtual environment:

python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate

2. Install Python dependencies:

pip install -r requirements.txt

GUI Requirements:

The --gui option automatically selects the best GUI framework for your platform:

• Windows: Uses Toga (included in requirements.txt)
• macOS/Linux: Tries GTK4 first (recommended), then falls back to Toga

Optional: Install GTK4 for better GUI experience (macOS/Linux)

# Ubuntu/Debian
sudo apt install python3-gi gir1.2-gtk-4.0
# Fedora
sudo dnf install python3-gobject gtk4-devel
# macOS
brew install gtk4 pygobject3

Optional: Build native macOS/iOS apps

pip install -r requirements-mobile.txt
# See INSTALL.md for complete mobile app build instructions

Usage

Command Line Interface (CLI)

source venv/bin/activate # Activate virtual environment first
python p2p_messenger.py --cli --port 8888 --password "your_secret_password"

CLI Commands:

• /list - Show all connected peers
• /select <peer_id> - Select a peer to message
• /broadcast <message> - Send message to all peers
• /info - Show node information
• /help - Show help
• /quit - Exit application

Graphical Interface (GUI)

source venv/bin/activate # Activate virtual environment first
# Auto-select best GUI for your platform (recommended)
python p2p_messenger.py --gui --port 8888 --nickname "YourName" --password "your_secret_password"
# Force GTK4 specifically (macOS/Linux only)
python p2p_messenger.py --gui-gtk4 --port 8888 --nickname "YourName" --password "your_secret_password"
# Force Toga GUI (cross-platform)
python p2p_messenger.py --gui-toga --port 8888 --nickname "YourName" --password "your_secret_password"
# Or run GUI directly:
python gui/gui_app_gtk4_simple.py --port 8888 --password "your_secret_password" # GTK4
python gui/gui_app_toga.py --port 8888 --password "your_secret_password" # Toga (cross-platform)

Note: The --gui option automatically selects:

• Windows: Toga (native WinForms backend)
• macOS/Linux: GTK4 if available, otherwise Toga
• Use --gui-gtk4 to force GTK4 on macOS/Linux
• Use --gui-toga to force Toga on any platform

How It Works

1. Node Initialization: Each instance creates a unique node ID and starts listening on the specified port

2. Discovery: Nodes broadcast their presence via UDP every 3 seconds. Other nodes receive these broadcasts and add them to their peer list

3. Messaging: When sending a message, the node:

   • Encrypts the message using the shared password
   • Establishes a TCP connection to the target peer
   • Sends the encrypted message
   • The receiving peer decrypts and displays it

4. Encryption: Uses PBKDF2 for key derivation from the password and Fernet for symmetric encryption

Security Notes

• All nodes on the network must use the same password to communicate
• The password is used to derive an encryption key - choose a strong password
• Messages are only as secure as the shared password
• This is designed for local network use - not recommended for internet use

Architecture

Core Components:

• core/p2p_core.py - Core P2P networking and encryption logic
• p2p_messenger.py - Main launcher with auto-selection logic

Interfaces:

• cli/cli_app.py - Command-line interface
• gui/gui_app_gtk4_simple.py - GTK4 GUI (recommended for macOS/Linux)
• gui/gui_app_toga.py - Toga GUI (cross-platform, required for Windows)
• mobile/ - Mobile app package for native iOS/macOS apps (via BeeWare)

Native Mobile Apps

Build native macOS and iOS applications using BeeWare/Toga:

# Install mobile dependencies
pip install -r requirements-mobile.txt
# Quick test in development mode
python -m mobile
# Build native macOS app and .dmg installer
briefcase create macOS
briefcase build macOS
briefcase package macOS --adhoc-sign
# Build iOS app for simulator/device
briefcase create iOS
briefcase build iOS
briefcase run iOS

See INSTALL.md for complete mobile app build instructions, including:

• Creating distributable .dmg files for macOS
• Building for iOS simulator and physical devices
• App Store packaging and distribution
• Code signing options

Running Multiple Instances

Different Ports (Recommended)

To test on the same machine, run multiple instances with different ports:

# Terminal 1
source venv/bin/activate
python p2p_messenger.py --cli --port 8888
# Terminal 2
source venv/bin/activate
python p2p_messenger.py --cli --port 8889
# Terminal 3 (GUI)
source venv/bin/activate
python p2p_messenger.py --gui --port 8890

Same Port (Fully Supported)

On systems that support SO_REUSEPORT, multiple instances can share the same port:

# Terminal 1
source venv/bin/activate
python p2p_messenger.py --cli --port 8888
# Terminal 2 (same port)
source venv/bin/activate
python p2p_messenger.py --cli --port 8888

Features:

• ✅ Port sharing: Multiple instances bind to the same port successfully
• ✅ Peer discovery: 100% reliable via UDP broadcasts
• ✅ Message delivery: Direct same-port processing ensures reliable communication
• ✅ Cross-compatibility: Works seamlessly with different-port instances

All instances with the same password will automatically discover each other and can exchange messages.

Testing

Unit Tests (Automated, Fast)

Run the automated unit test suite - these tests are fast (<1 second), require no user interaction, and run automatically in CI/CD:

source venv/bin/activate
# Run all unit tests
python run_tests.py
# Or run individual test module
python -m unittest tests.test_encryption # Encryption and core functionality

Unit Test Suite:

• test_encryption.py - 17 tests covering encryption, node initialization, handlers, and peer management
• Fast execution (< 1 second)
• No network operations required
• Runs automatically in GitHub Actions CI/CD

Integration Tests (Manual, Slow)

Integration tests require actual network operations and take several minutes to complete. They are not run automatically in CI/CD:

source venv/bin/activate
# Run all integration tests (takes several minutes)
python -m unittest discover tests/integration
# Or run specific integration tests
python tests/integration/test_p2p_messaging.py # Comprehensive P2P tests
python tests/integration/test_basic_functionality.py # Basic functionality tests

See tests/integration/README.md for more details on integration tests.

CI/CD: Only unit tests run automatically on GitHub Actions for every push and pull request before building binaries.

Troubleshooting

"Address already in use" errors

• This can happen when running multiple instances quickly or if previous instances didn't shut down cleanly
• Wait a few seconds between starting instances
• Use different broadcast ports if needed: --broadcast-port <port>
• Kill any hanging processes: pkill -f p2p_messenger

Nodes not discovering each other

• Ensure all nodes use the same password
• Check firewall settings allow UDP broadcasts
• Verify nodes are on the same network subnet
• Try different ports if current ones are blocked

GUI issues

• GTK4 recommended: On macOS/Linux, install GTK4 for the best GUI experience
• Toga limitations: The Toga GUI may have minor threading issues on some platforms
  • Peer discovery works but updates may be delayed
  • Nickname must be provided via --nickname command-line argument (no dialog prompt)
• Windows: Toga is the only GUI option (works well with WinForms backend)
• Fallback: Use CLI mode if GUI has issues: --cli instead of --gui

Registration Server (Optional)

Coucou includes an optional registration server for persistent user identities. By default, Coucou generates anonymous unique IDs each session. With the registration server, users can register with email or phone to get a persistent identity that's saved locally.

Features

• Optional: App works fully on local network without the server
• Email/Phone Verification: Verify via SendGrid (email) or Twilio (SMS)
• Unique Nicknames: Nicknames are enforced to be unique among registered users
• Admin Dashboard: Web-based dashboard for user management
• Pluggable Database: SQLite (default), MongoDB, or in-memory for tests
• Pluggable Providers: Switchable email (SendGrid/SMTP) and SMS (Twilio/Vonage) backends

Quick Start

cd server
npm install
cp .env.example .env
# Edit .env with your settings (JWT_SECRET, SendGrid/Twilio keys, etc.)
npm start

The server runs on port 3000 by default. Access the admin dashboard at http://localhost:3000/admin.

Database Providers

The server supports three database backends, selectable via the DB_PROVIDER environment variable:

SQLite (Default)

# No extra setup needed - just run
npm start

MongoDB

# Install MongoDB driver (optional dependency)
npm install mongodb
# Configure in .env
DB_PROVIDER=mongodb
MONGODB_URI=mongodb://localhost:27017/coucou
npm start

In-Memory (Testing)

# Run tests with in-memory database (fast, no disk I/O)
npm test
# Or manually
DB_PROVIDER=memory npm start

Running Tests

# Run with in-memory database (default, fastest)
npm test
# Run with SQLite
npm run test:sqlite
# Run with MongoDB (requires running MongoDB instance)
npm run test:mongodb
# Watch mode
npm run test:watch

Email/SMS Providers

Configure via EMAIL_PROVIDER and SMS_PROVIDER environment variables:

SendGrid Setup (Email)

EMAIL_PROVIDER=sendgrid
SENDGRID_API_KEY=SG.your-api-key
SENDGRID_FROM_EMAIL=noreply@yourdomain.com

Twilio Setup (SMS)

SMS_PROVIDER=twilio
TWILIO_ACCOUNT_SID=your-account-sid
TWILIO_AUTH_TOKEN=your-auth-token
TWILIO_PHONE_NUMBER=+1234567890

API Endpoints

Admin Dashboard

Access at http://localhost:3000/admin (default credentials: admin/admin123)

Features:

• User management (list, search, enable/disable, delete)
• View pending registrations
• Server statistics and info
• Cleanup expired data

Production Deployment

1. Generate secure secrets:

   node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"
   

2. Set production environment variables:

   NODE_ENV=production
   JWT_SECRET=<generated-secret>
   ADMIN_PASSWORD_HASH=<bcrypt-hash>
   

3. Use a reverse proxy (Caddy example):

   coucou.yourdomain.com {
    reverse_proxy localhost:3000
   }
   

4. For MongoDB in production:

   DB_PROVIDER=mongodb
   MONGODB_URI=mongodb://user:pass@host:27017/coucou?authSource=admin