codexfer 0.1.0__tar.gz

codexfer-0.1.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: codexfer
+Version: 0.1.0
+Summary: End-to-end encrypted code sharing for developers.
+Requires-Python: >=3.10
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13.7
+Requires-Dist: cryptography>=42.0
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"

codexfer-0.1.0/README.md

@@ -0,0 +1,68 @@
+# CodeXfer
+
+End-to-end encrypted code sharing for developers. The server never sees
+plaintext source code — compression and encryption both happen locally.
+
+## Install (pure Python, cross-platform)
+
+```bash
+python -m venv .venv
+source .venv/bin/activate      # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"        # or: pip install -e .
+```
+
+## Usage
+
+```bash
+cd your-project
+codexfer pack
+codexfer share my-project
+
+# on the receiving machine
+codexfer build CXF8A92K
+```
+
+## Configuring the backend
+
+By default, with no backend configured, `share`/`build` fall back to a local
+folder (`~/.codexfer/packages`, override with `CODEXFER_LOCAL_DIR`) so you can
+test the full flow on one machine before deploying anything.
+
+To use the real Cloudflare-backed server, deploy `worker/` (see
+`worker/README.md`) and set:
+
+```bash
+export CODEXFER_API_URL="https://your-worker.your-subdomain.workers.dev"
+```
+
+## Security model
+
+- AES-256-GCM authenticated encryption, key derived from the Access Code via
+  PBKDF2-HMAC-SHA256 (390,000 iterations) with a random salt per package.
+- The Access Code is generated locally and never transmitted to or stored on
+  the server — only the Package ID and ciphertext travel over the network.
+- GCM's authentication tag detects any tampering or corruption at decrypt time.
+
+## Project layout
+
+```
+codexfer/
+  __init__.py
+  cli.py              Typer CLI: pack / share / build
+  config.py           Environment-driven settings
+  compression.py       Project -> zip (excludes .git, venv, node_modules, etc.)
+  encryption.py        AES-256-GCM + PBKDF2 key derivation
+  package_format.py    .cxf container read/write
+  api_client.py        Upload/download, with local-folder fallback
+  utils.py             ID/access-code generation, logging
+tests/
+  test_core.py
+worker/                Cloudflare Worker backend (R2 + D1)
+```
+
+## Running tests
+
+```bash
+pip install pytest
+pytest
+```

codexfer-0.1.0/codexfer/__init__.py

@@ -0,0 +1,2 @@
+"""CodeXfer: end-to-end encrypted code sharing."""
+__version__ = "0.1.0"

codexfer-0.1.0/codexfer/api_client.py

