tailkitty 0.1.0__py3-none-win_amd64.whl

tailkitty/__init__.py

@@ -0,0 +1,40 @@
+"""Tailkitty Python tooling for Tailcat."""
+
+from .constants import TAILKITTY_VERSION
+
+__version__ = TAILKITTY_VERSION
+
+from .backend import BackendInfo, inspect_backend, run
+from .bundle import BundleError, BundleManifest
+from .client import AsyncClient, Client
+from .derp import DerpMapCache, DerpMapError
+from .destination import DestinationError, resolve_destination, resolve_destination_async
+from .diagnostics import diagnostics
+from .process import AsyncServerProcess, ServerProcess, run_async, send
+from .token import ConnInfo, DerpNode, DerpRegion, TokenError, parse_token, resolve_token
+
+__all__ = [
+    "AsyncClient",
+    "AsyncServerProcess",
+    "BackendInfo",
+    "BundleError",
+    "BundleManifest",
+    "Client",
+    "ConnInfo",
+    "DerpMapCache",
+    "DerpMapError",
+    "DerpNode",
+    "DerpRegion",
+    "DestinationError",
+    "ServerProcess",
+    "TokenError",
+    "diagnostics",
+    "inspect_backend",
+    "parse_token",
+    "resolve_destination",
+    "resolve_destination_async",
+    "resolve_token",
+    "run",
+    "run_async",
+    "send",
+]

tailkitty/__main__.py

@@ -0,0 +1,5 @@
+"""Support ``python -m tailkitty``."""
+
+from .cli import main
+
+raise SystemExit(main())

tailkitty/backend.py

