claw-tap 0.0.5__py3-none-any.whl

claude_tap/__init__.py

@@ -0,0 +1,47 @@
+"""claude-tap: Proxy to trace Claude Code API requests.
+
+A CLI tool that wraps Claude Code with a local proxy (reverse or forward)
+to intercept and record all API requests. Useful for studying Claude Code's
+Context Engineering.
+"""
+
+from __future__ import annotations
+
+from claude_tap.certs import CertificateAuthority, ensure_ca
+from claude_tap.cli import (
+    __version__,
+    _cleanup_traces,
+    async_main,
+    dashboard_main,
+    main_entry,
+    parse_args,
+    parse_dashboard_args,
+)
+from claude_tap.forward_proxy import ForwardProxyServer
+from claude_tap.live import LiveViewerServer
+from claude_tap.proxy import filter_headers
+from claude_tap.session_dispatcher import SessionTraceDispatcher
+from claude_tap.session_index import SessionIndex
+from claude_tap.sse import SSEReassembler
+from claude_tap.trace import TraceWriter
+from claude_tap.viewer import _generate_html_viewer
+
+__all__ = [
+    "__version__",
+    "_cleanup_traces",
+    "main_entry",
+    "parse_args",
+    "parse_dashboard_args",
+    "async_main",
+    "dashboard_main",
+    "CertificateAuthority",
+    "ensure_ca",
+    "ForwardProxyServer",
+    "SessionTraceDispatcher",
+    "SessionIndex",
+    "SSEReassembler",
+    "TraceWriter",
+    "LiveViewerServer",
+    "filter_headers",
+    "_generate_html_viewer",
+]

claude_tap/__main__.py

@@ -0,0 +1,36 @@
+"""Allow running as `python -m claude_tap`."""
+
+import asyncio
+import sys
+
+from claude_tap.cli import async_main, parse_args
+
+
+def main():
+    # Check if first argument is "export" subcommand
+    if len(sys.argv) > 1 and sys.argv[1] == "export":
+        from claude_tap.export import export_main
+
+        sys.exit(export_main(sys.argv[2:]))
+
+    argv = sys.argv[1:]
+    if "--" in argv:
+        # Explicit separator: everything after "--" goes to claude
+        idx = argv.index("--")
+        our_args = argv[:idx]
+        claude_args = argv[idx + 1 :]
+        args = parse_args(our_args)
+        args.claude_args = claude_args
+    else:
+        # No separator: parse_args handles splitting via parse_known_args
+        args = parse_args(argv)
+        # claude_args already set by parse_args
+    try:
+        code = asyncio.run(async_main(args))
+    except KeyboardInterrupt:
+        code = 0
+    sys.exit(code)
+
+
+if __name__ == "__main__":
+    main()

claude_tap/certs.py

