@a13xu/lucid 1.1.0 → 1.9.0

package/build/security/guard.js

@@ -0,0 +1,133 @@
+/**
+ * Security guard — orchestrates all security checks for every tool call.
+ *
+ * Pipeline per request:
+ *   1. Rate limit check
+ *   2. WAF input validation (size, injection, path traversal, ReDoS)
+ *   3. Output leakage scan (before returning to caller)
+ *
+ * Enabled by default. Disable per-check via lucid.config.json:
+ *   { "security": { "rateLimiting": false, "waf": false } }
+ */
+import { rateLimiter, rateLimitMessage } from "./ratelimit.js";
+import { checkStringField, checkOutputLeakage, checkReDoS, } from "./waf.js";
+import { allowHost } from "./ssrf.js";
+import { sendAlert } from "./alerts.js";
+let _cfg = {
+    rateLimiting: true,
+    waf: true,
+    outputScan: true,
+};
+export function configureGuard(cfg) {
+    _cfg = { ..._cfg, ...cfg };
+    if (cfg.limits) {
+        rateLimiter.configure(cfg.limits);
+    }
+    if (cfg.trustedHosts) {
+        for (const host of cfg.trustedHosts)
+            allowHost(host);
+    }
+}
+const OK = { blocked: false };
+function blocked(reason, violations) {
+    return { blocked: true, reason, violations };
+}
+/**
+ * Per-tool WAF rules — maps each tool name to its field validation strategy.
+ * Returns the first violation found, or null if clean.
+ */
+function wafCheckArgs(tool, args) {
+    const str = (key) => (typeof args[key] === "string" ? args[key] : "");
+    switch (tool) {
+        case "remember":
+            return firstViolation([
+                checkStringField("entity", str("entity"), {}),
+                checkStringField("observation", str("observation"), {}),
+            ]);
+        case "relate":
+            return firstViolation([
+                checkStringField("from", str("from"), {}),
+                checkStringField("to", str("to"), {}),
+            ]);
+        case "recall":
+        case "get_context":
+            return checkStringField("query", str("query"), {});
+        case "forget":
+            return checkStringField("entity", str("entity"), {});
+        case "sync_file":
+        case "validate_file":
+            return checkStringField("path", str("path"), { isPath: true });
+        case "grep_code": {
+            const sizeCheck = checkStringField("pattern", str("pattern"), {});
+            if (sizeCheck.blocked)
+                return sizeCheck;
+            return checkReDoS(str("pattern"));
+        }
+        case "check_drift":
+            return checkStringField("code", str("code"), {});
+        case "init_project":
+        case "sync_project":
+            return str("directory")
+                ? checkStringField("directory", str("directory"), { isPath: true })
+                : null;
+        default:
+            return null;
+    }
+}
+function firstViolation(results) {
+    for (const r of results) {
+        if (r.blocked)
+            return r;
+    }
+    return null;
+}
+/** Run all security checks for an inbound tool call. */
+export function guardRequest(tool, args) {
+    // 1. Rate limiting
+    if (_cfg.rateLimiting !== false) {
+        const rl = rateLimiter.check(tool);
+        if (!rl.allowed) {
+            const msg = rateLimitMessage(tool, rl);
+            // Alert on repeated rate limit hits (severity: medium)
+            fireAlert({ severity: "medium", rule: "RATE_LIMIT", tool, detail: msg });
+            return blocked(msg);
+        }
+    }
+    // 2. WAF input validation
+    if (_cfg.waf !== false && args && typeof args === "object") {
+        const waf = wafCheckArgs(tool, args);
+        if (waf?.blocked) {
+            const v = waf.violations[0];
+            const detail = v?.detail ?? "Input rejected";
+            // Alert on HIGH/CRITICAL violations immediately
+            if (v && (v.severity === "high" || v.severity === "critical")) {
+                fireAlert({ severity: v.severity, rule: v.rule, tool, detail });
+            }
+            return blocked(`🛡️ WAF [${v?.rule ?? "UNKNOWN"}] (${v?.severity ?? "?"}): ${detail}`, waf.violations);
+        }
+    }
+    return OK;
+}
+/** Fire-and-forget alert — never throws, never blocks tool execution. */
+function fireAlert(event) {
+    sendAlert({ ...event, timestamp: new Date().toISOString() }).catch((e) => {
+        console.error(`[lucid:guard] Alert dispatch failed: ${e.message}`);
+    });
+}
+// ---------------------------------------------------------------------------
+// Output guard — run before returning response to caller
+// ---------------------------------------------------------------------------
+/** Scan output for sensitive data leakage. Logs a warning; does not block. */
+export function guardOutput(tool, text) {
+    if (_cfg.outputScan === false)
+        return text;
+    const leaks = checkOutputLeakage(text);
+    if (leaks.length > 0) {
+        // Log to stderr (never to stdout — that's the MCP channel)
+        console.error(`[lucid:security] ⚠️  Possible data leakage in response for "${tool}": ` +
+            leaks.map((v) => v.detail).join(", "));
+        // Redact the response rather than blocking it
+        return text + "\n\n⚠️  [Security notice: response may contain sensitive data — review before sharing]";
+    }
+    return text;
+}

