Network Membrane

Operational

The Network Membrane is the userland network stack. It runs the grafted LwIP (Lightweight IP) stack inside a sandboxed fiber, providing TCP/IP connectivity to applications through a POSIX-compatible shim.

What Is the Membrane?

The Membrane (libnexus.a) is a compatibility adapter — a "biosuit" that wraps POSIX system calls and routes them through Nexus's sovereign abstractions. For networking, this means:

• socket() creates a Membrane-managed endpoint
• connect() sends a connection request through the LwIP stack
• send()/recv() transfer data through ION Rings
• bind()/listen()/accept() work as expected

Applications compiled against POSIX (curl, wget, ssh) work through the Membrane without modification. They never touch the kernel's network code directly.

Architecture

┌─────────────────────────┐
│  Application Process    │
│  (calls socket/send)    │
├─────────────────────────┤
│  Membrane POSIX Shim    │  libnexus.a
│  (translates to ION)    │
├─────────────────────────┤
│  LwIP TCP/IP Stack      │  Grafted, runs as fiber
│  (DHCP, TCP, UDP, ICMP) │
├─────────────────────────┤
│  ION Ring (proc_rx/tx)  │  Zero-copy to kernel
├─────────────────────────┤
│  NetSwitch (Kernel)     │  L2 demux
└─────────────────────────┘

LwIP — The Grafted Stack

LwIP is an open-source lightweight TCP/IP stack designed for embedded systems. Nexus grafts it by:

1. Stripping all OS-specific code (no pthreads, no file I/O)
2. Replacing the platform layer with ION Ring integration
3. Running it as a Rumpk fiber with restricted capabilities
4. Applying pledge constraints (INET only — no filesystem access, no process spawning)

The result is a TCP/IP stack that provides full connectivity but cannot escape its sandbox.

DHCP and Network Configuration

The Membrane fiber runs DHCP client logic at boot:

1. NetSwitch routes incoming DHCP responses to the Membrane fiber's ION Ring
2. LwIP processes the DHCP offer and configures the interface
3. The assigned IP address is registered in /Bus/net/
4. Applications can now connect to the network

Why Not a Kernel Network Stack?

Three reasons:

1. Crash isolation: A bug in TCP processing kills only the Membrane fiber. The kernel restarts it. Applications reconnect.

2. Attack surface reduction: The kernel's trusted computing base does not include a TCP/IP stack. You cannot exploit a buffer overflow in packet parsing to gain kernel privileges.

3. Replaceability: The Membrane is a service, not a kernel feature. You can swap LwIP for a different stack, run multiple stacks simultaneously, or remove networking entirely — without recompiling the kernel.

Chimera POSIX Bridge

For full POSIX compatibility, the Membrane includes the Chimera bridge (SPEC-073) — a more complete adaptation layer that handles edge cases:

• Non-blocking I/O (O_NONBLOCK)
• Socket options (setsockopt)
• Signal-driven I/O (SIGIO)
• Unix domain sockets (mapped to local ION Rings)

This bridge makes it possible to graft complex network applications (nginx, PostgreSQL, Node.js) with minimal or no source modifications.