@a13xu/lucid 1.1.0 → 1.9.0

package/build/retrieval/qdrant.js

@@ -0,0 +1,135 @@
+// Qdrant vector search — via direct REST API calls (no npm dependency)
+// Only active when QDRANT_URL is set (via env var or lucid.config.json)
+// Falls back silently to TF-IDF when unavailable
+import { safeFetch } from "../security/ssrf.js";
+// ---------------------------------------------------------------------------
+// Embedding generation (OpenAI-compatible endpoint)
+// ---------------------------------------------------------------------------
+async function embed(texts, cfg) {
+    if (!cfg.embeddingApiKey) {
+        throw new Error("No embedding API key (set OPENAI_API_KEY or embeddingApiKey in lucid.config.json)");
+    }
+    const url = cfg.embeddingUrl ?? "https://api.openai.com/v1/embeddings";
+    const res = await safeFetch(url, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${cfg.embeddingApiKey}`,
+        },
+        body: JSON.stringify({ model: cfg.embeddingModel ?? "text-embedding-3-small", input: texts }),
+    });
+    if (!res.ok) {
+        const body = await res.text();
+        throw new Error(`Embedding API ${res.status}: ${body.slice(0, 200)}`);
+    }
+    const json = await res.json();
+    return json.data.map((d) => d.embedding);
+}
+// ---------------------------------------------------------------------------
+// Qdrant REST helpers
+// ---------------------------------------------------------------------------
+async function qdrantRequest(cfg, method, path, body) {
+    const url = `${cfg.url.replace(/\/$/, "")}${path}`;
+    const headers = { "Content-Type": "application/json" };
+    if (cfg.apiKey)
+        headers["api-key"] = cfg.apiKey;
+    const res = await safeFetch(url, {
+        method,
+        headers,
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Qdrant ${method} ${path} → ${res.status}: ${text.slice(0, 200)}`);
+    }
+    return res.json();
+}
+async function ensureCollection(cfg) {
+    const col = cfg.collection;
+    try {
+        await qdrantRequest(cfg, "GET", `/collections/${col}`);
+    }
+    catch {
+        // Create collection
+        await qdrantRequest(cfg, "PUT", `/collections/${col}`, {
+            vectors: { size: cfg.vectorDim ?? 1536, distance: "Cosine" },
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// Chunking
+// ---------------------------------------------------------------------------
+const CHUNK_LINES = 80;
+function chunkFile(filepath, text) {
+    const lines = text.split("\n");
+    const chunks = [];
+    for (let i = 0; i < lines.length; i += CHUNK_LINES) {
+        const chunkText = lines.slice(i, i + CHUNK_LINES).join("\n");
+        const chunkIndex = Math.floor(i / CHUNK_LINES);
+        // Deterministic integer ID from filepath + chunk index
+        const id = stableId(`${filepath}::${chunkIndex}`);
+        chunks.push({ id, text: chunkText, chunkIndex });
+    }
+    return chunks;
+}
+function stableId(s) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    // Ensure positive 32-bit int
+    return (h >>> 0) % 2_000_000_000;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/** Index one file into Qdrant (called by sync_file when Qdrant is configured). */
+export async function indexFileInQdrant(filepath, text, cfg) {
+    await ensureCollection(cfg);
+    const chunks = chunkFile(filepath, text);
+    if (chunks.length === 0)
+        return;
+    // Batch embed (max 96 texts per request for most providers)
+    const BATCH = 32;
+    for (let b = 0; b < chunks.length; b += BATCH) {
+        const batch = chunks.slice(b, b + BATCH);
+        const vectors = await embed(batch.map((c) => c.text), cfg);
+        const points = batch.map((c, idx) => ({
+            id: c.id,
+            vector: vectors[idx],
+            payload: { filepath, chunkIndex: c.chunkIndex, text: c.text },
+        }));
+        await qdrantRequest(cfg, "PUT", `/collections/${cfg.collection}/points`, {
+            points,
+        });
+    }
+}
+/** Top-k semantic search across all indexed chunks. */
+export async function searchQdrant(query, topK, cfg) {
+    const [queryVec] = await embed([query], cfg);
+    if (!queryVec)
+        return [];
+    const result = await qdrantRequest(cfg, "POST", `/collections/${cfg.collection}/points/search`, {
+        vector: queryVec,
+        limit: topK,
+        with_payload: true,
+    });
+    return result.result.map((r) => ({
+        id: r.id,
+        filepath: r.payload["filepath"],
+        chunkIndex: r.payload["chunkIndex"],
+        text: r.payload["text"],
+        score: r.score,
+    }));
+}
+/** Check if Qdrant collection exists and is reachable. */
+export async function pingQdrant(cfg) {
+    try {
+        await qdrantRequest(cfg, "GET", `/collections/${cfg.collection}`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/build/retrieval/tfidf.d.ts

@@ -0,0 +1,14 @@
+export declare function tokenize(text: string): string[];
+export interface ScoredFile {
+    filepath: string;
+    score: number;
+    matchedTerms: string[];
+}
+/**
+ * Rank files by TF-IDF relevance to a query.
+ * Returns all files sorted by score descending (score=0 files included at bottom).
+ */
+export declare function rankByRelevance(query: string, files: Array<{
+    filepath: string;
+    text: string;
+}>): ScoredFile[];

package/build/retrieval/tfidf.js

@@ -0,0 +1,64 @@
+// TF-IDF scoring — pure JS, no external deps
+// Used as the default relevance engine when Qdrant is not configured
+const STOPWORDS = new Set([
+    "the", "and", "for", "are", "but", "not", "you", "all", "can", "had",
+    "her", "was", "one", "our", "out", "day", "get", "has", "him", "his",
+    "how", "its", "let", "may", "new", "now", "old", "own", "say", "she",
+    "too", "use", "way", "who", "will", "with", "that", "this", "from",
+    "they", "been", "have", "their", "said", "each", "which", "what",
+    // code keywords (too common to be discriminative)
+    "return", "const", "import", "export", "function", "class", "type",
+    "interface", "string", "number", "boolean", "void", "null", "undefined",
+    "async", "await", "true", "false", "default", "module", "require",
+    "self", "def", "pass", "else", "elif", "then", "end", "var", "let",
+]);
+export function tokenize(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9_]/g, " ")
+        .split(/\s+/)
+        .filter((t) => t.length >= 3 && !STOPWORDS.has(t));
+}
+/**
+ * Rank files by TF-IDF relevance to a query.
+ * Returns all files sorted by score descending (score=0 files included at bottom).
+ */
+export function rankByRelevance(query, files) {
+    if (files.length === 0)
+        return [];
+    const queryTerms = tokenize(query);
+    if (queryTerms.length === 0) {
+        return files.map((f) => ({ filepath: f.filepath, score: 0, matchedTerms: [] }));
+    }
+    const N = files.length;
+    // Compute per-doc term frequencies + document frequencies
+    const df = new Map();
+    const docTF = [];
+    for (const file of files) {
+        const tokens = tokenize(file.text);
+        const tf = new Map();
+        for (const t of tokens)
+            tf.set(t, (tf.get(t) ?? 0) + 1);
+        docTF.push(tf);
+        for (const term of tf.keys())
+            df.set(term, (df.get(term) ?? 0) + 1);
+    }
+    const results = [];
+    for (let i = 0; i < files.length; i++) {
+        const tf = docTF[i];
+        const totalTokens = Math.max([...tf.values()].reduce((a, b) => a + b, 0), 1);
+        let score = 0;
+        const matched = [];
+        for (const qt of queryTerms) {
+            const freq = tf.get(qt) ?? 0;
+            if (freq > 0) {
+                const tfScore = freq / totalTokens;
+                const idf = Math.log((N + 1) / ((df.get(qt) ?? 0) + 1)) + 1;
+                score += tfScore * idf;
+                matched.push(qt);
+            }
+        }
+        results.push({ filepath: files[i].filepath, score, matchedTerms: matched });
+    }
+    return results.sort((a, b) => b.score - a.score);
+}

package/build/security/alerts.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Security alert dispatcher.
+ *
+ * Channels (all optional, configured via lucid-admin.json + env vars):
+ *   - Webhook  (generic HTTP POST, HMAC-SHA256 signed)
+ *   - Slack    (incoming webhook)
+ *   - Email    (SMTP via smtp.ts)
+ *
+ * Sensitive values MUST come from environment variables:
+ *   LUCID_SMTP_PASS        — SMTP password
+ *   LUCID_WEBHOOK_SECRET   — HMAC signing secret for webhook
+ *
+ * Config is stored in  <project>/.claude/lucid-admin.json  (non-sensitive fields only).
+ */
+import type { Severity } from "./waf.js";
+export interface AlertEvent {
+    severity: Severity;
+    rule: string;
+    tool: string;
+    detail: string;
+    timestamp: string;
+    projectDir?: string;
+}
+export interface AdminConfig {
+    adminName?: string;
+    adminEmail?: string;
+    smtpHost?: string;
+    smtpPort?: number;
+    smtpUser?: string;
+    smtpFrom?: string;
+    webhookUrl?: string;
+    slackWebhookUrl?: string;
+    /** Severities that trigger an alert (default: ["critical", "high"]) */
+    alertOn?: Severity[];
+    projectName?: string;
+}
+export declare const ADMIN_CONFIG_FILE = "lucid-admin.json";
+export declare function loadAdminConfig(projectDir: string): AdminConfig;
+export declare function saveAdminConfig(projectDir: string, cfg: AdminConfig): void;
+export declare function getAdminConfig(): AdminConfig;
+export declare function isAdminConfigured(): boolean;
+export declare function sendAlert(event: AlertEvent): Promise<void>;
+/** Send a test alert to verify all configured channels work. */
+export declare function sendTestAlert(projectDir: string): Promise<string[]>;

package/build/security/alerts.js

@@ -0,0 +1,228 @@
+/**
+ * Security alert dispatcher.
+ *
+ * Channels (all optional, configured via lucid-admin.json + env vars):
+ *   - Webhook  (generic HTTP POST, HMAC-SHA256 signed)
+ *   - Slack    (incoming webhook)
+ *   - Email    (SMTP via smtp.ts)
+ *
+ * Sensitive values MUST come from environment variables:
+ *   LUCID_SMTP_PASS        — SMTP password
+ *   LUCID_WEBHOOK_SECRET   — HMAC signing secret for webhook
+ *
+ * Config is stored in  <project>/.claude/lucid-admin.json  (non-sensitive fields only).
+ */
+import { createHmac } from "crypto";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { safeFetch } from "./ssrf.js";
+import { sendEmail } from "./smtp.js";
+// ---------------------------------------------------------------------------
+// Config loader
+// ---------------------------------------------------------------------------
+let _config = null;
+let _configDir = null;
+export const ADMIN_CONFIG_FILE = "lucid-admin.json";
+export function loadAdminConfig(projectDir) {
+    _configDir = join(projectDir, ".claude");
+    const path = join(_configDir, ADMIN_CONFIG_FILE);
+    if (existsSync(path)) {
+        try {
+            _config = JSON.parse(readFileSync(path, "utf-8"));
+        }
+        catch {
+            _config = {};
+        }
+    }
+    else {
+        _config = {};
+    }
+    return _config;
+}
+export function saveAdminConfig(projectDir, cfg) {
+    const dir = join(projectDir, ".claude");
+    mkdirSync(dir, { recursive: true });
+    // Merge with existing
+    const existing = loadAdminConfig(projectDir);
+    const merged = { ...existing, ...cfg };
+    _config = merged;
+    // Strip any sensitive fields that shouldn't be persisted to disk
+    // (user might accidentally pass smtpPass — we silently drop it)
+    const safe = { ...merged };
+    delete safe["smtpPass"];
+    delete safe["webhookSecret"];
+    writeFileSync(join(dir, ADMIN_CONFIG_FILE), JSON.stringify(safe, null, 2) + "\n", "utf-8");
+}
+export function getAdminConfig() {
+    return _config ?? {};
+}
+export function isAdminConfigured() {
+    const c = _config ?? {};
+    return !!(c.adminEmail || c.webhookUrl || c.slackWebhookUrl);
+}
+// ---------------------------------------------------------------------------
+// HMAC webhook signature
+// ---------------------------------------------------------------------------
+function signPayload(body) {
+    const secret = process.env["LUCID_WEBHOOK_SECRET"];
+    if (!secret)
+        return null;
+    return "sha256=" + createHmac("sha256", secret).update(body, "utf-8").digest("hex");
+}
+// ---------------------------------------------------------------------------
+// Channels
+// ---------------------------------------------------------------------------
+async function dispatchWebhook(url, event) {
+    const body = JSON.stringify({
+        source: "lucid-security",
+        ...event,
+    });
+    const headers = { "Content-Type": "application/json" };
+    const sig = signPayload(body);
+    if (sig)
+        headers["X-Lucid-Signature"] = sig;
+    const res = await safeFetch(url, { method: "POST", headers, body });
+    if (!res.ok)
+        throw new Error(`Webhook HTTP ${res.status}`);
+}
+async function dispatchSlack(webhookUrl, event) {
+    const icon = event.severity === "critical" ? "🚨" : "⚠️";
+    const payload = {
+        text: `${icon} *Lucid Security Alert* — ${event.severity.toUpperCase()}`,
+        blocks: [
+            {
+                type: "section",
+                text: {
+                    type: "mrkdwn",
+                    text: `${icon} *[${event.severity.toUpperCase()}] ${event.rule}*\n` +
+                        `*Tool:* \`${event.tool}\`\n` +
+                        `*Detail:* ${event.detail}\n` +
+                        `*Project:* ${_config?.projectName ?? "unknown"}\n` +
+                        `*Time:* ${event.timestamp}`,
+                },
+            },
+        ],
+    };
+    const res = await safeFetch(webhookUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+    });
+    if (!res.ok)
+        throw new Error(`Slack HTTP ${res.status}`);
+}
+async function dispatchEmail(event) {
+    const cfg = _config ?? {};
+    const smtpPass = process.env["LUCID_SMTP_PASS"];
+    if (!smtpPass)
+        throw new Error("LUCID_SMTP_PASS env var not set");
+    if (!cfg.adminEmail)
+        throw new Error("adminEmail not configured");
+    if (!cfg.smtpHost)
+        throw new Error("smtpHost not configured");
+    const smtpCfg = {
+        host: cfg.smtpHost,
+        port: cfg.smtpPort ?? 587,
+        user: cfg.smtpUser ?? cfg.adminEmail,
+        pass: smtpPass,
+        from: cfg.smtpFrom ?? `Lucid Security <${cfg.smtpUser ?? cfg.adminEmail}>`,
+        secure: cfg.smtpPort === 465,
+    };
+    const icon = event.severity === "critical" ? "🚨" : "⚠️";
+    const subject = `${icon} [${event.severity.toUpperCase()}] Lucid Security Alert — ${event.rule}`;
+    const body = [
+        `Lucid Security Alert`,
+        `${"─".repeat(40)}`,
+        ``,
+        `Severity : ${event.severity.toUpperCase()}`,
+        `Rule     : ${event.rule}`,
+        `Tool     : ${event.tool}`,
+        `Detail   : ${event.detail}`,
+        `Project  : ${cfg.projectName ?? "unknown"}`,
+        `Time     : ${event.timestamp}`,
+        ``,
+        `─────────────────────────────────────────`,
+        `This alert was sent automatically by lucid.`,
+        `Configure alerts in .claude/lucid-admin.json`,
+    ].join("\n");
+    await sendEmail(smtpCfg, { to: cfg.adminEmail, subject, body });
+}
+// ---------------------------------------------------------------------------
+// Main dispatch — fire-and-forget safe
+// ---------------------------------------------------------------------------
+const SEVERITY_ORDER = { low: 0, medium: 1, high: 2, critical: 3 };
+export async function sendAlert(event) {
+    const cfg = _config ?? {};
+    const alertOn = cfg.alertOn ?? ["critical", "high"];
+    // Check if this severity is configured to alert
+    const minSeverity = Math.min(...alertOn.map((s) => SEVERITY_ORDER[s]));
+    if (SEVERITY_ORDER[event.severity] < minSeverity)
+        return;
+    const errors = [];
+    // Dispatch to all configured channels concurrently
+    const dispatches = [];
+    if (cfg.webhookUrl) {
+        dispatches.push(dispatchWebhook(cfg.webhookUrl, event).catch((e) => {
+            errors.push(`webhook: ${e.message}`);
+        }));
+    }
+    if (cfg.slackWebhookUrl) {
+        dispatches.push(dispatchSlack(cfg.slackWebhookUrl, event).catch((e) => {
+            errors.push(`slack: ${e.message}`);
+        }));
+    }
+    if (cfg.adminEmail && cfg.smtpHost) {
+        dispatches.push(dispatchEmail(event).catch((e) => {
+            errors.push(`email: ${e.message}`);
+        }));
+    }
+    await Promise.all(dispatches);
+    if (errors.length > 0) {
+        console.error(`[lucid:alerts] ⚠️  Failed to deliver ${errors.length} alert(s): ${errors.join("; ")}`);
+    }
+}
+/** Send a test alert to verify all configured channels work. */
+export async function sendTestAlert(projectDir) {
+    loadAdminConfig(projectDir);
+    const event = {
+        severity: "low",
+        rule: "TEST",
+        tool: "init_project",
+        detail: "Lucid security alerts are correctly configured and working.",
+        timestamp: new Date().toISOString(),
+        projectDir,
+    };
+    const results = [];
+    const cfg = _config ?? {};
+    if (cfg.webhookUrl) {
+        try {
+            await dispatchWebhook(cfg.webhookUrl, event);
+            results.push("✅ Webhook: test alert delivered");
+        }
+        catch (e) {
+            results.push(`❌ Webhook: ${e.message}`);
+        }
+    }
+    if (cfg.slackWebhookUrl) {
+        try {
+            await dispatchSlack(cfg.slackWebhookUrl, event);
+            results.push("✅ Slack: test alert delivered");
+        }
+        catch (e) {
+            results.push(`❌ Slack: ${e.message}`);
+        }
+    }
+    if (cfg.adminEmail && cfg.smtpHost) {
+        try {
+            await dispatchEmail(event);
+            results.push(`✅ Email: test alert sent to ${cfg.adminEmail}`);
+        }
+        catch (e) {
+            results.push(`❌ Email: ${e.message}`);
+        }
+    }
+    if (results.length === 0) {
+        results.push("⚠️  No alert channels configured yet");
+    }
+    return results;
+}

package/build/security/env.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Secure environment variable access.
+ *
+ * Rules:
+ * - Never expose raw values in error messages or logs
+ * - Always validate format before use
+ * - Mask secrets in any diagnostic output
+ */
+/** Get a required env var. Throws a safe error (no value leak) if missing. */
+export declare function requireEnv(key: string): string;
+/** Get an optional env var with a typed default. */
+export declare function optionalEnv(key: string, defaultValue: string): string;
+/** Get a numeric env var. Returns default if missing or non-numeric. */
+export declare function numericEnv(key: string, defaultValue: number): number;
+/** Get a boolean env var ("true"/"1"/"yes" → true, anything else → false). */
+export declare function boolEnv(key: string, defaultValue: boolean): boolean;
+/** Mask a value for safe logging. Shows first 4 and last 2 chars only. */
+export declare function maskSecret(value: string): string;
+/** Safe env dump for diagnostics — masks any key that looks sensitive. */
+export declare function safeDump(keys: string[]): Record<string, string>;
+/** Validate a URL-format env var. Throws with safe message on failure. */
+export declare function requireEnvUrl(key: string): string;
+/** Validate that an API key looks like a real key (non-trivial length). */
+export declare function requireEnvApiKey(key: string, minLength?: number): string;

package/build/security/env.js

@@ -0,0 +1,85 @@
+/**
+ * Secure environment variable access.
+ *
+ * Rules:
+ * - Never expose raw values in error messages or logs
+ * - Always validate format before use
+ * - Mask secrets in any diagnostic output
+ */
+// ---------------------------------------------------------------------------
+// Core getters
+// ---------------------------------------------------------------------------
+/** Get a required env var. Throws a safe error (no value leak) if missing. */
+export function requireEnv(key) {
+    const val = process.env[key];
+    if (!val || val.trim() === "") {
+        throw new Error(`Missing required environment variable: ${key}`);
+    }
+    return val.trim();
+}
+/** Get an optional env var with a typed default. */
+export function optionalEnv(key, defaultValue) {
+    const val = process.env[key];
+    return val && val.trim() !== "" ? val.trim() : defaultValue;
+}
+/** Get a numeric env var. Returns default if missing or non-numeric. */
+export function numericEnv(key, defaultValue) {
+    const raw = process.env[key];
+    if (!raw)
+        return defaultValue;
+    const n = Number(raw.trim());
+    return Number.isFinite(n) ? n : defaultValue;
+}
+/** Get a boolean env var ("true"/"1"/"yes" → true, anything else → false). */
+export function boolEnv(key, defaultValue) {
+    const raw = process.env[key];
+    if (!raw)
+        return defaultValue;
+    return /^(true|1|yes)$/i.test(raw.trim());
+}
+// ---------------------------------------------------------------------------
+// Masking for logs / diagnostics
+// ---------------------------------------------------------------------------
+const SECRET_PATTERNS = [
+    /key/i, /secret/i, /token/i, /password/i, /pwd/i, /auth/i, /credential/i,
+];
+/** Mask a value for safe logging. Shows first 4 and last 2 chars only. */
+export function maskSecret(value) {
+    if (value.length <= 8)
+        return "***";
+    return `${value.slice(0, 4)}…${value.slice(-2)}`;
+}
+/** Safe env dump for diagnostics — masks any key that looks sensitive. */
+export function safeDump(keys) {
+    const result = {};
+    for (const key of keys) {
+        const val = process.env[key];
+        if (!val) {
+            result[key] = "<not set>";
+            continue;
+        }
+        const isSensitive = SECRET_PATTERNS.some((p) => p.test(key));
+        result[key] = isSensitive ? maskSecret(val) : val;
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Format validators (called before using values)
+// ---------------------------------------------------------------------------
+const URL_RE = /^https?:\/\/[^\s/$.?#].[^\s]*$/i;
+/** Validate a URL-format env var. Throws with safe message on failure. */
+export function requireEnvUrl(key) {
+    const val = requireEnv(key);
+    if (!URL_RE.test(val)) {
+        throw new Error(`Environment variable ${key} must be a valid URL (got invalid format)`);
+    }
+    return val;
+}
+/** Validate that an API key looks like a real key (non-trivial length). */
+export function requireEnvApiKey(key, minLength = 16) {
+    const val = requireEnv(key);
+    if (val.length < minLength) {
+        throw new Error(`Environment variable ${key} appears to be too short for an API key (min ${minLength} chars)`);
+    }
+    return val;
+}

package/build/security/guard.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 { type RateLimitConfig } from "./ratelimit.js";
+import { type WafViolation } from "./waf.js";
+export interface SecurityConfig {
+    /** Enable/disable rate limiting (default: true) */
+    rateLimiting?: boolean;
+    /** Enable/disable WAF input checks (default: true) */
+    waf?: boolean;
+    /** Enable/disable output leakage scan (default: true) */
+    outputScan?: boolean;
+    /** Per-tool rate limit overrides */
+    limits?: Record<string, Partial<RateLimitConfig>>;
+    /** Trusted hostnames for outbound requests */
+    trustedHosts?: string[];
+}
+export declare function configureGuard(cfg: SecurityConfig): void;
+export interface GuardResult {
+    blocked: boolean;
+    reason?: string;
+    violations?: WafViolation[];
+}
+/** Run all security checks for an inbound tool call. */
+export declare function guardRequest(tool: string, args: unknown): GuardResult;
+/** Scan output for sensitive data leakage. Logs a warning; does not block. */
+export declare function guardOutput(tool: string, text: string): string;