package/build/security/ratelimit.d.ts

@@ -0,0 +1,34 @@
+/**
+ * In-memory sliding-window rate limiter.
+ *
+ * No external dependencies — uses a circular timestamp buffer per key.
+ * Configurable per-tool limits; heavy operations have tighter defaults.
+ */
+export interface RateLimitConfig {
+    /** Window duration in milliseconds (default: 60_000 = 1 minute) */
+    windowMs: number;
+    /** Max requests allowed within the window */
+    maxRequests: number;
+}
+export interface RateLimitResult {
+    allowed: boolean;
+    remaining: number;
+    retryAfterMs: number;
+    limit: number;
+    windowMs: number;
+}
+declare class RateLimiter {
+    private windows;
+    private overrides;
+    /** Override limits from config (called at startup). */
+    configure(overrides: Record<string, Partial<RateLimitConfig>>): void;
+    private getConfig;
+    private getWindow;
+    check(tool: string): RateLimitResult;
+    /** Reset all counters (useful in tests). */
+    reset(): void;
+}
+export declare const rateLimiter: RateLimiter;
+/** Format a rate-limit rejection message. */
+export declare function rateLimitMessage(tool: string, result: RateLimitResult): string;
+export {};

package/build/security/ratelimit.js

@@ -0,0 +1,105 @@
+/**
+ * In-memory sliding-window rate limiter.
+ *
+ * No external dependencies — uses a circular timestamp buffer per key.
+ * Configurable per-tool limits; heavy operations have tighter defaults.
+ */
+// Default per-tool limits (requests per minute)
+const DEFAULT_LIMITS = {
+    // Heavy — decompress + score all files
+    get_context: { windowMs: 60_000, maxRequests: 20 },
+    grep_code: { windowMs: 60_000, maxRequests: 30 },
+    sync_project: { windowMs: 60_000, maxRequests: 5 },
+    // Medium
+    recall: { windowMs: 60_000, maxRequests: 60 },
+    recall_all: { windowMs: 60_000, maxRequests: 20 },
+    validate_file: { windowMs: 60_000, maxRequests: 30 },
+    check_drift: { windowMs: 60_000, maxRequests: 30 },
+    // Light — default for anything not listed
+    _default: { windowMs: 60_000, maxRequests: 120 },
+};
+// ---------------------------------------------------------------------------
+// Sliding window implementation
+// ---------------------------------------------------------------------------
+/** Circular buffer of request timestamps for one key. */
+class SlidingWindow {
+    windowMs;
+    max;
+    timestamps = [];
+    constructor(windowMs, max) {
+        this.windowMs = windowMs;
+        this.max = max;
+    }
+    /** Returns true if the request is allowed; records the timestamp. */
+    allow() {
+        const now = Date.now();
+        const cutoff = now - this.windowMs;
+        // Drop expired entries
+        this.timestamps = this.timestamps.filter((t) => t > cutoff);
+        if (this.timestamps.length >= this.max)
+            return false;
+        this.timestamps.push(now);
+        return true;
+    }
+    /** Remaining requests in current window. */
+    remaining() {
+        const now = Date.now();
+        const cutoff = now - this.windowMs;
+        const active = this.timestamps.filter((t) => t > cutoff).length;
+        return Math.max(0, this.max - active);
+    }
+    /** Milliseconds until oldest request falls out of window. */
+    retryAfterMs() {
+        if (this.timestamps.length === 0)
+            return 0;
+        const oldest = Math.min(...this.timestamps);
+        return Math.max(0, oldest + this.windowMs - Date.now());
+    }
+}
+class RateLimiter {
+    windows = new Map();
+    overrides = new Map();
+    /** Override limits from config (called at startup). */
+    configure(overrides) {
+        for (const [tool, cfg] of Object.entries(overrides)) {
+            const base = DEFAULT_LIMITS[tool] ?? DEFAULT_LIMITS["_default"];
+            this.overrides.set(tool, { ...base, ...cfg });
+        }
+    }
+    getConfig(tool) {
+        return this.overrides.get(tool) ?? DEFAULT_LIMITS[tool] ?? DEFAULT_LIMITS["_default"];
+    }
+    getWindow(key, cfg) {
+        let w = this.windows.get(key);
+        if (!w) {
+            w = new SlidingWindow(cfg.windowMs, cfg.maxRequests);
+            this.windows.set(key, w);
+        }
+        return w;
+    }
+    check(tool) {
+        const cfg = this.getConfig(tool);
+        const window = this.getWindow(tool, cfg);
+        const allowed = window.allow();
+        return {
+            allowed,
+            remaining: window.remaining(),
+            retryAfterMs: allowed ? 0 : window.retryAfterMs(),
+            limit: cfg.maxRequests,
+            windowMs: cfg.windowMs,
+        };
+    }
+    /** Reset all counters (useful in tests). */
+    reset() {
+        this.windows.clear();
+    }
+}
+// Singleton — one rate limiter per server process
+export const rateLimiter = new RateLimiter();
+/** Format a rate-limit rejection message. */
+export function rateLimitMessage(tool, result) {
+    const retryAfterSec = Math.ceil(result.retryAfterMs / 1000);
+    return (`🚦 Rate limit exceeded for "${tool}": ` +
+        `${result.limit} requests/${result.windowMs / 1000}s allowed. ` +
+        `Retry after ${retryAfterSec}s.`);
+}

