Metadata-Version: 2.4
Name: tokenade
Version: 3.5.0
Summary: Production-grade token shifting and session portability tool
Author: Tokenade Team
License: MIT
Project-URL: Homepage, https://github.com/mihir0209/tokenade
Project-URL: Documentation, https://github.com/mihir0209/tokenade#readme
Project-URL: Repository, https://github.com/mihir0209/tokenade
Project-URL: Issues, https://github.com/mihir0209/tokenade/issues
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: playwright>=1.40.0
Requires-Dist: requests>=2.28.0
Requires-Dist: pycryptodome>=3.19.0
Requires-Dist: keyring>=24.0.0
Requires-Dist: aiohttp>=3.9.0
Provides-Extra: windows
Requires-Dist: pywin32>=306; extra == "windows"
Provides-Extra: linux
Requires-Dist: secretstorage>=3.3.3; extra == "linux"
Provides-Extra: runtime
Requires-Dist: curl-cffi>=0.6.0; extra == "runtime"
Provides-Extra: ldap
Requires-Dist: ldap3>=2.9; extra == "ldap"
Provides-Extra: enterprise
Requires-Dist: ldap3>=2.9; extra == "enterprise"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"

# Tokenade v3.0 — Browser Session Portability Tool

Extract browser sessions from one device, package them into portable `.tokenade` files, and browse as the donor on another device using a **CDP reverse proxy** with TLS fingerprint matching.

## Features

### Core

| Feature | Description |
|---------|-------------|
| **Session Export** | Extract cookies from Chrome, Firefox, Brave, Edge, Safari, Tor Browser |
| **Session Injection** | Inject sessions via CDP proxy or direct profile modification |
| **TLS Fingerprint Matching** | Bypass Cloudflare, DataDome with curl-cffi |
| **localStorage Support** | Extract/inject localStorage (Telegram, WhatsApp) |
| **Encryption** | AES-256-GCM encryption for session files |
| **Multi-Browser** | Cross-browser support (extract from Firefox, inject into Chrome) |

### Advanced

| Feature | Description |
|---------|-------------|
| **Session Auto-Refresh** | WebSocket notifications, multi-browser fallback, hot-reload |
| **Session Sharing** | Email, webhook (Slack/Discord), QR codes, HMAC-SHA256 signatures |
| **Multi-Session Management** | List, merge, rotate, stats across multiple sessions |
| **Advanced Validation** | Custom JS rules, screenshot comparison, API validation |
| **Browser Extension** | Chrome/Firefox extension for one-click export |
| **HTTP Forward Proxy** | `HTTP_PROXY` mode with TLS matching |
| **Multi-Site Bundler** | Serve multiple sessions with tabbed GUI |

### Enterprise

| Feature | Description |
|---------|-------------|
| **Audit Logging** | Structured JSONL logs for all session operations |
| **Role-Based Access Control** | Admin/editor/viewer roles with persistent storage |
| **LDAP/SSO Integration** | LDAP bind authentication with group membership checks |

### Performance

| Feature | Description |
|---------|-------------|
| **Connection Pooling** | Shared HTTP connections across multi-site proxy |
| **LRU Session Caching** | In-memory cache with configurable TTL |
| **Parallel Extraction** | Concurrent cookie extraction from multiple profiles |

### Browser Support

| Browser | Status | Notes |
|---------|--------|-------|
| Chrome | Full | SQLite extraction, profile discovery |
| Firefox | Full | SQLite extraction, profile discovery |
| Edge | Full | Chromium-based, same as Chrome |
| Brave | Full | Chromium-based, same as Chrome |
| Safari | Partial | Binary cookie parsing, macOS only |
| Tor Browser | Full | Firefox-based, cross-platform profile discovery |
| Mobile (Android) | Full | Via ADB — Chrome and Firefox on Android |

### Integration

| Feature | Description |
|---------|-------------|
| **GitHub Actions** | CI/CD with lint, test matrix (3.9–3.12), security scan, build |
| **Docker** | Multi-stage build, session management, batch containers |
| **Kubernetes** | Deployment, Service, ConfigMap, sidecar YAML generation |

## How It Works

### 1. Session Export

