@mriekki/project-forge 4.21.0 → 4.22.0

package/assets/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.21.0",
+  "version": "4.22.0",
   "defaultProfile": "greenfield-project",
   "profiles": {
     "greenfield-project": {
@@ -21,7 +21,7 @@
       "canonicalDescriptor": "distributions/greenfield-workspace.json"
     },
     "deployment": {
-      "revision": "f2d20ec7aac61494ef9fdb7f3702060b8d8d8865",
+      "revision": "2258794181483747ed11a2c3c3226d6e66e1b9bb",
       "distribution": "greenfield-project",
       "descriptor": "assets/deployment/distribution.json",
       "sourceRoot": "assets/generated/deployment",

package/assets/generated/ASSEMBLY.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.21.0",
+  "version": "4.22.0",
   "components": {
     "core": {
       "revision": "4c74c1801b82d3aa438447d392024d32ca5697b0",
@@ -361,7 +361,7 @@
       ]
     },
     "deployment": {
-      "revision": "f2d20ec7aac61494ef9fdb7f3702060b8d8d8865",
+      "revision": "2258794181483747ed11a2c3c3226d6e66e1b9bb",
       "distribution": "greenfield-project",
       "files": [
         {
@@ -437,12 +437,12 @@
         {
           "source": "src/project_forge_deployment/cloudflare_ingress.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/cloudflare_ingress.py",
-          "sha256": "d07c79b7f9f6c9a0f9b417fd0a1d4502101075b128a12d23b2791c31e03d4f01"
+          "sha256": "31541e115f474fd3bd2a426eac1ca1beea429633c6ecc48afeace025a85054a9"
         },
         {
           "source": "src/project_forge_deployment/cloudflare_ingress_remote.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/cloudflare_ingress_remote.py",
-          "sha256": "73d9f68cbece33155ccac8ce2e24da8f0ec6698a7b66fba18cb9bf38734ea686"
+          "sha256": "19de0d8c04b7ad0006b8bc341eabd52a5eaa50c0e0bacdc9edb856de101dd259"
         },
         {
           "source": "src/project_forge_deployment/cloudflare_route_apply.py",
@@ -502,7 +502,7 @@
         {
           "source": "src/project_forge_deployment/ingress_cli.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/ingress_cli.py",
-          "sha256": "973b89daa7e57d925f0be56fbfc0dc4c6f79ab082036c7fb26462691f2f16d02"
+          "sha256": "069a7e5a4c7921448e6965ebff2df8b38a9aba77aaff1154a54969ab0e234324"
         },
         {
           "source": "src/project_forge_deployment/keys.py",
@@ -647,7 +647,7 @@
         {
           "source": "docs/CLOUDFLARE_INGRESS.md",
           "destination": "docs/project-forge/CLOUDFLARE_INGRESS.md",
-          "sha256": "b47bfb1ef1dcd7be3c501b88add0dea675907ce3f9e65cf7852c5ffddbe0ce46"
+          "sha256": "396327ae00bf4a54eeaea6eec8c07a17af6084eed5c4d0be97b55b29bd0160ff"
         },
         {
           "source": "docs/DEVELOPER_ENVIRONMENTS.md",

package/assets/generated/deployment/docs/CLOUDFLARE_INGRESS.md

@@ -200,11 +200,45 @@ without a zone or public hostname. Once a domain is registered and active in Clo
 
 The shared Cloudflare zone is environment infrastructure and should not be copied into every Project as a credential-like default. The exact application hostname remains Project/environment state.
 
-## Experimental authenticated public-origin mode (new scopes only)
+## Experimental authenticated public-origin mode
 
 For an isolated test scope, `ingress cloudflare configure` supports `--authenticated-origin`. This explicit opt-in provisions a private Caddy Unix listener and mounts its socket directory only in the pinned cloudflared connector. Public hostname rules use `unix:/run/project-forge-origin/origin.sock` and the public hostname as Host; the LAN TCP listener and the existing default mode remain unchanged. The remote adapter derives each authenticated route's upstream from its still-owned LAN registry entry and strips/replaces forwarding headers before proxying.
 
-**Not a supported Production setting yet:** origin mount possession is not end-user login. Real pinned cloudflared edge-to-app forwarding, canonical client-IP semantics, app proxy-peer trust, socket replacement, and rollback still need live proof. Do not grant the socket mount to unrelated containers or treat forwarded IP headers as an authorization credential. An installed ingress scope cannot switch modes in place; use a new dedicated scope and the normal host/route write gates. See the canonical Kit's `docs/EXPERIMENTAL_AUTHENTICATED_ORIGIN.md` and issue #78 for the detailed evidence boundary.
+**Not a supported Production setting yet:** origin mount possession is not end-user login. Real pinned cloudflared edge-to-app forwarding, canonical client-IP semantics, app proxy-peer trust, socket replacement, and rollback still need live proof. Do not grant the socket mount to unrelated containers or treat forwarded IP headers as an authorization credential.
+
+An existing legacy scope can be migrated without replacing its tunnel, public routes, DNS/CNAME records, or unrelated tunnel rules. The operation has its own read-only plan, exact interactive authorization, and guarded apply:
+
+```text
+project-forge-deploy ingress cloudflare migrate-authenticated-origin <target> \
+  --scope production \
+  --zone example.com
+```
+
+Before planning, the operator must stop all Cloudflare dashboard/API tunnel-configuration writers for this scope. The CLI asks for an exact scope-bound freeze-active acknowledgment before making plan reads, and the programmatic planning API requires the corresponding `change_freeze_active_acknowledgement`, for example:
+
+```text
+[CLOUDFLARE EXTERNAL CHANGE FREEZE] ACTIVE scope=production
+```
+
+The freeze must remain in effect through apply, verification, and any rollback or recovery. It is an external operational prerequisite: the Deployment Kit cannot enforce it, identify all external writers, or prove that they are stopped. Cloudflare's full-configuration PUT has no compare-and-swap; pre-write snapshots and post-write checks do not prevent an external write from racing between a read and PUT. Do not start the operation unless this freeze can be maintained.
+
+The plan requires every host-registered route to match one exact Project Forge legacy provider rule and one exact owned DNS record. Conflicting/unowned rules for managed hostnames, missing or duplicate routes, stale host/provider/DNS snapshots, or incomplete host migration evidence stop the operation. Other provider rules remain unchanged; no DNS write or tunnel creation occurs. Apply holds the existing per-scope host lock, prepares the connector-only socket and sanitized Caddy routes first, then changes only the exact managed Cloudflare rules. It rechecks ownership immediately before each phase and verifies the unchanged tunnel, route and DNS identities plus the socket/header contract afterward. These checks are defense in depth, not enforcement of the external freeze. There is no generic `--yes` bypass; the CLI first requires:
+
+```text
+[CLOUDFLARE AUTHENTICATED ORIGIN MIGRATION]
+```
+
+After showing the plan, the CLI separately requires the migration authorization and an exact freeze acknowledgment bound to the reviewed scope and snapshot context, for example:
+
+```text
+[CLOUDFLARE EXTERNAL CHANGE FREEZE] scope=production context=<plan-specific digest>
+```
+
+The programmatic apply API likewise requires `change_freeze_acknowledgement`; migration authorization alone is insufficient. The bound acknowledgment prevents accidental reuse for a different scope/plan, but is an operator assertion only—not a lock on Cloudflare. If the provider update is confirmed unchanged, a newly prepared host phase is rolled back from a protected host receipt. If provider state is uncertain or differs from both reviewed states, the host remains authenticated with its receipt retained; maintain the external freeze and do not hand-edit or rerun blindly. Re-plan/resume or roll back only after inspecting current state; keep the freeze until recovery is complete. This migration still does not establish an application identity/login flow or replace disposable application/database state.
+
+Final migration output labels its evidence **structural-only**: it checks socket metadata, connector mount configuration, Caddy configuration, and the generated sanitized route files. It does not prove that the running pinned cloudflared connector can forward an HTTP request over that socket or that an application receives the intended headers. Live socket forwarding and end-to-end readiness remain unproven.
+
+See `docs/EXPERIMENTAL_AUTHENTICATED_ORIGIN.md` and issue #78 for the detailed evidence boundary. For a new isolated scope, `configure --authenticated-origin` and the normal route gates remain unchanged.
 
 ## Current cloudflared runtime
 

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]

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

@@ -2,6 +2,7 @@
 
 REMOTE_SCRIPT = r"""#!/usr/bin/env bash
 set -Eeuo pipefail
+export LC_ALL=C
 
 ACTION="$1"
 SCOPE="$2"
@@ -43,6 +44,9 @@ AUTH_ROOT="$PLATFORM_ROOT/proxy/data/authenticated/$SCOPE"
 AUTH_ROUTES="$AUTH_ROOT/routes"
 AUTH_CADDY="$PLATFORM_ROOT/proxy/conf.d/90-project-forge-auth-$SCOPE.caddy"
 AUTH_SOCKET="$AUTH_ROOT/origin.sock"
+MIGRATION_MARKER_BACKUP="$ROOT/.authenticated-origin-migration.marker"
+MIGRATION_COMPOSE_BACKUP="$ROOT/.authenticated-origin-migration.compose"
+MIGRATION_RECEIPT="$ROOT/.authenticated-origin-migration.receipt"
 CONTAINER="project-forge-cloudflared-$SCOPE"
 LOCK_FILE="/run/lock/project-forge-cloudflare-$SCOPE.lock"
 
@@ -204,6 +208,7 @@ http://:19078 {
 EOF
     chmod 0644 "$tmp"
     mv -f "$tmp" "$AUTH_CADDY"
+    MIGRATION_CADDY_HASH="$(sha256sum "$AUTH_CADDY" | cut -d' ' -f1)"
     docker exec "$CADDY_CONTAINER" caddy reload --config /etc/caddy/Caddyfile >/dev/null
     [[ -S "$AUTH_SOCKET" ]] || {
         echo "Authenticated private origin socket did not appear." >&2; exit 27;
@@ -245,7 +250,19 @@ auth_route_write() {
     tmp="$file.tmp.$BASHPID"
     backup="$file.backup.$BASHPID"
     [[ ! -f "$file" ]] || cp -a "$file" "$backup"
-    cat > "$tmp" <<EOF
+    auth_route_content > "$tmp"
+    chmod 0644 "$tmp"
+    mv -f "$tmp" "$file"
+    if ! docker exec "$CADDY_CONTAINER" caddy reload --config /etc/caddy/Caddyfile >/dev/null; then
+        if [[ -f "$backup" ]]; then mv -f "$backup" "$file"; else rm -f "$file"; fi
+        docker exec "$CADDY_CONTAINER" caddy reload --config /etc/caddy/Caddyfile >/dev/null 2>&1 || true
+        echo "Authenticated Caddy route failed validation; restored previous state." >&2
+        exit 35
+    fi
+    rm -f "$backup"
+}
+auth_route_content() {
+    cat <<EOF
 @pf_$R_ROUTE host $R_PUBLIC
 handle @pf_$R_ROUTE {
     reverse_proxy $AUTH_UPSTREAM:$AUTH_PORT {
@@ -263,15 +280,6 @@ handle @pf_$R_ROUTE {
     }
 }
 EOF
-    chmod 0644 "$tmp"
-    mv -f "$tmp" "$file"
-    if ! docker exec "$CADDY_CONTAINER" caddy reload --config /etc/caddy/Caddyfile >/dev/null; then
-        if [[ -f "$backup" ]]; then mv -f "$backup" "$file"; else rm -f "$file"; fi
-        docker exec "$CADDY_CONTAINER" caddy reload --config /etc/caddy/Caddyfile >/dev/null 2>&1 || true
-        echo "Authenticated Caddy route failed validation; restored previous state." >&2
-        exit 35
-    fi
-    rm -f "$backup"
 }
 auth_route_remove() {
     [[ "$(marker_value AUTHENTICATED_ORIGIN)" == true ]] || return 0
@@ -364,6 +372,320 @@ route_inventory() {
     return 0
 }
 
+route_inventory_digest() {
+    route_inventory | sha256sum | cut -d' ' -f1
+}
+
+auth_files_digest() {
+    if [[ ! -d "$AUTH_ROOT" ]]; then
+        printf ''
+        return
+    fi
+    (
+        cd "$AUTH_ROOT"
+        find . -type f -print0 | sort -z | xargs -0r sha256sum
+    ) | sha256sum | cut -d' ' -f1
+}
+
+receipt_value() {
+    local key="$1"
+    [[ -f "$MIGRATION_RECEIPT" && ! -L "$MIGRATION_RECEIPT" ]] || return 1
+    sed -n "s/^${key}=//p" "$MIGRATION_RECEIPT" | head -n1
+}
+
+migration_pending_valid() {
+    [[ -f "$MIGRATION_MARKER_BACKUP" && ! -L "$MIGRATION_MARKER_BACKUP" &&
+       -f "$MIGRATION_COMPOSE_BACKUP" && ! -L "$MIGRATION_COMPOSE_BACKUP" &&
+       -f "$MIGRATION_RECEIPT" && ! -L "$MIGRATION_RECEIPT" &&
+       -f "$MARKER" && ! -L "$MARKER" &&
+       -f "$COMPOSE_FILE" && ! -L "$COMPOSE_FILE" &&
+       -f "$AUTH_CADDY" && ! -L "$AUTH_CADDY" &&
+       -d "$AUTH_ROOT" && ! -L "$AUTH_ROOT" &&
+       -d "$AUTH_ROUTES" && ! -L "$AUTH_ROUTES" ]] || return 1
+    [[ "$(marker_value AUTHENTICATED_ORIGIN 2>/dev/null || true)" == true ]] || return 1
+    [[ "$(route_inventory_digest)" == "$(receipt_value ROUTE_SNAPSHOT_SHA256)" ]] || return 1
+    [[ "$(sha256sum "$MARKER" | cut -d' ' -f1)" == "$(receipt_value MARKER_SHA256)" ]] || return 1
+    [[ "$(sha256sum "$COMPOSE_FILE" | cut -d' ' -f1)" == "$(receipt_value COMPOSE_SHA256)" ]] || return 1
+    [[ "$(sha256sum "$AUTH_CADDY" | cut -d' ' -f1)" == "$(receipt_value CADDY_SHA256)" ]] || return 1
+    [[ "$(auth_files_digest)" == "$(receipt_value AUTH_FILES_SHA256)" ]] || return 1
+    return 0
+}
+
+migration_inspect() {
+    local mode state
+    mode="$(marker_value AUTHENTICATED_ORIGIN 2>/dev/null || true)"
+    if [[ "$mode" == true ]]; then
+        if migration_pending_valid; then
+            state=pending
+        elif [[ ! -e "$MIGRATION_MARKER_BACKUP" && ! -e "$MIGRATION_COMPOSE_BACKUP" &&
+                ! -e "$MIGRATION_RECEIPT" ]]; then
+            state=complete
+        else
+            echo "Authenticated-origin migration recovery evidence is incomplete or changed." >&2
+            exit 37
+        fi
+    elif [[ "$mode" == false && ! -e "$MIGRATION_MARKER_BACKUP" &&
+            ! -e "$MIGRATION_COMPOSE_BACKUP" && ! -e "$MIGRATION_RECEIPT" &&
+            ! -e "$AUTH_ROOT" && ! -e "$AUTH_CADDY" ]]; then
+        state=clean
+    else
+        echo "Authenticated-origin migration paths conflict with unowned or incomplete state." >&2
+        exit 37
+    fi
+    printf 'migrationState=%s\n' "$state"
+}
+
+migration_rollback_on_error() {
+    local original_status="$1" rollback_failed=false path
+    trap - ERR EXIT
+    set +e
+    if [[ -f "$MIGRATION_MARKER_BACKUP" && ! -L "$MIGRATION_MARKER_BACKUP" ]]; then
+        cp -p "$MIGRATION_MARKER_BACKUP" "$MARKER.rollback.$$" &&
+            mv -f "$MARKER.rollback.$$" "$MARKER" || rollback_failed=true
+    fi
+    if [[ -f "$MIGRATION_COMPOSE_BACKUP" && ! -L "$MIGRATION_COMPOSE_BACKUP" ]]; then
+        cp -p "$MIGRATION_COMPOSE_BACKUP" "$COMPOSE_FILE.rollback.$$" &&
+            mv -f "$COMPOSE_FILE.rollback.$$" "$COMPOSE_FILE" || rollback_failed=true
+        docker compose -f "$COMPOSE_FILE" up -d --force-recreate >/dev/null 2>&1 || rollback_failed=true
+    fi
+    if [[ -e "$AUTH_CADDY" ]]; then
+        if [[ -f "$AUTH_CADDY" && ! -L "$AUTH_CADDY" &&
+              "$(sha256sum "$AUTH_CADDY" | cut -d' ' -f1)" == "${MIGRATION_CADDY_HASH:-}" ]]; then
+            rm -f "$AUTH_CADDY"
+            docker exec "$CADDY_CONTAINER" caddy reload --config /etc/caddy/Caddyfile >/dev/null 2>&1 ||
+                rollback_failed=true
+        else
+            rollback_failed=true
+        fi
+    fi
+    local index
+    for index in "${!MIGRATION_CREATED_ROUTES[@]}"; do
+        path="${MIGRATION_CREATED_ROUTES[$index]}"
+        if [[ "$path" == "$AUTH_ROUTES/"*.caddy && -f "$path" && ! -L "$path" &&
+              "$(sha256sum "$path" | cut -d' ' -f1)" == "${MIGRATION_CREATED_ROUTE_HASHES[$index]}" ]]; then
+            rm -f "$path"
+        else
+            rollback_failed=true
+        fi
+    done
+    if [[ -e "$AUTH_SOCKET" ]]; then
+        if [[ -S "$AUTH_SOCKET" && "$(stat -c '%u:%g:%a' "$AUTH_SOCKET")" == "65532:65532:222" ]]; then
+            rm -f "$AUTH_SOCKET"
+        else
+            rollback_failed=true
+        fi
+    fi
+    if [[ -d "$AUTH_ROUTES" ]] && ! rmdir "$AUTH_ROUTES" 2>/dev/null; then rollback_failed=true; fi
+    if [[ -d "$AUTH_ROOT" ]] && ! rmdir "$AUTH_ROOT" 2>/dev/null; then rollback_failed=true; fi
+    if [[ "$rollback_failed" == false ]]; then
+        rm -f "$MIGRATION_MARKER_BACKUP" "$MIGRATION_COMPOSE_BACKUP" "$MIGRATION_RECEIPT"
+        echo "Authenticated-origin host preparation failed and was rolled back." >&2
+    else
+        echo "Authenticated-origin host preparation failed; rollback is incomplete and recovery evidence was retained." >&2
+    fi
+    exit "$original_status"
+}
+
+migrate_authenticated_origin() {
+    local expected_route_digest="$EXPECTED" state path route_spec
+    [[ "$AUTHENTICATED_ORIGIN" == true ]] || { echo "Authenticated-origin migration must opt in explicitly." >&2; exit 37; }
+    [[ "$(status | sed -n 's/^state=//p' | head -n1)" == ready &&
+       "$(marker_value AUTHENTICATED_ORIGIN 2>/dev/null || true)" == false ]] || {
+        echo "Authenticated-origin migration requires a ready legacy scope." >&2; exit 37;
+    }
+    [[ "$(route_inventory_digest)" == "$expected_route_digest" ]] || {
+        echo "Managed public-route inventory changed after planning." >&2; exit 37;
+    }
+    state="$(migration_inspect | sed -n 's/^migrationState=//p')"
+    [[ "$state" == clean ]] || { echo "Authenticated-origin migration is not in a clean host state." >&2; exit 37; }
+    parse_meta
+    [[ "$(marker_value ACCOUNT_ID)" == "$M_ACCOUNT" &&
+       "$(marker_value ZONE_ID)" == "$M_ZONE_ID" &&
+       "$(marker_value ZONE_NAME)" == "$M_ZONE_NAME" &&
+       "$(marker_value TUNNEL_ID)" == "$M_TUNNEL_ID" &&
+       "$(marker_value TUNNEL_NAME)" == "$M_TUNNEL_NAME" ]] || {
+        echo "Existing host tunnel binding changed after planning." >&2; exit 37;
+    }
+    [[ -f "$MARKER" && ! -L "$MARKER" && -f "$COMPOSE_FILE" && ! -L "$COMPOSE_FILE" &&
+       -f "$TOKEN_FILE" && ! -L "$TOKEN_FILE" && -d "$ROUTE_ROOT" && ! -L "$ROUTE_ROOT" ]] || {
+        echo "Existing ingress host files are incomplete or unsafe." >&2; exit 37;
+    }
+    local route_count=0
+    MIGRATION_CREATED_ROUTES=()
+    MIGRATION_CREATED_ROUTE_HASHES=()
+    trap 'migration_rollback_on_error "$?"' EXIT
+    cp -p "$MARKER" "$MIGRATION_MARKER_BACKUP"
+    cp -p "$COMPOSE_FILE" "$MIGRATION_COMPOSE_BACKUP"
+    chmod 0600 "$MIGRATION_MARKER_BACKUP" "$MIGRATION_COMPOSE_BACKUP"
+    setup_authenticated_origin
+    AUTHENTICATED_ORIGIN=true
+    write_marker
+    write_compose
+    for path in "$ROUTE_ROOT"/*.route; do
+        [[ -f "$path" ]] || continue
+        route_spec="$(printf '%s\t%s\t%s\t%s\t%s\t%s\t%s' \
+            "$(route_value "$path" SCHEMA_VERSION)" "$(route_value "$path" OWNER_REPO)" \
+            "$(route_value "$path" ENVIRONMENT)" "$(route_value "$path" APP_SLUG)" \
+            "$(route_value "$path" ROUTE_ID)" "$(route_value "$path" PUBLIC_HOSTNAME)" \
+            "$(route_value "$path" ORIGIN_HOSTNAME)")"
+        parse_spec_value "$route_spec"
+        [[ "$(basename "$path")" == "$R_ROUTE.route" ]] || {
+            echo "Managed public-route identity is malformed." >&2; exit 37;
+        }
+        SPEC="$route_spec"
+        auth_route_write
+        MIGRATION_CREATED_ROUTES+=("$(auth_route_path "$R_ROUTE")")
+        MIGRATION_CREATED_ROUTE_HASHES+=("$(sha256sum "$(auth_route_path "$R_ROUTE")" | cut -d' ' -f1)")
+        route_count=$((route_count + 1))
+    done
+    (( route_count > 0 )) || { echo "No managed public routes are available to migrate." >&2; exit 37; }
+    docker compose -f "$COMPOSE_FILE" up -d --force-recreate >/dev/null
+    [[ "$(status | sed -n 's/^state=//p' | head -n1)" == ready &&
+       "$(marker_value AUTHENTICATED_ORIGIN)" == true ]] || {
+        echo "Authenticated-origin connector did not become ready." >&2; exit 37;
+    }
+    cat > "$MIGRATION_RECEIPT.tmp.$$" <<EOF
+ROUTE_SNAPSHOT_SHA256=$expected_route_digest
+MARKER_SHA256=$(sha256sum "$MARKER" | cut -d' ' -f1)
+COMPOSE_SHA256=$(sha256sum "$COMPOSE_FILE" | cut -d' ' -f1)
+CADDY_SHA256=$(sha256sum "$AUTH_CADDY" | cut -d' ' -f1)
+AUTH_FILES_SHA256=$(auth_files_digest)
+EOF
+    chmod 0600 "$MIGRATION_RECEIPT.tmp.$$"
+    mv -f "$MIGRATION_RECEIPT.tmp.$$" "$MIGRATION_RECEIPT"
+    migration_pending_valid || { echo "Authenticated-origin recovery receipt validation failed." >&2; exit 37; }
+    trap - ERR EXIT
+    printf 'migrationState=pending\n'
+}
+
+rollback_authenticated_origin() {
+    migration_pending_valid || { echo "Authenticated-origin migration rollback evidence is stale or unsafe." >&2; exit 38; }
+    [[ "$(status | sed -n 's/^state=//p' | head -n1)" == ready ]] || {
+        echo "Authenticated-origin host is not ready for rollback." >&2; exit 38;
+    }
+    cp -p "$MIGRATION_MARKER_BACKUP" "$MARKER.rollback.$$"
+    mv -f "$MARKER.rollback.$$" "$MARKER"
+    cp -p "$MIGRATION_COMPOSE_BACKUP" "$COMPOSE_FILE.rollback.$$"
+    mv -f "$COMPOSE_FILE.rollback.$$" "$COMPOSE_FILE"
+    docker compose -f "$COMPOSE_FILE" up -d --force-recreate >/dev/null
+    [[ "$(status | sed -n 's/^state=//p' | head -n1)" == ready &&
+       "$(marker_value AUTHENTICATED_ORIGIN 2>/dev/null || true)" == false ]] || {
+        echo "Legacy connector did not become ready after authenticated-origin rollback." >&2; exit 38;
+    }
+    [[ -f "$AUTH_CADDY" && ! -L "$AUTH_CADDY" ]] || {
+        echo "Authenticated Caddy configuration changed before rollback." >&2; exit 38;
+    }
+    rm -f "$AUTH_CADDY"
+    docker exec "$CADDY_CONTAINER" caddy reload --config /etc/caddy/Caddyfile >/dev/null
+    for path in "$AUTH_ROUTES"/*.caddy; do [[ -f "$path" ]] && rm -f "$path"; done
+    if [[ -e "$AUTH_SOCKET" ]]; then
+        [[ -S "$AUTH_SOCKET" && "$(stat -c '%u:%g:%a' "$AUTH_SOCKET")" == "65532:65532:222" ]] || {
+            echo "Authenticated origin socket changed before rollback." >&2; exit 38;
+        }
+        rm -f "$AUTH_SOCKET"
+    fi
+    rmdir "$AUTH_ROUTES" "$AUTH_ROOT"
+    rm -f "$MIGRATION_MARKER_BACKUP" "$MIGRATION_COMPOSE_BACKUP" "$MIGRATION_RECEIPT"
+    printf 'migrationState=rolled-back\n'
+}
+
+finalize_authenticated_origin() {
+    migration_pending_valid || { echo "Authenticated-origin migration receipt is stale or unsafe." >&2; exit 39; }
+    [[ "$(status | sed -n 's/^state=//p' | head -n1)" == ready ]] || {
+        echo "Authenticated-origin host is not ready for finalization." >&2; exit 39;
+    }
+    rm -f "$MIGRATION_MARKER_BACKUP" "$MIGRATION_COMPOSE_BACKUP" "$MIGRATION_RECEIPT"
+    printf 'migrationState=complete\n'
+}
+
+verify_authenticated_origin() {
+    local expected_route_digest="$EXPECTED" path route_spec
+    [[ "$(status | sed -n 's/^state=//p' | head -n1)" == ready &&
+       "$(marker_value AUTHENTICATED_ORIGIN 2>/dev/null || true)" == true &&
+       -S "$AUTH_SOCKET" && -d "$AUTH_ROOT" && ! -L "$AUTH_ROOT" &&
+       "$(stat -c '%u:%g:%a' "$AUTH_ROOT")" == "65532:65532:700" &&
+       "$(stat -c '%u:%g:%a' "$AUTH_SOCKET")" == "65532:65532:222" ]] || {
+        echo "Authenticated-origin socket or scope is not ready." >&2; exit 40;
+    }
+    [[ "$(route_inventory_digest)" == "$expected_route_digest" ]] || {
+        echo "Managed public-route inventory changed during migration." >&2; exit 40;
+    }
+    grep -Fqx "      - $AUTH_ROOT:/run/project-forge-origin:ro" "$COMPOSE_FILE" || {
+        echo "Connector Compose file does not grant the exact read-only origin mount." >&2; exit 40;
+    }
+    path_overlap() {
+        local left="${1%/}" right="${2%/}"
+        [[ "$left" == "$right" || "$left" == "$right/"* || "$right" == "$left/"* ]]
+    }
+    local connector_id caddy_id mount_count other_id mounts source destination writable source_mount
+    connector_id="$(docker inspect --format '{{.Id}}' "$CONTAINER")"
+    caddy_id="$(docker inspect --format '{{.Id}}' "$CADDY_CONTAINER")"
+    mapfile -t mounts < <(docker inspect --format '{{range .Mounts}}{{printf "%s|%s|%t\n" .Source .Destination .RW}}{{end}}' "$CONTAINER")
+    mount_count=0
+    for source_mount in "${mounts[@]}"; do
+        IFS='|' read -r source destination writable <<< "$source_mount"
+        if path_overlap "$source" "$AUTH_ROOT" || path_overlap "$destination" "/run/project-forge-origin"; then
+            [[ "$source" == "$AUTH_ROOT" && "$destination" == "/run/project-forge-origin" &&
+               "$writable" == false ]] || {
+                echo "Connector has an unexpected mount overlapping the authenticated-origin socket." >&2; exit 40;
+            }
+            mount_count=$((mount_count + 1))
+        fi
+    done
+    [[ "$mount_count" == 1 ]] || {
+        echo "Running connector does not have exactly the expected read-only origin mount." >&2; exit 40;
+    }
+    while IFS= read -r other_id; do
+        [[ -n "$other_id" && "$other_id" != "$connector_id" && "$other_id" != "$caddy_id" ]] || continue
+        mapfile -t mounts < <(docker inspect --format '{{range .Mounts}}{{printf "%s|%s\n" .Source .Destination}}{{end}}' "$other_id")
+        for source_mount in "${mounts[@]}"; do
+            IFS='|' read -r source destination <<< "$source_mount"
+            if path_overlap "$source" "$AUTH_ROOT" ||
+               path_overlap "$destination" "/run/project-forge-origin"; then
+                echo "Authenticated-origin mount is present on a non-connector container." >&2
+                exit 40
+            fi
+        done
+    done < <(docker ps -aq)
+    [[ -f "$AUTH_CADDY" && ! -L "$AUTH_CADDY" ]] &&
+        grep -Fqx "    bind unix//data/authenticated/$SCOPE/origin.sock|0222" "$AUTH_CADDY" &&
+        grep -Fqx "    import /data/authenticated/$SCOPE/routes/*.caddy" "$AUTH_CADDY" || {
+        echo "Authenticated Caddy Unix listener configuration is missing or changed." >&2; exit 40;
+    }
+    docker exec "$CADDY_CONTAINER" caddy validate --config /etc/caddy/Caddyfile >/dev/null
+    local route_count=0
+    for path in "$ROUTE_ROOT"/*.route; do
+        [[ -f "$path" ]] || continue
+        route_spec="$(printf '%s\t%s\t%s\t%s\t%s\t%s\t%s' \
+            "$(route_value "$path" SCHEMA_VERSION)" "$(route_value "$path" OWNER_REPO)" \
+            "$(route_value "$path" ENVIRONMENT)" "$(route_value "$path" APP_SLUG)" \
+            "$(route_value "$path" ROUTE_ID)" "$(route_value "$path" PUBLIC_HOSTNAME)" \
+            "$(route_value "$path" ORIGIN_HOSTNAME)")"
+        parse_spec_value "$route_spec"
+        auth_route_verify_lan
+        local expected_file tmp
+        expected_file="$(auth_route_path "$R_ROUTE")"
+        [[ -f "$expected_file" && ! -L "$expected_file" ]] || {
+            echo "Authenticated Caddy route file is missing or unsafe." >&2; exit 40;
+        }
+        tmp="$AUTH_ROUTES/.verify-$R_ROUTE.$$"
+        auth_route_content > "$tmp"
+        if ! cmp -s "$tmp" "$expected_file"; then
+            rm -f "$tmp"
+            echo "Authenticated Caddy route differs from the sanitized reviewed contract." >&2
+            exit 40
+        fi
+        rm -f "$tmp"
+        route_count=$((route_count + 1))
+    done
+    printf 'evidenceLevel=structural-only\n'
+    printf 'connectorOriginMount=read-only\n'
+    printf 'socketMetadataVerified=true\n'
+    printf 'caddyConfigValidated=true\n'
+    printf 'sanitizedRouteConfigVerified=true\n'
+    printf 'managedRouteCount=%s\n' "$route_count"
+}
+
 metadata_matches() {
     local path="$1" encoded="$2"
     parse_spec_value "$encoded"
@@ -449,6 +771,21 @@ case "$ACTION" in
     route-inventory)
         route_inventory
         ;;
+    migration-inspect)
+        migration_inspect
+        ;;
+    migrate-authenticated)
+        migrate_authenticated_origin
+        ;;
+    rollback-authenticated)
+        rollback_authenticated_origin
+        ;;
+    finalize-authenticated)
+        finalize_authenticated_origin
+        ;;
+    verify-authenticated)
+        verify_authenticated_origin
+        ;;
     route-register|route-remove)
         exec 9>>"$LOCK_FILE"
         flock -n 9 || { echo "Another Cloudflare ingress operation holds the lock." >&2; exit 75; }

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

@@ -9,14 +9,18 @@ import sys
 from typing import Any
 
 from .cloudflare_ingress import (
+    AUTHENTICATED_ORIGIN_CHANGE_FREEZE_PHRASE,
+    AUTHENTICATED_ORIGIN_MIGRATION_PHRASE,
     CLOUDFLARE_API_TOKEN_ENV,
     HOST_PUBLIC_INGRESS_WRITE_PHRASE,
     PUBLIC_INGRESS_ROUTE_REMOVE_PHRASE,
     PUBLIC_INGRESS_ROUTE_WRITE_PHRASE,
+    apply_authenticated_origin_migration,
     apply_cloudflare_ingress,
     cloudflare_ingress_doctor,
     cloudflare_ingress_status,
     cloudflare_route_inventory,
+    plan_authenticated_origin_migration,
     plan_cloudflare_ingress,
     plan_public_route,
     plan_public_route_removal,
@@ -50,7 +54,7 @@ def _token() -> str:
 
 
 def _confirm(args: argparse.Namespace, phrase: str, action: str) -> None:
-    if args.yes:
+    if getattr(args, "yes", False):
         return
     entered = input(f"Type {phrase} to {action}: ").strip()
     if entered != phrase:
@@ -81,6 +85,15 @@ def build_parser() -> argparse.ArgumentParser:
     configure.add_argument("--json", action="store_true")
     configure.add_argument("--yes", action="store_true")
 
+    migrate = commands.add_parser(
+        "migrate-authenticated-origin",
+        help="Migrate an existing managed scope to connector-exclusive Unix-socket origins",
+    )
+    migrate.add_argument("name")
+    migrate.add_argument("--scope", required=True)
+    migrate.add_argument("--zone", required=True, help="Existing bound Cloudflare zone")
+    migrate.add_argument("--json", action="store_true")
+
     route = commands.add_parser("route", help="Project-owned public hostname/DNS routes")
     route_commands = route.add_subparsers(dest="route_command", required=True)
 
@@ -143,6 +156,43 @@ def main(argv: list[str] | None = None) -> int:
             )
             _print(apply_cloudflare_ingress(plan, api_token=token), as_json=args.json)
             return 0
+        if args.command == "migrate-authenticated-origin":
+            token = _token()
+            preplan_freeze_acknowledgement = (
+                f"{AUTHENTICATED_ORIGIN_CHANGE_FREEZE_PHRASE} ACTIVE scope={args.scope}"
+            )
+            _confirm(
+                args,
+                preplan_freeze_acknowledgement,
+                "confirm that all external Cloudflare tunnel-configuration writers are frozen for this scope before planning",
+            )
+            plan = plan_authenticated_origin_migration(
+                args.name,
+                scope=args.scope,
+                zone_name=args.zone,
+                api_token=token,
+                change_freeze_active_acknowledgement=preplan_freeze_acknowledgement,
+            )
+            _print(plan, as_json=False)
+            _confirm(
+                args,
+                AUTHENTICATED_ORIGIN_MIGRATION_PHRASE,
+                f"migrate existing Cloudflare ingress scope {args.scope} on target {args.name}",
+            )
+            _confirm(
+                args,
+                plan["requiredChangeFreezeAcknowledgement"],
+                "acknowledge the operator-controlled Cloudflare change freeze for this migration plan",
+            )
+            _print(
+                apply_authenticated_origin_migration(
+                    plan,
+                    api_token=token,
+                    change_freeze_acknowledgement=plan["requiredChangeFreezeAcknowledgement"],
+                ),
+                as_json=args.json,
+            )
+            return 0
         if args.command == "route" and args.route_command == "inventory":
             _print(cloudflare_route_inventory(args.name, args.scope), as_json=args.json)
             return 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mriekki/project-forge",
-  "version": "4.21.0",
+  "version": "4.22.0",
   "description": "Public consumer distribution and updater for Project Forge engineering assets.",
   "type": "module",
   "bin": {