This document outlines the security architecture of the Iwa Wallet, explaining how secrets, keys, and access controls are managed.

Iwa is a self-hosted, local-first wallet management tool. It is designed to be run by a single user or a trusted team on their own infrastructure. No sensitive data is ever sent to external servers controlled by the Iwa developers.

Application secrets (such as API keys and RPC URLs) are managed via environment variables, typically loaded from a secrets.env file.

• Loading: Secrets are loaded into memory using the Settings class (powered by Pydantic settings with SecretStr for sensitive values).
• Storage: The secrets.env file should be secured with appropriate file system permissions (e.g., chmod 600) to prevent unauthorized access by other users on the system.
• Memory: Once loaded, secrets reside in the application's memory. Debug logs are configured to avoid printing these values, but a memory dump of the running process could reveal them.

Private keys are never stored in plain text on the disk.

• Keystore: Encrypted private keys are stored in a JSON keystore file (default: wallet.json).
• Encryption Algorithm: AES-256-GCM with AESGCM for authenticated encryption.
• Key Derivation: Scrypt with 2^14 iterations, r=8, p=1 for password-based key derivation.
• Decryption: Keys are decrypted only in memory and only when needed to sign a transaction.
• File Permissions: The wallet file is automatically set to chmod 600 (owner read/write only).
• Session: When you launch the TUI or CLI, you provide the password. The keys remain accessible in memory for the duration of the session.

The KeyStorage class provides internal signing methods that never expose the raw private key:

• sign_transaction(): Sign a transaction dict
• sign_message(): Sign raw message bytes
• sign_typed_data(): Sign EIP-712 typed data

These methods decrypt the key, sign, and return only the signature.

Iwa does not implement multi-user roles or permissions.

• Single User: The user running the iwa process has full access to all configured wallets.
• Infrastructure Security: Security relies on the security of the host machine (access to the secrets.env and wallet.json files).

To prevent accidental leakage of sensitive information:

• File Logging: Logs are written to iwa.log.
• Sanitization: The application is designed to avoid logging private keys or full secret values. However, care should be taken when sharing log files for debugging.
• TUI: The Terminal User Interface suppresses stderr output to prevent logs from overlapping with the UI, redirecting them to the log file instead.

Iwa connects to:

• RPC Providers: configured in secrets.env (e.g., Gnosis, Ethereum, Base).
• Price APIs: e.g., Coingecko (if configured).
• Etherscan/Gnosisscan: For fetching ABI or contract details.

Ensure you trust your RPC providers, as they can see your read requests (though they cannot sign transactions for you).

The project includes automated security checks (just security):

1. gitleaks: Scans for secrets accidentally committed to git
2. bandit: Static analysis for common security issues in Python
3. pip-audit: Checks for known vulnerabilities in dependencies