Compare commits

...

7 Commits

Author SHA1 Message Date
Quixos Subtree Publisher 9a211ee5d7 Publish quixos-nix-helpers from abc91ab1cbbd61ffd7f0a49dbc5768598ac8745c 2026-10-08 00:03:01 +00:00
Timothy J. Aveni dbd159be70 Keep checked browser runtime versions independent of authority upgrades 2026-10-07 17:03:01 -07:00
Timothy J. Aveni d6e66b537f Pool host-approved restricted code with scoped and fair graph execution 2026-10-07 16:47:19 -07:00
Timothy J. Aveni 929fdb4a28 Reuse restricted engines with fresh invocation state and revocable ports 2026-10-07 16:14:15 -07:00
Timothy J. Aveni f934347041 Bound checked candidate metadata and restricted invocation resources 2026-10-07 15:51:22 -07:00
Quixos Subtree Publisher ea923c40c4 Publish quixos-nix-helpers from 039f055a7dcff2a29d59a8c37d7433b269b50f7a 2026-10-07 11:04:32 +00:00
Timothy J. Aveni 47fcb47d5c Implement VM-scoped restricted registry transport 2026-10-07 04:04:32 -07:00
11 changed files with 1599 additions and 6 deletions
+1 -1
View File
@@ -1,7 +1,7 @@
{
"version": 1,
"sourceRepo": "https://gitea-external.egads.tutti.syntaxblitz.net/quixos/quixos",
"sourceCommit": "e5aec2bb26110ed474929f353ee51ff46d4f20d6",
"sourceCommit": "abc91ab1cbbd61ffd7f0a49dbc5768598ac8745c",
"sourcePath": "quixos-instance/quixos-nix-helpers",
"exportName": "quixos-nix-helpers",
"mirrorRemote": "https://gitea-external.egads.tutti.syntaxblitz.net/quixos/quixos-nix-helpers.git"
+56
View File
@@ -91,3 +91,59 @@ proves that a component-only edit preserves a mixed package's service digest.
Run `nix run .#camino-component-source-qualification` from the monorepo to
materialize separate retained Git resources and compile an ordinary Nix candidate.
This is a source/build qualification harness; it does not deploy a workspace.
## Restricted execution in a workspace VM
Add `service.restricted = true` to a checked portable package to select the pinned
`workerd` executor. Generated bindings and the ordinary transaction-port protocol
stay the same. All server exports must belong to one checked portable registry;
remote exports and custom process services retain their ordinary VM execution
path. The restricted build rejects Node imports and unresolved dependencies,
and supplies an explicit SDK for value codecs, identities and declared graph ports.
```nix
service = {
restricted = true;
limits = {
deadlineMs = 4000;
maxBytes = 1048576;
maxPortCalls = 1000;
maxQueued = 8;
};
};
```
Each invocation gets a fresh engine process. The adapter admits one active frame
and a bounded FIFO; queue wait consumes the deadline. Overflow is an explicit
`RESTRICTED_QUEUE_FULL` result. Cancellation kills the engine process group and
removes its sockets before acknowledgement. All graph calls inherit the trusted
invocation identity; authored code cannot choose another frame or workspace.
Native graph grants and transaction commit remain enforced by Camino outside
the guest. Initialization and synchronous loops are subject to the same deadline.
Direct network access, native filesystem imports, ambient clock and entropy,
parent environment credentials, and unlisted modules are denied. Explicit dates,
`Intl.Segmenter`, deterministic hashes and normal JavaScript computation remain
available. Host-managed HTTP bridges expose only the current frame's declared
graph ports. Authored serialization is untrusted protocol input.
This is an inner execution restriction, **not a hardened shared-process sandbox**.
One workspace owns the surrounding VM. Systemd limits the entire package cgroup,
including adapter and child engines; memory exhaustion terminates that group.
No per-isolate memory protection is claimed. A guest user can control its VM,
so authoritative graph grants and credentials must remain outside it.
Qualification commands:
```sh
nix build .#checks.x86_64-linux.camino-restricted-execution
nix build .#checks.x86_64-linux.camino-restricted-package-runners
nix build .#checks.x86_64-linux.camino-restricted-execution-vm
```
The first uses the actual pinned engine for frame isolation, graph ports,
SDK codecs, denied ambient access, cancellation and overload. The second runs
ordinary package dispatch, rollback, PostgreSQL and browser replica tests with
the restricted reader fixture. The VM check adds actual cgroup allocation
exhaustion, neighboring-service survival, native socket egress rejection and
fresh-frame timing. VM qualification is independent of hosted rollout.
+12
View File
@@ -96,6 +96,18 @@ let
esbuild = "${pkgs.esbuild}/bin/esbuild";
shell = "${pkgs.runtimeShell}";
serviceAdapter = ./portable-service.mjs;
restricted =
if service.restricted or false then
let
executor = import ./restricted-execution { inherit pkgs core; };
in
{
runtime = "${executor.runtime}/bin/quixos-restricted-registry";
sdk = "${executor.sdk}/core.mjs";
limits = service.limits or { };
}
else
null;
}
);
compiled =
+4 -3
View File
@@ -128,7 +128,8 @@ for (const { target, mode, settings } of builds) {
const bundlePath =
mode === "remote" ? "share/quixos/remote/server/module.mjs" : `share/quixos/portable/${target}/module.mjs`;
await fs.mkdir(path.dirname(path.join(output, bundlePath)), { recursive: true });
const coreImport = target === "browser" ? coreURL : coreServer;
const restricted = !!config.restricted && target === "server";
const coreImport = target === "browser" ? coreURL : restricted ? config.restricted.sdk : coreServer;
const metadata = path.join(work, "bundle-meta.json");
measureBuild("portable-bundle", { package: pkg.revision, target, mode }, () =>
execFileSync(
@@ -136,7 +137,7 @@ for (const { target, mode, settings } of builds) {
[
entry,
"--bundle",
`--platform=${target === "browser" ? "browser" : "node"}`,
`--platform=${target === "browser" || restricted ? "browser" : "node"}`,
"--format=esm",
"--minify-whitespace",
"--target=es2024",
@@ -158,7 +159,7 @@ for (const { target, mode, settings } of builds) {
(i) =>
i.external &&
i.path !== coreImport &&
!(target === "server" && builtinModules.includes(i.path.replace(/^node:/, ""))),
!(target === "server" && !restricted && builtinModules.includes(i.path.replace(/^node:/, ""))),
),
)
)
+56
View File
@@ -13,6 +13,62 @@ export async function buildService({
recordFile,
}) {
const relative = compiler.artifactPath;
if (config.restricted) {
if (config.service.entry || pkg.exports.some((e) => e.execution.kind === "remote"))
throw Error(
"Restricted services require portable snapshot/transaction exports; remote/custom services keep their VM path",
);
const modules = implementations.filter((i) => i.target === "server");
if (modules.length !== 1 || pkg.exports.some((e) => !modules[0].exports.includes(e.id)))
throw Error("Restricted service requires exactly one checked portable registry covering all exports");
const limits = config.restricted.limits;
if (!limits || typeof limits !== "object" || Array.isArray(limits))
throw Error("Restricted limits must be an object");
if (Object.keys(limits).some((key) => !["deadlineMs", "maxBytes", "maxPortCalls", "maxQueued"].includes(key)))
throw Error("Unknown restricted service limit");
for (const [key, min, max] of [
["deadlineMs", 1, 60000],
["maxBytes", 1024, 4194304],
["maxPortCalls", 1, 10000],
["maxQueued", 0, 64],
])
if (limits[key] !== undefined && (!Number.isSafeInteger(limits[key]) || limits[key] < min || limits[key] > max))
throw Error("Invalid restricted service limit " + key);
await fs.mkdir(path.join(output, "bin"), { recursive: true });
await fs.mkdir(path.join(output, "share/quixos/service"), { recursive: true });
const configFile = "share/quixos/service/restricted.json";
const module = modules[0];
await fs.writeFile(
path.join(output, configFile),
JSON.stringify({
module: path.relative("share/quixos/service", module.path),
registryExport: module.registryExport,
exports: module.exports,
sdk: [{ name: config.restricted.sdk, path: config.restricted.sdk }],
...limits,
}),
);
await fs.writeFile(
path.join(output, "bin/service"),
`#!${config.shell}\nservice_root=\${0%/*}/..\nexec ${config.restricted.runtime} "$service_root/${configFile}"\n`,
{ mode: 0o755 },
);
const body = {
id: "service",
target: "server",
compatibility: "quixos-service-v1",
path: "bin/service",
ports: "quixos-transaction-ports-v1",
exports: module.exports,
files: [
await recordFile("bin/service", "text/x-shellscript"),
await recordFile(configFile, "application/json"),
...module.files,
],
};
implementations.unshift({ ...body, contentDigest: compiler.implementationDigest(body) });
return;
}
if (pkg.exports.length || config.service.entry) {
await fs.mkdir(path.join(output, "bin"), { recursive: true });
await fs.mkdir(path.join(output, "share/quixos/service"), { recursive: true });
+6 -2
View File
@@ -8,6 +8,10 @@ builtins.path {
let
name = builtins.baseNameOf filename;
in
type == "directory"
|| (builtins.match ".*\\.mjs" name != null && builtins.match ".*\\.test\\.mjs" name == null);
(type == "directory" && filename == toString ./.)
|| (
builtins.dirOf filename == toString ./.
&& builtins.match ".*\\.mjs" name != null
&& builtins.match ".*\\.test\\.mjs" name == null
);
}
+47
View File
@@ -0,0 +1,47 @@
{ pkgs, core }:
let
workerd = import ./workerd.nix { inherit pkgs; };
# Transaction-port/value adapters do not need the browser's CRDT/Wasm engine.
# Keep this surface explicit; it is bundled into checked restricted handlers.
sdk = pkgs.runCommand "quixos-restricted-sdk" { nativeBuildInputs = [ pkgs.esbuild ]; } ''
mkdir -p "$out"
cat > entry.mjs <<'JS'
export {definePortableRegistry,QxReject} from '${core}/dist/portable.js';
export {encodeArgument,decodeArgument,canonicalJson,parseJson} from '${core}/dist/value.js';
export {workspaceId,operationId,objectId,entryId,hashIdentity} from '${core}/dist/identity.js';
export {reference} from '${core}/dist/references.js';
export {CodecError,ExecutionError} from '${core}/dist/limits.js';
JS
esbuild entry.mjs --bundle --platform=neutral --format=esm --target=es2024 --outfile="$out/core.mjs"
'';
runtime =
pkgs.runCommand "quixos-restricted-execution" { nativeBuildInputs = [ pkgs.makeWrapper ]; }
''
mkdir -p "$out/lib" "$out/bin"
cp ${./service.mjs} "$out/lib/service.mjs"
cp ${./worker.mjs} "$out/lib/worker.mjs"
makeWrapper ${pkgs.nodejs_24}/bin/node "$out/bin/quixos-restricted-registry" \
--add-flags "$out/lib/service.mjs" \
--set QUIXOS_RESTRICTED_WORKERD ${workerd}/bin/workerd \
--set QUIXOS_RESTRICTED_WORKER "$out/lib/worker.mjs"
'';
qualification =
pkgs.runCommand "quixos-restricted-execution-qualification"
{
nativeBuildInputs = [ pkgs.nodejs_24 ];
QUIXOS_TEST_WORKERD = "${workerd}/bin/workerd";
QUIXOS_TEST_SDK = "${sdk}/core.mjs";
}
''
node --test ${./.}/service.test.mjs
touch "$out"
'';
in
{
inherit
workerd
sdk
runtime
qualification
;
}
+668
View File
@@ -0,0 +1,668 @@
import { spawn } from "node:child_process";
import { randomUUID } from "node:crypto";
import { createServer, request as httpRequest } from "node:http";
import { mkdtemp, readFile, writeFile, rm, open } from "node:fs/promises";
import { constants } from "node:fs";
import { tmpdir } from "node:os";
import { join, dirname } from "node:path";
const abi = "quixos-transaction-ports-v1";
const fixedError = (code) => Object.assign(Error(code), { code });
const object = (v) => !!v && typeof v === "object" && !Array.isArray(v);
const absolute = (value) =>
typeof value === "string" &&
value.startsWith("/") &&
!/[\s\u0000-\u001f]/.test(value) &&
!value.split("/").includes("..");
/** Host-wide engine reservations. Only trusted adapters hold these callbacks;
* workers cannot alter admission or evict another invocation's engine. */
export class RestrictedEngineBudget {
#leases = new Set();
constructor(limit = 8, reserve = async () => ({})) {
if (!Number.isSafeInteger(limit) || limit < 1 || limit > 64) throw fixedError("INVALID_ENGINE_BUDGET");
this.limit = limit;
this.reserve = reserve;
}
async acquire(idle, evict) {
while (this.#leases.size >= this.limit) {
const victim = [...this.#leases].find((entry) => entry.idle());
if (!victim) throw fixedError("RESTRICTED_ENGINE_LIMIT");
await victim.evict();
}
const lease = { idle, evict };
this.#leases.add(lease);
try {
const resource = await this.reserve();
let releasing;
const release = () =>
(releasing ??= (async () => {
try {
await resource.release?.();
} finally {
this.#leases.delete(lease);
}
})());
release.attach = resource.attach;
return release;
} catch (error) {
this.#leases.delete(lease);
throw error;
}
}
stats() {
return { engines: this.#leases.size, limit: this.limit };
}
}
async function boundedSource(path, maximum, code) {
const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
try {
const stat = await handle.stat();
if (!stat.isFile() || stat.size > maximum) throw fixedError(code);
const bytes = Buffer.alloc(stat.size + 1);
let offset = 0;
while (offset < bytes.length) {
const read = await handle.read(bytes, offset, bytes.length - offset, offset);
if (!read.bytesRead) break;
offset += read.bytesRead;
}
if (offset !== stat.size) throw fixedError(code);
return new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, offset));
} finally {
await handle.close();
}
}
/** Trusted stdio adapter inside one workspace VM. Engine processes never own
* coordinator credentials. The supervising service must impose VM/OS limits.
* Each engine runs one fresh Worker per invocation. Host tokens expire before
* reuse; cancellation and watchdogs destroy the affected engine, not neighbors. */
export async function serveRestrictedRegistry(config, io = process) {
if (
!object(config) ||
!absolute(config.workerd) ||
!absolute(config.worker) ||
!absolute(config.module) ||
!/^[$A-Z_a-z][$\w]*$/.test(config.registryExport) ||
!Array.isArray(config.exports) ||
!config.exports.length ||
config.exports.length > 10000 ||
config.exports.some((x) => typeof x !== "string" || !x || x.length > 4096) ||
new Set(config.exports).size !== config.exports.length ||
!Array.isArray(config.sdk) ||
config.sdk.length > 8 ||
config.sdk.some(
(m) =>
!object(m) ||
!absolute(m.path) ||
typeof m.name !== "string" ||
!m.name ||
/[\u0000-\u001f]/.test(m.name) ||
["entry.mjs", "package.mjs"].includes(m.name),
) ||
new Set(config.sdk.map((m) => m.name)).size !== config.sdk.length
)
throw fixedError("INVALID_RESTRICTED_CONFIGURATION");
const limits = {
maxBytes: config.maxBytes ?? 1024 * 1024,
maxPortCalls: config.maxPortCalls ?? 1000,
deadlineMs: config.deadlineMs ?? 4000,
maxQueued: config.maxQueued ?? 8,
maxActive: config.maxActive ?? 2,
maxNested: config.maxNested ?? 4,
engineIdleMs: config.engineIdleMs ?? 30000,
};
if (
!Number.isSafeInteger(limits.maxBytes) ||
limits.maxBytes < 1024 ||
limits.maxBytes > 4 * 1024 * 1024 ||
!Number.isSafeInteger(limits.maxPortCalls) ||
limits.maxPortCalls < 1 ||
limits.maxPortCalls > 10000 ||
!Number.isSafeInteger(limits.deadlineMs) ||
limits.deadlineMs < 1 ||
limits.deadlineMs > 60000 ||
!Number.isSafeInteger(limits.maxQueued) ||
limits.maxQueued < 0 ||
limits.maxQueued > 64 ||
!Number.isSafeInteger(limits.maxActive) ||
limits.maxActive < 1 ||
limits.maxActive > 16 ||
!Number.isSafeInteger(limits.maxNested) ||
limits.maxNested < 1 ||
limits.maxNested > 16 ||
!Number.isSafeInteger(limits.engineIdleMs) ||
limits.engineIdleMs < 1 ||
limits.engineIdleMs > 60000
)
throw fixedError("INVALID_RESTRICTED_LIMITS");
const packageSource = await boundedSource(config.module, 1024 * 1024, "RESTRICTED_SOURCE_LIMIT");
const workerSource = await boundedSource(config.worker, 65536, "RESTRICTED_ENTRY_LIMIT");
const sdk = [];
for (const m of config.sdk)
sdk.push({ ...m, source: await boundedSource(m.path, 2 * 1024 * 1024, "RESTRICTED_SDK_LIMIT") });
const engineBudget = config.engineBudget ?? new RestrictedEngineBudget(limits.maxActive + limits.maxNested);
const active = new Map(),
engines = new Set(),
idleEngines = [];
const metrics = { starts: 0, reused: 0, completed: 0, peakRSSBytes: 0 };
let buffered = Buffer.alloc(0),
stopped = false,
failure;
const queued = [];
const send = (value) => {
if (stopped) return;
const line = JSON.stringify({ abi, ...value }) + "\n";
if (
Buffer.byteLength(line) > limits.maxBytes ||
io.stdout.writableLength + Buffer.byteLength(line) > limits.maxBytes * 2
)
throw fixedError("RESTRICTED_BACKPRESSURE");
io.stdout.write(line);
};
// Linux USER_HZ is 100 on the supported NixOS architectures. Read process
// CPU outside the engine; authored code cannot forge these usage messages.
const sampleCPU = async (call) => {
if (!call.child?.pid) return;
let text;
try {
text = await readFile(`/proc/${call.child.pid}/stat`, "utf8");
} catch (error) {
if (error.code === "ENOENT" || error.code === "ESRCH") return;
throw error;
}
const fields = text.slice(text.lastIndexOf(")") + 2).split(" ");
const total = (Number(fields[11]) + Number(fields[12])) * 10000;
const cpuMicroseconds = total - (call.cpuBaseline ?? 0);
if (call.engine) call.engine.cpuTotal = total;
if (!Number.isSafeInteger(cpuMicroseconds) || cpuMicroseconds < (call.cpuMicroseconds ?? 0))
throw fixedError("RESTRICTED_CPU_ACCOUNTING");
if (cpuMicroseconds !== (call.cpuMicroseconds ?? 0)) {
call.cpuMicroseconds = cpuMicroseconds;
send({ kind: "usage", invocation: call.message.invocation, frame: call.message.frame, cpuMicroseconds });
}
};
const watchCPU = (call) => {
call.cpuTimer = setTimeout(() => {
call.cpuRead = sampleCPU(call).then(() => {
if (call.open) watchCPU(call);
});
void call.cpuRead.catch(fail);
}, 20);
};
const retire = async (call, reason) => {
if (call.retiring) return call.retiring;
call.open = false;
call.retiring = (async () => {
clearTimeout(call.timer);
clearTimeout(call.cpuTimer);
const index = queued.indexOf(call);
if (index >= 0) queued.splice(index, 1);
for (const pending of call.pending.values()) pending.reject(reason);
call.pending.clear();
// Cancellation can arrive during async directory/socket preparation.
// Wait for it to settle before claiming every process/handle is gone.
await call.preparing?.catch(() => {});
clearTimeout(call.cpuTimer);
await call.cpuRead?.catch(() => {});
let usageFailure;
try {
await sampleCPU(call);
} catch (error) {
usageFailure = error;
}
const engine = call.engine;
if (engine) {
// Revoke the frame token before returning an engine to the idle pool.
// A delayed child request can never acquire the next call's authority.
if (engine.current === call) engine.current = null;
if (!stopped && reason.code === "INVOCATION_ENDED" && !usageFailure && !engine.destroying) {
const status = await readFile(`/proc/${engine.child.pid}/status`, "utf8").catch(() => "");
const rss = Number(status.match(/^VmRSS:\s+(\d+)/m)?.[1] ?? Infinity) * 1024;
metrics.peakRSSBytes = Math.max(metrics.peakRSSBytes, rss);
// Bound retained engine heaps as well as lifetime. Hard aggregate
// physical memory remains the supervising process/cgroup's contract.
if (rss <= 128 * 1024 * 1024) {
idleEngines.push(engine);
engine.idleTimer = setTimeout(() => void destroyEngine(engine).catch(fail), limits.engineIdleMs);
} else await destroyEngine(engine);
} else await destroyEngine(engine);
}
active.delete(call.message.invocation);
if (usageFailure) throw usageFailure;
})();
return call.retiring;
};
const fail = (error) => {
if (failure) return failure;
stopped = true;
return (failure = (async () => {
io.stdin.destroy();
for (const call of [...queued]) await retire(call, error);
await Promise.all([...active.values()].map((call) => retire(call, error)));
await Promise.all([...engines].map(destroyEngine));
io.stdout.end();
io.exitCode = 1;
})());
};
const body = async (stream) => {
const chunks = [];
let bytes = 0;
for await (const chunk of stream) {
bytes += chunk.length;
if (bytes > limits.maxBytes) throw fixedError("RESTRICTED_MESSAGE_LIMIT");
chunks.push(chunk);
}
return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks)));
};
const destroyEngine = async (engine) => {
if (engine.destroying) return engine.destroying;
engine.destroying = (async () => {
clearTimeout(engine.idleTimer);
const index = idleEngines.indexOf(engine);
if (index >= 0) idleEngines.splice(index, 1);
engine.current = null;
if (engine.child?.pid) {
try {
process.kill(-engine.child.pid, "SIGKILL");
} catch (error) {
if (error.code !== "ESRCH") throw error;
}
await engine.exited;
}
engine.server?.closeAllConnections();
if (engine.server) await new Promise((resolve) => engine.server.close(resolve));
try {
if (engine.directory) await rm(engine.directory, { recursive: true, force: true });
} finally {
engines.delete(engine);
await engine.release?.();
}
})();
return engine.destroying;
};
const prepareEngine = async (call) => {
const cached = idleEngines.pop();
if (cached) {
clearTimeout(cached.idleTimer);
cached.current = call;
call.engine = cached;
call.child = cached.child;
call.cpuBaseline = cached.cpuTotal ?? 0;
metrics.reused++;
watchCPU(call);
return;
}
const engine = { current: call, cpuTotal: 0 };
engines.add(engine);
call.engine = engine;
engine.release = await engineBudget.acquire(
() => !engine.current && !engine.destroying,
() => destroyEngine(engine),
);
if (!call.open) return;
engine.directory = await mkdtemp(join(tmpdir(), "qx-engine-"));
if (!call.open) return;
const broker = join(engine.directory, "broker.sock");
engine.socket = join(engine.directory, "engine.sock");
engine.server = createServer(async (request, response) => {
const call = engine.current;
const message = call?.message;
try {
if (!call?.open || request.method !== "POST" || request.url !== "/port/" + call.token)
throw fixedError("EXPIRED_CONTEXT");
const port = await body(request);
if (
!call.open ||
!object(port) ||
Object.keys(port).some((key) => !["portId", "action", "input", "key"].includes(key)) ||
typeof port.portId !== "string" ||
!object(port.action) ||
!Object.hasOwn(port, "input")
)
throw fixedError("INVALID_RESTRICTED_PORT");
if (
++call.sequence > Math.min(limits.maxPortCalls, message.budget?.calls ?? limits.maxPortCalls) ||
call.pending.size >= limits.maxPortCalls
)
throw fixedError("RESTRICTED_PORT_LIMIT");
const sequence = call.sequence;
const result = new Promise((resolve, reject) => call.pending.set(sequence, { resolve, reject }));
void result.catch(() => {});
send({
kind: "port",
invocation: message.invocation,
frame: message.frame,
sequence,
portId: port.portId,
action: { ...port.action, ...(port.key === undefined ? {} : { key: port.key }) },
input: port.input,
});
const value = await result;
if (!call.open) throw fixedError("EXPIRED_CONTEXT");
const encoded = JSON.stringify(value);
if (Buffer.byteLength(encoded) > limits.maxBytes) throw fixedError("RESTRICTED_MESSAGE_LIMIT");
response.writeHead(200, { "content-type": "application/json" });
response.end(encoded);
} catch {
response.writeHead(409);
response.end('{"status":"failed","error":{"code":"RESTRICTED_PORT_FAILED"}}');
}
});
await new Promise((resolve, reject) => {
engine.server.once("error", reject);
engine.server.listen(broker, resolve);
});
const modules = { "entry.mjs": { js: workerSource }, "package.mjs": { js: packageSource } };
for (const module of sdk) modules[module.name] = { js: module.source };
const setting = { registryExport: config.registryExport, exports: config.exports, maxBytes: limits.maxBytes };
// The parent contains immutable checked source only. It never imports the
// authored module or keeps a child stub, request, result or frame handle.
const parent = `const modules=${JSON.stringify(modules)}, setting=${JSON.stringify(setting)};
export default {async fetch(request,env) {
const input=await request.json();
const child=env.LOADER.load({compatibilityDate:"2026-10-05",mainModule:"entry.mjs",modules,
globalOutbound:null,env:{BROKER:env.BROKER,CONFIG:{...setting,frameToken:input.frameToken}}});
const response=await child.getEntrypoint().fetch(new Request("http://invocation/",{
method:"POST",body:JSON.stringify(input.message)}));
const body=await response.arrayBuffer();
return new Response(body,{status:response.status,headers:response.headers});
}};`;
await writeFile(join(engine.directory, "parent.mjs"), parent);
const configuration = `using Workerd = import "/workerd/workerd.capnp"; const config :Workerd.Config = (
services=[(name="main",worker=(modules=[(name="parent.mjs",esModule=embed "parent.mjs")],
compatibilityDate="2026-10-05",compatibilityFlags=["experimental"],globalOutbound="deny",
bindings=[(name="LOADER",workerLoader=()),(name="BROKER",service="broker")])),
(name="broker",external=(address=${JSON.stringify("unix:" + broker)},http=())),
(name="deny",network=(allow=[]))],
sockets=[(name="frame",address=${JSON.stringify("unix:" + engine.socket)},http=(),service="main")]);`;
const file = join(engine.directory, "config.capnp");
await writeFile(file, configuration);
if (!call.open) return;
engine.child = spawn(config.workerd, ["serve", "--experimental", file], {
detached: true,
env: { TZ: "UTC", LANG: "C.UTF-8" },
cwd: engine.directory,
stdio: ["ignore", "ignore", "pipe"],
});
metrics.starts++;
engine.exited = new Promise((resolve) => {
engine.child.once("exit", resolve);
engine.child.once("error", resolve);
});
call.child = engine.child;
await engine.release.attach?.(engine.child.pid);
watchCPU(call);
let diagnostics = 0;
engine.child.stderr.on("data", (chunk) => {
if ((diagnostics += chunk.length) > 65536) {
if (engine.current?.open) engine.current.terminate("RESTRICTED_DIAGNOSTIC_LIMIT");
else void destroyEngine(engine).catch(fail);
}
});
engine.child.once("error", () => engine.current?.terminate("RESTRICTED_START_FAILED"));
void engine.exited.then(() => {
if (engine.current?.open) engine.current.terminate("RESTRICTED_ENGINE_EXITED");
else void destroyEngine(engine).catch(fail);
});
};
const available = (call) =>
[...active.values()].filter((entry) => entry.nested === call.nested).length <
(call.nested ? limits.maxNested : limits.maxActive);
const pump = () => {
while (!stopped) {
const index = queued.findIndex(available);
if (index < 0) return;
void invoke(queued.splice(index, 1)[0]).catch(fail);
}
};
const finish = async (call, reason, reply) => {
if (reply.kind === "cancelled") call.cancellationReply = reply;
return (call.finished ??= (async () => {
await retire(call, reason);
metrics.lastInvocation = {
queueMs: (call.startedAt ?? performance.now()) - call.receivedAt,
preparationMs: call.preparationMs ?? 0,
roundtripMs: call.roundtripMs ?? 0,
initializationMs: call.initializationMs ?? null,
executionMs: call.executionMs ?? null,
totalMs: performance.now() - call.receivedAt,
};
send(call.cancellationReply ?? reply);
pump();
})());
};
const invoke = async (call) => {
const { message } = call;
call.startedAt = performance.now();
active.set(message.invocation, call);
const terminate = (code) => {
if (!call.open) return;
void finish(call, fixedError(code), {
invocation: message.invocation,
status: "failed",
error: { code, message: code },
}).catch(fail);
};
call.terminate = terminate;
try {
call.token = randomUUID();
call.preparing = prepareEngine(call);
await call.preparing;
call.preparationMs = performance.now() - call.startedAt;
if (!call.open) return;
const roundtripAt = performance.now();
const result = await new Promise((resolve, reject) => {
const attempt = () => {
if (!call.open) {
reject(fixedError("EXPIRED_CONTEXT"));
return;
}
const request = httpRequest(
{ socketPath: call.engine.socket, path: "/", method: "POST", agent: false },
async (response) => {
try {
const result = await body(response);
for (const [header, key] of [
["x-quixos-initialization-ms", "initializationMs"],
["x-quixos-execution-ms", "executionMs"],
]) {
const value = Number(response.headers[header]);
if (Number.isFinite(value) && value >= 0 && value <= limits.deadlineMs) call[key] = value;
}
if (response.statusCode !== 200) throw fixedError("RESTRICTED_PACKAGE_FAILED");
resolve(result);
} catch (error) {
reject(error);
}
},
);
request.once("error", (error) => {
if (call.open && ["ENOENT", "ECONNREFUSED"].includes(error.code)) setTimeout(attempt, 5);
else reject(error);
});
request.end(JSON.stringify({ message, frameToken: call.token }));
};
attempt();
});
call.roundtripMs = performance.now() - roundtripAt;
if (!call.open) return;
if (
!object(result) ||
!["returned", "failed"].includes(result.status) ||
Object.keys(result).some(
(key) => !(result.status === "returned" ? ["status", "output"] : ["status", "error"]).includes(key),
) ||
(result.status === "returned"
? !Object.hasOwn(result, "output")
: !object(result.error) || !/^[A-Z0-9_]{1,128}$/.test(result.error.code))
)
throw fixedError("RESTRICTED_PACKAGE_FAILED");
// Authored code can alter serialization prototypes. Treat even the
// platform worker's JSON as untrusted; never accept routing/ABI fields.
const reply =
result.status === "returned"
? { invocation: message.invocation, status: "returned", output: result.output }
: {
invocation: message.invocation,
status: "failed",
error: { code: result.error.code, message: result.error.code },
};
await finish(call, fixedError("INVOCATION_ENDED"), reply);
metrics.completed++;
} catch (error) {
if (call.open) {
const code = /^RESTRICTED_[A-Z_]+$/.test(error.code ?? "") ? error.code : "RESTRICTED_PACKAGE_FAILED";
await finish(call, error, { invocation: message.invocation, status: "failed", error: { code, message: code } });
}
}
};
const receive = (message) => {
if (!object(message) || message.abi !== abi) throw fixedError("RESTRICTED_ABI_MISMATCH");
if (message.kind === "shutdown") {
void fail(fixedError("SERVICE_SHUTDOWN"));
return;
}
if (message.kind === "invoke") {
if (
!config.exports.includes(message.exportId) ||
!["snapshot", "transaction"].includes(message.effect) ||
typeof message.invocation !== "string" ||
!message.invocation ||
message.invocation.length > 4096 ||
typeof message.frame !== "string" ||
!message.frame ||
message.frame.length > 4096
)
throw fixedError("INVALID_RESTRICTED_INVOCATION");
if (
message.budget !== undefined &&
(!object(message.budget) ||
Object.keys(message.budget).sort().join(",") !== "calls,deadlineMs,depth,root" ||
typeof message.budget.root !== "string" ||
!message.budget.root ||
message.budget.root.length > 4096 ||
!Number.isSafeInteger(message.budget.depth) ||
message.budget.depth < 0 ||
message.budget.depth > 32 ||
!Number.isSafeInteger(message.budget.calls) ||
message.budget.calls < 1 ||
message.budget.calls > 1000000 ||
!Number.isSafeInteger(message.budget.deadlineMs) ||
message.budget.deadlineMs < 1 ||
message.budget.deadlineMs > 60000)
)
throw fixedError("INVALID_RESTRICTED_BUDGET");
if (active.has(message.invocation) || queued.some((call) => call.message.invocation === message.invocation))
throw fixedError("RESTRICTED_DUPLICATE_INVOCATION");
const call = {
message,
receivedAt: performance.now(),
open: true,
pending: new Map(),
sequence: 0,
nested: (message.budget?.depth ?? 0) > 1,
};
// Descendants cannot wait behind ancestors that hold all nested capacity.
// Reject excess fan-out/depth rather than deadlock an admitted call tree.
if (!available(call) && (call.nested || queued.length >= limits.maxQueued)) {
send({
invocation: message.invocation,
status: "failed",
error: { code: "RESTRICTED_QUEUE_FULL", message: "RESTRICTED_QUEUE_FULL" },
});
return;
}
// Deadline includes queue wait: overload cannot extend a transaction frame.
call.timer = setTimeout(
() => {
if (!call.open) return;
void finish(call, fixedError("RESTRICTED_DEADLINE"), {
invocation: message.invocation,
status: "failed",
error: { code: "RESTRICTED_DEADLINE", message: "RESTRICTED_DEADLINE" },
}).catch(fail);
},
Math.min(limits.deadlineMs, message.budget?.deadlineMs ?? limits.deadlineMs),
);
queued.push(call);
pump();
return;
}
const waiting = queued.find(
(call) => call.message.invocation === message.invocation && call.message.frame === message.frame,
);
if (waiting && message.kind === "cancel") {
void finish(waiting, fixedError("INVOCATION_CANCELLED"), {
kind: "cancelled",
invocation: message.invocation,
frame: message.frame,
}).catch(fail);
return;
}
const call = active.get(message.invocation);
if (!call || message.invocation !== call.message.invocation || message.frame !== call.message.frame) {
if (message.kind === "cancel") send({ kind: "cancelled", invocation: message.invocation, frame: message.frame });
else if (message.kind !== "port-result") throw fixedError("RESTRICTED_UNKNOWN_INVOCATION");
return;
}
if (message.kind === "cancel") {
void finish(call, fixedError("INVOCATION_CANCELLED"), {
kind: "cancelled",
invocation: message.invocation,
frame: message.frame,
}).catch(fail);
return;
}
if (message.kind !== "port-result" || !["returned", "failed"].includes(message.status))
throw fixedError("INVALID_RESTRICTED_RESULT");
const pending = call.pending.get(message.sequence);
if (!pending) throw fixedError("RESTRICTED_UNKNOWN_PORT");
call.pending.delete(message.sequence);
pending.resolve(message);
};
io.stdin.on("data", (chunk) => {
if (stopped) return;
try {
let offset = 0;
while (offset < chunk.length) {
const newline = chunk.indexOf(10, offset),
end = newline < 0 ? chunk.length : newline;
if (buffered.length + end - offset > limits.maxBytes) throw fixedError("RESTRICTED_MESSAGE_LIMIT");
buffered = Buffer.concat([buffered, chunk.subarray(offset, end)]);
if (newline < 0) break;
receive(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(buffered)));
buffered = Buffer.alloc(0);
offset = newline + 1;
if (stopped) break;
}
} catch (error) {
void fail(error);
}
});
io.stdin.on("end", () => void fail(fixedError("COORDINATOR_DISCONNECTED")));
io.stdin.on("error", (error) => void fail(error));
io.stdout.on("error", (error) => void fail(error));
send({ kind: "ready", exports: config.exports });
return {
close: () => fail(fixedError("SERVICE_SHUTDOWN")),
stats: () => ({
...metrics,
active: active.size,
queued: queued.length,
engines: engines.size,
idle: idleEngines.length,
}),
};
}
if (process.argv[1] === new URL(import.meta.url).pathname) {
const config = JSON.parse(await readFile(process.argv[2], "utf8"));
await serveRestrictedRegistry({
...config,
workerd: process.env.QUIXOS_RESTRICTED_WORKERD,
worker: process.env.QUIXOS_RESTRICTED_WORKER,
module: join(dirname(process.argv[2]), config.module),
});
}
+598
View File
@@ -0,0 +1,598 @@
import test from "node:test";
import assert from "node:assert/strict";
import { PassThrough } from "node:stream";
import { mkdtemp, writeFile, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { fileURLToPath } from "node:url";
import { serveRestrictedRegistry, RestrictedEngineBudget } from "./service.mjs";
const workerd = process.env.QUIXOS_TEST_WORKERD;
if (!workerd) throw Error("Set QUIXOS_TEST_WORKERD to the pinned engine");
const worker = fileURLToPath(new URL("./worker.mjs", import.meta.url));
const abi = "quixos-transaction-ports-v1";
let next = 0;
async function fixture(source, options = {}) {
const directory = await mkdtemp(join(tmpdir(), "qx-restricted-test-"));
const module = join(directory, "module.mjs");
await writeFile(module, source);
const io = { stdin: new PassThrough(), stdout: new PassThrough(), exitCode: 0 };
const waiting = [],
queued = [];
const usage = [];
let buffer = "";
io.stdout.on("data", (chunk) => {
buffer += chunk;
let index;
while ((index = buffer.indexOf("\n")) >= 0) {
const value = JSON.parse(buffer.slice(0, index));
buffer = buffer.slice(index + 1);
if (value.kind === "usage") {
usage.push(value);
continue;
}
if (waiting.length) waiting.shift()(value);
else queued.push(value);
}
});
const receive = async () => {
if (queued.length) return queued.shift();
let timer;
try {
return await Promise.race([
new Promise((resolve) => waiting.push(resolve)),
new Promise((_, reject) => {
timer = setTimeout(() => reject(Error("TEST_MESSAGE_TIMEOUT")), 5000);
}),
]);
} finally {
clearTimeout(timer);
}
};
const service = await serveRestrictedRegistry(
{ workerd, worker, module, registryExport: "registry", exports: ["test"], sdk: [], ...options },
io,
);
assert.deepEqual(await receive(), { abi, kind: "ready", exports: ["test"] });
const send = (value) => io.stdin.write(JSON.stringify({ abi, ...value }) + "\n");
const start = (input = null, budget) => {
const invocation = "invoke-" + ++next,
frame = "frame-" + next;
send({
kind: "invoke",
invocation,
frame,
exportId: "test",
workspace: "workspace:restricted",
receiver: null,
input,
effect: "snapshot",
...(budget ? { budget } : {}),
});
return { invocation, frame };
};
return {
io,
receive,
send,
start,
usage,
stats: service.stats,
async close() {
await service.close();
await rm(directory, { recursive: true, force: true });
},
};
}
const registry = (code) => `export const registry={exports:['test'],async invoke(request,channel){${code}}};`;
test("parallel frames route independently and cancellation cannot retire a neighbor", async () => {
const f = await fixture(
registry("return await channel({portId:'read',action:{kind:'state',primitive:'read'},input:request.input});"),
);
try {
const first = f.start("a"),
second = f.start("b");
const ports = new Map([await f.receive(), await f.receive()].map((port) => [port.invocation, port]));
assert.equal(ports.get(first.invocation).input, "a");
assert.equal(ports.get(second.invocation).input, "b");
f.send({ kind: "cancel", ...first });
assert.equal((await f.receive()).kind, "cancelled");
f.send({
kind: "port-result",
...first,
sequence: ports.get(first.invocation).sequence,
status: "returned",
output: "late",
});
f.send({
kind: "port-result",
...second,
sequence: ports.get(second.invocation).sequence,
status: "returned",
output: "survived",
});
const result = await f.receive();
assert.equal(result.invocation, second.invocation);
assert.equal(result.output, "survived");
assert.equal(f.io.exitCode, 0);
} finally {
await f.close();
}
});
test("A to B to A uses reserved nested capacity while both root lanes are saturated", async () => {
const source = registry(
"if(request.input==='leaf')return 'done'; return await channel({portId:'next',action:{kind:'state',primitive:'read'},input:request.input});",
);
const a = await fixture(source, { maxActive: 1, maxNested: 1, maxQueued: 1 });
const b = await fixture(source, { maxActive: 1, maxNested: 1, maxQueued: 1 });
const budget = (depth) => ({ root: "root-chain", depth, deadlineMs: 2000, calls: 20 });
try {
const parent = a.start("B", budget(1)),
aPort = await a.receive();
const neighbor = b.start("held", { ...budget(1), root: "other-root" });
await b.receive();
const child = b.start("A", budget(2)),
bPort = await b.receive();
const leaf = a.start("leaf", budget(3));
const leafResult = await a.receive();
assert.equal(leafResult.invocation, leaf.invocation);
assert.equal(leafResult.output, "done");
b.send({ kind: "port-result", ...child, sequence: bPort.sequence, status: "returned", output: leafResult.output });
const childResult = await b.receive();
a.send({
kind: "port-result",
...parent,
sequence: aPort.sequence,
status: "returned",
output: childResult.output,
});
assert.equal((await a.receive()).output, "done");
b.send({ kind: "cancel", ...neighbor });
assert.equal((await b.receive()).kind, "cancelled");
} finally {
await a.close();
await b.close();
}
});
test("the remaining root wall budget overrides a longer adapter deadline", async () => {
const f = await fixture(
registry("return await channel({portId:'held',action:{kind:'state',primitive:'read'},input:null});"),
{ deadlineMs: 2000 },
);
try {
const started = performance.now();
f.start(null, { root: "short-root", depth: 2, deadlineMs: 150, calls: 10 });
await f.receive();
const result = await f.receive();
assert.equal(result.error.code, "RESTRICTED_DEADLINE");
assert.ok(performance.now() - started < 1000);
} finally {
await f.close();
}
});
test("real engine returns results and resets all globals between frames", async () => {
const f = await fixture(
registry(
"globalThis.retained=(globalThis.retained??0)+1; return {count:globalThis.retained,text:new Intl.Segmenter('zh',{granularity:'word'}).segment('雨后的书店').containing(3).segment};",
),
);
try {
for (let n = 0; n < 3; n++) {
const call = f.start();
const result = await f.receive();
assert.equal(result.invocation, call.invocation);
assert.equal(result.status, "returned");
assert.equal(result.output.count, 1);
assert.equal(typeof result.output.text, "string");
}
} finally {
await f.close();
}
});
test("captured frame is the sole source of nested port identities", async () => {
const f = await fixture(
registry("return await channel({portId:'read',action:{kind:'state',primitive:'read'},input:null});"),
);
try {
const call = f.start();
const port = await f.receive();
assert.equal(port.kind, "port");
assert.equal(port.frame, call.frame);
assert.equal(port.invocation, call.invocation);
f.send({ kind: "port-result", ...call, sequence: port.sequence, status: "returned", output: 42 });
const result = await f.receive();
assert.equal(result.status, "returned");
assert.equal(result.output, 42);
} finally {
await f.close();
}
});
test("authored serialization cannot forge result routing or ABI fields", async () => {
const f = await fixture(
registry(
"Object.prototype.toJSON=function(){return this.status==='returned'?{status:'returned',output:42,invocation:'forged',abi:'forged'}:this;};return 42;",
),
);
try {
const call = f.start();
const result = await f.receive();
assert.equal(result.invocation, call.invocation);
assert.equal(result.abi, abi);
assert.equal(result.status, "failed");
assert.equal(result.error.code, "RESTRICTED_PACKAGE_FAILED");
} finally {
await f.close();
}
});
test("the checked portable SDK keeps codecs and nested graph ports inside the frame", async () => {
const sdk = process.env.QUIXOS_TEST_SDK;
assert.ok(sdk, "Set QUIXOS_TEST_SDK to the checked portable SDK");
const C = await import(sdk),
workspace = C.workspaceId("workspace:restricted");
const integer = { kind: "scalar", name: "int64" },
unit = { kind: "builtin", name: "unit" };
const declarations = [
{
id: "test",
name: "test",
effect: "snapshot",
receiver: null,
input: integer,
output: integer,
methods: [
{
name: "get",
portName: "count",
portId: "count-read",
action: { kind: "state", primitive: "read" },
input: unit,
output: integer,
keyed: false,
},
],
},
];
const source = `import {definePortableRegistry} from 'qx:core'; export const registry=definePortableRegistry(${JSON.stringify(declarations)},{test:async ctx=>ctx.input+await ctx.ports.count.get()});`;
const f = await fixture(source, { sdk: [{ name: "qx:core", path: sdk }] });
try {
const call = f.start(C.encodeArgument(integer, 2n, { workspace }));
const port = await f.receive();
assert.equal(port.kind, "port");
assert.equal(C.decodeArgument(unit, port.input, { workspace }), null);
f.send({
kind: "port-result",
...call,
sequence: port.sequence,
status: "returned",
output: C.encodeArgument(integer, 4n, { workspace }),
});
const result = await f.receive();
assert.equal(result.status, "returned");
assert.equal(C.decodeArgument(integer, result.output, { workspace }), 6n);
} finally {
await f.close();
}
});
test("ambient clock, entropy, network and native imports are denied", async () => {
for (const code of [
"Date.now()",
"new Date()",
"new Intl.DateTimeFormat().format()",
"new Intl.DateTimeFormat().formatToParts()",
"Math.random()",
"crypto.randomUUID()",
"fetch('https://example.com')",
"(await import('node:fs')).readFileSync('/etc/passwd')",
"(await import('./unlisted.mjs')).secret",
]) {
const f = await fixture(registry(`return ${code};`));
try {
f.start();
assert.equal((await f.receive()).status, "failed", code);
} finally {
await f.close();
}
}
});
test("explicit dates remain useful without an implicit clock", async () => {
const f = await fixture(registry("return new Date('2026-01-01T00:00:00Z').toISOString();"));
try {
f.start();
assert.equal((await f.receive()).output, "2026-01-01T00:00:00.000Z");
} finally {
await f.close();
}
});
test("initialization and regex loops are killed, then a fresh frame can start", async () => {
for (const source of [
"while(true){};" + registry("return 1;"),
registry("return /(a+)+$/.test('a'.repeat(100000)+'!');"),
]) {
const f = await fixture(source, { deadlineMs: 350 });
try {
for (let n = 0; n < 2; n++) {
f.start();
const result = await f.receive();
assert.equal(result.error.code, "RESTRICTED_DEADLINE");
assert.ok(
f.usage.some((value) => value.cpuMicroseconds >= 50000),
"External watchdog did not account spinning engine CPU",
);
}
} finally {
await f.close();
}
}
});
test("cancellation kills the entire frame before acknowledgment and rejects late port replies", async () => {
const f = await fixture(
registry("return await channel({portId:'read',action:{kind:'state',primitive:'read'},input:null});"),
);
try {
const call = f.start();
const port = await f.receive();
f.send({ kind: "cancel", ...call });
const cancelled = await f.receive();
assert.equal(cancelled.kind, "cancelled");
f.send({ kind: "port-result", ...call, sequence: port.sequence, status: "returned", output: "late" });
const next = f.start();
const nextPort = await f.receive();
assert.equal(nextPort.invocation, next.invocation);
f.send({ kind: "port-result", ...next, sequence: nextPort.sequence, status: "returned", output: "fresh" });
const result = await f.receive();
assert.equal(result.output, "fresh");
assert.equal(result.invocation, next.invocation);
} finally {
await f.close();
}
});
test("cancellation during asynchronous preparation leaves no running frame", async () => {
const f = await fixture(registry("return 1;"));
try {
for (let n = 0; n < 5; n++) {
const call = f.start();
f.send({ kind: "cancel", ...call });
assert.equal((await f.receive()).kind, "cancelled");
}
f.start();
assert.equal((await f.receive()).output, 1);
} finally {
await f.close();
}
});
test("bounded FIFO rejects overload without losing active or queued frames", async () => {
const f = await fixture(
registry("return await channel({portId:'read',action:{kind:'state',primitive:'read'},input:request.input});"),
{ maxQueued: 2, maxActive: 1 },
);
try {
const first = f.start(1),
port = await f.receive();
const second = f.start(2),
third = f.start(3),
overflow = f.start(4);
const refused = await f.receive();
assert.equal(refused.invocation, overflow.invocation);
assert.equal(refused.error.code, "RESTRICTED_QUEUE_FULL");
f.send({ kind: "cancel", ...second });
assert.equal((await f.receive()).invocation, second.invocation);
f.send({ kind: "port-result", ...first, sequence: port.sequence, status: "returned", output: 1 });
assert.equal((await f.receive()).output, 1);
const nextPort = await f.receive();
assert.equal(nextPort.invocation, third.invocation);
assert.equal(nextPort.input, 3);
f.send({ kind: "port-result", ...third, sequence: nextPort.sequence, status: "returned", output: 3 });
assert.equal((await f.receive()).output, 3);
f.start(5);
const fresh = await f.receive();
f.send({
kind: "port-result",
invocation: fresh.invocation,
frame: fresh.frame,
sequence: fresh.sequence,
status: "returned",
output: 5,
});
assert.equal((await f.receive()).output, 5);
} finally {
await f.close();
}
});
test("queue wait consumes the deadline and cancelled work never reaches its ports", async () => {
const f = await fixture(
registry("return await channel({portId:'read',action:{kind:'state',primitive:'read'},input:null});"),
{ deadlineMs: 350, maxActive: 1 },
);
try {
const first = f.start();
await f.receive();
const queued = f.start();
const replies = [await f.receive(), await f.receive()];
assert.deepEqual(new Set(replies.map((x) => x.invocation)), new Set([first.invocation, queued.invocation]));
assert.ok(replies.every((x) => x.error.code === "RESTRICTED_DEADLINE"));
const fresh = f.start();
const port = await f.receive();
assert.equal(port.invocation, fresh.invocation);
f.send({ kind: "port-result", ...fresh, sequence: port.sequence, status: "returned", output: "fresh" });
assert.equal((await f.receive()).output, "fresh");
} finally {
await f.close();
}
});
test("warm engines create fresh transitive module state, closures and built-ins", async () => {
const directory = await mkdtemp(join(tmpdir(), "qx-transitive-"));
const helper = join(directory, "helper.mjs");
await writeFile(
helper,
"let value=0, retained; export function touch(channel){const old=retained; retained=channel; return {count:++value, captured:!!old};}",
);
const f = await fixture(
`import {touch} from 'helper.mjs'; let count=0;
export const registry={exports:['test'],async invoke(request,channel){
const before={object:Object.prototype.retained??null,array:Array.prototype.retained??null,
map:Map.prototype.retained??null, global:globalThis.retained??null};
Object.prototype.retained=request.input; Array.prototype.retained=request.input;
Map.prototype.retained=request.input; globalThis.retained=request.input;
return {count:++count, helper:touch(channel), before};
}};`,
{ sdk: [{ name: "helper.mjs", path: helper }] },
);
try {
for (const value of ["private graph A", "private graph B", "private graph C"]) {
f.start(value);
assert.deepEqual((await f.receive()).output, {
count: 1,
helper: { count: 1, captured: false },
before: { object: null, array: null, map: null, global: null },
});
}
assert.equal(f.stats().starts, 1, "Qualification must exercise actual engine reuse");
assert.equal(f.stats().reused, 2);
assert.equal(f.stats().idle, 1);
} finally {
await f.close();
await rm(directory, { recursive: true, force: true });
}
});
test("an expired frame token cannot borrow a later invocation's broker", async () => {
const directory = await mkdtemp(join(tmpdir(), "qx-token-"));
const worker = join(directory, "token-test.mjs");
// Trusted test entrypoint deliberately replays the old token. Authored
// registries never receive CONFIG or BROKER directly.
await writeFile(
worker,
`export default {async fetch(request,env) {
const message=await request.json();
const output=message.input ? (await env.BROKER.fetch('http://frame/port/'+message.input,{
method:'POST',body:JSON.stringify({portId:'read',action:{kind:'state',primitive:'read'},input:null})})).status
: env.CONFIG.frameToken;
return Response.json({status:'returned',output});
}};`,
);
const f = await fixture(registry("return null;"), { worker });
try {
f.start();
const token = (await f.receive()).output;
assert.match(token, /^[a-f0-9-]{36}$/);
f.start(token);
assert.equal((await f.receive()).output, 409);
assert.equal(f.stats().starts, 1);
assert.equal(f.stats().reused, 1);
} finally {
await f.close();
await rm(directory, { recursive: true, force: true });
}
});
test("idle engines evict without a graph poll and restart with fresh state", async () => {
const f = await fixture(registry("return request.input;"), { engineIdleMs: 30 });
try {
f.start("first");
assert.equal((await f.receive()).output, "first");
await new Promise((resolve) => setTimeout(resolve, 100));
assert.equal(f.stats().engines, 0);
f.start("second");
assert.equal((await f.receive()).output, "second");
assert.equal(f.stats().starts, 2);
} finally {
await f.close();
}
});
for (const loop of [
"while(true) await Promise.resolve();",
"const memory=[]; for(let n=0;n<128;n++) memory.push(new Uint8Array(256*1024)); while(true) await Promise.resolve(memory);",
])
test("await/allocation pressure is fenced without delaying a neighboring engine: " + loop.slice(0, 28), async () => {
const f = await fixture(registry(`if(request.input==='spin'){${loop}} return request.input;`), {
deadlineMs: 1500,
});
try {
const stuck = f.start("spin", { root: "stuck", depth: 1, deadlineMs: 350, calls: 10 });
const before = performance.now();
const healthy = f.start("healthy");
const replies = [await f.receive(), await f.receive()];
assert.equal(replies.find((r) => r.invocation === healthy.invocation).output, "healthy");
assert.equal(replies.find((r) => r.invocation === stuck.invocation).error.code, "RESTRICTED_DEADLINE");
assert.equal(replies[0].invocation, healthy.invocation, "Healthy work must finish before the stuck deadline");
assert.ok(performance.now() - before < 1200);
f.start("after fault");
assert.equal((await f.receive()).output, "after fault");
assert.equal(f.stats().starts, 2, "The healthy engine survives its neighbor's termination");
} finally {
await f.close();
}
});
test("detached microtask loops cannot escape the invocation wall deadline", async () => {
const f = await fixture(
registry("void(async()=>{while(true)await Promise.resolve();})(); return 'nominal return';"),
{ deadlineMs: 200 },
);
try {
const before = performance.now();
f.start();
assert.equal((await f.receive()).error.code, "RESTRICTED_DEADLINE");
assert.ok(performance.now() - before < 1000);
assert.equal(f.stats().engines, 0);
} finally {
await f.close();
}
});
test("detached digest callbacks cannot use a completed frame or contaminate reuse", async () => {
const f = await fixture(
registry(`
void(async()=>{
for(let n=0;n<100;n++)await crypto.subtle.digest('SHA-256',new Uint8Array(32768));
await channel({portId:'late',action:{kind:'state',primitive:'read'},input:request.input});
})().catch(()=>{});
return request.input;
`),
);
try {
f.start("private A");
assert.equal((await f.receive()).output, "private A");
await new Promise((resolve) => setTimeout(resolve, 75));
f.start("private B");
const reply = await f.receive();
assert.equal(reply.status, "returned", "No late graph port may appear after completion");
assert.equal(reply.output, "private B");
assert.equal(f.stats().starts, 1);
} finally {
await f.close();
}
});
test("the shared engine budget evicts idle code families and rejects busy oversubscription", async () => {
const engineBudget = new RestrictedEngineBudget(1);
const a = await fixture(registry("return request.input;"), { engineBudget });
const b = await fixture(
registry("return await channel({portId:'read',action:{kind:'state',primitive:'read'},input:null});"),
{ engineBudget },
);
try {
a.start("first family");
assert.equal((await a.receive()).output, "first family");
const busy = b.start();
const port = await b.receive();
assert.equal(a.stats().engines, 0, "Idle foreign code is evicted before allocating another engine");
assert.equal(engineBudget.stats().engines, 1);
a.start("overload");
assert.equal((await a.receive()).error.code, "RESTRICTED_ENGINE_LIMIT");
assert.equal(engineBudget.stats().engines, 1);
b.send({ kind: "port-result", ...busy, sequence: port.sequence, status: "returned", output: "survived" });
assert.equal((await b.receive()).output, "survived");
} finally {
await Promise.all([a.close(), b.close()]);
}
assert.equal(engineBudget.stats().engines, 0);
});
+105
View File
@@ -0,0 +1,105 @@
// Platform entrypoint, evaluated before loading the authored registry. A fresh
// Worker owns exactly one frame. The parent engine is reusable; BROKER's host
// token grants only this frame and expires before the next invocation.
const monotonic = performance.now.bind(performance);
const deny = () => {
throw Error("RESTRICTED_AMBIENT_ACCESS");
};
const replace = (object, key, value) =>
Object.defineProperty(object, key, { value, configurable: false, writable: false });
const NativeDate = Date;
const FixedDate = new Proxy(NativeDate, {
construct(target, args) {
if (!args.length) deny();
return Reflect.construct(target, args, target);
},
apply() {
deny();
},
});
replace(NativeDate, "now", deny);
replace(NativeDate.prototype, "constructor", FixedDate);
replace(globalThis, "Date", FixedDate);
replace(Math, "random", deny);
// Identity/value codecs need deterministic SHA-256, never entropy or key creation.
const digest = crypto.subtle.digest.bind(crypto.subtle);
replace(globalThis, "crypto", Object.freeze({ subtle: Object.freeze({ digest }) }));
for (const name of ["performance", "Temporal", "scheduler", "WebSocket", "EventSource", "SharedArrayBuffer", "Atomics"])
replace(globalThis, name, undefined);
for (const name of ["setTimeout", "setInterval", "fetch"]) replace(globalThis, name, deny);
// Intl's no-argument format defaults to the clock without consulting Date.now.
const format = Object.getOwnPropertyDescriptor(Intl.DateTimeFormat.prototype, "format").get;
Object.defineProperty(Intl.DateTimeFormat.prototype, "format", {
configurable: false,
get() {
const bound = format.call(this);
return (value) => {
if (value === undefined) deny();
return bound(value);
};
},
});
const formatToParts = Intl.DateTimeFormat.prototype.formatToParts;
replace(Intl.DateTimeFormat.prototype, "formatToParts", function (value) {
if (value === undefined) deny();
return formatToParts.call(this, value);
});
let used = false;
export default {
async fetch(request, env) {
if (used) return new Response("FRAME_EXPIRED", { status: 409 });
used = true;
const input = await request.json();
const loading = monotonic();
const source = await import("./package.mjs");
const initializationMs = monotonic() - loading;
const registry = source[env.CONFIG.registryExport];
if (
!registry ||
typeof registry.invoke !== "function" ||
JSON.stringify(registry.exports) !== JSON.stringify(env.CONFIG.exports)
)
throw Error("RESTRICTED_REGISTRY_MISMATCH");
let open = true;
const channel = async (value) => {
if (!open) throw Error("EXPIRED_CONTEXT");
const response = await env.BROKER.fetch("http://frame/port/" + env.CONFIG.frameToken, {
method: "POST",
body: JSON.stringify(value),
});
const result = await response.json();
if (!open) throw Error("EXPIRED_CONTEXT");
if (result.status !== "returned")
throw Object.assign(Error(result.error?.message ?? "Port failed"), {
code: result.error?.code ?? "PORT_FAILED",
});
return result.output;
};
const running = monotonic();
try {
const output = await registry.invoke(
{ exportId: input.exportId, workspace: input.workspace, receiver: input.receiver, input: input.input },
channel,
);
const body = JSON.stringify({ status: "returned", output });
if (new TextEncoder().encode(body).length > env.CONFIG.maxBytes) throw Error("RESTRICTED_OUTPUT_LIMIT");
return new Response(body, {
headers: {
"content-type": "application/json",
"x-quixos-initialization-ms": String(initializationMs),
"x-quixos-execution-ms": String(monotonic() - running),
},
});
} catch (error) {
// Only authored/codec rejection codes cross the engine boundary. Engine
// diagnostics stay private to the supervisor, never become protocol data.
const code =
typeof error?.code === "string" && /^[A-Z0-9_]{1,128}$/.test(error.code)
? error.code
: "RESTRICTED_PACKAGE_FAILED";
return Response.json({ status: "failed", error: { code, message: code } });
} finally {
open = false;
}
},
};
+46
View File
@@ -0,0 +1,46 @@
# Pinned upstream engine. This binary supplies an import/capability boundary;
# production execution additionally requires OS limits and platform approval
# for shared placement, or a workspace VM for unreviewed application code.
{ pkgs }:
let
version = "1.20261005.1";
platforms = {
x86_64-linux = {
name = "linux-64";
hash = "sha256-zm0T3YLo49ORPwR4iwP+WkQBMkiZQYftc+ArBQEoNGY=";
};
aarch64-linux = {
name = "linux-arm64";
hash = "sha256-jkvHyexr8Sn2wyqmLJJEOOGfAkfaVPLI7llHOX+FbxU=";
};
};
platform =
platforms.${pkgs.stdenv.hostPlatform.system}
or (throw "Restricted execution requires Linux x86_64 or aarch64");
in
pkgs.stdenvNoCC.mkDerivation {
pname = "quixos-workerd";
inherit version;
src = pkgs.fetchurl {
url = "https://registry.npmjs.org/@cloudflare/workerd-${platform.name}/-/workerd-${platform.name}-${version}.tgz";
inherit (platform) hash;
};
nativeBuildInputs = [ pkgs.autoPatchelfHook ];
buildInputs = [ pkgs.stdenv.cc.cc.lib ];
sourceRoot = "package";
installPhase = ''
runHook preInstall
install -Dm755 bin/workerd "$out/bin/workerd"
runHook postInstall
'';
doInstallCheck = true;
installCheckPhase = ''
"$out/bin/workerd" --version | grep -Fx 'workerd 2026-10-05'
'';
meta = {
description = "Pinned workerd engine for Quixos restricted execution";
homepage = "https://github.com/cloudflare/workerd";
license = pkgs.lib.licenses.asl20;
platforms = builtins.attrNames platforms;
};
}