@mriekki/project-forge 4.20.0 → 4.22.0

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

@@ -37,6 +37,8 @@ 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]"
+AUTHENTICATED_ORIGIN_MIGRATION_PHRASE = "[CLOUDFLARE AUTHENTICATED ORIGIN MIGRATION]"
+AUTHENTICATED_ORIGIN_CHANGE_FREEZE_PHRASE = "[CLOUDFLARE EXTERNAL CHANGE FREEZE]"
 CLOUDFLARE_API_TOKEN_ENV = "PROJECT_FORGE_CLOUDFLARE_API_TOKEN"
 
 
@@ -197,13 +199,15 @@ def _run_remote(
     scope: str,
     metadata: dict[str, Any] | None = None,
     spec: dict[str, Any] | None = None,
-    expected: dict[str, Any] | None = None,
+    expected: dict[str, Any] | str | None = None,
     tunnel_token: str | None = None,
     authenticated_origin: bool = False,
 ) -> str:
     if action not in {
         "status", "install", "upgrade", "route-inventory",
         "route-register", "route-remove", "route-register-locked", "route-remove-locked",
+        "migration-inspect", "migrate-authenticated", "rollback-authenticated",
+        "finalize-authenticated", "verify-authenticated",
     }:
         raise DeploymentKitError(f"Unsupported Cloudflare ingress action: {action}")
     args = [action, _slug(scope, "scope")]
