gowalk-cicd 1.0.147 → 1.0.149

package/CLAUDE.md

@@ -242,6 +242,16 @@ node /path/to/gowalk-cicd/bin/cli.mjs
   Docker port changes update only the managed nginx upstream, preserving existing TLS directives.
   Existing certificate inventory is followed by domain-scoped `certbot install`, so a legacy
   HTTP-only vhost also recovers without reissuance. Installation shares the bounded lock-only retry.
+- Optional backend edge delivery keeps `api-domain` as infrastructure and verifies the separate
+  `public-health-url` against exact health JSON `build_sha`. `public-base-url` supplies
+  `BACKEND_PUBLIC_BASE_URL` to Compose interpolation; app services consume it for generated URLs.
+  `ingress-required` requires a private `ingress-token` before deployment. Protect only the distinct
+  `backend-<app>-edge.conf`; preserve a legacy vhost's TLS/public access and update both managed
+  ports. A missing token/settings cannot downgrade an already protected app. Keep tokens in private
+  stdin/file transport, strip the ingress header before app forwarding, and validate real nginx in
+  focused tests. Managed locations forward WebSocket upgrades with a domain-scoped Connection map
+  and disable response buffering; verify a real frame exchange and a first SSE event before upstream
+  completion. Preserve legacy deployments that have not opted in and existing failure phases.
 - The Android action serves two build systems. `android_config.project_kind()`
   is the only place that decides which; every downstream step branches on the
   `project_kind` output rather than re-sniffing the repo. Flutter wins the tie

package/README.md

@@ -201,6 +201,8 @@ branch yet, manually dispatching **Mobile Deploy** on the feature branch runs
 the same backend action as a `backend-preview` job. The job is feature-branch
 only; normal default-branch backend deploys remain in `deploy-backend.yml`.
 
+For optional app-owned Cloudflare ingress, follow [backend edge delivery](docs/BACKEND_EDGE.md).
+
 ## Android credentials
 
 Place these files under `creds/`:

package/action/.daemux-version

@@ -1 +1 @@
-1.0.147
+1.0.149

package/action/scripts/mobile_inputs.cjs

@@ -24,6 +24,7 @@ function input(name, platform) {
 // checked against the template, and share the projection with the freeze CLI.
 const BUILD_VARIABLES = [
   'BACKEND_API_DOMAIN', 'BACKEND_APP_NAME', 'BACKEND_DEPLOY_HOST', 'BACKEND_HEALTH_PATH',
+  'BACKEND_INGRESS_REQUIRED', 'BACKEND_PUBLIC_BASE_URL', 'BACKEND_PUBLIC_HEALTH_URL',
   'DEPLOY_PLATFORMS', 'FIREBASE_APP_ID', 'GOOGLE_PLAY_STATUS', 'GOOGLE_PLAY_TRACK',
   'GOOGLE_PLAY_USER_FRACTION', 'JAVA_VERSION', 'ONBOARDING_PUBLIC_ORIGIN',
 ];

package/android-action/.daemux-version

@@ -1 +1 @@
-1.0.147
+1.0.149

package/backend-action/.daemux-version

@@ -1 +1 @@
-1.0.147
+1.0.149

package/backend-action/action.yml

@@ -53,6 +53,26 @@ inputs:
     description: HTTP path the service answers 2xx on once healthy.
     required: false
     default: "/health"
+  public-health-url:
+    description: App-owned HTTPS edge health URL; empty preserves the infrastructure health probe.
+    required: false
+    default: ""
+  public-base-url:
+    description: Canonical client API base supplied as BACKEND_PUBLIC_BASE_URL to Compose interpolation.
+    required: false
+    default: ""
+  expected-build-sha:
+    description: Exact 40-character lowercase commit SHA required in health JSON build_sha.
+    required: false
+    default: ""
+  ingress-required:
+    description: Protect a distinct edge-only infrastructure vhost, retaining an existing legacy vhost.
+    required: false
+    default: "false"
+  ingress-token:
+    description: Backend-only per-app token sent by the edge in X-App-Robot-Backend-Token.
+    required: false
+    default: ""
   cert-email:
     description: Email for the Let's Encrypt registration.
     required: false
@@ -82,10 +102,16 @@ runs:
       env:
         BACKEND_DIR: ${{ inputs.backend-dir }}
         COMPOSE_FILE_INPUT: ${{ inputs.compose-file }}
+        BACKEND_PUBLIC_HEALTH_URL: ${{ inputs.public-health-url }}
+        BACKEND_PUBLIC_BASE_URL: ${{ inputs.public-base-url }}
+        BACKEND_EXPECTED_BUILD_SHA: ${{ inputs.expected-build-sha }}
+        BACKEND_INGRESS_REQUIRED: ${{ inputs.ingress-required }}
+        BACKEND_INGRESS_TOKEN: ${{ inputs.ingress-token }}
       run: |
         set -euo pipefail
         source "${{ github.action_path }}/deploy_evidence.sh"
         BACKEND_DEPLOY_PHASE=validate_inputs
+        python3 "${{ github.action_path }}/edge_inputs.py" check
         COMPOSE_FILE="${COMPOSE_FILE_INPUT:-$BACKEND_DIR/docker-compose.yml}"
         test -d "$BACKEND_DIR" \
           || { echo "::error::no backend directory $BACKEND_DIR"; exit 1; }
@@ -138,6 +164,7 @@ runs:
         # (generated DB password, etc.) survive across deploys.
         if [ "$COMPOSE_FILE" = "$BACKEND_DIR/docker-compose.yml" ]; then
           rsync -az --delete --exclude '.env' --exclude '.git' \
+            --exclude '.backend-edge.json' --exclude '.backend-ingress.conf' --exclude '.backend-public.env' \
             -e "$SSH" "$BACKEND_DIR/" \
             "${{ inputs.ssh-user }}@${{ inputs.host }}:$DEST/"
         else
@@ -156,6 +183,9 @@ runs:
           "${{ github.action_path }}/select_certbot_account.sh" \
           "${{ github.action_path }}/ensure_certificate.sh" \
           "${{ github.action_path }}/configure_vhost.py" \
+          "${{ github.action_path }}/edge_inputs.py" \
+          "${{ github.action_path }}/edge_vhost.py" \
+          "${{ github.action_path }}/edge_health.py" \
           "${{ github.action_path }}/deploy_evidence.sh" \
           "${{ inputs.ssh-user }}@${{ inputs.host }}:$DEST/"
 
@@ -164,12 +194,21 @@ runs:
       shell: bash
       env:
         RUNTIME_ENV: ${{ inputs.runtime-env }}
+        BACKEND_PUBLIC_HEALTH_URL: ${{ inputs.public-health-url }}
+        BACKEND_PUBLIC_BASE_URL: ${{ inputs.public-base-url }}
+        BACKEND_EXPECTED_BUILD_SHA: ${{ inputs.expected-build-sha }}
+        BACKEND_INGRESS_REQUIRED: ${{ inputs.ingress-required }}
+        BACKEND_INGRESS_TOKEN: ${{ inputs.ingress-token }}
       run: |
         set -euo pipefail
         source "${{ github.action_path }}/deploy_evidence.sh"
         BACKEND_DEPLOY_PHASE=write_runtime_env
         SSH="ssh -i ~/.ssh/backend_deploy -o IdentitiesOnly=yes"
         DEST="/opt/gowalk-backends/${{ inputs.app-name }}"
+        EDGE_DIR="/opt/gowalk-backend-ingress/${{ inputs.app-name }}"
+        python3 "${{ github.action_path }}/edge_inputs.py" export | $SSH \
+          "${{ inputs.ssh-user }}@${{ inputs.host }}" \
+          "umask 077; mkdir -p '$EDGE_DIR'; python3 '$DEST/edge_inputs.py' receive '$EDGE_DIR/.backend-edge.json'"
         if [ -n "${RUNTIME_ENV:-}" ]; then
           printf '%s\n' "$RUNTIME_ENV" | $SSH \
             "${{ inputs.ssh-user }}@${{ inputs.host }}" \

package/backend-action/configure_vhost.py

@@ -1,4 +1,5 @@
-"""Update one managed nginx upstream without discarding Certbot's HTTPS configuration."""
+"""Update managed nginx transport without discarding Certbot's HTTPS configuration."""
+import hashlib
 import os
 from pathlib import Path
 import re
@@ -7,6 +8,29 @@ import sys
 import tempfile
 
 
+def transport(text, domain):
+    variable = "$gowalk_backend_connection_" + hashlib.sha256(domain.encode()).hexdigest()[:16]
+    mapping = f"map $http_upgrade {variable} {{\n    default upgrade;\n    '' close;\n}}\n\n"
+    result = text.removeprefix(mapping)
+    directives = (r"proxy_http_version", r"proxy_set_header[ \t]+Upgrade",
+                  r"proxy_set_header[ \t]+Connection", r"proxy_buffering")
+    for directive in directives:
+        pattern = rf"(?mi)^[ \t]*{directive}[ \t]+[^;\n]+;[^\n]*\n"
+        result, count = re.subn(pattern, "", result)
+        if count > 1:
+            raise ValueError("managed transport directive is not unique")
+    if variable in result:
+        raise ValueError("managed connection map is not recognized")
+    settings = ("proxy_http_version 1.1;", "proxy_set_header Upgrade $http_upgrade;",
+                f"proxy_set_header Connection {variable};", "proxy_buffering off;")
+    pattern = r"(?m)^([ \t]*)proxy_pass[ \t]+http://127\.0\.0\.1:\d+;[^\n]*$"
+    result, count = re.subn(pattern, lambda match: match[0] + "\n"
+                            + "\n".join(match[1] + setting for setting in settings), result)
+    if count != 1:
+        raise ValueError("managed upstream is not unique")
+    return mapping + result
+
+
 def content(previous, domain, port):
     if not re.fullmatch(r"[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?", domain) or not 0 < port < 65536:
         raise ValueError("invalid domain or port")
@@ -18,14 +42,13 @@ def content(previous, domain, port):
         result, count = re.subn(pattern, lambda match: f"{match[1]}{port}{match[2]}", previous)
         if count != 1:
             raise ValueError("managed upstream is not unique")
-        return result
-    return f"""server {{
+        return transport(result, domain)
+    return transport(f"""server {{
     listen 80;
     server_name {domain};
     client_max_body_size 100m;
     location / {{
         proxy_pass http://127.0.0.1:{port};
-        proxy_http_version 1.1;
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
@@ -33,7 +56,7 @@ def content(previous, domain, port):
         proxy_read_timeout 120s;
     }}
 }}
-"""
+""", domain)
 
 
 def configure(path, domain, port):

