worthless 0.3.0__py3-none-any.whl

worthless/adapters/__init__.py

@@ -0,0 +1,15 @@
+"""Provider adapters for upstream API request/response transformation."""
+
+from worthless.adapters.anthropic import AnthropicAdapter
+from worthless.adapters.openai import OpenAIAdapter
+from worthless.adapters.registry import get_adapter
+from worthless.adapters.types import AdapterRequest, AdapterResponse, ProviderAdapter
+
+__all__ = [
+    "AdapterRequest",
+    "AdapterResponse",
+    "AnthropicAdapter",
+    "OpenAIAdapter",
+    "ProviderAdapter",
+    "get_adapter",
+]

worthless/adapters/anthropic.py

@@ -0,0 +1,42 @@
+"""Anthropic provider adapter — stateless request/response transformer."""
+
+from __future__ import annotations
+
+import os
+
+import httpx
+
+from worthless.adapters.types import (
+    AdapterRequest,
+    AdapterResponse,
+    relay_response,
+    strip_internal_headers,
+)
+
+UPSTREAM_URL = os.environ.get(
+    "WORTHLESS_UPSTREAM_ANTHROPIC_URL",
+    "https://api.anthropic.com/v1/messages",
+)
+DEFAULT_ANTHROPIC_VERSION = "2023-06-01"
+
+
+class AnthropicAdapter:
+    """Transforms requests for the Anthropic messages API."""
+
+    def prepare_request(
+        self,
+        *,
+        body: bytes,
+        headers: dict[str, str],
+        api_key: bytearray,
+    ) -> AdapterRequest:
+        out_headers = strip_internal_headers(headers)
+        out_headers["x-api-key"] = api_key.decode()
+
+        if "anthropic-version" not in out_headers:
+            out_headers["anthropic-version"] = DEFAULT_ANTHROPIC_VERSION
+
+        return AdapterRequest(url=UPSTREAM_URL, headers=out_headers, body=body)
+
+    async def relay_response(self, response: httpx.Response) -> AdapterResponse:
+        return await relay_response(response)

worthless/adapters/openai.py

@@ -0,0 +1,37 @@
+"""OpenAI provider adapter — stateless request/response transformer."""
+
+from __future__ import annotations
+
+import os
+
+import httpx
+
+from worthless.adapters.types import (
+    AdapterRequest,
+    AdapterResponse,
+    relay_response,
+    strip_internal_headers,
+)
+
+UPSTREAM_URL = os.environ.get(
+    "WORTHLESS_UPSTREAM_OPENAI_URL",
+    "https://api.openai.com/v1/chat/completions",
+)
+
+
+class OpenAIAdapter:
+    """Transforms requests for the OpenAI chat completions API."""
+
+    def prepare_request(
+        self,
+        *,
+        body: bytes,
+        headers: dict[str, str],
+        api_key: bytearray,
+    ) -> AdapterRequest:
+        out_headers = strip_internal_headers(headers)
+        out_headers["authorization"] = f"Bearer {api_key.decode()}"
+        return AdapterRequest(url=UPSTREAM_URL, headers=out_headers, body=body)
+
+    async def relay_response(self, response: httpx.Response) -> AdapterResponse:
+        return await relay_response(response)

worthless/adapters/registry.py

@@ -0,0 +1,17 @@
+"""Path-based adapter lookup."""
+
+from __future__ import annotations
+
+from worthless.adapters.anthropic import AnthropicAdapter
+from worthless.adapters.openai import OpenAIAdapter
+from worthless.adapters.types import ProviderAdapter
+
+_ADAPTERS: dict[str, ProviderAdapter] = {
+    "/v1/chat/completions": OpenAIAdapter(),
+    "/v1/messages": AnthropicAdapter(),
+}
+
+
+def get_adapter(path: str) -> ProviderAdapter | None:
+    """Return the adapter for the given request path, or None if unrecognized."""
+    return _ADAPTERS.get(path)

worthless/adapters/types.py

