lynkr 0.1.0

package/src/mcp/permissions.js

@@ -0,0 +1,69 @@
+const config = require("../config");
+const logger = require("../logger");
+
+function normaliseValue(value) {
+  if (typeof value !== "string") return "";
+  return value.trim().toLowerCase();
+}
+
+function matchesPattern(pattern, target) {
+  if (!pattern) return false;
+  if (pattern === "*") return true;
+  if (pattern.endsWith("*")) {
+    const prefix = pattern.slice(0, -1);
+    return target.startsWith(prefix);
+  }
+  return pattern === target;
+}
+
+function evaluateSandboxRequest({ sessionId, command }) {
+  const permissions = config.mcp?.permissions ?? {};
+  const mode = typeof permissions.mode === "string" ? permissions.mode : "auto";
+  const allowList = Array.isArray(permissions.allow)
+    ? permissions.allow.map(normaliseValue)
+    : [];
+  const denyList = Array.isArray(permissions.deny)
+    ? permissions.deny.map(normaliseValue)
+    : [];
+  const target = normaliseValue(command);
+
+  if (denyList.some((pattern) => matchesPattern(pattern, target))) {
+    const reason = `Command "${command}" denied by sandbox deny list.`;
+    logger.warn({ sessionId, command }, reason);
+    return { allowed: false, reason, source: "deny_list" };
+  }
+
+  if (mode === "deny") {
+    const reason = "Sandbox execution disabled by configuration.";
+    logger.warn({ sessionId, command }, reason);
+    return { allowed: false, reason, source: "mode_deny" };
+  }
+
+  if (mode === "require") {
+    if (allowList.length === 0) {
+      const reason =
+        "Sandbox permission mode 'require' is set but no allow list entries are configured.";
+      logger.warn({ sessionId, command }, reason);
+      return { allowed: false, reason, source: "mode_require" };
+    }
+    if (!allowList.some((pattern) => matchesPattern(pattern, target))) {
+      const reason = `Command "${command}" is not permitted by sandbox allow list.`;
+      logger.warn({ sessionId, command }, reason);
+      return { allowed: false, reason, source: "mode_require" };
+    }
+    return { allowed: true, reason: "Allow list match", source: "allow_list" };
+  }
+
+  if (allowList.length > 0 && !allowList.some((pattern) => matchesPattern(pattern, target))) {
+    logger.debug(
+      { sessionId, command },
+      "Sandbox command not in allow list; proceeding because mode is not 'require'.",
+    );
+  }
+
+  return { allowed: true, source: mode === "auto" ? "auto" : "implicit_allow" };
+}
+
+module.exports = {
+  evaluateSandboxRequest,
+};

package/src/mcp/registry.js

