corvustunnel 1.0.0__tar.gz

corvustunnel-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KALAI (kalai-tech.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

corvustunnel-1.0.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: corvustunnel
+Version: 1.0.0
+Summary: Control AI coding agents from your phone — Claude Code, Codex, and Antigravity. Self-hosted, E2E encrypted, open source.
+Author-email: KALAI <hello@kalai-tech.com>
+License: MIT
+Project-URL: Homepage, https://corvustunnel.com
+Project-URL: Documentation, https://corvustunnel.com
+Project-URL: Repository, https://github.com/maliozturk/CorvusTunnel
+Project-URL: Issues, https://github.com/maliozturk/CorvusTunnel/issues
+Project-URL: Changelog, https://github.com/maliozturk/CorvusTunnel/blob/main/CHANGELOG.md
+Keywords: ai,agent,terminal,remote,claude,codex,antigravity,coding,mobile,self-hosted,pwa
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+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
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: uvicorn[standard]>=0.30.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pexpect>=4.9.0; sys_platform != "win32"
+Requires-Dist: pywinpty>=2.0.0; sys_platform == "win32"
+Requires-Dist: qrcode>=7.4.0
+Requires-Dist: slowapi>=0.1.9
+Requires-Dist: PyNaCl>=1.5.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: httpx; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Dynamic: license-file
+
+# CorvusTunnel
+
+**Control AI Agents from Your Phone**
+
+Self-hosted remote control for Claude Code, Codex, and Antigravity. Free, open source, E2E encrypted.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![PyPI](https://img.shields.io/pypi/v/corvustunnel.svg)](https://pypi.org/project/corvustunnel/)
+
+---
+
+## Quick Start
+
+```bash
+# Install
+pip install corvustunnel
+
+# Start
+corvustunnel start
+
+# With a specific workspace
+corvustunnel start --workspace /path/to/your/project
+```
+
+Scan the QR code with your phone → you're connected.
+
+## Features
+
+- **Multi-agent support** — Claude Code, Codex CLI, Antigravity
+- **End-to-end encryption** — NaCl/libsodium, key exchange via QR code
+- **QR code connect** — scan to connect, no manual URL typing
+- **Real-time streaming** — WebSocket-based terminal I/O via xterm.js
+- **Push notifications** — Web Push API alerts for agent events
+- **PWA support** — install on your phone like a native app
+- **Smart suggestions** — context-aware action chips (approve, reject, continue)
+- **Command favorites** — pin frequently used prompts for one-tap access
+- **Audit logging** — JSONL forensic logs of all sessions
+- **Security hardened** — IP ban, rate limiting, body size limits, CORS, security headers
+- **Self-hosted** — runs on your machine, your data stays with you
+- **Unlimited** — no session limits, no cooldowns, no restrictions
+
+## How It Works
+
+```
+Your Phone                    Your Computer
+┌─────────┐                  ┌──────────────────┐
+│         │   WebSocket      │  CorvusTunnel    │
+│  Scan   │ ◄──────────────► │  ├── FastAPI     │
+│  QR     │   (E2E encrypted)│  ├── PTY/pexpect │
+│  Code   │                  │  └── Agent       │
+│         │                  │      (claude/    │
+│  Send   │                  │       codex/     │
+│  prompts│                  │       agy)       │
+└─────────┘                  └──────────────────┘
+     ▲                              ▲
+     │    Cloudflare Relay          │
+     └──────────────────────────────┘
+         (TLS + E2E encryption)
+```
+
+## Installation
+
+```bash
+pip install corvustunnel
+corvustunnel start
+```
+
+## Security
+
+- **E2E Encryption**: All terminal I/O encrypted with NaCl SecretBox (XSalsa20-Poly1305)
+- **Key Exchange**: X25519 Diffie-Hellman during QR code scanning
+- **Auth**: One-time boot token → session token with IP binding
+- **WebSocket**: Ticket-based auth (one-time, 30s TTL, IP-bound)
+- **Rate Limiting**: Per-endpoint via slowapi
+- **IP Auto-Ban**: After repeated auth failures
+
+See [SECURITY.md](SECURITY.md) for full details and vulnerability reporting.
+
+## API
+
+| Endpoint | Auth | Description |
+|----------|------|-------------|
+| `GET /api/health` | No | Health check |
+| `POST /api/e2e/exchange` | No | E2E key exchange |
+| `POST /api/claim` | Boot token | Exchange boot token for session token |
+| `GET /api/browse` | Session | Directory browser |
+| `GET /api/check-agents` | Session | List available AI agents |
+| `POST /api/ws-ticket` | Session | Get WebSocket connection ticket |
+| `WS /api/terminal/ws` | Ticket | Interactive terminal session |
+
+Internal API (localhost:8001):
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /audit` | View audit logs |
+| `GET /deeplog` | View deep (plaintext) logs |
+| `GET /terminal/status` | Terminal session status |
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `AGENT_TOKEN` | Auto-generated | Bearer token for API auth |
+| `ALLOWED_DIRS` | Home + CWD | Comma-separated allowed directories |
+| `AUDIT_LOG_DIR` | `./logs` | Audit log directory |
+| `PUBLIC_PORT` | `8000` | Public API port |
+| `INTERNAL_PORT` | `8001` | Internal admin port |
+
+## Development
+
+```bash
+git clone https://github.com/maliozturk/CorvusTunnel.git
+cd CorvusTunnel
+pip install -e ".[dev]"
+AGENT_TOKEN=dev-token corvustunnel start --verbose
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT — see [LICENSE](LICENSE)
+
+## Links
+
+- **Website**: [corvustunnel.com](https://corvustunnel.com)
+- **GitHub**: [github.com/maliozturk/CorvusTunnel](https://github.com/maliozturk/CorvusTunnel)

corvustunnel-1.0.0/README.md

@@ -0,0 +1,130 @@
+# CorvusTunnel
+
+**Control AI Agents from Your Phone**
+
+Self-hosted remote control for Claude Code, Codex, and Antigravity. Free, open source, E2E encrypted.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![PyPI](https://img.shields.io/pypi/v/corvustunnel.svg)](https://pypi.org/project/corvustunnel/)
+
+---
+
+## Quick Start
+
+```bash
+# Install
+pip install corvustunnel
+
+# Start
+corvustunnel start
+
+# With a specific workspace
+corvustunnel start --workspace /path/to/your/project
+```
+
+Scan the QR code with your phone → you're connected.
+
+## Features
+
+- **Multi-agent support** — Claude Code, Codex CLI, Antigravity
+- **End-to-end encryption** — NaCl/libsodium, key exchange via QR code
+- **QR code connect** — scan to connect, no manual URL typing
+- **Real-time streaming** — WebSocket-based terminal I/O via xterm.js
+- **Push notifications** — Web Push API alerts for agent events
+- **PWA support** — install on your phone like a native app
+- **Smart suggestions** — context-aware action chips (approve, reject, continue)
+- **Command favorites** — pin frequently used prompts for one-tap access
+- **Audit logging** — JSONL forensic logs of all sessions
+- **Security hardened** — IP ban, rate limiting, body size limits, CORS, security headers
+- **Self-hosted** — runs on your machine, your data stays with you
+- **Unlimited** — no session limits, no cooldowns, no restrictions
+
+## How It Works
+
+```
+Your Phone                    Your Computer
+┌─────────┐                  ┌──────────────────┐
+│         │   WebSocket      │  CorvusTunnel    │
+│  Scan   │ ◄──────────────► │  ├── FastAPI     │
+│  QR     │   (E2E encrypted)│  ├── PTY/pexpect │
+│  Code   │                  │  └── Agent       │
+│         │                  │      (claude/    │
+│  Send   │                  │       codex/     │
+│  prompts│                  │       agy)       │
+└─────────┘                  └──────────────────┘
+     ▲                              ▲
+     │    Cloudflare Relay          │
+     └──────────────────────────────┘
+         (TLS + E2E encryption)
+```
+
+## Installation
+
+```bash
+pip install corvustunnel
+corvustunnel start
+```
+
+## Security
+
+- **E2E Encryption**: All terminal I/O encrypted with NaCl SecretBox (XSalsa20-Poly1305)
+- **Key Exchange**: X25519 Diffie-Hellman during QR code scanning
+- **Auth**: One-time boot token → session token with IP binding
+- **WebSocket**: Ticket-based auth (one-time, 30s TTL, IP-bound)
+- **Rate Limiting**: Per-endpoint via slowapi
+- **IP Auto-Ban**: After repeated auth failures
+
+See [SECURITY.md](SECURITY.md) for full details and vulnerability reporting.
+
+## API
+
+| Endpoint | Auth | Description |
+|----------|------|-------------|
+| `GET /api/health` | No | Health check |
+| `POST /api/e2e/exchange` | No | E2E key exchange |
+| `POST /api/claim` | Boot token | Exchange boot token for session token |
+| `GET /api/browse` | Session | Directory browser |
+| `GET /api/check-agents` | Session | List available AI agents |
+| `POST /api/ws-ticket` | Session | Get WebSocket connection ticket |
+| `WS /api/terminal/ws` | Ticket | Interactive terminal session |
+
+Internal API (localhost:8001):
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /audit` | View audit logs |
+| `GET /deeplog` | View deep (plaintext) logs |
+| `GET /terminal/status` | Terminal session status |
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `AGENT_TOKEN` | Auto-generated | Bearer token for API auth |
+| `ALLOWED_DIRS` | Home + CWD | Comma-separated allowed directories |
+| `AUDIT_LOG_DIR` | `./logs` | Audit log directory |
+| `PUBLIC_PORT` | `8000` | Public API port |
+| `INTERNAL_PORT` | `8001` | Internal admin port |
+
+## Development
+
+```bash
+git clone https://github.com/maliozturk/CorvusTunnel.git
+cd CorvusTunnel
+pip install -e ".[dev]"
+AGENT_TOKEN=dev-token corvustunnel start --verbose
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT — see [LICENSE](LICENSE)
+
+## Links
+
+- **Website**: [corvustunnel.com](https://corvustunnel.com)
+- **GitHub**: [github.com/maliozturk/CorvusTunnel](https://github.com/maliozturk/CorvusTunnel)

corvustunnel-1.0.0/audit/__init__.py

@@ -0,0 +1 @@
+"""CorvusTunnel audit package."""

corvustunnel-1.0.0/audit/deep_logger.py

@@ -0,0 +1,270 @@
+"""
+CorvusTunnel Deep Logger — Full forensic trail of every action.
+
+Unlike the audit logger (which hashes prompts), the deep logger records
+everything in plaintext:  prompts, full outputs, paths browsed, auth
+events, errors, and timing.  Files are stored locally with daily
+rotation and are NEVER exposed through the public API.
+
+Usage:
+    from audit.deep_logger import deep_log
+
+    deep_log("prompt_submitted", prompt="list files", job_id="abc123",
+             client_ip="198.41.200.1", work_dir="C:\\projects\\demo")
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import sys
+import threading
+import time
+import traceback
+from datetime import datetime, timezone
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+
+class DeepLogger:
+    """Append-only JSONL deep logger with daily rotation and thread safety.
+
+    Every event includes:
+        - Monotonic and wall-clock timestamps
+        - Event category and action name
+        - Full payload (prompts, outputs, paths — never hashed)
+        - System context on first boot event
+
+    Files are named  ``deep_YYYY-MM-DD.jsonl``  inside the log directory.
+    """
+
+    _BOOT_LOGGED = False
+
+    def __init__(self, log_dir: str = "./logs"):
+        self._log_dir = Path(log_dir) / "deep"
+        self._log_dir.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.Lock()
+        self._seq = 0  # Monotonic event counter
+
+        if not DeepLogger._BOOT_LOGGED:
+            DeepLogger._BOOT_LOGGED = True
+            self._log_boot()
+
+    # ── Public API ────────────────────────────────────────────────────
+
+    def log(
+        self,
+        action: str,
+        *,
+        category: str = "general",
+        **kwargs: Any,
+    ) -> None:
+        """Append an event to the deep log.
+
+        Args:
+            action:   Short verb, e.g. ``prompt_submitted``, ``job_approved``
+            category: Grouping tag — ``auth``, ``job``, ``browse``, ``exec``, ``system``
+            **kwargs: Arbitrary payload (prompts, outputs, paths, IPs, etc.)
+        """
+        with self._lock:
+            self._seq += 1
+            seq = self._seq
+
+        event: dict[str, Any] = {
+            "seq": seq,
+            "ts": time.time(),
+            "iso": datetime.now(timezone.utc).isoformat(),
+            "category": category,
+            "action": action,
+        }
+        # Flatten payload — skip None values to keep logs clean
+        for k, v in kwargs.items():
+            if v is not None:
+                event[k] = v
+
+        self._write(event)
+
+    # ── Convenience shortcuts ─────────────────────────────────────────
+
+    def auth_success(self, client_ip: str) -> None:
+        self.log("auth_success", category="auth", client_ip=client_ip)
+
+    def auth_fail(self, client_ip: str, reason: str = "") -> None:
+        self.log("auth_fail", category="auth", client_ip=client_ip, reason=reason)
+
+    def prompt_submitted(
+        self,
+        job_id: str,
+        prompt: str,
+        target: str,
+        client_ip: str,
+        work_dir: str | None = None,
+        require_approval: bool = True,
+        is_shell: bool = False,
+    ) -> None:
+        self.log(
+            "prompt_submitted",
+            category="job",
+            job_id=job_id,
+            prompt=prompt,
+            target=target,
+            client_ip=client_ip,
+            work_dir=work_dir,
+            require_approval=require_approval,
+            is_shell=is_shell,
+        )
+
+    def job_approved(self, job_id: str) -> None:
+        self.log("job_approved", category="job", job_id=job_id)
+
+    def job_rejected(self, job_id: str) -> None:
+        self.log("job_rejected", category="job", job_id=job_id)
+
+    def exec_start(
+        self, job_id: str, command: str, work_dir: str, mode: str = "agy"
+    ) -> None:
+        self.log(
+            "exec_start",
+            category="exec",
+            job_id=job_id,
+            command=command,
+            work_dir=work_dir,
+            mode=mode,
+        )
+
+    def exec_done(
+        self,
+        job_id: str,
+        return_code: int | None,
+        duration_s: float,
+        stdout: str | None = None,
+        stderr: str | None = None,
+        error: str | None = None,
+        timed_out: bool = False,
+    ) -> None:
+        self.log(
+            "exec_done",
+            category="exec",
+            job_id=job_id,
+            return_code=return_code,
+            duration_s=round(duration_s, 3),
+            stdout=stdout,
+            stderr=stderr,
+            error=error,
+            timed_out=timed_out,
+        )
+
+    def browse(self, client_ip: str, path: str | None, result_count: int) -> None:
+        self.log(
+            "browse",
+            category="browse",
+            client_ip=client_ip,
+            path=path,
+            result_count=result_count,
+        )
+
+    def browse_blocked(self, client_ip: str, path: str, reason: str) -> None:
+        self.log(
+            "browse_blocked",
+            category="browse",
+            client_ip=client_ip,
+            path=path,
+            reason=reason,
+        )
+
+    def error(self, action: str, error: str, **ctx: Any) -> None:
+        self.log(
+            action,
+            category="error",
+            error=error,
+            traceback=traceback.format_exc() if sys.exc_info()[0] else None,
+            **ctx,
+        )
+
+    # ── Reading (for the internal admin endpoint) ─────────────────────
+
+    def read_recent(self, limit: int = 100, date: str | None = None) -> list[dict]:
+        """Read recent deep log entries.
+
+        Args:
+            limit: Max entries to return (newest first)
+            date:  ``YYYY-MM-DD`` string; defaults to today
+        """
+        if date is None:
+            date = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+        log_path = self._log_dir / f"deep_{date}.jsonl"
+        if not log_path.exists():
+            return []
+
+        entries: list[dict] = []
+        try:
+            with open(log_path, "r", encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if line:
+                        try:
+                            entries.append(json.loads(line))
+                        except json.JSONDecodeError:
+                            continue
+        except OSError:
+            return []
+
+        return entries[-limit:]
+
+    def list_dates(self) -> list[str]:
+        """Return available log dates (newest first)."""
+        dates = []
+        for p in sorted(self._log_dir.glob("deep_*.jsonl"), reverse=True):
+            dates.append(p.stem.replace("deep_", ""))
+        return dates
+
+    # ── Internal ──────────────────────────────────────────────────────
+
+    def _log_boot(self) -> None:
+        """Log a boot event with system info on first init."""
+        self.log(
+            "server_boot",
+            category="system",
+            python=sys.version,
+            platform=platform.platform(),
+            pid=os.getpid(),
+            cwd=os.getcwd(),
+        )
+
+    def _get_log_path(self) -> Path:
+        today = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+        return self._log_dir / f"deep_{today}.jsonl"
+
+    def _write(self, event: dict[str, Any]) -> None:
+        log_path = self._get_log_path()
+        try:
+            with self._lock:
+                with open(log_path, "a", encoding="utf-8") as f:
+                    f.write(json.dumps(event, ensure_ascii=False, default=str) + "\n")
+        except OSError:
+            print(
+                f"[DEEP LOG FALLBACK] {json.dumps(event, default=str)}",
+                file=sys.stderr,
+            )
+
+
+# ── Singleton ────────────────────────────────────────────────────────
+
+@lru_cache(maxsize=1)
+def get_deep_logger() -> DeepLogger:
+    """Return the singleton DeepLogger.
+
+    Logs are stored at ``~/.corvustunnel/logs/deep/`` by default —
+    outside any ALLOWED_DIRS path so they are unreachable from the tunnel.
+    """
+    from config.settings import get_settings
+
+    settings = get_settings()
+    return DeepLogger(log_dir=settings.resolved_deep_log_dir)
+
+
+def deep_log(action: str, *, category: str = "general", **kwargs: Any) -> None:
+    """Module-level shortcut for quick logging."""
+    get_deep_logger().log(action, category=category, **kwargs)