From bf7f495a5307caf85a41b05c82757b2a3a8fcf20 Mon Sep 17 00:00:00 2001 From: montjeffrey Date: Tue, 10 Nov 2026 01:11:31 -0500 Subject: [PATCH] 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. --- scripts/lib/harness-adapter-compliance.js | 11 +++- tests/docs/harness-adapter-compliance.test.js | 50 +++++++++++++++++++ 2 files changed, 59 insertions(+), 2 deletions(-) diff --git a/scripts/lib/harness-adapter-compliance.js b/scripts/lib/harness-adapter-compliance.js index abcbfa045..2303058ca 100644 --- a/scripts/lib/harness-adapter-compliance.js +++ b/scripts/lib/harness-adapter-compliance.js @@ -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) { diff --git a/tests/docs/harness-adapter-compliance.test.js b/tests/docs/harness-adapter-compliance.test.js index 76d026c55..ea09b2a18 100644 --- a/tests/docs/harness-adapter-compliance.test.js +++ b/tests/docs/harness-adapter-compliance.test.js @@ -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);