@orygn/opa-mcp 0.4.0 → 0.6.0

package/dist/lib/rego-z3.js

@@ -1,29 +1,336 @@
 /**
  * Z3 singleton initialization.
  *
- * The z3-solver WASM module takes ~500ms to load and must only be
- * initialized once per process. Concurrent calls safely await the
- * same promise. Each verification call creates its own fresh Solver
- * from the shared Context, so contexts never accumulate stale state.
+ * The z3-solver WASM module takes ~500ms to load and is initialized once,
+ * unless it faults, in which case a fresh one replaces it (see getZ3).
+ * Concurrent calls safely await the same promise. Each verification call
+ * creates its own fresh Solver from the shared Context and releases it, and
+ * its model, as it finishes; that is what keeps the heap bounded.
+ *
+ * A fresh Solver is NOT enough to make concurrent verification safe. The whole
+ * Context lives in one single-threaded WASM heap, and `check()` is async, so two
+ * overlapping solves interleave on that heap and corrupt each other: observed
+ * symptoms were verdicts degrading to `inconclusive` and an allocator crash
+ * inside the WASM module. Everything touching the Context must therefore run
+ * under `withZ3Lock`.
  */
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { init } from 'z3-solver';
+/**
+ * Ceiling on Z3's own allocations, in megabytes. Reached, Z3 raises an
+ * ordinary exception that the engine turns into an inconclusive verdict.
+ * Without it the WASM heap itself runs out, and that abort surfaces outside
+ * every try/catch as an uncaughtException that ends the server.
+ */
+export const Z3_MEMORY_MAX_MB = 1024;
+/**
+ * The solver's own bound, checked at its checkpoints, where running out
+ * degrades to an "unknown" answer. It sits well below the process ceiling on
+ * purpose: at the same value the allocator's exception won the race, and an
+ * allocation failing inside a destructor ends in an abort rather than an
+ * error. Measured in review: equal caps aborted four times in four; a lower
+ * solver bound answered "unknown" four times in four.
+ */
+export const Z3_SOLVER_MAX_MEMORY_MB = 768;
 // Module-level singleton
 let z3InitPromise = null;
