Executive Summary

Firewood is a high-security, local-first, and completely offline password and credentials manager built with Flutter and Dart. Designed around a strict zero-knowledge security architecture, Firewood ensures that sensitive user secrets (passwords, credit cards, recovery phrases, and private notes) never touch remote servers or unencrypted persistent storage.

Rather than relying on third-party cloud storage or generic database-level encryption, Firewood implements manual, field-level authenticated symmetric encryption with XChaCha20-Poly1305 and derives 256-bit secret keys using the memory-hard Argon2id (RFC 9106) key derivation function. State management is orchestrated through Riverpod with explicit memory-zeroization routines on vault lock.

Architecture

flowchart TD subgraph UI_State_Layer ["UI & State Layer"] User[Master Password] --> AuthScreen[Vault Auth & Setup Screens] AuthScreen --> Riverpod[In-Memory AuthProvider / SecretKey] Riverpod --> VaultService[Vault Service] Riverpod --> ItemService[Item CRUD Service] LockService[Lock Service & Auto-Wipe] -->|Zeroize State| Riverpod end subgraph Cryptographic_Core ["Cryptographic Core"] User -->|Argon2id 64MB, 3 iter, 4 threads| KDF[Argon2id Key Derivation] KDF --> SecretKey[Ephemeral 256-bit SecretKey in RAM] SecretKey --> AEAD[XChaCha20-Poly1305 AEAD Engine] CSPRNG[Random.secure CSPRNG] -->|24-byte Fresh Nonce| AEAD CSPRNG -->|16-byte Salt| KDF end subgraph Persistence_Layer ["Persistence Layer"] AEAD -->|Ciphertext + Poly1305 MAC| Isar[(Isar Local Database)] CSPRNG -->|Nonce per Item| Isar KDF -->|Salt per Vault| Isar end

Cryptographic Specifications

Component	Algorithm	Configuration / Parameters	Standard Reference
Key Derivation Function (KDF)	Argon2id	64 MB memory (65,536 KB), 3 iterations, 4 parallelism threads, 32-byte key output	RFC 9106
Symmetric Encryption (AEAD)	XChaCha20-Poly1305	256-bit secret key, 192-bit (24-byte) random nonce per encryption operation	IETF CFRG Draft
Authentication Tag	Poly1305	16-byte MAC tag appended to ciphertext, verified before decryption	RFC 8439
Salt Generation	CSPRNG (`Random.secure()`)	16 bytes (128 bits), generated once per vault creation	Dart Security
Nonce Generation	CSPRNG (`Random.secure()`)	24 bytes (192 bits), fresh nonce generated on every single item write/update	CFRG Nonce Guidelines

Core Security Invariants

Zero Persistence of Master Key: Master passwords and derived SecretKey instances exist strictly within volatile RAM. When the vault is locked or backgrounded, state providers are immediately zeroized.
Strict Nonce Freshness: Every record modification or creation generates a cryptographically unique 24-byte nonce to prevent cryptographic replay attacks and stream cipher degradation.
Tamper-Evident Integrity: Poly1305 authentication tags verify data authenticity before decryption; any bit-level tampering causes decryption to reject immediately.
Offline Isolation: Completely zero network telemetry or remote server dependencies, eliminating remote attack vectors.

Key Features & Capabilities

Multi-Type Vault Items: Structured schemas for logins, payment cards, secure notes, and identity documents with dynamic custom fields.
Instant Search & Filter: Local in-memory search over item titles and tags with responsive UI filtering.
Clipboard Auto-Wiping: Automated background clipboard wiping after sensitive credentials or TOTP tokens are copied.
Cross-Platform Target: Native compiled support for Android, iOS, and Linux Desktop with hardware-accelerated rendering via Flutter.