Security

Elytro provides multiple layers of security: local vault protection, on-chain 2FA, and configurable spending limits.

Security Model

Layer	Feature
Local	macOS Keychain vault, AES-GCM encrypted keyring
On-chain	SecurityHook 2FA (signature/userop/both)
On-chain	Spending limits (USD/day)
Recovery	Email OTP, social recovery, guardians

Vault Key (macOS Keychain)

The vault key is a 256-bit random key that decrypts the local keyring vault. On macOS, elytro init generates the vault key and stores it in the system Keychain automatically.

Zero Configuration Required

The user never sees, copies, or configures the vault key. It is fully managed by the OS.

Security Properties

Domain separation: Encrypted vault (keyring.json) lives on disk; decryption key lives in Keychain. Copying ~/.elytro/ to another machine is useless without the Keychain entry.
OS-level protection: Keychain is encrypted with the user's login password and locked when logged out.
Zero-fill: Raw key buffer is zeroed in memory after keyring is unlocked.

Non-macOS Warning

Running on Windows, Linux, or containers weakens the security model. The vault key must be injected via ELYTRO_VAULT_SECRET environment variable. On-chain SecurityHook (2FA + spending limits) is strongly recommended as compensating control.

On-chain 2FA (SecurityHook)

The SecurityHook is an on-chain contract that enforces 2FA for your wallet operations. It requires OTP verification for transactions.

Capabilities

Value	Mode	Description
1	SIGNATURE_ONLY	2FA required for signing messages
2	USER_OP_ONLY	2FA required for UserOperations (transactions)
3	BOTH	2FA required for both signatures and transactions

# Install 2FA for UserOperations
elytro security 2fa install --capability 2

# Check status
elytro security status

# Uninstall (with safety delay)
elytro security 2fa uninstall --force
# Wait for safety period...
elytro security 2fa uninstall --execute

Spending Limits

Configure daily spending limits enforced on-chain. Limits are specified in USD.

# View current limit
elytro security spending-limit

# Set $100/day limit
elytro security spending-limit 100

# Set $1000/day limit
elytro security spending-limit 1000

Email OTP

Bind an email address to receive OTP codes for security operations.

# Bind email for OTP delivery
elytro security email bind user@example.com

# Change bound email
elytro security email change new@example.com

Storage Layout

~/.elytro/
├── keyring.json      # AES-GCM encrypted EOA private key vault
├── accounts.json     # Account list (alias, address, chainId, deployed)
└── config.json       # Chain config, API keys

No plaintext key files on disk. The vault key lives in macOS Keychain. Deleting ~/.elytro/ resets local state; on-chain contracts are unaffected.