tailscale-manager 0.1.0__py3-none-any.whl

tailscale_manager/__init__.py

@@ -0,0 +1,3 @@
+from tailscale_manager.core.exceptions import TemplateError
+
+__all__ = ["TemplateError"]

tailscale_manager/cli.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import importlib.metadata
+import json
+import sys
+
+import typer
+
+from tailscale_manager.core.config import AppConfig
+from tailscale_manager.repositories.state_repository import StateRepository
+from tailscale_manager.services.terraform_service import TerraformService
+
+app = typer.Typer(
+    name="tailscale-manager",
+    help="Manage Tailscale auth keys via Terraform",
+)
+
+
+def _load_config() -> AppConfig:
+    config = AppConfig.from_env()
+    config.state_dir.mkdir(parents=True, exist_ok=True)
+    return config
+
+
+@app.callback()
+def _main() -> None:
+    pass
+
+
+@app.command()
+def init() -> None:
+    config = _load_config()
+    svc = TerraformService(config)
+    svc.generate_config()
+    output = svc.init()
+    print(output)
+
+
+@app.command()
+def plan() -> None:
+    config = _load_config()
+    svc = TerraformService(config)
+    svc.generate_config()
+    svc.init()
+    output = svc.plan()
+    print(output)
+
+
+@app.command()
+def apply() -> None:
+    config = _load_config()
+    svc = TerraformService(config)
+    result = svc.apply()
+    print(json.dumps(result, indent=2))
+    if result["result"] == "ok":
+        print("Apply succeeded")
+    else:
+        print(f"Apply failed: {result.get('error_message', '')}", file=sys.stderr)
+        raise typer.Exit(1)
+
+
+@app.command()
+def destroy() -> None:
+    config = _load_config()
+    svc = TerraformService(config)
+    result = svc.destroy()
+    print(json.dumps(result, indent=2))
+    if result["result"] == "ok":
+        print("Destroy succeeded")
+    else:
+        print(f"Destroy failed: {result.get('error_message', '')}", file=sys.stderr)
+        raise typer.Exit(1)
+
+
+@app.command()
+def status(
+    json_output: bool = typer.Option(
+        False,
+        "--json",
+        help="Print last-apply.json to stdout instead of launching TUI",
+    ),
+) -> None:
+    config = _load_config()
+    repo = StateRepository(config.state_dir)
+    keys = repo.get_managed_keys()
+    last = repo.read_last_apply()
+
+    if json_output:
+        output: dict = {
+            "last_apply": last or {},
+            "managed_keys": [
+                {
+                    "id": k.id,
+                    "description": k.description,
+                    "tags": k.tags,
+                    "revoked": k.revoked,
+                }
+                for k in keys
+            ],
+        }
+        print(json.dumps(output, indent=2, default=str))
+        if last and last.get("result") == "error":
+            raise typer.Exit(1)
+        return
+
+    print(f"Tailscale Manager — {config.tailnet}")
+    print(f"State dir: {config.state_dir}")
+    print()
+
+    if last:
+        print(f"Last apply: {last.get('timestamp', 'unknown')}")
+        print(f"  Result: {last.get('result', 'unknown')}")
+        err = last.get("error_message")
+        if err:
+            print(f"  Error: {err}")
+    else:
+        print("No apply has been run yet.")
+
+    print()
+    keys_file = config.state_dir / "terraform.tfstate"
+    print(f"Terraform state: {'found' if keys_file.exists() else 'not found'}")
+
+    print(f"Managed keys: {len(keys)}")
+    for k in keys:
+        status_icon = "✗" if k.revoked else "✓"
+        print(f"  {status_icon} {k.id[:16] if k.id else '<no id>'} — {k.description or '<no desc>'}")
+        if k.tags:
+            print(f"     tags: {', '.join(k.tags)}")
+
+    # Try launching TUI if available
+    try:
+        from textual_ui import run_status_app  # type: ignore[import-untyped]
+
+        run_status_app(config, keys, last)
+    except ImportError:
+        pass
+    except Exception as exc:
+        print(f"TUI unavailable: {exc}", file=sys.stderr)
+
+
+@app.command()
+def backup_state() -> None:
+    config = _load_config()
+    svc = TerraformService(config)
+    svc._backup_state()
+    print(f"Backed up state in {config.state_dir / 'backups'}")
+
+
+@app.command()
+def restore_state() -> None:
+    config = _load_config()
+    svc = TerraformService(config)
+    svc._restore_state()
+    print("Restored most recent state backup")
+
+
+@app.command()
+def version() -> None:
+    """Show tailscale-manager version."""
+    v = importlib.metadata.version("tailscale-manager")
+    print(f"tailscale-manager {v}")
+
+
+def main() -> None:
+    app()