@@ -0,0 +1,212 @@
+"""CA and per-host certificate generation for forward proxy TLS termination.
+
+Generates a self-signed CA on first run and creates per-host certificates
+signed by that CA. The CA cert/key are persisted to disk so they survive
+restarts; host certs are cached in memory for the lifetime of the process.
+"""
+
+from __future__ import annotations
+
+import datetime
+import ipaddress
+import logging
+import ssl
+from pathlib import Path
+
+from cryptography import x509
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import rsa
+from cryptography.x509.oid import ExtendedKeyUsageOID, NameOID
+
+log = logging.getLogger("claude-tap")
+
+# Default directory for CA files
+_DEFAULT_CA_DIR = Path.home() / ".claude-tap"
+
+# CA validity: 5 years
+_CA_VALIDITY_DAYS = 5 * 365
+# Host cert validity: 1 year
+_HOST_VALIDITY_DAYS = 365
+
+
+def _generate_key() -> rsa.RSAPrivateKey:
+    return rsa.generate_private_key(public_exponent=65537, key_size=2048)
+
+
+def ensure_ca(ca_dir: Path | None = None) -> tuple[Path, Path]:
+    """Ensure a CA certificate and key exist on disk.
+
+    Returns (ca_cert_path, ca_key_path). Creates them if they don't exist.
+    """
+    ca_dir = ca_dir or _DEFAULT_CA_DIR
+    ca_dir.mkdir(parents=True, exist_ok=True)
+
+    ca_cert_path = ca_dir / "ca.pem"
+    ca_key_path = ca_dir / "ca-key.pem"
+
+    if ca_cert_path.exists() and ca_key_path.exists():
+        # Validate existing files are loadable
+        try:
+            _load_ca(ca_cert_path, ca_key_path)
+            return ca_cert_path, ca_key_path
+        except Exception:
+            log.warning("Existing CA files are invalid, regenerating")
+
+    log.info(f"Generating new CA certificate in {ca_dir}")
+    key = _generate_key()
+    name = x509.Name(
+        [
+            x509.NameAttribute(NameOID.COMMON_NAME, "claude-tap CA"),
+            x509.NameAttribute(NameOID.ORGANIZATION_NAME, "claude-tap"),
+        ]
+    )
+
+    now = datetime.datetime.now(datetime.timezone.utc)
+    cert = (
+        x509.CertificateBuilder()
+        .subject_name(name)
+        .issuer_name(name)
+        .public_key(key.public_key())
+        .serial_number(x509.random_serial_number())
+        .not_valid_before(now)
+        .not_valid_after(now + datetime.timedelta(days=_CA_VALIDITY_DAYS))
+        .add_extension(x509.BasicConstraints(ca=True, path_length=0), critical=True)
+        .add_extension(
+            x509.KeyUsage(
+                digital_signature=True,
+                key_cert_sign=True,
+                crl_sign=True,
+                content_commitment=False,
+                key_encipherment=False,
+                data_encipherment=False,
+                key_agreement=False,
+                encipher_only=False,
+                decipher_only=False,
+            ),
+            critical=True,
+        )
+        .add_extension(
+            x509.SubjectKeyIdentifier.from_public_key(key.public_key()),
+            critical=False,
+        )
+        .sign(key, hashes.SHA256())
+    )
+
+    ca_key_path.write_bytes(
+        key.private_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PrivateFormat.TraditionalOpenSSL,
+            encryption_algorithm=serialization.NoEncryption(),
+        )
+    )
+    # Restrict key file permissions
+    ca_key_path.chmod(0o600)
+
+    ca_cert_path.write_bytes(cert.public_bytes(serialization.Encoding.PEM))
+
+    log.info(f"CA certificate written to {ca_cert_path}")
+    return ca_cert_path, ca_key_path
+
+
+def _load_ca(ca_cert_path: Path, ca_key_path: Path) -> tuple[x509.Certificate, rsa.RSAPrivateKey]:
+    """Load CA cert and key from PEM files."""
+    ca_cert = x509.load_pem_x509_certificate(ca_cert_path.read_bytes())
+    ca_key = serialization.load_pem_private_key(ca_key_path.read_bytes(), password=None)
+    return ca_cert, ca_key  # type: ignore[return-value]
+
+
+class CertificateAuthority:
+    """In-memory CA that generates per-host TLS certificates.
+
+    Caches generated host certs for the lifetime of the process.
+    """
+
+    def __init__(self, ca_cert_path: Path, ca_key_path: Path) -> None:
+        self._ca_cert, self._ca_key = _load_ca(ca_cert_path, ca_key_path)
+        self._host_cache: dict[str, tuple[bytes, bytes]] = {}
+
+    def get_host_cert_pem(self, hostname: str) -> tuple[bytes, bytes]:
+        """Return (cert_pem, key_pem) for the given hostname.
+
+        Generates and caches a new certificate signed by the CA if needed.
+        """
+        if hostname in self._host_cache:
+            return self._host_cache[hostname]
+
+        key = _generate_key()
+        now = datetime.datetime.now(datetime.timezone.utc)
+
+        subject = x509.Name(
+            [
+                x509.NameAttribute(NameOID.COMMON_NAME, hostname),
+            ]
+        )
+
+        # Build SAN: use IPAddress for IP addresses, DNSName for hostnames
+        san_names: list[x509.GeneralName] = []
+        try:
+            ip = ipaddress.ip_address(hostname)
+            san_names.append(x509.IPAddress(ip))
+        except ValueError:
+            san_names.append(x509.DNSName(hostname))
+
+        builder = (
+            x509.CertificateBuilder()
+            .subject_name(subject)
+            .issuer_name(self._ca_cert.subject)
+            .public_key(key.public_key())
+            .serial_number(x509.random_serial_number())
+            .not_valid_before(now)
+            .not_valid_after(now + datetime.timedelta(days=_HOST_VALIDITY_DAYS))
+            .add_extension(
+                x509.SubjectAlternativeName(san_names),
+                critical=False,
+            )
+            .add_extension(
+                x509.ExtendedKeyUsage([ExtendedKeyUsageOID.SERVER_AUTH]),
+                critical=False,
+            )
+            .add_extension(
+                x509.AuthorityKeyIdentifier.from_issuer_public_key(self._ca_key.public_key()),
+                critical=False,
+            )
+            .add_extension(
+                x509.SubjectKeyIdentifier.from_public_key(key.public_key()),
+                critical=False,
+            )
+        )
+
+        cert = builder.sign(self._ca_key, hashes.SHA256())
+
+        cert_pem = cert.public_bytes(serialization.Encoding.PEM)
+        key_pem = key.private_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PrivateFormat.TraditionalOpenSSL,
+            encryption_algorithm=serialization.NoEncryption(),
+        )
+
+        self._host_cache[hostname] = (cert_pem, key_pem)
+        return cert_pem, key_pem
+
+    def make_ssl_context(self, hostname: str) -> ssl.SSLContext:
+        """Create an SSL context for serving TLS as the given hostname."""
+        import tempfile
+
+        cert_pem, key_pem = self.get_host_cert_pem(hostname)
+
+        ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+        # Write cert and key to temp files (ssl module needs file paths)
+        with tempfile.NamedTemporaryFile(suffix=".pem", delete=False) as cf:
+            cf.write(cert_pem)
+            cert_path = cf.name
+        with tempfile.NamedTemporaryFile(suffix=".pem", delete=False) as kf:
+            kf.write(key_pem)
+            key_path = kf.name
+
+        try:
+            ctx.load_cert_chain(cert_path, key_path)
+        finally:
+            Path(cert_path).unlink(missing_ok=True)
+            Path(key_path).unlink(missing_ok=True)
+
+        return ctx