```
Your Browser (Firefox/Chrome/Safari/Tor)
        │
        ▼
┌─────────────────┐
│ tokenade export │
└─────────────────┘
        │
        ▼
┌─────────────────┐
│ Read SQLite DB  │──── Browser stores cookies in SQLite
└─────────────────┘
        │
        ▼
┌─────────────────┐
│ Decrypt Cookies │──── Platform-specific decryption
└─────────────────┘
        │
        ▼
┌─────────────────┐
│ Package .tokenade│──── JSON with cookies, fingerprint, TLS profile
└─────────────────┘
        │
        ▼
   session.tokenade
```

### 2. Session Injection (CDP Proxy)

```
.tokenade file
        │
        ▼
┌─────────────────┐
│ tokenade proxy  │
└─────────────────┘
        │
        ▼
┌─────────────────┐
│ Launch Chromium │──── Playwright browser
└─────────────────┘
        │
        ▼
┌─────────────────┐
│ Inject Cookies  │──── Add to browser context
└─────────────────┘
        │
        ▼
┌─────────────────┐
│ page.route()    │──── Intercept ALL browser requests
└─────────────────┘
        │
        ▼
┌─────────────────┐
│ curl-cffi       │──── Forward with donor TLS fingerprint
│ (TLS matched)   │
└─────────────────┘
        │
        ▼
   http://127.0.0.1:9222
   You are logged in as donor
```

### 3. TLS Fingerprint Matching (Why It Works)

```
Without Tokenade:
Your Browser → Your TLS fingerprint → Blocked by Cloudflare

With Tokenade:
Your Browser → Tokenade Proxy → Donor's TLS fingerprint → Allowed

curl-cffi impersonates Chrome's TLS handshake (JA3 hash),
so servers see the donor's fingerprint, not yours.
```

## Why Tokenade?

| Feature | Tokenade | Browser Extensions | Simple CLI Tools |
|---------|----------|-------------------|------------------|
| **CLI Interface** | ✅ Scriptable, automatable | ❌ GUI-only | ✅ |
| **TLS Fingerprint Matching** | ✅ Bypasses Cloudflare/DataDome | ❌ | ❌ |
| **Site-Agnostic** | ✅ Works with any website | ❌ Often site-specific | ⚠️ Limited |
| **Multi-Browser** | ✅ Chrome/Firefox/Edge/Safari/Tor | ⚠️ Single browser | ❌ |
| **localStorage Support** | ✅ Critical for Telegram, WhatsApp | ❌ | ❌ |
| **Encrypted Session Files** | ✅ AES-256-GCM | ❌ | ⚠️ Varies |
| **Enterprise Features** | ✅ Audit, RBAC, LDAP | ❌ | ❌ |
| **Docker/K8s Ready** | ✅ Built-in integration | N/A | ❌ |
| **Self-Hosted** | ✅ No third-party | N/A | ✅ |

**Unique advantage**: Tokenade is the only CLI tool that matches TLS fingerprints for cross-browser session portability.

## Quick Start (3 commands)

### Step 1 — Export cookies from your browser

```bash
# See what browsers are installed
tokenade export --list-profiles

# Export ChatGPT session from Firefox
tokenade export --browser-name firefox --domains "chatgpt.com,openai.com" -o chatgpt.tokenade

# Export Gmail session from Chrome
tokenade export --browser-name chrome --domains "google.com,accounts.google.com" -o gmail.tokenade
```

### Step 2 — Start the proxy

```bash
# Start CDP proxy (default — recommended)
tokenade proxy -s chatgpt.tokenade

# Custom port, visible browser
tokenade proxy -s gmail.tokenade --port 8080 --visible
```

### Step 3 — Browse

Open `http://127.0.0.1:9222`, enter the target URL, and click Browse.

## Full CLI Reference

### Export

```bash
tokenade export [options]

Options:
  --browser-name {chrome,firefox,edge,brave}
  --browser-path PATH        Custom browser profile path
  --profile NAME             Profile name (e.g. "Default", "Profile 1")
  --domains DOMAINS          Comma-separated domains to filter
  --site-config FILE         JSON site config for domain filtering
  -o, --output FILE          Output file path
  --list-profiles            List discovered browser profiles
  --extract-local-storage    Also extract localStorage
  --local-storage-origin ORIGIN
```

### Proxy

```bash
tokenade proxy -s SESSION_FILE [options]

Options:
  -s, --session FILE    .tokenade session file (required)
  -p, --port PORT       Port (default: 9222)
  --host HOST           Bind address (default: 127.0.0.1)
  --visible             Show Chromium window
  --no-open-browser     Don't auto-open GUI
  --timeout SECONDS     Request timeout (default: 30)
  --all                 Multi-site mode (use -d for sessions directory)
  --mode {cdp,forward}  Proxy mode
  --legacy              Use legacy service-worker proxy
  --auto-refresh        Enable auto-refresh from source browser
  --source-browser NAME Browser to refresh from
```

