{"_id":"@attest-protocol/openclaw-attest","_rev":"2-aab4bc3fcc19b96c0920202b30ff3176","name":"@attest-protocol/openclaw-attest","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@attest-protocol/openclaw-attest","version":"0.1.0","keywords":["openclaw","attest-protocol","audit-trail","receipts","verifiable-credentials","ed25519"],"author":{"name":"Otto Jongerius"},"license":"MIT","_id":"@attest-protocol/openclaw-attest@0.1.0","maintainers":[{"name":"ojongerius","email":"otto.jongerius@gmail.com"}],"homepage":"https://github.com/attest-protocol/openclaw-attest#readme","bugs":{"url":"https://github.com/attest-protocol/openclaw-attest/issues"},"dist":{"shasum":"b36c8308652e7bb5bd933426db2c6cbef47abd58","tarball":"https://registry.npmjs.org/@attest-protocol/openclaw-attest/-/openclaw-attest-0.1.0.tgz","fileCount":20,"integrity":"sha512-FXd8vr4tB5AEH/mth9Xw+QTKa3yN7k+KQ7AX67BiyywS3f2U6gxl34bcCwFDTthjwHLxIrz6uQLaxAqvG196uw==","signatures":[{"sig":"MEQCIAyabxUskYCmtpopzrBdU+TaJfr9XpMyQwUfZqYSqBX0AiA7Ix3r8pHwX2GzW/tfCc6mE5p2CbZDrzN15aQZIIqRzQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":41136},"type":"module","exports":{".":{"types":"./dist/src/index.d.ts","default":"./dist/src/index.js"}},"gitHead":"423e77bcf05603e34256d11d6073d07665b77141","scripts":{"test":"vitest run","build":"tsc -p tsconfig.build.json","typecheck":"tsc --noEmit","test:coverage":"vitest run --coverage"},"_npmUser":{"name":"ojongerius","email":"otto.jongerius@gmail.com"},"openclaw":{"extensions":["./src/index.ts"]},"repository":{"url":"git+https://github.com/attest-protocol/openclaw-attest.git","type":"git"},"_npmVersion":"11.9.0","description":"Cryptographically signed audit trail for OpenClaw agent actions via Attest Protocol","directories":{},"_nodeVersion":"25.6.1","dependencies":{"@sinclair/typebox":"0.34.49","@attest-protocol/attest-ts":"^0.1.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.1.0","openclaw":"*","typescript":"^5.7.0","@types/node":"^25.5.0","@vitest/coverage-v8":"^4.1.2"},"peerDependencies":{"openclaw":">=2025.0.0"},"_npmOperationalInternal":{"tmp":"tmp/openclaw-attest_0.1.0_1774992526919_0.36871751054044255","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@attest-protocol/openclaw-attest","version":"0.2.0","description":"Cryptographically signed audit trail for OpenClaw agent actions via Attest Protocol","type":"module","license":"MIT","author":{"name":"Otto Jongerius"},"repository":{"type":"git","url":"git+https://github.com/attest-protocol/openclaw-attest.git"},"keywords":["openclaw","attest-protocol","audit-trail","receipts","verifiable-credentials","ed25519"],"exports":{".":{"types":"./dist/src/index.d.ts","default":"./dist/src/index.js"}},"bin":{"openclaw-attest":"dist/src/cli.js"},"scripts":{"build":"tsc -p tsconfig.build.json","test":"vitest run","test:coverage":"vitest run --coverage","typecheck":"tsc --noEmit"},"dependencies":{"@attest-protocol/attest-ts":"^0.1.0","@sinclair/typebox":"0.34.49"},"devDependencies":{"@types/node":"^25.5.0","@vitest/coverage-v8":"^4.1.2","openclaw":"*","typescript":"^5.7.0","vitest":"^3.1.0"},"peerDependencies":{"openclaw":">=2025.0.0"},"openclaw":{"extensions":["./src/index.ts"]},"gitHead":"67e47ad76143ad13f7444799cc908c7cdddf0afa","_id":"@attest-protocol/openclaw-attest@0.2.0","bugs":{"url":"https://github.com/attest-protocol/openclaw-attest/issues"},"homepage":"https://github.com/attest-protocol/openclaw-attest#readme","_nodeVersion":"22.22.1","_npmVersion":"11.12.1","dist":{"integrity":"sha512-Uo7vg/dofW1l7FHdaAF+8YMx58lXlVdDGiEBFfBvNQHY6TnuXodHYq4zpL3JlO1OQYVfZca1XwNj75BrmCUFQQ==","shasum":"2202c4a38d1e025c7fda79439dcd08b191493e23","tarball":"https://registry.npmjs.org/@attest-protocol/openclaw-attest/-/openclaw-attest-0.2.0.tgz","fileCount":22,"unpackedSize":76398,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@attest-protocol%2fopenclaw-attest@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBXHMeZMRYGHh4v6/zBaaVZwfhxsNOpr2mbNLHBMwOwhAiEA6tQpoqqExChxAj5vjnuWTCCkO8Y/GGurTncEd4pEY58="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:ad36e8ce-0d42-483a-9baf-e476a88403c1"}},"directories":{},"maintainers":[{"name":"ojongerius","email":"otto.jongerius@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/openclaw-attest_0.2.0_1775025606361_0.5803136082702773"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-31T21:28:46.789Z","modified":"2026-04-01T06:40:06.767Z","0.1.0":"2026-03-31T21:28:47.057Z","0.2.0":"2026-04-01T06:40:06.523Z"},"bugs":{"url":"https://github.com/attest-protocol/openclaw-attest/issues"},"author":{"name":"Otto Jongerius"},"license":"MIT","homepage":"https://github.com/attest-protocol/openclaw-attest#readme","keywords":["openclaw","attest-protocol","audit-trail","receipts","verifiable-credentials","ed25519"],"repository":{"type":"git","url":"git+https://github.com/attest-protocol/openclaw-attest.git"},"description":"Cryptographically signed audit trail for OpenClaw agent actions via Attest Protocol","maintainers":[{"name":"ojongerius","email":"otto.jongerius@gmail.com"}],"readme":"\n\n# openclaw-attest\n\n### Attest Protocol plugin for OpenClaw\n\n[](https://www.npmjs.com/package/@attest-protocol/openclaw-attest)\n[](LICENSE)\n[](https://www.typescriptlang.org/)\n[](https://github.com/attest-protocol/openclaw-attest/actions/workflows/ci.yml)\n\n---\n\nCryptographically signed, hash-linked audit trail for every tool call an OpenClaw agent makes.\n\nBuilt on [`@attest-protocol/attest-ts`](https://github.com/attest-protocol/attest-ts) and [`@sinclair/typebox`](https://github.com/sinclairzx81/typebox).\n\n[Spec](https://github.com/attest-protocol/spec) • [TypeScript SDK](https://github.com/attest-protocol/attest-ts) • [Python SDK](https://github.com/attest-protocol/attest-py)\n\n
\n\n---\n\n## What it looks like\n\nAfter a session where the agent reads files, runs a command, browses a page, and writes output, querying the audit trail returns:\n\n```json\n{\n \"total_receipts\": 5,\n \"total_chains\": 1,\n \"by_risk\": { \"low\": 4, \"high\": 1 },\n \"by_status\": { \"success\": 4, \"failure\": 1 },\n \"by_action\": {\n \"filesystem.file.read\": 2,\n \"filesystem.file.create\": 1,\n \"system.command.execute\": 1,\n \"system.browser.navigate\": 1\n },\n \"results\": [\n { \"id\": \"rec-…01\", \"timestamp\": \"2026-04-01T02:10:01Z\", \"action\": \"filesystem.file.read\", \"risk\": \"low\", \"target\": \"read_file\", \"status\": \"success\", \"sequence\": 1 },\n { \"id\": \"rec-…02\", \"timestamp\": \"2026-04-01T02:10:02Z\", \"action\": \"filesystem.file.read\", \"risk\": \"low\", \"target\": \"read_file\", \"status\": \"failure\", \"sequence\": 2 },\n { \"id\": \"rec-…03\", \"timestamp\": \"2026-04-01T02:10:03Z\", \"action\": \"system.command.execute\", \"risk\": \"high\", \"target\": \"run_command\", \"status\": \"success\", \"sequence\": 3 },\n { \"id\": \"rec-…04\", \"timestamp\": \"2026-04-01T02:10:04Z\", \"action\": \"system.browser.navigate\", \"risk\": \"low\", \"target\": \"browser_navigate\", \"status\": \"success\", \"sequence\": 4 },\n { \"id\": \"rec-…05\", \"timestamp\": \"2026-04-01T02:10:05Z\", \"action\": \"filesystem.file.create\", \"risk\": \"low\", \"target\": \"write_file\", \"status\": \"success\", \"sequence\": 5 }\n ]\n}\n```\n\nVerifying the chain confirms nothing was tampered with:\n\n```\nChain \"chain_openclaw_main_sid-42\" is valid: 5 receipts, all signatures and hash links verified.\n```\n\nEvery receipt is a signed [W3C Verifiable Credential](https://www.w3.org/TR/vc-data-model-2.0/) — parameters are hashed (never stored in plaintext), and each receipt is hash-linked to the previous one, forming a tamper-evident chain.\n\n---\n\n## Why receipts?\n\nAI agents that read files, run commands, and browse the web are powerful — but that power needs accountability. When an agent operates autonomously, you need to know exactly what it did, prove that the record hasn't been tampered with, and keep sensitive details private.\n\n**Use cases:**\n\n- **Post-incident review** — your agent ran overnight and something broke. The receipt chain shows exactly which commands it ran, in what order, and whether each succeeded or failed — with cryptographic proof that the log hasn't been altered after the fact.\n- **Compliance and audit** — regulated environments require evidence of what systems did and why. Receipts are W3C Verifiable Credentials with Ed25519 signatures, giving auditors a tamper-evident trail they can independently verify.\n- **Safer autonomous agents** — the agent can query its own audit trail mid-session. Before taking a high-risk action, it can check what it has already done and whether previous steps succeeded, enabling self-correcting workflows.\n- **Multi-agent trust** — when agents collaborate, receipts serve as proof of prior actions. Agent B can verify that Agent A actually completed step 1 before proceeding to step 2, without trusting a shared log.\n- **Cost and usage tracking** — every tool call is classified by type and risk level, giving you a structured breakdown of what your agent spent its time on across sessions.\n\n### Beyond local storage\n\nToday, receipts are stored locally in SQLite — fully under your control. The [Attest Protocol](https://github.com/attest-protocol/spec) is designed for receipts to travel further when you choose: publishing to a shared ledger, forwarding to a compliance system, or exchanging with other agents as proof of prior actions. The receipts are portable W3C Verifiable Credentials, but where they go is always your decision.\n\n## How it works\n\nEvery time the OpenClaw agent executes a tool, this plugin:\n\n1. **Classifies the action** using the [Attest Protocol taxonomy](https://github.com/attest-protocol/spec/tree/main/spec/taxonomy)\n2. **Creates a signed receipt** — a [W3C Verifiable Credential](https://www.w3.org/TR/vc-data-model-2.0/) with Ed25519 proof\n3. **Hash-links it** into a per-session chain (tamper-evident)\n4. **Stores it** in a local SQLite database\n\nThe agent also gets two introspection tools to query and verify its own audit trail.\n\n```\nOpenClaw Gateway\n │\n ├─ before_tool_call ──► capture params + timing\n │\n ├─ [tool executes]\n │\n └─ after_tool_call ──► classify → sign → chain → store\n```\n\n## Install\n\n```bash\nopenclaw plugins install @attest-protocol/openclaw-attest\n```\n\nThen enable the plugin in your OpenClaw config. See [`docs/INSTALL.md`](docs/INSTALL.md) for tool visibility setup and configuration options.\n\n## CLI — Receipt Explorer\n\nQuery and verify receipts outside of agent sessions, useful for auditing and debugging.\n\n```bash\n# Query all receipts\nnpx @attest-protocol/openclaw-attest receipts\n\n# Filter by risk level\nnpx @attest-protocol/openclaw-attest receipts --risk high\n\n# Filter by action type and output as JSON\nnpx @attest-protocol/openclaw-attest receipts --action system.command.execute --json\n\n# Verify all chains\nnpx @attest-protocol/openclaw-attest verify\n\n# Verify a specific chain\nnpx @attest-protocol/openclaw-attest verify --chain chain_openclaw_main_sid-42\n\n# Export a chain as JSON-LD (full W3C Verifiable Credentials)\nnpx @attest-protocol/openclaw-attest export --chain chain_openclaw_main_sid-42\n\n# Export as a W3C Verifiable Presentation envelope\nnpx @attest-protocol/openclaw-attest export --chain chain_openclaw_main_sid-42 --format presentation\n\n# Export a single receipt by ID\nnpx @attest-protocol/openclaw-attest export --id urn:receipt:abc-123\n```\n\nRun `npx @attest-protocol/openclaw-attest --help` for all options including `--status`, `--limit`, and `--db`.\n\n## Agent tools\n\n### `attest_query_receipts`\n\nSearch the audit trail by action type, risk level, or outcome status. Returns receipt summaries and aggregate statistics.\n\n```\n> Query all high-risk actions from this session\n\n{\n \"total_receipts\": 12,\n \"results\": [\n { \"action\": \"filesystem.file.delete\", \"risk\": \"high\", \"target\": \"delete_file\", \"status\": \"success\", \"sequence\": 7 },\n { \"action\": \"system.command.execute\", \"risk\": \"high\", \"target\": \"run_command\", \"status\": \"success\", \"sequence\": 3 }\n ]\n}\n```\n\n### `attest_verify_chain`\n\nCryptographically verify the integrity of the receipt chain. Checks Ed25519 signatures, hash links, and sequence numbering.\n\n```\n> Verify the audit trail for this session\n\nChain \"chain_openclaw_main_sid-42\" is valid: 12 receipts, all signatures and hash links verified.\n```\n\n## What's in a receipt?\n\nEach receipt is a W3C Verifiable Credential signed with Ed25519, recording:\n\n| Field | What it captures |\n|:---|:---|\n| **Issuer** | Which agent performed the action (`did:openclaw:`) |\n| **Principal** | Which session authorized it (`did:session:`) |\n| **Action** | What happened — classified type, risk level, target tool |\n| **Outcome** | Success/failure status and error details |\n| **Chain** | Sequence number + SHA-256 hash link to previous receipt |\n| **Privacy** | Parameters are hashed, never stored in plaintext |\n| **Proof** | Ed25519Signature2020 with verification method |\n\n## Taxonomy\n\nThe plugin maps OpenClaw tool names to Attest Protocol action types:\n\n| OpenClaw tool | Action type | Risk |\n|:---|:---|:---|\n| `read_file` | `filesystem.file.read` | low |\n| `write_file` | `filesystem.file.create` | low |\n| `edit_file` | `filesystem.file.modify` | medium |\n| `delete_file` | `filesystem.file.delete` | high |\n| `run_command` | `system.command.execute` | high |\n| `browser_navigate` | `system.browser.navigate` | low |\n| `browser_click` | `system.browser.form_submit` | medium |\n| `send_message` | `system.application.control` | medium |\n\nSee [`taxonomy.json`](taxonomy.json) for the full 20-tool mapping. Override with a custom file via the `taxonomyPath` config option.\n\n## Configuration\n\nAll settings are optional — the plugin works out of the box with sensible defaults.\n\n| Setting | Default | Description |\n|:---|:---|:---|\n| `enabled` | `true` | Generate receipts for tool calls |\n| `dbPath` | `~/.openclaw/attest/receipts.db` | SQLite receipt database path |\n| `keyPath` | `~/.openclaw/attest/keys.json` | Ed25519 signing key pair path |\n| `taxonomyPath` | _(bundled)_ | Custom tool-to-action-type mapping |\n\nEd25519 signing keys are generated automatically on first run and persisted to `keyPath`.\n\n## Project structure\n\n```\nsrc/\n index.ts # Plugin entry — wires hooks, tools, service\n cli.ts # Receipt Explorer CLI (npx @attest-protocol/openclaw-attest)\n hooks.ts # before_tool_call / after_tool_call → receipt creation\n classify.ts # Tool name → action type + risk level classification\n chain.ts # Per-session hash-linked chain state\n tools.ts # attest_query_receipts + attest_verify_chain\n config.ts # Config resolution + Ed25519 key management\ntaxonomy.json # Default OpenClaw tool → action type mappings\n```\n\n## Development\n\n```sh\npnpm install\npnpm test # run the test suite\npnpm run typecheck # TypeScript strict mode\npnpm test:coverage # with V8 coverage\n```\n\n| | |\n|:---|:---|\n| **Language** | TypeScript ESM, strict mode |\n| **Testing** | Vitest (colocated `*.test.ts` files) |\n| **Runtime deps** | `@attest-protocol/attest-ts` + `@sinclair/typebox` |\n\n## Ecosystem\n\n| Repository | Description |\n|:---|:---|\n| [attest-protocol/spec](https://github.com/attest-protocol/spec) | Protocol specification, JSON Schemas, canonical taxonomy |\n| [attest-protocol/attest-ts](https://github.com/attest-protocol/attest-ts) | TypeScript SDK |\n| [attest-protocol/attest-py](https://github.com/attest-protocol/attest-py) | Python SDK ([PyPI](https://pypi.org/project/attest-protocol/)) |\n| **attest-protocol/openclaw-attest** (this plugin) | OpenClaw integration |\n| [ojongerius/attest](https://github.com/ojongerius/attest) | MCP proxy + CLI (reference implementation) |\n\n## License\n\nMIT\n","readmeFilename":"README.md"}