@j0hanz/filesystem-mcp 1.19.0 → 2.0.0

package/dist/core/watcher-registry.js

@@ -0,0 +1,312 @@
+import { statSync, watch } from 'node:fs';
+import { formatUnknownErrorMessage } from './errors.js';
+import { extractPath } from './file-uri.js';
+import { Logger } from './observability.js';
+import { parseEnvInt } from './util.js';
+// Cap concurrent file watchers to avoid exhausting OS-level watch handles
+// (e.g. Linux inotify, default ~8192/user). One subscription == one watcher.
+export const MAX_WATCHERS = parseEnvInt('FS_MAX_WATCHERS', 256, 1, 4096);
+function warnWatcherCap(uri) {
+    Logger.warn(`Cannot subscribe to ${uri}: MAX_WATCHERS limit (${MAX_WATCHERS}) reached.`);
+}
+/**
+ * Owns the uri → FSWatcher map and the subscription bookkeeping around it:
+ * notify callbacks, desired subscribe/unsubscribe state, and the watcher cap —
+ * plus `acquire`, the one ladder that sequences them correctly. `acquire` awaits
+ * path validation midway and re-checks `isStale` and `hasWatcher` itself
+ * afterwards, so callers do not: they take a lease and release it. The
+ * individual primitives stay public for the state-machine tests.
+ */
+export function createWatcherRegistry() {
+    const watchers = new Map();
+    // A URI may have several notification sinks and several independent leases.
+    // Callback identity and lifetime are intentionally separate: the HTTP leg
+    // uses one stable bus-publishing callback for every listen stream, while each
+    // stream still owns one lease that must be released on close.
+    // ponytail: no per-subscription id in the SDK unsubscribe contract, so we
+    // ref-count by URI. A departed direct-notification callback can linger until
+    // the final lease ends; sends to a closed transport already fail harmlessly.
+    // The count outlives the watcher (see `dropWatcher`), so a URI whose watcher
+    // errored keeps one map entry per still-unreleased lease until they drain —
+    // no watcher slot, just bookkeeping. Per-subscription-id keying retires both
+    // this and the unsubscribe-by-URI over-release if that churn is observed.
+    const activeCallbacks = new Map();
+    const subscriberCounts = new Map();
+    const desiredState = new Map();
+    const debounceTimers = new Map();
+    let destroyed = false;
+    // 'unsubscribed' exists only to abort a subscribe that is mid-await
+    // (isStale). If no subscribe is in flight, keep no entry at all: a lingering
+    // 'unsubscribed' would permanently block the modern attach path (which never
+    // calls startSubscribe) and leak one map entry per URI ever watched. This
+    // must be idempotent: remove()'s teardown branch calls this directly and
+    // then unconditionally calls dropWatcher (which also calls this) for the
+    // same uri — the second call must not clobber what the first one set.
+    const settleDesiredState = (uri) => {
+        const current = desiredState.get(uri);
+        if (current === 'subscribing') {
+            desiredState.set(uri, 'unsubscribed');
+        }
+        else if (current !== 'unsubscribed') {
+            desiredState.delete(uri);
+        }
+    };
+    // Tears down the watcher itself, NOT the ref-count. The 'error' event calls
+    // this with leases still outstanding: clearing the count there would let the
+    // next release from one of those leases decrement from zero and drop a
+    // watcher a later subscriber re-established for the same URI. `drop` below is
+    // the only path that ends leases, and it is the only one that clears them.
+    const dropWatcher = (uri, watcher) => {
+        const current = watchers.get(uri);
+        if (current !== watcher)
+            return;
+        const timer = debounceTimers.get(uri);
+        if (timer) {
+            clearTimeout(timer);
+            debounceTimers.delete(uri);
+        }
+        watcher.close();
+        watchers.delete(uri);
+        activeCallbacks.delete(uri);
+        settleDesiredState(uri);
+    };
+    /** The last lease ended: drop the watcher and every trace of the URI. */
+    const drop = (uri) => {
+        const timer = debounceTimers.get(uri);
+        if (timer) {
+            clearTimeout(timer);
+            debounceTimers.delete(uri);
+        }
+        const watcher = watchers.get(uri);
+        if (watcher)
+            dropWatcher(uri, watcher);
+        activeCallbacks.delete(uri);
+        subscriberCounts.delete(uri);
+        settleDesiredState(uri);
+    };
+    const notifyAll = (uri) => {
+        const callbacks = activeCallbacks.get(uri);
+        if (!callbacks || callbacks.size === 0)
+            return;
+        const existing = debounceTimers.get(uri);
+        if (existing) {
+            clearTimeout(existing);
+        }
+        const timer = setTimeout(() => {
+            debounceTimers.delete(uri);
+            const cbs = activeCallbacks.get(uri);
+            if (!cbs)
+                return;
+            // One debounce timer per URI — fan out to every subscriber inside it, so
+            // a burst of changes still fires one notification round per URI, not per
+            // subscriber.
+            for (const cb of cbs) {
+                try {
+                    cb(uri);
+                }
+                catch (err) {
+                    Logger.warn(`Notify callback error for ${uri}: ${formatUnknownErrorMessage(err)}`);
+                }
+            }
+        }, 50);
+        timer.unref();
+        debounceTimers.set(uri, timer);
+    };
+    // The seven members below are hoisted out of the returned literal so `acquire`
+    // can sequence them from inside the closure. Their signatures and the shape of
+    // the returned object are unchanged — they are still public members, listed
+    // shorthand in the `return` at the bottom.
+    const hasWatcher = (uri) => watchers.has(uri);
+    const isAtCap = () => watchers.size >= MAX_WATCHERS;
+    /** The registry was destroyed, or this uri was unsubscribed, mid-await. */
+    const isStale = (uri) => destroyed || desiredState.get(uri) === 'unsubscribed';
+    const startSubscribe = (uri) => {
+        desiredState.set(uri, 'subscribing');
+    };
+    /**
+     * A subscribe that declared intent and then failed — bad URI, unvalidatable
+     * path, cap, fs.watch refusal — drops the entry entirely. Not
+     * `settleDesiredState`: that maps 'subscribing' onto 'unsubscribed' to abort
+     * an attach still mid-await, and a *finished* failure leaving 'unsubscribed'
+     * behind would make `isStale` true forever, so the modern attach path (which
+     * never calls `startSubscribe`) could never watch this uri again. Only
+     * clears its own 'subscribing' — a concurrent unsubscribe that already set
+     * 'unsubscribed' still wins.
+     */
+    const cancelSubscribe = (uri) => {
+        if (desiredState.get(uri) === 'subscribing')
+            desiredState.delete(uri);
+    };
+    const addCallback = (uri, notify) => {
+        let callbacks = activeCallbacks.get(uri);
+        if (!callbacks) {
+            callbacks = new Set();
+            activeCallbacks.set(uri, callbacks);
+        }
+        callbacks.add(notify);
+        desiredState.set(uri, 'subscribed');
+    };
+    const retain = (uri) => {
+        subscriberCounts.set(uri, (subscriberCounts.get(uri) ?? 0) + 1);
+    };
+    /**
+     * Ref-count by URI: only tear down the shared watcher when the last lease
+     * ends. Callback identity is independent from this count. A release with no
+     * lease outstanding (a rolled-back attach) drops the watcher outright.
+     */
+    const release = (uri) => {
+        const remaining = (subscriberCounts.get(uri) ?? 0) - 1;
+        if (remaining > 0) {
+            subscriberCounts.set(uri, remaining);
+            return;
+        }
+        drop(uri);
+    };
+    const attach = (uri, resolvedPath) => {
+        try {
+            // Watch directories recursively (children included) and files as-is.
+            // `fs.watch` async errors arrive via the 'error' event below, not as a
+            // sync throw, so no recursive-fallback try/catch is needed here — the
+            // outer catch handles sync throws (inotify exhaustion, path-race).
+            // `{ recursive: true }` is honored on macOS, Windows, and — since Node
+            // 20.13 — Linux; `engines.node` is >=24, so all three are covered.
+            const recursive = statSync(resolvedPath).isDirectory();
+            const watcher = watch(resolvedPath, recursive ? { recursive: true } : undefined, () => {
+                notifyAll(uri);
+            });
+            watcher.on('error', (err) => {
+                Logger.warn(`Watcher error for ${uri}: ${err.message}`);
+                dropWatcher(uri, watcher);
+            });
+            // Two attaches that both cleared `hasWatcher` before either finished
+            // validating land here for the same uri. Keep the one already wired to
+            // the callback set and close this one — overwriting the map entry would
+            // strand the first watcher's fd with nothing left holding a reference.
+            if (watchers.has(uri)) {
+                watcher.close();
+                return true;
+            }
+            watchers.set(uri, watcher);
+            return true;
+        }
+        catch (err) {
+            Logger.error(`Failed to create watcher for ${uri}: ${formatUnknownErrorMessage(err)}`);
+            return false;
+        }
+    };
+    return {
+        hasWatcher,
+        isAtCap,
+        /** Live watcher count, for pre-checking a batched listen against remaining capacity. */
+        size: () => watchers.size,
+        isStale,
+        startSubscribe,
+        cancelSubscribe,
+        addCallback,
+        retain,
+        release,
+        /**
+         * The one attach ladder both watcher entry points run: `resources/subscribe`
+         * (2025 era) and the `subscriptions/listen` filter (modern era, HTTP and
+         * stdio). Never throws — it reports the outcome and lets each caller decide
+         * what that is worth: subscribe owes its caller a precise error, and listen
+         * (`prepareListenWatchers`) treats the batch as all-or-nothing, releasing
+         * every lease it already took and rejecting the request. Idempotent per URI
+         * — a second call for an already-watched URI re-registers the notify
+         * callback (one watcher per URI).
+         *
+         * `markSubscribe` is the one branch that differs: only `resources/subscribe`
+         * declares desired state (what `isStale` aborts against). The listen path
+         * must not, or a rejected attach past that point strands a `'subscribing'`
+         * entry nothing settles. Whoever declares it, this function settles it:
+         * every failing exit past that point cancels the declaration, so no uri is
+         * poisoned for a later attach.
+         *
+         * Every `ok` return takes one lease; lifetime is the caller's to manage.
+         * HTTP releases when the listen response closes. Stdio tracks the listen
+         * request ID and releases on cancellation, SDK rejection, or graceful
+         * completion. In both legs the ref-count is by URI, so a watcher another
+         * stream still holds survives.
+         */
+        async acquire(pathGuard, uri, notify, { markSubscribe = false } = {}) {
+            // Every failing exit below routes through here, so the declaration made by
+            // `startSubscribe` can never outlive the attach that made it.
+            const fail = (result) => {
+                if (markSubscribe)
+                    cancelSubscribe(uri);
+                return result;
+            };
+            if (hasWatcher(uri)) {
+                // A watcher already tracks this uri; just (re)register the callback so
+                // its change events reach the new subscriber. No validation or cap work
+                // is needed for an already-live watcher.
+                addCallback(uri, notify);
+                retain(uri);
+                return { ok: true };
+            }
+            // A cap hit before validation and one found after the await are the same
+            // condition, and both are reported the same way.
+            if (isAtCap()) {
+                warnWatcherCap(uri);
+                return { ok: false, reason: 'capped' };
+            }
+            if (markSubscribe)
+                startSubscribe(uri);
+            const filePath = extractPath(uri);
+            if (!filePath)
+                return fail({ ok: false, reason: 'bad-uri' });
+            let resolved;
+            try {
+                resolved = await pathGuard.validateExistingPath(filePath);
+            }
+            catch (error) {
+                return fail({ ok: false, reason: 'invalid-path', error });
+            }
+            // Re-check what the await could have changed. A stale uri is the one
+            // failure that must NOT cancel: an unsubscribe landed mid-await and its
+            // 'unsubscribed' marker is the thing that aborted this attach.
+            if (isStale(uri))
+                return { ok: false, reason: 'stale' };
+            if (hasWatcher(uri)) {
+                addCallback(uri, notify);
+                retain(uri);
+                return { ok: true };
+            }
+            if (isAtCap()) {
+                warnWatcherCap(uri);
+                return fail({ ok: false, reason: 'capped' });
+            }
+            addCallback(uri, notify);
+            if (!attach(uri, resolved)) {
+                // fs.watch threw (inotify exhaustion, or a race deleted the path): roll
+                // back so no dangling callback is left believing a watcher exists. No
+                // lease was taken yet, so `release` drops the entry outright.
+                release(uri);
+                return fail({ ok: false, reason: 'attach-failed' });
+            }
+            retain(uri);
+            return { ok: true };
+        },
+        attach,
+        destroy() {
+            destroyed = true;
+            for (const timer of debounceTimers.values()) {
+                clearTimeout(timer);
+            }
+            debounceTimers.clear();
+            for (const watcher of watchers.values()) {
+                try {
+                    watcher.close();
+                }
+                catch {
+                    /* ignore close errors so all watchers are attempted */
+                }
+            }
+            watchers.clear();
+            activeCallbacks.clear();
+            subscriberCounts.clear();
+            desiredState.clear();
+        },
+    };
+}
+//# sourceMappingURL=watcher-registry.js.map