claude_tap/claw_session.py

@@ -0,0 +1,42 @@
+"""Claw session ID extraction and normalization for multi-session traces."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from collections.abc import Mapping
+
+# Header clients send to route traces; stripped before forwarding upstream.
+CLAW_SESSION_HEADER = "claw-session-id"
+
+_MAX_SLUG_LEN = 48
+
+
+def extract_claw_session_id(headers: Mapping[str, str]) -> str | None:
+    """Return the claw session id from headers, or ``None`` if absent or blank (no tracing)."""
+    for key, value in headers.items():
+        if key.lower() == CLAW_SESSION_HEADER:
+            if isinstance(value, str):
+                stripped = value.strip()
+                return stripped if stripped else None
+            return None
+    return None
+
+
+def strip_claw_session_header(headers: dict[str, str]) -> None:
+    """Remove claw-session-id from a mutable header dict (any key casing)."""
+    to_drop = [k for k in list(headers.keys()) if k.lower() == CLAW_SESSION_HEADER]
+    for k in to_drop:
+        del headers[k]
+
+
+def sanitize_filename_suffix(raw: str) -> str:
+    """Map a session id to a short filesystem-safe component (may truncate)."""
+    compact = re.sub(r"[^a-zA-Z0-9._-]+", "_", raw.strip()).strip("._-")
+    if not compact:
+        compact = "session"
+    if len(compact) > _MAX_SLUG_LEN:
+        digest = hashlib.sha256(raw.encode("utf-8")).hexdigest()[:12]
+        head = compact[: max(8, _MAX_SLUG_LEN - 13)]
+        compact = f"{head}_{digest}"
+    return compact