Security Architecture

Defense-in-depth layers, cryptographic pipelines, and data protection mechanisms in the LIOP TypeScript SDK

The LIOP TypeScript SDK enforces a defense-in-depth security model composed of six independent layers. Each layer addresses a distinct threat surface (from static code analysis to post-execution data filtering), ensuring that no single point of failure can compromise the system.

Features marked with [ROADMAP] are architecturally defined but not yet available in the current release.

---

Security Layers Overview

Layer	Purpose	Timing
Guardian AST	Blocks unauthorized WASM imports before execution	Pre-compile
WASI Sandbox	Isolates runtime with 25 poisoned globals, prototype freezing, and CPU fuel limits	Execution
IFC Taint Analyzer	Static information flow control preventing PII side-channel and computed-key derivations	Pre-flight
PII Shield	Prevents data leakage with algorithmic validators and NER detection	Post-execution
Aggregation Policy	Enforces output cardinality limits on row-level data (Aggregation-First)	Post-execution
ZK-Receipt	Tri-modal proof of honest computation: HMAC (v1), Groth16 BN254 (v2), and ML-DSA-65 PQC Hybrid (v2.1)	Post-execution

---

Layer 1: Guardian AST

The Guardian AST module performs a synchronous static inspection of WebAssembly modules before compilation. It leverages WebAssembly.Module.imports() to enumerate all host-bound import requests and validate them against a strict allowlist.

WASI Function Allowlist

Only the following 14 wasi_snapshot_preview1 functions are permitted:

fd_write, fd_read, fd_close, fd_seek, fd_prestat_get, fd_prestat_dir_name,
fd_fdstat_get, environ_get, environ_sizes_get, args_get, args_sizes_get,
clock_time_get, proc_exit, random_get

Any import outside this set triggers an immediate SandboxViolation error. A hard cap of 128 total imports per module prevents resource exhaustion via logic-bomb payloads.

The Guardian AST inspects WASM module imports, not JavaScript globals. Blocking of dangerous JS APIs (require, eval, fetch) is handled by Layer 2 through global poisoning.

---

Layer 2: WASI Sandbox

The SDK provides a dual-path execution engine that routes payloads to the appropriate isolation mechanism:

Path	Technology	Use Case
Native WASM	node:wasi (preview1)	Pre-compiled .wasm binaries
V8 Isolate	node:vm + hardened context	Dynamic JavaScript payloads

V8 Global Poisoning

Twenty-five attack vectors are neutralized by setting each to undefined and sealing them as non-writable:

const POISONED_GLOBALS = [
  // Core Node.js / Runtime APIs
  "require", "process", "global", "globalThis",
  "Buffer", "setTimeout", "setInterval", "setImmediate",
  "queueMicrotask", "eval", "Function", "SharedArrayBuffer",
  // Timing Side-Channel Defense
  "Date", "performance", "Intl",
  // Heap Bomb / Binary Exploitation Defense
  "ArrayBuffer", "Uint8Array", "Int8Array",
  "Uint16Array", "Int16Array", "Uint32Array", "Int32Array",
  "Float32Array", "Float64Array",
  "BigInt64Array", "BigUint64Array", "DataView"
];

Timing API poisoning (Date, performance, Intl, SharedArrayBuffer) prevents injected logic from performing high-resolution side-channel analysis to infer dataset cardinality or record values. TypedArray poisoning prevents heap bomb DoS attacks that allocate massive binary buffers to crash the worker process.

After assignment, the entire sandbox context is recursively frozen via Object.freeze(), preventing any runtime modification of the execution environment.

Prototype Pollution Defense

Inside the sandbox IIFE, eleven core JavaScript prototypes are frozen before user code executes to satisfy strict PCI-DSS and HIPAA logical isolation requirements:

Object.freeze(Object.prototype);
Object.freeze(Array.prototype);
Object.freeze(String.prototype);
Object.freeze(Number.prototype);
Object.freeze(Boolean.prototype);
Object.freeze(RegExp.prototype);
Object.freeze(Map.prototype);
Object.freeze(Set.prototype);
Object.freeze(Promise.prototype);
Object.freeze(Object.getPrototypeOf(function(){})); // Resolves and freezes Function.prototype
Object.freeze(Error.prototype);

Because Function and other global namespaces are explicitly poisoned (set to undefined) in the global scope to eliminate execution escapes, Function.prototype cannot be frozen directly. The SDK resolves it dynamically via Object.getPrototypeOf(function(){}) to apply the freeze.

The entire guest execution is wrapped inside a block containing "use strict";. Consequently, any attempt by the injected code to write or assign properties to these frozen prototypes (e.g., Object.prototype.polluted = "leak") will immediately throw a hard TypeError, halting execution and preventing prototype pollution vulnerabilities.

CPU Fuel Limits

Parameter	Value
Execution timeout	5,000 ms (hard kill)
Fuel limit	1,000,000 units
Working directory	Ephemeral (deleted on teardown)

Microtask Escape Defense

In V8 context execution, microtasks (like resolved Promises) scheduled during evaluation can sometimes outlive the script execution boundary or bypass simple synchronous limits. To prevent this, the SDK enforces:

const context = vm.createContext(sandboxEnv, {
  name: "LIOP Isolate",
  origin: "liop://sandbox",
  microtaskMode: "afterEvaluate",
});

The microtaskMode: 'afterEvaluate' option instructs Node.js to immediately run all microtasks queued by the script before returning. This guarantees that no async logic survives outside the 5,000 ms sandbox execution limit, neutralizing potential asynchronous logic-bomb bypasses.

Safe Host Environment Variables (allowEnv)

