tailkitty 0.2.1__tar.gz → 0.2.2__tar.gz

{tailkitty-0.2.1 → tailkitty-0.2.2}/AGENTS.md

@@ -12,6 +12,14 @@ Read these files before making architectural, packaging, security, or release ch
 3. `BUILDING.md` for the reproducible bundle and wheel pipeline.
 4. `pyproject.toml` and `.mise.toml` for supported versions and canonical tasks.
 
+For a focused task, then read the matching guide:
+
+- `docs/python-api.md` for public Python behavior.
+- `docs/recipes.md` for user-facing command examples.
+- `docs/troubleshooting.md` for failure and diagnostic guidance.
+- `docs/architecture.md` for ownership and data flows.
+- `RELEASING.md` before changing versions, tags, workflows, or publication.
+
 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.
 
@@ -44,11 +52,14 @@ compatibility and fail-closed bundle discovery are core requirements.
 | `scripts/targets.py` | Supported build targets and wheel tags |
 | `scripts/build_binary.py` | Reproducible cross-compilation and manifest creation |
 | `patches/` | Auditable patches applied to the immutable upstream Tailcat source |
-| `scripts/build_wheels.py` | Isolated five-target wheel orchestration |
+| `scripts/build_wheels.py` | Isolated six-target wheel orchestration |
 | `scripts/verify_wheel.py` | Wheel metadata, archive, binary, and RECORD verification |
 | `scripts/check_upstream.py` | Latest stable Tailcat release drift check |
 | `hatch_build.py` | Platform-wheel build hook |
 | `tests/` | Unit and subprocess behavior tests |
+| `docs/` | Task-oriented user, API, troubleshooting, and architecture guides |
+| `CONTRIBUTING.md` | Human contributor workflow and checklist |
+| `RELEASING.md` | Release metadata, artifact, publishing, and verification checklist |
 
 Public imports are curated in `src/tailkitty/__init__.py`. Adding a public API requires updating
 that file, type annotations, tests, and README documentation.
@@ -67,6 +78,9 @@ mise run test
 strict mypy, and pytest. During iteration, run the narrowest relevant test first, then run the full
 gate before declaring completion.
 