package/build/security/smtp.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Minimal SMTP client — Node.js built-ins only (net + tls + crypto).
+ *
+ * Supports:
+ *  - Direct TLS (port 465, implicit SSL)
+ *  - STARTTLS (port 587, explicit upgrade)
+ *  - AUTH LOGIN
+ *  - Plain-text message body
+ */
+export interface SmtpConfig {
+    host: string;
+    port: number;
+    user: string;
+    /** Must come from LUCID_SMTP_PASS env var — never hardcoded */
+    pass: string;
+    from: string;
+    /** true = direct TLS (port 465); false/omit = STARTTLS (port 587) */
+    secure?: boolean;
+    timeoutMs?: number;
+}
+export interface SmtpMessage {
+    to: string;
+    subject: string;
+    body: string;
+}
+export declare function sendEmail(cfg: SmtpConfig, msg: SmtpMessage): Promise<void>;

package/build/security/smtp.js

@@ -0,0 +1,125 @@
+/**
+ * Minimal SMTP client — Node.js built-ins only (net + tls + crypto).
+ *
+ * Supports:
+ *  - Direct TLS (port 465, implicit SSL)
+ *  - STARTTLS (port 587, explicit upgrade)
+ *  - AUTH LOGIN
+ *  - Plain-text message body
+ */
+import * as net from "net";
+import * as tls from "tls";
+function readResponse(socket, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        let buf = "";
+        const timer = setTimeout(() => reject(new Error("SMTP read timeout")), timeoutMs);
+        const handler = (chunk) => {
+            buf += chunk.toString("utf-8");
+            // A complete (possibly multi-line) SMTP response ends with "DDD text\r\n"
+            // where DDD is followed by a space (not a dash, which denotes continuation)
+            if (/\r?\n$/.test(buf)) {
+                const rawLines = buf.split(/\r?\n/).filter((l) => l.length > 0);
+                const last = rawLines[rawLines.length - 1];
+                // Final line: code + space (e.g. "250 OK")
+                if (/^\d{3} /.test(last)) {
+                    clearTimeout(timer);
+                    socket.removeListener("data", handler);
+                    const code = parseInt(last.slice(0, 3), 10);
+                    resolve({ code, lines: rawLines });
+                }
+            }
+        };
+        socket.on("data", handler);
+        socket.once("error", (e) => { clearTimeout(timer); reject(e); });
+    });
+}
+async function cmd(socket, command, timeout) {
+    await new Promise((res, rej) => {
+        socket.write(command + "\r\n", "utf-8", (err) => (err ? rej(err) : res()));
+    });
+    return readResponse(socket, timeout);
+}
+function expect(res, ...codes) {
+    if (!codes.includes(res.code)) {
+        throw new Error(`SMTP unexpected response ${res.code}: ${res.lines.join(" | ")}`);
+    }
+}
+function b64(s) {
+    return Buffer.from(s, "utf-8").toString("base64");
+}
+// ---------------------------------------------------------------------------
+// Main send function
+// ---------------------------------------------------------------------------
+export async function sendEmail(cfg, msg) {
+    const timeout = cfg.timeoutMs ?? 15_000;
+    let socket;
+    if (cfg.secure) {
+        // Direct TLS — connect already encrypted
+        socket = await new Promise((resolve, reject) => {
+            const s = tls.connect({ host: cfg.host, port: cfg.port, servername: cfg.host });
+            s.once("secureConnect", () => resolve(s));
+            s.once("error", reject);
+            setTimeout(() => reject(new Error("TLS connect timeout")), timeout);
+        });
+    }
+    else {
+        // Plain TCP first (STARTTLS later)
+        socket = await new Promise((resolve, reject) => {
+            const s = net.createConnection({ host: cfg.host, port: cfg.port });
+            s.once("connect", () => resolve(s));
+            s.once("error", reject);
+            setTimeout(() => reject(new Error("TCP connect timeout")), timeout);
+        });
+    }
+    try {
+        // 1. Server greeting
+        expect(await readResponse(socket, timeout), 220);
+        // 2. EHLO
+        const ehlo = await cmd(socket, `EHLO lucid-security`, timeout);
+        expect(ehlo, 250);
+        // 3. STARTTLS upgrade (plain TCP only)
+        if (!cfg.secure) {
+            expect(await cmd(socket, "STARTTLS", timeout), 220);
+            // Wrap plain socket in TLS
+            socket = await new Promise((resolve, reject) => {
+                const upgraded = tls.connect({
+                    socket: socket,
+                    host: cfg.host,
+                    servername: cfg.host,
+                });
+                upgraded.once("secureConnect", () => resolve(upgraded));
+                upgraded.once("error", reject);
+                setTimeout(() => reject(new Error("STARTTLS upgrade timeout")), timeout);
+            });
+            // EHLO again after TLS
+            expect(await cmd(socket, `EHLO lucid-security`, timeout), 250);
+        }
+        // 4. AUTH LOGIN
+        expect(await cmd(socket, "AUTH LOGIN", timeout), 334);
+        expect(await cmd(socket, b64(cfg.user), timeout), 334);
+        expect(await cmd(socket, b64(cfg.pass), timeout), 235);
+        // 5. Envelope
+        expect(await cmd(socket, `MAIL FROM:<${cfg.from}>`, timeout), 250);
+        expect(await cmd(socket, `RCPT TO:<${msg.to}>`, timeout), 250);
+        // 6. Message body
+        expect(await cmd(socket, "DATA", timeout), 354);
+        const date = new Date().toUTCString();
+        const body = [
+            `Date: ${date}`,
+            `From: ${cfg.from}`,
+            `To: ${msg.to}`,
+            `Subject: ${msg.subject}`,
+            `MIME-Version: 1.0`,
+            `Content-Type: text/plain; charset=UTF-8`,
+            ``,
+            msg.body,
+            `.`,
+        ].join("\r\n");
+        expect(await cmd(socket, body, timeout), 250);
+        // 7. Quit
+        await cmd(socket, "QUIT", timeout);
+    }
+    finally {
+        socket.destroy();
+    }
+}

