tailkitty 0.1.0__tar.gz

tailkitty-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+.cache/
+.tools/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.coverage
+dist/
+src/tailkitty/bin/tailcat
+src/tailkitty/bin/tailcat.exe
+src/tailkitty/bin/manifest.json

tailkitty-0.1.0/.mise.toml

@@ -0,0 +1,60 @@
+[tools]
+python = "3.13.11"
+go = "1.26.5"
+uv = "0.12.7"
+
+[env]
+UV_CACHE_DIR = "{{config_root}}/.cache/uv"
+
+[tasks.setup]
+description = "Install Python dependencies and the interoperable Tailcat backend"
+run = [
+  "uv sync --all-groups",
+  "mise run backend",
+]
+
+[tasks.backend]
+description = "Build the upstream Tailcat data-plane helper"
+run = "uv run python -m scripts.build_binary build --output .tools/bin"
+
+[tasks.bundle]
+description = "Build a bundled executable for the host platform"
+run = "uv run python -m scripts.build_binary build --target host --output src/tailkitty/bin"
+
+[tasks.bundle-verify]
+description = "Verify the bundled executable and integrity manifest"
+run = "uv run python -m scripts.build_binary verify --output src/tailkitty/bin"
+
+[tasks.bundle-clean]
+description = "Remove generated bundled executable files"
+run = "uv run python -m scripts.build_binary clean --output src/tailkitty/bin"
+
+[tasks.wheel]
+description = "Build a platform wheel containing the host executable"
+depends = ["bundle", "bundle-verify"]
+run = "uv build --wheel"
+
+[tasks.wheels]
+description = "Build and verify all supported platform wheels"
+run = "uv run python -m scripts.build_wheels"
+
+[tasks.wheel-smoke]
+description = "Install and inspect the bundled host wheel in an isolated environment"
+run = "uv run python -m scripts.smoke_wheel"
+
+[tasks.test]
+description = "Run the Python test suite"
+run = [
+  "uv run ruff check src tests scripts hatch_build.py",
+  "uv run ruff format --check src tests scripts hatch_build.py",
+  "uv run mypy src scripts",
+  "uv run pytest",
+]
+
+[tasks.tailkitty]
+description = "Run Tailkitty"
+run = "uv run tailkitty"
+
+[tasks.tailcat]
+description = "Run Tailkitty through its Tailcat-compatible alias"
+run = "uv run tailcat"

tailkitty-0.1.0/.python-version

@@ -0,0 +1,2 @@
+3.13.11
+

tailkitty-0.1.0/AGENTS.md