@@ -0,0 +1,73 @@
+"""HTTP client for the CodeXfer backend (Cloudflare Worker).
+
+If CODEXFER_API_URL is not configured, CodeXfer falls back to a local
+"packages" directory so the whole pack/share/build flow still works
+end-to-end on one machine without any cloud account -- useful for testing
+before you deploy the Worker.
+"""
+from __future__ import annotations
+
+import logging
+import shutil
+from pathlib import Path
+
+import requests
+
+from .config import settings
+
+logger = logging.getLogger(__name__)
+
+
+class ApiClient:
+    def __init__(self, base_url: str | None = None):
+        self.base_url = (base_url or settings.api_base_url).rstrip("/")
+        self.local_dir = Path(settings.local_fallback_dir)
+        self.local_dir.mkdir(parents=True, exist_ok=True)
+
+    @property
+    def is_remote(self) -> bool:
+        return bool(self.base_url)
+
+    def upload(self, package_id: str, cxf_path: Path, expiry_hours: int, max_downloads: int) -> None:
+        if self.is_remote:
+            with open(cxf_path, "rb") as f:
+                resp = requests.post(
+                    f"{self.base_url}/upload",
+                    params={
+                        "package_id": package_id,
+                        "expiry_hours": expiry_hours,
+                        "max_downloads": max_downloads,
+                    },
+                    data=f,
+                    headers={"Content-Type": "application/octet-stream"},
+                    timeout=120,
+                )
+            resp.raise_for_status()
+        else:
+            dest = self.local_dir / f"{package_id}.cxf"
+            shutil.copyfile(cxf_path, dest)
+            logger.warning(
+                "CODEXFER_API_URL not set -- saved package locally to %s "
+                "(no real upload happened; set CODEXFER_API_URL to use the "
+                "Cloudflare backend).",
+                dest,
+            )
+
+    def download(self, package_id: str, destination: Path) -> Path:
+        if self.is_remote:
+            resp = requests.get(f"{self.base_url}/download/{package_id}", timeout=120, stream=True)
+            resp.raise_for_status()
+            with open(destination, "wb") as f:
+                for chunk in resp.iter_content(chunk_size=settings.chunk_size_bytes):
+                    f.write(chunk)
+            return destination
+        else:
+            src = self.local_dir / f"{package_id}.cxf"
+            if not src.exists():
+                raise FileNotFoundError(
+                    f"No local package '{package_id}' found in {self.local_dir}. "
+                    "If the sender used a real deployment, set CODEXFER_API_URL "
+                    "to the same Worker URL before running 'codexfer build'."
+                )
+            shutil.copyfile(src, destination)
+            return destination

codexfer-0.1.0/codexfer/cli.py