+Direct build-module commands must run through `mise exec --`; plain `uv run` can select an
+unrelated system Go version.
+
 Packaging changes also require:
 
 ```console
@@ -144,6 +158,24 @@ without an explicit compatibility decision.
   keys, cache, bundle, or configured backend.
 - Keep Ruff's 100-character line length and run formatting rather than hand-aligning code.
 
+## Documentation conventions
+
+- The README is the onboarding map, not the exhaustive reference. Put task recipes, detailed API
+  behavior, troubleshooting, and architecture in their dedicated guides.
+- Documentation on `main` describes the current source tree. Cut a release promptly when the user
+  asks for GitHub, PyPI, and `main` to match.
+- State which machine runs each side of multi-peer examples.
+- Use complete copyable commands and quote `tc...` placeholders because addresses are
+  case-sensitive shell data.
+- Never put a syntactically plausible private key or active address in documentation.
+- Distinguish encryption, address possession, tunnel allow-lists, SSH keys, and application
+  authentication; do not collapse them into a generic “secure” claim.
+- Do not claim typed Python support for an upstream CLI or Go-library feature unless a Python API
+  actually exists.
+- Keep relative Markdown links resolvable from the file containing them and include new `docs/`
+  files in the source distribution.
+- When a command or flag is version-sensitive, check it against the pinned backend's `--help`.
+
 ## Generated files and release safety
 
 Do not manually edit or commit generated files under:
@@ -155,8 +187,9 @@ Do not manually edit or commit generated files under:
 
 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.
+GitHub environment, build all six wheels plus the source distribution, smoke-test the host wheel,
+and retain checksums and provenance attestations. Follow `RELEASING.md`; do not race automated and
+local publishers or upload from a directory containing artifacts from multiple versions.
 
 ## Definition of done
 

tailkitty-0.2.2/BUILDING.md

@@ -0,0 +1,216 @@
+# Building Tailkitty
+
+Tailkitty builds one upstream Tailcat executable per supported target, records its provenance in a
+manifest, and packages it in a platform-specific Python wheel. Source distributions remain
+binary-free.
+
+For the end-to-end publication checklist, see [RELEASING.md](RELEASING.md).
+
+## Pinned environment
+
+Mise is the source of truth for build tools:
+
+| Tool | Pin |
+| --- | --- |
+| Python | 3.13.11 |
+| Go | 1.27.1 |
+| uv | 0.12.7 |
+| Tailcat | `v0.6.0` |
+
+Install and synchronize them with:
+
+```console
+mise install
+uv sync --all-groups --locked
+```
+
+The builder sets `GOTOOLCHAIN=local` and rejects any Go version other than the exact pin. When
+running a Python build module directly, enter mise's environment:
+
+```console
+mise exec -- uv run python -m scripts.build_wheels --target linux-x86_64
+```
+
+Using plain `uv run` can select an unrelated system Go compiler.
+
+## Canonical tasks
+
+```console
+mise run test             # Ruff, formatting, strict mypy, pytest
+mise run backend          # source-checkout backend under .tools/bin
+mise run bundle           # host bundle under src/tailkitty/bin
+mise run bundle-verify    # verify the host bundle and manifest
+mise run wheel            # package the host bundle
+mise run wheels           # build and verify all six platform wheels
+mise run upstream-check   # compare the Tailcat pin with the latest stable release
+```
+
+Generated content under `.tools/bin/`, `src/tailkitty/bin/`, and `dist/` is ignored and must not be
+edited or committed.
+
+## Build pipeline
+
+`scripts.build_binary` performs these steps:
+
+1. Resolve the requested target.
+2. Verify the exact Go compiler.
+3. Download `github.com/tailscale/tailcat@<immutable-pin>` through the Go module system.
+4. Copy the source into a temporary writable workspace.
+5. Check and apply every lexically sorted patch under `patches/`.
+6. Read upstream's release build tags from `build-tags.txt`.
+7. Cross-compile `./cmd/tailcat` with the reproducibility and compatibility settings below.
+8. Check the executable header and minimum plausible size.
+9. Atomically place the executable and write `manifest.json`.
+
+The build uses:
+
+- `CGO_ENABLED=0`
+- `GOTOOLCHAIN=local`
+- `GOAMD64=v1`
+- `GOARM64=v8.0`
+- `-trimpath`
+- `-buildvcs=false`
+- stripped symbols
+- an empty Go build ID
+- upstream's official release omission tags
+
+Module downloads have three bounded attempts with short exponential backoff for transient failures.
+Build failures are not silently converted into old or partial bundles.
+
+## Bundle manifest
+
+Each generated bundle contains its executable and a schema-1 JSON manifest. The manifest records:
+
+- Internal target name and wheel platform tag.
+- Executable filename, size, and SHA-256.
+- Tailcat module and immutable version.
+- Applied patch filenames and SHA-256 values.
+- Go compiler version.
+- Reproducibility flags and release build tags.
+- CGO policy.
+
+Build-time verification rechecks those inputs. Runtime verification additionally requires the
+manifest target to match the current interpreter platform, rejects path-containing filenames and
+symlinks, and refuses size or digest mismatches.
+
+## Wheel matrix
+
+| Build target | Go target | Wheel tag | Executable |
+| --- | --- | --- | --- |
+| `macos-arm64` | `darwin/arm64` | `macosx_12_0_arm64` | Mach-O `tailcat` |
+| `macos-x86_64` | `darwin/amd64` | `macosx_12_0_x86_64` | Mach-O `tailcat` |
+| `linux-x86_64` | `linux/amd64` | `manylinux_2_17_x86_64` | ELF `tailcat` |
+| `linux-aarch64` | `linux/arm64` | `manylinux_2_17_aarch64` | ELF `tailcat` |
+| `windows-x86_64` | `windows/amd64` | `win_amd64` | PE `tailcat.exe` |
+| `windows-arm64` | `windows/arm64` | `win_arm64` | PE `tailcat.exe` |
+
+Build one target:
+
+```console
+mise exec -- uv run python -m scripts.build_wheels \
+  --target windows-arm64 \
+  --output dist/wheels
+```
+
+Build all targets:
+
+```console
+mise run wheels
+```
+
+Each target uses a separate temporary bundle directory. Environment variables tell the Hatch build
+hook which bundle and exact tag to include. This prevents one architecture's executable from
+leaking into another wheel.
+
+## Wheel verification
+
+`scripts.verify_wheel` opens the wheel as an archive and checks:
+
+- The filename and `WHEEL` metadata carry the expected platform tag.
+- The wheel is marked non-pure.
+- Archive members are unique and cannot escape through absolute or `..` paths.
+- Total uncompressed content is bounded.
+- `py.typed`, the manifest, and the one expected executable are present.
+- Manifest target, module, Tailcat pin, patch set, tags, size, and digest match build inputs.
+- The executable begins with the expected Mach-O, ELF, or PE magic.
+- Every non-`RECORD` member has the exact hash and size recorded in `RECORD`.
+- `RECORD` names exactly the archive contents.
+
+Cross-compiled executables cannot be run on the build host, so this structural verification is
+paired with native CI builds and the host smoke test.
+
+## Host smoke test
+
+Build or select the current host wheel, then run:
+
+```console
+uv run python -m scripts.smoke_wheel dist/wheels/<host-wheel>.whl
+```
+
+The smoke test:
+
+1. Creates a temporary isolated Python environment.
+2. Installs only the selected wheel and its dependencies.
+3. Runs `tailkitty doctor --json` and confirms the bundled backend is selected.
+4. Starts an isolated local DERP/STUN relay through Tailcat's test mode.
+5. Starts a peer and performs an actual encrypted ping.
+6. Applies five-second startup and client bounds, followed by bounded termination.
+
+It does not depend on public relay availability and does not touch saved developer keys.
+
+## Source distribution
+
+Build a source archive after removing any generated host bundle:
+
+```console
+mise run bundle-clean
+uv build --sdist --out-dir dist/release
+```
+
+The Hatch sdist configuration includes Python source, scripts, tests, patches, documentation, lock
+and tool configuration, but excludes generated executables and manifests. A source installation can
+use pure-Python address functionality immediately; networking requires a separately built or
+configured backend.
+
+## Reproducibility scope
+
+Tailkitty pins the compiler, module version, build tags, target baseline, and flags that commonly
+introduce host or VCS variation. The manifest makes every shipped executable auditable. Byte-for-byte
+reproduction can still depend on the Go module proxy serving the same immutable module contents and
+on the pinned tool downloads remaining available.
+
+`SOURCE_DATE_EPOCH` is set during matrix wheel builds so archive metadata is stable. Reproducibility
+does not mean one binary can be relabeled for another platform; each wheel is built and verified for
+exactly one target.
+
+## Upstream updates
+
+```console
+mise run upstream-check
+```
+
+This bounded GitHub API check fails when a newer stable Tailcat release exists. A daily scheduled
+workflow runs the same command. Before updating the pin, review:
+
+- Upstream changelog and security notes.
+- `wire.go` for address fields and validation changes.
+- CLI help and command ownership conflicts.
+- `build-tags.txt` and Go version.
+- New platform requirements.
+- Whether local patches are now upstream or no longer apply.
+
+Do not silently pin `main`. An immutable pseudo-version is acceptable only as an explicit,
+documented compatibility decision.
+
+## Common build failures
+
+| Failure | Likely cause | Action |
+| --- | --- | --- |
+| Wrong Go version | Command ran outside mise | Prefix the direct command with `mise exec --` |
+| Patch check fails | Upstream source changed | Review and update or remove the patch; never force it |
+| One wheel expected, several found | Output contains another artifact with the same version/tag | Use a clean release directory |
+| Wrong executable magic | Target or output staging mismatch | Inspect target selection; do not relabel the wheel |
+| Host smoke timeout | Backend did not advertise or handshake in bounds | Inspect local relay logs and process cleanup |
+| Public DERP timeout | External relay availability | Reproduce with the isolated smoke test |
+
+More user-facing failures are covered in [docs/troubleshooting.md](docs/troubleshooting.md).

{tailkitty-0.2.1 → tailkitty-0.2.2}/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.2.2 - 2026-09-08
+
+- Use Tailcat's declarative `serve` subcommand in managed Python server processes.
+- Add typed sync/async server options for DERP-map selection, PSK policy, file roots, and SSH
+  authorized-key sources.
+- Add a verified Windows ARM64 platform wheel target.
+- Replace the monolithic README with task-oriented recipes, API, troubleshooting, architecture,
+  contributor, build, security, and release documentation.
+- Export `BackendNotFound` and `ServerStartError` from the public package and report the current
+  version in DERP-map requests.
+
 ## 0.2.1 - 2026-09-08
 
 - Match upstream token rejection for trailing CBOR data, signed 64-bit overflows, and malformed

tailkitty-0.2.2/COMPARISON.md

@@ -0,0 +1,64 @@
+# Tailkitty and `pytailcat`
+
+Tailkitty and the separate [`pytailcat`](https://pypi.org/project/pytailcat/) distribution are
+independent Python projects built around upstream
+[Tailscale Tailcat](https://github.com/tailscale/tailcat). They are not rename-compatible packages:
+install and import the one you intend.
+
+This comparison was checked on 2026-09-08 against `pytailcat` 0.1.4 and Tailkitty 0.2.2.
+
+## Summary
+
+- Choose Tailkitty for current Tailcat behavior, pure-Python address tooling, asyncio, managed
+  lifecycle, fail-closed bundle verification, and reproducible release evidence.
+- Choose `pytailcat` when Python 3.8–3.10 or older macOS deployment targets are required.
+- Choose upstream Tailcat directly when no Python API or Python packaging is needed.
+
+## Feature comparison
+
+| Capability | `pytailcat` 0.1.4 | Tailkitty 0.2.2 |
+| --- | --- | --- |
+| Distribution/import | `pytailcat` | `tailkitty` |
+| Upstream data plane | Bundled Tailcat executable | Pinned Tailcat v0.6.0 executable |
+| Upstream revision | Pre-release commit `c04c5af` | Signed stable tag `v0.6.0` |
+| CLI compatibility | `tailcat` wrapper | `tailkitty` plus `tailcat` alias |
+| Address parsing | Delegated to executable | Typed pure-Python `ConnInfo` model |
+| Modern address fields | Depends on older bundled executable | Disco key and WireGuard PSK validated and preserved |
+| Future address fields | Depends on executable | Unknown root and nested extensions round-trip losslessly |
+| DERP expansion | Delegated to executable | Pure Python with bounded ETag cache and stale fallback |
+| DNS destinations | Delegated to executable | Pure-Python sync and asyncio resolution |
+| Client API | Thin synchronous process wrapper | Typed finite, streaming, sync, and asyncio clients |
+| Server API | Synchronous `ServerProcess` | Managed sync/async servers with typed v0.6 options |
+| Lifecycle cleanup | Basic process management | Bounded startup, terminate/kill escalation, reaping |
+| Bundle verification | Package transport integrity | Runtime target, schema, size, and SHA-256 verification |
+| Invalid bundle policy | Not documented as fail-closed | Explicit fail-closed behavior |
+| Build environment | uv-based | mise + uv with exact Python, Go, and Tailcat pins |
+| Wheel checks | Prebuilt wheel matrix | Archive, manifest, binary magic, and every `RECORD` entry |
+| Data-plane smoke test | Server lifecycle startup | Real encrypted peer handshake through local DERP/STUN |
+| Platforms | Five wheel targets | Six wheel targets, including Windows ARM64 |
+| Python requirement | 3.8+ | 3.11+ |
+| macOS floor | Older Intel/ARM targets | macOS 12+ |
+| Project license | BSD-3-Clause | MIT; bundled Tailcat remains BSD-3-Clause |
+
+Both projects retain the correct architectural boundary: the complex, interoperable network data
+plane is native Go. Tailkitty's “pure Python” claim applies to address parsing, DNS lookup, and DERP
+resolution—not to WireGuard, NAT traversal, or relay transport.
+
+## What Tailkitty deliberately does not claim
+
+- Tailkitty is not an official Tailscale product.
+- It is not a pure-Python VPN or a replacement Tailscale control plane.
+- It has not demonstrated a general throughput advantage over `pytailcat`; both ultimately depend
+  on Tailcat and network path behavior.
+- More validation does not replace PyPI/package-manager trust or an upstream security review.
+- Newer Python and macOS minimums are real compatibility costs, not hidden implementation details.
+
+## Why a separate name exists
+
+The `pytailcat` name belongs to another project. Tailkitty uses distinct distribution, import, and
+primary CLI names to avoid dependency confusion and accidental replacement. The optional `tailcat`
+command is only a compatibility alias inside an environment where Tailkitty was deliberately
+installed.
+
+For architectural details, see [docs/architecture.md](docs/architecture.md). For the exact current
+platform matrix, see [README.md](README.md#supported-wheels).

tailkitty-0.2.2/CONTRIBUTING.md

@@ -0,0 +1,131 @@
+# Contributing to Tailkitty
+
+Thank you for improving Tailkitty. The project values upstream compatibility, explicit security
+boundaries, deterministic tests, and documentation that can be followed without hidden context.
+
+## Before starting
+
+Read:
+
+1. [README.md](README.md) for public behavior.
+2. [SECURITY.md](SECURITY.md) for authorization and executable trust.
+3. [docs/architecture.md](docs/architecture.md) for the Python/native boundary.
+4. [BUILDING.md](BUILDING.md) for packaging changes.
+
+Automated contributors must also follow [AGENTS.md](AGENTS.md).
+
+## Development environment
+
+Install [mise](https://mise.jdx.dev/) and clone the repository, then run:
+
+```console
+mise install
+mise run setup
+mise run test
+```
+
+Mise pins Python, Go, and uv. Do not create a second toolchain configuration or commit a local
+virtual environment. `mise run setup` synchronizes the uv environment and builds the pinned Tailcat
+development backend.
+
+The normal edit loop is:
+
+```console
+uv run pytest tests/test_token.py
+mise run test
+```
+
+Use the narrowest relevant test while iterating, then run the complete quality gate before handing
+off a change. The gate includes Ruff linting, Ruff formatting checks, strict mypy, and pytest.
+
+## Change boundaries
+
+Tailkitty owns the Python control plane:
+
+- Address parsing, validation, and resolution.
+- DNS TXT destination lookup.
+- DERP-map caching.
+- Typed sync and asyncio wrappers.
+- Process lifecycle and diagnostics.
+- Verified distribution of the pinned backend.
+
+Upstream Tailcat owns magicsock, WireGuard, STUN, DERP transport, and gVisor netstack. Do not add a
+Python-only transport that only interoperates with itself. If a behavior belongs in Tailcat,
+consider an upstream contribution and pin the released result here.
+
+The Python CLI intentionally owns only `parse`, `resolve`, `doctor`, `--version`, and top-level
+help. New Python-native subcommands can shadow future Tailcat commands; adding one requires an
+explicit compatibility decision.
+
+## Tests
+
+Good tests are:
+
+- Deterministic and independent of public DERP availability.
+- Bounded by short, explicit timeouts when processes or networks are involved.
+- Isolated from saved user keys, caches, package directories, and configured backends.
+- Paired across sync and asyncio APIs when behavior should match.
+- Written as regressions for the exact failure being repaired.
+
+Public relays can be slow or unavailable. Default tests must not use them. The wheel smoke test uses
+an isolated local DERP/STUN relay and a five-second handshake bound.
+
+For Python compatibility changes, test the minimum supported runtime:
+
+```console
+uv run --isolated --python 3.11 --all-groups pytest
+```
+
+## Documentation
+
+Update documentation with the same change when public behavior changes:
+
+- README for discovery, installation, quickstarts, and the public boundary.
+- `docs/python-api.md` for Python parameters, results, exceptions, and lifecycle.
+- `docs/recipes.md` for task-oriented CLI examples.
+- `docs/troubleshooting.md` for new failure modes.
+- SECURITY for authorization, secrets, and trust changes.
+- BUILDING and RELEASING for packaging changes.
+- CHANGELOG for user-visible changes.
+- AGENTS when repository invariants or canonical workflows change.
+
+Examples must use placeholders, never live addresses or private keys. Keep commands copyable and
+state which machine runs each side of a multi-machine example.
+
+## Packaging changes
+
+Changes to bundle building, wheel tags, targets, manifests, dependencies, or build hooks require:
+
+```console
+mise run test
+mise run bundle
+mise run bundle-verify
+mise run wheels
+uv run python -m scripts.smoke_wheel dist/wheels/<host-wheel>.whl
+```
+
+When running a build module directly, keep it inside mise so the exact Go pin is selected:
+
+```console
+mise exec -- uv run python -m scripts.build_wheels --target windows-arm64
+```
+
+Do not manually edit or commit generated content under `src/tailkitty/bin/`, `dist/`, `.tools/bin/`,
+caches, or virtual environments.
+
+## Pull-request checklist
+
+- [ ] The change stays inside the Python/native ownership boundary.
+- [ ] Public APIs have complete annotations and root-package exports where appropriate.
+- [ ] Tests cover success, validation failure, timeout, and cleanup where relevant.
+- [ ] Sync and asyncio behavior remain aligned.
+- [ ] Documentation and changelog describe the public result.
+- [ ] No active address, private key, credential, or verbose network log is committed.
+- [ ] `mise run test` passes.
+- [ ] Packaging verification passes when packaging changed.
+- [ ] Remaining external limitations are stated explicitly.
+
+## Reporting security issues
+
+Do not open a public report containing secrets, live unrestricted addresses, private key files, or
+raw verbose logs. Follow [SECURITY.md](SECURITY.md).

{tailkitty-0.2.1 → tailkitty-0.2.2}/ITERATIONS.md

@@ -1,5 +1,10 @@
 # 100-iteration improvement ledger
 
+> [!NOTE]
+> This is the historical ledger for the initial Tailkitty implementation, not current product
+> documentation. See `README.md`, `CHANGELOG.md`, and `docs/` for the current release. Version and
+> platform statements below intentionally record what was true when each iteration was completed.
+
 Each checkbox is a distinct implementation, hardening, verification, or documentation pass. Items
 are marked only after their stated evidence exists.