package/dist/core/watcher-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watcher-registry.js","sourceRoot":"","sources":["../../src/core/watcher-registry.ts"],"names":[],"mappings":"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","sourcesContent":["import type { FSWatcher } from 'node:fs';\nimport { statSync, watch } from 'node:fs';\n\nimport { formatUnknownErrorMessage } from './errors.js';\nimport { extractPath } from './file-uri.js';\nimport { Logger } from './observability.js';\nimport type { PathGuard } from './path.js';\nimport { parseEnvInt } from './util.js';\n\n// Cap concurrent file watchers to avoid exhausting OS-level watch handles\n// (e.g. Linux inotify, default ~8192/user). One subscription == one watcher.\nexport const MAX_WATCHERS = parseEnvInt('FS_MAX_WATCHERS', 256, 1, 4096);\n\nfunction warnWatcherCap(uri: string): void {\n  Logger.warn(`Cannot subscribe to ${uri}: MAX_WATCHERS limit (${MAX_WATCHERS}) reached.`);\n}\n\n/**\n * `ok` means a watcher is live for this uri and `notify` is registered. Every\n * other outcome names why, and only `invalid-path` carries what\n * `validateExistingPath` threw — so `error` is unreachable on a branch that has\n * none.\n */\nexport type WatcherAttachResult =\n  | { ok: true }\n  | { ok: false; reason: 'stale' | 'capped' | 'bad-uri' | 'attach-failed' }\n  | { ok: false; reason: 'invalid-path'; error: unknown };\n\n/**\n * Owns the uri → FSWatcher map and the subscription bookkeeping around it:\n * notify callbacks, desired subscribe/unsubscribe state, and the watcher cap —\n * plus `acquire`, the one ladder that sequences them correctly. `acquire` awaits\n * path validation midway and re-checks `isStale` and `hasWatcher` itself\n * afterwards, so callers do not: they take a lease and release it. The\n * individual primitives stay public for the state-machine tests.\n */\nexport function createWatcherRegistry() {\n  const watchers = new Map<string, FSWatcher>();\n  // A URI may have several notification sinks and several independent leases.\n  // Callback identity and lifetime are intentionally separate: the HTTP leg\n  // uses one stable bus-publishing callback for every listen stream, while each\n  // stream still owns one lease that must be released on close.\n  // ponytail: no per-subscription id in the SDK unsubscribe contract, so we\n  // ref-count by URI. A departed direct-notification callback can linger until\n  // the final lease ends; sends to a closed transport already fail harmlessly.\n  // The count outlives the watcher (see `dropWatcher`), so a URI whose watcher\n  // errored keeps one map entry per still-unreleased lease until they drain —\n  // no watcher slot, just bookkeeping. Per-subscription-id keying retires both\n  // this and the unsubscribe-by-URI over-release if that churn is observed.\n  const activeCallbacks = new Map<string, Set<(uri: string) => void>>();\n  const subscriberCounts = new Map<string, number>();\n  const desiredState = new Map<string, 'subscribed' | 'unsubscribed' | 'subscribing'>();\n  const debounceTimers = new Map<string, NodeJS.Timeout>();\n  let destroyed = false;\n\n  // 'unsubscribed' exists only to abort a subscribe that is mid-await\n  // (isStale). If no subscribe is in flight, keep no entry at all: a lingering\n  // 'unsubscribed' would permanently block the modern attach path (which never\n  // calls startSubscribe) and leak one map entry per URI ever watched. This\n  // must be idempotent: remove()'s teardown branch calls this directly and\n  // then unconditionally calls dropWatcher (which also calls this) for the\n  // same uri — the second call must not clobber what the first one set.\n  const settleDesiredState = (uri: string): void => {\n    const current = desiredState.get(uri);\n    if (current === 'subscribing') {\n      desiredState.set(uri, 'unsubscribed');\n    } else if (current !== 'unsubscribed') {\n      desiredState.delete(uri);\n    }\n  };\n\n  // Tears down the watcher itself, NOT the ref-count. The 'error' event calls\n  // this with leases still outstanding: clearing the count there would let the\n  // next release from one of those leases decrement from zero and drop a\n  // watcher a later subscriber re-established for the same URI. `drop` below is\n  // the only path that ends leases, and it is the only one that clears them.\n  const dropWatcher = (uri: string, watcher: FSWatcher): void => {\n    const current = watchers.get(uri);\n    if (current !== watcher) return;\n    const timer = debounceTimers.get(uri);\n    if (timer) {\n      clearTimeout(timer);\n      debounceTimers.delete(uri);\n    }\n    watcher.close();\n    watchers.delete(uri);\n    activeCallbacks.delete(uri);\n    settleDesiredState(uri);\n  };\n\n  /** The last lease ended: drop the watcher and every trace of the URI. */\n  const drop = (uri: string): void => {\n    const timer = debounceTimers.get(uri);\n    if (timer) {\n      clearTimeout(timer);\n      debounceTimers.delete(uri);\n    }\n    const watcher = watchers.get(uri);\n    if (watcher) dropWatcher(uri, watcher);\n    activeCallbacks.delete(uri);\n    subscriberCounts.delete(uri);\n    settleDesiredState(uri);\n  };\n\n  const notifyAll = (uri: string): void => {\n    const callbacks = activeCallbacks.get(uri);\n    if (!callbacks || callbacks.size === 0) return;\n    const existing = debounceTimers.get(uri);\n    if (existing) {\n      clearTimeout(existing);\n    }\n    const timer = setTimeout(() => {\n      debounceTimers.delete(uri);\n      const cbs = activeCallbacks.get(uri);\n      if (!cbs) return;\n      // One debounce timer per URI — fan out to every subscriber inside it, so\n      // a burst of changes still fires one notification round per URI, not per\n      // subscriber.\n      for (const cb of cbs) {\n        try {\n          cb(uri);\n        } catch (err) {\n          Logger.warn(`Notify callback error for ${uri}: ${formatUnknownErrorMessage(err)}`);\n        }\n      }\n    }, 50);\n    timer.unref();\n    debounceTimers.set(uri, timer);\n  };\n\n  // The seven members below are hoisted out of the returned literal so `acquire`\n  // can sequence them from inside the closure. Their signatures and the shape of\n  // the returned object are unchanged — they are still public members, listed\n  // shorthand in the `return` at the bottom.\n\n  const hasWatcher = (uri: string): boolean => watchers.has(uri);\n\n  const isAtCap = (): boolean => watchers.size >= MAX_WATCHERS;\n\n  /** The registry was destroyed, or this uri was unsubscribed, mid-await. */\n  const isStale = (uri: string): boolean => destroyed || desiredState.get(uri) === 'unsubscribed';\n\n  const startSubscribe = (uri: string): void => {\n    desiredState.set(uri, 'subscribing');\n  };\n\n  /**\n   * A subscribe that declared intent and then failed — bad URI, unvalidatable\n   * path, cap, fs.watch refusal — drops the entry entirely. Not\n   * `settleDesiredState`: that maps 'subscribing' onto 'unsubscribed' to abort\n   * an attach still mid-await, and a *finished* failure leaving 'unsubscribed'\n   * behind would make `isStale` true forever, so the modern attach path (which\n   * never calls `startSubscribe`) could never watch this uri again. Only\n   * clears its own 'subscribing' — a concurrent unsubscribe that already set\n   * 'unsubscribed' still wins.\n   */\n  const cancelSubscribe = (uri: string): void => {\n    if (desiredState.get(uri) === 'subscribing') desiredState.delete(uri);\n  };\n\n  const addCallback = (uri: string, notify: (uri: string) => void): void => {\n    let callbacks = activeCallbacks.get(uri);\n    if (!callbacks) {\n      callbacks = new Set();\n      activeCallbacks.set(uri, callbacks);\n    }\n    callbacks.add(notify);\n    desiredState.set(uri, 'subscribed');\n  };\n\n  const retain = (uri: string): void => {\n    subscriberCounts.set(uri, (subscriberCounts.get(uri) ?? 0) + 1);\n  };\n\n  /**\n   * Ref-count by URI: only tear down the shared watcher when the last lease\n   * ends. Callback identity is independent from this count. A release with no\n   * lease outstanding (a rolled-back attach) drops the watcher outright.\n   */\n  const release = (uri: string): void => {\n    const remaining = (subscriberCounts.get(uri) ?? 0) - 1;\n    if (remaining > 0) {\n      subscriberCounts.set(uri, remaining);\n      return;\n    }\n    drop(uri);\n  };\n\n  const attach = (uri: string, resolvedPath: string): boolean => {\n    try {\n      // Watch directories recursively (children included) and files as-is.\n      // `fs.watch` async errors arrive via the 'error' event below, not as a\n      // sync throw, so no recursive-fallback try/catch is needed here — the\n      // outer catch handles sync throws (inotify exhaustion, path-race).\n      // `{ recursive: true }` is honored on macOS, Windows, and — since Node\n      // 20.13 — Linux; `engines.node` is >=24, so all three are covered.\n      const recursive = statSync(resolvedPath).isDirectory();\n      const watcher = watch(resolvedPath, recursive ? { recursive: true } : undefined, () => {\n        notifyAll(uri);\n      });\n      watcher.on('error', (err: Error) => {\n        Logger.warn(`Watcher error for ${uri}: ${err.message}`);\n        dropWatcher(uri, watcher);\n      });\n      // Two attaches that both cleared `hasWatcher` before either finished\n      // validating land here for the same uri. Keep the one already wired to\n      // the callback set and close this one — overwriting the map entry would\n      // strand the first watcher's fd with nothing left holding a reference.\n      if (watchers.has(uri)) {\n        watcher.close();\n        return true;\n      }\n      watchers.set(uri, watcher);\n      return true;\n    } catch (err) {\n      Logger.error(`Failed to create watcher for ${uri}: ${formatUnknownErrorMessage(err)}`);\n      return false;\n    }\n  };\n\n  return {\n    hasWatcher,\n\n    isAtCap,\n\n    /** Live watcher count, for pre-checking a batched listen against remaining capacity. */\n    size: (): number => watchers.size,\n\n    isStale,\n\n    startSubscribe,\n\n    cancelSubscribe,\n\n    addCallback,\n\n    retain,\n\n    release,\n\n    /**\n     * The one attach ladder both watcher entry points run: `resources/subscribe`\n     * (2025 era) and the `subscriptions/listen` filter (modern era, HTTP and\n     * stdio). Never throws — it reports the outcome and lets each caller decide\n     * what that is worth: subscribe owes its caller a precise error, and listen\n     * (`prepareListenWatchers`) treats the batch as all-or-nothing, releasing\n     * every lease it already took and rejecting the request. Idempotent per URI\n     * — a second call for an already-watched URI re-registers the notify\n     * callback (one watcher per URI).\n     *\n     * `markSubscribe` is the one branch that differs: only `resources/subscribe`\n     * declares desired state (what `isStale` aborts against). The listen path\n     * must not, or a rejected attach past that point strands a `'subscribing'`\n     * entry nothing settles. Whoever declares it, this function settles it:\n     * every failing exit past that point cancels the declaration, so no uri is\n     * poisoned for a later attach.\n     *\n     * Every `ok` return takes one lease; lifetime is the caller's to manage.\n     * HTTP releases when the listen response closes. Stdio tracks the listen\n     * request ID and releases on cancellation, SDK rejection, or graceful\n     * completion. In both legs the ref-count is by URI, so a watcher another\n     * stream still holds survives.\n     */\n    async acquire(\n      pathGuard: PathGuard,\n      uri: string,\n      notify: (uri: string) => void,\n      { markSubscribe = false }: { markSubscribe?: boolean } = {},\n    ): Promise<WatcherAttachResult> {\n      // Every failing exit below routes through here, so the declaration made by\n      // `startSubscribe` can never outlive the attach that made it.\n      const fail = (result: WatcherAttachResult & { ok: false }): WatcherAttachResult => {\n        if (markSubscribe) cancelSubscribe(uri);\n        return result;\n      };\n\n      if (hasWatcher(uri)) {\n        // A watcher already tracks this uri; just (re)register the callback so\n        // its change events reach the new subscriber. No validation or cap work\n        // is needed for an already-live watcher.\n        addCallback(uri, notify);\n        retain(uri);\n        return { ok: true };\n      }\n      // A cap hit before validation and one found after the await are the same\n      // condition, and both are reported the same way.\n      if (isAtCap()) {\n        warnWatcherCap(uri);\n        return { ok: false, reason: 'capped' };\n      }\n\n      if (markSubscribe) startSubscribe(uri);\n\n      const filePath = extractPath(uri);\n      if (!filePath) return fail({ ok: false, reason: 'bad-uri' });\n\n      let resolved: string;\n      try {\n        resolved = await pathGuard.validateExistingPath(filePath);\n      } catch (error: unknown) {\n        return fail({ ok: false, reason: 'invalid-path', error });\n      }\n\n      // Re-check what the await could have changed. A stale uri is the one\n      // failure that must NOT cancel: an unsubscribe landed mid-await and its\n      // 'unsubscribed' marker is the thing that aborted this attach.\n      if (isStale(uri)) return { ok: false, reason: 'stale' };\n      if (hasWatcher(uri)) {\n        addCallback(uri, notify);\n        retain(uri);\n        return { ok: true };\n      }\n      if (isAtCap()) {\n        warnWatcherCap(uri);\n        return fail({ ok: false, reason: 'capped' });\n      }\n\n      addCallback(uri, notify);\n      if (!attach(uri, resolved)) {\n        // fs.watch threw (inotify exhaustion, or a race deleted the path): roll\n        // back so no dangling callback is left believing a watcher exists. No\n        // lease was taken yet, so `release` drops the entry outright.\n        release(uri);\n        return fail({ ok: false, reason: 'attach-failed' });\n      }\n      retain(uri);\n      return { ok: true };\n    },\n\n    attach,\n\n    destroy(): void {\n      destroyed = true;\n      for (const timer of debounceTimers.values()) {\n        clearTimeout(timer);\n      }\n      debounceTimers.clear();\n      for (const watcher of watchers.values()) {\n        try {\n          watcher.close();\n        } catch {\n          /* ignore close errors so all watchers are attempted */\n        }\n      }\n      watchers.clear();\n      activeCallbacks.clear();\n      subscriberCounts.clear();\n      desiredState.clear();\n    },\n  };\n}\n\nexport type WatcherRegistry = ReturnType<typeof createWatcherRegistry>;\n"]}