@@ -0,0 +1,134 @@
+"""CodeXfer CLI -- exactly three commands: pack, share, build."""
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+
+from .api_client import ApiClient
+from .compression import compress_project, extract_project
+from .config import settings
+from .encryption import EncryptedBlob, decrypt_bytes, encrypt_bytes
+from .package_format import read_cxf, write_cxf
+from .utils import generate_access_code, generate_package_id, setup_logging
+
+app = typer.Typer(add_completion=False, help="CodeXfer: end-to-end encrypted code sharing.")
+console = Console()
+
+PACK_FILENAME = ".codexfer_pack.zip"
+
+
+@app.command()
+def pack(
+    project_dir: str = typer.Argument(".", help="Project directory to pack (default: current dir)."),
+    verbose: bool = typer.Option(False, "--verbose", "-v"),
+):
+    """Scan and compress the current project locally. No upload happens here."""
+    setup_logging(verbose)
+    project_path = Path(project_dir).resolve()
+    out_path = project_path / PACK_FILENAME
+
+    with console.status("[bold cyan]Scanning and compressing project..."):
+        compress_project(project_path, out_path)
+
+    size_mb = out_path.stat().st_size / (1024 * 1024)
+    console.print(Panel.fit(
+        f"[green]Packed successfully[/green]\n"
+        f"Archive: {out_path}\nSize: {size_mb:.2f} MB",
+        title="codexfer pack",
+    ))
+
+
+@app.command()
+def share(
+    package_name: str = typer.Argument(..., help="Friendly name for this package."),
+    project_dir: str = typer.Option(".", "--dir", help="Project directory (must already be packed)."),
+    expiry_hours: int = typer.Option(settings.default_expiry_hours, "--expiry"),
+    max_downloads: int = typer.Option(settings.default_max_downloads, "--max-downloads"),
+    verbose: bool = typer.Option(False, "--verbose", "-v"),
+):
+    """Encrypt the packed project locally and upload only the ciphertext."""
+    setup_logging(verbose)
+    project_path = Path(project_dir).resolve()
+    pack_path = project_path / PACK_FILENAME
+
+    if not pack_path.exists():
+        console.print("[yellow]No pack found -- packing now...[/yellow]")
+        compress_project(project_path, pack_path)
+
+    package_id = generate_package_id()
+    access_code = generate_access_code()
+
+    with console.status("[bold cyan]Encrypting locally..."):
+        plaintext = pack_path.read_bytes()
+        blob = encrypt_bytes(plaintext, access_code)
+
+    with tempfile.TemporaryDirectory() as tmp:
+        cxf_path = Path(tmp) / f"{package_id}.cxf"
+        write_cxf(cxf_path, package_name, blob)
+
+        with console.status("[bold cyan]Uploading encrypted package..."):
+            client = ApiClient()
+            client.upload(package_id, cxf_path, expiry_hours, max_downloads)
+
+    pack_path.unlink(missing_ok=True)
+
+    console.print(Panel.fit(
+        f"[bold]Package ID[/bold]\n{package_id}\n\n"
+        f"[bold]Access Code[/bold]\n{access_code}\n\n"
+        f"Expires: {expiry_hours} Hours\n"
+        f"Max Downloads: {max_downloads}",
+        title="[green]Share ready[/green]",
+    ))
+    console.print("[dim]Share ONLY the Package ID and Access Code with the receiver.[/dim]")
+
+
+@app.command()
+def build(
+    package_id: str = typer.Argument(..., help="Package ID given by the sender."),
+    destination: str = typer.Option(".", "--dest", help="Where to restore the project."),
+    verbose: bool = typer.Option(False, "--verbose", "-v"),
+):
+    """Download, verify, decrypt, and restore a shared project."""
+    setup_logging(verbose)
+    access_code = typer.prompt("Enter Access Code", hide_input=True)
+
+    with tempfile.TemporaryDirectory() as tmp:
+        cxf_path = Path(tmp) / f"{package_id}.cxf"
+
+        with console.status("[bold cyan]Downloading..."):
+            client = ApiClient()
+            try:
+                client.download(package_id, cxf_path)
+            except Exception as exc:  # noqa: BLE001
+                console.print(f"[red]Download failed:[/red] {exc}")
+                raise typer.Exit(code=1)
+
+        with console.status("[bold cyan]Decrypting..."):
+            header, ciphertext = read_cxf(cxf_path)
+            blob = EncryptedBlob(
+                salt=bytes.fromhex(header.salt_hex),
+                nonce=bytes.fromhex(header.nonce_hex),
+                ciphertext=ciphertext,
+            )
+            try:
+                plaintext = decrypt_bytes(blob, access_code)
+            except Exception:
+                console.print("[red]Decryption failed -- wrong access code or corrupted package.[/red]")
+                raise typer.Exit(code=1)
+
+        zip_path = Path(tmp) / "restore.zip"
+        zip_path.write_bytes(plaintext)
+
+        with console.status("[bold cyan]Restoring project..."):
+            dest_dir = Path(destination).resolve() / header.package_name
+            extract_project(zip_path, dest_dir)
+
+    console.print(Panel.fit(f"[green]Done[/green]\nRestored to: {dest_dir}", title="codexfer build"))
+
+
+if __name__ == "__main__":
+    app()

codexfer-0.1.0/codexfer/compression.py

