xLineage: AI Agent Tool-Use Chain of Custody

The Problem

AI agents use dozens of external tools, but there is no verifiable record of which tools were called, with what parameters, or what results were returned.

Tool-use agents can call APIs, query databases, execute code, and modify systems. Without a chain-of-custody log, there is no way to reconstruct what an agent did, why, or whether it was authorized.

Standard logging is insufficient because logs can be tampered with. A compromised agent can delete or modify its own log entries to cover its tracks.

The Old Way: Tamperable Logs

The PRIVATE.ME Solution

xLineage creates an HMAC-chained, DID-signed record of every tool invocation. Each entry is cryptographically linked to the previous, making tampering detectable.

Every tool call generates a signed entry: tool name, parameters (hashed if sensitive), result hash, timestamp, and the calling agent's DID. Entries are HMAC-SHA256-chained.

Threshold authorization can gate sensitive tools — require K-of-N approval before the agent can execute high-risk operations like database writes or payment calls.

The New Way: Tamper-Evident Chain

Solution Architecture

xLineage provides an append-only tool-use audit trail with HMAC chaining, DID signatures, and optional threshold gates for sensitive operations.

Pipeline Architecture

Core Modules

Real-World Use Cases

Developer Experience

import { auditChain, verifyChain } from '@private.me/xlineage';

// Log tool call with DID signature
const result = await auditChain({
  lineageId: 'agent-session-abc',
  actionType: 'tool:database.query',
  actorDid: agent.did,
  dataHash: hashParams(queryParams)
});

// Verify chain integrity before forensic reconstruction
const verification = await verifyChain('agent-session-abc');
if (!verification.ok) {
  console.error('Chain tampered!', verification.error);
}

import { gateToolCall } from '@private.me/xlineage';

// Require 2-of-3 approval for payment API calls
const gateResult = await gateToolCall({
  toolName: 'stripe.createCharge',
  threshold: 2,
  totalShares: 3,
  approverDids: [did1, did2, did3],
  paramsHash: hashParams(chargeData)
});

if (gateResult.ok) {
  // Execute payment only after threshold approval
  await executeCharge();
  await auditChain({ /* log execution */ });
}

API Reference

Security Properties

Test Coverage

xLineage ships with comprehensive test coverage across 4 test files:

• audit.test.ts (23 tests) — Chain generation, HMAC linking, tamper detection
• verification.test.ts (23 tests) — Integrity verification, DID signature validation, chain break diagnostics
• reconstruction.test.ts (19 tests) — Event replay, filtered playback, forensic reconstruction
• tracking.test.ts (6 tests) — Tool call logging, parameter hashing, DID attribution

Verifiable Data Protection

Every operation in this ACI produces a verifiable audit trail via xProve. HMAC-chained integrity proofs let auditors confirm that data was split, stored, and reconstructed correctly — without accessing the data itself.

Ready to deploy xLineage?

Talk to Sol, our AI sales engineer, or book a live demo with our team.