package/backend-action/edge_health.py

@@ -0,0 +1,72 @@
+"""Verify private-origin refusal, retained aliases and the public edge's exact build."""
+import json
+from pathlib import Path
+import subprocess
+import sys
+import tempfile
+import time
+
+from edge_inputs import load, TOKEN_HEADER
+from edge_vhost import NGINX_DIR, paths, recorded_domain
+
+
+def request(url, *, headers=None, run=subprocess.run):
+    # curl retains its strict TLS/time bounds. Private headers and bounded response
+    # bytes live only in an owned mode-0700 directory, never argv or diagnostics.
+    with tempfile.TemporaryDirectory(prefix="backend-edge-health-") as directory:
+        root = Path(directory)
+        config, body = root / "curl.conf", root / "body"
+        config.write_text("".join(f'header = "{key}: {value}"\n' for key, value in (headers or {}).items()))
+        config.chmod(0o600)
+        result = run(["curl", "--disable", "--silent", "--config", str(config), "--output", str(body),
+                      "--write-out", "%{http_code}", "--proto", "=https", "--connect-timeout", "5",
+                      "--max-time", "10", "--max-filesize", "65536", url],
+                     capture_output=True, timeout=15)
+        status = result.stdout.decode("ascii", errors="replace")
+        data = body.read_bytes() if body.exists() and body.stat().st_size <= 65536 else b""
+        return result.returncode, int(status) if status.isdigit() else 0, data
+
+
+def healthy(url, sha="", *, headers=None, fetch=request, sleep=time.sleep):
+    for attempt in range(15):
+        try:
+            code, status, body = fetch(url, headers=headers)
+            valid = code == 0 and 200 <= status < 300
+            if valid and sha:
+                value = json.loads(body)
+                valid = isinstance(value, dict) and value.get("build_sha") == sha
+            if valid:
+                return
+        except (OSError, ValueError, subprocess.SubprocessError):
+            pass
+        if attempt != 14:
+            sleep(2)
+    raise ValueError("backend_public_health_failed")
+
+
+def verify(config, app, domain, health, *, nginx_dir=NGINX_DIR, fetch=request, sleep=time.sleep):
+    value = load(config)
+    if not health.startswith("/") or any(character in health for character in "\r\n?#"):
+        raise ValueError("backend_health_path_invalid")
+    origin_url = f"https://{domain}{health}"
+    if value["ingress_required"] == "true":
+        for headers in (None, {TOKEN_HEADER: "invalid-backend-ingress-token"}):
+            code, status, _body = fetch(origin_url, headers=headers)
+            if code != 0 or status != 403:
+                raise ValueError("backend_origin_ingress_unverified")
+        healthy(origin_url, value["expected_build_sha"], headers={TOKEN_HEADER: value["ingress_token"]},
+                fetch=fetch, sleep=sleep)
+        legacy = recorded_domain(paths(config, app, nginx_dir)[0])
+        if legacy:
+            healthy(f"https://{legacy}{health}", fetch=fetch, sleep=sleep)
+    public = value["public_health_url"] or origin_url
+    healthy(public, value["expected_build_sha"], fetch=fetch, sleep=sleep)
+    return {"ok": True, "public_health_verified": True, "build_sha": value["expected_build_sha"],
+            "ingress_verified": value["ingress_required"] == "true"}
+
+
+if __name__ == "__main__":
+    try:
+        print(json.dumps(verify(*sys.argv[1:5])))
+    except (OSError, ValueError, subprocess.SubprocessError):
+        sys.exit("backend_edge_health_failed")

