dyolo-kya

Know Your Agent (KYA) — cryptographic chain-of-custody for recursive AI delegation.

dyolo-kya solves the Recursive Delegation Gap: the security failure that occurs when AI agents delegate tasks to other AI agents without cryptographic proof linking those actions back to an original human authorization.

Every action verified by this library generates a cryptographically verifiable audit trail from the executing agent back to the authorizing human. The protocol enforces strict capability boundaries: agents cannot grant authority they do not possess, certificates cannot outlive their parents, and cryptographic nonces prevent replay attacks.

The Problem

Modern AI agent systems suffer from a fundamental security failure:

• Scope escalation — an agent authorized only to query a portfolio can silently grant drain authority to a sub-agent.
• Broken provenance — when an action is executed by a deeply nested agent, there is no proof it traces back to a human.
• Coarse authorization — delegations are typically "full access" rather than "only TRADE_AAPL_100 at limit=182.50".
• No replay protection — the same delegation token can be reused indefinitely.
• No revocation — a compromised delegation cannot be cancelled mid-chain.
• Temporal abuse — a child delegation can outlive its parent.

In a world where autonomous AI agents manage real capital, these gaps are not theoretical.

The Solution

dyolo-kya closes every gap through five composable primitives:

The AuthorizedAction type is the key design: you cannot construct one yourself. The Rust type system enforces that no execution path exists that bypasses verification.

Install

[dependencies]
dyolo-kya = "1"

With JSON/binary serialization:

[dependencies]
dyolo-kya = { version = "1", features = ["serde"] }

Quick Start

use dyolo_kya::{
    CertBuilder, DyoloChain, DyoloIdentity, Intent, IntentTree,
    MerkleProof, MemoryNonceStore, MemoryRevocationStore,
    SubScopeProof, SystemClock,
};

// ── Identities ────────────────────────────────────────────────────────────────

let human        = DyoloIdentity::generate();
let orchestrator = DyoloIdentity::generate();
let executor     = DyoloIdentity::generate();

// ── Principal defines the authorized intent set ───────────────────────────────

let trade = Intent::new("trade.equity")
    .param("symbol", "AAPL")
    .param("side", "buy")
    .param("limit_usd", "182.50")
    .param("qty", "100")
    .hash();

let query = Intent::new("query.portfolio").hash();

let tree  = IntentTree::build(vec![trade, query]).unwrap();
let root  = tree.root();

// ── Human → Orchestrator (full scope) ────────────────────────────────────────

let now    = 1_700_000_000u64;
let expiry = now + 3_600;

let cert_orch = CertBuilder::new(orchestrator.verifying_key(), root, now, expiry)
    .sign(&human);

// ── Orchestrator → Executor (trade-only, no further delegation) ───────────────

let sub_proof = SubScopeProof::build(&tree, &[trade]).unwrap();
let sub_root  = IntentTree::build(vec![trade]).unwrap().root();

let cert_exec = CertBuilder::new(executor.verifying_key(), sub_root, now, expiry)
    .scope_proof(sub_proof)
    .max_depth(0)
    .sign(&orchestrator);

// ── Assemble chain and authorize ──────────────────────────────────────────────

let mut chain = DyoloChain::new(human.verifying_key(), root);
chain.push(cert_orch).push(cert_exec);

let action = chain.authorize(
    &executor.verifying_key(),
    &trade,
    &MerkleProof::default(),
    &SystemClock,
    &MemoryRevocationStore::new(),
    &MemoryNonceStore::new(),
).unwrap();

// action.receipt is your tamper-proof compliance record.
println!("Authorized at depth {}", action.receipt.chain_depth);

Security Guarantees

Pluggable Backends

The in-memory stores (MemoryRevocationStore, MemoryNonceStore) are for development and testing. Production systems should implement the traits over persistent storage:

use dyolo_kya::{RevocationStore, NonceStore};

struct RedisRevocationStore { /* ... */ }

impl RevocationStore for RedisRevocationStore {
    fn is_revoked(&self, fingerprint: &[u8; 32]) -> Result<bool, String> {
        Ok(false) // query Redis
    }

    fn revoke(&self, fingerprint: &[u8; 32]) -> Result<(), String> {
        Ok(()) // write to Redis
    }
}

The same pattern applies to NonceStore. A persistent NonceStore is critical for production replay protection across process restarts.

Architecture

dyolo-kya/
├── src/
│   ├── lib.rs          — public API surface
│   ├── crypto.rs       — domain-separated Blake3 hashing (private)
│   ├── intent.rs       — Intent, IntentTree, SubScopeProof, MerkleProof
│   ├── identity.rs     — DyoloIdentity (Ed25519, ZeroizeOnDrop)
│   ├── cert.rs         — DelegationCert, CertBuilder
│   ├── registry.rs     — RevocationStore, NonceStore, in-memory impls
│   ├── chain.rs        — DyoloChain, AuthorizedAction, VerificationReceipt
│   └── zk_guest/       — RISC Zero ZK guest program (feature = "prove")
│       ├── Cargo.toml
│       └── src/main.rs — Ed25519 chain verifier inside ZK VM
├── benches/
│   └── chain_bench.rs  — criterion benchmarks (single-hop, two-hop, revocation)
├── tests/
│   └── integration.rs  — adversarial test suite (clock, tampering, revocation)
├── examples/
│   └── trading_agent.rs — end-to-end multi-agent authorization demo
├── .github/
│   └── workflows/
│       └── ci.yml      — matrix CI (Linux, macOS, Windows)
├── CHANGELOG.md
├── SECURITY.md
└── LICENSE

Running

# End-to-end example
cargo run --example trading_agent

# Test suite (including adversarial integration tests)
cargo test

# Benchmarks
cargo bench

Environment Variables

Target Use Cases

• Autonomous crypto trading agents and execution engines
• Multi-agent research and orchestration frameworks
• Enterprise AI workflow automation requiring compliance
• On-chain agent protocols (AI DAOs, intent-based solvers)
• Any system where humans delegate authority to AI that may further delegate

Authors

Created by dyolo (@dyologician).

License

MIT — see LICENSE.