Security Architecture
Conto implements multiple layers of security to protect AI agent financial operations.
Authentication
SDK Keys
SDK keys authenticate AI agents making payment requests.
Format: conto_agent_{random_32_bytes_hex}
Example: conto_agent_a1b2c3d4e5f6...
- Cryptographically random (32 bytes entropy)
- Hashed before storage (SHA-256)
- Scoped to specific agent
- Support expiration dates
- Can be instantly revoked
Security Measures:
- Keys shown only once at creation
- Only key prefix stored for identification
- Rate limited per key
- Usage tracking and anomaly detection
API Keys
Organization-level API keys for dashboard and management access.
Format: conto_{random_32_bytes_hex}
Example: conto_x7y8z9...
| Scope | Description |
|---|
agents:read | View agent data |
agents:write | Modify agents |
wallets:read | View wallet data |
wallets:write | Modify wallets |
transactions:read | View transactions |
policies:read | View policies |
policies:write | Modify policies |
admin | Full access |
Session Authentication
Dashboard users authenticate via NextAuth.js:
- OAuth Providers: Google, GitHub
- Email/Password: With bcrypt hashing
- Session Storage: HTTP-only cookies
- CSRF Protection: Built-in token validation
Encryption
At Rest
Database Encryption:
- PostgreSQL with TLS connections
- Sensitive fields encrypted at application layer
- AES-256-GCM for symmetric encryption
Wallet Private Keys:
// Encryption approach
const encrypted = await encryptPrivateKey(privateKey, ENCRYPTION_KEY);
// Stored as: iv:authTag:ciphertext (base64)
In production, use a Hardware Security Module (HSM) or cloud KMS (AWS KMS, Google Cloud KMS) for key management.
In Transit
- All API traffic over HTTPS (TLS 1.3)
- Certificate pinning for mobile clients
- Strict Transport Security headers
Authorization
Role-Based Access Control (RBAC)
Organization member roles:
| Role | Capabilities |
|---|
OWNER | Full access, billing, delete org |
ADMIN | Manage agents, wallets, policies |
MANAGER | View all, manage assigned agents |
VIEWER | Read-only access |
Policy-Based Authorization
Payment authorization flows through the policy engine:
Payment Request
↓
┌─────────────────┐
│ Authentication │ → Is SDK key valid?
└────────┬────────┘
↓
┌─────────────────┐
│ Authorization │ → Does agent have wallet access?
└────────┬────────┘
↓
┌─────────────────┐
│ Policy Engine │ → Do policies allow this payment?
└────────┬────────┘
↓
┌─────────────────┐
│ Spend Limits │ → Is agent within limits?
└────────┬────────┘
↓
APPROVED / DENIED
Rate Limiting
Protects against abuse and ensures fair usage.
Limits by Endpoint Type
| Endpoint | Limit | Window |
|---|
| SDK Payments | 60 requests | per minute |
| SDK Read | 120 requests | per minute |
| API Write | 100 requests | per minute |
| API Read | 100 requests | per minute |
Implementation
// Redis-based sliding window rate limiting
const result = await rateLimit(agentId, {
limit: 60,
window: '1m',
identifier: `sdk:${agentId}`
});
if (!result.allowed) {
return Response.json(
{ error: 'Rate limited', retryAfter: result.retryAfter },
{ status: 429 }
);
}
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 2024-01-15T10:01:00.000Z
Retry-After: 30
const PaymentRequestSchema = z.object({
amount: z.number().positive().max(1_000_000),
recipientAddress: z.string().regex(/^0x[a-fA-F0-9]{40}$/),
recipientName: z.string().max(100).optional(),
purpose: z.string().max(500).optional(),
category: z.enum(['API_PROVIDER', 'CLOUD_SERVICES', ...]).optional(),
});
Protection Against
- SQL Injection: Parameterized queries via Prisma
- XSS: Input sanitization, CSP headers
- CSRF: Token validation on mutations
- Path Traversal: Input validation, no file system access
Audit Logging
Comprehensive audit trail for compliance and forensics.
Logged Events
| Category | Events |
|---|
| Authentication | Login, logout, key creation/revocation |
| Agents | Create, update, suspend, revoke |
| Wallets | Create, freeze, link to agent |
| Transactions | Request, approve, execute, confirm |
| Policies | Create, update, delete, apply |
| Settings | Organization changes, role updates |
Audit Log Schema
{
id: "audit_abc123",
timestamp: "2024-01-15T14:30:00Z",
action: "PAYMENT_EXECUTED",
actorType: "AGENT", // AGENT, USER, SYSTEM
actorId: "agt_xyz789",
resource: "transaction",
resourceId: "tx_abc123",
organizationId: "org_123",
ipAddress: "203.0.113.1",
userAgent: "Conto-SDK/1.0.0",
metadata: {
amount: 50,
recipient: "0x...",
policyResult: "ALLOWED"
}
}
Retention
- Active logs: 90 days hot storage
- Archived logs: 7 years cold storage (compliance)
- Immutable once written
Network Security
Infrastructure
- WAF: Web Application Firewall (Cloudflare/Vercel)
- DDoS Protection: Automatic mitigation
- IP Allowlisting: Available for enterprise
- VPC Isolation: Database in private subnet
Strict-Transport-Security: max-age=31536000; includeSubDomains
Content-Security-Policy: default-src 'self'
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Referrer-Policy: strict-origin-when-cross-origin
Blockchain Security
Transaction Safety
- Atomic Operations: Database + blockchain in sync
- Nonce Management: Prevent transaction replay
- Gas Estimation: Prevent failed transactions
- Balance Verification: Before every transaction
Smart Contract Interaction
// Only interact with verified stablecoin contracts
const stablecoin = getContract({
address: STABLECOIN_ADDRESS,
abi: STABLECOIN_ABI,
client: publicClient,
});
Incident Response
Detection
- Real-time anomaly detection
- Unusual spending pattern alerts
- Failed authentication monitoring
- Rate limit breach alerts
Response Playbook
- Contain: Suspend affected agents/keys
- Assess: Review audit logs
- Remediate: Revoke compromised credentials
- Recover: Restore from known-good state
- Review: Post-incident analysis
Emergency Actions
# Suspend agent immediately
curl -X POST https://conto.finance/api/agents/{id}/suspend \
-H "Authorization: Bearer $ADMIN_KEY"
# Revoke all SDK keys for agent
curl -X DELETE https://conto.finance/api/agents/{id}/sdk-keys/all \
-H "Authorization: Bearer $ADMIN_KEY"
# Freeze wallet
curl -X POST https://conto.finance/api/wallets/{id}/freeze \
-H "Authorization: Bearer $ADMIN_KEY"
Compliance
Standards
- SOC 2 Type II: In progress
- GDPR: Data protection controls
- OFAC: Sanctions screening integration
Data Handling
| Data Type | Retention | Encryption |
|---|
| Transaction history | 7 years | AES-256 |
| Audit logs | 7 years | At rest |
| User PII | While active | AES-256 |
| API keys | Until revoked | SHA-256 (hashed) |
| Session data | 24 hours | HTTP-only cookies |
Security Best Practices
Reporting Vulnerabilities
If you discover a security vulnerability:
- Do not open a public GitHub issue
- Email security@conto.finance
- Include detailed reproduction steps
- We’ll respond within 24 hours
We offer a bug bounty program for qualifying vulnerabilities.