+let z3Api;
+/** Set once Z3 has failed outside a try/catch; it is not trusted again. */
+let z3Unusable;
+/** Number of Z3 critical sections currently running (0 or 1). */
+let z3Depth = 0;
+/** Rejects the section in flight; set while one is running. */
+let poisonInFlight;
+/** Generation of the module in use; a finalizer from an earlier one is dropped. */
+let z3Generation = 0;
+/** Finalizers that arrived while a solve was running, to run once it is not. */
+let deferredFinalizers = [];
+/** Fresh modules this process may still bring up after a fault. */
+let recoveriesLeft = 3;
+/**
+ * The registry class this process started with, and the identity of each
+ * init along its own async chain: z3-solver builds its registry in the
+ * continuation after its WASM loads, so the store there names the init that
+ * owns it, however inits interleave.
+ */
+const NativeRegistry = globalThis.FinalizationRegistry;
+const registryGlobal = globalThis;
+const initInFlight = new AsyncLocalStorage();
+/**
+ * Inits whose window is open; the global goes back when the last closes. An
+ * init that never settles leaves it on the subclass, which behaves natively
+ * for everything off an init's chain: only the class identity differs.
+ */
+let initWindows = 0;
+/**
+ * The stack at the call, with enough frames kept to reach the caller's module
+ * whatever `Error.stackTraceLimit` the host has chosen: a limit of zero, a
+ * common speed setting, would otherwise leave nothing to read and the wrap
+ * would quietly not happen.
+ */
+function stackHere() {
+    const limit = Error.stackTraceLimit;
+    Error.stackTraceLimit = 20;
+    try {
+        return new Error().stack ?? '';
+    }
+    finally {
+        Error.stackTraceLimit = limit;
+    }
+}
+/**
+ * The registry z3-solver gets while an init runs.
+ *
+ * z3-solver frees every AST, solver and model from one FinalizationRegistry,
+ * built inside its createApi, whose callbacks run on the main thread whenever
+ * the collector gets to them. A solve runs on a worker over the same shared
+ * memory, and a callback landing mid-solve raced it on Z3's allocator and
+ * faulted the heap (measured: a collection forced mid-solve crashed inside a
+ * hundred solves; the same collection while the worker was idle ran 1500
+ * clean). So a finalizer that arrives while a section is open waits for the
+ * section to close, and one from a module that has since faulted is dropped.
+ *
+ * Each construction looks at its own stack and async context: one from
+ * z3-solver on an init's chain is wrapped with that init's generation; any
+ * other gets the real behaviour. Inits can overlap, since a recovery starts
+ * the next while the one given up on is still coming up, and each still
+ * gets its own generation: the frees of the abandoned module are dropped
+ * and the recovered module's are routed.
+ *
+ * Releasing the solver and model as each solve ends removes most of the
+ * finalizer traffic that made the race reachable; the deferral covers what
+ * a collection still frees.
+ */
+class DeferringRegistry extends NativeRegistry {
+    constructor(callback) {
+        const owner = initInFlight.getStore();
+        const mine = owner !== undefined && stackHere().includes('z3-solver') ? owner : undefined;
+        const generation = mine?.generation;
+        super(mine === undefined
+            ? callback
+            : (held) => {
+                if (generation !== z3Generation)
+                    return;
+                if (z3Depth > 0)
+                    deferredFinalizers.push(() => callback(held));
+                else
+                    callback(held);
+            });
+    }
+}
+/** Bring up z3-solver with its finalizers routed through this module. */
+async function initModule() {
+    initWindows++;
+    registryGlobal.FinalizationRegistry = DeferringRegistry;
+    try {
+        return await initInFlight.run({ generation: z3Generation }, () => init());
+    }
+    finally {
+        if (--initWindows === 0)
+            registryGlobal.FinalizationRegistry = NativeRegistry;
+    }
+}
+/**
+ * Run the finalizers held back during a solve; only called with the worker
+ * idle. Each is a dec_ref; one that throws must not take the rest, or the
+ * lock, with it.
+ */
+function runDeferredFinalizers() {
+    const run = deferredFinalizers;
+    deferredFinalizers = [];
+    for (const finalizer of run) {
+        try {
+            finalizer();
+        }
+        catch {
+            // A free that fails leaks one object; the section still closes.
+        }
+    }
+}
 /**
  * Return the shared Z3 Context, initializing WASM on first call.
  * Safe to call from concurrent async paths.
  */
 export async function getZ3() {
+    if (z3Unusable !== undefined) {
+        if (recoveriesLeft === 0) {
+            throw new Error(`Z3 is unavailable in this process after repeated failures (${z3Unusable}). Restart the server to verify again.`);
+        }
+        // The heap that faulted cannot be trusted, so bring up a fresh module.
+        // Every init() is a new WASM instance with its own memory and worker
+        // (measured: two live side by side, independent, ~100 ms each), so
+        // nothing is shared with the one that faulted; its finalizers were
+        // dropped by generation when it was given up on. The faulted instance
+        // is retained, about 30 MB and one worker each, which is why the number
+        // of recoveries is bounded for the life of the process.
+        recoveriesLeft--;
+        z3Unusable = undefined;
+        z3InitPromise = null;
+        z3Api = undefined;
+    }
     if (z3InitPromise === null) {
-        z3InitPromise = init().then(({ Context }) => Context('main'));
+        const started = initModule().then((api) => {
+            // An init a recovery superseded while it was coming up must not
+            // become the module in use; whoever was waiting on it is told.
+            if (z3InitPromise !== started)
+                throw new Error('Z3 init superseded by a recovery');
+            api.setParam('memory_max_size', Z3_MEMORY_MAX_MB);
+            z3Api = api;
+            return api.Context('main');
+        });
+        z3InitPromise = started;
     }
     return z3InitPromise;
 }
