mcp-coordinator 0.2.1 → 0.4.0

package/dist/src/path-guard.js

@@ -0,0 +1,44 @@
+import path from "path";
+/**
+ * Resolve a request URL into a safe filesystem path within a known root.
+ *
+ * Defends against path traversal: a request like `/dashboard/../../etc/passwd`
+ * would otherwise escape the dashboard directory because `path.join` does not
+ * validate that the result stays under the root.
+ *
+ * Returns the resolved absolute path on success, or `null` if the path would
+ * escape the root, contains a null byte, or is otherwise invalid.
+ *
+ * `urlPath` should already have the route prefix stripped (e.g. for
+ * `/dashboard/app.js` pass `"app.js"`).
+ */
+export function safeJoinUnderRoot(root, urlPath) {
+    // Reject null bytes (NUL injection that some libs/OS handle inconsistently).
+    if (urlPath.includes("\0"))
+        return null;
+    // Decode percent-encoding so "%2e%2e/foo" cannot bypass the literal ".." check.
+    // decodeURIComponent throws on malformed sequences — treat as invalid.
+    let decoded;
+    try {
+        decoded = decodeURIComponent(urlPath);
+    }
+    catch {
+        return null;
+    }
+    if (decoded.includes("\0"))
+        return null;
+    // Strip leading slashes so absolute-path injection ("//etc/passwd") becomes relative.
+    const trimmed = decoded.replace(/^[/\\]+/, "");
+    // Empty after strip → caller decides what default file to serve.
+    if (trimmed === "")
+        return null;
+    const rootResolved = path.resolve(root);
+    const candidate = path.resolve(rootResolved, trimmed);
+    // The resolved candidate MUST be either equal to the root or live below it.
+    // Append separator before comparison to avoid the "/var/data" vs "/var/data-evil" trap.
+    const rootWithSep = rootResolved.endsWith(path.sep) ? rootResolved : rootResolved + path.sep;
+    if (candidate !== rootResolved && !candidate.startsWith(rootWithSep)) {
+        return null;
+    }
+    return candidate;
+}

package/dist/src/reset-guard.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Guard for the destructive `/api/reset` endpoint.
+ *
+ * `/api/reset` wipes every coordination table. When `COORDINATOR_AUTH_ENABLED`
+ * is on, the upstream auth middleware enforces admin-role tokens for this route
+ * (see `auth.ts` `ADMIN_ONLY_ROUTES`). When auth is OFF (the default), we still
+ * need to prevent accidental data loss in production.
+ *
+ * Allowed when ANY of:
+ *   - NODE_ENV === "test"          (vitest sets this automatically)
+ *   - COORDINATOR_ALLOW_RESET=true (explicit opt-in for dev/CI scripts)
+ *   - authEnabled === true         (handled by the auth middleware upstream)
+ *
+ * Otherwise rejected.
+ */
+export declare function canResetDb(env: NodeJS.ProcessEnv, authEnabled: boolean): boolean;

package/dist/src/reset-guard.js

@@ -0,0 +1,24 @@
+/**
+ * Guard for the destructive `/api/reset` endpoint.
+ *
+ * `/api/reset` wipes every coordination table. When `COORDINATOR_AUTH_ENABLED`
+ * is on, the upstream auth middleware enforces admin-role tokens for this route
+ * (see `auth.ts` `ADMIN_ONLY_ROUTES`). When auth is OFF (the default), we still
+ * need to prevent accidental data loss in production.
+ *
+ * Allowed when ANY of:
+ *   - NODE_ENV === "test"          (vitest sets this automatically)
+ *   - COORDINATOR_ALLOW_RESET=true (explicit opt-in for dev/CI scripts)
+ *   - authEnabled === true         (handled by the auth middleware upstream)
+ *
+ * Otherwise rejected.
+ */
+export function canResetDb(env, authEnabled) {
+    if (authEnabled)
+        return true;
+    if (env.NODE_ENV === "test")
+        return true;
+    if (env.COORDINATOR_ALLOW_RESET === "true")
+        return true;
+    return false;
+}

package/dist/src/serve-http.d.ts

@@ -1,5 +1,35 @@
 export interface ServerOptions {
     port?: number;
     dataDir?: string;
+    /**
+     * MQTT TCP listener port. Defaults to COORDINATOR_MQTT_TCP_PORT env or 1883.
+     * Pass an OS-ephemeral free port (see net.createServer().listen(0)) to run
+     * multiple coordinators in the same process without collision.
+     */
+    mqttTcpPort?: number;
+    /**
+     * MQTT WebSocket path on the HTTP server. Defaults to COORDINATOR_MQTT_WS_PATH or "/mqtt".
+     */
+    mqttWsPath?: string;
+    /**
+     * If false, do NOT register process-level SIGTERM/SIGINT handlers. Default
+     * true. Embedders that manage their own signals (essaim's orchestrator runs
+     * many in-process coordinators per session) should pass false and call
+     * `handle.stop()` from their own teardown.
+     */
+    registerSignalHandlers?: boolean;
 }
-export declare function startServer(opts?: ServerOptions): Promise<void>;
+/**
+ * Returned by startServer(). Lets callers shut down all owned resources
+ * (HTTP server, MQTT broker + bridge, SSE listeners, DB, quota timer) without
+ * waiting for process exit. Safe to call multiple times.
+ *
+ * Backward-compatible: previous callers used `await startServer({...})` and
+ * ignored the resolved value. They continue to work; the new return value is
+ * additive.
+ */
+export interface ServerHandle {
+    port: number;
+    stop: () => Promise<void>;
+}
+export declare function startServer(opts?: ServerOptions): Promise<ServerHandle>;