Security Guide

MCP Wallet implements multiple layers of security to protect your funds while allowing convenient AI integration.

Security Architecture

1. Private Key Encryption

Your private keys are secured using industry-standard encryption:

• Algorithm: AES-256-GCM
• Key Derivation: Argon2id (memory-hard, resistant to GPU attacks)
• Storage: SQLite database encrypted on your device
• Access: Only unlocked when you enter your password

What this means:

• Even if someone accesses your device, they cannot access your keys without your password
• Your keys never leave your device unencrypted
• No one (not even MCP Wallet developers) can access your funds

2. Password Security

Your password is never stored - only a secure hash is kept for verification.

Best Practices:

• Use at least 12 characters
• Mix uppercase, lowercase, numbers, and symbols
• Avoid common words or patterns
• Don't reuse passwords from other services
• Use a password manager

Example of Strong Password:

Bad:  password123
Good: mcp!Wallet$2025#SecureKey

3. Seed Phrase (Recovery Key)

Your 12-word seed phrase is the master key to your wallet.

Critical Rules:

Never Share Your Seed Phrase

• Not with MCP Wallet support
• Not with any website or service
• Not via email, chat, or phone
• Anyone with your seed phrase can access ALL your funds

Storage Recommendations:

1. ✅ Write on paper and store in multiple secure locations
2. ✅ Use metal backup (fireproof, waterproof)
3. ✅ Split storage (words 1-6 in location A, 7-12 in location B)
4. ❌ NEVER store digitally (cloud, email, photos, notes apps)
5. ❌ NEVER share with anyone for any reason

Backup Checklist:

□ Seed phrase written down accurately
□ Verified word spelling against BIP39 list
□ Stored in secure location #1
□ Stored in secure location #2
□ Never photographed or digitally stored
□ Safe from fire/water damage

4. OAuth 2.1 Security

AI access is secured through OAuth 2.1 with PKCE (Proof Key for Code Exchange).

Security Features:

• No password sharing - AI never sees your password
• Scoped permissions - AI only gets specific capabilities
• Time-limited tokens - Access expires automatically
• Revocable access - You can revoke AI access anytime
• PKCE (S256) - Prevents authorization code interception

Access Token Lifecycle:

• Access Token: Valid for 1 hour
• Refresh Token: Valid for 30 days
• After expiration: Re-authorization required

How to Revoke Access:

1. Go to Settings → Accounts
2. Toggle "Enable API" to OFF
3. Done! AI can no longer access your wallet

5. Transaction Control

You maintain control over AI transactions through OAuth authorization and API access.

How AI Transactions Work:

1. Initial Authorization

   • User approves AI access once during OAuth flow
   • Authorization grants AI permission to execute transactions
   • No per-transaction approval needed after initial authorization

2. Transaction Execution

   • AI can freely execute transactions while API is enabled
   • All transactions are logged and labeled as "AI-initiated"
   • You monitor activity through transaction history

Controlling AI Access:

1. Enable/Disable API

   • Go to Settings → Accounts
   • Toggle "Enable API" on or off
   • When disabled, AI cannot execute any transactions

2. Revoke OAuth Tokens

   • Disabling API invalidates all access tokens
   • AI must re-authorize to regain access

Coming Soon: Spending Limits

Per-transaction and daily spending limits will be added in a future update to provide additional safeguards for AI transactions.

6. Transaction Signing

Manual Transactions (via UI):

• You review all details
• You click "Sign & Send"
• Your password may be required

AI Transactions (via API):

• Executed after user approves during OAuth authorization
• Auto-signed when API is enabled
• Labeled as "AI-initiated" in history
• Can be stopped by disabling API access

What AI Cannot Do:

• ❌ Change your password
• ❌ Export your private keys
• ❌ View your seed phrase
• ❌ Modify security settings
• ❌ Disable API access
• ❌ Continue after you revoke access

Security Best Practices

For Daily Use

1. Lock wallet when away

   • MCP Wallet locks automatically after inactivity
   • Configure timeout in Settings → Security

2. Keep software updated

   • Updates include security patches
   • Check for updates regularly

3. Use hardware wallet (coming soon)

   • Keep keys on dedicated hardware device
   • Sign transactions offline

4. Verify transaction details

   • Always check recipient address
   • Verify amounts before sending
   • Transaction cannot be reversed

