{"_id":"@8k4protocol/plugin-trust","_rev":"2-af9b802b973892e670d5cf795ba9e43c","name":"@8k4protocol/plugin-trust","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@8k4protocol/plugin-trust","version":"0.1.0","keywords":["elizaos","plugin","trust","8k4","erc-8004","agent-trust"],"license":"MIT","_id":"@8k4protocol/plugin-trust@0.1.0","maintainers":[{"name":"8k4protocol","email":"info@8k4protocol.com"}],"homepage":"https://github.com/8k4-Protocol/plugin-8k4-trust#readme","bugs":{"url":"https://github.com/8k4-Protocol/plugin-8k4-trust/issues"},"dist":{"shasum":"c1eefe7a671fe7dfaa552d64dafb2a6b94b1bb96","tarball":"https://registry.npmjs.org/@8k4protocol/plugin-trust/-/plugin-trust-0.1.0.tgz","fileCount":21,"integrity":"sha512-jlgqE6ZtqpIZtHSIBWueWGPBkZyLoI2Q62otJu1MR8Zspp5RsQUO4ZIObtCBlMYLa7yTHmFzT7afBaVHGdZ3Mg==","signatures":[{"sig":"MEYCIQDrAWe7B+EXFABHjtShY5Tp7tMtf2OdFwu/3Q2FEPAH6wIhAN+qBrovF2nXJI0Us2IgkUzA5yZ5Yj7xQ/WDT5IJsDCJ","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":53689},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","elizaos":{"name":"@8k4protocol/plugin-trust","type":"plugin","category":"trust-and-safety","displayName":"8K4 Trust Plugin"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"70e3d3b0828f41f15c2759bde947ed48cab6b72f","scripts":{"dev":"tsc --watch","test":"vitest run","build":"tsc","prepublishOnly":"npm run build && npm run test"},"_npmUser":{"name":"8k4protocol","email":"info@8k4protocol.com"},"repository":{"url":"git+https://github.com/8k4-Protocol/plugin-8k4-trust.git","type":"git"},"_npmVersion":"10.9.4","description":"8K4 Protocol trust scoring plugin for ElizaOS — check agent trust scores before interacting","directories":{},"_nodeVersion":"22.22.0","_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.2.4","typescript":"^5.9.3"},"peerDependencies":{"@elizaos/core":">=1.0.0"},"_npmOperationalInternal":{"tmp":"tmp/plugin-trust_0.1.0_1773130784135_0.7425918820411328","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@8k4protocol/plugin-trust","version":"0.1.1","description":"8K4 Protocol trust scoring plugin for ElizaOS — check agent trust scores before interacting","type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsc","dev":"tsc --watch","test":"vitest run","prepublishOnly":"npm run build && npm run test"},"peerDependencies":{"@elizaos/core":">=1.0.0"},"devDependencies":{"typescript":"^5.9.3","vitest":"^3.2.4"},"keywords":["elizaos","plugin","trust","8k4","erc-8004","agent-trust"],"license":"MIT","repository":{"type":"git","url":"git+https://github.com/8k4-Protocol/plugin-8k4-trust.git"},"homepage":"https://github.com/8k4-Protocol/plugin-8k4-trust#readme","bugs":{"url":"https://github.com/8k4-Protocol/plugin-8k4-trust/issues"},"elizaos":{"type":"plugin","name":"@8k4protocol/plugin-trust","displayName":"8K4 Trust Plugin","category":"trust-and-safety"},"_id":"@8k4protocol/plugin-trust@0.1.1","gitHead":"0d6847506a4b43c4193c7ffb77567cd8d959ef4b","_nodeVersion":"22.22.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-ZkCi535ACxvXoWGvWl0lRBnxcHxS5trF+Exdw625Ejeo0E0CU6hZ/1G/kSN0Dy3N9QEnM8WYbDY8VG7vfSdYqg==","shasum":"c7e3e07a6b9366e3a296bfee051178d85ce45acb","tarball":"https://registry.npmjs.org/@8k4protocol/plugin-trust/-/plugin-trust-0.1.1.tgz","fileCount":21,"unpackedSize":66336,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICmGq+yT0x7S8m+O5BI2mqkplma6ca0KDL4CyGzv/Of3AiEA8laTi4YQCkUXM5nz86RqtIPbbpuFACi6XTqPVmQ8U34="}]},"_npmUser":{"name":"8k4protocol","email":"info@8k4protocol.com"},"directories":{},"maintainers":[{"name":"8k4protocol","email":"info@8k4protocol.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/plugin-trust_0.1.1_1773173925858_0.2903596664681878"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-10T08:19:44.015Z","modified":"2026-03-10T20:18:46.130Z","0.1.0":"2026-03-10T08:19:44.279Z","0.1.1":"2026-03-10T20:18:46.024Z"},"bugs":{"url":"https://github.com/8k4-Protocol/plugin-8k4-trust/issues"},"license":"MIT","homepage":"https://github.com/8k4-Protocol/plugin-8k4-trust#readme","keywords":["elizaos","plugin","trust","8k4","erc-8004","agent-trust"],"repository":{"type":"git","url":"git+https://github.com/8k4-Protocol/plugin-8k4-trust.git"},"description":"8K4 Protocol trust scoring plugin for ElizaOS — check agent trust scores before interacting","maintainers":[{"name":"8k4protocol","email":"info@8k4protocol.com"}],"readme":"# @8k4protocol/plugin-trust\n\n`@8k4protocol/plugin-trust` adds trust-aware behavior to ElizaOS agents using 8K4 Protocol trust APIs: explicit trust checks (`CHECK_AGENT_TRUST`), trusted counterparty discovery (`FIND_TRUSTED_AGENT`), a pre-evaluator trust guard (`off/warn/block`), and a lightweight trust context provider powered by free `/agents/top` data.\n\n## Install\n\n```bash\nbun add @8k4protocol/plugin-trust\n```\n\n(or `npm i @8k4protocol/plugin-trust`)\n\n## What this plugin gives you\n\n- `CHECK_AGENT_TRUST` — check trust for an ERC-8004 agent ID or wallet\n- `FIND_TRUSTED_AGENT` — search for trusted counterparties for a task\n- trust guard pre-evaluator — warn or block before low-trust interactions\n- trust context provider — inject current `/agents/top` trust context into runtime\n\n## Development / Local Install\n\nClone and link locally:\n\n```bash\ngit clone https://github.com/8k4-Protocol/plugin-8k4-trust\ncd plugin-8k4-trust\nbun install\nbun run build\nbun link\n\n# In your ElizaOS project:\nbun link @8k4protocol/plugin-trust\n```\n\n## Register in your character\n\n```ts\nimport trustPlugin from \"@8k4protocol/plugin-trust\";\n\nexport default {\n  name: \"MyAgent\",\n  plugins: [trustPlugin],\n};\n```\n\nOr in JSON-style character configs:\n\n```json\n{\n  \"name\": \"TrustTestAgent\",\n  \"plugins\": [\"@8k4protocol/plugin-trust\"]\n}\n```\n\n## Configuration\n\n| Setting | Required | Default | Description |\n|---|---:|---|---|\n| `EIGHTK4_API_KEY` | No* | _(unset)_ | API key used for paid endpoints. Required unless paid calls are handled via x402. |\n| `EIGHTK4_API_BASE` | No | `https://api.8k4protocol.com` | Base URL for 8K4 API. |\n| `EIGHTK4_DEFAULT_CHAIN` | No | `eth` | Default chain for score/search calls. |\n| `EIGHTK4_GUARD_MODE` | No | `warn` | Trust guard mode: `off`, `warn`, or `block`. |\n| `EIGHTK4_GUARD_FAIL_MODE` | No | derived | Enforcement failure behavior: `open` or `closed`. Defaults to `open` in `warn` mode and `closed` in `block` mode unless explicitly set. |\n| `EIGHTK4_GUARD_BLOCK_THRESHOLD` | No | `30` | In `block` mode, block if score is below this threshold or trust tier is `minimal`/`new`. |\n| `EIGHTK4_GUARD_CAUTION_THRESHOLD` | No | `60` | In `warn`/`block` mode, warn if score is below this threshold. |\n| `EIGHTK4_CACHE_TTL_MS` | No | `300000` | In-memory cache TTL for trust/search/top responses. Clamped to `1000..3600000`. |\n| `EIGHTK4_CACHE_MAX_ENTRIES` | No | `500` | Maximum in-memory cache entries before oldest entries are evicted. Clamped to `50..10000`. |\n| `EIGHTK4_TIMEOUT_MS` | No | `8000` | HTTP timeout per request. Clamped to `500..30000`. |\n| `EIGHTK4_ALLOW_CUSTOM_API_BASE` | No | `false` | Permit non-default HTTPS API hosts. Without this, non-default hosts are rejected and the default API base is used. |\n\n\\* Paid endpoints need API key or x402 micropayment flow.\n\n## Quickstart\n\nMinimal setup (free features only — trust context provider, no paid lookups):\n\n```env\n# No API key needed for free endpoints\nEIGHTK4_GUARD_MODE=warn\n```\n\nFull setup (paid trust checks + guard enforcement):\n\n```env\nEIGHTK4_API_KEY=your-api-key-here\nEIGHTK4_GUARD_MODE=block\n# block mode defaults to fail-closed — no need to set EIGHTK4_GUARD_FAIL_MODE\n```\n\n## Tested runtime status\n\nValidated in a live ElizaOS runtime with:\n- plugin boot/loading\n- `CHECK_AGENT_TRUST`\n- `FIND_TRUSTED_AGENT`\n- bare-number negative case (`roadmap 2026 has 3 milestones`)\n- browser UI response path\n\n## Security model\n\nThe plugin applies several hardening measures by default:\n\n- **No bare-number inference.** The plugin will never treat a random number in conversation as an agent ID. Only explicit forms are accepted: `parameters.agentId`, wallet addresses (`0x...`), or text patterns like `agent:6888`, `agent_id=6888`, `erc8004:6888`, `8k4:6888`.\n- **Fail-closed in block mode.** If the trust API is unreachable while the guard is set to `block`, the plugin blocks the interaction rather than silently allowing it. This is configurable via `EIGHTK4_GUARD_FAIL_MODE`.\n- **API base is locked down.** Only `https://` is accepted. Non-default hosts are rejected unless `EIGHTK4_ALLOW_CUSTOM_API_BASE=true` is set, preventing accidental credential leakage to wrong hosts.\n- **Inputs are clamped.** Agent IDs, search limits, score thresholds, query lengths, timeouts, and cache sizes are all bounded to sane ranges regardless of what the caller passes.\n- **Cache is bounded.** The in-memory cache has a max entry count with LRU eviction and deduplicates concurrent in-flight requests to the same endpoint to avoid redundant paid calls.\n- **Provider context is sandboxed.** Data injected into model context is framed as untrusted reference material, serialized as structured data, and sanitized to strip control characters and injection-prone tokens.\n\n**Operator responsibility:** The plugin reduces accidental spend through caching, input clamping, and deduplication, but does not implement per-user rate limits or budget caps. Production deployments should enforce these at the host/gateway level.\n\n## Actions\n\n### `CHECK_AGENT_TRUST`\nChecks trust by **agent ID (integer ERC-8004 token ID)** or wallet address.\n\nExample prompts:\n- \"Check trust for agent 6888 on eth\"\n- \"Check trust for wallet 0xabc... on base\"\n- \"Explain trust for agent 6888\"\n\nParameters:\n- `agentId` (required) — numeric agent ID or wallet `0x...`\n- `chain` (optional)\n- `explain` (optional boolean)\n\nOutput includes:\n- `score`\n- `score_tier`\n- `trust_tier`\n- `confidence`\n- `adjusted`\n- `adjustment_reasons`\n- optional `positives/cautions` when `explain=true`\n\n### `FIND_TRUSTED_AGENT`\nFinds trusted counterparties for a task using `/agents/search`.\n\nExample prompts:\n- \"Find me a trusted agent for token swaps\"\n- \"Search trusted liquidation bot agents on base with score above 70\"\n\nParameters:\n- `query` (required)\n- `chain` (optional)\n- `minScore` (optional, default `60`)\n- `limit` (optional, default `20`)\n\n## Trust guard (pre-evaluator)\n\nMode behavior:\n- `off`: no trust guard checks.\n- `warn`: message is allowed, but warning context is injected when trust is low or the score falls below the caution threshold.\n- `block`: minimal/new-trust interactions or scores below the block threshold are blocked before normal response processing.\n\nExample settings:\n\n```env\nEIGHTK4_GUARD_MODE=warn\nEIGHTK4_GUARD_FAIL_MODE=open\nEIGHTK4_GUARD_CAUTION_THRESHOLD=60\n```\n\n```env\nEIGHTK4_GUARD_MODE=block\nEIGHTK4_GUARD_FAIL_MODE=closed\nEIGHTK4_GUARD_BLOCK_THRESHOLD=30\n```\n\n## Provider: trust context\n\nThe provider calls **free** endpoint `/agents/top` and injects a ranked trust snapshot into runtime state (`8k4_trust_context`). This gives the model up-to-date trusted-agent context even when no API key is configured.\n\n## x402 synergy\n\n8K4 paid endpoints support x402 micropayments. If `EIGHTK4_API_KEY` is not set, this plugin can use an available `plugin-x402` payment fetch path for paid calls (when configured in runtime). This allows trust checks/search over paid endpoints without hard-coding API key auth.\n\n## API caveats / rate limits\n\n- Free endpoints: `/agents/top`, `/stats/public`, `/health`\n- Paid endpoints used by this plugin: `/agents/{agent_id}/score`, `/agents/{agent_id}/score/explain`, `/agents/search`, `/wallet/{wallet}/score`\n- Add caching and sane call frequency to avoid rate-limit pressure.\n\n## Notes\n\n- `agent_id` is an integer token ID, not an EVM address.\n- Use wallet endpoints for `0x...` identifiers.\n- Bare numbers in arbitrary free text are intentionally ignored; use explicit forms like `agent:6888` or pass `parameters.agentId`.\n- `EIGHTK4_API_BASE` must be HTTPS. Non-default hosts require `EIGHTK4_ALLOW_CUSTOM_API_BASE=true`.\n- Guard enforcement failure behavior is explicit: `warn` mode defaults to fail-open, while `block` mode defaults to fail-closed unless overridden.\n\n## Troubleshooting\n\n**\"Paid 8K4 endpoint requires EIGHTK4_API_KEY or plugin-x402...\"**\nSet `EIGHTK4_API_KEY` in your character settings or configure `@elizaos/plugin-x402` for micropayments. Free features (trust context provider, `/agents/top`) work without a key.\n\n**Trust guard blocks everything after an API outage**\nIn `block` mode, the guard defaults to fail-closed. If you prefer fail-open during outages, set `EIGHTK4_GUARD_FAIL_MODE=open`.\n\n**\"EIGHTK4_API_BASE host rejected\"**\nThe plugin only allows `api.8k4protocol.com` by default. For staging/custom hosts, set `EIGHTK4_ALLOW_CUSTOM_API_BASE=true`.\n\n**Agent ID not recognized from conversation text**\nThe plugin intentionally ignores bare numbers. Use explicit forms: `agent:6888`, `agent_id=6888`, `erc8004:6888`, or `8k4:6888`. Or pass the ID via `parameters.agentId`.\n\n## Publish checklist\n\nBefore publishing publicly:\n- run `npm install`\n- run `npm run build`\n- run `npm run test`\n- verify install/link in a clean ElizaOS project\n- confirm package scope/ownership on npm\n\n## References\n\n- 8K4 Protocol API base: `https://api.8k4protocol.com`\n- 8K4 docs: `https://docs.8k4protocol.com`\n- ElizaOS x402 plugin: `@elizaos/plugin-x402`\n","readmeFilename":"README.md"}