> ## Documentation Index
> Fetch the complete documentation index at: https://nekzus-32.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Server Concepts
> Understanding how an LIOP Data Node protects resources and executes logic
In the Logic-Injection-on-Origin Protocol (LIOP), a "Server" is historically termed a **Data Node**. Unlike a traditional web server that passively serves JSON responses upon request, an LIOP Server is an active Execution Engine. Its primary duty is to receive foreign logic, strictly isolate it, and allow it to operate on local data.
To accomplish this securely, LIOP Servers expose three foundational primitives: **Modules**, **Capabilities**, and **Watchdogs**.
## 1. WebAssembly Modules (The Logic)
In legacy protocols (like MCP), servers define static "Tools" (e.g., `calculate_sum`, `read_log`), and the AI instructs the server to execute them.
In LIOP, the Server does not need to pre-program endless tools. Instead, it exposes an **Execution Interface**.
The Agent sends a completely dynamic **WebAssembly Module (`.wasm`)** containing its own novel logic.
### How it works:
* The Agent complies its reasoning (e.g., "Find all error logs containing IP 192.168.1.1 and group them by timestamp") into a tiny binary cross-platform WASM blob.
* The LIOP Server receives this blob via gRPC.
* Instead of executing it natively, the Server spins up an ephemeral **WASI Sandbox** (using Bytecode Alliance's `Wasmtime`) and injects the WASM module into it.
* **Extreme Scalability:** Both the Rust backend and the TS SDK leverage advanced threading models (Native OS Threads and Node.js `piscina` Worker Pools) to process thousands of these sandboxes concurrently without blocking the Main Event Loop.
This allows infinite capabilities without requiring the server administrator to constantly write new tool endpoints.
## 2. Capabilities (The Resources)
If the server executes arbitrary code via WASM, how is it secure? Through **Capabilities-Based Security**.
Capabilities are the LIOP equivalent of MCP "Resources", but radically more secure. By default, a running WASM module in LIOP has **absolute zero access** to anything:
* No file system read/write.
* No network socket access.
* No environment variables.
* No system clock.
### Granting Access
When an Agent sends a Module, it must specify the Capabilities it requires to function. The Server verifies these requests against its configured manifest. If approved, the Server *dynamically maps* specific file descriptors directly into the Sandbox memory space.
For example, a Capability might be: `READ_ONLY_ACCESS: /var/logs/nginx/`.
The WASM module can now read the nginx logs at blinding speed, but if the malicious logic attempts to read `/etc/passwd`, the Sandboxing Engine will trigger an immediate, uncatchable `WASI Trap`, instantly terminating the agent's logic.
## 3. Watchdogs (Persistent Asynchronous Events)
One of LIOP's most powerful features is **Watchdogs**, superseding the concept of simple prompts or manual polling.
AI applications often need to monitor a server (e.g., "Tell me when memory usage exceeds 90%"). In HTTP/REST or JSON-RPC, the AI must constantly send manual requests every 5 seconds, wasting massive network bandwidth and LLM tokens.
**LIOP push architecture solves this:**
* The Agent sends a Watchdog WASM Module to the Data Node.
* The Server parses it and lets it "sleep" perpetually in a passive, low-resource background thread.
* The WASM module connects locally to the system streams.
* The moment the condition is met (Memory > 90%), the WASM module wakes up and pushes an asynchronous event straight down the permanently open multiplexed **QUIC connection** back to the Agent.
This creates true real-time autonomous systems with zero polling overhead.
## 4. Trust & Evidence (Enterprise TEE Execution Sandbox)
In Tier-0 Enterprise Environments, the Logic-Injection-on-Origin Server fundamentally evolves past standard OS-level sandboxing. The server provides Mathematical and Physical evidence utilizing a **TEE (Trusted Execution Environment) Sandbox**.
The TEE execution pipeline executes malicious or foreign logic under zero-trust assumptions through the following isolated modules:
#### 1. Host Bounds & Checks (Guardian AST & Egress Filter)
Before any logic touches the execution engine, the outermost Host Server interceptor unlocks the `.wasm` payload from its `Kyber768` / `AES-256-GCM` transport encryption. Instantly, the **Guardian AST Sentinel** parses the WebAssembly Abstract Syntax Tree. If it detects attempted imports from arbitrary Host functions rather than authorized `wasi_snapshot_preview1` bounds, the payload is purged before entry.
Upon successful execution, a **Layer 3 Egress Filter** mathematically analyzes the outgoing buffer to prevent PII or sensitive schema data exfiltration prior to transmission.
#### 2. Hardware Isolated Enclave (TEE)
The core computation does not run in the Host OS. It is pushed into a physical Hardware Enclave (such as **AWS Nitro Enclaves** or **Intel SGX**). This ensures *Blind Computation*: the Host’s RAM is hardware-encrypted, meaning not even the Server Administrator or Cloud Provider can dump the memory to steal the Agent's reasoning.
#### 3. Wasmtime Engine & Fuel Monitor
Inside the TEE, the `Wasmtime` engine boots the WASI context. Since WebAssembly is Turing Complete, it could theoretically execute an infinite loop to starve the server. The **Fuel Monitor** defends against this by enforcing `.consume_fuel()`. Every operation deducts "fuel" limits; if exhausted, the engine unconditionally kills the execution thread, repelling DoS bombs.
#### 4. ZK Prover (Mathematical Certainty)
When the `.wasm` finishes outputting data, the result passes to the **Zero-Knowledge Prover** (e.g., `RISC Zero` integration). This module generates a mathematical *Receipt* (consisting of a Journal and a cryptographic Seal). The returned packet proves unconditionally to the Agent that the specific logic payload executed flawlessly, and the output was not tampered with by the execution Node.
## 5. TypeScript Server & MCP Bridge (The SDK Node)
While the Rust Dataplane dominates heavy WASI Sandboxing and Mathematical Evidence, the LIOP Ecosystem also provides a lightweight, pure-TypeScript Server implementation (`@nekzus/liop`).
This Server acts primarily as a backward-compatibility layer and local endpoint for Agent logic.
### How the Bridge handles Legacy MCP Clients:
1. **JSON-RPC Interception**: Legacy tools (like older MCP Clients) dispatch standard text-heavy `tools/call` JSON-RPC 2.0 requests over traditional network ports.
2. **LiopMcpBridge Adapter**: The SDK intercepts these primitive payloads and translates them into an internalized `CallToolRequest`. It also flawlessly exposes registered `resources/list` and `resources/read` endpoints, enabling *Zero-Shot Self-Discovery* of Data Schemas for generic LLMs.
3. **LiopServer Zod Validation**: Before any logic touches the Node.js Main Thread, the `LiopServer` imposes strict Zod schema runtime validations ensuring structural integrity.
4. **Native Node.js Execution**: The registered Tool Handler executes locally (using standard Node.js/TypeScript code) rather than isolating itself in a sandboxed WebAssembly boundary.
5. **JSON-RPC Response**: The finding returns seamlessly down the pipeline formatted as a legacy `result` block.
This guarantees that developers can immediately adopt `@nekzus/liop` and serve their existing Tools into the LIOP ecosystem with **Zero-Code modifications**, slowly transitioning towards full *WASM Logic-on-Origin* payloads when required.
## 6. Advanced Security & Data Dictionary
To ensure the highest level of Zero-Shot Autonomy (where the AI makes its own plans), LIOP Servers must provide metadata about their internal structures.
### Data Dictionary (Anti-Hallucination)
When an Agent executes foreign logic, it might "hallucinate" fields that don't exist (e.g., trying to access `gender` in a database that only has `age`). To prevent this, developers should use the `dataDictionary` method:
```typescript theme={null}
server.dataDictionary({
id: "string (Anonymized PII)",
age: "number",
condition: "string (Healthy, Hypertension...)"
});
```
The SDK's **Reactive Sync** engine will automatically inject this schema directly into the `liop_blind_analyst` **System Prompt**. By explicitly detailing the available fields, LIOP forces the LLM to adopt a **Strict Schema Adherence** policy, drastically reducing hallucination risks during logic generation.
### Sandbox Data Injection
While `dataDictionary` teaches the *Agent* what the data looks like, you must actually inject the real data into the *Execution Sandbox* for the WASM/JS logic to process.
Use the `setSandboxData` method to load your context (e.g., from a database or JSON file) into the server's memory:
```typescript theme={null}
const records = await db.fetchPatients();
server.setSandboxData(records); // Exposed as 'env.records' inside the Sandbox
```
This guarantees a strict separation of concerns: The Schema goes to the AI, but the Raw Data stays cryptographically trapped inside the execution Node.
### PII Forbidden Keys
You can dynamically restrict specific fields from ever leaving the server, regardless of the logic's intent. Pass the `forbiddenKeys` array during server instantiation:
```typescript theme={null}
const server = new LiopServer({
security: {
forbiddenKeys: ["id", "ssn", "password", "email"]
}
});
```
The **O(1) Egress Filter** will use a high-performance memory `Set` to scan every return object and block any key matching these terms, even if they are nested deep within a JSON structure.
### Sensitive Keys & Tiered Budget (NIST SP 800-226)
To protect domain-critical fields (like bank account balances or medical diagnoses) without outright blocking them at egress like forbidden keys, you can classify them as **Sensitive Keys**.
LIOP automatically enforces a **3-Tier Query Budget** session limit per client:
* **Forbidden Tier (3 queries/session)**: Applies to all fields declared in `forbiddenKeys`.
* **Sensitive Tier (8 queries/session)**: Applies to all fields declared in `sensitiveKeys`.
* **Public Tier (25 queries/session)**: Applies to any other field accessed.
You can declare sensitive keys globally at the server level, or locally at the tool registration level:
#### Global Server Configuration
```typescript theme={null}
const server = new LiopServer(
{ name: "financial-vault", version: "1.0.0" },
{
security: {
forbiddenKeys: ["ssn"],
sensitiveKeys: ["balance"] // Global sensitive keys
}
}
);
```
#### Tool-Level Configuration
You can add extra sensitive keys for a specific tool. The server will dynamically merge these with the global list:
```typescript theme={null}
server.tool(
"analyze_transactions",
"Analyzes account transactions",
{ payload: z.string() },
async (args) => { ... },
{
enforceAggregationFirst: true,
sensitiveKeys: ["accountType"] // Merged with global 'balance' key
}
);
```
#### Legacy Uniform Budget
If you need a backward-compatible uniform limit across all fields instead of tiered budgets, define `queryBudgetPerField` on the tool options:
```typescript theme={null}
server.tool(
"legacy_analyzer",
"Analyzes legacy records",
{ payload: z.string() },
async (args) => { ... },
{
enforceAggregationFirst: true,
queryBudgetPerField: 5 // Uniform limit: exactly 5 queries for any field
}
);
```
#### Persistent Budget Store
To persist and share query budgets across server restarts and multiple running processes, configure the `budgetStorePath` property. This can be defined globally in the `LiopServer` constructor, or locally inside a tool-level policy:
```typescript theme={null}
import path from "path";
// 1. Global Persistence Configuration
const server = new LiopServer(
{ name: "financial-vault", version: "1.0.0" },
{
budgetStorePath: path.join(__dirname, "../data/query-budgets.json"),
security: {
sensitiveKeys: ["balance"]
}
}
);
// 2. Tool-Level Persistence Override
server.tool(
"analyze_records",
"Analyzes database records securely",
{ payload: z.string() },
async (args) => { /* ... */ },
{
enforceAggregationFirst: true,
budgetStorePath: path.join(__dirname, "../data/tool-specific-budgets.json")
}
);
```
##### Directory & Database Autogeneration
* **Automatic Directory Creation**: The SDK automatically detects if parent folders in `budgetStorePath` do not exist and creates them recursively (via `fs.mkdirSync(..., { recursive: true })`) during first write.
* **Hierarchical JSON Structure**: The file initializes automatically as a JSON database structured in a 3-level nested schema tracking `clientId` (or `agentDid`), `toolName`, and the accessed `field` counter:
```json theme={null}
{
"mcp-client": {
"analyze_records": {
"ssn": 2,
"balance": 5
}
}
}
```
Atomic locking (`.lock`) is managed automatically under the hood to synchronize concurrent writes. If file storage writes fail, it silently falls back to session-isolated in-memory budget tracking.
##### Client Identity Binding & Budget Resets (Anti-Bypass)
* **Persistent Identity Anchoring**: The budget limits are bound to the client's persistent cryptographic identity (`agentDid` derived from their Ed25519 PeerID or `clientId` from OAuth 2.1 JSON Web Tokens) rather than ephemeral transport tokens (such as gRPC `session_token`). This prevents malicious clients from bypassing their query budgets by simply reconnecting or negotiating new gRPC intents.
* **Budget Resets via PQC Session Rotation**: For legitimate clients or environments without file-backed persistence, the session budget can be reset by initiating a new ephemeral ML-KEM-768 (Kyber) handshake, which rotates the Post-Quantum session keys. If a budget is exhausted and no persistence is configured, the SDK returns a clear error: `Rotate PQC session to reset budget`.
### Differential Privacy Policy
For datasets below the `dpSmallDatasetThreshold` (default: 50 records), the server automatically applies calibrated Laplace noise to all numeric outputs. Configure the privacy profile at the tool-level policy when registering a tool:
```typescript theme={null}
server.tool(
"analyze_records",
"Analyzes database records securely",
{ payload: z.string() },
async (args) => {
// handler implementation
},
{
enforceAggregationFirst: true,
dpEpsilon: 2.0, // Privacy budget (higher = less noise, more utility)
dpSensitivity: 1000.0, // Max change per record for SUM fields
dpSmallDatasetThreshold: 50 // Apply noise only when dataset size < this threshold
}
);
```
The engine automatically derives **per-field sensitivity** based on the output key name:
* **Count keys** (`count`, `length`, `size`, `num`): sensitivity = 1
* **Average keys** (`avg`, `mean`): sensitivity = `dpSensitivity / recordCount`
* **Sum/other keys**: sensitivity = `dpSensitivity`
**Industry Reference for ε calibration:**
| Domain | ε | Reference |
| :----------------- | :-------- | :----------------------- |
| Healthcare (HIPAA) | `2.0` | Apple Health Data |
| Finance (SOX/PCI) | `2.0` | DOJ PET Guidelines |
| Public Data | `4.0–8.0` | US Census, Google RAPPOR |
See [Zero-Trust Security § Differential Privacy](/concepts/zero-trust#7-differential-privacy-engine-laplace-mechanism) for the full technical deep-dive.
### Dynamic Return Structure (Native Auto-i18n) \[PLANNED]
LIOP introduces an architectural pattern where cross-border language translation friction is non-existent. This feature is on the roadmap.
When a Data Node registers its capabilities, it intrinsically embeds a structural directive into the payload definition (`DYNAMIC RETURN STRUCTURE`). This forces the executing agent to output JSON schemas using keys mathematically mapped to the **exact language spoken by the user on the initial prompt.**
* If the user queries *"¿Cuántos pacientes tienen hipertensión?"*, the Node naturally receives a response matching native Spanish taxonomy (e.g., `{"cantidad": 25, "edad_promedio": 45}`).
* This entirely eliminates the need for heavyweight frontend internationalization (i18n) libraries, dropping the cognitive load of data parsing right at the Origin without hallucination risks.