Trust & Verification

Trust & Verification

AgentCTX’s trust model ensures that every agent action is verifiable. This guide explains how the cryptographic verification pipeline works and how to use it.

The Trust Problem

When an AI agent modifies your codebase, how do you know what it actually did? You could:

1. Read the agent’s chat output — but it might hallucinate
2. Diff the files — but you miss the intent
3. Review a log — but who wrote the log?

AgentCTX solves this with cryptographic verification: every action is translated to human-readable form by a deterministic compiler (not an LLM), then signed with Ed25519.

The Verification Pipeline

1. Agent writes CTX:    +m "decision" #arch "Use PASETO"
                              ↓
2. Sidecar translates:  "Stored architecture decision: Use PASETO"
                              ↓
3. Crypto signs:         Ed25519(ctx + translation) → signature
                              ↓
4. Three files written:  {digest}.ctx, {digest}.md, {digest}.json
                              ↓
5. Human verifies:       crypto.verifyAll() → ✅ all signatures valid

Key Properties

Property	How
Deterministic	Sidecar is a compiler — same input, same output, always
Tamper-evident	Ed25519 signature breaks if any byte changes
Offline-capable	Signing happens locally, no network required
Non-repudiable	Agent’s Ed25519 key proves authorship
Auditable	✅ crypto.verifyAll() validates any translation

Setting Up Trust

1. Initialize

Ed25519 keypairs are created automatically when a gateway is instantiated or when using the SDK:

import { Gateway } from '@agentctx/core';

const gw = new Gateway();
// Creates Ed25519 keypair at .context/.keys/ if not present

2. Operations Are Signed Automatically

Every operation through the gateway creates a signed translation:

const result = await gw.process('+m "auth-choice" #arch "PASETO for all APIs"');
// 🗣️  Human: Stored architecture decision: PASETO for all APIs
//    (Signed: a1b2c3d4...)

3. Verify Anytime

import { CryptoManager } from '@agentctx/core';

const crypto = new CryptoManager('.context');
const result = await crypto.verifyAll('.context/translations/');
// { total: 42, valid: 42, invalid: [] }

Translation Files

Each signed translation produces three files in .context/translations/:

{digest}.ctx

+m "auth-choice" #arch "PASETO for all APIs"

{digest}.md

> +m "auth-choice" #arch "PASETO for all APIs"

Stored architecture decision: PASETO for all APIs

---
*Signature: base64(Ed25519...)*
*Digest: a1b2c3d4...*
*Timestamp: 2026-03-20T20:15:00Z*

{digest}.json

{
  "ctx": "+m \"auth-choice\" #arch \"PASETO for all APIs\"",
  "human": "Stored architecture decision: PASETO for all APIs",
  "signature": "base64...",
  "digest": "a1b2c3d4...",
  "timestamp": "2026-03-20T20:15:00Z"
}

Detecting Tampering

If someone modifies a translation file:

const result = await crypto.verifyAll('.context/translations/');
// {
//   total: 42,
//   valid: 41,
//   invalid: ["e5f6g7h8.json"]
// }

Content-Addressed Store (CAS)

The CAS provides a second layer of integrity. Every stored object is named by its SHA-256 hash — if a file’s content doesn’t match its hash-based filename, it’s been tampered with.

CAS integrity is enforced structurally: the ObjectStore recomputes SHA-256 on every get() call and rejects any object whose content doesn’t match its hash-derived path. No separate verification step is needed — integrity is built into every read.

See Also

• Sidecar — the compiler architecture
• Security Model — all 8 security layers