@klhapp/skillmux 0.2.0

package/src/scan.ts

@@ -0,0 +1,260 @@
+import { existsSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { decodeUtf8Strict, listSupportingFiles, scanVault } from "./vault";
+
+export type ScanSeverity = "low" | "medium" | "high";
+
+export interface RuleMatch {
+  rule_id: string;
+  severity: ScanSeverity;
+  message: string;
+  line?: number;
+}
+
+export type Rule = (content: string) => RuleMatch[];
+
+function lineOf(content: string, index: number): number {
+  return content.slice(0, index).split("\n").length;
+}
+
+const INJECTION_PHRASES = [
+  "ignore previous instructions",
+  "ignore all previous instructions",
+  "ignore your instructions",
+  "disregard all prior instructions",
+  "disregard the above",
+  "disregard previous instructions",
+  "new instructions:",
+  "system prompt:",
+  "you are now",
+];
+
+export const promptInjectionPhraseRule: Rule = (content) => {
+  const lower = content.toLowerCase();
+  const matches: RuleMatch[] = [];
+  for (const phrase of INJECTION_PHRASES) {
+    const index = lower.indexOf(phrase);
+    if (index !== -1) {
+      matches.push({
+        rule_id: "prompt-injection-phrase",
+        severity: "high",
+        message: `contains instruction-override phrase: "${phrase}"`,
+        line: lineOf(content, index),
+      });
+    }
+  }
+  return matches;
+};
+
+const INVISIBLE_CODE_POINTS = new Set([0x200b, 0x200c, 0x200d, 0xfeff]);
+const TAG_CHAR_START = 0xe0000;
+const TAG_CHAR_END = 0xe007f;
+
+function isInvisibleCodePoint(codePoint: number): boolean {
+  return INVISIBLE_CODE_POINTS.has(codePoint) || (codePoint >= TAG_CHAR_START && codePoint <= TAG_CHAR_END);
+}
+
+export const invisibleUnicodeRule: Rule = (content) => {
+  let count = 0;
+  let firstIndex = -1;
+  let searchOffset = 0;
+  for (const char of content) {
+    const codePoint = char.codePointAt(0)!;
+    if (isInvisibleCodePoint(codePoint)) {
+      count++;
+      if (firstIndex === -1) firstIndex = searchOffset;
+    }
+    searchOffset += char.length;
+  }
+  if (count === 0) return [];
+  return [
+    {
+      rule_id: "invisible-unicode",
+      severity: "high",
+      message: `contains ${count} invisible/zero-width Unicode character${count === 1 ? "" : "s"}`,
+      line: lineOf(content, firstIndex),
+    },
+  ];
+};
+
+const SECRET_PATTERNS: { pattern: RegExp; describe: string }[] = [
+  { pattern: /AKIA[0-9A-Z]{16}/, describe: "AWS-style access key" },
+  { pattern: /-----BEGIN (RSA |EC |OPENSSH |)PRIVATE KEY-----/, describe: "PEM private key block" },
+  {
+    pattern: /\b(api[_-]?key|token|secret)\s*[:=]\s*["']?[A-Za-z0-9_-]{16,}["']?/i,
+    describe: "hardcoded credential-shaped assignment",
+  },
+];
+
+export const secretPatternRule: Rule = (content) => {
+  const matches: RuleMatch[] = [];
+  for (const { pattern, describe } of SECRET_PATTERNS) {
+    const match = pattern.exec(content);
+    if (match) {
+      matches.push({
+        rule_id: "secret-pattern",
+        severity: "high",
+        message: `contains a ${describe}`,
+        line: lineOf(content, match.index),
+      });
+    }
+  }
+  return matches;
+};
+
+const URL_PATTERN = /https?:\/\/[^\s)"']+/g;
+const BARE_IP_URL_PATTERN = /^https?:\/\/(?:\d{1,3}\.){3}\d{1,3}(?::\d+)?/;
+const EXFIL_PHRASES = [
+  "post this to",
+  "send this to",
+  "upload this to",
+  "send the contents",
+  "exfiltrate",
+];
+
+export const suspiciousUrlRule: Rule = (content) => {
+  const lower = content.toLowerCase();
+  const matches: RuleMatch[] = [];
+  for (const match of content.matchAll(URL_PATTERN)) {
+    const url = match[0]!;
+    if (BARE_IP_URL_PATTERN.test(url)) {
+      matches.push({
+        rule_id: "suspicious-url",
+        severity: "medium",
+        message: `bare-IP-address URL: ${url}`,
+        line: lineOf(content, match.index!),
+      });
+      continue;
+    }
+    const nearby = lower.slice(Math.max(0, match.index! - 60), match.index!);
+    const exfilPhrase = EXFIL_PHRASES.find((phrase) => nearby.includes(phrase));
+    if (exfilPhrase) {
+      matches.push({
+        rule_id: "suspicious-url",
+        severity: "medium",
+        message: `URL paired with exfiltration-suggesting text ("${exfilPhrase}"): ${url}`,
+        line: lineOf(content, match.index!),
+      });
+    }
+  }
+  return matches;
+};
+
+export const RULES: Rule[] = [promptInjectionPhraseRule, invisibleUnicodeRule, secretPatternRule, suspiciousUrlRule];
+
+export function scanContent(content: string): RuleMatch[] {
+  return RULES.flatMap((rule) => rule(content));
+}
+
+export interface ScanFinding extends RuleMatch {
+  skill_id: string;
+  file: string;
+}
+
+export interface ScanResult {
+  scanned: number;
+  findings: ScanFinding[];
+}
+
+interface ScanContentTarget {
+  skill_id: string;
+  file: string;
+  content: string;
+}
+
+export async function readTextFileOrNull(path: string): Promise<string | null> {
+  try {
+    const bytes = await Bun.file(path).bytes();
+    return decodeUtf8Strict(bytes);
+  } catch {
+    return null;
+  }
+}
+
+async function collectSkillTargets(
+  vaultPath: string,
+  skillId: string,
+  skillMdBody: string,
+): Promise<ScanContentTarget[]> {
+  const targets: ScanContentTarget[] = [{ skill_id: skillId, file: "SKILL.md", content: skillMdBody }];
+  for (const rel of listSupportingFiles(vaultPath, skillId)) {
+    const content = await readTextFileOrNull(join(vaultPath, skillId, rel));
+    if (content !== null) targets.push({ skill_id: skillId, file: rel, content });
+  }
+  return targets;
+}
+
+interface ResolvedScanTargets {
+  targets: ScanContentTarget[];
+  /** skill_ids whose SKILL.md could not be parsed/decoded — must still be counted and
+   *  flagged, never silently dropped, or a malformed SKILL.md becomes a scan-evasion trick. */
+  unparseable: string[];
+}
+
+/** Single-skill-dir mode when `rootPath` itself holds a SKILL.md; otherwise treats
+ *  `rootPath` as a vault root and enumerates every skill dir under it. */
+async function resolveScanTargets(rootPath: string): Promise<ResolvedScanTargets> {
+  if (existsSync(join(rootPath, "SKILL.md"))) {
+    const skillId = basename(rootPath);
+    const vaultPath = dirname(rootPath);
+    const body = await readTextFileOrNull(join(rootPath, "SKILL.md"));
+    if (body === null) return { targets: [], unparseable: [skillId] };
+    return { targets: await collectSkillTargets(vaultPath, skillId, body), unparseable: [] };
+  }
+
+  const unparseable: string[] = [];
+  const skills = await scanVault(rootPath, (skillId) => unparseable.push(skillId));
+  const targets: ScanContentTarget[] = [];
+  for (const skill of skills) {
+    targets.push(...(await collectSkillTargets(rootPath, skill.skill_id, skill.body)));
+  }
+  return { targets, unparseable };
+}
+
+export async function scanPath(rootPath: string): Promise<ScanResult> {
+  const { targets, unparseable } = await resolveScanTargets(rootPath);
+  const findings: ScanFinding[] = [];
+  const skillIds = new Set<string>();
+  for (const target of targets) {
+    skillIds.add(target.skill_id);
+    for (const match of scanContent(target.content)) {
+      findings.push({ ...match, skill_id: target.skill_id, file: target.file });
+    }
+  }
+  for (const skillId of unparseable) {
+    skillIds.add(skillId);
+    findings.push({
+      skill_id: skillId,
+      file: "SKILL.md",
+      rule_id: "unparseable-skill",
+      severity: "medium",
+      message: "SKILL.md could not be parsed or decoded — content was not scanned; review manually",
+    });
+  }
+  return { scanned: skillIds.size, findings };
+}
+
+export function renderScanText(result: ScanResult): string {
+  const skillWord = result.scanned === 1 ? "skill" : "skills";
+  if (result.findings.length === 0) {
+    return `scanned ${result.scanned} ${skillWord}, no findings`;
+  }
+  const lines: string[] = [`scanned ${result.scanned} ${skillWord}, ${result.findings.length} finding(s)`];
+  for (const finding of result.findings) {
+    const location = finding.line !== undefined ? `${finding.file}:${finding.line}` : finding.file;
+    lines.push(`[${finding.severity}] ${finding.skill_id}/${location} ${finding.rule_id} — ${finding.message}`);
+  }
+  return lines.join("\n");
+}
+
+export function renderScanJson(result: ScanResult): string {
+  return JSON.stringify(result, null, 2);
+}
+
+const SEVERITY_RANK: Record<ScanSeverity, number> = { low: 0, medium: 1, high: 2 };
+
+export function scanExitCode(findings: RuleMatch[], failOn: ScanSeverity | undefined): number {
+  if (!failOn) return 0;
+  const threshold = SEVERITY_RANK[failOn];
+  return findings.some((f) => SEVERITY_RANK[f.severity] >= threshold) ? 1 : 0;
+}

package/src/server.ts

@@ -0,0 +1,318 @@
+#!/usr/bin/env bun
+import { timingSafeEqual } from "node:crypto";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { createClients } from "./clients";
+import { loadConfig } from "./config";
+import { backfillEmbeddings, configure, fetchSkill, resolveSkill } from "./router-core";
+import { closeRuntime, getRuntime, startVaultWatcher } from "./router-core";
+import { getStats, SINCE_PATTERN } from "./stats";
+import { SKILL_ID_PATTERN } from "./vault";
+import { MetricsRegistry } from "./metrics";
+import { ReadinessState } from "./readiness";
+import { initializeRuntime } from "./lifecycle";
+import type { Clients, Config } from "./types";
+
+export const metricsRegistry = new MetricsRegistry();
+export const readinessState = new ReadinessState();
+
+export interface ServerHandle {
+  port?: number;
+  stop(): Promise<void>;
+}
+
+let warnedAuthToken = false;
+function resolveAuthToken(envName: string): string {
+  const value = process.env[envName];
+  if (value) return value;
+  if (envName === "SKILLMUX_AUTH_TOKEN" && process.env.SKILL_ROUTER_AUTH_TOKEN) {
+    if (!warnedAuthToken) {
+      warnedAuthToken = true;
+      console.error("skillmux: SKILL_ROUTER_AUTH_TOKEN is deprecated, set SKILLMUX_AUTH_TOKEN instead");
+    }
+    return process.env.SKILL_ROUTER_AUTH_TOKEN;
+  }
+  return "";
+}
+
+function safeTokenEquals(a: string, b: string): boolean {
+  const bufA = Buffer.from(a);
+  const bufB = Buffer.from(b);
+  if (bufA.length !== bufB.length) return false;
+  return timingSafeEqual(bufA, bufB);
+}
+
+export async function startServer(opts?: {
+  transport?: "stdio" | "http";
+  port?: number;
+  config?: Config;
+  clients?: Partial<Clients>;
+}): Promise<ServerHandle> {
+  const config = opts?.config ?? await loadConfig();
+  configure({ config, clients: opts?.clients ?? createClients(config) });
+  await initializeRuntime(readinessState);
+  metricsRegistry.setReadiness(readinessState.get());
+  const stopWatcher = await startVaultWatcher();
+
+  const server = new McpServer({ name: "skillmux", version: "0.1.0" });
+
+  // Transport rule from schema.json: the SKILL.md body appears exactly once on
+  // the wire — verbatim as text content; structuredContent carries the metadata.
+  server.registerTool(
+    "resolve_skill",
+    {
+      description:
+        "Route a natural-language task description to the most relevant skill in the vault. " +
+        "Returns outcome matched (skill delivered inline), ambiguous (shortlist — pick one, then call fetch_skill), " +
+        "or no_match (proceed under your normal workflow).",
+      inputSchema: { query: z.string().min(1).max(8192) },
+    },
+    async ({ query }) => {
+      const startTime = performance.now();
+      try {
+        const result = await resolveSkill({ query });
+        const duration = (performance.now() - startTime) / 1000;
+        metricsRegistry.recordResolveLatencySeconds(duration);
+        metricsRegistry.recordResolveOutcome(result.outcome);
+
+        if (result.outcome === "matched") {
+          const { body, ...meta } = result;
+          return { content: [{ type: "text" as const, text: body }], structuredContent: { ...meta } };
+        }
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify(result) }],
+          structuredContent: { ...result },
+        };
+      } catch (err) {
+        metricsRegistry.recordError();
+        throw err;
+      }
+    },
+  );
+
+  server.registerTool(
+    "fetch_skill",
+    {
+      description:
+        "Fetch a skill's SKILL.md verbatim by skill_id, with sha256 and supporting-file paths. " +
+        "Independent of any prior resolve_skill outcome.",
+      inputSchema: { skill_id: z.string().regex(SKILL_ID_PATTERN) },
+    },
+    async ({ skill_id }) => {
+      try {
+        const result = await fetchSkill({ skill_id });
+        const { body, ...meta } = result;
+        return { content: [{ type: "text" as const, text: body }], structuredContent: { ...meta } };
+      } catch (err) {
+        metricsRegistry.recordError();
+        throw err;
+      }
+    },
+  );
+
+  const transportType = opts?.transport ?? "stdio";
+  if (transportType === "http") {
+    const { WebStandardStreamableHTTPServerTransport } = await import(
+      "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js"
+    );
+    const transport = new WebStandardStreamableHTTPServerTransport({
+      sessionIdGenerator: () => crypto.randomUUID(),
+    });
+    await server.connect(transport);
+
+    const { RateLimiter } = await import("./rate-limiter");
+    const rateLimiter = new RateLimiter(
+      config.server?.rate_limit || { enabled: false, requests_per_minute: 60 }
+    );
+
+    const port = opts?.port ?? Number(process.env.PORT || 3000);
+    const hostname = config.server?.hostname ?? "127.0.0.1";
+    const bunServer = Bun.serve({
+      port,
+      hostname,
+      async fetch(req, server) {
+        const serverConfig = config.server || {
+          auth_enabled: false,
+          auth_token_env: "SKILLMUX_AUTH_TOKEN",
+          allowed_origins: [],
+        };
+        const origin = req.headers.get("origin") || "";
+        const allowedOrigins = serverConfig.allowed_origins;
+        const isAllowed = allowedOrigins.includes("*") || allowedOrigins.includes(origin);
+        const allowOriginHeader = isAllowed ? (allowedOrigins.includes("*") ? "*" : origin) : "";
+
+        if (origin && !isAllowed) {
+          return new Response("CORS origin not allowed", { status: 403 });
+        }
+
+        if (req.method === "OPTIONS") {
+          return new Response(null, {
+            headers: {
+              "Access-Control-Allow-Origin": allowOriginHeader,
+              "Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS",
+              "Access-Control-Allow-Headers": "Content-Type, Authorization, MCP-Protocol-Version",
+            },
+          });
+        }
+
+        // Run rate limiter check
+        const rateLimitResult = rateLimiter.check({
+          nowMs: Date.now(),
+          auth_enabled: serverConfig.auth_enabled,
+          req,
+          server,
+        });
+
+        if (!rateLimitResult.allowed) {
+          metricsRegistry.recordRateLimitExceeded();
+
+          // Count the request in requests_total under the method if possible
+          let mcpMethod = "unknown";
+          try {
+            const bodyClone = await req.clone().json();
+            if (bodyClone.method === "tools/call") {
+              mcpMethod = bodyClone.params?.name || "tools/call";
+            } else {
+              mcpMethod = bodyClone.method || "unknown";
+            }
+          } catch {
+            // Non-JSON or parsing error
+          }
+          metricsRegistry.recordRequest(mcpMethod);
+
+          const headers = new Headers(rateLimitResult.headers);
+          if (allowOriginHeader) {
+            headers.set("Access-Control-Allow-Origin", allowOriginHeader);
+          }
+          return new Response("Too Many Requests", {
+            status: 429,
+            headers,
+          });
+        }
+
+        const url = new URL(req.url);
+        if (req.method === "GET") {
+          if (url.pathname === "/health" || url.pathname === "/health/live") {
+            const headers = new Headers({ "Content-Type": "application/json" });
+            if (allowOriginHeader) {
+              headers.set("Access-Control-Allow-Origin", allowOriginHeader);
+            }
+            for (const [key, value] of Object.entries(rateLimitResult.headers)) {
+              headers.set(key, value);
+            }
+            return new Response(JSON.stringify({ status: "ok" }), { status: 200, headers });
+          }
+          if (url.pathname === "/health/ready") {
+            const readiness = readinessState.get();
+            const headers = new Headers({ "Content-Type": "application/json" });
+            if (allowOriginHeader) headers.set("Access-Control-Allow-Origin", allowOriginHeader);
+            return new Response(JSON.stringify(readiness), {
+              status: readiness.status === "ready" ? 200 : 503,
+              headers,
+            });
+          }
+          if (url.pathname === "/metrics") {
+            const headers = new Headers({ "Content-Type": "text/plain; version=0.0.4" });
+            if (allowOriginHeader) {
+              headers.set("Access-Control-Allow-Origin", allowOriginHeader);
+            }
+            for (const [key, value] of Object.entries(rateLimitResult.headers)) {
+              headers.set(key, value);
+            }
+            return new Response(metricsRegistry.render(), { status: 200, headers });
+          }
+        }
+
+        // Token Auth Check
+        if (serverConfig.auth_enabled) {
+          const expectedToken = resolveAuthToken(serverConfig.auth_token_env);
+          if (!expectedToken) {
+            return new Response("Server authentication configured but token environment variable is empty", { status: 500 });
+          }
+          const authHeader = req.headers.get("authorization") || "";
+          const token = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : authHeader;
+          if (!token || !safeTokenEquals(token, expectedToken)) {
+            return new Response("Unauthorized", { status: 401 });
+          }
+        }
+
+        // GET /stats — placed after the Token Auth Check above (unlike /health and /metrics,
+        // which return earlier and stay open) since audit queries carry raw user text.
+        if (req.method === "GET" && url.pathname === "/stats") {
+          const since = url.searchParams.get("since") ?? "";
+          if (!SINCE_PATTERN.test(since)) {
+            return new Response(
+              JSON.stringify({ error: "since must be a relative window (e.g. 30d) or an absolute ISO-8601 date" }),
+              { status: 400, headers: { "Content-Type": "application/json" } },
+            );
+          }
+          const { db } = await getRuntime();
+          const headers = new Headers({ "Content-Type": "application/json" });
+          if (allowOriginHeader) headers.set("Access-Control-Allow-Origin", allowOriginHeader);
+          for (const [key, value] of Object.entries(rateLimitResult.headers)) headers.set(key, value);
+          return new Response(JSON.stringify(getStats(db, since)), { status: 200, headers });
+        }
+
+        // Record request metrics
+        let mcpMethod = "unknown";
+        try {
+          const bodyClone = await req.clone().json();
+          if (bodyClone.method === "tools/call") {
+            mcpMethod = bodyClone.params?.name || "tools/call";
+          } else {
+            mcpMethod = bodyClone.method || "unknown";
+          }
+        } catch {
+          // Non-JSON or parsing error
+        }
+        metricsRegistry.recordRequest(mcpMethod);
+
+        const res = await transport.handleRequest(req);
+        const headers = new Headers(res.headers);
+        if (allowOriginHeader) {
+          headers.set("Access-Control-Allow-Origin", allowOriginHeader);
+        }
+        for (const [key, value] of Object.entries(rateLimitResult.headers)) {
+          headers.set(key, value);
+        }
+        return new Response(res.body, {
+          status: res.status,
+          statusText: res.statusText,
+          headers,
+        });
+      },
+    });
+    let stopped = false;
+    console.log(`skillmux serving over HTTP on ${hostname}:${bunServer.port}`);
+    return {
+      port: bunServer.port,
+      async stop() {
+        if (stopped) return;
+        stopped = true;
+        readinessState.set({ ...readinessState.get(), status: "stopping" });
+        metricsRegistry.setReadiness(readinessState.get());
+        bunServer.stop(true);
+        stopWatcher();
+        await server.close();
+        closeRuntime();
+      },
+    };
+  } else {
+    await server.connect(new StdioServerTransport());
+    let stopped = false;
+    return {
+      async stop() {
+        if (stopped) return;
+        stopped = true;
+        readinessState.set({ ...readinessState.get(), status: "stopping" });
+        metricsRegistry.setReadiness(readinessState.get());
+        stopWatcher();
+        await server.close();
+        closeRuntime();
+      },
+    };
+  }
+}
+
+if (import.meta.main) await startServer();