@@ -0,0 +1,225 @@
+const fs = require("fs");
+const path = require("path");
+const config = require("../config");
+const logger = require("../logger");
+const McpClient = require("./client");
+
+const servers = new Map();
+const clients = new Map();
+let manifestLoaded = false;
+
+function normaliseServer(entry) {
+  if (!entry || typeof entry !== "object") return null;
+  const id = entry.id ?? entry.name ?? entry.label;
+  if (!id) return null;
+  return {
+    id: String(id),
+    name: entry.name ?? String(id),
+    description: entry.description ?? null,
+    command: entry.command ?? null,
+    args: Array.isArray(entry.args) ? entry.args.map(String) : [],
+    env: entry.env && typeof entry.env === "object" ? entry.env : {},
+    transport: entry.transport ?? "stdio",
+    metadata: entry.metadata && typeof entry.metadata === "object" ? entry.metadata : {},
+    raw: entry,
+  };
+}
+
+function registerServer(entry) {
+  const server = normaliseServer(entry);
+  if (!server) return null;
+  servers.set(server.id, server);
+  return server;
+}
+
+function listServers() {
+  return Array.from(servers.values());
+}
+
+function getServer(id) {
+  if (!id) return null;
+  return servers.get(String(id)) ?? null;
+}
+
+function clearServers() {
+  servers.clear();
+  manifestLoaded = false;
+  clients.forEach((client) => {
+    client.close().catch((err) => {
+      logger.debug({ err }, "Error closing MCP client");
+    });
+  });
+  clients.clear();
+}
+
+function loadServersFromEntries(entries, { source } = {}) {
+  let registeredCount = 0;
+  entries.forEach((entry) => {
+    const registered = registerServer(entry);
+    if (registered) {
+      registeredCount += 1;
+      logger.debug(
+        { mcpServer: registered.id, source },
+        "Registered MCP server",
+      );
+    }
+  });
+  if (registeredCount > 0) {
+    logger.info(
+      { count: registeredCount, source },
+      "Loaded MCP servers",
+    );
+  }
+  return registeredCount;
+}
+
+function readManifest(manifestPath) {
+  const resolved = path.resolve(manifestPath);
+  try {
+    const raw = fs.readFileSync(resolved, "utf8");
+    const parsed = JSON.parse(raw);
+    const entries = Array.isArray(parsed?.servers)
+      ? parsed.servers
+      : Array.isArray(parsed)
+      ? parsed
+      : [];
+    return { entries, path: resolved };
+  } catch (err) {
+    logger.warn({ err, manifest: resolved }, "Failed to load MCP server manifest");
+    return { entries: [], path: resolved, error: err };
+  }
+}
+
+function loadFromManifest(manifestPath, { clear = true } = {}) {
+  const { entries, path: resolved } = readManifest(manifestPath);
+  if (clear) {
+    clearServers();
+  }
+  const registeredCount = loadServersFromEntries(entries, { source: resolved });
+  manifestLoaded = manifestLoaded || registeredCount > 0;
+  return listServers();
+}
+
+function discoverManifestFiles(directories = []) {
+  const files = [];
+  directories.forEach((dir) => {
+    if (typeof dir !== "string" || dir.length === 0) return;
+    let stats = null;
+    try {
+      stats = fs.statSync(dir);
+    } catch (err) {
+      logger.debug({ dir, err }, "Manifest directory not accessible");
+      return;
+    }
+    if (!stats.isDirectory()) {
+      logger.debug({ dir }, "Manifest path is not a directory");
+      return;
+    }
+    try {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      entries.forEach((entry) => {
+        if (!entry.isFile()) return;
+        if (!entry.name.toLowerCase().endsWith(".json")) return;
+        files.push(path.join(dir, entry.name));
+      });
+    } catch (err) {
+      logger.debug({ dir, err }, "Failed to read manifest directory");
+    }
+  });
+  return files;
+}
+
+function loadConfiguredServers() {
+  const manifestPath = config.mcp?.servers?.manifestPath;
+  const manifestDirs = Array.isArray(config.mcp?.servers?.manifestDirs)
+    ? config.mcp.servers.manifestDirs
+    : [];
+
+  clearServers();
+  const seen = new Set();
+
+  if (manifestPath) {
+    const resolved = path.resolve(manifestPath);
+    seen.add(resolved);
+    loadFromManifest(resolved, { clear: false });
+  }
+
+  const discovered = discoverManifestFiles(manifestDirs);
+  discovered.forEach((filePath) => {
+    const resolved = path.resolve(filePath);
+    if (seen.has(resolved)) return;
+    seen.add(resolved);
+    const { entries } = readManifest(resolved);
+    loadServersFromEntries(entries, { source: resolved });
+  });
+
+  manifestLoaded = true;
+  listServers().forEach((server) => {
+    ensureClient(server.id).catch((err) => {
+      logger.warn({ err, server: server.id }, "Failed to start MCP client");
+    });
+  });
+  return listServers();
+}
+
+function hasLoadedManifest() {
+  return manifestLoaded;
+}
+
+async function ensureClient(serverId) {
+  if (!serverId) return null;
+  const existing = clients.get(serverId);
+  if (existing) return existing;
+  const server = getServer(serverId);
+  if (!server) return null;
+  if (server.transport && server.transport !== "stdio") {
+    logger.warn(
+      { server: server.id, transport: server.transport },
+      "Unsupported MCP transport; only 'stdio' is implemented",
+    );
+    return null;
+  }
+
+  const client = new McpClient(server);
+  clients.set(serverId, client);
+  try {
+    await client.start();
+    logger.info({ server: server.id }, "MCP client ready");
+  } catch (err) {
+    clients.delete(serverId);
+    logger.error({ err, server: server.id }, "Failed to start MCP client");
+    throw err;
+  }
+  return client;
+}
+
+function getClient(serverId) {
+  return clients.get(serverId) ?? null;
+}
+
+function listClients() {
+  return Array.from(clients.keys());
+}
+
+module.exports = {
+  registerServer,
+  listServers,
+  getServer,
+  clearServers,
+  loadFromManifest,
+  loadConfiguredServers,
+  hasLoadedManifest,
+  ensureClient,
+  getClient,
+  listClients,
+};
+
+module.exports = {
+  registerServer,
+  listServers,
+  getServer,
+  clearServers,
+  loadFromManifest,
+  loadConfiguredServers,
+  hasLoadedManifest,
+};