@@ -0,0 +1,73 @@
+"""Project compression: zip a project tree while excluding noise directories,
+preserving hidden files, binary files, and folder structure exactly.
+"""
+from __future__ import annotations
+
+import fnmatch
+import logging
+import os
+import zipfile
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_EXCLUDES = [
+    ".git", ".git/*", "__pycache__", "__pycache__/*", "*.pyc",
+    "node_modules", "node_modules/*", ".venv", ".venv/*", "venv", "venv/*",
+    ".mypy_cache", ".mypy_cache/*", ".pytest_cache", ".pytest_cache/*",
+    "dist", "dist/*", "build", "build/*", "*.egg-info", "*.egg-info/*",
+    ".codexfer_pack.zip", "*.cxf",
+]
+
+
+def _is_excluded(rel_path: str, patterns: list[str]) -> bool:
+    parts = rel_path.replace("\\", "/").split("/")
+    for pattern in patterns:
+        if fnmatch.fnmatch(rel_path.replace("\\", "/"), pattern):
+            return True
+        if any(fnmatch.fnmatch(part, pattern) for part in parts):
+            return True
+    return False
+
+
+def compress_project(
+    project_dir: str | Path,
+    output_path: str | Path,
+    excludes: list[str] | None = None,
+) -> Path:
+    """Zip project_dir -> output_path, streaming file-by-file (no full read into RAM)."""
+    project_dir = Path(project_dir).resolve()
+    output_path = Path(output_path).resolve()
+    patterns = DEFAULT_EXCLUDES + (excludes or [])
+
+    file_count = 0
+    with zipfile.ZipFile(output_path, mode="w", compression=zipfile.ZIP_DEFLATED) as zf:
+        for root, dirnames, filenames in os.walk(project_dir):
+            rel_root = os.path.relpath(root, project_dir)
+            dirnames[:] = [
+                d for d in dirnames
+                if not _is_excluded(os.path.join(rel_root, d), patterns)
+            ]
+            for name in filenames:
+                rel_path = os.path.normpath(os.path.join(rel_root, name))
+                abs_path = Path(os.path.join(root, name)).resolve()
+                # Never zip the archive into itself (it may already exist on
+                # disk while we're actively writing to it) and skip any
+                # leftover .cxf packages from a previous share.
+                if abs_path == output_path or abs_path.suffix == ".cxf":
+                    continue
+                if _is_excluded(rel_path, patterns):
+                    continue
+                zf.write(abs_path, arcname=rel_path)
+                file_count += 1
+
+    logger.info("Packed %d files from %s into %s", file_count, project_dir, output_path)
+    return output_path
+
+
+def extract_project(archive_path: str | Path, destination_dir: str | Path) -> Path:
+    destination_dir = Path(destination_dir)
+    destination_dir.mkdir(parents=True, exist_ok=True)
+    with zipfile.ZipFile(archive_path, mode="r") as zf:
+        zf.extractall(destination_dir)
+    return destination_dir

codexfer-0.1.0/codexfer/config.py

@@ -0,0 +1,24 @@
+"""Central configuration for CodeXfer.
+
+All values can be overridden via environment variables so the CLI works
+identically for every user without editing source.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Settings:
+    api_base_url: str = os.environ.get("CODEXFER_API_URL", "")
+    local_fallback_dir: str = os.environ.get(
+        "CODEXFER_LOCAL_DIR", os.path.expanduser("~/.codexfer/packages")
+    )
+    default_expiry_hours: int = int(os.environ.get("CODEXFER_EXPIRY_HOURS", "24"))
+    default_max_downloads: int = int(os.environ.get("CODEXFER_MAX_DOWNLOADS", "1"))
+    chunk_size_bytes: int = 4 * 1024 * 1024  # 4 MB streaming chunks
+    kdf_iterations: int = 390_000  # PBKDF2-HMAC-SHA256 iterations
+
+
+settings = Settings()

codexfer-0.1.0/codexfer/encryption.py

@@ -0,0 +1,55 @@
+"""AES-256-GCM encryption with PBKDF2-HMAC-SHA256 key derivation.
+
+Design:
+  - Access code is the only secret. It is generated locally, never sent
+    to the server, and never stored anywhere.
+  - A random salt (16 bytes) + random nonce (12 bytes) are stored alongside
+    the ciphertext (they are not secret; they make the key/ciphertext unique).
+  - GCM's authentication tag provides integrity verification: any tampering
+    with the ciphertext causes decryption to raise InvalidTag.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
+from cryptography.hazmat.primitives import hashes
+
+from .config import settings
+
+SALT_SIZE = 16
+NONCE_SIZE = 12
+KEY_SIZE = 32  # AES-256
+
+
+@dataclass(frozen=True)
+class EncryptedBlob:
+    salt: bytes
+    nonce: bytes
+    ciphertext: bytes  # includes GCM tag appended
+
+
+def _derive_key(access_code: str, salt: bytes) -> bytes:
+    kdf = PBKDF2HMAC(
+        algorithm=hashes.SHA256(),
+        length=KEY_SIZE,
+        salt=salt,
+        iterations=settings.kdf_iterations,
+    )
+    return kdf.derive(access_code.encode("utf-8"))
+
+
+def encrypt_bytes(plaintext: bytes, access_code: str) -> EncryptedBlob:
+    salt = os.urandom(SALT_SIZE)
+    nonce = os.urandom(NONCE_SIZE)
+    key = _derive_key(access_code, salt)
+    ciphertext = AESGCM(key).encrypt(nonce, plaintext, associated_data=None)
+    return EncryptedBlob(salt=salt, nonce=nonce, ciphertext=ciphertext)
+
+
+def decrypt_bytes(blob: EncryptedBlob, access_code: str) -> bytes:
+    key = _derive_key(access_code, blob.salt)
+    # Raises cryptography.exceptions.InvalidTag on wrong code or tampering.
+    return AESGCM(key).decrypt(blob.nonce, blob.ciphertext, associated_data=None)

