docs: consolidate historical records and verify public manual publication

2026-09-15 14:37:29 +02:00
parent 5f3a7f5975
commit 4ff91e8d6e
63 changed files with 633 additions and 6598 deletions
@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""Mutation fixtures for current auth/DWH documentation; never contacts services."""
+import importlib.util
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+SCRIPT = ROOT / "scripts/verify-auth-docs.py"
+spec = importlib.util.spec_from_file_location("authdocs", SCRIPT)
+module = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(module)
+mode = sys.argv[1] if len(sys.argv) > 1 else "auth"
+assert mode in ("auth", "dwh")
+relative = next(iter(module.AUTH if mode == "auth" else module.DWH))
+
+with tempfile.TemporaryDirectory(prefix="thoth-auth-docs-") as tmp:
+    fixture = Path(tmp)
+    shutil.copytree(ROOT / "docs", fixture / "docs")
+    for item in ROOT.glob("*.md"):
+        shutil.copy2(item, fixture / item.name)
+    target = fixture / relative
+    original = target.read_text()
+
+    def check(expected=None):
+        result = subprocess.run([sys.executable, str(SCRIPT), mode, "--root", tmp], capture_output=True, text=True)
+        if expected is None:
+            assert result.returncode == 0, result.stderr
+        else:
+            assert result.returncode != 0 and expected in result.stderr, result.stderr
+
+    check()
+    mutations = [
+        ("curl -k https://example.invalid", "TLS bypass"),
+        ("curl --insecure https://example.invalid", "TLS bypass"),
+        ("verify_tls=false", "TLS bypass"),
+        ("DWH_API_KEY=synthetic", "raw environment secret"),
+        ('curl -H "X-API-Key: synthetic" https://example.invalid', "raw key header"),
+        ("tht auth user add demo --password synthetic", "secret argument"),
+        ("password: synthetic", "plaintext password"),
+        ("chmod 644 /protected/demo.key", "world-readable secret"),
+        ("sudo nginx -T", "raw nginx capture"),
+        ("git diff /protected/secret", "raw diff capture"),
+        ("docker compose up dwh-auth", "Compose coupling"),
+        ("thtdwh_v1." + "a" * 16 + "." + "b" * 43, "credential literal"),
+        ("secret_sha256: " + "a" * 64, "credential digest"),
+        ("auth-canonical:/run/thothii-auth:ro", "canonical auth root"),
+        ("useradd --uid 10001 core", "host runtime identity"),
+        ("nano /protected/generations/one/auth.yaml", "direct auth projection edit"),
+    ]
+    for snippet, error in mutations:
+        target.write_text(original + "\n```sh\n" + snippet + "\n```\n")
+        check(error)
+    target.write_text(original + '\nDo not use `curl -k`.\n```sh\nDWH_API_KEY_FILE=/protected/demo.key\n```\n')
+    check()
+    if mode == "auth":
+        target.write_text(original.replace("`memory.manage`, ", ""))
+        check("role-to-permission")
+        target.write_text(original.replace("auth_ready\n", "auth_unknown\n"))
+        check("diagnostic code")
+    target.write_text(original + "\n[broken](missing-file.md)\n")
+    check("broken local link")
+    target.unlink()
+    check("missing")
+print(f"{mode} documentation mutation fixtures passed")