@mriekki/project-forge 4.8.0 → 4.9.0

package/assets/generated/deployment/src/project_forge_deployment/cloudflare_ingress.py

@@ -0,0 +1,834 @@
+"""Optional Cloudflare Tunnel public ingress for remote Project Forge targets.
+
+Cloudflare is an ingress provider, not a deployment transport.  The existing
+remote-ssh target and trusted-LAN Caddy route remain authoritative.  This
+module owns an optional shared cloudflared runtime plus Project-scoped public
+hostname/DNS registrations that forward to those existing Caddy routes.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import re
+import shlex
+import subprocess
+import urllib.parse
+from copy import deepcopy
+from typing import Any
+
+from . import cloudflare_api
+from .box_platform import platform_status
+from .box_platform_assets import CADDY_CONTAINER, NETWORK_NAME, PLATFORM_ROOT
+from .cloudflare_ingress_remote import REMOTE_SCRIPT
+from .errors import DeploymentKitError
+from .profiles import load_profile
+from .route_registry import route_inventory
+from .ssh import ssh_args, verify_access
+
+INGRESS_SCHEMA_VERSION = 1
+INGRESS_VERSION = "1"
+INGRESS_DISTRIBUTION = "cloudflare-remote-managed-tunnel"
+CLOUDFLARED_VERSION = "2026.10.4"
+CLOUDFLARED_IMAGE = f"cloudflare/cloudflared:{CLOUDFLARED_VERSION}"
+HOST_PUBLIC_INGRESS_WRITE_PHRASE = "[HOST PUBLIC INGRESS WRITE]"
+PUBLIC_INGRESS_ROUTE_WRITE_PHRASE = "[PUBLIC INGRESS ROUTE WRITE]"
+PUBLIC_INGRESS_ROUTE_REMOVE_PHRASE = "[PUBLIC INGRESS ROUTE REMOVE]"
+CLOUDFLARE_API_TOKEN_ENV = "PROJECT_FORGE_CLOUDFLARE_API_TOKEN"
+
+_SLUG_RE = re.compile(r"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$")
+_REPO_RE = re.compile(r"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$")
+_LABEL_RE = re.compile(r"^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$")
+_BOOL_STATUS_KEYS = {"markerPresent", "platformReady", "tokenPresent", "containerRunning", "networkAttached"}
+_STATUS_KEYS = {
+    "state", "scope", "markerPresent", "markerSchemaVersion", "markerIngressVersion",
+    "markerDistribution", "platformReady", "tokenPresent", "containerRunning",
+    "networkAttached", "containerName", "cloudflaredImage", "accountId", "zoneId",
+    "zoneName", "tunnelId", "tunnelName",
+}
+
+
+def _slug(value: str, field: str) -> str:
+    if not isinstance(value, str) or _SLUG_RE.fullmatch(value) is None:
+        raise DeploymentKitError(f"{field} must use lowercase letters, digits, and internal hyphens.")
+    return value
+
+
+def _owner_repo(value: str) -> str:
+    if not isinstance(value, str) or _REPO_RE.fullmatch(value) is None:
+        raise DeploymentKitError("ownerRepo must use GitHub owner/repository form without URL syntax.")
+    return value
+
+
+def _hostname(value: str, field: str) -> str:
+    if not isinstance(value, str) or not value or len(value) > 253:
+        raise DeploymentKitError(f"{field} must be a non-empty DNS hostname.")
+    normalized = value.lower().rstrip(".")
+    labels = normalized.split(".")
+    if len(labels) < 2 or any(_LABEL_RE.fullmatch(label) is None for label in labels):
+        raise DeploymentKitError(f"Invalid {field}: {normalized}")
+    return normalized
+
+
+def _first_level_public_hostname(value: str, zone_name: str) -> str:
+    host = _hostname(value, "public hostname")
+    zone = _hostname(zone_name, "Cloudflare zone")
+    suffix = "." + zone
+    if not host.endswith(suffix):
+        raise DeploymentKitError(f"Public hostname {host} must belong to Cloudflare zone {zone}.")
+    relative = host[: -len(suffix)]
+    if "." in relative or not relative:
+        raise DeploymentKitError(
+            "The current partial Cloudflare adapter supports one first-level subdomain per application "
+            "(for example app.example.com). Deeper names require an explicit certificate/support review."
+        )
+    return host
+
+
+def _origin_hostname(value: str) -> str:
+    host = _hostname(value, "origin hostname")
+    if not host.endswith(".local"):
+        raise DeploymentKitError("Cloudflare origin hostname must be an existing trusted-LAN .local route.")
+    return host
+
+
+def tunnel_name_for_scope(scope: str) -> str:
+    return f"project-forge-{_slug(scope, 'scope')}"
+
+
+def build_remote_script(*, tunnel_token: str | None = None) -> str:
+    token_b64 = ""
+    if tunnel_token is not None:
+        if not isinstance(tunnel_token, str) or not tunnel_token.strip():
+            raise DeploymentKitError("Cloudflare tunnel token is empty.")
+        token_b64 = base64.b64encode(tunnel_token.strip().encode("utf-8")).decode("ascii")
+    replacements = {
+        "__PLATFORM_ROOT__": PLATFORM_ROOT,
+        "__NETWORK_NAME__": NETWORK_NAME,
+        "__CADDY_CONTAINER__": CADDY_CONTAINER,
+        "__CLOUDFLARED_IMAGE__": CLOUDFLARED_IMAGE,
+        "__SCHEMA_VERSION__": str(INGRESS_SCHEMA_VERSION),
+        "__INGRESS_VERSION__": INGRESS_VERSION,
+        "__DISTRIBUTION__": INGRESS_DISTRIBUTION,
+        "__TOKEN_B64__": token_b64,
+    }
+    script = REMOTE_SCRIPT
+    for placeholder, replacement in replacements.items():
+        script = script.replace(placeholder, replacement)
+    if "__" in script:
+        raise DeploymentKitError("Internal Cloudflare ingress script contains an unresolved placeholder.")
+    return script
+
+
+def _parse_status(output: str) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for raw in output.splitlines():
+        if not raw.strip():
+            continue
+        if "=" not in raw:
+            raise DeploymentKitError(f"Malformed Cloudflare ingress status line: {raw!r}")
+        key, value = raw.split("=", 1)
+        if key not in _STATUS_KEYS or key in result:
+            raise DeploymentKitError(f"Unexpected or duplicate Cloudflare ingress status key: {key!r}")
+        if key in _BOOL_STATUS_KEYS:
+            if value not in {"true", "false"}:
+                raise DeploymentKitError(f"Invalid boolean Cloudflare ingress status value for {key}.")
+            result[key] = value == "true"
+        else:
+            result[key] = value
+    missing = _STATUS_KEYS - result.keys()
+    if missing:
+        raise DeploymentKitError("Cloudflare ingress status omitted keys: " + ", ".join(sorted(missing)))
+    return result
+
+
+def _metadata_tsv(values: dict[str, Any]) -> str:
+    return "\t".join(
+        str(values[key])
+        for key in ("accountId", "zoneId", "zoneName", "tunnelId", "tunnelName")
+    )
+
+
+def _route_spec(
+    *,
+    owner_repo: str,
+    environment: str,
+    app_slug: str,
+    public_hostname: str,
+    origin_hostname: str,
+) -> dict[str, Any]:
+    owner_repo = _owner_repo(owner_repo)
+    environment = _slug(environment, "environment")
+    app_slug = _slug(app_slug, "appSlug")
+    public_hostname = _hostname(public_hostname, "public hostname")
+    if public_hostname.endswith(".local"):
+        raise DeploymentKitError("Public hostname must not use the .local suffix.")
+    origin_hostname = _origin_hostname(origin_hostname)
+    return {
+        "schemaVersion": INGRESS_SCHEMA_VERSION,
+        "ownerRepo": owner_repo,
+        "environment": environment,
+        "appSlug": app_slug,
+        "routeId": f"{app_slug}--{environment}",
+        "publicHostname": public_hostname,
+        "originHostname": origin_hostname,
+    }
+
+
+def _route_tsv(spec: dict[str, Any]) -> str:
+    return "\t".join(
+        str(spec[key])
+        for key in (
+            "schemaVersion", "ownerRepo", "environment", "appSlug", "routeId",
+            "publicHostname", "originHostname",
+        )
+    )
+
+
+def _run_remote(
+    profile: dict[str, Any],
+    address: str,
+    action: str,
+    *,
+    scope: str,
+    metadata: dict[str, Any] | None = None,
+    spec: dict[str, Any] | None = None,
+    expected: dict[str, Any] | None = None,
+    tunnel_token: str | None = None,
+) -> str:
+    if action not in {"status", "install", "upgrade", "route-inventory", "route-register", "route-remove"}:
+        raise DeploymentKitError(f"Unsupported Cloudflare ingress action: {action}")
+    args = [action, _slug(scope, "scope")]
+    args.append(_metadata_tsv(metadata) if metadata is not None else "")
+    args.append(_route_tsv(spec) if spec is not None else "")
+    if action == "route-register":
+        args.append(_route_tsv(expected) if expected is not None else "NONE")
+    elif action == "route-remove":
+        args.append("")
+    remote_command = "sudo -n bash -s -- " + " ".join(shlex.quote(item) for item in args)
+    completed = subprocess.run(
+        ssh_args(profile, address, command=remote_command),
+        input=build_remote_script(tunnel_token=tunnel_token).encode("utf-8"),
+        check=False,
+        capture_output=True,
+    )
+    stdout = completed.stdout.decode("utf-8", errors="replace")
+    stderr = completed.stderr.decode("utf-8", errors="replace")
+    if completed.returncode != 0:
+        detail = stderr.strip() or stdout.strip() or f"exit {completed.returncode}"
+        raise DeploymentKitError(f"Remote Cloudflare ingress {action} failed: {detail}")
+    return stdout
+
+
+def cloudflare_ingress_status(name: str, scope: str) -> dict[str, Any]:
+    scope = _slug(scope, "scope")
+    profile = load_profile(name)
+    access = verify_access(profile)
+    status = _parse_status(
+        _run_remote(profile, access["address"], "status", scope=scope)
+    )
+    status["targetName"] = name
+    status["verifiedAddress"] = access["address"]
+    status["mutated"] = False
+    return status
+
+
+def cloudflare_ingress_doctor(name: str, scope: str) -> dict[str, Any]:
+    status = cloudflare_ingress_status(name, scope)
+    status["nextAction"] = {
+        "installable": "configure-cloudflare-ingress",
+        "upgrade-required": "upgrade-cloudflare-ingress",
+        "drifted": "inspect-cloudflare-ingress-drift",
+        "blocked-platform": "prepare-shared-host-platform",
+        "incompatible": "manual-cloudflare-ingress-recovery",
+        "ready": "none",
+    }.get(status["state"], "manual-review")
+    return status
+
+
+def _status_snapshot(status: dict[str, Any]) -> str:
+    selected = {key: status[key] for key in sorted(_STATUS_KEYS)}
+    return hashlib.sha256(json.dumps(selected, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
+
+
+def _config_snapshot(config: dict[str, Any]) -> str:
+    return hashlib.sha256(json.dumps(config, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
+
+
+def _tunnel_summary(tunnel: dict[str, Any] | None) -> dict[str, Any] | None:
+    if tunnel is None:
+        return None
+    return {
+        "id": tunnel.get("id"),
+        "name": tunnel.get("name"),
+        "configSrc": tunnel.get("config_src"),
+        "status": tunnel.get("status"),
+        "deletedAt": tunnel.get("deleted_at"),
+    }
+
+
+def _empty_tunnel_config(config: dict[str, Any]) -> bool:
+    ingress = config.get("ingress")
+    return isinstance(ingress, list) and ingress == [{"service": "http_status:404"}]
+
+
+def plan_cloudflare_ingress(
+    name: str,
+    *,
+    scope: str,
+    zone_name: str,
+    api_token: str,
+    tunnel_name: str | None = None,
+) -> dict[str, Any]:
+    """Plan creation/adoption of one shared remotely managed Cloudflare tunnel."""
+    scope = _slug(scope, "scope")
+    zone = cloudflare_api.resolve_zone(api_token, zone_name)
+    expected_tunnel_name = tunnel_name or tunnel_name_for_scope(scope)
+    if not isinstance(expected_tunnel_name, str) or not expected_tunnel_name.strip():
+        raise DeploymentKitError("Cloudflare tunnel name must be non-empty.")
+    expected_tunnel_name = expected_tunnel_name.strip()
+
+    platform = platform_status(name)
+    if platform["state"] != "ready":
+        raise DeploymentKitError(
+            f"Cloudflare ingress requires a ready shared Project Forge platform; target {name} is {platform['state']}."
+        )
+    host = cloudflare_ingress_status(name, scope)
+    if host["state"] not in {"installable", "upgrade-required", "ready"}:
+        raise DeploymentKitError(
+            f"Cloudflare ingress cannot be configured while host scope {scope} is {host['state']}."
+        )
+
+    tunnel = cloudflare_api.find_tunnel(api_token, zone["accountId"], expected_tunnel_name)
+    tunnel_config: dict[str, Any] | None = None
+    if tunnel is not None:
+        if tunnel.get("config_src") not in {None, "cloudflare"}:
+            raise DeploymentKitError("Project Forge supports adoption only of remotely managed Cloudflare tunnels.")
+        tunnel_config = cloudflare_api.get_tunnel_configuration(api_token, zone["accountId"], str(tunnel["id"]))
+
+    if host["state"] in {"ready", "upgrade-required"}:
+        expected = {
+            "accountId": zone["accountId"],
+            "zoneId": zone["zoneId"],
+            "zoneName": zone["zoneName"],
+            "tunnelName": expected_tunnel_name,
+        }
+        for key, value in expected.items():
+            if host[key] != value:
+                raise DeploymentKitError(
+                    f"Host Cloudflare ingress scope {scope} is already bound to different {key}; explicit migration is required."
+                )
+        if tunnel is None or host["tunnelId"] != str(tunnel.get("id")):
+            raise DeploymentKitError("Host Cloudflare tunnel identity no longer matches the provider; refusing implicit replacement.")
+        action = "upgrade" if host["state"] == "upgrade-required" else "refresh-token"
+    else:
+        action = "adopt-and-install" if tunnel is not None else "create-and-install"
+        if tunnel_config is not None and not _empty_tunnel_config(tunnel_config):
+            raise DeploymentKitError(
+                "An existing tunnel with the desired name already has ingress configuration. "
+                "Project Forge will not implicitly adopt or overwrite it."
+            )
+
+    return {
+        "targetName": name,
+        "scope": scope,
+        "action": action,
+        "zone": zone,
+        "tunnelName": expected_tunnel_name,
+        "existingTunnel": _tunnel_summary(tunnel),
+        "existingTunnelConfigSha256": _config_snapshot(tunnel_config) if tunnel_config is not None else None,
+        "hostState": host["state"],
+        "hostStatusSnapshot": _status_snapshot(host),
+        "cloudflaredImage": CLOUDFLARED_IMAGE,
+        "requiredAuthorization": HOST_PUBLIC_INGRESS_WRITE_PHRASE,
+        "secrets": {
+            "apiToken": "workstation-only; not persisted by Deployment Kit",
+            "tunnelToken": "written only to the selected host scope through verified SSH",
+        },
+    }
+
+
+def _delete_tunnel(api_token: str, account_id: str, tunnel_id: str) -> None:
+    cloudflare_api._request(  # package-internal bounded rollback helper
+        "DELETE",
+        f"/accounts/{urllib.parse.quote(account_id, safe='')}/cfd_tunnel/{urllib.parse.quote(tunnel_id, safe='')}",
+        token=api_token,
+    )
+
+
+def apply_cloudflare_ingress(plan: dict[str, Any], *, api_token: str) -> dict[str, Any]:
+    """Apply exactly one reviewed shared Cloudflare ingress plan."""
+    required = {
+        "targetName", "scope", "action", "zone", "tunnelName", "existingTunnel",
+        "existingTunnelConfigSha256", "hostState", "hostStatusSnapshot", "cloudflaredImage",
+        "requiredAuthorization", "secrets",
+    }
+    if not isinstance(plan, dict) or set(plan) != required:
+        raise DeploymentKitError("Malformed Cloudflare ingress plan.")
+    if plan["cloudflaredImage"] != CLOUDFLARED_IMAGE:
+        raise DeploymentKitError("Cloudflare ingress plan uses a different cloudflared image; re-plan with the current package.")
+
+    name = plan["targetName"]
+    scope = plan["scope"]
+    zone = cloudflare_api.resolve_zone(api_token, plan["zone"]["zoneName"])
+    if zone != plan["zone"]:
+        raise DeploymentKitError("Cloudflare zone identity changed after planning; create a fresh plan.")
+    current_host = cloudflare_ingress_status(name, scope)
+    if _status_snapshot(current_host) != plan["hostStatusSnapshot"]:
+        raise DeploymentKitError("Host Cloudflare ingress state changed after planning; create a fresh plan.")
+
+    current_tunnel = cloudflare_api.find_tunnel(api_token, zone["accountId"], plan["tunnelName"])
+    if _tunnel_summary(current_tunnel) != plan["existingTunnel"]:
+        raise DeploymentKitError("Cloudflare tunnel state changed after planning; create a fresh plan.")
+    if current_tunnel is not None:
+        current_config = cloudflare_api.get_tunnel_configuration(api_token, zone["accountId"], str(current_tunnel["id"]))
+        if _config_snapshot(current_config) != plan["existingTunnelConfigSha256"]:
+            raise DeploymentKitError("Cloudflare tunnel configuration changed after planning; create a fresh plan.")
+
+    created = False
+    tunnel = current_tunnel
+    if tunnel is None:
+        tunnel = cloudflare_api.create_tunnel(api_token, zone["accountId"], plan["tunnelName"])
+        created = True
+    tunnel_id = str(tunnel["id"])
+    metadata = {
+        **zone,
+        "tunnelId": tunnel_id,
+        "tunnelName": plan["tunnelName"],
+    }
+
+    try:
+        config = cloudflare_api.get_tunnel_configuration(api_token, zone["accountId"], tunnel_id)
+        if not _empty_tunnel_config(config):
+            raise DeploymentKitError(
+                "Cloudflare tunnel acquired non-empty ingress configuration during apply; refusing overwrite."
+            )
+        token = cloudflare_api.get_tunnel_token(api_token, zone["accountId"], tunnel_id)
+        profile = load_profile(name)
+        access = verify_access(profile)
+        remote_action = "upgrade" if plan["hostState"] == "upgrade-required" else (
+            "upgrade" if plan["hostState"] == "ready" else "install"
+        )
+        _run_remote(
+            profile,
+            access["address"],
+            remote_action,
+            scope=scope,
+            metadata=metadata,
+            tunnel_token=token,
+        )
+        final = cloudflare_ingress_status(name, scope)
+        if final["state"] != "ready":
+            raise DeploymentKitError(f"Cloudflare ingress apply completed but host readiness is {final['state']}.")
+        for key in ("accountId", "zoneId", "zoneName", "tunnelId", "tunnelName"):
+            if final[key] != str(metadata[key]):
+                raise DeploymentKitError(f"Host Cloudflare ingress returned mismatched {key} after apply.")
+        final["mutated"] = True
+        final["providerTunnel"] = _tunnel_summary(tunnel)
+        return final
+    except Exception:
+        if created:
+            try:
+                _delete_tunnel(api_token, zone["accountId"], tunnel_id)
+            except Exception:
+                pass
+        raise
+
+
+def _parse_route_inventory(output: str) -> dict[str, Any]:
+    summary: dict[str, str] = {}
+    routes: list[dict[str, Any]] = []
+    for raw in output.splitlines():
+        if not raw:
+            continue
+        parts = raw.split("\t")
+        if parts[0] == "SUMMARY":
+            if len(parts) != 3 or parts[1] in summary:
+                raise DeploymentKitError("Malformed Cloudflare public-route inventory summary.")
+            summary[parts[1]] = parts[2]
+        elif parts[0] == "ROUTE":
+            if len(parts) != 8:
+                raise DeploymentKitError("Malformed Cloudflare public-route inventory record.")
+            try:
+                schema = int(parts[1])
+            except ValueError as error:
+                raise DeploymentKitError("Malformed Cloudflare public-route schema.") from error
+            spec = _route_spec(
+                owner_repo=parts[2],
+                environment=parts[3],
+                app_slug=parts[4],
+                public_hostname=parts[6],
+                origin_hostname=parts[7],
+            )
+            if schema != INGRESS_SCHEMA_VERSION or spec["routeId"] != parts[5]:
+                raise DeploymentKitError("Cloudflare public-route schema or route ID mismatch.")
+            routes.append(spec)
+        else:
+            raise DeploymentKitError("Unexpected Cloudflare public-route inventory record.")
+    if set(summary) != {"scope", "managedRouteCount"}:
+        raise DeploymentKitError("Cloudflare public-route inventory omitted summary fields.")
+    try:
+        count = int(summary["managedRouteCount"])
+    except ValueError as error:
+        raise DeploymentKitError("Malformed Cloudflare managed route count.") from error
+    if count != len(routes):
+        raise DeploymentKitError("Cloudflare managed route count does not match inventory.")
+    return {"scope": summary["scope"], "managedRoutes": sorted(routes, key=lambda item: item["routeId"])}
+
+
+def cloudflare_route_inventory(name: str, scope: str) -> dict[str, Any]:
+    profile = load_profile(name)
+    access = verify_access(profile)
+    result = _parse_route_inventory(
+        _run_remote(profile, access["address"], "route-inventory", scope=scope)
+    )
+    result["targetName"] = name
+    result["verifiedAddress"] = access["address"]
+    result["mutated"] = False
+    return result
+
+
+def _route_inventory_snapshot(value: dict[str, Any]) -> str:
+    selected = {"scope": value["scope"], "managedRoutes": value["managedRoutes"]}
+    return hashlib.sha256(json.dumps(selected, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
+
+
+def _find_route(inventory: dict[str, Any], route_id: str) -> dict[str, Any] | None:
+    return next((item for item in inventory["managedRoutes"] if item["routeId"] == route_id), None)
+
+
+def _lan_route(name: str, spec: dict[str, Any]) -> dict[str, Any]:
+    inventory = route_inventory(name)
+    route = next((item for item in inventory["managedRoutes"] if item["routeId"] == spec["routeId"]), None)
+    if route is None:
+        raise DeploymentKitError(
+            f"Trusted-LAN Caddy route {spec['routeId']} must exist before public ingress can be registered."
+        )
+    for key in ("ownerRepo", "environment", "appSlug"):
+        if route[key] != spec[key]:
+            raise DeploymentKitError("Trusted-LAN route ownership does not match the requested public-ingress route.")
+    if spec["originHostname"] not in route["hostnames"]:
+        raise DeploymentKitError(
+            f"Origin hostname {spec['originHostname']} is not owned by trusted-LAN route {spec['routeId']}."
+        )
+    return route
+
+
+def _cloudflare_rule(spec: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "hostname": spec["publicHostname"],
+        "service": f"http://{CADDY_CONTAINER}:80",
+        "originRequest": {"httpHostHeader": spec["originHostname"]},
+    }
+
+
+def _split_ingress(config: dict[str, Any]) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+    ingress = config.get("ingress")
+    if not isinstance(ingress, list) or not ingress:
+        raise DeploymentKitError("Cloudflare tunnel configuration must contain ingress rules.")
+    if ingress[-1] != {"service": "http_status:404"}:
+        raise DeploymentKitError("Cloudflare tunnel must retain the Project Forge fail-closed final 404 ingress rule.")
+    rules = ingress[:-1]
+    if any(not isinstance(item, dict) for item in rules):
+        raise DeploymentKitError("Cloudflare tunnel contains a malformed ingress rule.")
+    return [deepcopy(item) for item in rules], deepcopy(ingress[-1])
+
+
+def _dns_marker(spec: dict[str, Any]) -> str:
+    identity = "|".join((spec["ownerRepo"], spec["environment"], spec["appSlug"])).encode("utf-8")
+    return "Project Forge " + hashlib.sha256(identity).hexdigest()[:20]
+
+
+def _exact_dns_record(records: list[dict[str, Any]], *, spec: dict[str, Any], tunnel_id: str) -> dict[str, Any] | None:
+    if not records:
+        return None
+    if len(records) != 1:
+        raise DeploymentKitError(f"Public hostname {spec['publicHostname']} has multiple Cloudflare DNS records; refusing takeover.")
+    record = records[0]
+    expected_content = f"{tunnel_id}.cfargotunnel.com"
+    if (
+        record.get("type") != "CNAME"
+        or str(record.get("content", "")).lower().rstrip(".") != expected_content
+        or record.get("proxied") is not True
+        or record.get("comment") != _dns_marker(spec)
+    ):
+        raise DeploymentKitError(
+            f"Public hostname {spec['publicHostname']} already has DNS state not owned by this Project Forge route."
+        )
+    return record
+
+
+def plan_public_route(
+    name: str,
+    *,
+    scope: str,
+    owner_repo: str,
+    environment: str,
+    app_slug: str,
+    public_hostname: str,
+    origin_hostname: str,
+    api_token: str,
+) -> dict[str, Any]:
+    host = cloudflare_ingress_status(name, scope)
+    if host["state"] != "ready":
+        raise DeploymentKitError(f"Cloudflare ingress scope {scope} is not ready on target {name}.")
+    public_hostname = _first_level_public_hostname(public_hostname, host["zoneName"])
+    spec = _route_spec(
+        owner_repo=owner_repo,
+        environment=environment,
+        app_slug=app_slug,
+        public_hostname=public_hostname,
+        origin_hostname=origin_hostname,
+    )
+    _lan_route(name, spec)
+
+    inventory = cloudflare_route_inventory(name, scope)
+    existing = _find_route(inventory, spec["routeId"])
+    if existing is not None and existing != spec:
+        raise DeploymentKitError(
+            "This Project/environment already owns a different public-ingress route. Remove it explicitly before rebinding."
+        )
+    for other in inventory["managedRoutes"]:
+        if other["routeId"] != spec["routeId"] and other["publicHostname"] == spec["publicHostname"]:
+            raise DeploymentKitError("Public hostname is already owned by another Project Forge route on this ingress scope.")
+
+    config = cloudflare_api.get_tunnel_configuration(api_token, host["accountId"], host["tunnelId"])
+    rules, final_rule = _split_ingress(config)
+    desired_rule = _cloudflare_rule(spec)
+    conflicting = [item for item in rules if item.get("hostname") == spec["publicHostname"] and item != desired_rule]
+    if conflicting:
+        raise DeploymentKitError("Cloudflare tunnel already has a conflicting ingress rule for this hostname.")
+    exact_rules = [item for item in rules if item == desired_rule]
+    if len(exact_rules) > 1:
+        raise DeploymentKitError("Cloudflare tunnel contains duplicate exact Project Forge ingress rules.")
+
+    records = cloudflare_api.list_dns_records(api_token, host["zoneId"], name=spec["publicHostname"])
+    dns = _exact_dns_record(records, spec=spec, tunnel_id=host["tunnelId"])
+    return {
+        "targetName": name,
+        "scope": scope,
+        "action": "already-configured" if existing == spec and exact_rules and dns is not None else "register",
+        "route": spec,
+        "previousRoute": existing,
+        "routeInventorySnapshot": _route_inventory_snapshot(inventory),
+        "hostStatusSnapshot": _status_snapshot(host),
+        "tunnelConfig": config,
+        "tunnelConfigSha256": _config_snapshot(config),
+        "desiredTunnelConfig": {**config, "ingress": rules + ([] if exact_rules else [desired_rule]) + [final_rule]},
+        "dnsRecord": deepcopy(dns),
+        "dnsMarker": _dns_marker(spec),
+        "requiredAuthorization": PUBLIC_INGRESS_ROUTE_WRITE_PHRASE,
+    }
+
+
+def apply_public_route(plan: dict[str, Any], *, api_token: str) -> dict[str, Any]:
+    if plan.get("action") == "already-configured":
+        return {**plan, "mutated": False}
+    required = {
+        "targetName", "scope", "action", "route", "previousRoute", "routeInventorySnapshot",
+        "hostStatusSnapshot", "tunnelConfig", "tunnelConfigSha256", "desiredTunnelConfig",
+        "dnsRecord", "dnsMarker", "requiredAuthorization",
+    }
+    if not isinstance(plan, dict) or set(plan) != required or plan["action"] != "register":
+        raise DeploymentKitError("Malformed Cloudflare public-route plan.")
+    name = plan["targetName"]
+    scope = plan["scope"]
+    spec = plan["route"]
+    host = cloudflare_ingress_status(name, scope)
+    if _status_snapshot(host) != plan["hostStatusSnapshot"]:
+        raise DeploymentKitError("Cloudflare host ingress changed after planning; create a fresh route plan.")
+    inventory = cloudflare_route_inventory(name, scope)
+    if _route_inventory_snapshot(inventory) != plan["routeInventorySnapshot"]:
+        raise DeploymentKitError("Cloudflare public-route inventory changed after planning; create a fresh plan.")
+    _lan_route(name, spec)
+    config = cloudflare_api.get_tunnel_configuration(api_token, host["accountId"], host["tunnelId"])
+    if _config_snapshot(config) != plan["tunnelConfigSha256"]:
+        raise DeploymentKitError("Cloudflare tunnel configuration changed after planning; create a fresh route plan.")
+    records = cloudflare_api.list_dns_records(api_token, host["zoneId"], name=spec["publicHostname"])
+    current_dns = _exact_dns_record(records, spec=spec, tunnel_id=host["tunnelId"])
+    if current_dns != plan["dnsRecord"]:
+        raise DeploymentKitError("Cloudflare DNS state changed after planning; create a fresh route plan.")
+
+    profile = load_profile(name)
+    access = verify_access(profile)
+    host_written = False
+    config_written = False
+    dns_created: dict[str, Any] | None = None
+    try:
+        _run_remote(
+            profile,
+            access["address"],
+            "route-register",
+            scope=scope,
+            spec=spec,
+            expected=plan["previousRoute"],
+        )
+        host_written = True
+        if plan["desiredTunnelConfig"] != plan["tunnelConfig"]:
+            cloudflare_api.update_tunnel_configuration(
+                api_token, host["accountId"], host["tunnelId"], plan["desiredTunnelConfig"]
+            )
+            config_written = True
+        if current_dns is None:
+            dns_created = cloudflare_api.create_dns_cname(
+                api_token,
+                host["zoneId"],
+                name=spec["publicHostname"],
+                content=f"{host['tunnelId']}.cfargotunnel.com",
+                comment=plan["dnsMarker"],
+            )
+    except Exception:
+        if dns_created is not None:
+            try:
+                cloudflare_api.delete_dns_record(api_token, host["zoneId"], str(dns_created["id"]))
+            except Exception:
+                pass
+        if config_written:
+            try:
+                cloudflare_api.update_tunnel_configuration(
+                    api_token, host["accountId"], host["tunnelId"], plan["tunnelConfig"]
+                )
+            except Exception:
+                pass
+        if host_written and plan["previousRoute"] is None:
+            try:
+                _run_remote(profile, access["address"], "route-remove", scope=scope, spec=spec)
+            except Exception:
+                pass
+        raise
+
+    final_inventory = cloudflare_route_inventory(name, scope)
+    if _find_route(final_inventory, spec["routeId"]) != spec:
+        raise DeploymentKitError("Public route registration returned without exact host ownership metadata.")
+    final_config = cloudflare_api.get_tunnel_configuration(api_token, host["accountId"], host["tunnelId"])
+    if final_config != plan["desiredTunnelConfig"]:
+        raise DeploymentKitError("Cloudflare tunnel configuration does not match the reviewed route plan after apply.")
+    final_dns = _exact_dns_record(
+        cloudflare_api.list_dns_records(api_token, host["zoneId"], name=spec["publicHostname"]),
+        spec=spec,
+        tunnel_id=host["tunnelId"],
+    )
+    if final_dns is None:
+        raise DeploymentKitError("Cloudflare DNS record is missing after public-route apply.")
+    return {
+        "targetName": name,
+        "scope": scope,
+        "route": spec,
+        "dnsRecordId": str(final_dns["id"]),
+        "publicUrl": f"https://{spec['publicHostname']}",
+        "mutated": True,
+    }
+
+
+def plan_public_route_removal(
+    name: str,
+    *,
+    scope: str,
+    owner_repo: str,
+    environment: str,
+    app_slug: str,
+    api_token: str,
+) -> dict[str, Any]:
+    route_id = f"{_slug(app_slug, 'appSlug')}--{_slug(environment, 'environment')}"
+    owner_repo = _owner_repo(owner_repo)
+    host = cloudflare_ingress_status(name, scope)
+    if host["state"] != "ready":
+        raise DeploymentKitError("Cloudflare ingress must be ready before removing a managed public route.")
+    inventory = cloudflare_route_inventory(name, scope)
+    route = _find_route(inventory, route_id)
+    if route is None:
+        raise DeploymentKitError(f"Managed Cloudflare public route does not exist: {route_id}")
+    if route["ownerRepo"] != owner_repo or route["environment"] != environment or route["appSlug"] != app_slug:
+        raise DeploymentKitError("Cloudflare public-route removal ownership does not match.")
+    config = cloudflare_api.get_tunnel_configuration(api_token, host["accountId"], host["tunnelId"])
+    rules, final_rule = _split_ingress(config)
+    expected_rule = _cloudflare_rule(route)
+    matches = [item for item in rules if item == expected_rule]
+    if len(matches) != 1:
+        raise DeploymentKitError("Cloudflare tunnel does not contain exactly one expected managed rule for this route.")
+    desired = {**config, "ingress": [item for item in rules if item != expected_rule] + [final_rule]}
+    dns = _exact_dns_record(
+        cloudflare_api.list_dns_records(api_token, host["zoneId"], name=route["publicHostname"]),
+        spec=route,
+        tunnel_id=host["tunnelId"],
+    )
+    if dns is None:
+        raise DeploymentKitError("Managed public route DNS record is missing; inspect drift before removal.")
+    return {
+        "targetName": name,
+        "scope": scope,
+        "action": "remove",
+        "route": route,
+        "routeInventorySnapshot": _route_inventory_snapshot(inventory),
+        "hostStatusSnapshot": _status_snapshot(host),
+        "tunnelConfig": config,
+        "tunnelConfigSha256": _config_snapshot(config),
+        "desiredTunnelConfig": desired,
+        "dnsRecord": deepcopy(dns),
+        "requiredAuthorization": PUBLIC_INGRESS_ROUTE_REMOVE_PHRASE,
+    }
+
+
+def apply_public_route_removal(plan: dict[str, Any], *, api_token: str) -> dict[str, Any]:
+    required = {
+        "targetName", "scope", "action", "route", "routeInventorySnapshot", "hostStatusSnapshot",
+        "tunnelConfig", "tunnelConfigSha256", "desiredTunnelConfig", "dnsRecord", "requiredAuthorization",
+    }
+    if not isinstance(plan, dict) or set(plan) != required or plan["action"] != "remove":
+        raise DeploymentKitError("Malformed Cloudflare public-route removal plan.")
+    name = plan["targetName"]
+    scope = plan["scope"]
+    route = plan["route"]
+    host = cloudflare_ingress_status(name, scope)
+    if _status_snapshot(host) != plan["hostStatusSnapshot"]:
+        raise DeploymentKitError("Cloudflare ingress host state changed after removal planning.")
+    inventory = cloudflare_route_inventory(name, scope)
+    if _route_inventory_snapshot(inventory) != plan["routeInventorySnapshot"]:
+        raise DeploymentKitError("Cloudflare public-route inventory changed after removal planning.")
+    config = cloudflare_api.get_tunnel_configuration(api_token, host["accountId"], host["tunnelId"])
+    if _config_snapshot(config) != plan["tunnelConfigSha256"]:
+        raise DeploymentKitError("Cloudflare tunnel configuration changed after removal planning.")
+    dns = _exact_dns_record(
+        cloudflare_api.list_dns_records(api_token, host["zoneId"], name=route["publicHostname"]),
+        spec=route,
+        tunnel_id=host["tunnelId"],
+    )
+    if dns is None or str(dns.get("id")) != str(plan["dnsRecord"].get("id")):
+        raise DeploymentKitError("Cloudflare DNS record changed after removal planning.")
+
+    cloudflare_api.update_tunnel_configuration(
+        api_token, host["accountId"], host["tunnelId"], plan["desiredTunnelConfig"]
+    )
+    try:
+        cloudflare_api.delete_dns_record(api_token, host["zoneId"], str(dns["id"]))
+    except Exception:
+        cloudflare_api.update_tunnel_configuration(
+            api_token, host["accountId"], host["tunnelId"], plan["tunnelConfig"]
+        )
+        raise
+
+    profile = load_profile(name)
+    access = verify_access(profile)
+    try:
+        _run_remote(profile, access["address"], "route-remove", scope=scope, spec=route)
+    except Exception:
+        try:
+            cloudflare_api.update_tunnel_configuration(
+                api_token, host["accountId"], host["tunnelId"], plan["tunnelConfig"]
+            )
+            cloudflare_api.create_dns_cname(
+                api_token,
+                host["zoneId"],
+                name=route["publicHostname"],
+                content=f"{host['tunnelId']}.cfargotunnel.com",
+                comment=_dns_marker(route),
+            )
+        except Exception:
+            pass
+        raise
+
+    final = cloudflare_route_inventory(name, scope)
+    if _find_route(final, route["routeId"]) is not None:
+        raise DeploymentKitError("Cloudflare public route remains in host ownership registry after removal.")
+    return {"targetName": name, "scope": scope, "routeId": route["routeId"], "mutated": True}