package/src/mcp/sandbox.js

@@ -0,0 +1,238 @@
+const { spawn } = require("child_process");
+const path = require("path");
+const config = require("../config");
+const logger = require("../logger");
+const { workspaceRoot } = require("../workspace");
+const { evaluateSandboxRequest } = require("./permissions");
+
+const DEFAULT_MAX_BUFFER = 1024 * 1024;
+const sessionStore = new Map();
+
+function isSandboxEnabled() {
+  return Boolean(config.mcp?.sandbox?.enabled);
+}
+
+function normaliseSessionId(sessionId) {
+  if (!sessionId) return "shared";
+  return String(sessionId);
+}
+
+function ensureSession(sessionId) {
+  const key = normaliseSessionId(sessionId);
+  if (!sessionStore.has(key)) {
+    sessionStore.set(key, {
+      id: key,
+      createdAt: Date.now(),
+      lastUsedAt: null,
+      runCount: 0,
+    });
+  }
+  return sessionStore.get(key);
+}
+
+function listSessions() {
+  return Array.from(sessionStore.values()).map((session) => ({
+    id: session.id,
+    createdAt: session.createdAt,
+    lastUsedAt: session.lastUsedAt,
+    runCount: session.runCount,
+  }));
+}
+
+function releaseSession(sessionId) {
+  const key = normaliseSessionId(sessionId);
+  sessionStore.delete(key);
+}
+
+function toContainerPath(hostPath) {
+  const relative = path.relative(workspaceRoot, hostPath);
+  if (relative && relative.startsWith("..")) {
+    throw new Error(`Path "${hostPath}" is outside of the workspace root and cannot be mounted.`);
+  }
+  const containerRoot = config.mcp?.sandbox?.containerWorkspace ?? "/workspace";
+  if (!relative || relative === "") {
+    return containerRoot;
+  }
+  const segments = relative.split(path.sep).filter(Boolean);
+  return [containerRoot, ...segments].join("/").replace(/\/+/g, "/");
+}
+
+function buildRuntimeArgs({ session, command, args, cwd, env }) {
+  const sandboxConfig = config.mcp?.sandbox ?? {};
+  const runtimeArgs = ["run", "--rm"];
+
+  if (!sandboxConfig.allowNetworking) {
+    runtimeArgs.push("--network", "none");
+  } else if (sandboxConfig.networkMode && sandboxConfig.networkMode !== "none") {
+    runtimeArgs.push("--network", sandboxConfig.networkMode);
+  }
+
+  if (sandboxConfig.mountWorkspace !== false) {
+    runtimeArgs.push(
+      "-v",
+      `${workspaceRoot}:${sandboxConfig.containerWorkspace ?? "/workspace"}:rw`,
+    );
+  }
+
+  for (const mount of sandboxConfig.extraMounts ?? []) {
+    runtimeArgs.push("-v", `${mount.host}:${mount.container}:${mount.mode}`);
+  }
+
+  const containerCwd = toContainerPath(cwd ?? workspaceRoot);
+  runtimeArgs.push("-w", containerCwd);
+
+  if (sandboxConfig.user) {
+    runtimeArgs.push("-u", sandboxConfig.user);
+  }
+  if (sandboxConfig.entrypoint) {
+    runtimeArgs.push("--entrypoint", sandboxConfig.entrypoint);
+  }
+
+  const passthroughEnv = new Set(
+    Array.isArray(sandboxConfig.passthroughEnv)
+      ? sandboxConfig.passthroughEnv.map((name) => String(name).toUpperCase())
+      : [],
+  );
+
+  const envArgs = [];
+  if (env && typeof env === "object") {
+    for (const [key, value] of Object.entries(env)) {
+      if (passthroughEnv.size > 0 && !passthroughEnv.has(String(key).toUpperCase())) {
+        continue;
+      }
+      if (value === undefined || value === null) continue;
+      envArgs.push("-e", `${key}=${value}`);
+    }
+  }
+
+  envArgs.push("-e", `MCP_SANDBOX_SESSION=${session.id}`);
+  runtimeArgs.push(...envArgs);
+
+  const commandArgs = Array.isArray(args) ? args.map(String) : [];
+  runtimeArgs.push(sandboxConfig.image, command, ...commandArgs);
+  return runtimeArgs;
+}
+
+function appendBuffer(current, chunk, maxBuffer) {
+  if (current.length >= maxBuffer) {
+    return { value: current, overflow: true };
+  }
+  const next = current + chunk;
+  if (next.length > maxBuffer) {
+    return { value: next.slice(0, maxBuffer), overflow: true };
+  }
+  return { value: next, overflow: false };
+}
+
+async function runSandboxProcess({
+  sessionId,
+  command,
+  args = [],
+  input,
+  cwd,
+  env,
+  timeoutMs,
+  maxBuffer = DEFAULT_MAX_BUFFER,
+}) {
+  if (!isSandboxEnabled()) {
+    throw new Error("Sandbox execution requested but the sandbox is not enabled.");
+  }
+  const sandboxConfig = config.mcp?.sandbox ?? {};
+  const session = ensureSession(sessionId);
+
+  const permission = evaluateSandboxRequest({ sessionId: session.id, command });
+  if (!permission.allowed) {
+    const error = new Error(`Sandbox permission denied: ${permission.reason}`);
+    error.code = "SANDBOX_PERMISSION_DENIED";
+    throw error;
+  }
+
+  const runtimeCommand = sandboxConfig.runtime ?? "docker";
+  const runtimeArgs = buildRuntimeArgs({
+    session,
+    command,
+    args,
+    cwd,
+    env,
+  });
+
+  logger.debug(
+    {
+      sessionId: session.id,
+      runtime: runtimeCommand,
+      args: runtimeArgs,
+      permissionSource: permission.source,
+    },
+    "Launching sandboxed process",
+  );
+
+  const timeout = Number.isFinite(timeoutMs) && timeoutMs > 0
+    ? timeoutMs
+    : sandboxConfig.defaultTimeoutMs ?? 20000;
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(runtimeCommand, runtimeArgs, {
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+    let stdoutOverflow = false;
+    let stderrOverflow = false;
+    let timedOut = false;
+    const start = Date.now();
+
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGKILL");
+    }, timeout);
+
+    child.stdout.on("data", (chunk) => {
+      const { value, overflow } = appendBuffer(stdout, chunk.toString(), maxBuffer);
+      stdout = value;
+      if (overflow) stdoutOverflow = true;
+    });
+
+    child.stderr.on("data", (chunk) => {
+      const { value, overflow } = appendBuffer(stderr, chunk.toString(), maxBuffer);
+      stderr = value;
+      if (overflow) stderrOverflow = true;
+    });
+
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+
+    child.on("close", (code, signal) => {
+      clearTimeout(timer);
+      session.lastUsedAt = Date.now();
+      session.runCount += 1;
+      resolve({
+        exitCode: code,
+        signal,
+        stdout,
+        stderr,
+        stdoutOverflow,
+        stderrOverflow,
+        timedOut,
+        durationMs: Date.now() - start,
+      });
+    });
+
+    if (typeof input === "string" && input.length > 0 && child.stdin.writable) {
+      child.stdin.write(input);
+      child.stdin.end();
+    } else if (child.stdin.writable) {
+      child.stdin.end();
+    }
+  });
+}
+
+module.exports = {
+  isSandboxEnabled,
+  runSandboxProcess,
+  ensureSession,
+  listSessions,
+  releaseSession,
+};

package/src/metrics/index.js

@@ -0,0 +1,38 @@
+const metrics = {
+  requestsTotal: 0,
+  responses: {
+    success: 0,
+    error: 0,
+  },
+  streamingSessions: 0,
+};
+
+function recordRequest() {
+  metrics.requestsTotal += 1;
+}
+
+function recordStreamingStart() {
+  metrics.streamingSessions += 1;
+}
+
+function recordResponse(status) {
+  if (status >= 200 && status < 400) {
+    metrics.responses.success += 1;
+  } else {
+    metrics.responses.error += 1;
+  }
+}
+
+function snapshot() {
+  return {
+    ...metrics,
+    timestamp: Date.now(),
+  };
+}
+
+module.exports = {
+  recordRequest,
+  recordResponse,
+  recordStreamingStart,
+  snapshot,
+};