package/build/security/ssrf.d.ts

@@ -0,0 +1,18 @@
+/**
+ * SSRF (Server-Side Request Forgery) prevention.
+ *
+ * Validates URLs before any outbound fetch call to ensure they point to
+ * legitimate external services and not to internal network resources.
+ */
+/** Register a trusted host (called once at startup with Qdrant URL etc.) */
+export declare function allowHost(urlOrHost: string): void;
+export declare function resetAllowedHosts(): void;
+export interface UrlCheckResult {
+    allowed: boolean;
+    reason?: string;
+}
+export declare function validateUrl(rawUrl: string): UrlCheckResult;
+/** Throw if URL is not allowed. Use before every outbound fetch. */
+export declare function assertSafeUrl(url: string): void;
+/** Resolve and return timeout-wrapped fetch (default 10s). */
+export declare function safeFetch(url: string, init?: RequestInit, timeoutMs?: number): Promise<Response>;

package/build/security/ssrf.js

@@ -0,0 +1,109 @@
+/**
+ * SSRF (Server-Side Request Forgery) prevention.
+ *
+ * Validates URLs before any outbound fetch call to ensure they point to
+ * legitimate external services and not to internal network resources.
+ */
+// ---------------------------------------------------------------------------
+// Private/reserved IP ranges to block
+// ---------------------------------------------------------------------------
+// IPv4 ranges that should never be reachable from outside
+const BLOCKED_IPV4_PATTERNS = [
+    /^127\./, // loopback
+    /^10\./, // RFC-1918 class A
+    /^172\.(1[6-9]|2\d|3[01])\./, // RFC-1918 class B
+    /^192\.168\./, // RFC-1918 class C
+    /^169\.254\./, // link-local / AWS metadata
+    /^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./, // CGNAT (RFC-6598)
+    /^0\./, // "this" network
+    /^255\./, // broadcast
+    /^::1$/, // IPv6 loopback
+    /^fc00:/i, // IPv6 unique local
+    /^fe80:/i, // IPv6 link-local
+];
+// Hostnames that are always blocked
+const BLOCKED_HOSTS = new Set([
+    "localhost",
+    "metadata.google.internal",
+    "metadata",
+]);
+// Cloud metadata endpoints
+const BLOCKED_PATHS_PREFIX = [
+    "/latest/meta-data", // AWS EC2 metadata
+    "/computeMetadata", // GCP metadata
+    "/metadata/instance", // Azure IMDS
+    "/odata/", // Azure (generic)
+];
+// ---------------------------------------------------------------------------
+// Allowlist (set from env/config at startup)
+// ---------------------------------------------------------------------------
+let _allowedHosts = new Set();
+/** Register a trusted host (called once at startup with Qdrant URL etc.) */
+export function allowHost(urlOrHost) {
+    try {
+        const host = new URL(urlOrHost).hostname.toLowerCase();
+        _allowedHosts.add(host);
+    }
+    catch {
+        _allowedHosts.add(urlOrHost.toLowerCase());
+    }
+}
+export function resetAllowedHosts() {
+    _allowedHosts = new Set();
+}
+export function validateUrl(rawUrl) {
+    // 1. Must be parseable
+    let parsed;
+    try {
+        parsed = new URL(rawUrl);
+    }
+    catch {
+        return { allowed: false, reason: "Malformed URL" };
+    }
+    // 2. Only http/https allowed
+    if (!["http:", "https:"].includes(parsed.protocol)) {
+        return { allowed: false, reason: `Protocol not allowed: ${parsed.protocol}` };
+    }
+    const hostname = parsed.hostname.toLowerCase();
+    const path = parsed.pathname;
+    // 3. Check blocked hostnames
+    if (BLOCKED_HOSTS.has(hostname)) {
+        return { allowed: false, reason: `Blocked hostname: ${hostname}` };
+    }
+    // 4. Check blocked IPv4 patterns
+    for (const pattern of BLOCKED_IPV4_PATTERNS) {
+        if (pattern.test(hostname)) {
+            return { allowed: false, reason: `Blocked IP range: ${hostname}` };
+        }
+    }
+    // 5. Check cloud metadata paths
+    for (const prefix of BLOCKED_PATHS_PREFIX) {
+        if (path.startsWith(prefix)) {
+            return { allowed: false, reason: `Blocked metadata path: ${path}` };
+        }
+    }
+    // 6. If allowlist is populated, host must be in it
+    if (_allowedHosts.size > 0 && !_allowedHosts.has(hostname)) {
+        return { allowed: false, reason: `Host not in allowlist: ${hostname}` };
+    }
+    return { allowed: true };
+}
+/** Throw if URL is not allowed. Use before every outbound fetch. */
+export function assertSafeUrl(url) {
+    const result = validateUrl(url);
+    if (!result.allowed) {
+        throw new Error(`SSRF guard blocked request: ${result.reason}`);
+    }
+}
+/** Resolve and return timeout-wrapped fetch (default 10s). */
+export async function safeFetch(url, init = {}, timeoutMs = 10_000) {
+    assertSafeUrl(url);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, { ...init, signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/build/security/waf.d.ts

@@ -0,0 +1,33 @@
+/**
+ * WAF (Web Application Firewall) rules for MCP tool inputs.
+ *
+ * Covers:
+ *  - Path traversal & directory escape
+ *  - Null-byte & CRLF injection
+ *  - ReDoS (catastrophic backtracking) detection
+ *  - Input size limits (DoS prevention)
+ *  - Suspicious injection patterns (SQLi, command injection)
+ *  - Sensitive data leakage in outputs
+ */
+export type Severity = "low" | "medium" | "high" | "critical";
+export interface WafViolation {
+    rule: string;
+    severity: Severity;
+    detail: string;
+}
+export interface WafResult {
+    blocked: boolean;
+    violations: WafViolation[];
+}
+export declare function checkSize(field: string, value: string): WafResult;
+export declare function checkInjection(value: string): WafResult;
+export declare function checkPath(inputPath: string, allowedRoot?: string): WafResult;
+export declare function checkReDoS(pattern: string): WafResult;
+export declare function checkInjectionPatterns(value: string): WafResult;
+/** Check if a text blob about to be returned contains secrets. */
+export declare function checkOutputLeakage(text: string): WafViolation[];
+export declare function checkStringField(field: string, value: string, opts?: {
+    isPath?: boolean;
+    isRegex?: boolean;
+    allowedRoot?: string;
+}): WafResult;