{"_id":"@aivoralabs/agenttrail","_rev":"2-9802e65a58ec318680c973d6ebf435a6","name":"@aivoralabs/agenttrail","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@aivoralabs/agenttrail","version":"0.1.0","keywords":["ai-compliance","eu-ai-act","audit-trail","ai-agents","article-12","hash-chain","cryptographic-receipts","compliance","ai-governance","audit","llm","openai"],"author":{"name":"AivoraLabs","email":"hello@aivoralabs.org"},"license":"MIT","_id":"@aivoralabs/agenttrail@0.1.0","maintainers":[{"name":"user_aivoralabs","email":"aivoralabs@aivoralabs.org"}],"homepage":"https://agenttrail.aivoralabs.org","bugs":{"url":"https://github.com/AiVoraLabs/agenttrail/issues"},"dist":{"shasum":"0642e218fc987487aa74c2b623513f3584a392e1","tarball":"https://registry.npmjs.org/@aivoralabs/agenttrail/-/agenttrail-0.1.0.tgz","fileCount":3,"integrity":"sha512-fsvdIXJXfYpePQwufqt1ZT7yvVH3N46P1sW0Pd4KP7lZHd46Vrlxe2DHhU4R8uXddWn1ydvoNg3tFhEWeAmfrg==","signatures":[{"sig":"MEQCIGflBht47sgYPIZrqrXdMaQi6WiXVYp9em8NmL1nMwoSAiAaHaePke4pXoHrUxU/HByQTx+cJ/r2Aty7VEAqf0CVmA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":31401},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=22.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"1877bded265a5a7215d618e3787b6a65fed7ec7f","scripts":{"dev":"tsup src/index.ts --format esm --dts --watch","test":"vitest run","build":"tsup src/index.ts --format esm --dts --clean","clean":"rm -rf dist","prepack":"pnpm run build","test:watch":"vitest","test:coverage":"vitest run --coverage"},"_npmUser":{"name":"user_aivoralabs","email":"aivoralabs@aivoralabs.org"},"repository":{"url":"git+https://github.com/AiVoraLabs/agenttrail.git","type":"git"},"_npmVersion":"11.13.0","description":"Compliance receipts for AI agents — EU AI Act Article 12 audit trails","directories":{},"_nodeVersion":"26.2.0","dependencies":{"zod":"^3.25.76","uuid":"^11.0.0","@noble/ed25519":"^2.2.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","openai":"^4.0.0","vitest":"^2.0.0","typescript":"^5.5.0","@types/node":"^22.0.0","async-mutex":"^0.5.0","@faker-js/faker":"^9.0.0","proper-lockfile":"^4.1.0","@fast-check/vitest":"^0.2.0"},"_npmOperationalInternal":{"tmp":"tmp/agenttrail_0.1.0_1781286724316_0.3170528178577974","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@aivoralabs/agenttrail","version":"0.1.1","description":"Compliance receipts for AI agents — EU AI Act Article 12 audit trails","license":"MIT","type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"}},"scripts":{"build":"tsup src/index.ts --format esm --dts --clean","test":"vitest run","test:watch":"vitest","dev":"tsup src/index.ts --format esm --dts --watch","clean":"rm -rf dist","test:coverage":"vitest run --coverage","prepack":"pnpm run build"},"dependencies":{"@noble/ed25519":"^2.2.0","uuid":"^11.0.0","zod":"^3.25.76"},"devDependencies":{"@faker-js/faker":"^9.0.0","@fast-check/vitest":"^0.2.0","@types/node":"^22.0.0","async-mutex":"^0.5.0","proper-lockfile":"^4.1.0","openai":"^4.0.0","tsup":"^8.0.0","typescript":"^5.5.0","vitest":"^2.0.0"},"publishConfig":{"access":"public"},"engines":{"node":">=22.0.0"},"homepage":"https://agenttrail.aivoralabs.org","repository":{"type":"git","url":"git+https://github.com/AiVoraLabs/agenttrail.git"},"author":{"name":"AivoraLabs","email":"hello@aivoralabs.org"},"keywords":["ai-compliance","eu-ai-act","audit-trail","ai-agents","article-12","hash-chain","cryptographic-receipts","compliance","ai-governance","audit","llm","openai"],"gitHead":"ee83022922dd905b9c8c653845198f7c5b1af6b6","_id":"@aivoralabs/agenttrail@0.1.1","bugs":{"url":"https://github.com/AiVoraLabs/agenttrail/issues"},"_nodeVersion":"26.2.0","_npmVersion":"11.13.0","dist":{"integrity":"sha512-qlbFF+20UWjwYH8l96TFxZyI+Cg7zWkKpNqNxVt7/YnepbBhbCOy7K3Yhg7WtikuYFY1wnKbguS0I7Bn3ybfdg==","shasum":"a188e2f5cb7ec932b8e78fec7c1a5ba228632478","tarball":"https://registry.npmjs.org/@aivoralabs/agenttrail/-/agenttrail-0.1.1.tgz","fileCount":4,"unpackedSize":38063,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDMugv1iLt0UIPNVfLREItHaazc/SGNKVg80X+gNn5jHwIhAMio3q8Ot5y0pc2WGIaE7KW5SnczUEM+fslpVNsqAL/s"}]},"_npmUser":{"name":"user_aivoralabs","email":"aivoralabs@aivoralabs.org"},"directories":{},"maintainers":[{"name":"user_aivoralabs","email":"aivoralabs@aivoralabs.org"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agenttrail_0.1.1_1781289056075_0.6053950204770342"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-12T17:52:04.113Z","modified":"2026-06-12T18:30:56.340Z","0.1.0":"2026-06-12T17:52:04.461Z","0.1.1":"2026-06-12T18:30:56.223Z"},"bugs":{"url":"https://github.com/AiVoraLabs/agenttrail/issues"},"author":{"name":"AivoraLabs","email":"hello@aivoralabs.org"},"license":"MIT","homepage":"https://agenttrail.aivoralabs.org","keywords":["ai-compliance","eu-ai-act","audit-trail","ai-agents","article-12","hash-chain","cryptographic-receipts","compliance","ai-governance","audit","llm","openai"],"repository":{"type":"git","url":"git+https://github.com/AiVoraLabs/agenttrail.git"},"description":"Compliance receipts for AI agents — EU AI Act Article 12 audit trails","maintainers":[{"name":"user_aivoralabs","email":"aivoralabs@aivoralabs.org"}],"readme":"# @aivoralabs/agenttrail\n\n[![npm version](https://img.shields.io/npm/v/@aivoralabs/agenttrail?color=CB3837&logo=npm)](https://www.npmjs.com/package/@aivoralabs/agenttrail)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript)](https://www.typescriptlang.org/)\n[![EU AI Act](https://img.shields.io/badge/EU_AI_Act-Art._12-003399)](https://artificialintelligenceact.eu/article/12/)\n\n**Cryptographic audit trail SDK for AI agents. EU AI Act Article 12 compliance.**\n\nAgentTrail generates tamper-proof audit receipts for every AI agent interaction. SHA-256 hash chain + Ed25519 signatures. Zero data retention — receipts stay in your infrastructure.\n\nThis package (`@aivoralabs/agenttrail`) is the **core SDK**. It provides hash chaining, receipt building, Ed25519 signing, PII redaction, and JSONL storage.\n\nPart of the [AgentTrail monorepo](https://github.com/AIvoraLabs/agenttrail).\n\n**Other packages:**\n- [`@aivoralabs/agenttrail-openai`](https://www.npmjs.com/package/@aivoralabs/agenttrail-openai) — OpenAI SDK wrapper\n- [`@aivoralabs/agenttrail-vercel`](https://www.npmjs.com/package/@aivoralabs/agenttrail-vercel) — Vercel AI SDK middleware\n- [`@aivoralabs/agenttrail-cli`](https://www.npmjs.com/package/@aivoralabs/agenttrail-cli) — CLI auditor tool\n\n---\n\n## Installation\n\n```bash\nnpm install @aivoralabs/agenttrail\n# or\npnpm add @aivoralabs/agenttrail\n# or\nyarn add @aivoralabs/agenttrail\n```\n\nRequires **Node.js >= 22**.\n\n---\n\n## Quick Start\n\n```typescript\nimport { AuditReceipt, JSONLFileWriter } from '@aivoralabs/agenttrail';\n\nconst auditor = new AuditReceipt({\n  agentId: 'legal-ai',\n  storage: new JSONLFileWriter('./audit-logs'),\n  complianceConfig: {\n    mode: 'strict',           // fail-closed: agent won't respond if receipt fails\n    redactPII: true,          // redact emails, phones, SSNs before storage\n  },\n});\n\nconst receipt = await auditor.record({\n  input: 'Review contract clause 3.2 regarding liability limits',\n  output: 'Clause 3.2 limits liability to $500,000. Recommend flagging for legal review.',\n  model: 'gpt-4o',\n  provider: 'openai',\n  toolCalls: [],\n  metadata: { reviewType: 'contract-analysis' },\n});\n\nconsole.log(receipt.receipt_id); // UUIDv7, time-sortable\nconsole.log(receipt.hash);       // SHA-256 hash\n```\n\n---\n\n## API Reference\n\n### `AuditReceipt`\n\nThe main class. Constructor options:\n\n| Option | Type | Required | Description |\n|--------|------|----------|-------------|\n| `agentId` | `string` | Yes | Unique identifier for this agent |\n| `storage` | `IReceiptStorage` | Yes | Storage backend (e.g., `JSONLFileWriter`) |\n| `complianceConfig` | `ComplianceConfig` | No | Compliance mode and PII settings |\n| `keyStore` | `IKeyStore` | No | Ed25519 key management |\n\n**`complianceConfig` options:**\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `mode` | `'strict' \\| 'permissive'` | `'strict'` | `strict`: fail-closed. `permissive`: log warning but continue |\n| `redactPII` | `boolean` | `false` | Enable PII redaction before storage |\n\n**Methods:**\n\n| Method | Signature | Description |\n|--------|-----------|-------------|\n| `record()` | `(interaction: Interaction) => Promise<Receipt>` | Generate a signed receipt for an interaction |\n| `getChainLength()` | `() => number` | Number of receipts in the chain |\n\n### `JSONLFileWriter`\n\nStores receipts as JSONL files with monthly rotation.\n\n```typescript\nnew JSONLFileWriter(baseDir: string)\n```\n\nFiles are named `audit-log-{agentId}-{YYYY-MM}.jsonl`.\n\n### `verifyChains()`\n\n```typescript\nasync function verifyChains(\n  receipts: Receipt[],\n  options?: { verifySignatures?: boolean; publicKeys?: KeyEntry[] }\n): Promise<Map<string, VerifyResult>>\n```\n\nVerifies hash chain integrity and optionally Ed25519 signatures for one or more agents.\n\n### `redactPII()`\n\n```typescript\nfunction redactPII(\n  text: string,\n  config?: RedactConfig\n): { redacted: string; found: string[] }\n```\n\nConfigurable PII redaction with regex rules. Default rules cover emails, phones, SSNs, credit cards.\n\n---\n\n## Receipt Structure\n\n```typescript\ninterface Receipt {\n  receipt_id: string;        // UUIDv7, time-sortable (RFC 9562)\n  agent_id: string;          // Agent identifier\n  prev_hash: string | null;  // Hash of previous receipt (null = genesis)\n  hash: string;              // SHA-256(prev_hash || canonicalJSON(payload))\n  signature: string;         // Ed25519 signature of hash\n  payload: {\n    input: string;           // PII-redacted if configured\n    output: string;          // LLM response\n    input_hash: string;      // SHA-256 of original input (pre-redaction)\n    timestamp_start: string; // ISO 8601 - interaction start\n    timestamp_end: string;   // ISO 8601 - response received\n    tokens: { prompt: number; completion: number; total: number };\n    model: string;           // e.g., 'gpt-4o'\n    provider: string;        // e.g., 'openai'\n    tool_calls: ToolCall[];  // Function calling records\n    policy_check: PolicyCheck | null; // Compliance gate result\n    key_id: string;          // Ed25519 key identifier\n    human_verifier: string | null; // Art. 14 human oversight\n  };\n  metadata: Record<string, unknown>; // Max 50 keys, depth ≤ 4\n}\n```\n\n---\n\n## Hash Chain Algorithm\n\nEach receipt's hash is computed as:\n\n```\nH₀ = SHA-256(canonicalJSON(Receipt₀.payload))\nH₁ = SHA-256(H₀ || canonicalJSON(Receipt₁.payload))\nH₂ = SHA-256(H₁ || canonicalJSON(Receipt₂.payload))\n...\n```\n\n`canonicalJSON` recursively sorts object keys before serialization — guaranteeing deterministic output across any JavaScript engine.\n\nAny modification to a receipt changes its hash and breaks the entire subsequent chain. Verify with:\n\n```typescript\nimport { verifyChains } from '@aivoralabs/agenttrail';\n\nconst result = await verifyChains(receipts);\n// { hashChainIntact: true, signaturesValid: true, verifiedSignatures: 150 }\n```\n\n---\n\n## Error Handling\n\n| Error | When |\n|-------|------|\n| `ComplianceError` | Strict mode: receipt generation failed |\n| `ValidationError` | Invalid interaction input |\n| `StorageError` | JSONL write/read failure |\n| `KeyStoreError` | Ed25519 key generation failure |\n\nIn `strict` mode, `ComplianceError` prevents the agent from responding (fail-closed). In `permissive` mode, it's logged as a warning.\n\n---\n\n## Links\n\n- 🌐 [agenttrail.aivoralabs.org](https://agenttrail.aivoralabs.org)\n- 🐙 [GitHub: AiVoraLabs/agenttrail](https://github.com/AIvoraLabs/agenttrail)\n- 📄 [EU AI Act Article 12](https://artificialintelligenceact.eu/article/12/)\n\n**License:** MIT\n","readmeFilename":"README.md"}