Metadata-Version: 2.4
Name: message-metadata-mirror
Version: 0.1.0
Summary: Self-hosted privacy dashboard that reveals what messaging apps leak about you
Project-URL: Homepage, https://github.com/yourusername/message-metadata-mirror
Project-URL: Repository, https://github.com/yourusername/message-metadata-mirror
Project-URL: Documentation, https://github.com/yourusername/message-metadata-mirror#readme
Author-email: Your Name <you@example.com>
License: MIT
License-File: LICENSE
Keywords: messaging,metadata,privacy,security,self-hosted
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Requires-Python: >=3.11
Requires-Dist: aiosqlite>=0.19.0
Requires-Dist: fastapi>=0.110.0
Requires-Dist: httpx>=0.26.0
Requires-Dist: jinja2>=3.1.3
Requires-Dist: mitmproxy>=10.2.0
Requires-Dist: pydantic-settings>=2.1.0
Requires-Dist: pydantic>=2.6.0
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: sqlalchemy>=2.0.25
Requires-Dist: stripe>=8.0.0
Requires-Dist: uvicorn[standard]>=0.27.0
Provides-Extra: dev
Requires-Dist: black>=24.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.2.0; extra == 'dev'
Description-Content-Type: text/markdown

# message-metadata-mirror

**See what your messaging apps are really telling Meta, Google, and Telegram—in real-time.**

## What is this?

message-metadata-mirror is a self-hosted privacy auditing tool that captures and visualizes metadata leakage from WhatsApp, Telegram, and Signal. Install a CA certificate on your local network, and immediately see timestamps, contact graphs, IP addresses, and device fingerprints that messaging apps reveal—even when end-to-end encryption is enabled. Generate weekly privacy reports showing the gap between what companies *claim* is encrypted and what you're actually exposing.

Think Little Snitch meets Wireshark, built for privacy-conscious users who want proof, not promises.

## Features

- **Real-time metadata capture** – HTTPS proxy intercepts and logs messaging app traffic without decrypting message content
- **Privacy-focused analytics** – See contact graphs, request timing, IP patterns, device fingerprints, and server endpoints
- **Weekly privacy reports** – Automated PDF exports showing what Meta/Google collected vs. their encryption claims
- **One-click setup** – CA certificate installer + network proxy configuration for macOS, Linux, and Raspberry Pi
- **Docker-native** – Deploy on any hardware (laptop, Pi, home server) with a single `docker-compose up`
- **Privacy by design** – All data stays local; no cloud syncing or telemetry
- **Multi-app support** – Built for WhatsApp, Telegram, and Signal (extensible analyzer framework)

## Quick Start

### Requirements
- Docker and Docker Compose (or Python 3.10+)
- 50MB disk space
- Network access to route devices through proxy

### Installation

1. **Clone and configure**
   ```bash
   git clone https://github.com/yourusername/message-metadata-mirror.git
   cd message-metadata-mirror
   cp .env.example .env
   ```

2. **Launch with Docker**
   ```bash
   docker-compose up -d
   ```
   
   The web dashboard is now running at `http://localhost:8080`

3. **Install CA certificate**
   - Visit the setup page: `http://localhost:8080/setup`
   - Download the CA certificate and follow platform-specific installation steps
   - Configure your device to route traffic through the proxy

4. **Start capturing**
   - Open WhatsApp, Telegram, or Signal on your device
   - Metadata is captured automatically
   - View live captures at `http://localhost:8080/captures`
   - Download weekly reports from the dashboard

### Headless Setup (Raspberry Pi)
```bash
docker-compose -f docker-compose.yml up -d
# Configure devices to use <pi-ip>:8080 as proxy
# Access dashboard remotely at http://<pi-ip>:8080
```

## Usage Examples

### View real-time metadata captures
```
Dashboard → Captures tab shows every metadata leak with timestamps, endpoints, and contact info
```

### Generate privacy report
```
Dashboard → Reports tab → "Generate Weekly Report"
Creates PDF showing:
  - Message sending patterns (timestamps)
  - Contact graph (who you're talking to)
  - IP geolocation of Meta/Telegram servers
  - Device fingerprint data leaked
  - Comparison vs. published privacy policies
```

### Export raw capture data
```
API: GET /api/captures?format=json
Returns structured metadata for analysis in Excel, Python, etc.
```

### Monitor specific contact
```
Captures → Search by phone number or contact name
See all metadata patterns for that conversation thread
```

## Tech Stack

| Layer | Technology | Rationale |
|-------|-----------|-----------|
| **Proxy** | mitmproxy | Mature TLS interception; non-invasive metadata logging |
| **Backend** | Python 3.10 + FastAPI | Fast async framework; easy analyzer plugins |
| **Database** | SQLite | Local-only, zero-config, queryable |
| **Reporting** | ReportLab + Jinja2 | Self-contained PDF generation |
| **Frontend** | Jinja2 templates + HTMX | Lightweight, no build step, responsive |
| **Deployment** | Docker + Docker Compose | Single-command setup across all platforms |
| **Payments** | Stripe (optional) | Premium hosted version monetization |

## Configuration

Copy `.env.example` to `.env` and adjust:
```env
PROXY_PORT=8080              # Local proxy listen port
DATABASE_URL=sqlite:///data/captures.db
REPORT_FREQUENCY=weekly      # daily, weekly, monthly
RETENTION_DAYS=90            # Auto-purge old captures
STRIPE_API_KEY=sk_live_...   # Optional: premium features
```

## Privacy & Security

- **All data stays local** – No cloud sync, no remote servers, no telemetry
- **Message content is never logged** – Only metadata (headers, timestamps, endpoints)
- **Requires admin access** – CA certificate installation prevents accidental interception
- **Open source** – Audit the code at any time

## Limitations

- Requires network-level proxy configuration (devices must route through your network)
- Metadata analysis only—encrypted message content remains inaccessible
- Signal limits metadata exposure (smallest footprint of tested apps)
- Requires periodic CA certificate updates on devices

## License

MIT – Use freely for personal privacy auditing and research. Commercial deployment requires Stripe integration for hosted services (see MONETIZATION.md).

## Contributing

Issues and pull requests welcome. Priority areas:
- Additional app analyzers (iMessage, Viber, WeChat)
- Mobile app setup wizard (iOS profile installer)
- Tor routing option for metadata obfuscation

---

**Questions?** Open an issue. **Want to audit your own apps?** Start with the [Quick Start](#quick-start) above.