tailscale_manager/core/config.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+
+class AppConfig(BaseModel):
+    tailnet: str = Field(
+        description="Tailscale tailnet name (e.g. example.com)"
+    )
+    state_dir: Path = Field(
+        default=Path("/var/lib/tailscale-manager"),
+        description="Directory for Terraform state and backups",
+    )
+    terraform_bin: Path = Field(
+        default=Path("terraform"),
+        description="Path to the terraform binary",
+    )
+    backup_count: int = Field(
+        default=5,
+        ge=1,
+        description="Number of tfstate backups to retain",
+    )
+    tags: list[str] = Field(
+        default_factory=list,
+        description="Tags to apply to the managed auth key",
+    )
+
+    @classmethod
+    def from_env(cls) -> AppConfig:
+        tailnet = os.environ.get("TAILSCALE_TAILNET")
+        if not tailnet:
+            # Fallback: the Tailscale Terraform provider's canonical env var
+            tailnet = os.environ.get("TAILSCALE_OAUTH_TAILNET", "")
+        if not tailnet:
+            raise ConfigurationError(
+                "TAILSCALE_TAILNET environment variable is required"
+            )
+        state_dir = Path(
+            os.environ.get(
+                "TAILSCALE_MANAGER_STATE_DIR",
+                "/var/lib/tailscale-manager",
+            )
+        )
+        terraform_bin = Path(
+            os.environ.get(
+                "TAILSCALE_MANAGER_TERRAFORM_BIN",
+                "terraform",
+            )
+        )
+        backup_count = int(
+            os.environ.get("TAILSCALE_MANAGER_BACKUP_COUNT", "5")
+        )
+        tags_raw = os.environ.get("TAILSCALE_MANAGER_TAGS", "")
+        tags = [t.strip() for t in tags_raw.split(",") if t.strip()]
+
+        return cls(
+            tailnet=tailnet,
+            state_dir=state_dir,
+            terraform_bin=terraform_bin,
+            backup_count=backup_count,
+            tags=tags,
+        )
+
+
+class ConfigurationError(Exception):
+    pass

tailscale_manager/core/constants.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+APP_NAME = "tailscale-manager"
+VERSION = "0.1.0"
+DEFAULT_STATE_DIR = "/var/lib/tailscale-manager"
+PROVIDER_VERSION = "~> 0.29"
+LAST_APPLY_FILE = "last-apply.json"
+BACKUP_DIR = "backups"
+TERRAFORM_DIR = ".terraform"
+MAIN_TF_FILE = "main.tf.json"
+STATE_FILE = "terraform.tfstate"

tailscale_manager/core/exceptions.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+
+class TemplateError(Exception):
+    pass
+
+
+class ConfigurationError(TemplateError):
+    pass
+
+
+class ServiceError(TemplateError):
+    pass
+
+
+class NotFoundError(TemplateError):
+    pass
+
+
+class TerraformError(TemplateError):
+    pass

tailscale_manager/models/auth_key.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+
+@dataclass
+class TailscaleAuthKey:
+    id: str
+    description: str
+    tags: list[str] = field(default_factory=list)
+    expiry: datetime | None = None
+    revoked: bool = False
+    reusable: bool = True
+    ephemeral: bool = False
+    preauthorized: bool = True
+    created_at: datetime | None = None
+    key: str | None = None

tailscale_manager/repositories/state_repository.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from pathlib import Path
+
+from tailscale_manager.models.auth_key import TailscaleAuthKey
+
+
+class StateRepository:
+    def __init__(self, state_dir: Path) -> None:
+        self.state_file = state_dir / "terraform.tfstate"
+        self.last_apply_file = state_dir / "last-apply.json"
+
+    def read_state(self) -> dict | None:
+        if not self.state_file.exists():
+            return None
+        raw = self.state_file.read_text()
+        return json.loads(raw)
+
+    def get_managed_keys(self) -> list[TailscaleAuthKey]:
+        state = self.read_state()
+        if state is None:
+            return []
+
+        keys: list[TailscaleAuthKey] = []
+        resources = state.get("resources", [])
+        for res in resources:
+            if res.get("type") != "tailscale_tailnet_key":
+                continue
+            for instance in res.get("instances", []):
+                attrs = instance.get("attributes", {})
+                key = TailscaleAuthKey(
+                    id=attrs.get("id", ""),
+                    description=attrs.get("description", ""),
+                    tags=attrs.get("tags", []),
+                    expiry=self._parse_ts(attrs.get("expires")),
+                    revoked=attrs.get("revoked", False),
+                    reusable=attrs.get("reusable", True),
+                    ephemeral=attrs.get("ephemeral", False),
+                    preauthorized=attrs.get("preauthorized", True),
+                    created_at=self._parse_ts(attrs.get("created_at")),
+                    key=attrs.get("key"),
+                )
+                keys.append(key)
+        return keys
+
+    def read_last_apply(self) -> dict | None:
+        if not self.last_apply_file.exists():
+            return None
+        raw = self.last_apply_file.read_text()
+        return json.loads(raw)
+
+    def write_last_apply(self, data: dict) -> None:
+        self.last_apply_file.parent.mkdir(parents=True, exist_ok=True)
+        self.last_apply_file.write_text(json.dumps(data, indent=2) + "\n")
+
+    @staticmethod
+    def _parse_ts(value: str | None) -> datetime | None:
+        if value is None:
+            return None
+        try:
+            return datetime.fromisoformat(value.replace("Z", "+00:00"))
+        except (ValueError, TypeError):
+            return None

