The official TypeScript SDK and MCP Bridge for the Logic-Injection-on-Origin Protocol.
\n\n
\n \n \n \n \n \n \n
\n
\n\n---\n\n## Official Documentation\n\nComprehensive interactive guides, architectural deep dives, and API specifications are hosted on our official portal:\n\n| Documentation Section | Focus Area | Canonical Guide |\n|---|---|---|\n| **Overview & Setup** | Package architecture, core exports, and installation modes | [SDK Overview](https://nekzus-32.mintlify.app/typescript-sdk/overview) |\n| **LiopClient API** | Discovery, intent negotiation, gRPC channels, and error catalog | [LiopClient Reference](https://nekzus-32.mintlify.app/typescript-sdk/client) |\n| **LiopServer API** | Capability hosting, Zod schemas, and V8 sandboxing boundaries | [LiopServer Reference](https://nekzus-32.mintlify.app/typescript-sdk/server) |\n| **LiopMcpBridge** | Zero-trust wrapping of `@modelcontextprotocol/sdk` servers | [Bridge Documentation](https://nekzus-32.mintlify.app/typescript-sdk/bridge) |\n| **Runtime & Discovery** | `TopologyProbe`, `RoutingTable` circuit breaker, and `TokenManager` | [Runtime Architecture](https://nekzus-32.mintlify.app/typescript-sdk/runtime) |\n| **Security Architecture** | 6-Layer defense-in-depth, AST Guardian, and Egress PII Shield | [Security Guide](https://nekzus-32.mintlify.app/typescript-sdk/security) |\n| **Observability & SRE** | Prometheus metrics catalog and 26-panel Grafana master dashboard | [Observability Runbook](https://nekzus-32.mintlify.app/operations/observability-runbook) |\n\n---\n\n## Overview\n\n`@nekzus/liop` is an SDK that implements the **Logic-Injection-on-Origin (LIO)** paradigm: instead of extracting raw data from a server and sending it to an LLM, the LLM injects a micro-module of logic to be executed *at the data source*, inside a secure sandbox. The result, and never the raw data, is returned.\n\nThis addresses the data privacy, bandwidth, and latency bottlenecks of distributed agent data analysis.\n\n### Key Capabilities\n\n| Feature | Description |\n| :---------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- |\n| **Logic-Injection-on-Origin** | LLMs send code, not queries. Data never leaves the origin server. |\n| **Dual-Era MCP Compliance** | Dual-era compatibility supporting modern stateless MCP v2 (2026-07-28) and legacy MCP (2025-11-25) clients (Claude Desktop, Cursor). |\n| **Token Economy Engine** | Inlined BPE `o200k_base` tokenizer with zero runtime dependencies (16.5MB footprint reduction) and OpenTelemetry `gen_ai.*` bridge. |\n| **Protocol Interceptors & Jev** | In-situ pre/post execution admission hooks (`LogInterceptor`, `AuditInterceptor`, `GatewayInterceptor`) with TypeSafe Jev schema validation for protocol payload governance. |\n| **Interactive Playground UI** | Real-time Web UI (`:16000` prod / `:14000` dev) with 4-tab modular architecture (`Output`, `Debug`, `Telemetry`, `Export`), code generation (TS/cURL/Python), and dual OLED/Slate themes. |\n| **Multi-Tier Sovereign Enclaves** | Physical socket isolation via `@libp2p/pnet` (256-bit Swarm Key PSK) and Border LIO Gateway (`blg`) with OAuth 2.1 authentication. |\n| **AST Fuel Metering** | Deterministic AST instruction fuel scoring with 100-bucket quantization for NIST SP 800-53 timing side-channel elimination (`stddev = 0`).|\n| **Differential Privacy Engine** | NIST SP 800-226 Laplace mechanism with CSPRNG entropy, query-aware sensitivity, and deterministic ZK-Receipt auditing (`DpEngine`). |\n| **MCP Drop-in Replacement** | `LiopServer` mirrors the Anthropic MCP `Server` API (tools, resources, and prompts with `Zod` schemas). |\n| **Guardian AST** | Pre-execution heuristic inspection blocks sandbox escapes (`require`, `fs`, `eval`, `fetch`, prototype pollution). |\n| **IFC Taint Analyzer** | 5-pass Acorn AST information flow control tracking collection aliases, correlation guards, and extrema gates at preflight. |\n| **WASI Sandbox** | JavaScript payloads execute inside V8 isolates with CPU fuel limits, no Node.js globals, and safe environment isolation (`allowEnv`). |\n| **Adaptive Network Discovery**| Single-URL RFC 9728 Protected Resource Metadata probe and adaptive execution mode resolution (`TopologyProbe`). |\n| **Resilient Hybrid Routing** | Deterministic per-tool multiplexing across `http-gateway`, `p2p-grpc`, and `local` with 5-failure circuit breaker (`RoutingTable`).|\n| **OAuth 2.1 M2M Lifecycle** | Concurrency in-flight de-duplication, 30-second preemptive refresh buffer, and reactive invalidation (`TokenManager`). |\n| **Sliding-Window Rate Limiter**| In-memory OWASP API4:2023 rate limiting with background cleanup unreferenced intervals (`InMemoryRateLimiter`). |\n| **ZK-Receipts** | Tri-modal Zero-Knowledge proofs: HMAC-SHA256 (v1), Groth16 BN254 with 144-byte binary journal (v2), and dual-layer ML-DSA-65 post-quantum hybrid receipts (v2.1). Enforces `ZK_BLOCKING` on Tier 1 Enclaves. |\n| **Hardware TEE Attestation** | Pre-flight validation of confidential hardware root-of-trust evidence for AMD SEV-SNP (1,184-byte report) and AWS Nitro Enclaves (`verifyTeeAttestationDetailed`). |\n| **Worker Pool** | Heavy computation (crypto, sandboxing) dispatched to OS threads via `piscina` with background async warmup. |\n| **Post-Quantum Ready** | ML-KEM-768 (Kyber) + ML-DSA-65 (Dilithium) with 1-hour session lifetime and AES-256-GCM encryption. |\n| **Enterprise Observability** | Immutable SOC 2 Hash-Chain audit log (`AuditLogger`), physical wire egress tracking, Prometheus metrics (`/metrics`), and K8s probes. |\n| **P2P Mesh** | Kademlia DHT discovery via `libp2p` with TCP + WebSocket + Yamux multiplexing and Noise encryption. |\n\n---\n\n## Installation\n\n```bash\nnpm install @nekzus/liop@latest\n```\n\nOr for the latest stable zero-trust features on the beta channel:\n\n```bash\nnpm install @nekzus/liop@beta\n```\n\n> **Requirements:** Node.js ≥ 20.0. The SDK uses `node:crypto`, `node:vm`, and `piscina` (worker threads) internally.\n\n### Zero-Bloat & Micro-Deployments (Opt-Out)\n\nBy default, the SDK provides backward compatibility with MCP (`LiopMcpBridge`) by declaring `@modelcontextprotocol/sdk` as an optional dependency (which is automatically resolved by standard installations of NPM, PNPM, or Yarn).\n\nFor constrained production environments (e.g., Docker, AWS Lambda, Edge/IoT) where every megabyte counts, you can perform a **pure, zero-bloat LIOP installation** by opting out of the optional dependencies:\n\n```bash\n# npm\nnpm install @nekzus/liop@latest --no-optional\n\n# pnpm\npnpm add @nekzus/liop@latest --without optional\n\n# yarn\nyarn add @nekzus/liop@latest --ignore-optional\n```\n\nThe SDK uses dynamic `import()` statements under the hood to ensure that MCP translator modules are only loaded if they are actually instantiated, guaranteeing a lightweight memory footprint.\n\n---\n\n## LIOP Agent (CLI)\n\nThe SDK includes a zero-config agent CLI (`liop`) designed to bridge the Logic-Injection-on-Origin Protocol with local AI clients like **Claude Desktop**.\n\n### Installation & Run\n\nYou can run the agent directly using `npx` (recommended) or install it globally:\n\n```bash\n# Run instantly\nnpx @nekzus/liop@latest\n\n# Or install globally\nnpm install -g @nekzus/liop@latest\nliop\n```\n\n### Claude Desktop Configuration\n\nTo integrate LIOP into Claude Desktop, update your `claude_desktop_config.json` (typically found in `%APPDATA%\\Claude\\claude_desktop_config.json` on Windows):\n\n```json\n{\n \"mcpServers\": {\n \"liop\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@nekzus/liop@latest\"],\n \"env\": {\n \"LIOP_NEXUS_URL\": \"http://your-nexus-host:15000\",\n \"LIOP_LOG_LEVEL\": \"info\",\n \"LIOP_TOKEN_BANK\": \"your-secure-bank-token\",\n \"LIOP_TOKEN_VAULT\": \"your-secure-vault-token\",\n \"NODE_OPTIONS\": \"--use-system-ca\"\n }\n }\n }\n}\n```\n\n### Persistence & Identity\n\nThe agent automatically manages your P2P identity:\n\n- **Identity Path**: `~/.liop/identity.json`. This file contains your unique PeerID. Keep it safe if you want to maintain a consistent identity in the mesh.\n- **Bootstrap Nodes**: By default, the agent connects to the **LIOP Alpha Nexus**. You can provide custom bootstrap addresses as CLI arguments:\n ```bash\n npx @nekzus/liop@latest /ip4/1.2.3.4/tcp/4001/p2p/PEER_ID\n ```\n\n---\n\n## Quick Start\n\n### 1. Create a Server\n\n```typescript\nimport { LiopServer, PII_PATTERNS } from \"@nekzus/liop/server\";\nimport { z } from \"zod\";\n\nconst server = new LiopServer(\n { name: \"MyDataNode\", version: \"1.0.0\" },\n {\n capabilities: { tools: { listChanged: true } },\n security: {\n // Built-in PII detection (Email, Credit Card, IP, Phone)\n piiPatterns: [PII_PATTERNS.EMAIL, PII_PATTERNS.CREDIT_CARD],\n // Keys that will be stripped from any outgoing response\n forbiddenKeys: [\"id\", \"ssn\", \"password\", \"email\", \"name\"],\n },\n }\n);\n```\n\n### 2. Register a Tool\n\n```typescript\nserver.tool(\n \"analyze_logs\",\n \"Analyzes local log files without sending raw data to the LLM.\",\n { target_error: z.string().describe(\"The error pattern to search for\") },\n async ({ target_error }) => {\n // This logic runs at origin, data never leaves the server\n return {\n content: [{ type: \"text\", text: `Found 51 occurrences of ${target_error}` }],\n };\n }\n);\n```\n\n### 3. Connect to Claude Desktop / Cursor (MCP Bridge)\n\n```typescript\nimport { LiopMcpBridge } from \"@nekzus/liop/bridge\";\n\nconst bridge = new LiopMcpBridge(server);\nawait bridge.connect(); // Listens on stdio (JSON-RPC 2.0)\n```\n\n**Claude Desktop config** (`claude_desktop_config.json`):\n\n```json\n{\n \"mcpServers\": {\n \"my-data-node\": {\n \"command\": \"npx\",\n \"args\": [\"tsx\", \"src/server.ts\"]\n }\n }\n}\n```\n\n---\n\n## Module Exports\n\nThe package exposes targeted entry points to minimize bundle size:\n\n```typescript\nimport { LiopServer, PII_PATTERNS } from \"@nekzus/liop/server\";\nimport { LiopMcpBridge } from \"@nekzus/liop/bridge\";\nimport { LiopClient } from \"@nekzus/liop/client\";\nimport type { Tool, Resource, Prompt, CallToolRequest, CallToolResult } from \"@nekzus/liop/types\";\n```\n\n---\n\n## API Reference\n\n### `LiopServer`\n\nThe core class for declaring data nodes. API-compatible with Anthropic's MCP `Server`.\n\n#### Constructor\n\n```typescript\nnew LiopServer(\n serverInfo: { name: string; version: string },\n config?: {\n capabilities?: Record;\n workerPool?: {\n enabled?: boolean; // Enable OS-thread sandboxing (default: true)\n minThreads?: number; // Min worker threads (default: CPU count based)\n maxThreads?: number; // Max worker threads (default: CPU count)\n idleTimeout?: number; // Idle timeout in milliseconds for workers\n maxHeapMb?: number; // V8 heap limit per worker (default: 64, env: LIOP_WORKER_MAX_HEAP_MB)\n };\n security?: {\n piiPatterns?: PiiRule[]; // Regex/validator rules for PII detection\n forbiddenKeys?: string[]; // Keys stripped from outgoing responses\n sensitiveKeys?: string[]; // Keys that trigger sensitive query budget\n enableNerScanning?: boolean; // NLP entity detection via compromise (default: false)\n rateLimit?: { // Sliding window rate limiter configuration\n maxPerWindow?: number; // Max calls per window per tool (default: 15)\n globalMaxPerWindow?: number; // Max total calls across all tools (default: 40)\n windowMs?: number; // Window duration in ms (default: 60000)\n };\n };\n taxonomy?: { // Data domain classification\n domain?: string; // e.g., \"finance\", \"healthcare\"\n clearanceTier?: number; // e.g., 3, 5 (strictly numeric)\n executionTypes?: string[]; // e.g., [\"aggregation\", \"analytics\"]\n };\n auth?: LiopAuthConfig; // OAuth 2.1 Hybrid authentication config\n tokenSlug?: string; // Deterministic token resolution slug (e.g., \"BANK\", \"VAULT\")\n allowEnv?: boolean; // Enable safe host environment propagation (default: false)\n budgetStorePath?: string; // Path to a shared JSON file for persistent Query Budget tracking\n }\n)\n```\n\n#### Methods\n\n| Method | Signature | Description |\n| :--------------------------- | :------------------------------------------------- | :---------------------------------------------------------------------------------- |\n| `tool()` | `(name, description, shape, handler, policy?)` | Registers a callable tool with Zod input validation and logic execution policies. |\n| `prompt()` | `(name, description, args, handler)` | Registers a dynamic prompt template. |\n| `resource()` | `(name, uri, description?, mimeType?, content?)` | Registers a readable resource. |\n| `dataDictionary()` | `(schema, name?, uri?, description?)` | Broadcasts a data schema so LLMs can write accurate Logic-Injection-on-Origin code. |\n| `setSandboxData()` | `(records: Record[])` | Injects data into the sandbox as `env.records` for Logic-on-Origin tools. |\n| `enableZeroShotAutonomy()` | `()` | Registers the \"Blind Analyst\" prompt for autonomous code generation. |\n| `callTool()` | `(request: CallToolRequest)` | Invokes a registered tool (used locally or via MCP Bridge). |\n| `listTools()` | `()` | Returns all registered tools. |\n| `listPrompts()` | `()` | Returns all registered prompts. |\n| `getPrompt()` | `(request: GetPromptRequest)` | Returns a specific prompt by name. |\n| `listResources()` | `()` | Returns all registered resources. |\n| `readResource()` | `(uri: string)` | Reads a resource by URI. |\n| `getServerInfo()` | `()` | Returns the server's name and version. |\n| `connectToMesh()` | `()` | Connects to the libp2p Kademlia DHT. |\n| `clearAstCache()` | `()` | Invalidates the Guardian AST logic cache. |\n| `close()` | `()` | Destroys the worker pool and releases threads. |\n\n#### LogicExecutionPolicy Options\n\nWhen registering a tool via `server.tool()`, you can optionally pass a `policy` object to configure security and privacy guards for that specific tool:\n\n```typescript\ninterface LogicExecutionPolicy {\n outputSchema?: z.ZodType; // Validate returned business payload (strict by default)\n enforceAggregationFirst?: boolean | AggregationPolicy; // Block row-level exports & enforce K-Anonymity\n preflightDenyPatterns?: RegExp[]; // Custom regex patterns blocked in static analysis\n dpEpsilon?: number; // Laplace Differential Privacy epsilon (default: 1.0)\n dpSensitivity?: number; // Maximum change per single record (default: 1.0)\n dpSmallDatasetThreshold?: number; // Size threshold below which DP is active (default: 50)\n queryBudgetPerField?: number; // Uniform session query limit per field (legacy compatibility)\n sensitiveKeys?: string[]; // Tool-level fields under the 8-query sensitive budget tier\n budgetStorePath?: string; // Shared path for persistent and concurrent query budgets\n}\n```\n\n### `LiopMcpBridge`\n\nAdapter that connects any `LiopServer` to MCP-compatible clients via JSON-RPC 2.0 over stdio.\n\n```typescript\nconst bridge = new LiopMcpBridge(server);\nawait bridge.connect();\n```\n\n**Supported JSON-RPC methods:**\n\n- `initialize`: Returns server capabilities and info\n- `tools/list`: Lists available tools\n- `tools/call`: Calls a tool (with ZK-Receipt verification)\n- `resources/list`: Lists available resources\n- `resources/read`: Reads a resource\n- `prompts/list`: Lists available prompts\n- `prompts/get`: Gets a specific prompt\n\n---\n\n## Security Architecture\n\n### Defense-in-Depth Architecture\n\n```\n┌───────────────────────────────────────────────────────────┐\n│ Layer 1: Guardian AST (Pre-Execution Static Analysis) │\n│ 14-function WASI allowlist • 128 import cap • Blocks │\n│ require, import(), fs, eval, fetch, __proto__ │\n├───────────────────────────────────────────────────────────┤\n│ Layer 2: WASI Sandbox (V8 Isolate) │\n│ 25 poisoned globals (incl. Date, TypedArrays) • │\n│ CPU Fuel limits • 5s timeout • maxHeapMb (64MB default) │\n│ Object.freeze() on 11 core prototypes • allowEnv allowlist │\n├───────────────────────────────────────────────────────────┤\n│ Layer 3: Taint Analyzer (IFC, Static) │\n│ Acorn AST 3-pass analysis blocks PII side-channels: │\n│ charCodeAt, boolean inference, arithmetic derivation │\n├───────────────────────────────────────────────────────────┤\n│ Layer 4: PII Shield (Egress Filter) │\n│ 4-stage pipeline: exact key → fuzzy key → pattern │\n│ validators (Luhn, IBAN Mod-97) → NER (compromise) • │\n│ Recursive In-Memory Numerical Sanitization (4 decimals) │\n├───────────────────────────────────────────────────────────┤\n│ Layer 5: Aggregation-First Policy │\n│ Blocks raw row export • maxOutputRows (default: 10) • │\n│ Conditional error: detailed (dev) vs opaque (production) │\n├───────────────────────────────────────────────────────────┤\n│ Layer 6: ZK-Receipt (Groth16 BN254 & Replay Mitigation) │\n│ Version 2: 144-byte binary journal + Groth16 curve points │\n│ Version 1: HMAC-SHA256 session commitment (Kyber768) │\n│ output_hash cross-verification • Balanced-brace extractor │\n└───────────────────────────────────────────────────────────┘\n```\n\n### PII Patterns\n\nBuilt-in patterns with multi-layer verification:\n\n```typescript\nimport { PII_PATTERNS, PII_PRESETS } from \"@nekzus/liop/server\";\n\n// Available patterns:\nPII_PATTERNS.EMAIL // RFC 5322 compliant, excludes @example.com/@test.com\nPII_PATTERNS.CREDIT_CARD // Visa/MC/Amex + Luhn algorithm validation\nPII_PATTERNS.IP_ADDRESS // IPv4 with octet range validation (excludes localhost)\nPII_PATTERNS.PHONE // International phone formats with digit-length validation\nPII_PATTERNS.SSN // USA Social Security Number rules (blocks 000 segments)\nPII_PATTERNS.IBAN // ISO 7064 Modulo 97-10 algorithm precision via BigInt\nPII_PATTERNS.PASSPORT_MRZ // Strict 44-character TD3 international passport MRZ string\n\n// Pre-built Regional Presets ready to drop-in via LiopServer(options):\nPII_PRESETS.GLOBAL_STRICT\nPII_PRESETS.US_COMPLIANT\nPII_PRESETS.EU_GDPR\n```\n\n### Forbidden Keys\n\nThe PII Shield automatically strips any key from outgoing responses that matches your configured list:\n\n```typescript\nconst server = new LiopServer(info, {\n security: {\n forbiddenKeys: [\"id\", \"ssn\", \"password\", \"token\", \"secret\", \"email\", \"name\"],\n },\n});\n// Any response containing these keys → instantly blocked with \"Egress Security Violation\"\n```\n\n### Envelope & Cryptographic Unwrapping\n\nTo avoid false positive triggers caused by HMAC-SHA256 ZK-Receipt signatures or transport wrapper frames (such as `{ content: [{ type: \"text\", text: \"...\" }] }`), the PII Shield and Aggregation-First engines scan only the unwrapped business data (via `unwrapForAggregationPolicyScan`). Cryptographic seals and protocol routing structures are isolated and excluded from compliance scans.\n\n### 3-Tier Query Budget (NIST SP 800-226)\n\nTo prevent advanced statistical differentiation or database reconstruction attacks, the SDK implements a tiered, session-based budget engine:\n\n- **Forbidden Tier** (Limit: `3` queries/session): Applied to highly restricted variables like user IDs, passwords, emails, SSNs (configured via `forbiddenKeys`).\n- **Sensitive Tier** (Limit: `8` queries/session): Applied to moderately sensitive variables like account types, medical diagnoses, blood types, financial tickers (configured via `sensitiveKeys`).\n- **Public Tier** (Limit: `25` queries/session): Default budget for non-sensitive public metadata.\n\nIf an injected payload queries a field beyond its budget limit, the preflight static analysis immediately blocks execution.\n\n### K-Anonymity on Small Datasets\n\nWhen operating on high-privacy datasets, if the source records count is **less than 10**, the SDK forces a strict K-Anonymity restriction:\n- Rejects any output that contains nested objects or arrays.\n- Restricts the returned structure to a maximum of **3 scalar keys** (e.g., simple aggregate counts or statistics).\n- Prevents structural data leakage in low-entropy datasets.\n\n### Sandbox Poisoned Globals & Date Workaround\n\nFor maximum host security, the WASI sandbox enforces a poisoned environment that strips dangerous globals and prevents timing side-channels:\n- **Poisoned/Disabled**: `Date` (Date.now, parse, etc. throw an exception to prevent timing analysis), `eval`, `Function`, `setTimeout`, `setInterval`, `Buffer`, `ArrayBuffer`, and all `TypedArrays`.\n- **Date Workaround**: To perform date checks, use lexicographical string comparison on ISO 8601 strings (e.g., `record.date >= \"2026-01-01\"`).\n\n### Recursive In-Memory Numerical Sanitization\n\nTo mitigate timing channels, statistical differentiation, and floats side-channels, the SDK executes a recursive sanitization pipeline before the PII scanner runs:\n- Positive floating-point numbers are recursively rounded to exactly **4 decimal places**.\n- Negative values are safely clamped to **0** (via `sanitizeOutput()`).\n- This operation runs entirely in-memory and recursively on all fields, preserving data structure immutability without expensive and fragile serialization-deserialization cycles.\n\n### Environment Isolation & allowEnv Allowlist\n\nFor robust sandboxing, the WASI execution path isolates host environment variables. Propagation can be enabled explicitly:\n```typescript\nconst server = new LiopServer(info, {\n allowEnv: true\n});\n```\nTo block arbitrary command execution (e.g., Shellshock) and prevent exposure of host credentials, the SDK filters environment variables through a **strict system allowlist** (`getDefaultEnvironment()`):\n- **Windows Allowlist**: `APPDATA`, `HOMEDRIVE`, `HOMEPATH`, `LOCALAPPDATA`, `PATH`, `PROCESSOR_ARCHITECTURE`, `SYSTEMDRIVE`, `SYSTEMROOT`, `TEMP`, `USERNAME`, `USERPROFILE`, `PROGRAMFILES`.\n- **Unix/Linux Allowlist**: `HOME`, `LOGNAME`, `PATH`, `SHELL`, `TERM`, `USER`.\nVariables starting with shell functions `()` are dropped.\n\n### Sovereign Tri-Modal ZK-Receipts & Hardware Attestation\n\nLIOP ZK-Receipts provide cryptographic evidence that a computation was executed honestly under zero-trust bounds. The protocol implements three complementary cryptographic modes:\n- **Mode 0 (`HMAC_LEGACY`, v1)**: Session commitments sealed with the ML-KEM-768 quantum-resistant shared key.\n- **Mode 2 (`GROTH16`, v2)**: Compact Zero-Knowledge SNARK proofs over the BN254 pairing-friendly elliptic curve packing a 144-byte binary journal (~252 bytes total).\n- **Mode 3 (`GROTH16_PQC_HYBRID`, v2.1)**: Dual-layer receipts combining Groth16 BN254 mathematical proofs with an ML-DSA-65 post-quantum digital signature conforming to NIST FIPS 204 (~5.6 KB total).\n\n- **144-Byte Binary Journal Layout**:\n - `guest_image_id` (32 bytes): Sovereign enclave guest runtime image identifier\n - `logic_digest` (32 bytes): SHA-256 fingerprint of the executed JavaScript/WASM logic\n - `dataset_digest` (32 bytes): SHA-256 fingerprint of the origin dataset at execution time\n - `output_digest` (32 bytes): SHA-256 fingerprint of the sanitized computation result\n - `fuel_consumed` (8 bytes uint64 BE): Quantized instruction-level AST fuel units consumed\n - `execution_timestamp` (8 bytes uint64 BE): Epoch timestamp in milliseconds\n- **Tampering & Replay Mitigation**: The client computes the local SHA-256 hash of the received output and asserts strict equality with `journal.outputDigest`. Any modified bit in either the journal, curve proof, or post-quantum signature causes immediate rejection.\n- **Enclave Policy Invariant (`ZK_BLOCKING`)**: Tier 1 Sovereign Enclaves configure `zkMode: \"required\"`, rejecting queries if a valid Groth16 proof cannot be synthesized or if mock proofs are supplied. When `pqcSign: true` is configured, the enclave emits a Version 2.1 hybrid receipt co-signed with ML-DSA-65.\n\n```typescript\nimport { LiopServer } from \"@nekzus/liop/server\";\nimport { LiopVerifier, verifyTeeAttestationDetailed } from \"@nekzus/liop\";\n\n// 1. Enclave configuration with ZK_BLOCKING and PQC signing\nconst server = new LiopServer({ name: \"bank-enclave\", version: \"1.0.0\" });\nserver.tool(\n \"calculate_payroll_aggregate\",\n \"Aggregates payroll without egressing employee identities\",\n { payload: z.string() },\n async () => ({ content: [{ type: \"text\", text: \"ok\" }] }),\n {\n zkMode: \"required\", // Enforces Groth16 proof generation (ZK_BLOCKING)\n pqcSign: true, // Enables ML-DSA-65 digital signature (Receipt v2.1)\n circuitName: \"sum\",\n }\n);\n\n// 2. Client verification via LiopVerifier\nconst verifier = new LiopVerifier();\nconst isValid = await verifier.verifyZkReceipt(\n Buffer.from(logicPayload),\n remoteImageIdHex,\n rawReceiptBuffer,\n { zkPolicy: \"required\" }\n);\n\n// 3. Pre-flight Hardware TEE Attestation (AMD SEV-SNP / AWS Nitro Enclaves)\nconst teeStatus = await verifyTeeAttestationDetailed(\n attestationBytes,\n expectedNonce,\n { requireHardwareSigned: true }\n);\n```\n\n---\n\n## Logic-Injection-on-Origin Flow\n\nThe following shows a complete Logic-Injection-on-Origin execution cycle (handled internally by the SDK):\n\n```\n1. LLM generates JavaScript analysis code wrapped in @LIOP / @END boundaries\n2. LiopServer receives the payload via tools/call (JSON-RPC or direct)\n3. Guardian AST inspects for sandbox escapes (pre-execution heuristic analysis)\n4. Code executes inside a V8 isolate with CPU fuel limits (no Node.js globals)\n5. Taint Analyzer blocks PII side-channel derivation (charCodeAt, boolean inference)\n6. PII Shield scans output for forbidden data and keys\n7. ZK-Receipt generated (Tri-modal: HMAC v1, Groth16 v2, or Groth16 + ML-DSA-65 v2.1)\n8. Result + receipt returned to the LLM (raw data never exposed)\n```\n\n### Data Dictionary & Zero-Shot Autonomy\n\nThe Data Dictionary tells the LLM exactly what fields exist in `env.records`, enabling accurate code generation without seeing the actual data:\n\n```typescript\nserver.dataDictionary({\n id: \"string (Anonymized patient identifier, strictly PII)\",\n age: \"number (Patient age in years)\",\n condition: \"string (Healthy, Hypertension, Diabetes Type 1, Diabetes Type 2, Heart Disease, Asthma)\",\n riskScore: \"number (Float 0.0 to 1.0)\",\n lastVisit: \"string (ISO 8601 date)\",\n});\n\nserver.enableZeroShotAutonomy(); // Registers the \"Blind Analyst\" prompt\n```\n\n---\n\n## Worker Pool (Multi-Core Scaling)\n\nNode.js is single-threaded. Heavy operations like Kyber768 decryption, AES-GCM authentication, AST validation, and V8 sandbox instantiation would block the event loop in a standard setup.\n\nThis SDK dispatches all heavy computation to OS-level threads via [`piscina`](https://github.com/piscinajs/piscina), achieving Rust-like concurrency. On server or verifier initialization, background warmup tasks are automatically dispatched to pre-warm the pool workers, eliminating V8/WASI cold-start overhead (~820k fuel units) for subsequent calls:\n\n```typescript\n// Automatic, no configuration needed\n// When a Logic-Injection-on-Origin payload is received:\n// 1. Main thread receives JSON-RPC request\n// 2. Worker thread: AST inspection + PQC decryption + Sandbox execution\n// 3. Main thread: Returns result (non-blocking)\n\n// Cleanup on shutdown:\nawait server.close();\n```\n\n---\n\n## Post-Quantum Cryptography\n\nTransport-layer security using ML-KEM-768 (Kyber) for key encapsulation and AES-256-GCM for symmetric encryption:\n\n```typescript\nimport { LiopClient } from \"@nekzus/liop/client\";\n\nconst client = new LiopClient();\nawait client.connect();\n\n// Discover remote tools via Kademlia DHT\nconst tools = await client.discoverTools();\n\n// Call a tool with PQC-encrypted WASM payload\n// Kyber768 key encapsulation + AES-256-GCM happens automatically\nconst result = await client.callTool(request, wasmPayload, serverPublicKey);\n\n// Verify the ZK-Receipt from the remote server\nconst isValid = await client.verifyZkReceipt(payload, imageId, receipt);\n```\n\n---\n\n## P2P Mesh Network\n\nDecentralized tool discovery via Kademlia DHT:\n\n```typescript\nawait server.connectToMesh();\n// Server is now discoverable on the libp2p network\n// Transports: TCP + WebSocket\n// Multiplexing: Yamux\n// Encryption: Noise Protocol\n```\n\n---\n\n---\n\n## Interactive Web Playground (`:16000` prod / `:14000` dev)\n\nThe SDK includes a real-time developer interface to test Logic-Injection-on-Origin, trace post-quantum handshakes, evaluate AST fuel consumption, and inspect cryptographic proofs:\n\n```bash\n# 1. Launch the full 10-node production audit mesh with traffic shaping (http://localhost:16000)\npnpm run audit:prod:start\n\n# Run the 12-suite automated production audit against the mesh (64 tests)\npnpm run audit:prod:run\n\n# Teardown and cleanup production containers\npnpm run audit:prod:clean\n\n# 2. Alternatively, launch the lightweight 5-node demo (http://localhost:14000)\npnpm run demo:start\n```\n\nNavigate to **`http://localhost:16000`** in your browser:\n\n* **Live 7-Phase Streaming:** Visualizes Bootstrap, DHT Discovery, ML-KEM-768 Handshake, AES-256-GCM Sealing, WASI Sandbox Execution, ZK-Receipt Verification, and Output Aggregation via real-time Server-Sent Events (SSE).\n* **Tri-Tab Results Panel:** Switch between `Aggregated Output` (sanitized JSON), `Fuel & Telemetry` (WASI fuel metering, token economy comparison banner), and `Crypto Proofs` (ImageID, Dataset Hash, and HMAC-SHA256 signature with instant copy).\n* **Token Economy Dashboard:** Live comparison showing **98.9% to 99.6% token reduction** and **99.6% network bandwidth savings** over traditional MCP context-pulling.\n* **REST Telemetry Endpoint:** Query session analytics programmatically at `GET http://localhost:16000/api/telemetry`.\n* **Built-in Scenario Presets:** Ready-to-run micro-modules for High-Frequency Trading (HFT Level 2 order books), Banking transaction analysis, Medical Vault HIPAA records, and Edge IoT industrial sensor telemetry.\n* **Dual Dark Modes:** Toggle between Obsidian OLED (`#000000`) and Slate Navy (`#0f172a`) interfaces.\n\n---\n\n## Token Economy & Telemetry\n\nThe SDK ships with a zero-runtime-dependency **`o200k_base`** BPE token estimation and telemetry engine:\n\n```typescript\nimport {\n createTokenEstimator,\n createSyncTokenEstimator,\n TokenTelemetryEngine,\n LiopOTelBridge\n} from \"@nekzus/liop\";\n\n// 1. Exact BPE Token Counting (Bundled inlined o200k_base vocab, zero network/disk lag)\nconst estimator = createSyncTokenEstimator();\nconst tokens = estimator.countTokens(\"Hello world! Logic-Injection-on-Origin\"); // 12\n\n// 2. Operation-Level Token Telemetry\nconst telemetry = TokenTelemetryEngine.getInstance();\ntelemetry.record({\n type: \"tool_call\",\n method: \"tools/call\",\n toolName: \"Analyze_HFT_Market_Data\",\n estimatedInputTokens: 120,\n estimatedOutputTokens: 42\n});\n\n// 3. OpenTelemetry gen_ai.* Bridge\n// Automatically exports gen_ai.client.token.usage and gen_ai.client.operation.duration histograms\n```\n\n---\n\n## Testing & Quality\n\nThis package is continuously tested across multiple platforms and Node.js versions via CI/CD:\n\n- **490+ tests** spanning unit, integration, conformance, adversarial, and live Docker mesh suites\n- **Multi-OS matrix:** Ubuntu, Windows, macOS\n- **Node.js versions:** 20.x, 22.x\n- **Code quality:** Enforced by [Biome.js](https://biomejs.dev/) (linting + formatting)\n- **Security:** Verified 6-layer defense-in-depth architecture (see [Security Architecture](https://nekzus-32.mintlify.app/typescript-sdk/security))\n\n> To run tests locally or contribute, clone the [repository](https://github.com/Nekzus/LIOP) and follow the [Contributing Guide](https://github.com/Nekzus/LIOP/blob/main/CONTRIBUTING.md).\n\n## Security Auditing & Supply Chain\n\nThis repository is integrated with [Socket.dev](https://socket.dev) to continuously monitor and secure the software supply chain against malicious packages, hidden telemetry, and dependency vulnerabilities.\n\nYou can run security audits and check package health scores directly from the monorepo root:\n\n- **Scan Monorepo Dependencies:** `pnpm socket:scan` (performs a security scan and generates a report)\n- **Check SDK Security Score:** `pnpm socket:score` (shows the detailed package score for the SDK in Markdown format)\n- **Fix Vulnerabilities:** `pnpm socket:fix` (automatically remediates known CVEs in package.json)\n\nThe codebase undergoes regular dependencies audits. As of June 2026, the SDK is verified to be 100% free of orphan packages and dead dependencies, ensuring a minimal deployment footprint.\n\n---\n\n## Related\n\n- [LIOP Documentation](https://nekzus-32.mintlify.app/): Full conceptual and API documentation\n- [LIOP Specification](https://github.com/Nekzus/LIOP/blob/main/protocol/SPECIFICATION.md): Technical specification\n- [LIOP Manifesto](https://github.com/Nekzus/LIOP/blob/main/MANIFESTO.md): Project philosophy\n- [Contributing Guide](https://github.com/Nekzus/LIOP/blob/main/CONTRIBUTING.md): How to contribute\n- [Rust Mesh Node](https://github.com/Nekzus/LIOP/tree/main/servers/liop-node): Native high-performance backend\n- [LIOP CLI](https://github.com/Nekzus/LIOP/tree/main/tools/liop-cli): Developer diagnostics\n\n---\n\n## License\n\nLicensed under the [Apache License, Version 2.0](https://github.com/Nekzus/LIOP/blob/main/LICENSE) (the \"License\"). You may not use this file except in compliance with the License. See [NOTICE](https://github.com/Nekzus/LIOP/blob/main/NOTICE) and [TRADEMARKS.md](https://github.com/Nekzus/LIOP/blob/main/TRADEMARKS.md) for attribution and trademark details.\n\nCopyright 2026 [Nekzus Solutions](https://github.com/Nekzus) and contributors.\n","readmeFilename":""}
![\"Logic-Injection-on-Origin](\"https://raw.githubusercontent.com/Nekzus/LIOP/main/docs/logo/dark.svg\"){kind=logo}
\n ![\"Github](\"https://github.com/Nekzus/LIOP/actions/workflows/ci.yml/badge.svg?event=push\"){kind=icon}
\n ![\"npm](\"https://img.shields.io/npm/v/@nekzus/liop.svg\")
\n ![\"npm](\"https://img.shields.io/npm/dm/@nekzus/liop.svg\")
\n ![\"License\"](\"https://img.shields.io/badge/License-Apache_2.0-blue.svg\"){kind=icon}
\n ![\"Docs\"](\"https://img.shields.io/badge/docs-mintlify-0D9373?style=flat\"){kind=icon}
![\"Ask](\"https://deepwiki.com/badge.svg\"){kind=icon}
\n