Log & Audit Interceptors

Technology-agnostic hooks for operational log streams and cryptographic audit chain ledgers

The LIOP SDK provides two runtime interceptor hooks designed for telemetry, anomaly detection, and regulatory compliance:

• LogInterceptor: Intercepts operational log events emitted by LiopLogger (transports, peer-to-peer gossip, routing).
• AuditInterceptor: Intercepts cryptographic audit entries emitted by AuditLogger after hash sealing (SOC 2 Type II and HIPAA compliance).

Both hooks operate out-of-band using an asynchronous fire-and-forget execution model, ensuring that external analysis or network latency never degrades core protocol throughput.

---

​

Interceptor Architecture

---

​

Operational Log Interceptor (LogInterceptor)

LiopLogger emits structured log messages exclusively to stderr to adhere to MCP stdio stream separation constraints (reserving stdout strictly for JSON-RPC framing). The LogInterceptor hook enables developers to forward, analyze, or filter these messages programmatically.

​

Contract Definition

import type { LogLevel } from "@nekzus/liop";

export interface LogEvent {
  timestamp: string;
  level: LogLevel; // "silent" | "error" | "warn" | "info" | "debug"
  message: string;
  args: readonly unknown[];
}

export type LogInterceptor = (
  event: Readonly<LogEvent>,
) => void | Promise<void>;

​

Registration and Lifecycle

The interceptor is registered directly on the LiopLogger singleton instance:

import { log, type LogInterceptor } from "@nekzus/liop";

const operationalInterceptor: LogInterceptor = async (event) => {
  if (event.level === "error") {
    // Forward to central monitoring or semantic anomaly detector
    await notifyOpsTeam(event);
  }
};

// Register hook
log.setInterceptor(operationalInterceptor);

// Disable hook (returns to zero-overhead execution)
log.setInterceptor(undefined);

​

Recursion Guard

If an interceptor implementation invokes code that triggers LiopLogger (directly or through dependencies), an infinite re-entrant loop could trigger a stack overflow. LiopLogger maintains an internal re-entrancy flag (_isIntercepting) that suppresses recursive interceptor dispatch within the same call frame while preserving normal stderr output.

---

​

Cryptographic Audit Interceptor (AuditInterceptor)

AuditLogger records immutable execution traces for every Logic-on-Origin workload. Each AuditEntry is cryptographically bound to its predecessor via SHA-256 hash chaining (prevEntryHash and entryHash), forming an unalterable audit ledger.

​

Contract Definition

import type { AuditEntry } from "@nekzus/liop";

export type AuditInterceptor = (
  entry: Readonly<AuditEntry>,
) => void | Promise<void>;

​

Post-Seal Invariant

The AuditInterceptor hook executes strictly after the audit entry has been sealed:

1. The SHA-256 hash of the entry is calculated and verified.
2. The hash chain pointer (lastEntryHash) is updated.
3. The entry is persisted to the local JSONL ledger file (if configured).
4. The interceptor receives an immutable deep clone created via Object.freeze(structuredClone(fullEntry)).

Mutations attempted by the interceptor throw in strict mode and cannot alter the stored hash chain or affect downstream verification.

import { AuditLogger, type AuditInterceptor } from "@nekzus/liop";

const auditLogger = new AuditLogger("/var/log/liop/audit.jsonl");

const securityInterceptor: AuditInterceptor = async (entry) => {
  if (entry.status === "BLOCKED_EGRESS") {
    // Alert security operations on blocked data exfiltration attempts
    await triggerSecurityEscalation(entry);
  }
};

auditLogger.setInterceptor(securityInterceptor);

---

​

Integration Examples

​

Example 1: External Threat Detection with TypeSafe Jev

Forwarding internal log streams or execution exceptions to external cloud services such as TypeSafe Jev is not recommended in production. Log messages frequently contain infrastructure paths, query metadata, or partial error traces. Transmitting this operational telemetry to third-party endpoints compromises infrastructure privacy, incurs per-call financial overhead, and introduces remote availability dependencies. For production deployments, use local in-process models (Example 3) or internal SIEM collectors (Example 2).

In development environments permitting outbound telemetry, operational error logs can be evaluated via cloud classification:

import { log, type LogInterceptor } from "@nekzus/liop";