+/** Read back a Z3 global parameter, after initialisation. */
+export async function getZ3Param(name) {
+    await getZ3();
+    return z3Api?.getParam(name) ?? null;
+}
+/** Whether a Z3 critical section is running right now. */
+export function isZ3Busy() {
+    return z3Depth > 0;
+}
+/**
+ * Give up on the Z3 module in use. Called when it failed outside a try/catch:
+ * the heap it lives in cannot be trusted. The next call brings up a fresh
+ * module, a bounded number of times per process.
+ */
+export function markZ3Unusable(reason) {
+    z3Unusable = reason;
+    // Move the generation now, before anything unwinds: the poison below ends
+    // the section, whose close would otherwise run every deferred free into
+    // the heap that just faulted, and any finalizer that arrives later from
+    // this module must be dropped rather than run.
+    z3Generation++;
+    deferredFinalizers = [];
+    // A heap abort arrives from the WASM worker and leaves the solve's promise
+    // unsettled for good. Settle it here, so the section releases the lock and
+    // the calls queued behind it are answered instead of hanging.
+    poisonInFlight?.(new Error(`Z3 became unusable during the solve (${reason}).`));
+}
+/**
+ * Whether an error message is one of the two this module produces once Z3
+ * has been given up on. The engine passes such a message through to the
+ * caller verbatim, since a restart is the one thing they can do about it.
+ */
+export function isZ3UnavailableMessage(detail) {
+    return /Z3 (is unavailable|became unusable)/.test(detail);
+}
+/**
+ * Whether a failure is the solve in flight being cut short by a fault, which
+ * a fresh module can answer: the engine retries such a call once.
+ */
+export function isZ3RecoverableMessage(detail) {
+    return /Z3 became unusable during the solve/.test(detail);
+}
+/**
+ * How many fresh modules this process may still bring up after a fault.
+ * Three for the life of the process, however far apart the faults: each
+ * retained instance costs memory, and a fourth fault is a pattern to
+ * restart out of, not to ride.
+ */
+export function z3RecoveriesLeft() {
+    return recoveriesLeft;
+}
+/** For tests: how many finalizers are waiting for the open section to close. */
+export function deferredFinalizersForTesting() {
+    return deferredFinalizers.length;
+}
+/**
+ * For tests: what z3-solver's finalizers go through. Runs at once when no
+ * section is open, otherwise once the open one closes.
+ */
+export function enqueueFinalizerForTesting(finalizer) {
+    if (z3Depth > 0)
+        deferredFinalizers.push(finalizer);
+    else
+        finalizer();
+}
+/**
+ * Whether an uncaught error is the WASM heap giving out, rather than some
+ * unrelated failure that happened while a solve was running.
+ */
+export function isZ3Failure(e) {
+    // A WebAssembly.RuntimeError is named just that; the global is not in this
+    // project's compiler libs, so the name is the check.
+    if (e instanceof Error && e.name === 'RuntimeError')
+        return true;
+    const message = e instanceof Error ? e.message : String(e);
+    // A call-stack overflow was also seen once as a symptom of a corrupted
+    // heap; it counts only when the stack shows it came from the WASM glue,
+    // so an overflow elsewhere does not spend a recovery. With no frames to
+    // read (a host that keeps none) the conservative answer stands: while a
+    // solve is running, the overflow is Z3's.
+    if (/Maximum call stack size exceeded/.test(message)) {
+        if (!(e instanceof Error))
+            return false;
+        const stack = e.stack ?? '';
+        if (!/\n\s+at /.test(stack))
+            return true;
+        return stack.includes('z3-built');
+    }
+    return /Aborted\(|memory access out of bounds|out of memory|unreachable executed/i.test(message);
+}
+/**
+ * Tail of the queue of pending Z3 critical sections. Each acquirer waits on the
+ * current tail and installs its own completion as the new tail, so sections run
+ * in call order with no overlap.
+ */
+let z3LockTail = Promise.resolve();
+/**
+ * Run `fn` with exclusive access to the shared Z3 Context.
+ *
+ * Serializes rather than parallelizes: an MCP client is free to issue several
+ * rego_verify calls at once, and letting them into the WASM heap together
+ * crashes it. Solve times are in the tens of milliseconds, so queueing is
+ * cheaper than the alternative of one Context per call, which would re-pay the
+ * WASM init cost every time.
+ */
+export async function withZ3Lock(fn) {
+    let release;
+    const mine = new Promise((resolve) => {
+        release = resolve;
+    });
+    const predecessor = z3LockTail;
+    z3LockTail = predecessor.then(() => mine);
+    await predecessor;
+    z3Depth++;
+    const poisoned = new Promise((_resolve, reject) => {
+        poisonInFlight = reject;
+    });
+    try {
+        return await Promise.race([fn(), poisoned]);
+    }
+    finally {
+        poisonInFlight = undefined;
+        z3Depth--;
+        try {
+            // The worker is idle: whatever the collector noticed mid-solve can be
+            // freed now.
+            if (z3Depth === 0)
+                runDeferredFinalizers();
+        }
+        finally {
+            // Whatever happened above, the lock must pass on, or every later call
+            // waits for ever.
+            release();
+        }
+    }
+}
 /**
  * Reset the singleton - intended for test teardown only.
  * Do NOT call in production paths; re-init is expensive.
  */
 export function resetZ3ForTesting() {
     z3InitPromise = null;
+    z3Api = undefined;
+    z3Unusable = undefined;
+    z3Depth = 0;
+    poisonInFlight = undefined;
+    z3LockTail = Promise.resolve();
+    z3Generation++;
+    deferredFinalizers = [];
+    recoveriesLeft = 3;
 }
 //# sourceMappingURL=rego-z3.js.map

package/dist/lib/rego-z3.js.map

@@ -1 +1 @@
-{"version":3,"file":"rego-z3.js","sourceRoot":"","sources":["../../src/lib/rego-z3.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAQjC,yBAAyB;AACzB,IAAI,aAAa,GAA4B,IAAI,CAAC;AAElD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK;IACzB,IAAI,aAAa,KAAK,IAAI,EAAE,CAAC;QAC3B,aAAa,GAAG,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,aAAmC,CAAC;AAC7C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB;IAC/B,aAAa,GAAG,IAAI,CAAC;AACvB,CAAC"}
+{"version":3,"file":"rego-z3.js","sourceRoot":"","sources":["../../src/lib/rego-z3.ts"],"names":[],"mappings":"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"}

package/dist/lib/security.d.ts

@@ -7,6 +7,14 @@ export interface PathValidationResult {
 /**
  * Resolve `inputPath` and confirm it is contained within at least one
  * `allowedRoots` entry. Returns the resolved absolute path on success.
+ *
+ * Two checks, both of which must pass. The first is syntactic: `..` segments
+ * are collapsed without touching the disk and the result must sit under a
+ * root as written. The second follows the filesystem: the path's real
+ * location, including the part of it that does not exist yet, must sit under
+ * a root's real location. A link is still followed at read or write time by
+ * the tool that receives the path, so the check is against the layout at the
+ * moment of validation.
  */
 export declare function validatePath(inputPath: string, allowedRoots: string[], options?: {
     mustExist?: boolean;

package/dist/lib/security.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../../src/lib/security.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EAAE,EACtB,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAO,GACpC,oBAAoB,CAwGtB;AAED,+EAA+E;AAC/E,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAMjD"}
+{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../../src/lib/security.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC;CAC7B;AA6ED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EAAE,EACtB,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAO,GACpC,oBAAoB,CAsGtB;AAED,+EAA+E;AAC/E,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAMjD"}

package/dist/lib/security.js

@@ -5,12 +5,90 @@
  * `validatePath` to prevent reading or writing outside the
  * agreed-upon roots.
  */
-import { existsSync, realpathSync, statSync } from 'node:fs';
-import { isAbsolute, resolve, sep } from 'node:path';
+import { lstatSync, realpathSync, statSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, resolve, sep } from 'node:path';
 import { err } from './errors.js';
+const WINDOWS = process.platform === 'win32';
+/**
+ * Canonical form of an existing path: every link resolved, and on Windows
+ * 8.3 short names expanded and on-disk casing restored. The JavaScript
+ * `realpathSync` resolves links but leaves short names and casing alone, so
+ * two spellings of one directory could compare unequal.
+ */
+function canonical(p) {
+    return realpathSync.native(p);
+}
+/** Does `p` fall under at least one of `roots`? */
+function isUnderRoots(p, roots, caseInsensitive) {
+    const fold = (s) => (caseInsensitive ? s.toLowerCase() : s);
+    const candidate = fold(p);
+    return roots.some((root) => {
+        const r = fold(root);
+        const rootWithSep = r.endsWith(sep) ? r : r + sep;
+        return candidate === r || candidate.startsWith(rootWithSep);
+    });
+}
+/**
+ * Where a path really leads, whether or not it exists yet.
+ *
+ * Walks up from `p` to the nearest entry that exists, resolves that entry's
+ * real location, and re-attaches the segments below it. A write to `p` lands
+ * under that real location, so that is what has to be checked against the
+ * roots. Checking only paths that already exist left every not-yet-created
+ * write target unchecked, and a junction or symlink inside a root could point
+ * it anywhere.
+ *
+ * An entry that exists only as a link to something that does not exist (a
+ * dangling link) is reported on its own: a write through it would create the
+ * target wherever the link points.
+ */
+function realLocation(p) {
+    const below = [];
+    let cur = p;
+    for (;;) {
+        let entry;
+        try {
+            entry = lstatSync(cur);
+        }
+        catch (e) {
+            const code = e.code;
+            if (code === 'ENOENT' || code === 'ENOTDIR') {
+                const parent = dirname(cur);
+                if (parent === cur)
+                    return { kind: 'unresolvable', reason: 'no existing ancestor' };
+                below.unshift(basename(cur));
+                cur = parent;
+                continue;
+            }
+            return { kind: 'unresolvable', reason: code ?? String(e) };
+        }
+        let real;
+        try {
+            real = canonical(cur);
+        }
+        catch (e) {
+            if (entry.isSymbolicLink())
+                return { kind: 'dangling', link: cur };
+            return { kind: 'unresolvable', reason: e.code ?? String(e) };
+        }
+        return {
+            kind: 'real',
+            path: below.length === 0 ? real : join(real, ...below),
+            exists: below.length === 0,
+        };
+    }
+}
 /**
  * Resolve `inputPath` and confirm it is contained within at least one
  * `allowedRoots` entry. Returns the resolved absolute path on success.
+ *
+ * Two checks, both of which must pass. The first is syntactic: `..` segments
+ * are collapsed without touching the disk and the result must sit under a
+ * root as written. The second follows the filesystem: the path's real
+ * location, including the part of it that does not exist yet, must sit under
+ * a root's real location. A link is still followed at read or write time by
+ * the tool that receives the path, so the check is against the layout at the
+ * moment of validation.
  */
 export function validatePath(inputPath, allowedRoots, options = {}) {
     if (typeof inputPath !== 'string' || inputPath.length === 0) {
@@ -28,24 +106,42 @@ export function validatePath(inputPath, allowedRoots, options = {}) {
         };
     }
     const resolved = isAbsolute(inputPath) ? resolve(inputPath) : resolve(process.cwd(), inputPath);
-    // Helper: confirm p falls under at least one of the provided root strings.
-    const isUnderRoots = (p, roots) => roots.some((root) => {
-        const rootWithSep = root.endsWith(sep) ? root : root + sep;
-        return p === root || p.startsWith(rootWithSep);
-    });
-    // Phase 1: syntactic traversal check. path.resolve() collapses `..`
-    // segments without I/O, so this catches plain traversal attacks cheaply.
     const resolvedRoots = allowedRoots.map((r) => resolve(r));
-    if (!isUnderRoots(resolved, resolvedRoots)) {
+    const outsideHint = 'Set OPA_MCP_ALLOWED_PATHS to a comma-separated list of directories, or use a path under the current allowed roots.';
+    // Phase 1: syntactic containment, cheap and free of I/O. It is not the
+    // decision on its own: a root spelled through a link (macOS /var, a Windows
+    // short name, a junction) and a path spelled through the target land in the
+    // same real place and must be accepted. It settles which message an
+    // escaping path gets. Windows compares without regard to case.
+    const syntacticallyInside = isUnderRoots(resolved, resolvedRoots, WINDOWS);
+    const outsideRoots = () => err('PATH_NOT_ALLOWED', `Path is outside allowed roots: ${inputPath}`, {
+        hint: outsideHint,
+        details: { resolved, allowedRoots },
+    });
+    // Phase 2: real location. This is the decision.
+    const location = realLocation(resolved);
+    if (location.kind === 'dangling') {
+        return {
+            ok: false,
+            error: err('PATH_NOT_ALLOWED', `Path goes through a link whose target does not exist: ${inputPath}`, {
+                hint: 'A write through a dangling link would create its target wherever the link points. Remove the link or use a path that does not go through it.',
+                details: { resolved, link: location.link },
+            }),
+        };
+    }
+    if (location.kind === 'unresolvable') {
+        if (!syntacticallyInside)
+            return { ok: false, error: outsideRoots() };
         return {
             ok: false,
-            error: err('PATH_NOT_ALLOWED', `Path is outside allowed roots: ${inputPath}`, {
-                hint: 'Set OPA_MCP_ALLOWED_PATHS to a comma-separated list of directories, or use a path under the current allowed roots.',
-                details: { resolved, allowedRoots },
+            error: err('PATH_NOT_FOUND', `Path could not be fully resolved: ${inputPath}`, {
+                details: { resolved, reason: location.reason },
             }),
         };
     }
-    if (options.mustExist && !existsSync(resolved)) {
+    if (options.mustExist && !location.exists) {
+        if (!syntacticallyInside)
+            return { ok: false, error: outsideRoots() };
         return {
             ok: false,
             error: err('PATH_NOT_FOUND', `Path does not exist: ${inputPath}`, {
@@ -53,51 +149,31 @@ export function validatePath(inputPath, allowedRoots, options = {}) {
             }),
         };
     }
-    // Phase 2: symlink resolution. path.resolve() is purely syntactic and
-    // does not follow symlinks. A symlink inside an allowed root can point
-    // arbitrarily outside. For any path that exists on disk, resolve the
-    // real target and re-validate against the real allowed-root locations.
-    //
-    // We validate via realpath but return `resolved` (the syntactic path)
-    // for backward compatibility across OSes where system directories are
-    // themselves symlinks (e.g. macOS /var -> /private/var). Callers pass
-    // the returned path to OPA/regal; the OS follows any remaining symlinks
-    // at read time, which is safe because we have verified the real target.
-    if (existsSync(resolved)) {
-        let realPath;
+    // A root that is itself a link, or spelled with a short name, compares
+    // correctly only in canonical form. A root that does not exist stays as
+    // written; nothing under it can resolve to it anyway.
+    const realRoots = resolvedRoots.map((r) => {
         try {
-            realPath = realpathSync(resolved);
+            return canonical(r);
         }
         catch {
-            // Rare race: path removed between existsSync and realpathSync, or
-            // insufficient permissions to read the symlink chain. Fail closed.
-            return {
-                ok: false,
-                error: err('PATH_NOT_FOUND', `Path could not be fully resolved: ${inputPath}`, {
-                    details: { resolved },
-                }),
-            };
-        }
-        // Also realpath the roots themselves so that a root that is a symlink
-        // compares correctly against the realpath of the input.
-        const realRoots = resolvedRoots.map((r) => {
-            try {
-                return existsSync(r) ? realpathSync(r) : r;
-            }
-            catch {
-                return r;
-            }
-        });
-        if (!isUnderRoots(realPath, realRoots)) {
-            return {
-                ok: false,
-                error: err('PATH_NOT_ALLOWED', `Path resolves outside allowed roots via symlink: ${inputPath}`, {
-                    hint: 'Set OPA_MCP_ALLOWED_PATHS to a comma-separated list of directories, or use a path under the current allowed roots.',
-                    details: { resolved, realPath, allowedRoots },
-                }),
-            };
+            return r;
         }
+    });
+    if (!isUnderRoots(location.path, realRoots, false)) {
+        if (!syntacticallyInside)
+            return { ok: false, error: outsideRoots() };
+        return {
+            ok: false,
+            error: err('PATH_NOT_ALLOWED', `Path resolves outside allowed roots via a link: ${inputPath}`, {
+                hint: outsideHint,
+                details: { resolved, realPath: location.path, allowedRoots },
+            }),
+        };
     }
+    // The syntactic path is returned, not the canonical one: on macOS the
+    // system temp directory is itself a link, and tools compare and report
+    // paths as the caller spelled them.
     return { ok: true, resolved };
 }
 /** Convenience: returns true if the path is a directory (after validation). */

package/dist/lib/security.js.map

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

package/dist/lib/subprocess.d.ts

@@ -54,7 +54,20 @@ export interface SpawnResult {
      * valid; absent means "not truncated".
      */
     outputTruncated?: boolean;
+    /**
+     * The signal that ended the child, when one did. Set for the server's own
+     * kills (timeout, cancellation, output cap) and for kills from outside it,
+     * such as the kernel's out-of-memory killer. Optional for the same reason as
+     * `outputTruncated`.
+     */
+    signal?: NodeJS.Signals | null;
 }
+/**
+ * Signal every child still running. A child sits in its own process group on
+ * POSIX, so a signal that stops the server does not reach it on its own; the
+ * server calls this on the way out. Returns how many were signalled.
+ */
+export declare function terminateChildren(sig?: NodeJS.Signals): number;
 /**
  * Run a binary and return its captured output. Never throws -- failures are
  * reflected in `exitCode` / `timedOut` / `outputTruncated`.

package/dist/lib/subprocess.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subprocess.d.ts","sourceRoot":"","sources":["../../src/lib/subprocess.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,wBAAwB,QAAmB,CAAC;AAEzD,MAAM,WAAW,YAAY;IAC3B,qDAAqD;IACrD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,wDAAwD;IACxD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,mEAAmE;IACnE,OAAO,EAAE,OAAO,CAAC;IACjB,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AA6CD;;;GAGG;AACH,wBAAsB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAmIxF"}
+{"version":3,"file":"subprocess.d.ts","sourceRoot":"","sources":["../../src/lib/subprocess.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,wBAAwB,QAAmB,CAAC;AAEzD,MAAM,WAAW,YAAY;IAC3B,qDAAqD;IACrD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,wDAAwD;IACxD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,mEAAmE;IACnE,OAAO,EAAE,OAAO,CAAC;IACjB,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;CAChC;AAgDD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAM,CAAC,OAAmB,GAAG,MAAM,CAOzE;AA6CD;;;GAGG;AACH,wBAAsB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CA4MxF"}