@@ -0,0 +1,167 @@
+# Repository instructions for coding agents
+
+These instructions apply to the entire repository. They supplement the user request; they do not
+override it.
+
+## Start here
+
+Read these files before making architectural, packaging, security, or release changes:
+
+1. `README.md` for the product boundary and public behavior.
+2. `SECURITY.md` for executable trust and authorization concerns.
+3. `BUILDING.md` for the reproducible bundle and wheel pipeline.
+4. `pyproject.toml` and `.mise.toml` for supported versions and canonical tasks.
+
+Do not confuse Tailkitty with the separate `pytailcat` distribution on PyPI. This checkout is the
+source of truth for Tailkitty; upstream Tailcat remains the data-plane source of truth.
+
+## Architecture and non-negotiable boundaries
+
+The project intentionally has two layers:
+
+- The control plane is Python: token encoding/decoding, validation, DNS TXT lookup, DERP-map
+  resolution/cache, typed clients, diagnostics, and process lifecycle.
+- The network data plane is the pinned upstream Go Tailcat executable: magicsock, userspace
+  WireGuard, DERP transport, and gVisor netstack.
+
+Do not replace the data plane with a Python-only protocol that interoperates only with itself. Do
+not silently fall back from a corrupt bundled executable to an unverified backend. Wire
+compatibility and fail-closed bundle discovery are core requirements.
+
+## Repository map
+
+| Path | Responsibility |
+| --- | --- |
+| `src/tailkitty/token.py` | Tailcat CBOR/base64url wire format and DERP embedding |
+| `src/tailkitty/destination.py` | Literal-token and DNS TXT destination resolution |
+| `src/tailkitty/derp.py` | Validated, bounded, atomic DERP-map caching |
+| `src/tailkitty/backend.py` | Backend precedence and command execution |
+| `src/tailkitty/bundle.py` | Runtime manifest and executable integrity checks |
+| `src/tailkitty/client.py` | Sync and asyncio client APIs |
+| `src/tailkitty/process.py` | Managed server processes and low-level async execution |
+| `src/tailkitty/cli.py` | Python-native commands and upstream pass-through |
+| `src/tailkitty/constants.py` | Package, Go, module, and upstream Tailcat pins |
+| `scripts/targets.py` | Supported build targets and wheel tags |
+| `scripts/build_binary.py` | Reproducible cross-compilation and manifest creation |
+| `scripts/build_wheels.py` | Isolated five-target wheel orchestration |
+| `scripts/verify_wheel.py` | Wheel metadata, archive, binary, and RECORD verification |
+| `hatch_build.py` | Platform-wheel build hook |
+| `tests/` | Unit and subprocess behavior tests |
+
+Public imports are curated in `src/tailkitty/__init__.py`. Adding a public API requires updating
+that file, type annotations, tests, and README documentation.
+
+## Environment and canonical commands
+
+Use mise and uv; do not introduce a parallel virtualenv, dependency manager, or ad hoc Go version.
+
+```console
+mise install
+uv sync --all-groups --locked
+mise run test
+```
+
+`mise run test` is the required local quality gate. It runs Ruff linting, Ruff formatting checks,
+strict mypy, and pytest. During iteration, run the narrowest relevant test first, then run the full
+gate before declaring completion.
+
+Packaging changes also require:
+
+```console
+mise run bundle
+mise run bundle-verify
+mise run wheels
+uv run python -m scripts.smoke_wheel dist/wheels/<host-wheel>.whl
+```
+
+For Python-version compatibility changes, test the minimum version:
+
+```console
+uv run --isolated --python 3.11 --all-groups pytest
+```
+
+Public DERP relays are external and can be unavailable or rate-limited. Keep unit tests deterministic
+and do not make the default test suite depend on a live relay. Report live integration timeouts
+honestly rather than treating them as proof of a local regression or success.
+
+## Version and build invariants
+
+- `TAILKITTY_VERSION` must match `[project].version` in `pyproject.toml`.
+- `GO_VERSION` must match `[tools].go` in `.mise.toml` exactly.
+- `TAILCAT_VERSION` must remain an immutable upstream version or pseudo-version.
+- Bundle builds must use the exact Go toolchain with `GOTOOLCHAIN=local`.
+- Keep `CGO_ENABLED=0`, `-trimpath`, `-buildvcs=false`, the empty build ID, stripped symbols, and
+  baseline CPU feature levels unless a documented compatibility decision changes them.
+- Every platform wheel must be non-pure and tagged for exactly one supported target.
+- Source distributions and pure-Python fallback wheels must contain no generated executable or
+  bundle manifest.
+- Do not invent a platform tag. Update `scripts/targets.py`, build validation, CI, tests, and docs as
+  one change when adding a target.
+
+## Backend and security invariants
+
+Backend priority is:
+
+1. `TAILKITTY_BACKEND`, which must be executable or fail immediately.
+2. A verified, runtime-compatible bundled executable.
+3. `.tools/bin/tailcat`, followed by the legacy `.tools/bin/tailcat-go` path.
+4. `tailcat-go` on `PATH`.
+
+Preserve these behaviors:
+
+- A present but invalid bundle is an integrity error; it must not trigger fallback.
+- Manifest filenames cannot contain paths, and bundled executables cannot be symlinks.
+- Runtime checks cover schema, module, revision, platform, size, and SHA-256.
+- `allow=None` preserves upstream's allow-all behavior; `allow=[]` must become `--allow=none`.
+- Timeout and cancellation paths must terminate and reap child processes.
+- Cache files remain bounded, private, atomically replaced, and safe to use stale after refresh
+  failure.
+- Never log saved private keys or embed real active connection addresses in fixtures or docs.
+
+## CLI compatibility
+
+The Python CLI owns only `parse`, `resolve`, `doctor`, `--version`, and top-level help. All other
+argument sequences must pass unchanged to the upstream executable, including no arguments.
+
+When changing command dispatch, test both the Python-native commands and an arbitrary upstream
+argument sequence. Do not add a Python subcommand whose name silently shadows an upstream command
+without an explicit compatibility decision.
+
+## Code and test conventions
+
+- Support Python 3.11 and newer.
+- Keep complete annotations and strict-mypy compatibility.
+- Prefer standard-library types and small typed dataclasses over untyped dictionaries at public
+  boundaries.
+- Keep synchronous and asyncio behavior aligned, especially timeout, cancellation, and cleanup.
+- Validate external input early with domain-specific exceptions (`TokenError`, `DestinationError`,
+  `DerpMapError`, `BundleError`, or `BackendNotFound`).
+- Add regression tests for bug fixes. Avoid weakening a safety check merely to satisfy a fixture.
+- Use temporary directories in tests; never depend on or overwrite a developer's saved Tailcat
+  keys, cache, bundle, or configured backend.
+- Keep Ruff's 100-character line length and run formatting rather than hand-aligning code.
+
+## Generated files and release safety
+
+Do not manually edit or commit generated files under:
+
+- `src/tailkitty/bin/`
+- `dist/`
+- `.tools/bin/`
+- cache, virtualenv, or `__pycache__` directories
+
+Use the scripts and mise tasks that own those artifacts. Publish only the `tailkitty` distribution;
+the `pytailcat` name belongs to another project. Before a release, verify project URLs and the `pypi`
+GitHub environment, build all five wheels plus the source distribution, smoke-test the host wheel,
+and retain checksums and provenance attestations.
+
+## Definition of done
+
+A change is complete when:
+
+1. The implementation respects the Python/native boundary and security invariants.
+2. Focused regression tests cover new behavior or the repaired failure.
+3. Public behavior and types are documented where users will find them.
+4. `mise run test` passes.
+5. Packaging changes pass the full wheel matrix and host installation smoke test.
+6. Remaining external limitations or unverified assumptions are stated explicitly.