@@ -0,0 +1,107 @@
+"""Discovery and execution of Tailcat's Go data-plane helper."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, NoReturn
+
+from .bundle import BundleError, BundleManifest, verify_bundle
+
+
+class BackendNotFound(RuntimeError):
+    """No usable Tailcat data-plane executable was found."""
+
+
+@dataclass(frozen=True, slots=True)
+class BackendInfo:
+    path: Path
+    source: str
+    manifest: BundleManifest | None = None
+
+
+def project_backend() -> Path:
+    return Path(__file__).resolve().parents[2] / ".tools" / "bin" / "tailcat"
+
+
+def inspect_backend() -> BackendInfo:
+    configured = os.environ.get("TAILKITTY_BACKEND")
+    if configured:
+        path = Path(configured).expanduser().resolve()
+        if _is_executable(path):
+            return BackendInfo(path, "environment")
+        raise BackendNotFound(f"TAILKITTY_BACKEND is not executable: {path}")
+    bundle = verify_bundle()
+    if bundle is not None:
+        return BackendInfo(bundle.executable, "bundle", bundle.manifest)
+    development = project_backend()
+    if _is_executable(development):
+        return BackendInfo(development, "development")
+    legacy_development = development.with_name("tailcat-go")
+    if _is_executable(legacy_development):
+        return BackendInfo(legacy_development, "development")
+    if candidate := shutil.which("tailcat-go"):
+        return BackendInfo(Path(candidate).resolve(), "path")
+    raise BackendNotFound(
+        "Tailcat data-plane backend is not installed. Run `mise run backend`, "
+        "or set TAILKITTY_BACKEND to an upstream tailcat executable."
+    )
+
+
+def _is_executable(path: Path) -> bool:
+    return path.is_file() and (os.name == "nt" or os.access(path, os.X_OK))
+
+
+def find_backend() -> str:
+    try:
+        return str(inspect_backend().path)
+    except BundleError as exc:
+        raise BackendNotFound(f"bundled Tailcat executable failed integrity checks: {exc}") from exc
+
+
+def exec_backend(arguments: Sequence[str]) -> NoReturn:
+    backend = find_backend()
+    if os.name == "posix":
+        os.execv(backend, [backend, *arguments])
+    completed = subprocess.run([backend, *arguments], check=False)
+    raise SystemExit(completed.returncode)
+
+
+def backend_version() -> str:
+    info = inspect_backend()
+    if info.manifest is not None:
+        return info.manifest.tailcat_version
+    return "unknown (external executable)"
+
+
+def run(
+    arguments: Sequence[str],
+    *,
+    input: str | bytes | None = None,
+    capture_output: bool = False,
+    text: bool | None = None,
+    check: bool = False,
+    timeout: float | None = None,
+    **kwargs: Any,
+) -> subprocess.CompletedProcess[Any]:
+    """Run an upstream-compatible Tailcat command.
+
+    This deliberately follows :func:`subprocess.run` conventions. ``text`` is
+    inferred from the input type when omitted, avoiding the common bytes/text
+    mismatch in thin process wrappers.
+    """
+    if text is None:
+        text = not isinstance(input, bytes)
+    return subprocess.run(
+        [find_backend(), *arguments],
+        input=input,
+        capture_output=capture_output,
+        text=text,
+        check=check,
+        timeout=timeout,
+        **kwargs,
+    )

tailkitty/bin/manifest.json

@@ -0,0 +1,17 @@
+{
+  "cgo_enabled": false,
+  "filename": "tailcat.exe",
+  "go_version": "go version go1.26.5 darwin/arm64",
+  "reproducible_flags": [
+    "-trimpath",
+    "-buildvcs=false",
+    "-ldflags=-s -w -buildid="
+  ],
+  "schema": 1,
+  "sha256": "17d06a87f24dc9f579c2beff0c6cdf923c70699714f30ceffcf3463894f64dab",
+  "size": 20491264,
+  "tailcat_module": "github.com/tailscale/tailcat",
+  "tailcat_version": "v0.0.0-20260828194103-53845983d15e",
+  "target": "windows-x86_64",
+  "wheel_platform": "win_amd64"
+}

tailkitty/bundle.py

@@ -0,0 +1,139 @@
+"""Integrity validation for an executable embedded in a Tailkitty platform wheel."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import platform
+import stat
+import sys
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+from .constants import TAILCAT_MODULE, TAILCAT_VERSION
+
+
+class BundleError(RuntimeError):
+    """A bundled executable or its manifest is missing or invalid."""
+
+
+MAX_BUNDLE_SIZE = 100 * 1024 * 1024
+
+
+@dataclass(frozen=True, slots=True)
+class BundleManifest:
+    schema: int
+    target: str
+    wheel_platform: str
+    filename: str
+    sha256: str
+    size: int
+    tailcat_module: str
+    tailcat_version: str
+    go_version: str
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> BundleManifest:
+        try:
+            manifest = cls(
+                schema=int(value["schema"]),
+                target=str(value["target"]),
+                wheel_platform=str(value["wheel_platform"]),
+                filename=str(value["filename"]),
+                sha256=str(value["sha256"]),
+                size=int(value["size"]),
+                tailcat_module=str(value["tailcat_module"]),
+                tailcat_version=str(value["tailcat_version"]),
+                go_version=str(value["go_version"]),
+            )
+        except (KeyError, TypeError, ValueError) as exc:
+            raise BundleError(f"invalid bundle manifest: {exc}") from exc
+        if manifest.schema != 1:
+            raise BundleError(f"unsupported bundle manifest schema {manifest.schema}")
+        if manifest.tailcat_version != TAILCAT_VERSION:
+            raise BundleError(
+                f"bundle contains Tailcat {manifest.tailcat_version}, expected {TAILCAT_VERSION}"
+            )
+        if manifest.tailcat_module != TAILCAT_MODULE:
+            raise BundleError(f"bundle contains unexpected module {manifest.tailcat_module!r}")
+        if Path(manifest.filename).name != manifest.filename:
+            raise BundleError("bundle manifest filename must not contain a path")
+        if len(manifest.sha256) != 64 or any(
+            character not in "0123456789abcdef" for character in manifest.sha256
+        ):
+            raise BundleError("bundle manifest contains an invalid SHA-256 digest")
+        if manifest.size <= 0 or manifest.size > MAX_BUNDLE_SIZE:
+            raise BundleError("bundle manifest contains an invalid executable size")
+        return manifest
+
+
+@dataclass(frozen=True, slots=True)
+class VerifiedBundle:
+    executable: Path
+    manifest: BundleManifest
+
+
+def runtime_target() -> str:
+    """Return the bundle target name compatible with this interpreter."""
+    system = {"darwin": "macos", "linux": "linux", "win32": "windows"}.get(sys.platform)
+    machine = platform.machine().lower()
+    architecture = {
+        "amd64": "x86_64",
+        "x86_64": "x86_64",
+        "arm64": "arm64",
+        "aarch64": "aarch64" if system == "linux" else "arm64",
+    }.get(machine)
+    if system is None or architecture is None:
+        raise BundleError(f"unsupported runtime platform: {sys.platform}/{platform.machine()}")
+    return f"{system}-{architecture}"
+
+
+def bundle_directory() -> Path:
+    return Path(__file__).resolve().parent / "bin"
+
+
+def _sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+@lru_cache(maxsize=4)
+def verify_bundle(directory: Path | None = None) -> VerifiedBundle | None:
+    root = directory or bundle_directory()
+    manifest_path = root / "manifest.json"
+    if not manifest_path.exists():
+        return None
+    try:
+        raw = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise BundleError(f"cannot read bundle manifest: {exc}") from exc
+    if not isinstance(raw, dict):
+        raise BundleError("bundle manifest must contain a JSON object")
+    manifest = BundleManifest.from_dict(raw)
+    expected_target = runtime_target()
+    if manifest.target != expected_target:
+        raise BundleError(
+            f"bundle target {manifest.target!r} is incompatible with runtime {expected_target!r}"
+        )
+    executable = root / manifest.filename
+    if executable.is_symlink():
+        raise BundleError("bundled executable must not be a symbolic link")
+    if not executable.is_file():
+        raise BundleError(f"bundled executable is missing: {executable}")
+    if executable.stat().st_size != manifest.size:
+        raise BundleError("bundled executable size does not match its manifest")
+    if _sha256(executable) != manifest.sha256:
+        raise BundleError("bundled executable checksum does not match its manifest")
+    if os.name != "nt" and not os.access(executable, os.X_OK):
+        executable.chmod(executable.stat().st_mode | stat.S_IXUSR)
+    return VerifiedBundle(executable, manifest)
+
+
+def clear_bundle_cache() -> None:
+    verify_bundle.cache_clear()

