# Security Architecture
This page explains toani Facilitate's security model and design invariants, addressing the core question: "How reliable is the compliance guarantee for AI Agent transactions?"
> For product overview, see [toani Facilitate Overview](/toani-facilitate/overview.md). For technical implementation details, see [toani Facilitate Compliance Engine Technical Architecture](/toani-facilitate/facilitate-engine.md).
***
## Three Security Commitments
| Commitment | Technical Guarantee |
| ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Both parties compliant on every transaction** | Zero-knowledge KYC plus real-time wallet risk scanning verify both payer and payee; rejection if either party fails compliance |
| **Agent spending within Owner's cryptographic authorization** | Intent Mandate signed with EIP-712, stored as W3C verifiable credential; signature covers all constraint fields and cannot be forged or tampered with |
| **Settlement is atomic and traceable** | x402 protocol completes USDC transfer on Base chain; every transaction is linked to compliance status and Mandate verification records |
***
## Bidirectional Compliance Model
In Agentic Commerce, trust cannot be one-directional. AI Agents initiate payments on behalf of humans; transaction parties may not know each other. Payers need to know payees are legitimate, and payees need to know payer funds are clean. toani Facilitate verifies both parties on every transaction.
### KYC: Zero-knowledge Proof via zkMe
| Dimension | Description |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Verification Method** | zkMe Widget guides users through document upload and liveness detection |
| **Privacy Guarantee** | Zero-knowledge proof architecture: toani confirms "this person has been verified" without acquiring any personal identity data |
| **Verification Frequency** | Verified once; credential remains valid |
| **Status Model** | `pending` then `approved` or `rejected` |
| **Compliance Pass Condition** | `kycCompleted === true && kycStatus === "approved"` |
### KYT: Real-time Wallet Risk Scanning
| Dimension | Description |
| ----------------------------- | ----------------------------------------------------------------------------------------------------- |
| **Scan Content** | Scans wallet address against AML (anti-money laundering) and international sanctions databases |
| **Output** | Risk level (`low`, `medium`, `high`, `severe`) plus risk score (0–100) plus risk signals |
| **Cache Strategy** | Redis cache with configurable TTL to avoid redundant queries |
| **Audit Log** | Every check recorded in `KytCheckLog` with address, chain, risk level, decision, and cache hit status |
| **Compliance Pass Condition** | `decision === "pass"` |
### Risk Level Handling
| Risk Level | Action |
| ---------- | ------------------------ |
| `low` | Approve |
| `medium` | Approve (with log entry) |
| `high` | Reject |
| `severe` | Reject |
***
## Google AP2 Cryptographic Trust Chain
Google AP2 creates an unforgeable authorization chain through three cryptographic signatures:
| Mandate | Issued By | Signature Standard | Content |
| ------------------- | ------------------ | ------------------ | ---------------------------------------------- |
| **Intent Mandate** | Owner (fund owner) | EIP-712 | Per-tx limit, total budget, expiration |
| **Cart Mandate** | Merchant (payee) | EIP-191 | Invoice details, payment amount, payee address |
| **Payment Mandate** | MCP Gateway | EIP-3009 | On-chain USDC transfer authorization |
The three mandates form a verification chain: Payment Mandate verifies Cart Mandate is legitimate, and Cart Mandate verifies Intent Mandate authorizes the transaction. If any signature mismatches or rule fails, the transaction stops immediately.
***
## Fail-close Design Principle
toani Facilitate follows fail-close design: when compliance configuration is missing or abnormal, all payments are rejected by default.
| Missing Configuration | System Behavior |
| ----------------------------- | ------------------------------------- |
| `COMPLIANCE_BASE_URL` not set | Reject all payments |
| `COMPLIANCE_API_KEY` not set | Reject all payments |
| KYC service unavailable | Reject (not "default approve") |
| KYT check timeout | Reject (not "skip check and proceed") |
| Intent Mandate not found | Reject |
| Dashboard API call fails | Reject |
There is no degradation mode. The system rejects payments on any anomaly rather than accidentally bypassing compliance checks.
***
## Attack Surface Coverage
| Attack Scenario | toani Facilitate Defense |
| ----------------------------------------- | -------------------------------------------------------------------------------------------- |
| Compromised Agent with unlimited spending | Intent Mandate enforces per-tx limit and total budget; overspend is auto-blocked |
| Payment to sanctioned entity | Bidirectional KYT scans payee wallet risk before settlement |
| Forged merchant invoice | Cart Mandate EIP-191 signature verified; public key retrieved from Dashboard |
| Forged Owner authorization | Intent Mandate EIP-712 signature covers all constraint fields; impossible to forge |
| Tampered budget limit | VC signature covers perTxLimit, totalBudget, and expiresAt; any change fails verification |
| Conflicting authorizations | One active Mandate per account; conflicting mandates cannot coexist |
| Money laundering source | Payee verifies payer wallet risk through KYT check |
| Missing compliance configuration | Fail-close policy: missing config = reject all payments |
| Transaction record tampering | Every transaction linked to on-chain txHash; cross-verification possible with Dashboard logs |
***
## Privacy Protection
| Dimension | Implementation |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **KYC Privacy** | zkMe zero-knowledge architecture: verification happens without exposing identity data; toani receives only verification status |
| **Personal Data** | System does not retain name, ID number, photo, or other personal identity information |
| **KYT Data** | Uses only public on-chain wallet address information; no private data involved |
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.toani.ai/toani-facilitate/security-architecture.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.