By default, the WASI sandbox completely isolates the guest environment. If your business logic strictly requires environment variables, you can enable safe host environment propagation:

const server = new LiopServer(info, {
  // In WasiSandbox options
  allowEnv: true
});

To prevent shell injection exploits (such as Shellshock) and avoid silent leaks of sensitive host credentials (such as AWS_SECRET_ACCESS_KEY or NPM_TOKEN), the SDK filters environment variables through a strict safe allowlist via getDefaultEnvironment():

• Windows Host Allowlist: APPDATA, HOMEDRIVE, HOMEPATH, LOCALAPPDATA, PATH, PROCESSOR_ARCHITECTURE, SYSTEMDRIVE, SYSTEMROOT, TEMP, USERNAME, USERPROFILE, PROGRAMFILES.
• Unix/Linux Host Allowlist: HOME, LOGNAME, PATH, SHELL, TERM, USER.

Any environment variable starting with shell function definitions () is immediately rejected to prevent remote code execution vectors.

Post-Execution Cleanup

The sandbox destroys all temporary artifacts after every execution cycle:

await fs.rm(workingDir, { recursive: true, force: true });

---

Layer 3: Information Flow Control (IFC Taint Analyzer)

The IFC Taint Analyzer (TaintAnalyzer) inspects the JavaScript Abstract Syntax Tree (AST) generated by Acorn before any guest code enters the V8 isolate. It tracks the flow of sensitive data fields and blocks attempts to leak confidential information through indirect computational channels.

Attack Vectors Mitigated

Attack Vector	Mechanism	Defense
Boolean Inference	if (record.balance > 1000000) side-channel branches	Static AST path tracking prevents conditional deriving of PII
Character Derivation	record.ssn.charCodeAt(0) ASCII leakage	Member access on sensitive fields marks derived expressions as tainted
Aliased Collections	const accounts = env.records; accounts.filter(...)	Iterative source detection identifies alias chains and binds record variables
Dynamic Computed Keys	acc[record.accountHolder] = record.balance in .reduce()	Marks objects receiving tainted keys or values as contaminated, halting preflight
Object Literal Spreads	{ [record.name]: record.id, ...rest }	Computed property expressions evaluate key taint and block dynamic dictionary exports

Dynamic Computed Key Defense

Adversaries attempting to bypass Layer 5 (Aggregation-First) by transforming datasets into dynamic dictionary mappings (e.g., using reduce to create { [name]: balance }) are intercepted statically at preflight:

// Adversarial Payload Blocked at Preflight:
const accounts = env.records;
const top5 = accounts.slice(0, 5);
return top5.reduce((acc, a) => {
  acc[a.accountHolder] = a.balance; // BLOCKED: acc marked as PII-derived
  return acc;
}, {});

When propagateTaint detects an assignment to a MemberExpression where the property expression is computed and tainted (isExpressionTainted(member.property)), the enclosing container is permanently marked as tainted. Any subsequent ReturnStatement returning this container triggers a fail-closed rejection:

Preflight policy rejected: PII side-channel detected: output contains values derived from restricted fields. Operation: variable 'acc' is PII-derived

---

Layer 4: PII Egress Shield

The PII Scanner intercepts all sandbox output before results are returned to the caller. Starting from v3, it operates a four-stage detection pipeline that combines structural analysis, pattern matching, and natural language processing. Each stage is independent: the system blocks data if any stage detects a violation.

Detection Pipeline

Stage	Mechanism	Purpose
1. Exact Key Match	Set<string>.has() (O(1))	Blocks well-known PII field names (ssn, email, password)
2. Fuzzy Key Match	Boundary regex + substring	Catches aliases and variations (patientId, names, fullName)
3. Pattern Validators	Regex + algorithmic checks	Detects PII values regardless of key naming (emails, credit cards, IBANs)
4. NER Content Scan	compromise NLP engine	Identifies person names, places, and organizations in free text

Stages 1 and 2: Key Analysis

Exact match uses a Set<string> for O(1) constant-time lookup against a configurable list of forbidden keys.

Fuzzy match extends protection to aliases and variations using two algorithms:

• Short tokens (< 4 chars, e.g., id): Boundary-aware regex that detects patientId, record_id, user-id but allows grid, video, android
• Long tokens (≥ 4 chars, e.g., name, phone): Substring containment that detects firstName, accountName, names

A safelist of common English words and LIOP protocol internal keys prevents false positives on terms like diagnosis, medication, image_id, or timestamp.

Stage 3: Pattern Validators

Pattern	Algorithm	Validation
EMAIL	Regex	Excludes @example.com, @test.com
CREDIT_CARD	Luhn checksum	Digit sum mod 10 === 0
IP_ADDRESS	Regex + range check	Excludes 127.x.x.x, validates octets 0 to 255
PHONE	Regex + repetition check	7 to 15 digits, rejects 1111111 patterns
SSN	Structural validation	Blocks area=0/666/≥900, group=0, serial=0
IBAN	ISO 7064 Mod-97 via BigInt	BigInt(numericString) % 97n === 1n
PASSPORT_MRZ	Regex	TD3 44-character Machine Readable Zone

Stage 4: Named Entity Recognition (NER)

When enableNerScanning is set to true, the scanner leverages the compromise NLP library to detect person names, geographic locations, and organization names embedded in output values, regardless of the key used to store them.

const server = new LiopServer(
  { name: "secure-vault", version: "1.0.0" },
  {
    security: {
      enableNerScanning: true,  // Activates NLP-based entity detection
      forbiddenKeys: ["id", "name", "ssn", "email"],
    },
  },
);

NER scanning is opt-in during the alpha phase. It adds approximately 10ms of latency for typical output sizes (< 10KB). The compromise library operates entirely in-process with no external API calls.

