@finalai/final-agent-provider 0.3.4 → 0.4.1

package/dist/modules/sandboxes/egress-bootstrap.mjs

@@ -0,0 +1,928 @@
+const workspaceEgressBootstrap = String.raw`import collections, errno, fcntl, hashlib, ipaddress, json, os, pathlib, platform, re, shutil, signal, shlex, socket, stat, struct, subprocess, sys, tempfile, threading, time, urllib.parse, uuid
+
+ROOT = pathlib.Path('/run/final-workspace-egress')
+PERSISTENT = pathlib.Path('/var/lib/final-workspace-egress')
+RESOLVER = pathlib.Path('/etc/resolv.conf')
+HOSTS = pathlib.Path('/etc/hosts')
+CHAIN = 'FINAL-EGRESS'
+REPLY = 'FINAL-EGRESS-REPLY'
+FORWARD = 'FINAL-EGRESS-FWD'
+NAT = 'FINAL-EGRESS-NAT'
+MARK = '0x80000/0xff0000'
+os.environ['PATH'] = '/usr/sbin:/usr/bin:/sbin:/bin'
+os.environ.pop('SSL_CERT_FILE', None)
+os.environ.pop('SSL_CERT_DIR', None)
+# Prime autoload before choosing families; later kernel enablement requires reinitialization.
+try: socket.socket(socket.AF_INET6, socket.SOCK_DGRAM).close()
+except OSError as failure:
+    if failure.errno not in (errno.EAFNOSUPPORT, errno.EPROTONOSUPPORT, errno.EPERM, errno.EACCES): raise
+FAMILIES = ('iptables', 'ip6tables') if pathlib.Path('/proc/net/if_inet6').exists() else ('iptables',)
+
+class WorkspaceConflictError(RuntimeError):
+    pass
+
+class PrerequisiteError(RuntimeError):
+    pass
+
+class DenialUnavailableError(RuntimeError):
+    pass
+
+class EnrollmentLostError(RuntimeError):
+    pass
+
+
+def command(*args, check=True, timeout=25):
+    if args[0] in ('iptables', 'ip6tables') and '--version' not in args: args = (args[0], '-w', '5', *args[1:])
+    result = subprocess.run(args, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.PIPE, timeout=timeout)
+    if check and result.returncode != 0:
+        raise RuntimeError('Workspace networking command failed: ' + ' '.join(args[:4]))
+    return result
+
+def atomic(path, value, binary=False, mode=0o600):
+    staged = None
+    try:
+        with tempfile.NamedTemporaryFile(dir=path.parent, delete=False) as out:
+            staged = pathlib.Path(out.name)
+            out.write(value if binary else json.dumps(value).encode())
+            out.flush(); os.fsync(out.fileno())
+        os.chmod(staged, mode)
+        os.replace(staged, path)
+        directory = os.open(path.parent, os.O_RDONLY | os.O_DIRECTORY)
+        try: os.fsync(directory)
+        finally: os.close(directory)
+    finally:
+        if staged is not None: staged.unlink(missing_ok=True)
+
+def managed_text(path, content):
+    data = content.encode()
+    try: atomic(path, data, binary=True, mode=0o644)
+    except OSError as failure:
+        if failure.errno != errno.EBUSY: raise
+        # Docker bind-mounted files cannot be replaced; never follow a raced-in symlink.
+        pending = PERSISTENT / 'resolver-write-pending.json' if path == RESOLVER else None
+        if pending is not None: atomic(pending, True)
+        fd = os.open(path, os.O_WRONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+        with os.fdopen(fd, 'wb') as out:
+            if not stat.S_ISREG(os.fstat(out.fileno()).st_mode): raise RuntimeError('Managed network file must be regular')
+            os.ftruncate(out.fileno(), 0)
+            out.write(data); out.flush(); os.fsync(out.fileno())
+        if pending is not None: pending.unlink(missing_ok=True)
+
+def load(path, default=None):
+    try:
+        return json.loads(path.read_text())
+    except FileNotFoundError:
+        return default
+
+def prerequisite(action):
+    if sys.version_info < (3, 8):
+        raise PrerequisiteError('Device egress requires Python 3.8 or newer')
+    if sys.platform != 'linux' or os.geteuid() != 0:
+        raise PrerequisiteError('Device egress requires an isolated Linux workspace with privileged networking access')
+    ROOT.mkdir(mode=0o700, exist_ok=True)
+    if ROOT.is_symlink() or ROOT.stat().st_uid != 0:
+        raise RuntimeError('Workspace egress state must be a root-owned directory')
+    ROOT.chmod(0o700)
+    direct = not load(ROOT / 'config.json') or (load(ROOT / 'config.json', {}).get('mode') == 'direct' and load(ROOT / 'status.json', {}).get('mode') == 'direct')
+    if action in ('status', 'artifact', 'claim', 'unlock') or (action == 'disable' and (direct or load(ROOT / 'config.json', {}).get('noNetworkChanges') is True)): return
+    if action in ('configure', 'renew') and not pathlib.Path('/dev/net/tun').exists():
+        raise PrerequisiteError('This sandbox provider does not expose /dev/net/tun')
+    command('ip', '-V')
+    for family in FAMILIES:
+        command(family, '--version'); command(family + '-restore', '--version')
+
+BOOT_ID = pathlib.Path('/proc/sys/kernel/random/boot_id').read_text().strip()
+
+def existing_control_replies():
+    saved = load(ROOT / 'control-replies.json')
+    sockets = []
+    for table in ('tcp', 'tcp6'):
+        def address(value):
+            host, port = value.split(':')
+            raw = bytes.fromhex(host)
+            raw = b''.join(raw[i:i+4][::-1] for i in range(0, len(raw), 4))
+            ip = ipaddress.ip_address(raw)
+            if isinstance(ip, ipaddress.IPv6Address) and ip.ipv4_mapped is not None: ip = ip.ipv4_mapped
+            return str(ip), int(port, 16)
+        source = pathlib.Path('/proc/net/' + table)
+        if not source.exists(): continue
+        for line in source.read_text().splitlines()[1:]:
+            columns = line.split()
+            if columns[3] in ('01', '0A'): sockets.append((address(columns[1]), address(columns[2]), columns[3], int(columns[7])))
+    addresses = json.loads(command('ip', '-j', 'addr', 'show').stdout)
+    local_addresses = {ipaddress.ip_address(address['local']) for interface in addresses for address in interface.get('addr_info', [])}
+    bridge_networks = [ipaddress.ip_network(network) for _, network in local_bridges()]
+    listeners = [local for local, remote, state, uid in sockets if state == '0A' and not ipaddress.ip_address(local[0]).is_loopback]
+    replies = []
+    for local, remote, state, uid in sockets:
+        # Only privileged provider sockets may use the pre-conntrack compatibility exception.
+        remote_ip = ipaddress.ip_address(remote[0])
+        if uid != 0 or state != '01' or remote_ip.is_loopback or remote_ip in local_addresses: continue
+        if any(remote_ip.version == network.version and remote_ip in network for network in bridge_networks): continue
+        if any(port == local[1] and (ipaddress.ip_address(host).is_unspecified or host == local[0]) for host, port in listeners):
+            replies.append({'source': local[0], 'sourcePort': local[1], 'destination': remote[0], 'destinationPort': remote[1], 'uid': 0})
+    if saved is not None and any(reply.get('uid') != 0 for reply in saved): saved = None
+    capture_overflow = saved is None and len(replies) > 128
+    if saved is not None: replies = saved
+    server_ports = [{'source': host, 'sourcePort': port} for host, port in listeners]
+    for prior in load(ROOT / 'control-listeners.json', []):
+        if any(local[1] == prior['sourcePort'] and state == '01' for local, remote, state, uid in sockets): server_ports.append(prior)
+    # A dual-stack listener appears in tcp6 even when the accepted transport uses IPv4.
+    server_ports += [{'source': reply['source'], 'sourcePort': reply['sourcePort']} for reply in replies]
+    server_ports = [dict(source=host, sourcePort=port) for host, port in sorted({(item['source'], item['sourcePort']) for item in server_ports})]
+    prior = load(ROOT / 'control-listeners.json', [])
+    privileged = {local for local, remote, state, uid in sockets if state == '0A' and uid == 0}
+    server_ports.sort(key=lambda item: (item not in prior, (item['source'], item['sourcePort']) not in privileged))
+    atomic(ROOT / 'control-listeners.json', server_ports[:256])
+    if len(server_ports) > 256:
+        atomic(ROOT / 'listener-limit.json', {'limit': 256, 'observed': len(server_ports)})
+    else: (ROOT / 'listener-limit.json').unlink(missing_ok=True)
+    if capture_overflow: raise RuntimeError('Too many existing inbound control connections')
+    atomic(ROOT / 'control-replies.json', replies)
+    return replies
+
+def local_bridges():
+    result = []
+    # Minimal VM kernels can reject a type-filtered dump; ordinary link dumps remain portable.
+    links = json.loads(command('ip', '-j', '-d', 'link', 'show').stdout)
+    by_name = {link['ifname']: link for link in links}
+    uplinks = set()
+    for route in json.loads(command('ip', '-j', '-4', 'route', 'show', 'table', 'all').stdout):
+        if route.get('dst') == 'default' or route.get('gateway') is not None or route.get('nexthops'):
+            uplinks.add(route.get('dev'))
+            uplinks.update(hop.get('dev') for hop in route.get('nexthops', []))
+    for link in links:
+        if link.get('linkinfo', {}).get('info_kind') != 'bridge': continue
+        try: members = list((pathlib.Path('/sys/class/net') / link['ifname'] / 'brif').iterdir())
+        except FileNotFoundError: continue
+        if link['ifname'] in uplinks or any(member.name in uplinks or by_name.get(member.name, {}).get('linkinfo', {}).get('info_kind') != 'veth' for member in members): continue
+        name = link['ifname']
+        if not re.fullmatch(r'[A-Za-z0-9_.-]{1,15}', name): raise RuntimeError('Unsupported local bridge name')
+        for interface in json.loads(command('ip', '-j', '-4', 'addr', 'show', 'dev', name).stdout):
+            for address in interface.get('addr_info', []):
+                if address.get('family') == 'inet': result.append((name, str(ipaddress.ip_network(address['local'] + '/' + str(address['prefixlen']), strict=False))))
+    return sorted(result)
+
+def install_guard(allow_tunnel=False, closed=False):
+    if closed: allow_tunnel = False
+    replies = [reply for reply in load(ROOT / 'control-replies.json', []) if reply.get('uid') == 0] if closed else existing_control_replies()
+    bridges = [] if closed else local_bridges()
+    try: listeners = load(ROOT / 'control-listeners.json', [])
+    except Exception:
+        if not closed: raise
+        listeners = []
+    if closed: tunnel_addresses = load(ROOT / 'tunnel-addresses.json', [])
+    else:
+        tunnel = command('ip', '-j', 'addr', 'show', 'dev', 'final-egress0', check=False)
+        tunnel_addresses = [str(ipaddress.ip_address(address['local'])) for interface in json.loads(tunnel.stdout or b'[]') for address in interface.get('addr_info', [])]
+        atomic(ROOT / 'tunnel-addresses.json', tunnel_addresses)
+    for family in FAMILIES:
+        rules = ['*filter', ':' + CHAIN + ' - [0:0]', '-F ' + CHAIN]
+        # Block namespace-local DNS stubs that would otherwise resolve on the provider's network.
+        for proto in ('tcp', 'udp'):
+            rules.append('-A ' + CHAIN + ' -o lo -p ' + proto + ' --dport 53 -j REJECT')
+        if family == 'iptables':
+            rules.append('-A ' + CHAIN + ' -d 127.0.0.11 -j REJECT')
+            rules.append('-A ' + CHAIN + ' -d 100.100.100.100 -j REJECT')
+        rules += ['-A ' + CHAIN + ' -o lo -j ACCEPT', '-A ' + CHAIN + ' -m mark --mark ' + MARK + ' -m owner --uid-owner 0 -j ACCEPT', '-A ' + CHAIN + ' -m mark --mark ' + MARK + ' -m conntrack --ctdir REPLY -j ACCEPT']
+        if family == 'ip6tables':
+            for kind in (133, 134, 135, 136):
+                rules += ['-A ' + CHAIN + ' -p ipv6-icmp --icmpv6-type ' + str(kind) + ' -m owner --uid-owner 1-4294967294 -j REJECT',
+                          '-A ' + CHAIN + ' -p ipv6-icmp --icmpv6-type ' + str(kind) + ' -j ACCEPT']
+        if family == 'iptables':
+            for name, network in bridges: rules.append('-A ' + CHAIN + ' -o ' + name + ' -d ' + network + ' -j ACCEPT')
+        if family == 'iptables' and allow_tunnel:
+            rules.append('-A ' + CHAIN + ' -o final-egress0 -j ACCEPT')
+        if closed:
+            for reply in replies:
+                if (':' in reply['source']) != (family == 'ip6tables'): continue
+                rules.append('-A ' + CHAIN + ' -p tcp -s ' + reply['source'] + ' --sport ' + str(reply['sourcePort']) + ' -d ' + reply['destination'] + ' --dport ' + str(reply['destinationPort']) + ' --tcp-flags SYN,RST,ACK ACK -j ACCEPT')
+        rules += ['-A ' + CHAIN + ' -j REJECT', 'COMMIT', '*mangle', ':' + REPLY + ' - [0:0]', '-F ' + REPLY,
+                  # Docker rewrites its DNS stub's port in nat/OUTPUT; block before that translation.
+                  '-A ' + REPLY + ' -o lo -p tcp --dport 53 -j DROP',
+                  '-A ' + REPLY + ' -o lo -p udp --dport 53 -j DROP',
+                  ]
+        if family == 'iptables': rules.append('-A ' + REPLY + ' -d 127.0.0.11 -j DROP')
+        # mangle/OUTPUT sees the initial exit route even for physical provider replies.
+        # Exclude only the actual tunnel source addresses before marking server replies.
+        for address in tunnel_addresses:
+            if (':' in address) == (family == 'ip6tables'):
+                rules.append('-A ' + REPLY + ' -s ' + address + ' -j RETURN')
+        # Minimal provider kernels omit connmark. Reserve the existing server ports for TCP replies;
+        # an untracked outgoing client's ephemeral port cannot obtain this exception.
+        for listener in listeners:
+            host = listener['source']
+            address = ipaddress.ip_address(host)
+            if (':' in host) != (family == 'ip6tables') and not (family == 'iptables' and address.version == 6 and address.is_unspecified): continue
+            source = '' if ipaddress.ip_address(host).is_unspecified else ' -s ' + host
+            rules.append('-A ' + REPLY + ' -p tcp' + source + ' --sport ' + str(listener['sourcePort']) +
+                         ' -m conntrack --ctdir REPLY --ctorigdstport ' + str(listener['sourcePort']) + ' -j MARK --set-xmark ' + MARK)
+        # Conntrack can load after a provider's long-lived inbound RPC already opened (E2B envd).
+        # Preserve only ACKs on those accepted server sockets, never a new outbound SYN.
+        for reply in replies:
+            if (':' in reply['source']) != (family == 'ip6tables'): continue
+            rules.append('-A ' + REPLY + ' -p tcp -s ' + reply['source'] + ' --sport ' + str(reply['sourcePort']) +
+                         ' -d ' + reply['destination'] + ' --dport ' + str(reply['destinationPort']) +
+                         ' --tcp-flags SYN,RST,ACK ACK -j MARK --set-xmark ' + MARK)
+        rules.append('COMMIT')
+        # Docker can prepend filter/FORWARD accepts; mangle runs before that table.
+        rules += ['*mangle', ':' + FORWARD + ' - [0:0]', '-F ' + FORWARD]
+        if family == 'iptables': rules.append('-A ' + FORWARD + ' -d 100.100.100.100 -j DROP')
+        if family == 'iptables':
+            for name, network in bridges:
+                for ingress, _ in bridges: rules.append('-A ' + FORWARD + ' -i ' + ingress + ' -o ' + name + ' -d ' + network + ' -j RETURN')
+        if family == 'iptables' and allow_tunnel:
+            for name, network in bridges:
+                rules += ['-A ' + FORWARD + ' -i ' + name + ' -s ' + network + ' -o final-egress0 -j RETURN',
+                          '-A ' + FORWARD + ' -i final-egress0 -o ' + name + ' -d ' + network + ' -m conntrack --ctstate ESTABLISHED,RELATED -j RETURN']
+        rules += ['-A ' + FORWARD + ' -j DROP', 'COMMIT']
+        rules += ['*filter', ':' + FORWARD + ' - [0:0]', '-F ' + FORWARD]
+        if family == 'iptables': rules.append('-A ' + FORWARD + ' -d 100.100.100.100 -j DROP')
+        if family == 'iptables':
+            for name, network in bridges:
+                for ingress, _ in bridges: rules.append('-A ' + FORWARD + ' -i ' + ingress + ' -o ' + name + ' -d ' + network + ' -j RETURN')
+        if family == 'iptables' and allow_tunnel:
+            for name, network in bridges:
+                rules += ['-A ' + FORWARD + ' -i ' + name + ' -s ' + network + ' -o final-egress0 -j ACCEPT',
+                          '-A ' + FORWARD + ' -i final-egress0 -o ' + name + ' -d ' + network + ' -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT']
+        rules += ['-A ' + FORWARD + ' -j REJECT', 'COMMIT']
+        if family == 'iptables':
+            rules += ['*nat', ':' + NAT + ' - [0:0]', '-F ' + NAT]
+            for name, network in bridges:
+                rules.append('-A ' + NAT + ' -s ' + network + ' -o final-egress0 -j MASQUERADE')
+            rules.append('COMMIT')
+        installed = subprocess.run([family + '-restore', '-w', '5', '--noflush'], timeout=25, input=('\n'.join(rules) + '\n').encode(), stdout=subprocess.DEVNULL, stderr=subprocess.PIPE)
+        if installed.returncode: raise RuntimeError(family + ' firewall installation failed: ' + installed.stderr.decode(errors='replace')[:800])
+        hooks = [('mangle', 'OUTPUT', REPLY), ('mangle', 'FORWARD', FORWARD), ('filter', 'OUTPUT', CHAIN), ('filter', 'FORWARD', FORWARD)]
+        if family == 'iptables': hooks.append(('nat', 'POSTROUTING', NAT))
+        for table, hook, chain in hooks:
+            if command(family, '-t', table, '-C', hook, '-j', chain, check=False).returncode != 0:
+                command(family, '-t', table, '-I', hook, '1', '-j', chain)
+    # Reverse-NAT replies from TUN must return to a nested bridge rather than the exit default route.
+    if allow_tunnel:
+        while command('ip', '-4', 'rule', 'del', 'pref', '5210', 'iif', 'final-egress0', 'lookup', 'main', 'protocol', '242', check=False).returncode == 0: pass
+        existing = command('ip', '-4', 'rule', 'show').stdout.decode()
+        for name, network in bridges:
+            if not any('to ' + value + ' iif final-egress0 lookup main' in existing for value in (network, network[:-3] if network.endswith('/32') else network)):
+                command('ip', '-4', 'rule', 'add', 'pref', '5210', 'iif', 'final-egress0', 'to', network, 'lookup', 'main', 'protocol', '242')
+    existing_rules = command('ip', '-4', 'rule', 'show').stdout.decode() if bridges else ''
+    for name, network in bridges:
+        if not any('to ' + value + ' lookup main' in existing_rules for value in (network, network[:-3] if network.endswith('/32') else network)):
+            command('ip', '-4', 'rule', 'add', 'pref', '5210', 'to', network, 'lookup', 'main', 'protocol', '242')
+
+def chain_hooked(family, table, hook, chain):
+    result = command(family, '-t', table, '-S', check=False)
+    if result.returncode != 0:
+        if table != 'filter' and result.returncode == 3 and b'Table does not exist' in result.stderr: return False
+        raise RuntimeError('Cannot inspect namespace firewall hooks')
+    return ('-A ' + hook + ' -j ' + chain) in result.stdout.decode().splitlines()
+
+def denial_present():
+    for family in FAMILIES:
+        for hook, chain in [('OUTPUT', CHAIN), ('FORWARD', FORWARD)]:
+            if not chain_hooked(family, 'filter', hook, chain): return False
+            rules = command(family, '-t', 'filter', '-S', chain, check=False)
+            if rules.returncode or not any(shlex.split(line)[:4] in (['-A', chain, '-j', 'DROP'], ['-A', chain, '-j', 'REJECT']) for line in rules.stdout.decode().splitlines()): return False
+    return True
+
+def restoration_pending():
+    if load(ROOT / 'config.json', {}).get('mode') == 'error' or load(ROOT / 'status.json', {}).get('mode') == 'error': return True
+    if (PERSISTENT / 'hosts.original').exists() or (PERSISTENT / 'resolver.original').exists() or (not HOSTS.is_symlink() and HOSTS.exists() and '# final-workspace-egress' in HOSTS.read_text()): return True
+    if RESOLVER.exists() and RESOLVER.read_bytes().startswith(b'# Final workspace egress\n'): return True
+    if not all(shutil.which(family) for family in FAMILIES):
+        return (PERSISTENT / 'identity.json').exists() or load(ROOT / 'config.json', {}).get('mode', 'direct') != 'direct'
+    try:
+        return any(chain_hooked(family, table, hook, chain)
+            for family in FAMILIES
+            for table, hook, chain in [('filter', 'OUTPUT', CHAIN), ('filter', 'FORWARD', FORWARD), ('mangle', 'OUTPUT', REPLY), ('mangle', 'FORWARD', FORWARD)] + ([('nat', 'POSTROUTING', NAT)] if family == 'iptables' else []))
+    except RuntimeError:
+        # Never-managed images need no repair when their provider denies firewall inspection.
+        if not (PERSISTENT / 'identity.json').exists() and load(ROOT / 'config.json', {}).get('mode', 'direct') == 'direct': return False
+        raise
+
+def restore():
+    transport_hosts({})
+    original = PERSISTENT / 'resolver.original'
+    if not original.exists() and (load(PERSISTENT / 'resolver-write-pending.json', False) or (RESOLVER.exists() and RESOLVER.read_bytes().startswith(b'# Final workspace egress\n'))):
+        raise RuntimeError('Original workspace resolver backup is missing; repair the provider resolver before Disable')
+    if original.exists():
+        current = RESOLVER
+        if load(PERSISTENT / 'resolver-write-pending.json', False) or not current.exists() or current.read_text().startswith('# Final workspace egress\n'):
+            link = load(PERSISTENT / 'resolver-link.json')
+            if link is None:
+                if load(PERSISTENT / 'resolver-absent.json', False): current.unlink(missing_ok=True)
+                else:
+                    if current.is_symlink(): current.unlink()
+                    managed_text(current, original.read_text())
+            else:
+                staged = current.parent / ('.final-egress-resolver-' + uuid.uuid4().hex)
+                try:
+                    os.symlink(link['target'], staged); os.replace(staged, current)
+                finally: staged.unlink(missing_ok=True)
+        (PERSISTENT / 'resolver-write-pending.json').unlink(missing_ok=True)
+        original.unlink()
+        (PERSISTENT / 'resolver-link.json').unlink(missing_ok=True)
+        (PERSISTENT / 'resolver-absent.json').unlink(missing_ok=True)
+    for family in FAMILIES:
+        hooks = [('filter', 'OUTPUT', CHAIN), ('mangle', 'OUTPUT', REPLY), ('mangle', 'FORWARD', FORWARD), ('filter', 'FORWARD', FORWARD)]
+        if family == 'iptables': hooks.append(('nat', 'POSTROUTING', NAT))
+        for table, hook, chain in hooks:
+            while chain_hooked(family, table, hook, chain):
+                command(family, '-t', table, '-D', hook, '-j', chain)
+            command(family, '-t', table, '-F', chain, check=False)
+            command(family, '-t', table, '-X', chain, check=False)
+    while command('ip', '-4', 'rule', 'del', 'pref', '5210', 'protocol', '242', 'lookup', 'main', check=False).returncode == 0: pass
+    for saved in ('control-replies.json', 'control-listeners.json', 'listener-limit.json', 'tunnel-addresses.json'):
+        (ROOT / saved).unlink(missing_ok=True)
+    (PERSISTENT / 'identity.json').unlink(missing_ok=True)
+    (PERSISTENT / 'intent.json').unlink(missing_ok=True)
+
+def validated_resolvers(addresses):
+    if not isinstance(addresses, list) or not addresses or len(addresses) > 3:
+        raise RuntimeError('One to three IPv4 DNS resolvers are required')
+    addresses = [str(ipaddress.IPv4Address(address)) for address in addresses]
+    if len(set(addresses)) != len(addresses) or any(int(address.split('.')[0]) in (0, 127) or int(address.split('.')[0]) >= 224 or address == '100.100.100.100' for address in addresses):
+        raise RuntimeError('Device DNS resolvers must be unique reachable unicast addresses')
+    return addresses
+
+def resolver(addresses):
+    addresses = validated_resolvers(addresses)
+    source = RESOLVER
+    if not (PERSISTENT / 'resolver.original').exists():
+        if source.exists() and source.read_bytes().startswith(b'# Final workspace egress\n'):
+            raise RuntimeError('Original workspace resolver backup is missing; repair the provider resolver')
+        absent = not source.exists() and not source.is_symlink()
+        try: original = source.read_bytes()
+        except FileNotFoundError: original = b''
+        atomic(PERSISTENT / 'resolver-absent.json', absent)
+        if source.is_symlink(): atomic(PERSISTENT / 'resolver-link.json', {'target': os.readlink(source)})
+        else: (PERSISTENT / 'resolver-link.json').unlink(missing_ok=True)
+        atomic(PERSISTENT / 'resolver.original', original, binary=True)
+    content = '# Final workspace egress\n' + ''.join('nameserver ' + address + '\n' for address in addresses) + 'options timeout:2 attempts:2\n'
+    if not source.is_symlink() and source.exists() and source.read_bytes() == content.encode(): return
+    managed_text(source, content)
+
+def transport_hosts(hosts):
+    original = PERSISTENT / 'hosts.original'
+    absent = PERSISTENT / 'hosts-absent.json'
+    if HOSTS.is_symlink():
+        if hosts: raise PrerequisiteError('Workspace egress requires a regular /etc/hosts file')
+        if original.exists():
+            if load(absent, False): HOSTS.unlink()
+            else: atomic(HOSTS, original.read_bytes(), binary=True, mode=0o644)
+            original.unlink(); absent.unlink(missing_ok=True)
+        return
+    if hosts and not original.exists():
+        atomic(absent, not HOSTS.exists())
+        atomic(original, HOSTS.read_bytes() if HOSTS.exists() else b'', binary=True)
+    if not HOSTS.exists() and not hosts:
+        if original.exists() and not load(absent, False): atomic(HOSTS, original.read_bytes(), binary=True, mode=0o644)
+        original.unlink(missing_ok=True); absent.unlink(missing_ok=True)
+        return
+    lines = HOSTS.read_text().splitlines() if HOSTS.exists() else []
+    lines = [line for line in lines if not line.endswith('# final-workspace-egress')]
+    for host, address in hosts.items():
+        if not host or any(c not in 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789.-' for c in host):
+            raise RuntimeError('Invalid egress transport hostname')
+        lines.append(str(ipaddress.IPv4Address(address)) + ' ' + host + ' # final-workspace-egress')
+    content = '\n'.join(lines) + '\n'
+    if not hosts and load(absent, False) and not lines: HOSTS.unlink(missing_ok=True)
+    elif not HOSTS.exists() or HOSTS.read_text() != content: managed_text(HOSTS, content)
+    if not hosts:
+        original.unlink(missing_ok=True); absent.unlink(missing_ok=True)
+
+def status(mode, config, **extra):
+    try: policy_routing = command('ip', '-4', 'rule', 'show', check=False).returncode == 0
+    except FileNotFoundError: policy_routing = False
+    result = {'mode': mode, 'leaseId': config.get('leaseId'), 'ownerUserId': config.get('ownerUserId'),
+              'workspaceId': config.get('workspaceId'), 'architecture': platform.machine(), 'policyRouting': policy_routing, 'expiresAtMs': config.get('expiresAtMs'), 'deviceId': None, 'path': None, **extra}
+    atomic(ROOT / 'status.json', result)
+    return result
+
+def controller_status(mode, config, **extra):
+    # A writer may await daemon shutdown while holding this lock; skip stale/busy publication.
+    with open(ROOT / 'request.lock', 'a') as requests:
+        try: fcntl.flock(requests, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError: return
+        saved = load(ROOT / 'config.json', {})
+        fields = ('mode', 'revision', 'leaseId', 'workspaceId', 'ownerUserId', 'expiresAtMs', 'state')
+        if any(saved.get(field) != config.get(field) for field in fields): return
+        return status(mode, config, **extra)
+
+def lease_id(value):
+    if not isinstance(value, str) or not value: raise RuntimeError('Missing workspace lease identifier')
+    return value
+
+def lease_state_name(value):
+    value = lease_id(value)
+    try: return str(uuid.UUID(value))
+    except ValueError: return 'opaque-' + hashlib.sha256(value.encode()).hexdigest()
+
+def helper_environment():
+    env = {'PATH': '/usr/sbin:/usr/bin:/sbin:/bin'}
+    env.update(FINAL_TAILSCALE_MANAGED='1', FINAL_DEVICE_PARENT_PID=str(os.getpid()), TS_NO_LOGS_NO_SUPPORT='true', TS_DEBUG_ENV_FILE='/dev/null', TS_LOGS_DIR=str(ROOT / 'logs'))
+    return env
+
+def cli(helper, sock, *args):
+    # CLI operations are managed children as well: closing their pipe stops them on controller death.
+    env = helper_environment()
+    errors = os.open(ROOT / 'last-control-error.log', os.O_WRONLY | os.O_CREAT | os.O_TRUNC | os.O_NOFOLLOW, 0o600)
+    try:
+        proc = subprocess.Popen([str(helper), 'final-cli', '--socket=' + str(sock), *args], stdin=subprocess.PIPE,
+                                stdout=subprocess.PIPE, stderr=errors, env=env)
+    finally: os.close(errors)
+    try:
+        proc.stdin.write(b'final-device-start\n'); proc.stdin.flush()
+        deadline = time.monotonic() + 20
+        output = bytearray()
+        os.set_blocking(proc.stdout.fileno(), False)
+        while proc.poll() is None:
+            chunk = proc.stdout.read(65536)
+            if chunk: output.extend(chunk)
+            if len(output) > 1024 * 1024 or time.monotonic() > deadline:
+                raise RuntimeError('Workspace egress control operation exceeded its limit: ' + args[0])
+            time.sleep(.01)
+        output.extend(proc.stdout.read() or b'')
+        if proc.returncode != 0:
+            detail = ': ' + bytes(output).decode(errors='replace')[:1000] if args[0] == 'ping' else ''
+            raise RuntimeError('Workspace egress control operation failed (' + args[0] + ')' + detail)
+        return bytes(output)
+    finally:
+        try: proc.stdin.close()
+        except BrokenPipeError: pass
+        if proc.poll() is None: proc.kill()
+        proc.wait()
+
+def stop(proc):
+    if proc is not None:
+        try: proc.stdin.close()
+        except BrokenPipeError: pass
+        try: proc.wait(timeout=2)
+        except subprocess.TimeoutExpired: proc.kill(); proc.wait()
+
+def minimal_guard():
+    failures = []
+    # Cached accepted sockets permit recovery even without conntrack or mangle.
+    try: replies = [reply for reply in load(ROOT / 'control-replies.json', []) if reply.get('uid') == 0]
+    except Exception: replies = []
+    for family in FAMILIES:
+        try:
+            for hook, chain in [('OUTPUT', CHAIN), ('FORWARD', FORWARD)]:
+                existing = command(family, '-t', 'filter', '-S', chain, check=False)
+                hooked = command(family, '-t', 'filter', '-C', hook, '-j', chain, check=False)
+                # Retain a successfully installed closed family and its control exceptions.
+                if existing.returncode == 0 and hooked.returncode == 0 and b'-o final-egress0' not in existing.stdout and any(shlex.split(line)[:4] in (['-A', chain, '-j', 'DROP'], ['-A', chain, '-j', 'REJECT']) for line in existing.stdout.decode().splitlines()): continue
+                rules = ['*filter', ':' + chain + ' - [0:0]', '-F ' + chain]
+                if hook == 'OUTPUT':
+                    for proto in ('tcp', 'udp'):
+                        rules.append('-A ' + chain + ' -o lo -p ' + proto + ' --dport 53 -j DROP')
+                    if family == 'iptables':
+                        rules += ['-A ' + chain + ' -d 127.0.0.11 -j DROP', '-A ' + chain + ' -d 100.100.100.100 -j DROP']
+                    rules.append('-A ' + chain + ' -o lo -j ACCEPT')
+                    if family == 'ip6tables':
+                        for kind in (133, 134, 135, 136):
+                            rules += ['-A ' + chain + ' -p ipv6-icmp --icmpv6-type ' + str(kind) + ' -m owner --uid-owner 1-4294967294 -j REJECT',
+                                      '-A ' + chain + ' -p ipv6-icmp --icmpv6-type ' + str(kind) + ' -j ACCEPT']
+                    for reply in replies:
+                        if (':' in reply['source']) != (family == 'ip6tables'): continue
+                        rules.append('-A ' + chain + ' -p tcp -s ' + reply['source'] + ' --sport ' + str(reply['sourcePort']) +
+                                     ' -d ' + reply['destination'] + ' --dport ' + str(reply['destinationPort']) +
+                                     ' --tcp-flags SYN,RST,ACK ACK -j ACCEPT')
+                rules += ['-A ' + chain + ' -j DROP', 'COMMIT']
+                result = subprocess.run([family + '-restore', '-w', '5', '--noflush'], input=('\n'.join(rules) + '\n').encode(), capture_output=True, timeout=25)
+                if result.returncode and family == 'ip6tables':
+                    # Without owner matching, deny IPv6 neighbor traffic too rather than leaving the family open.
+                    fallback = [rule for rule in rules if '-p ipv6-icmp ' not in rule]
+                    result = subprocess.run([family + '-restore', '-w', '5', '--noflush'], input=('\n'.join(fallback) + '\n').encode(), capture_output=True, timeout=25)
+                if result.returncode: raise RuntimeError('Atomic emergency denial failed for ' + family)
+                if hooked.returncode != 0: command(family, '-t', 'filter', '-I', hook, '1', '-j', chain)
+        except Exception as cause: failures.append(str(cause))
+    if failures: raise RuntimeError('Cannot install minimal namespace denial: ' + '; '.join(failures))
+
+def guard(allow_tunnel=False):
+    try: install_guard(allow_tunnel)
+    except Exception:
+        try: install_guard(closed=True)
+        except Exception:
+            try: minimal_guard()
+            except Exception as failure:
+                raise DenialUnavailableError('Workspace network denial could not be installed') from failure
+        raise
+
+def clear_identity():
+    for path in ROOT.glob('state-*'):
+        if path.is_file(): path.unlink()
+    (ROOT / 'enrollment.key').unlink(missing_ok=True)
+
+def stop_controller():
+    with open(ROOT / 'daemon.lock', 'a') as lock:
+        deadline = time.monotonic() + 5
+        signaled = None
+        while True:
+            pid = load(ROOT / 'controller.pid')
+            if isinstance(pid, int) and pid != signaled:
+                try:
+                    args = pathlib.Path('/proc/' + str(pid) + '/cmdline').read_bytes().split(bytes([0]))
+                    if str(ROOT / 'controller.py').encode() in args and b'run' in args:
+                        os.kill(pid, signal.SIGTERM); signaled = pid
+                except ProcessLookupError: pass
+                except FileNotFoundError: pass
+            try:
+                fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                clear_identity()
+                return
+            except BlockingIOError:
+                if time.monotonic() >= deadline: raise RuntimeError('Workspace egress controller did not stop')
+                time.sleep(.05)
+
+def capture_errors(proc):
+    tail = collections.deque(maxlen=128)
+    while True:
+        chunk = proc.stderr.read1(4096)
+        if not chunk: return
+        tail.append(chunk)
+        atomic(ROOT / 'daemon.log', b''.join(tail), binary=True)
+
+def select_exit(config, peers, selected, health_misses, helper, sock):
+    candidates = sorted(config.get('devices', []), key=lambda item: item.get('tailscaleIp') != selected)
+    for item in candidates:
+        ip = item.get('tailscaleIp')
+        if ip not in peers or not peers[ip].get('Online') or peers[ip].get('Expired'): continue
+        try:
+            # TSMP tests the encrypted peer path without opening a destination connection.
+            cli(helper, sock, 'ping', '--tsmp', '--c=1', '--timeout=2s', str(ipaddress.IPv4Address(ip)))
+            health_misses[ip] = 0
+            return item
+        except (RuntimeError, ValueError) as cause:
+            atomic(ROOT / 'last-peer-error.json', {'deviceId': item['deviceId'], 'error': str(cause), 'atMs': int(time.time() * 1000)})
+            health_misses[ip] = health_misses.get(ip, 0) + 1
+            if ip == selected and health_misses[ip] < 3: break
+            continue
+    return None
+
+def run():
+    with open(ROOT / 'daemon.lock', 'a') as lock:
+        deadline = time.monotonic() + 5
+        while True:
+            try:
+                fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                break
+            except BlockingIOError:
+                pid = load(ROOT / 'controller.pid')
+                alive = False
+                try:
+                    alive = isinstance(pid, int) and str(ROOT / 'controller.py').encode() in pathlib.Path('/proc/' + str(pid) + '/cmdline').read_bytes().split(bytes([0]))
+                except FileNotFoundError: pass
+                if time.monotonic() >= deadline:
+                    if alive: return
+                    raise RuntimeError('Workspace controller startup lock is busy')
+                time.sleep(.01)
+        atomic(ROOT / 'controller.pid', os.getpid())
+        proc = None
+        current = None
+        selected = None
+        health_misses = {}
+        bridges = None
+        revision = None
+        def terminate(signum, frame):
+            raise SystemExit(0)
+        signal.signal(signal.SIGTERM, terminate)
+        signal.signal(signal.SIGINT, terminate)
+        try:
+            while True:
+                config = load(ROOT / 'config.json', {})
+                mode = config.get('mode', 'blocked')
+                if mode != 'device' or config.get('bootId') != BOOT_ID or config.get('expiresAtMs', 0) <= time.time() * 1000 or config.get('deadlineMonotonic', 0) <= time.monotonic():
+                    # Coordinate relinquishing the daemon lock with writers so a renewal cannot lose its controller.
+                    with open(ROOT / 'request.lock', 'a') as requests:
+                        fcntl.flock(requests, fcntl.LOCK_EX)
+                        if load(ROOT / 'config.json', {}) != config: continue
+                        stop(proc); proc = None; current = None; selected = None
+                        clear_identity()
+                        if mode == 'direct':
+                            restore(); status('direct', config)
+                        else:
+                            guard(); status('blocked', config)
+                        fcntl.flock(lock, fcntl.LOCK_UN)
+                        return
+                helper = ROOT / 'helper'
+                sock = ROOT / 'control.sock'
+                revision = config.get('revision', config['leaseId'])
+                if revision != current or proc is None or proc.poll() is not None:
+                    stop(proc); proc = None
+                    with open(ROOT / 'request.lock', 'a') as requests:
+                        fcntl.flock(requests, fcntl.LOCK_EX)
+                        if load(ROOT / 'config.json', {}).get('revision', load(ROOT / 'config.json', {}).get('leaseId')) != revision: continue
+                        guard(); transport_hosts(config['transportHosts'])
+                    sock.unlink(missing_ok=True)
+                    state = ROOT / ('state-' + lease_state_name(config['leaseId']))
+                    for old in ROOT.glob('state-*'):
+                        if old != state and old.is_file(): old.unlink()
+                    env = helper_environment()
+                    proc = subprocess.Popen([str(helper), '--tun=final-egress0', '--port=0', '--socket=' + str(sock), '--state=' + str(state)],
+                                            stdin=subprocess.PIPE, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE, env=env)
+                    threading.Thread(target=capture_errors, args=(proc,), daemon=True).start()
+                    proc.stdin.write(b'final-device-start\n'); proc.stdin.flush()
+                    deadline = time.monotonic() + 5
+                    while not sock.exists():
+                        if proc.poll() is not None or time.monotonic() > deadline:
+                            raise RuntimeError('Workspace egress daemon did not become ready')
+                        time.sleep(.05)
+                    args = ['up', '--reset', '--login-server=' + config['controlUrl'], '--hostname=workspace-' + lease_state_name(config['leaseId'])[:40],
+                            '--accept-dns=false', '--accept-routes=false', '--shields-up', '--netfilter-mode=off']
+                    if config.get('authKey'):
+                        atomic(ROOT / 'enrollment.key', config['authKey'].encode(), binary=True)
+                        args.append('--auth-key=file:' + str(ROOT / 'enrollment.key'))
+                        args.append('--force-reauth')
+                    try: cli(helper, sock, *args)
+                    finally:
+                        (ROOT / 'enrollment.key').unlink(missing_ok=True)
+                        with open(ROOT / 'request.lock', 'a') as requests:
+                            # A writer may hold request.lock while awaiting our daemon.lock.
+                            try: fcntl.flock(requests, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                            except BlockingIOError: pass
+                            else:
+                                pending = load(ROOT / 'config.json', {})
+                                if pending.get('revision', pending.get('leaseId')) == revision:
+                                    pending.pop('authKey', None); atomic(ROOT / 'config.json', pending)
+                    with open(ROOT / 'request.lock', 'a') as requests:
+                        fcntl.flock(requests, fcntl.LOCK_EX)
+                        saved = load(ROOT / 'config.json', {})
+                        if saved.get('mode') != 'device' or saved.get('leaseId') != config.get('leaseId') or saved.get('revision', saved.get('leaseId')) != revision:
+                            stop(proc); proc = None; current = None; selected = None
+                            continue
+                        resolver(saved.get('dnsResolvers', ['1.1.1.1', '9.9.9.9']))
+                        saved.pop('authKey', None); atomic(ROOT / 'config.json', saved)
+                        current = revision; selected = None
+                        guard(allow_tunnel=True)
+                if config.get('state') == 'provisioning':
+                    controller_status('enrolled', config)
+                    time.sleep(.2)
+                    continue
+                actual_bridges = local_bridges()
+                with open(ROOT / 'request.lock', 'a') as requests:
+                    fcntl.flock(requests, fcntl.LOCK_EX)
+                    latest = load(ROOT / 'config.json', {})
+                    if latest.get('mode') != 'device' or latest.get('revision', latest.get('leaseId')) != revision: continue
+                    resolver(latest.get('dnsResolvers', ['1.1.1.1', '9.9.9.9']))
+                    previous_listeners = load(ROOT / 'control-listeners.json', [])
+                    existing_control_replies()
+                    actual_tunnel = command('ip', '-j', 'addr', 'show', 'dev', 'final-egress0', check=False)
+                    actual_addresses = [str(ipaddress.ip_address(address['local'])) for interface in json.loads(actual_tunnel.stdout or b'[]') for address in interface.get('addr_info', [])]
+                    if bridges != actual_bridges or previous_listeners != load(ROOT / 'control-listeners.json', []) or actual_addresses != load(ROOT / 'tunnel-addresses.json', []):
+                        guard(allow_tunnel=True); bridges = actual_bridges
+                try:
+                    raw = json.loads(cli(helper, sock, 'status', '--json'))
+                    peers = {ip: peer for peer in (raw.get('Peer') or {}).values() for ip in (peer.get('TailscaleIPs') or [])}
+                    candidates = config.get('devices', [])
+                    candidate = select_exit(config, peers, selected, health_misses, helper, sock)
+                    if candidate is None:
+                        last = next((item for item in candidates if item.get('tailscaleIp') == selected), None)
+                        # A health miss must not tear down an authorized route during control outage/rekey.
+                        # Keeping it can only use the approved exit; the namespace guard still forbids direct fallback.
+                        if last is not None and selected in peers and not peers[selected].get('Expired'):
+                            peer = peers[selected]
+                            controller_status('reconnecting', config, deviceId=last['deviceId'], path='direct' if peer.get('CurAddr') else 'relay')
+                        else:
+                            if selected is not None: cli(helper, sock, 'set', '--exit-node=')
+                            selected = None
+                            controller_status('blocked', config)
+                    else:
+                        ip = str(ipaddress.IPv4Address(candidate['tailscaleIp']))
+                        if selected != ip:
+                            cli(helper, sock, 'set', '--exit-node=' + ip, '--exit-node-allow-lan-access=false')
+                            selected = ip
+                        route = command('ip', '-4', 'route', 'get', '192.0.2.254').stdout
+                        if b'dev final-egress0' not in route:
+                            controller_status('configuring', config)
+                            time.sleep(.1)
+                            continue
+                        peer = peers[ip]
+                        controller_status('device', config, deviceId=candidate['deviceId'], path='direct' if peer.get('CurAddr') else 'relay')
+                    time.sleep(1)
+                except (RuntimeError, subprocess.TimeoutExpired, json.JSONDecodeError) as failure:
+                    atomic(ROOT / 'last-peer-error.json', {'error': str(failure)[:1000], 'atMs': int(time.time() * 1000)})
+                    controller_status('reconnecting', config)
+                    time.sleep(1)
+        except Exception as cause:
+            atomic(ROOT / 'last-error.json', {'error': str(cause), 'atMs': int(time.time() * 1000)})
+            controller_status('error', load(ROOT / 'config.json', {}), error='Workspace egress stopped; inspect the controller error')
+            raise
+        finally:
+            stop(proc)
+            if load(ROOT / 'controller.pid') == os.getpid(): (ROOT / 'controller.pid').unlink(missing_ok=True)
+            # Writers can await daemon.lock while holding request.lock; finish secret cleanup after releasing it.
+            fcntl.flock(lock, fcntl.LOCK_UN)
+            with open(ROOT / 'request.lock', 'a') as requests:
+                fcntl.flock(requests, fcntl.LOCK_EX)
+                pending = load(ROOT / 'config.json', {})
+                if revision is not None and pending.get('revision', pending.get('leaseId')) == revision and 'authKey' in pending:
+                    pending.pop('authKey', None); atomic(ROOT / 'config.json', pending)
+
+def apply(request):
+    prerequisite(request['action'])
+    with open(ROOT / 'request.lock', 'a') as lock:
+        fcntl.flock(lock, fcntl.LOCK_EX)
+        action = request['action']
+        source = pathlib.Path(__file__).read_bytes() if '__file__' in globals() else sys.argv[1].encode()
+        cached_source = ROOT / 'controller.py'
+        if not cached_source.exists() or cached_source.read_bytes() != source: atomic(cached_source, source, binary=True)
+        existing = load(ROOT / 'config.json', {})
+        capabilities = [int(line.split()[1], 16) for line in pathlib.Path('/proc/self/status').read_text().splitlines() if line.startswith(('CapInh:', 'CapPrm:', 'CapEff:', 'CapBnd:', 'CapAmb:'))]
+        # A prior choice with lost volatile state is not proof of an untouched namespace.
+        network_pristine = (existing.get('noNetworkChanges') is True or ((not existing or existing.get('mode') == 'direct') and not (PERSISTENT / 'intent.json').exists())) and bool(capabilities) and not any(mask & (1 << 12) for mask in capabilities) and not (PERSISTENT / 'resolver.original').exists() and not (PERSISTENT / 'hosts.original').exists() and not (ROOT / 'controller.pid').exists()
+        workspace_id = request.get('workspaceId')
+        if action != 'status' and existing.get('workspaceId') is not None and existing['workspaceId'] != workspace_id:
+            raise RuntimeError('This network namespace belongs to a different workspace')
+        operation = load(ROOT / 'operation.json', {})
+        operation_live = operation.get('bootId') == BOOT_ID and operation.get('deadline', 0) > time.monotonic()
+        token = str(uuid.UUID(request['configurationToken'])) if request.get('configurationToken') is not None else None
+        if action == 'claim':
+            if (request.get('refresh') or request.get('verifyOnly')) and (not operation_live or operation.get('token') != token):
+                raise WorkspaceConflictError('Workspace configuration claim was superseded')
+            if operation_live and operation.get('token') != token:
+                return {**load(ROOT / 'status.json', {'mode': 'blocked', 'leaseId': None, 'expiresAtMs': None, 'deviceId': None, 'path': None}), 'busy': True}
+            token = str(uuid.UUID(token))
+            if not request.get('verifyOnly'):
+                atomic(ROOT / 'operation.json', {'token': token, 'deadline': time.monotonic() + 300, 'bootId': BOOT_ID})
+            return {**load(ROOT / 'status.json', {'mode': 'blocked', 'leaseId': None, 'expiresAtMs': None, 'deviceId': None, 'path': None}), 'busy': False}
+        if action == 'unlock':
+            if operation.get('token') == token: (ROOT / 'operation.json').unlink(missing_ok=True)
+            return load(ROOT / 'status.json', {'mode': 'blocked', 'leaseId': None, 'expiresAtMs': None, 'deviceId': None, 'path': None})
+        if action not in ('status', 'artifact'):
+            if token is not None and (not operation_live or operation.get('token') != token):
+                raise WorkspaceConflictError('Workspace egress configuration was superseded')
+            if operation_live and token != operation.get('token'):
+                raise WorkspaceConflictError('Another binding is configuring workspace egress')
+            expected = lease_id(request['expectedLeaseId']) if request.get('expectedLeaseId') is not None else None
+            if token is None and expected is not None and existing.get('leaseId') != expected:
+                if action == 'block' and existing.get('leaseId') is None and existing.get('mode') == 'direct':
+                    return load(ROOT / 'status.json', {'mode': 'direct', 'leaseId': None, 'expiresAtMs': None, 'deviceId': None, 'path': None})
+                if action == 'block' and existing.get('leaseId') is None and existing.get('mode') == 'blocked':
+                    try: guard()
+                    except Exception as failure:
+                        status('error' if isinstance(failure, DenialUnavailableError) else 'blocked', existing)
+                        raise
+                    return status('blocked', existing)
+                if not (action == 'block' and existing.get('leaseId') is None and (not existing or existing.get('mode') == 'blocked')):
+                    raise WorkspaceConflictError('Workspace egress lease changed before cleanup')
+        if action not in ('status', 'artifact'):
+            PERSISTENT.mkdir(mode=0o700, exist_ok=True)
+            if PERSISTENT.is_symlink() or PERSISTENT.stat().st_uid != 0:
+                raise RuntimeError('Persistent workspace egress state must be root-owned')
+            PERSISTENT.chmod(0o700)
+            identity = load(PERSISTENT / 'identity.json', {})
+            if identity.get('workspaceId') is not None and identity['workspaceId'] != workspace_id:
+                raise RuntimeError('Persistent egress state belongs to a different workspace')
+            if action != 'disable': atomic(PERSISTENT / 'identity.json', {'workspaceId': workspace_id})
+        if action == 'block': atomic(PERSISTENT / 'intent.json', {'requiresChoice': not request.get('restoreDirect', False)})
+        if action == 'disable' and existing.get('noNetworkChanges') is True:
+            if (PERSISTENT / 'resolver.original').exists() or (PERSISTENT / 'hosts.original').exists() or (ROOT / 'controller.pid').exists():
+                raise RuntimeError('Workspace contains restoration artifacts; privileged repair is required')
+            (PERSISTENT / 'identity.json').unlink(missing_ok=True)
+            (PERSISTENT / 'intent.json').unlink(missing_ok=True)
+            config = {'mode': 'direct', 'workspaceId': workspace_id, 'ownerUserId': None}
+            atomic(ROOT / 'config.json', config)
+            return status('direct', config)
+        if action == 'disable' and (not existing or (existing.get('mode') == 'direct' and load(ROOT / 'status.json', {}).get('mode') == 'direct')):
+            if restoration_pending(): restore()
+            (PERSISTENT / 'identity.json').unlink(missing_ok=True)
+            (PERSISTENT / 'intent.json').unlink(missing_ok=True)
+            config = {'mode': 'direct', 'workspaceId': workspace_id, 'ownerUserId': None}
+            atomic(ROOT / 'config.json', config)
+            return status('direct', config)
+        if action == 'artifact':
+            ready = False
+            try: fd = os.open(ROOT / 'helper', os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+            except FileNotFoundError: pass
+            else:
+                with os.fdopen(fd, 'rb') as source:
+                    info = os.fstat(source.fileno())
+                    if stat.S_ISREG(info.st_mode) and info.st_size <= 128 * 1024 * 1024:
+                        ready = hashlib.sha256(source.read(128 * 1024 * 1024 + 1)).hexdigest() == request['sha256']
+            return {**load(ROOT / 'status.json', {'mode': 'blocked', 'leaseId': None, 'expiresAtMs': None, 'deviceId': None, 'path': None}), 'helperReady': ready}
+        if action == 'status':
+            result = load(ROOT / 'status.json', {'mode': 'direct', 'leaseId': None, 'expiresAtMs': None, 'deviceId': None, 'path': None, 'architecture': platform.machine()})
+            alive = False
+            with open(ROOT / 'daemon.lock', 'a') as daemon_lock:
+                try:
+                    fcntl.flock(daemon_lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                    if result.get('mode') != 'error' and existing.get('mode') not in ('direct', 'error') and existing:
+                        result = {**result, 'mode': 'blocked' if denial_present() else 'error', 'deviceId': None, 'path': None}
+                except BlockingIOError: alive = True
+            return {**result, 'networkPristine': existing.get('noNetworkChanges', False), 'controllerAlive': alive, 'configuring': operation_live, 'restorePending': restoration_pending(), 'choicePending': load(PERSISTENT / 'intent.json', {}).get('requiresChoice', existing.get('mode') == 'blocked')}
+        if action in ('block', 'configure'):
+            try: guard()
+            except Exception as failure:
+                mode = 'error' if isinstance(failure, DenialUnavailableError) else 'blocked'
+                failed = {'mode': mode, 'workspaceId': workspace_id, 'ownerUserId': request.get('ownerUserId'), 'noNetworkChanges': network_pristine}
+                atomic(ROOT / 'config.json', failed); status(mode, failed)
+                raise
+        if action == 'configure':
+            # Validation failure must not leave an old direct/device status after guard installation.
+            pending = {'mode': 'blocked', 'workspaceId': workspace_id, 'ownerUserId': request.get('ownerUserId')}
+            atomic(ROOT / 'config.json', pending); status('blocked', pending)
+            if request.get('config', {}).get('workspaceId') != workspace_id: raise RuntimeError('Enrollment belongs to a different workspace')
+            if command('ip', '-4', 'rule', 'show', check=False).returncode != 0:
+                raise PrerequisiteError('This workspace kernel does not support Linux policy routing')
+            config = request['config']
+            config['dnsResolvers'] = validated_resolvers(config.get('dnsResolvers', ['1.1.1.1', '9.9.9.9']))
+            control = urllib.parse.urlsplit(config['controlUrl'])
+            if control.scheme != 'https' or not control.hostname or control.username is not None or control.password is not None or control.query or control.fragment:
+                raise RuntimeError('Workspace control URL must use HTTPS without credentials, query or fragment')
+            config['leaseId'] = lease_id(config['leaseId'])
+            remaining = config['expiresAtMs'] - time.time() * 1000
+            if not 0 < remaining <= 16 * 60 * 1000:
+                raise RuntimeError('Workspace egress lease is expired or exceeds fifteen minutes')
+            config['bootId'] = BOOT_ID
+            config['deadlineMonotonic'] = time.monotonic() + min(remaining, 15 * 60 * 1000) / 1000
+            staged = pathlib.Path(request['helperPath'])
+            try: fd = os.open(staged, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+            except FileNotFoundError as failure:
+                raise RuntimeError('Staged networking helper is missing; transfer the approved artifact again') from failure
+            with os.fdopen(fd, 'rb') as source:
+                if not stat.S_ISREG(os.fstat(source.fileno()).st_mode):
+                    raise RuntimeError('Workspace networking helper must be a regular file')
+                content = source.read(128 * 1024 * 1024 + 1)
+            if len(content) > 128 * 1024 * 1024 or hashlib.sha256(content).hexdigest() != config['helper']['sha256']:
+                raise RuntimeError('Workspace networking helper failed integrity verification')
+            machine = {'x86_64': 62, 'aarch64': 183}.get(platform.machine())
+            if content[:6] != b'\x7fELF\x02\x01' or len(content) < 20 or struct.unpack('<H', content[18:20])[0] != machine:
+                raise RuntimeError('The pinned networking helper does not match this Linux workspace architecture')
+            atomic(ROOT / 'helper', content, binary=True, mode=0o700)
+            config = dict(config, mode='device')
+        elif action == 'renew':
+            request['lease']['leaseId'] = lease_id(request['lease']['leaseId'])
+            if request.get('lease', {}).get('workspaceId') != workspace_id: raise RuntimeError('Renewal belongs to a different workspace')
+            config = load(ROOT / 'config.json')
+            if config is None or config.get('leaseId') != request['lease']['leaseId']:
+                raise WorkspaceConflictError('Workspace egress lease changed')
+            if config.get('bootId') != BOOT_ID or config.get('deadlineMonotonic', 0) <= time.monotonic() or config.get('expiresAtMs', 0) <= time.time() * 1000:
+                raise EnrollmentLostError('Workspace enrollment expired locally; authorized reenrollment is required')
+            lease = request['lease']
+            lease['leaseId'] = lease_id(lease['leaseId'])
+            remaining = lease['expiresAtMs'] - time.time() * 1000
+            if not 0 < remaining <= 16 * 60 * 1000:
+                raise RuntimeError('Workspace egress renewal is invalid')
+            config.update(bootId=BOOT_ID, expiresAtMs=lease['expiresAtMs'], devices=lease['devices'], state=lease['state'], deadlineMonotonic=time.monotonic() + min(remaining, 15 * 60 * 1000) / 1000)
+        elif action in ('block', 'disable'):
+            config = {'mode': 'direct' if action == 'disable' else 'blocked', 'workspaceId': workspace_id, 'ownerUserId': None if action == 'disable' else request.get('ownerUserId')}
+        else:
+            raise RuntimeError('Unknown workspace egress action')
+        atomic(ROOT / 'config.json', config)
+        if action in ('block', 'disable'): stop_controller()
+        if action == 'renew':
+            with open(ROOT / 'daemon.lock', 'a') as daemon_lock:
+                try: fcntl.flock(daemon_lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                except BlockingIOError:
+                    prior = load(ROOT / 'status.json', {})
+                    return {**prior, 'expiresAtMs': config['expiresAtMs']}
+        # The controller uses a root-owned copy after this caller's temporary files are removed.
+        source = pathlib.Path(__file__).read_bytes() if '__file__' in globals() else sys.argv[1].encode()
+        atomic(ROOT / 'controller.py', source, binary=True)
+        subprocess.Popen([sys.executable, '-I', str(ROOT / 'controller.py'), 'run'], stdin=subprocess.DEVNULL,
+                         stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, start_new_session=True)
+        if action == 'block': return status('blocked', config)
+        return status('configuring', config)
+
+if __name__ == '__main__':
+    try:
+        if len(sys.argv) > 1 and sys.argv[1] == 'run': run()
+        else: print(json.dumps(apply(json.load(sys.stdin))))
+    except Exception as cause:
+        try:
+            if ROOT.exists() and not ROOT.is_symlink() and ROOT.stat().st_uid == 0:
+                atomic(ROOT / 'last-error.json', {'error': str(cause)[:1000], 'atMs': int(time.time() * 1000)})
+        except OSError: pass
+        code = 'egress_enrollment_lost' if isinstance(cause, EnrollmentLostError) else 'prerequisite' if isinstance(cause, (FileNotFoundError, PrerequisiteError)) else 'conflict' if isinstance(cause, WorkspaceConflictError) else 'configuration'
+        print(json.dumps({'errorCode': code}))
+        sys.exit(1)
+`;
+const cachedWorkspaceEgressBootstrap = (sha256) => {
+  if (!/^[a-f0-9]{64}$/.test(sha256)) throw new Error("Invalid workspace controller SHA256");
+  return String.raw`import hashlib, os, pathlib, stat
+path = pathlib.Path('/run/final-workspace-egress/controller.py')
+try:
+    fd = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+    with os.fdopen(fd, 'rb') as file:
+        info = os.fstat(file.fileno())
+        source = file.read(128 * 1024 + 1)
+    valid = stat.S_ISREG(info.st_mode) and info.st_uid == 0 and not info.st_mode & 0o022 and len(source) <= 128 * 1024 and hashlib.sha256(source).hexdigest() == '${sha256}'
+except OSError: valid = False
+if valid: exec(compile(source, str(path), 'exec'), {'__name__': '__main__', '__file__': str(path)})
+else: print('{"needsBootstrap":true}')
+`;
+};
+const workspaceEgressLauncher = String.raw`import io,json,sys
+request=json.load(sys.stdin)
+source=request['source']
+sys.argv=['-c',source]
+sys.stdin=io.StringIO(request['input'])
+exec(compile(source,'<final-workspace-egress>','exec'),{'__name__':'__main__'})
+`;
+export {
+  cachedWorkspaceEgressBootstrap,
+  workspaceEgressBootstrap,
+  workspaceEgressLauncher
+};
+//# sourceMappingURL=egress-bootstrap.mjs.map