package/dist/http-policy.d.ts

@@ -0,0 +1,121 @@
+import type { Request, RequestHandler, Response } from 'express';
+/**
+ * The one JSON-RPC error envelope every HTTP refusal goes out in — this
+ * module's pre-handler rejections and `transport.ts`'s. It lives here because
+ * `transport.ts` already imports this module and not the other way round; a
+ * second hand-built literal is how the two drift apart.
+ *
+ * `headers` carries what a particular refusal owes the client on top of the
+ * JSON content type — `WWW-Authenticate` on a 401, `Retry-After` on a 429.
+ * Goes out through `res.json` so every refusal keeps the `charset=utf-8` and
+ * `Content-Length` a hand-rolled `writeHead`/`end` pair drops.
+ */
+export declare function sendJsonRpcError(res: Response, status: number, code: number, message: string, id?: string | number | null, headers?: Record<string, string>): void;
+/**
+ * Pure HTTP auth and binding policy. Holds no state; all functions are
+ * directly testable without spinning up a server.
+ */
+export declare function isLoopbackHttpHost(host: string): boolean;
+export declare function isAllowedLocalhostOrigin(origin: string): boolean;
+/**
+ * True if `origin` (a raw `Origin` request header) is allowed given the
+ * env-derived `allowedHostnames` set (hostname-form, no scheme/port). Localhost
+ * origins are always accepted via {@link isAllowedLocalhostOrigin}; a remote
+ * origin is accepted iff its parsed hostname is in the set. Both the SDK app's
+ * `allowedOrigins` and this OPTIONS-handler check consume hostname-form, so a
+ * remote origin allowed via `FS_ALLOWED_ORIGINS` is reflected
+ * end-to-end in `Access-Control-Allow-Origin`.
+ */
+export declare function isOriginAllowed(origin: string, allowedHostnames: readonly string[]): boolean;
+export declare function validateBearerAuthorization(apiKey: string, authHeader: unknown): authHeader is string;
+/**
+ * Refuse to bind to a non-loopback host without an API key. Throws on
+ * policy violation; returns silently when allowed.
+ */
+export declare function assertHttpBindingPolicy(host: string, apiKey: string | undefined): void;
+/**
+ * The Host header values this bind accepts. `FS_ALLOWED_HOSTS` wins
+ * when set; otherwise a loopback bind takes the whole localhost hostname set (a
+ * client dialing http://localhost:<port> sends `Host: localhost`, which a bare
+ * ['127.0.0.1'] list would 403), a wildcard bind takes none, and a concrete
+ * non-loopback bind takes itself. An empty result means no Host validation is
+ * mounted — only reachable under FS_ALLOW_UNRESTRICTED_HOSTS=1.
+ */
+export declare function resolveAllowedHosts(httpHost: string, allowedHostsEnv: string | undefined): string[];
+/**
+ * Express's `trust proxy` setting from `FS_TRUST_PROXY`. A
+ * non-negative integer hop count parses to a number (Express counts hops from
+ * the socket); anything else (a subnet name/expression, or a negative/
+ * non-integer string) passes through unchanged for Express to interpret.
+ * `undefined` means the env var was unset or empty — leave Express's default
+ * (disabled) in place.
+ */
+export declare function resolveTrustProxySetting(value: string | undefined): number | string | undefined;
+/**
+ * Refuse to bind a wildcard host (`0.0.0.0` / `::`) without an explicit
+ * `FS_ALLOWED_HOSTS` list. Clients never send `Host: 0.0.0.0`, so
+ * defaulting the allowed-host set to the wildcard string would reject all real
+ * traffic. Operators who accept the risk can set
+ * `FS_ALLOW_UNRESTRICTED_HOSTS=1` to restore warn-and-bind.
+ * Loopback and concrete non-loopback hosts are unaffected.
+ */
+export declare function assertHttpHostPolicy(host: string, allowedHosts: readonly string[], allowUnrestricted: boolean): void;
+/**
+ * This server is a resource server with no authorization server: `API_KEY` is a
+ * static secret the operator hands out of band, not an issued token. So the
+ * metadata document deliberately omits `authorization_servers` — RFC 9728 §2
+ * makes it optional, and its absence is the accurate statement that a token
+ * cannot be obtained from an endpoint. `mcpAuthMetadataRouter` from
+ * `@modelcontextprotocol/express` is the tool for the IdP-backed case: it
+ * requires RFC 8414 authorization-server metadata, and inventing an issuer with
+ * endpoints that answer nothing would send clients into a flow that cannot
+ * complete. Adopt it if this ever moves to a real IdP.
+ *
+ * What discovery buys here: a client hitting 401 learns the resource identifier
+ * and that the credential goes in the Authorization header, instead of a bare
+ * challenge plus a 404 on the well-known path.
+ */
+export declare function protectedResourceUrl(req: Request, hostValidated: boolean, configured: string | undefined): URL | null;
+/**
+ * Express middleware: when `apiKey` is set, require a matching bearer token.
+ * No key set = open access (loopback dev mode). `apiKey` is captured once per
+ * app setup (passed in from startHttpServer) so the middleware and
+ * assertHttpBindingPolicy share one source of truth.
+ *
+ * `requireBearerAuth` + `verifyAccessToken` from `@modelcontextprotocol/express`
+ * is the tool for verifier-backed tokens; this middleware stays hand-rolled
+ * because the credential is a static operator key with no verifier, the 401 body
+ * must stay a JSON-RPC envelope, and the RFC 6750 bare-vs-`invalid_token`
+ * challenge split is implemented here. Adopt `requireBearerAuth` if this ever
+ * verifies issued tokens.
+ */
+export declare function bearerAuthMiddleware(apiKey: string | undefined, hostValidated: boolean, publicUrl?: string): RequestHandler;
+/**
+ * Env-derived CORS origins (hostname-form, no scheme/port — matches the SDK
+ * app's `allowedOrigins` consumer). Defaults to the SDK's loopback hostname set
+ * so loopback browser clients keep working; operators set
+ * `FS_ALLOWED_ORIGINS` to allow remote clients on non-loopback
+ * binds. An empty value reads as unset, matching how parseAllowedHostsEnv
+ * treats an all-empty list. The same set is consulted by corsPreflightHandler
+ * so a remote origin is reflected end-to-end in Access-Control-Allow-Origin.
+ */
+export declare function computeAllowedOriginHostnames(originsEnv: string | undefined): string[];
+/** Mounted ahead of the `/mcp` handlers so every response — not just the
+ * OPTIONS preflight — carries `Access-Control-Allow-Origin` for an allowed
+ * Origin. */
+export declare function corsOriginMiddleware(allowedOriginHostnames: readonly string[]): RequestHandler;
+/**
+ * OPTIONS preflight for `/mcp`. The allow-list carries the SEP-2243 standard
+ * headers (`mcp-protocol-version`, `mcp-method`, `mcp-name`): SDK clients send
+ * all three on every modern request POST and `createMcpHandler` requires them
+ * (400 / -32020), so omitting them here would fail every browser preflight —
+ * and the HTTP leg is modern-only, so there is no legacy path to fall back to.
+ * `mcp-session-id` is deliberately absent: it is 2025-era only and this
+ * endpoint rejects legacy traffic.
+ */
+export declare function corsPreflightHandler(allowedOriginHostnames: readonly string[]): RequestHandler;
+/**
+ * Fixed-window per-client-IP rate limiter.
+ */
+export declare function createRateLimiter(max: number): RequestHandler;
+//# sourceMappingURL=http-policy.d.ts.map