### Multi-Session

```bash
tokenade sessions list -d ./sessions         # List sessions
tokenade sessions list --site google          # Filter by site
tokenade sessions merge s1.tokenade s2.tokenade -o merged.tokenade
tokenade sessions rotate s1.tokenade s2.tokenade
tokenade sessions stats *.tokenade
```

### Session Sharing

```bash
tokenade share -s session.tokenade                    # Create URL
tokenade share -s session.tokenade --format qr -o qr.png
tokenade share -s session.tokenade --password x --expiry 48
tokenade share -s session.tokenade --webhook https://hooks.slack.com/...
tokenade unshare --list
tokenade unshare <session-id>
```

### Encrypt / Decrypt

```bash
tokenade encrypt -s session.tokenade -o encrypted.tokenade
tokenade decrypt -s encrypted.tokenade -o session.tokenade
tokenade rekey -s encrypted.tokenade
```

### Health & Validation

```bash
tokenade health -s session.tokenade
tokenade validate-rules -s session.tokenade -r rules.json
tokenade diff file1.tokenade file2.tokenade
```

### Inject Profile

```bash
tokenade inject-profile -s session.tokenade --browser firefox --profile "default"
tokenade inject-profile -s session.tokenade --browser firefox --profile "default" --dry-run
```

## Docker

```bash
# Build
docker build -t tokenade .

# Run proxy in container
docker run --rm -p 9222:9222 \
  -v ./sessions:/app/sessions:ro \
  --cap-add=SYS_ADMIN \
  tokenade proxy --host 0.0.0.0 -s /app/sessions/session.tokenade

# Docker Compose
docker compose up tokenade
```

### Docker Session Management

```python
from tokenade.core.integration import DockerSessionManager

manager = DockerSessionManager()
manager.create_session_container("session.tokenade", "my-proxy", port=9222)
print(manager.get_status())
```

## Kubernetes

### Sidecar Mode

```python
from tokenade.core.integration import KubernetesManager, KubernetesConfig

k8s = KubernetesManager(KubernetesConfig(namespace="production"))
print(k8s.generate_sidecar_yaml("my-app:latest", "tokenade-sessions"))
```

### Generate Manifests

```python
# Full deployment
print(k8s.generate_deployment_yaml(session_configmap="tokenade-sessions"))

# Service
print(k8s.generate_service_yaml())

# ConfigMap from session files
print(k8s.generate_configmap_yaml({
    "session.tokenade": open("session.tokenade").read()
}))
```

## Enterprise

### Audit Logging

```python
from tokenade.core.security.audit import AuditLogger

logger = AuditLogger()
logger.log_event("session_export", session_id="abc", site_name="google")
logger.log_event("session_share", session_id="abc", method="email")
print(logger.get_summary())
```

### Role-Based Access Control

```python
from tokenade.core.security.audit import RoleManager

rbac = RoleManager()
rbac.assign_role("user@example.com", "editor")
rbac.check_permission("user@example.com", "view_share")  # True
rbac.check_permission("user@example.com", "revoke_share")  # False
```

### LDAP Authentication

```python
from tokenade.core.security.audit import LDAPAuthenticator, LDAPConfig

config = LDAPConfig(
    server="ldap.example.com",
    port=636,
    use_ssl=True,
    bind_dn="cn=admin,dc=example,dc=com",
    bind_password="...",
    user_search_base="ou=users,dc=example,dc=com",
    user_search_filter="(uid={username})",
)
auth = LDAPAuthenticator(config)
auth.authenticate("alice", "password123")
```

## Architecture

