fix(harness): canonicalize source_doc containment with native realpath

Resolve both sides of the source_doc containment check with
fs.realpathSync.native (falling back to fs.realpathSync). With the JS
realpath, a repo root reached through a Windows 8.3 short name stays in
short form while an in-repo symlink whose target uses the long-path form
resolves to the long form, so a legitimate in-repo doc was reported as
"resolves outside repository root". Escapes outside the repo are still
rejected.

Adds a cross-platform regression test that models differing JS and
native realpath results: in-repo docs are accepted through a short-form
root and an outside target is still rejected. It fails on the previous
implementation.

Not required for the #3882 Windows CI fix; kept as a separate commit so
it can be taken or dropped on its own.
This commit is contained in:
montjeffrey committed 2026-11-12 00:21:26 -05:00
1 parent cefc906288
commit bf7f495a53
2 files changed
+59 -2

No files matched your search

+9 -2
View File
@@ -688,6 +688,13 @@ function isSafeRelativeSourceDocPath(trimmedEntry, normalizedEntry) {
&& !segments.includes('.');
}
// Canonicalize both sides of the containment check the same way. The native
// realpath also expands Windows 8.3 short names (e.g. RUNNER~1), which the JS
// realpath leaves as-is.
function nativeRealpath(value) {
return (fs.realpathSync.native || fs.realpathSync)(value);
}
function validateSingleSourceDoc(label, docEntry, repoRoot, canonicalRepoRoot) {
if (typeof docEntry !== 'string' || !docEntry.trim()) {
return null;
@@ -706,7 +713,7 @@ function validateSingleSourceDoc(label, docEntry, repoRoot, canonicalRepoRoot) {
let canonicalResolved;
try {
canonicalResolved = fs.realpathSync(resolved);
canonicalResolved = nativeRealpath(resolved);
} catch (_error) {
return `${label}: missing source_doc ${trimmedEntry}`;
}
@@ -720,7 +727,7 @@ function validateSingleSourceDoc(label, docEntry, repoRoot, canonicalRepoRoot) {
function validateSourceDocs(records = ADAPTER_RECORDS, options = {}) {
const repoRoot = path.resolve(options.repoRoot || path.resolve(__dirname, '..', '..'));
const canonicalRepoRoot = fs.existsSync(repoRoot) ? fs.realpathSync(repoRoot) : repoRoot;
const canonicalRepoRoot = fs.existsSync(repoRoot) ? nativeRealpath(repoRoot) : repoRoot;
const errors = [];
for (const record of records) {
@@ -287,6 +287,56 @@ test('validateSourceDocs rejects a symlinked source_doc escaping the repository
}
});
test('validateSourceDocs canonicalizes the root and source_docs with the native realpath', () => {
// Models Windows 8.3 aliasing without needing symlink privileges: the JS
// realpath keeps the root's short form (e.g. RUNNER~1) while an in-repo
// link resolves to a long-form target; the native realpath returns the
// long form for both. Before the fix, both in-repo docs were reported as
// outside the repository root.
const tempRoot = fs.realpathSync.native(fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-adapter-native-')));
const outsideRoot = fs.realpathSync.native(fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-adapter-native-outside-')));
const shortRoot = path.join(path.dirname(tempRoot), 'ECC-AD~1');
const realDoc = path.join(tempRoot, 'docs', 'real.md');
const linkDoc = path.join(tempRoot, 'docs', 'link.md');
const outsideDoc = path.join(tempRoot, 'docs', 'outside.md');
const outsideFile = path.join(outsideRoot, 'secret.md');
const originalRealpathSync = fs.realpathSync;
try {
fs.mkdirSync(path.join(tempRoot, 'docs'), { recursive: true });
for (const file of [realDoc, linkDoc, outsideDoc, outsideFile]) {
fs.writeFileSync(file, 'doc\n');
}
const linkTargets = new Map([[linkDoc, realDoc], [outsideDoc, outsideFile]]);
const nativeRealpath = value => linkTargets.get(path.resolve(value)) || path.resolve(value);
const jsRealpath = value => (path.resolve(value) === tempRoot ? shortRoot : nativeRealpath(value));
fs.realpathSync = Object.assign(jsRealpath, { native: nativeRealpath });
const errors = validateSourceDocs(
[{
id: 'sample',
harness: 'Sample',
state: 'Adapter-backed',
supported_assets: ['skills'],
unsupported_surfaces: ['hooks'],
install_or_onramp: ['`./install.sh --target sample`'],
verification_commands: ['`npm test`'],
risk_notes: ['None'],
last_verified_at: '2026-10-30',
owner: 'ECC maintainers',
source_docs: ['docs/real.md', 'docs/link.md', 'docs/outside.md'],
}],
{ repoRoot: tempRoot }
);
assert.strictEqual(errors.length, 1, errors.join('\n'));
assert.match(errors[0], /docs\/outside\.md resolves outside repository root/);
} finally {
fs.realpathSync = originalRealpathSync;
fs.rmSync(tempRoot, { recursive: true, force: true });
fs.rmSync(outsideRoot, { recursive: true, force: true });
}
});
if (failed > 0) {
console.log(`\nFailed: ${failed}`);
process.exit(1);