Regional Presets

The SDK ships with three preconfigured pattern sets tailored to common regulatory frameworks:

PII_PRESETS.GLOBAL_STRICT  // 6 patterns (Excludes SSN)
PII_PRESETS.US_COMPLIANT   // 6 patterns (Includes SSN, excludes IBAN)
PII_PRESETS.EU_GDPR        // 6 patterns (Includes IBAN, excludes SSN)

Presets can be merged with custom regex rules for organization-specific compliance requirements. See the LiopServer configuration guide for usage examples.

Anti-Bypass Protections

• Nested JSON Defense: Recursive parsing of JSON-encoded strings defeats obfuscation through JSON.stringify() wrapping
• Circular Reference Guard: WeakSet tracking prevents infinite recursion on self-referencing objects
• Aggregation-First Policy: Blocks raw row-level data export; only aggregated results (counts, averages, summaries) pass through
• Output Schema Enforcement: When a Zod output schema is defined, .strict() mode is automatically applied, rejecting any keys not explicitly allowed in the schema
• Cryptographic & Envelope Unwrapping: Automatically isolates and extracts the raw business data payload from MCP/LIOP envelopes and gRPC proxied responses (via unwrapForAggregationPolicyScan) before scanning. This prevents false positives from binary metadata and cryptographic seals (like HMAC-SHA256 ZK-Receipt signatures).
• Recursive In-Memory Numerical Sanitization: Before scanning, all numeric values inside the returned payload are processed recursively: positive floats are clamped to a maximum of 4 decimal places, and negative values are safely clamped to 0 (via sanitizeOutput()). This is executed fully in-memory to prevent float-representation side-channels and avoids redundant string conversions.
• K-Anonymity on Small Datasets: For micro-datasets or synthetic demos (dataset size < 10), the Egress Shield applies a strict K-Anonymity filter. Any output returned by the sandbox is rejected if it contains more than 3 scalar keys (flat properties) or if it has any arrays or nested objects. This blocks attempts to rebuild datasets key-by-key or through nested structure side-channels.

---

Differential Privacy & 3-Tier Query Budget (NIST SP 800-226)

To prevent reconstruction and statistical differentiation attacks (where an agent performs multiple overlapping queries to isolate a single record’s values), the SDK implements a tiered query budget system coupled with Laplace differential privacy.

3-Tier Query Budget Session Limits

During a secure PQC-negotiated session, the SDK tracks query access to data fields. In compliance with NIST SP 800-226 guidelines, fields are classified into three sensitivity tiers, each with its own strict query limit per session:

1. Forbidden Tier (Max 3 queries/session): Applies to fields declared in forbiddenKeys (e.g., ssn, password, email). Any attempt to query these fields beyond the limit triggers an immediate egress block.
2. Sensitive Tier (Max 8 queries/session): Applies to fields declared in global or tool-level sensitiveKeys (e.g., balance, diagnosis, ticker).
3. Public Tier (Max 25 queries/session): Applies to any public fields not registered as sensitive or forbidden.

Limits are enforced dynamically based on taint analysis tracking. If any tier’s budget is exhausted, further sandbox executions attempting to access fields in that tier are blocked.

Persistent Query Budgets & Concurrency Controls

To maintain zero-trust security invariants across server restarts, server crashes, or in multi-instance clusters (such as multiple parallel local bridge processes), the SDK supports filesystem-backed persistence of active query budgets:

• Configuring Persistence: Operators can provide budgetStorePath either globally in the LiopServer constructor options or locally inside a tool-level LogicExecutionPolicy.
• Client Identity Binding (Anti-Bypass): The budget limits are strictly bound to the client’s cryptographic identity (agentDid derived from their persistent Ed25519 PeerID, or clientId from JWT tokens authorized by the Nexus OAuth 2.1 server). By auditing the actual client identity rather than ephemeral transport tokens (such as gRPC session_token), the SDK prevents adversaries from resetting their query budgets by spawning new handshakes or reconnecting.
• Atomic File Locking: Under the hood, the SDK enforces cross-process synchronization and atomic updates to the budget JSON store using file-system locking (.lock files). This prevents race conditions where parallel LLM requests execute concurrently on separate worker threads/instances to exceed budget caps.
• Fail-Safe In-Memory Fallback: If filesystem write permissions fail, if the storage directory is read-only, or if a locking deadlock occurs, the SDK automatically reports the error to system logs and falls back to session-isolated in-memory budget tracking, ensuring continued node serviceability without dropping security enforcement.

Laplace Mechanism & Field Sensitivity

When the dataset size falls below dpSmallDatasetThreshold (default: 50), the DP Engine applies calibrated Laplace noise ($Noise \sim \text{Laplace}(0, \frac{\Delta s}{\epsilon})$) to all numeric outputs.

The engine automatically calibrates the sensitivity ($\Delta s$) based on field naming conventions:

• Count fields (count, length, size, num): Sensitivity is locked to $1.0$.
• Average fields (avg, mean): Sensitivity is dynamically calculated as $\frac{dpSensitivity}{recordCount}$.
• Sum & general fields: Sensitivity is set to the tool’s configured dpSensitivity.

---

Layer 6: ZK-Receipts (Tri-Modal ZK Architecture)

Every sandbox execution produces a cryptographic receipt that binds the output to the exact logic that generated it, providing tamper-evident proof of honest computation. The protocol supports a tri-modal receipt architecture spanning three cryptographic regimes:

1. Mode 0 (HMAC_LEGACY, Version 1): Cryptographic commitments derived from the ML-KEM-768 quantum-resistant session key.
2. Mode 2 (GROTH16, Version 2): True Zero-Knowledge SNARK proofs over the BN254 pairing-friendly elliptic curve with a 144-byte binary journal.
3. Mode 3 (GROTH16_PQC_HYBRID, Version 2.1): Dual-layer quantum-resistant receipts combining a Groth16 BN254 mathematical proof with an ML-DSA-65 post-quantum digital signature adhering to NIST FIPS 204.

Receipt Structure (Binary v2.1: Groth16 + ML-DSA-65 PQC Hybrid)

Version 2.1 receipts provide defense-in-depth against both algorithmic tampering and quantum adversaries. The payload packs the 144-byte canonical execution journal, the Groth16 proof, and the ML-DSA-65 signature into an immutable binary wire envelope (~5.6 KB):

+------+-----------+---------------+---------------+---------------+--------------+---------------+------------------+-------------------+------------------+
| 0x02 | 0x03      | journalLen    | Journal       | proofLen      | Proof        | sigLen        | Signature        | PublicKey         | Checksum         |
| (1B) | (1B)      | (4B BE)       | (144B fixed)  | (2B BE)       | (Variable)   | (2B BE)       | (3309B fixed)    | (1952B fixed)     | (32B SHA-256)    |
+------+-----------+---------------+---------------+---------------+--------------+---------------+------------------+-------------------+------------------+

Field	Size	Type	Description
Version	1 byte	0x02	Protocol version identifier
Proof Type	1 byte	0x03	Discriminator (0x03 = GROTH16_PQC_HYBRID)
Journal Length	4 bytes	Big-Endian UInt32	Byte length of the canonical journal (fixed 144 bytes)
Journal	144 bytes	Fixed Binary	Packed execution journal
↳ guest_image_id	32 bytes	Binary hash	Enclave guest binary or runtime image identifier
↳ logic_digest	32 bytes	Binary hash	SHA-256 fingerprint of injected JavaScript or WASM logic
↳ dataset_digest	32 bytes	Binary hash	SHA-256 fingerprint of the enclave dataset at execution
↳ output_digest	32 bytes	Binary hash	SHA-256 fingerprint of post-DP sanitized output
↳ fuel_consumed	8 bytes	Big-Endian UInt64	Quantized instruction-level fuel consumed by the sandbox
↳ execution_timestamp	8 bytes	Big-Endian UInt64	Epoch timestamp in milliseconds
Proof Length	2 bytes	Big-Endian UInt16	Byte length of the Groth16 proof payload
Proof	Variable	Binary	Compressed Groth16 curve points ($A \in G_1, B \in G_2, C \in G_1$)
Signature Length	2 bytes	Big-Endian UInt16	Byte length of the post-quantum signature (fixed 3,309 bytes)
Signature	3309 bytes	Binary	ML-DSA-65 digital signature over Version + ProofType + Journal + Proof
Public Key	1952 bytes	Binary	ML-DSA-65 verification key of the signing enclave
Checksum	32 bytes	SHA-256	Integrity digest over Version through Public Key

Receipt Structure (Binary v2: Groth16 BN254)

Version 2 receipts provide compact zero-knowledge attestation without post-quantum signatures, packing the 144-byte binary journal and curve points into approximately 252 bytes:

Field	Size	Type	Description
Version	1 byte	0x02	Protocol version identifier
Proof Type	1 byte	0x02	Discriminator (0x02 = GROTH16)
Journal	144 bytes	Fixed Binary	Packed execution journal identical to v2.1
Proof Length	4 bytes	Big-Endian UInt32	Byte length of the Groth16 proof payload
Proof	Variable	Binary	Compressed Groth16 curve points ($A \in G_1, B \in G_2, C \in G_1$)
Checksum	32 bytes	SHA-256	Integrity digest over Version + ProofType + Journal + Proof

Receipt Structure (Binary v1: Legacy HMAC)

Maintained for backwards compatibility with legacy nodes:

Field	Size	Type	Description
Version	1 byte	0x01	Protocol version identifier
Journal Length	2 bytes	Big-Endian UInt16	Length of the JSON payload
Journal	Variable	JSON string	Contains image_id, dataset_hash, output_hash, fuel, and ts
Seal	32 bytes	HMAC-SHA256	Cryptographic commitment derived from ML-KEM-768 session key

Enclave ZK Execution Policies

Tool capabilities configure their Zero-Knowledge attestation level via LogicExecutionPolicy:

• zkMode: "none": Default standard mode using HMAC-SHA256 session commitment.
• zkMode: "optimistic": Attempts Groth16 v2 receipt generation via @nekzus/liop-zk-native or fast-path R1CS circuits. If the native prover is unavailable, falls back gracefully to HMAC commitment without disrupting analytical query workflows.
• zkMode: "required" (ZK_BLOCKING): Mandatory for Tier 1 Sovereign Enclaves (banking, defense, sensitive healthcare). Strictly enforces valid Groth16 zero-knowledge proof generation. If the native prover is absent, if mock proofs are supplied, or if proof verification fails, the enclave rejects the request with an explicit error response: "[LIOP-ZK] Clearance Tier 1 enclave policy violation: Valid Groth16 zero-knowledge proof required but unavailable."
• pqcSign: true: Instructs the enclave to co-sign the Groth16 proof with its persistent ML-DSA-65 private key, emitting a Version 2.1 GROTH16_PQC_HYBRID receipt.

Hardware TEE Pre-Flight Attestation

To establish trust in untrusted physical infrastructure before transmitting encrypted logic payloads, the SDK provides the verifyTeeAttestationDetailed function. This utility inspects hardware root-of-trust measurements emitted by confidential virtual machines:

import { verifyTeeAttestationDetailed } from "@nekzus/liop";

const result = await verifyTeeAttestationDetailed(
  attestationBytes,
  expectedNonce,
  {
    allowedMeasurements: ["b7f8c..."],
    requireHardwareSigned: true,
  }
);

if (!result.valid) {
  throw new Error(`TEE Attestation rejected: ${result.reason}`);
}

The verifier supports two primary confidential computing platforms:

1. AMD SEV-SNP:

   • Parses the canonical 1,184-byte snp_report_t data structure.
   • Extracts the 64-byte REPORT_DATA field at byte offset 0x50 (decimal 80).
   • Validates that REPORT_DATA matches the cryptographic digest SHA-256(publicKey || nonce) padded with trailing zeroes.
   • Asserts that debug mode is disabled (POLICY.DEBUG === 0) and validates the firmware signature chain against AMD Versioned Chip Endorsement Keys (VCEK).

2. AWS Nitro Enclaves:

   • Decodes the CBOR-encoded COSE_Sign1 attestation document.
   • Evaluates Platform Configuration Registers (PCR0 for image digest, PCR1 for Linux kernel, PCR2 for user application).
   • Verifies the cryptographic binding of the caller’s ephemeral public key and nonce in user_data.
   • Validates the X.509 certificate chain up to the AWS Nitro Enclaves Root CA.

Cryptographic Pipeline

1. ImageID Generation: A SHA-256 hash of the original logic payload fingerprints the exact code that was executed.
2. Dataset Hash: A SHA-256 hash of the serialized dataset anchors the data state at execution time for regulatory audit compliance.
3. Differential Privacy: Laplace noise is applied to numeric outputs before commitment, ensuring the ZK-Receipt matches the noisy data the client receives. Supports DDP mode (seeded PRNG via dataset_hash + image_id) for audit reproducibility.
4. Binary Journal Encoding: A fixed 144-byte memory buffer packing guest_image_id, logic_digest, dataset_digest, output_digest, fuel_consumed, and execution_timestamp.
5. Native Groth16 Proving: Rayon-parallelized R1CS circuit execution via @nekzus/liop-zk-native generating curve points over the BN254 pairing-friendly elliptic curve in sub-second CPU time.
6. Post-Quantum Co-Signing (Mode 3): When pqcSign is active, the enclave signs the journal and proof points using ML-DSA-65, embedding the signature and public key into the v2.1 wire layout.
7. Verification & Replay Mitigation: The client verifier validates the proof via constant-time pairing checks or Worker Pool execution. To prevent reply manipulation and replay attacks, the verifier computes a local SHA-256 hash of the received result and strictly asserts identity against journal.outputDigest.
8. Balanced-Brace Proxy Extractor: If the tool call was delegated via proxy (__liop_proxy_tool), the verifier utilizes an in-process balanced-brace state machine to isolate raw proxy arguments before hashing, avoiding false positives when host layers append metadata.

The sessionSecret used in legacy v1 mode is the shared key negotiated via Post-Quantum Cryptography (ML-KEM-768), ensuring legacy compatibility remains quantum-resistant.

---

Transport Security

Post-Quantum Key Encapsulation (ML-KEM-768)

The SDK uses the mlkem package (FIPS 203 compliant) for key encapsulation:

Parameter	Value
Algorithm	ML-KEM-768 (Kyber)
Public Key Size	1,184 bytes
Ciphertext Size	1,088 bytes
Shared Secret	32 bytes
Symmetric Cipher	AES-256-GCM
Nonce	12 bytes (unique per input)

Nonce Isolation

Each encrypted payload uses a fresh 12-byte random nonce (crypto.randomBytes(12)) prepended to the ciphertext. This prevents AES-GCM nonce reuse when multiple payloads are encrypted under the same session key.

Production TLS Hardening

While LIOP’s PQC layer encrypts all application-level payloads end-to-end, transport-level encryption (TLS/mTLS) is critical for preventing metadata eavesdropping and ensuring node identity.

To prevent silent failures in production, the SDK implements a strict fail-safe check:

• In development/testing environments, missing or misconfigured certificate files trigger a warning and gracefully fall back to insecure gRPC channels.
• In production (process.env.NODE_ENV === 'production'), any failure to resolve or load configured TLS certificates (rootCert, certChain, or privateKey) throws a fatal error, forcing the process to crash immediately instead of silently degrading to an unencrypted channel.

Zero-Trust Bridge Authentication

The LiopStreamBridge enforces mandatory Bearer token authentication on all HTTP endpoints:

• If ZERO_TRUST_TOKEN is not set, a secure ephemeral token is auto-generated via randomUUID()
• Every request to /mcp requires a valid Authorization: Bearer <token> header
• Per-IP rate limiting on session creation (default: 10 concurrent sessions)
• Automatic eviction of idle sessions (TTL: 30 minutes)

---

OAuth 2.1 Authorization & Scope-Based Access Control (RBAC)

LIOP embeds a complete OAuth 2.1 / OIDC Machine-to-Machine (M2M) authorization stack conforming to RFC 6749, RFC 8707 (Resource Indicators), RFC 9068 (JWT Profile), and RFC 9728 (Protected Resource Metadata).

1. Embedded Authorization Server (createOAuthServer)

For Nexus coordinator nodes, the SDK provides an embedded authorization server backed by panva/node-oidc-provider:

import { createOAuthServer } from "@nekzus/liop";

const { provider, jwks } = createOAuthServer({
  issuer: "http://127.0.0.1:15000/oidc",
  clients: [
    {
      client_id: "agent-alpha",
      client_secret: process.env.AGENT_SECRET!,
      grant_types: ["client_credentials"],
      scope: "liop:tools:list liop:tools:call liop:resources:read",
    },
  ],
});