```
tokenade/
├── core/
│   ├── proxy/
│   │   ├── cdp_proxy.py          # CDP proxy (recommended)
│   │   ├── server.py             # Legacy SW proxy
│   │   ├── forward_proxy.py      # HTTP forward proxy
│   │   └── multi_site_proxy.py   # Multi-site bundler + connection pooling
│   ├── runtime/
│   │   ├── tls_matcher.py        # curl-cffi TLS fingerprint matching
│   │   └── engine.py             # CookieJar, FingerprintMatcher
│   ├── importer/
│   │   ├── browser_discovery.py  # Find browser profiles
│   │   ├── cookie_extractor.py   # Extract cookies from SQLite
│   │   ├── local_storage_extractor.py
│   │   ├── session_packager.py   # Package into .tokenade (with LRU cache)
│   │   ├── session_loader.py     # Load .tokenade into browser
│   │   ├── session_refresher.py  # Auto-refresh with WebSocket notifications
│   │   ├── session_sharer.py     # Email, webhook, HMAC signatures
│   │   ├── session_manager.py    # Multi-session management
│   │   ├── session_comparator.py # Session diff tool
│   │   ├── advanced_validator.py # Custom validation rules
│   │   ├── safari_extractor.py   # Safari binary cookie parser
│   │   ├── tor_extractor.py      # Tor Browser extraction
│   │   ├── adb_extractor.py      # Android ADB extraction
│   │   └── db_utils.py           # Shared SQLite utilities
│   ├── security/
│   │   ├── credentials.py        # Credential management
│   │   └── audit.py              # Audit logging, RBAC, LDAP
│   ├── integration/
│   │   ├── docker_manager.py     # Docker session management
│   │   └── kubernetes.py         # K8s deployment + sidecar
│   ├── crypto/
│   │   ├── encryptor.py          # AES-256-GCM encryption
│   │   └── cookie_crypto.py      # Browser cookie decryption
│   ├── injector/
│   │   └── profile_manager.py    # Direct profile injection
│   ├── batch/
│   │   └── operations.py         # Batch export/load
│   └── utils/
│       └── performance.py        # LRU cache, connection pooling, parallel extraction
├── cli.py                        # CLI entry point (21 commands)
├── handlers/                     # Site-specific handlers
├── extension/                    # Browser extension
└── tests/                        # 1009 tests
```

## .tokenade File Format

```json
{
  "version": "2.0",
  "created_at": "2026-06-14T12:00:00Z",
  "source_device": {
    "browser": "firefox",
    "profile": "default",
    "platform": "Linux",
    "hostname": "my-pc"
  },
  "site_name": "google",
  "auth_status": "logged_in",
  "cookies": [
    {
      "name": "SID",
      "value": "abc123",
      "domain": ".google.com",
      "path": "/",
      "secure": true,
      "httpOnly": true,
      "sameSite": "Lax",
      "expires": 1781000000
    }
  ],
  "fingerprint": {
    "user_agent": "Mozilla/5.0 ...",
    "platform": "Linux",
    "language": "en-US"
  },
  "tls_profile": {
    "browser": "chrome",
    "version": "120",
    "impersonate": "chrome120",
    "http_version": "2"
  },
  "metadata": {
    "cookie_count": 50,
    "critical_cookie_count": 30
  }
}
```

## Installation

```bash
git clone https://github.com/mihir0209/tokenade.git
cd tokenade
pip install -e ".[dev]"
playwright install chromium --with-deps
```

### Optional Dependencies

```bash
pip install -e ".[runtime]"    # curl-cffi for TLS matching
pip install -e ".[enterprise]" # ldap3 for LDAP/SSO
pip install -e ".[linux]"      # secretstorage for Linux keyring
```

## Development

```bash
make install-dev     # Install with dev deps + Playwright
make test            # Run all 1009 tests
make test-quick      # Skip slow/network tests
make lint            # Flake8 linting
make format          # Black formatting
make typecheck       # Mypy type checking
make clean           # Remove build artifacts
make build           # Build distribution packages
```

### Docker Development

```bash
make docker-build    # Build Docker image
make docker-run      # Run interactively
make docker-proxy SESSION=session.tokenade  # Run proxy
make docker-cleanup  # Remove all containers
```

## Documentation

- [Use Cases & Competitor Comparison](USE-CASES.md) - All use cases, competitor analysis, feature matrix
- [API Reference](docs/API.md) - Complete API documentation
- [Architecture](docs/ARCHITECTURE.md) - System design and data flow
- [Security](docs/SECURITY.md) - Security considerations
- [Competitor Comparison](docs/competitor-comparison.md) - Market analysis
- [Contributing](docs/CONTRIBUTING.md) - How to contribute

## Security

- Session files contain raw cookies — treat like passwords
- Use `tokenade encrypt` to encrypt at rest
- The proxy runs on `127.0.0.1` only (not accessible from network)
- Cookies are injected into an isolated Playwright browser context
- SSRF protection blocks private/loopback/link-local IPs
- HMAC-SHA256 signatures on shared sessions
- Audit logging tracks all session operations

## License

MIT License