codexfer-0.1.0/codexfer/package_format.py

@@ -0,0 +1,57 @@
+"""The .cxf container format: a small JSON header + the encrypted archive.
+
+Layout on disk:
+    [4 bytes]  header length (big-endian uint32)
+    [N bytes]  UTF-8 JSON header
+    [rest]     raw ciphertext bytes (AES-GCM, tag appended)
+
+The header never contains secrets. It is safe for the server to read it,
+though CodeXfer's server never needs to.
+"""
+from __future__ import annotations
+
+import json
+import struct
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from .encryption import EncryptedBlob
+
+FORMAT_VERSION = 1
+
+
+@dataclass(frozen=True)
+class CxfHeader:
+    version: int
+    package_name: str
+    compression: str  # "zip"
+    salt_hex: str
+    nonce_hex: str
+
+
+def write_cxf(path: str | Path, package_name: str, blob: EncryptedBlob) -> Path:
+    header = CxfHeader(
+        version=FORMAT_VERSION,
+        package_name=package_name,
+        compression="zip",
+        salt_hex=blob.salt.hex(),
+        nonce_hex=blob.nonce.hex(),
+    )
+    header_bytes = json.dumps(asdict(header)).encode("utf-8")
+    path = Path(path)
+    with open(path, "wb") as f:
+        f.write(struct.pack(">I", len(header_bytes)))
+        f.write(header_bytes)
+        f.write(blob.ciphertext)
+    return path
+
+
+def read_cxf(path: str | Path) -> tuple[CxfHeader, bytes]:
+    path = Path(path)
+    with open(path, "rb") as f:
+        (header_len,) = struct.unpack(">I", f.read(4))
+        header_bytes = f.read(header_len)
+        ciphertext = f.read()
+    header_dict = json.loads(header_bytes.decode("utf-8"))
+    header = CxfHeader(**header_dict)
+    return header, ciphertext

codexfer-0.1.0/codexfer/utils.py

@@ -0,0 +1,29 @@
+"""Small shared helpers: ids, access codes, logging setup."""
+from __future__ import annotations
+
+import logging
+import secrets
+import string
+
+
+def setup_logging(verbose: bool = False) -> None:
+    level = logging.DEBUG if verbose else logging.WARNING
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    )
+
+
+def generate_package_id(length: int = 8) -> str:
+    alphabet = string.ascii_uppercase + string.digits
+    return "CXF" + "".join(secrets.choice(alphabet) for _ in range(length - 3))
+
+
+def generate_access_code(groups: int = 3, group_len: int = 4) -> str:
+    """Human-friendly high-entropy code, e.g. A9KP-29QX-L81M."""
+    alphabet = string.ascii_uppercase + string.digits
+    parts = [
+        "".join(secrets.choice(alphabet) for _ in range(group_len))
+        for _ in range(groups)
+    ]
+    return "-".join(parts)