tailkitty/cli.py

@@ -0,0 +1,82 @@
+"""Tailkitty command-line entry point."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import __version__
+from .backend import BackendNotFound, exec_backend
+from .bundle import BundleError
+from .derp import DEFAULT_DERP_MAP_URL
+from .destination import DestinationError, resolve_destination
+from .diagnostics import diagnostics
+from .token import TokenError, parse_token, resolve_token
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="tailkitty",
+        description="Tailkitty: Python tooling with an upstream-compatible Tailcat data plane",
+        epilog=(
+            "Streaming, port serving, ping, SOCKS, SSH, and key commands are passed "
+            "unchanged to the bundled data-plane helper."
+        ),
+    )
+    parser.add_argument("--version", action="version", version=f"tailkitty {__version__}")
+    commands = parser.add_subparsers(dest="command")
+    parse = commands.add_parser("parse", help="decode a Tailcat connection token in Python")
+    parse.add_argument("token")
+    resolve = commands.add_parser("resolve", help="embed DERP relay details in a token")
+    resolve.add_argument("token")
+    resolve.add_argument("--derpmap-url", default=DEFAULT_DERP_MAP_URL)
+    doctor = commands.add_parser("doctor", help="show environment and backend diagnostics")
+    doctor.add_argument("--json", action="store_true", dest="as_json")
+    return parser
+
+
+def main(arguments: list[str] | None = None) -> int:
+    args = list(sys.argv[1:] if arguments is None else arguments)
+    # Keep the upstream CLI surface intact. Only Python-native commands are
+    # parsed here; everything else (including no arguments) is passed through.
+    if not args or args[0] not in {"parse", "resolve", "doctor", "--version", "-h", "--help"}:
+        try:
+            exec_backend(args)
+        except BackendNotFound as exc:
+            print(f"tailkitty: {exc}", file=sys.stderr)
+            return 127
+
+    parser = _parser()
+    namespace = parser.parse_args(args)
+    try:
+        if namespace.command == "parse":
+            info = parse_token(resolve_destination(namespace.token))
+            print(json.dumps(info.to_display_dict(raw=True), indent=4))
+            return 0
+        if namespace.command == "resolve":
+            token = resolve_destination(namespace.token)
+            print(resolve_token(token, derp_map_url=namespace.derpmap_url))
+            return 0
+        if namespace.command == "doctor":
+            report = diagnostics()
+            if namespace.as_json:
+                print(json.dumps(report, indent=2, sort_keys=True))
+            else:
+                print(f"tailkitty {report['tailkitty_version']}")
+                print(f"Python {report['python_version']} ({report['machine']})")
+                print(
+                    f"data-plane backend: {report['backend']['path']} "
+                    f"[{report['backend']['source']}]"
+                )
+                if bundle := report["backend"].get("bundle"):
+                    print(f"Tailcat {bundle['tailcat_version']} ({bundle['target']}, verified)")
+            return 0
+    except (TokenError, DestinationError, BackendNotFound, BundleError) as exc:
+        parser.error(str(exc))
+    parser.print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tailkitty/client.py

@@ -0,0 +1,150 @@
+"""High-level synchronous and asynchronous Tailcat clients."""
+
+from __future__ import annotations
+
+import asyncio
+import subprocess
+from typing import Self
+
+from .backend import find_backend
+from .destination import resolve_destination, resolve_destination_async
+
+
+def _port_argument(port: int) -> list[str]:
+    if not 0 <= port <= 65535:
+        raise ValueError(f"port must be between 0 and 65535, got {port}")
+    return [] if port == 0 else [str(port)]
+
+
+class Client:
+    """A reusable Tailcat destination with process and request helpers."""
+
+    def __init__(self, destination: str, *, dns_timeout: float = 5.0) -> None:
+        self.destination = destination
+        self.dns_timeout = dns_timeout
+        self._token: str | None = None
+
+    @property
+    def token(self) -> str:
+        if self._token is None:
+            self._token = resolve_destination(self.destination, timeout=self.dns_timeout)
+        return self._token
+
+    def connect(
+        self,
+        port: int = 0,
+        *,
+        stdin: int = subprocess.PIPE,
+        stdout: int = subprocess.PIPE,
+        stderr: int = subprocess.PIPE,
+    ) -> subprocess.Popen[bytes]:
+        """Start a streaming connection and return its process handles."""
+        return subprocess.Popen(
+            [find_backend(), self.token, *_port_argument(port)],
+            stdin=stdin,
+            stdout=stdout,
+            stderr=stderr,
+        )
+
+    def request(
+        self,
+        data: str | bytes = b"",
+        *,
+        port: int = 0,
+        timeout: float | None = None,
+    ) -> bytes:
+        """Send a finite payload, close stdin, and return response bytes."""
+        return self.run(data, port=port, timeout=timeout, check=True).stdout
+
+    def run(
+        self,
+        data: str | bytes = b"",
+        *,
+        port: int = 0,
+        timeout: float | None = None,
+        check: bool = False,
+    ) -> subprocess.CompletedProcess[bytes]:
+        """Run a finite exchange and retain status, stdout, and stderr."""
+        payload = data.encode() if isinstance(data, str) else data
+        return subprocess.run(
+            [find_backend(), self.token, *_port_argument(port)],
+            input=payload,
+            capture_output=True,
+            check=check,
+            timeout=timeout,
+        )
+
+    def refresh(self) -> Self:
+        """Discard a cached DNS result so the next operation resolves it again."""
+        self._token = None
+        return self
+
+
+class AsyncClient:
+    """Asyncio Tailcat client."""
+
+    def __init__(self, destination: str, *, dns_timeout: float = 5.0) -> None:
+        self.destination = destination
+        self.dns_timeout = dns_timeout
+        self._token: str | None = None
+
+    async def resolve(self) -> str:
+        if self._token is None:
+            self._token = await resolve_destination_async(
+                self.destination, timeout=self.dns_timeout
+            )
+        return self._token
+
+    async def connect(self, port: int = 0) -> asyncio.subprocess.Process:
+        token = await self.resolve()
+        return await asyncio.create_subprocess_exec(
+            find_backend(),
+            token,
+            *_port_argument(port),
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+
+    async def request(
+        self,
+        data: str | bytes = b"",
+        *,
+        port: int = 0,
+        timeout: float | None = None,
+    ) -> bytes:
+        """Send a finite payload and return response bytes."""
+        return (await self.run(data, port=port, timeout=timeout, check=True)).stdout
+
+    async def run(
+        self,
+        data: str | bytes = b"",
+        *,
+        port: int = 0,
+        timeout: float | None = None,
+        check: bool = False,
+    ) -> subprocess.CompletedProcess[bytes]:
+        """Async finite exchange retaining status, stdout, and stderr."""
+        payload = data.encode() if isinstance(data, str) else data
+        backend = find_backend()
+        token = await self.resolve()
+        command = [backend, token, *_port_argument(port)]
+        process = await asyncio.create_subprocess_exec(
+            *command,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        try:
+            stdout, stderr = await asyncio.wait_for(process.communicate(payload), timeout=timeout)
+        except (TimeoutError, asyncio.CancelledError):
+            process.kill()
+            await process.wait()
+            raise
+        if check and process.returncode:
+            raise subprocess.CalledProcessError(process.returncode, command, stdout, stderr)
+        return subprocess.CompletedProcess(command, process.returncode or 0, stdout, stderr)
+
+    def refresh(self) -> Self:
+        self._token = None
+        return self

tailkitty/constants.py

@@ -0,0 +1,7 @@
+"""Version pins shared by Tailkitty runtime diagnostics and build tooling."""
+
+TAILKITTY_VERSION = "0.1.0"
+GO_VERSION = "1.26.5"
+TAILCAT_MODULE = "github.com/tailscale/tailcat"
+TAILCAT_VERSION = "v0.0.0-20260828194103-53845983d15e"
+TAILCAT_COMMAND = f"{TAILCAT_MODULE}/cmd/tailcat"