tailscale_manager/services/terraform_service.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import json
+import shutil
+from datetime import datetime, timezone
+from pathlib import Path
+
+from tailscale_manager.core.config import AppConfig
+from tailscale_manager.core.constants import (
+    BACKUP_DIR,
+    MAIN_TF_FILE,
+    PROVIDER_VERSION,
+    STATE_FILE,
+)
+from tailscale_manager.core.exceptions import TerraformError
+from tailscale_manager.repositories.state_repository import StateRepository
+from tailscale_manager.utils.subprocess_helpers import run_terraform
+
+
+class TerraformService:
+    def __init__(self, config: AppConfig) -> None:
+        self.config = config
+        self.state_repo = StateRepository(config.state_dir)
+
+    def generate_config(self) -> Path:
+        self.config.state_dir.mkdir(parents=True, exist_ok=True)
+        tf_path = self.config.state_dir / MAIN_TF_FILE
+
+        tags = self.config.tags
+
+        cfg = {
+            "terraform": {
+                "required_providers": {
+                    "tailscale": {
+                        "source": "tailscale/tailscale",
+                        "version": PROVIDER_VERSION,
+                    }
+                }
+            },
+            "provider": {
+                "tailscale": {}
+            },
+            "resource": {
+                "tailscale_tailnet_key": {
+                    "managed_key": {
+                        "reusable": True,
+                        "ephemeral": False,
+                        "preauthorized": True,
+                        "tags": tags,
+                        "recreate_if_invalid": "always",
+                    }
+                }
+            },
+        }
+
+        tf_path.write_text(json.dumps(cfg, indent=2) + "\n")
+        return tf_path
+
+    def init(self) -> str:
+        return run_terraform(
+            self.config.terraform_bin,
+            ["init", "-input=false"],
+            cwd=self.config.state_dir,
+        )
+
+    def plan(self) -> str:
+        return run_terraform(
+            self.config.terraform_bin,
+            ["plan", "-input=false", "-detailed-exitcode"],
+            cwd=self.config.state_dir,
+            timeout=60,
+        )
+
+    def apply(self) -> dict:
+        timestamp = datetime.now(timezone.utc).isoformat()
+        try:
+            self._backup_state()
+            self.generate_config()
+            self.init()
+            run_terraform(
+                self.config.terraform_bin,
+                [
+                    "apply",
+                    "-input=false",
+                    "-auto-approve",
+                ],
+                cwd=self.config.state_dir,
+                timeout=180,
+            )
+            result = {
+                "timestamp": timestamp,
+                "result": "ok",
+            }
+        except TerraformError as exc:
+            self._restore_state()
+            result = {
+                "timestamp": timestamp,
+                "result": "error",
+                "error_message": str(exc),
+            }
+        self.state_repo.write_last_apply(result)
+        return result
+
+    def destroy(self) -> dict:
+        timestamp = datetime.now(timezone.utc).isoformat()
+        try:
+            self._backup_state()
+            run_terraform(
+                self.config.terraform_bin,
+                [
+                    "destroy",
+                    "-input=false",
+                    "-auto-approve",
+                ],
+                cwd=self.config.state_dir,
+                timeout=180,
+            )
+            result = {
+                "timestamp": timestamp,
+                "result": "ok",
+                "action": "destroy",
+            }
+        except TerraformError as exc:
+            self._restore_state()
+            result = {
+                "timestamp": timestamp,
+                "result": "error",
+                "error_message": str(exc),
+                "action": "destroy",
+            }
+        self.state_repo.write_last_apply(result)
+        return result
+
+    def _backup_state(self) -> None:
+        state_file = self.config.state_dir / STATE_FILE
+        if not state_file.exists():
+            return
+        backup_dir = self.config.state_dir / BACKUP_DIR
+        backup_dir.mkdir(parents=True, exist_ok=True)
+        ts = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%f")
+        backup_path = backup_dir / f"{ts}.tfstate"
+        shutil.copy2(state_file, backup_path)
+        self._prune_backups()
+
+    def _restore_state(self) -> None:
+        backup_dir = self.config.state_dir / BACKUP_DIR
+        if not backup_dir.exists():
+            return
+        backups = sorted(backup_dir.glob("*.tfstate"))
+        if not backups:
+            return
+        latest = backups[-1]
+        state_file = self.config.state_dir / STATE_FILE
+        shutil.copy2(latest, state_file)
+
+    def _prune_backups(self) -> None:
+        backup_dir = self.config.state_dir / BACKUP_DIR
+        backups = sorted(backup_dir.glob("*.tfstate"))
+        while len(backups) > self.config.backup_count:
+            backups[0].unlink()
+            backups = backups[1:]

tailscale_manager/utils/subprocess_helpers.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Mapping
+from pathlib import Path
+
+from tailscale_manager.core.exceptions import TerraformError
+
+
+def run_terraform(
+    terraform_bin: Path,
+    args: list[str],
+    cwd: Path,
+    env: Mapping[str, str] | None = None,
+    timeout: int = 120,
+) -> str:
+    cmd = [str(terraform_bin), *args]
+    try:
+        result = subprocess.run(
+            cmd,
+            cwd=str(cwd),
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            env=env,
+        )
+        # terraform plan -detailed-exitcode returns:
+        #   0 = no changes, 1 = error, 2 = non-empty diff
+        # Treat exit code 2 as success for plan (changes to apply).
+        if result.returncode != 0 and not (
+            len(args) >= 1 and args[0] == "plan" and result.returncode == 2
+        ):
+            msg = (
+                f"terraform {' '.join(args)} failed (exit {result.returncode}):\n"
+                f"{result.stderr.strip()}"
+            )
+            raise TerraformError(msg)
+        return result.stdout.strip()
+    except FileNotFoundError:
+        raise TerraformError(
+            f"terraform binary not found at {terraform_bin}"
+        )
+    except subprocess.TimeoutExpired:
+        raise TerraformError(
+            f"terraform {' '.join(args)} timed out after {timeout}s"
+        )

tailscale_manager-0.1.0.dist-info/METADATA