package/backend-action/edge_inputs.py

@@ -0,0 +1,115 @@
+"""Validate optional edge delivery inputs without exposing credentials or response bodies."""
+import json
+import os
+from pathlib import Path
+import re
+import sys
+import tempfile
+from urllib.parse import urlsplit
+
+CONFIG_NAME = ".backend-edge.json"
+TOKEN_HEADER = "X-App-Robot-Backend-Token"
+FIELDS = ("public_health_url", "public_base_url", "expected_build_sha", "ingress_required", "ingress_token")
+
+
+def validate(value):
+    if not isinstance(value, dict) or set(value) != set(FIELDS):
+        raise ValueError("backend_edge_inputs_invalid")
+    if any(not isinstance(value[key], str) for key in FIELDS):
+        raise ValueError("backend_edge_inputs_invalid")
+    public, base, sha, required, token = (value[key] for key in FIELDS)
+    if required not in {"true", "false"}:
+        raise ValueError("backend_ingress_required_invalid")
+    if sha and not re.fullmatch(r"[a-f0-9]{40}", sha):
+        raise ValueError("backend_build_sha_invalid")
+    if public:
+        parsed = urlsplit(public)
+        if (parsed.scheme != "https" or not parsed.hostname or parsed.username or parsed.password
+                or parsed.query or parsed.fragment or re.search(r"[\s\\]", public) or not sha):
+            raise ValueError("backend_public_health_invalid")
+        if parsed.port not in {None, 443}:
+            raise ValueError("backend_public_health_invalid")
+    if base:
+        parsed = urlsplit(base)
+        if (parsed.scheme != "https" or not parsed.hostname or parsed.username or parsed.password
+                or parsed.query or parsed.fragment or parsed.port not in {None, 443}
+                or not re.fullmatch(r"[a-zA-Z0-9._~:/%-]+", base) or base.endswith("/")):
+            raise ValueError("backend_public_base_invalid")
+        if public and not public.startswith(base + "/"):
+            raise ValueError("backend_public_health_base_mismatch")
+    if required == "true" and (not public or not base or not re.fullmatch(r"[a-zA-Z0-9_-]{43,128}", token)):
+        raise ValueError("backend_ingress_configuration_required")
+    return value
+
+
+def environment():
+    return validate({key: os.environ.get("BACKEND_" + key.upper(), "false" if key == "ingress_required" else "")
+                     for key in FIELDS})
+
+
+def load(path):
+    path = Path(path)
+    if path.is_symlink():
+        raise ValueError("backend_edge_config_symlink")
+    if not path.exists():
+        return validate(dict(zip(FIELDS, ("", "", "", "false", ""))))
+    if path.stat().st_size > 8192:
+        raise ValueError("backend_edge_config_invalid")
+    return validate(json.loads(path.read_text()))
+
+
+def mode(value):
+    if value["ingress_required"] == "true":
+        return "edge"
+    return "verify" if value["public_health_url"] or value["expected_build_sha"] else "legacy"
+
+
+def runtime(path):
+    value = load(path)["public_base_url"]
+    if value:
+        target = Path(path).parent / ".backend-public.env"
+        if target.is_symlink():
+            raise ValueError("backend_public_env_symlink")
+        descriptor = os.open(target, os.O_WRONLY | os.O_CREAT | os.O_TRUNC | os.O_NOFOLLOW, 0o600)
+        with os.fdopen(descriptor, "w") as output:
+            os.fchmod(output.fileno(), 0o600)
+            output.write("BACKEND_PUBLIC_BASE_URL=" + json.dumps(value) + "\n")
+
+
+def receive(path):
+    target = Path(path)
+    value = validate(json.loads(sys.stdin.buffer.read(8193)))
+    if target.is_symlink() or target.parent.is_symlink():
+        raise ValueError("backend_edge_config_symlink")
+    descriptor, temporary = tempfile.mkstemp(prefix=target.name + ".", dir=target.parent)
+    try:
+        with os.fdopen(descriptor, "w") as output:
+            os.fchmod(output.fileno(), 0o600)
+            json.dump(value, output)
+            output.flush()
+            os.fsync(output.fileno())
+        os.replace(temporary, target)
+    finally:
+        Path(temporary).unlink(missing_ok=True)
+
+
+def main():
+    if sys.argv[1] == "check":
+        environment()
+    elif sys.argv[1] == "export":
+        print(json.dumps(environment()))
+    elif sys.argv[1] == "mode":
+        print(mode(load(sys.argv[2])))
+    elif sys.argv[1] == "runtime":
+        runtime(sys.argv[2])
+    elif sys.argv[1] == "receive":
+        receive(sys.argv[2])
+    else:
+        raise ValueError("backend_edge_operation_invalid")
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except (OSError, ValueError):
+        sys.exit("backend_edge_configuration_invalid")

package/backend-action/edge_vhost.py

