gowalk-cicd 1.0.191 → 1.0.193

package/README.md

@@ -1372,3 +1372,14 @@ provenance. Call it from the app's read-only diagnostic workflow with `diagnosti
 `expected-build-sha`, using its existing host/key/pin inputs. It requires the released host forced command as well
 as the updated action. See [the scoped runtime contract and host installer](docs/BACKEND_SSH_GATE.md#applied-runtime-readback).
 Identity failure logs and source Compose files do not establish this applied state.
+
+### Read-only bridge and VPN prerequisite diagnostics
+
+Backend Deploy also offers `operation: network-diagnostics`, with an exact `diagnostic-service`, deployed
+`diagnostic-build-sha`, owned `diagnostic-network`, proposed namespace-only private IPv4 `/24` in
+`diagnostic-pool`, exact `diagnostic-vpn-service`, and optional `diagnostic-provider: digitalocean`.
+It reports the owned bridge/IPAM, observed pool conflicts, UDP 500/4500 ownership, bound host identity and
+kernel/firewall facts in a closed v3 artifact. The allocator stays retired; a completed read is never
+deployment, port reservation, globally unused address space or tunnel proof. Effective firewall ingress and
+unobserved capabilities remain unverified. The [trusted-host procedure](docs/BACKEND_SSH_GATE.md#owned-bridge-and-vpn-prerequisite-readback)
+defines scope, retained evidence and the required host runtime adoption before this operation is available.

package/backend-action/action.yml

@@ -7,7 +7,7 @@ description: >
 
 inputs:
   operation:
-    description: deploy (default), identity-diagnostics or runtime-diagnostics.
+    description: deploy (default), identity-diagnostics, runtime-diagnostics or read-only network-diagnostics.
     required: false
     default: deploy
   diagnostic-service:
@@ -19,9 +19,21 @@ inputs:
     required: false
     default: ""
   diagnostic-provider:
-    description: Ignored; network-diagnostics was removed with the network allocator.
+    description: Fixed metadata corroboration for network-diagnostics (none or digitalocean); allocates nothing.
     required: false
     default: none
+  diagnostic-network:
+    description: Exact owned Compose bridge network key for network-diagnostics.
+    required: false
+    default: default
+  diagnostic-pool:
+    description: Proposed strict private IPv4 /24 for a VPN container namespace; never a host allocation.
+    required: false
+    default: ""
+  diagnostic-vpn-service:
+    description: Exact owned Compose service whose existing UDP 500/4500 bindings may be reused.
+    required: false
+    default: vpn
   host:
     description: Explicit SSH host from the backend binding; no infrastructure fallback.
     required: true
@@ -106,7 +118,7 @@ runs:
         API_DOMAIN: ${{ inputs.api-domain }}
         DEPLOY_HOST: ${{ inputs.host }}
       run: |
-        case "$OPERATION" in deploy|identity-diagnostics|runtime-diagnostics) ;; *) exit 1;; esac
+        case "$OPERATION" in deploy|identity-diagnostics|runtime-diagnostics|network-diagnostics) ;; *) exit 1;; esac
         # Only a repository with a bound origin holds the deploy key; the panel sets the domain when it binds one.
         if [ "$OPERATION" = deploy ] && [ -z "$API_DOMAIN" ]; then
           echo "::notice title=backend_origin_unbound::No api-domain: the backend origin is not bound yet, nothing deployed"
@@ -306,6 +318,39 @@ runs:
         path: ${{ steps.runtime_diagnostics.outputs.result }}
         if-no-files-found: error
 
+    - name: Read scoped backend network prerequisites
+      id: network_diagnostics
+      if: inputs.operation == 'network-diagnostics'
+      shell: bash
+      env:
+        DIAGNOSTIC_APP: ${{ inputs.app-name }}
+        DIAGNOSTIC_SERVICE: ${{ inputs.diagnostic-service }}
+        DIAGNOSTIC_HOST: ${{ inputs.host }}
+        DIAGNOSTIC_USER: ${{ inputs.ssh-user }}
+        DIAGNOSTIC_BUILD: ${{ inputs.expected-build-sha }}
+        DIAGNOSTIC_NETWORK: ${{ inputs.diagnostic-network }}
+        DIAGNOSTIC_POOL: ${{ inputs.diagnostic-pool }}
+        DIAGNOSTIC_VPN_SERVICE: ${{ inputs.diagnostic-vpn-service }}
+        DIAGNOSTIC_PROVIDER: ${{ inputs.diagnostic-provider }}
+      run: |
+        RESULT_DIR="$(mktemp -d "$RUNNER_TEMP/backend-network-diagnostics.XXXXXX")"
+        echo "result=$RESULT_DIR/result.json" >> "$GITHUB_OUTPUT"
+        python3 "${{ github.action_path }}/network_diagnostics.py" \
+          --app "$DIAGNOSTIC_APP" --service "$DIAGNOSTIC_SERVICE" --expected-build-sha "$DIAGNOSTIC_BUILD" \
+          --network "$DIAGNOSTIC_NETWORK" --pool "$DIAGNOSTIC_POOL" --vpn-service "$DIAGNOSTIC_VPN_SERVICE" \
+          --host "$DIAGNOSTIC_HOST" --user "$DIAGNOSTIC_USER" --provider "$DIAGNOSTIC_PROVIDER" \
+          --output "$RESULT_DIR/result.json"
+
+    - name: Retain scoped backend network result
+      if: always() && inputs.operation == 'network-diagnostics'
+      uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5
+      env:
+        NODE_OPTIONS: --require "${{ github.action_path }}/scripts/artifact_env.cjs"
+      with:
+        name: backend-network-diagnostics-${{ github.job }}-${{ github.run_attempt }}
+        path: ${{ steps.network_diagnostics.outputs.result }}
+        if-no-files-found: error
+
     - name: Cleanup key
       if: always()
       shell: bash

package/backend-action/install_runtime.py

@@ -21,6 +21,7 @@ REQUIRED = (
     'runtime_env.py', 'runtime_env_parse.py', 'edge_inputs.py', 'edge_vhost.py', 'edge_health.py',
     'configure_vhost.py', 'vhost_diagnostics.py', 'remote_deploy.sh', 'deploy_evidence.sh',
     'ensure_certificate.sh', 'select_certbot_account.sh',
+    'network_projection.py', 'network_inventory.py', 'network_host.py', 'network_metadata.py', 'network_readback.py',
 )
 
 
@@ -96,13 +97,14 @@ def update_commands(content, target, owners):
     for owner in owners:
         if not re.fullmatch(r'[a-z0-9-]{1,40}', owner):
             raise ValueError('release_owner_invalid')
