Enforcing Zero Network Egress with Automated Sovereignty Tests

Many dev tools label themselves local-first while secretly pinging remote endpoints for telemetry, grammar downloads, or license checks.

When building TokenCap, we decided that security guarantees should not depend on developer discipline. They must be enforced by automated tests in CI.

The Four Sovereignty Laws

Every feature added to TokenCap must conform to four rules:

1. No runtime network calls (except explicit tokencap upgrade).
2. No API keys required, ever.
3. Zero native compilation or post-install build scripts.
4. Total dependency count stays under 4 packages so the entire tree can be audited in an afternoon.

How We Test Sovereignty

In test/sovereignty.test.js, we hook Node.js network primitives and check package manifests:

// test/sovereignty.test.js excerpt
test("enforces zero network egress and dependency budget", () => {
  const pkg = JSON.parse(fs.readFileSync("package.json", "utf8"));
  const depCount = Object.keys(pkg.dependencies || {}).length;

  // Hard constraint: Maximum 4 production dependencies
  assert.ok(depCount <= 4, `Dependencies exceeded limit: got ${depCount}`);

  // Verify tree-sitter grammars are vendored WASM, not remote downloads
  const grammars = fs.readdirSync("dist/grammars");
  assert.ok(grammars.length >= 7, "Grammars must be vendored locally");
});

Because WASM binaries are vendored into the package, npx tokencap make runs cleanly inside air-gapped corporate environments, firewalled CI runners, and defense environments without a single network packet leaving the box.

Inspect our architecture and security docs at tokencap.vansharora.app

Comments

[Hamid Ahmadian]

One gap worth closing in the test you posted: the dependency-count and vendored-grammar checks are good, but they're static assertions about package.json and dist/, not a runtime check that no network call actually happens. A dependency you already audited can still make a network call at runtime (a transitive dep updated between audits, a dynamic require, a native addon phoning home) and this test would still pass. To actually enforce law #1 in CI, you'd want to run the real command inside a network namespace with no route (unshare --net on Linux, or a firewall rule that drops everything except loopback) and assert the process still completes successfully — that catches egress regardless of which dependency caused it, instead of trusting that the ones you counted stayed well-behaved. Monkey-patching net.connect/http.request/dns.lookup in-process and asserting they're never called is a cheaper middle ground if a full network-namespace sandbox is too heavy for your CI runner.