const jevThreatDetector: LogInterceptor = async (event) => {
  if (event.level !== "error") return;

  const response = await fetch("https://api.typesafe.ai/v1/systemone", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.TYPESAFE_API_KEY}`,
    },
    body: JSON.stringify({
      model: "jev-latest",
      state: {
        source: "liop_logger",
        level: event.level,
        message: event.message,
      },
      questions: {
        is_threat: {
          type: "noul",
          instructions: "Does this log message indicate an injection attack or exploit attempt?",
        },
        category: {
          type: "choice",
          instructions: "Classify the security nature of this event",
          criteria: {
            sql_injection: "SQL injection or database manipulation syntax",
            xss: "Cross-site scripting or DOM injection payload",
            benign_failure: "Standard infrastructure or network timeout",
          },
        },
      },
    }),
  });

  const judgment = await response.json();
  if (judgment.answers.is_threat?.noul > 0.7) {
    console.error(`[SECURITY ALERT] ${judgment.answers.category?.choice}: ${event.message}`);
  }
};

log.setInterceptor(jevThreatDetector);

​

Example 2: Compliance Event Streaming to SIEM

Stream sealed audit entries to an external SOC 2 aggregator:

import { AuditLogger, type AuditInterceptor } from "@nekzus/liop";

const siemForwarder: AuditInterceptor = async (entry) => {
  await fetch("https://siem.internal.corp/api/v1/events", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      eventId: entry.id,
      timestamp: entry.timestamp,
      agentDid: entry.agentDid,
      toolName: entry.toolName,
      fuelConsumed: entry.fuelConsumed,
      status: entry.status,
      hash: entry.entryHash,
    }),
  });
};

const auditLogger = new AuditLogger();
auditLogger.setInterceptor(siemForwarder);

​

Example 3: Zero-Egress Threat Monitoring with Local ONNX (LogInterceptor)

In air-gapped enclaves where outbound network calls to cloud classifiers are prohibited, LogInterceptor can evaluate error patterns using a local ONNX runtime:

import { pipeline, env } from "@huggingface/transformers";
import { log, type LogInterceptor } from "@nekzus/liop";

env.localModelPath = process.env.LIOP_MODEL_PATH || "~/.liop/models";
env.allowRemoteModels = false;

const localDetector = await pipeline("text-classification", "tiny-prompt-guard", {
  device: "cpu",
});

export const onnxLogMonitor: LogInterceptor = async (event) => {
  if (event.level !== "error" && event.level !== "warn") return;

  const [verdict] = await localDetector(event.message);
  if (verdict.label === "INJECTION" && verdict.score >= 0.75) {
    // Record threat telemetry locally without blocking logging pipeline
    console.error(`[LOCAL THREAT ALERT] Potential operational exploit: ${event.message} (${(verdict.score * 100).toFixed(1)}%)`);
  }
};

log.setInterceptor(onnxLogMonitor);

​

Example 4: Local Cryptographic Audit Ledger Bridge (AuditInterceptor)

Process sealed audit entries locally to detect unusual execution patterns or trigger local compliance storage:

import { AuditLogger, type AuditInterceptor } from "@nekzus/liop";
import * as fs from "node:fs/promises";

export const localAuditBridge: AuditInterceptor = async (entry) => {
  // Post-seal invariant guarantees immutable access to cryptographic hash chain
  const record = JSON.stringify({
    timestamp: entry.timestamp,
    toolName: entry.toolName,
    status: entry.status,
    entryHash: entry.entryHash,
    prevEntryHash: entry.prevEntryHash,
    fuelConsumed: entry.fuelConsumed,
  });

  // Append asynchronously to local immutable ledger
  await fs.appendFile("/var/log/liop/audit-ledger.jsonl", `${record}\n`);
};

const auditLogger = new AuditLogger();
auditLogger.setInterceptor(localAuditBridge);

---

​

Universal Out-of-Band Deployment

Unlike GatewayInterceptor (which is strictly restricted to perimeter gateways), LogInterceptor and AuditInterceptor can and should be deployed on EVERY node across all tiers:

Node Role	GatewayInterceptor	LogInterceptor	AuditInterceptor	Network Boundary Role
Perimeter Ingress (Nexus)	Mandatory	Active (OOB)	Active (OOB)	L7 WAF / Admission filtering
Border Gateway (BLG)	Bypassed	Active (OOB)	Active (OOB)	Asymmetric mTLS / Swarm PSK bridge
Data Enclaves (Bank / Vault)	Prohibited	Active (OOB)	Active (OOB)	Zero-Trust WASI / The Shield execution

Because both hooks execute asynchronously via fire-and-forget (Promise.resolve().then(...) or un-awaited fetch()), external inference latency or remote SIEM outages introduce exactly 0 ms of delay to client RPC responses or host sandbox evaluation.

LIOP Interceptor Topology: Demarcation between Ingress Admission and Enclave Isolation

---

​

Security Model Comparison

LIOP defines three complementary interceptor hooks. None replace or compromise the 6 security layers of The Shield:

LIOP Security Layer	GatewayInterceptor	LogInterceptor	AuditInterceptor
Layer 1: Guardian AST	Evaluated after admission	Operates outside enclave	Operates outside enclave
Layer 2: WASI Sandbox	Pre-sandbox evaluation	Outside sandbox boundary	Post-sandbox completion
Layer 3: Taint Analyzer	Pre-analysis filter	Independent of taint flow	Independent of taint flow
Layer 4: Egress PII Shield	Pre-egress gate	Emits log metadata only	Receives hashes, never raw PII
Layer 5: Aggregation-First	Pre-aggregation gate	No dataset access	No dataset access
Layer 6: ZK-Receipt	Verified post-execution	Post-execution telemetry	Receipt hash sealed prior to hook

---

​

Related References

• Gateway Interceptor: Perimeter admission hook for LiopHybridGateway.
• Audit & Compliance: Hash-chain specifications and SOC 2 Type II controls.