@@ -213,6 +217,11 @@ def _run_remote(
         args.append(_route_tsv(expected) if expected is not None else "NONE")
     elif action in {"route-remove", "route-remove-locked"}:
         args.append("")
+    elif action in {
+        "migration-inspect", "migrate-authenticated", "rollback-authenticated",
+        "finalize-authenticated", "verify-authenticated",
+    }:
+        args.append(str(expected) if expected is not None else "")
     args.append("true" if authenticated_origin else "false")
     remote_command = "sudo -n bash -s -- " + " ".join(shlex.quote(item) for item in args)
     completed = subprocess.run(
@@ -649,6 +658,25 @@ def _route_inventory_snapshot(value: dict[str, Any]) -> str:
     return hashlib.sha256(json.dumps(selected, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
 
 
+def _route_inventory_wire_snapshot(value: dict[str, Any]) -> str:
+    routes = sorted(value["managedRoutes"], key=lambda item: item["routeId"])
+    lines = [
+        f"SUMMARY\tscope\t{value['scope']}",
+        f"SUMMARY\tmanagedRouteCount\t{len(routes)}",
+    ]
+    for spec in routes:
+        lines.append(
+            "ROUTE\t" + "\t".join(
+                str(spec[key])
+                for key in (
+                    "schemaVersion", "ownerRepo", "environment", "appSlug", "routeId",
+                    "publicHostname", "originHostname",
+                )
+            )
+        )
+    return hashlib.sha256(("\n".join(lines) + "\n").encode("utf-8")).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)
 
@@ -696,6 +724,571 @@ def _split_ingress(config: dict[str, Any]) -> tuple[list[dict[str, Any]], dict[s
     return [deepcopy(item) for item in rules], deepcopy(ingress[-1])
 
 
+def _migration_ingress_config(
+    config: dict[str, Any],
+    routes: list[dict[str, Any]],
+    *,
+    host_authenticated: bool,
+) -> tuple[dict[str, Any], int]:
+    rules, final_rule = _split_ingress(config)
+    if not routes:
+        raise DeploymentKitError("Authenticated-origin migration requires at least one managed public route.")
+    desired_rules = deepcopy(rules)
+    seen_route_ids: set[str] = set()
+    seen_hostnames: set[str] = set()
+    for spec in routes:
+        route_id = spec["routeId"]
+        hostname = spec["publicHostname"]
+        if route_id in seen_route_ids or hostname in seen_hostnames:
+            raise DeploymentKitError("Managed public-route identities are ambiguous; migration was not planned.")
+        seen_route_ids.add(route_id)
+        seen_hostnames.add(hostname)
+        legacy = _cloudflare_rule(spec)
+        authenticated = _cloudflare_rule(spec, authenticated_origin=True)
+        matches = [index for index, rule in enumerate(rules) if rule.get("hostname") == hostname]
+        if len(matches) != 1:
+            raise DeploymentKitError(
+                f"Managed public route {route_id} does not have exactly one provider ingress rule; refusing takeover."
+            )
+        index = matches[0]
+        if rules[index] == legacy:
+            desired_rules[index] = authenticated
+        elif rules[index] == authenticated and host_authenticated:
+            desired_rules[index] = authenticated
+        elif rules[index] == authenticated:
+            raise DeploymentKitError(
+                "Provider ingress is already authenticated while the managed connector is in legacy mode."
+            )
+        else:
+            raise DeploymentKitError(
+                f"Provider ingress for managed route {route_id} has conflicting, unowned, or changed fields."
+            )
+    desired = deepcopy(config)
+    desired["ingress"] = desired_rules + [final_rule]
+    return desired, sum(left != right for left, right in zip(rules, desired_rules))
+
+
+def _unmanaged_ingress_summary(
+    config: dict[str, Any],
+    routes: list[dict[str, Any]],
+) -> dict[str, Any]:
+    rules, _ = _split_ingress(config)
+    managed_hostnames = {spec["publicHostname"] for spec in routes}
+    unmanaged = [rule for rule in rules if rule.get("hostname") not in managed_hostnames]
+    return {
+        "unmanagedIngressRuleCount": len(unmanaged),
+        "unmanagedIngressRulesSha256": _config_snapshot({"rules": unmanaged}),
+    }
+
+
+def _migration_dns_snapshot(
+    api_token: str,
+    host: dict[str, Any],
+    routes: list[dict[str, Any]],
+) -> list[dict[str, str]]:
+    result: list[dict[str, str]] = []
+    for spec in routes:
+        records = cloudflare_api.list_dns_records(
+            api_token, host["zoneId"], name=spec["publicHostname"]
+        )
+        record = _exact_dns_record(records, spec=spec, tunnel_id=host["tunnelId"])
+        if record is None or not record.get("id"):
+            raise DeploymentKitError(
+                f"Managed route {spec['routeId']} has no exact owned DNS record; refusing migration."
+            )
+        result.append(
+            {
+                "routeId": spec["routeId"],
+                "recordId": str(record["id"]),
+                "recordSha256": _config_snapshot(record),
+            }
+        )
+    return result
+
+
+def _migration_freeze_context(plan: dict[str, Any]) -> str:
+    context = {
+        "scope": plan["scope"],
+        "hostStatusSnapshot": plan["hostStatusSnapshot"],
+        "zone": plan["zone"],
+        "tunnel": plan["tunnel"],
+        "routeInventorySnapshot": plan["routeInventorySnapshot"],
+        "dnsSnapshot": plan["dnsSnapshot"],
+        "tunnelConfigSha256": plan["tunnelConfigSha256"],
+        "desiredTunnelConfigSha256": plan["desiredTunnelConfigSha256"],
+    }
+    return hashlib.sha256(
+        json.dumps(context, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    ).hexdigest()[:16]
+
+
+def _required_change_freeze_acknowledgement(plan: dict[str, Any]) -> str:
+    return (
+        f"{AUTHENTICATED_ORIGIN_CHANGE_FREEZE_PHRASE} "
+        f"scope={plan['scope']} context={_migration_freeze_context(plan)}"
+    )
+
+
+def _required_preplan_change_freeze_acknowledgement(scope: str) -> str:
+    return f"{AUTHENTICATED_ORIGIN_CHANGE_FREEZE_PHRASE} ACTIVE scope={scope}"
+
+
+def _remote_migration_state(name: str, scope: str) -> str:
+    profile = load_profile(name)
+    access = verify_access(profile)
+    output = _run_remote(profile, access["address"], "migration-inspect", scope=scope)
+    lines = output.splitlines()
+    if len(lines) != 1 or not lines[0].startswith("migrationState="):
+        raise DeploymentKitError("Remote authenticated-origin migration state is malformed.")
+    state = lines[0].split("=", 1)[1]
+    if state not in {"clean", "pending", "complete"}:
+        raise DeploymentKitError("Remote authenticated-origin migration state is unsupported.")
+    return state
+
+
+def plan_authenticated_origin_migration(
+    name: str,
+    *,
+    scope: str,
+    zone_name: str,
+    api_token: str,
+    change_freeze_active_acknowledgement: str,
+) -> dict[str, Any]:
+    """Plan a guarded migration of one existing legacy ingress scope."""
+    scope = _slug(scope, "scope")
+    if change_freeze_active_acknowledgement != _required_preplan_change_freeze_acknowledgement(scope):
+        raise DeploymentKitError(
+            "Planning requires an explicit scope-bound acknowledgement that the operator-controlled Cloudflare change freeze is active."
+        )
+    zone = cloudflare_api.resolve_zone(api_token, zone_name)
+    host = cloudflare_ingress_status(name, scope)
+    if host["state"] != "ready":
+        raise DeploymentKitError(f"Cloudflare ingress scope {scope} is not ready on target {name}.")
+    if (
+        host["accountId"] != zone["accountId"]
+        or host["zoneId"] != zone["zoneId"]
+        or host["zoneName"] != zone["zoneName"]
+    ):
+        raise DeploymentKitError("Cloudflare zone does not match the existing ingress scope binding.")
+    tunnel = cloudflare_api.find_tunnel(api_token, zone["accountId"], host["tunnelName"])
+    if (
+        tunnel is None
+        or str(tunnel.get("id")) != host["tunnelId"]
+        or tunnel.get("config_src") not in {None, "cloudflare"}
+    ):
+        raise DeploymentKitError("Existing remotely managed tunnel identity changed; refusing migration.")
+
+    migration_state = _remote_migration_state(name, scope)
+    host_authenticated = bool(host["authenticatedOrigin"])
+    if host_authenticated and migration_state != "pending":
+        raise DeploymentKitError(
+            "This scope is already authenticated and has no pending migration receipt; no migration is required."
+        )
+    if not host_authenticated and migration_state != "clean":
+        raise DeploymentKitError(
+            "Legacy ingress scope has conflicting or incomplete authenticated-origin migration state."
+        )
+
+    inventory = cloudflare_route_inventory(name, scope)
+    if inventory["scope"] != scope:
+        raise DeploymentKitError("Remote managed-route inventory belongs to a different ingress scope.")
+    routes = sorted(inventory["managedRoutes"], key=lambda item: item["routeId"])
+    if not routes:
+        raise DeploymentKitError("Authenticated-origin migration requires at least one managed public route.")
+    for spec in routes:
+        _lan_route(name, spec)
+    config = cloudflare_api.get_tunnel_configuration(api_token, zone["accountId"], host["tunnelId"])
+    desired_config, converted_count = _migration_ingress_config(
+        config, routes, host_authenticated=host_authenticated
+    )
+    if converted_count == 0 and not host_authenticated:
+        raise DeploymentKitError("No legacy managed route rules were found to migrate.")
+    dns_snapshot = _migration_dns_snapshot(api_token, host, routes)
+    unmanaged_summary = _unmanaged_ingress_summary(config, routes)
+    return {
+        "targetName": name,
+        "scope": scope,
+        "action": "resume" if migration_state == "pending" else "prepare",
+        "migrationState": migration_state,
+        "hostStatusSnapshot": _status_snapshot(host),
+        "zone": zone,
+        "tunnel": _tunnel_summary(tunnel),
+        "routeInventorySnapshot": _route_inventory_snapshot(inventory),
+        "routeInventoryWireSnapshot": _route_inventory_wire_snapshot(inventory),
+        "managedRoutes": routes,
+        "dnsSnapshot": dns_snapshot,
+        "tunnelConfigSha256": _config_snapshot(config),
+        "desiredTunnelConfigSha256": _config_snapshot(desired_config),
+        "convertedRouteCount": converted_count,
+        **unmanaged_summary,
+        "requiredAuthorization": AUTHENTICATED_ORIGIN_MIGRATION_PHRASE,
+        "requiredPrePlanChangeFreezeAcknowledgement":
+            _required_preplan_change_freeze_acknowledgement(scope),
+        "changeFreezePrerequisite": (
+            "Operator has stopped all Cloudflare dashboard/API tunnel-configuration writers for this scope "
+            "before planning and will keep them stopped through apply, verification, rollback, or recovery. "
+            "Deployment Kit cannot enforce or prove this external change freeze."
+        ),
+        "requiredChangeFreezeAcknowledgement": _required_change_freeze_acknowledgement({
+            "scope": scope,
+            "hostStatusSnapshot": _status_snapshot(host),
+            "zone": zone,
+            "tunnel": _tunnel_summary(tunnel),
+            "routeInventorySnapshot": _route_inventory_snapshot(inventory),
+            "dnsSnapshot": dns_snapshot,
+            "tunnelConfigSha256": _config_snapshot(config),
+            "desiredTunnelConfigSha256": _config_snapshot(desired_config),
+        }),
+        "secrets": {
+            "apiToken": "workstation-only; not persisted by Deployment Kit",
+            "tunnelToken": "existing tunnel token is unchanged and never displayed",
+            "providerConfiguration": "not included in this migration plan",
+        },
+    }
+
+
+def _migration_remote_action(
+    name: str,
+    scope: str,
+    action: str,
+    *,
+    zone: dict[str, Any],
+    tunnel: dict[str, Any],
+    route_snapshot: str,
+    authenticated_origin: bool = True,
+) -> str:
+    profile = load_profile(name)
+    access = verify_access(profile)
+    return _run_remote(
+        profile,
+        access["address"],
+        action,
+        scope=scope,
+        metadata={
+            **zone,
+            "tunnelId": str(tunnel["id"]),
+            "tunnelName": str(tunnel["name"]),
+        },
+        expected=route_snapshot,
+        authenticated_origin=authenticated_origin,
+    )
+
+
+def _rollback_prepared_migration(
+    name: str,
+    scope: str,
+    *,
+    zone: dict[str, Any],
+    tunnel: dict[str, Any],
+    route_snapshot: str,
+) -> None:
+    _migration_remote_action(
+        name,
+        scope,
+        "rollback-authenticated",
+        zone=zone,
+        tunnel=tunnel,
+        route_snapshot=route_snapshot,
+    )
+    restored_host = cloudflare_ingress_status(name, scope)
+    if restored_host["state"] != "ready" or restored_host["authenticatedOrigin"]:
+        raise DeploymentKitError("Legacy host rollback did not restore a ready unauthenticated scope.")
+
+
+def _parse_migration_proof(output: str, expected_route_count: int) -> dict[str, Any]:
+    result: dict[str, str] = {}
+    for line in output.splitlines():
+        if "=" not in line:
+            raise DeploymentKitError("Authenticated-origin final proof was malformed.")
+        key, value = line.split("=", 1)
+        if key in result:
+            raise DeploymentKitError("Authenticated-origin final proof contained duplicate fields.")
+        result[key] = value
+    expected = {
+        "evidenceLevel": "structural-only",
+        "connectorOriginMount": "read-only",
+        "socketMetadataVerified": "true",
+        "caddyConfigValidated": "true",
+        "sanitizedRouteConfigVerified": "true",
+        "managedRouteCount": str(expected_route_count),
+    }
+    if result != expected:
+        raise DeploymentKitError("Authenticated-origin structural checks did not match the reviewed contract.")
+    return {
+        "evidenceLevel": "structural-only",
+        "connectorOriginMountReadOnly": True,
+        "socketMetadataVerified": True,
+        "caddyConfigValidated": True,
+        "sanitizedRouteConfigVerified": True,
+        "managedRouteCount": expected_route_count,
+        "liveSocketForwardingVerified": False,
+    }
+
+
+def apply_authenticated_origin_migration(
+    plan: dict[str, Any],
+    *,
+    api_token: str,
+    change_freeze_acknowledgement: str,
+    _lock_held: bool = False,
+) -> dict[str, Any]:
+    """Apply one reviewed existing-scope mode migration without replacing identities."""
+    required = {
+        "targetName", "scope", "action", "migrationState", "hostStatusSnapshot",
+        "zone", "tunnel", "routeInventorySnapshot", "routeInventoryWireSnapshot",
+        "managedRoutes", "dnsSnapshot", "tunnelConfigSha256",
+        "desiredTunnelConfigSha256", "convertedRouteCount", "unmanagedIngressRuleCount",
+        "unmanagedIngressRulesSha256", "requiredAuthorization",
+        "changeFreezePrerequisite", "requiredChangeFreezeAcknowledgement", "secrets",
+        "requiredPrePlanChangeFreezeAcknowledgement",
+    }
+    if not isinstance(plan, dict) or set(plan) != required:
+        raise DeploymentKitError("Malformed authenticated-origin migration plan.")
+    if (
+        plan["requiredAuthorization"] != AUTHENTICATED_ORIGIN_MIGRATION_PHRASE
+        or plan["action"] not in {"prepare", "resume"}
+        or plan["migrationState"] not in {"clean", "pending"}
+        or type(plan["convertedRouteCount"]) is not int
+        or not isinstance(plan["managedRoutes"], list)
+        or not plan["managedRoutes"]
+    ):
+        raise DeploymentKitError("Malformed authenticated-origin migration authorization or route plan.")
+    if (
+        plan["requiredChangeFreezeAcknowledgement"]
+        != _required_change_freeze_acknowledgement(plan)
+        or plan["requiredPrePlanChangeFreezeAcknowledgement"]
+        != _required_preplan_change_freeze_acknowledgement(plan["scope"])
+        or change_freeze_acknowledgement != plan["requiredChangeFreezeAcknowledgement"]
+    ):
+        raise DeploymentKitError(
+            "The required scope- and context-bound Cloudflare change-freeze acknowledgement is missing or invalid."
+        )
+    if not _lock_held:
+        with route_transaction_lock(plan["targetName"], plan["scope"]):
+            return apply_authenticated_origin_migration(
+                plan,
+                api_token=api_token,
+                change_freeze_acknowledgement=change_freeze_acknowledgement,
+                _lock_held=True,
+            )
+
+    name, scope = plan["targetName"], _slug(plan["scope"], "scope")
+    zone = cloudflare_api.resolve_zone(api_token, plan["zone"]["zoneName"])
+    if zone != plan["zone"]:
+        raise DeploymentKitError("Cloudflare zone identity changed after migration planning; create a fresh plan.")
+    host = cloudflare_ingress_status(name, scope)
+    if _status_snapshot(host) != plan["hostStatusSnapshot"]:
+        raise DeploymentKitError("Host Cloudflare ingress state changed after migration planning.")
+    if host["state"] != "ready" or host["authenticatedOrigin"] != (plan["migrationState"] == "pending"):
+        raise DeploymentKitError("Host mode no longer matches the reviewed migration phase.")
+    migration_state = _remote_migration_state(name, scope)
+    if migration_state != plan["migrationState"]:
+        raise DeploymentKitError("Host migration receipt changed after planning; create a fresh plan.")
+
+    tunnel_value = cloudflare_api.find_tunnel(api_token, zone["accountId"], host["tunnelName"])
+    if (
+        _tunnel_summary(tunnel_value) != plan["tunnel"]
+        or tunnel_value is None
+        or str(tunnel_value.get("id")) != host["tunnelId"]
+        or tunnel_value.get("config_src") not in {None, "cloudflare"}
+    ):
+        raise DeploymentKitError("Existing Cloudflare tunnel identity changed after migration planning.")
+    tunnel = {"id": host["tunnelId"], "name": host["tunnelName"]}
+
+    inventory = cloudflare_route_inventory(name, scope)
+    if (
+        _route_inventory_snapshot(inventory) != plan["routeInventorySnapshot"]
+        or _route_inventory_wire_snapshot(inventory) != plan["routeInventoryWireSnapshot"]
+        or sorted(inventory["managedRoutes"], key=lambda item: item["routeId"]) != plan["managedRoutes"]
+    ):
+        raise DeploymentKitError("Managed public-route ownership changed after migration planning.")
+    for spec in plan["managedRoutes"]:
+        _lan_route(name, spec)
+
+    config = cloudflare_api.get_tunnel_configuration(api_token, zone["accountId"], host["tunnelId"])
+    if _config_snapshot(config) != plan["tunnelConfigSha256"]:
+        raise DeploymentKitError("Cloudflare tunnel configuration changed after migration planning.")
+    desired_config, converted_count = _migration_ingress_config(
+        config, plan["managedRoutes"], host_authenticated=host["authenticatedOrigin"]
+    )
+    unmanaged_summary = _unmanaged_ingress_summary(config, plan["managedRoutes"])
+    if (
+        _config_snapshot(desired_config) != plan["desiredTunnelConfigSha256"]
+        or converted_count != plan["convertedRouteCount"]
+        or unmanaged_summary["unmanagedIngressRuleCount"] != plan["unmanagedIngressRuleCount"]
+        or unmanaged_summary["unmanagedIngressRulesSha256"] != plan["unmanagedIngressRulesSha256"]
+    ):
+        raise DeploymentKitError("Managed ingress rule ownership no longer matches the reviewed migration.")
+    dns_snapshot = _migration_dns_snapshot(api_token, host, plan["managedRoutes"])
+    if dns_snapshot != plan["dnsSnapshot"]:
+        raise DeploymentKitError("Cloudflare DNS ownership or record identities changed after planning.")
+
+    host_prepared_by_this_apply = plan["migrationState"] == "clean"
+    if host_prepared_by_this_apply:
+        _migration_remote_action(
+            name,
+            scope,
+            "migrate-authenticated",
+            zone=zone,
+            tunnel=tunnel,
+            route_snapshot=plan["routeInventoryWireSnapshot"],
+        )
+        prepared_host = cloudflare_ingress_status(name, scope)
+        prepared_inventory = cloudflare_route_inventory(name, scope)
+        if (
+            prepared_host["state"] != "ready"
+            or not prepared_host["authenticatedOrigin"]
+            or _route_inventory_snapshot(prepared_inventory) != plan["routeInventorySnapshot"]
+            or _remote_migration_state(name, scope) != "pending"
+        ):
+            raise DeploymentKitError(
+                "Authenticated-origin host preparation failed verification; provider ingress was not changed."
+            )
+
+    prewrite_host = cloudflare_ingress_status(name, scope)
+    prewrite_inventory = cloudflare_route_inventory(name, scope)
+    prewrite_tunnel = cloudflare_api.find_tunnel(api_token, zone["accountId"], host["tunnelName"])
+    if (
+        prewrite_host["state"] != "ready"
+        or not prewrite_host["authenticatedOrigin"]
+        or prewrite_host["tunnelId"] != host["tunnelId"]
+        or prewrite_host["tunnelName"] != host["tunnelName"]
+        or _route_inventory_snapshot(prewrite_inventory) != plan["routeInventorySnapshot"]
+        or _tunnel_summary(prewrite_tunnel) != plan["tunnel"]
+        or _migration_dns_snapshot(api_token, prewrite_host, plan["managedRoutes"]) != plan["dnsSnapshot"]
+        or _remote_migration_state(name, scope) != "pending"
+    ):
+        raise DeploymentKitError(
+            "Host, tunnel, managed-route, DNS, or recovery evidence changed before provider apply; "
+            "the authenticated host phase was retained."
+        )
+    prewrite_config = cloudflare_api.get_tunnel_configuration(
+        api_token, zone["accountId"], host["tunnelId"]
+    )
+    if _reviewed_config_matches(prewrite_config, desired_config):
+        desired_already_applied = True
+    elif _config_snapshot(prewrite_config) != plan["tunnelConfigSha256"]:
+        raise DeploymentKitError(
+            "Cloudflare tunnel configuration changed during host preparation; "
+            "provider state was preserved and the authenticated host phase was retained."
+        )
+    else:
+        desired_already_applied = False
+
+    # Cloudflare exposes a whole-configuration PUT without compare-and-swap.
+    # The operator's external-writer freeze is the concurrency prerequisite;
+    # these reads detect stale evidence but cannot enforce that freeze.
+    if not desired_already_applied:
+        try:
+            cloudflare_api.update_tunnel_configuration(
+                api_token, zone["accountId"], host["tunnelId"], desired_config
+            )
+        except Exception as write_error:
+            try:
+                after_error = cloudflare_api.get_tunnel_configuration(
+                    api_token, zone["accountId"], host["tunnelId"]
+                )
+            except Exception:
+                raise DeploymentKitError(
+                    "Provider migration response is uncertain. The authenticated host phase and recovery receipt "
+                    "were retained; inspect Cloudflare state and re-plan before retrying."
+                ) from write_error
+            if _reviewed_config_matches(after_error, prewrite_config):
+                if host_prepared_by_this_apply:
+                    try:
+                        _rollback_prepared_migration(
+                            name, scope, zone=zone, tunnel=tunnel,
+                            route_snapshot=plan["routeInventoryWireSnapshot"],
+                        )
+                    except Exception as rollback_error:
+                        raise DeploymentKitError(
+                            "Provider state is unchanged, but authenticated host rollback did not complete. "
+                            "The migration receipt was retained for safe recovery."
+                        ) from rollback_error
+                raise DeploymentKitError(
+                    "Cloudflare provider update failed before changing the reviewed configuration; "
+                    "the operation was rolled back or remains safely resumable."
+                ) from write_error
+            if not _reviewed_config_matches(after_error, desired_config):
+                raise DeploymentKitError(
+                    "Provider migration response is uncertain and current configuration differs from both "
+                    "reviewed states. The authenticated host phase was retained; no rollback overwrote provider state."
+                ) from write_error
+
+    final_config = cloudflare_api.get_tunnel_configuration(
+        api_token, zone["accountId"], host["tunnelId"]
+    )
+    if not _reviewed_config_matches(final_config, desired_config):
+        raise DeploymentKitError(
+            "Provider migration did not produce the exact reviewed authenticated rules; "
+            "the host recovery receipt was retained."
+        )
+    final_host = cloudflare_ingress_status(name, scope)
+    final_inventory = cloudflare_route_inventory(name, scope)
+    final_dns_snapshot = _migration_dns_snapshot(api_token, final_host, plan["managedRoutes"])
+    if (
+        final_host["state"] != "ready"
+        or not final_host["authenticatedOrigin"]
+        or final_host["tunnelId"] != host["tunnelId"]
+        or final_host["tunnelName"] != host["tunnelName"]
+        or _route_inventory_snapshot(final_inventory) != plan["routeInventorySnapshot"]
+        or final_dns_snapshot != plan["dnsSnapshot"]
+    ):
+        raise DeploymentKitError(
+            "Final migration state changed or did not preserve the reviewed tunnel, routes, or DNS identities; "
+            "host recovery evidence was retained."
+        )
+    proof_output = _migration_remote_action(
+        name,
+        scope,
+        "verify-authenticated",
+        zone=zone,
+        tunnel=tunnel,
+        route_snapshot=plan["routeInventoryWireSnapshot"],
+    )
+    proof = _parse_migration_proof(proof_output, len(plan["managedRoutes"]))
+
+    _migration_remote_action(
+        name,
+        scope,
+        "finalize-authenticated",
+        zone=zone,
+        tunnel=tunnel,
+        route_snapshot=plan["routeInventoryWireSnapshot"],
+    )
+    if _remote_migration_state(name, scope) != "complete":
+        raise DeploymentKitError(
+            "Migration is verified but the host recovery receipt could not be finalized; inspect before retrying."
+        )
+    post_finalize_host = cloudflare_ingress_status(name, scope)
+    if (
+        post_finalize_host["state"] != "ready"
+        or not post_finalize_host["authenticatedOrigin"]
+        or post_finalize_host["tunnelId"] != host["tunnelId"]
+    ):
+        raise DeploymentKitError("Final host status changed after migration finalization.")
+    return {
+        "targetName": name,
+        "scope": scope,
+        "tunnelId": host["tunnelId"],
+        "tunnelName": host["tunnelName"],
+        "authenticatedOrigin": True,
+        "managedRoutes": [
+            {"routeId": spec["routeId"], "publicHostname": spec["publicHostname"]}
+            for spec in plan["managedRoutes"]
+        ],
+        "preservedDnsRecordIds": [
+            {"routeId": item["routeId"], "recordId": item["recordId"]}
+            for item in plan["dnsSnapshot"]
+        ],
+        "structuralEvidence": proof,
+        "liveSocketForwardingVerified": False,
+        "endToEndReadiness": "unproven",
+        "requiredAuthorization": AUTHENTICATED_ORIGIN_MIGRATION_PHRASE,
+        "mutated": True,
+    }
+
+
 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]