@a13xu/lucid 1.4.0 → 1.9.1

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;

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>;