Repository navigation
Expand file tree
/
Copy pathllms.txt
More file actions
63 lines (49 loc) · 7.22 KB
/
Copy pathllms.txt
File metadata and controls
63 lines (49 loc) · 7.22 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
# AgentGuard
> A spending firewall for AI agents on NEAR. Funds stay in an on-chain vault owned by a person, DAO or multisig. The agent holds only a function-call key that can call `request_spend`. A smart contract decides each request against the owner's policy, optionally with a signed verdict from a prompt-injection risk oracle running in a TEE (Intel TDX via OutLayer). Every request ends as executed, pending (owner approval) or denied, with a reason code.
NEAR hackathon entry, 1–14 Nov 2026. Tracks: security, agents, business, privacy. License: MIT.
## Key facts
- Live contract: guard.cm-agentguard.testnet (NEAR testnet). Public demo vault: id 6. TEE vault: id 11, whose only oracle is the TEE verdict key (its activity shows a TEE-verified payment paid, an injected invoice refused with oracle_denied, and a spend without a verdict held).
- Live app: https://agentguard-beryl.vercel.app (demo vault: https://agentguard-beryl.vercel.app/?contract=guard.cm-agentguard.testnet&network=testnet&vault=6#/app). Demo video: https://agentguard-beryl.vercel.app/agentguard-demo.mp4. Demo post on X: https://x.com/MyCryptoWallet/status/2116833046041416166.
- Fastest check: README "Judge walkthrough: do X, see Y". Read-only live check with no install: `node --experimental-strip-types scripts/verify-live.ts` (exit 0 = deployed code matches docs/TESTNET.md).
- Languages: Rust (contract, TEE oracle), TypeScript (SDK, MCP server, oracle, web app).
- Agent interface: MCP server with 4 tools: agentguard_budget, agentguard_pay, agentguard_pending, agentguard_swap_status.
- Outcomes: executed | pending(reason) | denied(reason). Each emits a NEP-297 event with the agent's stated purpose.
- Policy: token allowlist, per-tx cap, per-period limit, recipient allow/deny lists, hourly rate limit with auto-pause, auto-approve threshold, new-recipient approval, optional oracle verdict above an amount.
- The dashboard is optional: every owner action is a plain contract call (get_vault, get_pending, approve_pending, reject_pending, pause, unpause, withdraw, deposit_near, update_policy, set_agent, set_oracle, create_vault). README "No dashboard needed" and dashboard/src/cli.ts give near-cli-rs commands.
- Owners hear about held payments: the dashboard's activity log rebuilds each vault's history from the contract's NEP-297 events (dashboard/src/activity.ts, via FastNEAR's tx API), the dashboard can send browser notifications, and `agentguard-watch` (mcp/src/watch.ts) pushes alerts to ntfy, Slack/Discord webhooks or Telegram with the dashboard closed.
- For browsing agents: the web app serves /llms.txt and /.well-known/ard.json, and registers read-only WebMCP tools (agentguard_get_vault, agentguard_list_pending, agentguard_open_vault) in dashboard/src/webmcp.ts.
- Kill switch: `pause` (no deposit needed); `set_agent(None)` revokes the agent; withdraw works while paused.
- Oracle verdict: ed25519 over (contract, vault, request incl. nonce, verdict, expiry). Score ≥35 review, ≥70 deny.
- Cross-chain: NEAR Intents 1Click quotes, checked by a binding verifier (signature, deposit address, recipient/chain, refund to owner, exact amount, deadline, ≤3% value loss).
## Claims and evidence
- Policy decisions are correct and ordered: contract/src/policy.rs; 47 tests in contract/src/tests.rs (`cd contract && cargo test`).
- Verdicts cannot be forged, replayed, swapped or used after expiry: contract/src/attestation.rs; tests in contract/src/tests.rs; golden vector shared with sdk/ (`npm test`).
- Prompt-injection detection (hidden Unicode tags, zero-width/bidi, instruction overrides, secrecy and payment demands, address poisoning): oracle/src/injection.ts, oracle/src/rules.ts; 33 oracle tests as `node --test` counts them (23 `test(` blocks; intents.test.ts makes one test per tampering case in a loop).
- TEE oracle matches the TypeScript oracle: tee-oracle/src; 21 tests pinned by shared vectors (`cd tee-oracle && cargo test --lib`). Published separately: https://github.com/CodeMasterLabs/agentguard-tee-oracle (v0.1.0). That GitHub release is the WASM's only hosting; a run failing with `wasm_url could not be fetched` is a hosting problem, not the oracle — see the tester note in docs/TESTNET.md.
- Owner actions work from a real wallet: vault 13 on testnet (Meteor via NEAR Connect): create_vault, set_agent, approve_pending, reject_pending, pause, withdraw while paused, unpause, update_policy, each checked on-chain.
- Works on a live chain: docs/TESTNET.md (13 policy scenarios, 9 cross-chain checks, 5 TEE-oracle checks, wasm hash, output); scripts/e2e-*.ts.
- Optional LLM pass (TypeScript oracle only; the TEE oracle is rules only): any OpenAI-compatible endpoint, can only raise risk, falls back to the rules with `llm_unavailable` if the endpoint fails; sends up to 4,000 characters of context to that endpoint. Live runs through NEAR AI Cloud on 2026-11-11 (deepseek-ai/DeepSeek-V4.1-Flash-1017, listed as verifiable; anthropic/claude-opus-5-5, listed as external), same result with both: honest invoice allowed, injection denied, and a vendor-change scam that no rule flags denied. docs/TESTNET.md "Oracle LLM pass, live run"; oracle/src/llm.ts; test in oracle/test/oracle.test.ts.
- Agent key is restricted: scripts/provision-agent.ts creates a function-call key limited to request_spend.
- Threats considered: docs/THREAT_MODEL.md, 28 threats, each with its mitigation and evidence (a unit test or script for 22; a testnet run, the TEE manifest or a design note for the rest), plus known limitations.
## File map
- contract/src/lib.rs: vaults, custody, approvals, pause, withdraw, settlement and refunds.
- contract/src/policy.rs: pure decision function and reason codes.
- contract/src/attestation.rs: verdict message and signature check.
- sdk/src: TypeScript clients (viewer, agent, owner), verdict encoding, unit conversion, chain-prefixed addresses.
- mcp/src/index.ts: MCP server and its 4 tools; mcp/src/oneclick.ts: 1Click quotes.
- oracle/src: HTTP service (server.ts), rules, injection detection, cross-chain verifier (intents.ts), optional LLM (llm.ts), signer, TEE gateway (gateway.ts).
- tee-oracle/: OutLayer WASI P2 component (Rust) and wasmtime harness.
- dashboard/src: web app. landing.tsx (#/), onboarding.tsx (#/start, 6-step setup), docs.tsx (#/docs), App.tsx (routes, wallet), vault.tsx (#/app, owner dashboard), activity.ts (vault history from events), chrome.tsx (header/footer), near.ts (RPC, wallet).
- scripts/: provision-agent.ts, seed-demo-vault.ts, demo-policy.json, e2e-testnet.ts, e2e-intents-testnet.ts, e2e-tee-testnet.ts.
## Run
- All unit tests: `cd contract && cargo test`; `cd tee-oracle && cargo test --lib`; `npm install && npm run build && npm test`.
- Held-payment alerts: `npm run build -w sdk -w mcp`, then `AGENTGUARD_CONTRACT=... AGENTGUARD_VAULT_ID=... ALERT_NTFY_URL=... node mcp/dist/watch.js`
- Web app: `npm run dev -w dashboard`, then http://localhost:5173/?contract=guard.cm-agentguard.testnet&vault=6
- Local oracle: `PORT=8787 ORACLE_SEED_HEX=<64 hex> node oracle/dist/index.js`, `POST /verdict`.
## Limits
- 1Click runs on mainnet only; the testnet cross-chain run uses quotes signed by a test key.
- The owner is trusted; the oracle is trusted as far as its TEE-bound key.
## Docs
- README.md: overview, diagrams, quickstart, FAQ.
- docs/THREAT_MODEL.md
- docs/TESTNET.md