webnetstack

webnetstack is a browser-to-localhost networking bridge for Linux that uses existing OS socket APIs while keeping the exposed surface narrow, permissioned, and auditable.

It is inspired by the repository style and capability posture used by WebGPU, WebGL, and WebUSB work: explainer material, protocol/spec notes, examples, tests, and a constrained API surface instead of direct kernel or hardware exposure.

Status

Prototype host bridge plus browser SDK.

Linux only.

Implemented:

• TCP connect/send/receive/close
• UDP connect/send/receive/close
• Real DNS resolution through the host OS resolver
• Real HTTP client requests over http and https
• Real outbound WebSocket client channels over ws and wss
• Permission-descriptor helpers similar in spirit to browser capability requests
• Origin allow-list enforcement
• Secure-origin style restriction: https:// or loopback http://
• Required WebSocket subprotocol: webnetstack.v1
• Explicit destination allow-list with protocol scope
• Token gate for session establishment
• Payload limits, channel limits, idle timeout, and session timeout
• User-space simulation knobs: latency, jitter, loss, duplication, rate limiting
• Rust integration tests and Jest SDK tests

Not implemented:

• Inbound listeners
• QUIC
• Raw packets
• Interface enumeration
• Kernel stats
• Hardware identifiers
• Browser-native permission prompts

Repository layout

• explainer/: rationale and API shape notes
• spec/: host protocol documentation
• examples/: demo page and manifest
• sdk/: browser-facing JavaScript API
• src/: Rust host bridge
• tests/: Rust integration tests
• tools/: local development helpers
• .github/workflows/: CI

Security model

webnetstack is intentionally narrower than native sockets.

Constraints:

• No /sys reads
• No kernel telemetry
• No interface enumeration
• No MAC addresses or host hardware identifiers
• No raw packet or privileged socket features
• Opaque channel handles only
• Explicit origin and destination policy checks
• Session and resource limits enforced by the host

Main JS API

WebNetStack methods:

• connect()
• openTcp()
• openUdp()
• openWebSocket()
• resolveDns()
• fetchHttp()
• requestTcpAccess()
• requestUdpAccess()
• requestAccess()
• ping()
• closeAll()
• close()
• getPolicy()
• getOrigins()
• getDestinations()
• getLimits()
• supportsDestination()

WebNetChannel methods:

• send()
• sendText()
• sendJson()
• sendHex()
• setSimulation()
• resetSimulation()
• setLatency()
• setLoss()
• setDuplication()
• setRateLimit()
• readOnce()
• waitForClose()
• close()
• onMessage()
• onClose()
• decode()

Run

npm package

Install the package on Linux:

npm install @devanshraulo/webnetstack

Start the packaged host binary directly with npx:

npx @devanshraulo/webnetstack --manifest /path/to/manifest.json

Or start it from Node without requiring a separate Rust install on the target machine:

import { startHost, WebNetStack } from "@devanshraulo/webnetstack";

const host = await startHost({
  allowOrigins: ["http://127.0.0.1:8080"],
  destinations: [{ host: "example.com", port: 80, protocols: ["tcp"] }],
});

const client = await new WebNetStack(host.wsUrl, host.token).connect();

The npm package includes the Linux Rust host binary. Browser code still cannot launch local processes by itself, so automatic host startup requires either npx @devanshraulo/webnetstack ... or Node code calling startHost().

repository

Start the host from source:

cargo run -- --manifest examples/manifest.json

Serve the demo from an allowed loopback origin:

python3 tools/serve_localhost.py

Open:

http://127.0.0.1:8080/examples/demo.html

Validation

Rust:

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test

JavaScript:

npm run test:js

Manifest example

{
  "token": "dev-token",
  "allowOrigins": ["http://127.0.0.1:8080"],
  "destinations": [
    { "host": "example.com", "port": 80, "protocols": ["tcp"] },
    { "host": "127.0.0.1", "port": 18080, "protocols": ["tcp", "udp"] }
  ],
  "maxPayloadBytes": 1048576,
  "maxChannelsPerSession": 8,
  "idleTimeoutMs": 30000,
  "sessionTimeoutMs": 300000
}

Upload notes

Before pushing to GitHub:

npm ci
cargo test
npm run test:js

If you want the repository to be fully publishable, the next practical addition is a LICENSE file and any release/versioning policy you want to use.