@@ -0,0 +1,550 @@
+Metadata-Version: 2.4
+Name: tailscale-manager
+Version: 0.1.0
+Summary: NixOS module + CLI for managing Tailscale auth keys via Terraform
+Author-email: Tailscale Manager <maintainers@example.com>
+License: MIT
+Keywords: tailscale,terraform,nixos
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.12
+Requires-Dist: pydantic>=2.5
+Provides-Extra: tui
+Requires-Dist: textual>=0.60; extra == "tui"
+Provides-Extra: dev
+
+<picture>
+  <source
+    srcset="https://raw.githubusercontent.com/Cairnstew/tailscale-manager/main/assets/logo-dark.svg"
+    media="(prefers-color-scheme: dark)"
+  />
+  <img
+    src="https://raw.githubusercontent.com/Cairnstew/tailscale-manager/main/assets/logo-light.svg"
+    alt="tailscale-manager"
+  />
+</picture>
+
+# tailscale-manager
+
+Declaratively manage Tailscale auth keys via Terraform on NixOS.
+
+A NixOS module + Python CLI that wraps the [Tailscale Terraform
+provider](https://registry.terraform.io/providers/tailscale/tailscale)
+to create, rotate, and expire auth keys — all packaged hermetically with
+[uv2nix](https://github.com/pyproject-nix/uv2nix).
+
+```console
+$ tailscale-manager status
+Tailscale Manager — your-tailnet.ts.net
+State dir: /var/lib/tailscale-manager
+
+Last apply: 2026-05-31T00:00:00+00:00
+  Result: ok
+
+Terraform state: found
+Managed keys: 1
+  ✓ k123abc — managed key
+     tags: tag:ci
+```
+
+## Features
+
+- **Declarative key management** — one `nixos-rebuild switch` to create,
+  update, or rotate auth keys. No imperative API calls.
+- **Automatic rotation** — `recreate_if_invalid = "always"` means expired keys
+  are replaced automatically on the next apply. No cron, no expiry tracking.
+- **Failure-safe** — tfstate is backed up before every apply. On failure, the
+  previous state is restored and the error is written to `last-apply.json`.
+- **Credential watcher** — a systemd path unit re-runs apply when the OAuth
+  secret file changes (e.g. after agenix rotation).
+- **Read-only TUI** — optional Textual dashboard showing managed keys and
+  system status. No write operations from the UI.
+- **Monitoring-ready** — `tailscale-manager status --json` with exit code
+  signaling for waybar, Prometheus node_exporter textfile collector, etc.
+- **Hermetic builds** — full dependency tree locked via `uv.lock` and built
+  by Nix. No `pip install` outside of Nix.
+
+## Quick start
+
+### 1. Add the flake
+
+```nix
+# flake.nix
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    tailscale-manager = {
+      url = "github:Cairnstew/tailscale-manager";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+  };
+
+  outputs = { self, nixpkgs, tailscale-manager, ... }: {
+    nixosConfigurations.your-host = nixpkgs.lib.nixosSystem {
+      modules = [
+        tailscale-manager.nixosModules.default
+        ./configuration.nix
+      ];
+    };
+  };
+}
+```
+
+### 2. Create an OAuth client
+
+1. Go to https://login.tailscale.com/admin/settings/oauth
+2. Create a client with **all** (read + write) scopes
+3. Under **Tag ownership**, add the tags this client can create keys with
+   (e.g. `tag:ci`, `tag:infra`)
+4. Save the client ID and secret
+
+### 3. Configure the module
+
+```nix
+# configuration.nix
+{ config, ... }: {
+
+  services.tailscale-manager = {
+    enable = true;
+    tailnet = "-";                              # auto-resolve from OAuth
+    credentialsFile = "/run/secrets/tailscale-oauth";
+    tags = [ "tag:ci" ];
+  };
+}
+```
+
+### 4. Deploy
+
+```bash
+nixos-rebuild switch
+```
+
+On first deploy, the service will:
+1. Back up any existing tfstate (none on first run)
+2. Generate `main.tf.json` 
+3. Run `terraform init` (downloads the Tailscale provider)
+4. Run `terraform apply` (creates the auth key)
+5. Write the result to `last-apply.json`
+
+Every subsequent `nixos-rebuild switch` repeats steps 1–5. If a key has
+expired, `recreate_if_invalid = "always"` causes Terraform to delete it
+and create a new one — **automatic rotation with zero custom logic.**
+
+---
+
+## NixOS module reference
+
+All options under `services.tailscale-manager`.
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `enable` | `bool` | `false` | Enable the tailscale-manager service |
+| `tailnet` | `string` | *(required)* | Tailnet name, e.g. `example.com`. Pass `"-"` to auto-resolve from the OAuth credential. |
+| `credentialsFile` | `path` | *(required)* | Path to an EnvironmentFile containing `TAILSCALE_OAUTH_CLIENT_ID` and `TAILSCALE_OAUTH_CLIENT_SECRET`. Encrypt with agenix or sops-nix. |
+| `tags` | `list of strings` | `[]` | Tags to apply to the managed auth key (e.g. `["tag:ci"]`). The OAuth client must own these tags. |
+| `stateDir` | `string` | `/var/lib/tailscale-manager` | Directory for Terraform state and backups |
+| `package` | `package` | `pkgs.tailscale-manager` | Package providing the CLI |
+| `terraformBin` | `path` | `"${pkgs.terraform}/bin/terraform"` | Path to the Terraform binary |
+| `backupCount` | `int` | `5` | Number of tfstate backups to retain in `stateDir/backups/` |
+| `watchCredentials` | `bool` | `true` | Create a systemd path unit that re-runs apply when `credentialsFile` changes |
+
+### Systemd units
+
+Three units are created when enabled:
+
+**`tailscale-manager.service`** — `Type=oneshot`, runs on every
+`nixos-rebuild switch` (via `wantedBy = ["multi-user.target"]`):
+1. Backs up `terraform.tfstate` to `backups/<timestamp>.tfstate`
+2. Prunes old backups to `backupCount`
+3. Generates `main.tf.json`
+4. Runs `terraform init`
+5. Runs `terraform apply -auto-approve`
+6. Writes result to `last-apply.json`
+7. On failure: restores the most recent backup, writes error to
+   `last-apply.json`, exits 1 (systemd shows red)
+
+**`tailscale-manager-watch.path`** — if `watchCredentials = true`:
+writes the file path changes. Re-triggers the service when
+`credentialsFile` changes via atomic rename (e.g. agenix rotation).
+
+**`tailscale-manager.timer`** — placeholder (commented out). Uncomment
+and configure `OnCalendar` for periodic apply if desired.
+
+### Activation script
+
+After every `nixos-rebuild switch`, the system prints:
+```
+tailscale-manager: last apply [ok]
+```
+or:
+```
+tailscale-manager: last apply [error]
+```
+This is informational only — does not trigger re-apply.
+
+---
+
+## Home Manager module
+
+For user-level CLI install without systemd service:
+
+```nix
+{ config, ... }: {
+
+  homeManagerModules.tailscale-manager = {
+    enable = true;
+    tailnet = "-";
+    credentialsFile = "/run/secrets/tailscale-oauth";
+  };
+}
+```
+
+Options: `enable`, `package`, `tailnet`, `credentialsFile`.
+
+---
+
+## Credential setup
+
+The credentials file must be an EnvironmentFile (KEY=VAL format) containing:
+
+```
+TAILSCALE_OAUTH_CLIENT_ID=<your-client-id>
+TAILSCALE_OAUTH_CLIENT_SECRET=<your-client-secret>
+```
+
+### With agenix
+
+```nix
+# secrets.nix
+{
+  "tailscale-oauth.age".publicKeys = [ <your-host-key> ];
+}
+```
+
+```nix
+# configuration.nix
+age.secrets.tailscale-oauth = {
+  file = ./secrets/tailscale-oauth.age;
+};
+
+services.tailscale-manager = {
+  enable = true;
+  tailnet = "-";
+  credentialsFile = config.age.secrets.tailscale-oauth.path;
+  tags = [ "tag:ci" ];
+};
+```
+
+The path watcher automatically re-runs apply when agenix rotates the file.
+
+### With sops-nix
+
+```nix
+sops.secrets.tailscale-oauth = {
+  format = "dotenv";
+  sopsFile = ./secrets/tailscale-oauth.env;
+};
+
+services.tailscale-manager = {
+  enable = true;
+  tailnet = "-";
+  credentialsFile = config.sops.secrets.tailscale-oauth.path;
+  tags = [ "tag:ci" ];
+};
+```
+
+---
+
+## CLI reference
+
+```console
+tailscale-manager init          # terraform init + provider download
+tailscale-manager plan          # terraform plan (shows pending changes)
+tailscale-manager apply         # backup → generate → init → apply
+tailscale-manager destroy       # backup → terraform destroy
+tailscale-manager status        # read-only TUI dashboard
+tailscale-manager status --json # JSON for scripting
+tailscale-manager backup-state  # manual tfstate backup
+tailscale-manager restore-state # manual tfstate restore
+tailscale-manager version       # show version
+```
+
+### Environment variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `TAILSCALE_OAUTH_CLIENT_ID` | ✅ | — | Tailscale OAuth client ID |
+| `TAILSCALE_OAUTH_CLIENT_SECRET` | ✅ | — | Tailscale OAuth client secret |
+| `TAILSCALE_TAILNET` | ✅ | — | Tailnet name or `"-"` to auto-resolve |
+| `TAILSCALE_MANAGER_STATE_DIR` | — | `/var/lib/tailscale-manager` | State and backup directory |
+| `TAILSCALE_MANAGER_TERRAFORM_BIN` | — | `terraform` | Terraform binary path |
+| `TAILSCALE_MANAGER_BACKUP_COUNT` | — | `5` | Number of backups to retain |
+| `TAILSCALE_MANAGER_TAGS` | — | `""` | Comma-separated tags, e.g. `tag:ci,tag:infra` |
+
+### Exit codes
+
+| Command | Exit 0 | Exit 1 |
+|---|---|---|
+| `apply` | Key created/updated | Apply failed (error in `last-apply.json`) |
+| `destroy` | Key destroyed | Destroy failed |
+| `status --json` | Last result was `ok` | Last result was `error` |
+| `plan` | No changes (or changes pending) | Plan failed |
+
+Exit code 2 from `terraform plan -detailed-exitcode` (non-empty diff) is
+treated as success — it means there are changes to apply, not an error.
+
+### last-apply.json schema
+
+Written to `stateDir/last-apply.json` after every apply:
+
+```json
+{
+  "timestamp": "2026-05-31T00:00:00.000000+00:00",
+  "result": "ok"
+}
+```
+
+On failure:
+
+```json
+{
+  "timestamp": "2026-05-31T00:00:00.000000+00:00",
+  "result": "error",
+  "error_message": "terraform apply ... failed (exit 1):\nError creating tailnet key: ..."
+}
+```
+
+---
+
+## Failure handling & recovery
+
+```mermaid
+flowchart TD
+    A[nixos-rebuild switch] --> B[Backup tfstate]
+    B --> C[Generate main.tf.json]
+    C --> D[terraform init]
+    D --> E[terraform apply]
+    E --> F{Success?}
+    F -->|Yes| G[Write last-apply.json]
+    F -->|No| H[Restore backup]
+    H --> I[Write error to last-apply.json]
+    I --> J[Exit 1 — systemd shows red]
+    G --> K[Exit 0]
+```
+
+Key guarantees:
+- **Before every mutation**: tfstate is backed up to `backups/<timestamp>.tfstate`
+- **On any failure**: the most recent backup is restored, leaving state exactly
+  as it was before the apply
+- **Monitoring surface**: `last-apply.json` is the single source of truth for
+  the last operation's result. The TUI, `status --json`, and activation script
+  all read from it.
+- **Systemd visibility**: non-zero exit code means `systemctl status
+  tailscale-manager` shows red on failure. The error message is in the
+  journal and `last-apply.json`.
+
+---
+
+## Key rotation strategy
+
+This project does **not** implement custom key rotation logic. Instead, it
+relies on a single Terraform attribute:
+
+```json
+"recreate_if_invalid": "always"
+```
+
+When a key expires, Terraform detects it as "invalid" and replaces it on the
+next apply — deleting the old resource and creating a new one. This means:
+
+- No cron jobs, no expiry date tracking, no manual intervention
+- The rotation happens on the next `nixos-rebuild switch` or credential
+  watcher trigger after expiry
+- The key `id` changes (it's a new key), so any system that consumes the
+  key value needs to re-read it from Terraform state or the Tailscale admin
+  console
+
+Key defaults: `reusable = true`, `ephemeral = false`, `preauthorized = true`,
+`expiry` = 90 days (Tailscale default, configurable in the provider).
+
+---
+
+## TUI (optional)
+
+Install with `uv add textual` or enable the `tui` extra, then run
+`tailscale-manager status`.
+
+```
+┌─────────────────────────────────────────┐
+│  Tailscale Manager — your-tailnet.ts.net│
+├────────────────┬────────────────────────┤
+│ KEY STATUS     │  SYSTEM STATUS         │
+│                │                        │
+│ DataTable:     │  Last apply: 2026-...  │
+│  ✓ k123 — ci  │  Result: ✓ ok          │
+│                │  Terraform state: found│
+│                │  Credentials: found    │
+│                │  Backups: 3 retained   │
+│                │                        │
+│                │  State dir: /var/lib/..│
+│                │  Tailnet: your-tailnet │
+└────────────────┴────────────────────────┘
+│  Q: Quit  R: Refresh  L: View Logs      │
+└─────────────────────────────────────────┘
+```
+
+- **Left panel**: DataTable of managed auth keys from local tfstate
+- **Right panel**: System status (last apply, backups, credentials)
+- **Footer**: Q=Quit, R=Refresh (or auto-refresh every 30s), L=View Logs
+  (tails `journalctl -u tailscale-manager.service`)
+- **Read-only**: zero write operations from the UI
+
+---
+
+## Waybar / scripting integration
+
+```json
+{
+  "custom/tailscale-manager": {
+    "exec": "tailscale-manager status --json",
+    "return-type": "json",
+    "format": "{}"
+  }
+}
+```
+
+The `status --json` command exits 0 on success, 1 on failure, and outputs:
+
+```json
+{
+  "last_apply": {
+    "timestamp": "2026-05-31T00:00:00+00:00",
+    "result": "ok"
+  },
+  "managed_keys": [
+    {
+      "id": "k123abc",
+      "description": "ci runner key",
+      "tags": ["tag:ci"],
+      "revoked": false
+    }
+  ]
+}
+```
+
+For Prometheus node_exporter textfile collector:
+
+```bash
+#!/bin/sh
+# /etc/periodic/tailscale-manager-metrics
+STATUS=$(tailscale-manager status --json 2>/dev/null) || STATUS='{"result":"error"}'
+RESULT=$(echo "$STATUS" | jq -r '.last_apply.result // "unknown"')
+COUNT=$(echo "$STATUS" | jq '.managed_keys | length')
+cat > /var/lib/node_exporter/textfile/tailscale-manager.prom <<EOF
+# HELP tailscale_manager_last_apply Last apply result (1=ok, 0=error)
+# TYPE tailscale_manager_last_apply gauge
+tailscale_manager_last_apply $([ "$RESULT" = "ok" ] && echo 1 || echo 0)
+# HELP tailscale_manager_managed_keys Number of managed auth keys
+# TYPE tailscale_manager_managed_keys gauge
+tailscale_manager_managed_keys $COUNT
+EOF
+```
+
+---
+
+## Development
+
+```bash
+# Enter the dev environment
+nix develop
+
+# Fast environment (lint/typecheck only)
+nix develop .#bootstrap
+
+# Add a dependency
+nix develop .#bootstrap
+uv add <package>
+
+# Lint
+ruff check src/
+
+# Type check
+mypy src/tailscale_manager/
+
+# Test
+pytest tests/unit/ -v
+
+# Build
+nix build .#default
+
+# Full check
+nix flake check
+```
+
+See `CONTRIBUTING.md` for pull request workflow.
+
+---
+
+## Architecture
+
+```
+pyproject.toml  ──uv add/lock──►  uv.lock
+                                      │
+                                      ▼
+flake.nix  ──workspace.mkPyprojectOverlay──►  Nix overlay
+ │                                                 │
+ │  pyproject-build-systems ───────────────────────┤
+ │                                                 │
+ └── composeManyExtensions ───────────────────────► pythonSet
+                                                           │
+                                               ┌───────────┼───────────────────┐
+                                               ▼           ▼                   ▼
+                                    nix/default.nix   nix/devshell.nix    nix/module.nix
+                                    (mkApplication)   (mkShell)           (systemd service)
+```
+
+The project uses [uv2nix](https://github.com/pyproject-nix/uv2nix) to convert
+`uv.lock` into Nix package derivations. The NixOS module provides the systemd
+service, credential watcher, and activation hook. The Python CLI wraps the
+`terraform` binary — the Tailscale provider does all the actual API work.
+
+**Package layers** (import direction rules):
+
+```
+src/tailscale_manager/
+├── core/           imports nothing from the package
+├── models/         pure data shapes
+├── services/       imports models/ and repositories/
+├── repositories/   data access (tfstate I/O)
+├── utils/          stateless pure functions
+└── cli.py          Typer entrypoint (imports services/)
+```
+
+---
+
+## Common issues
+
+- **"tailnet-owned auth key must have tags set"** — the OAuth client needs
+  tag ownership configured. See [OAuth tag
+  ownership](https://tailscale.com/kb/1215/oauth-clients).
+- **"requested tags are invalid or not permitted"** — same cause. Add the
+  tags to the OAuth client's tag ownership list in the admin console.
+- **Provider download fails on first run** — `terraform init` needs outbound
+  internet to `registry.terraform.io`. See `GOTCHAS.md` for airgap workarounds.
+- **`terraform` binary not found** — the module sets `terraformBin` to
+  `${pkgs.terraform}/bin/terraform` by default. When running the CLI outside
+  the NixOS service, ensure terraform is in PATH or set
+  `TAILSCALE_MANAGER_TERRAFORM_BIN`.
+
+For a full list of gotchas, see [`GOTCHAS.md`](./GOTCHAS.md).
+
+---
+
+## Related resources
+
+- [Tailscale Terraform provider docs](https://registry.terraform.io/providers/tailscale/tailscale)
+- [Tailscale OAuth client docs](https://tailscale.com/kb/1215/oauth-clients)
+- [Tailscale Terraform provider source](https://github.com/tailscale/terraform-provider-tailscale)
+- [uv2nix docs](https://pyproject-nix.github.io/uv2nix/)

tailscale_manager-0.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+tailscale_manager/__init__.py,sha256=hY2Q7RAVyihDYp28CzQnwMZErjdXvu3jU7nxsuE5B-c,89
+tailscale_manager/cli.py,sha256=o8kznIQNs5p4F6iAkRGw-FTm7EiSQadEHVYWgIaUqPU,4224
+tailscale_manager/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tailscale_manager/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tailscale_manager/core/config.py,sha256=5a-N2d0DGHo9aDFG_BVsov4I442zJwqXs3PCOyRgQuM,2005
+tailscale_manager/core/constants.py,sha256=BsscnytMNAfcvQD84UCCvvIXPGOQ3diY3ynjO2ZvRkk,314
+tailscale_manager/core/exceptions.py,sha256=623cWjre89KBKGdGGdaUIZpCIcemjwr6Qyl7lndHHEo,271
+tailscale_manager/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tailscale_manager/models/auth_key.py,sha256=JQwQAxG91LEdPW4_BSVDaSSbcV_F2udeAey6dDOUFmc,439
+tailscale_manager/repositories/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tailscale_manager/repositories/state_repository.py,sha256=aUiqKuTa2sqdaSnPb7hOptTJ8PEffMMQRMCX3fgwjU8,2351
+tailscale_manager/services/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tailscale_manager/services/terraform_service.py,sha256=OjjwlazXpEAhd7FbQOPeip-j3R-KzuhxykNH7nLGF5g,5031
+tailscale_manager/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tailscale_manager/utils/subprocess_helpers.py,sha256=JDYbYS4QF_qq5qoM3uby8Ezx0ySu9WzVK2T_TofCkb8,1397
+textual_ui/__init__.py,sha256=4eTXG8M8e8rOYlY2bUFZkfQ3g0S7BgMCIHpaa7CeKyY,116
+textual_ui/app.py,sha256=c5z0WwGCJKn37uQ3kE5UXjJFDhT3ZCnv7Sx5ZnSNXPk,5897
+textual_ui/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tailscale_manager-0.1.0.dist-info/METADATA,sha256=JRwq_b2tpwaNmoLtRdOMwvjjLGQGomgiU-XZhZcWP14,17595
+tailscale_manager-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+tailscale_manager-0.1.0.dist-info/entry_points.txt,sha256=KOyFwHQJy6hwvOv29J1s1cZg2IFKnhAIDYupykTdVq8,64
+tailscale_manager-0.1.0.dist-info/top_level.txt,sha256=RErty97X5XN6v1YYarg1pcO4C4rnUeqlBS-cPW2DeZc,29
+tailscale_manager-0.1.0.dist-info/RECORD,,

tailscale_manager-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tailscale_manager-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tailscale-manager = tailscale_manager.cli:app

tailscale_manager-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+tailscale_manager
+textual_ui

textual_ui/__init__.py

@@ -0,0 +1,3 @@
+from textual_ui.app import TailscaleManagerApp, run_status_app
+
+__all__ = ["TailscaleManagerApp", "run_status_app"]

textual_ui/app.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+import os
+import subprocess
+
+from textual.app import App as TextualAppBase
+from textual.app import ComposeResult
+from textual.containers import Horizontal, Vertical
+from textual.screen import Screen
+from textual.widgets import DataTable, Footer, Header, Static, TextArea
+
+from tailscale_manager.core.config import AppConfig
+from tailscale_manager.models.auth_key import TailscaleAuthKey
+from tailscale_manager.repositories.state_repository import StateRepository
+
+
+def run_status_app(
+    config: AppConfig,
+    keys: list[TailscaleAuthKey],
+    last_apply: dict | None,
+) -> None:
+    app = TailscaleManagerApp(config, keys, last_apply)
+    app.run()
+
+
+class SystemStatus(Static):
+    config: AppConfig
+    last_apply: dict | None
+
+    def __init__(
+        self,
+        config: AppConfig,
+        last_apply: dict | None,
+    ) -> None:
+        super().__init__()
+        self.config = config
+        self.last_apply = last_apply
+
+    def on_mount(self) -> None:
+        self.refresh_content()
+
+    def refresh_content(self) -> None:
+        repo = StateRepository(self.config.state_dir)
+        last = repo.read_last_apply()
+        if last:
+            self.last_apply = last
+
+        lines: list[str] = []
+        lines.append("[bold]System Status[/bold]")
+        lines.append("")
+
+        if self.last_apply:
+            ts = self.last_apply.get("timestamp", "unknown")
+            result = self.last_apply.get("result", "unknown")
+            icon = "✓" if result == "ok" else "✗"
+            ts_str = str(ts)[:19] if not isinstance(ts, str) else ts[:19]
+            lines.append(f"Last apply: {ts_str}")
+            lines.append(f"  Result: {icon} {result}")
+            err = self.last_apply.get("error_message")
+            if err:
+                lines.append(f"  Error: {str(err)[:80]}")
+        else:
+            lines.append("Last apply: never")
+
+        lines.append("")
+        state_file = self.config.state_dir / "terraform.tfstate"
+        tf_found = "found" if state_file.exists() else "not found"
+        lines.append(f"Terraform state: {tf_found}")
+
+        has_id = bool(os.environ.get("TAILSCALE_OAUTH_CLIENT_ID"))
+        has_secret = bool(os.environ.get("TAILSCALE_OAUTH_CLIENT_SECRET"))
+        creds_status = "found" if has_id and has_secret else "not set"
+        lines.append(f"Credentials: {creds_status}")
+
+        backup_dir = self.config.state_dir / "backups"
+        if backup_dir.exists():
+            bcount = len(list(backup_dir.glob("*.tfstate")))
+        else:
+            bcount = 0
+        lines.append(f"Backups: {bcount} retained")
+
+        lines.append("")
+        lines.append(f"State dir: {self.config.state_dir}")
+        lines.append(f"Tailnet: {self.config.tailnet}")
+        self.update("\n".join(lines))
+
+
+class LogViewer(Screen):
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield TextArea("Loading logs...", read_only=True)
+        yield Footer()
+
+    BINDINGS = [("escape", "dismiss", "Back")]
+
+    def on_mount(self) -> None:
+        try:
+            result = subprocess.run(
+                ["journalctl", "-u", "tailscale-manager.service", "--no-pager", "-n", "30"],
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+            content = result.stdout or "No logs found"
+        except (subprocess.TimeoutExpired, FileNotFoundError):
+            content = "Unable to fetch logs"
+        ta = self.query_one(TextArea)
+        ta.text = content
+
+
+class TailscaleManagerApp(TextualAppBase):
+    CSS = """
+    Screen {
+        layout: horizontal;
+    }
+
+    .left-panel {
+        width: 60%;
+        height: 100%;
+        border: solid $primary;
+        padding: 0 1;
+    }
+
+    .right-panel {
+        width: 40%;
+        height: 100%;
+        border: solid $primary;
+        padding: 0 1;
+    }
+    """
+
+    BINDINGS = [
+        ("q", "quit", "Quit"),
+        ("r", "refresh", "Refresh"),
+        ("l", "view_logs", "View Logs"),
+    ]
+
+    def __init__(
+        self,
+        config: AppConfig,
+        keys: list[TailscaleAuthKey],
+        last_apply: dict | None,
+    ) -> None:
+        super().__init__()
+        self.app_config = config
+        self.initial_keys = keys
+        self.initial_last_apply = last_apply
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        with Horizontal():
+            with Vertical(classes="left-panel"):
+                yield DataTable(id="keys-table")
+            with Vertical(classes="right-panel"):
+                yield SystemStatus(self.app_config, self.initial_last_apply)
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self.title = f"Tailscale Manager — {self.app_config.tailnet}"
+        self._populate_table(self.initial_keys)
+        self.set_interval(30, self.action_refresh)
+
+    def _populate_table(self, keys: list[TailscaleAuthKey]) -> None:
+        table = self.query_one("#keys-table", DataTable)
+        table.clear(columns=True)
+        table.add_columns("ID", "Description", "Tags", "Expiry", "Status")
+        for k in keys:
+            status = "✓" if not k.revoked else "✗"
+            expiry = k.expiry.strftime("%Y-%m-%d") if k.expiry else "-"
+            tags = ", ".join(k.tags) if k.tags else "-"
+            table.add_row(
+                k.id[:16] if k.id else "-",
+                k.description or "-",
+                tags,
+                expiry,
+                status,
+            )
+        if not keys:
+            table.add_row("(no keys managed)", "", "", "", "")
+
+    def action_refresh(self) -> None:
+        repo = StateRepository(self.app_config.state_dir)
+        keys = repo.get_managed_keys()
+        self._populate_table(keys)
+        sys_panel = self.query_one(SystemStatus)
+        sys_panel.refresh_content()
+
+    def action_view_logs(self) -> None:
+        self.push_screen(LogViewer())