# Volidator Full Reference Manual

This document provides the complete, consolidated technical specification, architectural guide, and integration instructions for the Volidator zero-knowledge compliance audit logging platform.

---

## 1. Architectural Overview & Cryptographic Model

Volidator implements a **Zero-Trust, Server-Blind Audit Logging Model**. It separates the storage provider (Volidator) from the data owner (your application).

### 1.1 Local Encryption (AES-256-GCM)
Before any audit log leaves your server, the SDK encrypts the payload locally using an in-memory Data Encryption Key (DEK) derived from your environment secrets.
* **Ciphertext:** Stored on Volidator.
* **Decryption Key:** Stored strictly in your environment variables. Volidator never receives the raw key.

### 1.2 Blind Indexing (HMAC-SHA-256)
To allow searching and filtering over encrypted records without letting the backend read them, the SDK computes **blind indexes** (deterministic hashes) of key search fields:
* `actorBlindIndex` = `HMAC-SHA-256(actor_id, salt)`
* `actionBlindIndex` = `HMAC-SHA-256(action, salt)`
* `targetBlindIndex` = `HMAC-SHA-256(target, salt)`
* `tenantBlindIndex` = `HMAC-SHA-256(tenant_id, salt)`
* `traceBlindIndex` = `HMAC-SHA-256(trace_id, salt)`

---

## 2. Ingesting Payloads > 30KB (Claim Checks)

Cloudflare D1 Drizzle and SQLite have strict envelope boundaries. Payloads exceeding **30KB** triggers the **Claim Check Pattern**:

```
[ Application SDK ] 
        │ 
   (size > 30KB) 
        ▼
 1. Stream encrypted payload payload to R2 bucket (pending/hash)
 2. Send metadata envelope referencing hash to Ingestion Worker
 3. Ingestion Worker promotes hash from pending/ to active/ in R2
```

### 5MB Guardrail:
* **SDK:** Throws a fail-fast error `Volidator SDK Error: Audit log payload exceeds the 5MB hard limit` if payload size exceeds 5MB.
* **Worker:** Enforces `Content-Length <= 5MB` on the R2 upload endpoint, returning `413 Payload Too Large`.

---

## 3. Lamport Timestamps & Trace Ordering

In distributed systems, Network Time Protocol (NTP) clock drift makes chronological visual ordering unreliable. Volidator uses a lightweight **Lamport Timestamp** (logical clock counter) inside the SDK.

### 3.1 Logical Clock State
The Node/Next.js SDK isolates logical clocks across requests using Node's `AsyncLocalStorage`:
* Each event increments the local logical clock.
* Outgoing headers include `x-volidator-clock` and `x-volidator-trace`.
* Incoming requests synchronize the logical clock to `max(local_clock, incoming_clock) + 1`.

### 3.2 Trace Sorting Priority (Frontend Visualizer)
1. **Trace ID** match grouping.
2. **Logical Clock** (Lamport Timestamp) integer ascending.
3. **Captured Date/Time** (Fallback for concurrency).
4. **Span ID** alphabetical tie-breaker.

---

## 4. Node/TypeScript SDK Integration

### 4.1 Installation
```bash
npm install @volidator/node
```

### 4.2 Initialization & Config
```ts
import { VolidatorClient } from '@volidator/node';

export const volidator = new VolidatorClient({
  apiKey: process.env.VOLIDATOR_API_KEY!,
  encryptionKey: process.env.VOLIDATOR_ENCRYPTION_KEY!,
});
```

### 4.3 Log Ingestion API
```ts
await volidator.log({
  actor: 'user_9823',
  action: 'document.delete',
  target: 'doc_882',
  req: request, // optional - auto-extracts IP & Geolocation
  metadata: {
    fileName: 'sensitive_report.pdf',
    fileSize: 4528120
  }
});
```

### 4.4 In-Memory PII Redaction
Prevent leakages of sensitive fields (SSNs, emails, credit cards) before encryption using local rules:
```ts
const client = new VolidatorClient({
  apiKey: '...',
  encryptionKey: '...',
  redactionRules: [
    {
      pattern: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g,
      replacement: '[REDACTED_EMAIL]'
    }
  ]
});
```

---

## 5. Embeddable Visualizer Dashboard

To embed compliant audit logs into user interfaces, issue a JIT Signed Token. The decryption key is sent in the URL hash fragment (`#key=...`), ensuring the key is never exposed to intermediate servers or networks.

```ts
const embedToken = await volidator.generateEmbedToken({
  tenantId: 'company_tenant_abc',
  role: 'admin',
  expiresIn: '1h'
});

const iframeUrl = `https://embed.volidator.com/${embedToken}#key=${process.env.VOLIDATOR_ENCRYPTION_KEY}`;
```