maximus/vps-health-api
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

test: cover degraded paths and shell commands in the write guard (#36)

Browse source 
Review of PR #39: the spies only watched authenticated requests on
complete fixtures, so a write on an error path passed the whole suite
(reviewer mutations R1, R2, R3 and R11: quarantining a corrupt
agents-map.json, recreating a missing status.json, logging a 401/403 or a
refused payload to disk).

A new case walks rejections (401/403/404), invalid input (400/413), a
corrupt agents-map.json, missing Defenseurs files and a corrupt snapshot,
requires the degraded content (no_data, neverSeen), and requires no write
outside HOSTS_DIR. child_process is now spied the same way as node:fs and
the set of shell commands is pinned to the two read-only ones metrics.js
runs, with GET /health as positive control.

R1, R2, R3 and R11 went from 0 to 1 red each; R4 (touch through
execFileSync) is now caught by this file. A write deferred by a timer
longer than 20 ms (R8b) stays out of sight, as the header says.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
le king fu 2026-09-30 19:59:44 -04:00
parent 6a2f7fec04
commit 7523b397f0
1 changed files with 141 additions and 15 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

156
__tests__/writes.test.js
View file

@ -2,6 +2,7 @@ const http = require("node:http");
const fs = require("node:fs");
const os = require("node:os");
const path = require("node:path");
const child_process = require("node:child_process");
const { fileURLToPath } = require("node:url");
// The API's only write surface is HOSTS_DIR (issue #36).
@ -11,13 +12,20 @@ const { fileURLToPath } = require("node:url");
// or /data/defenseurs would not fail in the other test files: their fixtures
// live in a writable temp dir, and CI runs as root, so a chmod-555 fixture
// would prove nothing either. It would fail in production, as a 500 (EROFS)
// on the route that tried it. This file moves that failure to CI.
// on the route that tried it. This file moves that failure to CI, for the
// paths it exercises: boot, the nominal reads and ingest, and the degraded
// ones (rejections, invalid input, a corrupt file, missing files).
//
// Every node:fs function that can write is spied BEFORE a fresh require,
// because the runtime modules destructure their fs functions at load time
// (same technique as the timingSafeEqual spy in auth.test.js). A call is
// recorded when its stack goes through a runtime file of the repo, then passed
// through to the real function.
// through to the real function. A shell command can write too, out of the fs
// spies' sight, so child_process is spied the same way and the set of commands
// is pinned to the two read-only ones metrics.js runs.
//
// Limits: a path no case takes stays out of sight, and so does a write
// deferred past settle() (a timer longer than 20 ms).
//
// Boot is exercised by calling the exported sweepStaleTempFiles(), which is
// what the `require.main === module` block runs before listen. That block
@ -29,7 +37,7 @@ const INGEST_TOKEN = "test-ingest-token";
const ORPHAN = ".thinkpad.4242.1700000000000.tmp";
// Runtime file = under the repo root, outside node_modules and __tests__.
// Used both to attribute a write to the API and to purge the module cache.
// Used both to attribute a call to the API and to purge the module cache.
function isRuntimeFile(file) {
const rel = path.relative(REPO_ROOT, file);
if (rel === "" || rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) return false;
@ -47,6 +55,14 @@ function fromRuntimeFile(stack) {
});
}
function captureStack() {
const limit = Error.stackTraceLimit;
Error.stackTraceLimit = 50;
const { stack } = new Error();
Error.stackTraceLimit = limit;
return stack;
}
// Write APIs of node:fs, by the argument(s) naming what gets written. Each is
// spied in its callback, Sync and fs.promises forms, when that form exists.
const O_WRITE =
@ -86,7 +102,17 @@ const WRITE_APIS = [
["open", (args) => (opensForWriting(args[1]) ? [args[0]] : null)],
];
// The two commands metrics.js runs, to read /proc/stat and the root disk.
const ALLOWED_COMMANDS = ["df -k /", "head -1 /proc/stat"];
const CHILD_PROCESS_APIS = ["exec", "execSync", "execFile", "execFileSync", "spawn", "spawnSync", "fork"];
// `exec("cmd")` and `execFile("file", ["arg"])` both come out as one string.
function commandOf(args) {
return (Array.isArray(args[1]) ? [args[0], ...args[1]] : [args[0]]).map(String).join(" ");
}
let log = [];
let commandLog = [];
function drain() {
const out = log;
@ -94,6 +120,10 @@ function drain() {
return out;
}
function foreignCommands() {
return commandLog.filter((command) => !ALLOWED_COMMANDS.includes(command));
}
function installWriteSpies() {
for (const [name, targetsOf] of WRITE_APIS) {
for (const [owner, key] of [
@ -105,11 +135,7 @@ function installWriteSpies() {
if (typeof owner[key] !== "function") continue;
const original = owner[key];
vi.spyOn(owner, key).mockImplementation(function (...args) {
const limit = Error.stackTraceLimit;
Error.stackTraceLimit = 50;
const { stack } = new Error();
Error.stackTraceLimit = limit;
if (fromRuntimeFile(stack)) {
if (fromRuntimeFile(captureStack())) {
const targets = targetsOf(args);
if (targets) log.push({ fn: key, targets });
}
@ -119,8 +145,19 @@ function installWriteSpies() {
}
}
function installCommandSpies() {
for (const key of CHILD_PROCESS_APIS) {
if (typeof child_process[key] !== "function") continue;
const original = child_process[key];
vi.spyOn(child_process, key).mockImplementation(function (...args) {
if (fromRuntimeFile(captureStack())) commandLog.push(commandOf(args));
return original.apply(this, args);
});
}
}
// Every runtime module, not only index.js: a module left in the cache would
// keep the fs functions it destructured under a previous test's spies, which
// keep the functions it destructured under a previous test's spies, which
// vi.restoreAllMocks() has turned back into silent pass-throughs.
function purgeRuntimeModules() {
for (const file of Object.keys(require.cache)) {
@ -177,6 +214,26 @@ let server;
let baseUrl;
let bootWrites;
// A transport failure (a connection cut before a 413 is read) comes back as
// "transport-error", so it fails an assertion instead of passing for a code.
async function send(route, { method = "GET", auth = `Bearer ${TOKEN}`, body } = {}) {
const headers = auth ? { Authorization: auth } : {};
if (body !== undefined) headers["Content-Type"] = "application/json";
try {
const res = await fetch(`${baseUrl}${route}`, { method, headers, body });
const text = await res.text();
let json = null;
try {
json = JSON.parse(text);
} catch {
// Not JSON: the status alone is asserted.
}
return { status: res.status, body: json };
} catch {
return { status: "transport-error", body: null };
}
}
// Created before the spies: nothing here is attributed to the API.
function writeFixtures() {
tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "vps-health-writes-test-"));
@ -226,7 +283,9 @@ function writeFixtures() {
beforeEach(async () => {
writeFixtures();
log = [];
commandLog = [];
installWriteSpies();
installCommandSpies();
purgeRuntimeModules();
const { handler, sweepStaleTempFiles } = require("../index.js");
sweepStaleTempFiles();
@ -247,6 +306,7 @@ describe("fs writes — the API writes only under HOSTS_DIR (#36)", () => {
expect(bootWrites.map(({ fn }) => fn)).toContain("unlinkSync");
expect(fs.existsSync(path.join(process.env.HOSTS_DIR, ORPHAN))).toBe(false);
expect(violations(bootWrites)).toEqual([]);
expect(foreignCommands()).toEqual([]);
});
// Each route with the content that proves its fixture was really read: a
@ -277,28 +337,94 @@ describe("fs writes — the API writes only under HOSTS_DIR (#36)", () => {
// This test's own spies are live: they saw the boot sweep.
expect(bootWrites).not.toHaveLength(0);
const res = await fetch(`${baseUrl}${route}`, { headers: { Authorization: `Bearer ${TOKEN}` } });
expect(res.status).toBe(200);
const body = await res.json();
const { status, body } = await send(route);
expect(status).toBe(200);
expect(body.status).not.toBe("no_data");
expectContent(body);
await settle();
expect(drain()).toEqual([]);
expect(foreignCommands()).toEqual([]);
});
test("POST /hosts/<id> writes, and only under HOSTS_DIR", async () => {
const res = await fetch(`${baseUrl}/hosts/thinkpad`, {
const { status } = await send("/hosts/thinkpad", {
method: "POST",
headers: { Authorization: `Bearer ${INGEST_TOKEN}`, "Content-Type": "application/json" },
auth: `Bearer ${INGEST_TOKEN}`,
body: JSON.stringify(validSnapshot()),
});
expect(res.status).toBe(204);
expect(status).toBe(204);
await settle();
const writes = drain();
expect(writes.map(({ fn }) => fn)).toEqual(expect.arrayContaining(["writeFileSync", "renameSync"]));
expect(violations(writes)).toEqual([]);
expect(foreignCommands()).toEqual([]);
});
// The branches the nominal cases never take, and where the most plausible
// future writes would land: quarantining a corrupt file, recreating a
// missing one, logging a rejection or a refused payload to disk.
test("rejections, invalid input, corrupt and missing files write nothing outside HOSTS_DIR", async () => {
expect(bootWrites).not.toHaveLength(0);
const ingest = `Bearer ${INGEST_TOKEN}`;
const rejected = [
[401, "/defenseurs", { auth: null }],
[401, "/defenseurs", { auth: "Bearer wrong" }],
[401, "/hosts", { auth: ingest }],
[404, "/nope", {}],
[400, "/defenseurs/findings", {}],
[400, "/defenseurs/findings?project=proj&severity=BOGUS", {}],
[404, "/defenseurs/findings?project=unknown", {}],
[400, "/reports/scans?date=../../etc", {}],
[401, "/hosts/thinkpad", { method: "POST", auth: "Bearer wrong", body: "{}" }],
[403, "/hosts/laptop", { method: "POST", auth: ingest, body: JSON.stringify(validSnapshot()) }],
[400, "/hosts/thinkpad", { method: "POST", auth: ingest, body: "{not json" }],
[400, "/hosts/thinkpad", { method: "POST", auth: ingest, body: JSON.stringify({ hostname: "x" }) }],
[413, "/hosts/thinkpad", { method: "POST", auth: ingest, body: "x".repeat(5000) }],
];
for (const [expected, route, options] of rejected) {
const { status } = await send(route, options);
expect([options.method || "GET", route, status]).toEqual([options.method || "GET", route, expected]);
}
// A corrupt agents-map.json: where a quarantine rename would go.
fs.writeFileSync(process.env.DEFENSEURS_AGENTS_MAP_PATH, "{corrupt");
expect((await send("/defenseurs/findings?project=proj")).status).toBe(500);
// Missing Defenseurs files and a corrupt snapshot: where a "recreate it"
// write would go. Each route must degrade, with the content that says so.
fs.writeFileSync(process.env.DEFENSEURS_AGENTS_MAP_PATH, JSON.stringify({ proj: "defenseur-proj" }));
fs.rmSync(process.env.DEFENSEURS_STATUS_PATH);
fs.rmSync(process.env.DEFENSEURS_FINDINGS_STATE_PATH);
fs.rmSync(process.env.REPORTS_DIR, { recursive: true });
fs.writeFileSync(path.join(process.env.HOSTS_DIR, "thinkpad.json"), "{corrupt");
const degraded = [
["/defenseurs", (body) => expect(body.status).toBe("no_data")],
["/defenseurs/state", (body) => expect(body.status).toBe("no_data")],
["/defenseurs/findings?project=proj", (body) => expect(body).toEqual({ findings: [], status: "no_data" })],
["/reports/scans?date=2026-09-30", (body) => expect(body.count).toBe(0)],
["/hosts", (body) => expect(body.hosts.find(({ id }) => id === "thinkpad").neverSeen).toBe(true)],
];
for (const [route, expectContent] of degraded) {
const { status, body } = await send(route);
expect([route, status]).toEqual([route, 200]);
expectContent(body);
}
await settle();
expect(violations(drain())).toEqual([]);
expect(foreignCommands()).toEqual([]);
});
});
describe("shell commands — only the two read-only metrics ones (#36)", () => {
// Positive control for the child_process spies: /health must show exactly
// the two commands. The other cases only check that nothing else ran.
test("GET /health runs exactly `head -1 /proc/stat` and `df -k /`", async () => {
const { status } = await send("/health");
expect(status).toBe(200);
expect([...new Set(commandLog)].sort()).toEqual([...ALLOWED_COMMANDS].sort());
});
});