codexfer-0.1.0/codexfer.egg-info/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: codexfer
+Version: 0.1.0
+Summary: End-to-end encrypted code sharing for developers.
+Requires-Python: >=3.10
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13.7
+Requires-Dist: cryptography>=42.0
+Requires-Dist: requests>=2.31
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"

codexfer-0.1.0/codexfer.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+README.md
+pyproject.toml
+codexfer/__init__.py
+codexfer/api_client.py
+codexfer/cli.py
+codexfer/compression.py
+codexfer/config.py
+codexfer/encryption.py
+codexfer/package_format.py
+codexfer/utils.py
+codexfer.egg-info/PKG-INFO
+codexfer.egg-info/SOURCES.txt
+codexfer.egg-info/dependency_links.txt
+codexfer.egg-info/entry_points.txt
+codexfer.egg-info/requires.txt
+codexfer.egg-info/top_level.txt
+tests/test_core.py

codexfer-0.1.0/codexfer.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

codexfer-0.1.0/codexfer.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+codexfer = codexfer.cli:app

codexfer-0.1.0/codexfer.egg-info/requires.txt

@@ -0,0 +1,7 @@
+typer>=0.12
+rich>=13.7
+cryptography>=42.0
+requests>=2.31
+
+[dev]
+pytest>=8.0

codexfer-0.1.0/codexfer.egg-info/top_level.txt

@@ -0,0 +1 @@
+codexfer

codexfer-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "codexfer"
+version = "0.1.0"
+description = "End-to-end encrypted code sharing for developers."
+requires-python = ">=3.10"
+dependencies = [
+    "typer>=0.12",
+    "rich>=13.7",
+    "cryptography>=42.0",
+    "requests>=2.31",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[project.scripts]
+codexfer = "codexfer.cli:app"
+
+[tool.setuptools.packages.find]
+include = ["codexfer*"]

codexfer-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

codexfer-0.1.0/tests/test_core.py

@@ -0,0 +1,45 @@
+from codexfer.encryption import encrypt_bytes, decrypt_bytes
+from codexfer.compression import compress_project, extract_project
+from codexfer.package_format import write_cxf, read_cxf
+
+
+def test_encrypt_decrypt_roundtrip():
+    plaintext = b"print('hello world')"
+    code = "A9KP-29QX-L81M"
+    blob = encrypt_bytes(plaintext, code)
+    assert decrypt_bytes(blob, code) == plaintext
+
+
+def test_wrong_access_code_fails():
+    plaintext = b"secret source code"
+    blob = encrypt_bytes(plaintext, "RIGHT-CODE-0000")
+    try:
+        decrypt_bytes(blob, "WRONG-CODE-1111")
+        assert False, "should have raised"
+    except Exception:
+        pass
+
+
+def test_pack_and_extract_roundtrip(tmp_path):
+    project = tmp_path / "proj"
+    (project / "src").mkdir(parents=True)
+    (project / "src" / "main.py").write_text("print(1)")
+    (project / ".hidden").write_text("secret")
+
+    archive = tmp_path / "out.zip"
+    compress_project(project, archive)
+
+    restored = tmp_path / "restored"
+    extract_project(archive, restored)
+
+    assert (restored / "src" / "main.py").read_text() == "print(1)"
+    assert (restored / ".hidden").read_text() == "secret"
+
+
+def test_cxf_header_roundtrip(tmp_path):
+    blob = encrypt_bytes(b"data", "CODE-0000-0000")
+    cxf_path = tmp_path / "pkg.cxf"
+    write_cxf(cxf_path, "demo-project", blob)
+    header, ciphertext = read_cxf(cxf_path)
+    assert header.package_name == "demo-project"
+    assert ciphertext == blob.ciphertext