Zero Knowledge Certifying Proxy

The Volidator Certifying Proxy is an inline, zero-knowledge network proxy designed for developers who want to integrate compliance logging with zero SDK dependencies.

By routing LLM completions (such as OpenAI, DeepSeek, Anthropic) or database writes directly through Volidator, you capture system events automatically at the network edge.

---

Why Use the Proxy?

• Zero Dependency Onboarding: Route completions by changing only the base destination URL and headers in your existing HTTP client.
• Universal Compatibility: Works with any programming language (Python, Go, Rust, Ruby) or framework that supports standard HTTP requests.
• Real-Time Streaming: Built with native streams ensuring sub-5ms latency overhead, fully supporting Server-Sent Events (SSE).
• Symmetric Edge Encryption: Payloads are encrypted at the edge using your symmetric key before storing, ensuring zero-knowledge privacy.

---

Integration Guide

Quickstart Example

To route requests, target the Volidator Proxy destination. For example, in a standard curl command:

curl -X POST https://ingestion.volidator.com/v1/proxy \
  -H "Authorization: Bearer val_agent_bb48417cb42cb26fc88106247d" \
  -H "X-Volidator-Encryption-Key: test-key-32-chars-xyz-abcdefghij" \
  -H "X-Volidator-Agent-ID: research-agent-v1" \
  -H "X-Volidator-Run-ID: run_902cf1e8" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "https://api.anthropic.com/v1/messages",
    "payload": {
      "model": "claude-5-sonnet",
      "max_tokens": 1024,
      "messages": [{"role": "user", "content": "Fetch latest compliance updates"}]
    },
    "requestProof": true
  }'

---

Request Configuration

Required Headers

Header	Description
Authorization	Bearer API Key. Must use standard prefixes (val_human_, val_agent_, val_service_) to dictate caller class.
X-Volidator-Encryption-Key	Client-supplied symmetric key. Used to encrypt the request and response payloads before storage.

Optional Context Headers

Header	Description
X-Volidator-Agent-ID	Maps to the actor field in the audit logs (defaults to proxy).
X-Volidator-Action	Maps to the action field in the audit logs (defaults to proxy.request).
X-Volidator-Run-ID	Maps to the traceId. Setting this automatically stitches agent calls together in the Story Visualizer.

Payload Properties

The request body sent to /v1/proxy must contain:

• target (string): The destination URL (e.g. OpenAI or Supabase).
• payload (object): The request body forwarded directly to the destination URL.
• requestProof (boolean, optional): Toggle premium RFC 3161 proof receipt generation (batched in 5s windows).

---

Security Architecture

1. Header Scrub Scrubbing

The proxy strips all incoming X-Volidator-* headers before sending requests to the upstream server. The target API (such as Claude or Stripe) never sees your project API keys or symmetric encryption keys.

2. Server-Side Request Forgery (SSRF) Filters

The proxy blocks all requests pointing to loopback addresses, localhosts, cloud provider metadata servers (169.254.169.254), IPv6 local ranges, and private CIDR subnets (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16).

3. Memory Protection

Streams are parsed up to 2MB in-memory for logging. If a response exceeds 2MB, the proxy continues streaming the full data to the client but truncates the log record to avoid memory exhaustion crashes.

---

Retrieving Receipts and Proofs

Via the Terminal

Query the proof endpoint to get Merkle paths, Rekor indexes, and DER-encoded TSA signatures:

curl -H "Authorization: Bearer val_live_bb48417cb42cb26fc88106247d" \
  "https://management.volidator.com/v1/projects/proj_123/logs/log_5678abcd90ef/proof"

Via the Dashboard

Simply click on any node in the Story Visualizer canvas. The visualizer detail panel automatically performs an async lookup and displays the certified signatures and verification logs.

---

Client-Side Local Fallback Backups

To guarantee zero audit trail loss during network failures or outages, you can register a local backup file transport.

1. Register the Fallback Transport (Node.js backend)

Import the decoupled file transport adapter and pass it as the onDeliveryFailure callback:

import { VolidatorClient } from "@volidator/node";
import { createFileFallbackTransport } from "@volidator/node/fallback-file";

const fallback = createFileFallbackTransport({
  directory: "./backups/volidator-logs",
  filenamePrefix: "my-app-logs",
});

const client = new VolidatorClient({
  apiKey: "...",
  encryptionKey: "...",
  onDeliveryFailure: fallback,
});

2. High-Performance Concurrency & Date-suffixed Rotation

The fallback transport is designed for production applications:

• No Concurrency Interleaving: Multiple concurrent failure writes are queued inside an internal, non-blocking promise chain so that log rows are written sequentially, avoiding file corruption.
• Daily Rolling Files: Filenames automatically roll over daily using a date suffix (my-app-logs-YYYY-MM-DD.log). You should configure external log rotation (such as logrotate) to manage file size limits.

---

Cryptographic Verification Dissection

Easy Verification using the Node.js SDK

If you are using our Node.js SDK, you do not need to execute these calculations manually. Simply use our built-in helper method:

import { VolidatorClient } from "@volidator/node";

const isValid = await VolidatorClient.verifyProof(decryptedLogPayload, proofReceipt);
if (isValid) {
  console.log("Log has not been tampered with!");
}

Manual Verification Steps

To mathematically prove that an audit log is genuine and has not been retroactively altered without relying on our SDK libraries, execute these validation steps:

1. Check Payload Integrity

Compute the SHA-256 hash of the decrypted log payload JSON (containing request and response metadata). Verify that it matches the payloadHash inside the proof receipt. Any alteration of log content will break this match.

2. Verify Merkle Path Membership

Walk the sibling hashes list inside merklePathJson. Combine the running hash with each sibling hash and compute the SHA-256 hash. The final result must equal the merkleRoot. This guarantees the log was not swapped or removed from the batch.

3. Verify TSA DER Signature

Parse the tsaResponse CMS block. Verify the certificate authority chain up to a trusted Root CA and verify that the signed digest matches the merkleRoot. This proves the batch existed at the certified timestamp.

4. Verify Rekor Public Anchoring

Query the public Sigstore Rekor ledger at the given rekorLogIndex: GET https://rekor.sigstore.dev/api/v1/log/entries?logIndex={rekorLogIndex} Verify that the root hash stored in the write-once ledger matches the merkleRoot. This prevents retroactive history rewrites.