heinzel-tailscale 0.9.1__tar.gz

heinzel_tailscale-0.9.1/.gitignore

@@ -0,0 +1,15 @@
+.venv/
+.tools/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.pyright/
+.coverage*
+htmlcov/
+node_modules/
+dist/
+release-dist/
+*.egg-info/
+.acceptance/
+.preview/
+.candidates/

heinzel_tailscale-0.9.1/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.9.1
+
+Move this plugin to its independent repository project for the Heinzel 0.9.1 plugin contract.
+Own its dependencies, tests and artifacts; consume public contracts without concrete provider dependencies.
+
+Earlier history is preserved in the source repository named in README.md.

heinzel_tailscale-0.9.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Helmut Hoffer von Ankershoffen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

heinzel_tailscale-0.9.1/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.5
+Name: heinzel-tailscale
+Version: 0.9.1
+Summary: Share the authenticated web app privately through Tailscale Serve: a Heinzelmännchen plugin.
+Project-URL: Source, https://github.com/helmut-hoffer-von-ankershoffen/heinzel-plugins/tree/main/plugins/heinzel-tailscale
+Project-URL: Changelog, https://github.com/helmut-hoffer-von-ankershoffen/heinzel-plugins/blob/main/plugins/heinzel-tailscale/CHANGELOG.md
+Project-URL: Issues, https://github.com/helmut-hoffer-von-ankershoffen/heinzel-plugins/issues
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: heinzel<0.10,>=0.9.1
+Requires-Dist: httpx>=0.28
+Description-Content-Type: text/markdown
+
+# Tailscale private web sharing
+
+A first-party adapter for the installed Tailscale client. It keeps the web app's bearer/device authentication and
+loopback listener; tailnet membership does not grant access to the backend owner's operations or terminal.
+
+Install the released plugin from Discover Plugins, or run `hz system plugin add tailscale --confirm`. The core PyPI
+package does not bundle this separate plugin distribution, so add it explicitly after installing Heinzel. Tailscale
+itself must already be installed and signed in; hz does not install it, log in, grant HTTPS consent or change OS
+permissions for you.
+On macOS it also detects the CLI bundled in `/Applications/Tailscale.app` and explicitly selects CLI mode, as
+described in [Tailscale's CLI documentation](https://tailscale.com/docs/reference/tailscale-cli?tab=macos).
+
+In Settings or the footer's sharing icon, turn **Share over Tailscale** on. The control checks the node and existing
+Serve mappings, merges its exact HTTPS origin into your user configuration and configures its loopback target. The
+running web app applies the updated origin policy immediately; it does not require a backend restart. It shows ON and
+a URL only after the owning authenticated web app verifies its actual port, active origin policy and matching Serve
+configuration. A CLI/stdio MCP request saves the same intent but reports verification pending until that web owner
+verifies it. Status reads never enable sharing.
+
+```sh
+hz tailscale status --json
+hz tailscale enable --json
+hz tailscale disable --json
+```
+
+The corresponding private operations are available through authenticated API and stdio MCP. They are absent from
+the unauthenticated REST and HTTP MCP heads. In-process calls use the actual bound web port. A separate CLI retains
+a previously observed port override; it cannot discover an arbitrary ephemeral web listener or claim it is ready.
+
+**Copy URL** copies a working link with the current `#token=...` session fragment when the authenticated session has
+one. Treat that link like a password: anyone who receives it can use that session until it is revoked or expires. If
+there is no session token, the control copies only the address. A fresh phone browser also needs authentication: use
+the separate **Copy sign-in link** action from the session owner, then pair that browser. Pairing a device never grants
+it authority to pair another device. See [private web sharing](https://github.com/helmut-hoffer-von-ankershoffen/heinzel/blob/main/docs/PRIVATE_WEB_SHARING.md) for authentication
+and revocation.
+
+Turning sharing off removes only the still-matching hz root handler and any origin permission this plugin added.
+Other paths, listeners, services and manually configured origins remain. An existing conflicting root, public
+Funnel setting, foreground session or higher-priority origin policy is refused. A changed Serve revision or unknown
+write outcome stops without retry or rollback; inspect current status before taking another action.
+Matching an existing manual handler does not make it owned by hz, so enabling refuses to adopt it. OFF without an
+owned request is non-destructive. Completed removal relinquishes ownership before cleanup; repeating OFF cannot
+delete a later manual recreation. An uncertain create remains unverified and needs inspection before deletion.
+
+`tailscale.https_port` chooses an alternate HTTPS port when another app owns the default. Disable a previous request
+before changing its external origin. A Tailscale version must provide the conditional Serve LocalAPI and one of the
+recognized local endpoint formats. Unsupported client installations report an actionable error; no sudo or remote
+endpoint fallback is attempted. The exact node DNS name must be eligible for HTTPS certificates in Tailscale's own
+configuration. Readiness verifies the local deployment; actual phone access still depends on Tailscale login,
+network policy and the remote browser's credential.
+
+Development and release commands: [repository guide](../../README.md).
+
+Migration provenance: heinzel, before the 0.9 plugin-boundary migration.

heinzel_tailscale-0.9.1/README.md

@@ -0,0 +1,54 @@
+# Tailscale private web sharing
+
+A first-party adapter for the installed Tailscale client. It keeps the web app's bearer/device authentication and
+loopback listener; tailnet membership does not grant access to the backend owner's operations or terminal.
+
+Install the released plugin from Discover Plugins, or run `hz system plugin add tailscale --confirm`. The core PyPI
+package does not bundle this separate plugin distribution, so add it explicitly after installing Heinzel. Tailscale
+itself must already be installed and signed in; hz does not install it, log in, grant HTTPS consent or change OS
+permissions for you.
+On macOS it also detects the CLI bundled in `/Applications/Tailscale.app` and explicitly selects CLI mode, as
+described in [Tailscale's CLI documentation](https://tailscale.com/docs/reference/tailscale-cli?tab=macos).
+
+In Settings or the footer's sharing icon, turn **Share over Tailscale** on. The control checks the node and existing
+Serve mappings, merges its exact HTTPS origin into your user configuration and configures its loopback target. The
+running web app applies the updated origin policy immediately; it does not require a backend restart. It shows ON and
+a URL only after the owning authenticated web app verifies its actual port, active origin policy and matching Serve
+configuration. A CLI/stdio MCP request saves the same intent but reports verification pending until that web owner
+verifies it. Status reads never enable sharing.
+
+```sh
+hz tailscale status --json
+hz tailscale enable --json
+hz tailscale disable --json
+```
+
+The corresponding private operations are available through authenticated API and stdio MCP. They are absent from
+the unauthenticated REST and HTTP MCP heads. In-process calls use the actual bound web port. A separate CLI retains
+a previously observed port override; it cannot discover an arbitrary ephemeral web listener or claim it is ready.
+
+**Copy URL** copies a working link with the current `#token=...` session fragment when the authenticated session has
+one. Treat that link like a password: anyone who receives it can use that session until it is revoked or expires. If
+there is no session token, the control copies only the address. A fresh phone browser also needs authentication: use
+the separate **Copy sign-in link** action from the session owner, then pair that browser. Pairing a device never grants
+it authority to pair another device. See [private web sharing](https://github.com/helmut-hoffer-von-ankershoffen/heinzel/blob/main/docs/PRIVATE_WEB_SHARING.md) for authentication
+and revocation.
+
+Turning sharing off removes only the still-matching hz root handler and any origin permission this plugin added.
+Other paths, listeners, services and manually configured origins remain. An existing conflicting root, public
+Funnel setting, foreground session or higher-priority origin policy is refused. A changed Serve revision or unknown
+write outcome stops without retry or rollback; inspect current status before taking another action.
+Matching an existing manual handler does not make it owned by hz, so enabling refuses to adopt it. OFF without an
+owned request is non-destructive. Completed removal relinquishes ownership before cleanup; repeating OFF cannot
+delete a later manual recreation. An uncertain create remains unverified and needs inspection before deletion.
+
+`tailscale.https_port` chooses an alternate HTTPS port when another app owns the default. Disable a previous request
+before changing its external origin. A Tailscale version must provide the conditional Serve LocalAPI and one of the
+recognized local endpoint formats. Unsupported client installations report an actionable error; no sudo or remote
+endpoint fallback is attempted. The exact node DNS name must be eligible for HTTPS certificates in Tailscale's own
+configuration. Readiness verifies the local deployment; actual phone access still depends on Tailscale login,
+network policy and the remote browser's credential.
+
+Development and release commands: [repository guide](../../README.md).
+
+Migration provenance: heinzel, before the 0.9 plugin-boundary migration.

heinzel_tailscale-0.9.1/plugin-lock.json

@@ -0,0 +1,41 @@
+{
+  "format": 1,
+  "sdk": 1,
+  "inputs": [
+    "coverage>=7.12",
+    "editables>=0.5",
+    "hatchling>=1.29.0",
+    "heinzel>=0.9.1,<0.10",
+    "httpx>=0.28",
+    "mypy>=1.19.0,<3",
+    "pyright[nodejs]==1.1.414",
+    "pytest-timeout>=2.4.0,<3",
+    "pytest-xdist>=3.8",
+    "pytest>=9.0.3,<10",
+    "ruff==0.17.2"
+  ],
+  "core": {
+    "version": "0.9.1",
+    "dependencies": [
+      "croniter>=6.2.4",
+      "fastapi>=0.161",
+      "keyring>=25.6",
+      "mcp>=2.3",
+      "packaging>=25.0",
+      "platformdirs>=4.5",
+      "pluggy<2,>=1.6.0",
+      "psutil==7.2.2",
+      "pydantic-ai-slim==2.61.0",
+      "pydantic-ai-slim[anthropic]==2.61.0; extra == \"anthropic\"",
+      "pydantic-ai-slim[openai]==2.61.0; extra == \"openai\"",
+      "pydantic-settings<3,>=2.11.0",
+      "pydantic<3,>=2.12.0",
+      "pyyaml<7,>=6.0.2",
+      "rich>=14.2.0",
+      "tomlkit>=0.13",
+      "typer>=0.23.0",
+      "uvicorn>=0.54",
+      "wsproto>=1.3"
+    ]
+  }
+}

heinzel_tailscale-0.9.1/pyproject.toml

@@ -0,0 +1,131 @@
+[project]
+name = "heinzel-tailscale"
+version = "0.9.1"
+description = "Share the authenticated web app privately through Tailscale Serve: a Heinzelmännchen plugin."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = ["heinzel>=0.9.1,<0.10", "httpx>=0.28"]
+
+[project.urls]
+Source = "https://github.com/helmut-hoffer-von-ankershoffen/heinzel-plugins/tree/main/plugins/heinzel-tailscale"
+Changelog = "https://github.com/helmut-hoffer-von-ankershoffen/heinzel-plugins/blob/main/plugins/heinzel-tailscale/CHANGELOG.md"
+Issues = "https://github.com/helmut-hoffer-von-ankershoffen/heinzel-plugins/issues"
+
+[project.entry-points."heinzel.modules"]
+tailscale = "heinzel_tailscale"
+
+[build-system]
+requires = ["hatchling>=1.29.0"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+test = ["editables>=0.5", "pytest>=9.0.3,<10", "pytest-timeout>=2.4.0,<3", "pytest-xdist>=3.8", "ruff==0.17.2", "mypy>=1.19.0,<3", "coverage>=7.12", "pyright[nodejs]==1.1.414"]
+
+
+[tool.ruff]
+line-length = 120
+fix = true
+extend-exclude = ["template"] # rendered and checked by `make template-test`
+
+[tool.ruff.lint]
+select = ["ALL"]
+# pydoclint (DOC): docstring sections must match what the code raises, returns and yields. Preview rules, opted into
+# one by one so no other preview rule sneaks in.
+preview = true
+explicit-preview-rules = true
+extend-select = ["DOC201", "DOC202", "DOC402", "DOC403", "DOC501", "DOC502"]
+ignore = [
+    "COM812",  # conflicts with the ruff formatter
+    "CPY001",  # no copyright header in OSS files
+    "D203",    # incompatible with D211
+    "DOC201",  # a return value is documented by the type and the summary line; Returns: only when it adds meaning
+    "DOC502",  # documenting exceptions raised by callees is useful for callers
+    "D213",    # incompatible with D212
+    "FBT001",  # boolean positional arguments are idiomatic for Typer options
+    "FBT002",  # same as FBT001
+    "ISC001",  # conflicts with the ruff formatter
+    "TD003",   # todos don't need an issue link
+    "FIX002",  # todos are allowed
+]
+
+[tool.ruff.lint.per-file-ignores]
+".claude/hooks/*.py" = [
+    "D103",    # hook entry points are documented by the module docstring
+    "INP001",  # hooks are scripts, not a package
+    "S603",    # subprocess calls with fixed argument lists
+    "S607",    # tools (uv, git, make) are resolved from PATH on purpose
+    "T201",    # hooks talk to the agent through stdout/stderr
+]
+"fuzz/*.py" = [
+    "INP001",  # fuzz targets are scripts, not a package
+]
+"hatch_build.py" = [
+    "INP001",  # the build hook hatch loads by path, not a package
+]
+"scripts/*.py" = [
+    "INP001",  # scripts are not a package
+    "T201",    # scripts report on stdout/stderr
+]
+"**/tests/**/*.py" = [
+    "ANN",     # fixtures and tests don't need full annotations
+    "DOC",     # test docstrings describe behaviour, not interfaces
+    "ARG",     # fixtures are used for their side effects
+    "D",       # test names are the documentation
+    "INP001",  # tests are not a package
+    "PLC0415", # local imports keep fixtures isolated
+    "PLR2004", # magic values are fine in assertions
+    "S101",    # asserts are what tests do
+    "S105",    # fake tokens and passwords are test data (credentials, adapters for tracker and document services)
+    "S106",    # same as S105, passed as arguments
+    "S603",    # subprocess calls with trusted input
+    "S607",    # partial executable paths (uv, hz) are resolved from PATH on purpose
+    "SLF001",  # private access is needed for solitary unit tests
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.mypy]
+strict = true
+mypy_path = ["src"]
+files = ["src"]
+plugins = ["pydantic.mypy"]
+
+[tool.pydantic-mypy]
+init_forbid_extra = true
+init_typed = true
+warn_required_dynamic_aliases = true
+
+[tool.pytest]
+minversion = "9.0"
+strict = true
+testpaths = ["tests"]
+addopts = ["-ra", "--import-mode=importlib"]
+filterwarnings = ["error"]
+markers = ["unit: Offline isolated behavior.", "integration: Offline public-contract integration.", "e2e: Installed artifacts or real external services.", "perf: Explicit timing tests.", "long_running: Extended end-to-end budget."]
+
+[tool.heinzel.plugin]
+profiles = ["standard"]
+requires = ["core:plugin-api@1"]
+provides = []
+
+[tool.coverage.run]
+source = ["heinzel_tailscale"]
+branch = true
+
+[tool.coverage.report]
+fail_under = 90
+show_missing = true
+
+[tool.pyright]
+typeCheckingMode = "strict"
+include = ["src"]
+pythonVersion = "3.12"
+
+[tool.hatch.build.targets.sdist]
+exclude = [".venv", ".acceptance", ".preview", "dist", "web/node_modules", "**/__pycache__", ".pytest_cache", ".mypy_cache", ".coverage*"]