The first of four sub-projects that harden how countinghouse runs module code, inside the architecture it already has. Opt-in enforcement, default audit, so a minor release.
Verified against fix/loadfile-without-rewire at 22c19d2 on 2026-10-15,
which this design builds on (see Prerequisites). Every claim
below names the file that backs it — re-check rather than believe, the tree
moves.
docs/security-model.md is honest about it: modules run in
worker_threads.Workers (lib/module-manager.js, spawnModuleWorker), which
separate JS heaps and nothing else. A module, or any npm package it depends
on, can read and write any file the server can, open any connection
(including to the server’s own Redis), load native code, kill the whole
process, and allocate memory without limit. Measured on Node v24.21 from
inside a module’s worker during the design discussion:
| From a module’s worker | Today |
|---|---|
Read the server’s secrets from /proc/self/environ |
readable |
Open /proc/self/mem |
openable |
| Raw TCP connect to Redis on localhost | connects |
process.binding('fs') |
works, bypassing anything layered on fs |
process.kill(process.pid, 'SIGKILL') |
kills the whole server |
Allocate Buffers past a heap cap |
not limited (measured 108 MB under a 32 MB cap) |
These were decided before the design and are not up for trade:
worker_threads, direct peer channels unchanged. They are
where countinghouse’s performance comes from. No cordons, no per-module
processes.sendRedisCommandToParent (lib/redis-api.js,
lib/worker-message.js) already makes it the single point of contact for
Redis.Stated once, here, and repeated in docs/security-model.md:
--hardened backstop (below)
limits what the whole process can then reach, but it applies to the main
thread too, so it cannot separate a module from countinghouse’s own data.| Part | Contents | Status |
|---|---|---|
| 1. Foundation (this spec) | Permission declaration and operator policy; validator checks; worker lockdown; resource limits with restart and suspend; --moduleSandbox off\|audit\|enforce; --hardened |
this spec |
| 2. File broker and virtual root | fs/fs/promises routed through the main thread; per-module virtual root (/app, /data, /tmp, declared mounts) with __dirname and require virtualized; out-of-root access answers ENOENT and is logged on the host; file quotas; explicit uninstall that deletes the module’s private data unless told to keep it |
later spec |
| 3. HTTP(S) broker | fetch, http, https through the main thread; DNS done by the broker; destination checked after resolution, private ranges and localhost denied unless approved; request quotas |
later spec |
| 4. Raw TCP/TLS relay | net, tls through the main thread; UDP stays denied |
later spec |
Decisions already made for parts 2–4, recorded so this spec’s formats leave
room for them: outside paths are declared r or rw per path; modules must be
self-contained (their whole dependency tree inside their own directory); a
spike on Node v24.21 showed module.registerHooks can give module code
virtual __dirname, __filename, require.resolve and stack traces.
Separately, not in this spec: making --workerThread the default. The
sandbox needs worker mode; the default flip is its own change.
fix/loadfile-without-rewire (22c19d2), unmerged at the time of writing:
ModuleManager.prototype.
loadModuleByWorker), so lockdown runs once per worker and is never undone
by an in-place reload.CHUtil.loadFile is a plain require() (lib/countinghouse-util.js), so
it goes through the loader hooks this spec adds. rewire read and compiled
files itself and would have bypassed them, and its __set__ used eval.exit event no longer unloads a newer worker under the same
name — the restart policy below depends on that.New flag --moduleSandbox off|audit|enforce, default audit.
| Mode | Behaviour |
|---|---|
off |
Today’s behaviour: no lockdown, no limits, no policy. Logged once at startup as a warning. |
audit |
Every check runs; a violation is logged (module, rule, detail — e.g. log-read require child_process) and the operation goes ahead. |
enforce |
A violation is blocked. The blocked call throws the error type Node itself would throw (ERR_ACCESS_DENIED, MODULE_NOT_FOUND), and the host logs it. |
audit too. Logging a runaway allocation does not stop it.--workerThread is off by default
(docs/cli-and-api-reference.md). Without it:
audit downgrades to off with a startup warning, so
existing single-thread setups keep starting;--moduleSandbox audit or enforce is a startup error.ctx.call and
billing. Part 1 adds no hop to any existing call path.In package.json, beside the existing countinghouse.calls
(lib/module-validator.js, callsProblems):
"countinghouse": {
"calls": ["…"],
"permissions": {
"fs": [ { "path": "/var/log/app", "access": "r" } ],
"net": [ { "host": "api.example.com", "ports": [443] } ],
"env": [ "WEATHER_API_KEY" ],
"limits": { "heapMb": 128, "externalMb": 128, "maxBlockMs": 5000 }
}
}
| Field | Rules |
|---|---|
fs |
Outside paths only. Absolute, normalized, no ... access is r or rw. /app, /data, /tmp and anything under them are reserved for part 2’s virtual root and cannot be declared. |
net |
host is a hostname or *.-prefixed wildcard (one leading label only); ports optional, integers 1–65535. Covers HTTP(S) in part 3; a later "protocols": ["tcp"] opts into part 4’s relay. IP literals are allowed only as exact hosts. |
env |
Environment variable names ([A-Z_][A-Z0-9_]*). |
limits |
What the module asks for; all optional. |
No permissions key means: nothing outside its own root, no env vars, default
limits.
What part 1 enforces from this: syntax (validator and load time), env,
limits, and the net check on CHUtil.request / CHUtil.createSOAPClient
(section 3, item 5). fs and the rest of net are parsed, validated, and
logged as effective permissions, and take effect when parts 2 and 3 ship.
New flag --modulePolicy <file>, JSON keyed by package name:
{
"limits": { "heapMb": 256, "externalMb": 256, "maxBlockMs": 10000 },
"modules": {
"log-read": {
"fs": [ { "path": "/var/log/app", "access": "r" } ]
},
"weather": {
"approve": "as-declared",
"env": { "WEATHER_API_KEY": "…" }
}
}
}
fs entry must equal or sit inside a declared path, with the
same or less access (r ≤ rw);net entry must name a declared host (or a host matched by a
declared wildcard), with the same or fewer ports;limits, then the per-module entry);"approve": "as-declared" grants the declaration unchanged.fs or net):
audit grants the declaration; enforce grants only the module’s own root
until the operator adds an entry. A module that declares nothing outside
needs no entry in either mode.env if set there, otherwise from the server’s own
environment, otherwise it is absent. Undeclared names are never passed.--modulePolicy is re-read on module restart, so an edit takes effect by
restarting the module, not the server.In countinghouse-validate (bin/countinghouse-validate.js,
lib/module-validator.js), and repeated at load time:
dependencies, followed
through the whole tree, resolves to a directory inside the module’s own
directory..node file, no binding.gyp, no
"gypfile": true anywhere in the tree.preinstall, install, postinstall in any
package.json in the tree) are reported as a warning, not an error —
groundwork for admission work later.The validator advises; the load-time check decides. In enforce a module
failing 1–3 is refused with MODULE_SANDBOX_REFUSED and the reasons; in
audit the failures are logged and the module loads.
When it runs. lib/sandbox.js loads countinghouse’s own worker code first,
as today; that code keeps its own references to the real fs, net and the
rest. A new lib/module-lockdown.js then runs once, on the set-options
message, before the first load-module message — no module code runs before
it.
What it does:
process.dlopen and the .node loader
(Module._extensions['.node']) throw. process.binding and
process._linkedBinding throw.process.kill, process.abort, process.chdir,
process.setuid, setgid, seteuid, setegid, setgroups,
initgroups throw. process.umask is already a stub (lib/sandbox.js).
process.exit stays allowed: in a worker it ends only that module, which
then goes through the crash path in section 4.require boundary. A module.registerHooks resolve hook allows
Node built-ins (subject to item 4) and files inside the module’s own
directory. Everything else — NODE_PATH (which bin/countinghouse sets
to countinghouse’s lib/), global folders, other modules — gets
MODULE_NOT_FOUND, logged on the host.Built-ins blocked or reduced. Enforced as an allowlist written out from Node 24.21’s built-ins less the blocked ones below, so a built-in a later Node adds is refused until reviewed (amended after review, 2026-10-17):
| Module | Why | Treatment |
|---|---|---|
child_process, cluster |
new processes outside every check | blocked |
worker_threads |
parentPort lets a module send raw broker messages as if it were countinghouse’s worker code |
blocked |
inspector, wasi |
debugger access; a second runtime | blocked |
v8 |
setFlagsFromString can switch protections off |
blocked |
sqlite |
loadExtension loads native code |
blocked |
test, test/reporters |
run() starts child processes outside every check |
blocked |
sea |
no use in a module | blocked |
crypto, tls |
OpenSSL engines (setEngine, privateKeyEngine, clientCertEngine) load native code |
engine loading blocked |
module |
Module._load, _extensions, registerHooks bypass the boundary |
reduced: builtinModules, isBuiltin, and a createRequire that stays inside the boundary |
fs, net, http and the like stay usable until parts 2 and 3. The first
require of each by each module is logged in both modes, so the operator
learns which modules will need fs/net permissions before those parts
ship.
CHUtil is a global in every worker
(lib/sandbox.js), and three of its members would bypass the lockdown:
CHUtil.loadFile(path) — same check as require: the module’s own tree
only.CHUtil.request (postman-request) and CHUtil.createSOAPClient — the
target URL’s hostname and port are checked against the module’s
effective net permissions. Part 3 adds the check after DNS resolution.env holding only the
approved names (section 2). process.env in the worker is that object.Audit vs enforce. In audit each override logs and calls through. In
enforce it throws.
Known gap, accepted. A module that obtains an object countinghouse loaded
before lockdown can reach the originals through it. The CHUtil surface is
therefore part of the review checklist for every change to
lib/countinghouse-util.js, and docs/security-model.md says so.
| Limit | Mechanism | Default ceiling |
|---|---|---|
heapMb — JS heap |
resourceLimits.maxOldGenerationSizeMb on the Worker; V8 ends the worker itself |
256 |
externalMb — Buffers, typed arrays |
main thread polls worker.getHeapStatistics() every second and terminates a worker whose external_memory exceeds the limit (verified available on Node v24.21) |
256 |
maxBlockMs — blocked event loop |
main thread pings each worker every second; no reply for maxBlockMs means the worker is stuck in synchronous code, and it is terminated (terminate() works mid-loop) |
10000 |
The existing per-call timeout (DEVICE_NOT_RESPONDING, --requestTimeout)
is unchanged: it answers a slow caller and kills nothing.
Worker → main message rate: a token bucket per worker, default 2000
messages/second, --moduleMessageRate <n>. Excess messages are answered in
the worker with RATE_LIMITED. Redis commands travel this channel, so a
high-throughput module may need more.
Limit kills and crashes (uncaught exception, process.exit(), a worker
error event) follow one policy:
MODULE_RESTARTING
and the reason (heap limit, external memory limit, blocked event
loop, crash: <message>), instead of waiting for the call timeout.MODULE_RESTARTING with the time of the next attempt.
Tools stay in tools/list: countinghouse sends no tools/list_changed
notification, and a tool that appears and vanishes confuses clients more
than one that answers with a clear code.MODULE_SUSPENDED with the last reason. The host logs an error with the
module, its exit history and the reasons. An operator POST
/restart-module or a load clears the suspension and the counter.Deliberate exits do not count: an operator unload, restart or reload, and a server shutdown.
Behaviour change: today a crashed module is unloaded and stays down
(spawnModuleWorker’s exit handler). Under audit and enforce it now
restarts. off keeps today’s behaviour.
The main thread keeps one record per module: running | restarting |
suspended, the last reason, the exit history in the current window, the next
restart time, and the audit violation counter. It is added to the existing
admin route GET /get-module-device-list (lib/routes/
get-module-device-list.js) under a sandbox key.
--hardened launch modeNode’s permission model (--permission) blocked /proc/self/mem and
/proc/self/environ in the design-time test. It must be given when Node
starts, so --hardened makes the entry point (framework.js) re-launch
itself under it:
--hardened is set and process.permission is absent, framework.js
computes the flags below, spawns process.execPath with them and the same
arguments, forwards signals and stdio, and exits with the child’s code.
Under the permission model, process.permission is present and startup
continues normally.--modulePath (default
~/countinghouse_modules, lib/cli-options.js); --authConfigPath;
--deviceConfigPath; --modulePolicy.--modulePath directory (it holds
countinghouse-modules.db, lib/device-db.js) and the directory of the
SQLite auth file when --authProvider sqlite.--allow-worker always (modules run in Workers; Node warns that it
weakens the model, and the docs say why it is needed). --allow-addons
only with --authProvider sqlite (the sqlite3 addon), and the docs note
that native code in the main thread is outside the permission model.
--allow-child-process only with --authoringTools
(countinghouse_validate_module runs the module in a child process,
lib/mcp/gateway.js).--modulePath. A --loadModule path or a
load_module / /load-module path outside it is refused with
MODULE_PATH_OUTSIDE_ROOT. This also stops loading code from arbitrary
paths at run time.--hardened requires worker mode, like the sandbox.ProtectSystem=strict,
ReadWritePaths for the write paths above, NoNewPrivileges,
PrivateTmp, MemoryMax, and IPAddressAllow limited to Redis, CouchDB
and operator-approved hosts.New entries in lib/error-info.en-US.json and lib/error-info.zh-CN.json,
each head text saying what to do on its own (the worker hop keeps only the
code, lib/handler-ctx.js):
| Code | Meaning |
|---|---|
MODULE_SANDBOX_REFUSED |
the module failed a load-time check in enforce (permissions syntax, not self-contained, native code) |
MODULE_RESTARTING |
the module’s worker exited and is restarting; retry after the given time |
MODULE_SUSPENDED |
the module exceeded the restart limit; an operator must restart it |
RATE_LIMITED |
(worker-side) too many messages to the main thread |
MODULE_PATH_OUTSIDE_ROOT |
--hardened: the module path is not under --modulePath |
| Flag | Default | Section |
|---|---|---|
--moduleSandbox off\|audit\|enforce |
audit (off without --workerThread) |
1 |
--modulePolicy <file> |
none | 2 |
--moduleMessageRate <n> |
2000 | 4 |
--hardened |
off | 5 |
docs/security-model.md — rewritten around this design: the layers, what
each stops, the “strong barrier, not a hard boundary” statement, the
accepted gaps.docs/module-development.md — declaring permissions, the self-contained
rule, no native addons, env vars, limits, what MODULE_RESTARTING and
MODULE_SUSPENDED mean.docs/cli-and-api-reference.md — the new flags and the sandbox status
key.CHANGELOG.md — including the crash-restart behaviour change.| Area | What the tests prove |
|---|---|
| Lockdown | Each blocked route in enforce fails with Node’s own error type and a host log line; in audit it works and logs once. Routes: process.dlopen, process.binding, process.kill, child_process, worker_threads, v8, module internals, a NODE_PATH require of a countinghouse internal, CHUtil.loadFile outside the module, CHUtil.request to an undeclared host. |
| Validator | Permission syntax cases; a dependency outside the tree; a .node file; an install-script warning. |
| Policy | Narrowing; a wider operator entry ignored and reported; enforce without an entry; audit granting the declaration; approve: as-declared; the startup effective-permissions line; policy re-read on restart. |
| Env | Only declared, approved names are visible; policy value beats server env. |
| Limits | Heap, external memory, blocked loop, message rate; in-flight calls get MODULE_RESTARTING; backoff timing; suspend on the third exit; counter reset; a crash takes the same path; operator restart clears a suspension; deliberate exits do not count; the sandbox status key. |
--hardened |
Starts under the permission model; a module cannot read /proc/self/environ or /proc/self/mem; a module path outside --modulePath is refused; authoring tools and SQLite auth still work with their flags. |
off |
Startup warning; no check runs; crash behaviour as today. |
| No regressions | The existing suite runs under the default audit; the direct-peer-channel tests and the test6/test7 benchmarks show no slowdown. |
Ports: the next free range above the suite’s current maximum (9602–9604
are taken by test/module-loading/12-reload-fresh-code.js).
fs and network (parts 2–4), module data directories and
uninstall (part 2).--workerThread the default (separate change).lib/device-config.js now reads files). To be
revisited after this part, so env values and DeviceConfig end up as one
configuration story.Part 2 (2026-10-17-module-sandbox-fs-broker-design.md, 8.0.0) changes
three things this spec says:
off is no longer “today’s behaviour” for files. Under
--moduleSandbox off in worker mode the file broker still runs: modules
see virtual paths (/app, /data, /tmp), the link rules apply, and
every file call is a hop to the main thread. Where this spec says off
adds no new hop, that no longer holds for file calls. off still turns
off the lockdown, the limits, the policy and violation logging, as this
spec says. Within part 2’s file broker, off also makes no host checks,
which keeps its hop cheap (part 2 spec, §3).MODULE_NAME_MISMATCH), off and
single-thread mode included, and the policy is looked up by the
package.json name.--hardened’s grants (§5): it also grants read and write on
--moduleDataPath, creates that directory before relaunching, and grants
read on countinghouse’s dependency code roots outside its install
directory.The known gap accepted here, module code borrowing countinghouse’s loaded modules to reach files, is closed for files by part 2’s bounded loader. Access to the objects themselves remains (part 2 spec, “Gaps that remain”).
Worker mode became the default in the same release (part 2 spec, §5).