tailkitty-0.1.0/BUILDING.md

@@ -0,0 +1,42 @@
+# Building bundled wheels
+
+The environment is fully pinned by mise: Python 3.13.11, Go 1.26.5, and uv 0.12.7.
+
+```console
+mise install
+uv sync --all-groups --locked
+mise run test
+mise run wheels
+```
+
+`mise run wheels` cross-compiles the exact Tailcat revision in `constants.py` for five targets,
+stages each executable separately, builds a correctly tagged non-pure wheel, and verifies its
+archive paths, executable format, bundle digest, and every wheel `RECORD` entry. Build inputs use
+`CGO_ENABLED=0`, `-trimpath`, no VCS metadata, no Go build ID, baseline CPU levels, and the exact
+mise-managed Go compiler. Dependency downloads receive bounded retries for transient CI failures.
+
+Build one target with:
+
+```console
+uv run python -m scripts.build_wheels --target linux-x86_64 --output dist/wheels
+```
+
+Install-test the wheel matching the current host with:
+
+```console
+uv run python -m scripts.smoke_wheel path/to/tailkitty-*.whl
+```
+
+The wheel matrix is:
+
+| Build target | Wheel platform tag | Executable |
+| --- | --- | --- |
+| `macos-arm64` | `macosx_12_0_arm64` | Mach-O |
+| `macos-x86_64` | `macosx_12_0_x86_64` | Mach-O |
+| `linux-x86_64` | `manylinux_2_17_x86_64` | ELF |
+| `linux-aarch64` | `manylinux_2_17_aarch64` | ELF |
+| `windows-x86_64` | `win_amd64` | PE |
+
+The release workflow rebuilds the matrix, creates a binary-free source distribution, generates
+checksums, creates GitHub build-provenance attestations, and uses PyPI trusted publishing. Configure
+the `pypi` GitHub environment before enabling it.

tailkitty-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0 - unreleased
+
+- Launch under the Tailkitty distribution, import, and primary CLI name.
+- Implement Tailcat token parsing, validation, resolution, DNS destination lookup, and DERP caching
+  in Python.
+- Add typed synchronous and asyncio client/server process APIs.
+- Bundle a pinned upstream data plane in verified wheels for five desktop/server targets.
+- Add structured backend diagnostics, reproducible builds, artifact verification, isolated wheel
+  smoke tests, CI, release provenance, and trusted-publishing automation.

tailkitty-0.1.0/COMPARISON.md