@@ -0,0 +1,126 @@
+"""Adapter contracts for provider request/response transformation."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from typing import Protocol
+
+import httpx
+
+INTERNAL_HEADER_PREFIX = "x-worthless-"
+
+# RFC 2616 hop-by-hop headers that must not be forwarded by proxies.
+_HOP_BY_HOP_HEADERS: frozenset[str] = frozenset(
+    {
+        "connection",
+        "transfer-encoding",
+        "te",
+        "upgrade",
+        "proxy-authorization",
+        "host",
+        "keep-alive",
+        "trailer",
+        "proxy-connection",
+    }
+)
+
+SSE_RESPONSE_HEADERS: dict[str, str] = {
+    "Content-Type": "text/event-stream; charset=utf-8",
+    "Cache-Control": "no-cache",
+    "X-Accel-Buffering": "no",
+    "Connection": "keep-alive",
+}
+
+
+_SENSITIVE_HEADER_KEYS: frozenset[str] = frozenset({"authorization", "x-api-key"})
+
+
+@dataclass(frozen=True)
+class AdapterRequest:
+    """Upstream request prepared by a provider adapter."""
+
+    url: str
+    headers: dict[str, str]
+    body: bytes
+
+    def __repr__(self) -> str:
+        redacted: dict[str, str] = {}
+        for k, v in self.headers.items():
+            if k.lower() in _SENSITIVE_HEADER_KEYS:
+                redacted[k] = "REDACTED"
+            else:
+                redacted[k] = v
+        return (
+            f"AdapterRequest(url={self.url!r}, headers={redacted!r}, body=<{len(self.body)} bytes>)"
+        )
+
+
+@dataclass(frozen=True)
+class AdapterResponse:
+    """Upstream response relayed by a provider adapter."""
+
+    status_code: int
+    headers: dict[str, str]
+    body: bytes
+    is_streaming: bool = False
+    stream: AsyncIterator[bytes] | None = field(default=None, compare=False)
+
+    def __repr__(self) -> str:
+        return (
+            f"AdapterResponse(status_code={self.status_code}, "
+            f"headers=<{len(self.headers)} entries>, "
+            f"body=<{len(self.body)} bytes>, "
+            f"is_streaming={self.is_streaming})"
+        )
+
+
+class ProviderAdapter(Protocol):
+    """Protocol that all provider adapters must satisfy."""
+
+    def prepare_request(
+        self,
+        *,
+        body: bytes,
+        headers: dict[str, str],
+        api_key: bytearray,
+    ) -> AdapterRequest: ...
+
+    async def relay_response(self, response: httpx.Response) -> AdapterResponse: ...
+
+
+def strip_internal_headers(headers: dict[str, str]) -> dict[str, str]:
+    """Copy headers, dropping x-worthless-*, hop-by-hop headers, and lowercasing keys."""
+    return {
+        low: v
+        for k, v in headers.items()
+        if not (low := k.lower()).startswith(INTERNAL_HEADER_PREFIX)
+        and low not in _HOP_BY_HOP_HEADERS
+    }
+
+
+async def relay_response(response: httpx.Response) -> AdapterResponse:
+    """Shared relay logic for all adapters — handles streaming and non-streaming.
+
+    Supports responses sent with stream=True: for non-SSE responses, reads the
+    body with aread() before accessing content.
+    """
+    content_type = response.headers.get("content-type", "")
+    ct_main = content_type.split(";")[0].strip().lower()
+    if ct_main == "text/event-stream":
+        return AdapterResponse(
+            status_code=response.status_code,
+            headers=dict(SSE_RESPONSE_HEADERS),
+            body=b"",
+            is_streaming=True,
+            stream=response.aiter_bytes(),
+        )
+    # For non-streaming: read body if sent with stream=True
+    if not hasattr(response, "_content"):
+        await response.aread()
+    return AdapterResponse(
+        status_code=response.status_code,
+        headers=dict(response.headers),
+        body=response.content,
+        is_streaming=False,
+    )

worthless/cli/__init__.py

@@ -0,0 +1,5 @@
+"""Worthless CLI — enrollment and key management stubs."""
+
+from worthless.cli.app import app
+
+__all__ = ["app"]

worthless/cli/app.py

@@ -0,0 +1,107 @@
+"""Typer application — CLI entry point for ``worthless``."""
+
+from __future__ import annotations
+
+import sys
+import traceback
+from importlib.metadata import version as pkg_version
+
+import typer
+
+from worthless.cli.console import WorthlessConsole, get_console, set_console
+from worthless.cli.default_command import run_default
+from worthless.cli.errors import WorthlessError, set_debug
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"worthless {pkg_version('worthless')}")
+        raise typer.Exit()
+
+
+app = typer.Typer(
+    name="worthless",
+    help=(
+        "Protect your API keys in 90 seconds.\n\n"
+        "Run 'worthless' with no arguments to auto-detect keys, "
+        "lock them, and start the proxy."
+    ),
+    no_args_is_help=False,
+    invoke_without_command=True,
+    pretty_exceptions_enable=False,
+    add_completion=False,
+)
+
+
+@app.callback(invoke_without_command=True)
+def _main(
+    ctx: typer.Context,
+    quiet: bool = typer.Option(False, "--quiet", "-q", help="Suppress non-error output"),
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON"),
+    debug: bool = typer.Option(False, "--debug", help="Show full tracebacks on error"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Auto-approve prompts"),
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        help="Show version and exit",
+        callback=_version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    """Worthless — make leaked API keys worthless."""
+    set_debug(debug)
+    set_console(WorthlessConsole(quiet=quiet, json_mode=json_output))
+
+    # When no subcommand is given, run the magic default pipeline
+    if ctx.invoked_subcommand is None:
+        try:
+            interactive = hasattr(sys.stdin, "isatty") and sys.stdin.isatty()
+            run_default(interactive=interactive, yes=yes, json_mode=json_output)
+        except WorthlessError as exc:
+            if debug:
+                traceback.print_exc(file=sys.stderr)
+            else:
+                get_console().print_error(exc)
+            raise typer.Exit(code=exc.exit_code) from exc
+
+
+# -- Register command modules --------------------------------------------------
+from worthless.cli.commands.lock import register_lock_commands  # noqa: E402
+
+register_lock_commands(app)
+
+from worthless.cli.commands.unlock import register_unlock_commands  # noqa: E402
+
+register_unlock_commands(app)
+
+from worthless.cli.commands.scan import register_scan_commands  # noqa: E402
+
+register_scan_commands(app)
+
+from worthless.cli.commands.status import register_status_commands  # noqa: E402
+
+register_status_commands(app)
+
+from worthless.cli.commands.wrap import register_wrap_commands  # noqa: E402
+
+register_wrap_commands(app)
+
+from worthless.cli.commands.up import register_up_commands  # noqa: E402
+
+register_up_commands(app)
+
+from worthless.cli.commands.down import register_down_commands  # noqa: E402
+
+register_down_commands(app)
+
+try:
+    from worthless.cli.commands.mcp import register_mcp_commands  # noqa: E402
+
+    register_mcp_commands(app)
+except ImportError:
+    pass  # mcp extra not installed — worthless[mcp]
+
+from worthless.cli.commands.revoke import register_revoke_commands  # noqa: E402
+
+register_revoke_commands(app)

worthless/cli/bootstrap.py

@@ -0,0 +1,235 @@
+"""First-run ~/.worthless/ initialization and lock management."""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+import time
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from pathlib import Path
+from collections.abc import Generator
+
+from cryptography.fernet import Fernet
+
+from worthless.cli.errors import ErrorCode, WorthlessError, sanitize_exception
+from worthless.cli.keystore import migrate_file_to_keyring, read_fernet_key, store_fernet_key
+from worthless.cli.platform import IS_WINDOWS
+
+_DEFAULT_BASE = Path.home() / ".worthless"
+_STALE_LOCK_SECONDS = 300  # 5 minutes
+
+
+@dataclass
+class WorthlessHome:
+    """Paths within the ``~/.worthless/`` directory tree."""
+
+    base_dir: Path = field(default_factory=lambda: _DEFAULT_BASE)
+
+    @property
+    def db_path(self) -> Path:
+        return self.base_dir / "worthless.db"
+
+    @property
+    def fernet_key_path(self) -> Path:
+        env_path = os.environ.get("WORTHLESS_FERNET_KEY_PATH")
+        if env_path:
+            return Path(env_path)
+        return self.base_dir / "fernet.key"
+
+    @property
+    def shard_a_dir(self) -> Path:
+        return self.base_dir / "shard_a"
+
+    @property
+    def lock_file(self) -> Path:
+        return self.base_dir / ".lock-in-progress"
+
+    @property
+    def fernet_key(self) -> bytearray:
+        """Read the Fernet key via keystore cascade (SR-01: mutable bytearray)."""
+        return read_fernet_key(self.base_dir)
+
+
+def ensure_home(base_dir: Path | None = None) -> WorthlessHome:
+    """Create ``~/.worthless/`` structure on first run (idempotent).
+
+    Creates directories with 0700 permissions, generates a Fernet key if
+    missing, and initialises the SQLite database.
+    """
+    home = WorthlessHome(base_dir=base_dir or _DEFAULT_BASE)
+
+    try:
+        # Create directories
+        home.base_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
+        home.shard_a_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
+
+        # Ensure permissions are correct even if dir already existed
+        if not IS_WINDOWS:
+            home.base_dir.chmod(0o700)
+            home.shard_a_dir.chmod(0o700)
+
+        # Validate custom fernet key path if set via env var
+        fernet_path = home.fernet_key_path
+        fernet_parent = fernet_path.parent
+        if os.environ.get("WORTHLESS_FERNET_KEY_PATH") and not fernet_parent.is_dir():
+            raise WorthlessError(
+                ErrorCode.BOOTSTRAP_FAILED,
+                f"WORTHLESS_FERNET_KEY_PATH directory does not exist: {fernet_parent}\n"
+                "Create it or mount a volume at that path.",
+            )
+
+        # Generate Fernet key if missing (keyring or file fallback)
+        try:
+            read_fernet_key(home.base_dir)
+        except WorthlessError as exc:
+            if exc.code != ErrorCode.KEY_NOT_FOUND:
+                raise
+            key = Fernet.generate_key()
+            store_fernet_key(key, home_dir=home.base_dir)
+        else:
+            migrate_file_to_keyring(home.base_dir)
+    except WorthlessError:
+        raise
+    except OSError as exc:
+        fernet_env = os.environ.get("WORTHLESS_FERNET_KEY_PATH")
+        if fernet_env:
+            raise WorthlessError(
+                ErrorCode.BOOTSTRAP_FAILED,
+                f"Cannot write fernet key to {fernet_env}: "
+                f"{sanitize_exception(exc, generic='permission denied or path invalid')}\n"
+                "Check that the directory exists and is writable.",
+            ) from exc
+        raise WorthlessError(
+            ErrorCode.BOOTSTRAP_FAILED,
+            sanitize_exception(exc, generic="failed to initialise home directory"),
+        ) from exc
+
+    # Initialise database (idempotent — CREATE TABLE IF NOT EXISTS)
+    try:
+        _init_db(home)
+    except (OSError, sqlite3.DatabaseError) as exc:
+        raise WorthlessError(
+            ErrorCode.SHARD_STORAGE_FAILED,
+            sanitize_exception(exc, generic="failed to initialise database"),
+        ) from exc
+
+    return home
+
+
+def _init_db(home: WorthlessHome) -> None:
+    """Create the SQLite database using the canonical schema and run migrations."""
+    import asyncio
+
+    from worthless.storage.schema import SCHEMA, migrate_db
+
+    conn = sqlite3.connect(str(home.db_path))
+    try:
+        conn.execute("PRAGMA foreign_keys = ON")
+
+        # Run forward-only migrations BEFORE the full schema so that
+        # upgraded installs whose enrollments table pre-dates the
+        # decoy_hash column get it added before CREATE INDEX touches it.
+        tables = {
+            row[0]
+            for row in conn.execute("SELECT name FROM sqlite_master WHERE type='table'").fetchall()
+        }
+        if "enrollments" in tables:
+            cursor = conn.execute("PRAGMA table_info(enrollments)")
+            columns = {row[1] for row in cursor.fetchall()}
+            if "decoy_hash" not in columns:
+                try:
+                    conn.execute("ALTER TABLE enrollments ADD COLUMN decoy_hash TEXT")
+                    conn.commit()
+                except sqlite3.OperationalError as exc:
+                    if "duplicate column" not in str(exc).lower():
+                        raise
+
+        conn.executescript(SCHEMA)
+        conn.execute("PRAGMA journal_mode=WAL")
+        conn.commit()
+    finally:
+        conn.close()
+
+    # Run async migrations (WOR-183: rules engine columns, spend_log cleanup)
+    try:
+        asyncio.get_running_loop()
+        # Already in async context — schedule as a task won't work from sync.
+        # Use a new thread's event loop instead.
+        import concurrent.futures
+
+        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+            pool.submit(asyncio.run, migrate_db(str(home.db_path))).result()
+    except RuntimeError:
+        # No running loop — safe to use asyncio.run()
+        asyncio.run(migrate_db(str(home.db_path)))
+
+    # Restrict DB file permissions (no-op on Windows — NTFS ACLs are different)
+    if not IS_WINDOWS:
+        home.db_path.chmod(0o600)
+
+
+@contextmanager
+def acquire_lock(home: WorthlessHome) -> Generator[None, None, None]:
+    """Acquire an exclusive lock file using O_CREAT|O_EXCL."""
+    check_stale_lock(home)
+    try:
+        fd = os.open(
+            str(home.lock_file),
+            os.O_WRONLY | os.O_CREAT | os.O_EXCL,
+            0o600,
+        )
+        os.close(fd)
+    except FileExistsError:
+        raise WorthlessError(
+            ErrorCode.LOCK_IN_PROGRESS,
+            "Another worthless operation is in progress. "
+            "Remove ~/.worthless/.lock-in-progress if stale.",
+        ) from None  # FileExistsError context is not useful to callers
+    try:
+        yield
+    finally:
+        try:
+            home.lock_file.unlink()
+        except FileNotFoundError:
+            pass
+
+
+def get_home() -> WorthlessHome:
+    """Resolve WorthlessHome from WORTHLESS_HOME env var or default."""
+    env_home = os.environ.get("WORTHLESS_HOME")
+    if env_home:
+        return ensure_home(Path(env_home))
+    return ensure_home()
+
+
+def resolve_home() -> WorthlessHome | None:
+    """Try to load WorthlessHome; return None if not initialized."""
+    try:
+        env_home = os.environ.get("WORTHLESS_HOME")
+        if env_home:
+            base = Path(env_home)
+            if base.exists():
+                return ensure_home(base)
+            return None
+        default = Path.home() / ".worthless"
+        if default.exists():
+            return ensure_home(default)
+        return None
+    except Exception:
+        return None
+
+
+def check_stale_lock(home: WorthlessHome) -> None:
+    """Remove stale lock files (> 5 min old), raise on fresh locks."""
+    if not home.lock_file.exists():
+        return
+    age = time.time() - home.lock_file.stat().st_mtime
+    if age > _STALE_LOCK_SECONDS:
+        home.lock_file.unlink(missing_ok=True)
+    else:
+        raise WorthlessError(
+            ErrorCode.LOCK_IN_PROGRESS,
+            f"Lock file is {int(age)}s old (< {_STALE_LOCK_SECONDS}s). "
+            "Another operation may be running.",
+        )

worthless/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""CLI command modules for worthless."""