Key security properties:

• M2M Client Credentials Grant Only: Interactive and authorization code flows are locked out at the engine level to eliminate user-hijack vectors.
• Ed25519 (EdDSA) Token Signing: Asymmetric Ed25519 keypairs are generated and signed with zero external network dependencies.
• RFC 9068 JWT Access Tokens: Tokens carry verified client_id, scope, and aud claims, allowing stateless verification across distributed nodes.

2. Protocol Scopes (LIOP_SCOPES)

LIOP defines five granular, least-privilege scopes mapped to MCP and protocol operations:

Scope	Operations Covered	Standard
liop:tools:list	Listing advertised tools via tools/list	NIST SP 800-207 §4.3
liop:tools:call	In-situ WASM/JS logic execution via tools/call	OWASP LLM06
liop:resources:read	Reading static resources via resources/list, resources/read, resources/templates/list	Least Privilege
liop:schema:read	Reading prompt templates and schemas via prompts/list, prompts/get	Data Minimization
liop:mesh:query	Inter-node DHT manifest query and routing resolution	Mesh Governance

import { LIOP_SCOPES, type LiopScope } from "@nekzus/liop";

3. Gateway Request Authorization (authorizeRequest)

Incoming JSON-RPC requests are validated against required scopes before reaching router dispatchers:

import { authorizeRequest } from "@nekzus/liop";

const result = authorizeRequest("tools/call", authInfo);
if (!result.allowed) {
  // Returns HTTP 403 / JSON-RPC error with detailed rejection reason
  console.error("Access denied:", result.reason);
}

• Public lifecycle methods (initialize, ping, server/discover) execute without authentication per MCP specifications.
• Unrecognized methods or unauthenticated calls requesting protected scopes fail closed immediately.

4. Protected Resource Metadata (buildProtectedResourceMetadata)

Enables MCP clients to discover authorization endpoints per RFC 9728:

import { buildProtectedResourceMetadata } from "@nekzus/liop";

const metadata = buildProtectedResourceMetadata(
  "http://127.0.0.1:15000/oidc",
  "urn:liop:enclave:vault"
);
// Served at /.well-known/oauth-protected-resource

5. JWT Validation (JwtValidator)

Worker nodes validate bearer tokens statelessly via dual-mode JWKS resolution:

import { JwtValidator } from "@nekzus/liop";

// Remote JWKS resolution with 10-minute cache
const validator = new JwtValidator(
  "http://127.0.0.1:15000/oidc",
  "urn:liop:mesh",
  new URL("http://127.0.0.1:15000/oidc/jwks")
);

const authInfo = await validator.validate(token);
// Returns: { token, clientId, scopes: string[], expiresAt }

---

P2P Network Security

Component	Technology
Enclave Isolation	@libp2p/pnet (256-bit Swarm Key PSK)
Transport Encryption	Noise Protocol (Ed25519)
Stream Multiplexing	Yamux
Identity	Ed25519 persistent key pairs
Discovery	Kademlia DHT with public bootstrap nodes
Transports	TCP + WebSocket

Tier 1 Sovereign Enclave Isolation (pnet Swarm Key PSK)

For highly regulated environments (such as Core Banking, Health Records, and Defense), LIOP enforces physical-layer mesh isolation via libp2p Private Networks (@libp2p/pnet):

• Pre-Shared Key (PSK): A 256-bit cryptographic swarm key (formatted with /key/swarm/psk/1.0.0/ header) is loaded into enclave nodes (The Bank, The Vault) and authorized border gateways (blg).
• Transport Socket Shielding: The PSK operates before any multi-stream multiplexing or cryptographic handshake (Noise/TLS/Kyber). Any incoming TCP, WebSocket, or QUIC connection from a node without the matching swarm key is dropped immediately at the raw socket layer.
• Perimeter Defense: Even if an unauthorized peer discovers the enclave’s multiaddr or IP address on a shared LAN/VPC, it cannot establish a libp2p session, send RPC envelopes, or participate in the Kademlia DHT routing table.

---

Worker Pool Isolation

Computationally intensive cryptographic operations are dispatched to OS-level threads via Piscina worker pools, preventing blocking of the main V8 event loop:

Worker	Purpose
logic-execution	Sandbox instantiation, AES decryption, AST inspection
zk-verifier	Receipt deserialization, HMAC verification

Default configuration: 2 to 8 threads (production), 0 to 1 threads (test), FixedQueue scheduling, 5s idle timeout.

Heap Bomb Defense

Each worker thread is constrained via V8’s resourceLimits.maxOldGenerationSizeMb (default: 64 MB, configurable via workerPool.maxHeapMb or the LIOP_WORKER_MAX_HEAP_MB environment variable). If injected logic attempts to allocate memory beyond this limit, the worker is terminated immediately with a WorkerPoolError, preventing denial-of-service attacks that target Node.js heap exhaustion.

Worker Pool Async Warmup

To avoid initial CPU latency spikes and mitigate V8/WASI cold-starts (~820k fuel units), the SDK features an asynchronous thread-pool warmup strategy. On server initialization (or verifier creation), background “warmup” tasks (isWarmup: true or action: "warmup") are dispatched to pre-warm the Piscina worker instances. This ensures worker threads are initialized, V8 isolate contexts are allocated, and WASI handles are pre-cached before processing real client payloads.

---

Aggregation-First Policy

The SDK enforces an Aggregation-First heuristic that blocks raw row-level data from leaving the sandbox. This is the last computational defense before the ZK-Receipt layer.

How It Works

After execution, the output is recursively scanned for arrays containing objects. If the number of object elements exceeds the configured threshold, the response is blocked:

Parameter	Default	Description
maxOutputRows	10	Maximum number of object-type array elements allowed
allowPrimitiveArrays	true	Permits arrays containing only primitive values (numbers, strings)

server.tool(
  "analyze_data",
  "Aggregated analysis",
  { query: z.string() },
  async ({ query }) => { /* ... */ },
  {
    enforceAggregationFirst: {
      maxOutputRows: 5,
      allowPrimitiveArrays: true
    }
  }
);

Conditional Error Normalization

The SDK implements environment-aware error reporting for policy violations:

Environment	Behavior
development / test	Exposes detailed Zod validation errors, schema mismatch metadata, and HINT messages to enable LLM self-correction
production	Returns a generic [LIOP] Egress Security Violation message with zero internal details leaked

This is controlled automatically via process.env.NODE_ENV. In production deployments, always ensure NODE_ENV=production is set to activate full error opacity.

Detailed error messages in development mode may include field names, schema structures, and rejected value excerpts. Never expose development-mode error output to untrusted clients.

---

Protocol-Native Directive Channels

To ensure that LLM clients generate compliant JavaScript code that respects sandbox limits without trial-and-error latency, the SDK broadcasts structured, protocol-native instructions at three levels:

1. JSON Schema Metadata ($comment): The data dictionary automatically injects a $comment field containing sandbox directives directly into the active JSON schema representation.
2. Execution Guidelines Resource: A dynamic resource (liop://schema/guidelines) details the exact workarounds (e.g., date filtering via ISO 8601 strings) and constraints (K-Anonymity rules, Laplace suffixes) required by the node.
3. Cross-AI System Prompts: The prompt adapter system normalizes constraints across models (Claude, OpenAI, Gemini) to prevent hallucinated API calls.

---

---

Post-Quantum Cryptography & Session Lifecycle

LIOP combines ML-KEM-768 (Kyber768) for quantum-resistant key encapsulation with ML-DSA-65 (Dilithium65) for quantum-resistant digital signatures and manifest sealing:

1-Hour Strict Session Expiration

To prevent replay attacks and minimize the vulnerability window of derived symmetric keys, all PQC sessions enforce a hard 1-hour lifetime limit:

• Sessions automatically expire 3600 seconds after the initial ML-KEM-768 key exchange.
• Expired sessions reject subsequent RPC invocations and trigger an automatic re-negotiation handshake without dropping the underlying P2P connection.

Mutual TLS (mTLS) & Hot-Reloading (CertManager)

For enterprise environments requiring X.509 cryptographic client verification alongside PQC, CertManager manages dynamic certificate rotation without service restarts:

• Monitors CA, server, and client certificate paths on disk.
• Automatically swaps in-memory TLS contexts when renewed certificates are detected.
• Rejects untrusted client certificates at the transport handshake.

---

Industrial Compliance & Observability (SOC 2 Type II / HIPAA)

Immutable Audit Trail (AuditLogger)

Every logic execution, schema discovery, and security rejection is committed to an append-only, cryptographically verifiable Hash-Chain:

$\text{Block}_{n}.\text{hash} = \text{SHA-256}(\text{Block}_{n-1}.\text{hash} \parallel \text{Timestamp} \parallel \text{PeerID} \parallel \text{ImageID} \parallel \text{Status})$

• Tamper Evidence: Modifying or deleting any historical log record breaks the SHA-256 chain integrity, instantly flagging compliance auditors.
• Data Sovereignty: Log entries record cryptographic digests and token consumption metrics without ever persisting raw confidential data.

Deterministic AST Fuel Metering & Side-Channel Invariance (NIST SP 800-53)

To defend against CPU exhaustion attacks that execute hidden computational loops and eliminate timing side-channels, the engine statically analyzes JavaScript Abstract Syntax Trees via calculateAstInstructionFuel:

• Static Complexity Scoring: Analyzes AST node operations (loop depth, branching factor, function declarations, array iterations) before execution.
• 100-Bucket Quantization: In accordance with NIST SP 800-53 controls against timing side-channels, the computed fuel value is quantized to 100-unit buckets: $\text{Fuel}_{\text{quantized}} = \lceil \frac{\text{RawFuel}}{100} \rceil \times 100$
• Zero Standard Deviation (stddev = 0): Structural payloads with identical AST topologies evaluating diverging secret inputs consume precisely identical fuel units, preventing adversaries from deducing record cardinality or private data values through execution timing or fuel metering differentials.

---

Static Information Flow Control (TaintAnalyzer)

Layer 3 of the LIOP defense-in-depth model implements Static Information Flow Control (IFC) via the TaintAnalyzer class. Built on top of the Acorn ESTree parser and acorn-walk, it inspects injected JavaScript logic inside the @LIOP{...} envelope before bytecode compilation or isolate execution.

import { TaintAnalyzer } from "@nekzus/liop";

const analyzer = new TaintAnalyzer(
  ["ssn", "credit_card", "email", "password", "medical_record"], // Forbidden PII
  ["salary", "account_balance"]                                    // Policy-sensitive
);

const violation = analyzer.analyze(sourceCode, recordCount, 50);
if (violation) {
  throw new Error(`Execution rejected by Layer 3 IFC: ${violation.reason} (line ${violation.line})`);
}

Multi-Pass AST Static Analysis

The analyzer runs a deterministic 5-pass inspection pipeline:

1. Record-Bound Variable Identification (Pass 1): Traverses the AST to detect variables bound to individual confidential records inside iteration callbacks (map, filter, forEach, flatMap, find, some, every, and reduce/reduceRight).
2. Taint Propagation (Pass 2): Tracks data flows through variable assignments, object destructuring, binary arithmetic, string concatenations, and method invocations. A comprehensive set of character-extraction methods are flagged as taint propagators:
   • Character extraction: charCodeAt, codePointAt, charAt, at
   • Search & Structural discovery: indexOf, lastIndexOf, search, startsWith, endsWith, includes
   • Transformations: substring, slice, substr, split, match, replace, toLowerCase, trim
3. Return Statement Escapes (Pass 3): Validates that no scalar variable derived from a tainted PII field flows into the function’s return statement or export object.
4. Correlation Guard (Pass 4 - F-01 Mitigation): On datasets with fewer than 50 records, detects multiple distinct reduce operations targeting the same sensitive field, which could allow attackers to reconstruct values via differential equations.
5. Min/Max Extrema Gate (Pass 5 - F-02 Mitigation): Intercepts single-record extraction attempts (such as sorting records by PII fields or extracting maximum/minimum bounds on tiny cohorts) that facilitate binary search attacks.

Field Sensitivity Classification (NIST SP 800-226)

Fields are evaluated against a 3-tier classification matrix:

Sensitivity Tier	Behavior	Example Attributes
forbidden	Direct exfiltration or derivation unconditionally blocked by Layer 3 AST pass	ssn, iban, passport_number, password_hash
sensitive	Permitted only through verified aggregation algorithms with DP noise injection	balance, transaction_amount, health_diagnosis
public	Unrestricted aggregation and export	country_code, currency, timestamp_epoch

---

Differential Privacy Engine (DpEngine)

To defend against statistical reconstruction and membership inference attacks on small or sensitive datasets, the LIOP SDK integrates a high-performance Differential Privacy Engine conforming to NIST SP 800-226 and Google DP library specifications.

import { applyDpToOutput, addLaplaceNoise, type DpConfig } from "@nekzus/liop";

const dpConfig: DpConfig = {
  epsilon: 1.5,                 // Privacy budget (lower = more noise)
  sensitivity: 1000,            // Maximum plausible delta for SUM operations
  smallDatasetThreshold: 50,    // Only inject noise when cohort n < 50
  seed: "tenant_audit_seed_42"  // Optional seed for Deterministic DP (DDP)
};

const sanitizedResult = applyDpToOutput(rawOutput, dpConfig, datasetSize);

Laplace Mechanism & Cryptographic Entropy

The engine samples noise from the continuous Laplace distribution $\text{Lap}(0, \lambda)$ where scale $\lambda = \frac{\Delta f}{\varepsilon}$:

$f(x) = \frac{1}{2\lambda} \exp\left(-\frac{|x|}{\lambda}\right)$

Security Decisions (Industrial Recalibration)

1. CSPRNG Source (crypto.randomBytes): Unlike generic implementations that rely on Math.random() (Xorshift128+), DpEngine generates entropy using crypto.randomBytes(4) mapped into $[-0.5, 0.5)$. This prevents state-reconstruction attacks where an adversary observing 3 to 5 outputs could predict future pseudo-random states and subtract the noise.
2. Query-Aware Sensitivity: Sensitivity ($\Delta f$) is derived automatically according to key semantics:
   • COUNT Queries: Sensitivity is fixed at $\Delta f = 1$ (axiom: adding/removing one individual alters count by at most 1).
   • AVG / VARIANCE Queries: Sensitivity is scaled dynamically by cohort size: $\Delta f = \frac{\text{sensitivity}}{n}$.
   • SUM Queries: Uses the operator-configured global sensitivity cap.
3. Epsilon Floor ($\varepsilon \ge 1.0$): For extremely small cohorts ($n < 10$), the engine enforces an $\varepsilon$ floor of $1.0$ to prevent utility destruction (running $\varepsilon < 1.0$ on $n < 10$ yields purely random noise with zero analytical value).
4. Deterministic Differential Privacy (DDP): When an audit seed is supplied, entropy is derived via an HMAC-SHA-256 counter sequence. This allows verified reproducibility of ZK-Receipts in compliance audits while maintaining rigorous mathematical privacy.
5. Structural Preservation: Original integers remain rounded integers (Math.round), and non-negative attributes remain clamped to $\ge 0$, adhering to US Census TopDown post-processing standards.

Configuration Reference (DpConfig)

Property	Type	Default	Purpose
epsilon	number	1.0	Privacy loss parameter $\varepsilon$. Controls trade-off between privacy and numerical precision.
sensitivity	number	1.0	Global sensitivity cap $\Delta f$ representing the maximum plausible contribution of a single record.
smallDatasetThreshold	number	50	Record count threshold below which DP noise is activated (aligned with HIPAA Safe Harbor).
seed	string	undefined	Cryptographic seed string for deterministic audit reproducibility.

---

Roadmap

The following capabilities are architecturally defined and active across the protocol release channels:

Feature	Status	Description
Native ZK-VM	Active (v2.1)	Groth16 BN254 proofs and dual-layer ML-DSA-65 post-quantum hybrid receipts via @nekzus/liop-zk-native
Rust Core ZK	Active (v2.1)	Rayon multi-threaded arkworks R1CS circuits for analytical queries with Criterion benchmarks and SP1 guest
TEE Attestation	Active Pre-Flight	Hardware enclave measurement verification (AMD SEV-SNP and AWS Nitro Enclaves)

Sovereign Zero-Knowledge Proofs are available through version 2 and version 2.1 binary receipts. Enclaves equipped with @nekzus/liop-zk-native generate mathematical Groth16 proofs over the BN254 curve, whereas lightweight TypeScript SDK clients and MCP bridges verify proofs and post-quantum signatures without native compilation dependencies.