@@ -0,0 +1,22 @@
+# Tailkitty compared with the existing PyPI project
+
+Both projects expose the upstream Tailcat command through Python and use an upstream-compatible
+native data plane. The existing [`pytailcat`](https://pypi.org/project/pytailcat/) primarily ships
+prebuilt executables with a small process wrapper. This implementation adds substantial Python-side
+functionality and a more inspectable supply chain under the distinct Tailkitty name.
+
+| Capability | Existing PyPI project | This implementation |
+| --- | --- | --- |
+| Upstream-compatible data plane | Bundled executable | Pinned, verified bundled executable |
+| Token parsing and validation | Delegated to executable | Native Python typed models |
+| DERP resolution and caching | Delegated to executable | Native Python with ETag/stale fallback |
+| DNS `tailcat=` destination lookup | Delegated to executable | Sync and async Python APIs |
+| Process API | Thin synchronous wrapper | Sync/async clients and managed servers |
+| Bundle integrity | Package-manager transport integrity | Runtime manifest, target, size, and SHA-256 checks |
+| Reproducible local toolchain | Not the focus | mise + uv + exact Go compiler and revision |
+| Release evidence | Prebuilt wheels | Matrix verification, checksums, and provenance workflow |
+
+The remaining architectural boundary is intentional: reimplementing Tailscale magicsock,
+userspace WireGuard, DERP routing, and gVisor netstack faithfully in pure Python would be a separate
+networking stack and would create interoperability and security risk. The control-plane and wire
+format are Python; the interoperable encrypted transport stays upstream.

tailkitty-0.1.0/ITERATIONS.md

@@ -0,0 +1,135 @@
+# 100-iteration improvement ledger
+
+Each checkbox is a distinct implementation, hardening, verification, or documentation pass. Items
+are marked only after their stated evidence exists.
+
+## 001-010 — reproducible environment
+
+- [x] 001. Update and pin uv to 0.12.7 with mise.
+- [x] 002. Pin Python 3.13.11 with mise.
+- [x] 003. Pin Go 1.26.5 with mise.
+- [x] 004. Keep the virtual environment driven by uv.
+- [x] 005. Lock all Python runtime dependencies.
+- [x] 006. Lock all Python development dependencies.
+- [x] 007. Add a one-command mise setup task.
+- [x] 008. Add a locked CI dependency-sync step.
+- [x] 009. Move package, Tailcat, and Go pins into central constants.
+- [x] 010. Test that project metadata and runtime versions agree.
+
+## 011-020 — Python-native control plane
+
+- [x] 011. Decode Tailcat CBOR tokens in Python.
+- [x] 012. Model connection data with typed dataclasses.
+- [x] 013. Validate token prefixes and base64 payloads.
+- [x] 014. Validate node-key length and structure.
+- [x] 015. Validate DERP region fields.
+- [x] 016. Re-encode resolved Tailcat tokens in Python.
+- [x] 017. Resolve DERP maps without invoking Go.
+- [x] 018. Cache DERP maps on disk with a bounded lifetime.
+- [x] 019. Revalidate DERP caches with HTTP ETags.
+- [x] 020. Fall back to stale DERP data during network failure.
+
+## 021-030 — Python APIs and process safety
+
+- [x] 021. Resolve DNS `tailcat=` TXT destinations synchronously.
+- [x] 022. Resolve DNS destinations asynchronously.
+- [x] 023. Add a typed synchronous client.
+- [x] 024. Add an asyncio client.
+- [x] 025. Add a managed synchronous server process.
+- [x] 026. Add a managed asyncio server process.
+- [x] 027. Capture server readiness without blocking stdout.
+- [x] 028. Clean up forgotten child processes at interpreter shutdown.
+- [x] 029. Preserve exit status and stderr for non-raising calls.
+- [x] 030. Translate an empty allow-list to the secure `--allow=none` value.
+
+## 031-040 — pinned binary construction
+
+- [x] 031. Pin the exact upstream Tailcat pseudo-version.
+- [x] 032. Fetch the command package rather than an ambiguous module root.
+- [x] 033. Build inside an isolated temporary Go module.
+- [x] 034. Disable CGO for portable cross-compilation.
+- [x] 035. Strip source paths with `-trimpath`.
+- [x] 036. Disable VCS stamping.
+- [x] 037. Remove the Go build ID.
+- [x] 038. Strip symbols and debug tables.
+- [x] 039. Set baseline amd64 and arm64 CPU levels.
+- [x] 040. Retry transient module-download failures with a bounded backoff.
+
+## 041-050 — target matrix and build safety
+
+- [x] 041. Model build targets with immutable typed records.
+- [x] 042. Support macOS arm64.
+- [x] 043. Support macOS x86-64.
+- [x] 044. Support Linux x86-64.
+- [x] 045. Support Linux arm64.
+- [x] 046. Support Windows x86-64.
+- [x] 047. Normalize common machine-architecture aliases.
+- [x] 048. Detect and reject unsupported build hosts.
+- [x] 049. Validate Mach-O, ELF, and PE executable headers.
+- [x] 050. Replace completed binaries atomically and remove stale opposite-OS files.
+
+## 051-060 — platform-wheel packaging
+
+- [x] 051. Migrate to Hatchling for a programmable wheel hook.
+- [x] 052. Mark binary wheels as non-pure.
+- [x] 053. Emit exact Python/ABI/platform wheel tags.
+- [x] 054. Use a correct macOS 12 deployment floor.
+- [x] 055. Use conservative manylinux 2.17 Linux tags.
+- [x] 056. Force-include only the selected staged executable.
+- [x] 057. Force-include its matching integrity manifest.
+- [x] 058. Reject a caller-supplied tag that disagrees with the bundle.
+- [x] 059. Keep generated binaries out of source distributions.
+- [x] 060. Retain a pure-Python wheel fallback when no bundle is staged.
+
+## 061-070 — runtime integrity and discovery
+
+- [x] 061. Define a versioned JSON bundle-manifest schema.
+- [x] 062. Record target, platform tag, module, revision, compiler, size, and SHA-256.
+- [x] 063. Reject unsupported manifest schemas.
+- [x] 064. Reject module or upstream-version mismatches.
+- [x] 065. Reject path traversal and symlinked executables.
+- [x] 066. Reject invalid digests and implausible bundle sizes.
+- [x] 067. Recompute size and SHA-256 before execution.
+- [x] 068. Reject a valid bundle copied to an incompatible runtime platform.
+- [x] 069. Restore a missing POSIX user-execute bit after integrity validation.
+- [x] 070. Cache successful verification while preserving explicit cache invalidation for tests.
+
+## 071-080 — diagnostics and artifact verification
+
+- [x] 071. Give `TAILKITTY_BACKEND` explicit, fail-closed priority.
+- [x] 072. Prefer verified wheel bundles over development and PATH helpers.
+- [x] 073. Preserve a migration fallback for the former `tailcat-go` development filename.
+- [x] 074. Expose backend path, source, version, and manifest metadata.
+- [x] 075. Add human-readable `tailcat doctor` output.
+- [x] 076. Add machine-readable `tailcat doctor --json` output.
+- [x] 077. Reject unsafe or duplicate wheel archive paths.
+- [x] 078. Verify WHEEL purity and compatibility metadata.
+- [x] 079. Verify the embedded executable and manifest together.
+- [x] 080. Verify every wheel `RECORD` digest, size, and member mapping.
+
+## 081-090 — automation, metadata, and supply chain
+
+- [x] 081. Add unit coverage for bundle corruption and backend precedence.
+- [x] 082. Run Ruff, formatting, strict mypy, and pytest from one mise task.
+- [x] 083. Add a five-target CI wheel matrix.
+- [x] 084. Add isolated host-wheel installation smoke testing in CI.
+- [x] 085. Add binary-free source-distribution CI.
+- [x] 086. Add checksums and GitHub build-provenance attestations.
+- [x] 087. Add OIDC trusted-publishing automation with least-privilege permissions.
+- [x] 088. Pin third-party GitHub Actions to immutable commits.
+- [x] 089. Add PEP 561 typing metadata, classifiers, URLs, and third-party notices.
+- [x] 090. Document building, security, architecture boundaries, and the existing-project comparison.
+
+## 091-100 — real artifact and integration validation
+
+- [x] 091. Cross-compile and structurally verify all five real platform wheels locally.
+- [x] 092. Install the host wheel into an isolated environment and discover its verified bundle.
+- [x] 093. Rebuild identical host binaries and prove byte-for-byte reproducibility.
+- [x] 094. Detect and close Go's silent automatic-toolchain substitution path.
+- [x] 095. Build and inspect the no-bundle pure-Python wheel fallback.
+- [x] 096. Build and inspect the binary-free source distribution.
+- [x] 097. Run the full suite on the minimum supported Python 3.11.
+- [x] 098. Repeat live encrypted transfer testing and capture the current external DERP timeout
+  after earlier successful bundled transfers.
+- [x] 099. Rebuild final artifacts and pass the complete lint, type, test, and integrity audit.
+- [x] 100. Audit this ledger against the workspace and deliver the handoff.

tailkitty-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Tailkitty contributors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.