worthless/cli/commands/down.py

@@ -0,0 +1,97 @@
+"""down command -- stop a running proxy daemon.
+
+``worthless down`` reads the PID file, sends SIGTERM to the process group,
+polls for exit, escalates to SIGKILL after a timeout, and cleans up.
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+import typer
+
+from worthless.cli.bootstrap import get_home
+from worthless.cli.console import WorthlessConsole, get_console
+from worthless.cli.errors import ErrorCode, WorthlessError, error_boundary
+from worthless.cli.platform import kill_tree, warn_windows_once
+from worthless.cli.process import MAX_VALID_PID, check_pid, pid_path, read_pid
+
+# Tunable for tests
+_TERM_TIMEOUT: float = 5.0
+_POLL_INTERVAL: float = 0.2
+
+
+def _done(pf: Path, console: WorthlessConsole, msg: str, *, success: bool = False) -> None:
+    """Clean PID file and print status."""
+    pf.unlink(missing_ok=True)
+    if success:
+        console.print_success(msg)
+    else:
+        console.print_warning(msg)
+
+
+def register_down_commands(app: typer.Typer) -> None:
+    """Register the ``down`` command on the Typer app."""
+
+    @app.command()
+    @error_boundary
+    def down() -> None:
+        """Stop the running proxy daemon."""
+        console = get_console()
+        home = get_home()
+        warn_windows_once(quiet=console.quiet)
+
+        pf = pid_path(home)
+        info = read_pid(pf)
+
+        # No PID file or corrupt → nothing to stop (idempotent)
+        if info is None:
+            _done(pf, console, "Proxy is not running.")
+            return
+
+        pid, port = info
+
+        # Reject dangerous or out-of-range PID values
+        if pid <= 1 or pid > MAX_VALID_PID:
+            _done(pf, console, f"Proxy is not running (invalid PID {pid} cleaned up).")
+            return
+
+        # Stale PID → clean up
+        if not check_pid(pid):
+            _done(pf, console, f"Proxy is not running (stale PID {pid} cleaned up).")
+            return
+
+        # Kill the process tree (SIGTERM via psutil)
+        try:
+            kill_tree(pid)
+        except PermissionError as exc:
+            raise WorthlessError(
+                ErrorCode.PROXY_NOT_RUNNING,
+                f"Cannot stop PID {pid}: permission denied. "
+                f"Try: sudo kill -9 {pid}, then: worthless down",
+            ) from exc
+
+        console.print_hint(f"Stopping proxy (PID {pid})...")
+
+        # Poll for graceful exit
+        deadline = time.monotonic() + _TERM_TIMEOUT
+        while time.monotonic() < deadline:
+            if not check_pid(pid):
+                _done(pf, console, f"Proxy stopped (was PID {pid} on port {port}).", success=True)
+                return
+            time.sleep(_POLL_INTERVAL)
+
+        # Escalate: force kill (SIGKILL on Unix, TerminateProcess on Windows)
+        try:
+            kill_tree(pid, force=True)
+        except PermissionError:
+            pass
+
+        time.sleep(_POLL_INTERVAL)
+        _done(
+            pf,
+            console,
+            f"Proxy did not respond to SIGTERM within {_TERM_TIMEOUT:.0f}s; "
+            f"force-killed (was PID {pid} on port {port}).",
+        )