@@ -0,0 +1,140 @@
+"""Protect a distinct edge vhost while retaining an app's released direct-host address."""
+import os
+from pathlib import Path
+import re
+import stat
+import subprocess
+import sys
+import tempfile
+
+from configure_vhost import content
+from edge_inputs import load
+
+NGINX_DIR = Path("/etc/nginx/conf.d")
+
+
+def paths(config, app, nginx_dir=NGINX_DIR):
+    if not re.fullmatch(r"[a-z0-9-]+", app):
+        raise ValueError("backend_app_invalid")
+    return (nginx_dir / f"backend-{app}.conf", nginx_dir / f"backend-{app}-edge.conf",
+            Path(config).parent / ".backend-ingress.conf")
+
+
+def previous(path):
+    if path.is_symlink():
+        raise ValueError("backend_vhost_symlink")
+    return path.read_text() if path.exists() else ""
+
+
+def recorded_domain(path):
+    text = previous(path)
+    if not text:
+        return ""
+    names = set(re.findall(r"(?m)^\s*server_name\s+([^;]+);", text))
+    if len(names) != 1:
+        raise ValueError("backend_vhost_identity_invalid")
+    domain = names.pop().strip()
+    content(text, domain, 1)
+    return domain
+
+
+def validate(config, app, domain, nginx_dir=NGINX_DIR):
+    value = load(config)
+    legacy, edge, include = paths(config, app, nginx_dir)
+    protected = bool(previous(edge) or previous(include))
+    if value["ingress_required"] != "true":
+        if protected:
+            raise ValueError("backend_ingress_downgrade_refused")
+        return value
+    content("", domain, 1)
+    old_domain = recorded_domain(legacy)
+    if old_domain == domain:
+        raise ValueError("backend_edge_domain_must_be_distinct")
+    if previous(edge) and recorded_domain(edge) != domain:
+        raise ValueError("backend_edge_domain_changed")
+    return value
+
+
+def edge_content(text, domain, port, include):
+    updated = content(text, domain, port)
+    directive = f"        include {include};\n"
+    if re.search(r"[\s;{}]", str(include)):
+        raise ValueError("backend_ingress_path_invalid")
+    if updated.count(directive) == 1:
+        return updated
+    if ".backend-ingress.conf" in updated or len(re.findall(r"\bproxy_pass\b", updated)) != 1:
+        raise ValueError("backend_edge_vhost_invalid")
+    pattern = r"(?m)^(\s*location / \{\n)"
+    updated, count = re.subn(pattern, lambda match: match[1] + directive, updated)
+    if count != 1:
+        raise ValueError("backend_edge_location_invalid")
+    return updated
+
+
+def replace(path, data, mode):
+    fd, temporary = tempfile.mkstemp(prefix=path.name + ".", dir=path.parent)
+    try:
+        with os.fdopen(fd, "wb") as output:
+            os.fchmod(output.fileno(), mode)
+            output.write(data)
+            output.flush()
+            os.fsync(output.fileno())
+        os.replace(temporary, path)
+    finally:
+        Path(temporary).unlink(missing_ok=True)
+
+
+def planned(config, app, domain, port, nginx_dir=NGINX_DIR):
+    value = validate(config, app, domain, nginx_dir)
+    if value["ingress_required"] != "true":
+        raise ValueError("backend_ingress_configuration_required")
+    legacy, edge, include = paths(config, app, nginx_dir)
+    token = value["ingress_token"]
+    guard = (f'if ($http_x_app_robot_backend_token != "{token}") {{ return 403; }}\n'
+             'proxy_set_header X-App-Robot-Backend-Token "";\n')
+    files = {include: (guard.encode(), 0o600),
+             edge: (edge_content(previous(edge), domain, port, include).encode(), 0o644)}
+    old_domain = recorded_domain(legacy)
+    if old_domain:
+        files[legacy] = (content(previous(legacy), old_domain, port).encode(),
+                         stat.S_IMODE(legacy.stat().st_mode))
+    return files
+
+
+def configure(config, app, domain, port, nginx_dir=NGINX_DIR, run=subprocess.run):
+    files = planned(config, app, domain, port, nginx_dir)
+    saved = {path: ((path.read_bytes(), stat.S_IMODE(path.stat().st_mode)) if path.exists() else None)
+             for path in files}
+    changes = {path: value for path, value in files.items() if saved[path] != value}
+    if not changes:
+        return "unchanged"
+    try:
+        for path, (data, mode) in changes.items():
+            replace(path, data, mode)
+        run(["nginx", "-t"], capture_output=True, timeout=30, check=True)
+        run(["systemctl", "reload", "nginx"], capture_output=True, timeout=30, check=True)
+    except (OSError, subprocess.SubprocessError):
+        for path in changes:
+            if saved[path] is None:
+                path.unlink(missing_ok=True)
+            else:
+                replace(path, *saved[path])
+        raise ValueError("backend_edge_nginx_failed") from None
+    return "changed"
+
+
+def main():
+    operation, config, app, domain = sys.argv[1:5]
+    if operation == "validate":
+        validate(config, app, domain)
+    elif operation == "configure":
+        print(configure(config, app, domain, int(sys.argv[5])))
+    else:
+        raise ValueError("backend_edge_operation_invalid")
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except (OSError, ValueError):
+        sys.exit("backend_edge_vhost_refused")

package/backend-action/nginx_test_fixture.py

@@ -0,0 +1,98 @@
+"""A task-owned HTTP server for real nginx protocol and streaming checks."""
+import base64
+import hashlib
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+import json
+import subprocess
+import threading
+
+LEGACY_VHOST = """server {
+    listen 80;
+    server_name legacy.example;
+    location / {
+        proxy_pass http://127.0.0.1:31000;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_read_timeout 120s;
+    }
+}
+"""
+
+
+class BackendServer(ThreadingHTTPServer):
+    def __init__(self):
+        super().__init__(("127.0.0.1", 0), Backend)
+        self.stream_release = threading.Event()
+        self.stream_finished = threading.Event()
+
+
+class Backend(BaseHTTPRequestHandler):
+    protocol_version = "HTTP/1.1"
+
+    def do_GET(self):
+        if self.path == "/ws":
+            return self.websocket()
+        if self.path == "/stream":
+            return self.stream()
+        payload = json.dumps({"build_sha": "a" * 40, "path": self.path,
+                              "upgrade": self.headers.get("Upgrade"),
+                              "connection": self.headers.get("Connection"),
+                              "ingress_received": "X-App-Robot-Backend-Token" in self.headers}).encode()
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(payload)))
+        self.end_headers()
+        self.wfile.write(payload)
+
+    def websocket(self):
+        self.close_connection = True
+        if (self.headers.get("Upgrade", "").lower() != "websocket"
+                or self.headers.get("Connection", "").lower() != "upgrade"
+                or self.request_version != "HTTP/1.1"
+                or "X-App-Robot-Backend-Token" in self.headers):
+            self.send_error(400)
+            return
+        key = self.headers["Sec-WebSocket-Key"] + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
+        self.send_response(101)
+        self.send_header("Upgrade", "websocket")
+        self.send_header("Connection", "Upgrade")
+        self.send_header("Sec-WebSocket-Accept", base64.b64encode(hashlib.sha1(key.encode()).digest()).decode())
+        self.end_headers()
+        self.connection.settimeout(2)
+        frame = self.rfile.read(2)
+        if len(frame) != 2 or frame[0] != 0x81 or frame[1] & 0x80 == 0 or frame[1] & 0x7F > 125:
+            return
+        mask = self.rfile.read(4)
+        payload = self.rfile.read(frame[1] & 0x7F)
+        decoded = bytes(value ^ mask[index % 4] for index, value in enumerate(payload))
+        self.wfile.write(bytes((0x81, len(decoded))) + decoded)
+        self.wfile.flush()
+
+    def stream(self):
+        self.close_connection = True
+        self.send_response(200)
+        self.send_header("Content-Type", "text/event-stream")
+        self.end_headers()
+        self.wfile.write(b"data: first\n\n")
+        self.wfile.flush()
+        try:
+            if self.server.stream_release.wait(5):
+                self.wfile.write(b"data: second\n\n")
+                self.wfile.flush()
+        finally:
+            self.server.stream_finished.set()
+
+    def log_message(self, *_args):
+        pass
+
+
+def stop(process):
+    process.terminate()
+    try:
+        process.communicate(timeout=5)
+    except subprocess.TimeoutExpired:
+        process.kill()
+        process.communicate(timeout=5)

package/backend-action/remote_deploy.sh

@@ -17,6 +17,15 @@ source "$DIR/ensure_certificate.sh"
 
 log() { echo "[deploy $APP] $*"; }
 
+# Refuse a missing ingress token or an older unprotected workflow before Compose changes.
+EDGE_CONFIG="/opt/gowalk-backend-ingress/$APP/.backend-edge.json"
+EDGE_MODE=legacy
+if [ -f "$EDGE_CONFIG" ] || [ -e "/etc/nginx/conf.d/backend-$APP-edge.conf" ]; then
+  python3 "$DIR/edge_vhost.py" validate "$EDGE_CONFIG" "$APP" "$DOMAIN"
+  EDGE_MODE="$(python3 "$DIR/edge_inputs.py" mode "$EDGE_CONFIG")"
+  python3 "$DIR/edge_inputs.py" runtime "$EDGE_CONFIG"
+fi
+
 # ── secrets: generate a per-app .env once, then preserve it (rsync excludes it)
 BACKEND_DEPLOY_PHASE=initialize_environment
 if [ ! -f .env ]; then
