Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Filesystem-touching validator fuzz tests.
*
* Separate from `pure-validators.test.ts` because these targets need real fs
* access (realpathSync, lstatSync) and CANNOT be in the purity-guarded suite.
* That separation is the structural fix for the "fuzz purity guard contradicts
* itself" CRITICAL finding from the 2-pass eng review.
*
* Every test in this file uses a clean temp dir created in beforeEach so
* fuzz inputs can't leak across tests. The temp dir is the entire confinement
* boundary — `validateUploadPath` resolves symlinks and rejects traversal
* outside the dir, which is exactly the contract we want to fuzz.
*/
import { describe, test, expect, beforeAll, afterAll, beforeEach } from 'bun:test';
import fc from 'fast-check';
import { mkdtempSync, writeFileSync, mkdirSync, rmSync, symlinkSync, realpathSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join, sep } from 'node:path';
import { validateUploadPath } from '../../src/core/operations.ts';
const NUM_RUNS = 500;
let baseTmpRoot: string;
let savedCwd: string;
beforeAll(() => {
baseTmpRoot = mkdtempSync(join(tmpdir(), 'gbrain-fuzz-fs-'));
// #4479: the `..`-probe expectations assume a cwd DEEP enough that
// resolve('..') stays well below the filesystem root. In the CI container
// the workdir is the depth-1 /app mount, where '..' resolves to '/' and
// relative('/', box) no longer starts with '..' — the probe "passes"
// confinement and the test false-fails as a container-only failure. Run
// the whole file from a guaranteed-deep working directory instead of
// depending on where the harness happened to be launched.
savedCwd = process.cwd();
const deepCwd = join(baseTmpRoot, 'deep', 'cwd', 'for', 'traversal', 'probes');
mkdirSync(deepCwd, { recursive: true });
process.chdir(deepCwd);
});
afterAll(() => {
// Restore BEFORE removing baseTmpRoot — rmSync of the cwd's ancestor
// leaves the process in a deleted directory otherwise.
process.chdir(savedCwd);
rmSync(baseTmpRoot, { recursive: true, force: true });
});
let confinementDir: string;
beforeEach(() => {
// Fresh confinement per test so traversal attempts can't leak state.
confinementDir = mkdtempSync(join(baseTmpRoot, 'box-'));
// Seed a legitimate file inside the box so success cases have something to find.
writeFileSync(join(confinementDir, 'safe.txt'), 'safe');
mkdirSync(join(confinementDir, 'subdir'), { recursive: true });
writeFileSync(join(confinementDir, 'subdir', 'nested.txt'), 'nested');
});
describe('validateUploadPath fuzz (fs-backed)', () => {
test('arbitrary relative paths: never wedges, and any RETURNED path is inside the box', () => {
// A6 fix: the original suite passed (confinementDir, probe) — args
// reversed against the (filePath, root, strict) signature — and swallowed
// every throw, so the traversal/symlink properties tested nothing. The
// property now is real: candidate = join(box, probe), and when the
// validator RETURNS, the realpath it hands back must live inside the box.
const realBox = realpathSync(confinementDir);
fc.assert(
fc.property(fc.string({ minLength: 0, maxLength: 200 }), (relPath) => {
let returned: string | null = null;
try {
returned = validateUploadPath(join(confinementDir, relPath), confinementDir);
} catch {
/* throwing IS the contract for traversal / unresolvable input */
}
if (returned !== null && !returned.startsWith(realBox + sep)) {
throw new Error(`validateUploadPath returned an out-of-box path for ${JSON.stringify(relPath)}: ${returned}`);
}
}),
{ numRuns: NUM_RUNS },
);
});
test('shaped traversal probes: explicit `..` patterns rejected', () => {
// Generate adversarial traversal shapes deliberately, beyond what
// fc.string() would surface organically.
const traversalProbe = fc.oneof(
fc.constant('../etc/passwd'),
fc.constant('../../etc/passwd'),
fc.constant('subdir/../../etc/passwd'),
fc.constant('./../../../tmp'),
fc.constantFrom('.', '..', '...', './'),
fc.tuple(fc.constant('../'), fc.string({ minLength: 1, maxLength: 50 })).map(([a, b]) => a + b),
);
fc.assert(
fc.property(traversalProbe, (probe) => {
let threw = false;
try {
validateUploadPath(join(confinementDir, probe), confinementDir);
} catch {
threw = true;
}
// A probe with a `..` path SEGMENT is a traversal and must throw. A name
// that only contains two dots (`...`, `..drafts`) is not a traversal and
// is judged by the inside-the-box test below.
if (probe.split(/[\\/]/).includes('..') && !threw) {
throw new Error(`validateUploadPath did not reject traversal probe: ${JSON.stringify(probe)}`);
}
}),
{ numRuns: 200 },
);
});
test('a folder whose name starts with two dots is not a traversal', () => {
// Pins the probe above to "escape", not "name contains `..`": an existing
// file under `<box>/..drafts/` and `<box>/.../` is inside the box.
const realBox = realpathSync(confinementDir);
for (const dir of ['..drafts', '...']) {
mkdirSync(join(confinementDir, dir), { recursive: true });
writeFileSync(join(confinementDir, dir, 'report.txt'), 'r');
expect(validateUploadPath(join(confinementDir, dir, 'report.txt'), confinementDir))
.toBe(join(realBox, dir, 'report.txt'));
}
});
// Symlink creation is platform / permission gated (Windows without dev mode,
// restricted CI runners). Detect upfront and skip the probe explicitly via
// `test.skipIf` so the result is reported as "skipped" — NOT silently green.
// The earlier early-return pattern hid a security-critical confinement test
// behind a fake pass on any platform that couldn't make symlinks.
// Probe via the OS tmpdir directly — baseTmpRoot isn't available until
// beforeAll runs, and this expression evaluates at module load time.
const symlinksAvailable = (() => {
const probeDir = mkdtempSync(join(tmpdir(), 'gbrain-symlink-probe-'));
try {
symlinkSync(tmpdir(), join(probeDir, 'probe-link'));
return true;
} catch {
return false;
} finally {
rmSync(probeDir, { recursive: true, force: true });
}
})();
test.skipIf(!symlinksAvailable)(
'symlink-escape probe: symlinks pointing outside the box are rejected',
() => {
const linkPath = join(confinementDir, 'evil-link');
symlinkSync(tmpdir(), linkPath);
let threw = false;
try {
validateUploadPath(linkPath, confinementDir);
} catch {
threw = true;
}
if (!threw) {
throw new Error('validateUploadPath did not reject a symlink pointing outside the confinement dir');
}
},
);
// A6: loose mode (strict:false) — outside-box files are allowed, but a
// final-component symlink is STILL rejected in both modes.
test('strict:false resolves an outside-box file but still rejects symlinks', () => {
const outsideFile = join(baseTmpRoot, 'outside.txt');
writeFileSync(outsideFile, 'outside');
const real = validateUploadPath(outsideFile, confinementDir, false);
expect(real).toBe(realpathSync(outsideFile));
expect(real.startsWith(realpathSync(confinementDir))).toBe(false);
});
test.skipIf(!symlinksAvailable)('strict:false still rejects a final-component symlink', () => {
const target = join(baseTmpRoot, 'loose-target.txt');
writeFileSync(target, 'target');
const linkPath = join(confinementDir, 'loose-link');
symlinkSync(target, linkPath);
let threw = false;
try {
validateUploadPath(linkPath, confinementDir, false);
} catch {
threw = true;
}
expect(threw).toBe(true);
});
});