python-cad-tools 0.1.0rc1__py3-none-any.whl

python_cad_tools/site.py

@@ -0,0 +1,676 @@
+"""Strict, Node-free viewer-site preparation and local HTTP serving."""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import http.server
+import ipaddress
+import json
+import os
+import re
+import shutil
+import signal
+import socket
+import tempfile
+import threading
+import unicodedata
+import urllib.parse
+import uuid
+from collections.abc import Iterator
+from dataclasses import asdict, dataclass
+from importlib import metadata, resources
+from pathlib import Path, PurePosixPath
+from typing import Any, Literal, cast
+
+from .artifacts import ArtifactRecord, get_package_build_info, load_design_manifest, verify_build_output
+from .determinism import canonical_json_bytes, sha256_file
+from .exceptions import ArtifactIntegrityError, BuildLockedError, SiteError, UnsafePathError
+from .project_config import load_project_config, output_path, resolve_project_root
+
+DOWNLOAD_SCHEMA = "urn:python-cad-tools:schema:download-manifest:2"
+SITE_SCHEMA = "urn:python-cad-tools:schema:site-metadata:1"
+ASSET_SCHEMA = "urn:python-cad-tools:schema:viewer-assets:1"
+_HEX = re.compile(r"[0-9a-f]{64}\Z")
+_SITE_FIELDS = {
+    "schema_id", "schema_version", "managed_by", "tool_version", "project_id", "design_build_hash", "base_path",
+    "destination_path_sha256", "viewer_shell_sha256", "download_manifest_sha256", "managed_inventory",
+}
+_INVENTORY_FIELDS = {"path", "size", "sha256", "media_type", "owner"}
+
+
+@dataclass(frozen=True, slots=True)
+class SiteEntry:
+    source_path: str
+    site_path: str
+    kind: str
+    media_type: str
+    size: int
+    sha256: str
+    viewer_loadable: bool
+    downloadable: bool
+
+
+@dataclass(frozen=True, slots=True)
+class ManagedSiteFile:
+    path: str
+    size: int
+    sha256: str
+    media_type: str
+    owner: Literal["viewer_shell", "generated_artifact", "site_document"]
+
+
+@dataclass(frozen=True, slots=True)
+class PreparedSite:
+    destination: Path
+    base_path: str
+    project_id: str
+    design_build_hash: str
+    viewer_shell_sha256: str
+    download_manifest_sha256: str
+    file_count: int
+
+
+@dataclass(frozen=True, slots=True)
+class ServerResult:
+    url: str
+    interrupted: bool
+
+
+_ALLOWLIST: tuple[tuple[re.Pattern[str], str, str, bool, bool], ...] = (
+    (re.compile(r"glb/[^/]+\.glb\Z"), "glb", "model/gltf-binary", True, True),
+    (re.compile(r"glb/manifest\.json\Z"), "glb_manifest", "application/json", True, False),
+    (re.compile(r"step/[^/]+\.step\Z"), "step", "model/step", False, True),
+    (re.compile(r"step/validation\.json\Z"), "step_validation", "application/json", False, False),
+    (re.compile(r"ifc/[^/]+\.ifc\Z"), "ifc", "application/x-step", False, True),
+    (re.compile(r"ifc/validation\.json\Z"), "ifc_validation", "application/json", False, False),
+    (re.compile(r"drawings/svg/[^/]+\.svg\Z"), "drawing_svg", "image/svg+xml", True, True),
+    (re.compile(r"drawings/dxf/[^/]+\.dxf\Z"), "drawing_dxf", "image/vnd.dxf", False, True),
+    (re.compile(r"drawings/pdf/[^/]+\.pdf\Z"), "drawing_pdf", "application/pdf", True, True),
+    (re.compile(r"drawings/annotation-manifest\.json\Z"), "annotation_manifest", "application/json", True, False),
+    (re.compile(r"quantities/quantities\.json\Z"), "quantity_json", "application/json", True, True),
+    (re.compile(r"quantities/(?:materials|quantities)\.csv\Z"), "quantity_csv", "text/csv; charset=utf-8", False, True),
+    (re.compile(r"quantities/summary\.md\Z"), "quantity_markdown", "text/markdown; charset=utf-8", False, True),
+    (re.compile(r"manifests/design-manifest\.json\Z"), "design_manifest", "application/json", True, False),
+    (re.compile(r"manifests/build-manifest\.json\Z"), "build_manifest", "application/json", True, False),
+)
+
+
+def normalize_base_path(value: str) -> str:
+    """Validate and normalize a root or absolute deployment base path."""
+    if value == "/":
+        return value
+    if not isinstance(value, str) or not value.startswith("/") or not value.endswith("/"):
+        raise SiteError("Base path must have one leading and trailing slash")
+    if "\\" in value or "?" in value or "#" in value or ":" in value or "//" in value:
+        raise SiteError(f"Unsafe base path: {value!r}")
+    try:
+        decoded = urllib.parse.unquote(value, errors="strict")
+    except UnicodeError as error:
+        raise SiteError(f"Unsafe base path: {value!r}") from error
+    if decoded != value or any(part in {"", ".", ".."} for part in value[1:-1].split("/")):
+        raise SiteError(f"Unsafe base path: {value!r}")
+    return value
+
+
+def destination_identity(destination: Path) -> tuple[Path, str]:
+    resolved = destination.expanduser().resolve(strict=False)
+    normalized = unicodedata.normalize("NFC", os.path.normcase(str(resolved)))
+    if resolved.anchor and normalized != resolved.anchor:
+        normalized = normalized.rstrip(os.sep)
+    return resolved, hashlib.sha256(normalized.encode("utf-8")).hexdigest()
+
+
+def prepare_site(project_root: Path, destination: Path, base_path: str = "/") -> PreparedSite:
+    """Verify generated artifacts and atomically replace a managed viewer site."""
+    root = resolve_project_root(project_root)
+    config = load_project_config(root)
+    output = output_path(root, config)
+    base = normalize_base_path(base_path)
+    target, identity = destination_identity(destination)
+    _validate_destination(root, output, target)
+    target.parent.mkdir(parents=False, exist_ok=True)
+    with _destination_lock(target.parent, identity):
+        _recover_site_transaction(target, identity)
+        _validate_destination(root, output, target)
+        verification = verify_build_output(root)
+        design = load_design_manifest(output / "manifests/design-manifest.json")
+        project_id = str(design["model_id"])
+        _validate_existing_site(target, identity, project_id)
+        entries, omitted = _site_entries(output, verification.artifacts)
+        shell, viewer_hash = _viewer_shell()
+        version = metadata.version("python-cad-tools")
+        download = {
+            "schema_id": DOWNLOAD_SCHEMA,
+            "schema_version": 2,
+            "generator_distribution": "python-cad-tools",
+            "generator_version": version,
+            "project_id": project_id,
+            "design_build_hash": verification.stable_artifact_set_hash,
+            "base_path": base,
+            "entries": [asdict(entry) for entry in entries],
+            "omitted": omitted,
+        }
+        download_bytes = _canonical_json(download)
+        download_hash = _sha256_bytes(download_bytes)
+        _check_site_collisions(shell, entries)
+        prepared = _stage_site(
+            target=target,
+            identity=identity,
+            output=output,
+            shell=shell,
+            entries=entries,
+            download_bytes=download_bytes,
+            project_id=project_id,
+            design_build_hash=verification.stable_artifact_set_hash,
+            base_path=base,
+            viewer_shell_sha256=viewer_hash,
+            download_manifest_sha256=download_hash,
+            tool_version=version,
+        )
+        _promote_site(target, identity, prepared)
+        metadata_value = _verify_managed_site(target, identity, project_id)
+        return PreparedSite(
+            destination=target,
+            base_path=base,
+            project_id=project_id,
+            design_build_hash=verification.stable_artifact_set_hash,
+            viewer_shell_sha256=viewer_hash,
+            download_manifest_sha256=download_hash,
+            file_count=len(cast(list[Any], metadata_value["managed_inventory"])) + 1,
+        )
+
+
+def serve_project(
+    project_root: Path,
+    *,
+    host: str = "127.0.0.1",
+    port: int = 8000,
+    build: bool = False,
+    allow_unsafe_bind: bool = False,
+) -> ServerResult:
+    """Prepare an ephemeral verified site and serve it until interrupted."""
+    if not 0 <= port <= 65535:
+        raise SiteError(f"Invalid port: {port}")
+    if not _is_loopback(host) and not allow_unsafe_bind:
+        raise SiteError(f"Refusing non-loopback host {host!r}; pass --allow-unsafe-bind to opt in")
+    root = resolve_project_root(project_root)
+    if build:
+        from .build import BuildOptions, build_project
+
+        build_project(BuildOptions(root))
+    with tempfile.TemporaryDirectory(prefix="python-cad-site-") as directory:
+        prepared = prepare_site(root, Path(directory) / "site")
+        return serve_prepared_site(prepared.destination, host=host, port=port, allow_unsafe_bind=allow_unsafe_bind)
+
+
+def serve_prepared_site(site_root: Path, *, host: str = "127.0.0.1", port: int = 8000, allow_unsafe_bind: bool = False) -> ServerResult:
+    """Serve an already prepared, independently verified managed site."""
+    if not _is_loopback(host) and not allow_unsafe_bind:
+        raise SiteError(f"Refusing non-loopback host {host!r}; explicit opt-in is required")
+    root = site_root.resolve()
+    site = _verify_managed_site(root)
+    handler = _handler(root, site)
+    try:
+        server = http.server.ThreadingHTTPServer((host, port), handler)
+    except OSError as error:
+        raise SiteError(f"Unable to bind {host}:{port}: {error}") from error
+    server.daemon_threads = True
+    server.timeout = 0.2
+    actual_host, actual_port = cast(tuple[str, int], server.server_address[:2])
+    display_host = f"[{actual_host}]" if ":" in actual_host else actual_host
+    url = f"http://{display_host}:{actual_port}{site['base_path']}"
+    print(f"READY {url}", flush=True)
+    stopped = threading.Event()
+    previous: dict[signal.Signals, Any] = {}
+
+    def stop(_signum: int, _frame: Any) -> None:
+        stopped.set()
+
+    if threading.current_thread() is threading.main_thread():
+        for signum in (signal.SIGINT, signal.SIGTERM):
+            previous[signum] = signal.getsignal(signum)
+            signal.signal(signum, stop)
+    try:
+        while not stopped.is_set():
+            server.handle_request()
+    finally:
+        server.server_close()
+        for signum, callback in previous.items():
+            signal.signal(signum, callback)
+    return ServerResult(url=url, interrupted=stopped.is_set())
+
+
+def _site_entries(output: Path, records: tuple[ArtifactRecord, ...]) -> tuple[tuple[SiteEntry, ...], list[dict[str, str]]]:
+    all_records = list(records)
+    build_path = output / "manifests/build-manifest.json"
+    all_records.append(ArtifactRecord(
+        path="manifests/build-manifest.json", size=build_path.stat().st_size, sha256=sha256_file(build_path),
+        media_type="application/json", producer="python-cad-tools",
+        schema_id="urn:python-cad-tools:schema:build-manifest:1", schema_version=1, volatile=False,
+    ))
+    entries: list[SiteEntry] = []
+    omitted: list[dict[str, str]] = []
+    seen: set[str] = set()
+    for record in sorted(all_records, key=lambda item: item.path):
+        if record.path in seen:
+            raise ArtifactIntegrityError(f"Duplicate site source path: {record.path}")
+        seen.add(record.path)
+        if record.path == "manifests/run-metadata.json":
+            omitted.append({"source_path": record.path, "reason": "volatile_run_metadata"})
+            continue
+        if record.path == ".gitkeep":
+            omitted.append({"source_path": record.path, "reason": "non_web_anchor"})
+            continue
+        rule = next((value for value in _ALLOWLIST if value[0].fullmatch(record.path)), None)
+        if rule is None:
+            raise SiteError(f"Generated artifact is not allowed in a viewer site: {record.path}")
+        _, kind, media_type, viewer_loadable, downloadable = rule
+        if record.media_type != media_type:
+            raise SiteError(f"Artifact media type mismatch for {record.path}: expected {media_type}, got {record.media_type}")
+        entries.append(SiteEntry(record.path, f"artifacts/{record.path}", kind, media_type, record.size, record.sha256, viewer_loadable, downloadable))
+    if sum(entry.kind == "glb" for entry in entries) != 1:
+        raise SiteError("A prepared site requires exactly one manifest-listed GLB")
+    required = {"glb_manifest", "design_manifest", "build_manifest"}
+    missing = sorted(required - {entry.kind for entry in entries})
+    if missing:
+        raise SiteError(f"Prepared site is missing required artifact kind(s): {', '.join(missing)}")
+    return tuple(sorted(entries, key=lambda entry: entry.site_path)), sorted(omitted, key=lambda item: item["source_path"])
+
+
+def _viewer_shell() -> tuple[dict[str, tuple[bytes, str]], str]:
+    root = resources.files("python_cad_tools").joinpath("_viewer_static")
+    try:
+        manifest = json.loads(root.joinpath("asset-manifest.json").read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError) as error:
+        raise ArtifactIntegrityError("Installed viewer asset manifest is missing or invalid") from error
+    if not isinstance(manifest, dict) or set(manifest) != {"schema_id", "schema_version", "entries"} or manifest.get("schema_id") != ASSET_SCHEMA or manifest.get("schema_version") != 1:
+        raise ArtifactIntegrityError("Unsupported viewer asset manifest schema")
+    raw_entries = manifest.get("entries")
+    if not isinstance(raw_entries, list):
+        raise ArtifactIntegrityError("Viewer asset manifest entries must be an array")
+    shell: dict[str, tuple[bytes, str]] = {}
+    canonical_records: list[dict[str, Any]] = []
+    for value in raw_entries:
+        if not isinstance(value, dict) or set(value) != {"path", "size", "sha256", "media_type"}:
+            raise ArtifactIntegrityError("Invalid viewer asset record")
+        relative = _safe_relative(value.get("path"))
+        if relative in shell or relative.casefold() in {path.casefold() for path in shell}:
+            raise ArtifactIntegrityError(f"Duplicate viewer shell path: {relative}")
+        if relative.startswith("artifacts/") or relative in {"asset-manifest.json", "download-manifest.json", "site-metadata.json"}:
+            raise ArtifactIntegrityError(f"Reserved viewer shell path: {relative}")
+        data = root.joinpath(*PurePosixPath(relative).parts).read_bytes()
+        if type(value.get("size")) is not int or len(data) != value["size"] or _sha256_bytes(data) != value.get("sha256"):
+            raise ArtifactIntegrityError(f"Viewer shell integrity mismatch: {relative}")
+        media_type = value.get("media_type")
+        if not isinstance(media_type, str):
+            raise ArtifactIntegrityError(f"Invalid viewer shell media type: {relative}")
+        shell[relative] = (data, media_type)
+        canonical_records.append(cast(dict[str, Any], value))
+    if [item["path"] for item in canonical_records] != sorted(item["path"] for item in canonical_records):
+        raise ArtifactIntegrityError("Viewer asset records are not path-sorted")
+    digest = _sha256_bytes(canonical_json_bytes(canonical_records))
+    if get_package_build_info().viewer_shell_sha256 != digest:
+        raise ArtifactIntegrityError("Viewer shell hash does not match build-info.json")
+    return shell, digest
+
+
+def _stage_site(
+    *, target: Path, identity: str, output: Path, shell: dict[str, tuple[bytes, str]], entries: tuple[SiteEntry, ...],
+    download_bytes: bytes, project_id: str, design_build_hash: str, base_path: str, viewer_shell_sha256: str,
+    download_manifest_sha256: str, tool_version: str,
+) -> Path:
+    staging = target.parent / f".{target.name}.python-cad-stage-{uuid.uuid4().hex}"
+    staging.mkdir(mode=0o700)
+    owners: dict[str, tuple[str, Literal["viewer_shell", "generated_artifact", "site_document"]]] = {}
+    try:
+        for relative, (data, media_type) in shell.items():
+            _write_bytes(staging, relative, data)
+            owners[relative] = (media_type, "viewer_shell")
+        for entry in entries:
+            source = output.joinpath(*PurePosixPath(entry.source_path).parts)
+            _write_bytes(staging, entry.site_path, source.read_bytes())
+            owners[entry.site_path] = (entry.media_type, "generated_artifact")
+        _write_bytes(staging, "download-manifest.json", download_bytes)
+        owners["download-manifest.json"] = ("application/json", "site_document")
+        inventory = _managed_inventory(staging, owners)
+        site_metadata = {
+            "schema_id": SITE_SCHEMA,
+            "schema_version": 1,
+            "managed_by": "python-cad-tools",
+            "tool_version": tool_version,
+            "project_id": project_id,
+            "design_build_hash": design_build_hash,
+            "base_path": base_path,
+            "destination_path_sha256": identity,
+            "viewer_shell_sha256": viewer_shell_sha256,
+            "download_manifest_sha256": download_manifest_sha256,
+            "managed_inventory": [asdict(item) for item in inventory],
+        }
+        _write_bytes(staging, "site-metadata.json", _canonical_json(site_metadata))
+        _verify_managed_site(staging, identity, project_id, destination_for_identity=target)
+        return staging
+    except BaseException:
+        shutil.rmtree(staging, ignore_errors=True)
+        raise
+
+
+def _promote_site(target: Path, identity: str, staging: Path) -> None:
+    journal = _journal_path(target, identity)
+    backup = target.parent / f".{target.name}.python-cad-backup-{uuid.uuid4().hex}"
+    state = {"schema_version": 1, "destination_path_sha256": identity, "destination": str(target), "staging": str(staging), "backup": str(backup), "phase": "staged"}
+    _write_journal(journal, state)
+    try:
+        _recheck_rename_target(target, identity)
+        if target.exists():
+            target.rename(backup)
+        state["phase"] = "backup_created"
+        _write_journal(journal, state)
+        _recheck_rename_target(target, identity)
+        staging.rename(target)
+        state["phase"] = "promoted"
+        _write_journal(journal, state)
+        _verify_managed_site(target, identity)
+        shutil.rmtree(backup, ignore_errors=True)
+        journal.unlink(missing_ok=True)
+    except BaseException:
+        if target.exists():
+            shutil.rmtree(target, ignore_errors=True)
+        if backup.exists():
+            backup.rename(target)
+        shutil.rmtree(staging, ignore_errors=True)
+        journal.unlink(missing_ok=True)
+        raise
+
+
+def _recover_site_transaction(target: Path, identity: str) -> None:
+    journal = _journal_path(target, identity)
+    if not journal.exists():
+        return
+    try:
+        state = json.loads(journal.read_text(encoding="utf-8"))
+        if state.get("destination_path_sha256") != identity or Path(state.get("destination", "")) != target:
+            raise UnsafePathError(f"Refusing foreign site transaction journal: {journal}")
+        staging = _transaction_path(target, state.get("staging"), "stage")
+        backup = _transaction_path(target, state.get("backup"), "backup")
+        if target.exists():
+            _verify_managed_site(target, identity)
+            shutil.rmtree(staging, ignore_errors=True)
+            shutil.rmtree(backup, ignore_errors=True)
+        elif backup.exists():
+            backup.rename(target)
+            shutil.rmtree(staging, ignore_errors=True)
+        elif staging.exists():
+            _verify_managed_site(staging, identity, destination_for_identity=target)
+            staging.rename(target)
+        else:
+            raise UnsafePathError("Site recovery has no complete destination, staging, or backup tree")
+        journal.unlink(missing_ok=True)
+    except (OSError, ValueError, TypeError, json.JSONDecodeError) as error:
+        raise UnsafePathError(f"Unable to recover viewer-site transaction: {error}") from error
+
+
+def _validate_destination(project_root: Path, output: Path, target: Path) -> None:
+    home = Path.home().resolve()
+    git = project_root / ".git"
+    root = Path(target.anchor)
+    forbidden = (root, home, project_root, git.resolve(strict=False), output.resolve(strict=False))
+    if any(target == value or value.is_relative_to(target) for value in forbidden):
+        raise UnsafePathError(f"Unsafe viewer-site destination: {target}")
+    if target.is_relative_to(git.resolve(strict=False)) or target.is_relative_to(output.resolve(strict=False)):
+        raise UnsafePathError(f"Viewer-site destination may not be inside .git or generated output: {target}")
+    if target.is_symlink():
+        raise UnsafePathError(f"Viewer-site destination may not be a symlink: {target}")
+    parent = target.parent
+    if not parent.exists() or not parent.is_dir() or parent.is_symlink():
+        raise UnsafePathError(f"Viewer-site destination parent must be an existing regular directory: {parent}")
+
+
+def _validate_existing_site(target: Path, identity: str, project_id: str) -> None:
+    if not target.exists():
+        return
+    if not target.is_dir() or target.is_symlink():
+        raise UnsafePathError(f"Viewer-site destination is not a regular directory: {target}")
+    if not any(target.iterdir()):
+        return
+    _verify_managed_site(target, identity, project_id)
+
+
+def _verify_managed_site(root: Path, identity: str | None = None, project_id: str | None = None, *, destination_for_identity: Path | None = None) -> dict[str, Any]:
+    marker = root / "site-metadata.json"
+    try:
+        value = json.loads(marker.read_text(encoding="utf-8"))
+    except (FileNotFoundError, OSError, json.JSONDecodeError) as error:
+        raise UnsafePathError(f"Destination is not a valid Python CAD Tools managed site: {root}") from error
+    if not isinstance(value, dict) or set(value) != _SITE_FIELDS or value.get("schema_id") != SITE_SCHEMA or value.get("schema_version") != 1 or value.get("managed_by") != "python-cad-tools":
+        raise UnsafePathError(f"Destination has invalid ownership metadata: {root}")
+    expected_identity = identity
+    if expected_identity is None:
+        _, expected_identity = destination_identity(destination_for_identity or root)
+    if value.get("destination_path_sha256") != expected_identity:
+        raise UnsafePathError("Viewer-site destination identity does not match ownership metadata")
+    if project_id is not None and value.get("project_id") != project_id:
+        raise UnsafePathError(f"Viewer-site destination belongs to foreign project {value.get('project_id')!r}")
+    if not isinstance(value.get("base_path"), str) or normalize_base_path(value["base_path"]) != value["base_path"]:
+        raise UnsafePathError("Viewer-site metadata has an invalid base path")
+    inventory = value.get("managed_inventory")
+    if not isinstance(inventory, list):
+        raise UnsafePathError("Viewer-site managed_inventory must be an array")
+    actual = _regular_files(root)
+    actual.pop("site-metadata.json", None)
+    expected: dict[str, dict[str, Any]] = {}
+    for record in inventory:
+        if not isinstance(record, dict) or set(record) != _INVENTORY_FIELDS:
+            raise UnsafePathError("Viewer-site inventory contains an invalid record")
+        relative = _safe_relative(record.get("path"))
+        if relative in expected or record.get("owner") not in {"viewer_shell", "generated_artifact", "site_document"}:
+            raise UnsafePathError(f"Viewer-site inventory contains an invalid path or owner: {relative}")
+        expected[relative] = record
+    if [record["path"] for record in inventory] != sorted(expected):
+        raise UnsafePathError("Viewer-site inventory is not path-sorted")
+    if set(actual) != set(expected):
+        raise UnsafePathError(f"Viewer-site inventory mismatch; missing={sorted(set(expected)-set(actual))}, unexpected={sorted(set(actual)-set(expected))}")
+    for relative, path in actual.items():
+        record = expected[relative]
+        if path.stat().st_size != record.get("size") or sha256_file(path) != record.get("sha256"):
+            raise UnsafePathError(f"Viewer-site file does not match ownership inventory: {relative}")
+    download = actual.get("download-manifest.json")
+    if download is None or sha256_file(download) != value.get("download_manifest_sha256"):
+        raise UnsafePathError("Viewer-site download manifest hash mismatch")
+    return value
+
+
+def _managed_inventory(root: Path, owners: dict[str, tuple[str, Literal["viewer_shell", "generated_artifact", "site_document"]]]) -> tuple[ManagedSiteFile, ...]:
+    actual = _regular_files(root)
+    if set(actual) != set(owners):
+        raise SiteError("Internal prepared-site inventory mismatch")
+    return tuple(
+        ManagedSiteFile(relative, path.stat().st_size, sha256_file(path), owners[relative][0], owners[relative][1])
+        for relative, path in sorted(actual.items())
+    )
+
+
+def _regular_files(root: Path) -> dict[str, Path]:
+    if root.is_symlink() or not root.is_dir():
+        raise UnsafePathError(f"Managed site is not a regular directory: {root}")
+    result: dict[str, Path] = {}
+    for directory, names, files in os.walk(root, followlinks=False):
+        current = Path(directory)
+        for name in names:
+            if (current / name).is_symlink():
+                raise UnsafePathError(f"Managed site contains a symlink: {(current / name).relative_to(root)}")
+        for name in files:
+            path = current / name
+            if path.is_symlink() or not path.is_file():
+                raise UnsafePathError(f"Managed site contains a non-regular file: {path.relative_to(root)}")
+            relative = _safe_relative(path.relative_to(root).as_posix())
+            if relative in result or relative.casefold() in {value.casefold() for value in result}:
+                raise UnsafePathError(f"Managed site contains a path collision: {relative}")
+            result[relative] = path
+    return dict(sorted(result.items()))
+
+
+def _check_site_collisions(shell: dict[str, tuple[bytes, str]], entries: tuple[SiteEntry, ...]) -> None:
+    paths = list(shell) + [entry.site_path for entry in entries] + ["download-manifest.json", "site-metadata.json"]
+    folded = [path.casefold() for path in paths]
+    if len(folded) != len(set(folded)):
+        raise SiteError("Viewer shell and generated artifacts contain a case-folded path collision")
+
+
+def _handler(root: Path, site: dict[str, Any]) -> type[http.server.BaseHTTPRequestHandler]:
+    inventory = {record["path"]: record for record in site["managed_inventory"]}
+    inventory["site-metadata.json"] = {
+        "media_type": "application/json", "sha256": sha256_file(root / "site-metadata.json"), "size": (root / "site-metadata.json").stat().st_size,
+    }
+    health = _canonical_json({"status": "ok", "tool_version": site["tool_version"], "design_build_hash": site["design_build_hash"]})
+    base = cast(str, site["base_path"])
+
+    class Handler(http.server.BaseHTTPRequestHandler):
+        def do_HEAD(self) -> None:  # noqa: N802
+            self._serve(send_body=False)
+
+        def do_GET(self) -> None:  # noqa: N802
+            self._serve(send_body=True)
+
+        def _serve(self, *, send_body: bool) -> None:
+            parsed = urllib.parse.urlsplit(self.path)
+            if parsed.query or parsed.fragment or "\\" in self.path or "%2f" in self.path.lower() or "%5c" in self.path.lower():
+                return self.send_error(400)
+            if parsed.path in {"/healthz", f"{base.rstrip('/')}/healthz"}:
+                return self._bytes(health, "application/json", _sha256_bytes(health), send_body)
+            if "Range" in self.headers:
+                return self.send_error(416)
+            try:
+                decoded = urllib.parse.unquote(parsed.path, errors="strict")
+            except UnicodeError:
+                return self.send_error(400)
+            if not decoded.startswith(base):
+                return self.send_error(404)
+            relative = decoded[len(base):] or "index.html"
+            try:
+                relative = _safe_relative(relative)
+            except ArtifactIntegrityError:
+                return self.send_error(400)
+            record = inventory.get(relative)
+            if record is None:
+                return self.send_error(404)
+            data = (root / relative).read_bytes()
+            self._bytes(data, record["media_type"], record["sha256"], send_body)
+
+        def _bytes(self, data: bytes, media_type: str, digest: str, send_body: bool) -> None:
+            etag = f'"sha256-{digest}"'
+            if self.headers.get("If-None-Match") == etag:
+                self.send_response(304)
+                self.send_header("ETag", etag)
+                self.end_headers()
+                return
+            self.send_response(200)
+            self.send_header("Content-Type", media_type)
+            self.send_header("Content-Length", str(len(data)))
+            self.send_header("ETag", etag)
+            self.send_header("X-Content-Type-Options", "nosniff")
+            self.send_header("Cache-Control", "no-cache")
+            self.end_headers()
+            if send_body:
+                self.wfile.write(data)
+
+        def log_message(self, _format: str, *_args: Any) -> None:
+            return
+
+    return Handler
+
+
+@contextlib.contextmanager
+def _destination_lock(parent: Path, identity: str) -> Iterator[None]:
+    path = parent / f".python-cad-site-{identity}.lock"
+    handle = path.open("a+b")
+    try:
+        if os.name == "nt":
+            import msvcrt
+            try:
+                msvcrt.locking(handle.fileno(), msvcrt.LK_LOCK, 1)  # type: ignore[attr-defined]
+            except OSError as error:
+                raise BuildLockedError(f"Viewer-site destination is locked: {path}") from error
+        else:
+            import fcntl
+            try:
+                fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
+            except OSError as error:
+                raise BuildLockedError(f"Viewer-site destination is locked: {path}") from error
+        yield
+    finally:
+        if os.name == "nt":
+            import msvcrt
+            with contextlib.suppress(OSError):
+                handle.seek(0)
+                msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)  # type: ignore[attr-defined]
+        else:
+            import fcntl
+            with contextlib.suppress(OSError):
+                fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+        handle.close()
+
+
+def _write_bytes(root: Path, relative: str, data: bytes) -> None:
+    safe = _safe_relative(relative)
+    path = root.joinpath(*PurePosixPath(safe).parts)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_bytes(data)
+
+
+def _safe_relative(value: object) -> str:
+    if not isinstance(value, str) or not value or "\\" in value or "\x00" in value:
+        raise ArtifactIntegrityError(f"Unsafe site path: {value!r}")
+    path = PurePosixPath(value)
+    if path.is_absolute() or path.as_posix() != value or any(part in {"", ".", ".."} for part in path.parts):
+        raise ArtifactIntegrityError(f"Unsafe site path: {value!r}")
+    return value
+
+
+def _canonical_json(value: Any) -> bytes:
+    return canonical_json_bytes(value)
+
+
+def _sha256_bytes(value: bytes) -> str:
+    return hashlib.sha256(value).hexdigest()
+
+
+def _journal_path(target: Path, identity: str) -> Path:
+    return target.parent / f".python-cad-site-{identity}.journal.json"
+
+
+def _write_journal(path: Path, state: dict[str, Any]) -> None:
+    temporary = path.with_suffix(".tmp")
+    temporary.write_bytes(_canonical_json(state))
+    os.replace(temporary, path)
+
+
+def _transaction_path(target: Path, value: object, kind: str) -> Path:
+    if not isinstance(value, str):
+        raise UnsafePathError(f"Site recovery has no valid {kind} path")
+    path = Path(value)
+    prefix = f".{target.name}.python-cad-{kind}-"
+    if path.parent != target.parent or not path.name.startswith(prefix):
+        raise UnsafePathError(f"Unsafe site recovery {kind} path: {path}")
+    return path
+
+
+def _recheck_rename_target(target: Path, identity: str) -> None:
+    resolved, current = destination_identity(target)
+    if resolved != target or current != identity or target.parent.is_symlink() or not target.parent.is_dir() or target.is_symlink():
+        raise UnsafePathError("Viewer-site destination changed during promotion")
+
+
+def _is_loopback(host: str) -> bool:
+    if host.lower() == "localhost":
+        return True
+    try:
+        return ipaddress.ip_address(host).is_loopback
+    except ValueError:
+        try:
+            return all(ipaddress.ip_address(item[4][0]).is_loopback for item in socket.getaddrinfo(host, None))
+        except (OSError, ValueError):
+            return False
+
+
+__all__ = ["PreparedSite", "ServerResult", "destination_identity", "normalize_base_path", "prepare_site", "serve_prepared_site", "serve_project"]