@@ -33,6 +42,10 @@ if [ -s .runtime.env ]; then
   chmod 600 .runtime.env
   COMPOSE_ENV+=(--env-file .runtime.env)
 fi
+EDGE_PUBLIC="$(dirname "$EDGE_CONFIG")/.backend-public.env"
+if [ -s "$EDGE_PUBLIC" ]; then
+  COMPOSE_ENV+=(--env-file "$EDGE_PUBLIC")
+fi
 
 # ── bring the stack up
 BACKEND_DEPLOY_PHASE=compose_up
@@ -80,10 +93,14 @@ fi
 # ── nginx vhost → proxy the domain to the published port
 BACKEND_DEPLOY_PHASE=configure_vhost
 VHOST="/etc/nginx/conf.d/backend-$APP.conf"
-VHOST_STATE="$(python3 "$DIR/configure_vhost.py" "$VHOST" "$DOMAIN" "$PORT")"
-if [ "$VHOST_STATE" = changed ]; then
-  log "updated nginx upstream for $DOMAIN → 127.0.0.1:$PORT"
-  nginx -t && systemctl reload nginx
+if [ "${EDGE_MODE:-legacy}" = edge ]; then
+  python3 "$DIR/edge_vhost.py" configure "$EDGE_CONFIG" "$APP" "$DOMAIN" "$PORT"
+else
+  VHOST_STATE="$(python3 "$DIR/configure_vhost.py" "$VHOST" "$DOMAIN" "$PORT")"
+  if [ "$VHOST_STATE" = changed ]; then
+    log "updated nginx upstream for $DOMAIN → 127.0.0.1:$PORT"
+    nginx -t && systemctl reload nginx
+  fi
 fi
 
 # ── Let's Encrypt cert: failed inventory is never absence; only lock contention retries.
@@ -99,6 +116,11 @@ fi
 # ── public health-check. This validates DNS, the certificate, nginx routing,
 # and the application together; a green deploy must mean the public API works.
 BACKEND_DEPLOY_PHASE=public_health
+if [ "$EDGE_MODE" != legacy ]; then
+  python3 "$DIR/edge_health.py" "$EDGE_CONFIG" "$APP" "$DOMAIN" "$HEALTH"
+  log "done"
+  exit 0
+fi
 PUBLIC_HEALTHY=""
 for i in $(seq 1 15); do
   CURL_EXIT=0

package/backend-action/test_edge_health.py

@@ -0,0 +1,75 @@
+import json
+from pathlib import Path
+import subprocess
+import tempfile
+import unittest
+
+import configure_vhost
+import edge_health
+from test_edge_inputs import configured
+
+
+class Health(unittest.TestCase):
+    def test_exact_edge_build_and_legacy_access_with_no_client_ingress_token(self):
+        calls = []
+
+        def fetch(url, *, headers=None):
+            calls.append((url, headers))
+            if url.startswith("https://edge.example") and (headers or {}).get(
+                    edge_health.TOKEN_HEADER) != configured()["ingress_token"]:
+                return 0, 403, b""
+            return 0, 200, json.dumps({"build_sha": "a" * 40}).encode()
+
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            config = root / ".backend-edge.json"
+            config.write_text(json.dumps(configured()))
+            (root / "backend-fixture.conf").write_text(configure_vhost.content("", "legacy.example", 32000))
+            result = edge_health.verify(config, "fixture", "edge.example", "/healthz",
+                                        nginx_dir=root, fetch=fetch)
+        self.assertTrue(result["ok"])
+        self.assertEqual(calls[-2:], [("https://legacy.example/healthz", None),
+                                     ("https://app.pages.dev/api/healthz", None)])
+        self.assertEqual(len(calls), 5)
+
+    def test_redirect_partial_response_missing_build_and_mismatch_fail(self):
+        cases = [(0, 302, b""), (28, 200, b'{"build_sha":"' + b"a" * 40 + b'"}'),
+                 (0, 200, b"{}"), (0, 200, b'{"build_sha":"wrong"}'), (0, 200, b"invalid")]
+        for response in cases:
+            calls = []
+
+            def fetch(url, **kwargs):
+                calls.append(url)
+                return response
+
+            with self.subTest(response=response), self.assertRaises(ValueError):
+                edge_health.healthy("https://app.pages.dev/api/healthz", "a" * 40,
+                                    fetch=fetch, sleep=lambda _seconds: None)
+            self.assertEqual(len(calls), 15)
+
+    def test_origin_that_accepts_a_missing_token_fails_before_public_probe(self):
+        with tempfile.TemporaryDirectory() as directory:
+            config = Path(directory) / ".backend-edge.json"
+            config.write_text(json.dumps(configured()))
+            with self.assertRaisesRegex(ValueError, "ingress_unverified"):
+                edge_health.verify(config, "fixture", "edge.example", "/healthz",
+                                   fetch=lambda *args, **kwargs: (0, 200, b"{}"))
+
+    def test_curl_keeps_token_out_of_argv_and_deletes_private_temporary_files(self):
+        retained = []
+
+        def run(command, **kwargs):
+            self.assertNotIn(configured()["ingress_token"], str(command))
+            config = Path(command[command.index("--config") + 1])
+            retained.append(config.parent)
+            self.assertEqual(config.stat().st_mode & 0o777, 0o600)
+            self.assertIn(configured()["ingress_token"], config.read_text())
+            for unsafe in ("--insecure", "-k", "--location", "-L"):
+                self.assertNotIn(unsafe, command)
+            Path(command[command.index("--output") + 1]).write_text('{"build_sha":"' + "a" * 40 + '"}')
+            return subprocess.CompletedProcess(command, 0, stdout=b"200", stderr=b"")
+
+        result = edge_health.request("https://edge.example/healthz",
+                                     headers={edge_health.TOKEN_HEADER: configured()["ingress_token"]}, run=run)
+        self.assertEqual(result[:2], (0, 200))
+        self.assertFalse(retained[0].exists())

package/backend-action/test_edge_inputs.py