-        pattern = re.compile(r'command="/usr/bin/python3 /opt/gowalk-cicd-runtime/\d+\.\d+\.\d+'
+        pattern = re.compile(r'command="(?P<python>/usr/bin/python3(?: -B)?) /opt/gowalk-cicd-runtime/\d+\.\d+\.\d+'
                              r'/backend-action/ssh_gate\.py ' + re.escape(owner) + r'"')
         matches = [index for index, line in enumerate(lines) if pattern.search(line)]
         if len(matches) != 1 or 'restrict' not in lines[matches[0]].split(' ')[0].split(','):
             raise ValueError('release_owner_command_ambiguous')
-        replacement = 'command="/usr/bin/python3 ' + str(target / 'backend-action/ssh_gate.py') + ' ' + owner + '"'
-        lines[matches[0]] = pattern.sub(lambda _match: replacement, lines[matches[0]])
+        destination = str(target / 'backend-action/ssh_gate.py') + ' ' + owner + '"'
+        lines[matches[0]] = pattern.sub(lambda match: 'command="' + match['python'] + ' ' + destination,
+                                       lines[matches[0]])
     return ''.join(lines)
 
 

package/backend-action/network_diagnostics.py

@@ -0,0 +1,65 @@
+"""Call only the released scoped network reader through the pinned CI backend identity."""
+import argparse
+import json
+import re
+import shlex
+from pathlib import Path
+
+from identity_diagnostics import ReaderFailure, bounded, retain_result
+from network_projection import NetworkFailure, envelope, scope, validate
+
+
+def local(args):
+    fields = (args.app, args.service, args.expected_build_sha, args.network, args.pool,
+              args.vpn_service, args.host, args.provider)
+    scope(*fields)
+    if not re.fullmatch(r'[a-z_][a-z0-9_-]{0,31}', args.user):
+        raise NetworkFailure('invalid_scope')
+    command = shlex.join(['gowalk-backend', 'network-diagnostics', *fields])
+    try:
+        status, raw = bounded(['ssh', '-T', '-i', str(Path.home() / '.ssh/backend_deploy'),
+            '-o', 'IdentitiesOnly=yes', '-o', 'BatchMode=yes', '-o', 'StrictHostKeyChecking=yes',
+            '-o', 'ConnectTimeout=10', '-o', 'ServerAliveInterval=5', '-o', 'ServerAliveCountMax=2',
+            '-o', 'ClearAllForwardings=yes', args.user + '@' + args.host, command], seconds=120, with_status=True)
+    except ReaderFailure as error:
+        raise NetworkFailure(error.code) from None
+    except OSError:
+        raise NetworkFailure('transport_failure') from None
+    if status not in (0, 1):
+        raise NetworkFailure('transport_failure')
+    if status == 1 and not raw.strip():
+        raise NetworkFailure('network_reader_unavailable')
+    try:
+        result = validate(json.loads(raw), *fields)
+    except (ValueError, TypeError, KeyError):
+        raise NetworkFailure('remote_invalid') from None
+    if result['ok'] != (status == 0):
+        raise NetworkFailure('remote_invalid')
+    return result
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    for name in ('app', 'expected-build-sha', 'pool', 'host', 'output'):
+        parser.add_argument('--' + name, required=True)
+    for name, default in [('service', 'api'), ('network', 'default'), ('vpn-service', 'vpn'),
+                          ('provider', 'none'), ('user', 'root')]:
+        parser.add_argument('--' + name, default=default)
+    args = parser.parse_args()
+    fields = (args.app, args.service, args.expected_build_sha, args.network, args.pool,
+              args.vpn_service, args.host, args.provider)
+    try:
+        result = local(args)
+    except Exception as error:
+        result = envelope(*fields, failure=error.code if isinstance(error, NetworkFailure) else 'unclassified',
+                          reader_version=None)
+    try:
+        retain_result(args.output, result)
+    except ReaderFailure:
+        result = envelope(*fields, failure='artifact_write_failed', reader_version=None)
+    print(json.dumps(result, separators=(',', ':')))
+    return 0 if result['ok'] else 1
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

package/backend-action/network_host.py

@@ -0,0 +1,149 @@
+"""Fixed host-side observations; socket owners and firewall rules stay private."""
+import ipaddress
+import json
+import re
+import shlex
+
+from network_inventory import run
+from network_projection import NetworkFailure
+
+
+def host_binding(host, rows):
+    try:
+        addresses = {str(ipaddress.IPv4Address(host))}
+    except ValueError:
+        raw = run(['getent', 'ahostsv4', host])
+        try:
+            addresses = {str(ipaddress.IPv4Address(line.split()[0])) for line in raw.decode().splitlines()}
+        except (ValueError, IndexError, UnicodeError):
+            raise NetworkFailure('host_binding_mismatch') from None
+    local = {row['local'] for row in rows if row['kind'] == 'address'}
+    if not addresses or not addresses.issubset(local):
+        raise NetworkFailure('host_binding_mismatch')
+    return addresses
+
+
+def listeners():
+    raw = run(['ss', '-H', '-l', '-u', '-n', '-p'])
+    values = {'500': [], '4500': []}
+    try:
+        for line in raw.decode().splitlines():
+            parts = line.split()
+            if len(parts) < 5 or parts[0] != 'UNCONN':
+                raise ValueError()
+            port = parts[3].rsplit(':', 1)[1]
+            if port in values:
+                owner = 'docker_proxy' if len(parts) > 5 and re.fullmatch(
+                    r'users:\(\("docker-proxy",pid=\d+,fd=\d+\)\)', ''.join(parts[5:])) else 'unknown'
+                values[port].append(owner)
+    except (ValueError, IndexError, UnicodeError):
+        raise NetworkFailure('network_invalid') from None
+    return values
+
+
+def udp_ports(app, service, bindings, observed):
+    result = {}
+    for port in ('500', '4500'):
+        owners = []
+        for row in bindings:
+            try:
+                matches = [binding for key, entries in (row['ports'] or {}).items() if key.endswith('/udp')
+                           for binding in entries or [] if str(binding['HostPort']) == port]
+            except (KeyError, TypeError, AttributeError):
+                raise NetworkFailure('network_invalid') from None
+            if matches:
+                own = (row['project'] == app and row['service'] == service
+                       and row['directory'] == '/opt/gowalk-backends/' + app)
+                owners.append('app_vpn' if own else 'foreign')
+        sockets = observed[port]
+        status = 'foreign' if 'foreign' in owners else 'unknown'
+        if owners and set(owners) == {'app_vpn'} and set(sockets).issubset({'docker_proxy'}):
+            status = 'app_vpn'
+        elif not owners and not sockets:
+            status = 'free'
+        result[port] = {'status': status, 'host_listener_observed': bool(sockets),
+                        'docker_binding_observed': bool(owners)}
+    return result
+
+
+def firewall(bridge):
+    raw = run(['iptables', '-w', '2', '-S'], optional=True)
+    nat = run(['iptables', '-w', '2', '-t', 'nat', '-S'], optional=True)
+    result = {'reader': 'unverified', 'input_policy': 'unverified', 'forward_policy': 'unverified',
+              'udp_allow_rules': {'500': False, '4500': False}, 'effective_ingress': 'unverified'}
+    masquerade = None
+    try:
+        if raw is not None:
+            rules = [shlex.split(line) for line in raw.decode().splitlines()]
+            result['reader'] = 'observed'
+            for chain, key in [('INPUT', 'input_policy'), ('FORWARD', 'forward_policy')]:
+                matches = [words[2] for words in rules if len(words) == 3 and words[:2] == ['-P', chain]]
+                if len(matches) == 1 and matches[0] in ('ACCEPT', 'DROP'):
+                    result[key] = matches[0]
+            for port in ('500', '4500'):
+                result['udp_allow_rules'][port] = any(words[:2] == ['-A', 'INPUT']
+                    and '-p' in words and words[words.index('-p') + 1] == 'udp'
+                    and '--dport' in words and words[words.index('--dport') + 1] == port
+                    and '-j' in words and words[words.index('-j') + 1] == 'ACCEPT' for words in rules)
+        if nat is not None:
+            subnets = {str(ipaddress.ip_network(item['subnet'])) for item in bridge['ipam']}
+            rules = [shlex.split(line) for line in nat.decode().splitlines()]
+            masquerade = any(words[:2] == ['-A', 'POSTROUTING'] and '-s' in words
+                and words[words.index('-s') + 1] in subnets and '-j' in words
+                and words[words.index('-j') + 1] == 'MASQUERADE' for words in rules)
+    except (ValueError, IndexError, UnicodeError):
+        raise NetworkFailure('network_invalid') from None
+    return result, masquerade, 'available' if nat is not None else 'unverified'
+
+
+def local_docker():
+    try:
+        endpoint = json.loads(run(['docker', 'context', 'inspect', '--format', '{{json .Endpoints.docker.Host}}']))
+    except (ValueError, TypeError):
+        raise NetworkFailure('network_scope_mismatch') from None
+    if endpoint not in ('unix:///var/run/docker.sock', 'unix:///run/docker.sock'):
+        raise NetworkFailure('network_scope_mismatch')
+
+
+def namespace(containers, app, vpn_service, bridge):
+    info = run(['docker', 'info', '--format', '{"os":{{json .OSType}},"security":{{json .SecurityOptions}}}'])
+    try:
+        value = json.loads(info)
+        if set(value) != {'os', 'security'} or not isinstance(value['security'], list):
+            raise ValueError()
+        rootful = value['os'] == 'linux' and not any('rootless' in str(item) for item in value['security'])
+    except (ValueError, TypeError):
+        raise NetworkFailure('network_invalid') from None
+    forwarding = run(['cat', '/proc/sys/net/ipv4/ip_forward'], optional=True)
+    forward = None if forwarding is None else forwarding.strip() == b'1'
+    xfrm = run(['ip', 'xfrm', 'state', 'count'], optional=True)
+    return {'docker_linux_rootful': rootful, 'host_ipv4_forwarding': forward,
+            'xfrm_read': 'available' if xfrm is not None else 'unverified',
+            'vpn_settings': vpn_settings(containers, app, vpn_service, bridge)}
+
+
+def vpn_settings(containers, app, service, bridge):
+    identifiers = [row['id'] for row in containers if row['service'] == service]
+    if not identifiers:
+        return 'absent'
+    if len(identifiers) != 1:
+        raise NetworkFailure('network_ambiguous')
+    template = ('{"id":{{json .Id}},"project":{{json (index .Config.Labels "com.docker.compose.project")}},'
+        '"service":{{json (index .Config.Labels "com.docker.compose.service")}},'
+        '"privileged":{{json .HostConfig.Privileged}},"network_mode":{{json .HostConfig.NetworkMode}},'
+        '"cap_add":{{json .HostConfig.CapAdd}},"cap_drop":{{json .HostConfig.CapDrop}},'
+        '"sysctls":{{json .HostConfig.Sysctls}}}')
+    try:
+        row = json.loads(run(['docker', 'inspect', '--format', template, identifiers[0]]))
+        if row['id'] != identifiers[0] or row['project'] != app or row['service'] != service:
+            raise NetworkFailure('network_scope_mismatch')
+        added = set(row['cap_add'] or [])
+        allowed = {'NET_ADMIN', 'NET_BIND_SERVICE', 'CHOWN', 'SETUID', 'SETGID'}
+        safe = (row['privileged'] is False and row['network_mode'] == bridge['name']
+                and 'NET_ADMIN' in added and added.issubset(allowed)
+                and 'ALL' in (row['cap_drop'] or [])
+                and (row['sysctls'] or {}).get('net.ipv4.ip_forward') == '1'
+                and (row['sysctls'] or {}).get('net.ipv4.conf.all.send_redirects') == '0')
+    except (ValueError, KeyError, TypeError):
+        raise NetworkFailure('network_invalid') from None
+    return 'isolated_net_admin' if safe else 'other'

package/backend-action/network_inventory.py

@@ -0,0 +1,152 @@
+"""Bounded private network snapshots; foreign names and configuration never enter receipts."""
+import ipaddress
+import json
+import re
+
+from identity_diagnostics import ReaderFailure, bounded
+from network_projection import CID, NetworkFailure
+
+NETWORK_FORMAT = ('{"id":{{json .Id}},"name":{{json .Name}},"driver":{{json .Driver}},'
+    '"project":{{json (index .Labels "com.docker.compose.project")}},'
+    '"key":{{json (index .Labels "com.docker.compose.network")}},'
+    '"bridge":{{json (index .Options "com.docker.network.bridge.name")}},"ipam":{{json .IPAM.Config}}}')
+PORT_FORMAT = ('{"id":{{json .ID}},"project":{{json (.Label "com.docker.compose.project")}},'
+    '"service":{{json (.Label "com.docker.compose.service")}},'
+    '"directory":{{json (.Label "com.docker.compose.project.working_dir")}},"ports":{{json .Ports}}}')
+
+
+def run(arguments, *, optional=False):
+    try:
+        return bounded(arguments, seconds=10)
+    except ReaderFailure as error:
+        if optional and error.code == 'command_failed':
+            return None
+        raise NetworkFailure(error.code) from None
+    except OSError:
+        if optional:
+            return None
+        raise NetworkFailure('command_failed') from None
+
+
+def decode(raw, *, lines=False):
+    try:
+        value = [json.loads(line) for line in raw.splitlines()] if lines else json.loads(raw)
+        if not isinstance(value, list) or len(value) > 1024:
+            raise ValueError()
+        return value
+    except (ValueError, TypeError, UnicodeError):
+        raise NetworkFailure('network_invalid') from None
+
+
+def identifiers(raw):
+    try:
+        values = raw.decode('ascii').splitlines()
+    except UnicodeError:
+        raise NetworkFailure('network_invalid') from None
+    if len(values) > 1024 or len(set(values)) != len(values) or any(not re.fullmatch(CID, x) for x in values):
+        raise NetworkFailure('network_invalid')
+    return sorted(values)
+
+
+def networks():
+    ids = identifiers(run(['docker', 'network', 'ls', '--no-trunc', '--format', '{{.ID}}']))
+    rows = []
+    for offset in range(0, len(ids), 32):
+        rows.extend(decode(run(['docker', 'network', 'inspect', '--format', NETWORK_FORMAT,
+                               *ids[offset:offset + 32]]), lines=True))
+    if sorted(row.get('id', '') for row in rows) != ids:
+        raise NetworkFailure('network_changed')
+    for row in rows:
+        if set(row) != {'id', 'name', 'driver', 'project', 'key', 'bridge', 'ipam'}:
+            raise NetworkFailure('network_invalid')
+        for item in row['ipam'] or []:
+            try:
+                ipaddress.ip_network(item['Subnet'], strict=True)
+            except (ValueError, KeyError, TypeError):
+                raise NetworkFailure('network_invalid') from None
+    return sorted(rows, key=lambda row: row['id'])
+
+
+def selected(rows, app, key):
+    matches = [row for row in rows if row['project'] == app and row['key'] == key]
+    if len(matches) != 1:
+        raise NetworkFailure('network_absent' if not matches else 'network_ambiguous')
+    row = matches[0]
+    if row['driver'] != 'bridge' or not row['ipam']:
+        raise NetworkFailure('network_scope_mismatch')
+    return {'network_id': row['id'], 'name': row['name'], 'driver': row['driver'], 'project': app, 'key': key,
+            'bridge': row['bridge'] or 'br-' + row['id'][:12],
+            'ipam': [{'subnet': x['Subnet'], 'gateway': x.get('Gateway', '')} for x in row['ipam']]}
+
+
+def host_networks():
+    addresses = decode(run(['ip', '-j', 'address', 'show']))
+    routes = decode(run(['ip', '-j', '-4', 'route', 'show', 'table', 'all']))
+    result = []
+    try:
+        for row in addresses:
+            for address in row.get('addr_info', []):
+                local = ipaddress.ip_address(address['local'])
+                result.append({'kind': 'address', 'device': row['ifname'], 'local': str(local),
+                    'subnet': str(ipaddress.ip_network(str(local) + '/' + str(address['prefixlen']), strict=False))})
+        for row in routes:
+            destination = row.get('dst', 'default')
+            if destination != 'default':
+                result.append({'kind': 'route', 'device': row.get('dev', ''), 'local': '',
+                               'subnet': str(ipaddress.ip_network(destination, strict=False))})
+    except (ValueError, TypeError, KeyError):
+        raise NetworkFailure('network_invalid') from None
+    if len(result) > 16384:
+        raise NetworkFailure('output_limit')
+    return sorted(result, key=lambda row: (row['kind'], row['device'], row['subnet'], row['local']))
+
+
+def overlap(rows, bridge, host_rows, pool):
+    proposed = ipaddress.IPv4Network(pool)
+    own = [ipaddress.ip_network(item['subnet']) for item in bridge['ipam']]
+    foreign = [ipaddress.ip_network(item['Subnet']) for row in rows if row['id'] != bridge['network_id']
+               for item in row['ipam'] or []]
+    others = [item for item in host_rows if item['device'] != bridge['bridge']]
+    intersects = lambda a, b: a.version == b.version and a.overlaps(b)
+    return {'selected_bridge_foreign_docker': any(intersects(a, b) for a in own for b in foreign),
+        'selected_bridge_host': any(intersects(a, ipaddress.ip_network(b['subnet'])) for a in own for b in others),
+        'pool_selected_bridge': any(intersects(proposed, item) for item in own),
+        'pool_foreign_docker': any(intersects(proposed, item) for item in foreign),
+        'pool_host_routes': any(intersects(proposed, ipaddress.ip_network(item['subnet'])) for item in host_rows
+                               if item['kind'] == 'route'),
+        'pool_host_addresses': any(intersects(proposed, ipaddress.ip_network(item['subnet'])) for item in host_rows
+                                  if item['kind'] == 'address'),
+        'default_gateway_destinations': 'unverified'}
+
+
+def port_bindings():
+    # Docker's publish filter matches the container port, so it can miss host 500 -> container 999.
+    rows = decode(run(['docker', 'ps', '--no-trunc', '--format', PORT_FORMAT]), lines=True)
+    result, observed = [], set()
+    for row in rows:
+        if (set(row) != {'id', 'project', 'service', 'directory', 'ports'}
+                or not re.fullmatch(CID, row['id']) or row['id'] in observed or not isinstance(row['ports'], str)):
+            raise NetworkFailure('network_invalid')
+        observed.add(row['id'])
+        bindings = {}
+        for entry in row['ports'].split(', '):
+            if '->' not in entry or not entry.endswith('/udp'):
+                continue
+            try:
+                host, target = entry.rsplit('->', 1)
+                if not re.fullmatch(r'[0-9]+(?:-[0-9]+)?/udp', target):
+                    raise ValueError()
+                ports = host.rsplit(':', 1)[1].split('-')
+                if not 1 <= len(ports) <= 2 or any(not re.fullmatch(r'[0-9]+', x) for x in ports):
+                    raise ValueError()
+                low, high = int(ports[0]), int(ports[-1])
+                if not 0 < low <= high <= 65535:
+                    raise ValueError()
+            except (ValueError, IndexError):
+                raise NetworkFailure('network_invalid') from None
+            for port in ('500', '4500'):
+                if low <= int(port) <= high:
+                    bindings.setdefault(port + '/udp', []).append({'HostPort': port})
+        if bindings:
+            result.append({**row, 'ports': bindings})
+    return sorted(result, key=lambda row: row['id'])

package/backend-action/network_metadata.py

@@ -0,0 +1,91 @@
+"""Optional fixed DigitalOcean metadata corroboration, without provider management or discovery."""
+import ipaddress
+import re
+import socket
+import time
+
+from network_host import host_binding
+from network_projection import NetworkFailure
+
+PATHS = {'droplet_id': '/metadata/v1/id', 'region': '/metadata/v1/region',
+    'public_ipv4': '/metadata/v1/interfaces/public/0/ipv4/address',
+    'private_ipv4': '/metadata/v1/interfaces/private/0/ipv4/address',
+    'netmask': '/metadata/v1/interfaces/private/0/ipv4/netmask'}
+
+
+def fetch(path):
+    if path not in PATHS.values():
+        raise NetworkFailure('invalid_scope')
+    deadline, raw = time.monotonic() + 2, bytearray()
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as connection:
+            connection.settimeout(2)
+            connection.connect(('169.254.169.254', 80))
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                return None
+            connection.settimeout(remaining)
+            request = 'GET ' + path + ' HTTP/1.0\r\nHost: 169.254.169.254\r\nConnection: close\r\n\r\n'
+            connection.sendall(request.encode('ascii'))
+            while True:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    return None
+                connection.settimeout(remaining)
+                data = connection.recv(1024)
+                if not data:
+                    break
+                raw.extend(data)
+                if len(raw) > 8192 + 128:
+                    return None
+        return payload(bytes(raw))
+    except (OSError, UnicodeError, ValueError):
+        return None
+
+
+def payload(raw):
+    try:
+        header, body = raw.split(b'\r\n\r\n', 1)
+        lines = header.split(b'\r\n')
+        if (len(header) > 8192 or len(body) > 128 or len(lines) > 17
+                or not re.fullmatch(rb'HTTP/1\.[01] 200(?: [\x20-\x7e]*)?', lines[0])):
+            return None
+        fields = [line.split(b':', 1) for line in lines[1:]]
+        headers = {key.lower(): value.strip() for key, value in fields}
+        if (len(headers) != len(fields) or b'transfer-encoding' in headers
+                or headers.get(b'content-encoding', b'identity') != b'identity'):
+            return None
+        length = headers.get(b'content-length')
+        if length is not None and (not re.fullmatch(rb'[0-9]{1,3}', length) or int(length) != len(body)):
+            return None
+        return body.decode('ascii').strip()
+    except (ValueError, UnicodeError):
+        return None
+
+
+def observe(host, rows, provider):
+    addresses = host_binding(host, rows)
+    result = {'binding': 'matched_local_address', 'provider': provider, 'provider_identity': None,
+              'metadata_status': 'not_requested' if provider == 'none' else 'unavailable'}
+    if provider == 'none':
+        return result
+    values = {key: fetch(path) for key, path in PATHS.items()}
+    if any(value is None for value in values.values()):
+        return result
+    try:
+        if (not re.fullmatch(r'[1-9][0-9]{0,19}', values['droplet_id'])
+                or not re.fullmatch(r'[a-z0-9-]{1,32}', values['region'])):
+            raise ValueError()
+        public = str(ipaddress.IPv4Address(values['public_ipv4']))
+        private = str(ipaddress.IPv4Address(values['private_ipv4']))
+        mask = ipaddress.IPv4Network('0.0.0.0/' + values.pop('netmask'))
+        subnet = str(ipaddress.IPv4Network(private + '/' + str(mask.prefixlen), strict=False))
+    except (ValueError, TypeError):
+        result['metadata_status'] = 'unverified'
+        return result
+    if (public not in addresses or not any(row['kind'] == 'address' and row['local'] == private
+                                          and row['subnet'] == subnet for row in rows)):
+        raise NetworkFailure('host_binding_mismatch')
+    values['private_subnet'] = subnet
+    result.update(provider_identity=values, metadata_status='matched')
+    return result

package/backend-action/network_projection.py

@@ -0,0 +1,151 @@
+"""Closed observations for one owned bridge and a proposed namespace-only VPN pool."""
+import ipaddress
+import re
+
+from runtime_projection import READER_VERSION, PROJECT, SERVICE, SHA, CID
+
+SCHEMA = 'gowalk-cicd/backend-network-diagnostics.v3'
+FAILURES = frozenset({'invalid_scope', 'network_absent', 'network_ambiguous', 'network_scope_mismatch',
+    'network_changed', 'network_invalid', 'build_mismatch', 'host_binding_mismatch', 'command_timeout',
+    'output_limit', 'command_failed', 'transport_failure', 'remote_invalid', 'artifact_write_failed',
+    'network_reader_unavailable', 'unclassified'})
+
+
+class NetworkFailure(Exception):
+    def __init__(self, code):
+        self.code = code if code in FAILURES else 'unclassified'
+        super().__init__(self.code)
+
+
+def scope(app, service, expected, network, pool, vpn_service, host, provider):
+    fields = ((app, PROJECT), (service, SERVICE), (expected, SHA), (network, SERVICE),
+              (vpn_service, SERVICE), (host, r'[A-Za-z0-9][A-Za-z0-9.-]{0,252}'))
+    if any(not isinstance(value, str) or not re.fullmatch(pattern, value) for value, pattern in fields):
+        raise NetworkFailure('invalid_scope')
+    try:
+        candidate = ipaddress.IPv4Network(pool, strict=True)
+    except (ValueError, TypeError):
+        raise NetworkFailure('invalid_scope') from None
+    private = ('10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16')
+    if (candidate.prefixlen != 24 or not any(candidate.subnet_of(ipaddress.IPv4Network(x)) for x in private)
+            or provider not in ('none', 'digitalocean')):
+        raise NetworkFailure('invalid_scope')
+
+
+def envelope(app, service, expected, network, pool, vpn_service, host, provider, failure='', *,
+             reader_version=READER_VERSION):
+    return {'schema': SCHEMA, 'reader_version': reader_version, 'ok': not failure, 'failure': failure,
+            'project': app, 'build_service': service, 'expected_build_sha': expected, 'network_key': network,
+            'proposed_pool': pool, 'vpn_service': vpn_service, 'expected_host': host, 'provider': provider}
+
+
+def closed(value, fields):
+    if not isinstance(value, dict) or set(value) != set(fields):
+        raise NetworkFailure('remote_invalid')
+
+
+def bridge_record(row, app, network):
+    closed(row, ('network_id', 'name', 'driver', 'project', 'key', 'bridge', 'ipam'))
+    if (not isinstance(row['network_id'], str) or not re.fullmatch(CID, row['network_id'])
+            or row['project'] != app or row['key'] != network or row['driver'] != 'bridge'
+            or not isinstance(row['name'], str) or not re.fullmatch(r'[A-Za-z0-9_.-]{1,256}', row['name'])
+            or not isinstance(row['bridge'], str) or not re.fullmatch(r'[A-Za-z0-9_.-]{1,15}', row['bridge'])
+            or not isinstance(row['ipam'], list) or not 1 <= len(row['ipam']) <= 16):
+        raise NetworkFailure('remote_invalid')
+    for item in row['ipam']:
+        closed(item, ('subnet', 'gateway'))
+        if any(not isinstance(value, str) for value in item.values()):
+            raise NetworkFailure('remote_invalid')
+        try:
+            subnet = ipaddress.ip_network(item['subnet'], strict=True)
+            gateway = ipaddress.ip_address(item['gateway'])
+            if gateway not in subnet:
+                raise ValueError()
+        except (ValueError, TypeError):
+            raise NetworkFailure('remote_invalid') from None
+
+
+def observation_records(result):
+    closed(result['overlap'], ('selected_bridge_foreign_docker', 'selected_bridge_host',
+        'pool_selected_bridge', 'pool_foreign_docker', 'pool_host_routes', 'pool_host_addresses',
+        'default_gateway_destinations'))
+    if (result['overlap']['default_gateway_destinations'] != 'unverified'
+            or any(type(value) is not bool for key, value in result['overlap'].items()
+                   if key != 'default_gateway_destinations')):
+        raise NetworkFailure('remote_invalid')
+    closed(result['udp_ports'], ('500', '4500'))
+    for row in result['udp_ports'].values():
+        closed(row, ('status', 'host_listener_observed', 'docker_binding_observed'))
+        if (row['status'] not in ('free', 'app_vpn', 'foreign', 'unknown')
+                or any(type(row[key]) is not bool for key in ('host_listener_observed', 'docker_binding_observed'))):
+            raise NetworkFailure('remote_invalid')
+        observed = row['host_listener_observed'] or row['docker_binding_observed']
+        if ((row['status'] == 'free') == observed
+                or row['status'] in ('app_vpn', 'foreign') and not row['docker_binding_observed']):
+            raise NetworkFailure('remote_invalid')
+    closed(result['namespace'], ('docker_linux_rootful', 'host_ipv4_forwarding', 'xfrm_read',
+        'netfilter_nat_read', 'selected_bridge_masquerade', 'vpn_settings'))
+    for key in ('docker_linux_rootful', 'host_ipv4_forwarding', 'selected_bridge_masquerade'):
+        if result['namespace'][key] is not None and type(result['namespace'][key]) is not bool:
+            raise NetworkFailure('remote_invalid')
+    for key in ('xfrm_read', 'netfilter_nat_read'):
+        if result['namespace'][key] not in ('available', 'unavailable', 'unverified'):
+            raise NetworkFailure('remote_invalid')
+    if result['namespace']['vpn_settings'] not in ('absent', 'isolated_net_admin', 'other', 'unverified'):
+        raise NetworkFailure('remote_invalid')
+
+
+def host_records(result, provider):
+    closed(result['host'], ('binding', 'provider', 'provider_identity', 'metadata_status'))
+    row = result['host']
+    if (row['binding'] != 'matched_local_address' or row['provider'] != provider
+            or row['metadata_status'] not in ('matched', 'unavailable', 'unverified', 'not_requested')):
+        raise NetworkFailure('remote_invalid')
+    identity = row['provider_identity']
+    if identity is not None:
+        closed(identity, ('droplet_id', 'region', 'public_ipv4', 'private_ipv4', 'private_subnet'))
+        if any(not isinstance(value, str) for value in identity.values()):
+            raise NetworkFailure('remote_invalid')
+        if (not re.fullmatch(r'[1-9][0-9]{0,19}', str(identity['droplet_id']))
+                or not isinstance(identity['region'], str) or not re.fullmatch(r'[a-z0-9-]{1,32}', identity['region'])):
+            raise NetworkFailure('remote_invalid')
+        try:
+            ipaddress.IPv4Address(identity['public_ipv4'])
+            ipaddress.IPv4Address(identity['private_ipv4'])
+            ipaddress.IPv4Network(identity['private_subnet'], strict=True)
+        except (ValueError, TypeError):
+            raise NetworkFailure('remote_invalid') from None
+    if (row['metadata_status'] == 'matched') != (identity is not None):
+        raise NetworkFailure('remote_invalid')
+    if (provider == 'none') != (row['metadata_status'] == 'not_requested'):
+        raise NetworkFailure('remote_invalid')
+    closed(result['firewall'], ('reader', 'input_policy', 'forward_policy', 'udp_allow_rules', 'effective_ingress'))
+    row = result['firewall']
+    if (row['reader'] not in ('observed', 'unverified') or row['effective_ingress'] != 'unverified'
+            or any(row[key] not in ('ACCEPT', 'DROP', 'unverified') for key in ('input_policy', 'forward_policy'))):
+        raise NetworkFailure('remote_invalid')
+    closed(row['udp_allow_rules'], ('500', '4500'))
+    if any(type(value) is not bool for value in row['udp_allow_rules'].values()):
+        raise NetworkFailure('remote_invalid')
+
+
+def validate(result, app, service, expected, network, pool, vpn_service, host, provider):
+    scope(app, service, expected, network, pool, vpn_service, host, provider)
+    base = envelope(app, service, expected, network, pool, vpn_service, host, provider)
+    if (not isinstance(result, dict) or type(result.get('ok')) is not bool
+            or any(result.get(key) != value for key, value in base.items() if key not in ('ok', 'failure'))):
+        raise NetworkFailure('remote_invalid')
+    if not result['ok']:
+        if set(result) != set(base) or result.get('failure') not in FAILURES:
+            raise NetworkFailure('remote_invalid')
+        return result
+    closed(result, set(base) | {'observed_build_sha', 'bridge', 'overlap', 'udp_ports', 'host', 'namespace',
+                              'firewall', 'observed_at'})
+    if (result['failure'] or result['observed_build_sha'] != expected
+            or not isinstance(result['observed_at'], str)
+            or not re.fullmatch(r'\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ', result['observed_at'])):
+        raise NetworkFailure('remote_invalid')
+    bridge_record(result['bridge'], app, network)
+    observation_records(result)
+    host_records(result, provider)
+    return result

package/backend-action/network_readback.py

@@ -0,0 +1,65 @@
+"""Read stable owned bridge and namespace-only VPN prerequisites; never mutate host networking."""
+import datetime
+import json
+import sys
+
+import network_host
+import network_inventory
+import network_metadata
+import runtime_readback
+from network_projection import NetworkFailure, envelope, scope, validate
+from runtime_projection import RuntimeFailure
+
+
+def application(app, service, expected):
+    try:
+        identifiers = runtime_readback.containers(app)
+        rows = runtime_readback.inspect(app, identifiers)
+    except RuntimeFailure as error:
+        mapping = {'runtime_absent': 'network_absent', 'runtime_ambiguous': 'network_ambiguous',
+                   'runtime_scope_mismatch': 'network_scope_mismatch', 'runtime_changed': 'network_changed',
+                   'runtime_invalid': 'network_invalid'}
+        raise NetworkFailure(mapping.get(error.code, error.code)) from None
+    selected = [row for row in rows if row['service'] == service and row['running']]
+    if len(selected) != 1 or selected[0]['binding'].get('BUILD_SHA') != expected:
+        raise NetworkFailure('build_mismatch')
+    return rows
+
+
+def snapshot(app, service, expected):
+    return {'application': application(app, service, expected), 'networks': network_inventory.networks(),
+            'host': network_inventory.host_networks(), 'bindings': network_inventory.port_bindings(),
+            'listeners': network_host.listeners()}
+
+
+def collect(app, service, expected, network, pool, vpn_service, host, provider):
+    scope(app, service, expected, network, pool, vpn_service, host, provider)
+    network_host.local_docker()
+    original = snapshot(app, service, expected)
+    bridge = network_inventory.selected(original['networks'], app, network)
+    host_result = network_metadata.observe(host, original['host'], provider)
+    firewall, masquerade, netfilter = network_host.firewall(bridge)
+    namespace = network_host.namespace(original['application'], app, vpn_service, bridge)
+    namespace.update(netfilter_nat_read=netfilter, selected_bridge_masquerade=masquerade)
+    if snapshot(app, service, expected) != original:
+        raise NetworkFailure('network_changed')
+    result = dict(envelope(app, service, expected, network, pool, vpn_service, host, provider),
+        observed_build_sha=expected, bridge=bridge, host=host_result, firewall=firewall, namespace=namespace,
+        overlap=network_inventory.overlap(original['networks'], bridge, original['host'], pool),
+        udp_ports=network_host.udp_ports(app, vpn_service, original['bindings'], original['listeners']),
+        observed_at=datetime.datetime.now(datetime.timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ'))
+    return validate(result, app, service, expected, network, pool, vpn_service, host, provider)
+
+
+def main():
+    arguments = (sys.argv[1:] + [''] * 8)[:8]
+    try:
+        result = collect(*arguments)
+    except Exception as error:
+        result = envelope(*arguments, failure=error.code if isinstance(error, NetworkFailure) else 'unclassified')
+    print(json.dumps(result, separators=(',', ':')))
+    return 0 if result['ok'] else 1
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

package/backend-action/runtime_projection.py

@@ -3,7 +3,7 @@ import math
 import re
 
 SCHEMA = 'gowalk-cicd/backend-runtime-diagnostics.v1'
-READER_VERSION = '1.0.191'
+READER_VERSION = '1.0.193'
 PROJECT = r'[a-z0-9][a-z0-9-]{0,79}'
 SERVICE = r'[a-z0-9][a-z0-9_-]{0,63}'
 SHA = r'[a-f0-9]{40}'

package/backend-action/ssh_gate.py

@@ -80,6 +80,8 @@ def authorize(owner, project, policy, may_claim):
 
 
 def helper_command(words):
+    if words[:2] == ['gowalk-backend', 'network-diagnostics']:
+        return network_command(words)
     if len(words) == 5 and words[:2] == ['gowalk-backend', 'runtime-diagnostics']:
         from runtime_projection import RuntimeFailure, scope
         try:
@@ -114,6 +116,17 @@ def helper_command(words):
     raise ValueError('ssh_operation_refused')
 
 
+def network_command(words):
+    from network_projection import NetworkFailure, scope
+    if len(words) != 10:
+        raise ValueError('ssh_arguments_refused')
+    try:
+        scope(*words[2:])
+    except NetworkFailure:
+        raise ValueError('ssh_arguments_refused') from None
+    return words[2], False, [sys.executable, str(HELPERS / 'network_readback.py'), *words[2:]]
+
+
 def transfer_command(words):
     if len(words) == 3 and words[:2] == ['mkdir', '-p']:
         project, path = scoped_path(words[2])

package/docs/BACKEND_SSH_GATE.md

@@ -43,6 +43,7 @@ The entry permits only:
 - the standard private runtime environment and edge-input receive envelopes;
 - the standard backend deploy invocation, redirected to the host-owned released helper;
 - the standard bounded identity-diagnostic invocation, also redirected to the released helper;
+- `gowalk-backend network-diagnostics` with fixed owned project, API build, bridge key and namespace-only VPN pool;
 - `gowalk-backend native-deploy <project>` for an existing [root-profiled native service](BACKEND_NATIVE.md).
 
 It refuses arbitrary shell commands, interactive shells, rsync sender/download operations, traversal,
@@ -89,6 +90,59 @@ malformed result refuses proof. A replay is another read and makes no mutation.
 records never establish database ownership or resources, and an absent source `db` container alone proves no
 shared-database substitution.
 
+## Owned bridge and VPN prerequisite readback
+
+`operation: network-diagnostics` is a read-only operation. The network allocator remains retired.
+Select `diagnostic-service` (the existing API), `diagnostic-network` (the existing Compose bridge key,
+default `default`), `diagnostic-vpn-service` (default `vpn`), `expected-build-sha`, and `diagnostic-pool`:
+a strict RFC1918 IPv4 `/24` proposed only for the VPN container namespace. It creates no address reservation,
+network, route, firewall rule, container, certificate or service. Do not use this pool as Compose IPAM.
+The generated workflow transports `diagnostic-build-sha` separately so a workflow-only commit can inspect
+the API build actually deployed, rather than claiming its own checkout SHA is running.
+
+The existing pinned CI identity sends only this fixed command:
+
+```text
+gowalk-backend network-diagnostics <project> <api-service> <deployed-SHA> <bridge-key> <pool> <vpn-service> <bound-host> <provider>
+```
+
+The trusted gate checks existing panel/project ownership and the global freeze, then invokes only its own
+released `network_readback.py`. It accepts no uploaded Python or app-mirror helper. Updating an app action
+alone cannot install this host operation: install the integrity-verified published runtime first. A missing
+host reader returns `network_reader_unavailable` with no host reader version; it is not a network verdict.
+
+The closed `gowalk-cicd/backend-network-diagnostics.v3` result is retained as
+`backend-network-diagnostics-<job>-<attempt>/result.json`. `ok: true` means the bounded read completed;
+it never means a VPN is provisioned, traffic is reachable, a pool is globally unused or a tunnel works.
+The reader binds the existing API's `BUILD_SHA`, checks its exact project/service/directory labels, and
+rechecks application identity, selected network inventory, host addresses/routes, Docker UDP bindings and
+socket observations before returning. A changed or ambiguous observation refuses the result.
+
+- `bridge` reports only the selected app bridge's actual network ID/name, ownership key, interface and IPAM.
+- `overlap` distinguishes selected-bridge foreign/host overlaps and proposed-pool selected/foreign/host
+  overlaps. Default-gateway destinations remain `unverified`; route snapshots cannot prove remote routes absent.
+- `udp_ports` classifies fixed UDP ports `500` and `4500` as `free`, exact `app_vpn`, `foreign` or `unknown`.
+  Reuse requires the exact app/vpn-service/directory binding. A host listener not attributable to Docker's
+  proxy stays unknown. This is a timestamped observation, not a port reservation; actual deployment can race.
+- `host.binding` requires the bound host's IPv4 address(es) to match local host addresses. Optional
+  `diagnostic-provider: digitalocean` corroborates fixed metadata with those live interfaces. Metadata
+  unavailable/unverified states remain explicit; metadata does not establish VPC, firewall or routing authority.
+- `namespace` reports local rootful Linux Docker, existing host forwarding, read-only XFRM/netfilter
+  availability and the selected bridge's observed masquerade rule. Existing VPN settings are observed only
+  for this app's exact service. `isolated_net_admin` requires that bridge, no privileged mode, dropping ALL,
+  only NET_ADMIN plus optional NET_BIND_SERVICE/CHOWN/SETUID/SETGID for bootstrap and privilege dropping,
+  and namespace-only forwarding/redirect settings. This observes grants, not that a daemon actually dropped privileges.
+  An absent VPN reports `absent`; these observations do not test creating a namespace or applying capabilities.
+- `firewall` reports observed INPUT/FORWARD policies and explicit UDP ACCEPT rules. Effective ingress
+  remains `unverified`: chained rules, nftables and upstream/provider firewalls need actual external traffic proof.
+
+Foreign network ownership/configuration, process identities, raw firewall rules, environment values and
+private bindings never leave the host. Foreign subnet data is used privately only to calculate overlap flags.
+The reader executes no container code, reads no logs and contacts no provider management API.
+No retry, downgrade, unrestricted SSH or historical inventory can replace a refused current read.
+Preserve bridge and database identities, assess the observations within their stated scope, then separately
+verify the actual namespaced gateway configuration, IKEv2 negotiation and encrypted forwarded traffic.
+
 ## Install a published host runtime
 
 Use the published package's `backend-action/install_runtime.py` with its npm archive, the registry's exact
@@ -96,8 +150,8 @@ Use the published package's `backend-action/install_runtime.py` with its npm arc
 For example, after transferring those verified public files to task-owned host scratch:
 
 ```sh
-python3 install_runtime.py --archive gowalk-cicd-1.0.191.tgz --integrity "$PACKAGE_INTEGRITY" \
-  --version 1.0.191 --owner robot --owner vpnrobot
+python3 install_runtime.py --archive gowalk-cicd-1.0.192.tgz --integrity "$PACKAGE_INTEGRITY" \
+  --version 1.0.192 --owner robot --owner vpnrobot
 ```
 
 The root-only installer verifies integrity/name/version again, installs only package-owned backend helpers under
@@ -105,6 +159,7 @@ The root-only installer verifies integrity/name/version again, installs only pac
 `/root/.ssh/authorized_keys`. It refuses missing/duplicate owners, nonrestricted entries, untrusted paths and
 changed existing release bytes; it never provisions keys or changes another entry. Exact replay verifies the
 release and leaves keys unchanged. A fixed receipt confirms the version and owners without key contents.
+The established `/usr/bin/python3 -B` spelling is accepted and preserves `-B`; other interpreter flags refuse.
 It changes no app source, runtime profile, container, database, service timer or deployment freeze. Preserve the
 previous release directory; this is ordinary released-helper installation, not app-state recovery.
 Verify a fresh scoped readback through each owner and keep that receipt with the exact npm integrity and release.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gowalk-cicd",
-  "version": "1.0.191",
+  "version": "1.0.193",
   "description": "Zero-config GitHub Actions delivery for iOS TestFlight and Android Google Play.",
   "type": "module",
   "bin": {

package/templates/deploy-backend.yml

@@ -20,13 +20,38 @@ on:
     inputs:
       operation:
         type: choice
-        description: Deploy or read scoped identity diagnostics without changing the running app
+        description: Deploy or read scoped diagnostics without changing the running app
         default: deploy
-        options: [deploy, identity-diagnostics]
+        options: [deploy, identity-diagnostics, network-diagnostics]
       diagnostic-since:
         type: string
         description: For diagnostics, UTC YYYY-MM-DDTHH:MM:SSZ within the previous 24 hours
         required: false
+      diagnostic-service:
+        type: string
+        description: Existing API Compose service for network diagnostics
+        default: api
+      diagnostic-build-sha:
+        type: string
+        description: Exact currently deployed API SHA for network diagnostics
+        required: false
+      diagnostic-pool:
+        type: string
+        description: Proposed namespace-only VPN private IPv4 /24
+        required: false
+      diagnostic-network:
+        type: string
+        description: Existing owned Compose bridge key
+        default: default
+      diagnostic-vpn-service:
+        type: string
+        description: Exact app service whose UDP bindings may be reused
+        default: vpn
+      diagnostic-provider:
+        type: choice
+        description: Optional fixed metadata corroboration
+        options: [none, digitalocean]
+        default: none
 
 permissions:
   contents: read
@@ -58,6 +83,11 @@ jobs:
         with:
           operation: ${{ inputs.operation || 'deploy' }}
           diagnostic-since: ${{ inputs.diagnostic-since }}
+          diagnostic-service: ${{ inputs.diagnostic-service || 'api' }}
+          diagnostic-network: ${{ inputs.diagnostic-network || 'default' }}
+          diagnostic-pool: ${{ inputs.diagnostic-pool }}
+          diagnostic-vpn-service: ${{ inputs.diagnostic-vpn-service || 'vpn' }}
+          diagnostic-provider: ${{ inputs.diagnostic-provider || 'none' }}
           ssh-key: ${{ secrets.BACKEND_DEPLOY_SSH_KEY }}
           known-hosts: ${{ vars.BACKEND_DEPLOY_KNOWN_HOSTS }}
           host: ${{ vars.BACKEND_DEPLOY_HOST }}
@@ -68,7 +98,9 @@ jobs:
           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 || '' }}
+          expected-build-sha: >-
+            ${{ (inputs.operation == 'network-diagnostics' && inputs.diagnostic-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 }}