Engineering & Architecture

The Architecture of Trust

A technical deep dive into the "Paranoid Architecture" that makes EPI suitable for high-compliance environments.

1. The Recorder Engine

The heart of EPI is its ability to capture code execution "autonomously" without requiring the developer to rewrite their application. This is achieved through Dynamic Runtime Patching.

A. The "Magic" Mechanism: Monkey-Patching

Instead of asking developers to use a custom SDK, we intercept the standard libraries they already use. The patcher.py module uses functools.wraps to replace original methods (e.g., openai.resources.chat.completions.Completions.create) with a wrapper that captures inputs, executes the original method, and logs the result—without altering functionality.

B. The Security Kernel

Trust is not achieved by "logs" but by Cryptographic Signatures. Before signing, the manifest.json is canonicalized (sorted keys, stripped whitespace) to ensure deterministic hashing across platforms.

  • Algorithm: Ed25519 (Edwards-curve Digital Signature Algorithm)
  • Library: cryptography.hazmat.primitives.asymmetric.ed25519
  • Key Size: 32 bytes (High performance, low overhead)

2. The Zero-Knowledge Verifier

The Verifier is a Zero-Knowledge application. It proves the validity of a file without ever needing to see its contents on a server. The Python backend logic was ported entirely to JavaScript using JSZip and @noble/ed25519.

The "Integrated Visualizer" Sandbox

Rendering an embedded `viewer.html` inside the Verifier carries XSS risks. We solved this using a Sandboxed Blob Iframe architecture: 

// 1. Create a Blob from the untrusted content
const blob = new Blob([htmlContent], { type: 'text/html' });

// 2. Generate a unique, isolated URL
vizFrame.src = URL.createObjectURL(blob);

// 3. Enforce strict sandboxing (No 'allow-same-origin')
// <iframe sandbox="allow-scripts allow-popups allow-forms">

This prevents the viewer from accessing the parent Verifier's cookies, local storage, or DOM. It effectively runs in a null origin.

3. The Invisible CI/CD Hook

To enforce this at enterprise scale, the epi-action GitHub Action integrates directly into the pipeline:

  1. Trigger: Runs on pull_request or push.
  2. Gen: Runs tests wrapped in epi run.
  3. Verify: Immediately runs epi verify.
  4. Block: Fails the build if verification fails.

Conclusion: Trustless Verification

The EPI system is designed with a "Paranoid Architecture": The Recorder assumes the environment is hostile (redacts secrets), the Verifier assumes the file is hostile (sandboxes viewer), and the Crypto assumes the network is hostile (signs offline).