@@ -0,0 +1,79 @@
+import json
+import os
+from pathlib import Path
+import subprocess
+import sys
+import tempfile
+import unittest
+
+import edge_inputs
+
+
+def configured(**changes):
+    return {"public_health_url": "https://app.pages.dev/api/healthz",
+            "public_base_url": "https://app.pages.dev/api", "expected_build_sha": "a" * 40,
+            "ingress_required": "true", "ingress_token": "synthetic-token-" + "a" * 43, **changes}
+
+
+class Inputs(unittest.TestCase):
+    def test_edge_and_legacy_configurations(self):
+        self.assertEqual(edge_inputs.mode(edge_inputs.validate(configured())), "edge")
+        with tempfile.TemporaryDirectory() as directory:
+            value = edge_inputs.load(Path(directory) / "absent")
+        self.assertEqual(edge_inputs.mode(value), "legacy")
+        self.assertEqual(edge_inputs.mode(configured(ingress_required="false")), "verify")
+
+    def test_invalid_inputs_refuse_without_credential_output(self):
+        cases = [{"ingress_token": ""}, {"ingress_token": 'private\"; return 200;'},
+                 {"ingress_required": "yes"}, {"expected_build_sha": "A" * 40},
+                 {"public_health_url": "http://app.pages.dev/api/healthz"},
+                 {"public_health_url": "https://other.pages.dev/api/healthz"},
+                 {"public_base_url": "https://app.pages.dev/api/$TOKEN"},
+                 {"public_base_url": ""}, {"expected_build_sha": ""},
+                 {"public_health_url": "https://user:private@app.pages.dev/api/healthz"}]
+        for changes in cases:
+            with self.subTest(changes=changes), self.assertRaises(ValueError):
+                edge_inputs.validate(configured(**changes))
+        env = {"BACKEND_" + key.upper(): value for key, value in configured(ingress_token="private").items()}
+        result = subprocess.run([sys.executable, str(Path(edge_inputs.__file__)), "check"],
+                                env={**os.environ, **env}, capture_output=True, text=True)
+        self.assertNotEqual(result.returncode, 0)
+        self.assertNotIn("private", result.stdout + result.stderr)
+
+    def test_runtime_input_is_private_and_separate_from_secret_dotenv(self):
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            config = root / edge_inputs.CONFIG_NAME
+            config.write_text(json.dumps(configured()))
+            secrets = root / ".runtime.env"
+            secrets.write_text("PASSWORD=synthetic-private\n")
+            edge_inputs.runtime(config)
+            output = root / ".backend-public.env"
+            self.assertEqual(output.read_text(), 'BACKEND_PUBLIC_BASE_URL="https://app.pages.dev/api"\n')
+            self.assertEqual(output.stat().st_mode & 0o777, 0o600)
+            self.assertEqual(secrets.read_text(), "PASSWORD=synthetic-private\n")
+            edge_inputs.runtime(config)
+            output.unlink()
+            output.symlink_to(secrets)
+            with self.assertRaises(ValueError):
+                edge_inputs.runtime(config)
+            self.assertEqual(secrets.read_text(), "PASSWORD=synthetic-private\n")
+
+    def test_private_input_receive_is_atomic_and_refuses_symlinks(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / ".backend-edge.json"
+            command = [sys.executable, str(Path(edge_inputs.__file__)), "receive", str(path)]
+            value = json.dumps(configured())
+            result = subprocess.run(command, input=value, capture_output=True, text=True)
+            self.assertEqual(result.returncode, 0, result.stderr)
+            self.assertEqual(result.stdout, "")
+            self.assertEqual(path.stat().st_mode & 0o777, 0o600)
+            invalid = subprocess.run(command, input="broken", capture_output=True, text=True)
+            self.assertNotEqual(invalid.returncode, 0)
+            self.assertEqual(json.loads(path.read_text()), configured())
+            other = Path(directory) / "preserved"
+            path.rename(other)
+            path.symlink_to(other)
+            refused = subprocess.run(command, input=value, capture_output=True, text=True)
+            self.assertNotEqual(refused.returncode, 0)
+            self.assertEqual(json.loads(other.read_text()), configured())

package/backend-action/test_edge_nginx.py

@@ -0,0 +1,125 @@
+"""Exercise generated ingress with an owned nginx process and real HTTP, WebSocket and SSE."""
+from http.client import HTTPResponse
+import json
+from pathlib import Path
+import shutil
+import socket
+import subprocess
+import tempfile
+import threading
+import time
+import unittest
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+import edge_vhost
+from nginx_test_fixture import BackendServer, LEGACY_VHOST, stop
+from test_edge_inputs import configured
+
+
+class Ingress(unittest.TestCase):
+    def setUp(self):
+        self.assertIsNotNone(shutil.which("nginx"), "nginx is required for the backend ingress contract")
+        directory = tempfile.TemporaryDirectory()
+        self.addCleanup(directory.cleanup)
+        self.root = Path(directory.name)
+        server = self.server = BackendServer()
+        self.addCleanup(server.server_close)
+        thread = threading.Thread(target=server.serve_forever, daemon=True)
+        thread.start()
+        self.addCleanup(server.shutdown)
+        with socket.socket() as listener:
+            listener.bind(("127.0.0.1", 0))
+            self.port = listener.getsockname()[1]
+        self.config = self.root / ".backend-edge.json"
+        self.config.write_text(json.dumps(configured()))
+        legacy = self.root / "backend-fixture.conf"
+        legacy.write_text(LEGACY_VHOST.replace(":31000;", f":{server.server_port};"))
+        files = edge_vhost.planned(self.config, "fixture", "edge.example", server.server_port, self.root)
+        for path, (data, mode) in files.items():
+            path.write_bytes(data.replace(b"listen 80;", f"listen 127.0.0.1:{self.port};".encode()))
+            path.chmod(mode)
+        nginx = (f"pid {self.root}/nginx.pid;\nerror_log {self.root}/error.log;\n"
+                 "events { worker_connections 64; }\nhttp { access_log off;\n"
+                 f"include {self.root}/backend-fixture.conf;\n"
+                 f"include {self.root}/backend-fixture-edge.conf;\n}}\n")
+        (self.root / "nginx.conf").write_text(nginx)
+        process = subprocess.Popen(["nginx", "-p", str(self.root) + "/", "-c", "nginx.conf",
+                                    "-g", "daemon off;"], stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+        self.addCleanup(stop, process)
+        for _ in range(50):
+            try:
+                self.fetch("legacy.example")
+                break
+            except URLError:
+                self.assertIsNone(process.poll(), "owned nginx did not start")
+                time.sleep(0.05)
+        else:
+            self.fail("owned nginx did not become ready")
+
+    def fetch(self, host, token=None):
+        headers = {"Host": host}
+        if token is not None:
+            headers["X-App-Robot-Backend-Token"] = token
+        request = Request(f"http://127.0.0.1:{self.port}/healthz?probe=owned", headers=headers)
+        try:
+            with urlopen(request, timeout=2) as response:
+                return response.status, json.load(response)
+        except HTTPError as error:
+            with error:
+                return error.code, None
+
+    def test_real_nginx_rejects_missing_and_forged_tokens_and_retains_legacy_access(self):
+        self.assertEqual(self.fetch("edge.example"), (403, None))
+        self.assertEqual(self.fetch("edge.example", "wrong-token"), (403, None))
+        for host, token in (("edge.example", configured()["ingress_token"]), ("legacy.example", None)):
+            status, body = self.fetch(host, token)
+            self.assertEqual(status, 200)
+            self.assertEqual(body["build_sha"], "a" * 40)
+            self.assertEqual(body["path"], "/healthz?probe=owned")
+            self.assertFalse(body["ingress_received"])
+            self.assertIsNone(body["upgrade"])
+            self.assertEqual(body["connection"], "close")
+
+    def test_real_nginx_exchanges_websocket_frames_and_enforces_ingress(self):
+        cases = (("edge.example", None, 403), ("edge.example", "wrong-token", 403),
+                 ("edge.example", configured()["ingress_token"], 101), ("legacy.example", None, 101))
+        for host, token, status in cases:
+            with self.subTest(host=host, status=status), socket.create_connection(("127.0.0.1", self.port), 2) as peer:
+                request = (f"GET /ws HTTP/1.1\r\nHost: {host}\r\nUpgrade: websocket\r\n"
+                           "Connection: Upgrade\r\nSec-WebSocket-Version: 13\r\n"
+                           "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==\r\n")
+                if token is not None:
+                    request += f"X-App-Robot-Backend-Token: {token}\r\n"
+                peer.sendall((request + "\r\n").encode())
+                with HTTPResponse(peer) as response:
+                    response.begin()
+                    self.assertEqual(response.status, status)
+                    if status != 101:
+                        continue
+                    self.assertEqual(response.getheader("Upgrade").lower(), "websocket")
+                    self.assertEqual(response.getheader("Sec-WebSocket-Accept"), "s3pPLMBiTxaQ9kYGzzhZRbK+xOo=")
+                    payload, mask = b"ping-through-nginx", b"\x01\x02\x03\x04"
+                    masked = bytes(value ^ mask[index % 4] for index, value in enumerate(payload))
+                    peer.sendall(bytes((0x81, 0x80 | len(payload))) + mask + masked)
+                    self.assertEqual(response.fp.read(2), bytes((0x81, len(payload))))
+                    self.assertEqual(response.fp.read(len(payload)), payload)
+
+    def test_real_nginx_delivers_sse_before_upstream_completion(self):
+        for host, token in (("edge.example", configured()["ingress_token"]), ("legacy.example", None)):
+            with self.subTest(host=host):
+                self.server.stream_release.clear()
+                self.server.stream_finished.clear()
+                headers = {"Host": host}
+                if token is not None:
+                    headers["X-App-Robot-Backend-Token"] = token
+                request = Request(f"http://127.0.0.1:{self.port}/stream", headers=headers)
+                try:
+                    with urlopen(request, timeout=2) as response:
+                        self.assertEqual(response.readline(), b"data: first\n")
+                        self.assertFalse(self.server.stream_finished.is_set())
+                        self.server.stream_release.set()
+                        self.assertEqual(response.read(), b"\ndata: second\n\n")
+                finally:
+                    self.server.stream_release.set()
+                    self.assertTrue(self.server.stream_finished.wait(2))

package/backend-action/test_edge_vhost.py

@@ -0,0 +1,72 @@
+import json
+from pathlib import Path
+import subprocess
+import tempfile
+import unittest
+
+import configure_vhost
+import edge_vhost
+from test_edge_inputs import configured
+
+
+class Vhosts(unittest.TestCase):
+    def setUp(self):
+        self.directory = tempfile.TemporaryDirectory()
+        self.addCleanup(self.directory.cleanup)
+        self.root = Path(self.directory.name)
+        self.config = self.root / ".backend-edge.json"
+        self.config.write_text(json.dumps(configured()))
+        self.legacy, self.edge, self.include = edge_vhost.paths(self.config, "fixture", self.root)
+        self.calls = []
+
+    def run_nginx(self, command, **kwargs):
+        self.calls.append(command)
+
+    def test_legacy_tls_port_changes_and_replay(self):
+        original = configure_vhost.content("", "legacy.example", 31000).replace(
+            "listen 80;", "listen 443 ssl;\n    ssl_certificate /existing/cert;")
+        self.legacy.write_text(original)
+        self.legacy.chmod(0o640)
+        for port in (32000, 33000, 33000):
+            edge_vhost.configure(self.config, "fixture", "edge.example", port, self.root, self.run_nginx)
+            self.assertEqual(self.legacy.read_text(), original.replace(":31000;", f":{port};"))
+            self.assertEqual(self.legacy.stat().st_mode & 0o777, 0o640)
+            self.assertIn(f":{port};", self.edge.read_text())
+            self.assertNotIn("backend-ingress", self.legacy.read_text())
+        self.assertEqual(self.calls, [["nginx", "-t"], ["systemctl", "reload", "nginx"]] * 2)
+        self.assertEqual(self.include.stat().st_mode & 0o777, 0o600)
+        self.assertNotIn(configured()["ingress_token"], self.edge.read_text())
+
+    def test_new_app_has_no_public_legacy_vhost_and_cannot_downgrade(self):
+        edge_vhost.configure(self.config, "fixture", "edge.example", 32000, self.root, self.run_nginx)
+        self.assertFalse(self.legacy.exists())
+        self.config.write_text(json.dumps(configured(ingress_required="false", ingress_token="")))
+        with self.assertRaisesRegex(ValueError, "downgrade"):
+            edge_vhost.validate(self.config, "fixture", "edge.example", self.root)
+        self.config.unlink()
+        with self.assertRaisesRegex(ValueError, "downgrade"):
+            edge_vhost.validate(self.config, "fixture", "edge.example", self.root)
+
+    def test_domain_collision_and_ambiguous_legacy_refuse_without_changes(self):
+        for original in (configure_vhost.content("", "edge.example", 31000),
+                         "server {\n    server_name ambiguous.example another.example;\n}"):
+            self.legacy.write_text(original)
+            with self.assertRaises(ValueError):
+                edge_vhost.configure(self.config, "fixture", "edge.example", 32000, self.root, self.run_nginx)
+            self.assertEqual(self.legacy.read_text(), original)
+            self.assertFalse(self.edge.exists())
+            self.assertFalse(self.include.exists())
+        self.assertEqual(self.calls, [])
+
+    def test_failed_nginx_check_restores_only_the_owned_files(self):
+        original = configure_vhost.content("", "legacy.example", 31000)
+        self.legacy.write_text(original)
+
+        def failure(command, **kwargs):
+            raise subprocess.CalledProcessError(1, command, stderr=b"private-output")
+
+        with self.assertRaisesRegex(ValueError, "backend_edge_nginx_failed"):
+            edge_vhost.configure(self.config, "fixture", "edge.example", 32000, self.root, failure)
+        self.assertEqual(self.legacy.read_text(), original)
+        self.assertFalse(self.edge.exists())
+        self.assertFalse(self.include.exists())

package/docs/BACKEND_EDGE.md

@@ -0,0 +1,45 @@
+# App-owned Cloudflare API ingress
+
+Provision the app's Pages/Workers route and its per-app ingress token before deploying the backend.
+`BACKEND_API_DOMAIN` remains a distinct infrastructure hostname pointing to the deploy host; never
+set it to a Pages/Workers hostname. Set these repository values for edge delivery:
+
+- `BACKEND_PUBLIC_BASE_URL`: the client API base, for example `https://app.pages.dev/api`.
+- `BACKEND_PUBLIC_HEALTH_URL`: that base plus the backend health path, for example `/healthz`.
+- `BACKEND_INGRESS_REQUIRED`: `true`.
+- Secret `BACKEND_INGRESS_TOKEN`: the same 43–128 character URL-safe token the edge sends in
+  `X-App-Robot-Backend-Token`; never ship it in clients or app source.
+
+The workflow supplies the exact commit SHA, and the public health endpoint must return JSON
+with `build_sha` equal to that SHA. A completed HTTPS 2xx is required; redirects, partial transfers,
+missing identity and another build fail deployment. The same check rejects missing/incorrect tokens
+at the infrastructure hostname, verifies authenticated origin health and probes the public URL
+without passing the token. The edge must add it itself.
+
+The action adds `BACKEND_PUBLIC_BASE_URL` to Compose interpolation through a separate host-side
+dotenv file, after `.env` and `.runtime.env`. The app's Compose service must explicitly consume it:
+
+```yaml
+environment:
+  BACKEND_PUBLIC_BASE_URL: ${BACKEND_PUBLIC_BASE_URL:?required}
+```
+
+Use that value for redirects and generated API links. Preserve the action's private runtime files;
+the ingress token is transported on SSH stdin and used in a mode-0600 nginx include, not CLI arguments.
+Ingress configuration and public dotenv live in `/opt/gowalk-backend-ingress/<app>/`, outside the
+application's Docker build context; broad application COPY instructions cannot include the token.
+The new protected vhost is `backend-<app>-edge.conf`. An existing `backend-<app>.conf` keeps its
+legacy domain and TLS configuration, and both upstream ports follow Compose on every deployment.
+The old public hostname is health-checked without authentication so released clients remain usable.
+An edge alias matching the existing legacy hostname is refused; provision a new alias instead.
+Missing ingress settings on an already protected app cannot reopen its origin.
+
+Managed backend locations forward WebSocket upgrades and disable response buffering so SSE and
+streaming responses arrive incrementally. The Connection header becomes `upgrade` only when the
+request carries an Upgrade header; ordinary HTTP requests use `close`. Each vhost owns a distinct
+connection map, so protected and legacy domains coexist. Deployment updates existing locations
+while preserving their domains, TLS settings and ingress checks.
+
+These options are also named backend settings in `.gowalk-cicd.yml`: `public-base-url`,
+`public-health-url`, `expected-build-sha`, `ingress-required` and `ingress-token`. Reference secrets
+by name. Deployments without these options retain public origin access, certificate handling and health checks.

package/docs/CONFIGURATION.md

@@ -19,6 +19,11 @@ mobile:
 backend:
   host: ${{ vars.BACKEND_DEPLOY_HOST }}
   runtime-env: ${{ secrets.BACKEND_RUNTIME_ENV }}
+  public-base-url: ${{ vars.BACKEND_PUBLIC_BASE_URL }}
+  public-health-url: ${{ vars.BACKEND_PUBLIC_HEALTH_URL }}
+  expected-build-sha: ${{ vars.BACKEND_PUBLIC_HEALTH_URL && github.sha || '' }}
+  ingress-required: ${{ vars.BACKEND_INGRESS_REQUIRED || 'false' }}
+  ingress-token: ${{ secrets.BACKEND_INGRESS_TOKEN }}
 workflows:
   deploy.yml:
     overrides: []
@@ -30,6 +35,12 @@ until the app explicitly replaces their references in this file. Keep passwords,
 signing material, tokens and private keys in GitHub Secrets. Reference their names;
 never put their values in this configuration.
 
+Backend edge settings are optional and preserve legacy deployments when absent. When enabled,
+the infrastructure `api-domain` must be a fresh alias distinct from the retained legacy hostname.
+Provision its Cloudflare route/token first. Public health proves the exact `build_sha`; the app's
+Compose service must pass `BACKEND_PUBLIC_BASE_URL` into its container and use it in generated URLs.
+The same named repository inputs reach the feature-branch backend preview in `deploy.yml`.
+
 The supported managed files are `deploy.yml`, `mobile-candidate.yml`,
 `deploy-web.yml` and `deploy-backend.yml`. App-specific values outside the named
 mobile/backend inputs, and custom jobs or steps embedded in those workflows,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gowalk-cicd",
-  "version": "1.0.147",
+  "version": "1.0.149",
   "description": "Zero-config GitHub Actions delivery for iOS TestFlight and Android Google Play.",
   "type": "module",
   "bin": {
@@ -23,6 +23,7 @@
     "CLAUDE.md",
     "docs/GRADLE_CACHE.md",
     "docs/CANDIDATE_ARTIFACTS.md",
+    "docs/BACKEND_EDGE.md",
     "scripts/upgrade-org.mjs",
     "scripts/lib/",
     "docs/CONFIGURATION.md"

package/src/config/settings.mjs

@@ -8,7 +8,8 @@ const backend = ['jobs', 'deploy', 'steps', 'items', 'name:Deploy backend', 'wit
 const inputs = {
   ios: ['project', 'workspace', 'scheme', 'configuration', 'bundle-id', 'team-id', 'firebase-app-id'],
   android: ['project-dir', 'module', 'variant', 'firebase-app-id', 'dart-defines'],
-  backend: ['ssh-key', 'host', 'app-name', 'api-domain', 'backend-dir', 'compose-file', 'health-path', 'runtime-env'],
+  backend: ['ssh-key', 'host', 'app-name', 'api-domain', 'backend-dir', 'compose-file', 'health-path', 'runtime-env',
+    'public-health-url', 'public-base-url', 'expected-build-sha', 'ingress-required', 'ingress-token'],
 };
 
 export function settingsPaths(file) {

package/templates/deploy-backend.yml

@@ -72,4 +72,9 @@ jobs:
           backend-dir: ${{ steps.dir.outputs.path }}
           compose-file: ${{ steps.dir.outputs.compose }}
           health-path: ${{ vars.BACKEND_HEALTH_PATH || '/health' }}
+          public-health-url: ${{ vars.BACKEND_PUBLIC_HEALTH_URL }}
+          public-base-url: ${{ vars.BACKEND_PUBLIC_BASE_URL }}
+          expected-build-sha: ${{ vars.BACKEND_PUBLIC_HEALTH_URL && github.sha || '' }}
+          ingress-required: ${{ vars.BACKEND_INGRESS_REQUIRED || 'false' }}
+          ingress-token: ${{ secrets.BACKEND_INGRESS_TOKEN }}
           runtime-env: ${{ secrets.BACKEND_RUNTIME_ENV }}

package/templates/deploy.yml

@@ -714,4 +714,9 @@ jobs:
           backend-dir: ${{ steps.dir.outputs.path }}
           compose-file: ${{ steps.dir.outputs.compose }}
           health-path: ${{ vars.BACKEND_HEALTH_PATH || '/health' }}
+          public-health-url: ${{ vars.BACKEND_PUBLIC_HEALTH_URL }}
+          public-base-url: ${{ vars.BACKEND_PUBLIC_BASE_URL }}
+          expected-build-sha: ${{ vars.BACKEND_PUBLIC_HEALTH_URL && github.sha || '' }}
+          ingress-required: ${{ vars.BACKEND_INGRESS_REQUIRED || 'false' }}
+          ingress-token: ${{ secrets.BACKEND_INGRESS_TOKEN }}
           runtime-env: ${{ secrets.BACKEND_RUNTIME_ENV }}