package/dist/http-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-policy.d.ts","sourceRoot":"","sources":["../src/http-policy.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAgB,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAe/E;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,QAAQ,EACb,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,EAAE,GAAE,MAAM,GAAG,MAAM,GAAG,IAAW,EACjC,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GACnC,IAAI,CAEN;AAID;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAQxD;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEhE;AAgBD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAI5F;AAED,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,OAAO,GAClB,UAAU,IAAI,MAAM,CAiBtB;AAMD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAetF;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,GAAG,SAAS,GAClC,MAAM,EAAE,CAMV;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAI/F;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,iBAAiB,EAAE,OAAO,GACzB,IAAI,CAUN;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,OAAO,EACZ,aAAa,EAAE,OAAO,EACtB,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,GAAG,GAAG,IAAI,CAcZ;AAyBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,aAAa,EAAE,OAAO,EACtB,SAAS,CAAC,EAAE,MAAM,GACjB,cAAc,CAgChB;AAED;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAKtF;AAyBD;;aAEa;AACb,wBAAgB,oBAAoB,CAAC,sBAAsB,EAAE,SAAS,MAAM,EAAE,GAAG,cAAc,CAK9F;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,sBAAsB,EAAE,SAAS,MAAM,EAAE,GAAG,cAAc,CAU9F;AAYD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CA+B7D"}