5. Secure your device

   • Use disk encryption (FileVault on macOS, BitLocker on Windows)
   • Keep OS and antivirus updated
   • Use firewall

For AI Integration

1. Start with testnet

   • Test integration on BSC Testnet first
   • No real money at risk

2. Monitor transactions

   • Check transaction history regularly
   • Look for unexpected transactions
   • All AI transactions are labeled

3. Use dedicated account

   • Create separate account for AI access
   • Keep limited funds in AI-accessible account

4. Disable when not needed

   • Turn off API access when not using AI
   • Re-enable when needed

5. Review logs

   • Check MCP server logs periodically
   • Look for unusual activity

For Advanced Users

1. Multi-account setup

   • Create separate accounts for different purposes
   • Example: One for AI (with limits), one for manual (no API access)

2. Network segregation

   • Use different accounts for mainnet and testnet
   • Never mix test and production funds

3. Regular backups

   • Export transaction history periodically
   • Keep records of all transactions

Common Security Scenarios

Scenario 1: Suspected Unauthorized Access

What to do:

1. Immediately disable API access
   • Settings → Accounts → Toggle "Enable API" OFF
2. Lock your wallet
3. Check transaction history for unauthorized transactions
4. Change your password
5. Transfer remaining funds to a new wallet if needed
6. If funds were stolen: They cannot be recovered (blockchain is immutable)

Scenario 2: Lost or Stolen Device

What to do:

1. Don't panic - Your keys are encrypted
2. Get a new device
3. Install MCP Wallet
4. Import with seed phrase
5. Set new password
6. Transfer funds to new wallet (optional, for extra security)

Timeline:

• Attacker needs your password to access wallet
• Without password, encrypted keys are useless
• If you recover before attacker breaks encryption, funds are safe

Scenario 3: Forgot Password

What to do:

1. Find your seed phrase backup
2. Uninstall or delete MCP Wallet data
3. Reinstall MCP Wallet
4. Choose "Import Wallet"
5. Enter your 12-word seed phrase
6. Set a new password
7. ✅ Funds recovered

If you don't have seed phrase: ❌ Funds are permanently lost

Scenario 4: Suspicious Transaction

What to do:

1. Check transaction history
2. Look at transaction label (AI-initiated vs manual)
3. Check block explorer for confirmation
4. If unauthorized:
   • Disable API access immediately
   • Change password
   • Transfer remaining funds to new wallet

Security Checklist

Initial Setup

□ Created strong password (12+ characters)
□ Backed up seed phrase on paper
□ Stored seed phrase in 2+ secure locations
□ Verified seed phrase backup is accurate
□ Never photographed or digitally stored seed phrase
□ Enabled API access only when needed
□ Tested wallet with small transaction

Regular Maintenance

□ Review transaction history weekly
□ Check for software updates monthly
□ Confirm API access is enabled only when needed
□ Review AI transaction activity
□ Review MCP server logs periodically

Before AI Integration

□ Tested on testnet first
□ Reviewed OAuth permissions
□ Understood how to revoke access
□ Created dedicated account for AI (optional)
□ Monitored first few AI transactions

Understanding Security Trade-offs

MCP Wallet balances security with convenience:

Feature	Security Benefit	Convenience Trade-off
Password encryption	Keys safe even if device stolen	Must remember password
OAuth 2.1	AI never sees password/keys	Must authorize each AI client
One-time approval	Fast AI transactions after approval	Must monitor activity yourself
Token expiration	Limits exposure window	Must re-auth periodically
API toggle	Instant revocation	Must re-enable when needed

Philosophy: You remain in full control while allowing AI to assist after initial authorization. Future spending limits will add additional safeguards.

Reporting Security Issues

Found a security vulnerability?

1. Do NOT open a public GitHub issue
2. Email security@example.com with:
   • Detailed description
   • Steps to reproduce
   • Potential impact
   • Suggested fix (if any)
3. We'll respond within 48 hours
4. We may offer a bug bounty (program coming soon)

Responsible Disclosure

Please give us reasonable time to fix vulnerabilities before public disclosure.

Additional Resources

• OWASP Cryptographic Storage Cheat Sheet
• OAuth 2.1 Specification
• BIP39 Seed Phrase Standard
• Argon2 Password Hashing

---

Remember: Security is a shared responsibility. MCP Wallet provides the tools, but you must use them correctly to keep your funds safe.