@markup-carve/carve-lsp 0.1.0 → 0.1.2

package/dist/include-path.js

@@ -0,0 +1,135 @@
+/**
+ * The single place an include path becomes a file read.
+ *
+ * PART 9 §19 puts four MUSTs on this function, and they are here rather than
+ * spread over the callers on purpose: a guard applied on one path and missed on
+ * another is the defect this repository's siblings keep hitting. Nothing else
+ * in this package joins, canonicalizes or opens an include target.
+ *
+ * - MUST resolve include paths only to files under the configured project root
+ *   AFTER symlink resolution (rejecting `..`-traversal and absolute paths that
+ *   escape the root)
+ * - MUST NOT fetch remote URLs unless an allowlist is explicitly configured
+ *
+ * The remaining two MUSTs (recursion depth, total expanded byte size) are
+ * properties of the include GRAPH rather than of one path, so they live in
+ * {@link ./includes.js} where the walk is.
+ */
+import { closeSync, fstatSync, openSync, readSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+/** A scheme with an authority (`https://…`), or a protocol-relative `//host/…`. */
+const REMOTE_RE = /^(?:[A-Za-z][A-Za-z0-9+.-]*:)?\/\//;
+function remoteHost(spec) {
+    const withScheme = spec.startsWith('//') ? `https:${spec}` : spec;
+    try {
+        return new URL(withScheme).hostname;
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Filesystem resolver with canonical root containment, for a workspace the
+ * client reports as trusted.
+ *
+ * Canonicalize-then-contain: the candidate is resolved to its real path
+ * (symlinks followed) and only then compared against the real root.
+ *
+ * Deliberately NOT a lexical ban on `..`, which is both too strict and too
+ * weak. Too strict: `../shared/glossary.crv` from `chapters/ch1.crv` is a
+ * normal book layout whose canonical target is inside the root, and the
+ * conformance vector `i10-fs-dotdot-inside-root-allowed` requires it to
+ * resolve. Too weak: a symlink inside the root pointing out of it, or an
+ * absolute path, escapes without containing `..` at all
+ * (`i10-fs-symlink-dir-escape-denied`). Canonical containment subsumes both.
+ */
+export function fileSystemResolver(includeRoot, opts = {}) {
+    const rootReal = realpathSync(includeRoot);
+    const allowedRemoteHosts = opts.allowedRemoteHosts ?? [];
+    const contains = (candidate) => {
+        const rel = path.relative(rootReal, candidate);
+        if (rel === '')
+            return true;
+        if (!rel || path.isAbsolute(rel))
+            return false;
+        // Segment-wise, so a directory legitimately named "..foo" is not read as
+        // an escape the way a startsWith('..') prefix test would.
+        return rel.split(path.sep)[0] !== '..';
+    };
+    return (includePath, ctx) => {
+        // GUARD 1 (§19: MUST NOT fetch remote URLs unless an allowlist is
+        // explicitly configured). Checked before any path join, so a URL can never
+        // be mistaken for a relative path and read off disk as `<root>/https:/…`.
+        if (REMOTE_RE.test(includePath)) {
+            const host = remoteHost(includePath);
+            if (!allowedRemoteHosts.includes(host)) {
+                return { ok: false, id: includePath, denial: 'remote-not-allowed' };
+            }
+            // Allowlisted, and still refused: this server has no fetcher. Reported
+            // as a denial rather than silently, so the author sees why.
+            return { ok: false, id: includePath, denial: 'remote-not-allowed' };
+        }
+        // GUARD 2 (§19: absolute paths). Denied outright by default; when the host
+        // opts in, an absolute path still has to survive GUARD 3.
+        if (!opts.allowAbsolute && path.isAbsolute(includePath)) {
+            return { ok: false, id: includePath, denial: 'absolute-denied' };
+        }
+        // The stack carries the canonical path of each ancestor, so a nested
+        // relative include resolves against its actual parent directory, not the
+        // root.
+        const parent = ctx.stack[ctx.stack.length - 1];
+        const base = parent ? path.dirname(path.resolve(rootReal, parent)) : rootReal;
+        const joined = path.isAbsolute(includePath)
+            ? includePath
+            : path.resolve(base, includePath);
+        let real;
+        try {
+            // Symlink resolution happens HERE, before containment, which is what
+            // makes a symlinked escape visible to GUARD 3 at all.
+            real = realpathSync(joined);
+        }
+        catch {
+            return { ok: false, id: includePath, denial: 'not-found' };
+        }
+        // GUARD 3 (§19: only files under the configured project root AFTER symlink
+        // resolution). Catches `..` that leaves the root, a symlink that points out
+        // of it, and an absolute path outside it.
+        if (!contains(real)) {
+            return { ok: false, id: includePath, denial: 'outside-root' };
+        }
+        let fd;
+        try {
+            fd = openSync(real, 'r');
+        }
+        catch {
+            return { ok: false, id: includePath, denial: 'not-found' };
+        }
+        try {
+            const stat = fstatSync(fd);
+            // Regular files only. A FIFO or a character device would block the read
+            // or stream without end, and neither is a document.
+            if (!stat.isFile())
+                return { ok: false, id: real, denial: 'not-a-file' };
+            const buffer = Buffer.allocUnsafe(stat.size);
+            let read = 0;
+            while (read < stat.size) {
+                const n = readSync(fd, buffer, read, stat.size - read, read);
+                if (n <= 0)
+                    break;
+                read += n;
+            }
+            return {
+                ok: true,
+                id: real,
+                source: buffer.subarray(0, read).toString('utf8'),
+                // Encoded bytes, not JavaScript characters, so the budget counts what
+                // the include-bomb actually costs.
+                bytes: read,
+            };
+        }
+        finally {
+            closeSync(fd);
+        }
+    };
+}
+//# sourceMappingURL=include-path.js.map

package/dist/include-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"include-path.js","sourceRoot":"","sources":["../src/include-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAChF,OAAO,IAAI,MAAM,WAAW,CAAA;AAoD5B,mFAAmF;AACnF,MAAM,SAAS,GAAG,oCAAoC,CAAA;AAEtD,SAAS,UAAU,CAAC,IAAY;IAC9B,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAA;IACjE,IAAI,CAAC;QACH,OAAO,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC,QAAQ,CAAA;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAA;IACX,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,kBAAkB,CAChC,WAAmB,EACnB,OAAkC,EAAE;IAEpC,MAAM,QAAQ,GAAG,YAAY,CAAC,WAAW,CAAC,CAAA;IAC1C,MAAM,kBAAkB,GAAG,IAAI,CAAC,kBAAkB,IAAI,EAAE,CAAA;IAExD,MAAM,QAAQ,GAAG,CAAC,SAAiB,EAAW,EAAE;QAC9C,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAA;QAC9C,IAAI,GAAG,KAAK,EAAE;YAAE,OAAO,IAAI,CAAA;QAC3B,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAA;QAC9C,yEAAyE;QACzE,0DAA0D;QAC1D,OAAO,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAA;IACxC,CAAC,CAAA;IAED,OAAO,CAAC,WAAW,EAAE,GAAG,EAAE,EAAE;QAC1B,kEAAkE;QAClE,2EAA2E;QAC3E,0EAA0E;QAC1E,IAAI,SAAS,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,GAAG,UAAU,CAAC,WAAW,CAAC,CAAA;YACpC,IAAI,CAAC,kBAAkB,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;gBACvC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,oBAAoB,EAAE,CAAA;YACrE,CAAC;YACD,uEAAuE;YACvE,4DAA4D;YAC5D,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,oBAAoB,EAAE,CAAA;QACrE,CAAC;QAED,2EAA2E;QAC3E,0DAA0D;QAC1D,IAAI,CAAC,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;YACxD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAA;QAClE,CAAC;QAED,qEAAqE;QACrE,yEAAyE;QACzE,QAAQ;QACR,MAAM,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;QAC9C,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAA;QAC7E,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC;YACzC,CAAC,CAAC,WAAW;YACb,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,WAAW,CAAC,CAAA;QAEnC,IAAI,IAAY,CAAA;QAChB,IAAI,CAAC;YACH,qEAAqE;YACrE,sDAAsD;YACtD,IAAI,GAAG,YAAY,CAAC,MAAM,CAAC,CAAA;QAC7B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,CAAA;QAC5D,CAAC;QAED,2EAA2E;QAC3E,4EAA4E;QAC5E,0CAA0C;QAC1C,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACpB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,cAAc,EAAE,CAAA;QAC/D,CAAC;QAED,IAAI,EAAU,CAAA;QACd,IAAI,CAAC;YACH,EAAE,GAAG,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,CAAA;QAC5D,CAAC;QACD,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC,CAAA;YAC1B,wEAAwE;YACxE,oDAAoD;YACpD,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE;gBAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,CAAA;YACxE,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;YAC5C,IAAI,IAAI,GAAG,CAAC,CAAA;YACZ,OAAO,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;gBACxB,MAAM,CAAC,GAAG,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,GAAG,IAAI,EAAE,IAAI,CAAC,CAAA;gBAC5D,IAAI,CAAC,IAAI,CAAC;oBAAE,MAAK;gBACjB,IAAI,IAAI,CAAC,CAAA;YACX,CAAC;YACD,OAAO;gBACL,EAAE,EAAE,IAAI;gBACR,EAAE,EAAE,IAAI;gBACR,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC;gBACjD,sEAAsE;gBACtE,mCAAmC;gBACnC,KAAK,EAAE,IAAI;aACZ,CAAA;QACH,CAAC;gBAAS,CAAC;YACT,SAAS,CAAC,EAAE,CAAC,CAAA;QACf,CAAC;IACH,CAAC,CAAA;AACH,CAAC"}

package/dist/include-path.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/include-path.test.js

@@ -0,0 +1,189 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileSystemResolver } from './include-path.js';
+// PART 9 §19 puts four MUSTs on path resolution. Each has a test here, and
+// each was proven load-bearing by deleting its guard in `include-path.ts` and
+// watching THIS test go red (see the pull request for the transcript).
+//
+// Expectations follow the cross-engine include-conformance vectors
+// `i10-fs-*` in markup-carve/carve, which currently live only on the unmerged
+// spec branch for markup-carve/carve#291. They are cited, not vendored.
+const CTX = { stack: [], depth: 0 };
+function fixture(tree) {
+    const dir = realpathSync(mkdtempSync(path.join(tmpdir(), 'carve-lsp-inc-')));
+    for (const [name, value] of Object.entries(tree)) {
+        const full = path.join(dir, name);
+        mkdirSync(path.dirname(full), { recursive: true });
+        if (typeof value === 'string')
+            writeFileSync(full, value);
+        else
+            symlinkSync(path.join(dir, value.symlink), full);
+    }
+    test.after(() => rmSync(dir, { recursive: true, force: true }));
+    return dir;
+}
+// ---------------------------------------------------------------------------
+// MUST 1: resolve only under the root AFTER symlink resolution
+// ---------------------------------------------------------------------------
+test('a symlinked DIRECTORY escaping the root is denied (i10-fs-symlink-dir-escape-denied)', () => {
+    const dir = fixture({
+        'root/main.crv': '{{ linkdir/secret.crv }}\n',
+        'outside/secret.crv': 'TOP SECRET\n',
+        'root/linkdir': { symlink: 'outside' },
+    });
+    const resolve = fileSystemResolver(path.join(dir, 'root'));
+    const result = resolve('linkdir/secret.crv', CTX);
+    assert.equal(result.ok, false);
+    assert.equal(result.ok === false && result.denial, 'outside-root');
+    // The dependency id is the path as written, never the real path behind it.
+    assert.equal(result.id, 'linkdir/secret.crv');
+});
+test('a symlinked FILE whose real target escapes the root is denied (i10-fs-symlink-file-and-dotdot-denied)', () => {
+    const dir = fixture({
+        'root/main.crv': '{{ link.crv }}\n',
+        'secret.crv': 'TOP SECRET\n',
+        'root/link.crv': { symlink: 'secret.crv' },
+    });
+    const resolve = fileSystemResolver(path.join(dir, 'root'));
+    const result = resolve('link.crv', CTX);
+    assert.equal(result.ok, false);
+    assert.equal(result.ok === false && result.denial, 'outside-root');
+});
+// ---------------------------------------------------------------------------
+// MUST 2: reject `..`-traversal that leaves the root
+// ---------------------------------------------------------------------------
+test('a ../ escape out of the root is denied (i10-fs-dotdot-escape-denied)', () => {
+    const dir = fixture({
+        'root/main.crv': '{{ ../secret.crv }}\n',
+        'secret.crv': 'TOP SECRET\n',
+    });
+    const resolve = fileSystemResolver(path.join(dir, 'root'));
+    const result = resolve('../secret.crv', CTX);
+    assert.equal(result.ok, false);
+    assert.equal(result.ok === false && result.denial, 'outside-root');
+});
+test('a ../ path whose canonical target stays INSIDE the root resolves (i10-fs-dotdot-inside-root-allowed)', () => {
+    // Control for the test above: the guard is canonical containment, not a
+    // lexical ban on `..`. A book layout that reaches a sibling directory is
+    // legal and must keep working. No mutation of the containment check breaks
+    // this case - deleting the check makes it pass just as well - so it is
+    // stated here as the boundary the guard must NOT overreach, not as proof.
+    const dir = fixture({
+        'chapters/ch1.crv': 'Chapter one.\n',
+        'shared/glossary.crv': 'Glossary body.\n',
+    });
+    const resolve = fileSystemResolver(dir);
+    const result = resolve('../shared/glossary.crv', {
+        stack: [path.join(dir, 'chapters/ch1.crv')],
+        depth: 1,
+    });
+    assert.equal(result.ok, true);
+    assert.equal(result.ok === true && result.source, 'Glossary body.\n');
+});
+// ---------------------------------------------------------------------------
+// MUST 3: reject absolute paths that escape the root
+// ---------------------------------------------------------------------------
+test('an absolute path outside the root is denied even with allowAbsolute (i10-fs-absolute-path-denied)', () => {
+    // With absolute paths explicitly enabled, containment is the ONLY thing
+    // standing between the directive and the file, which is what makes this the
+    // test for the MUST rather than for the convenience default below.
+    const dir = fixture({
+        'root/main.crv': 'x\n',
+        'secret.crv': 'TOP SECRET\n',
+    });
+    const resolve = fileSystemResolver(path.join(dir, 'root'), { allowAbsolute: true });
+    const result = resolve(path.join(dir, 'secret.crv'), CTX);
+    assert.equal(result.ok, false);
+    assert.equal(result.ok === false && result.denial, 'outside-root');
+});
+test('an absolute path is denied by default, before containment is consulted', () => {
+    const dir = fixture({ 'root/main.crv': 'x\n', 'root/inside.crv': 'Inside.\n' });
+    const resolve = fileSystemResolver(path.join(dir, 'root'));
+    // Absolute AND inside the root: only the default-deny can reject this one,
+    // so it isolates that guard from containment.
+    const result = resolve(path.join(dir, 'root/inside.crv'), CTX);
+    assert.equal(result.ok, false);
+    assert.equal(result.ok === false && result.denial, 'absolute-denied');
+});
+test('an absolute path inside the root resolves once allowAbsolute is set', () => {
+    const dir = fixture({ 'root/inside.crv': 'Inside.\n' });
+    const resolve = fileSystemResolver(path.join(dir, 'root'), { allowAbsolute: true });
+    const result = resolve(path.join(dir, 'root/inside.crv'), CTX);
+    assert.equal(result.ok, true);
+});
+// ---------------------------------------------------------------------------
+// MUST 4: never fetch a remote URL without an explicit allowlist
+// ---------------------------------------------------------------------------
+test('a remote URL is denied with no allowlist configured, and never touches the disk', () => {
+    const dir = fixture({ 'main.crv': 'x\n' });
+    const resolve = fileSystemResolver(dir);
+    for (const url of [
+        'https://example.com/evil.crv',
+        'http://example.com/evil.crv',
+        'file://localhost/etc/passwd',
+        '//example.com/evil.crv',
+    ]) {
+        const result = resolve(url, CTX);
+        assert.equal(result.ok, false, url);
+        assert.equal(result.ok === false && result.denial, 'remote-not-allowed', url);
+    }
+});
+test('a remote URL is denied even when its host IS allowlisted, because nothing fetches', () => {
+    const dir = fixture({ 'main.crv': 'x\n' });
+    const resolve = fileSystemResolver(dir, { allowedRemoteHosts: ['example.com'] });
+    const result = resolve('https://example.com/ok.crv', CTX);
+    assert.equal(result.ok, false);
+    assert.equal(result.ok === false && result.denial, 'remote-not-allowed');
+});
+test('a URL-shaped path is not read off disk as a relative path', () => {
+    // Without the scheme check a URL falls through to path joining, and
+    // `<root>/https:/example.com/evil.crv` is a file an attacker can plant.
+    const dir = fixture({
+        'https:/example.com/evil.crv': 'PLANTED\n',
+    });
+    const resolve = fileSystemResolver(dir);
+    const result = resolve('https://example.com/evil.crv', CTX);
+    assert.equal(result.ok, false);
+    assert.equal(result.ok === false && result.denial, 'remote-not-allowed');
+});
+// ---------------------------------------------------------------------------
+// Ordinary resolution and non-file targets
+// ---------------------------------------------------------------------------
+test('a missing target is reported as not-found, not as a containment denial', () => {
+    const dir = fixture({ 'main.crv': 'x\n' });
+    const resolve = fileSystemResolver(dir);
+    const result = resolve('absent.crv', CTX);
+    assert.equal(result.ok, false);
+    assert.equal(result.ok === false && result.denial, 'not-found');
+});
+test('a directory is not a document', () => {
+    const dir = fixture({ 'sub/child.crv': 'x\n' });
+    const resolve = fileSystemResolver(dir);
+    const result = resolve('sub', CTX);
+    assert.equal(result.ok, false);
+    assert.equal(result.ok === false && result.denial, 'not-a-file');
+});
+test('bytes are counted as encoded UTF-8, not as JavaScript characters', () => {
+    const dir = fixture({ 'child.crv': 'éé\u{1f600}' });
+    const resolve = fileSystemResolver(dir);
+    const result = resolve('child.crv', CTX);
+    assert.equal(result.ok, true);
+    assert.equal(result.ok === true && result.bytes, Buffer.byteLength('éé\u{1f600}', 'utf8'));
+});
+test('a nested relative include resolves against its parent directory, not the root', () => {
+    const dir = fixture({
+        'chapters/ch1.crv': 'Chapter one.\n',
+        'chapters/notes.crv': 'Notes.\n',
+    });
+    const resolve = fileSystemResolver(dir);
+    const result = resolve('notes.crv', {
+        stack: [path.join(dir, 'chapters/ch1.crv')],
+        depth: 1,
+    });
+    assert.equal(result.ok, true);
+    assert.equal(result.ok === true && result.source, 'Notes.\n');
+});
+//# sourceMappingURL=include-path.test.js.map

package/dist/include-path.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"include-path.test.js","sourceRoot":"","sources":["../src/include-path.test.ts"],"names":[],"mappings":"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"}

package/dist/include-security-conformance.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/include-security-conformance.test.js

@@ -0,0 +1,100 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { fileSystemResolver } from './include-path.js';
+import { resolveIncludes } from './includes.js';
+const sourceRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const corpusPath = path.join(sourceRoot, 'tests/spec/tests/include-security-conformance/vectors.json');
+const corpus = JSON.parse(readFileSync(corpusPath, 'utf8'));
+function fixture(tree) {
+    const dir = realpathSync(mkdtempSync(path.join(tmpdir(), 'carve-lsp-security-')));
+    const links = [];
+    for (const [name, value] of Object.entries(tree ?? {})) {
+        const full = path.join(dir, name);
+        mkdirSync(path.dirname(full), { recursive: true });
+        if (typeof value === 'string')
+            writeFileSync(full, value);
+        else
+            links.push([full, value.symlink]);
+    }
+    for (const [full, target] of links)
+        symlinkSync(path.join(dir, target), full);
+    test.after(() => rmSync(dir, { recursive: true, force: true }));
+    return dir;
+}
+function graph(vector) {
+    const calls = [];
+    let maxVisitedDepth = 0;
+    const resolver = (request, context) => {
+        calls.push(request);
+        maxVisitedDepth = Math.max(maxVisitedDepth, context.depth + 1);
+        const source = vector.files?.[request];
+        return source === undefined
+            ? { ok: false, id: request, denial: 'not-found' }
+            : { ok: true, id: request, source, bytes: Buffer.byteLength(source, 'utf8') };
+    };
+    const result = resolveIncludes(vector.entry ?? '', {
+        resolver,
+        maxDepth: vector.maxDepth,
+        maxBytes: vector.maxBytes,
+    });
+    const warning = result.warnings.find((item) => item.rule === 'include-depth' || item.rule === 'include-budget');
+    return {
+        resolverCalls: calls,
+        maxVisitedDepth,
+        chargedBytes: result.bytes,
+        status: warning ? 'denied' : 'allowed',
+        denial: warning?.rule === 'include-depth' ? 'depth' : warning ? 'budget' : undefined,
+    };
+}
+function run(vector) {
+    if (vector.kind === 'activation') {
+        const calls = [];
+        const resolver = (request) => {
+            calls.push(request);
+            return { ok: false, id: request, denial: 'not-found' };
+        };
+        resolveIncludes(vector.entry ?? '', vector.enabled ? { resolver } : {});
+        return { resolverCalls: calls };
+    }
+    if (vector.kind === 'graph')
+        return graph(vector);
+    const dir = fixture(vector.tree ?? { 'root/main.crv': '' });
+    const root = realpathSync(path.join(dir, vector.root ?? 'root'));
+    const resolver = fileSystemResolver(root, {
+        allowAbsolute: vector.allowAbsolute,
+        allowedRemoteHosts: vector.allowedRemoteHosts,
+    });
+    const rawRequest = vector.request ?? '';
+    const request = rawRequest.replace(/^<ABS:([^>]+)>$/, (_match, rel) => path.join(dir, rel));
+    const context = vector.from
+        ? { stack: [realpathSync(path.join(dir, vector.from))], depth: 0 }
+        : { stack: [], depth: 0 };
+    const result = resolver(request, context);
+    if (vector.kind === 'remote') {
+        return {
+            status: result.ok ? 'allowed' : vector.allowedRemoteHosts?.length ? 'unsupported' : 'denied',
+            denial: result.ok ? undefined : result.denial,
+            remoteFetches: [],
+        };
+    }
+    return result.ok
+        ? { status: 'allowed', canonicalId: result.id.replace(root, '<ROOT>') }
+        : { status: 'denied', denial: result.denial };
+}
+test('executes every shared PART 9 section 19 security vector', async (t) => {
+    assert.equal(corpus.version, 1);
+    assert.equal(corpus.vectors.length, 12);
+    for (const vector of corpus.vectors) {
+        await t.test(vector.name, () => {
+            const actual = run(vector);
+            for (const [field, expected] of Object.entries(vector.expected)) {
+                assert.deepEqual(actual[field], expected, `${vector.name}: ${field}`);
+            }
+        });
+    }
+});
+//# sourceMappingURL=include-security-conformance.test.js.map

package/dist/include-security-conformance.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"include-security-conformance.test.js","sourceRoot":"","sources":["../src/include-security-conformance.test.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,oBAAoB,CAAA;AACvC,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAChH,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAChC,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,kBAAkB,EAA6C,MAAM,mBAAmB,CAAA;AACjG,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAmB/C,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAA;AACnF,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,4DAA4D,CAAC,CAAA;AACtG,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,UAAU,EAAE,MAAM,CAAC,CAA2C,CAAA;AAErG,SAAS,OAAO,CAAC,IAAoB;IACnC,MAAM,GAAG,GAAG,YAAY,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,qBAAqB,CAAC,CAAC,CAAC,CAAA;IACjF,MAAM,KAAK,GAA4B,EAAE,CAAA;IACzC,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;QACjC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;QAClD,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,aAAa,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;;YACpD,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAA;IACxC,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,KAAK;QAAE,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,IAAI,CAAC,CAAA;IAC7E,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;IAC/D,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,SAAS,KAAK,CAAC,MAAc;IAC3B,MAAM,KAAK,GAAa,EAAE,CAAA;IAC1B,IAAI,eAAe,GAAG,CAAC,CAAA;IACvB,MAAM,QAAQ,GAAoB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE;QACrD,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QACnB,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,eAAe,EAAE,OAAO,CAAC,KAAK,GAAG,CAAC,CAAC,CAAA;QAC9D,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC,OAAO,CAAC,CAAA;QACtC,OAAO,MAAM,KAAK,SAAS;YACzB,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE;YACjD,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAA;IACjF,CAAC,CAAA;IACD,MAAM,MAAM,GAAG,eAAe,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,EAAE;QACjD,QAAQ;QACR,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ;KAC1B,CAAC,CAAA;IACF,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,eAAe,IAAI,IAAI,CAAC,IAAI,KAAK,gBAAgB,CAAC,CAAA;IAC/G,OAAO;QACL,aAAa,EAAE,KAAK;QACpB,eAAe;QACf,YAAY,EAAE,MAAM,CAAC,KAAK;QAC1B,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;QACtC,MAAM,EAAE,OAAO,EAAE,IAAI,KAAK,eAAe,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;KACrF,CAAA;AACH,CAAC;AAED,SAAS,GAAG,CAAC,MAAc;IACzB,IAAI,MAAM,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;QACjC,MAAM,KAAK,GAAa,EAAE,CAAA;QAC1B,MAAM,QAAQ,GAAoB,CAAC,OAAO,EAAE,EAAE;YAC5C,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;YACnB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,CAAA;QACxD,CAAC,CAAA;QACD,eAAe,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;QACvE,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,CAAA;IACjC,CAAC;IAED,IAAI,MAAM,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO,KAAK,CAAC,MAAM,CAAC,CAAA;IAEjD,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,IAAI,EAAE,eAAe,EAAE,EAAE,EAAE,CAAC,CAAA;IAC3D,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,CAAC,CAAA;IAChE,MAAM,QAAQ,GAAG,kBAAkB,CAAC,IAAI,EAAE;QACxC,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,kBAAkB,EAAE,MAAM,CAAC,kBAAkB;KAC9C,CAAC,CAAA;IACF,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,IAAI,EAAE,CAAA;IACvC,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC,iBAAiB,EAAE,CAAC,MAAM,EAAE,GAAW,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAA;IACnG,MAAM,OAAO,GAAmB,MAAM,CAAC,IAAI;QACzC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE;QAClE,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAA;IAC3B,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;IAEzC,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,OAAO;YACL,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,QAAQ;YAC5F,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM;YAC7C,aAAa,EAAE,EAAE;SAClB,CAAA;IACH,CAAC;IAED,OAAO,MAAM,CAAC,EAAE;QACd,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE;QACvE,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAA;AACjD,CAAC;AAED,IAAI,CAAC,yDAAyD,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE;IAC1E,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;IAC/B,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IAEvC,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACpC,MAAM,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE;YAC7B,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAAA;YAC1B,KAAK,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAChE,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC,CAAA;YACvE,CAAC;QACH,CAAC,CAAC,CAAA;IACJ,CAAC;AACH,CAAC,CAAC,CAAA"}

package/dist/include-settings.d.ts

@@ -0,0 +1,50 @@
+import type { IncludeOptions } from './includes.js';
+export interface IncludeSettings {
+    /**
+     * `auto` (the default) means ON ONLY for a workspace the client has reported
+     * as trusted. A client that says nothing about trust therefore gets includes
+     * OFF: silence is not consent.
+     */
+    enabled: 'auto' | 'on' | 'off';
+    /** Containment root override. Otherwise the workspace root, then the document's directory. */
+    includeRoot?: string;
+    /** Allow absolute include paths, still subject to root containment. */
+    allowAbsolute?: boolean;
+    /** Hosts a remote include may name. Empty means none; this server never fetches. */
+    allowedRemoteHosts?: string[];
+    maxDepth?: number;
+    maxBytes?: number;
+}
+export declare const DEFAULT_INCLUDE_SETTINGS: IncludeSettings;
+/**
+ * Read `carve.includes` out of `initializationOptions` or a
+ * `workspace/didChangeConfiguration` payload. Anything unrecognized falls back
+ * to the default rather than being trusted as given.
+ */
+export declare function readIncludeSettings(raw: unknown): IncludeSettings;
+/** Client-reported workspace trust. Absent means untrusted. */
+export declare function readWorkspaceTrusted(raw: unknown): boolean;
+export declare function fsPath(uri: string): string | undefined;
+export interface IncludeGateInput {
+    uri: string;
+    settings: IncludeSettings;
+    workspaceTrusted: boolean;
+    /**
+     * Every workspace folder the client reported, in the order it reported them.
+     * A multi-root session gets one root per folder, not the first folder for
+     * everything: rooting a document from the second folder at the first would
+     * reject its ordinary relative includes as escapes.
+     */
+    workspaceRoots?: string[];
+}
+/**
+ * Build the include options for one document, or undefined to leave its
+ * directives literal.
+ *
+ * The containment root is the explicit override, else the workspace root, else
+ * the document's own directory for a file opened outside any workspace. It is
+ * NEVER the process working directory: a language server is commonly spawned
+ * from the user's home or from `/`, and rooting there would make containment
+ * meaningless.
+ */
+export declare function includeOptionsFor(input: IncludeGateInput): IncludeOptions | undefined;

package/dist/include-settings.js

@@ -0,0 +1,135 @@
+/**
+ * Client-facing include settings and the decision of whether a document gets
+ * include resolution at all (PART 9 §19: "MUST treat includes as opt-in (off
+ * for untrusted input)").
+ *
+ * Kept out of `server.ts` so the opt-in decision is testable on its own. It is
+ * the gate in front of a file-read capability, which is not something to leave
+ * exercised only by hand.
+ */
+import { realpathSync } from 'node:fs';
+import path, { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { fileSystemResolver } from './include-path.js';
+export const DEFAULT_INCLUDE_SETTINGS = { enabled: 'auto' };
+/**
+ * Read `carve.includes` out of `initializationOptions` or a
+ * `workspace/didChangeConfiguration` payload. Anything unrecognized falls back
+ * to the default rather than being trusted as given.
+ */
+export function readIncludeSettings(raw) {
+    const source = raw?.carve
+        ?.includes;
+    if (!source || typeof source !== 'object')
+        return DEFAULT_INCLUDE_SETTINGS;
+    const enabled = source['enabled'];
+    const settings = {
+        enabled: enabled === 'on' || enabled === 'off' ? enabled : 'auto',
+    };
+    if (typeof source['includeRoot'] === 'string')
+        settings.includeRoot = source['includeRoot'];
+    if (typeof source['allowAbsolute'] === 'boolean')
+        settings.allowAbsolute = source['allowAbsolute'];
+    if (Array.isArray(source['allowedRemoteHosts'])) {
+        settings.allowedRemoteHosts = source['allowedRemoteHosts'].filter((host) => typeof host === 'string');
+    }
+    if (typeof source['maxDepth'] === 'number')
+        settings.maxDepth = source['maxDepth'];
+    if (typeof source['maxBytes'] === 'number')
+        settings.maxBytes = source['maxBytes'];
+    return settings;
+}
+/** Client-reported workspace trust. Absent means untrusted. */
+export function readWorkspaceTrusted(raw) {
+    return raw?.workspaceTrusted === true;
+}
+export function fsPath(uri) {
+    if (!uri.startsWith('file:'))
+        return undefined;
+    try {
+        return fileURLToPath(uri);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** True when `candidate` is `root` or sits underneath it, segment-wise. */
+function contains(root, candidate) {
+    const rel = path.relative(root, candidate);
+    if (rel === '')
+        return true;
+    if (!rel || path.isAbsolute(rel))
+        return false;
+    return rel.split(path.sep)[0] !== '..';
+}
+/**
+ * The workspace folder this document belongs to: the deepest one containing
+ * it. A document in no folder at all has no workspace root, and falls back to
+ * its own directory rather than to somebody else's folder.
+ */
+function workspaceRootFor(documentPath, roots) {
+    let best;
+    for (const root of roots ?? []) {
+        if (!contains(root, documentPath))
+            continue;
+        if (best === undefined || root.length > best.length)
+            best = root;
+    }
+    return best;
+}
+/**
+ * Build the include options for one document, or undefined to leave its
+ * directives literal.
+ *
+ * The containment root is the explicit override, else the workspace root, else
+ * the document's own directory for a file opened outside any workspace. It is
+ * NEVER the process working directory: a language server is commonly spawned
+ * from the user's home or from `/`, and rooting there would make containment
+ * meaningless.
+ */
+export function includeOptionsFor(input) {
+    // GUARD 0 (§19: MUST treat includes as opt-in, off for untrusted input).
+    if (input.settings.enabled === 'off')
+        return undefined;
+    if (input.settings.enabled === 'auto' && !input.workspaceTrusted)
+        return undefined;
+    const documentPath = fsPath(input.uri);
+    // A document with no filesystem identity (untitled:, a remote scheme) has no
+    // directory to resolve against and gets no capability.
+    if (documentPath === undefined)
+        return undefined;
+    const configured = input.settings.includeRoot ??
+        workspaceRootFor(documentPath, input.workspaceRoots) ??
+        dirname(documentPath);
+    // Canonicalize the root here as well as inside the resolver, so that the
+    // root a caller sees on `includeRoot` is in the same coordinate system as
+    // the ids the resolver returns. Without it, a root reached through a symlink
+    // (or given relatively) makes every child id look like it sits outside the
+    // root, and a diagnostic naming that child would print an absolute path.
+    let root;
+    try {
+        root = realpathSync(configured);
+    }
+    catch {
+        return undefined;
+    }
+    let resolver;
+    try {
+        resolver = fileSystemResolver(root, {
+            allowAbsolute: input.settings.allowAbsolute ?? false,
+            allowedRemoteHosts: input.settings.allowedRemoteHosts ?? [],
+        });
+    }
+    catch {
+        // A root that is not a real directory yields no capability at all, rather
+        // than a resolver that silently falls back to somewhere wider.
+        return undefined;
+    }
+    const options = { resolver, sourcePath: documentPath, includeRoot: root };
+    if (input.settings.maxDepth !== undefined)
+        options.maxDepth = input.settings.maxDepth;
+    if (input.settings.maxBytes !== undefined)
+        options.maxBytes = input.settings.maxBytes;
+    return options;
+}
+//# sourceMappingURL=include-settings.js.map