@nekzus/liop 2.0.0-alpha.1 → 2.0.0-alpha.2

package/dist/server/index.js

@@ -1,1047 +0,0 @@
-import { Buffer } from "node:buffer";
-import crypto from "node:crypto";
-import { createRequire } from "node:module";
-import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-import * as grpc from "@grpc/grpc-js";
-import { FixedQueue, Piscina } from "piscina";
-import { z } from "zod";
-import { zodToJsonSchema } from "zod-to-json-schema";
-import { MeshNode } from "../mesh/node.js";
-import { LiopRpcServer } from "../rpc/server.js";
-import { log } from "../utils/logger.js";
-import { NerScanner } from "./ner-scanner.js";
-import { PII_PATTERNS, PII_PRESETS, PiiScanner } from "./pii.js";
-export { NerScanner, PII_PATTERNS, PII_PRESETS, PiiScanner };
-/**
- * When enabled, `payload` tools that are not LIOP v1 envelopes are passed through to the
- * registered handler unchanged (no worker extraction). Default off for strict protocol tests.
- */
-function respectPlainToolPayload() {
-    const v = process.env.LIOP_RESPECT_PLAIN_TOOL_PAYLOAD?.toLowerCase().trim();
-    return v === "1" || v === "true" || v === "yes";
-}
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-export class LiopServer {
-    serverInfo;
-    config;
-    logicCache = new Map();
-    connectionStats = new Map();
-    CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
-    THROTTLE_THRESHOLD = 5;
-    THROTTLE_COOLDOWN_MS = 60 * 1000; // 60 seconds
-    // [OWASP-A01] Sliding window rate limiter — prevents micro-query exfiltration
-    toolCallWindows = new Map();
-    toolCallMaxPerWindow;
-    toolCallWindowMs;
-    tools = new Map();
-    resources = new Map();
-    prompts = new Map();
-    activeSchema = null;
-    sandboxRecords = [];
-    piiScanner;
-    workerPool;
-    meshNode = null;
-    rpcServer = null;
-    boundPort = null;
-    sessions = new Map();
-    // Compact envelope: @LIOP{target,name}\n<code>\n@END
-    static LIOP_COMPACT_REGEX = /@LIOP\{(?<target>[^,}]+)(?:,(?<name>[^}]*))?\}\n(?<logic>[\s\S]*?)\n@END/m;
-    extractLogic(payload) {
-        const compact = payload.match(LiopServer.LIOP_COMPACT_REGEX);
-        return compact?.groups?.logic ? compact.groups.logic.trim() : null;
-    }
-    parseUnknownJson(input) {
-        if (typeof input !== "string")
-            return input;
-        const trimmed = input.trim();
-        if ((trimmed.startsWith("{") && trimmed.endsWith("}")) ||
-            (trimmed.startsWith("[") && trimmed.endsWith("]"))) {
-            try {
-                return JSON.parse(trimmed);
-            }
-            catch {
-                return input;
-            }
-        }
-        return input;
-    }
-    runPreflightPolicy(_toolName, logic, policy) {
-        if (!policy)
-            return null;
-        const compact = logic.replace(/\s+/g, " ");
-        if (policy.enforceAggregationFirst) {
-            const rowExtractionPatterns = [
-                // Block raw record dumps but allow safe aggregation chains
-                // (.reduce, .length, .filter().length, .every, .some)
-                /return\s+env\.records(?!\s*\.\s*(?:reduce|length|filter|every|some|find)\b)/i,
-                /return\s*\{[\s\S]*\b(accounts|patients|rows|records)\s*:\s*env\.records(?!\s*\.\s*(?:reduce|length|filter)\b)/i,
-            ];
-            if (rowExtractionPatterns.some((p) => p.test(compact))) {
-                return "Preflight policy rejected: potential row-level export pattern detected.";
-            }
-        }
-        if (policy.preflightDenyPatterns?.some((p) => p.test(compact))) {
-            return "Preflight policy rejected: custom deny pattern matched.";
-        }
-        return null;
-    }
-    validateOutputPolicy(toolName, output, policy) {
-        if (!policy)
-            return null;
-        const parsed = this.parseUnknownJson(output);
-        if (policy.outputSchema) {
-            // SEC-HARDENING: Force strict mode on ZodObject schemas to prevent
-            // key aliasing bypasses via .passthrough(). However, respect schemas
-            // that explicitly use .catchall() — calling .strict() would override
-            // the catchall with ZodNever, destroying the developer's intent.
-            const effectiveSchema = (() => {
-                if (!(policy.outputSchema instanceof z.ZodObject)) {
-                    return policy.outputSchema;
-                }
-                const obj = policy.outputSchema;
-                // If schema has an explicit catchall (not ZodNever), respect it
-                if (!(obj._def.catchall instanceof z.ZodNever)) {
-                    return obj;
-                }
-                // Otherwise force strict to block unrecognized keys by default
-                return obj.strict();
-            })();
-            const schemaResult = effectiveSchema.safeParse(parsed);
-            if (!schemaResult.success) {
-                // SEC-CRITICAL: Never expose rejected data in error messages.
-                // Only report the structural violation (unrecognized keys, type mismatches).
-                return `[LIOP] Output schema violation for ${toolName}: ${schemaResult.error.issues
-                    .map((i) => `${i.path.join(".") || "<root>"} ${i.message}`)
-                    .join("; ")}. HINT: Your output must conform to the declared schema. Use 'env.records' to access the dataset and return only allowed fields.`;
-            }
-        }
-        if (policy.enforceAggregationFirst &&
-            this.violatesAggregationFirstPolicy(this.unwrapForAggregationPolicyScan(parsed), policy.enforceAggregationFirst)) {
-            return "Aggregation-First Policy Violation: row-level export blocked. HINT: Use .reduce() to produce a flat {key:value} object. Do NOT use .map() to create arrays of objects.";
-        }
-        return null;
-    }
-    /**
-     * Proxied tools stringify a full MCP CallToolResult (`{ content: [...] }`).
-     * Aggregation-first heuristics must scan the inner business JSON, not the MCP envelope
-     * (otherwise `content` looks like a tabular array of objects and everything blocks).
-     */
-    unwrapForAggregationPolicyScan(input) {
-        if (typeof input === "string") {
-            const trimmed = input.trim();
-            if ((trimmed.startsWith("{") && trimmed.endsWith("}")) ||
-                (trimmed.startsWith("[") && trimmed.endsWith("]"))) {
-                try {
-                    return this.unwrapForAggregationPolicyScan(JSON.parse(trimmed));
-                }
-                catch {
-                    return input;
-                }
-            }
-            return input;
-        }
-        if (!input || typeof input !== "object") {
-            return input;
-        }
-        const rec = input;
-        if (!Array.isArray(rec.content) || rec.content.length === 0) {
-            return input;
-        }
-        const texts = [];
-        for (const part of rec.content) {
-            if (part && typeof part === "object" && "text" in part) {
-                const t = part.text;
-                if (typeof t === "string") {
-                    texts.push(t);
-                }
-            }
-        }
-        if (texts.length === 0) {
-            return input;
-        }
-        const joined = texts.length === 1 ? texts[0] : texts.join("\n");
-        return this.unwrapForAggregationPolicyScan(joined);
-    }
-    violatesAggregationFirstPolicy(input, policyObj) {
-        const maxRows = typeof policyObj === "object" &&
-            typeof policyObj.maxOutputRows === "number"
-            ? policyObj.maxOutputRows
-            : 10;
-        const allowPrimitives = typeof policyObj === "object" &&
-            typeof policyObj.allowPrimitiveArrays === "boolean"
-            ? policyObj.allowPrimitiveArrays
-            : true;
-        if (typeof input === "string") {
-            const trimmed = input.trim();
-            if ((trimmed.startsWith("{") && trimmed.endsWith("}")) ||
-                (trimmed.startsWith("[") && trimmed.endsWith("]"))) {
-                try {
-                    return this.violatesAggregationFirstPolicy(JSON.parse(trimmed), policyObj);
-                }
-                catch {
-                    return false;
-                }
-            }
-            return false;
-        }
-        if (Array.isArray(input)) {
-            if (input.length > 0 &&
-                input.every((item) => typeof item === "object" && item !== null)) {
-                // Treat tabular row export as non-aggregated leakage risk if above threshold.
-                if (input.length > maxRows) {
-                    return true;
-                }
-                return input.some((item) => this.violatesAggregationFirstPolicy(item, policyObj));
-            }
-            if (input.length > 0 &&
-                input.every((item) => typeof item !== "object" || item === null)) {
-                if (!allowPrimitives)
-                    return true;
-                return false;
-            }
-            return input.some((item) => this.violatesAggregationFirstPolicy(item, policyObj));
-        }
-        if (input && typeof input === "object") {
-            const keys = Object.keys(input);
-            // Treat flat dictionary with too many keys as non-aggregated leakage risk (Dynamic Key Bypass).
-            if (keys.length > maxRows) {
-                return true;
-            }
-            return Object.values(input).some((value) => this.violatesAggregationFirstPolicy(value, policyObj));
-        }
-        return false;
-    }
-    constructor(serverInfo, config) {
-        this.serverInfo = serverInfo;
-        this.config = config;
-        const nerScanner = this.config?.security?.enableNerScanning
-            ? new NerScanner()
-            : null;
-        this.piiScanner = new PiiScanner(this.config?.security?.piiPatterns ?? PII_PRESETS.GLOBAL_STRICT, this.config?.security?.forbiddenKeys ?? [
-            "id",
-            "name",
-            "fullName",
-            "firstName",
-            "lastName",
-            "address",
-            "street",
-            "city",
-            "postalCode",
-            "zipCode",
-            "phone",
-            "email",
-            "ssn",
-            "accountHolder",
-            "accountNumber",
-            "account_number",
-            "password",
-            "token",
-            "secret",
-            "privateKey",
-        ], nerScanner);
-        // [OWASP-A01] Rate limit: config > env > default (30 calls/min)
-        const rlConfig = this.config?.security?.rateLimit;
-        this.toolCallWindowMs =
-            rlConfig?.windowMs ??
-                Number.parseInt(process.env.LIOP_RATE_LIMIT_WINDOW_MS ?? "60000", 10);
-        this.toolCallMaxPerWindow =
-            rlConfig?.maxPerWindow ??
-                Number.parseInt(process.env.LIOP_RATE_LIMIT_MAX ?? "30", 10);
-        // Initialize Zero-Blocking Worker Pool for Heavy Cryptography & Sandboxing
-        const isTS = import.meta.url.endsWith(".ts");
-        const workerExt = isTS ? ".ts" : ".js";
-        let execArgv = [];
-        if (isTS) {
-            try {
-                const req = createRequire(import.meta.url);
-                const tsxPkg = req.resolve("tsx/package.json");
-                const absoluteTsx = pathToFileURL(path.join(path.dirname(tsxPkg), "dist", "loader.mjs")).href;
-                execArgv = ["--import", absoluteTsx];
-            }
-            catch (_e) {
-                execArgv = ["--import", "tsx"];
-            }
-        }
-        const isTest = process.env.NODE_ENV === "test" || process.env.VITEST;
-        // Sync capabilities to serverInfo for MCP Handshakes
-        if (this.config?.capabilities && !this.serverInfo.capabilities) {
-            this.serverInfo.capabilities = this.config.capabilities;
-        }
-        this.workerPool = new Piscina({
-            filename: path.resolve(__dirname, `../workers/logic-execution${workerExt}`),
-            minThreads: this.config?.workerPool?.minThreads ?? (isTest ? 0 : 2),
-            maxThreads: this.config?.workerPool?.maxThreads ?? (isTest ? 1 : 8),
-            idleTimeout: this.config?.workerPool?.idleTimeout ?? (isTest ? 500 : 5000),
-            maxQueue: "auto",
-            taskQueue: new FixedQueue(),
-            execArgv,
-            // [DoS Defense] Enforce hard memory ceiling per worker thread.
-            // Workers exceeding this limit are terminated by Node.js runtime.
-            resourceLimits: {
-                maxOldGenerationSizeMb: this.config?.workerPool?.maxHeapMb ??
-                    Number.parseInt(process.env.LIOP_WORKER_MAX_HEAP_MB ?? "64", 10),
-            },
-        });
-        // [Token Economy] Auto-register LIOP protocol spec as a single Resource.
-        // This centralizes the envelope documentation that was previously
-        // duplicated in every tool description, reducing token overhead.
-        this.resource("LIOP Envelope Specification", "liop://protocol/envelope-spec", "Complete Logic-on-Origin envelope format, execution rules, and security constraints", "text/plain", () => Promise.resolve(this.buildEnvelopeSpec()));
-    }
-    /**
-     * Builds the centralized LIOP envelope specification document.
-     * Served as a single Resource (liop://protocol/envelope-spec) instead
-     * of being duplicated across every tool description.
-     */
-    buildEnvelopeSpec() {
-        const lines = [
-            "LIOP v1 Envelope Specification",
-            "================================",
-            "",
-            "FORMAT:",
-            "",
-            "Compact Envelope:",
-            "  @LIOP{wasi_v1,TaskName}",
-            "  <JavaScript code>",
-            "  @END",
-            "",
-            "RUNTIME ENVIRONMENT:",
-            "- env.records: Array of data objects from the origin",
-            "- Must use 'return' to output results",
-            "- Zero-Trust WASI Sandbox (Node.js Worker Pool)",
-            "- Return aggregated objects, NOT raw row-level arrays",
-            "",
-            "SECURITY CONSTRAINTS:",
-            "- PII Egress Shield blocks raw identifiers in output",
-            "- Aggregation-First policy: prefer counts, averages, summaries",
-            "- AST Guardian: static analysis before execution",
-        ];
-        if (this.config?.security?.forbiddenKeys?.length) {
-            lines.push(`- Restricted fields: ${this.config.security.forbiddenKeys.join(", ")}`);
-        }
-        lines.push("", "OPTIONAL PARAMETERS:", "- __liop_bypass_ast_cache: boolean (force AST re-evaluation)");
-        return lines.join("\n");
-    }
-    /**
-     * Extracts a compact, human-readable field summary from a JSON Schema.
-     *
-     * Walks the schema structure to find actual data property names and types,
-     * rather than returning top-level schema metadata keys (type, items, etc.).
-     *
-     * Example output for a banking schema:
-     *   "Array of {id(string), accountHolder(string), balance(number), transactions(array of {date(string), amount(number)})}"
-     */
-    extractSchemaFieldSummary(schema, depth = 0) {
-        // Prevent excessive recursion in deeply nested schemas
-        if (depth > 3)
-            return "{...}";
-        const schemaType = schema.type;
-        const properties = schema.properties;
-        const items = schema.items;
-        // Object with properties → list field names with their types
-        if (properties) {
-            const fields = Object.entries(properties).map(([key, prop]) => {
-                const propType = prop.type;
-                if (propType === "array" && prop.items) {
-                    const nested = this.extractSchemaFieldSummary(prop.items, depth + 1);
-                    return `${key}(array of ${nested})`;
-                }
-                if (propType === "object" && prop.properties) {
-                    const nested = this.extractSchemaFieldSummary(prop, depth + 1);
-                    return `${key}(${nested})`;
-                }
-                return `${key}(${propType || "unknown"})`;
-            });
-            return `{${fields.join(", ")}}`;
-        }
-        // Array type → describe the items structure
-        if (schemaType === "array" && items) {
-            const itemsSummary = this.extractSchemaFieldSummary(items, depth + 1);
-            return `Array of ${itemsSummary}`;
-        }
-        // Simple type or unknown structure → fallback to key listing
-        if (schemaType)
-            return schemaType;
-        return Object.keys(schema).join(", ");
-    }
-    /**
-     * Convenience alias for connectToMesh(), matching official documentation.
-     */
-    async connect(options = {}) {
-        return this.connectToMesh(options);
-    }
-    /**
-     * Register a new Tool
-     */
-    tool(name, description, shape, handler, policy) {
-        if (this.tools.has(name)) {
-            throw new Error(`Tool already registered: ${name}`);
-        }
-        const schema = z.object(shape);
-        const generatedSchema = zodToJsonSchema(schema);
-        let finalDescription = description;
-        let finalHandler = handler;
-        // LIOP Zero-Shot Autonomy Middleware: Detect Logic-on-Origin tools
-        if (shape.payload && shape.payload instanceof z.ZodString) {
-            const blockedKeys = this.config?.security?.forbiddenKeys || [];
-            // [Token Economy] Centralized description: reference the protocol spec
-            // Resource instead of duplicating the full envelope format per tool.
-            // Same information, delivered once via liop://protocol/envelope-spec.
-            finalDescription +=
-                "\n\nPayload: LIOP v1 envelope (WASI sandbox)." +
-                    " Format: @LIOP{wasi_v1,TaskName}\\n<JS code>\\n@END" +
-                    " | Access data: env.records. Return aggregated object." +
-                    " | Full spec: resource liop://protocol/envelope-spec";
-            if (blockedKeys.length > 0) {
-                finalDescription += `\nRestricted fields: ${blockedKeys.join(", ")}.`;
-            }
-            if (this.activeSchema) {
-                const schemaDigest = this.extractSchemaFieldSummary(this.activeSchema);
-                finalDescription += `\nData structure: ${schemaDigest}. Full schema: resource liop://schema/global`;
-            }
-            finalHandler = async (args, _extra) => {
-                const clientId = "global_connection"; // Simplify for now, treating the instance as one connection
-                const now = Date.now();
-                const stats = this.connectionStats.get(clientId) || {
-                    failures: 0,
-                    lastAttempt: 0,
-                };
-                if (stats.failures >= this.THROTTLE_THRESHOLD &&
-                    now - stats.lastAttempt < this.THROTTLE_COOLDOWN_MS) {
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: "LIOP_THROTTLED: Too many violations. Cooling down for 60 seconds.",
-                            },
-                        ],
-                        isError: true,
-                    };
-                }
-                const payloadValue = args
-                    .payload;
-                const bypassCache = args.__liop_bypass_ast_cache === true;
-                const payloadHash = crypto
-                    .createHash("sha256")
-                    .update(payloadValue)
-                    .digest("hex");
-                const logic = this.extractLogic(payloadValue);
-                const cached = this.logicCache.get(payloadHash);
-                if (!bypassCache &&
-                    cached &&
-                    now - cached.timestamp < this.CACHE_TTL_MS) {
-                    // Hash verified. Skips boundaries check (already validated!). Extract logic directly.
-                    if (logic) {
-                        args.payload = logic;
-                        // DELEGATE TO WORKER POOL: Parallel PQC & Sandboxing
-                        const preflightReason = this.runPreflightPolicy(name, logic, policy);
-                        if (preflightReason) {
-                            return {
-                                content: [{ type: "text", text: preflightReason }],
-                                isError: true,
-                            };
-                        }
-                        return await this.executeInWorkerPool(args, logic, name);
-                    }
-                }
-                if (!logic) {
-                    if (respectPlainToolPayload()) {
-                        return await handler(args, _extra);
-                    }
-                    stats.failures++;
-                    stats.lastAttempt = now;
-                    this.connectionStats.set(clientId, stats);
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: "Error: Malformed payload. Missing @LIOP boundary.\\nYou MUST wrap your logic exactly like this:\\n\\n@LIOP{wasi_v1,DynamicAudit}\\n// Your JS code here\\n@END",
-                            },
-                        ],
-                        isError: true,
-                    };
-                }
-                try {
-                    // Logic check already performed above, extraction is guaranteed at this point.
-                    // biome-ignore lint/style/noNonNullAssertion: safe extraction after check
-                    const logic = this.extractLogic(args.payload);
-                    // Extract pure logic and deliver it to the developer's function
-                    args.payload = logic;
-                    // DELEGATE TO WORKER POOL: Parallel PQC & Sandboxing (Includes PII Shield)
-                    const preflightReason = this.runPreflightPolicy(name, logic, policy);
-                    if (preflightReason) {
-                        stats.failures++;
-                        stats.lastAttempt = now;
-                        this.connectionStats.set(clientId, stats);
-                        return {
-                            content: [{ type: "text", text: preflightReason }],
-                            isError: true,
-                        };
-                    }
-                    const result = await this.executeInWorkerPool(args, logic, name);
-                    if (!result.isError) {
-                        this.connectionStats.set(clientId, {
-                            failures: 0,
-                            lastAttempt: now,
-                        });
-                        this.logicCache.set(payloadHash, {
-                            hash: payloadHash,
-                            timestamp: now,
-                        });
-                    }
-                    else {
-                        stats.failures++;
-                        stats.lastAttempt = now;
-                        this.connectionStats.set(clientId, stats);
-                    }
-                    return result;
-                }
-                catch (error) {
-                    const e = error;
-                    stats.failures++;
-                    stats.lastAttempt = now;
-                    this.connectionStats.set(clientId, stats);
-                    return {
-                        content: [
-                            { type: "text", text: `ExecutionRuntimeException: ${e.message}` },
-                        ],
-                        isError: true,
-                    };
-                }
-            };
-        }
-        const inputSchema = {
-            type: "object",
-            properties: generatedSchema.properties || {},
-            required: generatedSchema.required,
-        };
-        this.tools.set(name, {
-            tool: { name, description: finalDescription, inputSchema },
-            handler: finalHandler,
-            schema,
-            policy,
-        });
-        // [LIOP-ALPHA] Auto-announce capability to the Mesh P2P DHT if node is active
-        if (this.meshNode) {
-            this.meshNode.announceCapability(name).catch((err) => {
-                log.info(`[LIOP-Mesh] Failed to auto-announce tool ${name}: ${err.message}`);
-            });
-        }
-    }
-    /**
-     * Register a dynamic prompt
-     */
-    prompt(name, description, args, handler) {
-        if (this.prompts.has(name)) {
-            throw new Error(`Prompt already registered: ${name}`);
-        }
-        this.prompts.set(name, {
-            prompt: { name, description, arguments: args },
-            handler,
-        });
-    }
-    /**
-     * Enables LIOP Zero-Shot Autonomy by registering the Blind Analyst standard prompt.
-     */
-    enableZeroShotAutonomy() {
-        this.prompt("liop_blind_analyst", "The official Logic-Injection-on-Origin Protocol system prompt. Instructs the LLM on how to securely inject Logic-on-Origin without violating PII or safety constraints.", [], (_request) => {
-            return {
-                description: "LIOP Blind Analyst Instructions",
-                messages: [
-                    {
-                        role: "user",
-                        content: {
-                            type: "text",
-                            text: `You are the "Blind Analyst" operating within the Logic-Injection-on-Origin Protocol (LIOP) ecosystem.
-Your objective is to perform secure Logic-on-Origin injections. You must process remote data without ever requesting its extraction.
-
-INDUSTRIAL CONSTRAINTS & PROTOCOL RULES:
-1. DATA PRIVACY: NEVER attempt to export Personally Identifiable Information (PII). The LIOP Egress Shield will block any response containing raw IDs, names, or addresses.
-2. AGGREGATION FIRST: Always prefer returning counts, averages, or anonymized summaries.
-3. PAYLOAD ENCAPSULATION: Your JavaScript payloads MUST strictly adhere to the Compact Envelope. DO NOT include markdown backticks or leading text inside the 'payload' argument.
-   Structure:
-   @LIOP{wasi_v1,AnalysisTask}
-   // Your JS Code Here
-   @END
-4. RUNTIME SCOPE: The execution environment provides a global 'env' object. Use 'env.records' to access the target dataset.
-5. LOCALIZATION: Format all JSON response keys in the language used by the user in their query (e.g., use Spanish keys if the query is in Spanish).
-6. SCHEMA RIGIDITY: Only use fields defined in the 'Data Dictionary'. Usage of non-existent fields will trigger a sandbox runtime exception.${this.activeSchema
-                                ? `\n\nCURRENT DATA DICTIONARY (STRICT):\n${JSON.stringify(this.activeSchema, null, 2)}`
-                                : ""}
-
-Protocol Adherence is mandatory for successful execution.`,
-                        },
-                    },
-                ],
-            };
-        });
-    }
-    /**
-     * Register a dynamic resource
-     */
-    resource(name, uri, description, mimeType, content) {
-        if (this.resources.has(uri)) {
-            throw new Error(`Resource URI already registered: ${uri}`);
-        }
-        this.resources.set(uri, { name, uri, description, mimeType, content });
-    }
-    /**
-     * Broadcasts the Data Dictionary to the LLM prior to code injection.
-     */
-    dataDictionary(schema, name = "Global Medical Data Dictionary", uri = "liop://schema/global", description = "Exposes the internal database schema for Zero-Shot Autonomy planning") {
-        this.activeSchema = schema;
-        // [Token Economy] Retroactively update tool descriptions with schema field references.
-        // Extracts actual data property names from the JSON Schema structure.
-        const schemaDigest = this.extractSchemaFieldSummary(schema);
-        for (const [toolName, entry] of this.tools.entries()) {
-            if (entry.schema.shape.payload &&
-                entry.schema.shape.payload instanceof z.ZodString &&
-                entry.tool.description &&
-                !entry.tool.description.includes("Data structure:")) {
-                entry.tool.description += `\nData structure: ${schemaDigest}. Full schema: resource ${uri}`;
-                this.tools.set(toolName, entry);
-            }
-        }
-        this.resource(name, uri, description, "application/json", JSON.stringify(schema, null, 2));
-    }
-    /**
-     * Manually invalidates the AST Logic Cache (e.g. for Zero-Day patches).
-     */
-    clearAstCache() {
-        this.logicCache.clear();
-        log.info("[LIOP-SDK] AST Security Cache cleared by Admin.");
-    }
-    /**
-     * Sliding window rate limiter for tool call frequency.
-     * Prevents micro-query exfiltration attacks where an attacker
-     * makes hundreds of individually-legitimate calls to reconstruct
-     * the full dataset field by field. (OWASP A01)
-     */
-    checkToolCallRateLimit(toolName) {
-        const now = Date.now();
-        const windowMs = this.toolCallWindowMs;
-        const maxPerWindow = this.toolCallMaxPerWindow;
-        const window = this.toolCallWindows.get(toolName) || [];
-        // Evict expired timestamps outside the sliding window
-        const active = window.filter((t) => now - t < windowMs);
-        if (active.length >= maxPerWindow) {
-            const retryAfterSec = Math.ceil((active[0] + windowMs - now) / 1000);
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: `LIOP_RATE_LIMITED: Too many calls to ${toolName}. ` +
-                            `Max ${maxPerWindow} per ${windowMs / 1000}s window. ` +
-                            `Retry after ${retryAfterSec}s.`,
-                    },
-                ],
-                isError: true,
-            };
-        }
-        active.push(now);
-        this.toolCallWindows.set(toolName, active);
-        return null;
-    }
-    /**
-     * Emulates calling a tool (used locally or via LIOPMcpBridge)
-     */
-    async callTool(request) {
-        const entry = this.tools.get(request.name);
-        if (!entry) {
-            throw new Error(`Tool not found: ${request.name}`);
-        }
-        // [OWASP-A01] Rate limiting: prevent micro-query exfiltration
-        const rateLimitResult = this.checkToolCallRateLimit(request.name);
-        if (rateLimitResult)
-            return rateLimitResult;
-        try {
-            // Validate inputs natively with Zod before execution
-            const parsedArgs = entry.schema.parse(request.arguments || {});
-            // Re-inject the bypass flag if present since Zod might strip unrecognized keys
-            if (request.arguments
-                ?.__liop_bypass_ast_cache === true) {
-                parsedArgs.__liop_bypass_ast_cache = true;
-            }
-            // [LOGIC-ON-ORIGIN] Intercept code injection directly
-            if (parsedArgs &&
-                typeof parsedArgs.payload === "string") {
-                const payload = parsedArgs
-                    .payload;
-                const logic = this.extractLogic(payload);
-                if (logic) {
-                    const preflightReason = this.runPreflightPolicy(request.name, logic, entry.policy);
-                    if (preflightReason) {
-                        return {
-                            content: [{ type: "text", text: preflightReason }],
-                            isError: true,
-                        };
-                    }
-                    parsedArgs.payload = logic;
-                    return await this.executeInWorkerPool(parsedArgs, logic, request.name);
-                }
-            }
-            const result = await entry.handler(parsedArgs, {});
-            return result;
-        }
-        catch (error) {
-            const e = error;
-            if (e instanceof z.ZodError) {
-                return {
-                    content: [{ type: "text", text: `Validation Error: ${e.message}` }],
-                    isError: true,
-                };
-            }
-            return {
-                content: [
-                    { type: "text", text: `Internal Execution Error: ${e.message}` },
-                ],
-                isError: true,
-            };
-        }
-    }
-    /**
-     * Retrieves registered tools
-     */
-    listTools() {
-        return Array.from(this.tools.values()).map((t) => t.tool);
-    }
-    /**
-     * Retrieves registered prompts
-     */
-    listPrompts() {
-        return Array.from(this.prompts.values()).map((p) => p.prompt);
-    }
-    /**
-     * Gets a specific prompt by name
-     */
-    async getPrompt(request) {
-        const entry = this.prompts.get(request.name);
-        if (!entry) {
-            throw new Error(`Prompt not found: ${request.name}`);
-        }
-        return await entry.handler(request);
-    }
-    /**
-     * Retrieves registered resources
-     */
-    listResources() {
-        return Array.from(this.resources.values());
-    }
-    /**
-     * Reads a specific resource by URI
-     */
-    async readResource(uri) {
-        const resource = this.resources.get(uri);
-        if (!resource) {
-            throw new Error(`Resource not found: ${uri}`);
-        }
-        let text = "No description provided";
-        if (typeof resource.content === "function") {
-            text = await resource.content();
-        }
-        else if (typeof resource.content === "string") {
-            text = resource.content;
-        }
-        else if (resource.description) {
-            text = resource.description;
-        }
-        return {
-            contents: [
-                {
-                    uri: resource.uri,
-                    mimeType: resource.mimeType || "text/plain",
-                    text,
-                },
-            ],
-        };
-    }
-    getServerInfo() {
-        return this.serverInfo;
-    }
-    getMeshNode() {
-        return this.meshNode;
-    }
-    /**
-     * Injects data into the secure sandbox context for Logic-on-Origin tools.
-     */
-    setSandboxData(records) {
-        this.sandboxRecords = records;
-    }
-    getBoundPort() {
-        return this.boundPort;
-    }
-    /**
-     * Connects to the libp2p Kademlia DHT and announces capabilities.
-     * Boots the gRPC server for secure Logic-on-Origin.
-     */
-    async connectToMesh(options = {}) {
-        const envPort = process.env.LIOP_GRPC_PORT
-            ? Number.parseInt(process.env.LIOP_GRPC_PORT, 10)
-            : undefined;
-        const port = options.port ?? envPort ?? 50051;
-        // 1. Initialize Mesh Node (Discovery)
-        this.meshNode = new MeshNode(options.meshConfig);
-        await this.meshNode.start();
-        // 2. Register LIOP Manifest Protocol Handler
-        // This allows remote peers to query our tool/resource metadata dynamically.
-        const meshNodeRef = this.meshNode;
-        this.meshNode.registerManifestHandler(() => {
-            const tools = this.listTools().map((t) => ({
-                name: t.name,
-                description: t.description,
-                inputSchema: t.inputSchema,
-            }));
-            const resources = Array.from(this.resources.values()).map((r) => ({
-                name: r.name,
-                uri: r.uri,
-                description: r.description,
-                mimeType: r.mimeType,
-                text: typeof r.content === "string" ? r.content : r.description,
-            }));
-            return {
-                peerId: meshNodeRef.getPeerId(),
-                grpcPort: port,
-                tools,
-                resources,
-                serverInfo: this.serverInfo,
-            };
-        });
-        // 3. Announce local tools to the DHT
-        for (const tool of this.listTools()) {
-            await this.meshNode.announceCapability(tool.name).catch(log.info);
-        }
-        // 4. Announce manifest availability
-        await this.meshNode.announceManifest().catch(log.info);
-        // 5. Initialize gRPC Server (Execution)
-        this.rpcServer = new LiopRpcServer();
-        this.rpcServer.addService({
-            negotiateIntent: (call, callback) => {
-                const request = call.request;
-                log.info(`[LIOP-RPC] Negotiating intent for capability: ${request.capability_hash}`);
-                // Standard dynamic import to avoid potential circularity
-                import("../rpc/crypto/kyber.js").then(async ({ Kyber768Wrapper }) => {
-                    const { publicKey, secretKey } = await Kyber768Wrapper.generateKeyPair();
-                    const sessionToken = crypto.randomUUID();
-                    this.sessions.set(sessionToken, {
-                        capability_hash: request.capability_hash,
-                        kyber_sk: secretKey,
-                    });
-                    callback(null, {
-                        accepted: true,
-                        session_token: sessionToken,
-                        error_message: "",
-                        kyber_public_key: publicKey,
-                    });
-                });
-            },
-            executeLogic: async (call) => {
-                const request = call.request;
-                log.info(`[LIOP-RPC] Executing Logic-on-Origin for session: ${request.session_token}`);
-                const session = this.sessions.get(request.session_token);
-                if (!session) {
-                    call.emit("error", {
-                        code: grpc.status.UNAUTHENTICATED,
-                        details: "Invalid session token",
-                    });
-                    return;
-                }
-                try {
-                    // Pass to Worker Pool for PQC Decryption and WASI/V8 execution
-                    const workerResponse = await this.workerPool.run({
-                        ciphertext: request.pqc_ciphertext,
-                        secretKeyObj: Array.from(session.kyber_sk),
-                        wasmBinary: request.wasm_binary,
-                        inputs: request.inputs,
-                        aesNonce: request.aes_nonce,
-                        records: this.sandboxRecords,
-                        sessionToken: request.session_token,
-                        isEncrypted: true,
-                    });
-                    let finalOutput;
-                    try {
-                        finalOutput =
-                            typeof workerResponse.output === "string"
-                                ? workerResponse.output
-                                : JSON.stringify(workerResponse.output);
-                        // [PROTOCOL TRANSFORMER] Support for Proxied Tool Calls
-                        const decoded = JSON.parse(finalOutput);
-                        if (decoded.__liop_proxy_tool) {
-                            log.info(`[LIOP-RPC] Executing Proxied Tool: ${decoded.__liop_proxy_tool}`);
-                            const toolResult = await this.callTool({
-                                name: decoded.__liop_proxy_tool,
-                                arguments: decoded.__liop_proxy_args || {},
-                            });
-                            finalOutput = JSON.stringify(toolResult);
-                        }
-                    }
-                    catch {
-                        finalOutput = String(workerResponse.output);
-                    }
-                    const response = {
-                        semantic_evidence: finalOutput,
-                        cryptographic_proof: Buffer.from(workerResponse.image_id || "", "hex"),
-                        zk_receipt: workerResponse.zk_receipt
-                            ? Buffer.from(workerResponse.zk_receipt, "base64")
-                            : Buffer.from(""),
-                        is_error: false,
-                    };
-                    // Final PII check for gRPC egress
-                    const violation = this.piiScanner.scan([
-                        { type: "text", text: finalOutput },
-                    ]);
-                    const aggregationViolation = this.violatesAggregationFirstPolicy(this.unwrapForAggregationPolicyScan(finalOutput));
-                    if (violation || aggregationViolation) {
-                        // SEC-CRITICAL: Log details server-side, never expose to caller
-                        const internalReason = violation || "Aggregation-First Policy Violation";
-                        log.info(`[LIOP-RPC] Secure egress blocked in gRPC stream: ${internalReason}`);
-                        response.semantic_evidence =
-                            "[LIOP] Egress Security Violation. Output blocked due to policy enforcement.";
-                        response.is_error = true;
-                    }
-                    call.write(response, () => {
-                        call.end();
-                    });
-                }
-                catch (error) {
-                    const e = error;
-                    const isDev = process.env.NODE_ENV === "development" ||
-                        process.env.NODE_ENV === "test";
-                    const detail = e.message || String(error);
-                    log.error(`[LIOP-RPC] Execution Error: ${detail}`);
-                    const errorMessage = isDev
-                        ? `Execution Error: ${detail}`
-                        : "[LIOP] Execution Failed. The injected logic violated runtime constraints or encountered a fatal error.";
-                    // Send error response before closing, avoiding "stream closed without results"
-                    const errorResponse = {
-                        semantic_evidence: errorMessage,
-                        cryptographic_proof: Buffer.from(""),
-                        zk_receipt: Buffer.from(""),
-                        is_error: true,
-                    };
-                    try {
-                        call.write(errorResponse, () => {
-                            call.end();
-                        });
-                    }
-                    catch (_writeErr) {
-                        call.end();
-                    }
-                }
-            },
-        });
-        this.boundPort = await this.rpcServer.listen(port);
-        log.info(`[LIOP-SDK] Node successfully announced to Mesh. PeerID: ${this.meshNode.getPeerId()}`);
-    }
-    /**
-     * Internal worker execution with Egress Filtering logic.
-     */
-    async executeInWorkerPool(_args, rawPayload, toolName) {
-        try {
-            // Transparent local execution without dynamic PQC
-            const workerResponse = await this.workerPool.run({
-                ciphertext: new Uint8Array(0),
-                secretKeyObj: Array.from(new Uint8Array(0)),
-                kyberPublicKey: new Uint8Array(0),
-                wasmBinary: Buffer.from(rawPayload),
-                inputs: {},
-                records: this.sandboxRecords,
-                sessionToken: "local-dev-token",
-                isEncrypted: false, // Use plaintext for local Logic-on-Origin injection
-            });
-            // Standard MCP Content Array
-            const textOutput = JSON.stringify({
-                computation_result: workerResponse.output,
-                image_id: workerResponse.image_id,
-                zk_receipt: workerResponse.zk_receipt,
-                status: "Worker Pool Execution Success",
-            });
-            const content = [
-                {
-                    type: "text",
-                    text: textOutput,
-                },
-            ];
-            const toolPolicy = toolName
-                ? this.tools.get(toolName)?.policy
-                : undefined;
-            const policyViolation = this.validateOutputPolicy(toolName || "unknown_tool", workerResponse.output, toolPolicy);
-            if (policyViolation) {
-                // SEC-CRITICAL: Log details server-side, never expose to caller in Production
-                log.info(`[LIOP-SDK] Output policy blocked for ${toolName || "unknown_tool"}: ${policyViolation}`);
-                const isDev = process.env.NODE_ENV === "development" ||
-                    process.env.NODE_ENV === "test";
-                const errorMessage = isDev
-                    ? policyViolation
-                    : "[LIOP] Egress Security Violation. Output blocked due to policy enforcement. HINT: Return only aggregated, non-PII results using .reduce() to produce a flat {key:value} object with allowed schema fields.";
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: errorMessage,
-                        },
-                    ],
-                    isError: true,
-                };
-            }
-            // Professional PII Protection Guard
-            const violation = this.piiScanner.scan(content);
-            const aggregationViolation = this.violatesAggregationFirstPolicy(workerResponse.output);
-            if (violation || aggregationViolation) {
-                // SEC-CRITICAL: Log the specific violation reason server-side only.
-                // Never expose detection details (entity names, matched values) to the caller in Production.
-                const internalReason = violation ||
-                    "Aggregation-First Policy Violation: Output blocked due to dynamic flat-key policy enforcement.";
-                log.info(`[LIOP-SDK] Secure egress blocked in local execution: ${internalReason}`);
-                const isDev = process.env.NODE_ENV === "development" ||
-                    process.env.NODE_ENV === "test";
-                const errorMessage = isDev
-                    ? `[LIOP] Egress Security Violation: ${internalReason}`
-                    : "[LIOP] Egress Security Violation. Output blocked due to policy enforcement. HINT: Return only aggregated, non-PII results using .reduce() to produce a flat {key:value} object with allowed schema fields.";
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: errorMessage,
-                        },
-                    ],
-                    isError: true,
-                };
-            }
-            return { content };
-        }
-        catch (error) {
-            const e = error;
-            const isDev = process.env.NODE_ENV === "development" ||
-                process.env.NODE_ENV === "test";
-            const detail = e.message || String(error);
-            log.error(`[LIOP-SDK] WorkerPool Execution Fault: ${detail}`);
-            const errorMessage = isDev
-                ? `WorkerPoolError: ${detail}`
-                : "[LIOP] Execution Failed. The injected logic violated runtime constraints or encountered a fatal error.";
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: errorMessage,
-                    },
-                ],
-                isError: true,
-            };
-        }
-    }
-    /**
-     * Safely destroys the worker pool, gRPC server, and Mesh node.
-     * Recommended to be called during graceful shutdowns or test teardowns.
-     */
-    async close() {
-        if (this.workerPool) {
-            await this.workerPool.close({ force: true });
-        }
-        if (this.rpcServer) {
-            await this.rpcServer.stop();
-        }
-        if (this.meshNode) {
-            await this.meshNode.stop();
-        }
-    }
-}